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
parent 7635480e06
commit 0f7b5a87fb
253 changed files with 2234 additions and 4541 deletions
@@ -8,17 +8,17 @@
 * 修改记录：
 *     2026-09-24  王建锋  创建（自 Src/usart.c USER CODE 区迁出，实现逻辑不变，
 *              仅变更文件位置：HAL 库生成文件不得包含应用代码）
- *     2026-10-02  王建锋  僵尸通道喂狗节奏保护（台架 gen-288 实证）：round-3 的
+ *     2026-10-02  王建锋  僵尸通道喂狗节奏保护（台架日志代次 288 实证）：第 3 轮的
 *              "单次 drain 预算 250ms" 只限单次调用——ORE 锁存在外设软复位后
 *              毫秒级重锁（PA10 悬空 + RX 使能），背靠背 drain 每轮再耗 100ms
 *              块超时 → 主循环周期拉到 450~500ms → 100ms 节流的喂狗抽样间隙
 *              超过 IWDG 最坏容限 1.7s → 停喂 → 误复位（且心跳位全员健康、
 *              无 stall 日志，纯节奏性饥饿）。修复：发送故障后立即结束本轮
 *              drain 并进入 300ms 发送冷却（冷却期内 drain 直接让位主循环），
- *              保证喂狗节奏 ≤ ~300ms。根治（USART1 TX-only 灭 ORE 机制）
- *              另行推进（.ioc 结构性修改 + CubeMX 重生成，见 docs/任务规划/登记簿.md S-3）。
- *     2026-10-02  王建锋  round 8b 加固：发送超时判据改用 DWT CYCCNT（时间源无关）。
- *              台架 round 8a 取证（见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录）定位到：defaultTask
+ *              保证喂狗节奏 ≤ ~300ms。根治（把 USART1 改成只发不收）已于 2026-10-26
+ *              由用户裁定不做，本缓解即长期方案；机制详述 docs/子系统设计/控制台单写者日志设计说明.md §12。
+ *     2026-10-02  王建锋  第 8b 轮加固：发送超时判据改用 DWT CYCCNT（时间源无关）。
+ *              台架第 8a 轮取证（见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录）定位到：defaultTask
 *              冻结在 console 突发行内、无 STALL、复位为 IWDGRSTF。唯一自洽机理 =
 *              HAL_UART_Transmit 的超时判据 `HAL_GetTick() - Tickstart` 依赖
 *              TIM7 的 uwTick —— TIM7 一旦停摆，超时永不成立 → 写者死等 TXE →
@@ -75,13 +75,13 @@
 #define DBG_CON_TX_TIMEOUT_MS   100U  /* 单次发送超时：256B 块 @115200 标称 22ms；僵尸通道限时 + 自愈 */
 #define DBG_CON_DRAIN_BUDGET_MS 250U  /* 单次 drain 连续发送上限：让位喂狗轮询（缺失容忍 800ms） */
 #define DBG_CON_FAULT_COOL_MS   300U  /* 故障后发送冷却：ORE 锁存毫秒级重锁，背靠连发无益
-                                       且拖长主循环周期 → 喂狗节奏饥饿（gen-288 实证）；
+                                       且拖长主循环周期 → 喂狗节奏饥饿（台架日志代次 288 实证）；
                                       冷却期内 drain 只让位、不发送，下轮重试 */

