init
This commit is contained in:
233
enriched-partialglm/Common/DTS.CommonCore/Interface/Groups.md
Normal file
233
enriched-partialglm/Common/DTS.CommonCore/Interface/Groups.md
Normal file
@@ -0,0 +1,233 @@
|
||||
---
|
||||
source_files:
|
||||
- Common/DTS.CommonCore/Interface/Groups/IGroupImportImportView.cs
|
||||
- Common/DTS.CommonCore/Interface/Groups/IGroupHardwareDbRecord.cs
|
||||
- Common/DTS.CommonCore/Interface/Groups/IGroupImportOptionsView.cs
|
||||
- Common/DTS.CommonCore/Interface/Groups/IGroupImportPreviewView.cs
|
||||
- Common/DTS.CommonCore/Interface/Groups/ITestSetupGroupRecord.cs
|
||||
- Common/DTS.CommonCore/Interface/Groups/IGroupChannel.cs
|
||||
- Common/DTS.CommonCore/Interface/Groups/ITestObject.cs
|
||||
- Common/DTS.CommonCore/Interface/Groups/IGroupDbRecord.cs
|
||||
- Common/DTS.CommonCore/Interface/Groups/IGroupImportViewModel.cs
|
||||
generated_at: "2026-04-16T12:14:34.783297+00:00"
|
||||
model: "zai-org/GLM-5-FP8"
|
||||
schema_version: 1
|
||||
sha256: "0073692ccbf88d7d"
|
||||
---
|
||||
|
||||
# Documentation: DTS.Common.Interface.Groups
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This module defines the core interfaces for the Groups subsystem within DTS, providing abstractions for group import workflows, database record structures, and channel/test object management. It serves as a contract layer between the group import UI views, view models, and the application core, enabling the parsing of `.GRP` files, validation of group configurations, and persistence of group and hardware records to the database. The module supports both legacy (pre-2.0) test object channels and ISO 13499-compliant metadata fields.
|
||||
|
||||
---
|
||||
|
||||
## 2. Public Interface
|
||||
|
||||
### Interfaces
|
||||
|
||||
#### `IGroupImportImportView`
|
||||
Marker interface for views responsible for presenting progress feedback during group creation and commit operations.
|
||||
- **Inherits:** `IBaseView`
|
||||
- **Members:** None (marker interface)
|
||||
|
||||
---
|
||||
|
||||
#### `IGroupHardwareDbRecord`
|
||||
Interface describing a GroupHardware record in the database.
|
||||
|
||||
| Property | Type | Attributes | Description |
|
||||
|----------|------|------------|-------------|
|
||||
| `Id` | `int` | `[Key]`, `[Column("Id")]` | Primary key of the GroupHardware record |
|
||||
| `GroupId` | `int` | `[Column("GroupId")]` | Foreign key to the associated group |
|
||||
| `DASId` | `int` | `[Column("DASId")]` | Data Acquisition System identifier |
|
||||
| `SerialNumber` | `string` | `[Column("SerialNumber")]` | Serial number of the hardware |
|
||||
|
||||
---
|
||||
|
||||
#### `IGroupImportOptionsView`
|
||||
Interface for views controlling file selection and validation.
|
||||
|
||||
- **Inherits:** `IBaseView`
|
||||
|
||||
| Method | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `Validate` | `bool Validate(out List<string> errors, out List<string> warnings)` | Returns `true` if files have been selected; populates `errors` and `warnings` collections with validation issues |
|
||||
|
||||
---
|
||||
|
||||
#### `IGroupImportPreviewView`
|
||||
Interface for views handling channel parsing from `.GRP` files, result display, and group selection/renaming.
|
||||
|
||||
- **Inherits:** `IBaseView`
|
||||
|
||||
| Method | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `Validate` | `bool Validate(bool userIsAdmin, out List<string> errors, out List<string> warnings)` | Validates currently selected groups including channels and group names. Returns `true` if all selected groups are valid. Errors are fatal; warnings are non-blocking. |
|
||||
|
||||
---
|
||||
|
||||
#### `ITestSetupGroupRecord`
|
||||
Interface describing a test setup group database record.
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `GroupId` | `int` | Database ID of the group |
|
||||
| `DisplayOrder` | `int` | Display order of the group |
|
||||
| `Position` | `string` | Position field (ISO 13499), if available; groups can have mixed position fields |
|
||||
| `TestObjectType` | `string` | Test Object field (ISO 13499), if available; groups can have mixed test object fields |
|
||||
| `TestSetupId` | `int` | Database ID of the test setup the group belongs to |
|
||||
|
||||
---
|
||||
|
||||
#### `IGroupChannel`
|
||||
Interface representing a logical channel in a group, associated with physical hardware and/or sensors.
|
||||
|
||||
- **Inherits:** `IGroupTemplateChannel`, `IComparable<IGroupChannel>`
|
||||
- **Note:** Marked as "FOR THE OLD (PRE 2.0) TESTOBJECT CHANNELS"
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `Disabled` | `bool` | Controls whether channel is used during data collection; disabled channels are excluded from run test |
|
||||
| `ChannelIdx` | `int` | Channel index |
|
||||
| `SensorSerialNumber` | `string` | Serial number of the associated sensor (if any) |
|
||||
| `HardwareId` | `string` | Hardware channel identifier associated with this channel |
|
||||
|
||||
---
|
||||
|
||||
#### `ITestObject`
|
||||
Interface representing a test object with channel management and metadata.
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `DisplaySerialNumber` | `string` | Read-only display-formatted serial number |
|
||||
| `SerialNumberConverted` | `string` | Converted serial number |
|
||||
| `SerialNumber` | `string` | Serial number |
|
||||
| `SerialNumberOrOriginalSerialNumber` | `string` | Read-only fallback to original serial number |
|
||||
| `TestObjectType` | `string` | Type of test object |
|
||||
| `ParentObject` | `string` | Parent object reference |
|
||||
| `SysBuilt` | `bool` | System-built flag |
|
||||
| `TextL1` | `string` | Text line 1 |
|
||||
| `HardwareIds` | `string[]` | Array of hardware IDs |
|
||||
| `Template` | `string` | Template name |
|
||||
| `LocalOnly` | `bool` | Local-only flag |
|
||||
| `LastModifiedBy` | `string` | User who last modified the object |
|
||||
| `LastModified` | `DateTime` | Timestamp of last modification |
|
||||
| `Embedded` | `bool` | Embedded flag |
|
||||
| `OriginalSerialNumber` | `string` | Original serial number before conversion |
|
||||
| `OriginalTemplate` | `string` | Original template (before embedding in test setup) |
|
||||
|
||||
| Method | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `SortChannels` | `void SortChannels()` | Sorts channels within the test object |
|
||||
| `SetTemplateOnly` | `void SetTemplateOnly(string value)` | Sets template without triggering additional side effects |
|
||||
|
||||
---
|
||||
|
||||
#### `IGroupDbRecord`
|
||||
Interface describing a Group record in the database.
|
||||
|
||||
| Property | Type | Attributes | Description |
|
||||
|----------|------|------------|-------------|
|
||||
| `Id` | `int` | `[Key]`, `[Column("Id")]` | Primary key |
|
||||
| `SerialNumber` | `string` | `[Column("SerialNumber")]` | Serial number of the group |
|
||||
| `Picture` | `string` | `[Column("Picture")]` | Picture path/identifier |
|
||||
| `DisplayName` | `string` | `[Column("DisplayName")]` | Display name |
|
||||
| `Description` | `string` | `[Column("Description")]` | Description text |
|
||||
| `Embedded` | `bool` | `[Column("Embedded")]` | Whether the group is embedded |
|
||||
| `LastModified` | `DateTime` | `[Column("LastModified")]` | Last modification timestamp |
|
||||
| `LastModifiedBy` | `string` | `[Column("LastModifiedBy")]` | User who last modified |
|
||||
| `StaticGroupId` | `int?` | `[Column("StaticGroupId")]` | Optional static group ID |
|
||||
| `ExtraProperties` | `string` | `[Column("ExtraProperties")]` | Extra properties (serialized) |
|
||||
|
||||
---
|
||||
|
||||
#### `IGroupImportViewModel`
|
||||
Interface for the group import view model, coordinating views, application logic, and intermediate data.
|
||||
|
||||
- **Inherits:** `IBaseViewModel`
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `ImportOptionsView` | `IGroupImportOptionsView` | View for file selection |
|
||||
| `ImportPreviewView` | `IGroupImportPreviewView` | View for group selection and channel viewing |
|
||||
| `ImportView` | `IGroupImportImportView` | View for commit progress display |
|
||||
| `Logger` | `FileUtils.LogDelegate` | Logging facility |
|
||||
| `SwitchNavSteps` | `SwitchNavStepsDelegate` | Callback to change navigation steps |
|
||||
| `CheckGroupExists` | `CheckGroupExistsDelegate` | Callback to check if a group exists |
|
||||
| `CheckSensorExists` | `CheckSensorExistsDelegate` | Callback to check if a sensor exists |
|
||||
| `CreateGroup` | `CreateGroupDelegate` | Callback to create a group |
|
||||
| `AddChannel` | `AddChannelToGroupDelegate` | Callback to add a channel to a group |
|
||||
| `CommitGroups` | `CommitGroupsDelegate` | Callback to commit groups to database |
|
||||
| `DisableUI` | `Disable_UIDelegate` | Callback to disable the UI |
|
||||
| `EnableUI` | `Enable_UIDelegate` | Callback to enable the UI |
|
||||
| `BrowseOk` | `bool` | Flag indicating browse operation status |
|
||||
|
||||
| Method | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `SetStatus` | `void SetStatus(string message, Color color)` | Sets status message with color |
|
||||
| `ParseSourceFiles` | `void ParseSourceFiles(string userTags)` | Reads source files and parses channels/groups |
|
||||
| `Import` | `void Import()` | Commits groups and channels to application |
|
||||
| `Reset` | `void Reset()` | Resets view model to initial values |
|
||||
|
||||
---
|
||||
|
||||
### Delegates
|
||||
|
||||
| Delegate | Signature | Description |
|
||||
|----------|-----------|-------------|
|
||||
| `SwitchNavStepsDelegate` | `void (GroupImportEnums.Steps step)` | Switches navigation to specified step |
|
||||
| `CheckGroupExistsDelegate` | `bool (string name)` | Checks if a group exists by serial number |
|
||||
| `CheckSensorExistsDelegate` | `bool (string serialNumber)` | Checks if a sensor exists by serial number |
|
||||
| `CreateGroupDelegate` | `void (string serialNumber, string tags)` | Creates a new group with tags |
|
||||
| `AddChannelToGroupDelegate` | `void (string groupSerialNumber, string displayName, string sensorSerialNumber, double? capacity, bool? invert, string isoCode, IChannelSetting[] channelDefaults)` | Adds a channel to the end of a group's existing channels; `capacity`/`invert` use sensor defaults when `null` |
|
||||
| `CommitGroupsDelegate` | `void (string[] serialNumbers)` | Commits specified groups to database |
|
||||
| `Disable_UIDelegate` | `void ()` | Disables the UI |
|
||||
| `Enable_UIDelegate` | `void ()` | Enables the UI |
|
||||
|
||||
---
|
||||
|
||||
## 3. Invariants
|
||||
|
||||
1. **Database Column Mapping:** All `IGroupDbRecord` and `IGroupHardwareDbRecord` properties are explicitly mapped to database columns via `[Column]` attributes; implementations must preserve these mappings.
|
||||
|
||||
2. **Primary Keys:** `Id` properties on `IGroupDbRecord` and `IGroupHardwareDbRecord` are marked with `[Key]` attribute and must be unique.
|
||||
|
||||
3. **Validation Pattern:** Both `IGroupImportOptionsView.Validate` and `IGroupImportPreviewView.Validate` follow the pattern of returning a boolean success indicator while populating `out` parameters for errors (fatal) and warnings (non-fatal).
|
||||
|
||||
4. **Channel Ordering:** `IGroupChannel` implements `IComparable<IGroupChannel>`, implying a defined sort order for channels.
|
||||
|
||||
5. **Channel Append Semantics:** Per `AddChannelToGroupDelegate` documentation, channels are appended to the end of a group's existing channels.
|
||||
|
||||
6. **Nullable Foreign Keys:** `StaticGroupId` on `IGroupDbRecord` is nullable (`int?`), indicating optional relationships.
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
### This module depends on:
|
||||
- **DTS.Common.Base** - `IBaseView`, `IBaseViewModel` base interfaces
|
||||
- **DTS.Common.Enums.Groups** - `GroupImportEnums.Steps` enumeration
|
||||
- **DTS.Common.Interface.Channels** - `IChannelSetting` interface
|
||||
- **DTS.Common.Interface.GroupTemplate** - `IGroupTemplateChannel` interface
|
||||
- **DTS.Common.Utils** - `FileUtils.LogDelegate` delegate type
|
||||
- **System.ComponentModel.DataAnnotations** - `[Key]`, `[Column]` attributes
|
||||
- **System.Windows.Media** - `Color` type for status display
|
||||
|
||||
### What depends on this module:
|
||||
- **Unclear from source alone** - No downstream consumers are visible in these interface definitions. The delegate patterns (`CreateGroupDelegate`, `CommitGroupsDelegate`, etc.) indicate that an application layer provides implementations, but specific consumers cannot be determined from these files.
|
||||
|
||||
---
|
||||
|
||||
## 5. Gotchas
|
||||
|
||||
1. **Legacy Channel Interface:** `IGroupChannel` is explicitly marked as "FOR THE OLD (PRE 2.0) TESTOBJECT CHANNELS" in the source comments. New implementations should investigate whether a newer channel interface exists.
|
||||
|
||||
2. **ViewModel Reuse Pattern:** The `Reset()` method documentation states: *"we are currently not creating a new viewmodel in the page, but re-using an existing one so everytime we re-visit the page we must re-initialize the vm"*. This singleton-like reuse pattern requires explicit cleanup via `Reset()` to avoid stale state.
|
||||
|
||||
3. **Mixed ISO 13499 Fields:** `ITestSetupGroupRecord.Position` and `TestObjectType` comments note that groups can be composed of mixed position and test object fields, which may complicate validation or display logic.
|
||||
|
||||
4. **Template Mutation on Embedding:** `ITestObject.OriginalTemplate` documentation indicates that the template changes when embedded in a test setup, suggesting template mutation side effects that may not be obvious.
|
||||
|
||||
5. **Null Parameter Semantics:** In `AddChannelToGroupDelegate`, `capacity` and `invert` parameters use `null` to signal "use sensor defaults" rather than "no value" — implementations must explicitly handle this convention.
|
||||
Reference in New Issue
Block a user