init

enriched-qwen3-coder-next/Common/DTS.Common/Events/ChannelCodes.md

@@ -0,0 +1,68 @@
+---
+source_files:
+  - Common/DTS.Common/Events/ChannelCodes/ChannelCodesViewChangedEvent.cs
+  - Common/DTS.Common/Events/ChannelCodes/ChannelCodeCommittedEvent.cs
+generated_at: "2026-04-16T03:25:06.865522+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "6fb84d209aefd419"
+---
+
+# ChannelCodes
+
+## Documentation: Channel Codes Event Definitions
+
+### 1. Purpose  
+This module defines Prism-based pub/sub events used to communicate channel code state changes across the application—specifically, when the user switches the view mode for channel codes (`ChannelCodesViewChangedEvent`) and when one or more channel codes are committed (saved) by the user (`ChannelCodeCommittedEvent`). These events decouple UI components (e.g., views, viewmodels) that trigger or react to channel code operations, enabling modular and testable interaction without tight coupling.
+
+---
+
+### 2. Public Interface  
+
+#### `ChannelCodesViewChangedEvent`  
+- **Type**: `class` (inherits `PubSubEvent<DTS.Common.Enums.IsoViewMode>`)  
+- **Payload**: `DTS.Common.Enums.IsoViewMode`  
+- **Behavior**: A singleton event used to notify subscribers when the active view mode for channel codes has changed. The payload indicates the new view mode (e.g., `IsoViewMode.List`, `IsoViewMode.Tree`). Subscribers should update their UI or internal state accordingly.
+
+#### `ChannelCodeCommittedEvent`  
+- **Type**: `class` (inherits `PubSubEvent<ChannelCodeCommittedEventArgs[]>`)  
+- **Payload**: `ChannelCodeCommittedEventArgs[]` (array of committed channel codes)  
+- **Behavior**: A singleton event used to publish one or more channel codes that have been successfully committed (e.g., saved or persisted). Subscribers may refresh caches, update related UI, or audit the action.
+
+##### `ChannelCodeCommittedEventArgs`  
+- **Type**: `class`  
+- **Properties**:  
+  - `ChannelCodeType`: `ChannelEnumsAndConstants.ChannelCodeType` — the semantic type of the channel code (e.g., `ChannelCodeType.Network`, `ChannelCodeType.Service`).  
+  - `Code`: `string` — the canonical identifier string for the channel code (e.g., `"NBC"`).  
+  - `Name`: `string` — the human-readable display name (e.g., `"National Broadcasting Company"`).  
+  - `CanUserCommitChannelCodes`: `bool` — indicates whether the user who triggered the commit has write privileges for channel codes.  
+- **Behavior**: Encapsulates metadata about a single committed channel code. Instances are created and published as part of the `ChannelCodeCommittedEvent` payload.
+
+---
+
+### 3. Invariants  
+- `ChannelCodeCommittedEventArgs.Code` and `ChannelCodeCommittedEventArgs.Name` are non-null (enforced by constructor; no validation is performed in the class itself, but nulls would likely cause downstream failures).  
+- `ChannelCodeCommittedEventArgs.ChannelCodeType` must be a valid member of `ChannelEnumsAndConstants.ChannelCodeType` (enforced by caller; no runtime check in the class).  
+- `ChannelCodeCommittedEvent` payload is always an array (possibly empty or with one or more elements); no ordering guarantee is specified.  
+- `CanUserCommitChannelCodes` reflects the *submitting user’s* privileges at the time of commit, not necessarily the current user’s privileges.
+
+---
+
+### 4. Dependencies  
+- **Dependencies on other modules**:  
+  - `Prism.Events` (external library for event aggregation).  
+  - `DTS.Common.Enums` (for `IsoViewMode` used in `ChannelCodesViewChangedEvent`).  
+  - `DTS.Common.Enums.Channels` (for `ChannelEnumsAndConstants.ChannelCodeType` used in `ChannelCodeCommittedEventArgs`).  
+- **Depended upon by**:  
+  - UI components (e.g., views/viewmodels handling channel code display or editing) that subscribe to these events to synchronize state.  
+  - Likely consumed by modules in `DTS.Common` and higher layers (e.g., `DTS.Client` or `DTS.Application`) that manage channel code workflows.
+
+---
+
+### 5. Gotchas  
+- **Namespace inconsistency**: `ChannelCodesViewChangedEvent` resides in `DTS.Common.Events`, while `ChannelCodeCommittedEvent` resides in `DTS.Common.Events.ChannelCodes`. This may cause confusion when discovering or subscribing to events.  
+- **No validation in `ChannelCodeCommittedEventArgs`**: The constructor accepts any `string` values for `Code`/`Name` and does not enforce non-empty or format constraints. Callers must ensure validity.  
+- **Privilege flag is static at commit time**: `CanUserCommitChannelCodes` is captured at the moment of commit and does not reflect potential privilege changes afterward. Subscribers should treat it as a historical snapshot.  
+- **No documentation of `IsoViewMode` values**: The meaning of each `IsoViewMode` enum member is not included here; refer to `DTS.Common.Enums.IsoViewMode` definition.  
+- **Array payload may be empty**: `ChannelCodeCommittedEvent` may be published with an empty array (e.g., in batch operations where no codes were actually modified). Subscribers should handle this case.  
+- **None identified from source alone** for `ChannelCodesViewChangedEvent` beyond namespace inconsistency.