refactor(task): 19 处任务句柄裸 extern 收拢为 task_handles.h 引用契约

推荐清单第 3 步（结构债 S-2 剩余面），用户批准"按你推荐做"。

新建 `App/task/task_handles.h`——**只有声明、没有 `.c`**：头文件不需要双端注册，
且 `../App/task` 本来就在 uvprojx 的 `<IncludePath>` 里，所以这一步零构建面。

- `App/task/default_task.c:52-69` 的 18 行局部 extern（9 个句柄 + 9 个 attributes）
  删除，改 include；栈水位观测用的任务清单表本体仍留在该文件
- `App/task/adc_task.c:125` 的 1 行同法收口
- `Src/main.c` 函数内的 `extern volatile uint32_t g_rcc_csr_latched;` 移进
  `App/app/app_main.h`（`main.c` 本来就 include 它），USER CODE 区内只留"读
  RCC_CSR → 写 RMVF 清除"两句，顺序约束的原注释保留

为什么值得做：原先每加一个任务都得记得往 `default_task.c` 再抄两行 extern，抄
漏一行 = 读别人的栈（静默，无报错）。现在只有一个改动点；而且 CubeMX 若把句柄
改名，报错会落在链接期而不是静默通过。

**镜像逐项体积不变**：`Code=213,188 RO-data=18,580 RW-data=1,184
ZI-data=131,504`，`@build` 0 错 0 警告 → 行为中性。

`check_cubemx_survival.py` 对这次有意的 USER CODE 区改动报"漂移"，已按其文档流程
`--write` 重建基线（`.cubemx_survival_baseline.json` 仅 1 个指纹变化；顺手把该脚本
写文件带来的 CRLF 归一回 LF，符合 `* text=auto eol=lf`），`--check` 复跑通过、易失
清单 29 项全部到位。

报告 §0.4/§9 的 S-2 口径同时改成**精确分类**：该修的手写跨模块裸 extern **24 处，
今天已消 22 处，只剩 2 处**（`ch395f.c:177` 的 `g_spi1_dma_done` 与 `net_socket.c:77`
的 `netMsgQueueHandle`）；`stm32f4xx_it.c:241-256` 那 16 条是 CubeMX「External
variables」生成块（删了会被重生成写回来，**不算债**），`:183/195/207/220` 那 4 条
是手写在 `__asm` Handler 里引用汇编标签（ARMCC `__asm` 取不到 C 数据符号，
**合法例外**）。上一版写的"25 处"把这三类混在一起了，一并更正。另更正 §0.4 的
S-1 一格：不是"运行时属主纪律被破"（UI 只投递 `net_cfg_save_request()`，写盘在
defaultTask），也不是"进不了主机侧单测"（模拟器已跑整条链），要修的只是静态分层
方向。

门禁：`@build` 0/0；`cubemx-survival --check` 通过；`check_doc_links.py --all
--sections-strict` 146 文档 0 问题；`check_ids.py --strict` 增量拦截通过、可判定
82.83%；`mem-numbers` 0。字节卫生：新增头文件与各改动文件 BOM 无 / CR 0 /
U+FFFD 0。未推送。

docs/问题记录/项目审查与优化建议报告.md

@@ -48,8 +48,8 @@
 | 内存 RAM | R-2 剩余 / R-3 / R-4 / R-6 ⏸（N-27） | 待迁体量 29,570 B，而 CCM 只剩 7,904 B → 搬迁已无空间收益 | 暂缓；重开条件 §5.3 |
 | 内存 RAM | N-14 🟡（N-22） | FTL 单页写回缓存无空闲/掉电强制 flush（整页写与换页已 flush，`f_close` 经 `CTRL_SYNC` 已落盘） | 用户裁定 2026-10-22 暂不做；残余窗口只是"单条记录" |
 | Flash | **F-5 🟡 观察项**（N-28） | uvprojx 201 个 LVGL `.c` 里 **127 个空 TU**；增量构建 4~5 s、CI 不跑 `@build` | 有实测全量耗时痛点再做，用 `<IncludeInBuild>` |
