 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 |
|