init

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

@@ -0,0 +1,108 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Base/Interface/IBaseClass.cs
+  - Common/DTS.CommonCore/Base/Interface/IViewModel.cs
+  - Common/DTS.CommonCore/Base/Interface/IBaseView.cs
+  - Common/DTS.CommonCore/Base/Interface/IBaseWindow.cs
+  - Common/DTS.CommonCore/Base/Interface/IBaseModel.cs
+  - Common/DTS.CommonCore/Base/Interface/IBasePropertyChanged.cs
+  - Common/DTS.CommonCore/Base/Interface/IHeaderInfoProvider.cs
+  - Common/DTS.CommonCore/Base/Interface/IBaseWindowModel.cs
+  - Common/DTS.CommonCore/Base/Interface/IBaseViewModel.cs
+generated_at: "2026-04-16T02:50:59.182890+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "cd583516ecde421b"
+---
+
+# Interface
+
+## Documentation: DTS.Common.Base Interface Layer
+
+---
+
+### 1. Purpose
+
+This module defines a foundational set of interfaces for implementing the Model-View-ViewModel (MVVM) pattern within the DTS codebase. It establishes contract-based abstractions for core UI and data entities—`IBaseModel`, `IBaseViewModel`, `IBaseWindowModel`, `IBaseView`, `IBaseWindow`, and supporting interfaces like `IBasePropertyChanged` and `IHeaderInfoProvider<T>`—to enforce consistency, lifecycle management, and property change notification across the application. These interfaces decouple UI components (Views/Windows) from their backing logic (ViewModels/Models), enabling testability, reuse, and standardized behavior for state tracking (`IsDirty`, `IsBusy`, `IsSaved`), initialization, and cleanup.
+
+---
+
+### 2. Public Interface
+
+#### Interfaces (all in `DTS.Common.Base` namespace)
+
+| Interface | Signature | Description |
+|-----------|-----------|-------------|
+| `IBaseClass` | `public interface IBaseClass : IBasePropertyChanged { }` | Marker interface extending `IBasePropertyChanged`. Used as a base contract for classes requiring property change notification. |
+| `IBasePropertyChanged` | `public interface IBasePropertyChanged : INotifyPropertyChanged { void OnPropertyChanged(string propertyName); }` | Extends `INotifyPropertyChanged` with a required `OnPropertyChanged(string)` method. *Note: No default implementation is provided.* |
+| `IBaseModel` | `public interface IBaseModel : IBasePropertyChanged { bool IsSaved { get; } }` | Base interface for domain models. Guarantees `IsSaved` read-only state (e.g., whether the model has unsaved changes). |
+| `IBaseViewModel` | `public interface IBaseViewModel : IBasePropertyChanged { ... }` | Base interface for ViewModels. Includes lifecycle methods (`Initialize`, `Activated`, `Cleanup`, `CleanupAsync`, `InitializeAsync`) and state properties (`IsMenuIncluded`, `IsNavigationIncluded`, `IsBusy`, `IsDirty`). Supports multiple `Initialize` overloads (with/without `parameter`, and with `parameter` + `model`). |
+| `IBaseWindowModel` | `public interface IBaseWindowModel : INotifyPropertyChanged { ... }` | Base interface for Window-level ViewModels. Mirrors `IBaseViewModel` but **does not inherit `IBasePropertyChanged`** (directly implements `INotifyPropertyChanged`). Includes identical lifecycle/state members. |
+| `IViewModel` | `public interface IViewModel { object Model { get; set; } }` | Minimal interface for ViewModels to expose their backing `Model`. Does not enforce lifecycle or state properties. |
+| `IBaseView` | `public interface IBaseView { object DataContext { get; set; } }` | Base interface for Views (e.g., UserControls). Declares `DataContext` for binding to a ViewModel. |
+| `IBaseWindow` | `public interface IBaseWindow { object DataContext { get; set; } }` | Base interface for Window classes. Declares `DataContext` for binding to a Window-level ViewModel. |
+| `IHeaderInfoProvider<T>` | `public interface IHeaderInfoProvider<T> { T HeaderInfo { get; } }` | Generic interface for objects that expose a `HeaderInfo` (e.g., for XAML binding to UI headers). Type parameter `T` specifies the `HeaderInfo` type. |
+
+**Lifecycle Method Overloads Summary**  
+All `Initialize`/`Cleanup` methods are defined in both `IBaseViewModel` and `IBaseWindowModel`:
+
+- `void Initialize();`
+- `void Initialize(object parameter);`
+- `void Initialize(object parameter, object model);` *(only in `IBaseViewModel`)*
+- `Task InitializeAsync();`
+- `Task InitializeAsync(object parameter);`
+- `void Activated();`
+- `void Cleanup();`
+- `Task CleanupAsync();`
+
+**State Properties**  
+Shared across `IBaseViewModel` and `IBaseWindowModel`:
+
+- `bool IsMenuIncluded { get; set; }`
+- `bool IsNavigationIncluded { get; set; }`
+- `bool IsBusy { get; set; }`
+- `bool IsDirty { get; }` *(read-only)*
+- `bool IsSaved { get; }` *(only in `IBaseModel`)*
+
+---
+
+### 3. Invariants
+
+- **Property Change Notification**: Any class implementing `IBasePropertyChanged` (including `IBaseClass`, `IBaseModel`, `IBaseViewModel`) **must** raise `PropertyChanged` via `OnPropertyChanged(string propertyName)`. The interface does *not* enforce thread-safety or throttling—consumers must handle this.
+- **`IsDirty` vs `IsSaved`**:  
+  - `IsDirty` (in `IBaseViewModel`/`IBaseWindowModel`) indicates whether the ViewModel has unsaved changes *relative to its initialization state*.  
+  - `IsSaved` (in `IBaseModel`) indicates whether the underlying Model has been persisted.  
+  These are orthogonal: a model can be `IsSaved=true` but `IsDirty=true` if the ViewModel has made new changes since the last save.
+- **Lifecycle Order**:  
+  `Initialize`/`InitializeAsync` → `Activated` → (user interaction) → `Cleanup`/`CleanupAsync`.  
+  `InitializeAsync` and `CleanupAsync` are asynchronous; callers must await them to ensure completion before proceeding.
+- **`IHeaderInfoProvider<T>`**: The `HeaderInfo` property is read-only (`get` only). Implementations must ensure `HeaderInfo` is non-null (or handle null gracefully) for XAML binding.
+
+---
+
+### 4. Dependencies
+
+#### Dependencies *of this module*:
+- **`System.ComponentModel`**: Required for `INotifyPropertyChanged` (used in `IBasePropertyChanged`, `IBaseWindowModel`, `IBaseViewModel`).
+- **`System.Threading.Tasks`**: Required for `Task` return types in `IBaseViewModel` and `IBaseWindowModel`.
+
+#### Dependencies *on this module* (inferred from naming conventions and usage patterns):
+- **UI Layer**: Views (e.g., WPF `Window`, `UserControl`) likely implement `IBaseView`/`IBaseWindow` and bind `DataContext` to ViewModels implementing `IBaseViewModel`/`IBaseWindowModel`.
+- **ViewModel Layer**: Concrete ViewModels inherit from base classes implementing `IBaseViewModel` or `IBaseWindowModel`.
+- **Model Layer**: Domain models likely implement `IBaseModel`.
+- **Header Binding**: UI components (e.g., headers, toolbars) consume types implementing `IHeaderInfoProvider<T>`.
+
+#### No internal dependencies *within* this module (interfaces are self-contained).
+
+---
+
+### 5. Gotchas
+
+- **`IBaseWindowModel` does *not* inherit `IBasePropertyChanged`**: It directly implements `INotifyPropertyChanged`. This is inconsistent with `IBaseViewModel` (which inherits `IBasePropertyChanged`). Developers may mistakenly assume both share the same base contract.
+- **`OnPropertyChanged` signature lacks default parameter**: The interface defines `void OnPropertyChanged(string propertyName);` without a default value (commented-out alternatives exist in source but are not part of the contract). Implementers *must* pass a non-null property name (or risk silent failures).
+- **`IsDirty` is read-only**: Its value must be computed internally (e.g., via `SetProperty` logic or manual tracking). No setter is exposed, so external state changes (e.g., after save) require updating via internal logic.
+- **`Initialize(object parameter, object model)` is `IBaseViewModel`-only**: `IBaseWindowModel` lacks this overload. Using it in a Window-level ViewModel may cause ambiguity or require custom implementation.
+- **No default implementations**: These are *interfaces only*. Concrete behavior (e.g., `SetProperty`, `IsDirty` tracking) must be provided by base classes or implementations (not documented here).
+- **Namespace quirk**: All interfaces use `DTS.Common.Base` despite being in `DTS.CommonCore` paths. This may cause confusion if namespace resolution is expected to match folder structure.
+
+*None identified from source alone.*