wandering1
77779d49d6
UI 面：ui_data 增加深度 4 参数写队列（请求 168 B、队列 .bss 672 B）与状态机 OK/ERR_RANGE/ERR_LOCKED/ERR_BUSY，ui_data_feed 出队后按注入 ops 走「闭锁 → 整批 预检 → 逐项 prot_set_set_sealed」，只提交改动位图；par 帧尾追加 cal_block （口径 = UA/UN/IA 三路 ADC_CAL_F_VALID，与 protect_task 判据同构，不用 rt.eng 反推，V0.1 下 eng 恒 0）、UI_DATA_VER 升到 2。参数/定值/控制字/软压板四叶绑定 内容页（UI_PAGE_MAP_COUNT 12→16，复用四个查看模块，零新增 .c），编辑态按 is_editable 分派，LOCK（写不进去）与「未标定」（仍可改值）两源两通道两词。 记录面：syslog_request_clear/state/apply 三段式删除 API（UI 只发请求，落地在 defaultTask 的 drain 尾部且必须后置，卷锁一律 try，幂等只认 FR_NO_FILE）； 事故/告警/启动/操作/遥控五类各有一个真实写入点，记录类型 = 日志 ID 本身 （一类一个 /log 严格 8.3 文件；64B 定长体没有类型字段位，塞字段会砸掉既有读者）。 为守 protectTask 872 B 静态最坏链另拆 syslog_post_quiet()（无 DBG 的投递核， 丢弃留痕挪到 drain 侧差值补发），syslog_post 对外语义逐字不变。 为什么两道合成一笔而不是各一笔（实测，不是省事）：simulator/main.c 同时消费 两道新增 API（整定 pump 与 logtest 清除用例），按道切文件会让中间提交编不过； RAM 受管快照与体积同码凭证描述的是合并后的 .map，拆开必落在「台账与 .map 不同 码」这条红线上。pre-commit 跑钩子前会 stash 未 staged 部分，这类耦合没法绕。 实测：@build 0 错误 0 警告；Code 228,260 / RO 24,960 / RW 1,440 / ZI 135,976 B； RW_IRAM1 79,992 B = 61.0%、RW_CCM 87.9%（阈值 92%）；九个任务静态最坏链全 PASS， protectTask 872 B / 57% 改前后逐字节不变（记录投递没垫栈）。主机单测 ui_data 82→ 164、sys_log_mcu 106→137、prot_elm 47→60、iec104 141→154、iec104_serv 28→34， 既有断言零删改；48 个钩子 --all-files 全绿；编号门禁可判定 86.34%（基线 86.0%）、 不可判定 1,153 处低于上限 1,166；doc-links 无法判定 0；UI 黄金 18 页扩到 27 页 连跑两次逐字节一致；字库 diff 空。 顺手修掉三处既有缺陷（都是本轮第一个消费者才暴露）：sim_syslog.c 的 s_paths 行宽 16 而 "sim_selftest.log" 正好 16 字符没有 NUL 位（stat/remove 读越过数组尾，此前 靠后面 .rodata 碰巧为 0）；ui_w_setlist 二态行 ENTER 不回绕（控制字与软压板出厂值 全在最后一项，按了像没反应而叠层里已是越界值）；生成物 ui_menu_tab.h 与 gen_menu.py 模板漂移（上一笔改了模板没重跑生成器），现随生成器输出对齐。 未收口（不算完成）：保存后重启值保持与主站 C_RD 读回两条只能上板，台架窗口执行； LOCK 屏显与越界反显的页面侧在模拟器造不出来（模拟器不跑定值自检、无 NAND）， 已由生成侧单测与代码注释点名差距；同类页数与钩子数陈述残留另立待办。
App/algo/ — 采集与算法层（L1 / L2 / L3）
本目录的索引：文件清单、依赖、逐文件的"改代码必须知道"、构建与测试入口、新增模块动作。 详细设计——机制、契约、判据、为什么这样设计 →
docs/算法/采集与算法层设计说明.md（本文不复制其内容）。 分层归属与功能项状态 →docs/算法/继电保护功能复现规划.md§2.1； 通道映射唯一权威 →docs/硬件平台/ADC通道映射说明.md；采样节拍 →docs/子系统设计/ADC采样节拍设计说明.md。
1. 文件清单（一眼版）
| 文件 | 层 | 作用（一句话） | 主要对外入口 | 覆盖规划项 |
|---|---|---|---|---|
adc_input.h / .c |
L1 | 统一语义取数：两片转换器的码值按语义（UA…IN / 温度）暴露，并消费 STM32 ADC1 的 DMA 乒乓缓冲 |
adc_input_init() adc_input_poll() adc_input_raw() |
L1-2 / L1-3 / L1-4 |
adc_health.h / .c |
L1 | 采样有效性判定：吃计数快照，产出静默 / 丢帧 / 单调性 / 错误增量故障位（判定与告警编排分离）；L5-2 残余的码值贴轨观察器同层 | adc_health_check() adc_health_flags() adc_health_rail_watch() |
L1-6 / L5-2（残余） |
adc_cal.h / .c |
L1.5 | 通道标定折算（「数据可信」卡 2/卡 4）：工程量 =(code+b)×k，Q16 系数/零点两段落盘 + 三态 flags + 合法带哨兵 + 两点公式 | adc_cal_apply() adc_cal_flags() adc_cal_set() |
L1-5（M4 半边） |
meas.h / .c |
L2 发布 | 遥测快照（「数据可信」卡 8，M5 地基）：200 ms 基波有效值 + 品质快照，双区无锁读，全仓唯一发布者 = adcTask | meas_tick() meas_get() meas_seq() |
M5（卡 9/11 与 UI 是读者） |
sample_ring.h / .c |
L2 输入 | 按语义通道存最近 2 周波（40 点），供相量层"以当前时刻为终止"取窗 | sample_ring_push_frame() sample_ring_window() |
L2 输入（为 L2-6 供数） |
phasor.h / .c |
L2 | 全周傅氏：一周波 20 点 DFT → 基波 / 谐波相量（有效值口径），双区原子切换供无锁读 | phasor_run() phasor_get() phasor_calc() |
L2-1 / L2-2 / L2-3 / L2-6 / L2-7 |
freq.h / .c |
L2 派生量 | 频率测量：相邻两拍基波相量共轭乘积取角 + 自适应窗滑动平均 + 假值钳制 + 幅值门（UA→IA 源回退） | freq_run() freq_get() freq_valid() |
L3-5 测量侧（测频范围 → docs/算法/继电保护功能复现规划.md §4.2） |
prot_set.h / .c |
L3 输入 | 保护定值模型：Q10 定点 RAM 表 + 范围校验 + 校验和封存 / 自检 / 闭锁 + 持久化 blob 纯逻辑 | prot_set_load_raw() prot_set_get_f() prot_set_selfcheck() |
L5-1 载体 |
prot_elm.h / .c |
L3 | 保护元件框架：通用"越限 + 返回系数滞回 + 定时限"核 + 数据驱动实例表（过流三段 / 过负荷 / 过压 / 欠压 / 零序过压 / 过频 / 低频） | prot_elm_run() prot_elm_eval() prot_elm_active_mask() |
L3-1 / L3-3 / L3-4 / L3-5 / L3-6（软件侧） |
依赖（自下而上、无环）：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。
adc_health 只吃调用方喂进来的计数 / 码值，不反向依赖 L1 实现（L5-2 贴轨门限由调用方
从 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（L1.5 折算，现口径 =
ADC 引脚电压 V）+ adc_health_rail_watch() ×9（L5-2，码值域）→ sample_ring_push_frame()
→ phasor_run() → freq_run() → 消费者（adcTask 心跳与 L1 健康判定；protectTask 每 20 ms 取相量 / 频率跑
prot_elm_run()；每 200 ms meas_tick() 发布遥测快照供 iec104Task / uiTask 读，卡 8）。节拍 = TIM3 1 kHz 更新事件，两片转换器同源触发。
完整数据流图与初始化落点 → docs/算法/采集与算法层设计说明.md §2。
3. 逐文件要点（只留"改代码时必须知道"的；机制与理由见设计文档）
改本目录前先记五条红线：① 取数只经
adc_input_raw()，不写死下标；② 禁止跨转换器做 相位 / 功率 / 矢量运算（双转换器无共同采样触发）；③ 帧值已是 L1.5 工程量，但 未标定（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 — L1 语义取数
- 语义映射表
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 — L2 输入采样环
- 整帧写入后才推进写指针 → 取到的窗永远落在整帧边界。
- 本拍取数失败 → 整拍跳过入环（
adc_task.c的skip），绝不补 0 点。 - 不做跨通道运算、不做丢帧判定（只出
frames()计数）。→docs/算法/采集与算法层设计说明.md§5。
3.3 phasor.c / .h — L2 相量计算
- 系数表预乘 √2/N →
fAmSQ直接是有效值（口径docs/算法/傅氏算法详解.md§2.3）。 - 实例表
k_inst[]数据驱动：新增实例只在表尾加一行。 - 任一实例不足一周波 → 本拍整体不产出（不切使用区）；每拍 20 点全部重算（不做增量递推）。
- →
docs/算法/采集与算法层设计说明.md§6。
3.4 adc_health.c / .h — L1 有效性判定
- 三类位严格分开：电平（可自愈）/ 锁存（必留痕）/ 边沿事件（仅当拍）；静默 ≠ 丢帧。
- gap 不告警（消费者超拍是已知现象）；告警编排在
adc_task.c，不在本层。 - 首拍
check()只建基线。→docs/算法/采集与算法层设计说明.md§4。
3.5 prot_set.c / .h — 保护定值模型（L5-1 载体）
- 装载 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 — L3 保护元件框架
- 数据缺失两种处理刻意不同：相量类任一未就绪 → 整拍跳过；频率类无有效读数 → 按方向填"必不启动"值，不整拍跳过。
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 — 频率测量（L3-5 的测量输入）
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 — L1.5 通道标定折算（「数据可信」卡 2 / 卡 4）
- 折算模型：工程量 = (code + b) × k；k 落盘用 int32 Q16（µV/码 × 65536）、b 用
int32 码值（负零点靠
CFG_VAL_INT）——单位与定点格式的选型依据见docs/任务规划/数据可信.md§4.1，勿改回 V/码 直存（Q16 只剩 20 个刻度）。 - ROM 默认 = 卡 1 定死的引脚侧 LSB（TPAFE 152.59 / STM32 805.66 µV/码，
docs/硬件平台/ADC通道映射说明.md§7.1）；表下标 = 语义枚举（UA0…IN7）， V0.2 改版与本目录adc_input映射表同步改。 - 三态可用性
adc_cal_flags()：VALID（已按变比标定，二次值成立——卡 0b/12 前恒 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）；台架两点标定（卡 12）待实测，本层不含注入。- cfg 两段
[adc_cal]/[adc_cal_ofs]不挂回调（RAM 副本即生效值，引擎 load/poll 原地改写，逐点现读）；注册在app_main_init()内核前完成，必须先于cfg_file_load。
3.9 meas.c / .h — 遥测快照发布（L2 发布侧，「数据可信」卡 8）
- 唯一发布者 = adcTask：
phasor_run()/freq_run()同拍、200 ms tick 经过分频 调meas_tick()（非拍计数——idle/skip 拍拉长名义节拍）。docs/任务规划/数据可信.md §8 风险表"快照双写"行 = 评审判据：全仓meas_tick调用点数须为 1；iec104Task / uiTask 只读。 - 值口径（批 2 卡 8 A-lite 裁决）：基波有效值瞬时透传，与 phasor 使用区 同拍同核逐位相等（单测钉死）；不做 4 点平均 / 谐波方和根——按 docs/任务规划/数据可信.md §4.5"上送节拍非平均窗，再平均引入滞后"；谐波 k-bin 轨 （docs/算法/继电保护功能复现规划.md L2-8）扩展只许结构尾部追加， docs/任务规划/数据可信.md §4.5 字段序 = 协议（布局由单测按偏移钉死，72 B × 双区）。
- 并发 = phasor 双区 + 单字节索引翻转（L2-7 同型，无锁）；seq 只增供消费者判换帧。
- 品质注入：削顶位图唯一源 =
adc_cal_flags()（口径 docs/任务规划/数据可信.md §4.2 三态表；由 adc_task 编排注入，本层不链adc_cal）；TEMP = 最新一拍原始值透传 +NT（「数据可信」决策 5）；MEAS_QDS_*低字节与 104 QDS 线上字节同值 （本层不 include 协议层头——分层方向）。 - 104 死区迁移 / 频率点绑定 = 卡 9/卡 11（道D 后续分支）；读数与注入源比对 = 待台架实测。
4. 构建与测试
4.1 挂载与模拟器边界
- 九个
.c已登记在MDK-ARM/STM32F407-Demo.uvprojx；../App/algo已在<IncludePath>内。 - 本层不进
simulator/CMakeLists.txt（UI 模拟器不跑采集链路）：九个文件全部登记在scripts/check_registration.py的SIM_EXEMPT（附理由），registration-check钩子反向校验（登记簿条目「rs485_task 白名单缺口」）。
4.2 主机侧单测（L0.5）——生产源文件以 #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 |
改本目录任一 .c/.h，提交时对应钩子自动跑。用例清单与判据数字的属主是各
test/host/<模块>/ 与 docs/测试说明/ 下的单测说明，本文不复制（三处抄数字必然打架）。
4.3 板端
@build 0 错误 0 警告 → @test 看 [ADC_TASK] 首拍 / 心跳（phasor(...)、freq(...)、
cal: ua_mv=… vl=0x00 cl=0xE6 rail=…、ring / skip / adc1_* / tgap）；
健康判据 = 零 [ERR]（健康告警与标定哨兵全以 [ERR] 开头，误报会被闭环直接抓住；
vl 在未标定默认构建必须为 0x00，卡 5 闭锁落地后 cal: 行就是台架期望的直接证据）。
→ docs/算法/采集与算法层设计说明.md §12。
5. 新增一个算法模块的固定动作
- 在本目录建
xxx.c/h，文件头写模块注释块（规范 V1.0），尽量零平台依赖以便免桩单测。 - 用
new-source-fileskill 注册到MDK-ARM/STM32F407-Demo.uvprojx（新建子目录还要补<IncludePath>）。 模拟器侧二选一：有消费路径 → 加simulator/CMakeLists.txt；纯算法无消费路径 → 加scripts/check_registration.py的SIM_EXEMPT（照本目录既有七条写理由），否则registration-check拦。 - 加
test/host/<模块>/主机单测 +.pre-commit-config.yaml钩子（照phasor-unit-test抄）。 - 消费者写在
App/task/，本层只出"数"；跨转换器禁令见 §3 开头四条红线。 - 在本 README §1 清单加一行，并在
docs/算法/采集与算法层设计说明.md里写清该模块的契约与理由。
6. 相关文档
- 本层设计与判据：
docs/算法/采集与算法层设计说明.md - 通道映射权威口径：
docs/硬件平台/ADC通道映射说明.md - 分层与功能项清单：
docs/算法/继电保护功能复现规划.md - 傅氏算法与有效值口径：
docs/算法/傅氏算法详解.md - 采样节拍（TIM3 1 kHz + TRGO 触发 ADC1 / DMA）：
docs/子系统设计/ADC采样节拍设计说明.md - 相量层 / ADC 输入层单测细则：
docs/测试说明/相量层单元测试说明.md、docs/测试说明/ADC输入层单元测试说明.md - RAM 与栈台账：
docs/内存管理/RAM使用分析与优化方案.md