-| 结构 | **S-1 ❌**（口径已按实测更正） | **不是"命名错位"，是真实的 BSP→App 反向依赖**：`Drivers/BSP/NETCFG/{net_cfg,ftp_cfg}.c` include `App/cfg/cfg_file.h`（10 处调用点：`cfg_file_load/save/poll/register`），`Drivers/BSP/UI` 另有 3 个文件 include App 层头（`ui_page_runlog.c`、`ui_page_selftest.c`、`ui_w_records.h`）；21 个 BSP 文件用 `dbg_log.h`（横切，待显式豁免） | **反转依赖**（约 7 文件 / 15 处；NETCFG 去掉 `cfg_file.h` 后还能进主机侧单测）+ 加一条「`Drivers/BSP/**` 不得 include `App/**`」的门禁；**目录搬迁暂缓**（远程 CI 仍不跑 `@build`，兜底未成立） |
-| 结构 | **S-2 ❌**（实测 **25 处**，旧写「4 处」低估） | 原 4 处全部仍在，其中 `ch395f.c:177` 最危险：CH395F 裸写 GD5F 的 `g_spi1_dma_done`，并在 `HAL_SPI_ErrorCallback` 的 SPI1 分支里**替 GD5F 释放等待者**——谁清理那两行「看着无关」的分支，编译零报错，GD5F 的 DMA 出错就退化成干等 `GD5F_SPI_TIMEOUT`；`HAL_SPI_AbortCpltCallback`（`HAL_SPI_DMAStop` 会触发）无人实现。新增实测面：`App/task/default_task.c:52-69` 18 行任务句柄/属性 extern（看门狗用的任务清单表）、`adc_task.c:125`、`Src/main.c:115`、`Src/stm32f4xx_it.c` 2 处；其中 `fault_entry_hard` 属 ARMCC `__asm` **合法例外** | 四步：① ~~删冗余 extern~~ ✅ 已做 2 处（2026-10-22）② SPI 完成/错误/中止回调**归属拆清**（GD5F 导出 `gd5f_spi1_notify_*`，CH395F 只转发）③ 建 `App/task/task_registry.h` 集中消掉 19 行 ④ `netMsgQueueHandle` 收口 |
+| 结构 | **S-1 ❌**（口径已按实测更正） | **不是"命名错位"，是真实的 BSP→App 反向依赖**：`Drivers/BSP/NETCFG/{net_cfg,ftp_cfg}.c` include `App/cfg/cfg_file.h`（10 处调用点：`cfg_file_load/save/poll/register`），`Drivers/BSP/UI` 另有 3 个文件 include App 层头（`ui_page_runlog.c`、`ui_page_selftest.c`、`ui_w_records.h`）；21 个 BSP 文件用 `dbg_log.h`（横切，待显式豁免） | **反转依赖**（约 7 文件 / 15 处）。⚠ 修正一条我先前写下的理由：这不是"运行时属主纪律被破"——UI 只投递 `net_cfg_save_request()`，写盘仍在 defaultTask，且 NETCFG 已有 `net_cfg_set_save_req_cb` / `net_cfg_request_apply` 的**回调注入**先例；也不是"测不了"——模拟器今天就在主机侧跑 `net_cfg_load → poll → save` 整条链（`../../simulator/README.md` 的验证链）。要修的只是**静态分层方向**（BSP 引用了 App 的头）+ 加一条「`Drivers/BSP/**` 不得 include `App/**`」的门禁；**目录搬迁暂缓**（远程 CI 仍不跑 `@build`，兜底未成立） |
+| 结构 | **S-2 大半已消**（24 处手写已消 22 处） | **该修的手写跨模块裸 `extern` 共 24 处，今天已消 22 处，只剩 2 处**：`ch395f.c:177`（CH395F 裸写 GD5F 的 `g_spi1_dma_done`，还在 `HAL_SPI_ErrorCallback` 的 SPI1 分支里**替 GD5F 释放等待者**——谁清理那两行「看着无关」的分支，编译零报错，GD5F 的 DMA 出错就退化成干等 `GD5F_SPI_TIMEOUT`）与 `net_socket.c:77`（`netMsgQueueHandle` 跨文件裸引）。已消的 22 处 = 2 处与 `Inc/spi.h` / `Inc/i2c.h` 重复（GD5F/SD2506）+ 19 处任务句柄与属性（`default_task.c:52-69` 的 18 行 + `adc_task.c:125`）+ 1 处 `main.c` 函数内的 `g_rcc_csr_latched`。**两类不算债要分清**：`stm32f4xx_it.c:241-256` 那 16 条是 CubeMX「External variables」生成块（删了会被重生成写回来）；`:183/195/207/220` 那 4 条是手写在 `__asm` Handler 里引用汇编标签 `fault_entry_*`（ARMCC `__asm` 取不到 C 数据符号，**合法例外**）。上一版写的「25 处」把这两类混进来了，已更正 | 剩余两步：① `ch395f.c` 改为经 GD5F 导出的 `gd5f_spi1_notify_done()` / `notify_error()` 转调（标志收回 GD5F 内部）② `netMsgQueueHandle` 收进 net_socket 内部 + 提供投递 API |
 | 驱动规范 | S-5 ❌ | `bsp_err_t` 至今只出现在本报告里（无统一错误码/超时/重试约定） | 定义后进 `docs/代码规范/` |
 | 网络 | N-09 / PHY ❌（N-25） | `NET_MAX_SOCKETS` 仍为 8（与单连接复用语义不符）；PHY 强制 100M 无自协商回退；PASV 每次新建监听 | 见 §4.2；随 N-25 一并处置 |
 | 存储 | N-15 🟡（N-25） | `nand_ftl.o` 静态 6,216 B——三块 2 KB 级页缓冲并存未合并 | 与 R-3 同批评估 |
