DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface/Database.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Interface/Database/IDatabaseCopyView.cs Common/DTS.Common/Interface/Database/IDatabaseSwitchView.cs Common/DTS.Common/Interface/Database/IDatabaseStatusBarView.cs Common/DTS.Common/Interface/Database/IDatabaseSwitchViewModel.cs Common/DTS.Common/Interface/Database/IUserDbRecord.cs Common/DTS.Common/Interface/Database/IDatabaseCopyViewModel.cs Common/DTS.Common/Interface/Database/IDatabaseStatusBarViewModel.cs	2026-04-16T02:58:05.427871+00:00	Qwen/Qwen3-Coder-Next-FP8	1	029f22455457f0fd

Database

Documentation: Database View/ViewModel Interfaces

---

1. Purpose

This module defines a set of interfaces that constitute the view-layer contract for database-related UI functionality in the DTS system. Specifically, it establishes abstractions for three distinct database management operations—copying (synchronizing) a remote database to local, switching between remote and local database contexts, and displaying the current database status in the UI. These interfaces follow a clean separation of concerns: view interfaces (IDatabase*View) declare no behavior beyond inheritance from IBaseView, while their corresponding viewmodel interfaces (IDatabase*ViewModel) encapsulate the logic, state, and coordination required for each operation. The module serves as a contract between UI components and their backing logic, enabling testability and decoupling of presentation from data access.

---

2. Public Interface

Interfaces (No Implementation)

• IDatabaseCopyView : IBaseView
  Marker interface for the view associated with database copying functionality. No additional members.

• IDatabaseSwitchView : IBaseView
  Marker interface for the view associated with database switching functionality. No additional members.

• IDatabaseStatusBarView : IBaseView
  Marker interface for the view associated with the database status bar UI element. No additional members.

ViewModels

• IDatabaseSwitchViewModel : IBaseViewModel
  Manages state and logic for switching between local and remote database connections.

  • IDatabaseSwitchView View { get; set; } — The associated view.
  • void Unset() — Releases resources held by the viewmodel.
  • bool RemoteIsActive { get; } — Indicates whether the remote database is currently active.
  • string DefaultDbName { get; } — The default database name (read-only).
  • void InitializeDbSettings(string defaultDbName, string dbHost, bool ntlmAuthentication, string dbUser, string dbPassword) — Configures database connection settings.
  • void SwitchRemote() — Switches the active database to the remote instance.
  • void SwitchLocal() — Switches the active database to the local instance.
  • string DbHost { get; }, bool NTLMAuthentication { get; }, string DbUser { get; }, string DbPassword { get; } — Expose current connection configuration.

• IDatabaseCopyViewModel : IBaseViewModel
  Manages state and logic for copying data from remote to local database (clears local, repopulates from remote).

  • IDatabaseCopyView View { get; set; } — The associated view.
  • void Unset() — Releases resources held by the viewmodel.
  • void CopyDatabase() — Executes the copy operation (remote → local), using DTS.Common.Storage to determine sources/destinations.
  • void InitializeState(DbType dbType, string dbName) — Initializes internal state (e.g., database type and name).
  • string DbName { get; } — The name of the database being copied.
  • IStatusAndProgressBarView OverallProgressBarView { get; } — View for overall copy progress.
  • IStatusAndProgressBarView CurrentTaskProgressBarView { get; } — View for progress of the current subtask.
  • DbType DatabaseType { get; } — The type of database being copied.
  • bool CopyEnabled { get; } — Indicates whether the copy operation is currently enabled (e.g., not already running).
  • bool IsCopyVisible { get; set; } — Controls visibility of the copy UI.

• IDatabaseStatusBarViewModel : IBaseViewModel
  Manages display of current database connection status in the status bar.

  • IDatabaseStatusBarView View { get; set; } — The associated view.
  • void Unset() — Releases resources held by the viewmodel.
  • DbType DatabaseType { get; } — The type of database currently in use.
  • bool RemoteConnected { get; } — Whether the remote database is connected.
  • string ServerName { get; } — The server (host) name, not the database name.
  • void InitializeValues(DbType dbType, string serverName, bool remoteConnected) — Sets initial values for status display.
  • string ActiveDbName { get; } — The currently active database name (computed based on DatabaseType, RemoteConnected, and ServerName).
  • Brush BackgroundBrush { get; } — Visual indicator (e.g., color) for the active database context.

