 lovife
|
db6a51d617
|
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 项全部通过
|
2026-09-30 09:10:34 +08:00 |
|
|
lovife
|
8debf371bf
|
docs: 完成度盘点（F-1~F-97）、确认函 E 组、交接摘要 §一·二十八与 AGENTS 更新
docs/08 是计划与现实的对账：完成度表、未完成按「能不能上线」排序（P0/P1/P2 + 卡点→找谁→编号）、
97 条编号问题、施工记录 6.1~6.4（每条都带验证方式，不写没有证据的「已完成」）。
docs/01 新增 E 组第二轮待确认：E1 union_id（H5 与小程序不能同时上线的阻断项）、
E2 D3 限流口径更新、E3 二期时点；D3 那行划掉。
交接摘要 §一·二十八 把坐标从「M5 后端」刷新到「一期功能收口」：120/121、V17、
27 实体/33 表、36 脚本/1548 断言，以及这 20 多轮最该记住的 7 条（含 F-96：
三处「没断言就往下走」把排查引向了完全错误的方向）。
AGENTS.md：H5 那条「没有可直接联调的独立 dev server」已过时，改为三端行为的说明。
|
2026-09-30 09:02:58 +08:00 |
|
|
lovife
|
fdfe21345a
|
feat(roster): 名册导入（M2-01/02/03 后端）—— 表头探测 + 体检报告 + 合并/替换
计划里排第一的一步。顺序不是拍的，是依赖方向：
没有名册，门禁匹配不到任何人 → 学生进不来；而名册此前只能靠 SQL 夹具造。
（做了这一步，下一步的前端一上，任务发布就能在界面上走通。）
一、新增（module/roster/）
RosterColumnCatalog 官方 21 列(A~U) ↔ 名册字段 对照 + 别名 + 表头文本归一化
RosterImportService 表头探测 + 行解析 + 体检 + 落库（APPEND / REPLACE）
RosterService 分页（姓名模糊 / 身份证号精确 / 班级 / 状态）
RosterImportReport 体检报告（严格照 §8.1 的 JSON）
RosterVO 名册项（证件号与手机号一律脱敏）
CollectRosterMapper 批量判重 / 按 hash 定位 / 整表替换（都带显式 tenant_id）
RosterController POST /tasks/{id}/roster/import、GET /tasks/{id}/roster
权限码现成且口径天然合上契约：导入 roster:manage（仅管理员），
查看 roster:view（管理员+班主任+审核员）
二、先修了一个隐患：规范化被抄成两份就会出事
门禁是按 id_card_hash（HMAC）等值查名册的，而 HMAC 的输入是**规范化后**的字符串。
原来 normalizeName 是 MpRosterService 的私有方法，导入再抄一份的话，
两处只要有一步不同 → 同一号码算出不同 hash → **名册里明明有这个人却查不到**，
而症状会把人引向"学生是不是填错了"。已抽成 support/IdentityNormalizer
（name/idCard），门禁与导入共用；并注明：加宽松（本次补的全角转换）安全，
收紧是破坏性的（已有名册的学生会突然进不来）。
验证不是"读代码比对"，而是**用真门禁去核验导入进来的名册**（E2E 第 3 节）。
三、几个刻意的决定
· dryRun 默认 true —— 不显式要求就不写库
· ignoreEmptyRow(false) + 行号与 Excel 对齐 —— EasyExcel 默认跳过空行会让行号错位，
报告说"第 12 行有问题"而用户翻到第 12 行是空的，整份报告就没人信了
· 未识别的列进 ext_json（列名做键）—— "备注""推荐人"这类列不该被丢掉
· 名册上的 phone 存脱敏值（不是密文）：名册不需要回放完整号码
· REPLACE 在已有人核验/提交时直接拒绝（40029）—— 否则那个学生的材料
会挂到空名单上，他下次扫码进不来
· APPEND 命中已绑定/已提交的行 → 跳过不覆盖（ROW_LOCKED）：
「报考职业」是锁定字段，盖掉等于把学生已确认的材料变成另一种认定
· 校验位不通过**阻断且不自动改** —— 与"文件名里的号码"策略相反：
名册是权威基准，改它等于我们替机构编了个身份证号
四、E2E：scripts/e2e-m2-roster.py → 58/58
夹具刻意把**表头放在第 6 行**、第一张表全空白、表头带换行、另加一列"备注"。
逐条验：4 个阻断行 + 2 个警告行的**行号与 code 都对**、dryRun 不落库、
密文/脱敏值/ext_json、**完整身份证号能精确搜**（密文搜不了 LIKE）、
响应里不得出现完整证件号、重复导入合并不新增、REPLACE 被拒后名册没被破坏、
40028/40017 两条兜底出路。
⭐ 第 3 节用**真门禁接口**核验导入的名册 —— 导入与门禁的 hash 口径一致才算过。
**本次 E2E 抓到一个真 bug**：write() 里"已存在则更新"的判断写反了
（写成"不在 existingHashes 里才去查"），于是重复导入会插重复行，
撞唯一约束 uk_task_idcard → 50000。也就是"第一次能用、第二次就炸"，
而重导一次正是最自然的动作。已修 + 在代码里点名这个坑。
五、又发现一处文档与代码不一致（以代码为准）
接口设计 §3.6 把报考三项的"↔列"写成 ext_json，而建表脚本里它们是真实列。
按 §3.6 实现的话，门禁回填（读真实列）会永远给学生空值。
已在 RosterVO 类注释写明。
六、回归
全量 613 条断言、0 失败（新增 58；门禁 29 照旧通过 → 规范化抽取没改变门禁行为）
verify-docs.py 19 项全通过
七、下一步（第 2 步）
名册导入前端（frontend-pc/src/views/task/）：上传 → 表头确认 → 体检报告
（错行定位、红黄区分）→ 名册列表。做完它，任务发布就能在界面上走通了。
|
2026-09-29 17:00:21 +08:00 |
|