# 故障录波（立项 · 卡片登记簿）

> **本文管排期与判据**：卡片表、顺序、资源占用、边界。**设计与口径的属主是 `docs/子系统设计/故障录波设计说明.md`**——为什么存原始码值、为什么先做 1 kHz、段文件格式、回放页画什么，都写在那份里，本文不重抄。
> **本文的待办只认下面的卡片表**；设计层面的开放项去设计文档找。

---

## 1. 现状一句话

**数据面与接线已在仓内，板级判据一轮未跑**（诚实口径，2026-10-29 更新）：录波环与段格式编解码在 `App/algo/wave_ring.c` 与 `App/algo/wave_store.c`，压环与落盘与保护启动接线、以及两条 UI 页的代码侧判据已过（三套主机单测 100 / 170 / 110 全 rc=0、双端编译 0 错误 0 警告、板端编码器与 PC 解码器两份独立实现字节级互验通过；「手动录波」第 26 叶与「录波回放」两叶均已绑页，`UI_PAGE_MAP_COUNT` = 30，内容页黄金参考 60 → 66 张含录波 6 态）。**没做完的是板级那一轮**：注 1 V / 50 Hz、FTP 拉回、与 `meas:` 行和 104 浮点 YC 对表、CRC 不符必须拒收的实测、真机上看回放页放一段真波；产品需求把「录波文件存储」「文件传输（录波）」两行的更新排在台架轮次之后。旧口径把录波挂在「工程量口径实测闭环之后」，本波用**原始码值**解掉了这个依赖（`docs/子系统设计/故障录波设计说明.md` §3.2）。

三条已裁定口径（用户裁定 2026-10-29，理由见`docs/子系统设计/故障录波设计说明.md` §1.2 与 §2）：

1. **采样率 1 kHz（每周波 20 点）**——复用现有 TIM3 节拍，与产品需求「80 点/周波」的偏离已在`docs/子系统设计/故障录波设计说明.md` §2 显式登记；
2. **8 路电气量全录**，含 V0.1 下必削顶的 STM32 五路，数据不筛选、用位图标记可信性；
3. **一屏只画一路、8 路可切换**——160×160 单色屏画不出多路，且跨转换器本就没有同一时刻性。

---

## 2. 卡片表

资源图例：**🔴 标准源**（需送检机构/0.05 级标准表）· **🟡 台架可做**（信号发生器、注入、FTP、串口）· **🟢 纯软件**（主机单测、构建、模拟器）。

