wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
739 Commits 3 Branches 0 Tags
cbb4fdb893115ce7fe8e8687a115d45a91ee2d46
Commit Graph

39 Commits

Author SHA1 Message Date
wandering1 2b4c0e97c2 docs: ADC 注入流程 §4 补码值刻度图 
§4 的「码」定义表只有文字与数字，台架现场容易把 TPAFE 的
152.59 µV 与 STM32 的 805.66 µV 混着用。新增一张刻度尺对照
图（docs/images/ADC码值刻度.svg），上下两把尺子分别标出
11430 码 ≈ 1.744 V 与 1000 码 ≈ 0.806 V，把"同一整数在两片
转换器上代表不同电压"变成可见的；正文补一句两把尺子差 5.3
倍、§9 每格必须写明所属通道。

生成器 tools/arch_diagram/gen_adc_code_scale_svg.py 沿用图形绘制
流程 §3.2 约定（纯标准库 / html.escape / newline="\n" /
ElementTree 自检 + 文字溢出预检）；码制与 LSB 数据集中在
PANELS 常量，换芯片才重画。已登记到 tools/arch_diagram/README.md
与 docs/架构设计/图形绘制流程.md 的生成器表 + 变更记录。

目检用无头 Chrome 截图完成（cairosvg 未装，截图不入库）。
 2026-10-27 17:25:51 +08:00
wandering1 9163a92d3b docs(adc): 前端拓扑改 SVG，③ 段定死 1:1（本板不是分压器） 
ASCII 拓扑图把 C44 / R32 画成挂在 ADC7 下的一根竖线，读起来像 2:1 分压，
恰是文档要否掉的结论。改为两个节点分开画的 SVG，并加 STM32 侧对照面板。

- 新增 tools/arch_diagram/gen_adc_frontend_svg.py →
  docs/images/ADC前端电路.svg（纯标准库 + 文字溢出预检 + 幂等重跑）
- docs/测试说明/ADC前端注入验证流程.md §2、docs/硬件平台/
  ADC通道映射说明.md §7.1 的 ASCII 图换成该 SVG
- ③ 段（AINn ↔ 转换器引脚）定死变比 1:1：ADCn 节点只有
  {串阻.2, 滤波 C, 转换器引脚}，无对地元件；"1k 到地"接在差分负端
- 305.18 / 1611.3 µV/码（读法 A）作废；数据可信.md §2.1 表改为
  引脚侧系数 152.59 / 805.66，卡 0 判据从"判别两种读法"降为
  "确认转换器 LSB 与逐通道映射"
- 顺带修 ADC通道映射说明.md §8 步骤 1 的 §5.1 自引用误判
  （文档名以 V0.0 开头被前缀规则误认，改写成全路径形式）

门禁：Keil 无关（纯文档 + 生成器）；check_ids --strict、
check_doc_links --all --sections-strict、pre-commit 全过。
 2026-10-27 17:08:56 +08:00
wandering1 4c74cfa825 refactor(编号·批次二): 文档侧 194 处保护功能号改成功能名，定义表 7 张首格改语义标识 
批次二文档半（道 gate-docs 执行）。先纠三个数的口径账，别再拿任何旧数当准：**234 处是准数** —— 卡片写
52（Lead 用了门禁 Checker 的引用集合，它**刻意排除属主文档内部的定义位**）、道里先报 265（裸正则把
`SDL2-2.32.10` 里的 `L2-2` 当成功能号，误报 10 处）。最终边界口径 = 带左边界 + 跳过反引号代码段。

· 19 只文件 HEAD 共 234 处 → 现 40 处，**40 处 100% 落在变更记录行**（冻结历史，按 Q3 一条没动），
  非变更记录残留 **0**；改写 163 行 / 16 只文档。站点最多：规划文档 110→37、相量层单测说明 25→1、
  采集与数据处理短板评测 21→0、App/algo/README 26→0。
  （`App/algo/README.md` 由上一笔代码提交带上车，路径归属已在该笔正文注明，内容是本批改写）
· **定义表首列由编号改成语义标识**（编号规范 §3.3「表首格就是短语」的完全形态）：首列原为编号的表
  共 **7 张**（不是 5 张），删掉与之重复的「语义名」列；表头标签按域词区分——三张 L3 保护**元件**表
  保留 `| 元件 |`，四张 L1/L2 表用 `| 功能名 |`（把「元件」统一洗成功能名会丢掉领域信息）。
  七张表逐张核：表头竖线数 == 分隔行 == 首条数据行 == 列数+1；与 HEAD 逐块对拍**净新增不一致块 0**，
  并且正是这个对拍抓到第一版「三张表数据行已删列、表头没删」的破表。
· 7 处删号留下的残词/重复解释括号人工收口（如「L1-5（通道标定）」→「通道标定（一次系数 + 零漂）」），
  复扫待收口站点 0；措辞逐字取自映射表，无第二种说法。
· tools/arch_diagram 三只生成器 4 处（3 处 docstring + 1 处图形文案）与产物同批：重跑后**只有位图那张
  变 2 个 text 节点的换行位置**，画布 1580x740 与总行数不变，另两张逐字节未变；改前先干跑对照证明三张
  svg 原本与生成器一致（不在 stale 基线里）——`check_generated_fresh --only docs-svg` PASS。

本笔另含 **F-* 半批的文档面**（同一轮 `git add docs tools/arch_diagram AGENTS.md` 一并收进
，非误伤）：BSD
函数调用关系里 9 处反引号紧邻指针、属主文档 §7 的停发句与导读行（**12 条定义行原样保留、不删登记族**）、
以及 `gen_net_instability_svg.py` 与它的产物 `网络不稳根因总览.svg`（「唯一读者红线」那条的框宽自适应
526 → 551，右缘 1411 未越界，画布 1560x1468 不变）——该半批的**代码注释面**在下一笔。

⚠ 因 `docs/任务规划/登记簿.md` 与 `docs/任务规划/UI补齐.md` 正被另一张卡（UI 叶数复核）改动，本笔**不含
那两只文件**，批次二的 §9 存量收尾与它们同批提交。
 2026-10-27 09:05:24 +08:00
wandering1 0f7b5a87fb chore(编号): 存量编号全量转语义短语，门禁识别面与语料同批重打 
登记簿、文档与代码注释里的存量字母加数字编号（N-x / S-x / T-x / E-x / A-x / 卡号）
一律改写为语义短语，净删 2,028 处引用；删除基线与待确认、并行分道方案、排期详述、
采集保护收尾 4 篇（内容已并入 docs/任务规划/README 与登记簿）。

门禁机器与三张账同批重打：check_ids.py 新增变更记录行豁免与第二根护栏
undecidable_total_ceiling；check_test_traceability.py 只加 stdout/stderr UTF-8
reconfigure（TC_RE 未动）；check_cubemx_survival.py 的 --write 固定 newline=LF；
id_registry / id_aliases（+19 条 retired-to-phrase）/ id_known_backlog 重打。

test/ 56 个文件同步 TC 标签语义化，其中 18 个 TU 改了 CHECK / printf 里的标签文字，
是本批唯一改变构建产物的文件集合。

为什么合成一笔、不拆四笔（实测撞闸，非偏好）：pre-commit 跑钩子前会 stash 未 staged
部分，拆开后中间提交必然是「新规则 + 旧语料」——实跑可判定 85.15% < 基线 86.00%、
不可判定 1,453 > 上限 1,166，编号门禁直接拦下。编号识别面与它描述的语料只能同码移动。

实跑基线（工作区全量）：754 文件 / 8,230 处编号字面量 / 可判定 7,079 = 86.01%
（基线 86.0%，容差 0.1pp）/ 不可判定绝对数 1,151（上限 1,166）/ 校验 1-6 错误级 0 /
告警 = 悬空 2（App/algo/freq.c 的 S2，属 §4.4 同号不同义）+ 孤儿 50。

基线从 84.0 抬到 86.0 的理由见 docs/门禁说明/id-check.md §7.6：本批真删了 2,028 处
引用，可判定面随真实内容上升，不是把分母做小。同批新增排除 docs/硬件平台/ 语料，使
识别面少 264 处——芯片手册位号与网表料号不属编号空间（registry 有 excluded_paths_note）。

⚠ 余量只剩 0.11pp（约 10 处）与绝对数 15 处：把「可判定的引用」改成散文会立刻撞第二
根护栏。另遗留一项：id_aliases 里 retired 的 N / S / T / A 别名没有 scope（U1~U5 有），
今后有人新写一个 A-4，校验 3 不会响，只能靠人，建议下批补 scope。

固件不变证据：115 个 .c/.h 剥注释并归一字符串后与 HEAD 逐字节全等，残留代码差异 0；
App / Src / Drivers 的字符串字面量零改动。@build 0 错误 0 警告；40/40 主机套件、2,889
断言全通过；覆盖率 line 89.2% / func 92.6%；pre-commit 48 钩子 --all-files 全绿；
check_doc_links --all 通过（176 文档，章节引用无法判定 0）；逐字节卫生核过：14 个带
BOM 文件与 HEAD 一致、0 个 CR、0 个 U+FFFD，字符串字面量纯 ASCII。

