docs(S-5): 补齐 16 条返回值约定，bsp-err 基线 19 → 1，并修门禁自身误判

A（还债）先行，B（GD5F 的 SPI 失败被吞成成功）另波处理。本笔不改行为：@build 的
Program Size 与上一笔逐字段相同（Code 213,648、RO 18,860、RW 1,188、ZI 131,500）。

**补齐 16 条「返回值：」约定，bsp-err 存量基线 19 → 1**：
· gd5f2gq5ue.h 九个 SPI 原语（wait_busy / write_enable / read_status / page_read /
  read_from_cache / program_load / program_exec / block_erase / check_ecc）
  写全规范五要素，
  并把**每个函数能返回哪些码**写死：哪一个是"可重试"的 GD5F_WAIT_EXPIRED、哪一个才是
  器件自认坏块的 P_FAIL/E_FAIL、失败时出参为什么不可信（E-42 同族）。
· nand_ftl.h 从零散三行补成带模块头，并明写 **nand_ftl_init() 的 −1 抹掉了失败类**：
  分类目前只在失败点进日志，要按类分支需要 C4 快照（现无消费者故未做）；同时警告"不得
  把 −1 解读成卷坏了可以重格式化"（E-31 的教训正在这条上）。
· ui_menu_tab.h 五个表查询 API 由行尾短注释升级为完整块（含"越界返回 false 是保守取
  只读"、"宁可按一张错表导航失败也不要按错表导航成功"这类判断依据）。

**修掉门禁自己的一条误判口径**（本笔最该记的）：R3 原本要求紧邻注释块里出现字面"返回值"，
而规范 V1.0 允许列对齐写法「返 回 值：」。后果有两层：① 合规写法被判违规；② 反向更糟——
gd5f_write_enable / gd5f_read_status 两条**早就"通过"了**，原因竟是它们的**函数说明**里顺口
写了"返回值"三个字，而不是真有一行返回值说明。**一条会因为散文里出现关键词而放行的规则，
等于在奖励运气**。修法是在块内忽略空格后再匹配关键词（排版选择不是违规），并在注释里写明
为什么不许把"必须写成不空格的形式"写进规则。

剩余 1 条刻意保留：bool ui_content_page_open()。它与"补注释"不是一档事——要改签名、要处理
3 个调用点（ui_menu.c:138/192/196 **今天三处全部丢弃返回值**，即"按 ENTER 开页失败是静默的"
这件事现在没人知道）、且 UI 源码双端编译（模拟器同一份），验证面是"重建模拟器 + 像素回归 +
真机逐页进菜单"。这不是还债，是独立一波改动，留档待决策。UI 三个文件带 BOM，Edit 会静默
剥掉 → 已按原样补回 3 字节（AGENTS 铁律：丢 BOM 后 ARMCC 按 CP936 解码，中文报 #870-D）。

**更正我自己写进文档的一条错话**：S-5 各条里我把 GD5F_SPI_TIMEOUT 100 记成"自旋圈数（改
分频时长会变）"。这次逐行核它 12 处用法，**全部是 HAL_* 超时参数或 HAL_GetTick() 差值 →
它也是毫秒**。真问题降级为"单位没写进名字（缺 _MS 后缀），读代码必须回实现里查单位"。
osWaitForever 与 HAL_MAX_DELAY 同为 0xFFFFFFFFU、以及 *_BUSY_TIMEOUT = -2 其实是返回码这两条
仍然成立（后者已改）。现状类条目（报告 §0.4、bsp_err.h、pre-commit使用说明.md §2.27、脚本
文件头）已全部改准；**已提交的变更记录行仍写着旧说法——按 §8.1 冻结历史不回改，以本笔新增
的更正行为准**。

验证：@build 0 错 0 警告（尺寸同上，故**不跑 @test**——无指令变化，跑它没有新信息）；受影响
文件的 17 个钩子全 Passed（含 ui-golden 像素回归、cppcheck、编码规范、bsp-err 1/1/0 且
--prune 干净）；check_doc_links --all --sections-strict 147 篇 0 问题；id-check
  --strict 通过；
9 个文件字节卫生 0 异常（UI 头 BOM 仍在、无 CR、无 U+FFFD、无行尾空格、均有尾换行）。
口径同步：AGENTS.md、.pre-commit-config.yaml、pre-commit使用说明.md §2.27 的基线计数 19 → 1；
报告 §0.4 / §9 / 附录 A 与变更记录两条（还债一条、更正一条）。

docs/代码规范/pre-commit使用说明.md

