f5902bcc21
两篇规划期文档改成对当前系统的描述,档名统一去掉"设计说明"的"说明"。 运行与自检记录: - 旧档重写为现状版(10 节:概览 / 记录布局 / 写入路径 / 读取与呈现 / 事件分类 / 控制台日志 / 双端差异 / 内存 / 异常恢复 / 自测要点), 删掉需求表、调研摘要、模块清单动作列、实施步骤与开放问题。 - 按代码纠正:七类记录齐备(原文只写了两类)、自检描述串换成实际 落盘的 28 条、待机阈值以 ui_tokens.h 为准、记录页已走 ui_w_records 共享组件、容量满只删该文件而非整卷清空。 - 待机屏移出本篇:它不属于日志,归 UI 侧;内容页架构补"待机屏 (覆盖层)"一节,产品需求 FR-LOG-3 拆成单纯的上电/重启分类, 待机显示归口已有的 FR-UI-3。 ADC 采样节拍: - §4.5 从 45 行压到 24 行,只留规则 / 违反的代价 / 为什么 / 兜底与 档案指针;九路置换实测表、A/B 对照、探针计数等取证归 ADC_Trap_Records.md 的 TRAP-ADC-01(那里已有完整档案)。 - adc1_gap 字段去掉"2026-10-21 起、此前固件为次数"的修订记录式括号。 - app_main.c 的注释改为指向 TRAP-ADC-01 取证、§4.5 设计口径。 引用同步:两个旧档名全仓替换(含代码注释、角色档、归档 id 表), 旧名残留 0;对 ADC 篇的 § 引用逐条复核落在真实章节上。 验证:48 个提交期钩子全通过,check_doc_links --sections-strict 通过。
62 lines
7.7 KiB
Markdown
62 lines
7.7 KiB
Markdown
### G. 任务树内跑门禁与审计:输出落点(ci-artifacts)与 SDL2 联接假红
|
||
|
||
三条硬规矩,全是 2026-10-29 实测付过失败成本的(两起 ENOENT + 一次假红误判):
|
||
|
||
1. **门禁/审计输出只落 `<tree>/ci-artifacts/`,而新树里它不存在 → 落盘前先 `mkdir -p`**。`ci-artifacts/` 被
|
||
`.gitignore` 忽略(不污染脏行数,E 第 4 步的备份同理),但也因此**不会被检出**——`$TW new` 出来的树里没有这个
|
||
目录。直接 `fs.writeFileSync("<tree>/ci-artifacts/head-md.md", …)` 当场 `ENOENT: no such file or directory`,
|
||
**整段程序零执行**(实测:那一轮的门禁体检与快照读取全没跑成,白重跑一次)。用 Node 写之前先
|
||
`fs.mkdirSync(dir, { recursive: true })`;用 bash 重定向就先单独敲一条 `mkdir -p ci-artifacts` 再落盘
|
||
——重定向在命令执行**之前**解析,目录没建出来时是同一条命令直接失败,后面串着的 `grep` 跟着一起报
|
||
`No such file or directory`,看着像「门禁没跑出结果」,其实是写错了地方。
|
||
2. **`cd` 进任务树之后,`../_wt/x.txt` 不是你以为的地方**:`cd` 之后 `..` = `_wt`,`../_wt/x.txt` 落到
|
||
`_wt/_wt/x.txt`(实测就是这么报的)。**树内命令的输出一律用树内相对路径**(`ci-artifacts/xxx.txt`);
|
||
要绝对路径就写完整绝对路径,跨树取文件用 `$MAIN/…`、`$WTROOT/…` 这种变量打头的全路径,
|
||
不靠 `cd` 之后的相对层级往上跳。
|
||
3. **任务树内文档门禁按单文件跑;全库 `--all` 基线留到合并后在主树跑**。任务树的 `simulator/SDL2` 是指向
|
||
主树同一份的**目录联接**(`new` 的第 2/3 步建的),`--all` 会把这份「仓库里的第二份仓库副本」一起扫:
|
||
实测任务树里 `check_doc_links.py --all` 打 `检查 222 个文档,35 处问题`、RC=1,而 **35 处全落在
|
||
`simulator/SDL2` 联接下**、要改的文档一条都没有 → 判红纯属联接带来的假红。单文件检查不受影响
|
||
(扫描根就是那一个文件,联接目录不在面内)。主树本身没有 SDL2 时不产生这类假红(联接如实镜像主树,
|
||
F 节那棵树连 SDL2 都没得联),但**别据此认为 `--all` 在树内可信**。
|
||
|
||
```bash
|
||
F="docs/<子目录>/<本次改动的文件>.md" # 本次改动的那一个文件
|
||
"$PY" scripts/check_doc_links.py "$F" > ci-artifacts/dl-<slug>.txt 2>&1; echo RC=$?
|
||
cat ci-artifacts/dl-<slug>.txt
|
||
```
|
||
|
||
逐文件跑的实测读数:需求文档 161 处章节引用 / 98% 机器可判定 / rc=0;方案文档 16 处 / 88% / rc=0。
|
||
确实要在树内跑 `--all` 时(例如怀疑主干基线本身),判红顺序**固定三步**,缺一步都不许下结论:
|
||
① 在**主树**跑同一条命令拿基线;② 过滤掉 `simulator/SDL2` 联接下的问题行;③ 剩下的与主树基线逐行比。
|
||
只跑 `--all` 见 RC=1 就回「文档门禁挂了」= 把基线噪声算成本任务的账;只跑「过滤后为空」就回「全绿」
|
||
= 会漏掉真红。全库 `--all` 的正解位置是**合并后的主工作树**:实测合入后在主树跑 `check_doc_links.py --all`
|
||
= 2,597 处章节引用 / 194 个文档 / rc=0 —— 这才证明「就地删叙述」没打断任何引用。
|
||
另:**不因 `--all` 的既有假红跳过对本次改动文件的单文件复检**(假红是基线的事,你的文件仍要逐个过)。
|
||
|
||
4. **文档改动在树内提交前的固定体检**(2026-10-29 实测):`lines / bytes / BOM / CR / U+FFFD / 三连续空行 /
|
||
行尾空格 / 末行单个 LF` + 一个自写的 **Markdown 表格每行列数一致性**检查(数格子前先把转义管道 `\|` 还原成占位符,
|
||
否则会把 `\|` 当成列边界数错)。为什么要自己数:`doc-links` 只管链接与章节、`no-mojibake` 只管编码面,
|
||
**表格断列与删段留下的三连续空行没有任何钩子会报**。
|
||
实测读数:需求文档 `lines=2665 bytes=196137 BOM=false CR=0 U+FFFD=0 tripleBlank=0 trailingWS=0 endLF=true`,
|
||
表格体检另报两处坏表格(`L988-992 counts=5/7`、`L2472-2486 counts=2/3`)——**与本次编辑无关的历史行**。
|
||
所以体检要**区分「本次改动 bad=0」与「整份文件 bad=0」**:先定位归属再决定动不动手,顺手改别人的区域等于把
|
||
没打算提交的内容卷进这笔改动(报告里写「本次改动引入 0 处」,并点名那两处是存量)。
|
||
|
||
5. **提交 / 合并信息一律 `-F` 读文件;清退类任务还要做禁词自检**(2026-10-29 两遍实测):消息文件写在
|
||
`ci-artifacts/`(被忽略 → 不污染脏行数),UTF-8 无 BOM、CR=0、标题 ≤100 字符、正文每行 ≤80(实测标题 31 / 32 字符、
|
||
正文最长行 50 / 55)——`-m` 会把中文按终端代码页转码搞坏,长中文标题还容易撞 gitlint。硬自检:
|
||
|
||
```bash
|
||
git log -1 --pretty=%B | grep -c '485' # 被清退主题的关键词:必须是 0
|
||
git log -1 --pretty=%B | grep -ci '\bDE\b' # 同主题的次要关键词:同样 0
|
||
```
|
||
|
||
关键词不许出现在**标题、正文、合并信息**任何一处(实测标题改写成「删除与本方案无关的其它串口通道对照内容」这种
|
||
语义短语替掉了它)——否则「别让我看到 X」这条要求在 `git log` 里当场破产。合并信息是另一份文件:
|
||
`ci-artifacts/merge-msg-<slug>.txt` 落盘后**同样 grep 一遍**再 `git merge --no-ff --no-edit -F`(C2 第 3 步)。
|
||
自审发现消息里的行数 / 统计算错而**尚未推送** → `git commit --amend -F <改好的文件>` 就地修(实测就这么修掉一次
|
||
off-by-one);**别追加一笔「更正」提交**——那等于把禁词和被更正的错数一起写回历史。
|
||
6. **合并提交期 pre-commit 只查冲突文件(2026-10-29 实测)**:合并那一次提交的钩子日志首行是 `[INFO] Checking merge-conflict files only.`,其余钩子全打 `(no files to check) Skipped` —— 于是「合并提交通过了 30 项钩子」这句话**只覆盖冲突文件**,别拿它当全量绿。正解:合并落主干后立刻在主工作树跑全量 `scripts/ci_local.py`(静态 + 提交信息 + 主机侧单测 + manual 段),实测全量这一步才会抓到「表格断列」「章节引用悬空」这类跨文件问题。合并解冲突时若上游把 Markdown 表格重排过,注意**单元格里的竖线必须写成反斜杠竖线**(先例 `docs/子系统设计/运行与自检记录设计.md` 的 `FA_WRITE\|FA_SEEKEND`),否则 `FA_WRITE|FA_OPEN_APPEND` 会被当列分隔符打断,而 `doc-links` 不查表格列数——要自己数(第 4 条)。
|
||
7. **跨层改动拆不成「按层分笔」提交(2026-10-29 实测,四笔改一笔)**:钩子看到的世界 = HEAD + 本笔 staged——pre-commit 会 stash 已跟踪文件的未暂存改动,而**未跟踪文件不在 `git diff-index` 里、不会被藏**(`git add -N` 也救不了,pre-commit 会把它撤下索引、文件仍在盘上)。后果:把双端登记(`MDK-ARM/*.uvprojx` / `simulator/CMakeLists.txt`)、生成器产物、互锁引用的文档分到别的笔里,本笔必被 `doc-links`(引用了还没入册的小节)、`registration-check`(源文件登记在另一笔)、`generated-fresh`(`#page=` 找不到页面描述符、字库清单与源不一致)、`mem-numbers`(受管区还是旧 .map 的数)四道**整仓**门禁一起拦。判据:**一笔提交必须自洽**——互锁的改动(代码 + 登记 + 生成物 + 文档)走同一笔;机制与三条处置结论(半成品要么先落地要么先挪出工作树)→ `docs/代码规范/pre-commit使用说明.md` §2「stash 覆盖面」。
|