feat(adc): 心跳新增 adc: 行输出 9 路原始码值，并补卡 0 台架注入验证流程

背景：ADC 采集的软件链路已全部打通（节拍、语义取数、折算、相量、 200 ms 快照、104/UI 消费），但"读数对不对"从未验证过——卡 0 的已知电压注入一直挂账。挂账的直接原因之一是读数出口不够用：固件只有 cal: 行（UA/UN/IA 三路，mV）与 first: 行（9 路码值，仅开机一次），验 8 个通道 × 3 个注入点要复位二十余次。改动一（App/task/adc_task.c，v3.3） - 心跳新增 adc: 行，每 10 s 输出 9 路原始码值，与 first: 行同序同格式，台架"改电压 → 读一行"即可对表，全程免复位。 - 不并入 cal: 行：9 个码值会把该行推到 168 字符，撞 DBG_CON_LINE_MAX(192) 的静默截断边界（截断不报错，只会少打几路，是最难发现的台架假数据来源）。 - 无新增跨任务状态、无新增外设访问；栈 +36 B（局部码值数组）， adcTask 静态最坏 1400 B / 余量 1160 B（底线 1024 B），stack_report PASS；静态 RAM 不变，Flash +188 B。改动二（新增 docs/测试说明/ADC前端注入验证流程.md） - 卡 0 的执行侧：注入点清单、期望码值表、零点/线性/映射/极性/节奏五步、现场记录表、安全红线、已知坑。 - 固化 2026-10-27 的网表结论：逐通道追 V0.1.tel 确认 ADCn 节点上只有"串阻 2 脚 + 滤波电容 + 转换器引脚"，没有对地分流电阻；所谓 "1k 到地"是 TPAFE 负输入脚 AIN_nGND 经 1k 拴到 AGND 的差分滤波。故本板不存在 2:1 分压，端子侧斜率 = 引脚侧斜率 = 6553.6 / 1241.2 码/V。数据可信.md §2.1 的 305.18 / 1611.3 µV/码确认不成立。 - 不验交流：台架无信号源，且五路单极性削顶。改动三（索引与指针） - docs/README.md 测试说明索引、测试文档模板规范.md 的 ADC 缩写行（原"待立"）同步。 - 数据可信.md 卡 0 增加指向该流程的指针（本表只写判据，不写怎么接表笔）。门禁：Keil 构建 0 错误 0 警告；check_ids --strict 通过； check_doc_links --all --sections-strict 通过（193 文档 / 2871 处引用）； pre-commit 全过（含 cppcheck、编码规范、体积档、标定层与量纲回归单测）；两处内存台账已按 --write / --update 刷新。
2026-10-27 15:14:07 +08:00
parent 103e26e111
commit 343305b433
9 changed files with 301 additions and 18 deletions
@@ -0,0 +1,248 @@
+# ADC 前端注入验证流程（台架）
+
+> **这篇是什么**：把「ADC 采到的数到底对不对」从"没人验过"推进到"有实测斜率与零点"的固定动作。
+> 它是 `docs/任务规划/数据可信.md` 卡 0 的**执行侧**——那边写判据，这边写怎么接表笔、读哪一行日志、
+> 填哪张表、结果往哪回写。补的是 `docs/硬件平台/ADC通道映射说明.md` §8「逐通道验证方法」
+> 长期挂账的"尚未执行"（挂账自 2026-10-09）。
+>
+> **只验直流**：零点 / 线性 / 通道映射 / 极性。不验交流有效值——台架无信号源，且 V0.1 有五路
+> 单极性削顶（`UB/UC/IB/IC/IN`），交流精度要等标准源到位后的两点标定（`docs/任务规划/数据可信.md` 卡 12）。
+>
+> **不需要**示波器、信号源、标准源。**只需要**一块万用表 + 一个电位器 + 串口日志。
+
+---
+
+## 1. 为什么非做不可
+
+现有台架判据只证明过"通路是活的"：9 通道全部转换成功、零超时、互异非饱和、跨次开机读数不同。
+这些**一条都不证明读数正确**——连符号位对不对都没验过。而下游已经全部按"工程量"消费了：
+保护判据、104 遥测、UI 交流量页读的都是 `adc_cal_apply()` 的输出。系数错一倍，三处一起错，且
+没有任何一处会报错。
+
+所以这一步的性质是**给整条链路的量纲盖章**，不是"补充测试"。
+
+## 2. 前置事实：这个前端不是分压器
+
+2026-10-27 按 `docs/硬件平台/V0.1.tel` 逐通道追线，以 UA 为例：
+
+```text
+U5.A3 (AIN1，端子侧) ──[R31 1k]── ADC7 ──┬── U3.61 (AIN_7P，正输入)
+                                          └──[C44]── ADC7_GND ──[R32 1k]── AGND
+                                                      └── U3.62 (AIN_7GND，负输入)
+```
+
+`ADC7` 这个节点上**只有** R31、C44、U3.61 三样东西，**没有对地电阻**。所谓"1k 到地"是 R32，
+它接在 TPAFE 的**负输入脚 AIN_7GND**（芯片手册 pin62）上，是把差分负端经 1k 拴到 AGND，
+属于差分滤波，不是信号分压。STM32 侧更直接：`AIN2 —[R52 1k]— ADC17 —[C111]— AGND`，同样没有分流电阻。
+
+**由此得到两条可直接用的结论**：
+
+1. **不存在 2:1 分压**。`docs/任务规划/数据可信.md` §2.1 那组"板级系数 305.18 / 1611.3 µV/码"
+   （按 2:1 折算到 `AINn` 侧的条件值）在本板上不成立，且该文档已禁止它进代码——本次实测只需**确认**它不成立。
+2. **端子侧斜率 = 引脚侧斜率**。所以在**端子侧**注入既安全（有 1k 串阻护着芯片）又能直接验 LSB，
+   不必去碰 LQFP 引脚。
+
+期望斜率（由转换器满量程事实推出，与前端无关）：
+
+| 转换器 | 满量程 | LSB | **期望斜率** |
+|---|---|---|---|
+| TPAFE5160 | ±5 V（10 V 跨度 / 65536 码） | 152.587890625 µV | **6553.6 码/V** |
+| STM32 ADC1 | 0~3.3 V（3.3 V / 4096 码） | 805.6640625 µV | **1241.2 码/V** |
+
+## 3. 注入点清单
+
+串联电阻的两只焊盘就是两个注入层级：**1 脚 = 端子侧（靠 U5）**，**2 脚 = 引脚侧（靠转换器）**。
+
+| 语义 | 串阻 | 端子侧节点 | 引脚侧节点 | 转换器脚 | 期望斜率 |
+|---|---|---|---|---|---|
+| UA | R31 | `AIN1`（U5.A3） | `ADC7` | U3.61 | 6553.6 |
+| UN | R28 | `AIN4`（U5.A4） | `ADC6` | U3.59 | 6553.6 |
+| IA | R19 | `AIN8`（U5.B5） | `ADC3` | U3.53 | 6553.6 |
+| UB | R52 | `AIN2`（U5.B7） | `ADC17` | U17.44（PC4） | 1241.2 |
+| UC | R20 | `AIN3`（U5.C14） | `ADC12` | U17.37（PA3） | 1241.2 |
+| IB | R49 | `AIN9`（U5.A8） | `ADC15` | U17.42（PA6） | 1241.2 |
+| IC | R46 | `AIN10`（U5.C9） | `ADC10` | U17.35（PA1） | 1241.2 |
+| IN | R48 | `AIN11`（U5.C10） | `ADC11` | U17.36（PA2） | 1241.2 |
+| 温度 | R47 | `V_ZL2`（U5.C11） | `ADC14` | U17.41（PA5） | 不验（非线性，不参与标定） |
+
+> 引脚侧没有串阻保护，注入前**必须外串 10 k 限流**。除非端子侧结果对不上、需要分离
+> "转换器的错"和"前端的错"，否则不要用引脚侧。
+
+## 4. 读数出口（固件只给这四行，没有命令控制台）
+
+| 日志行 | 频率 | 内容 | 用途 |
+|---|---|---|---|
+| `adc: UA=.. UB=.. UC=.. UN=.. IA=.. IB=.. IC=.. IN=.. T=..` | 每 10 s | **9 路原始码值** | 本次验证的主读数 |
+| `cal: ua_mv=.. un_mv=.. ia_mv=.. vl=.. cl=..` | 每 10 s | UA/UN/IA 折算后毫伏 + 标定/削顶位图 | 旁证：码值 → 电压是否自洽 |
+| `first: UA=.. … T=..` | 每次开机一次 | 9 路原始码值 | 与 `adc:` 行互校（同序同格式） |
+| `frames=.. idle=.. adc1_err=.. tgap=..` | 每 10 s | 采集健康计数 | 步骤 5 的节奏判据 |
+
+`adc:` 行是 2026-10-27 新增的（`App/task/adc_task.c` 心跳块），此前只有 `cal:` 的三路，
+验 8 个通道要复位二十余次。现在**全程不必复位**。
+
+⚠ `adc:` 行某路取数失败时该槽打 0，所以"9 路全 0"要读作"没数据"，判据是同一份心跳里
+`frames` 是否还在涨。
+
+## 5. 步骤
+
+### 5.1 步骤 0：断电核阻（5 分钟）
+
+断电，万用表电阻档逐路量 **注入点对 AGND**：
+
+- 端子侧应量到 **1 kΩ 量级**（串阻 + 转换器输入阻抗并联，不会精确 1 k）；
+- 引脚侧应量到 **高阻**（只有滤波电容和转换器输入）。
+
+任一路量到 **0 Ω 或几十 Ω** → 停，先查焊接/短路，不要通电。
+
+### 5.2 步骤 1：零点（这一步是整套测试的分水岭）
+
+把注入点**短接到 AGND**（短接点先用 0 Ω 档确认与 AGND 直通），读 `adc:` 行。
+
+| 通道 | 判据 | 当前空载实测（浮空） |
+|---|---|---|
+| UA / UN / IA | \|码\| ≤ 10 | **≈ 11430** |
+| UB / UC / IB / IC / IN | \|码\| ≤ 5 | **≈ 1000** |
+
+**为什么这一步最关键**：空载（输入浮空）读数比判据高两个数量级，最可能的解释是输入悬空后
+漏电流在滤波电容上建立的平衡点——短接 AGND 后应塌回 0。但如果**短接后仍读 11430**，那就是
+真实偏置，且超过零点补偿上限 `ADC_CAL_B_MAX`（8192 码）——`adc_cal_set()` 会直接拒掉、
+回退 ROM 系数、永远置不了 `VALID`，保护也就永远解不了锁。**那种情况必须回前端查**
+（R32 那侧接地是否断、TPAFE 是否失调），不能靠软件补偿。
+
+### 5.3 步骤 2：三点线性（用 UA 做，免复位）
+
+3.3 V 轨经 10 k 电位器分压作源，逐点注入。**每点同时记两个数**：万用表读注入点实际电压、
+`adc:` 行读对应码值。
+
+| 注入（实测电压） | TPAFE 期望码 | STM32 期望码 |
+|---|---|---|
+| ≈ 0.3 V | 1966 | 372 |
+| ≈ 1.0 V | 6554 | 1241 |
+| ≈ 2.0 V | 13107 | 2482 |
+
+判据：三点线性拟合 **R² ≥ 0.999**，斜率与期望值偏差 **≤ 2 %**。
+
+偏差 > 2 % 时**先查前端**（焊点、串阻实际值、电位器负载效应），不要用系数去凑——
+把硬件的错固化成"标定值"是最坏的结果。
+
+### 5.4 步骤 3：逐通道映射（8 路各一次）
+
+对每一路单独注入 1.0 V，其余路保持短接 AGND，读 `adc:` 行：
+
+- **只有对应的那一路上升**，幅值落在期望码附近；
+- 其余七路仍在零点附近。
+
+任何"注入 A 路、B 路动"都是映射错。这一条比斜率更重要——映射错时斜率可能完全正常。
+
+> 记录时把"注入路 → 实际变动路"写进附录表；`ADC通道映射说明.md` §3 的映射表如有不符，
+> 以实测为准并当场记下来。
+
+### 5.5 步骤 4：极性（只 TPAFE 三路）
+
+TPAFE 是双极性、二进制补码，可以注负压；STM32 是单极性，负半周测不了。给 UA/UN/IA 各加一个
+**−1.0 V** 点：
+
+| 注入 | 期望码 |
+|---|---|
+| −1.0 V | **−6554** |
+
+码值为负、幅值与 +1.0 V 点对称（差值 ≤ 2 %）→ 符号位与补码解释正确。
+这一步专门补"连极性都没证过"这个缺口。
+
+### 5.6 步骤 5：节奏（注入期间顺带看）
+
+注入期间 `frames=` 应仍**严格 1000 Hz 递增**（10 s 间隔 +10000 左右），`idle=0`，
+`adc1_err=0`。这一条替代了原方案里"用示波器看 U3.14 BUSY 有脉冲"的判据——不需要示波器。
+
+### 5.7 步骤 6：回写
+
+1. 把实测斜率、零点、映射结果写进 `docs/硬件平台/ADC通道映射说明.md` §8，把"尚未执行"改成
+   实测值 + 日期；
+2. 若实测确认无分压，同步在 `docs/硬件平台/ADC通道映射说明.md` §7.1 的链路分段表把第 ③ 段
+   （`AINn` ↔ 转换器引脚）从"待台架实测"改为实测结论；
+3. `docs/任务规划/数据可信.md` 卡 0 销项（按该文件夹"完成即删"的约定，删行不留记录）。
+
+## 6. 判据汇总
+
+| 项 | 判据 | 不通过意味着 |
+|---|---|---|
+| 零点 | TPAFE \|码\| ≤ 10；STM32 \|码\| ≤ 5 | 有真实偏置，需查前端；可能超出补偿上限 |
+| 线性 | R² ≥ 0.999 | 前端非线性或注入源带载失真 |
+| 斜率 | 偏差 ≤ 2 % | 前端有未识别元件，或转换器档位/参考错 |
+| 映射 | 注入哪路只动哪路 | 语义表与物理通道不符（`k_adc_map[]` 错） |
+| 极性 | −1.0 V → −6554 码 | 补码符号处理错 |
+| 节奏 | 注入期间仍 1000 Hz | 注入改变了输入共模，触发转换异常 |
+
+## 7. 安全红线
+
+1. **STM32 侧严禁超过 3.3 V**（VDDA + 0.3 V 即击穿），电位器上限就接 3.3 V 轨，不要接 5 V。
+2. **TPAFE 侧按判据只到 ±2 V**，虽芯片容 ±5 V，但判据不需要更大。
+3. **端子侧不许直接上额定电压**（220 V / 100 V 二次值）。本次是直流低压注入，
+   与"加压试保护"是两件事，后者要等变比确认（`docs/任务规划/数据可信.md` 卡 0b）之后单独排。
+4. **引脚侧注入必须外串 10 k**，且先接线后上电、先断电后拆线。
+5. 注入源与板子**共地**；电位器一端接 3.3 V、一端接 AGND、中间抽头串 10 k 到注入点。
+
+## 8. 已知坑
+
+| 现象 | 原因 | 处置 |
+|---|---|---|
+| 空载读数 11430 / 1000 码，跨开机稳定 | 输入浮空后的漏电平衡点（推测，待步骤 1 证实） | 短接 AGND 后应塌回 0；不塌则按 §5.2 处理 |
+| `cl=0xe6` 恒不变 | `UB/UC/IB/IC/IN` 五路单极性削顶，是 V0.1 硬件缺陷 | 正常；这五路只验直流，不验交流 |
+| `vl=0x00` 恒不变 | 从未做过两点标定，`VALID` 未置位 | 正常；标定后才会变 |
+| `meas: ua_mv=0` | 基波有效值，直流注入下本就为 0 | 正常；验交流要等信号源 |
+| `adc:` 行某路恒 0 而 `frames` 在涨 | 该路取数失败 | 查该路是否真的接线/短路 |
+| 斜率恰好差一倍 | 误用了 2:1 分压口径（305.18 / 1611.3） | 本板无分压，见 §2；按 152.59 / 805.66 重算 |
+
+## 9. 记录表（台架现场填）
+
+### 9.1 零点
+
+| 通道 | 短接后码值 | 判据 | 结论 |
+|---|---|---|---|
+| UA | | ≤ 10 | |
+| UN | | ≤ 10 | |
+| IA | | ≤ 10 | |
+| UB | | ≤ 5 | |
+| UC | | ≤ 5 | |
+| IB | | ≤ 5 | |
+| IC | | ≤ 5 | |
+| IN | | ≤ 5 | |
+
+### 9.2 三点线性（UA）
+
+| 注入电压（万用表） | 码值 | 反算 µV/码 |
+|---|---|---|
+| | | |
+| | | |
+| | | |
+
+拟合 R² = ______　斜率 = ______ 码/V　偏差 = ______ %
+
+### 9.3 逐通道映射
+
+| 注入路 | 注入 1.0 V 后变动的路 | 码值 | 是否符合预期 |
+|---|---|---|---|
+| UA | | | |
+| UB | | | |
+| UC | | | |
+| UN | | | |
+| IA | | | |
+| IB | | | |
+| IC | | | |
+| IN | | | |
+
+### 9.4 极性
+
+| 通道 | +1.0 V 码值 | −1.0 V 码值 | 对称性偏差 |
+|---|---|---|---|
+| UA | | | |
+| UN | | | |
+| IA | | | |
+
+---
+
+## 变更记录
+
+| 日期 | 内容 |
+|---|---|
+| 2026-10-27 | 建档。承接 `docs/任务规划/数据可信.md` 卡 0 的执行侧；固化"前端无分压"的网表结论、端子侧注入点清单、期望码值表与五步流程。同日 `App/task/adc_task.c` 心跳新增 `adc:` 行（9 路原始码值），使全程免复位 |
@@ -141,7 +141,7 @@
 | `GD5F` | GD5F2GQ5UE NAND Flash 驱动 | `GD5F2GQ5UE_Test_Guide.md` |
 | `STO` | 存储（FTL + FatFS 集成） | `GD5F2GQ5UE_Test_Guide.md`（TC-STO 章节） |
 | `RTC` | SD2506 RTC | `SD2506_Test_Guide.md` |
-| `ADC` | TPAFE5160 ADC | （待立） |
+| `ADC` | TPAFE5160 + STM32 ADC1 采集与折算（台架注入验证） | `ADC前端注入验证流程.md` |
 | `RS485` | RS-485 通信 | （待立） |

 > 新模块立测试文档时先定缩写（2~4 个大写字母），并同步更新本表与 `测试开发标准流程.md` §2.2 的缩写表。