@@ -481,8 +481,8 @@ cppcheck 是开源 C/C++ 静态分析工具，**不运行代码**，通过语法
 | **为什么需要** | 报告原文说"无统一错误码"，实测更准的说法是**六套并存**：0/−1（SD2506、NETCFG、nand_ftl）、`int32_t`；
 自研枚举（`CH395F_STATUS_*`）、芯片寄存器原生码（`CH395F_ERR_*`，与前一套同模块并存）、
 `HAL_StatusTypeDef`（`rs485.h` 曾直接暴露）、`bool`，外加第三方 dhara 的出参 `dhara_error_t`
-与 FatFs 的 `FRESULT`。超时侧更乱：**同形两义**的 `*_TIMEOUT` 有四个（毫秒 / 自旋圈数 /
-其实是返回码），`osWaitForever` 与 `HAL_MAX_DELAY` 又**同为 0xFFFFFFFFU**（值同域不同，
+与 FatFs 的 `FRESULT`。超时侧更乱：**同名形状装三种东西**——真毫秒但带不带 `_MS` 后缀不统一（`SD2506_I2C_TIMEOUT_MS` vs
+`GD5F_SPI_TIMEOUT`，后者逐行核过也是毫秒）、以及叫 `*_TIMEOUT` 其实是**返回码**的，`osWaitForever` 与 `HAL_MAX_DELAY` 又**同为 0xFFFFFFFFU**（值同域不同，
 跨层转手既不报错也不变慢）。**没有机械检查的约定等于没有约定**（分层方向那条的教训） |
 | **约定正文在哪** | `Drivers/BSP/bsp_err.h`（**header-only，无 `.c`** → 不占体积、不需双端注册）。
 `0 = BSP_OK`、负值失败、`BSP_ERR_CAN_RETRY(e)` 把"能不能重试"变成跨模块可判定（这是本契约
@@ -495,7 +495,8 @@ cppcheck 是开源 C/C++ 静态分析工具，**不运行代码**，通过语法
 它的 `226/425/450/550` 是 FTP 协议码不是内部错误码；**`net_*` BSD 兼容层不纳入**（用户裁定
 2026-10-23）：调用方要的就是"返回字节数 + 每任务 errno 槽"那个形状，模拟器的 Winsock
 后端也照同一形状实现 |
-| **增量拦截** | 存量 **17 条**（首清点 19，2026-10-23 C1 还掉 2）钉 `BASELINE`（一个 `bool ui_content_page_open()` + 16 个缺「返回值：」），**只减不增**、脚本没有 `--write`；修完跑 `--prune` 会点名"这条已消失，
+| **增量拦截** | 存量 **1 条**（首清点 19，2026-10-23 已还 18）钉 `BASELINE`（首清点 19 条：2 个 `*_BUSY_TIMEOUT = -2` + 16 个缺「返回值：」+ 1 个 bool；**现仅剩
+`bool ui_content_page_open()` 一条**——它需要改签名并处理 3 个调用点，与"还注释"不是一档事），**只减不增**、脚本没有 `--write`；修完跑 `--prune` 会点名"这条已消失，
 请从基线删除" |
 | **配置** | `files: ^Drivers/BSP/\|^scripts/check_bsp_err\.py$\|^\.pre-commit-config\.yaml$`、
 `pass_filenames: false`（恒扫全库，要按 git 清单建公开头索引） |

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

@@ -55,7 +55,7 @@
 `net_msg_queue_adopt()` 绑定（创建点不能外移——`osKernelInitialize()` 之前的创建类 API 会杀死启动；**故意不新建第二个队列**：那会白占 CCM 里 8×`net_msg_t`
 的堆空间，而 CCM 正是当前红线）。**两类从来不算债**：`stm32f4xx_it.c:241-256` 是 CubeMX「External variables」生成块；`:183/195/207/220` 是 `__asm` Handler
 里的汇编标签引用（ARMCC `__asm` 取不到 C 数据符号）。 | 无（后续由 `layer-deps` 与 `cubemx-survival` 两条门禁守着不回退：新增 `net-msgq-adopt` 存活项） |
