 lovife
|
5213bc214f
|
feat(audit): 审核闭环后端（M5-01~05）—— 「谁能审谁」比「怎么审」重要
一、落地
module/audit：entity(CollectAuditRecord) + 4 个 mapper + AuditService
+ RejectReasonCatalog（附录 C 的 10 条，写在代码里，理由同权限码）
两端接口：PC /api/v1/audit/*（§11）、小程序 /api/v1/mp/teacher/audit/*（§10.2~10.5，只做初审）
待办的 MP 与 PC **共用一份 VO**（契约里那两份重合九成）：做两份迟早分叉，
而"同一个学生在手机上是红、在电脑上是绿"最伤信任。
二、★ 三件必须守住的事
① 权限 ≠ 范围：全校几十个班主任都有 audit:first，但只有这个班的那位能审这个学生。
初审查询强制带 org 范围，且**空列表 = 看不见任何单子**（SQL 里显式 1 = 0，
不是"不过滤"）—— 那是这类查询最经典也最严重的写法错误。
E2E 专门造了个"同样是班主任但没被指定"的 T2：看不到待办、打不开详情、点不动通过。
② 有红问题不许通过（40032），且校验是**现场重算**的：提交时落库的 red_count 是快照，
而 OCR/识别是异步的、名册与材料规则也可能被改。"放过一份有问题材料"不可撤销。
③ 批量通过只带绿色项，红黄一律排除（onlyClean 服务端强制 true，传 false 不报错也不生效），
且跳过的每一条都要说清原因 —— 否则用户只会反复点那个大按钮。
三、红黄计数：列表用快照，动作/详情现场重算并**回写快照**（自己会收敛，最多错一次）
⚠️ 因此 detail() 不能标 readOnly=true —— 它要写回写。标了 PG 直接拒绝 UPDATE，
而这个 bug 只在"现场值与快照不一致"时炸，也就是最需要它工作的那一次。已踩并修。
四、⚠️ 三处文档与代码不一致，需要文档侧对齐（详见交接摘要 §一·二十七）
1. 撤回的动作码：DDL 注释 3=批量通过，而接口设计 §11.4 写"action = 3（撤回）"。
1~6 沿用 DDL，**撤回另取 7** —— 时间轴最不能混淆：把撤回显示成批量通过，
会让人以为这份单子被通过了。
2. 撤回的适用状态：§11.4 只列了状态 3；额外允许**状态 2**（"班主任点错了通过"正是这个状态）。
状态机自洽：撤初审 → 1，撤终审 → 2。**需客户确认**。
3. 文件 source 的语义：DDL(2 班主任代传/3 管理员代传/4 整理器导入) 与 §10.6(source=4 代传)
冲突，以 DDL 为准；代传接口(M5-06)未做，时间轴已按 source∈{2,3} 预留。
五、顺带补掉两个"没人写过"的窟窿
· 名册行的 submit_status **全仓库只有读没有写** → 名册列表状态列恒为"未提交"，
而 REPLACE 护栏只靠 bind_user_id 在生效。现在学生侧与审核侧都写它。
它**不是单调的**：被驳回(4)后重交必须回到 2，否则班主任一直以为他还欠一份。
· collect_submission 少映射了 class_audit_time / admin_audit_time（DDL 里一直有）。
口径是"**本轮**审核的状态"（驳回时清空，历史在 collect_audit_record 里一条不少）。
六、审核端看材料走单独通道
MaterialFileService 抽出 urlOf/contentOf（调用方授权），学生端仍 /mp/files/*、
审核端 /audit/files/*。不要为了"让管理员也能看"在学生那个方法里加 or 条件——那一刻学生端就漏了。
七、一个把「取值口径」讲清楚了的坑
SubmissionValidator 原本走 FillService.getForm(taskId)（学生视角：先过门禁、再拿自己的草稿），
审核人必然撞 40007 且拿到的是自己那份草稿。已抽 assembleFor(task, roster, sub)，两条路径共用同一段装配。
紧接着暴露第二层：**改提交单的列不一定改变"组装出来的值"** —— 学生没动过的字段值会**回退到名册**。
想造红问题要用**名册里没有的字段**（E2E 最后用"本职业工作年限填 999"→ VAL-17）。
八、E2E：scripts/e2e-m5-audit.py → 87/87
复用了既有的两个脚本工具（import e2e-m3-submit 拿学生侧造数、import e2e-m2-roster 拿服务端工具），
不复制第二份 mint/upload。覆盖：范围隔离、详情与策略、40032 现场重算、幂等回放、
终审、批量通过的三种跳过、驳回与升级、学生重交、撤回的 40033/40034/40301 与"不能撤两次"。
夹具教训：身份证材料的目录默认长边下限是 1400，小图必判「清晰度偏低」=黄色警告，
于是"绿色单"前提不成立、批量断言集体失败 —— 失败的样子像功能坏了，其实只是夹具不满足前提。
九、没做的（都在计划内）：代传(M5-06)、统计(M5-09)、通知(M5-12)、批量驳回/转交(P1)。
因为没有通知渠道，驳回响应**如实**回 notifySent=false + needManualNotice=true ——
不能为了让契约好看而写 true，那会让"学生到底收到没有"变成没人能回答的问题。
十、回归：全量 **753 条断言、0 失败**（新增 87）；verify-docs 19 项通过。
下一步：M5 前端（班主任卡片流只右滑通过 / 学生详情 / 驳回页 / 一键通过确认 / PC 终审）。
|
2026-09-29 22:29:00 +08:00 |
|