STM32F4-Base/App/algo/README.md

App/algo/ — 采集与算法层（语义取数与有效性 / 全周傅氏相量 / 保护判据）

本目录的索引：文件清单、依赖、逐文件的"改代码必须知道"、构建与测试入口、新增模块动作。 详细设计——机制、契约、判据、为什么这样设计 → docs/算法/采集与算法层设计说明.md（本文不复制其内容）。 分层归属与功能项状态 → docs/算法/继电保护功能复现规划.md §2.1； 通道映射唯一权威 → docs/硬件平台/ADC通道映射说明.md；采样节拍 → docs/子系统设计/ADC采样节拍设计说明.md。

1. 文件清单（一眼版）

文件	层	作用（一句话）	主要对外入口	覆盖规划项
adc_input.h / .c	语义取数与有效性	统一语义取数：两片转换器的码值按语义（UA…IN / 温度）暴露，并消费 STM32 ADC1 的 DMA 乒乓缓冲	adc_input_init() adc_input_poll() adc_input_raw()	TPAFE 快照消费 / STM32 ADC1 启动与扫描 / 通道语义映射
adc_health.h / .c	语义取数与有效性	采样有效性判定：吃计数快照，产出静默 / 丢帧 / 单调性 / 错误增量故障位（判定与告警编排分离）；「采样通道自检」残余的码值贴轨观察器同层	adc_health_check() adc_health_flags() adc_health_rail_watch()	「采样有效性校验」/「采样通道自检」（残余）
adc_cal.h / .c	标定折算	通道标定折算（「数据可信」标定折算与落盘整定）：工程量 =(code+b)×k，Q16 系数/零点两段落盘 + 三态 flags + 合法带哨兵 + 两点公式	adc_cal_apply() adc_cal_flags() adc_cal_set()	「通道标定（一次系数 + 零漂）」（M4 半边）
meas.h / .c	全周傅氏相量发布	遥测快照（「数据可信」遥测快照发布，M5 地基）：200 ms 基波有效值 + 品质快照，双区无锁读，全仓唯一发布者 = adcTask	meas_tick() meas_get() meas_seq()	M5（104 改读快照与频率点绑定、UI 是读者）
sample_ring.h / .c	全周傅氏相量输入	按语义通道存最近 2 周波（40 点），供相量层"以当前时刻为终止"取窗	sample_ring_push_frame() sample_ring_window()	全周傅氏相量输入（为「每 1 ms 滑动窗刷新」供数）
phasor.h / .c	全周傅氏相量	全周傅氏：一周波 20 点 DFT → 基波 / 谐波相量（有效值口径），双区原子切换供无锁读	phasor_run() phasor_get() phasor_calc()	全周傅氏系数表 / 基波相量实例 / 相量有效值输出 / 每 1 ms 滑动窗刷新 / 双区指针原子交换
freq.h / .c	全周傅氏相量的派生量	频率测量：相邻两拍基波相量共轭乘积取角 + 自适应窗滑动平均 + 假值钳制 + 幅值门（UA→IA 源回退）	freq_run() freq_get() freq_valid()	「过频 / 低频」测量侧（测频范围 → docs/算法/继电保护功能复现规划.md §4.2）
prot_set.h / .c	保护判据输入	保护定值模型：Q10 定点 RAM 表 + 范围校验 + 校验和封存 / 自检 / 闭锁 + 持久化 blob 纯逻辑	prot_set_load_raw() prot_set_get_f() prot_set_selfcheck()	「定值校验和」载体
prot_elm.h / .c	保护判据	保护元件框架：通用"越限 + 返回系数滞回 + 定时限"核 + 数据驱动实例表（过流三段 / 过负荷 / 过压 / 欠压 / 零序过压 / 过频 / 低频）	prot_elm_run() prot_elm_eval() prot_elm_active_mask()	「三段式相间过流」/「过负荷」/「过压 / 欠压」/「过频 / 低频」/「零序过压」（软件侧）
wave_ring.h / .c	故障录波数据面	录波环与冻结状态机：int16 × 320 点 × 8 路按通道分列，触发即冻结写指针、后触发计满 160 点封段、落盘回执才解冻、冷却期只加溢出计数	wave_ring_push() wave_ring_tick() wave_ring_request() wave_ring_sealed() wave_ring_read_ch()	「故障录波」数据面（环 + 触发冻结语义）
wave_store.h / .c	故障录波段格式	段文件字节层的编解码与分次搬运游标：段头 + 通道表 + 两处 CRC-16/MODBUS + 段名轮转与反解 + 整段自检；不碰文件系统	wave_store_crc() wave_store_head_build() wave_store_head_parse() wave_store_seg_check() wave_store_pack_next() wave_store_seg_path()	「故障录波」段格式（布局 + 自检）