-| 驱动规范 | **S-5 🟡 主体已落地**（2026-10-23：契约 + 门禁 + RS485/SD2506/TPAFE 收编 + GD5F 改名 + dhara 三类码） | 我原先写的"无统一错误码"**不准**，实测是 **六套并存**：0/−1（SD2506、NETCFG、nand_ftl）、自研枚举 `CH395F_STATUS_*`、**芯片寄存器原生码** `CH395F_ERR_*`（与前一套同模块并存）、`HAL_StatusTypeDef`（`rs485.h` 曾直接暴露）、`bool`，外加第三方 dhara 出参 `dhara_error_t` 与 FatFs `FRESULT`。超时侧是**同形两义**：`*_TIMEOUT` 里 100 是毫秒、`GD5F_SPI_TIMEOUT 100` 是**自旋圈数**、`GD5F/TPAFE5160_BUSY_TIMEOUT = -2` 其实是**返回码**；`osWaitForever` 与 `HAL_MAX_DELAY` **同为 0xFFFFFFFFU**（值同域不同，跨层转手不报错也不变慢）。真正值钱的不是码名，是"**能不能重试**"以前只写在个别注释里 | `Drivers/BSP/bsp_err.h`（header-only，含 `BSP_ERR_CAN_RETRY`）+ `bsp-err` 钩子（三条规则，基线 **19 → 17**）；已收编 **RS485（HAL 枚举不再外泄）/ SD2506（11 个公共 API，I2C 超时终于归成可重试）/ TPAFE5160（含 E-44 的 FRSTDATA → `BSP_ERR_NO_DEVICE`）**，GD5F 的 `GD5F_BUSY_TIMEOUT` 改名 `GD5F_WAIT_EXPIRED` 消掉同形两义，FTL 坍缩点按 **ECC / 预算耗尽 / 完整性** 三类就地分类并打可读日志（§10.4）。`net_*` BSD 层与 `tpafe5160_snapshot()` 三态按裁定**不纳入**。**待还**：GD5F 私有码集整体收编（169 处、含板级套件 48 处，需真机 + 套件回归）、C4 失败类快照（让卷健康探针按类分支）、16 条缺「返回值：」注释 |
+| 驱动规范 | **S-5 🟡 主体已落地**（2026-10-23：契约 + 门禁 + RS485/SD2506/TPAFE 收编 + GD5F 改名 + dhara 三类码） | 我原先写的"无统一错误码"**不准**，实测是 **六套并存**：0/−1（SD2506、NETCFG、nand_ftl）、自研枚举 `CH395F_STATUS_*`、**芯片寄存器原生码** `CH395F_ERR_*`（与前一套同模块并存）、`HAL_StatusTypeDef`（`rs485.h` 曾直接暴露）、`bool`，外加第三方 dhara 出参 `dhara_error_t` 与 FatFs `FRESULT`。超时侧是**同形两义**：`SD2506_I2C_TIMEOUT_MS` 带单位后缀而 `GD5F_SPI_TIMEOUT 100` 不带（**逐行核过：它也是毫秒**，我先前记成"自旋圈数"是错的）、`GD5F/TPAFE5160_BUSY_TIMEOUT = -2` 其实是**返回码**；`osWaitForever` 与 `HAL_MAX_DELAY` **同为 0xFFFFFFFFU**（值同域不同，跨层转手不报错也不变慢）。真正值钱的不是码名，是"**能不能重试**"以前只写在个别注释里 | `Drivers/BSP/bsp_err.h`（header-only，含 `BSP_ERR_CAN_RETRY`）+ `bsp-err` 钩子（三条规则，基线 **19 → 1**）；已收编 **RS485（HAL 枚举不再外泄）/ SD2506（11 个公共 API，I2C 超时终于归成可重试）/ TPAFE5160（含 E-44 的 FRSTDATA → `BSP_ERR_NO_DEVICE`）**，GD5F 的 `GD5F_BUSY_TIMEOUT` 改名 `GD5F_WAIT_EXPIRED` 消掉同形两义，FTL 坍缩点按 **ECC / 预算耗尽 / 完整性** 三类就地分类并打可读日志（§10.4）。`net_*` BSD 层与 `tpafe5160_snapshot()` 三态按裁定**不纳入**。**待还**：GD5F 私有码集整体收编（169 处、含板级套件 48 处，需真机 + 套件回归）、C4 失败类快照（让卷健康探针按类分支）、仅 `bool ui_content_page_open()` 一条（需改签名 + 处理 3 个调用点，与还注释不是一档事） |
 | 网络 | 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 同批评估 |
 | 存储/日志 | P2-10 ❌（N-25） | 卷锁现有 5 个使用者（配置原子写 / 日志 / SOE / lftpd_io / defaultTask），容量轮转删除与 UI 读并发仍未全覆盖 | 登记簿 S-5 面（卷锁覆盖面） |
@@ -324,7 +324,7 @@ W6 簇按 U4 → U1 → U3 → U2 的顺序执行完毕（U2 停在"够用即止
 | 波次 | 本报告条目（今天状态） | 备注 |
 |---|---|---|
 | ~~W3 预算与内存~~ ⏸ | R-9 ✅ / R-2 后半、R-3、R-4、R-6 暂缓 | 暂缓期间无验收动作，观测照常 |