.cubemx_survival_baseline.json 的 watchdog-module 哈希 56bf27 变 2bb051 属合法：
Src/freertos.c 的 USER CODE 区内只有注释文字随编号改写，代码未变。

同批带上体积同码凭证与 RAM 台账行（@build 之后盖戳）：RW_IRAM1 79,008 B / 60.3%，
RW_CCM 57,376 B / 87.9%，阈值 92%。
 2026-10-26 12:28:14 +08:00
wandering1 d9b887c0af feat(S-5 R4): 返回值不得裸丢弃成为机械检查，并修掉照出的第一处 ECC 静默降级 
B 的第一步（加规则）与第二步（修最小最值的那处）。用户裁定"B 按你说的进行"。

**为什么只能项目侧自己做**（两条实测负结果，已写进 §2.27 与 bsp_err.h 边界纪律 4）：
· ARMCC v5 对 __attribute__((warn_unused_result)) 不生效（凌晨在 rs485_transmit 上实测：属性
  在位、调用点裸调不接返回值，构建仍 0 错 0 警告）；
· cppcheck 也照不出来——按本仓自己的 --enable=warning,style,performance,portability 跑
  gd5f2gq5ue.c，对 14 处丢弃 HAL_SPI_* 返回值、以及"未初始化局部量直接进 P_FAIL 判定"
  **一条不报**（它假定 gd5f_read_status(&status) 会写出参，而失败路径根本不写）。
结论：**丢弃底层传输的返回值，今天没有任何工具会响**。

**R4 上线即照出 37 条存量丢弃**：gd5f2gq5ue.c 29（14 处 HAL + 15 处自家原语）、net_socket.c 8、
ui_net_sink.c 4（net_close）、rs485.c 2、nand_ftl.c 1。按增量拦截老规矩入基线、只减不增——
这是覆盖面扩大新暴露的历史债，不是新增违规；基线 19 → 1 → **38**。

**R4 自己被修三次（逐条记下，都是"规则比我想的更脆"）**：
① 首版漏判"裸调用行尾带注释"这种写法（正则的 \s*$ 卡死），而那恰是最常见的"带说明的丢弃"
   → 补可选注释分支，并做 6 条正/反例自检；
② 把 net_set_errno 八处误判成丢弃（它是 setter，返回 int 是状态回声不是调用成败）→ **按真实
   反例把规则收窄**（谓词 + setter 两类豁免），而不是塞进基线洗掉假阳性；
③ must-use 名单只从**头文件**取，gd5f_set_feature 这类 static 原语整个在视野外——而下面那处
   真窟窿恰恰是 static、靠人工才发现 → 名单扩到 .c 内 static 定义（同一套启发式），补完立刻
   又照出 gd5f_bbt_save#1：**运行时标坏后 BBT 落盘结果被丢弃 = 坏块记账可能没持久化**，已入
   基线记为待还，本步不动行为。
另修一处自己的排版误判：R3 原本要求注释块出现字面"返回值"，规范 V1.0 允许列对齐写法
「返 回 值：」→ 改为忽略空格匹配（门禁不该规定排版）。

**修掉的第一处真窟窿**：bbt_rebuild 的注释写着"无论扫描成败都须恢复 ECC，否则后续 I/O 在无
ECC 下运行"，而它下面 gd5f_set_feature(0xB0,…) + gd5f_wait_busy(100) **返回值全丢**：SPI 一抖
ECC 就保持关闭，且 gd5f_check_ecc() 在 ECC 关闭时恒读"无 ECC 错"——整条链再没有任何信号。
补法复用 init 路径的 E-10（写完回读 B0h 验 ECC_EN 位真生效，"写了但没生效"与写失败同罪），
并把"关 ECC 失败"改成**立即中止**（此时 ECC 仍开着，是安全侧；带着 ECC 去扫 spare 反而会把
厂标好块误判成坏块，"重建 BBT"变成制造坏块）。恢复失败时按 (void)gd5f_bbt_load() 回读盘上
副本，避免 RAM 留着"比盘上更新"的表而下次上电又退回旧表。

**一条定位纠正（差点把修复记大）**：查链接映射发现 Removing gd5f2gq5ue.o
(i.gd5f2gq5ue_bbt_rebuild), (604 bytes)——该函数在产品镜像里**根本没被链接**（产品构建无调用
者），只由 ENABLE_STORAGE_RECOVERY_TESTS 的恢复构建经 testTask 调用。所以本次修的是**恢复流程
自身的安全**（跑恢复时若 ECC 没恢复，设备会带着"已恢复"的结论在无保护状态下继续跑），不是
现场日常路径；相应地镜像 Code 的 +28 B 也不是它带来的（未逐字节追，线索是
gd5f_private_get_feature 由单调用点变多调用点、内联决策可能变化）。验证因此不能只跑产品构建：
临时打开 TEST_SUITE_STORAGE + ENABLE_STORAGE_RECOVERY_TESTS 编一次（0 错 0 警告且该函数不再
出现在 Removing 列表），随即还原两处开关并重编产品构建核对（test/board 无残留差异）。

**编号门禁把我自己的自造编号拦下了**：我起初用 B-1/B2/B3/B4 标记这批缺陷，id-check 报"未登记
前缀"13 处（且 B2/B3/B4 会与真实里程碑号撞号）→ 全部改写成平实语言。这是那条"注释与文档里
不许用没人检索得到的内部阶段编号"的规则第一次在提交前拦住我，规则是对的。

验证：@build 0 错 0 警告，Code 213,648 → **213,676**、RO 18,860、ER_IROM1 **232,536 B
  / 22.2%**
（ROM 合计 233,724 B；RAM 逐字段不变）；ram_report 重生成 + ram_baseline.py --update + 配图常量
同步（mem-numbers Passed）；@test **PASS**（到 net init: OK 682 ms、[ERR] 0）；R4 两处**探针
实证**（临时加一条裸调用 → 立刻成为新增并 RC=1；还原 → 38/38/0）；--prune 点名本次还掉的 2 条
已删；pre-commit run 全绿 15 Passed；check_doc_links --all --sections-strict 147 篇
  0 问题；
id-check --strict 增量拦截通过。

文档：AGENTS.md 与 .pre-commit-config.yaml 的 bsp-err 口径（四条规则、基线 38）；
pre-commit使用说明.md §2.27（R4 全量口径 + 两条负结果 + 名单来源与豁免形状 + 单行限度）；
bsp_err.h 边界纪律 4；报告 §0.4 / §5.1 / §9 / 附录 A + 变更记录；存储维护与容量恢复.md 新增
§4.3（运维判据：出现 ECC restore FAILED / ECC not enabled 即本次恢复**不算完成**，须断电重启
重走 init，不许接着 nand_ftl_format() 当作已修好；并记明该函数产品镜像不链接）——顺带修该文
结构缺陷：原 ## 5. 变更记录 误插在 §4.1 与 §4.2 之间，会让 §4.2 变成 §5 的子节。
 2026-10-23 09:15:41 +08:00
wandering1 78248a1cdf feat(S-5): 收编 SD2506/TPAFE 并给 dhara 失败分类，门禁基线 19→17 
前一笔立契约与门禁（`Drivers/BSP/bsp_err.h` + `bsp-err` 钩子 + RS485 试点）；这一笔按用户
指定顺序 C3 → C1 → C2 把三个模块真正收编，并让存储失败第一次变得可读、可分类。

**C3 · SD2506 整模块（11 个公共 API + 6 个内部 helper）**：三枚私有宏 `SD2506_OK`/
`SD2506_ERROR`/`SD2506_I2C_ERROR` **删除而不是留别名**——留别名等于新代码还能用旧形状，
把迁移洗掉；编译器替我们找全所有调用点。新增 `sd2506_err_from_hal()`，**把 I2C 超时从
"和没人应答共用一个 −2"里拆出来归成 `BSP_ERR_TIMEOUT`（可重试）**——SD2506 是启动链第一站、
I2C1 上电时序敏感，这是本波唯一真正的语义改善，不是改名。`sd2506_init` 的 charge 寄存器
**回读校验不符**原返参数类错误，改归 `BSP_ERR_IO`（那不是调用方的错）。

**C1 · 同形两义**：`GD5F_BUSY_TIMEOUT` → `GD5F_WAIT_EXPIRED`（**值 −2 不变**，纯消"名字叫
TIMEOUT 其实是返回码"）。**GD5F 私有码集整体收编刻意没做**：169 处引用里 48 处在板级套件、
还要动 Trap 记录用词，属另一波带真机+套件回归的工作，不夹带。TPAFE5160 收编 23 处：
`BUSY_TIMEOUT → BSP_ERR_TIMEOUT`、`ERROR → BSP_ERR_PARAM`（**同值 −1，行为零变化**）、
`FRSTDATA_ERR → BSP_ERR_NO_DEVICE`（E-44 的本义就是"芯片没驱动 DB 总线"，归到器件无响应比
私有 −3 有用，且避开与 `BSP_ERR_TIMEOUT` 撞值）。实测 `tpafe5160.o`/`gd5f2gq5ue.o` 的 Code
增量为 **0**——改名不产生一条指令。