| 卡 | 内容 | 退出判据 | 资源 | 依赖 |
|---|---|---|---|---|
| **录波数据面最小闭环**〔代码侧完成 / 板级待台架〕 | 新增专用录波环与段格式编解码（`docs/子系统设计/故障录波设计说明.md` §5 到 §7）；bench 构建定周期自抓；FTP 拉回；仓内新增一个纯标准库 PC 脚本读段、画图、重算全周傅氏 | **代码侧判据已完成**：三套主机单测 100 / 170 / 110 全 rc=0（环 100、段格式 170、触发状态机 110）、双端编译 0 错误 0 警告、板端编码器与 PC 侧解码器两份独立实现**字节级互验通过**（同一份字节两边同解）。**下列判据要板子与台架，一轮未跑**：注入 1 V / 50 Hz 正弦 → 拉回段文件 → PC 脚本量出周波数、幅值、极性与注入一致（**绝对相位不可比**，段内相位以点 0 为参考、触发瞬间在段内点 159，与发生器无相位锁定关系，可核对的是相对相位与极性——见 docs/子系统设计/故障录波设计说明.md §4.2 与 §10）；钉轨路数与头里 `clip_mask` 的合格判据是「头位图 ⊇ 实测钉轨路数，且差异必须能由注入条件解释」（`clip_mask` 按来源派生、非本段实测，V0.2 后该位恒 0、这条退化为只查实测）；**强观察项**：V0.1 下这五路做交流注入时反而没钉轨 → 先查接线或该路未驱动，属告警面不属失败面；**PC 重算的基波有效值与板上 `meas:` 行、104 浮点 YC 逐个对表通过**；段文件 CRC 不符时脚本必须拒绝而不是画出东西 | 🟡＋🟢（需信号发生器与板，不需标准源） | 无（可与固件其他道并行；独占构建锁） |
| **手动触发与保护启动接线**〔代码侧完成 / 板级待台架〕 | 触发状态机接两路真实来路：UI「手动录波」操作页（第 26 叶绑页，形态沿用已规划好的操作页确认模式）+ 保护启动的元件 picked 上升沿（落点 `App/task/protect_task.c` 的 `s_log_record_edge()`，不是判据核本身） | **代码侧已完成**：保护启动来路与并发语义（同拍多请求只录一段、冷却期内二次触发只加 `ovf`、冻结窗口只丢录波样本不丢采集）已在主机单测里钉住，双端编译 0 错误 0 警告。**下列属板级未完成**（第 26 叶已于 2026-10-29 绑页，模拟器侧手动触发路径已有黄金用例；剩下的必须在真机面板上按）：面板按一次出一段；造一次过流，段号与该时刻 `/log/start.log` 事件能对齐；冷却期内二次触发只加 `ovf` 计数、不重录（**同时看 `armed` 与那一刻 `/log/start.log` 的时刻，不要只盯 `ovf` 数字**：这两个计数是跨上下文自增、并发拒绝时可能少计一次，容差见 docs/子系统设计/故障录波设计说明.md §9）；冻结窗口内 104 上送与保护判据不受影响（**这条是"丢录波样本不丢采集"的验收**） | 🟡＋🟢＋UI 道（菜单树与字库是整文件生成物，须单写者） | 上一张卡 |
| **现场单通道回放页**〔代码侧完成 / 板级待台架〕 | 新增「录波回放」叶子与内容页：单通道 2 周波 40 点、阶梯线、0 线与峰值标注、单位徽标、削顶标记、空态文案（`docs/子系统设计/故障录波设计说明.md` §8） | **代码侧判据已完成**：两叶绑页（`UI_PAGE_MAP_COUNT` = 30）、`ui-golden` 内容页黄金参考 60 → 66 张（录波 6 态：手动录波 3 态 + 录波回放 3 态），任务树重建模拟器后同一批 66 张连跑三次逐字节一致（页面池水位 5,448 B）、菜单侧 8 状态连跑三次一致（5,368 B），`generated-fresh` 退出码 0（菜单树与中文字库生成物与源一致），双端编译 0 错误 0 警告。**下列判据要板子与台架，一轮未跑**：真机上放一段真波（不是模拟器合成节拍）、远端看图能拍到此页（只作留证，不当波形通路）、**空态与 CRC 失败态绝不允许画成一条直线**要在真机上用坏段复现一次 | 🟢＋🟡＋UI 道（模拟器与黄金参考） | 上一张卡 |
| 二期（不在本波） | 4 kHz 全速与 80 点/周波、突变量启动、COMTRADE、104 文件传输、分段与参考机形态（录波 65 通道、多类型多段） | 不在本波验收面内；重开条件见 §4 | 🔴／独立立项 | — |

**落盘道的失败留痕名（单板上一律一行 `[WAVE] seg drop: <原因> (idx=… written=…)`，统一打印点 `App/task/default_task.c:816`）**：`crc selftest FAIL` / `mkdir /wave` / `opendir /wave` / `readdir /wave` / `seg_path` / `pack_start` / `f_open` / `pack_next` / `f_write short` / `pack stall` / `f_close` / `len mismatch` / **`ring abandoned`**。最后一条是 docs/子系统设计/故障录波设计说明.md §5.2 第四条陷阱的处置留痕（写完关档后复检环侧身份不过 → 判废本段、`err` 加一、段号不推进），**代码与主机单测面已有、板级未测**；另有一条非失败的慢段留痕 `[WAVE][WARN] seg held <毫秒> ms (idx=…)`（`App/task/default_task.c:831`）——搬得慢不是错，真失败才走 `seg drop`。

**为什么录波排在信号发生器动态验证之前**（用户裁定）：动态验证真正缺的不是信号源，是**样本出口**——录波段文件一旦有了，动态验证就从「比对几个派生标量」升级成「PC 独立重算 vs 板上读数」的对表，同一套台架接线两次都用得上，不必再造一条串口通路。`docs/子系统设计/故障录波设计说明.md` §11 记了因此而变的三处口径。

---

## 3. 顺序与并行度

