更新开发文档

Docs/开发文档.md

@@ -1,6 +1,6 @@
 # 固态功率控制器动态参数测试系统 — 开发文档
 
-> 版本 v1.1 ｜ 技术栈：**C# + WPF + .NET 8** ｜ 口径：**以当前仓库代码为准**
+> 版本 v1.3 ｜ 更新：**2026-07-08 14:58:50 +08:00** ｜ 技术栈：**C# + WPF + .NET 8** ｜ 口径：**以当前仓库代码为准**
 >
 > 本文档描述当前仓库的真实结构、配置方式、核心流程和维护约定。
 > 若文档与代码冲突，以代码实现为准，并应同步回写本文档。
@@ -12,7 +12,7 @@
 对本项目进行新增、修改、排障时，默认遵守以下原则：
 
 1. **分层隔离优先**：UI 只依赖 ViewModel / Service / Logic，不直接依赖具体设备驱动。
-2. **接口先行**：SSPC、电源、负载、DAQ 一律经 `SSPCTester.Devices.Interfaces` 暴露，真假驱动由配置决定。
+2. **接口先行**：SSPC、电源、负载、DAQ、安全 DIO 一律经 `SSPCTester.Devices.Interfaces` 暴露，真假驱动由配置决定。
 3. **按设备粒度切换 Mock/Real**：当前不再是“一个全局 `MockMode` 管全部设备”，而是每类设备都有自己的 `UseMock`。
 4. **配置分层加载**：程序先读内置默认值，再读 `appsettings.json`，最后读 `%LOCALAPPDATA%\SSPCTester\settings.json`。
 5. **测试态独占**：进入测试后只展示当前项目，禁止切换其他项目，设备连接由测试态独占。
@@ -29,7 +29,7 @@
 - 基础通断状态
 - 开启/关断曲线与时间参数
 - 功率损耗与效率
-- 保护功能演示结果
+- 保护功能测试结果
 
 ### 1.2 当前测试台硬件
 
@@ -37,9 +37,10 @@
 |---|---|---|---|
 | 工控机 | Windows x64 | 运行 WPF 主程序 | 已支持 |
 | 被测件 SSPC | 24 路 | 控制 24 路导通/关断 | 已有 `SspcModbus` |
-| 程控电源 | UDP5080-100 | 输入端电压/电流读取 | 已有真实驱动，控制命令保留接口 |
+| 程控电源 | UDP5080-100 | 输入端电压/电流读取、输出开关控制 | 已有真实驱动 |
-| 可编程负载 | IT8733P / IT8702P | 输出端电压/电流/功率读取 | 已有真实驱动 |
+| 可编程负载 | IT8733P / IT8702P | 输出端电压/电流/功率读取、输入开关控制 | 已有真实驱动 |
 | 高速采集卡 | PCIe8586 | 曲线波形采集 | 已有 `Pcie8586Daq` |
+| 安全 DIO 卡 | PCI2312 | 急停输入读取、报警灯输出控制 | 已有 `Pci2312SafetyDio` |
 | 示波器 | Tektronix MDO3024 | 线下校准基准 | 不纳入软件控制 |
 
 ### 1.3 当前实现事实
@@ -47,7 +48,8 @@
 - SSPC 24 路通过 **3 个 Modbus 模块 × 每模块 8 路** 映射。
 - 采集卡实现已经统一为 **PCIe8586**，不再使用旧文档中的 `PCIe9318` 命名。
 - 真假设备切换已经演进为 **每类设备独立 `UseMock`**。
-- 主程序启动后会按配置自动连接 SSPC、电源、负载、DAQ。
+- 主程序启动后会按配置自动连接 SSPC、电源、负载、DAQ、PCI2312。
+- 新增设备安全监控链路：后台轮询 PCI2312 急停输入，触发后接通报警输出，并向 SSPC、电源、负载发送安全关断指令。
 - 根目录脚本 `run.ps1` / `publish.ps1` 已是当前标准运行入口。
 
 ---