⚠ **`tpafe5160_snapshot()` 刻意不套成败码**：它是 1=有新帧 / 0=无新帧 / −1=参数错 的三态
**状态**返回，0 不是错误而是"这一拍没有新数据"，强行收编会把慢消费者的正常路径变成失败。
顺带订正我上一版在 `bsp_err.h` 的断言——"本层只有 `net_*` 把数量与错误挤同一返回值"是错的，
`snapshot`/`adc_input_poll` 就是第二族；两族现都已写明并各注保留理由。

**C2 · FTL 坍缩点分类**：`ftl_flush_cache`/`ftl_read_page` 不再把 dhara 失败压成
  `GD5F_ERROR`，
按**处置差异**分三类，并在最早同时知道 LPN 与原始码的位置就地打印：`ECC`/`TOO_BAD` →
`BSP_ERR_CRC`（页级，重试或换页，不代表卷坏）；`JOURNAL_FULL`/`MAP_FULL` →
`BSP_ERR_NO_SPACE`（介质健康但块池/日志见底，此时重格式化只是把问题推回去）；
`BAD_BLOCK`/`RECOVER`/`CORRUPT_MAP`/越界 → `BSP_ERR_IO`（完整性故障，保卷 + 上报，不许自愈
重格式化）。这与 **E-31** 是同一条纪律的两端。可读名用自建短表：**本仓 dhara 没有编
`error.c`，用 `dhara_strerror()` 会直接链接失败**。`disk_read`/`disk_write` 仍回
  `RES_ERROR`
（FatFs 契约）；要让 defaultTask 卷健康探针按类分支还差跨调用存活的快照 → C4 待还。

**两次靠核实拦住的自我错误**：① 我一度认定 `DBG_ERROR("... err=%d", err)` 是把结构体塞进
varargs 的格式 bug——核 `Lib/dhara/error.h` 后确认 `dhara_error_t` 是 `enum`（标量），那行日志
本来合法，改了反而是引入错误；② `bsp-err` 一次 `replace_all` 越界把 8 处 **GD5F 码空间**的
判据改成 `!= BSP_OK`（数值同为 0、无行为变化），但那正是"把两个码空间混起来"，已逐一还原。
`cppcheck` 亦抓到 `cls` 声明作用域过宽，已收进失败分支。

**验证**：`@build` 0 错 0 警告（`Code` 213,648、RO 18,860、`ER_IROM1` 232,508 B /
  22.2%、
`ROM 合计` 233,696；**RAM 三项零增量**）；`@test` PASS（692 ms，烧入戳 `Oct 23 01:35:32`）
且逐条读到被改模块的锚点：`SD2506 init: OK (ret=0)` 与 ID/时间/温度/电池四条读回正常、
`ADC init: OK`、`NAND init: OK`、`Map resumed: 14094/97504`、`adc=` 帧计数持续递增（证明
snapshot 三态未被改坏）、`[ERR]`/Fault/FAIL 0 条。主机单测：系统时钟 100/100、dhara NAND
移植层 149/149（两者都因本次改动需补 `Drivers/BSP` include 路径，补后在钩子内实跑 Passed）。
`pre-commit run` 全量 RC=0（20 个实跑钩子 Passed）；`bsp-err` 基线 **19 → 17**（还掉两个
`*_BUSY_TIMEOUT = -2`）、`--prune` 干净；`doc-links --all --sections-strict` 147 篇
  0 问题；
`id-check --strict`、`layer-deps`、`mem-numbers`、`mem-budget`、`ui-golden` 全过；33
  个文件
字节卫生 0 异常（无 CR / 无 U+FFFD / 无行尾空格 / 均有尾换行）。

**口径与数字联动**：新增 `docs/架构设计/STM32F4-Base存储架构说明.md` §10.4（三类码与处置
理由）；`pre-commit使用说明.md` §2.27 与 `AGENTS.md` 基线计数 19 → 17；TPAFE README、
GD5F 测试指南与 Trap 记录均**保留旧名留痕**以便对旧日志；配图桶按 .map 对象级增量重算
（`dhara/FTL` 10,931 → 11,222，+291 全部落在 `nand_ftl.o`；应用代码/UI +36 落在
`app_main.o`；其余散量入"其他"7,557；桶和 = Code+RO 断言通过、文本溢出 0）；
`ram_baseline --update/--write`、`ram_report_20261023.md` 快照、报告 §1.3/§5.1/§5.4
  与
部署文档 §3.3 数字全部同步；报告 §0.4/§9 的 S-5 状态改为 🟡 主体已落地。
 2026-10-23 07:42:02 +08:00
wandering1 8b0ea17b71 fix(lftpd): LIST/NLST 满块续发——大目录不再被静默截断并回 550 
现象：`ftp_test.py` 的 `LIST 150->226` 断言失败——1512 B 数据全收到了，完成回包却是 **550**。

**根因**（`send_list`/`send_nlst` 各一处）：定案三把"整份目录一次性批量发送"落进 static 1536 B
缓冲时，顺手留下了"装满就 `break` 并回 −1"，`cmd_list` 据此回 550。于是目录一旦超过一块，客户端
拿到的是**静默截断**的清单**外加一个错误码**——而清单看起来完全像"目录里就这些"。这比单纯报错
更危险：没有人会去数条目个数。

**台架实测（同一台设备、同一个根目录，改动前后各测一次）**：
· 改前：1512 B / **24 条目** / 完成回包 **550**（停在 A0007.BIN，后面 6 个文件被吞）
· 改后：1880 B / **30 条目** / 完成回包 **226**

**修法：满块续发**，而不是把缓冲区加大。新增 `list_batch_flush()`——装满一块就整块发出、清空
继续装，收尾再发最后一块。为什么仍要"批量"：定案三的本体是实测结论——同一连接上背靠背 ~60 B
小段写会毒化 CH395F 的 TX（芯片报 SEND_OK 但对端全丢，无 RST 无 DISCONNECT），而 RETR 的 1 KB
满块连发安全；所以这里只发大块，绝不退回"每行一发"。单行真装不下时**明确失败**而不是少发条目
（8.3 短名 + 定长格式远小于 1536，真发生说明格式被改坏）。两条出口的 `lftpd_io_closedir` 收敛到
循环后单点：卷锁持有至 closedir，任何提前 return 都会漏锁。

**防回退**（关键）：修完之后，**目录清空的设备上这颗雷再也暴露不出来**，所以补了
`test/host/ftp_list_fill_test.py`——自造 26 个 8.3 短名文件把清单撑过一块，三条判据（STOR 全 226
／LIST 全文里每个名字都在／完成回包 226 而非 550，用 ftplib `retrlines` 让非 2xx 完成直接抛），
跑完逐个 DELE 还原。真机实测 `收到 56 行 / 3544 字节`（跨 3 块，满块续发被真正走到）→ 三条全
PASS。用法登记进 `docs/测试说明/FTP_Test_Guide.md` §4.5，机理与增补写进
`docs/问题记录/CH395F_Trap_Records.md` 定案三。

**顺带记录的已知偏差（未修）**：`cmd_list`/`cmd_nlst` 忽略命令参数、恒列会话 CWD
（`client->directory`）。主流客户端都是 `CWD` + 裸 `LIST`，实际影响小，先记在案。

体量：`Code` 213,264 → **213,436 B（+172）**、RO 不变 → `ER_IROM1` **232,088 B（22.1%）
  **、
`ROM 合计` 233,276 B；**RAM 一字未动**（`RW_IRAM1` 75,264 B 57.4% / `RW_CCM` 57,376 B
  87.9%）。
数字联动照做：`data/ram_report` 重跑、`ram_baseline --update/--write`、
  `check_mem_numbers --write`、
FLASH 配图常量重算重生成（桶合计 = 232,088 与 `Code+RO` 相符）、报告 §1.3/§5.1/§5.4 与部署 §3.3。

门禁：`@build` 0 错 0 警告；`@test` PASS（692 ms）；`ftp_test.py` → **TEST
  PASSED**（含此前失败
的 `LIST 150->226`）；`ftp_up_dl_test.py` → TEST PASSED；`ftp_list_fill_test.py`
  → TEST PASSED；
`doc-links --all` 146 文档 0 问题；`id-check --strict` 增量拦截通过（可判定 82.82%）；
`mem-numbers` / `mem-budget` 通过；改动文件字节卫生 BOM 无 / CR 0 / U+FFFD 0 / 无行尾空格。未推送。
 2026-10-22 22:41:31 +08:00
wandering1 4c21cff753 fix(lftpd): 对端行为不再打 [ERR]——新增 lftpd_peer 级别并划清级别边界 
现象：抓自检台账基线那次 FTP 会话一结束，设备就打 `[ERR] [FTP] error reading next command`，
本次 `@test` 直接 FAIL（Forbidden 含 `[ERR]`）。查下去发现 lftpd 把**全部**异常路径一律按
error 级打，其中九处其实由外部输入决定：客户端关窗口、连上就走、PASV 后不建数据连接、
运维改 IP 触发监听重建。两条代价：① 任何人"连 21 端口一下就断开"就能把一次启动测试打成
FAIL；② 同样的动作可以**无限制造固件级 ERROR 日志**——日志面与门禁面都可被外部驱动，
工业现场过不了审。

