feat(wave): 故障录波数据面、接线与单通道回放页（软件闭环交付）

数据面（App/algo，纯逻辑，双端编译） - wave_ring：8 路 × 320 点列优先环（1 kHz，预触发 160 + 后触发 160），adcTask 唯一写者；触发/冻结/封存/冷却四态，冻结持续到落盘回执才解冻，滞留 2 s 自弃兜底——下一次真故障无波可录比丢一段更贵 - wave_store：段头编解码 + 拉模式打包游标 + 自带无表位运算 CRC-16/MODBUS（带锚点自检）+ 段名与整段长度等式；格式不依赖平台类型宽度 - 段头只存原始码值与封存瞬间生效系数，工程量只当单位标签、不进任何算式 - 三套主机单测（环 113 / 编解码 170 / 触发状态机 110），全部无桩、生产源原样纳入；新文件补 stddef 是 ARMCC 与主机差异，主机侧照不出这条分叉 - test/host/wave_read.py 是按 §6.2 的独立第二实现（dump/fft/shape/plot），92 条自洽断言；三份合成段互读双校验全过、哈希钉死，格式面双向闭合 - 三套新单测不加专属钩子，由覆盖率总闸全量真跑（沿用既有裁定）接线（任务层） - adc_cal：新增生效系数的 32 位定点原值入口（与既有浮点入口共用生效视图），段头按最低有效位精确记账，不经浮点回算 - adcTask：每拍压 8 路语义原始码值并推进状态机，封存那一拍同拍交棒封存瞬间事实；台架定周期自抓走双层编译门，产品镜像里零存在；串口新增一条 wave: 周期行 - defaultTask：卷空闲后一次心跳整段搬完（try 锁 + 256 字节分片 + 一次完整开档到关档），成败都回执；失败先删半成品再计错，段号只在成功时推进；持锁超 50 ms 补一条告警并记历史峰值（喂狗余量可核） - Lead 复核补第四道并发陷阱：采集任务优先级高于落盘道，搬段中途它可能正好把滞留超时的本段自弃、甚至封出下一段——数据区校验和是对「实际读到的字节」算的，半新半旧的段照样自洽，故关档后复检环侧身份判废：删文件、不补账、段号不推进 - Lead 复核抓到触发挂号不是原子操作（旧实现分三个字节写，消费者可在窗口里读到上一段的触发源与元件号）：已把载荷压进一个字节，越界当场拒且不记任何计数；段文件字节布局零改动，三份合成段哈希逐字节不变 - protectTask：保护启动上升沿同点请求录波，一拍一次、元件号取最低位；判据本体零改动人机（160×160 单色屏） - 菜单树节点 26「手动录波」绑页面 + 记录查询组末新增「录波回放」叶，重跑生成器得 43 节点 / 34 叶 / 30 已绑，页面映射 28 → 30 - 回放页一屏一路、触发点前后各一周波共 40 点、每点 3 像素阶梯线（只用水平与垂直两种线段——单色屏斜线会被阈值裁掉）；零点虚线、触发光标、窗口峰值、单位徽标与形状受限徽标；空态与坏段各一句显式文案，绝不用半截波形冒充数据 - ui_data 新增录波注入通道（六件操作表、三态返回）；执行侧胶水带段头缓存、手动请求后连缓存一起作废、逐点走全仓唯一的码值换算入口 - 模拟器接真实环与编解码合成两段（含坏段与空态旗标），6 张新黄金参考，既有 60 张逐字节零漂移未用更新模式；字库 218 → 224 字 / 319 字形 - 两份图形配置里图表组件仍为关；零堆分配；页面池水位不变 - 回放读路径的 uiTask 阻塞上界按实码写清：一次渲染 = 段表刷新 + 未缓存段头最坏 22 次小读；已验段只剩一次开窗读 + 40 点解码；无实测数不编，实测归台架、仪器用已在跑的单轮工作耗时探针，不新加埋点台账与文档 - 内存台账：录波环与落盘/回放静态逐条入册，三档对照 81,536 → 88,296 → 89,936 字节（62.2% → 68.6%），累计 +8,400；预估 5.9 KB 与实测 +6,760 的差额点名；散列文件头注释同步；任务栈表核对后无需抬栈；体积趋势行与同码凭证由权威构建重打（0 错误 0 警告，四项体积与上一轮相同——本轮改动只有注释与声明位置） - 设计说明：§5 补第四条并发陷阱；§6.3 定字段口径（两份独立实现的共同依据）； §7 回填实测；§9 周期行写实；§10 台架判据改两段式且不比绝对相位；§12 补读路径风险行；抬头状态改成「代码面已交付、未做完的只有板级那一轮」 - 卡片：软件闭环一栏列证据；台架三条按用户裁定保持未完成，不做虚假销项 - 口径同步：数据可信、UI 补齐、页面补齐规划、产品需求、采集短板评测、任务规划索引与两份 README；陈旧现状句清扫 16 处（带日期戳的历史取数行一律不动） - 门禁说明：nested-comment 记仓库根探测必须兼容 linked worktree 的 gitdir 文件形态（修前该钩子在任务树里恒报环境错、静默不可用）；coding-standard 记「函数头注释超过 24 行就把函数功能挤出回看窗口」这条机制与本次现场 - 覆盖率基线登记两个新覆盖模块（套件 41 → 44 套）；环单测重打后该文件有效行 227 → 226、覆盖行 226 → 225，比率仍 99.6%，是分母变小不是覆盖率回退为什么是单一提交：文档链接、双端注册、生成器幂等（菜单与字库）、内存数字与体积事实源、编号门禁这五道整仓门禁要求代码、页面、菜单树、字库、文档与台账同处一个提交才自洽，按数据面/接线/人机/台账拆成四笔必然红其中至少四道编号门禁新增行 14 处命中已按语义改写：魔数常量按字符命名、段名样例改由格式串生成、频谱表头改 f / 2x / 5x 并加一行图例；改写后自洽断言 92 条仍全过
2026-10-29 19:23:15 +08:00
parent 325abe4337
commit d64bbdc57f
81 changed files with 8868 additions and 424 deletions
@@ -1,8 +1,8 @@
 # 故障录波设计说明（1 kHz · 8 路原始码值 · 现场单通道回放）