@@ -374,7 +374,7 @@ W6 簇按 U4 → U1 → U3 → U2 的顺序执行完毕（U2 停在"够用即止
 | **D-1** | 外部资料与工程文档同仓同树 | ❌ 暂不处理 | 本文 §3.3、登记簿 N-29 |
 | D-2 ~ D-7 | 文档治理条目（链接/同源/编号/BOM 等） | ✅ 多数已制度化为钩子 | 本文 §3.2、`../文档规范.md` |
 | D-9 | 文档面残余观察 | 🟡 观察 | 本节即定义位 |
-| **S-1 / S-2** | 分层反向依赖 / 跨模块裸 `extern` | ❌ 在策（2026-10-22 实测：S-1 = NETCFG+UI 共 7 文件 15 处；S-2 = 25 处，含 1 处合法例外） | 本文 §0.4、登记簿 C5 |
+| **S-1 / S-2** | 分层反向依赖 / 跨模块裸 `extern` | 🟡 半办（2026-10-22：S-2 的 24 处手写已消 22 处、剩 2 处；S-1 未动 = NETCFG+UI 反向 include） | 本文 §0.4、登记簿 C5 |
 | **S-4** | `app_cfg.h` 未接线占位开关 | ✅ **已闭环 2026-10-22**（4 个零消费点宏删除） | `App/app/app_cfg.h` 修改记录 v1.2；口径同步见 `../环境与部署/项目部署环境要求.md` §3.2/§3.5、`../产品需求/产品需求设计文档.md`、`../任务规划/排期详述.md` C5 |
 | **S-3** | `.ioc` 侧 USART1 配置 | ❌ 在策 | 登记簿 S-3 |
 | **S-5** | 统一 `bsp_err_t` 错误码约定 | ❌ 未做 | 本文 §0.4、`docs/代码规范/`（待建） |
@@ -409,6 +409,8 @@ W6 簇按 U4 → U1 → U3 → U2 的顺序执行完毕（U2 停在"够用即止
 **改判的三条旧结论**：① §6 的 U1/U3/U4 原写「❌ 未建」，实际已落地（`ui_tokens.h` 69 行、`ui_page_registry.c` 描述符注册表、`ui-golden`+`font-charset` 两枚钩子）；U2 只有 `ui_w_records` 一个组件；"27 页未落地"实为 7 页。② "新增一页 ≤30 行"目标**未达**（最省 40 行），如实记为未达项。③ §0.4 与登记簿已漂开 → 本版把待办清单降级为**快照 + 指向登记簿**，权威只留一处。
 **刻意保留的三层**（删了会出事）：§9 **编号族登记处**——本文是 `id_registry.json` 里 `N-RPT`/`D-RPT`/`S-RPT`/`R-RPT`(游标 R-9)/`F-RPT`/`U-RPT`(游标 U5) 六族的属主登记处，且外部存在「报告 N-14」「报告 F-4/F-5/F-6」「报告 D-1」「报告 R-2/R-3」式紧邻引用与 `check_dangling`，删定义位即触发编号门禁；§1.2/§1.3 方法与口径（数字可重跑）；文末**变更记录 + 已销项去处表**原样冻结保留（52 行）。被外部点名的锚点（`§0.3`/`§3.1`/`§4.1`/`§4.2`/`§4.3`/`§5.3`×9/`§5.4`/`§5.5`×4/`§6.2`/`§6.3`/`§6.5`）逐个保留，**68 处入站引用零改动**。
 **门禁**：`check_doc_links.py --all --sections-strict` → 146 文档 0 问题（章节引用 2,499、可判定 1,483）；`check_ids.py --strict` 增量拦截通过、**存量债 650 → 641（−9）**、可判定比例 82.98% → **82.79%**（仍高于基线 82.6%，但缓冲从 0.38pp 缩到 0.19pp——删掉的那批引用 99% 是可判定的，属预期副作用）；`mem-numbers` / `ram_baseline --gate` / `task-table` / `cubemx-survival` 全 0。字节卫生：BOM 无 / CR 0 / U+FFFD 0 / 无行尾空格 / LF 结尾。 |