-| W4 结构债 | N-14 ⏸、F-5 🟡、S-1/S-2/S-4/S-5、N-25 | `--strict` 已默认；S-5 契约/门禁已落地并收编三模块（基线 19→17，剩 GD5F 码集 + C4 快照） |
+| W4 结构债 | N-14 ⏸、F-5 🟡、S-1/S-2/S-4/S-5、N-25 | `--strict` 已默认；S-5 契约/门禁已落地并收编三模块（基线 19→1，剩 GD5F 码集收编与 C4 快照——均经论证暂不做） |
 | W5 验证常态 | 覆盖率、`malloc` 正则、TC 差异 13 处升门禁 | 逢窗口顺手做 |
 | W6 UI 扩展 | U2 残余、U5 页量 | 随产品需求，不再单列专项 |
 | W7 仓库决策 | D-1（N-29） | 已决策暂不处理；对外交付前重评 |
@@ -383,7 +383,7 @@ W6 簇按 U4 → U1 → U3 → U2 的顺序执行完毕（U2 停在"够用即止
 | **S-2** | 跨模块裸 `extern` | ✅ **已闭环 2026-10-22**（24 处手写全消；两类本就不算债见 §0.4） | 本文变更记录 2026-10-22 三行；契约见 `App/task/task_handles.h`、`gd5f_spi1_notify_*`、`net_msg_queue_adopt` |
 | **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` 错误码与超时命名约定 | 🟡 主体已落地（2026-10-23：契约 + `bsp-err` 钩子 + RS485/SD2506/TPAFE 收编 + GD5F 改名 + dhara 三类码；基线 19 → 17） | 本文 §0.4、`pre-commit使用说明.md` §2.27、`STM32F4-Base存储架构说明.md` §10.4、`Drivers/BSP/bsp_err.h` |
+| **S-5** | 统一 `bsp_err_t` 错误码与超时命名约定 | 🟡 主体已落地（2026-10-23：契约 + `bsp-err` 钩子 + RS485/SD2506/TPAFE 收编 + GD5F 改名 + dhara 三类码；基线 19 → 1） | 本文 §0.4、`pre-commit使用说明.md` §2.27、`STM32F4-Base存储架构说明.md` §10.4、`Drivers/BSP/bsp_err.h` |
 | R-1 ~ R-9 | 内存优化项（R-9 已落地、R-5 判定不可行、其余随簇暂缓） | 见 §5.3 | 本文 §5.3、`../内存管理/RAM预算台账.md` |
 | F-1 / F-2 / F-3 | LVGL 死代码裁剪，省 64,576 B | ✅ 已落地 2026-10-11 | `../内存管理/RAM使用分析与优化方案.md` §2.6.4 |
 | **F-4 / F-5 / F-6** | Flash 双精度与死代码簇 | ✅/🟡/❌ 见 §5.4 | 本文 §5.4、`App/algo/prot_set.h` 注释 |
@@ -442,6 +442,38 @@ admin/admin（SHA-256 `pwd_hash`）→ 该脚本**必然登录失败**；它是
 |  | 数字联动照做：两份 `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 行标 ✅。 |