-> **模块名称**：故障录波——采样源沿用 TIM3 1 kHz 节拍，专用录波环（拟新增 `App/algo/wave_ring.c`）、触发、落盘（defaultTask 是文件系统唯一写者）、取回（FTP 21 端口）、现场回放（UI 单通道页）。
+> **模块名称**：故障录波——采样源沿用 TIM3 1 kHz 节拍，专用录波环（`App/algo/wave_ring.c`，已落地）、触发、落盘（defaultTask 是文件系统唯一写者）、取回（FTP 21 端口）、现场回放（UI 单通道页）。
 > **文档定位**：本波的**设计属主**——口径、通道集、数据形态、触发模型、文件格式、预算与所有权边界、显示契约、二期不返工的结构约束在此定稿。**排期与卡片判据在 `docs/任务规划/故障录波.md`**，本文不写排期。
-> **状态**：P0 设计定稿（2026-10-29），**代码一行未动**。三条已裁定口径见 §1.2。
+> **状态**：设计已定稿，**数据面 + 触发与落盘接线 + UI 两个页面（手动录波、录波回放）的代码面已交付（2026-10-29）**——主机单测 113 / 170 / 110 全 rc=0、双端编译 0 错误 0 警告、板端编码器与 PC 侧解码器两份独立实现字节级互验通过。**没做完的只有板级判据那一轮**（注量对表、FTP 拉回、与 `meas:` 和 104 浮点 YC 对表、CRC 不符必须拒收的实测、回放页放一段真波、两个待台架核数值），逐条列在 docs/任务规划/故障录波.md 各卡的板级段。三条已裁定口径见 §1.2。
 > **相关文档**：
 > `docs/子系统设计/ADC采样节拍设计说明.md`（节拍与时序账的属主；本文 §3 的数据源就是它）
 > `docs/硬件平台/ADC通道映射说明.md`（网名 `AINn` 不等于板级 `ADCn`，也不等于转换器通道号；链路分段与削顶归属）
@@ -106,16 +106,19 @@

 | 触发 | 来源 | 本波 |
 |---|---|---|
-| **手动** | UI「手动录波」操作页（该叶子早已在菜单里：`ui_menu_tree.txt` 装置维护组，现未绑页） | 做 |
-| **保护启动** | `App/algo/prot_elm.c` 的 `picked` 上升沿（元件启动），与 `/log/start.log` 同源，避免两处各自判定 | 做（复用事件点，不新增判据） |
+| **手动** | UI「手动录波」操作页（叶子在菜单装置维护组，页面模块 `Drivers/BSP/UI/ui_page_wave_manual.c`，2026-10-29 已绑页；确认键在 `App/task/ui_task.c`:582 行调 `wave_ring_request()`，走手动来路、元件号填 0） | 做（已落地） |
+| **保护启动** | 落点在 `App/task/protect_task.c` 的 `s_log_record_edge()`（函数体自 158 行起，picked 上升沿分支 170 到 177 行，实际调用在 176 行：`wave_ring_request(WAVE_TRIG_PROTECT, 最低位上升元件)`），与 SYSLOG_START 同一条边沿、同一事件点，避免两处各自判定。**刻意不落在 `App/algo/prot_elm.c`**：判据核被三套主机单测源码级纳入编译，往它加录波依赖会一次全破——这条就是「判据核零改动」的前提。多元件同拍启动只录一段（环不重入，后续请求由环计 ovf，不算失败） | 做（复用事件点，不新增判据） |
 | 定周期自抓 | `DTU_BENCH` 构建下每 N 秒强制一段，供信号发生器对表 | 做，**只在 bench 构建**，产品构建无此路径 |
 | **突变量启动** | 需要增量化 `Δi` 类算法与定值 | 不做，归二期（`docs/算法/继电保护功能复现规划.md` 的「故障启动（波形启动）」行） |

 ### 4.2 段长与冻结语义（RAM 就靠这一条省下来）

 - 一段 = **预触发 8 周波 + 后触发 8 周波 = 320 点/路**（1 kHz 下 320 ms）；