依赖（自下而上、无环）：adc_input.h（纯枚举 + 声明）← adc_cal（另依赖 cfg_file.h 接口， 纯头文件级）← sample_ring ← phasor ← freq；meas ← sample_ring + phasor （仅 phasor_calc 纯核；频率/品质由调用方注入，不链 freq/adc_cal）； prot_set 独立；prot_elm ← prot_set + phasor + freq。 wave_store 独立（只用 stdint.h 与 stddef.h，编码与解码共用同一个字段校验函数）；wave_ring ← wave_store（只取段头类型与返回码；不链 adc_cal——封存瞬间的系数由 adcTask 现取现填后交棒，本层不复制第二个事实源）。两份录波文件同样零平台依赖、不碰文件系统。 adc_health 只吃调用方喂进来的计数 / 码值，不反向依赖 语义取数与有效性实现（「采样通道自检」贴轨门限由调用方 从 adc_cal_rail_ths() 取，本层仍零算法依赖）。

除 adc_input.c 外全部零平台依赖（只用 stdint.h / math.h / stddef.h 与本目录头） → 可被主机单测 #include 原样纳入、免桩跑。adc_input.c 另依赖 adc.h（hadc1）与 tpafe5160.h（快照），主机侧以桩头替身。

2. 一拍的数据流（一眼版）

adc_input_poll() → adc_input_raw() ×9 → adc_cal_apply() ×9（标定折算折算，现口径 = ADC 引脚电压 V）+ adc_health_rail_watch() ×9（「采样通道自检」，码值域）→ sample_ring_push_frame() → phasor_run() → freq_run() → 消费者（adcTask 心跳与 语义取数与有效性健康判定；protectTask 每 20 ms 取相量 / 频率跑 prot_elm_run()；每 200 ms meas_tick() 发布遥测快照供 iec104Task / uiTask 读，即「数据可信」遥测快照发布）。节拍 = TIM3 1 kHz 更新事件，两片转换器同源触发。 完整数据流图与初始化落点 → docs/算法/采集与算法层设计说明.md §2。

录波支路（与上面这条相量主线并行、同拍只多走两步，互不阻塞）：adc_input_raw() 取 8 路 → wave_ring_push() → wave_ring_tick()（触发即冻结写指针，后触发计满 160 点封段）→ defaultTask 只见 wave_ring_sealed() 与已封存区读口 → 游标分次搬运落盘 → wave_ring_write_done() 才解冻。 → docs/子系统设计/故障录波设计说明.md §4.2 与 §5.1。

3. 逐文件要点（只留"改代码时必须知道"的；机制与理由见设计文档）

改本目录前先记五条红线：① 取数只经 adc_input_raw()，不写死下标；② 禁止跨转换器做 相位 / 功率 / 矢量运算（双转换器无共同采样触发）；③ 帧值已是 标定折算工程量，但 未标定（adc_cal_flags() 无 VALID）时单位只是 ADC 引脚电压，不是端子二次值——下游消费精度判据见「数据可信」§4.2 三态 表；④ 工程量 → 帧的唯一折算点是 adc_cal_apply()，禁止旁路再乘系数；⑤ 本层不建任务、 不等事件、不写日志（adc_cal 的 [ERR] 哨兵留痕是唯一例外，且每通道每开机一次）， *_init() 才可在内核前调。 全文 → docs/算法/采集与算法层设计说明.md §10。

3.1 adc_input.c / adc_input.h — 语义取数与有效性语义取数

• 语义映射表 k_adc_map[] 的内容唯一权威是 docs/硬件平台/ADC通道映射说明.md；V0.2 改版只改表内容，API 不动。
• adc_input_poll() 仅任务上下文（TPAFE 快照是临界区）；STM32 侧固定滞后 1 拍。
• 四类 STM32 计数（adc1_seq / adc1_gap / adc1_err / adc1_hw）成因不同，勿混读。
• 本目录唯一允许出现 HAL 调用的文件。→ docs/算法/采集与算法层设计说明.md §3。

