将Feature/XP.Common和Feature/XP.Hardware分支合并至Develop/XP.forHardwareAndCommon，完善XPapp注册和相关硬件类库通用类库功能。

2026-04-16 17:31:13 +08:00
parent 6ec4c3ddaa
commit 2bd6e566c3
581 changed files with 74600 additions and 222 deletions
@@ -0,0 +1,310 @@
+# XP.Hardware.RaySource 项目结构文档
+
+## 1. 项目概览
+
+| 项目 | 框架 | 类型 | 命名空间 | 程序集名称 |
+|------|------|------|----------|-----------|
+| XP.Hardware.RaySource | .NET 8.0 (net8.0-windows7.0) | WPF 类库 | `XP.Hardware.RaySource.*` | XP.Hardware.RaySource |
+| XP.Hardware.RaySource.Comet.Host | .NET Framework 4.8 | WinForms 控制台 | `XP.Hardware.RaySource.Comet.Host` | XP.Hardware.RaySource.Comet.Host |
+| XP.Hardware.RaySource.Comet.Messages | netstandard2.0 | 类库 | `XP.Hardware.RaySource.Comet.Messages` | XP.Hardware.RaySource.Comet.Messages |
+
+## 2. 版本信息
+
+### XP.Hardware.RaySource
+
+- 目标框架：`net8.0-windows7.0`
+- SDK 风格项目
+- NuGet 依赖：
+  - `Prism.Wpf` 9.0.537
+  - `System.Configuration.ConfigurationManager` 8.0.0
+  - `Telerik.UI.for.Wpf.NetCore.Xaml` 2024.1.408
+- 项目引用：
+  - `XP.Common`（日志、数据库、多语言基础设施）
+  - `XP.Hardware.RaySource.Comet.Messages`（IPC 消息定义）
+
+### XP.Hardware.RaySource.Comet.Host
+
+- 目标框架：`.NET Framework 4.8`
+- WinForms 进程（因依赖 B&R PVI Services COM 组件，无法迁移到 .NET 8）
+- 外部依赖：
+  - `BR.AN.PviServices.dll`（Version 1.1.0.0，贝加莱 PVI 通讯库）
+  - `Newtonsoft.Json`（JSON 序列化）
+- 项目引用：
+  - `XP.Hardware.RaySource.Comet.Messages`（IPC 消息定义）
+
+### XP.Hardware.RaySource.Comet.Messages
+
+- 目标框架：`netstandard2.0`（跨框架共享）
+- 定义 IPC 命令和响应消息类型
+- 被 RaySource（.NET 8）和 Comet.Host（.NET Framework 4.8）共同引用
+
+## 3. 引用关系
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│           XP.Hardware.RaySource (.NET 8.0 WPF 类库)         │
+│                                                             │
+│  ProjectReference ──► XP.Common                             │
+│  ProjectReference ──► XP.Hardware.RaySource.Comet.Messages  │
+│                                                             │
+│  NuGet: Prism.Wpf, Telerik, ConfigurationManager            │
+└────────────────────┬────────────────────────────────────────┘
+                     │ Named Pipe IPC（进程间通信）
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│   XP.Hardware.RaySource.Comet.Host (.NET Framework 4.8)     │
+│                                                             │
+│  ProjectReference ──► XP.Hardware.RaySource.Comet.Messages  │
+│  外部引用 ──► BR.AN.PviServices.dll（贝加莱 PVI 通讯库）    │
+│  NuGet: Newtonsoft.Json                                     │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│   XP.Hardware.RaySource.Comet.Messages (netstandard2.0)     │
+│                                                             │
+│  共享消息库，定义 IPC 命令和响应类型                          │
+│  被 RaySource 和 Comet.Host 共同引用                         │
+│  NuGet: Newtonsoft.Json                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 进程隔离架构说明
+
+RaySource（.NET 8）通过 Named Pipe 与 Comet.Host（.NET Framework 4.8）进行进程间通信。之所以采用这种架构，是因为 `BR.AN.PviServices.dll`（贝加莱 PVI 通讯库）仅支持 .NET Framework，无法直接在 .NET 8 中使用。因此将 PVI 通讯层隔离到独立的 .NET Framework 4.8 Host 子进程中，通过 Named Pipe 双管道模式实现跨框架通信。
+
+`Comet.Messages` 作为 `netstandard2.0` 共享库，定义了两端通信的命令和响应消息格式，确保序列化/反序列化的一致性。
+
+## 4. XP.Hardware.RaySource 项目结构
+
+```
+XP.Hardware.RaySource/
+├── Abstractions/                          # 抽象层（接口、基类、枚举、事件）
+│   ├── Enums/
+│   │   └── RaySourceStatus.cs             # 射线源状态枚举（Unavailable=-1 / Closed=0 / Opened=1）
+│   ├── Events/
+│   │   ├── ErrorOccurredEvent.cs          # 错误触发事件（PubSubEvent<string>）
+│   │   ├── OperationResultEvent.cs        # 操作结果事件（PubSubEvent<OperationResultData>）
+│   │   ├── RaySourceStatusChangedEvent.cs # 射线源状态变更事件（PubSubEvent<RaySourceStatus>）
+│   │   ├── StatusUpdatedEvent.cs          # 系统状态更新事件（PubSubEvent<SystemStatusData>）
+│   │   └── VariablesConnectedEvent.cs     # PVI 变量连接状态事件（PubSubEvent<bool>）
+│   ├── IRaySourceFactory.cs               # 射线源工厂接口
+│   ├── IXRaySource.cs                     # 射线源策略接口（核心接口，同步方法）
+│   ├── XRayResult.cs                      # 操作结果封装类（Ok/Error 静态工厂方法）
+│   └── XRaySourceBase.cs                  # 射线源抽象基类（含 Dispose 模式）
+├── Config/
+│   ├── ConfigLoader.cs                    # 配置加载器（支持加载和保存到 App.config）
+│   └── RaySourceConfig.cs                 # 射线源配置实体类（含验证方法）
+├── Converters/
+│   ├── RaySourceOperateConverter.cs       # WPF 值转换器（状态→径向渐变色/边框色/启用状态）
+│   └── FilamentLifetimeColorConverter.cs  # 灯丝寿命百分比→颜色（绿/黄/红）
+├── Factories/
+│   └── RaySourceFactory.cs                # 射线源工厂实现（创建 CometHostManager + CometIpcClient + Comet225RaySource）
+├── Implementations/
+│   ├── Comet225RaySource.cs               # Comet 225kV 射线源适配器（委托 IPC 客户端和 Host 管理器）
+│   ├── CometHostManager.cs                # Host 进程生命周期管理器（启动/监控/关闭子进程）
+│   └── CometIpcClient.cs                  # Named Pipe IPC 客户端（双管道通信，消息收发）
+├── Module/
+│   └── RaySourceModule.cs                 # Prism 模块入口（DI 注册 + 灯丝寿命初始化 + 预警检查）
+├── Services/
+│   ├── IRaySourceService.cs               # 射线源业务服务接口（含 InitializeAndConnectAsync）
+│   ├── RaySourceService.cs                # 射线源业务服务实现（单例，业务规则校验 + 灯丝寿命联动）
+│   ├── IFilamentLifetimeService.cs        # 灯丝寿命管理服务接口
+│   └── FilamentLifetimeService.cs         # 灯丝寿命管理服务实现（SQLite 持久化）
+├── ViewModels/
+│   ├── RaySourceConfigViewModel.cs        # 配置视图模型（初始化/连接/断开/设备状态监控/灯丝寿命进度条）
+│   └── RaySourceOperateViewModel.cs       # 操作视图模型（开关/电压电流调节/自动初始化）
+├── Views/
+│   ├── RaySourceConfigView.xaml(.cs)      # 配置视图（设备状态面板 + 功能按钮 + 灯丝寿命进度条）
+│   ├── RaySourceConfigWindow.xaml(.cs)    # 配置窗口（包裹 ConfigView 的独立窗口）
+│   └── RaySourceOperateView.xaml(.cs)     # 操作视图（腰圆状态指示器 + 开关按钮 + 电压电流滑块）
+└── Documents/                             # 文档目录
+```
+
+
+## 5. 调用链路详解
+
+### 5.1 整体架构（适配器模式 + IPC 进程隔离 + 事件驱动）
+
+```
+┌──────────────┐    ┌──────────────────┐    ┌───────────────────┐    ┌────────────────┐    ┌──────────────┐
+│  ViewModel   │───►│ RaySourceService │───►│ Comet225RaySource │───►│ CometIpcClient │───►│  Host 进程   │
+│  (UI 层)     │    │  (业务服务层)     │    │  (适配器层)        │    │ (IPC 通信层)    │    │ (PVI 通讯层)  │
+└──────────────┘    └──────────────────┘    └───────────────────┘    └────────────────┘    └──────────────┘
+       ▲                    ▲                                               │                      │
+       │                    │                                               │                      │
+       └────────── Prism EventAggregator ◄──────────────────────────────────┘◄─── Named Pipe ──────┘
+                                                                    （推送消息路由为 Prism 事件）
+```
+
+### 5.2 调用流程
+
+#### 初始化流程
+
+```
+1. RaySourceModule.RegisterTypes()
+   → 注册 RaySourceConfig（从 App.config 加载）
+   → 注册 IRaySourceFactory → RaySourceFactory（单例）
+   → 注册 IRaySourceService → RaySourceService（单例）
+   → 注册 IFilamentLifetimeService → FilamentLifetimeService（单例）
+
+2. RaySourceModule.OnInitialized()
+   → FilamentLifetimeService.Initialize()（建表、异常恢复、重算累计寿命）
+   → 检查灯丝寿命预警（≥90% 弹出对话框）
+
+3. ViewModel 调用 IRaySourceService.Initialize()
+   → RaySourceService.Initialize()
+     → 验证配置参数
+     → IRaySourceFactory.CreateRaySource("Comet225")
+       → new CometHostManager(logger, config)
+       → new CometIpcClient(config, eventAggregator, logger)
+       → new Comet225RaySource(hostManager, ipcClient, logger)
+     → Comet225RaySource.Initialize()
+       → CometHostManager.EnsureRunning()     // 启动 Host 子进程
+         → 清理残留进程 → 启动新进程 → 等待 Named Pipe 就绪
+       → CometIpcClient.Initialize()
+         → Connect()                           // 连接双管道
+         → SendCommand(InitializeCommand)      // 发送初始化命令
+         → Host 端执行 PVI Service/CPU 连接
+         → 等待 ServiceConnected 推送确认
+```
+
+#### 变量连接流程
+
+```
+4. ViewModel 调用 IRaySourceService.ConnectVariables()
+   → RaySourceService.ConnectVariables()
+     → Comet225RaySource.ConnectVariables()
+       → CometIpcClient.ConnectVariables()
+         → SendCommand(ConnectVariablesCommand)
+         → Host 端执行：CreateVariables → ActivateVariables → BindEventHandlers
+         → Host 推送 VariablesConnected → RaySourceConnected
+         → CometIpcClient 路由推送为 Prism 事件
+           → VariablesConnectedEvent(true)
+           → RaySourceStatusChangedEvent(Closed)
+```
+
+#### 操作流程（以开启射线为例）
+
+```
+5. ViewModel.ExecuteTurnOn()
+   → RaySourceService.TurnOn()              // 业务规则校验（状态检查、防重复、双重检查锁定）
+     → Comet225RaySource.TurnOn()           // 适配器层
+       → CometIpcClient.TurnOn()            // IPC 通信层
+         → SendCommand(TurnOnCommand)        // 序列化为 JSON，写入命令管道
+         → Host 端执行 PVI 变量写入
+         → Host 返回响应 → CometIpcClient 接收
+     → 更新状态为 Opened
+     → 发布 RaySourceStatusChangedEvent
+     → FilamentLifetimeService.StartFilamentUsage()  // 记录灯丝使用开始
+```
+
+#### 状态反馈流程（事件驱动）
+
+```
+6. Host 端 PVI 变量值变化
+   → Host 构造推送消息（StatusChanged / XRayStateChanged / ErrorOccurred 等）
+   → 写入响应管道
+   → CometIpcClient.ReceiveLoop() 接收
+     → 识别为推送消息（IsPush=true）
+     → HandlePushMessage() 路由到对应 Prism 事件
+       → StatusUpdatedEvent（全量状态数据）
+       → RaySourceStatusChangedEvent（三态变更）
+       → ErrorOccurredEvent（错误信息）
+       → VariablesConnectedEvent（连接状态）
+     → ViewModel 通过事件订阅更新 UI
+```
+
+### 5.3 IPC 通信机制
+
+#### Named Pipe 双管道模式
+
+| 管道名称 | 方向 | 用途 |
+|----------|------|------|
+| `XP.Hardware.RaySource.Comet.Cmd` | 客户端 → Host | 命令管道（写入命令 JSON） |
+| `XP.Hardware.RaySource.Comet.Rsp` | Host → 客户端 | 响应管道（接收响应和推送） |
+
+#### 消息类型
+
+- **命令消息**：客户端发送，Host 处理后返回响应（请求-响应模式）
+- **推送消息**：Host 主动推送状态变化（`IsPush=true`），包括：
+  - `StatusChanged`：全量状态数据（电压/电流/各子系统状态）
+  - `XRayStateChanged`：射线开关状态变化
+  - `ErrorOccurred`：错误信息
+  - `ConnectionStateChanged`：连接状态变化（ServiceConnected / VariablesConnected / RaySourceConnected / Disconnected）
+  - `Log`：Host 端日志转发（按级别映射到主进程 ILoggerService）
+
+#### 超时机制
+
+- 命令超时：35000ms（大于 Host 端 PVI 连接超时 30s）
+- 管道连接超时：使用 `RaySourceConfig.ConnectionTimeout`（默认 5000ms）
+- Host 进程关闭超时：5000ms（超时则强制终止）
+
+### 5.4 日志桥接机制
+
+Host 进程（.NET Framework 4.8）通过 Named Pipe 推送日志消息到主进程。`CometIpcClient` 接收 `LogResponse` 推送后，根据 `Level` 字段映射到 `ILoggerService` 对应方法：
+
+```
+Host 端日志 → LogResponse（JSON）→ Named Pipe → CometIpcClient.HandleLogPush()
+  → Level="Debug" → _logger.Debug(message, args)
+  → Level="Info"  → _logger.Info(message, args)
+  → Level="Warn"  → _logger.Warn(message, args)
+  → Level="Error" → _logger.Error(null, message, args)
+  → Level="Fatal" → _logger.Fatal(null, message, args)
+```
+
+## 6. 灯丝寿命管理架构
+
+### 6.1 数据库表结构
+
+#### RaySourceFilamentLifetimeStatistics（累计统计表）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| Id | INTEGER PK | 自增主键 |
+| SourceType | TEXT | 射线源类型 |
+| SerialNumber | TEXT | 序列号（唯一索引） |
+| TotalLifeSeconds | REAL | 累计使用秒数 |
+| LastUpdateTime | TEXT | 最后更新时间（ISO 8601） |
+
+#### RaySourceFilamentUsageLogs（使用流水表）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| Id | INTEGER PK | 自增主键 |
+| SourceType | TEXT | 射线源类型 |
+| SerialNumber | TEXT | 序列号 |
+| StartTime | TEXT | 开始时间（ISO 8601） |
+| EndTime | TEXT | 结束时间（可为 NULL） |
+| DurationSeconds | REAL | 持续秒数 |
+| Status | INTEGER | 0=正常，1=异常中断 |
+
+### 6.2 灯丝寿命联动
+
+- 射线源开启（TurnOn）→ `StartFilamentUsage()`：插入流水记录
+- 射线源关闭（TurnOff）→ `StopFilamentUsage()`：事务更新流水记录 + 累加统计表
+- 断开连接 / 紧急关闭 → `StopFilamentUsage()`：同上
+- 异常断联 → 下次初始化时 `RecoverUnclosedRecords()`：将未关闭记录标记为异常中断
+
+### 6.3 预警机制
+
+- 模块初始化时检查灯丝寿命百分比
+- 百分比 ≥ 90% 时弹出模态预警对话框
+- ConfigView 中显示灯丝寿命进度条（60 秒定时刷新）
+- 进度条颜色：< 80% 绿色，80%-89% 黄色，≥ 90% 红色
+
+## 7. 设计模式总结
+
+| 模式 | 应用位置 | 说明 |
+|------|---------|------|
+| 策略模式 | `IXRaySource` → `Comet225RaySource` | 支持多种射线源实现的可扩展架构 |
+| 工厂模式 | `IRaySourceFactory` → `RaySourceFactory` | 根据配置类型创建对应射线源实例 |
+| 适配器模式 | `Comet225RaySource` | 将 IPC 通信适配为 IXRaySource 接口 |
+| 进程隔离 | `CometHostManager` + `CometIpcClient` | 通过 Named Pipe 实现 .NET 8 与 .NET Framework 4.8 跨框架通信 |
+| 事件驱动 | Prism EventAggregator + IPC 推送 | 解耦 PVI 通讯层与 UI 层的状态同步 |
+| 依赖注入 | Prism DI 容器 | 通过 RaySourceModule 注册所有服务 |
+| 单例模式 | RaySourceService、RaySourceFactory、FilamentLifetimeService | 全局唯一的服务和工厂实例 |
+| 双重检查锁定 | RaySourceService.TurnOn/TurnOff | 防止并发重复操作 |
+
+---
+
+**最后更新 | Last Updated**: 2026-03-26