# 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