+| **2026-10-22** | **S-2 第二步：19 处任务句柄裸 extern 收拢成引用契约**（推荐清单第 3 步） | 新建 `App/task/task_handles.h`——**只有声明、没有 `.c`**：头文件不需要双端注册，`../App/task` 本来就在 uvprojx 的 `<IncludePath>` 里，所以这一步零构建面。`default_task.c:52-69` 的 18 行 + `adc_task.c:125` 的 1 行局部 extern 全部删除改 include（栈水位表本体仍留在 `default_task.c`）；同批把 `Src/main.c` 函数内的 `extern volatile uint32_t g_rcc_csr_latched;` 移进 `App/app/app_main.h`（该文件 `main.c` 本来就 include），
+USER CODE 区内只留「读 RCC_CSR → 写 RMVF 清除」两句、顺序约束的原注释保留。**价值**：原先每加一个任务都得记得往 `default_task.c` 再抄两行 extern，抄漏一行 = 读别人的栈（静默）；现在只有一个改动点，且 CubeMX 若把句柄改名会在链接期报错而不是静默通过。**镜像逐项体积不变**（`Code=213,188 RO=18,580 RW=1,184 ZI=131,504`，`@build` 0 错 0 警告）证明行为中性。`check_cubemx_survival.py` 对这次有意的 USER CODE 区改动报「漂移」，已按其文档流程 `--write`重建基线（`.cubemx_survival_baseline.json` 仅 1 行变化），`--check` 复跑通过、易失清单 29 项全部到位；顺带把 §0.4 的 S-2 口径改成精确分类：**手写该修 24 处（已消 22）+ CubeMX 生成块 16 条（不算债）+ `__asm` 汇编标签 4 条（合法例外）**——上一版「25 处」混了这三类。 |
 | **2026-10-22** | **结构债 S-4 闭环 + S-2 第一步（用户批准「先只跑 1+2」）** | **S-4**：删除 `App/app/app_cfg.h` 里 4 个**零消费点**宏（`APP_NET_ENABLE`/`APP_ADC_ENABLE`/`APP_RS485_ENABLE`/`APP_SYS_TIME_SRC`），文件降格为「决策占位说明」——修改记录 v1.2 写明为什么删与将来怎么接回；并去掉 `app_main.c` 里只为它存在的 include。留「看着能裁剪、其实不生效」的宏比不留更糟：它不产生任何编译期效果，却让评审误信模块可裁剪；此前为了说明它，AGENTS 之外还得在 6 处文档各写一句「未接线占位，别当开关用」。同步改口径 **17 处**：`App/app/README.md`、`App/README.md`、根 `README.md`、`项目架构总览.md`、`项目部署环境要求.md`（§3.2 两行 + 配置表一行）、`产品需求设计文档.md`（B0 结论 + 配置表）、`基线与待确认.md`、`排期详述.md` C5、`登记簿.md` N-23 残余、`RAM使用分析与优化方案.md` 三处。
 |  | **顺带纠出另一个不存在的宏**：`RAM使用分析与优化方案.md` 把 `APP_CCM_ENABLE` 写成「加在 `App/app/app_cfg.h`」，实际从来没有落地（全库仅该文档提及）——已就地标注「未实现，重开本簇时一起落地」，避免下一个读者以为 CCM 有回退开关。
 |  | **S-2 第一步（实测纠偏）**：删掉 `gd5f2gq5ue.c:47`、`sd2506.c:20` 两处与 `Inc/spi.h`/`Inc/i2c.h` 重复的 `extern`，GD5F 改 `#include "spi.h"`（沿用 `ch395f.c:22` 的既有做法）。**镜像逐字节不变**：`Code=213,188 RO=18,580 RW=1,184 ZI=131,504` 与改动前完全相同，`@build` 0 错 0 警告 → 证明这两步是行为中性的。同时把 §0.4/§9 的旧口径换成实测值：**S-2 不是 4 处而是 25 处**（`App/task/default_task.c:52-69` 一次就有 18 行；`stm32f4xx_it.c` 的 `fault_entry_hard` 属 ARMCC `__asm` 合法例外，不该「修」），**S-1 不是语义错位而是真实反向依赖**（NETCFG include `App/cfg/cfg_file.h` 10 处 + UI 3 个文件）。**这两个旧数字是我 v3.0 重写时沿用未测，一并认错。** SPI 回调归属这条隐患（CH395F 替 GD5F 释放错误路径）目前只在本文 §0.4 留了痕，**尚未进登记簿**——要不要立项等你定。 |