docs: add time check design spec

docs/superpowers/specs/2026-07-10-time-check-design.md

@@ -0,0 +1,211 @@
+# 守时检测设计
+
+## 背景
+
+现有守时页面 `frontend/src/views/home/components/timeTest.vue` 是演示式页面，包含假数据、步骤条和旧的“标准时间/上送时刻”展示方式，不符合新的业务流程。新的守时检测需要同时支持多台装置，动态展示每台装置的暂态触发时刻、守时误差和结果，并与现有检测弹窗、后端 `startPreTest` 流程联动。
+
+后端项目位于 `D:\njcn\test\CN_Gather`。本设计覆盖前端与后端协同修改。
+
+## 目标
+
+- 守时页面只展示守时检测用时和设备结果表，不展示源连接、设备连接、协议校验、相序校验等前置阶段。
+- 表格列固定为：装置名称、暂态1触发时刻、暂态2触发时刻、守时误差、结果。
+- 未收到对应数据时，单元格显示 loading 转圈状态。
+- 守时检测计时格式为 `HH:mm:ss`。
+- 支持多台设备同时检测。
+- 守时检测过程要像 `factorTest.vue` 一样监听并拦截 WebSocket 错误，错误时终止流程。
+- 守时完成后，如果后续还有正式检测，前后端自动流向正式检测且保持组件状态；如果没有正式检测，则清理连接和 WebSocket 资源。
+
+## 检测项契约
+
+`PreDetectionParam.testItemList` 从 3 位改为 4 位：
+
+1. 第 1 位：预检测
+2. 第 2 位：系数校准
+3. 第 3 位：守时校验
+4. 第 4 位：正式检测
+
+前端所有调用 `startPreTest` 的位置都必须发送 4 位数组，例如：
+
+- 只做守时检测：`[false, false, true, false]`
+- 预检测 + 守时检测：`[true, false, true, false]`
+- 守时检测 + 正式检测：`[false, false, true, true]`
+- 预检测 + 守时检测 + 正式检测：`[true, false, true, true]`
+
+后端所有读取 `testItemList` 的逻辑同步使用新索引，不能继续把第三位解释为正式检测。
+
+## 前端流程
+
+### 启动规则
+
+`testPopup.vue` 继续作为检测弹窗流程编排入口。
+
+只勾选守时检测时，前端调用现有 `startPreTest`。接口成功返回后，认为守时检测开始，`timeTest.vue` 开始计时。后端随后执行源连接、设备连接、协议校验、相序校验，再进入守时暂态流程。
+
+勾选预检测 + 守时检测时，守时检测不在 `startPreTest` 成功后立刻开始计时。预检测包含源连接、设备连接、协议校验、相序校验四个阶段；这四个阶段完成后，后端推送守时开始/暂态数据相关消息，前端开始守时计时并展示表格更新。
+
+### 页面结构
+
+`timeTest.vue` 改为轻量结果页：
+
+- 顶部为紧凑计时区域，显示 `守时检测用时：HH:mm:ss`。
+- 下方为结果表格，列为 `装置名称 / 暂态1触发时刻 / 暂态2触发时刻 / 守时误差 / 结果`。
+- 行数据初始化自 `checkStore.devices`。
+- 未收到数据的字段显示 Element Plus loading 转圈。
+- `time_waiting_second` 消息只触发轻量提示，例如“已收到第一组暂态数据，等待第二组暂态数据”，不增加页面状态区和统计区。
+
+### Step 切换与状态保活
+
+守时检测完成且后续进入正式检测后，用户可以点击弹窗顶部 step 切回守时检测页。此时守时页只读展示已完成结果，不重启监听、不重置 loading、不重新计时。
+
+用户再切回正式检测页时，正式检测组件的表格信息、计时信息、日志进度和当前检测步骤不能初始化。实现上应保持组件实例存活，只切换 `stepsActiveView` 的显示状态，避免因 step 切换触发正式检测组件重建或初始化。
+
+### 错误处理
+
+`timeTest.vue` 需要接收并监听 `webMsgSend`，与 `factorTest.vue` 保持一致的错误拦截思路：
+
+- 通用错误码如 `10520`、`10521`、`10522`、`10523`、`10524`、`10525`、`10527`、`10528`、`10529`、`10550`、`10551`、`10552`、`-1`。
+- WebSocket 连接类错误，如 `socket_timeout`、`server_error`、`device_error`、`connect/Source`、`connect/Dev`。
+- 源连接、设备连接、协议校验、相序校验阶段虽然不展示在页面中，但这些阶段的错误必须被守时页捕获，弹窗提示后 `emit('update:testStatus', 'error')`，父流程终止。
+
+## 后端流程
+
+### 总体接入
+
+后端采用复用现有检测链路的方案。`startPreTest` 仍作为统一入口，守时校验作为现有检测链路中的独立业务阶段插入。
+
+单独勾选守时检测时，后端需要执行完整前置阶段：
+
+1. 源连接
+2. 设备连接
+3. 协议校验
+4. 相序校验
+5. 守时检测暂态流程
+
+勾选预检测 + 守时检测时，预检测已经包含前四个阶段。后端不重复执行、不关闭源连接和设备连接，直接进入守时检测暂态流程。
+
+### 守时业务规则
+
+守时检测使用后端内置的两段守时专用暂态脚本，不由前端传脚本编号。
+
+业务过程：
+
+1. 下发暂态脚本 1。
+2. 收取每台装置的一组暂态数据。
+3. 两次暂态触发时刻均从 `DevData.time` 读取。
+4. 同一设备存在多个监测点数据时，以第一条数据为准。
+5. 第一组数据收齐后，后端推送 `time_waiting_second` 事件。
+6. 后端等待 `waitTime - 暂态持续时间1 - fRampOut - fPreTime - fRampIn`。
+7. 下发暂态脚本 2。
+8. 收取每台装置第二组暂态数据。
+9. 计算 `dtMs = 暂态1触发时刻 - 暂态2触发时刻 - waitTime`。
+10. `dtMs <= 10ms` 为合格，否则不合格。
+
+结果判定完全由后端负责。前端只展示后端推送的守时误差和结果，不自行计算合格性。
+
+### 守时结束后的资源处理
+
+如果 `testItemList[3]` 为 `true`，守时检测完成后自动流向正式检测：
+
+- 后端不关闭源连接。
+- 后端不关闭设备连接。
+- 后端不清理正式检测需要的流程上下文。
+- 前端不关闭 WebSocket，不重建正式检测组件。
+- 前端收到守时成功后自动切到正式检测步骤。
+
+如果 `testItemList[3]` 为 `false`，守时检测后没有正式检测：
+
+- 后端在守时结束后断开设备连接和源连接。
+- 后端清理检测流程上下文。
+- 前端停止计时，展示最终结果，状态置为 `success` 或 `error`。
+- 弹窗关闭时清理 WebSocket 回调或连接。
+
+如果守时检测失败，无论是否勾选正式检测，都终止流程，不进入正式检测，并按错误流程释放资源。
+
+## WebSocket 消息
+
+守时阶段使用独立的守时消息语义，避免前端混在正式检测或系数校准消息里猜状态。推荐 `requestId` 使用 `Time_Check`。
+
+### `time_first_data`
+
+收到某台设备第一次暂态数据。
+
+`data` 建议字段：
+
+- `deviceId`
+- `deviceName`
+- `monitorId` 或监测点标识
+- `firstTriggerTime`
+
+### `time_waiting_second`
+
+第一组暂态数据已收齐，后端已进入等待第二次暂态数据阶段。
+
+该消息只作为事件触发标志，前端只做提示，不依赖业务字段。
+
+### `time_second_data`
+
+收到某台设备第二次暂态数据。
+
+`data` 建议字段：
+
+- `deviceId`
+- `deviceName`
+- `monitorId` 或监测点标识
+- `secondTriggerTime`
+
+### `time_result`
+
+某台设备守时结果计算完成。
+
+`data` 建议字段：
+
+- `deviceId`
+- `deviceName`
+- `firstTriggerTime`
+- `secondTriggerTime`
+- `waitTimeMs`
+- `dtMs`
+- `result`
+- `message`
+
+`result` 可以使用后端现有结果约定，也可以明确为 `passed` / `failed`。前端需统一映射为“合格 / 不合格”。
+
+### `time_finish`
+
+全部守时检测完成。
+
+`data` 建议字段：
+
+- `allPassed`
+- `results`
+- `hasFormalTest`
+
+前端收到后停止守时计时。如果 `hasFormalTest` 为 `true`，自动流向正式检测；否则结束当前检测流程。
+
+## 涉及文件
+
+前端：
+
+- `frontend/src/views/home/components/timeTest.vue`
+- `frontend/src/views/home/components/testPopup.vue`
+- `frontend/src/api/socket/socket.ts`
+- 必要时检查 `frontend/src/views/home/components/compareTestPopup.vue` 是否存在同类 `testItemList` 构造逻辑。
+
+后端：
+
+- `D:\njcn\test\CN_Gather\detection\src\main\java\com\njcn\gather\detection\pojo\param\PreDetectionParam.java`
+- `D:\njcn\test\CN_Gather\detection\src\main\java\com\njcn\gather\detection\controller\PreDetectionController.java`
+- `D:\njcn\test\CN_Gather\detection\src\main\java\com\njcn\gather\detection\service\impl\PreDetectionServiceImpl.java`
+- `D:\njcn\test\CN_Gather\detection\src\main\java\com\njcn\gather\detection\handler\SocketDevResponseService.java`
+- `D:\njcn\test\CN_Gather\detection\src\main\java\com\njcn\gather\detection\pojo\enums\SourceOperateCodeEnum.java`
+
+## 测试建议
+
+- 单独勾选守时检测：验证 `startPreTest` 成功后计时立即开始，前置四阶段错误可被前端拦截，最终无正式检测时资源被清理。
+- 勾选预检测 + 守时检测：验证前置四阶段不重复执行、不关闭连接，守时计时从预检测四阶段完成后开始。
+- 勾选守时检测 + 正式检测：验证守时成功后自动进入正式检测，连接和 WebSocket 不被清理。
+- 正式检测中点击 step 切回守时页，再切回正式检测页：验证正式检测表格、计时、日志和进度不初始化。
+- 多设备且多监测点：验证每台设备只取第一条监测点数据参与守时计算。
+- 守时失败：验证不进入正式检测，并按错误流程释放资源。
+- `time_waiting_second`：验证只提示，不改变表格结构。