init

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

@@ -0,0 +1,88 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/Channels/ChannelCodes/IChannelCodesListView.cs
+  - Common/DTS.CommonCore/Interface/Channels/ChannelCodes/IChannelCodesListViewModel.cs
+  - Common/DTS.CommonCore/Interface/Channels/ChannelCodes/IChannelCode.cs
+generated_at: "2026-04-16T02:38:26.071478+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "0d6003b6ee26589a"
+---
+
+# ChannelCodes
+
+### **Purpose**  
+This module defines the core interfaces for a channel codes management UI component within the DTS system. It establishes a standardized contract between the view, view model, and individual channel code entities, enabling consistent handling of both ISO-standard and user-defined channel codes. The module supports operations such as loading, editing, filtering, sorting, saving, and validating channel codes, while abstracting UI-specific concerns (e.g., paste handling, status indication) through well-defined interfaces.
+
+---
+
+### **Public Interface**  
+
+#### **`IChannelCodesListView`**  
+- **Inherits**: `IBaseView`  
+- **Description**: A marker interface representing the view layer for the channel codes list UI. No additional members beyond base view functionality.  
+
+#### **`IChannelCodesListViewModel`**  
+- **Inherits**: `IBaseViewModel`  
+- **Properties**:  
+  - `IChannelCodesListView View { get; set; }` — Reference to the associated view instance.  
+  - `ObservableCollection<IChannelCode> ISOChannelCodes { get; set; }` — Collection of ISO-standard channel codes.  
+  - `ObservableCollection<IChannelCode> UserChannelCodes { get; set; }` — Collection of user-defined channel codes.  
+  - `Func<IList<IChannelCode>> ChannelCodesFunc { get; }` — A delegate returning the full list of channel codes (likely used for persistence or validation).  
+  - `bool ShowISOStringBuilder { get; set; }` — Controls visibility of the ISO channel code builder UI.  
+  - `bool UniqueISOCodesRequired { get; set; }` — Enforces uniqueness constraint on ISO codes.  
+  - `bool ShowChannelCodeLookupHelper { get; set; }` — Toggles visibility of a lookup helper UI.  
+  - `bool IsReadOnly { get; set; }` — If `true`, disables editing operations.  
+  - `IChannelCode[] SelectedCodes { get; }` — Returns the currently selected channel codes.  
+- **Methods**:  
+  - `void Unset()` — Cleans up view model state, likely detaching from the view.  
+  - `void SetPage(object page)` — Associates the view model with a specific UI page (e.g., for navigation context).  
+  - `void OnSetActive()` — Invoked when the view becomes active (e.g., on navigation to the page).  
+  - `bool Save()` — Persists changes to the channel codes; returns `true` on success.  
+  - `bool Validate(bool bDisplayWindow)` — Validates the channel codes; if `bDisplayWindow` is `true`, shows validation errors in a dialog.  
+  - `void CopySelected()` — Copies selected channel codes to the clipboard.  
+  - `void DeleteSelected()` — Deletes the selected channel codes.  
+  - `void Filter(object columnTag, string searchTerm)` — Filters the displayed codes by `searchTerm` on the column identified by `columnTag`.  
+  - `void Sort(object columnTag, bool bColumnClick)` — Sorts the displayed codes by the column identified by `columnTag`; `bColumnClick` indicates if triggered by user column click.  
+
+#### **`IChannelCode`**  
+- **Properties**:  
+  - `int Id { get; }` — Database identifier of the channel code.  
+  - `string Code { get; set; }` — The code value (ISO or user-defined).  
+  - `string Name { get; set; }` — Human-readable name for the channel code.  
+  - `ChannelEnumsAndConstants.ChannelCodeType CodeType { get; }` — Indicates whether the code is `ISO` or `USER` (from `DTS.Common.Enums.Channels`).  
+  - `ICommand PasteCommand { get; set; }` — Command invoked when pasting multi-row data (e.g., CSV) into a field.  
+  - `UIItemStatus ItemStatus { get; set; }` — UI status (e.g., success, error) for the item.  
+
+---
+
+### **Invariants**  
+- `ISOChannelCodes` and `UserChannelCodes` are mutually exclusive collections (per `CodeType`).  
+- If `UniqueISOCodesRequired` is `true`, duplicate `Code` values in `ISOChannelCodes` must be rejected during validation or save.  
+- `IsReadOnly` mode must prevent modification of `Code`, `Name`, and deletion/copy operations (though `CopySelected` may still be allowed depending on implementation).  
+- `SelectedCodes` must reflect the current selection state in the view at all times.  
+- `ChannelCodesFunc` must return a consistent, up-to-date list of all channel codes (both ISO and user) when invoked.  
+
+---
+
+### **Dependencies**  
+- **Internal Dependencies**:  
+  - `DTS.Common.Base` (provides `IBaseView`, `IBaseViewModel`).  
+  - `DTS.Common.Enums` (provides `UIItemStatus`, `ChannelEnumsAndConstants.ChannelCodeType`).  
+- **External Dependencies**:  
+  - WPF (`System.Windows.Input.ICommand`, `ObservableCollection<T>`).  
+- **Depended Upon By**:  
+  - UI layers implementing `IChannelCodesListView` (e.g., XAML views).  
+  - View model implementations for channel codes management (e.g., `ChannelCodesListViewModel`).  
+  - Persistence or domain services that consume `ChannelCodesFunc` to serialize or validate codes.  
+
+---
+
+### **Gotchas**  
+- **`PasteCommand` behavior is UI-specific**: While the interface exposes `PasteCommand`, the actual parsing logic for multi-row pastes (e.g., CSV) is not defined here and must be implemented by concrete types.  
+- **`ChannelCodesFunc` is a delegate, not a property**: Its value may be lazily evaluated or change over time; callers should not cache its result.  
+- **`ShowISOStringBuilder`, `ShowChannelCodeLookupHelper`, and `IsReadOnly` are mutable properties**: Their values may change at runtime, and implementations must react appropriately (e.g., re-enabling/disabling UI controls).  
+- **`Validate` behavior depends on `bDisplayWindow`**: When `false`, validation may only return a boolean without user feedback—callers must handle error reporting if needed.  
+- **No explicit thread-safety guarantees**: `ObservableCollection<T>` is not thread-safe; modifications to `ISOChannelCodes`/`UserChannelCodes` must occur on the UI thread.  
+- **`SelectedCodes` is an array, not a collection**: Its contents may be stale if selection changes between calls; callers should use it immediately after selection operations.  
+- **None identified from source alone.**