3.2 sample_ring.c / .h — 全周傅氏相量输入采样环

• 整帧写入后才推进写指针 → 取到的窗永远落在整帧边界。
• 本拍取数失败 → 整拍跳过入环（adc_task.c 的 skip），绝不补 0 点。
• 不做跨通道运算、不做丢帧判定（只出 frames() 计数）。→ docs/算法/采集与算法层设计说明.md §5。

3.3 phasor.c / .h — 全周傅氏相量计算

• 系数表预乘 √2/N → fAmSQ 直接是有效值（口径 docs/算法/傅氏算法详解.md §2.3）。
• 实例表 k_inst[] 数据驱动：新增实例只在表尾加一行。
• 任一实例不足一周波 → 本拍整体不产出（不切使用区）；每拍 20 点全部重算（不做增量递推）。
• → docs/算法/采集与算法层设计说明.md §6。

3.4 adc_health.c / .h — 语义取数与有效性判定

• 三类位严格分开：电平（可自愈）/ 锁存（必留痕）/ 边沿事件（仅当拍）；静默 ≠ 丢帧。
• gap 不告警（消费者超拍是已知现象）；告警编排在 adc_task.c，不在本层。
• 首拍 check() 只建基线。→ docs/算法/采集与算法层设计说明.md §4。

3.5 prot_set.c / .h — 保护定值模型（「定值校验和」载体）

• 装载 all-or-nothing：任一项越界整表不装载，越界项由 prot_set_bad_mask() 指认。
• 批量 prot_set_set() 后必须 prot_set_seal()；单项原子写用 prot_set_set_sealed()。
• 定值项 / 实例只许尾部追加（枚举序 = 数组序 = 校验和覆盖序）。
• blob 换代（返回 2）≠ 损坏（返回负）：前者打 INFO、不记自检。→ docs/算法/采集与算法层设计说明.md §8、§12.3。

3.6 prot_elm.c / .h — 保护判据元件框架

• 数据缺失两种处理刻意不同：相量类任一未就绪 → 整拍跳过；频率类无有效读数 → 按方向填"必不启动"值，不整拍跳过。
• prot_set_locked() 或投退 = 0 → 元件整体复位不判据；跨上下文复归走 prot_elm_request_reset()。
• 零序过流（IN 走 STM32）故意不在实例表；OF / UF 无独立 104 遥信点，只经 YX15 总聚合可见。
• prot_elm_init() 须在 phasor_init() 之后。→ docs/算法/采集与算法层设计说明.md §9。

3.7 freq.c / .h — 频率测量（「过频 / 低频」的测量输入）

• freq_run() 仅 adcTask 上下文，须在 phasor_run() 之后同拍调；保护口径 = freq_get() == 0 && freq_valid() == 1。
• 精度靠自适应窗长（窗长 = 泄漏纹波周期的整数倍）；定长平均压不到 0.02 Hz， 换窗长 = 换精度，二者不是独立旋钮。
• 源切换即废相位基准重建（UA / IA 无共同相位基准，即双转换器无共同采样触发）。
• 判据 J1~J6 与实测口径 → docs/算法/采集与算法层设计说明.md §7.2（与 test/host/freq/freq_test.c 文件头同源）。

3.8 adc_cal.c / .h — 标定折算通道标定折算（「数据可信」标定折算与落盘整定）

