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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/Interface/Database/IDatabaseCopyView.cs Common/DTS.CommonCore/Interface/Database/IDatabaseSwitchView.cs Common/DTS.CommonCore/Interface/Database/IDatabaseStatusBarView.cs Common/DTS.CommonCore/Interface/Database/IDatabaseSwitchViewModel.cs Common/DTS.CommonCore/Interface/Database/IUserDbRecord.cs Common/DTS.CommonCore/Interface/Database/IDatabaseCopyViewModel.cs Common/DTS.CommonCore/Interface/Database/IDatabaseStatusBarViewModel.cs	2026-04-16T02:17:57.680551+00:00	Qwen/Qwen3-Coder-Next-FP8	1	142a1b67b74ee9e9

Database

Documentation: Database View/ViewModel Interfaces

1. Purpose

This module defines a set of interfaces for database-related UI components in a Model-View-ViewModel (MVVM) architecture. It provides contracts for views and viewmodels that manage database connection status, database switching (local ↔ remote), and database copying operations. These interfaces decouple UI presentation logic from implementation details, enabling modular UI development and testability. The interfaces are part of the DTS.Common.Interface.Database namespace and extend base contracts (IBaseView, IBaseViewModel) to integrate with the broader DTS framework.

---

2. Public Interface

Interfaces (View Contracts)

• IDatabaseCopyView : IBaseView
  Marker interface for the view associated with IDatabaseCopyViewModel. Represents the UI layer for database copy operations.

• IDatabaseSwitchView : IBaseView
  Marker interface for the view associated with IDatabaseSwitchViewModel. Represents the UI layer for switching between local and remote databases.

• IDatabaseStatusBarView : IBaseView
  Marker interface for the view associated with IDatabaseStatusBarViewModel. Represents the UI layer for displaying database connection status (e.g., active database name, connection state).

Interfaces (ViewModel Contracts)

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

  • IDatabaseSwitchView View { get; set; }
    Gets/sets the associated view.
  • void Unset()
    Releases resources (e.g., event handlers, view references).
  • bool RemoteIsActive { get; }
    Indicates whether the remote database is currently active.
  • string DefaultDbName { get; }
    Gets the default database name.
  • void InitializeDbSettings(string defaultDbName, string dbHost, bool ntlmAuthentication, string dbUser, string dbPassword)
    Initializes database connection settings (note: SetDefaultDbName is commented out and unused).
  • void SwitchRemote() / void SwitchLocal()
    Initiates switching to the remote or local database, respectively.
  • string DbHost { get; }, bool NTLMAuthentication { get; }, string DbUser { get; }, string DbPassword { get; }
    Exposes current database connection configuration.

• IDatabaseCopyViewModel : IBaseViewModel
  Manages state and logic for copying data from a remote database to a local database.

  • IDatabaseCopyView View { get; set; }
    Gets/sets the associated view.
  • void Unset()
    Releases resources.
  • void CopyDatabase()
    Performs the copy operation (clears local DB, populates from remote). Uses DTS.Common.Storage to resolve local/remote locations.
  • void InitializeState(DbType dbType, string dbName)
    Initializes viewmodel state with database type and name.
  • string DbName { get; }
    Gets the target database name.
  • IStatusAndProgressBarView OverallProgressBarView { get; }
    Gets progress view for the overall copy operation.
  • IStatusAndProgressBarView CurrentTaskProgressBarView { get; }
    Gets progress view for the current subtask.
  • DbType DatabaseType { get; }
    Gets the type of database being copied.
  • bool CopyEnabled { get; }
    Indicates whether the copy operation is enabled.
  • bool IsCopyVisible { get; set; }
    Controls visibility of the copy UI.

