init

enriched-qwen3-coder-next/Common/DTS.Common/Events/Groups/GroupChannelList.md

@@ -0,0 +1,91 @@
+---
+source_files:
+  - Common/DTS.Common/Events/Groups/GroupChannelList/GroupChannelDeleteRequestEvent.cs
+  - Common/DTS.Common/Events/Groups/GroupChannelList/GroupChannelsChangedEvent.cs
+  - Common/DTS.Common/Events/Groups/GroupChannelList/GroupUpdatedEvent.cs
+generated_at: "2026-04-16T03:26:19.461930+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "a198b0938e9f2ac1"
+---
+
+# GroupChannelList
+
+## Documentation: GroupChannelList Events Module
+
+### 1. Purpose  
+This module defines Prism-based pub/sub events used to coordinate group channel list state changes across loosely coupled components in the application. Specifically, it enables decoupled communication for three distinct scenarios: (1) a request to delete a channel from a group (`GroupChannelDeleteRequestEvent`), (2) notification that the set of channels in a group has changed (`GroupChannelsChangedEvent`), and (3) notification that a group’s state has been updated via channel insertion or assignment (`GroupUpdatedEvent`). These events facilitate UI-layer and service-layer synchronization without tight coupling, particularly around group template selection and channel management workflows.
+
+---
+
+### 2. Public Interface  
+
+#### `GroupChannelDeleteRequestEvent`  
+- **Type**: `class` inheriting from `PubSubEvent<GroupChannelDeleteRequestEventArgs>`  
+- **Behavior**: A Prism event used to signal that a channel deletion is requested. Subscribers receive a `GroupChannelDeleteRequestEventArgs` payload containing the page context and the channel to be deleted.  
+
+#### `GroupChannelDeleteRequestEventArgs`  
+- **Constructor**: `GroupChannelDeleteRequestEventArgs(object page, IGroupChannel channel)`  
+- **Properties**:  
+  - `object Page` — The UI page (e.g., view model or control) initiating or associated with the deletion request.  
+  - `IGroupChannel Channel` — The channel instance targeted for deletion.  
+
+#### `GroupChannelsChangedEvent`  
+- **Type**: `class` inheriting from `PubSubEvent<GroupChannelsChangedEventArgs>`  
+- **Behavior**: A Prism event used to notify subscribers that the number of channels in a group has changed (e.g., after adding/removing channels).  
+- **Note**: Despite the summary comment referencing “The GroupUpdated event”, the actual event name is `GroupChannelsChangedEvent`.  
+
+#### `GroupChannelsChangedEventArgs`  
+- **Constructor**: `GroupChannelsChangedEventArgs(object group, int channelCount)`  
+- **Properties**:  
+  - `object Group` — The group whose channel count has changed.  
+  - `int ChannelCount` — The new total number of channels in the group.  
+
+#### `GroupUpdatedEvent`  
+- **Type**: `class` inheriting from `PubSubEvent<GroupUpdatedEventArgs>`  
+- **Behavior**: A Prism event used to signal that a group’s state has been updated in a specific way (channel insertion or assignment).  
+- **Note**: The XML summary incorrectly labels this as “The GroupUpdated event” but the class name is `GroupUpdatedEvent`.  
+
+#### `GroupUpdatedEventArgs`  
+- **Constructor**: `GroupUpdatedEventArgs(object page, Status status)`  
+- **Properties**:  
+  - `object Page` — The UI page (e.g., view model or control) where the update occurred.  
+  - `Status UpdateStatus` — The type of update performed (see `Status` enum below).  
+- **Nested Enum `Status`**:  
+  - `ChannelsInserted` — Indicates channels were inserted into the group.  
+  - `AssignmentsMade` — Indicates channel assignments were modified (e.g., user/group assignments).  
+
+---
+
+### 3. Invariants  
+
+- **Event Payload Immutability**: All `EventArgs` classes expose only read-only properties (`get;`), and their constructors enforce non-null assignment of all fields at construction time.  
+- **Page Context Consistency**: In both `GroupChannelDeleteRequestEventArgs` and `GroupUpdatedEventArgs`, the `Page` property is expected to represent the originating UI context (e.g., a view model or control instance), though the type is `object`, allowing flexibility but requiring callers to ensure consistency.  
+- **Channel Count Validity**: In `GroupChannelsChangedEventArgs`, `ChannelCount` is expected to reflect the *current* number of channels in the group after the change, not a delta.  
+- **Status Exhaustiveness**: `GroupUpdatedEventArgs.Status` is a closed enum with exactly two values; no other statuses are defined.  
+
+---
+
+### 4. Dependencies  
+
+#### Dependencies *of* this module:  
+- **Prism.Events**: All event types derive from `PubSubEvent<T>` (from the Prism library), indicating a dependency on Prism’s event aggregation framework.  
+- **DTS.Common.Interface.Channels**: `GroupChannelDeleteRequestEventArgs` depends on the `IGroupChannel` interface (imported via `using DTS.Common.Interface.Channels;`).  
+
+#### Dependencies *on* this module:  
+- Any module or component that needs to coordinate group channel list changes (e.g., UI pages, channel management services) will subscribe to or publish these events.  
+- Specifically, components managing group templates (as suggested by the `<remarks>` in `GroupChannelsChangedEvent` and `GroupUpdatedEvent`) likely depend on this module.  
+
+---
+
+### 5. Gotchas  
+
+- **Ambiguous `object` Types**: The `Page` and `Group` properties are typed as `object`, not a specific interface or base class. This introduces ambiguity: consumers must know the expected concrete types (e.g., likely view models or controls) to safely cast or use them.  
+- **Misleading XML Comments**:  
+  - `GroupChannelsChangedEvent`’s summary says “The GroupUpdated event” — this appears to be a copy-paste error.  
+  - Both `GroupChannelsChangedEvent` and `GroupUpdatedEvent` have `<remarks>` stating “called when a template is selected,” but `GroupChannelDeleteRequestEvent` has no such comment. This may imply inconsistent documentation or that the remarks apply only to certain events.  
+- **No Validation on `ChannelCount`**: `GroupChannelsChangedEventArgs` accepts any `int` for `channelCount`, including negative values. While unlikely, there is no runtime enforcement that `channelCount ≥ 0`.  
+- **No Cancellation Mechanism**: `GroupChannelDeleteRequestEvent` is a *request* event, but there is no built-in cancellation or confirmation mechanism (e.g., via `CancelableEventArgs`). Subscribers must handle deletion logic themselves, and callers cannot abort the operation based on subscriber responses.  
+- **Enum Naming vs. Semantics**: `GroupUpdatedEventArgs.Status.AssignmentsMade` is vague — it could mean assignment of users to channels, channels to groups, or other relationships. The interface `IGroupChannel` is not defined here, so the exact semantics of “assignments” cannot be inferred.  
+
+None identified beyond the above.