• 折算模型：工程量 = (code + b) × k；k 落盘用 int32 Q16（µV/码 × 65536）、b 用 int32 码值（负零点靠 CFG_VAL_INT）——单位与定点格式的选型依据见 docs/任务规划/数据可信.md §4.1，勿改回 V/码 直存（Q16 只剩 20 个刻度）。
• ROM 默认 = 量程口径冻结定死的引脚侧 LSB（TPAFE 152.59 / STM32 805.66 µV/码， docs/硬件平台/ADC通道映射说明.md §7.1）；表下标 = 语义枚举（UA0…IN7）， V0.2 改版与本目录 adc_input 映射表同步改。
• 三态可用性 adc_cal_flags()：VALID（已按变比标定，二次值成立——端子变比确认与两点标定前恒 0） / CLIPPED（运行期按来源派生，V0.2 后自动清零）。消费者判「能不能信」只许查它， adc_cal_apply() 不返回可用性（「数据可信」§8 风险表）。
• 合法带哨兵：k ∉ ROM×[0.5,2.0] 或 |b| > 8192 → 折算回退 ROM + 每通道每开机一条 [ERR] + VALID 被压制（即便文件位图说已标定）；这层兜底同时挡坏文件与坏标定。
• adc_cal_set() / adc_cal_two_point()：整定与两点公式的算术核已齐备（单测还原合成 k/b）；台架两点标定待实测，本层不含注入。
• cfg 两段 [adc_cal] / [adc_cal_ofs] 不挂回调（RAM 副本即生效值，引擎 load/poll 原地改写，逐点现读）；注册在 app_main_init() 内核前完成，必须先于 cfg_file_load。

3.9 meas.c / .h — 遥测快照发布（全周傅氏相量发布侧，「数据可信」波次）

• 唯一发布者 = adcTask：phasor_run()/freq_run() 同拍、200 ms tick 经过分频 调 meas_tick()（非拍计数——idle/skip 拍拉长名义节拍）。docs/任务规划/数据可信.md §8 风险表"快照双写"行 = 评审判据：全仓 meas_tick 调用点数须为 1；iec104Task / uiTask 只读。
• 值口径（批 2「遥测快照发布」的 A-lite 裁决）：基波有效值瞬时透传，与 phasor 使用区 同拍同核逐位相等（单测钉死）；不做 4 点平均 / 谐波方和根——按 docs/任务规划/数据可信.md §4.5"上送节拍非平均窗，再平均引入滞后"；谐波 k-bin 轨 （docs/算法/继电保护功能复现规划.md 「遥测谐波轨（可选）」）扩展只许结构尾部追加， docs/任务规划/数据可信.md §4.5 字段序 = 协议（布局由单测按偏移钉死，72 B × 双区）。
• 并发 = phasor 双区 + 单字节索引翻转（「双区指针原子交换」同型，无锁）；seq 只增供消费者判换帧。
• 品质注入：削顶位图唯一源 = adc_cal_flags()（口径 docs/任务规划/数据可信.md §4.2 三态表；由 adc_task 编排注入，本层不链 adc_cal）；TEMP = 最新一拍原始值透传 + NT（「数据可信」决策 5）；MEAS_QDS_* 低字节与 104 QDS 线上字节同值 （本层不 include 协议层头——分层方向）。
• 104 死区迁移 / 频率点绑定 = 104 改读快照那一波（道D 后续分支）；读数与注入源比对 = 待台架实测。

3.10 wave_ring.c / wave_ring.h — 录波环与冻结状态机（「故障录波」数据面）

