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.

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

@@ -0,0 +1,58 @@
+---
+source_files:
+  - Common/DTS.Common/Events/Groups/GroupsList/GroupListEditGroupEvent.cs
+  - Common/DTS.Common/Events/Groups/GroupsList/GroupListGroupSelectedEvent.cs
+generated_at: "2026-04-16T03:26:07.948442+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "bca3088a7f9f7005"
+---
+
+# GroupsList
+
+## Documentation: Group List Events Module
+
+### 1. Purpose  
+This module defines two Prism-based pub/sub events used to communicate group selection and editing actions within the group list UI layer. Specifically, `GroupListEditGroupEvent` signals that a single group should be edited (via its numeric ID), while `GroupListGroupSelectedEvent` signals that a set of groups has been selected (via an array of IDs). These events decouple UI components (e.g., a group list view) from handlers (e.g., a view model or controller responsible for launching an edit dialog or performing bulk operations), enabling flexible event-driven interactions in the application’s MVVM architecture.
+
+---
+
+### 2. Public Interface  
+
+#### `GroupListEditGroupEvent`
+- **Signature**: `public class GroupListEditGroupEvent : PubSubEvent<int> { }`  
+- **Behavior**: A Prism `PubSubEvent<int>` used to publish when a single group is selected for editing. The payload is the group’s integer ID. Subscribers receive this ID to initiate editing logic (e.g., opening an edit dialog for the group with that ID).
+
+#### `GroupListGroupSelectedEvent`
+- **Signature**: `public class GroupListGroupSelectedEvent : PubSubEvent<int[]> { }`  
+- **Behavior**: A Prism `PubSubEvent<int[]>` used to publish when multiple groups are selected (e.g., via multi-select UI). The payload is an array of group IDs (`int[]`) representing the currently selected groups. Subscribers may use this to enable bulk operations (e.g., delete, assign) or update selection state.
+
+> **Note**: Both event classes have no public methods, properties, or constructors beyond the inherited `PubSubEvent<TPayload>` behavior (e.g., `Subscribe`, `Publish`). Their sole purpose is to define strongly-typed event payloads.
+
+---
+
+### 3. Invariants  
+- `GroupListEditGroupEvent` **always** carries a single non-null `int` payload representing a valid group identifier.  
+- `GroupListGroupSelectedEvent` **always** carries a non-null `int[]` payload. The array may be empty (indicating deselection of all groups) but must not be `null`.  
+- IDs in both events are expected to correspond to existing groups in the system’s data model (though validation is not enforced by the event classes themselves).  
+- No ordering guarantee is provided for `int[]` payloads in `GroupListGroupSelectedEvent`; the order of IDs is implementation-dependent (e.g., reflects UI selection order or internal storage order).
+
+---
+
+### 4. Dependencies  
+- **Depends on**:  
+  - `Prism.Events.PubSubEvent<T>` (from the Prism library) — base class for both events.  
+  - `DTS.Common` namespace — shared common library (implied by `DTS.Common.Events` namespace).  
+- **Depended on by**:  
+  - UI components (e.g., group list views) that publish these events on user interaction.  
+  - View models or services that subscribe to these events to handle group editing or selection logic.  
+  - *Inferred*: Any module handling group lifecycle operations (e.g., editing, bulk actions) will likely reference these events.
+
+---
+
+### 5. Gotchas  
+- **Misleading XML documentation**: Both events’ `<summary>` and `<remarks>` incorrectly reference `"GroupTemplateListGroupTemplateSelectedEvent"` and `"called when a template is selected"`. This appears to be copy-paste error or outdated documentation; the actual purpose relates to *groups*, not templates.  
+- **Ambiguous selection semantics**: `GroupListGroupSelectedEvent`’s payload (`int[]`) does not distinguish between user-initiated selection changes (e.g., adding/removing items) and explicit "apply" actions. Subscribers must infer intent from context or additional state.  
+- **No validation in event**: Neither event validates that IDs exist or are non-negative. Invalid IDs may propagate to subscribers, requiring defensive handling.  
+- **Thread-safety**: As Prism `PubSubEvent` instances, events are published on the UI thread by default (unless configured otherwise), but subscribers must ensure thread-safe operations if they perform non-UI work.  
+- **None identified from source alone** for behavioral quirks beyond the above.