• IDatabaseStatusBarViewModel : IBaseViewModel
  Manages state and logic for displaying database connection status in the UI.

  • IDatabaseStatusBarView View { get; set; }
    Gets/sets the associated view.
  • void Unset()
    Releases resources.
  • DbType DatabaseType { get; }
    Gets the database type (e.g., local, remote).
  • bool RemoteConnected { get; }
    Indicates whether the remote database is connected.
  • string ServerName { get; }
    Gets the server name (not database name).
  • void InitializeValues(DbType dbType, string serverName, bool remoteConnected)
    Sets initial values for status display.
  • string ActiveDbName { get; }
    Gets the currently active database name (e.g., local or remote, depending on state).
  • Brush BackgroundBrush { get; }
    Gets the background color brush for the active database name display.

Data Interface

• IUserDbRecord
  Represents a user record in the database.
  • int ID { get; set; }
    Database ID of the user.
  • string UserName { get; set; }
    Unique username.
  • string DisplayName { get; set; }
    User-friendly display name.
  • string Password { get; set; }
    Hashed and salted password (never stored in plaintext).
  • short Role { get; set; }
    User role (numeric code).
  • DateTime LastModified { get; set; }
    Timestamp of last modification.
  • string LastModifiedBy { get; set; }
    Username of the modifier.
  • bool LocalOnly { get; set; }
    Deprecated flag indicating whether the user should be local-only (not synchronized).

---

3. Invariants

• All view interfaces (IDatabaseCopyView, IDatabaseSwitchView, IDatabaseStatusBarView) extend IBaseView, implying they are part of a consistent UI abstraction layer.
• All viewmodel interfaces (IDatabaseSwitchViewModel, IDatabaseCopyViewModel, IDatabaseStatusBarViewModel) extend IBaseViewModel, implying they follow the MVVM pattern and require Unset() for resource cleanup.
• IDatabaseSwitchViewModel and IDatabaseCopyViewModel share overlapping functionality (e.g., clearing and repopulating local DB), but IDatabaseCopyViewModel includes progress tracking via IStatusAndProgressBarView.
• IUserDbRecord.Password is explicitly documented as hashed and salted; implementations must never store plaintext passwords.
• IUserDbRecord.LocalOnly is marked deprecated; its usage should be avoided.
• IDatabaseStatusBarViewModel.ActiveDbName dynamically reflects the active database (local/remote) based on DatabaseType and RemoteConnected state.

---

4. Dependencies

• Internal Dependencies:

  • DTS.Common.Base: All interfaces inherit from IBaseView or IBaseViewModel.
  • DTS.Common.Enums.Database: IDatabaseCopyViewModel and IDatabaseStatusBarViewModel use DbType (enum not shown; assumed to define database types like Local, Remote).
  • System.Windows.Media: IDatabaseStatusBarViewModel uses Brush (WPF-specific), indicating this module targets WPF UI.
  • DTS.Common.Storage: Referenced in IDatabaseCopyViewModel.CopyDatabase() documentation as the source for resolving local/remote database locations.

• External Dependencies:

  • WPF (System.Windows.Media) for Brush type.
  • System (via DateTime, string).

• Depended Upon:

  • Concrete implementations of these interfaces are expected in UI-layer projects (e.g., WPF views/viewmodels).
  • Likely consumed by UI controllers or services that manage database operations (e.g., a main window or database manager module).

---

5. Gotchas

• SetDefaultDbName is commented out in IDatabaseSwitchViewModel; the property DefaultDbName is read-only, and initialization relies solely on InitializeDbSettings.
• LocalOnly is deprecated in IUserDbRecord but not removed; implementations should ignore this property.
• IDatabaseStatusBarViewModel.BackgroundBrush has no documentation on how it is computed (e.g., based on connection state). Its value is implementation-defined.
• CopyDatabase() assumes pre-existing schema: Both IDatabaseSwitchViewModel and IDatabaseCopyViewModel require the local database to have tables and stored procedures already created.
• IStatusAndProgressBarView is used but not defined here: Its contract is assumed to be defined elsewhere (likely in DTS.Common.Base or a related module).
• No async methods: All operations (SwitchRemote, CopyDatabase) are synchronous; implementations may need to offload work to background threads to avoid UI blocking.
• DbPassword is exposed directly: The IDatabaseSwitchViewModel exposes the plaintext password via DbPassword { get; }, which may be a security risk if not handled carefully.