+| **2026-10-23** | **S-5 还债：`bsp-err` 基线 19 → 1**，并修掉门禁自己的一处误判口径 | 用户裁定先还 A（清存量）再调查 B。**16 条缺「返回值：」全部补齐**：`gd5f2gq5ue.h` 九个 SPI 原语
+（`wait_busy`/`write_enable`/`read_status`/`page_read`/`read_from_cache`/`program_load`/`program_exec`/
+`block_erase`/`check_ecc`）逐条写全 函数功能/入口参数/返回值/限定条件/函数说明，**并把每个函数
+能返回哪些码写死在注释里**（哪一个是"可重试"的 `GD5F_WAIT_EXPIRED`、哪一个是器件自认坏块的
+`P_FAIL`/`E_FAIL`）；`nand_ftl.h` 从零散三行补成带模块头的完整注释，并**明写"`nand_ftl_init()`
+的 -1 抹掉了失败类"**——分类目前只在失败点进日志，要按类分支需要 C4 快照（现无消费者故未做），
+同时警告"不得把 -1 解读成卷坏了可以重格式化"（E-31 的教训）。
+`ui_menu_tab.h` 五个表查询 API 由行尾短注释升级为完整块（含"越界返回 false 是保守取只读"、
+"宁可按一张错表拒绝显示也不要按它导航"这类判断依据）；该文件**带 BOM，Edit 后已按原样补回**
+（AGENTS 铁律：丢 BOM → ARMCC 按 CP936 解码 → 中文报 #870-D）。 |
+|  | **门禁自身的误判口径也修了，而且这是本轮最该记的一条**：R3 原本要求注释块里出现字面"返回值"，
+而规范 V1.0 允许列对齐写法「**返 回 值：**」。后果是双重的——① 合规写法被判违规；② 反向更糟：
+`gd5f_write_enable`/`gd5f_read_status` 两条**早就"通过"了**，原因竟是它们的**函数说明**里顺口写了
+"返回值"三个字，而不是真的有一行返回值说明。**一条会因为散文里出现关键词而放行的规则，等于在
+奖励运气**。修法是在块内**忽略空格**后再匹配关键词（规范允许的排版不是违规），并在注释里写明
+为什么不许把"必须不空格"写进规则。基线随之从表面 15 条回到真实 16 条缺说明，再一并补齐。 |
+|  | **刻意没做的最后一条**：`bool ui_content_page_open()` 留在基线里。它和"补注释"不是一档事——
+要改签名（`bsp_err_t`）、要处理 **3 个调用点**（`ui_menu.c:138/192/196`，**今天三处全部丢弃返回值**，
+即"按 ENTER 开页失败是静默的"这件事现在没人知道）、UI 三个文件都带 BOM、且 UI 源码**双端编译**
+（模拟器同份），验证面是"重新构建模拟器 + 像素回归 + 真机进菜单逐个页"。这不是还债，是独立一波改动。
+顺带查出的这一条（开页失败静默）比签名统一更值得修。 |
+|  | 验证：`@build` **0 错 0 警告且 `Program Size` 与上一笔逐字段相同**（`Code` 213,648、RO 18,860、
+RW 1,188、ZI 131,500）——证明本笔确为纯注释，故**不跑 `@test`**（无任何指令变化，跑它没有新信息）；
+受影响文件的 14 个钩子全 Passed（含 `ui-golden` 像素回归、`cppcheck`、编码规范、`bsp-err` 1/1/0）；
+`check_doc_links --all --sections-strict` 147 篇 0 问题；字节卫生复核：UI 头 BOM 仍在、无 CR、无 U+FFFD。 |
+|  | **顺手更正我自己写进文档的一条错话**（这类"听着很顺但没核"的说法最危险）：我在 S-5 各条里把
+`GD5F_SPI_TIMEOUT 100` 记成"**自旋圈数**（改分频时长会变）"。这次逐行核它的 12 处用法，**全部是
+HAL_* 超时参数或 `HAL_GetTick()` 差值 → 它也是毫秒**。真问题降级为"**单位没写进名字**（缺 `_MS`
+后缀），读代码必须回实现查单位"，而不是"换个 CPU 就悄悄变慢"。`osWaitForever` 与 `HAL_MAX_DELAY`
+同为 0xFFFFFFFFU、以及"`*_BUSY_TIMEOUT = -2` 是返回码"两条**仍然成立**（前者已核头文件，后者已改）。
+本行以上那些**已提交的变更记录行仍写着旧说法**——按 §8.1 冻结历史不回改，更正以本行为准；
+现状描述类条目（§0.4、`bsp_err.h`、`pre-commit使用说明.md` §2.27、脚本文件头）已全部改准。 |
 | **2026-10-23** | **S-5 第二波：C3 SD2506 整模块收编 + C1 GD5F/TPAFE 同形两义 + C2 dhara 失败类**（用户指定顺序 C3 → C1 → C2） | **C3**：`sd2506.h` 三枚私有宏（`SD2506_OK/ERROR/I2C_ERROR`）**删除而不是留别名**（留别名 = 新代码还能继续用旧形状，等于把迁移洗掉），11 个公共 API + 6 个内部 helper 改 `bsp_err_t`；新增 `sd2506_err_from_hal()`，**把 I2C 超时从"和没人应答同一个 −2"里拆出来归成 `BSP_ERR_TIMEOUT`（可重试）**——SD2506 是启动链第一站、I2C1 上电时序敏感，这是本波最实在的一处语义改善；
 `sd2506_init` 的 charge 寄存器**回读校验不符**原返 `SD2506_ERROR`（参数类）→ 改归 `BSP_ERR_IO`。连带迁移 `App`（`sys_clock.c`、`app_main.c`）、板级 RTC 套件、
 主机单测（`test/host/sys_clock/` 桩 + `run_unit_test.py` 补 `Drivers/BSP` include 路径）→ **单测 100/100**。 |