init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Classes/Groups/ChannelSettings.md

@@ -0,0 +1,122 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Classes/Groups/ChannelSettings/ChannelSettingRecord.cs
+  - Common/DTS.CommonCore/Classes/Groups/ChannelSettings/GroupChannelSettingRecord.cs
+  - Common/DTS.CommonCore/Classes/Groups/ChannelSettings/ChannelSettingBase.cs
+generated_at: "2026-04-16T02:42:22.673078+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "f67a48400fa70da5"
+---
+
+# ChannelSettings
+
+## Documentation: Channel Settings Module
+
+### 1. Purpose  
+This module defines core data structures for modeling channel configuration settings in the DTS system. It provides three key classes: `ChannelSettingRecord` (a metadata record describing a *type* of setting), `GroupChannelSettingRecord` (an *instance* of a setting applied to a specific channel), and `ChannelSettingBase` (a concrete implementation of `IChannelSetting` that supports typed value accessors and constant-based setting name definitions). Together, they enable storage, retrieval, and manipulation of channel-specific configuration values, with support for multiple channel types (analog, digital, squib, UART, etc.) and versioned database interactions.
+
+---
+
+### 2. Public Interface  
+
+#### `ChannelSettingRecord`
+- **`ChannelSettingRecord()`**  
+  Default constructor; initializes an empty record.
+- **`ChannelSettingRecord(IDataReader reader)`**  
+  Populates the record from an `IDataReader` by reading columns `"Id"`, `"SettingName"`, and `"DefaultValue"` using `Utility.GetInt` and `Utility.GetString`.  
+- **`int Id`**  
+  Gets/sets the unique identifier for this setting definition.
+- **`string SettingName`**  
+  Gets/sets the canonical name of the setting (e.g., `"Range"`, `"SquibCurrent"`).
+- **`string DefaultValue`**  
+  Gets/sets the default value string for this setting.
+
+#### `GroupChannelSettingRecord`
+- **`GroupChannelSettingRecord()`**  
+  Default constructor; initializes an empty record.
+- **`GroupChannelSettingRecord(IDataReader reader, int storedProcedureVersionUsed)`**  
+  Populates the record from an `IDataReader`. Behavior depends on `storedProcedureVersionUsed`:  
+  - If `>= Constants.BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`, reads `"ChannelId"` via `Utility.GetLong`; otherwise sets `ChannelId = 0`.  
+  - Always reads `"SettingId"` (via `Utility.GetInt`) and `"SettingValue"` (via `Utility.GetString`).  
+- **`GroupChannelSettingRecord(long channelId, int settingId, string settingValue)`**  
+  Constructor for programmatic creation; directly assigns `ChannelId`, `SettingId`, and `SettingValue`.
+- **`long ChannelId`**  
+  Gets/sets the channel identifier the setting applies to.
+- **`int SettingId`**  
+  Gets/sets the foreign key referencing `ChannelSettingRecord.Id`.
+- **`string SettingValue`**  
+  Gets/sets the actual value string for this channel’s setting instance.
+
+#### `ChannelSettingBase`
+- **`ChannelSettingBase(int settingType, string name, string defaultValue)`**  
+  Constructor initializing `SettingTypeId`, `SettingName`, and `DefaultValue`.
+- **`IChannelSetting Clone()`**  
+  Returns a new `ChannelSettingBase` instance with all properties copied from the current instance.
+- **`long ChannelId { get; set; }`**  
+  Channel ID the setting applies to.
+- **`int SettingTypeId { get; protected set; }`**  
+  Type identifier for the setting (e.g., analog, digital).
+- **`string SettingName { get; protected set; }`**  
+  Name of the setting (e.g., `"Range"`).
+- **`string DefaultValue { get; protected set; }`**  
+  Default value string for this setting.
+- **`string Value { get; set; }`**  
+  Current value string for this setting instance.
+- **`double DoubleValue { get; set; }`**  
+  Gets/sets `Value` as a `double`. Falls back to `DoubleDefaultValue` on parse failure.
+- **`double DoubleDefaultValue { get; }`**  
+  Parses `DefaultValue` as a `double` using `CultureInfo.InvariantCulture`.
+- **`int IntValue { get; set; }`**  
+  Gets/sets `Value` as an `int`. Falls back to `IntDefaultValue` on parse failure.
+- **`int IntDefaultValue { get; }`**  
+  Parses `DefaultValue` as an `int` using `CultureInfo.InvariantCulture`.
+- **`bool BoolValue { get; set; }`**  
+  Gets/sets `Value` as a `bool`. Falls back to `BoolDefaultValue` on parse failure.
+- **`bool BoolDefaultValue { get; }`**  
+  Parses `DefaultValue` as a `bool` (uses default `bool.Parse` behavior).
+
+#### Constants (public static fields in `ChannelSettingBase`)
+- **Analog**: `RANGE`, `CFC`, `FilterClass`, `POLARITY`, `POSITION`, `ZEROMETHOD`, `ZEROMETHODSTART`, `ZEROMETHODEND`, `USERVALUE1`, `USERVALUE2`, `USERVALUE3`, `INITIAL_OFFSET`, `ACCouplingEnabled`
+- **Deprecated**: `LIMIT_DURATION`, `DURATION`, `DELAY` (commented out)
+- **Bridge/Insertion**: `BRIDGE_TYPE`
+- **Squib**: `SQUIB_CURRENT`, `SQUIB_LIMIT_DURATION`, `SQUIB_DURATION`, `SQUIB_DELAY`, `SQMODE`
+- **Digital Out**: `DIGITALOUT_LIMIT_DURATION`, `DIGITALOUT_DURATION`, `DIGITALOUT_DELAY`, `OUTPUT_MODE`
+- **Digital In**: `DIMODE`, `DEFAULT_VALUE`, `ACTIVE_VALUE`
+- **UART**: `BAUD_RATE`, `DATA_BITS`, `STOP_BITS`, `PARITY`, `FLOW_CONTROL`, `DATA_FORMAT`
+- **Stream Out**: `UDP_PROFILE`, `UDP_ADDRESS`, `UDP_TIME_CHID`, `UDP_DATA_CHID`, `UDP_TMNS_CONFIG`, `IRIG_TDP_INTERVAL_MS`, `TMATS_INTERVAL_MS`
+- **Stream In**: `UDP_ADDRESS_IN`
+
+---
+
+### 3. Invariants  
+- **`ChannelSettingRecord.Id`** must be non-negative (implied by `int` type and database usage).
+- **`GroupChannelSettingRecord.SettingId`** must correspond to a valid `ChannelSettingRecord.Id` in the database (enforced by foreign key at persistence layer, not here).
+- **`GroupChannelSettingRecord.ChannelId`** may be `0` *only* when constructed from `IDataReader` with `storedProcedureVersionUsed < Constants.BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`. Otherwise, it must be positive.
+- **`ChannelSettingBase.Value`** is stored as a string; numeric/boolean accessors (`DoubleValue`, `IntValue`, `BoolValue`) parse it at runtime and fall back to defaults on failure.
+- **`ChannelSettingBase.DefaultValue`** must be parseable as the corresponding type (`double`, `int`, `bool`) for `DoubleDefaultValue`, `IntDefaultValue`, and `BoolDefaultValue` to succeed; otherwise, runtime exceptions may occur during parsing.
+
+---
+
+### 4. Dependencies  
+- **Internal Dependencies**:
+  - `DTS.Common.Interface.Channels` (interfaces `IChannelSettingRecord`, `IGroupChannelSettingRecord`, `IChannelSetting`)
+  - `DTS.Common.Base.BasePropertyChanged` (base class for `ChannelSettingRecord`)
+  - `DTS.Common.Base.BasePropertyChanged` (base class for `GroupChannelSettingRecord`)
+  - `DTS.Common.Interface.Channels` (interface `IChannelSetting`)
+  - `System.Data` (`IDataReader`)
+  - `Utility` class (static methods: `GetInt`, `GetString`, `GetLong`)
+  - `Constants` class (reference to `BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`)
+- **External Dependencies**:
+  - `System` (core types, `CultureInfo`, `NumberStyles`)
+  - `DTS.Common.Interface.Channels` (consumed by other modules for channel configuration management)
+
+---
+
+### 5. Gotchas  
+- **`GroupChannelSettingRecord` constructor with `IDataReader` silently sets `ChannelId = 0`** when `storedProcedureVersionUsed < Constants.BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`. This may mask missing data if the stored procedure version is misconfigured.
+- **`ChannelSettingBase` parsing methods (`DoubleValue`, `IntValue`, `BoolValue`) do not distinguish between parse failure and a valid default value**—e.g., if `Value = "0"` and `DefaultValue = "1"`, `IntValue` returns `0`, not `1`. The fallback only occurs on *parse failure* (e.g., `Value = "abc"`).
+- **`BoolDefaultValue` uses `bool.Parse(DefaultValue)` without `CultureInfo.InvariantCulture`**, unlike numeric defaults. This may cause culture-dependent failures if `DefaultValue` is not `"True"`/`"False"` (case-sensitive).
+- **`ChannelSettingBase` is mutable** (`Value`, `ChannelId`, etc., have public setters). Cloning via `Clone()` is shallow but may be insufficient if consumers modify nested objects (none present here, but worth noting).
+- **`ChannelSettingBase` has no validation on `SettingName` or `DefaultValue`**—invalid names or unparseable defaults may only surface at runtime during type conversion.
+- **`ChannelSettingBase` constants are string literals**; typos in usage (e.g., `"Rang"` instead of `"Range"`) will compile but cause runtime mismatches with database or UI expectations.