• 形态三条钉死（动它之前读 docs/子系统设计/故障录波设计说明.md §6.2 与 §7）：只存 int16 原始码值（不做折算、不许 float）、按通道分列（不按帧交错——回放与搬运都是整列取）、 ch_count 固定 8（TEMP 本波不录：未折算的非线性量进录波只多占字节不增信息）。环本体 5120 B， 本层全部可写静态 5298 B，落 SRAM1（scatter 的 RW_IRAM1 收 .ANY (+RW +ZI)，代码里没有 任何 section 属性；CCM 只放 FreeRTOS 堆，那 5 KB 既塞不进也不该塞）。
• 冻结 ≠ 停采集：触发冻住的是覆盖窗口（写指针停走），丢的只是录波样本，drop_cnt 的单位是 「点」（一拍 8 路 = 8 点）；sample_ring / 相量 / 保护在同拍照常跑，本层不碰它们。
• 点序：触发那一拍的样本落在段内点 159（预触发窗最后一点），点 160 起是触发后第一拍，两半 各 160 点、不重叠；回放页横轴与 PC 脚本都按这条对齐（设计说明未钉死 ±1，本层按不重叠实现）。
• 封存握手（顺序不许换，单测逐拍钉死）：wave_ring_tick() 计满那一拍返回 WAVE_RING_EVT_SEALED → adcTask 才去取标定事实并 wave_ring_latch_meta() → wave_ring_sealed() 要求「状态 SEALED 且已 latch」才返 1（两个标志并成一个，落盘道不可能拿半份快照落盘）→ defaultTask 只读锁副本 → wave_ring_write_done(0 / 非 0) 是唯一解冻入口：成功才推进轮转号与段 计数，失败只计 err 且保持同号（下一段重写同一个文件，盘上不留半截）。
• 两条不许把环焊死的兜底：SEALED 滞留超过 WAVE_SEAL_TIMEOUT_MS（2000 拍，待台架核）自弃本段 并计 err；冷却窗 WAVE_RING_COOL_MS（500 拍，待台架核）只在回执之后计时——「落完解冻」用的是 状态不是时间，回执前任何新触发只加 ovf_cnt 不重录。
• 上下文归属直接长在函数命名上（跨任务安全不靠约定）：wave_ring_init / push / tick / latch_meta 只能在 adcTask（⚠ 严禁挂到 TIM3 回调：那是 ISR 且比调度器早约 100 ms，本层没有 消费者就绪门）；wave_ring_write_done 只能在 defaultTask；request / state / sealed / sealed_meta / read_ch / read_cb / get_stat / col 任意上下文可调。本层不提供任何读活 缓冲的口子（docs/子系统设计/故障录波设计说明.md §5.2 第一条陷阱：sample_ring_window() 无临界区，本波不复用）。
• seg_idx 只是本次上电的本地计数；盘上的下一个写号归落盘道自持（开机扫目录用 wave_store_idx_from_name() 重建、写成功后 wave_store_next_idx() 推进）。

3.11 wave_store.c / wave_store.h — 段文件字节层（「故障录波」段格式）

• 只做字节：文件落点、路径拼法、标定系数、数据本体全部由调用方注入（meta 由 adcTask 填、 数据经 wave_reader_fn 回调取、路径由落盘道拼）→ 两份文件零平台依赖，主机单测免桩 #include 原样纳入；wave_store_meta_init() 只填格式侧静态事实（并把通道表 sem 钉成下标、按归属填 conv / bits），avail / k_q16 / b_codes 一律留 0 等封存瞬间现取现填——不复制第二个事实源。
• 尺寸等式（单测钉死，落盘道拿它比对写回字节数）：整段 = 32 + 12×通道数 + 2×点数×通道数 + 2； 当前口径（8 路 320 点）= 头 128 + 数据 5120 + 尾 CRC 2 = 5250 字节（这条等式是给落盘道比对写回 字节数用的）：FatFs 该移植在簇分配失败时会返回 FR_OK + 短写且无错误码，判成功必须校验字节数 （故障录波设计说明「四条已知陷阱」第二条）。
• CRC-16/MODBUS 自带无表实现（反射多项式 0xA001、初值 0xFFFF、异或输出 0，自检锚点字符串 "123456789" = 0x4B37）。设计说明 §6.2 原写「与屏板链路同一张表」经全仓实测不成立（这张表不 存在：crc.c 与 crc.h 已于 2026-10-02 删除，屏板侧 remo_crc() 是单字节异或）——文档等文档道回改， 代码不擅自改口径，也不再新造第三张表。
• 编解码同一把尺：wave_store_head_build() 与 wave_store_head_parse() 走同一个字段校验函数， 判据与 PC 侧读段脚本的拒绝清单逐条对齐（零长度、每周波点数不足 2、每通道点数不够一周波、 预触发点数超段长、通道表项语义号不等于下标、版本号与魔数第三字节不一致）——防的就是「板端 写得出、PC 读不了」。反过来不设任何品质侧不变式：avail 同时带有效与削顶是合法事实 （lead 裁定 2026-10-29），编码器如实透传、解码器不许据此判废。
• 游标分次搬运（256 B 缓冲够用，整段绝不驻留 RAM；数据 CRC 走增量中间值）： wave_store_pack_next() 头那一步要求缓冲容量不小于整头 128，否则返 WAVE_ST_E_PARAM 且不推进 游标；没有数据源却进数据区 → WAVE_ST_E_STATE 且不产空字节（产空字节等于写出「长度对、 内容全 0」的段 = docs/子系统设计/故障录波设计说明.md §8.1 明令禁止的伪造证据）。
• 段名严格 8.3（该移植 FF_USE_LFN=0）：wave_store_seg_path() 当前布局恒返回 16 个字符（不含结束 符），调用方缓冲至少 17 字节（WAVE_ST_PATH_MAX，原写 16 会让结束符写到缓冲外一字节）； 100 个号轮转，wave_store_next_idx() 回绕，wave_store_idx_from_name() 只认 basename 上的段名。
• wave_store_head_build() / wave_ring_read_ch() 这类函数成功时返回实际字节数 / 点数（不是 WAVE_ST_OK），负值才是错误码——写断言前先读头文件的「返 回 值」行（本层单测两次踩在这上面）。

