noisedestroyers/DP44
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
noisedestroyers
2026-04-17 14:55:32 -04:00
commit bc3ac1d4c9
18017 changed files with 4371742 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
enriched-qwen3-coder-next/Common/DTS.Common/Interface/Groups.md Normal file
View File

@@ -0,0 +1,176 @@
---
source_files:
- Common/DTS.Common/Interface/Groups/IGroupImportImportView.cs
- Common/DTS.Common/Interface/Groups/IGroupHardwareDbRecord.cs
- Common/DTS.Common/Interface/Groups/IGroupImportOptionsView.cs
- Common/DTS.Common/Interface/Groups/IGroupImportPreviewView.cs
- Common/DTS.Common/Interface/Groups/ITestSetupGroupRecord.cs
- Common/DTS.Common/Interface/Groups/IGroupChannel.cs
- Common/DTS.Common/Interface/Groups/ITestObject.cs
- Common/DTS.Common/Interface/Groups/IGroupDbRecord.cs
- Common/DTS.Common/Interface/Groups/IGroupImportViewModel.cs
generated_at: "2026-04-16T03:01:03.373806+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "0340d2475dba7f20"
---
# Documentation: Group Import Module Interfaces
## 1. Purpose
This module defines interfaces for the group import functionality, which enables users to import test groups and their associated channels from external `.grp` files into the system. It provides a layered architecture separating concerns: view interfaces for UI presentation (`IGroupImportOptionsView`, `IGroupImportPreviewView`, `IGroupImportImportView`), a view model (`IGroupImportViewModel`) to orchestrate interaction between views and application logic, and data interfaces representing domain entities (`IGroupDbRecord`, `IGroupHardwareDbRecord`, `ITestSetupGroupRecord`, `IGroupChannel`, `ITestObject`). The module facilitates file selection, parsing, validation, preview, and committing of group data while integrating with the broader application for group creation, sensor validation, and database persistence.
## 2. Public Interface
### Interfaces (No concrete implementations provided in source)
#### `IGroupImportImportView : IBaseView`
- **Purpose**: Represents the view responsible for presenting progress feedback during group creation and commit operations.
- **No additional members beyond `IBaseView`**.
#### `IGroupHardwareDbRecord`
- **Purpose**: Describes a database record mapping hardware to a group.
- **Properties**:
- `int Id { get; set; }` – Primary key of the record.
- `int GroupId { get; set; }` – Foreign key referencing the group.
- `int DASId { get; set; }` – Identifier for the data acquisition system.
- `string SerialNumber { get; set; }` – Serial number of the hardware device.
- **Attributes**: `[Key]` on `Id`, `[Column("...")]` attributes map properties to DB columns.
#### `IGroupImportOptionsView : IBaseView`
- **Purpose**: Controls file selection and validates the selection.
- **Methods**:
- `bool Validate(out List<string> errors, out List<string> warnings)` – Validates selected files; returns `true` if valid, `false` otherwise. `errors` and `warnings` are populated with validation messages.
#### `IGroupImportPreviewView : IBaseView`
- **Purpose**: Parses channels from `.grp` files, displays results, and allows group selection/renaming.
- **Methods**:
- `bool Validate(bool userIsAdmin, out List<string> errors, out List<string> warnings)` – Validates selected groups (including channels and names). `errors` prevent proceeding; `warnings` are non-fatal. Returns `true` only if all selected groups are valid.
#### `ITestSetupGroupRecord`
- **Purpose**: Describes a test setup group record in the database.
- **Properties**:
- `int GroupId { get; set; }` – Database ID of the group.
- `int DisplayOrder { get; set; }` – Display order of the group.
- `string Position { get; set; }` – ISO 13499 position field (may be mixed per group).
- `string TestObjectType { get; set; }` – ISO 13499 test object field (may be mixed per group).
- `int TestSetupId { get; set; }` – ID of the parent test setup.
#### `IGroupChannel : IGroupTemplateChannel, IComparable<IGroupChannel>`
- **Purpose**: Represents a logical channel in a group (legacy pre-2.0 test object channels).
- **Properties**:
- `bool Disabled { get; set; }` – Controls whether the channel is used during data collection.
- `int ChannelIdx { get; set; }` – Channel index.
- `string SensorSerialNumber { get; set; }` – Serial number of associated sensor (if any).
- `string HardwareId { get; set; }` – Hardware channel identifier.
- **Note**: Inherits from `IGroupTemplateChannel` and `IComparable<IGroupChannel>`; comparison logic not specified in source.
#### `ITestObject`
- **Purpose**: Represents a test object (group) in the system.
- **Properties**:
- `string DisplaySerialNumber { get; }` – Read-only display serial number.
- `string SerialNumber { get; set; }` – Current serial number.
- `string SerialNumberConverted { get; set; }` – Converted serial number.
- `string SerialNumberOrOriginalSerialNumber { get; }` – Serial number or original if current is empty.
- `string TestObjectType { get; set; }` – Type of test object.
- `string ParentObject { get; set; }` – Parent object identifier.
- `bool SysBuilt { get; set; }` – Whether the object is system-built.
- `string TextL1 { get; set; }` – L1 text label.
- `string[] HardwareIds { get; set; }` – Array of associated hardware IDs.
- `string Template { get; set; }` – Current template.
- `bool LocalOnly { get; set; }` – Whether the object is local-only.
- `string LastModifiedBy { get; set; }` – Last modifier user.
- `DateTime LastModified { get; set; }` – Last modification timestamp.
- `bool Embedded { get; set; }` – Whether the object is embedded in a test setup.
- `string OriginalSerialNumber { get; set; }` – Original serial number.
- `string OriginalTemplate { get; set; }` – Original template (preserved when embedded).
- **Methods**:
- `void SortChannels()` – Sorts channels.
- `void SetTemplateOnly(string value)` – Sets only the template (behavior unspecified beyond signature).
#### `IGroupDbRecord`
- **Purpose**: Describes a group record in the database.
- **Properties**:
- `int Id { get; set; }` – Primary key.
- `string SerialNumber { get; set; }` – Group serial number.
- `string Picture { get; set; }` – Path or reference to group image.
- `string DisplayName { get; set; }` – Human-readable name.
- `string Description { get; set; }` – Group description.
- `bool Embedded { get; set; }` – Whether embedded in test setup.
- `DateTime LastModified { get; set; }` – Last modification timestamp.
- `string LastModifiedBy { get; set; }` – Last modifier user.
- `int? StaticGroupId { get; set; }` – Optional reference to static group ID.
- `string ExtraProperties { get; set; }` – Serialized extra properties.
- **Attributes**: `[Key]` on `Id`, `[Column("...")]` attributes for DB mapping.
#### `IGroupImportViewModel : IBaseViewModel`
- **Purpose**: Orchestrates group import flow; binds views and delegates to application services.
- **Properties**:
- `IGroupImportOptionsView ImportOptionsView { get; set; }`
- `IGroupImportPreviewView ImportPreviewView { get; set; }`
- `IGroupImportImportView ImportView { get; set; }`
- `FileUtils.LogDelegate Logger { get; set; }` – Logging delegate.
- `SwitchNavStepsDelegate SwitchNavSteps { get; set; }` – Navigation step switcher.
- `CheckGroupExistsDelegate CheckGroupExists { get; set; }` – Group existence checker.
- `CheckSensorExistsDelegate CheckSensorExists { get; set; }` – Sensor existence checker.
- `CreateGroupDelegate CreateGroup { get; set; }` – Group creation delegate.
- `AddChannelToGroupDelegate AddChannel { get; set; }` – Channel addition delegate.
- `CommitGroupsDelegate CommitGroups { get; set; }` – Group commit delegate.
- `Disable_UIDelegate DisableUI { get; set; }` – UI disable delegate.
- `Enable_UIDelegate EnableUI { get; set; }` – UI enable delegate.
- `bool BrowseOk { get; set; }` – Indicates whether file browsing succeeded.
- **Methods**:
- `void SetStatus(string message, Color color)` – Updates status display.
- `void ParseSourceFiles(string userTags)` – Parses `.grp` files; `userTags` likely metadata.
- `void Import()` – Commits parsed groups/channels to the application.
- `void Reset()` – Resets view model to initial state (reused across page visits).
### Delegates (defined in `IGroupImportViewModel.cs`)
- `SwitchNavStepsDelegate(GroupImportEnums.Steps step)` – Navigates to a new step in the import flow.
- `CheckGroupExistsDelegate(string name)` → `bool` – Checks if a group with given serial number exists.
- `CheckSensorExistsDelegate(string serialNumber)` → `bool` – Checks if a sensor with given serial number exists.
- `CreateGroupDelegate(string serialNumber, string tags)` – Creates a new group with serial number and tags.
- `AddChannelToGroupDelegate(string groupSerialNumber, string displayName, string sensorSerialNumber, double? capacity, bool? invert, string isoCode, IChannelSetting[] channelDefaults)` – Adds a channel to a group.
- `CommitGroupsDelegate(string[] serialNumbers)` – Commits specified groups to the database.
- `Disable_UIDelegate()` / `Enable_UIDelegate()` – UI state toggles.
## 3. Invariants
- **`IGroupImportImportView`** must be used *only* for progress display during group commit; no validation or selection logic is part of this interface.
- **`IGroupHardwareDbRecord`** requires `Id`, `GroupId`, `DASId`, and `SerialNumber` to be non-null/non-default for valid records (implied by `[Key]` and `[Column]` attributes).
- **`IGroupImportOptionsView.Validate`** and **`IGroupImportPreviewView.Validate`** must populate `errors`/`warnings` even on success (no nulls); `errors` must be empty for `Validate` to return `true`.
- **`IGroupImportPreviewView.Validate`** accepts a `userIsAdmin` flag, implying admin-specific validation rules (e.g., relaxed constraints), but behavior is not specified beyond signature.
- **`IGroupChannel.Disabled`** directly controls data collection participation; disabled channels must be excluded from test runs.
- **`ITestObject.Embedded`** and **`ITestObject.OriginalTemplate`** imply that embedded objects retain original template metadata; modification behavior is not specified.
- **`IGroupImportViewModel`** delegates must be assigned before calling `ParseSourceFiles`, `Import`, or `Reset`; otherwise, runtime failures are likely (source does not specify default behavior).
## 4. Dependencies
### This Module Depends On:
- **`DTS.Common.Base`** namespace (for `IBaseView`, `IBaseViewModel`).
- **`System.ComponentModel.DataAnnotations`** and **`System.ComponentModel.DataAnnotations.Schema`** (for `IGroupHardwareDbRecord`, `IGroupDbRecord`).
- **`DTS.Common.Interface.GroupTemplate`** (for `IGroupChannel` inheriting `IGroupTemplateChannel`).
- **`DTS.Common.Interface.Channels`** (for `AddChannelToGroupDelegate` parameter `IChannelSetting[]`).
- **`DTS.Common.Enums.Groups`** (for `SwitchNavStepsDelegate` parameter `GroupImportEnums.Steps`).
- **`DTS.Common.Utils`** (for `FileUtils.LogDelegate`).
- **`System.Windows.Media`** (for `Color` in `SetStatus`).
### This Module Is Used By:
- **UI layer**: Concrete implementations of `IGroupImportOptionsView`, `IGroupImportPreviewView`, `IGroupImportImportView` (e.g., WPF views).
- **Application logic**: `IGroupImportViewModel` implementations (e.g., view model classes) that wire up delegates to application services.
- **Data layer**: Implementations of `IGroupDbRecord`, `IGroupHardwareDbRecord`, `ITestSetupGroupRecord` (e.g., Entity Framework models).
- **Channel/test object logic**: `IGroupChannel`, `ITestObject` implementations used during import and runtime.
## 5. Gotchas
- **`IGroupChannel`** is explicitly marked for *legacy* (pre-2.0) test object channels; modern channels may use a different interface (not specified here).
- **`IGroupImportPreviewView.Validate`** uses `userIsAdmin` but does not define how admin status affects validation—implementation must infer behavior.
- **`ITestObject.SerialNumberOrOriginalSerialNumber`** is read-only; its implementation must handle fallback logic (e.g., return `OriginalSerialNumber` if `SerialNumber` is empty), but the source does not specify.
- **`IGroupImportViewModel.Reset()`** is required due to view model reuse across page visits; callers must ensure `Reset()` is called before reusing the instance.
- **Delegate assignments** (e.g., `CreateGroup`, `CommitGroups`) are not validated in the interface; null delegates will cause runtime exceptions.
- **`ExtraProperties`** in `IGroupDbRecord` is a serialized string; its format (e.g., JSON, XML) is not defined.
- **`HardwareIds`** in `ITestObject` is an array, but `IGroupChannel.HardwareId` is a single string—implications for one-to-many hardware mapping are not documented.
- **`ITestSetupGroupRecord.Position`** and **`TestObjectType`** may be mixed per group (per comments), but no validation or normalization is specified.
- **`IGroupImportOptionsView.Validate`** and **`IGroupImportPreviewView.Validate`** do not specify thread-safety; UI calls must occur on the UI thread (inferred from WPF usage via `Color`).
- **`SwitchNavStepsDelegate`** uses `GroupImportEnums.Steps`—enum values are not provided, so step ordering/validity is unknown.
None identified beyond the above.