将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,413 @@
+# XP.Hardware.RaySource
+
+工业 X 射线源控制模块 | Industrial X-Ray Source Control Module
+
+---
+
+## 项目概述 | Project Overview
+
+XP.Hardware.RaySource 是 XplorePlane X 射线检测系统的核心硬件控制模块，负责与工业 X 射线源设备进行通讯和控制。该模块采用策略模式和工厂模式设计，支持多种 X 射线源型号的统一管理，提供完整的设备生命周期控制和安全机制。
+
+### 主要特性 | Key Features
+
+- 支持多种 X 射线源型号（当前支持 Comet 225kV）
+- 基于 Named Pipe IPC 的进程隔离架构（.NET 8 主进程 ↔ .NET Framework 4.8 Host 进程）
+- 完整的设备生命周期管理（初始化、连接变量、暖机、训机、灯丝校准、自动定心、开关射线）
+- 精确的电压电流控制（20-225kV / 10-1000μA）
+- 实时状态监控和错误检测
+- 基于 Prism 事件聚合器的松耦合跨模块通讯
+- 安全机制：紧急关闭优先级、参数范围验证
+- 灯丝寿命管理：使用时长记录、累计统计、预警提醒
+- TXI 开关控制、功率模式切换（Micro Focus / High Power）
+- 完整的日志记录和异常处理
+
+---
+
+## 框架架构 | Architecture
+
+```
+XP.Hardware.RaySource/
+├── Abstractions/              # 抽象层 | Abstraction Layer
+│   ├── IXRaySource.cs        # 策略接口（同步方法）
+│   ├── XRaySourceBase.cs     # 抽象基类
+│   ├── XRayResult.cs         # 结果封装类
+│   ├── IRaySourceFactory.cs  # 工厂接口
+│   ├── Enums/                # 枚举定义
+│   │   └── RaySourceStatus.cs  # 三态枚举（Unavailable/Closed/Opened）
+│   └── Events/               # Prism 事件定义
+│       ├── StatusUpdatedEvent.cs           # 系统状态更新事件
+│       ├── ErrorOccurredEvent.cs           # 错误触发事件
+│       ├── OperationResultEvent.cs         # 操作结果事件
+│       ├── RaySourceStatusChangedEvent.cs  # 射线源状态变更事件
+│       └── VariablesConnectedEvent.cs      # PVI 变量连接状态事件
+├── Implementations/           # 实现层 | Implementation Layer
+│   ├── Comet225RaySource.cs  # Comet 225kV 适配器（委托 IPC 客户端）
+│   ├── CometHostManager.cs   # Host 进程生命周期管理器
+│   └── CometIpcClient.cs     # Named Pipe IPC 客户端
+├── Factories/                 # 工厂层 | Factory Layer
+│   └── RaySourceFactory.cs   # 射线源工厂
+├── Services/                  # 业务服务层 | Service Layer
+│   ├── IRaySourceService.cs  # 服务接口
+│   ├── RaySourceService.cs   # 服务实现（单例）
+│   ├── IFilamentLifetimeService.cs  # 灯丝寿命服务接口
+│   └── FilamentLifetimeService.cs   # 灯丝寿命服务实现
+├── Config/                    # 配置层 | Configuration Layer
+│   ├── RaySourceConfig.cs    # 配置实体
+│   └── ConfigLoader.cs       # 配置加载器（支持保存）
+├── Module/                    # Prism 模块 | Prism Module
+│   └── RaySourceModule.cs    # 模块注册
+├── ViewModels/                # 视图模型 | View Models
+│   ├── RaySourceConfigViewModel.cs    # 配置视图模型（初始化/连接/断开/设备状态监控/灯丝寿命）
+│   └── RaySourceOperateViewModel.cs   # 操作视图模型（开关/电压电流调节）
+├── Views/                     # WPF 视图 | WPF Views
+│   ├── RaySourceConfigView.xaml       # 配置视图（设备状态面板）
+│   ├── RaySourceConfigWindow.xaml     # 配置窗口（包裹 ConfigView）
+│   └── RaySourceOperateView.xaml      # 操作视图（开关/滑块）
+├── Converters/                # WPF 值转换器 | WPF Value Converters
+│   ├── RaySourceOperateConverter.cs       # 状态→颜色/边框色/启用状态
+│   └── FilamentLifetimeColorConverter.cs  # 灯丝寿命百分比→颜色
+└── Documents/                 # 文档 | Documentation
+    ├── README.md                          # 项目说明（本文档）
+    ├── ProjectStructure.md                # 项目结构详解
+    ├── GUIDENCE.md                        # 使用指南
+    ├── README_RaySourceOperateView.md     # 操作视图说明
+    └── App.config.example                 # 配置文件示例
+```
+
+
+### 设计模式 | Design Patterns
+
+- **策略模式**：`IXRaySource` 接口定义统一操作，支持多种设备实现
+- **工厂模式**：`IRaySourceFactory` 根据设备类型动态创建实例
+- **适配器模式**：`Comet225RaySource` 将 IPC 通信适配为 `IXRaySource` 接口
+- **进程隔离**：通过 `CometHostManager` + `CometIpcClient` 实现 .NET 8 与 .NET Framework 4.8 的跨框架通信
+- **模板方法模式**：`XRaySourceBase` 提供基础实现框架
+- **单例模式**：`IRaySourceService`、`IFilamentLifetimeService` 作为全局单例
+- **依赖注入**：通过 Prism 容器管理服务生命周期
+- **事件聚合器**：使用 Prism `IEventAggregator` 实现松耦合通讯
+
+### IPC 进程隔离架构 | IPC Process Isolation Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                    .NET 8 主进程 (XP.Hardware.RaySource)              │
+│                                                                      │
+│  ViewModel → RaySourceService → Comet225RaySource                    │
+│                                      │                               │
+│                              CometHostManager（管理 Host 进程生命周期）│
+│                              CometIpcClient（Named Pipe 双管道通信）  │
+│                                      │                               │
+│                              NamedPipe: Cmd（写入）/ Rsp（读取）      │
+└──────────────────────────────┬───────────────────────────────────────┘
+                               │ Named Pipe IPC
+┌──────────────────────────────┴───────────────────────────────────────┐
+│              .NET Framework 4.8 Host 进程 (Comet.Host)               │
+│                                                                      │
+│              CometPviClient ← BR.AN.PviServices.dll                  │
+│              （PVI 通讯层，直接操作 PLC 变量）                         │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 核心功能 | Core Features
+
+### 1. 设备生命周期管理 | Device Lifecycle Management
+
+```csharp
+// 初始化射线源（类型从配置文件读取）
+XRayResult result = _raySourceService.Initialize();
+
+// 连接 PVI 变量并启动实时状态通讯
+XRayResult connectResult = _raySourceService.ConnectVariables();
+
+// 异步执行初始化 + 连接变量的完整流程
+XRayResult autoResult = await _raySourceService.InitializeAndConnectAsync();
+
+// 开启射线
+_raySourceService.TurnOn();
+
+// 关闭射线
+_raySourceService.TurnOff();
+
+// 紧急关闭（最高优先级）
+_raySourceService.EmergencyShutdown();
+
+// 断开连接（保留实例以便重连）
+_raySourceService.Disconnect();
+```
+
+### 2. 电压电流控制 | Voltage and Current Control
+
+```csharp
+// 设置电压（20-225kV）
+_raySourceService.SetVoltage(100f);
+
+// 设置电流（10-1000μA）
+_raySourceService.SetCurrent(500f);
+
+// 读取实际电压
+XRayResult voltageResult = _raySourceService.ReadVoltage();
+float voltage = voltageResult.GetFloat();
+
+// 读取实际电流
+XRayResult currentResult = _raySourceService.ReadCurrent();
+float current = currentResult.GetFloat();
+```
+
+### 3. 设备操作 | Device Operations
+
+```csharp
+// TXI 开启/关闭
+_raySourceService.TxiOn();
+_raySourceService.TxiOff();
+
+// 暖机
+_raySourceService.WarmUp();
+
+// 训机
+_raySourceService.Training();
+
+// 灯丝校准
+_raySourceService.FilamentCalibration();
+
+// 全部电压自动定心
+_raySourceService.AutoCenter();
+
+// 设置功率模式（1=Micro Focus，2=High Power）
+_raySourceService.SetPowerMode(1);
+```
+
+### 4. 状态监控 | Status Monitoring
+
+```csharp
+// 读取系统状态
+_raySourceService.ReadSystemStatus();
+
+// 检查错误
+_raySourceService.CheckErrors();
+
+// 清除错误
+_raySourceService.ClearErrors();
+
+// 检查状态属性
+bool isInitialized = _raySourceService.IsInitialized;
+bool isConnected = _raySourceService.IsConnected;
+bool isXRayOn = _raySourceService.IsXRayOn;
+RaySourceStatus status = _raySourceService.CurrentStatus;
+```
+
+### 5. 灯丝寿命管理 | Filament Lifetime Management
+
+```csharp
+// 初始化灯丝寿命服务（模块启动时自动调用）
+_filamentLifetimeService.Initialize();
+
+// 获取累计使用秒数
+double totalSeconds = _filamentLifetimeService.GetCurrentTotalLifeSeconds();
+
+// 获取寿命百分比
+double percentage = _filamentLifetimeService.GetLifetimePercentage();
+
+// 检查是否需要预警（≥90%）
+bool shouldWarn = _filamentLifetimeService.ShouldShowLifetimeWarning();
+```
+
+### 6. 事件通讯 | Event Communication
+
+```csharp
+// 订阅射线源状态变化事件（三态：Unavailable/Closed/Opened）
+_eventAggregator.GetEvent<RaySourceStatusChangedEvent>()
+    .Subscribe(OnRaySourceStatusChanged, ThreadOption.UIThread);
+
+// 订阅系统状态更新事件（电压/电流/各子系统状态）
+_eventAggregator.GetEvent<StatusUpdatedEvent>()
+    .Subscribe(OnStatusUpdated, ThreadOption.UIThread);
+
+// 订阅错误事件
+_eventAggregator.GetEvent<ErrorOccurredEvent>()
+    .Subscribe(OnErrorOccurred, ThreadOption.UIThread);
+
+// 订阅操作结果事件
+_eventAggregator.GetEvent<OperationResultEvent>()
+    .Subscribe(OnOperationResult, ThreadOption.UIThread);
+
+// 订阅 PVI 变量连接状态事件
+_eventAggregator.GetEvent<VariablesConnectedEvent>()
+    .Subscribe(OnVariablesConnected, ThreadOption.UIThread);
+```
+
+---
+
+## 技术要求 | Technical Requirements
+
+### 运行环境 | Runtime Environment
+
+- **.NET 8.0** (net8.0-windows7.0)
+- **Windows 操作系统**（WPF 依赖）
+- **Visual Studio 2022** 或更高版本
+
+### 核心依赖 | Core Dependencies
+
+| 依赖库 | 版本 | 用途 |
+|--------|------|------|
+| **Prism.Wpf** | 9.0.537 | MVVM 框架和依赖注入 |
+| **Telerik UI for WPF** | 2024.1.408 | UI 控件库 |
+| **System.Configuration.ConfigurationManager** | 8.0.0 | 配置文件管理 |
+| **XP.Common** | - | 日志、数据库、多语言基础设施 |
+| **XP.Hardware.RaySource.Comet.Messages** | - | IPC 消息定义（netstandard2.0 共享库） |
+
+### 关联项目 | Related Projects
+
+| 项目 | 框架 | 用途 |
+|------|------|------|
+| **XP.Hardware.RaySource.Comet.Host** | .NET Framework 4.8 | Host 子进程，运行 B&R PVI 通讯 |
+| **XP.Hardware.RaySource.Comet.Messages** | netstandard2.0 | IPC 命令/响应消息定义 |
+
+---
+
+## 快速开始 | Quick Start
+
+### 1. 配置文件设置
+
+参见 [App.config.example](./App.config.example)
+
+### 2. 注册模块
+
+在 `App.xaml.cs` 中：
+
+```csharp
+protected override void ConfigureModuleCatalog(IModuleCatalog moduleCatalog)
+{
+    moduleCatalog.AddModule<RaySourceModule>();
+}
+```
+
+### 3. 使用服务
+
+在 ViewModel 中注入并使用：
+
+```csharp
+public class YourViewModel : BindableBase
+{
+    private readonly IRaySourceService _raySourceService;
+    private readonly IEventAggregator _eventAggregator;
+
+    public YourViewModel(
+        IRaySourceService raySourceService,
+        IEventAggregator eventAggregator)
+    {
+        _raySourceService = raySourceService;
+        _eventAggregator = eventAggregator;
+        
+        _eventAggregator.GetEvent<RaySourceStatusChangedEvent>()
+            .Subscribe(OnStatusChanged, ThreadOption.UIThread);
+    }
+
+    public void Initialize()
+    {
+        XRayResult result = _raySourceService.Initialize();
+        if (result.Success)
+        {
+            _raySourceService.ConnectVariables();
+        }
+    }
+}
+```
+
+---
+
+## 配置参数说明 | Configuration Parameters
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| SourceType | string | Comet225 | 射线源类型 |
+| PlcIpAddress | string | 192.168.12.10 | PLC IP 地址 |
+| PlcPort | int | 11159 | PLC 端口号 |
+| StationNumber | int | 1 | 源站号 |
+| PortNumber | int | 11 | 源端口号 |
+| CpuName | string | cpu | CPU 名称 |
+| ConnectionTimeout | int | 5000 | 连接超时（毫秒）|
+| MinVoltage | float | 20 | 最小电压（kV）|
+| MaxVoltage | float | 225 | 最大电压（kV）|
+| MinCurrent | float | 10 | 最小电流（μA）|
+| MaxCurrent | float | 1000 | 最大电流（μA）|
+| AdvanceExePath | string | FXEControl.exe 路径 | 高级设置外部程序路径 |
+| HostExePath | string | 空（自动查找） | Host 进程可执行文件路径 |
+| InitializationTimeout | int | 30000 | 初始化超时（毫秒）|
+| WarmUpTimeout | int | 300000 | 暖机超时（5分钟）|
+| StartUpTimeout | int | 180000 | 启动超时（3分钟）|
+| AutoCenterTimeout | int | 120000 | 自动定心超时（2分钟）|
+| FilamentAdjustTimeout | int | 120000 | 灯丝调整超时（2分钟）|
+| GeneralOperationTimeout | int | 10000 | 一般操作超时（毫秒）|
+| SerialNumber | string | 空 | 射线源序列号（灯丝寿命管理） |
+| TotalLifeThreshold | int | 1000 | 灯丝总寿命阈值（小时） |
+
+---
+
+## 安全机制 | Safety Mechanisms
+
+### 1. 参数范围验证
+
+所有参数在设置前都会进行范围验证，超出范围返回错误结果。
+
+### 2. 紧急关闭优先级
+
+紧急关闭具有最高优先级，可以在任何状态下执行，会依次关闭射线、完全关闭设备。
+
+### 3. 业务规则校验
+
+- 未初始化禁止操作
+- 防重复开启/关闭（双重检查锁定）
+- 异常断联自动检测和状态重置
+
+### 4. 灯丝寿命预警
+
+灯丝使用时长达到阈值 90% 时，系统自动弹出预警对话框。
+
+---
+
+## 文档索引 | Documentation Index
+
+- **[README.md](./README.md)** - 本文档，项目概述和快速参考
+- **[ProjectStructure.md](./ProjectStructure.md)** - 项目结构详解和调用链路
+- **[GUIDENCE.md](./GUIDENCE.md)** - 详细使用指南，包含完整代码示例
+- **[README_RaySourceOperateView.md](./README_RaySourceOperateView.md)** - 操作视图使用说明
+- **[App.config.example](./App.config.example)** - 配置文件示例
+
+---
+
+## 故障排查 | Troubleshooting
+
+### 初始化失败
+- 检查 Host 进程可执行文件是否存在（默认路径：`{主程序目录}/Host/XP.Hardware.RaySource.Comet.Host.exe`）
+- 检查 PLC IP 地址和端口配置
+- 确认 PLC 网络连接正常
+- 查看日志中 Named Pipe 连接状态
+
+### 射线无法开启
+- 确认已成功初始化并连接变量（`IsInitialized && IsConnected`）
+- 检查设备错误状态
+- 验证互锁信号
+
+### 电压电流设置失败
+- 验证参数在有效范围内
+- 确认射线源已初始化
+- 检查 IPC 管道连接状态
+
+### Host 进程异常
+- 检查 Host 进程是否正常启动（查看日志中 PID 信息）
+- 确认 BR.AN.PviServices.dll 已正确部署到 Host 目录
+- 检查是否有残留的 Host 进程（CometHostManager 会自动清理）
+
+详细故障排查请参考 [GUIDENCE.md](./GUIDENCE.md) 第 14 节。
+
+---
+
+## 许可证 | License
+
+本模块是 XplorePlane 项目的一部分，遵循项目整体许可协议。
+
+---
+
+**最后更新 | Last Updated**: 2026-03-26