@@ -71,9 +73,33 @@
 | 基础测试 | 24 路逐路开/关、读电压电流、判定稳态关断 | 已实现 |
 | 开启与关断曲线 | 支持开通/关断波形采集、指标计算、独立曲线视窗、波形落盘 | 已实现 |
 | 功率损耗 | 使用 UDP5080 读输入端，IT87xx 读输出端功率/电压/电流 | 已实现 |
-| 保护功能 | UI、数据结构和演示结果生成已完成，真实联动未接 | 框架完成 |
+| 保护功能 | 固定保护项、自动获取/人工观测数据记录、人工判别结果 | 已实现 |
 
-### 2.2 指标口径
+### 2.2 设备安全与急停报警
+
+当前代码新增了独立于“保护功能测试页”的**运行时设备安全链路**：
+
+- 硬件连接：`PCI2312` 通过厂商 `PCI2312_64.dll` 以 P/Invoke 方式接入，使用 DI 通道读取急停状态，使用 DO 通道控制报警灯。
+- 后台监控：`SafetyMonitorService.Start()` 在主窗口初始化后启动，按 `Devices:Pci2312:PollIntervalMs` 周期轮询急停输入。
+- 硬件急停：当配置的 DI 通道达到有效电平时，程序写入报警 DO，并依次执行 SSPC 全通道关断、电源输出关闭、负载输入关闭。
+- 软件急停：主窗口顶部“报警急停”按钮调用 `TriggerSoftwareEmergencyAsync()`，走同一套报警灯和设备关断链路。
+- 状态重置：报警灯点亮后按钮变为“状态重置”。若硬件急停 DI 仍有效，重置会被拒绝；DI 复位后才关闭报警输出并恢复监控状态。
+
+控制链路如下：
+
+```text
+PCI2312 DI 急停输入 / UI 软件急停按钮
+-> SafetyMonitorService
+-> PCI2312 DO 报警灯输出
+-> ISspc.TurnOffAsync(1..24)
+-> IPowerSupply.OutputAsync(false)  // UDP5080 :OUTput OFF
+-> ILoad.InputAsync(false)          // IT8702P INP OFF
+-> UI 状态、日志和报警灯图标同步刷新
+```
+
+注意：这是软件侧联动安全链路，用于快速下发关断和报警指令；现场仍应保留硬件级急停/互锁作为最终安全边界。
+
+### 2.3 指标口径
 
 当前计算与判定主要围绕以下指标：
 
@@ -82,7 +108,7 @@
 - `1.5` 上升/下降时间：10%~90% 或 90%~10% 时间
 - `1.9` 电压降：`Vin - Vout`
 - `1.10 / 1.13` 功率损耗、效率
-- `1.14+` 保护功能相关故障时间与演示状态
+- `1.14+` 保护功能相关触发条件、实测/观测值与人工判别结果
 
 阈值定义和最终判断以 `Project.CurveThresholds` 与各页结果模型为准。
 
@@ -98,6 +124,8 @@
 | DI / Host | `Microsoft.Extensions.Hosting` | 启动时装配所有服务 |
 | Modbus | `NModbus` | SSPC 串口控制 |
 | 串口 | `System.IO.Ports` | SSPC/部分设备底层通信 |
+| TCP Socket | `System.Net.Sockets.TcpClient` | UDP5080 / IT87xx SCPI-RAW 通信 |
+| 原生驱动 | P/Invoke + 厂商 DLL | PCIe8586 / PCI2312 接入 |
 | 波形绘制 | `ScottPlot` / `ScottPlot.WPF` | 曲线页与报告插图 |
 | 报告 | `QuestPDF` + `DocumentFormat.OpenXml` | PDF 与 Word 双实现 |
 | Web 预览 | `Microsoft.Web.WebView2` | 报告页 PDF 预览 |
@@ -137,7 +165,7 @@ SSPCTester.sln
 │   ├── Storage/                   # 项目与波形持久化
 │   └── Models/                    # 项目、结果、阈值、枚举
 ├── SSPCTester.Devices/            # 设备抽象与驱动
-│   ├── Interfaces/                # ISspc / IPowerSupply / ILoad / IDaq
+│   ├── Interfaces/                # ISspc / IPowerSupply / ILoad / IDaq / ISafetyDio
 │   ├── Drivers/Mock/              # Mock 驱动
 │   ├── Drivers/Real/              # 真设备驱动
 │   ├── Drivers/ConfigurableDevices.cs  # 按设备切换 Mock/Real