Data Contracts

• IUserDbRecord
  Represents a user record in the database.
  • int ID { get; set; } — Primary key.
  • string UserName { get; set; } — Unique username.
  • string DisplayName { get; set; } — Human-readable name for UI display.
  • string Password { get; set; } — Hashed and salted password (never plaintext).
  • short Role { get; set; } — User role (enum or constant-based).
  • DateTime LastModified { get; set; } — Timestamp of last modification.
  • string LastModifiedBy { get; set; } — Username of modifier.
  • bool LocalOnly { get; set; } — Deprecated — Was intended to control sync behavior between local/remote.

---

3. Invariants

• All view interfaces (IDatabase*View) must be implemented by UI components (e.g., WPF UserControls) and must not contain logic beyond property accessors or event wiring.
• All viewmodel interfaces inherit from IBaseViewModel, implying they participate in a standard MVVM lifecycle (e.g., Unset() for cleanup).
• IDatabaseSwitchViewModel assumes the local database schema (tables, stored procedures) is pre-initialized before SwitchRemote() or SwitchLocal() is called.
• IDatabaseCopyViewModel.CopyDatabase() performs a destructive operation: it clears the local database before copying from remote. This must be guarded by UI controls (e.g., confirmation dialogs) and only triggered when CopyEnabled is true.
• IDatabaseStatusBarViewModel.ActiveDbName is computed, not stored directly; its value depends on DatabaseType, RemoteConnected, and ServerName.
• IUserDbRecord.Password is never stored in plaintext; implementations must ensure hashing/salting occurs before persistence.

---

4. Dependencies

Internal Dependencies (Inferred from Source)

• DTS.Common.Base
  All interfaces depend on IBaseView and IBaseViewModel (defined in DTS.Common.Base). This implies a shared base layer for MVVM.
• DTS.Common.Enums.Database
  Used by IDatabaseCopyViewModel and IDatabaseStatusBarViewModel for DbType (likely an enum like Local, Remote, Mixed, etc.).
• System.Windows.Media
  Used by IDatabaseStatusBarViewModel for Brush (WPF-specific UI rendering).

External Dependencies (Implied)

• DTS.Common.Storage
  Referenced in IDatabaseCopyViewModel.CopyDatabase() documentation as the source of truth for local/remote database locations. This module must be available at runtime.
• UI Framework
  WPF (due to Brush and IStatusAndProgressBarView, which is not defined here but referenced).

Dependencies on this Module

• Any UI component implementing database copy, switch, or status bar functionality must implement the corresponding *View interface.
• Any business logic or service layer orchestrating database operations must depend on the *ViewModel interfaces (e.g., to trigger CopyDatabase() or SwitchRemote()).

---

5. Gotchas

• LocalOnly in IUserDbRecord is deprecated — Its presence suggests legacy synchronization logic that may no longer be functional or enforced. Avoid relying on it.
• IDatabaseSwitchViewModel lacks Initialize() — While InitializeDbSettings() configures connection details, there is no explicit initialization method for the viewmodel itself. Callers must ensure InitializeDbSettings() is invoked before SwitchRemote()/SwitchLocal().
• CopyDatabase() is destructive — The documentation explicitly states it clears the local database. This behavior must be clearly communicated to users and guarded against accidental invocation.
• IStatusAndProgressBarView is referenced but not defined here — Its contract (likely from DTS.Common.Base) is assumed to exist and must be understood for full implementation.
• No async methods exposed — All copy/switch operations (CopyDatabase, SwitchRemote, SwitchLocal) are synchronous in the interface. This may indicate legacy design or reliance on internal threading (e.g., via BackgroundWorker), which is not visible in this layer.
• DbPassword is exposed as a property — This may pose security risks if the viewmodel is serialized or logged. Ensure consumers handle credentials securely.

None identified beyond the above.