**做法**：`private/lftpd_log.h` 新增 `lftpd_log_peer()`（info 级，带 `[FTP]` 前缀），而不是
就地改成 `DBG_INFO`——让"谁才算真故障"在读代码时一目了然，也防止后来者顺手把对端行为升回
error。降级的九处：控制通道被对端关闭（原 `error reading next command`，改为
`control channel closed by peer (ret=%d)`，措辞原先把正常收尾写成故障、误导过排查方向）、
发送 220 前对端已走、`listener rebuilt`（网络重建，原因由 accept 层自己记）、四处
`data accept failed`（PASV 后没来数据连接）、`accept timeout`。

**刻意留在 error 的**：create/bind/listen/取端口失败、写通道失败、文件打开失败、
`DOWNLOAD/UPLOAD FAILED`（对端中途退出确实让一次传输没走完 = 数据完整性事件，
`../问题记录/CH395F_Trap_Records.md` 的中止家族要靠这些锚点定位）、
`data listener disarmed`（控制连接还活着而我方数据监听已不在服役 = 本侧异常，就地注明）。

**实测划清的边界**：客户端**干净收尾**（发 `QUIT` 或 FIN 半关）现在整条链路没有任何 `[ERR]`；
但 **RST 硬拆**（`SO_LINGER` 清零 / 进程被杀 / 拔线）仍会留一条 `[ERR][NET] sockN TIMEOUT`——
那是 net 层的套接字超时锚点，网络自愈架构判据要读它，不在本次降级范围。所以"采集窗口内别跑
`data listener disarmed`（控制连接还活着而我方数据监听已不在服役 = 本侧异常，就地注明）。

**真机验证**：`@build` 0 错 0 警告；`@test --require-selftest-pass --device-ip` →
  **PASS**
（基线 29 条 → 本次无新增；`net init: OK` 726 ms）；专门写了 RST 复现脚本（登录后 `SO_LINGER`
清零直接关）→ 串口得到 `[FTP] control channel closed by peer (ret=-1)`，**不再是 `[ERR]` 行**；
同一份日志里 QUIT 收尾的那次会话完全没有错误行。

体量：`Code` 213,236 → **213,264 B（+28）**、`RO` 18,580 → **18,652 B（+72）**（措辞变长），
同一份日志里 QUIT 收尾的那次会话完全没有错误行。
`ZI` 131,500、`RW_IRAM1` 75,264 B 57.4% / `RW_CCM` 57,376 B 87.9% 全不变）。数字联动照做：
两份 `data/` 快照、`ram_baseline --update/--write`、`check_mem_numbers --write`、FLASH
  配图
常量重算重生成（桶合计 = 231,916 与 `Code+RO` 相符；越界复查 0）、报告 §1.3/§5.1/§5.4 与
部署文档 §3.3 同步。

口径落文：新增 `docs/架构设计/STM32F4-Base存储架构说明.md` §10.3「FTP 日志级别划分：对端行为
vs 固件故障」（含两类的判据表与边界），并更新 `docs/测试说明/自动化测试流程.md` 的采集窗口警示。
顺手把 `private/lftpd_log.h` 工作区的 CRLF 混用归一回 LF（仓库里 blob 本来就是 LF，diff 无影响）。

门禁：`doc-links --all --sections-strict` 146 文档 0 问题、`id-check --strict` 增量拦截通过
（可判定 82.82%）、`mem-numbers` / `mem-budget` / `layer-deps` 全绿；改动文件字节卫生 BOM 无 /
CR 0 / U+FFFD 0 / 无行尾空格。未推送。
 2026-10-22 22:31:09 +08:00
wandering1 e7f28502bc refactor(NET): netMsgQueueHandle 收进 net_socket 私有，改为创建后绑定 
结构债 S-2 的最后一步——**该族的 24 处手写跨模块裸 extern 就此全部清零**。

队列对象仍由 CubeMX 在 `MX_FREERTOS_Init()` 创建（**创建点不可外移**：
`osKernelInitialize()` 之前的任何创建类 API 会杀死启动，见
`docs/架构设计/项目启动顺序管理.md`）；改为创建后立刻在 `Src/freertos.c` 的
`USER CODE BEGIN RTOS_QUEUES` 区调用 `net_msg_queue_adopt(netMsgQueueHandle)`，
把句柄交给唯一使用者。`net_socket.c` 内改用 `static osMessageQueueId_t
s_net_msg_queue`（21 处引用改名），BSP 对该全局变量的裸 `extern` 消失——现在
`netMsgQueueHandle` 只出现在生成文件自己的两处（定义 + 创建）。

两个刻意的设计决定：
① **不新建第二个队列**。自建队列 + 删 `.ioc` 里的 netMsgQueue 也能收口，但要
   CubeMX 重生成（Ask-first），过渡期还会同时存在两个队列，白占 CCM 堆里
   8 × `net_msg_t` 的空间——CCM 正是当下 87.9% 的红线。故选"创建后绑定"。
② `adopt()` **拒绝重复绑定、保留首次句柄**。真出现两处绑定时，静默换句柄会让
   已入队的请求留在旧队列里永不处理；拒掉第二个反而更容易暴露。绑定前的判空
   是真实防线：丢了那一行，后果是"所有 net_* 请求被丢弃、网络全线静默不通"，
   不是崩溃。

**防回退**：`check_cubemx_survival.py` 新增存活项 `net-msgq-adopt`（region
`RTOS_QUEUES`、`must_contain=["net_msg_queue_adopt"]`），易失清单 29 → 30 项全部
到位；基线已重建（有意的 USER CODE 区改动，按脚本文档流程 `--write`）。

**体量**：`Code` 213,204 → **213,236 B（+32）**、`ER_IROM1` **231,816 B（22.1%）**；
`RW +4 / ZI −4` → `RW_IRAM1` 恒 **75,264 B（57.4%）**、`RW_CCM` 恒 **57,376 B
（87.9%）**、`RW+ZI` 总量 132,688 B 不变（没有多占一个字节 RAM）。

**验证**：`@build` 0 错 0 警告；`@test` PASS——624 ms 到 `net init: OK`、`i104:
listening on 2404`、无 `[ERR]`/Fault、`heap free=15800 min_ever=8464` 逐项不变。
另在真机跑了一次 FTP 控制通道往返：220 → `USER admin` 331 → `PASS admin` 230
→ `PWD` 257 → `TYPE I` 200 → `QUIT` 221。每条命令都是一次过队列的
net_recv/net_send，证明绑定路径真在跑；`.map` 里 `freertos.o(MX_FREERTOS_Init)
refers to net_socket.o(i.net_msg_queue_adopt)` 证明镜像含该行。

⚠ **顺带揪出一条测试工具漂移（本次未修，等定夺）**：
`test/host/ftp_up_dl_test.py:123/126` 仍写死 `USER anonymous` /
`PASS test@test.com`，而设备自 N-19（2026-10-11）起按 `/config.ini [ftp]` 校验
admin/admin（SHA-256 `pwd_hash`）→ 该脚本必然登录失败。它是手工工具、不在任何
pre-commit 钩子里，所以 11 天没人发现，而 `docs/测试说明/FTP_Test_Guide.md` 把它
列为"推荐入口"。建议加 `--user/--password`（默认 admin/admin），并连
`ftp_speed_test.py` 一起核。

数字联动：两份 `data/` 快照重跑、`ram_baseline --update/--write`、
`check_mem_numbers --write`、FLASH 与任务栈两张配图常量重算并重新生成（逐文本按
字号与锚点复查越界 = 0）、报告 §1.3/§5.1/§5.4 与部署文档 §3.3 同步。报告 §0.4 的
S-2 行按「完成即销项」改写为已闭环，§9 拆出独立 S-2 行标 ✅。

门禁：`@build` 0/0、`@test` PASS、`layer-deps` / `cubemx-survival` / `mem-numbers`
（本次改到台账受管区，scan 已过）/ `mem-budget`（57.4% / 87.9%）/ `task-table` /
`doc-links --all`（146 文档 0 问题）/ `id-check --strict`（增量拦截通过、可判定
82.84%、存量债 640）全绿；14 个文件字节卫生 BOM 无 / CR 0 / U+FFFD 0 / 无尾空格。
未推送。
 2026-10-22 20:01:40 +08:00
wandering1 7e77af08a0 fix(BSP): SPI1 完成标志收回 GD5F 私有，HAL 回调改契约转调 
推荐清单第 4a 步（结构债 S-2 剩余面里唯一带"静默失效"属性的那条）。

**问题不是风格**：HAL 的 SPI 完成/错误回调是**全局唯一符号**，整个工程只能有一份
实现，当前由 CH395F 代管并按 `hspi->Instance` 分发——于是 GD5F 的完成标志
`g_spi1_dma_done` 被 CH395F 跨模块裸 `extern` 直接写，**GD5F 出错时的"释放等待者"
寄居在别人的 .c 里**。谁哪天做"CH395F 清理"，把那两个 `else if (SPI1)` 分支当无关
代码删掉：编译零报错，GD5F 的 DMA 等待在出错时只能干等 `GD5F_SPI_TIMEOUT` 兜底。