```mermaid
flowchart TD
    DSG[设计定稿: 设计文档 + 本卡片表] --> RING[专用录波环与段格式编解码]
    RING --> PC[PC 侧读段脚本与对表]
    PC --> BENCH{bench 台架对表通过?}
    BENCH -- 否: 回头改环或格式 --> RING
    BENCH -- 是 --> TRIG[两路真实触发来路: 手动 + 保护启动]
    TRIG --> COOL{冻结窗口内采集与上送无恙?}
    COOL -- 否 --> TRIG
    COOL -- 是 --> PAGE[单通道回放页与叶子上线]
    PAGE --> DONE[录波本波收口: 台账回填 + 文档现状化]
    PAGE -. 二期另立项 .-> NEXT[4 kHz 全速 / 突变量启动 / COMTRADE / 104 文件传输];
```

图内不写步骤号，卡名与 §2 卡片表逐字对应。并行度规则见 `docs/环境与部署/并行任务工作树方案.md` §7.3；**UI 道是单写者**——菜单树与中文字库都是整文件生成物，动叶子的那张卡不许与别的改 UI 的道并行。

---

## 4. 落地时的硬前置（每张卡收尾都要过）

| 前置 | 为什么 |
|---|---|
| 跑 `scripts/ram_report.py` 与 `scripts/stack_report.py` 前后各一次，回填 `scripts/ram_baseline.py --update` | 录波环与落盘缓冲约 5.9 KB 静态增量，**大于 4 KB 触发 R6 规则**（`docs/内存管理/内存内容分配策略.md` §6 台账与 R6）；CCM 只剩七千余字节 → 落位必须进 SRAM1（`docs/子系统设计/故障录波设计说明.md` §7） |
| 新 .c 双端注册 | `new-source-file`：`MDK-ARM/STM32F407-Demo.uvprojx` 与 `simulator/CMakeLists.txt` 都是显式文件列表 |
| `/keil-build` 0 错误 0 警告 | 任何代码改动后的固定动作 |
| 主机侧单测新增三套并挂总闸 | 环、段格式、触发状态机都是纯逻辑，能被 `test-coverage` 真跑；别把该测的部分留给台架 |
| 菜单与字库生成物重跑 | 新增叶子改叶数 → 同步 `docs/UI设计/页面补齐规划.md` 与 `docs/任务规划/UI补齐.md` 的口径闭合，重跑 `tools/menu_gen/gen_menu.py` 与中文字库链，过 `generated-fresh` 与 `font-charset` |
| 台账回填与文档现状化 | `docs/任务规划/README.md` 登记簿销项时同步清理引用；`docs/子系统设计/故障录波设计说明.md` §11 的三处口径要回写 `docs/任务规划/数据可信.md` |

**一期不做**（重开条件）：4 kHz 全速要等采集节拍改造与算法层抽取结构一并评审（结构约束已写进`docs/子系统设计/故障录波设计说明.md` §2.1，二期只加不改）；突变量启动跟 `docs/算法/继电保护功能复现规划.md` 的「故障启动（波形启动）」行；COMTRADE 与 104 文件传输等送检或第三方交接需求。

---

## 5. 与其它文档的关系

| 文档 | 关系 |
|---|---|
| `docs/子系统设计/故障录波设计说明.md` | **设计与口径属主**；本文只登记卡片与判据 |
| `docs/任务规划/数据可信.md` | 上游信度口径；动态波形验证卡因录波而改排在其后，读数出口升级见`docs/子系统设计/故障录波设计说明.md` §11 |
| `docs/任务规划/登记簿.md` | 原「故障录波与 104 文件传输」暂缓行已随本波立项销项（104 文件传输仍留二期） |
| `docs/任务规划/UI补齐.md`、`docs/UI设计/页面补齐规划.md` | 「手动录波」叶子旧状态是「不做（录波模块不存在）」，重开条件正是本波；上线后两处的叶数闭合要一起改 |
| `docs/问题记录/采集与数据处理短板评测.md` | 记录链缺口的登记处；本波落地后该行改指设计文档 |
| `docs/产品需求/参考产品复刻明细.md` | 复刻明细 §7「录波采样率」行是本波偏离的对照基准；复刻明细 §1.2「立项未排」行与 §8「文件传输（录波）」行按本波状态更新 |