docs: 清掉三处"会静默过期"的小账 + check-test-profile 加固(F-98)
一、附录 A 从"手抄表"改成"可再生成的命令"
check-api-parity.py 加 --extra,现算"代码有、契约 §4 没有"的接口 = 41 个
(旧手抄表写 83/62/21,已差近一倍,而且没人会记得回来改它)。
并按"谁去改什么"分六类 —— 只有 E 类(8 个)要客户定口径,其余是文档侧补记。
二、F-6 已修:frontend-pc 的 Mock 说明
AGENTS.md 那句改正之外,连带修了 .agents/skills/project-api/SKILL.md ——
它整篇仍以 vite-plugin-mock / mock/** 为主线,而该项目里 mock/ 目录与插件都已删除。
只改指路牌、不改路的尽头,等于没改。
三、docs/03 两处文档内部口径冲突加 ⚠️ 注(不改口径,只把冲突摆明)
§2 notifyBizType 的 5/6 与 §13.5、落库值不一致 → 实现以 §13.5 为准(催报去重按 5);
§3.6/§9.5 的 collect_file.source 字段表(入口来源)与建表注释(谁传的)冲突 →
实现以建表口径为准。两处都写明"待客户确认",见 F-30 / F-38 / F-39。
四、check-test-profile.py 加固(新增 F-98)
· 子进程输出落盘(不再用没人读的 PIPE):失败时能看见"停在哪一行",
成功时打出启动用时(基线 ~10 秒 / 72 行 / 9.5KB);
· 开跑前按 jar + profile 清残留 JVM,且保留 dev 后端(E2E 正打着它);
· 等待期间每 15 秒报一次进度,卡住时不留沉默。
教训:随机端口这个防撞设计把残留 JVM 藏起来了 —— 撞不到端口就永远发现不了,
于是表现成"时好时坏",而失败时连日志都读不到。
验证:python scripts/verify-all.py --with-e2e → 通过 8 / 失败 0 / 跳过 0
(E2E 36 脚本 / 1548 断言 / 278s;prodguard 9/9;test profile 能起)
python scripts/verify-docs.py → 22 项全部通过
This commit is contained in:
+43
-1
@@ -2286,7 +2286,7 @@ M1 规则模板与任务克隆 → M2 报考范围与名册改删 → M3 提交
|
||||
**§14 开放接口(认定机构对接,HMAC)** → 小程序登录与组织导入 → 工作台数据看板 →
|
||||
CI/CD 与 test/prod 环境 → 压测 → 用户手册与客服话术 → 缩略图与 H5 dev server。
|
||||
|
||||
**每一轮的"做了什么 / 发现了什么"都在 docs/08 §六**,包含 97 条编号问题(F-1~F-97)。
|
||||
**每一轮的"做了什么 / 发现了什么"都在 docs/08 §六**,包含 98 条编号问题(F-1~F-98)。
|
||||
|
||||
### 这 20 多轮里最该记住的几条
|
||||
|
||||
@@ -2337,3 +2337,45 @@ CI/CD 与 test/prod 环境 → 压测 → 用户手册与客服话术 → 缩略
|
||||
⚠️ **不要在没有这些输入的情况下去"顺手实现"**:M4 的识别链路一旦按某家供应商写死,
|
||||
换供应商要重写;`union_id` 没拿到之前,"按 union_id 认人"也无从下手
|
||||
(字段与方案都已就位,见 `MpH5AuthService` 类头注释与 `sys_user.union_id`)。
|
||||
|
||||
---
|
||||
|
||||
## §一·二十九 提交入库 + 文档小账清理(2026-09-30 上午)
|
||||
|
||||
### 一、昨晚的改动已入库(18 个提交,**未推送**)
|
||||
|
||||
按"一轮一个 commit"的仓库惯例分组提交,`main` 上多了 18 个提交。
|
||||
⚠️ **没有推送**:`git status -sb` 显示 `main...origin/main [gone]`(跟踪分支已失效),
|
||||
要推之前先确认远端分支还在不在。
|
||||
|
||||
| 提交组 | 内容 |
|
||||
|---|---|
|
||||
| `chore(git)` | `.gitignore` 补 `backend/_*.txt` / `scripts/_*` / `shots/` —— 调试期临时产物,之前每次都要靠人记着别 add |
|
||||
| `feat(export)` / `feat(audit)` / `feat(mp)` / `feat(join)` / `feat(notify)` / `feat(ops)` | M6 导出交付 / 审核台 / 学生端与班主任端 / B1 加入申请 / 通知与校验 / 日志与字典 |
|
||||
| `feat(cleanup)` / `feat(open)` / `feat(task)` / `feat(schedule)` / `feat(file)` / `feat(pc)` | 历史整理器 / §14 开放接口 / 任务配置 / 定时任务 / 文件与缩略图 / 工作台看板 |
|
||||
| `chore(ci)` / `test(scripts)` / `docs`×3 | CI 三阶段 6 job / 36 个 E2E 与 6 个机械校验 / 部署手册 + 用户手册 / 盘点与交接 |
|
||||
|
||||
### 二、这一轮清掉的文档小账(都是"会静默过期"的那类)
|
||||
|
||||
1. **附录 A 从"手抄表"改成"可再生成的命令"**:`check-api-parity.py` 加 `--extra`,
|
||||
现算"代码有、契约 §4 没有"的接口 = **41 个**(旧手抄表写 83/62/21,已差近一倍),
|
||||
并按"谁去改什么"分六类 —— **只有 E 类(8 个)要客户定口径**,其余都是文档侧补记。
|
||||
教训:**手抄件会过期,命令不会**。
|
||||
2. **F-6 已修**:`frontend-pc/AGENTS.md` 的 Mock 说明改正;**并连带修了
|
||||
`.agents/skills/project-api/SKILL.md`** —— 它整篇仍以 `vite-plugin-mock` 为主线,
|
||||
而 `mock/` 目录与插件都已删除。只改指路牌、不改路的尽头,等于没改。
|
||||
3. **`docs/03` 两处内部口径冲突加了 ⚠️ 注(不改口径)**:
|
||||
§2 `notifyBizType` 的 `5`/`6` 与 §13.5、落库值不一致 → **实现以 §13.5 为准**(催报去重按 5);
|
||||
§3.6/§9.5 的 `collect_file.source` 字段表(入口来源)与建表注释(**谁传的**)冲突 →
|
||||
**实现以建表口径为准**。两处都写明"待客户确认",见 F-30 / F-38 / F-39。
|
||||
4. **`check-test-profile.py` 加固**(新增 **F-98**):日志落盘 + 按 jar/profile 清残留 JVM。
|
||||
⚠️ 这条的教训值得单独记:**"随机端口"这个防撞设计把残留 JVM 藏起来了** ——
|
||||
撞不到端口就永远发现不了,于是表现成"时好时坏",而失败时连日志都读不到
|
||||
(走 `PIPE` 没人读、事后读已被 kill 截断)。现在:基线 **~10 秒**起,
|
||||
失败时能看到"停在哪一行",等待期间每 15 秒报一次进度。
|
||||
|
||||
### 三、还没做的(顺序未变)
|
||||
|
||||
`docs/08` §四 剩下的**全部是外部依赖**(OCR 选型 / 小程序类目 / `union_id` / 真机 / 二期),
|
||||
另有 4 项"**没测过**":导出大包打包、上传并发、5000 行名册导入、长跑稳定性
|
||||
(`docs/09` §9.5 逐条写明"没测就是没测")。
|
||||
|
||||
Reference in New Issue
Block a user