**改法（时序一字不动，只换所有权）**：
· 标志收为 GD5F 文件内 `static volatile uint8_t s_spi1_dma_done`（6 处引用同步改名）
· GD5F 导出 `gd5f_spi1_notify_done()` / `gd5f_spi1_notify_error()`，头文件里写明
  "SPI1 分支必须转调这两个函数，否则本模块的 DMA 等待在出错时只能靠超时兜底"
· CH395F 删除裸 `extern`、include `gd5f2gq5ue.h`、两个 SPI1 分支改为转调并就地注明
  "勿删：少了这行 GD5F 的 DMA 出错只能靠超时退出"

`HAL_SPI_AbortCpltCallback`（`HAL_SPI_DMAStop()` 会触发）本次**刻意不做**——它会改
变中止语义、需要真机专项，当前超时兜底可用（已在报告 §0.4 记为观察项）。

**体量代价**：`ch395f.o` −8 B、`gd5f2gq5ue.o` +24 B → `Code` 213,188 → **213,204 B
（+16 B）**，RO/RW/ZI 全不变，`ER_IROM1` 231,768 → **231,784 B（22.1%）**。16 B 换
掉一个静默失效类，划算。

**真机 `@test` PASS**：无 `[ERR]`/Fault，复位原因 software；`[STACK] heap
free=15800 min_ever=8464` 与改前**逐项相同**；各任务实测峰值 default 2152 / net
1116 / ftp 764 / ui 4052 / timesync 616 / adc 952 / iec104 540 / protect 624，
**静态最坏链全部未变**（3024/1912/1456/4052/1264/1320/1456/872）→ 9/9 PASS。

⚠ 记一条读数陷阱：测试脚本打印的 "boot to net init: OK = 7,907 ms" 是采集窗口
锚点造成的度量偏差，真机日志里 `boot: syslog init OK → net init: OK` 实测 ≈699 ms，
与改前一致，**不是性能回退**。

**数字联动**：`data/ram_report_20261022.md`、`data/stack_report_20261022.md` 重跑；
`ram_baseline.py --update/--write`；`check_mem_numbers.py --write`（RAM 方案受管区 +
台账）；`gen_memory_svg.py` 常量更新后重新生成 FLASH 与任务栈两张配图（逐文本按
字号与锚点复查越界 = 0；RAM 图无需变更）；报告 §1.3/§5.1/§5.4、部署文档 §3.3 的
Flash 数字同步；§0.4/§9 的 S-2 口径改为"24 处手写已消 23 处，只剩
`net_socket.c:77`"。

门禁：`@build` 0 错 0 警告；`cubemx-survival --check`、`mem-numbers`、`mem-budget`
（57.4% / 87.9%）、`task-table`、`doc-links --all --sections-strict`（146 文档 0 问题）、
`id-check --strict`（增量拦截通过、可判定 82.83%）全绿；字节卫生 BOM/CR/U+FFFD/尾
空格全清；未提交 UV4 抖动的 `.uvprojx`（本次未被改写）。未推送。
 2026-10-22 19:21:08 +08:00
wandering1 f4b9bd57d5 docs(部署): 删任务栈副本表改指针；纠 CCM/FPU 事实并刷新配图基线 
范围：AGENTS.md 一处指针、部署环境要求 §2.2/§3.1/§3.3、RAM 方案 6 处现状
数字、内存配图生成器 + 3 张 SVG、两份报告脚本的行尾与路径修正、新增两份
.map/.htm 数据快照。未改任何 .c/.h（仍跑 @build 复核：0 错误 0 警告）。

部署环境要求.md
- §3.3 删"任务栈预算"副本表、改为指针：该表已缺 adcTask/iec104Task/
  protectTask，defaultTask/timeSyncTask 两值停在旧数，注释却写"由
  gen_task_table.py 同源"——该钩子的校验面只有 README.md / AGENTS.md
  两处受管块，抄出来的副本没有门禁、改栈后必漂。指针指向 Src/freertos.c
  + 两份受管表 + RAM 方案 §2.3/§0.6，并留一条"别再抄"的成因说明。
- §2.2 链接布局补 `RW_CCM 0x10000000`（scatter 给 0x0000FF00 = 65,280 B，
  2026-10-11 起承载 FreeRTOS 堆；另有 256 B UNINIT_CCM 尾区），写明 CCM
  不可 DMA。原文"SRAM3/CCM 故意未映射"与 STM32F407-Demo.sct 直接矛盾。
- §3.1 MCU 行更正为**单精度 FPU（VFPv4-SP，无硬件双精度）、无 TrustZone**
  （原写"双精度 FPU / TrustZone"是芯片事实错误，也正是报告 F-6 双精度软
  浮点被长期误判的土壤）；SRAM 行改为"两块都在用，仅 SRAM3 未映射"。
- §3.3 资源预算表补 CCM 行，并把"主 SRAM 125,104 B / 95.4% / 极度紧张"
  更正为 75,264 B / 57.4%（余 55,808 B）；红线改标在 CCM（余 7,904 B）。
- 变更记录补 2026-10-22 行（含上一提交里的资源表刷新那一笔）。

AGENTS.md：任务表注里 "RAM使用分析与优化方案.md §1.4" 是**指错小节**——§1.4 确实
存在（该文档 §4「方案」下的阶段 1 子项，讲 lftpd 大局部缓冲静态化），但栈余量
台账在 §2.3（任务栈配置与实测峰值）与 §0.6（静态最坏链与判定），故改指这两处
再加 内存内容分配策略.md §6。根因是该文档里 §1（背景）与 §4 下的 1.1~1.5 同号
撞面，人和 doc-links（自引用放过）都会看错——本会话我上一轮就被它带错过一次。

配图与数据（draw-diagram 流程：改生成器顶部数据 → 重跑 → 逐文本核越界）
- 新增 data/ram_report_20261022.md、data/stack_report_20261022.md；后者
  运行时水位取自 2026-10-22 真机 [STACK] 心跳（8 任务高水位 + heap
  free=15,800 / min_ever=8,464），静态侧来自同日 .htm（全局最深链 3,024 B）。
- gen_memory_svg.py：三组图数据从 2026-09-21 / 10-10 快照换成 2026-10-22
  实测；任务栈 6 → 9 行，堆总量 48KB → 56KB，判定 6/6 → 9/9 PASS，新增
  AboveNormal 配色；Flash 子条改为"窄段不压字 + 下方四列图例"；任务栈
  画布 440 → 620 高。CCM 段总量按 scatter 用 65,280 B（与台账同口径）。
- 三张 SVG 重生成；用"CJK≈1.0em / 其余≈0.58em + 锚点"逐文本估算边界，
  修掉 5 处文字越界/压字（生成器内置 ElementTree 自检亦通过）。
- ram_report.py / stack_report.py 两处工具性修正：write_text 未指定 newline
  参数 → Windows 下把 data/ 快照写成 CRLF（与 .gitattributes 及既有快照
  不符）；stack_report 的 relative_to 在传相对 -i 时抛 ValueError，且会把
  本机绝对路径写进入库快照 → 统一走 resolve+relative_to 的相对路径回退。

RAM 方案：6 处"当前状态"随 .map/[STACK] 更正——RW_IRAM1 89,168 → 75,264、
RW_CCM 49,184 → 57,376、FreeRTOS 堆 48KB → 56KB（两处）、CCM 余量 ~16KB →
7,904 B、min_ever 4,848 → 8,464 B、6 任务全过 → 9/9 PASS；S-1 历史句保留。

门禁：pre-commit 对全部改动文件 Passed（doc-links --sections-strict、
task-table、mem-numbers、mem-budget、id-check 增量拦截）；字节卫生自查
BOM / CR / U+FFFD / 行尾空格全清。已提交本地，未推送。
 2026-10-22 15:08:04 +08:00
wandering1 790e153cd6 fix(adc_input): 丢帧计数改按帧点数累计，与 TPAFE 侧 tgap 同单位 
读码确认的口径缺陷：两片转换器的丢帧计数单位不一致——TPAFE 侧
adc_health_tpafe_gaps() 按 (d-1) 加权记「帧点数」，STM32 侧
adc_input_stm32_gaps() 每次事件只 +1 记「次数」。两者都被当作心跳字段
并排打印（adc1_gap / tgap），一次跨多帧时数值就分叉：同样丢 3 帧，
一边记 2、一边记 1。跨字段对比或做除法会得出错误结论。

选 A（改代码，真对称）而不是只改字段名：
- 单拍超一帧（d=2）时两者数值相同，历史上绝大多数样本本来就等价，
  换单位对既有判读习惯冲击很小；
- 只在一次跨 ≥2 帧时分叉，而那正是心跳日志突发期最常见的形态，
  留在文档里当"注意点"迟早还会读错一次。

改动：
- adc_input.c：s_stm32_gaps += (d - 1u)（d = seq - s_dma_seq_seen，
  顺带把已算过的差值提成局部变量 d，不再重复算一遍）
- adc_input.h / adc_input.c 函数头：单位写明「Σ 每次前进的超出部分」，
  并点名 2026-10-21 之前固件该字段是次数口径，跨版本日志不可直接对比
