init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Interface/DTS.Viewer/CalculatedChannel.md

@@ -0,0 +1,84 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/DTS.Viewer/CalculatedChannel/IAddCalculatedChannelView.cs
+  - Common/DTS.CommonCore/Interface/DTS.Viewer/CalculatedChannel/IAddCalculatedChannelViewModel.cs
+generated_at: "2026-04-16T02:33:14.120126+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "720d768a9bb759bc"
+---
+
+# CalculatedChannel
+
+## Documentation: `IAddCalculatedChannelView` and `IAddCalculatedChannelViewModel`
+
+---
+
+### 1. **Purpose**
+
+This module defines the MVVM (Model-View-ViewModel) interface contract for a UI component used to *add a new calculated channel* in the DTS Viewer application. It enables user interaction to configure and submit a new calculated channel definition, with support for grouping, encoding settings, and integration with a search region (likely for channel/channel-group discovery). The interfaces serve as decoupled abstractions between the view (UI layer) and view model (business logic layer), following the project’s base interface hierarchy (`IBaseView`, `IBaseViewModel`).
+
+---
+
+### 2. **Public Interface**
+
+#### `IAddCalculatedChannelView`
+- **Type**: `interface`
+- **Inherits**: `IBaseView`
+- **Behavior**: Represents the *view* (e.g., XAML user control) for the add-calculated-channel dialog. No additional members beyond the base view contract are declared—implementation details are expected in the concrete view class.
+
+#### `IAddCalculatedChannelViewModel`
+- **Type**: `interface`
+- **Inherits**: `IBaseViewModel`
+- **Members**:
+  - `IBaseView View { get; set; }`  
+    Gets or sets the associated view instance (the concrete implementation of `IAddCalculatedChannelView`). Enables bidirectional linkage between view and view model.
+  - `IBaseViewModel Parent { get; set; }`  
+    Gets or sets the parent view model (e.g., the main channel management view), allowing hierarchical navigation or coordination.
+  - `void PublishChanges();`  
+    Commits or submits the current configuration (e.g., channel name, expression, group, encoding) to the underlying system or model. Likely triggers validation and persistence logic.
+  - `bool IncludeGroupNameInISOExport { get; set; }`  
+    Gets or sets a flag indicating whether the group name should be included when exporting the calculated channel to ISO format (e.g., for interoperability or metadata preservation).
+  - `int DefaultDTSEncoding { get; set; }`  
+    Gets or sets the default encoding (as an integer code, e.g., `0 = UTF8`, `1 = ASCII`, etc.) used for the new channel. Exact encoding semantics are defined elsewhere (e.g., in `DTS.Common.Base` or a related enum).
+  - `ICommand AddCalculatedChannelCommand { get; }`  
+    Returns a command (e.g., bound to a “Save” button) that, when executed, invokes the logic to add the calculated channel (likely calls `PublishChanges()` internally).
+  - `object ContextSearchRegion { get; set; }`  
+    Gets or sets a region/context object used for channel/channel-group search operations (e.g., a container or scope for search results). Type is `object`, suggesting flexibility but low type safety.
+
+---
+
+### 3. **Invariants**
+
+- `View` and `Parent` must be non-null after initialization and before `PublishChanges()` is called (implied by typical MVVM patterns, though not explicitly enforced in the interface).
+- `AddCalculatedChannelCommand` must be non-null and executable (i.e., `CanExecute` returns `true` when the input is valid).
+- `DefaultDTSEncoding` must be a valid encoding identifier recognized by the DTS system (e.g., matching values in a known `DTSEncoding` enum or constant set).
+- `IncludeGroupNameInISOExport` must be respected during export operations (e.g., if `true`, group metadata must appear in the ISO output).
+- `ContextSearchRegion` must be compatible with the search logic used by the view (e.g., if the view expects a `SearchRegionContext`, assigning an incompatible type will cause runtime failure).
+
+---
+
+### 4. **Dependencies**
+
+- **Internal Dependencies**:
+  - `DTS.Common.Base.IBaseView` and `DTS.Common.Base.IBaseViewModel` — base interfaces for view/view model layers.
+  - `System.Windows.Input.ICommand` — WPF command infrastructure.
+- **Inferred Consumers**:
+  - A concrete implementation of `IAddCalculatedChannelView` (e.g., `AddCalculatedChannelView.xaml.cs`).
+  - A concrete implementation of `IAddCalculatedChannelViewModel` (e.g., `AddCalculatedChannelViewModel`).
+  - Likely used by a parent view model (e.g., `ChannelManagerViewModel`) that instantiates and hosts this dialog/view model.
+- **External Dependencies**:
+  - WPF (via `ICommand` and likely XAML binding).
+  - `DTS.Common.Base` assembly (for base interfaces).
+
+---
+
+### 5. **Gotchas**
+
+- **Ambiguous `ContextSearchRegion` type**: The property is typed as `object`, making it unclear what concrete types are expected or supported. Consumers must rely on documentation or implementation details to avoid runtime type mismatches.
+- **No explicit validation or error reporting**: The interface does not define properties like `IsValid` or `ErrorMessage`, suggesting error handling may be implicit (e.g., via command `CanExecute` state or side effects of `PublishChanges()`).
+- **`DefaultDTSEncoding` is an `int`**: Using a raw integer instead of an enum or strongly-typed constant increases risk of invalid values (e.g., `-1`, `999`). Validation must occur at runtime.
+- **No cancellation support**: The interface lacks a `CancelCommand` or `IsCancellationRequested` flag—users may assume cancellation is possible, but it is not surfaced here.
+- **No documentation for `PublishChanges()` semantics**: It is unclear whether this method performs validation, throws exceptions on failure, or returns status. Implementation-specific behavior must be consulted.
+
+*None identified beyond the above.*