4. 构建与测试

4.1 挂载与模拟器边界

• 十一个 .c 已登记在 MDK-ARM/STM32F407-Demo.uvprojx；../App/algo 已在 <IncludePath> 内。
• 模拟器侧分两类（Lead 裁定 2026-10-29）：wave_ring.c 与 wave_store.c 真实参与 simulator/CMakeLists.txt——回放页要在模拟器里出真波形，两份又零平台依赖，与「双端共享核心、不造 第二真相」同一条口径，故不进 SIM_EXEMPT；其余九个采集链文件（UI 模拟器不跑采集链路）仍登记在 scripts/check_registration.py 的 SIM_EXEMPT（附理由），registration-check 钩子反向校验（登记簿条目「rs485_task 白名单缺口」）。

4.2 主机侧纯逻辑单测——生产源文件以 #include 原样纳入

模块	命令	pre-commit 钩子
相量 / 采样环	& '.venv\Scripts\python.exe' test/host/phasor/run_unit_test.py	phasor-unit-test
ADC 输入层	& '.venv\Scripts\python.exe' test/host/adc_input/run_unit_test.py	adc-input-unit-test
有效性校验	& '.venv\Scripts\python.exe' test/host/adc_health/run_unit_test.py	adc-health-unit-test
定值模型	& '.venv\Scripts\python.exe' test/host/prot_set/run_unit_test.py	prot-set-unit-test
元件框架	& '.venv\Scripts\python.exe' test/host/prot_elm/run_unit_test.py	prot-elm-unit-test
频率测量	& '.venv\Scripts\python.exe' test/host/freq/run_unit_test.py	freq-unit-test
通道标定（含真实 cfg_file 引擎集成）	& '.venv\Scripts\python.exe' test/host/adc_cal/run_unit_test.py	adc-cal-unit-test
遥测快照（布局钉死/双区无撕裂/品质汇总）	& '.venv\Scripts\python.exe' test/host/meas/run_unit_test.py	meas-unit-test
录波环（几何与点序 / 冻结与丢样 / 封存握手 / 读窗夹取 / 自弃与冷却）	& '.venv\Scripts\python.exe' test/host/wave_ring/run_unit_test.py	无专属钩子：靠 test-coverage 总闸真跑
录波段格式（尺寸等式 / CRC 锚点 / 编解码往返与拒绝清单 / 搬运游标 / 段名轮转）	& '.venv\Scripts\python.exe' test/host/wave_store/run_unit_test.py	同上
录波触发与全链路（三条来路 / 同拍多请求 / 已封存区不变 / 字节逐列对环）	& '.venv\Scripts\python.exe' test/host/wave_trig/run_unit_test.py	同上

改本目录任一 .c/.h，提交时对应钩子自动跑。用例清单与判据数字的属主是各 test/host/<模块>/ 与 docs/测试说明/ 下的单测说明，本文不复制（三处抄数字必然打架）。

录波三套刻意不新增专属钩子（Lead 裁定 2026-10-27：钩子口径冻结，新增套数由 test-coverage 总闸全量真跑并守基线回退，失败照样拦，只是归因落在总闸输出上）。两套录波单测之间刻意留了 一份分工：环那套管语义、段格式那套管字节、wave_trig 管「接起来之后的语义」（含把封存区 逐列读出来与打包游标产出的字节逐字节对齐）。两套合成段落在临时目录并把绝对路径打进日志（日志里 同时标明是哪一份形态），要跟 PC 侧读段脚本互验时把当次产物拷进 ci-artifacts/wave_interop/ 再报 路径——别拿旧副本当本次产物（踩过：拷过一次之后没刷，别人读到的是上一轮的字节）。

4.3 板端