- 用例：原两档只跨 1 帧（前进 2 记 1），钉不出单位；补第二档——连投
  3 帧不消费（一次跨 2 帧）必须记 2 点、累计 1+2=3。补充断言沿用所属
  用例覆盖点，不另立新编号，也不在文档外复制用例号（编号门禁按文件内
  实例数比对台账豁免，多写一处即被判新债）
- 文档同步：ADC采样节拍设计说明 §8/§9 字段口径与稳态基线、采集与算法
  层设计说明 §3/§4、采样有效性校验设计说明 §6.2/§10/§11（并把"两车道
  单位不同"从观测盲区降级为"历史日志口径差异"）、ADC输入层单元测试
  说明用例表该行；两张配图生成器文案同步

实测：
- @build 0 错 0 警；Program Size 与上一提交**逐字节相同**（Code=213520
  RW=1184 ZI=131504）——编译器早已为半区推导算过同一差值并复用，
  故本次净增 0 B，不产生新的台账漂移
- 主机单测：ADC 输入层 103/103、ADC 有效性 45/45
- stack_report：adcTask 1320 B / protectTask 872 B 均不变
- 字节卫生：BOM 无 / CR 0 / U+FFFD 0 / 文件尾换行齐
- id-check：Passed（曾因新增用例号实例触发"台账之外 +2"，已按不复制
  用例号的方式消除，未动 id_known_backlog.json 台账）

gate: only mem-budget/mem-numbers pending lead ledger backfill
pre-commit run --all-files 失败仅这两条，漂移量来自上一条提交 6f90600
（+96 B Code / +24 B ZI）；本条自身 0 B。按并行分支约定本分支不跑
--write，台账由 Lead 合并后统一回填。
 2026-10-22 00:43:32 +08:00
wandering1 9f826dbb4d fix(protect): 采样陈旧时独立闭锁保护（判定层失明的兜底门） 
问题：L5-4 闭锁读的 adc_health_flags() 只有 adcTask 每拍跑
adc_health_check() 才可能置位。TIM3 一停，adcTask 就永久阻塞在
osThreadFlagsWait（刻意的 fail-safe），check() 不再执行 → stall 位
永远是 0，而 protectTask 仍每 20 ms 拿冻在最后一帧的相量继续判据。
窗口最坏约 800 ms（停喂阈值）+ 2498 ms（IWDG 标称）≈ 3.3 s。

方案：保护侧建一条与消费者存活完全解耦的兜底新鲜度门。
- adc_health.c/h 新增 adc_health_age_stale()：无模块状态的纯判据，
  参照系 adc_health_age_t 由调用方自存。故意不让 protectTask 去调
  adc_health_check()——那是「每拍一次、单写者」的契约，两个上下文
  同写会互相刷新差值基线，把现有判定层一起弄坏。
- 新增 ADC_HF_STALE = bit8（与判定层 bit0..bit7 位段错开）。本位
  不由判定层写、不进 sticky、不进编排层 logged 位图。
- protect_task.c 用自己的时基直接读两个**中断侧递增**的计数器
  （tpafe5160_frame_seq / adc_input_stm32_seq），并入掩码。两条车道
  各自一份 primed：共用会让先观测的那条把标志置 1，另一条首拍拿
  adv_ms = 0 算年龄 → 开机即误锁保护。
- 门限 PROT_STALE_AGE_MS = 100 + 20 = 120 ms，买的是时序阶梯：
  判定层活着时它先报 0x1/0x2（带日志与自检留痕），死了只出现
  0x100。闭锁最迟 140 ms，仍远小于最小动作延时（默认 1000 ms）。

实测：
- @build 0 错 0 警：Code 213424 → 213520（+96 B）；ZI 131480 →
  131504（+24 B = 两份 age 结构）；RW-data 1184 不变
- stack_report：protectTask 静态最坏链 872 B 不变（余 1176 B / 57%）、
  adcTask 1320 B 不变——新判据无日志，不进最坏链
- 主机单测 45/45（新增 TC-ADCHEALTH-012..017 共 14 条断言：首拍只建
  基线 / 超拍不判老 / 门限含等号 / 跨 tick 回绕 / 倒退按分工不判老 /
  双观察者互不污染 / 空参数不判老）
- 台架注入（一次性停 TIM3 300 ms 探针，验完已撤；探针固件与最终
  固件 Program Size 逐字节相同）：
  [+5462ms] [ERR][PROT] sampling FAULT -> protection blocked (hf=0x00000100)
  [+5757ms] [PROT] sampling recovered -> protection resumed
  同次开机 [ADC_TASK] health: 出现 0 次；MISS 快照缺的正是 bit6
  （0x1F7 - 0x1B7 = 0x40，实证 adcTask 当时确实阻塞，不是"在跑但没报"）；
  reset cause: 仅 1 次（300 ms 被 800 ms 容忍吸收，闭锁不靠复位）
  证据 docs/测试说明/boot_log_data/20261021_probe_stale_gate_boot_log.txt
- 字节卫生：BOM 无 / CR 0 / U+FFFD 0；新增行无非法字面量

gate: only mem-budget/mem-numbers pending lead ledger backfill
pre-commit run --all-files 失败仅这两条（台账受管快照与本树 .map 的
Flash/RAM 水位漂移，即本次 +96 B Code、+24 B ZI）。按并行分支约定
本分支不跑 --write，台账由 Lead 合并后统一回填。

文档同步：设计说明新增 §15（原相关文档改 §16），§7 位表加 bit8 行、
§8 责任矩阵与「已知窗口」段改写为已闭合、§10 盲区第 3 条、§11 用例
表、§12 判读手册、§14 改前清单全部跟上；位图配图补 bit8 列，并修掉
生成器把列数硬编码成 8 列导致新列被备注框盖住的问题。
 2026-10-22 00:43:32 +08:00
wandering1 513becd61d docs(algo): 新增 adc_health 单文件深设计与三张配图 
- 新建 docs/算法/采样有效性校验设计说明.md（15 章）：判据推导
  （100 ms 门限的三条独立依据）、电平/锁存/事件三种位语义与
  位号对齐的收益代价、闭锁与 IWDG 兜底责任矩阵、观测盲区、
  主机侧验证分工（11 组 TC / 31 断言映射）、现场判读手册、
  自测问题与改前必读清单
- 配图走 draw-diagram 生成器路线（脚本 + 产物一并提交）：
  tools/arch_diagram/gen_adc_health_flow_svg.py 等三个脚本 →
  docs/images/ 下三张 SVG；文内另有 2 张 Mermaid（判定主干
  flowchart、静默位生命周期 stateDiagram-v2，沿用仓内既有方言）
- 登记与指针：docs/README.md §5.2 加一行 + 变更记录；
  docs/算法/采集与算法层设计说明.md §4 与 §13 加深读指针；
  本文只写「为什么」，接口表仍由该文档属主，不重复
- 读码确认并如实登记三项（本提交不改代码，待裁）：
  1) adc_task_init() 全库无调用点，adc_health_init() 因此不在
     产品路径，判定正确只依赖 .bss 清零 + 首拍建基线
  2) tgap 计帧点数（d-1 加权），adc1_gap 计次数——两侧单位
     不对称，心跳里不可直接对比
  3) TIM3 停摆时判定层随消费者一起停，最坏约 800 ms + 2498 ms
     窗口内 protectTask 仍以旧相量判据（细节见 §10 / §14）
- 门禁自查：pre-commit 目标集全绿（doc-links / id-check /
  空白 / EOF / 大文件）；主机单测 adc_health 31/31 复跑通过；
  9 个新增或改动文件 BOM=无、CR=0、U+FFFD=0
 2026-10-22 00:43:31 +08:00
wandering1 d770e36c7c refactor(NET): 源码注释去阶段化 + 网络两份文档重构 + 不稳根因图更新 
- 源码注释：删去自愈收敛阶段
1/1.5/3等 scaffolding 称谓，改为语义引用
  （E-02 收口 / F-NET-2/3/4 / docs/网络/网络自愈架构设计.md §5.2 E13）；
  涉及 net_socket/.h、net_events、net_listener、net_pending、net_types、
  net_config、ch395f、time_sync、iec104_serv、ui_net_sink、lftpd、
  simulator/sim/net_socket_sim、board/host 测试与探针
- 文档重构：网络自愈架构设计.md 与 Net层阻塞模型架构设计.md 改为现状口径
  （删历史节与阶段叙事），NET/README.md、docs/README.md 同步
- 工具与配图：gen_net_instability_svg.py 与
  docs/images/网络不稳根因总览.svg 随源码口径一并更新
- 门禁：@build 0 错误 0 警告
 2026-10-14 22:05:53 +08:00
wandering1 cea2b51efb docs(架构): 全景/启动顺序/存储/引用图与 README 同步任务面与 NET 内部模块 
- 项目架构总览 v1.1：§1.1 去重复⑥行、硬件行 UART4/TIM3/ADC1；§2.1
  任务表 6→9 行且栈值按 freertos.c 校准；§3 补采集算法链与 TIM3 节拍；
  §5 补 net_events/net_listener/net_pending 与 iec104_serv，单客户端
  恢复窗更正为实测 p50 208ms；§7 目录树、§9 索引、§10 变更记录同步