-/* ==== round 8b：与时间源无关的硬上界（DWT CYCCNT）====
+/* ==== 第 8b 轮：与时间源无关的硬上界（DWT CYCCNT）====
 * HAL_UART_Transmit 的超时判据是 `HAL_GetTick() - Tickstart > Timeout`，而 HAL 时基
 * = TIM7 的 uwTick。TIM7 停摆 → 超时永不成立 → 写者死等 TXE → 唯一喂狗者停摆 →
- * IWDG 误复位（round 8a 台架现场）。改用 DWT CYCCNT（内核硬件周期计数，不依赖任何
+ * IWDG 误复位（第 8a 轮台架现场）。改用 DWT CYCCNT（内核硬件周期计数，不依赖任何
 * 中断/uwTick）做判据；DWT 使能失败时退回 HAL_UART_Transmit（旧行为，功能不退化）。 */
 #define CON_TX_TIMEOUT_CYC  (SystemCoreClock / 10U)   /* 发送硬上界 = 100ms 对应周期数 */
 /*
@@ -293,7 +293,7 @@ void dbg_console_drain(void) {
    t0 = (uint32_t)HAL_GetTick();

    /* 故障冷却：僵尸通道（ORE 重锁）秒内不自愈，冷却期内不发送——
-     * 本轮 drain 直接让位主循环，保住喂狗节奏（gen-288 停喂误复位的
+     * 本轮 drain 直接让位主循环，保住喂狗节奏（日志代次 288 停喂误复位的
     * 直接诱因 = 背靠连发的块超时链）。是否在冷却看 s_con_cooling 独立标志，
     * **不再拿 tick 值当哨兵**（2026-10-24 实测：故障恰好落在 tick==0 那一拍时，旧写法
     * 记出的 cool_until==0 等于没记冷却，下一轮立刻再耗一次 100ms 块超时）。
@@ -403,7 +403,7 @@ void dbg_console_drain(void) {
 *          环满等待（vTaskDelay / DWT 判据）一律在临界区之外，区内绝不睡眠。
 *          写者自身记录日志时先排空缓冲，避免自等。
 *          等待上界优先用 DWT 真实时间（CON_APPEND_WAIT_CYC，时间源无关）——
- *          tick 停摆时 vTaskDelay 本身也会停，故不能用它作唯一判据（round 8b）。
+ *          tick 停摆时 vTaskDelay 本身也会停，故不能用它作唯一判据（第 8b 轮加固）。
 */
 static int con_append(const char *buf, uint16_t len) {
    uint32_t waited = 0U;
@@ -3,7 +3,7 @@
 * 模块功能：定长 64B SOE（Sequence-of-Events）记录的构建与解析：
 *           CP56Time2a 时标 + 记录类型 + 元件号 + 单调序号 + 值 + 校验和。
 *           **零 I/O、零 OS 依赖**（仅 stdint/string）→ 主机侧 L0.5 离线单测
- *           （落实登记簿 A-4 约束 1"协议/记录与硬件 I/O 分离"）。
+ *           （分层约束：协议/记录与硬件 I/O 分离）。
 * 记录口径（docs/算法/继电保护功能复现规划.md §3.4 L4-4/L4-5，B9）：
 *   落盘文件 = /log/soe.log（8.3 合规；FF_USE_LFN=0 约束），定长 64B 一条
 *   （照 run.log 先例：count = filesize/64 O(1)、容量满删除重建）。
@@ -152,7 +152,7 @@ void syslog_drain(void);
 * 返回值：0 - 成功；-1 - 卷占用或写失败（证据可能回滚，**不阻断判定**）  int
 * 限定条件：poller（defaultTask）上下文调用；卷锁一律 try（绝不阻塞，
 *          本上下文 = 看门狗喂狗点）
- * 函数说明：round 7 取证通道（设计见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录：
+ * 函数说明：第 7 轮取证通道（设计见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录：
 *          误复位后 RAM 态随复位消失、stall 行经僵尸串口丢失，故证据必须落盘）。
 *          内部在释放卷锁后立刻追加一条 s_append(SYSLOG_RUN, ...) 写另一个
 *          文件——FTL 单页缓存语义为"写到不同 LPN 才把前一脏页刷进 NAND"，
@@ -15,7 +15,7 @@
 *                              （本任务 = 看门狗喂狗点，绝不阻塞等锁）
 *     v1.3  2026-10-02  王建锋  新增 sys_log_evidence()：把看门狗停喂现场
 *                              证据落 /log/wdev.log（掉电不丢）+ flush 诱导
- *                              （round 7 纯取证，见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录）
+ *                              （第 7 轮纯取证，见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录）
 *     v1.5  2026-10-24  王建锋  主机单测批次照出的缺陷一起修，本文件内 5 条
 *                              （A/B/C/D/F；E 在 App/cfg/cfg_file_store_mcu.c）：
 *                              A 卷忙整批静默丢日志——syslog_drain 批量路径补
@@ -34,10 +34,10 @@
 *                              数组满各立 volatile 抑制位，与 B 的 drain 侧那位分
 *                              开）：卷被长期占用 + A 项回投让队列常驻满时，串口
 *                              不再按投递频率刷 "queue full, drop"
- *     v1.4  2026-10-04  王建锋  P2-9：syslog_mcu_mounted() 改为幂等 + 卷锁保护；
+ *     v1.4  2026-10-04  王建锋  syslog_mcu_mounted() 改为幂等 + 卷锁保护；
 *                              defaultTask 每 2s 复查，建 /log 曾失败时自动重试
 *                              （原"仅调用一次"→ 失败后 drain 永久 no-op）。
- *                              P2-10：s_read_raw() 纳入卷锁 try 语义，与写者
+ *                              读者 s_read_raw() 纳入卷锁 try 语义，与写者
 *                              s_append 的"容量满 unlink 重建"互斥，消除
 *                              "UI 读记录(FA_READ) 时文件被 unlink"竞态窗口。
 */
@@ -63,7 +63,7 @@ static const uint32_t s_caps[SYSLOG_COUNT] = { SYSLOG_RUN_MAX, SYSLOG_SELFTEST_M

 #define SYSLOG_QUEUE_MAX 8u

-/* N-24（2026-10-15，报告 N-16 写侧）：一次排空的合并写入上限。
+/* 日志读写放大收口（2026-10-15，写侧）：一次排空的合并写入上限。
 * 8 条 × 64 B = 512 B 静态缓冲（不吃任务栈），与队列深度 SYSLOG_QUEUE_MAX 同值
 * ——即"一轮排空最多一次 open/write/close"。 */
 #define SYSLOG_BATCH_MAX 8u
@@ -84,13 +84,13 @@ typedef struct {
 } syslog_entry_t;

 static syslog_entry_t s_preboot[SYSLOG_QUEUE_MAX]; /* 启动前待发数组（RTOS 前单生产者/后单消费者，免锁） */
-static syslog_entry_t s_batch_src[SYSLOG_BATCH_MAX]; /* 本批条目的原始来源（N-24：未落盘的尾部要回投队列，故必须留住 id + desc 副本）；
+static syslog_entry_t s_batch_src[SYSLOG_BATCH_MAX]; /* 本批条目的原始来源（未落盘的尾部要回投队列，故必须留住 id + desc 副本）；
                                                      * 唯一写者 defaultTask，走静态不吃栈 */
 static volatile uint8_t s_preboot_cnt;              /* 数组条目数 */
 static osMessageQueueId_t s_queue;                  /* 运行期消息队列（syslog_drain 首次调用时惰性创建） */
 static const osMessageQueueAttr_t s_queue_attr = { .name = "syslog" };
 static volatile uint8_t s_fs_ready;                 /* 卷挂载 + /log 目录就绪后置位 */
-static volatile uint8_t s_mount_fail_reported;      /* P2-9：建目录失败日志去重（成功复位） */
+static volatile uint8_t s_mount_fail_reported;      /* 建目录失败日志去重（成功复位） */
 /* B 项整改（2026-10-24）：syslog_drain 批量写失败"整批回投"这条留痕的节流位——
 * 只在"从正常转入故障"的那一次打一条，成功一轮后复位。与 s_append_many 内部的
 * s_batch_fault 各管一层：那位压的是"这个文件写坏了"，本位压的是"这批条目回投了"。
@@ -108,7 +108,7 @@ static uint8_t s_requeue_reported[SYSLOG_COUNT];
 static volatile uint8_t s_post_qfull_reported;     /* 队列满丢弃：已留痕？ */
 static volatile uint8_t s_post_pboot_full_reported;/* 启动前数组满丢弃：已留痕？ */

-/* N-24（2026-10-15，报告 N-16 读侧）：8 条滑动读窗口 + 写者代数。
+/* 日志读写放大收口（2026-10-15，读侧）：8 条滑动读窗口 + 写者代数。
 * 窗口 512 B 走静态（不吃任务栈；defaultTask/uiTask 最坏链见 stack_report.py，
 * 预算余量见 docs/内存管理/RAM预算台账.md）。s_rd_gen 由写者自增、读者比对，
 * 对齐 32 位在 ARM 上原子，跨任务无需临界区。 */
@@ -195,7 +195,7 @@ static int s_is_selfheal_code(FRESULT fr) {
 *           p_rec - 输出缓冲（SYSLOG_REC_SIZE 字节，不可为 NULL）  uint8_t *
 * 返回值：无
 * 限定条件：时间戳未就绪时落 "1970-01-01 08:00:00" 占位串
- * 函数说明：N-24（2026-10-15，报告 N-16）从 s_append 抽出，供"单条写"与
+ * 函数说明：日志读写放大收口（2026-10-15）时从 s_append 抽出，供"单条写"与
 *          "批量写"共用——两条路径必须产出逐字节相同的记录，否则 UI 按定长
 *          字段偏移解析会错位。
 */
@@ -327,7 +327,7 @@ static int s_append(syslog_id_t id, const char *desc) {
 * 返回值：0 - 成功；-1 - 写失败；-2 - 卷被占用（顺延，非故障）；
 *         -3 - 剩余容量不足 n 条，本批不能走快路径（交回按条慢路径做轮转）  int
 * 限定条件：仅 defaultTask（唯一写者）调用；卷已挂载
- * 函数说明：N-24（2026-10-15，报告 N-16 写侧）。旧实现每条记录一轮
+ * 函数说明：日志读写放大收口（2026-10-15，写侧）。旧实现每条记录一轮
 *          f_open + f_write(64 B) + f_close，而 f_close 要回写目录项、f_write
 *          要对目标扇区做读-改-写 → 每条日志 2~4 次 NAND 页读写。本函数把
 *          同一次排空里属于同一文件的最多 8 条合并成一次 512 B 追加写。
@@ -405,15 +405,15 @@ static int s_append_many(syslog_id_t id, const uint8_t *p_buf, uint32_t n) {
 *           idx  - 记录序号（0 起）  uint32_t
 *           p_rec- 输出缓冲（SYSLOG_REC_SIZE 字节，不可为 NULL）  uint8_t *
 * 返回值：0 - 成功；-1 - 越界/读失败/卷忙  int
- * 函数说明：P2-10（2026-10-04）：读者纳入卷锁（try），与写者 s_append 的
+ * 函数说明：读者纳入卷锁（try），与写者 s_append 的
 *          "容量满 unlink 重建"互斥——原实现读时无锁，写者 unlink 与读者
 *          open/read 可交错，读到的可能是半删除态文件。try 语义（timeout=0）：
 *          本路径可由 uiTask 调用，uiTask 在 required_mask 内、须每 100ms 喂
 *          心跳，绝不能阻塞等锁；busy = 本次读失败（UI 下轮刷新重读，非故障）。
 *
- *          N-24（2026-10-15，报告 N-16 读侧）：加**8 条滑动窗口**。旧实现每读
+ *          日志读写放大收口（2026-10-15，读侧）：加**8 条滑动窗口**。旧实现每读
 *          一条记录都要 open + lseek + read + close 一轮，UI 翻 20 条记录 =
- *          20 次目录项/ FAT 往返（报告 N-16 的"UI 翻记录逐条 open/seek/close"）。
+ *          20 次目录项/ FAT 往返（即"UI 翻记录逐条 open/seek/close"这笔开销）。
 *          记录定长 64 B，故一次 open + 一次 lseek + 一次 f_read 就能取回连续
 *          8 条（512 B），命中窗口时零 I/O 直接从 RAM 返回。API 与调用方
 *          （ui_page_runlog / ui_page_selftest 的逐行取数）一律不变。
@@ -424,7 +424,7 @@ static int s_append_many(syslog_id_t id, const uint8_t *p_buf, uint32_t n) {
 */
 static int s_read_raw(syslog_id_t id, uint32_t idx, uint8_t *p_rec) {
    static FIL f;             /* static：省 528 B 栈；open~close 全在卷锁区间内
-                               * （uiTask 与写者任务由 vol_lock 串行化，见上方 P2-10 说明） */
+                               * （uiTask 与写者任务由 vol_lock 串行化，见上方读者卷锁说明） */
    FRESULT fr;
    UINT br = 0u;
    uint32_t total;
@@ -504,8 +504,8 @@ int syslog_mcu_init(void) {
 * 入口参数：无
 * 返回值：无
 * 限定条件：defaultTask f_mount/f_mkfs 成功后调用；**可重复调用（幂等）**——
- *           产品运行期 defaultTask 每 2s 复查一次（见下 P2-9 说明）
- * 函数说明：P2-9（2026-10-04）：原实现"仅调用一次"，若此处建 /log 失败则
+ *           产品运行期 defaultTask 每 2s 复查一次（见下方幂等说明）
+ * 函数说明：原实现"仅调用一次"，若此处建 /log 失败则
 *          s_fs_ready 恒 0 → syslog_drain 永久 no-op（运行期日志与自检全部
 *          滞留/丢弃），且无任何重试。现改为幂等：s_fs_ready 已置位则立即
 *          返回；否则重试建目录。defaultTask 在 STORAGE_READY 置位后每 2s
@@ -570,7 +570,7 @@ void syslog_drain(void) {
        return;
    }

-    /* N-24（2026-10-15，报告 N-16 写侧）：一批一批地排空——同一文件、最多
+    /* 日志读写放大收口（2026-10-15，写侧）：一批一批地排空——同一文件、最多
     * SYSLOG_BATCH_MAX 条合并成一次 open/write/close（旧实现每条一轮
     * open/write/close，每条日志 2~4 次 NAND 页读写）。
     * 取数规则：preboot 数组按下标"看而不删"，整批落盘成功才真正删除；
@@ -831,13 +831,13 @@ int syslog_last_epoch(syslog_id_t id, uint32_t *p_epoch) {
 }

 /*
- * 函数功能：把一条取证行追加到 /log/wdev.log（掉电不丢；round 7 纯取证）
+ * 函数功能：把一条取证行追加到 /log/wdev.log（掉电不丢；第 7 轮纯取证）
 * 入口参数：p_desc - 取证描述行（调用方已格式化；不可为 NULL）  const char *
 * 返回值：0 - 成功；-1 - 卷占用或写失败（本条证据丢失，不阻断判定）  int
 * 限定条件：poller（defaultTask）上下文调用；卷锁一律 try（绝不阻塞）
 * 函数说明：
 * 为什么必须落盘：误复位后 RAM 态随复位消失、`[WD] task stall` 行经僵尸串口
- *   可能丢失（2026-10-02 台架 round 3~6 绕圈的判据缺口），故证据必须落到
+ *   可能丢失（2026-10-02 台架第 3~6 轮绕圈的判据缺口），故证据必须落到
 *   **掉电不丢**的盘上，复位后经 FTP RETR 回读。
 * 第二条写（旧称"flush 诱导"）：写完 wdev.log 后立刻 s_append(SYSLOG_RUN, ...)
 *   再落一条 run.log。保留理由是**多一条独立证据**（run.log 有 UI 记录页与 FTP
@@ -845,7 +845,7 @@ int syslog_last_epoch(syslog_id_t id, uint32_t *p_epoch) {
 *   disk_ioctl(CTRL_SYNC) 已经调 ftl_flush_cache() 把 wdev.log 的脏页刷进 NAND
 *   （nand_ftl.c 的 CTRL_SYNC 分支），所以"写另一个文件（不同 LPN）逼出前一脏页"
 *   从来不是必要条件。
- *   ⚠ 2026-10-02 round 3~8 那次"复位后写入整段丢失"的根因是 dhara resume 锚错
+ *   ⚠ 2026-10-02 台架第 3~8 轮那次"复位后写入整段丢失"的根因是 dhara resume 锚错
 *   checkpoint 使 journal 整段回退（docs/架构设计/STM32F4-Base存储架构说明.md
 *   §5.4.1），不是这层缓存：单页缓存最多丢最后未跨页那笔（≤512 B），丢不出
 *   "整段"。空闲周期 flush 兜底已接线（App/fs/vol_idle_sync.h：STORAGE_READY