init

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

@@ -0,0 +1,93 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/Graphs/IGraph.cs
+  - Common/DTS.CommonCore/Interface/Graphs/IGraphRecord.cs
+generated_at: "2026-04-16T02:23:21.443229+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "a5e5bc31a5802f38"
+---
+
+# Graphs
+
+## Documentation: `IGraph` Interface
+
+---
+
+### 1. **Purpose**
+
+The `IGraph` interface defines the contract for a graph entity that aggregates and manages a collection of `IGroupChannel` instances, along with associated display and persistence metadata. It extends `IGraphRecord` to combine database-backed metadata (e.g., name, axis limits, thresholds) with runtime graph composition logic (adding/removing channels, XML serialization/deserialization). This module serves as the core abstraction for graph configuration in the system—enabling programmatic manipulation of channel groupings and persistence of graph state to/from XML and database records.
+
+---
+
+### 2. **Public Interface**
+
+#### `IGraph` Interface (inherits `IGraphRecord`)
+
+- **`void AddChannel(IGroupChannel groupChannel)`**  
+  Adds the specified `IGroupChannel` to the graph’s internal collection of channels. Must be called before serialization to ensure the channel is included in `ChannelsString`.
+
+- **`void RemoveChannel(IGroupChannel groupChannel)`**  
+  Removes the specified `IGroupChannel` from the graph’s internal collection of channels. Must be followed by `UpdateChannelAndThresholdStrings()` to persist the change to `ChannelsString`.
+
+- **`void ReadXML(System.Xml.XmlElement root, IReadOnlyDictionary<long, IGroupChannel> channelLookup)`**  
+  Deserializes graph state from an XML element (`root`). Uses `channelLookup` to resolve channel references by ID (keyed by `long`). Populates the graph’s channels and metadata (e.g., axis limits, thresholds) from XML. *Note: Does not automatically call `UpdateChannelAndThresholdStrings()`—callers must do so explicitly if needed.*
+
+- **`void WriteXML(ref System.Xml.XmlWriter writer)`**  
+  Serializes the graph’s state (including channels and thresholds) to XML using the provided `XmlWriter`. Relies on the current values of `ChannelsString` and `ThresholdsString`, which must be up-to-date (e.g., via `UpdateChannelAndThresholdStrings()`).
+
+- **`void UpdateChannelAndThresholdStrings()`**  
+  Synchronizes the `ChannelsString` and `ThresholdsString` properties with the current in-memory state of `GroupChannels` and `Thresholds`. *This method must be invoked before `WriteXML()` or any database persistence to ensure consistency.*
+
+#### `IGraphRecord` Interface (inherited members)
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `GraphId` | `int` | Database primary key for the graph record. |
+| `TestSetupId` | `int` | Foreign key linking the graph to a specific test setup. |
+| `GraphName` | `string` | Human-readable name (max 50 chars). |
+| `GraphDescription` | `string` | Human-readable description (max 50 chars). |
+| `ChannelsString` | `string` | Serialized list of channel identifiers (max 2048 chars). |
+| `UseDomainMin`, `DomainMin` | `bool`, `double` | Controls whether the domain (X) axis minimum is enforced. |
+| `UseDomainMax`, `DomainMax` | `bool`, `double` | Controls whether the domain (X) axis maximum is enforced. |
+| `UseRangeMin`, `RangeMin` | `bool`, `double` | Controls whether the range (Y) axis minimum is enforced. |
+| `UseRangeMax`, `RangeMax` | `bool`, `double` | Controls whether the range (Y) axis maximum is enforced. |
+| `ThresholdsString` | `string` | Serialized list of threshold definitions (max 2048 chars). |
+| `LocalOnly` | `bool` | **Deprecated** flag indicating whether the record is local-only (not synced to central DB). |
+
+> **Note**: `IGraphRecord` does *not* expose `GroupChannels` or `Thresholds` as properties—these are inferred to be internal to implementations of `IGraph`. The `ChannelsString` and `ThresholdsString` are the persisted representations.
+
+---
+
+### 3. **Invariants**
+
+- `ChannelsString` and `ThresholdsString` **must** be kept in sync with the in-memory channel/threshold state via `UpdateChannelAndThresholdStrings()` before persistence (e.g., `WriteXML`, DB save).
+- `GraphName` and `GraphDescription` are constrained to ≤ 50 characters (via `[MaxLength(50)]`).
+- `ChannelsString` and `ThresholdsString` are constrained to ≤ 2048 characters (via `[MaxLength(2048)]`).
+- Axis limits (`DomainMin`, `DomainMax`, etc.) are only semantically valid when their corresponding `Use*` flag is `true`.
+- `LocalOnly` is deprecated and should be ignored in new logic.
+
+---
+
+### 4. **Dependencies**
+
+- **Depends on**:
+  - `DTS.Common.Interface.Channels.IGroupChannel` (for channel management).
+  - `System.Collections.Generic.IReadOnlyDictionary<long, IGroupChannel>` (for XML deserialization channel resolution).
+  - `System.Xml.XmlElement`, `System.Xml.XmlWriter` (for XML I/O).
+  - `System.ComponentModel.DataAnnotations` (for metadata annotations like `[MaxLength]`).
+
+- **Depended on by**:
+  - Likely consumed by UI layers (graph rendering), persistence services (DB/XML I/O), and test setup configuration modules (given `TestSetupId`).
+  - Implementations (not shown) would be concrete graph types (e.g., `Graph`, `TimeSeriesGraph`).
+
+---
+
+### 5. **Gotchas**
+
+- **Critical**: `ReadXML` does *not* automatically call `UpdateChannelAndThresholdStrings()`—implementations or callers must ensure strings are updated post-deserialization if persistence is required.
+- **Critical**: `AddChannel`/`RemoveChannel` modify internal state but do *not* update `ChannelsString`; `UpdateChannelAndThresholdStrings()` must be called explicitly afterward.
+- **Ambiguity**: The interface does not expose `GroupChannels` or `Thresholds` as properties—only their serialized string forms (`ChannelsString`, `ThresholdsString`). This implies implementations manage these collections internally, but the exact structure (e.g., `List<IGroupChannel>`, `HashSet<IGroupChannel>`) is unknown.
+- **Deprecated Flag**: `LocalOnly` is marked as deprecated but remains part of the interface—avoid using it in new code.
+- **String Length Limits**: `ChannelsString` and `ThresholdsString` are capped at 2048 characters; implementations must ensure serialization does not exceed this (e.g., by truncating or rejecting channels).
+- **No Validation on Axis Values**: While `Use*` flags control whether min/max values are applied, the interface does not enforce logical consistency (e.g., `DomainMin < DomainMax`).