- 项目启动顺序管理：任务表 5→10 行；启动轨迹表 8→14 行（fw build、
  ADC input layer、phasor/freq/protection、SD2506 明细、TIM3 启动）
- 存储架构说明：§1 初始化顺序块重写（gd5f 归位 app_main_init 内、
  rs485Task 未创建、补 TIM3 与 L1~L3 链）
- 引用关系图说明 §7 统计与产物重跑刷新；就绪屏障 SVG 补 iec104Task
  消费者后重生成（1400x912）
- README：外设引脚纠错（RS485=UART4/PC10/PC11/PA15、TPAFE 控制脚
  PC8/PC9/PC7）、启动流程补 sys_clock/adc_input/TIM3、任务表重生成
  （9 任务）、目录树与 NET 小节同步、ftp_speed_test→regression/
  integrity、文档表补四条专项索引
- 工具：gen_task_table.py 补 iec104Task/protectTask 职责；
  gen_barrier_svg.py 补 iec104Task 消费者与 bit0 计数
 2026-10-14 19:07:48 +08:00
wandering1 0edbfaf08b fix(NET): 监听重建单一所有者收口 + 沉降窗 800ms 上限只留痕
CI / L0 静态门禁 (pre-commit) (push) Failing after 1m12s
Details
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 17s
Details 
T0 降噪 + T1 单一所有者：四处重建触发（recon/accept/eof/drop）与 pending
第五处统一走 net_listener_request()，由 net_listener_tick 单点执行；
沉降重试日志改"只留首末"（E0 口径），每次恢复少打 3 行重复行。

force open 降级为只留痕（E19 反事实 A/B 实测）：芯片未回 CLOSED 时强行
open 注定吃 USE 错（TRAP-NET-09），放行与不放行的端口恢复时刻同一分布
（放行 +512 / 不放行 +505·533 / 降级后 +509 ms）——恢复由芯片何时回
CLOSED 决定。真正兜住"监听器永久失效"的是 D10 预算到期 + 对账形态④
重新登记，不是放行。新增 s_relisten_capped[] 使上限留痕只打一次，
隔离标志不清 → 下一轮继续排空残渣（构建 B 实测每 30ms 两行会刷屏）。

负向注入三轮打靶（E18，注入代码不入库）：形态① 吞掉 DISCONNECT 后
4/4 救回、③ 空闲监听器静默失位两轮独立复现、⑤ 开盲区吞掉芯片自发中断
+ 收回 LISTEN 后 -> resync 命中且挂起 recv 被取消 → 三条均不可降级为
只留痕。顺带稳定复现 [ERR] relisten retry budget exhausted = 对端不配合
拆链的签名，非回归。

台架：boot PASS；ftp_abort_probe RST 10/10 + FIN 5/5；relisten_stress
:21 50/50（p50 507ms）；n30_repro 30/30。构建 0 错 0 警 Code=212316；
netTask 静态最坏链 1920→1912 B；RAM 台账受管区已 --write 同步（RW +8B）。
文档：E17/E18/E19 三行 + §4.1 常态 0 命中归因 + §4.3 兜底归属改正；
登记簿 N-31 销项（结论沉淀进 §4.3 与 E19）。
 2026-10-14 15:57:10 +08:00
wandering1 f849c79b7a feat(NET): SEND pending 二期落地 + 末块挂起越界缺陷修复（台架复测闭环） 
net_pending.c/h 增设第二张挂起表 s_net_send[]（与 recv 表完全独立，收发
互不阻塞）；net_send_locked 快速路径改为有界自旋，单次等待超出
NET_SEND_SPIN_MS(2ms) 即登记挂起 send，由 net_send_pending_tick 按主循环
节拍分块推进，netTask 最坏停滞由 1s 压到 2ms。net_listener_retry_tick 的
挂起保险扩展到 send 侧；net_close_locked / 网络重建 / 状态对账三路均先
取消再动作（取消必通知，调用方永不挂死）。

台架复测（A/B 对照 + 插桩定位）发现并修复末块挂起越界缺陷：内层"等本块
发完(SENBUF_FREE)"位于写块之后，写完末块时 sent 已 == len，若该次等待越过
2ms 预算便会调用 net_send_pending_register，而登记函数按 sent >= len 拒收
并回 -1，把一次实际已完整交付芯片的发送报成失败。修复为内层等待开头判
sent >= len 即跳出（末块已交付、SENBUF_FREE 等待是纯保守自旋），并置于
超时/自旋判定之前；该守卫同时保证后续登记必伴随 sent < len。

复验：ftp_regression 连续 19 次 11/11；ftp_integrity_test 20 轮 x 64KB
STOR/RETR SHA-256 20/20 一致（两轮），吞吐稳定约 80KB/s；设备日志零
write error；ST-LINK 回读 No difference found。

文档：Net层阻塞模型架构设计.md 补二期设计与新增 9.1 缺陷记录，netTask
栈实测峰值按本次台架 920B 订正为 1116/3840（FTP 传输期 1164）；网络自愈
架构设计.md 吸收原监听生命周期文档、新增编号术语导读表，并把 5.2
"实验锚点速查"的 E 编号含义与 E-02 审计编号歧义写在表头（用户反馈该表
E 编号无法读懂）。

门禁：Keil 0 错 0 警；cppcheck / 编码规范 / 乱码零告警；
check_mem_numbers PASS；check_doc_links --all --sections-strict 142 篇 PASS。
 2026-10-14 12:05:21 +08:00
wandering1 df13dec479 refactor(net): 挂起 recv 模型拆出 net_pending.c/h + 留痕探针编译门控 + E15 归因修正
CI / L0 静态门禁 (pre-commit) (push) Failing after 2m14s
Details
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 22s
Details 
- E15 归因修正：幽灵状态 0x04+旧端口 = 芯片如实报告拆除中的旧连接
  （文档化行为，非芯片故障；bit3=1 为我方设置（ver>=0x46）、
  RFC 9293 §3.3.2 Fig5 拆除顺序、WCH 官方博客方案 = close 完成后重开监听）
- 术语统一：全库"了结"→"结束"（约 45 处）；阻塞模型 §4 首次出现处定义"五路"
- 注释清理：删孤儿函数头注释、考古叙事改现在时、去不可检索内部编码"L3"
  （33 处 6 文件）、banner 去重（唯一理由移到分支现场）
- 挂起超时留痕探针：编译期开关 NET_PENDING_TRIPWIRE（默认 0 = 编译剔除，
  省约 150B Flash；排查调用方挂死时置 1，只留痕绝不强制结束）
- 拆模块：net_pending.c/h（363/94 行）承载挂起 recv 模型，
  net_socket.c 4059→3661 行；tick 收控制块表参数、settle_close 双参显式传；
  net_pending_active 声明移配对头（S17 2.2）；仅注册 uvprojx +
  check_registration MCU-only 白名单（同 net_listener.c 机制，
  模拟器走 net_socket_sim.c 按外部语义模拟）
- 文档：阻塞模型新增全过程小节（单主干流程图）+ §9 排查辅助；
  NET README / 函数调用关系 / 自愈架构 / BSD 指南同步；引用关系图重生成
- 台架回归：启动闭环 PASS（[ERR]/Fault 零命中、回读一致）、
  :7003 重连探针 10/10、FTP 50 连接 STOR 50/50、回归窗口串口日志无异常
- RAM：ER_IROM1 230004B（探针门控后约 -150B），台账已回填
 2026-10-14 09:53:38 +08:00
wandering1 a12367981d fix(N34): E14 丢中断复核——芯片不丢事件；listen 排事件挪至 LISTEN 前+全局读收口+全库归因更正 
48 轮直读 SINT 矩阵（8 周期×6 变体）复核历史"丢中断"说法：芯片侧事件
丢失 = 0。归类：drain 读清消费 3/48（drain-int 探针现场抓获）、门控
竞态 2/48、主机同步 1/48、幽灵态 0/48 未复现。

根除性修复：net_listen_locked / net_listener_try 的排事件读清从
listen 后挪至 LISTEN 命令之前——新连接 CONNECT 落进该窗即被本方读清
吞掉，即"数据被吞"的生产侧自伤机制（台架 3/48 为同形态放大版）。

全局读收口：全局中断寄存器唯一读者 = net_poll（I7）；生产/测试/台架
游离全局读全部删除，ch395f.h 声明处加护栏注释。

归因更正：17 文件约 40 处"丢中断"措辞改为"事件未收到/读清消费竞态"
（机制全部保留，仅归因更正）；设计文档 §5.2 新增 E14 锚点；Trap
Records TRAP-NET-17/-20/B3 归因更正段；配图生成器与 SVG 重生成。

台架：事件未收到复核探针保留（drain-int / SINT 补读×3 / 超时归类），
下次跑矩阵自动归类；实验注册（main.c/uvprojx）已完全还原。

验证：@build 0 错误 0 警告；ci_local L0 32/0 + gitlint + L0.5
953/953；doc-links --all --sections-strict 通过；@test PASS（无
[ERR]，net init 619ms）；回归 :7003 300ms×10 = 10/10、:21 n30×50 =
0/50 失败。
 2026-10-14 02:48:50 +08:00