@@ -177,10 +205,11 @@ SSPCTester.sln
 - `Devices:PowerSupply:UseMock`
 - `Devices:Load:UseMock`
 - `Devices:Daq:UseMock`
+- `Devices:Pci2312:UseMock`
 
 `Devices:MockMode` 仅保留兼容旧配置用途，不应再作为新逻辑入口。
 
-### 5.3 当前 `appsettings.json` 示例
+### 5.3 当前 `appsettings.json` 节选
 
 ```json
 {
@@ -209,9 +238,26 @@ SSPCTester.sln
       "UseMock": false,
       "AutoConnect": true,
       "LogicalDeviceId": 0,
-      "ChannelCount": 4,
+      "ChannelCount": 1,
-      "PreTriggerMs": 10,
+      "InputRange": "PlusMinus5V",
-      "PostTriggerMs": 40
+      "ClockDivider": 1000,
+      "PreTriggerMs": 3,
+      "PostTriggerMs": 100,
+      "Channels": [
+        { "PhysicalChannel": 0, "Role": "OutputVoltage", "Name": "输出电压", "Scale": 1.0, "Offset": 0.0, "IsCalibrated": true },
+        { "PhysicalChannel": 1, "Role": "Unconfigured", "Name": "CH1", "Scale": 1.0, "Offset": 0.0, "IsCalibrated": false }
+      ]
+    },
+    "Pci2312": {
+      "Enabled": true,
+      "UseMock": false,
+      "AutoConnect": true,
+      "DeviceId": 0,
+      "EmergencyInputChannel": 0,
+      "EmergencyInputActiveHigh": true,
+      "AlarmOutputChannel": 0,
+      "AlarmOutputActiveHigh": true,
+      "PollIntervalMs": 100
     }
   },
   "Storage": {
@@ -306,6 +352,25 @@ public interface IDaq : IDeviceConnection
 `CaptureAroundActionAsync()` 是当前曲线测试的核心接口：  
 先进入预采集，再在触发点附近执行开关动作，以得到统一对齐的波形。
 
+### 6.6 安全 DIO
+
+```csharp
+public interface ISafetyDio : IDeviceConnection
+{
+    Task<bool> ReadInputAsync(int channel, CancellationToken ct = default);
+    Task WriteOutputAsync(int channel, bool on, CancellationToken ct = default);
+}
+```
+
+当前真实实现为 `Pci2312SafetyDio`：
+
+- `ConnectAsync()` 调用 `PCI2312_CreateDevice(DeviceId)` 创建设备句柄。
+- `ReadInputAsync(channel)` 调用 `PCI2312_GetDeviceDI()` 读取 0~15 路 DI。
+- `WriteOutputAsync(channel, on)` 维护 16 路 DO 状态数组，并调用 `PCI2312_SetDeviceDO()` 一次性写出。
+- `DisconnectAsync()` 调用 `PCI2312_ReleaseDevice()` 释放句柄。
+
+`ConfigurableSafetyDio` 按 `Devices:Pci2312:UseMock` 在 `MockSafetyDio` 与 `Pci2312SafetyDio` 间切换。PCI2312 是否参与自动连接由 `Devices:Pci2312:Enabled` 和 `Devices:Pci2312:AutoConnect` 共同决定。
+
 ---
 
 ## 7. 核心业务逻辑
@@ -332,6 +397,8 @@ public interface ITestModule
 
 `TestRunner` 依据 `Project.Selection` 串行执行模块。
 
+设备安全监控不属于 `ITestModule`，不会进入项目测试结果，也不会由 `TestRunner` 调度；它由 UI 层 `SafetyMonitorService` 在程序运行期持续维护。
+
 ### 7.2 浏览态 / 测试态
 
 当前程序已实现两种应用状态：
@@ -402,14 +469,68 @@ TurnOnAsync(ch)
 
 ### 7.6 保护功能
 
-当前保护功能页和逻辑层是**演示框架**：
+当前保护功能页和逻辑层已经按固定保护项落地，结果由 `ProtectRow` 持久化。`ProtectTestPlan` 负责初始化和刷新固定测试项：
 
-- UI 已完成
+- `跳闸`：触发条件默认 `1.5×额定电流`
-- 结果模型已完成
+- `短路`：触发条件默认 `输出短路`
-- `ProtectTest` 目前生成演示数据
+- `过温`：触发条件默认 `≥85℃`
-- 未接真实故障触发与真实曲线采集链路
+- `过压`：触发条件默认 `≥32V`
+- `欠压`：触发条件默认 `≤22V`
+- `限流`：触发条件默认 `≥1.2A`
 
-### 7.7 报告
+保护功能数据分为两类：
+
+- **自动获取**：对 `跳闸`、`过压`、`欠压`、`限流` 等可由电源读数支撑的项目，页面提供“测”按钮，调用 `IPowerSupply.ReadAsync()` 获取当前电压/电流并写入 `MeasuredValue`。
+- **人工观测**：对 `短路`、`过温` 等需要现场动作、仪表或人员观察的项目，由操作人员在 `MeasuredValue`、`Trigger` 等字段中填写观测记录。
+
+判定口径：
+
+- 最终判别标准为**人工判别**，不由程序自动计算合格/不合格。
+- `JudgeMode` 默认值为 `人工判别`。
+- `Status` 由操作人员在表格中选择 `合格` / `不合格` / `未判定`。
+- `ProtectTest.RunAsync()` 只负责刷新测量值和进度状态；若某项已经被人工判定为 `Pass` 或 `Fail`，运行批量测试时会保留该人工判定结果。
+
+### 7.7 设备安全监控
+
+`SafetyMonitorService` 是当前急停/报警链路的中心，依赖：
+
+- `ISafetyDio`：读取急停 DI、写报警灯 DO。
+- `ISspc`：触发急停后逐路执行 `TurnOffAsync(1..24)`。
+- `IPowerSupply`：触发急停后执行 `OutputAsync(false)`，真实 UDP5080 命令为 `:OUTput OFF`。
+- `ILoad`：触发急停后执行 `InputAsync(false)`，真实 IT8702P 命令为 `INP OFF`。
+- `UiLogSink`：写入 UI 日志，便于现场追踪急停动作。
+
+启动链路：
+
+```text
+App.ConfigureServices()
+-> 注册 MockSafetyDio / Pci2312SafetyDio / ConfigurableSafetyDio
+-> 注册 SafetyMonitorService
+-> MainViewModel.Initialize()
+-> ConnectConfiguredDevicesAsync()
+-> SafetyMonitorService.Start()
+```
+
+运行链路：
+
+```text
+Timer(PollIntervalMs，代码中限制 50~10000ms)
+-> 自动连接 PCI2312（若启用 AutoConnect）
+-> ReadInputAsync(EmergencyInputChannel)
+-> 按 EmergencyInputActiveHigh 解释有效电平
+-> 触发 HandleEmergencyAsync()
+```
+
+急停处理具有防重入保护：`_gate` 和 `_handlingEmergency` 避免重复并发关断。每个设备的关断失败会单独记录日志，不阻断后续设备的关断尝试。
+
+主窗口顶部状态区会展示：
+
+- 报警灯动态图标：绑定 `AlarmLampActive`
+- 急停/重置按钮：绑定 `ToggleEmergencyAlarmCommand`
+- 安全状态文本：来自 `SafetyMonitorService.StatusText / DetailText`
+- 设备面板中的 `报警/急停` 连接状态：来自 `ISafetyDio.IsConnected`
+
+### 7.8 报告
 
 当前报告支持：
 
@@ -522,6 +643,7 @@ PowerShell -ExecutionPolicy Bypass -File .\publish.ps1
 
 - 当前脚本明确没有走 WPF 单文件发布默认方案
 - 发布时会检查 `ACTS1000_64.dll` 是否存在
+- PCI2312 真设备模式还需要 `PCI2312_64.dll` 可由进程加载；当前发布脚本未做该 DLL 的存在性检查
 
 ### 9.4 运行环境
 
@@ -530,6 +652,7 @@ PowerShell -ExecutionPolicy Bypass -File .\publish.ps1
 - Windows x64
 - .NET 8 SDK x64
 - WebView2 Runtime
+- 真卡模式下的 PCIe8586 / PCI2312 厂商驱动与 x64 DLL
 
 若只运行现成发布版，则至少需要满足发布产物依赖和本机驱动/DLL 条件。
 
@@ -542,17 +665,18 @@ PowerShell -ExecutionPolicy Bypass -File .\publish.ps1
 - WPF 主程序骨架、主题资源、页面导航
 - 浏览态 / 测试态切换
 - 项目新建、加载、保存
-- 基础测试、曲线测试、功率损耗、保护功能页
+- 基础测试、曲线测试、功率损耗、保护功能页和结果记录
 - PDF / Word 报告生成
 - 真/假设备可按设备粒度切换
-- 实际 SSPC / 电源 / 负载 / PCIe8586 驱动接入代码
+- 实际 SSPC / 电源 / 负载 / PCIe8586 / PCI2312 驱动接入代码
+- PCI2312 急停输入轮询、报警输出、软件急停、状态重置和设备关断联动
 
 ### 10.2 待统一 / 待完善
 
-- 保护功能仍为演示逻辑，未接真实测试链路
 - 功率损耗旧版 `PowerTestLegacy` 仍在仓库，后续应明确去留
 - 曲线弹窗窗口已实现，但当前主页面尚未提供入口按钮
 - 报告生成对新旧曲线视窗字段的使用口径后续建议统一
+- PCI2312 真设备链路需要在现场确认 DI/DO 接线、电平有效性、报警灯供电方式和 DLL 随发布产物部署方式
 
 ---
 
@@ -561,9 +685,12 @@ PowerShell -ExecutionPolicy Bypass -File .\publish.ps1
 1. **DAQ 仍是最高风险点**：厂商 DLL、设备 ID、采样参数、输入量程和触发时序都依赖现场。
 2. **Modbus 地址和端口仍需现场核实**：虽然当前实现已支持 3 模块映射，但设备地址/串口号应视现场配置为准。
 3. **电源与负载真实驱动已接入，但控制命令支持度需按实物验证**。
-4. **所有长流程应贯穿 `CancellationToken`**，中止后优先保证设备回到安全状态。
+4. **PCI2312 急停报警链路依赖现场接线和 DLL 部署**：DI/DO 通道号、高/低有效配置、报警灯供电、`PCI2312_64.dll` 位数和搜索路径都必须逐项核实。
-5. **示波器不纳入软件控制**，仅作为线下校准基准。
+5. **软件安全链路不能替代硬件安全回路**：`SafetyMonitorService` 通过轮询和软件命令下发关断，适合作为上位机联动保护；最终急停/互锁仍应由硬件电气回路兜底。
-6. **任何涉及数据模型持久化格式的修改，都要考虑旧项目兼容**。
+6. **状态重置必须确认急停输入已复位**：当前代码在 DI 仍有效时拒绝关闭报警灯，避免误复位。
+7. **所有长流程应贯穿 `CancellationToken`**，中止后优先保证设备回到安全状态。
+8. **示波器不纳入软件控制**，仅作为线下校准基准。
+9. **任何涉及数据模型持久化格式的修改，都要考虑旧项目兼容**。
 
 ---
 
@@ -573,4 +700,5 @@ PowerShell -ExecutionPolicy Bypass -File .\publish.ps1
 2. 改项目结构前，先检查 `run.ps1`、`publish.ps1`、`Seed`、测试项目是否受影响。
 3. 改曲线页前，注意当前已经有“主页面 + 弹窗 + 报告图”的三处视窗相关逻辑。
 4. 改报告前，确认 `ReportViewModel`、`Logic/Report`、`WebView2` 预览链路同时保持可用。
-5. 若发现文档内容再次与代码偏离，应优先更新本文档，而不是继续在过时约束上开发。
+5. 改设备安全链路前，先确认 `ISafetyDio`、`Pci2312SafetyDio`、`ConfigurableSafetyDio`、`SafetyMonitorService`、主窗口急停按钮和设置页 PCI2312 配置同步调整。
+6. 若发现文档内容再次与代码偏离，应优先更新本文档，而不是继续在过时约束上开发。