lovife/xiaotutongxue
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
61 Commits 1 Branch 0 Tags
8f80744d637c2b6bef7403327bbef2e22bae6cdd
Commit Graph

4 Commits

Author SHA1 Message Date
lovife 28dedb4c16 docs: 补测结论回填与限流口径同步（docs/01 E2 / docs/08 F-99·F-100 / docs/09 §9 / 交接摘要 §一·三十） 
- docs/09 §9 重排为 9.1 结果 / 9.2 结论 / 9.3 门禁两次修正 / 9.4 怎么跑 /
  9.5 补测记录（上传并发、5000 行导入、导出大包、长跑）/ 9.6 仍然没测的；
  补记机器规格（12 物理核 / 59.6GB，全在同一台机器上）。
- docs/01 E2 二次修正备案：成功侧 200→600，附实测证据。
- docs/08：F-99（压测工具自己撒的 8 次谎）、F-100（门禁成功上限卡年级量级）、
  F-5/F-6 核销与更新，变更记录补 3 行；问题清单到 F-1~F-100。
- 交接摘要：§一·二十九（提交入库+文档小账）之后补 §一·三十（四项补测+门禁二次修正+磁盘清理）。
- AGENTS.md：清理残留一节写清 dry-run 默认与「演示态挂在 E2E 班下面」的风险。

验证：python scripts/verify-all.py --quick → 通过 5 / 失败 0
 2026-09-30 11:10:06 +08:00
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