/keil-build 0 错误 0 警告 → /serial-boot-test 看 [ADC_TASK] 首拍 / 心跳（phasor(...)、freq(...)、 cal: ua_mv=… vl=0x00 cl=0xE6 rail=…、ring / skip / adc1_* / tgap）； 健康判据 = 零 [ERR]（健康告警与标定哨兵全以 [ERR] 开头，误报会被闭环直接抓住； vl 在未标定默认构建必须为 0x00，未标定即闭锁落地后 cal: 行就是台架期望的直接证据）。 → docs/算法/采集与算法层设计说明.md §12。

5. 新增一个算法模块的固定动作

1. 在本目录建 xxx.c/h，文件头写模块注释块（规范 V1.0），尽量零平台依赖以便免桩单测。 需要 NULL 的 .c 自己 #include 一个 stddef.h：ARMCC 的 stdint.h 不提供 NULL，而主机侧 MSVC / gcc 会传递性把它拉进来，主机单测照不出这个分叉（2026-10-29 台基线构建实测报 22 条 identifier "NULL" 未定义，根因即此；与 sample_ring.c / freq.c 同口径，别塞进公共头）。
2. 用 new-source-file skill 注册到 MDK-ARM/STM32F407-Demo.uvprojx（新建子目录还要补 <IncludePath>）。 模拟器侧二选一：有消费路径 → 加 simulator/CMakeLists.txt；纯算法无消费路径 → 加 scripts/check_registration.py 的 SIM_EXEMPT（照本目录既有七条写理由），否则 registration-check 拦。
3. 加 test/host/<模块>/ 主机单测（照 test/host/meas 或 test/host/soe_store 抄目录形态与 run_unit_test.py）。要不要补 .pre-commit-config.yaml 专属钩子按 Lead 裁定 2026-10-27：默认不补， 由 test-coverage 总闸全量真跑；确有秒级归因需求再单独申请。用例标题写「它在验证什么」这类语义 短语，不要发字母紧跟数字的新编号（docs/编号规范.md §4.1「已停发」栏：停发不等于可以新发）。
4. 消费者写在 App/task/，本层只出"数"；跨转换器禁令见 §3 开头四条红线。
5. 在本 README §1 清单加一行，并在 docs/算法/采集与算法层设计说明.md 里写清该模块的契约与理由。
6. 单测产出的互验字节（要被别人的脚本读的那些）：跑测之后立刻刷新副本并记下 sha256。三套录波单测把合成段落 在临时目录、并把绝对路径 + 是哪一份形态打进日志，所以「跑完顺手拷一次、以后再没刷」必然留下旧副本—— 本仓这类坑不止一次（旧副本被当本次证据引用过：一次是别人拿上一轮的字节下了「字节级已闭合」的结论）。 判据：引用方只认当次运行日志里那条路径 + 当次 sha256；产物有第二种形态（例如本波真值形态与「已标定后 仍削顶」的构造形态）就在文件名或日志里把形态写明，别让读者靠猜；拷进 ci-artifacts/wave_interop/ 之类的 共享目录时，同一笔操作里就把新 sha 一起报给对岸，别隔一轮。

6. 相关文档

• 本层设计与判据：docs/算法/采集与算法层设计说明.md
• 通道映射权威口径：docs/硬件平台/ADC通道映射说明.md
• 分层与功能项清单：docs/算法/继电保护功能复现规划.md
• 傅氏算法与有效值口径：docs/算法/傅氏算法详解.md
• 采样节拍（TIM3 1 kHz + TRGO 触发 ADC1 / DMA）：docs/子系统设计/ADC采样节拍设计说明.md
• 故障录波（数据面 / 段格式 / 现场回放契约）：docs/子系统设计/故障录波设计说明.md §6.2 是段文件 字节布局的属主，同一篇的 docs/子系统设计/故障录波设计说明.md §6.3 是字段口径裁定——两节合起来是板端 编码器与 PC 读段脚本两份独立实现的共同依据；卡片判据与顺序 → docs/任务规划/故障录波.md §2
• 相量层 / ADC 输入层单测细则：docs/测试说明/单元测试/相量层单元测试说明.md、docs/测试说明/单元测试/ADC输入层单元测试说明.md
• RAM 与栈台账：docs/内存管理/RAM使用分析与优化方案.md