init

enriched-qwen3-coder-next/Common/DTS.Common/Interface/Channels/ChannelCodes.md

@@ -0,0 +1,117 @@
+---
+source_files:
+  - Common/DTS.Common/Interface/Channels/ChannelCodes/IChannelCodesListView.cs
+  - Common/DTS.Common/Interface/Channels/ChannelCodes/IChannelCodesListViewModel.cs
+  - Common/DTS.Common/Interface/Channels/ChannelCodes/IChannelCode.cs
+generated_at: "2026-04-16T03:13:50.172717+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "8f7a27f97cbd53de"
+---
+
+# ChannelCodes
+
+## Documentation: Channel Codes List Module
+
+---
+
+### 1. Purpose  
+This module defines the core interfaces for a UI component that manages and displays channel codes—specifically distinguishing between ISO-standardized codes and user-defined codes. It provides a structured contract for a list-based view (`IChannelCodesListView`) and its associated view model (`IChannelCodesListViewModel`), enabling data binding, editing, validation, and manipulation (copy, delete, filter, sort) of channel code entries. The module exists to decouple UI presentation logic from data persistence while enforcing consistent behavior across implementations for channel code management in the DTS system.
+
+---
+
+### 2. Public Interface  
+
+#### `IChannelCodesListView`  
+- **Inherits**: `IBaseView`  
+- **Description**: A marker interface representing the view layer for the channel codes list. It has no additional members beyond inheritance, implying it relies on conventions or base view infrastructure for implementation.
+
+#### `IChannelCodesListViewModel`  
+- **Inherits**: `IBaseViewModel`  
+- **Properties**:  
+  - `IChannelCodesListView View { get; set; }`  
+    Gets or sets the associated view instance (MVVM pattern).  
+  - `ObservableCollection<IChannelCode> ISOChannelCodes { get; set; }`  
+    Collection of ISO-standard channel codes displayed in the list.  
+  - `ObservableCollection<IChannelCode> UserChannelCodes { get; set; }`  
+    Collection of user-defined channel codes displayed in the list.  
+  - `Func<IList<IChannelCode>> ChannelCodesFunc { get; }`  
+    A delegate returning the *complete* list of channel codes (both ISO and user) for external use (e.g., saving, validation).  
+  - `IChannelCode[] SelectedCodes { get; }`  
+    Returns the currently selected `IChannelCode` items in the UI.  
+  - `bool ShowISOStringBuilder { get; set; }`  
+    Controls visibility of the ISO code builder UI component.  
+  - `bool UniqueISOCodesRequired { get; set; }`  
+    Enables/disables validation requiring ISO codes to be unique.  
+  - `bool ShowChannelCodeLookupHelper { get; set; }`  
+    Controls visibility of a helper UI for looking up channel codes.  
+  - `bool IsReadOnly { get; set; }`  
+    If `true`, disables editing operations (e.g., paste, delete, copy).  
+
+- **Methods**:  
+  - `void Unset()`  
+    Releases resources or clears state associated with the current view (e.g., detaching event handlers).  
+  - `void SetPage(object page)`  
+    Associates the view model with a specific page instance (likely for navigation or context).  
+  - `void OnSetActive()`  
+    Invoked when the view becomes active (e.g., on navigation to the page); likely triggers data refresh or initialization.  
+  - `bool Save()`  
+    Persists changes to the channel codes; returns `true` on success, `false` otherwise.  
+  - `bool Validate(bool bDisplayWindow)`  
+    Validates the current state of channel codes (e.g., uniqueness, required fields); if `bDisplayWindow` is `true`, shows validation errors in a UI dialog.  
+  - `void CopySelected()`  
+    Copies the selected `IChannelCode` items to the clipboard (likely in a structured format).  
+  - `void DeleteSelected()`  
+    Deletes the selected `IChannelCode` items from their respective collections.  
+  - `void Filter(object columnTag, string searchTerm)`  
+    Filters the displayed list based on `searchTerm` in the column identified by `columnTag`.  
+  - `void Sort(object columnTag, bool bColumnClick)`  
+    Sorts the displayed list by the column identified by `columnTag`; `bColumnClick` indicates if the sort was triggered by a user clicking the column header (likely toggles sort direction).
+
+#### `IChannelCode`  
+- **Properties**:  
+  - `int Id { get; }`  
+    Database identifier for the channel code.  
+  - `string Code { get; set; }`  
+    The code value (e.g., `"ISO-8601"` or `"CUSTOM-A"`).  
+  - `string Name { get; set; }`  
+    Human-readable name associated with the code (e.g., `"Date Format"` or `"Custom Input"`).  
+  - `ChannelEnumsAndConstants.ChannelCodeType CodeType { get; }`  
+    Enum value indicating whether the code is `ISO` or `USER`-defined (from `DTS.Common.Enums.Channels`).  
+  - `ICommand PasteCommand { get; set; }`  
+    Command handler for pasting multi-row or CSV data into a single field (e.g., pasting multiple codes into the `Code` or `Name` field).  
+  - `UIItemStatus ItemStatus { get; set; }`  
+    Current UI validation status (e.g., `Success`, `Warning`, `Error`) for the item (from `DTS.Common.Enums`).  
+
+---
+
+### 3. Invariants  
+- `ISOChannelCodes` and `UserChannelCodes` collections are mutually exclusive in type (`IChannelCode.CodeType` must match the collection’s semantic purpose).  
+- `ChannelCodesFunc` must return a *complete* list containing all items from both `ISOChannelCodes` and `UserChannelCodes` (order unspecified).  
+- `SelectedCodes` must reflect the *current* selection state at the time of access (no caching delay).  
+- `IsReadOnly = true` must prevent all mutation operations (`DeleteSelected`, `CopySelected`, `PasteCommand`, and edits to `Code`/`Name`).  
+- `Validate` with `bDisplayWindow = true` must display errors to the user; with `false`, it must only perform validation silently (e.g., for pre-save checks).  
+- `UniqueISOCodesRequired = true` implies `Validate` must enforce uniqueness of `Code` values *only* among `ISOChannelCodes`.  
+
+---
+
+### 4. Dependencies  
+- **Depends on**:  
+  - `DTS.Common.Base` (for `IBaseView`, `IBaseViewModel`).  
+  - `System.Collections.ObjectModel` (for `ObservableCollection<T>`).  
+  - `DTS.Common.Enums` (for `UIItemStatus`, `ChannelCodeType`).  
+  - `System.Windows.Input` (for `ICommand`).  
+- **Depended on by**:  
+  - Concrete implementations of `IChannelCodesListView` (e.g., WPF `UserControl` or `Window`), `IChannelCodesListViewModel` (e.g., `ChannelCodesListViewModel`), and `IChannelCode` (e.g., `ISOChannelCode`, `UserChannelCode`).  
+  - Likely consumed by higher-level modules managing channel configuration or system setup (inferred from namespace `DTS.Common.Interface.Channels`).  
+
+---
+
+### 5. Gotchas  
+- `PasteCommand` is defined on `IChannelCode`, but its behavior (e.g., parsing CSV, splitting rows) is not specified—implementation must handle multi-row pasting consistently.  
+- `ChannelCodesFunc` is a delegate, not a property returning a collection directly; callers must invoke it to get the latest list (risk of stale data if cached).  
+- `SelectedCodes` is an array (`IChannelCode[]`), not a collection—consumers must not modify the array (it is likely a snapshot).  
+- `SetPage(object page)` uses `object` instead of a typed interface (e.g., `IPage`), suggesting tight coupling to a specific UI framework (e.g., WPF `Page`).  
+- `Filter` and `Sort` use `object columnTag` without defining expected values—implementation must rely on conventions (e.g., string column names or enum values).  
+- No explicit thread-safety guarantees; `ObservableCollection` updates are likely expected on the UI thread.  
+- **Critical ambiguity**: `Validate`’s behavior when `UniqueISOCodesRequired = true` is *not* enforced in the interface—implementation must ensure uniqueness *only* for ISO codes, but the interface does not clarify if user codes must also be unique or if they may overlap with ISO codes.