+- **段内点序**（两份实现共同遵守，PC 与回放页都按这条）：触发那一拍的样本落在**段内点 159**（预触发 160 点的最后一点），后触发第一拍是**点 160**，两半不重叠，故障时刻就是这条分界。因此段内点 0 相对工频周期边界有任意偏移（触发瞬间在周期内任意落点），**段字节里没有绝对时间参考**——能核对的是相对相位与极性，绝对相位只能以段内点 0 为参考报出（§10 板级判据据此不比绝对相位）；
 - **触发即冻结环**：停止推进录波写指针，defaultTask 直接从已冻结的环落盘，落完解冻；
 - **冻结期间丢的是录波样本，不是采集**——`sample_ring`、相量、保护判据照常跑（这就是 §2.1 第 3 条要求解耦的原因），冻结不拖慢保护动作，也不让 104 断数；
+- **解冻的唯一入口是落盘方回执**（`wave_ring_write_done(result)`，只在 defaultTask 上下文调）：写成功才推进轮转段号，写失败只计 err 且**下一段重写同一个号**（不留半截文件）；冷却期从回执之后才开始计时，回执前新触发一律只加 ovf。「落完解冻」这条原本按时间窗口的假设，实现里改由回执保证，冷却数值只是二次抑制。
+- 兜底（绝不允许录波把环焊死）：封存态滞留超过 `WAVE_SEAL_TIMEOUT_MS`（当前 2000 拍 = 2 s，**待台架核**）就自弃本段、计 err 并解冻——卡在一次落盘上，代价是下一次真故障无波可录。
 - 代价：一次触发的落盘窗口（约几十 ms）内再来触发只记第一次（冷却期），**不做多段排队**——那是二期「6 段 / RAM 16 个」的形态。

 ```mermaid
@@ -150,13 +153,14 @@ flowchart TD
 | **uiTask**（回放页） | 只读窗口取段数据 → 自绘（与 `App/log/soe_store.c` 读侧同构） | 不写文件 |
 | **netTask / lftpd** | 把 /wave 暴露给 FTP 取回 | 不在 netTask 里读录波环 |

-### 5.2 三条已知陷阱，本波必须绕开
+### 5.2 四条已知陷阱，本波必须绕开

 | 陷阱 | 事实出处 | 本波处置 |
 |---|---|---|
 | **取窗竞态** | `App/algo/sample_ring.c` 的 `sample_ring_window()` 没有临界区（读 `s_head` 后逐点拷），现在只有 adcTask 同任务调用才安全 | 录波**不复用它**：adcTask 在自己的节拍里取「本拍帧」压专用环；跨任务只传递「已封存」标志，杜绝跨任务读活缓冲 |
 | **FatFs 追加写** | 该移植 `FA_OPEN_APPEND` 不含 `FA_WRITE`，且 `f_write` 簇分配失败时返回 `FR_OK` 加短写、无错误码（`docs/架构设计/STM32F4-Base存储架构说明.md` §10.1） | 打开一律 `FA_WRITE|FA_OPEN_APPEND`；**判成功必须比对写回字节数**，短写按失败处理（丢段 + 日志），绝不当成功记账 |
 | **只能 8.3 短名** | 出处同一张存储架构说明的短名限制：`FF_USE_LFN=0`，不得以点开头、不得长名 | 文件名 = WAVE 加两位十进制再加 .BIN，共 100 个名字轮转覆盖；目录 /wave（与 /log 平级，FTP 根下可见） |
+| **落盘途中环被解冻、甚至已换段**（实现期复核新增第四条，2026-10-29） | adcTask 优先级高于 defaultTask：搬段窗口里 adcTask 可能正好走到 SEALED 滞留 2 s 自弃，甚至已经封出下一段。**数据区 CRC 是对「本道实际读到的字节」算的**，半新半旧的段照样自洽——长度等式照过、两个 CRC 照对，文件骗得过任何读者，也骗过我们自己 | 写完关档后**复检环侧身份**：`wave_ring_sealed()` 仍为 1，且 `wave_ring_get_stat()` 的 `last_t0_ms` 与 `last_seq` 跟本道开始搬时那份段头一致；不符即走既有失败路——unlink 本道开过的文件 + `write_done(-1)`（此时多半回 `E_STATE`，环侧 `err` 已由自弃计过，不重复补账）+ 段号不推进（下一段同号重写覆盖）+ 单条 `[ERR] … seg drop: ring abandoned` 留痕。落点 `App/task/default_task.c`:786 到 796 行。**当前只有代码与单测面，板级未测**；可观察项见 §10 板级行 |

 ![录波数据的四个所有者与跨任务边界：adcTask 只写环，defaultTask 独占落盘，uiTask 与 PC 只读](../images/故障录波数据流.svg)

@@ -190,16 +194,44 @@ flowchart TD
 | 14 | t0_ms | 4 | 段首相对上电时刻；配合墙钟还原绝对时刻 |
 | 18 | wall | 4 | 对时后的 epoch 秒（未对时为 0） |
 | 22 | eng | 1 | 封存瞬间的折算档位：0 引脚域、1 二次值、2 一次值 |
-| 23 | flags_seq | 1 | 有效性位图（引 `adc_cal_flags()` 口径） |
-| 24 | clip_mask | 2 | 削顶归属（V0.1 恒 0xE6，见 `docs/任务规划/数据可信.md` §2.7） |
+| 23 | flags_seq | 1 | 每路 VALID 压成的位图：bit s = 语义通道 s 的 `ADC_CAL_F_VALID`（电气 8 路恰好占满 1 字节；TEMP 不参与标定，若要带 TEMP 连本行与下一行一起升版本） |
+| 24 | clip_mask | 2 | 削顶归属位图：bit s = 语义通道 s，与 `App/algo/meas.h` 同名参数同口径（封存瞬间 `ADC_CAL_F_CLIPPED` 快照，V0.1 恒 0xE6 = UB/UC/IB/IC/IN，见 `docs/任务规划/数据可信.md` §2.7）。⚠ **这个位图的本体是「链路可信性标记（按来源派生）」，不是「本段实测饱和标记」**：置位条件一次样本都不看（`App/algo/adc_cal.c` 291 到 296 行，该路 ROM 系数属片内 ADC 侧即置位）；「这一段有没有真钉轨」走另一条链——`App/algo/adc_health.c` 的 `adc_health_rail_watch()`（280 行起）与 `adc_health_rail_sticky()`，门限按满量程百分比由 `adc_cal_rail_ths()` 给、须连续 `ADC_RAIL_N_RUN` 拍。V0.2（8 路全接 TPAFE）后本位自动恒 0，届时「与 clip_mask 对表」这条判据退化为只查钉轨实测（§10） |
 | 26 | frame_seq | 4 | 段首帧序号，可与串口周期行的 frames 对账 |
-| 30 | 通道表 | 每路 12 | 语义号 1 + 来源转换器 1 + 位宽 1 + 有效位 1 + LSB(µV) 4 + k 2（定点）+ b 2（定点） |
-| — | CRC16(头) | 2 | 与屏板链路同一张 CRC-16/MODBUS 表，不新造 |
+| 30 | 通道表 | 每路 12 | 语义号 1 + 来源转换器 1 + 位宽 1 + 可用性 1（= `adc_cal_flags(sem)` 低 8 位原值，不自造位义）+ `k_q16` 4（int32，µV/码 × 65536）+ `b_codes` 4（int32，码值）。**没有独立 LSB 字段**，LSB 就是 `k_q16`，见 §6.3 |
+| — | CRC16(头) | 2 | CRC-16/MODBUS，**低字节在前**（与全文件小端统一）；覆盖 `[0, 30+12×ch_count)`，本字段自身紧随其后 |
 | — | 数据区 | pts_per_ch × ch_count × 2 | **按通道分列**：一路连续 320 点，单通道回放只读那一路 |
-| — | CRC16(数据区) | 2 | 长度为 0 或 CRC 不符 → 整段作废，页面必须显示「该段不可读」 |
+| — | CRC16(数据区) | 2 | 同上字节序；覆盖整个数据区、自身在文件尾（8 路 320 点整段 5250 B）；长度为 0、任一 CRC 不符、或 `ver` 与魔数第三字节不等 → 整段作废，页面必须显示「该段不可读」 |
+
+**段名轮转的呈现语义**（回放页与 PC 侧取「哪一段最新」都按这条）：段表按**数值升序**呈现，开屏落点取**数值最大的段号**。回绕（99 之后回到 00）之后「数值最大」不再等于「时间最新」——要真时间序必须逐段读段头 `frame_seq` / `t0_ms`，代价是 100 次开文件，**本波不做**。所以页顶把段号本身显示出来（§8.1 顶部行），让读者自己看见这是第几号，不去伪造一个「最新」的假象。
+
+### 6.3 字段口径裁定（两份独立实现的共同依据）
+
+本波段格式有**两份独立实现**：板端编码器 `App/algo/wave_store.c` 与 PC 解码器 `test/host/wave_read.py`，两份必须逐字节同解，所以动工前把 §6.2 的含糊处一次钉死（PC 道九问的逐条答复）：
+
+| 问题 | 裁定 |
+|---|---|
+| CRC 字节序 | **低字节在前**，与全文件小端一致。原稿「与屏板链路同一张 CRC-16/MODBUS 表」不成立：全仓**没有**可复用的 CRC-16 表——`App/util/README.md` 记 `crc.c/h` 已于 2026-10-02 删除，屏板链路 `Drivers/BSP/UI/ui_net_sink.c` 的 `remo_crc()` 是单字节异或、不是 CRC-16。本波在 `wave_store.c` 内自带**无表位运算** CRC-16/MODBUS（0x8005 反射、初值 0xFFFF、异或输出 0），单测锚点：串 123456789 的 CRC = 0x4B37 |
+| CRC 覆盖范围 | 头 CRC 覆盖 `[0, 30+12×ch_count)`、自身在 `30+12×ch_count`；数据区自 `32+12×ch_count` 起；数据 CRC 覆盖整个数据区、自身在文件尾。8 路 320 点整段 5250 B |
+| LSB 从哪来 | **不设独立 LSB 字段**：通道表的 `k_q16` 就是 LSB（µV/码 × 65536），与 `App/algo/adc_cal.h` 的 `ADC_CAL_K_Q16_TPAFE 10000000` / `ADC_CAL_K_Q16_STM32 52800000` 同口径，Q16 下无舍入（选型依据 `docs/任务规划/数据可信.md` §4.1）。PC 侧 `µV = k_q16 / 65536`，不许再乘一遍 |
+| k / b 宽度与角色 | `k_q16` int32、`b_codes` int32 = 封存瞬间该路生效的两个标定量。`adc_cal_apply()` 的算式是 `eng = (code + b) × k × 1e-6`，文件里存的正是等号右边两个数加原始 code，PC 照此重算。**必须取 int32 原值**，不得经 `adc_cal_k_uv()` 的 float 通道回算（float 在 5.28e7 量级掉尾数）→ 接线道在 `App/algo/adc_cal.[ch]` 补一个 int32 直读入口 `adc_cal_k_q16()`（与 `adc_cal_k_uv()` 孪生）；eng=0 时两者是 ROM 默认值，PC 折出来的单位是**引脚域 µV** 而非二次值——单位一律以头里的 `eng` 为准，PC 不许按当前固件口径猜 |
+| `flags_seq` 位义 | bit s = 语义通道 s 的 `ADC_CAL_F_VALID`；本波 `ch_count` 固定 8 |
+| 可用性字段真值表 | 两行，实现期按 `App/algo/adc_cal.c` 280 到 298 行核出（VALID 需文件位图与 k 合法带**同时**成立；CLIPPED 纯由来源派生——该路 ROM 系数属片内 ADC 侧即置位，与样本内容无关）：① **未标定**（产品构建，两点标定未做）逐路 availability = UA / UN / IA 取 `0x00`，UB / UC / IB / IC / IN 取 `0x02`，`flags_seq` = `0x00`，`clip_mask` = 0xE6；② **已标定**（电气 8 路系数全部写入且落合法带）逐路 = `0x01`（TPAFE 三路）/ `0x03`（片内 ADC 五路，VALID 与 CLIPPED 同时为真），`flags_seq` = `0xFF`，`clip_mask` 仍是 0xE6。**VALID 与 CLIPPED 是两件独立事实**：写侧如实透传 `adc_cal_flags()` 逐路原值（`App/task/adc_task.c` 548 行），读侧不得据任何品质组合判废，PC 与回放页只给软告警（见下面「判废面与软告警面」一行） |
+| eng 派生式 | `eng` 不是独立事实，是逐路有效位图的派生量：**电气 8 路全 VALID → 二次值（1），缺任意一路 → 引脚域（0）**。真机两处必须同口径，行号一并登记：判据本体 `App/app/ui_data_feed.c` 226 到 235 行的 `feed_eng()`（屏显侧），段头字段填写 `App/task/adc_task.c` 532 到 553 行（其中 552 到 553 行是段头侧的同一派生）。两处分布在**不同任务里现算**，理论上会撞上配置重载的毫秒级沉降窗而不一致——这是允许态，见下一行 |
+| 判废面与软告警面 | **完整性判废面自始至终只有这些**：精确尺寸等式、`magic` 与 `ver`（含 `ver` 须等于魔数第三字节）、头 CRC 与数据 CRC、表序 `sem` 等于下标、`ch_count` 上限、`pts_per_cycle` / `pts_per_ch` / `pre_pts` 下限、长度为零、文件短读。**品质组合与单位标签永远不进这道门**。本轮新增的只是**软告警面**：`avail` 同时带 VALID 与 CLIPPED 时 PC 在 NOTE 列打「同时为真，两点标定完成后属正常，非故障」；`eng` 与 `flags_seq` 违反上一条派生式时打 WARN。两者都**不改退出码、不影响出图、不拒渲染**。理由：把「单位标签不一致」当数据损坏，等于让一次改标定文件的沉降窗销毁故障证据 |
+| 通道表序与列序 | 第 i 个通道表项 ↔ 数据区第 i 列，按语义号**升序**：UA=0 UB=1 UC=2 UN=3 IA=4 IB=5 IC=6 IN=7（`App/algo/adc_input.h` 的 `adc_semantic_t`）。PC 必须校验表内语义号等于下标，不等即整段作废。交叉验证：`clip_mask` 恒 0xE6 = 2+4+32+64+128，恰好是 UB/UC/IB/IC/IN 五个语义号位，这份算术就是这个顺序的证据 |
+| 样本编码 | int16 小端；TPAFE 侧 16 位补码双极性；STM32 侧 0..4095 原样存正数，**不加中点偏置**——V0.1 单极性无偏置是硬件现状，加偏置等于伪造双极性（`docs/任务规划/数据可信.md` §2.7） |
+| 三个时间字段 | `t0_ms`（上电毫秒）、`wall`（epoch 秒，未对时 0）、`frame_seq`（段首帧序号）均 u32 无符号小端 |
+
+**本波 TEMP 不录**（`ch_count` = 8）：温度非线性未折算，进录波只多占一路字节、不增加可解释信息（`docs/任务规划/数据可信.md` §7 的「温度不参与线性标定」已定案）。

 **为什么按通道分列而不是按帧交错**：回放页只画一路 → 只需连续读那一路；PC 重算全周傅氏也是逐路独立。交错布局两种用法都要跨步长取数，白付代价。

+**实现期纠正记录（三条，只作追溯，不构成规格）**
+
+1. `flags_seq` 的 V0.1 真值一度被写成 `0x27`：那是把「按来源派生的 CLIPPED」当成了 VALID。按 `App/algo/adc_cal.c` 280 到 298 行，未标定态就是 `0x00`（见上面真值表第一行）。凡引用这个数字的地方一律以真值表为准。
+2. 一版互验夹具写成 `eng` = 0 而 `flags_seq` = `0xFF`——违反上面的 eng 派生式，是一串**真机写不出来**的字节。已改为按派生式自洽，并在 `test/host/wave_store` 那套单测里加了夹具自洽断言防复发。教训一句话：**互验夹具的资格来自「真机能写出这串字节」**，一份不可能状态的字节只能验证两个读者对幻觉的一致反应，正好掩盖真分歧。
+3. 顺带钉一条因果，免得后文写反：PC 侧早期一次 `shape` 子命令在 `--strict` 下 rc=1，与品质位**无关**，那是「实测触轨路数 vs 段头 `clip_mask`」对表不符（合成夹具的波形本来就没真触轨）。那条对表是 `docs/任务规划/数据可信.md` §4.6 与本文 §10 板级判据的本职，不是解码器的判废扩展。
+
 ---

 ## 7. 预算（先算后写，R6 是硬前置）
@@ -213,12 +245,24 @@ flowchart TD
 | **合计静态增量** | — | **约 5.9 KB** |

 - **大于 4 KB ⇒ 触发 R6**：`docs/内存管理/内存内容分配策略.md` 的 R6 要求「任何新增静态缓冲 >4 KB 必须先核 §6 台账余量，改后同步 §6 数字、.sct 头注释与 AGENTS 栈表」；加大缓冲本身属 **Ask-first**；
- **落位 = SRAM1，不进 CCM**：CCM 受管区已 87.9 %、只剩 7,904 B，SRAM1 为 62.2 %（数字出自 `docs/内存管理/RAM预算台账.md` §1 受管区表）；录波环不是 DMA 可见对象，没有「CCM 不可达」的约束，但 CCM 也**没有余量**给它；
+- **落位 = SRAM1，不进 CCM**：CCM 受管区已 87.9 %、只剩 7,904 B，本波开工时 SRAM1 为 62.2 %（数字出自 `docs/内存管理/RAM预算台账.md` §1 受管区表；录波落地后的终值见本节末「实测回填」）；录波环不是 DMA 可见对象，没有「CCM 不可达」的约束，但 CCM 也**没有余量**给它；
 - **UI 子系统配额早已超**（同一张表的子系统行）→ 回放页的描述符与名表仍要在台账记账，别拿「反正已超」当免检；
 - 前后各跑一次 `scripts/ram_report.py` 与 `scripts/stack_report.py`（defaultTask 多了落盘链、uiTask 多了读窗与自绘）；`mem-budget` 钩子是总量红线，`ram_baseline.py --update` 回填趋势；
 - **Flash**：段格式编解码 + 状态机 + 回放页 + 一条日志行，粗估 3 到 5 KB（Flash 基线在 25 % 量级，不是瓶颈）；
 - **NAND**：一段约 5.2 KB 数据加头。轮转 100 段约 0.5 MB，对 256 MB 单分区是零头——**瓶颈不是容量，是写次数**（§10 红线）。

+**实测回填（2026-10-29 权威构建，0 错误 0 警告；逐对象台账见 `docs/内存管理/内存内容分配策略.md` §6）**
+
+| 口径 | 上面的预估 | 实测 |
+|---|---|---|
+| SRAM1 静态增量 | 约 5.9 KB | 数据面 **+6,760 B**（81,536 → 88,296）；UI 道另 +1,640 B；累计 **+8,400 B** → 终值 **89,936 B / 68.6 %** |
+| CCM | 0（不得进 CCM） | **0**：`RW_CCM` 三档恒 57,376 B / 87.9 %，既没进 CCM 也没挤动它 |
+| Flash | 3 到 5 KB | `ER_IROM1` 264,580 → 270,248（数据面 +5,668）→ 272,300（UI 道 +2,052）→ 272,360（落盘判废复检 +60）→ **272,336** B（cppcheck 返工纯搬声明，−24），累计 **+7,756 B**、占 26.0 %；`Total ROM` 274,308 B、`Code` 243,552 B |
+| 任务栈 | 未估 | 九任务全 PASS、**未抬栈**：adcTask 静态最坏链 1,424 B（余 1,136 B / 44 %）、defaultTask 3,040 B（余 2,080 B / 40 %）、uiTask 1,336 B（余 15,048 B / 91 %） |
+
+- **差额构成（比预估多 860 B，可对账）**：原估漏记 `FIL` 528 B（`FF_FS_TINY=0`，落盘道刻意不上栈）、`DIR`/`FILINFO`、已封存段头副本 136 B、打包上下文（内部又含一份 136 B 段头）；反向少记一项——落盘实际是**单缓冲 256 B**，不是预估的 512 B 双缓冲。**预估与实测都留在本节**：只写实测，下一次估算就看不见原估漏在哪。
+- **回放页读窗不在数据面那 6,760 B 内**：它计入 UI 道的 +1,640 B；两张表不能相加当总量，逐对象拆分见 `docs/内存管理/内存内容分配策略.md` §6。
+
 ## 8. 现场回放显示契约

 ### 8.1 一屏画什么
@@ -261,8 +305,9 @@ flowchart TD
    wave: seg=NN armed=1 src=P pts=320 err=N ovf=N drop=N

 - `err` 是落盘失败或 CRC 自弃次数（**字节数不符就算失败**，见 §5.2）；`ovf` 是冷却期丢弃的触发数；`drop` 是冻结窗口丢掉的录波点数；
+- **实际落地形态（逐字）**：打印点在 `App/task/adc_task.c`:782 行，格式串 `"wave: seg=%lu armed=%u src=%s pts=%u err=%lu ovf=%lu drop=%lu"`——**字段名与顺序就是上面的模板**（台架与 PC 脚本按行名 grep，动它就断脚本）；`src` 取 M（手动）/ P（保护）/ T（定时自抓）/ `-`（本次上电还没触发过）；`armed` 只在 FREEZE 与 SEALED 为 1（COOL 期只挡新触发不录新段，画进 armed 会被台架误读）；`seg` 是累计**成功回执**的段数、不是轮转号；`err` = 落盘失败 + SEALED 滞留超时自弃（含 §5.2 第四条的 ring abandoned 判废），由环内计数收口，落盘道不数第二份账。`err` 与 `ovf` 的**已知容差**（lead 裁定 2026-10-29，不修只入档）：这两个计数是跨上下文的读-改-自增（`ovf` 由任意上下文的拒绝路径加、`err` 由 adcTask 的滞留自弃与 defaultTask 的落盘失败分别加），本层双端编译、不许引 FreeRTOS / CMSIS 的临界区内在函数，所以并发拒绝或并发失败时**理论上可能少计一次**。定性为**观测计数的已知容差**：只用于趋势与判读，**不作为任何判据的唯一依据**——要坐实「冷却期内确实来了第二次触发」，同时看 `armed` 与那一刻 `/log/start.log` 的时刻。契约原文见 `App/algo/wave_ring.h` 文件头「观测计数的已知容差」段；
 - 只在原先静默的黑洞处补锚点，别重复已有步骤——每条 DBG 日志约 90 B Flash 加 216 B 栈（`AGENTS.md` 的日志与工具链节）；
- 该行落地时同步进 `docs/测试说明/ADC前端注入验证流程.md` 的读数出口表。
+- 该行已同步进 `docs/测试说明/ADC前端注入验证流程.md` 的读数出口表（2026-10-29；同一张表还登记了段文件出口与 PC 侧读段工具）。

 ---

@@ -271,10 +316,13 @@ flowchart TD
 | 层 | 内容 |
 |---|---|
 | 主机侧纯逻辑单测（新增，进 `test/host/`） | ① 环：预触发与后触发点数、冻结与解冻、冷却丢弃计数；② 段格式编解码往返，含 CRC 不符、零长度、字节数不符三条失败路径；③ 触发状态机三条来路（手动 / 保护 / bench）。**环与格式必须是纯逻辑**（不碰寄存器、不碰 RTOS）才能这样测——这是 `App/algo/` 既有分层纪律 |
-| 板级 | 信号发生器注 1 V / 50 Hz → 手动一段 → FTP 拉回 → PC 脚本量出周波数、幅值、极性、削顶路数与 `clip_mask` 一致；再把 PC 重算的基波有效值与板上 `meas:` 与 104 浮点 YC 对表 |
+| PC 侧工具的定性 | `test/host/wave_read.py` 是 **bench 工具**（`test/host/` 下的 loose .py，先例 `test/host/ftp_capture.py`），**不是**主机单测套件 → 不建 `run_unit_test.py`、不加 pre-commit 专属钩子（专属钩子默认不补，按 Lead 裁定 2026-10-27）；它自带 `--selftest` 就是它的自带回归，跑法与四个子命令见 `docs/测试说明/ADC前端注入验证流程.md` §4 |
+| 跨工具链分叉（实证，写进来是为了下一个模块别重踩） | 两份录波 .c 只 include 自身头（链上只有 stdint.h）时，ARMCC 报 22 条 identifier "NULL" is undefined；而主机 MSVC / gcc 会传递性把 stddef.h 拉进来，**主机单测完全照不出这个分叉** → 新增模块需要用 NULL 就自己 include stddef.h（与 `App/algo/sample_ring.c` 同口径，别塞公共头） |
+| 板级 | 信号发生器注 1 V / 50 Hz → 手动一段 → FTP 拉回 → PC 脚本量出周波数、幅值、极性与注入一致；再把 PC 重算的基波有效值与板上 `meas:` 与 104 浮点 YC 对表。**判据只量四样：周波数、幅值、极性、钉轨路数——不比绝对相位**（理由见 §4.2「段内点序」：触发瞬间在工频周期内任意落点，段字节里没有绝对时间参考；真要比相位必须让发生器给同步触发，本波不做）。**钉轨对表的合格判据 = 头位图 ⊇ 实测钉轨路数，且差异必须能由注入条件解释**——因为 `clip_mask` 是按来源派生的链路可信性标记（§6.2 偏移 24 行），不是本段实测值：只加直流或小幅注入时那五路本就不该钉轨，硬取等式会假红。**同段另起一条强观察项**：V0.1 下这五路若在做**交流注入**时反而没钉轨，先怀疑接线或该路根本没被驱动——这是告警面，不是失败面（等式仍作为默认尺子留在 PC 侧 `shape --strict` 里，因为它有这个信号价值；要放行差异用那条判据的解释权，不靠改尺子）。**§5.2 第四条的板级观察项（代码与单测面已有、板级未测）**：bench 连续自抓期间人为把卷占住 2 s 以上（例如同一段跑 FTP 大文件读），看串口 `wave:` 行的 `err` 是否加一、是否只出现**一条** `[ERR] … seg drop: ring abandoned` 留痕（不是每拍刷屏）、且段号不推进（下一段仍写同号文件） |
 | UI | `ui-verify` 五步；回放页入 `ui-golden` 黄金参考（**参考图一旦入库只能改代码对齐，禁止刷参考掩盖**）；新叶走 `gen_menu.py` 重生成 + 字库链 |
 | 构建 | `@build` 要求 0 错误 0 警告；新 .c 双端注册走 `new-source-file`（`MDK-ARM/STM32F407-Demo.uvprojx` 与 `simulator/CMakeLists.txt` 两处显式列表） |
 | 台账 | R6 三处同步 + `scripts/ram_baseline.py --update` + `mem-numbers` 与 `mem-budget` 钩子 |
+| 板级（读路径耗时，2026-10-29 补） | 进回放页后**连续切段 + 连续切道**，读 `task_prof` 里 uiTask 的单轮工作耗时峰值与 800 ms 窗的余量；**不要为此新加埋点**（现成读数够用）。判读：峰值贴着窗走就是读路径该再加节流（先想缓存与分次，别去动心跳窗） |
 | 图与生成物 | 本设计文档的配图生成器受 `generated-fresh` 逐字节幂等约束；脚本与产物同一笔提交 |

 **bench 定时自抓的红线**：定周期自抓在 1 kHz / 8 路下每 2 s 一段，每 5 分钟就是一轮 NAND 写。**长时间挂着它白烧写次数**，而 dhara 的坏块记账是持久代价、普通恢复清不掉（`AGENTS.md` 测试构建节，`docs/测试说明/存储维护与容量恢复.md`）→ 定时模式必须**默认关闭 + 有时长上限 + 启动时打一次告警**，用完立刻回产品构建。
@@ -300,6 +348,7 @@ flowchart TD
 | 削顶五路被读成「系统有零序 / 有谐波」 | 现场误判 | 头里 `clip_mask` + 页面「削」徽标 + 空态不许画直线（§8.1） |
 | 有人把 U 与 I 两段叠图比相位 | 得出**没有物理意义**的相位差 | 回放不做多路叠加；头里写明来源转换器；与 `docs/任务规划/数据可信.md` §9 的 V0.1 禁止行同源 |
 | 落盘把 defaultTask 拖住 | 日志与配置引擎变慢（defaultTask 是两者唯一写者） | 分次写（256 B 双缓冲）、一次心跳最多一段、`f_write` 前后有耗时观测；不做整段驻留再写 |
+| **回放读路径把 uiTask 拖住**（2026-10-29 lead 评审补，此前风险表只有写侧没有读侧） | 一次渲染的实码 I/O（`App/task/ui_task.c` 376 到 398 行）：段表刷新 1 次 `f_opendir` + 至多 100 次 `f_readdir`；未缓存段的段头装载 = 1 次 `f_open` + 1 次 128 B 头读 + **20 次 256 B 数据区读并边读边算数据 CRC** + 尾 2 B 一次 = **最坏 22 次小读**；已验过则只剩窗装载 = 1 次 `f_open` + 1 次 `f_lseek` + 1 次 80 B 窗读 + 40 点解码与峰值扫描（**一屏只碰一路通道一个窗，不是 8 路 320 点**）。uiTask 在 IWDG `required_mask` 内、窗 800 ms（口径同 `docs/子系统设计/看门狗设计说明.md` §11.3 的解耦心跳）→ **现象先是 LVGL 停摆与远程推流缺席，不是复位**（心跳与画屏解耦） | 卷锁 try 非阻塞（拿不到就显示「存储忙」，不等）+ 256 B 分次读 + 已验段结果缓存（同段同道不重复验）+ 只在首次进页 / 切段 / 切道时读。**单轮耗时上界未实测**：不新加埋点，用现成的 `task_prof` 读数（板级动作见 §10） |
 | 触发风暴 + 轮转覆盖 | 现场唯一一段有效波形被后到的抖动冲掉 | 冷却期 + `ovf` 计数；「最新段号」进快照；分段优先级属二期 |
 | 定时自抓忘关 | 白烧 NAND 写次数（持久代价） | 默认关 + 上限 + 告警（§10 红线） |
 | 标定落地后老文件被解释错 | 同一个系数字段值变了含义漂移 | 头里存**封存瞬间**的 `eng` 与系数快照；PC 脚本按头解释，绝不按当前固件口径解释 |