wandering1 1a35b3684c docs(N34): 自愈审计目录 7 份文档合并为单文档，全库引用同步
CI / L0 静态门禁 (pre-commit) (push) Failing after 44s
Details
CI / L0.5 主机侧单测 (MSVC) (push) Failing after 43s
Details 
- `docs/网络/N34-自愈审计/` 目录 7 份文档（根因总览 / net 层盘点 /
  驱动层审计 / 主流对照 / 汇总裁决 / 实施方案 / 实验方案）合并为
  `docs/网络/N34-自愈审计.md`（§0~§6），原目录删除；docs/README.md
  索引与变更日志登记归档
- 全库引用同步：4 篇文档 + 驱动/NET/test 代码注释 + 配图生成器与 SVG
- 内容零丢失抽查：E0~E13 实验记录、E6 裁决（命中=0 不立项）、
  提交表（含 `925058a` 收口行）均在位
- 门禁：@build 0/0（注释级路径更新）；check_doc_links --all 143 文档
  通过（净 −6 = 删 7 增 1 吻合）；ci_local L0+L0.5 全绿
 2026-10-13 23:23:55 +08:00
wandering1 925058a5ae fix(NET)+docs: lftpd 对端地址修复、E6 裁决收口、陷阱编号迁移重排 TRAP-NET-01~21 
- lftpd：net_inet_ntoa 段序改 MSB 首 + 新增 net_getpeername，FTP 日志打印
  真实对端地址（真机实证 192.168.1.2:55524，登记 TRAP-NET-21）
- E6：NET_U15_PROBE 命中=0（含压测）→ 阶段 3 项 4 不立项，U15 登记观察项；
  插桩留仓（宏=0 零成本），soak 驱动 test/host/e6_soak.py 入库
- 编号：全库 Trap NN → TRAP-NET-<nn> 迁移并重排连续 01~21（单调映射，
  沿革见 CH395F_Trap_Records.md 头注）；死号 12/13/19/21 引用全部清除；
  GD5F 域引用补正为 TRAP-GD5F-NN
- 陷阱文档全新化：索引 21 行行行真陷阱；删误判存档/发现时间/git 考古/
  FTP 附录；台架纪律教训沉淀第六章方法论
- RAM：Code 211348→211456（+108 lftpd 修复），RW+ZI 净增 +4B；
  优化方案/台账受管区/tsv 同笔同步
- ftp_abort_probe.py 挪 test/host/；引用关系图重生成
- 回归：@build 0/0；@test PASS；ftp_abort 10/10；relisten :7003 20/20；
  ci_local L0+L0.5 全绿；E6 窗口零复位，7 条 WD stall 登记压测假象备查
 2026-10-13 20:54:31 +08:00
wandering1 c7459b393f docs(N34): 网络不稳根因复盘总览（比喻版）+ 全景图 SVG 生成器 
- 新增 网络不稳根因总览.md：七个误会（传达室比喻+机制+证据出处）→
  环↔拆法↔落点对照表 → E13 僵尸会话 Mermaid 时序图 → 一句话总结
- 新增 tools/arch_diagram/gen_net_instability_svg.py（draw-diagram 规范，
  纯标准库）与产物 docs/images/网络不稳根因总览.svg（headless Edge 目检两轮）
- N34 README：实施状态表补全阶段 1.5/2/3 与 E6 插桩行（原「阶段 2/3
  未开始」陈旧口径修正）；挂复盘总览为第一入口；§5.56 改紧邻写法
- 门禁：check_doc_links --sections-strict 本批 4 文件通过
 2026-10-13 17:12:36 +08:00
wandering1 c9aa12e8bd fix(arch_diagram): 生成器自写尾换行（gen_net_pending/gen_memory） 
gen_*.py 里 8 个已自带尾换行（'...</svg>\n'），仅
gen_net_pending_svg.py 少一个尾 \n → 每次重跑都被 pre-commit 的
end-of-file-fixer 补回，产生无意义的 1 行尾差异。

- gen_net_pending_svg.py: return "\n".join(svg) + "\n"，
  并把 open(...) 补 newline="\n"（与其余生成器一致）
- gen_memory_svg.py: open(...) 补 newline="\n"（输出本已带尾换行）

重跑验证：Net层阻塞模型.svg 与已提交 blob 逐字节一致
（hash-object --path 相同、git diff 为空）；内存 3 张 SVG 亦无差异。
 2026-10-12 19:26:28 +08:00
wandering1 01b9a90f45 docs(net): 同步 docs/网络 之外残留旧函数名（测试说明 + 生成图） 
docs/网络/ 主体已在 1a17d73 更新。自查发现两处「现状性」引用
仍用旧函数名（历史记录类保持原样，不改）：

- docs/测试说明/链路延迟测试说明.md §8 D10 排障行：
  net_relisten_try/retry_tick → net_listener_try/retry_tick
- tools/arch_diagram/gen_net_pending_svg.py 主循环标签
  net_relisten_retry_tick() → net_listener_retry_tick()，并重跑
  生成 docs/images/Net层阻塞模型.svg（该图被 Net层阻塞模型架构设计.md 内嵌）
 2026-10-12 19:18:38 +08:00
wandering1 0779d3a075 栈整改不抬栈：删旧档迁移、FIL静态化、日志行缓冲按模块收紧、钩子脱离HAL，defaultTask链5312→2776B 2026-10-10 10:17:00 +08:00
wandering1 0ac68605dd 看门狗 §3.2 流程图重绘为 SVG：任务置位→校验者判定→喂狗 + 时间轴 2026-10-01 06:35:57 +08:00
wandering1 0ddf8c9aca Net 层阻塞模型架构设计 §2 架构总览改用 SVG 矢量图 2026-09-29 06:00:48 +08:00
wandering1 22559365b9 整理 App 与 test 目录：按职责分子目录并同步全库引用 2026-09-26 12:52:39 +08:00
wandering1 39bd06adea 为自建代码目录补齐 README，建立目录级导航体系 
- 新增 26 份目录 README：App/(+log,task,util,protocol)、Drivers/BSP/(+8子系统)、
  Src/、Inc/、scripts/、tools/(+6子工具)、test/、MDK-ARM/、simulator/(+sim,tests)
- 每份含：定位、文件清单表、关键约束/陷阱、指向 docs 权威文档
- 第三方库与生成代码目录排除（CMSIS/HAL/Middlewares/Lib/SDL2）
- docs/文档规范.md 新增 §1.1b 代码目录 README 约定；根 README 目录结构加入说明
 2026-09-26 12:25:36 +08:00
wandering1 a6cdebde62 文档体系重组与 D-7 一致性门禁落地，清理芯片手册孤儿图片 
- D-6 目录规范化：docs 根目录散落文档归入 UI设计/子系统设计/架构设计/审查记录/
  环境与部署/网络 等子目录，去掉目录名空格，重命名 嵌入式C语言代码规范_V1.0.md
- D-7 三档一致性门禁：新增 scripts/check_doc_links.py（链接存在性）、
  scripts/gen_task_table.py（FreeRTOS 任务表数值）、scripts/check_mem_numbers.py
  （内存/Flash 体积），均支持 --check/--write/--diff，pre-commit 钩子同步注册
- D-5 文档索引：新建 docs/README.md，新建 docs/文档规范.md 约束目录命名与链接写法
- D-1 芯片手册瘦身：删除 1069 张无引用孤儿图片（77.06 MB），
  docs/芯片手册 120 MB → 41 MB，已引用图片零断链
- 同步 C 源码注释中的文档路径引用（D-6 重组后），构建 0 错误 0 警告
 2026-09-26 00:51:53 +08:00
wandering1 96855f6b6b 内存布局图更新到09-21最新：任务栈预算含实测峰值与判定，RAM双区/Flash布局同步 2026-09-21 05:10:01 +08:00
wandering1 1817fe792f 就绪屏障与配置引擎重构，新增串口助手、V0.0网表分析报告及芯片手册，同步更新文档 2026-09-15 21:13:20 +08:00
wandering1 97661415ca 通用配置文件 P1–P3：设计文档、FS 并发 A+ 定案、FatFs 墙钟接入、cfg_file 双端引擎与 net_cfg 集成（旧档 NCFG 首启迁移） 2026-09-14 02:15:49 +08:00
wandering1 cf2597f998 恢复 BSD Socket API 使用指南（4e9ac0d 误删）：同步当前 API，补分层架构图/状态机/时序图与 §2.3 模拟器端说明，README 索引补登 2026-09-13 20:55:58 +08:00
wandering1 342269fbd0 新增内存使用分析文档（报告/规划/优化建议）与 SVG 布局图生成脚本 2026-09-13 17:05:55 +08:00
wandering1 7e527fa04d 清理存量 ASCII 框图：存储栈/分区转 SVG、CH395F 时序转 Mermaid 2026-09-11 23:01:25 +08:00
wandering1 2429955d1a 绘图流程沉淀为 draw-diagram skill，SVG 收拢到 docs/images/ 2026-09-11 21:15:39 +08:00
wandering1 4515ee4c80 修复了网络参数的保存逻辑 2026-09-10 14:21:07 +08:00