lovife/xiaotutongxue
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
80 Commits 1 Branch 0 Tags
17c92b29c364e19a386813d2c832db60035251ab
Commit Graph

80 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
lovife 17c92b29c3 fix:正式环境API地址 2026-10-19 21:39:24 +08:00
lovife 2ff17cd0c9 refactor(h5)!: H5 改由 nginx 托管，后端退回纯 API 
用户决定：后端不再对外发静态文件，学生端 H5 交给网关。两者**仍然同源**
（微信只给一个授权回调域名；H5 的接口地址取自 location.origin），
所以前端业务代码、微信后台、application-dev.yml 的 h5-base-url 都不用改。

后端
- 删掉 dev/test/prod 三份 profile 里的 spring.web.resources.static-locations
- 主配置加 spring.web.resources.add-mappings=false —— 用开关而不是"指到空目录"：
  后者会连带启用 Spring Boot 的默认位置（classpath:/static 等），谁丢个文件进去就悄悄对外可见
- StaticCacheHeaderFilter → ApiNoStoreFilter，只剩 /api/** 的 no-store
  （静态资源的缓存策略整体归 nginx，避免"改一处漏一处"）
- 补 NoHandlerFoundException → 404：关掉静态映射后未匹配路径不再经过
  ResourceHttpRequestHandler，抛的是 NoHandlerFoundException，只处理
  NoResourceFoundException 时访问 / 会变成 500「系统繁忙」并刷 ERROR 日志

deploy
- 新增 xt-nginx（80）：发 frontend-mp/dist/build/h5 + /api 反代 8080（host.docker.internal，
  Linux 靠 extra_hosts host-gateway），端口与产物目录走 .env 的 H5_PORT/H5_DIR
- 三条"删了就会出事"的都已带上理由：client_max_body_size 50m（默认 1m，超了回 413
  而后端日志一个字都没有）、/assets 的 immutable 与 *.html 的 no-cache（§一·十 那个
  "发版后学生看到旧页面"的坑）、健康检查写 127.0.0.1（容器里 localhost 先解析到 IPv6，
  nginx 只听 IPv4 → 永远 starting 而首页是好的）

CI 与文档
- CI：学生端 H5 构建从"e2e 的输入"改为编译检查，不再留 artifact（e2e 不消费它）
- 同步 AGENTS.md / README.md / docs/09（启动步骤、CI 表、发布注意、排障表）/ docs/11
- 交接摘要新增 §一·四十三（含理由、验证数字、要人工做的一步与环境限制）

验证
- mvn clean package 通过（必须 clean：删掉的旧类会留在 target/classes 被组件扫描）
- 后端直连：/ 与 /assets/* → 404（{"code":40001,"msg":"接口不存在"}）、
  /api/.../captcha → 200 + no-store、/doc.html → 302→200、/v3/api-docs 与 /actuator/health → 200
- 经 nginx(80)：首页 200 + no-cache、/assets/*.js 200 + immutable、/nope.js 404（无回退）、
  /api 200 + no-store、gzip 生效；2MB multipart 上传 → 401（与直连一致 ⇒ 未踩 1m 的坑）、
  55MB → 413
- e2e（XT_BASE=http://localhost，全程走 nginx）：e2e-m0.py 37/37、e2e-m3-h5-auth.py 24/24、
  e2e-m2-scope.py 38/38
- verify-all.py --quick 6/6；check-test-profile.py：test profile 仍能起来
 2026-10-19 17:35:33 +08:00
lovife a9b2dd2a16 docs: 登记 F-125~F-130 并同步脚本数 37→38 
三个 P0 本轮只测不改、先记账：F-125 学生被驳回后改不了任何东西（改字段/传材料/
删材料全 40030、撤回 40001，而重新提交是允许的，四处信号都说他能改）、
F-128 扩展字段存得进读不出、必填扩展字段会让整个任务永久无法提交（内置表单一个
扩展字段都没有，所以从来没有数据走过这条路）、F-130 小程序端登录断成两截
（前端从没调过 /mp/login，后端 scene 带 taskId 必然 500）。

README 补 docs/11 的入口，AGENTS.md 补小程序端现状与 38 个脚本的新口径，
问题清单补 F-126/F-127/F-129 三条与 F-125/F-128/F-130 的修法方向。
 2026-10-14 15:40:18 +08:00
lovife 4e68d0e5da test(e2e): 新增填报流程端到端脚本与测试计划 
既有 37 个脚本是按模块切片的（门禁/草稿/提交/审核各一个），有三处固定盲区：
跨步骤的状态轨迹没人断言、切片之间那条缝（驳回后改了字段再交）、以及脚本
docstring 自述与实际断言不符（e2e-m3-draft.py:11 自述的那条断言全文没有）。

docs/11 给出 A~J 十组覆盖矩阵与判据口径（含用 grep 核对实际断言、不读自述的
规程），scripts/e2e-m3-flow.py 只补这三处、其余交给既有脚本，并钉住 F-125 /
F-128 的现状（XFAIL）。verify-all 的脚本数口径随之变成 38。

配套 scripts/dev-reveal-roster-idcard.py：L3-B 走查要在门禁界面手输身份证，
而明文只在建夹具那一刻存在过（库里是 AES 密文 + 脱敏 + HMAC 索引），
此脚本只读解密打印，不入库；用完连同夹具任务一起 --clean。
 2026-10-14 15:40:18 +08:00
lovife 623e6393d5 fix(pc): 弹窗遮罩改毛玻璃并清掉 9 处提示折行 
遮罩底色被 Naive 写死在 css-render 里（Modal / Drawer 主题没有 mask token，
themeOverrides 改不到），只能上 CSS；加 backdrop-filter 后遮罩后面的页面糊掉、
弹层本体仍是纯白，NModal / NDrawer / useDialog 共用 .n-modal-mask 一条规则覆盖。

折行的根因是格子宽度写死（半宽 264px / span 8 192px / 定宽 160px），与窗口宽度无关：
能压短的压短；「文件名预览」那处是 .n-form-item-blank 属于 flex 行、把提示挤成 3 行，
改成包一层块级容器；材料预览失败的占位在 108px 小格里曾折 3 行且被裁掉。

约定写进 frontend-pc/AGENTS.md 第 11 条与 code-css skill；实测与刻意不改的清单见
docs/交接摘要.md 的 §一·四十二。
 2026-10-14 15:34:40 +08:00
lovife e94e76ba0f fix(pc): 找回被 #feedback 吞掉的表单校验错误 + 收集任务文案精简 
naive 的 NFormItem 一旦用了 #feedback 插槽，renderExplains 就永不渲染
（children || feedback ? feedback : …），校验错误被完全遮住 —— 用户看到的是
"红框 + 一句无关的正常提示"，现象上等价于"点了保存没反应"。RoleFormModal 里
早就记录过这个机制，但只在自己那个文件绕开了，没固化成约定，于是扩散到 7 处。

- 7 处 validate() 的 catch 改成 message.error(firstError(errors) ?? 兜底)
  （login / org / role / user / task 建改任务 / 材料规则 / 表单设计）
- ⚠️ firstError 必须摊平后再取：naive reject 出来的是嵌套数组，
  errors[0].message 恒为 undefined，兜底文案会把每条错误都吞成"请检查表单填写"
- 批次号在"修改"时置灰（task_code = 批次号 + 4 位序号，且同时是文件目录名，
  而服务端 update 无条件写 batch_no、没有"编码已生成"的保护）
- 删掉「本期范围」区块（收集模式 / 认定类型恒定，请求体里仍写死 1）
- 清掉教材式描述：extras_json / extra_ 前缀 / 幂等 / 接收能力 / 识别结果只用于提示
- 规则沉淀进 frontend-pc/AGENTS.md 第 10 条与交接摘要 §一·四十
 2026-10-13 15:06:34 +08:00
lovife 31e7483464 docs: 同步契约 §6.5~6.9 / §13.4、问题清单 F-112~F-124、交接摘要 §一·三十九 
1) docs/03-接口设计.md：
   - §6.5 补 expireBefore **含当天**的语义与"格式不对返回 40001，不静默忽略筛选"；补
     "列表 contactPhone 恒为 null"与"packageName 与内嵌 usage{} 不实现（200 行内嵌用量会变成
     N+1 统计）"。
   - §6.6 的 tenantType 由 3 值改回真实的 **4 值**（1 学校 / 2 认定机构 / 3 报名点 / 4 企业）、
     packageId 由 ✅ 必填改为可选（DTO 里本来就是可选），并补副作用（发放 6 个内置角色 + 建管理员
     + 写 CREATE_TENANT 日志）。
   - §6.7 的响应示例原来写着 ocrCount=3105 / smsCount=420，**与实现恒 0 矛盾** —— 改成 0 并补齐
     契约没写的 notes 与 alerts.used/limit，再加三条口径：实时值 vs 周期、恒 0 的原因（编数字会让
     运营拿假数据去谈续费）、**只算这一个租户**（含"库里只有一所学校时看不出"这一点）。
   - **新增 §6.8 / §6.9**（PUT /tenants/{id} 与 GET /tenants/{id}）：PUT 此前只在 §4.2 的总览表里
     出现过一次、全文**没有详情节**；GET 更是只登记在 §17.1 的"清单漏列"组里。§6.8 含字段表、
     "不传的字段不修改"、"tenantCode 不可修改"的理由，以及留痕对照表（status→0 是 DISABLE_TENANT，
     不是 UPDATE_TENANT）+ "这些日志行的 tenant_id 是 0，要用 target_type/target_id 查"的警告。
   - §13.4 的 Query 补 targetType（并说明为什么 targetType+targetId 才是最重要的查询方式：
     关键字全文匹配会把"改了它"和"顺带提到它"混在一起，而合规结论不能建立在这种匹配上）；
     响应补 request_method / request_uri / extraJson；动作表由 9 行扩到**全集 27 个**并按来源分组
     （任务 / 名册 / 导出 / 角色 / 租户）；写明 request_param / duration_ms 刻意不采集；
     并记下"一期只做查询、不做日志导出"这条**此前只写在 LogController 类注释里**的口径
     （导出等于把"谁在什么时候看了谁的身份证"这份名单落到本地磁盘，而导出行为本身也要留痕）。
   - 登录日志响应补 tenantId，并写明 userType 的权威枚举与 location 恒为 null。

2) docs/08-完成度盘点与问题清单.md：新增 **F-112~F-124** —— 用量越界（含"为什么本地完全看不出来"）、
   PUT 明文写入加密列、两个枚举能建不能改、租户零留痕、expireBefore 差一天、AUTO_CLOSE 字面量、
   模块下拉里有死项、LogController 描述与事实相反、request_param/duration_ms 有列无写入点、
   schema-postgresql.sql 缺三张表、**"平台专属权限码 + 查带 tenant_id 的表"这个风险面**、
   登录日志缺租户列、userType 注释错位。F-112 标注为本轮最严重的一条。

3) docs/10-用户手册与客服话术.md：「三种角色，三个入口」→ **四种角色**（补平台运营，并写明它是
   唯一跨单位的角色、用"组织与账号/收集管理"这类单位内页面之前要先选"当前学校"）；
   §4 速查表的菜单名与路径同步（平台运维 → 日志，含两个页签；新增租户管理一行）；
   附录的排查话术补 traceId（"日志详情里能拿到，那是后端排查时最有用的一个线索"）。

4) docs/交接摘要.md：新增 **§一·三十九**，九节 —— 一、口径变更（旧注释原文 + 推翻理由）；
   二、用量越界那个 bug 的完整来龙去脉（权限码 → ignoreTable → 实测数据分布 → 修法与夹具）；
   三、另外四条后端缺陷表；四、日志详情为什么不新增接口（轻字段 vs 全库 0 行有值的重字段）；
   五、AUTO_CLOSE 与检查 ⑩ 的关系（**"这一族检查的价值取决于被检查的那一侧有没有被规范化"**）；
   六、顺带修掉的五处；七、前端刻意用分段按钮而不是 NTabs 的两条原因；八、验证表 +
   "改了后端必须重新打包重启、判据是看返回体里有没有新字段"的提醒；九、约定同步。
   另把 E2E 断言总数 1595 → **1617**（四处）。

5) 根 AGENTS.md：接线检查说明补第 ⑩ 项，并写明做这一项时才发现 AUTO_CLOSE 是字符串字面量写的
   —— "提成常量"是让这个检查真正生效的前提。

验证：python scripts/verify-docs.py **22/22**；python scripts/check-wiring.py 未接线 **0 条**
（⑦ 11 个权限码 / ⑧ 0 处漏 import / ⑨ 3 个 SVG 全合法 / ⑩ 27 个动作码两端逐字一致）；
python scripts/check-api-parity.py 契约 **119** / 已实现 118 / 缺口 1 —— **没变**，符合本轮
"不新增后端接口"的决定。
 2026-10-13 14:04:59 +08:00
lovife 624a05aa66 feat(pc): 平台运营的租户管理（详情/用量/编辑/停用）与日志详情 
需求：「设计开发平台运营人员对租户的管理功能，还有日志的详情查看功能。」

⚠️ **口径变更**（覆盖 2026-10 走查的旧结论）：views/tenant/index.vue 原先写着「列表**没有操作列**：
不提供编辑 / 停用入口（客户 2026-10 走查确认的口径）」。本轮用户明确选了全量范围，所以列表现在
有操作列（详情 / 编辑 / 停用·启用）。旧注释是**改写而不是删掉**，并写明推翻理由 —— 运营的真实
诉求是：① 到期日变了要能自己改，而不是每次找开发；② 欠费 / 停止合作时要能当场停掉；
③ 每周核对"谁快到期了"时要能点进详情看用量。

1) 租户管理：操作列用 tenant:view 门控「详情」、tenant:manage 门控「编辑 / 停用 / 启用」，
   拿不到管理权限时整列显示"只读"，而不是留一个点了报 403 的按钮。停用走 NPopconfirm 二次确认
   且文案写明后果（"停用后该校所有学生与老师会立刻无法登录"）；只发 {status} 一个字段 ——
   PUT 是部分更新，回传整行会把列表里看不见的字段覆盖成空。

2) 详情抽屉 TenantDetailDrawer：打开时**同时**调 getTenantDetail 与 getTenantUsage ——
   列表接口的 contactPhone **恒为 null**（电话以密文入库，列表不能成为批量拉取联系方式的通道），
   脱敏值只有详情接口给，拿行数据凑详情会显示成"没有联系电话"。用量区写明"学生数与存储是**实时值**，
   周期只影响计费项"，否则会以为"2026Q3 的学生数"是历史值；notes 如实全列（它解释"为什么这几项是 0"）。
   统计周期只给本月 / 上月 / 本季三个固定选项，不做自由文本输入。

3) 编辑弹窗 TenantEditModal：类型 4 选项、状态 3 选项；数字下拉的校验规则必须带 type: 'number'
   （只写 required 会"看起来填了但校验不过"，而且 #feedback 会把报错遮住）；联系电话留空 = 不修改；
   租户编码只读展示并注明"出现在扫码落地页与对接文档里，开通后不可修改"。不做"清空到期日"
   （MyBatis-Plus 忽略 null 更新，清不掉就不在界面上承诺）。

4) 日志页：操作日志 / 登录日志两个模式，各自维护 list / total / pageNum / pageSize / loading /
   筛选条件，切换时重置到第 1 页。⚠️ 页签用工具条上的**分段按钮**而不是 NTabs / NTabPane：
   ① NTabPane 的内容要额外 flex 化才能维持 .page-card 的高度链，否则表格高度算成 0、
   **一行数据都看不见**（本仓踩过）；② naive 2.45.3 的 tab="..." 属性写法本身也是坏的，
   必须用 #tab 插槽。

5) 日志详情 LogDetailDrawer：变更前后**完整不截断** + break-all + 各一个复制按钮；
   extraJson 格式化成 <pre>（解析失败原样展示）；traceId 带复制；request_param / duration_ms
   如实写"本版本未采集"（这两列从来没有写入点），不编。抽屉**不再打接口** —— 列表 SELECT 已经
   把抽屉要的字段都带出来了。

6) 「单位」列只对平台显示（0 → 「平台」），两张表统一用「单位」这个词：这一列要装得下
   tenant_id = 0 的「平台」，表头写「租户」而格子里写「平台」是自相矛盾的；且与筛选栏两个下拉的
   占位符、租户管理页的「单位名称」一致。登录日志刻意**不要「归属地」列**（location 恒为 null，
   整列空白看起来像功能坏了）。

7) 日志页的模块下拉换成导出的 MODULE_OPTIONS / TARGET_TYPE_OPTIONS：原先那 4 项里 AUDIT / EXPORT
   **后端一个写入点都没有**，而真会写的 FILE（代传材料）与 ROLE（6 个角色动作）**不在里面** ——
   选中死项只会得到一张空表，让人以为"这段时间没有审核动作"。

8) 菜单显示名「操作日志」→「日志」（key 保持 'log' 不动：后端 BuiltinRole 的菜单键与
   check-wiring 第 ⑥ 项都按它核对，改 key 会让平台角色的菜单静默少一项）。

同步 frontend-pc/AGENTS.md 与 .agents/：「最容易写错的约定」由 7 条扩到 **9 条** —— 新增
第 8 条「详情用抽屉、不要为详情新开路由」（含"列表接口可能刻意不返回某个字段"的坑）与
第 9 条「页面内的页签用工具条分段按钮」（写明高度链的原因）。

验证：pnpm typecheck **0 错**、pnpm lint **0 错 0 警告**、pnpm build 通过。
浏览器实测（平台账号，5173 + 8080）：租户页出现操作列且三档到期配色正确、卡片上内边距仍是 16px、
高度链未破（表格 570px / 日志表 528px）；详情抽屉显示脱敏电话 138****8000 —— 而库里存的是
**历史明文** 13800138000，也就是说这条同时验了"读路径容错"（否则是永久 500）；停用二次确认文案
正确；清空单位名称提交后弹窗不关且错误可见；登录日志同一张表里同时出现「示范职业学校」
（tenant_id=1）与「平台」（tenant_id=0）两种映射；**学校管理员视角两张表都没有「单位」列**。
 2026-10-13 14:04:53 +08:00
lovife b516a7c47b fix(tenant,log)!: 平台身份下用量统计算成全平台 + 5 处租户/日志缺陷 
做「平台运营的租户管理」时挖出来的，其中第 1 条与那个功能本身无关、但严重得多。

1) 🔴 GET /tenants/{id}/usage 一直算的是**全平台**的数。平台运营的 tenantId 是 0，而
   FillTenantLineHandler.ignoreTable() 对平台身份直接返回 true —— 整张表的租户过滤被关掉，
   于是 distinctStudents()（查 collect_roster）与存储量（查 collect_file）都不带租户条件，
   返回全平台数字却标着某一所学校的名字，运营会拿它去谈续费。而这个接口的调用者**一定是**
   平台运营（tenant:view 在 platformOnlyCodes 里），所以它从来只在"过滤被关掉"的上下文里跑过。
   ⚠️ 本地完全看不出来：实测 34 行 collect_roster、22 行 collect_file 全在 tenant_id=1，
   只有一所学校有数据时错误值与正确值**完全相等**。修法：统计段包进既有的 TenantScope.callAs，
   切走后 isPlatformAdmin() 变 false、过滤自动恢复；**没有**手写 tenant_id 条件 —— 那等于
   放弃拦截器的保护。

2) PUT /tenants/{id} 把手机号**明文**写进加密列（create 走 codec.encrypt，update 是裸赋值）。
   AesGcmCipher.decrypt 对非 Base64 直接抛（该类没有 dev 旁路）→ 存过一次电话，这所学校的
   详情页就永远打不开。库里 id=1 存的就是明文 13800138000。改为非空才加密写入（空 = 不修改），
   详情返回脱敏值；**读路径必须容错**（解密失败按明文处理 + WARN），否则故障形态是"永久 500"，
   看起来像系统坏了、而不是"库里有一行旧数据"。历史明文行不做迁移（迁移里拿不到密钥）。

3) 租户两个枚举"能建不能改"：tenantType 只放行 1~3（实体/DDL/契约/前端都是 4 值）、
   status 只放行 0/1（实体有 2 试用，而前端的状态筛选按钮里就有「试用」，选了永远是空列表）。
   已按真实枚举放开，报错文案与实体注释逐字对齐。

4) 开通/修改/停用租户原先一条日志都不写（只有给运维看的 log.warn/log.info）。新增
   MODULE_TENANT 与 CREATE_TENANT/UPDATE_TENANT/DISABLE_TENANT/ENABLE_TENANT —— 停用与启用
   不并进 UPDATE_TENANT：停用是这套系统里影响面最大的单个动作，出争议时第一个要看的就是这个
   区别。⚠️ 这些行的 tenant_id 是 0（写日志用的是**操作者**的上下文），查"这所学校被谁停过"
   要用 target_type=TENANT + target_id，**不能**用 tenantId 筛（反直觉，已写进常量注释）。

5) expireBefore 用 atStartOfDay() 与存进去的当天 23:59:59 比 → **差一天**，「今天到期」的租户
   查不出来（同型的坑在 LogController.parseTo 上修过一次，那次是"查 9 月 30 日查不到当天"）。
   改为补到当天末尾。格式不对返回 40001 并说明格式 —— **刻意不学** parseTo 的"当没传"：
   那侧是界面上的自由文本输入，静默忽略是为了"输错了也别让人看不到日志"；这侧的值只由界面按
   当前日期算出来，静默忽略筛选会让人以为"我按到期日筛过了"。

6) 顺带：
   - AUTO_CLOSE（定时任务自动截止）在 TaskService 里是**字符串字面量**、不在常量表里 ——
     也就是说"后端常量 ↔ 前端文案"这类检查**本来就扫不到它**，而它正是量最大的那类任务日志，
     界面上会原样回显英文码。提成常量（连带 STATUS_CHANGE 兜底名）。
   - 日志列表 SELECT 补 request_method/request_uri/extra_json 三个**轻字段**（实测一页 20 行
     约 2 KB），日志详情因此不需要新开接口；真正重的 request_param/duration_ms 全库 1758 行里
     **0 行有值**（从来没有 setXxx 过），不采集。
   - LoginLogVO 补 tenantId：平台运营看到的登录日志是**跨单位**的，没有这一列就分不清一行是
     哪所学校的，而"某个账号什么时候登进来的"一定得连着"哪个单位"一起回答。
   - 修正 LoginLogVO.userType 的 Javadoc：原来写着「1 超管 / 2 管理员 / 3 教师 / 4 学生」，
     与权威口径（1 平台运营 / 2 学校管理员 / 3 班主任 / 4 学生）错位 —— **同一个坑第三次出现**，
     该错位枚举曾导致"把班主任当成社会人员拒掉"。

新增检查 scripts/check-wiring.py 第 ⑩ 项：后端会写的动作码 ↔ PC 端 OPERATION_ACTIONS 的文案，
逐字核对（缺一个文案，日志页就会原样回显英文码）。**已反向验证**：删掉一条文案 → 报红 + exit 1。
⚠️ 写这个检查时踩到的坑：同文件里 MODULE_OPTIONS / TARGET_TYPE_OPTIONS 也是 { value: 'TASK' }
的形状，整文件扫会把模块名当成动作码收进来 —— 所以只从 OPERATION_ACTIONS 那个数组里取。

验证：python scripts/verify-all.py --with-e2e → **9 项全过 / 0 失败 / 0 跳过**（37 脚本 /
1617 断言）。e2e-m8-orgfile.py **74/74** —— 其中"用量只算这一所学校"这条**必须造夹具**才
证伪得了：它往新建的 E2E 租户**直插一行 collect_roster**（该表 NOT NULL 且无默认值的列只有 5 个，
不需要走导入夹具），再断言"接口值 == 库里 where tenant_id=1 的去重数"，并**额外断言
"全平台去重数 > 一号学校去重数"**，否则这条断言是空转的。e2e-m5-logs.py 44/44（回归）。
重打包重启后再验一次：/logs/logins 返回 tenantId、/tenants/1 返回 138****8000（而不是 500）——
判据是**看返回体里有没有新字段**，而不是"接口通了就算"。
 2026-10-13 14:04:48 +08:00
lovife 9f6d26c650 fix(e2e,pc): 不再产生跨租户同名的登录账号 
账号唯一性是 (tenant_id, username)，跨租户重名本身是合法行为（登录靠租户码区分）；但默认值与 e2e 残留会让它变成默认状态：不带租户码登录会撞上 40012（该账号存在于多个单位），平台侧看账号也分不清哪个 admin 属于哪所学校。三处一起收口 ——

1) scripts/e2e-m0.py 跑完不再留租户：以前每跑一次就留下一个 e2e###### 租户 + 里面叫 admin 的管理员 + demo 下 3 个测试组织，库里那两个孤儿租户就是这么来的。现在按本次跑出的 id 自清（崩溃路径也兜住），不越界成 LIKE 'e2e%' 全清。

2) scripts/e2e-m1-tenant-domain.py 自己造、自己清「另一个租户里也有 admin」的夹具：它原本靠第 1 条的残留凑出 40012 这个前提，残留一被清掉就会静默反转成 8 条 FAIL。顺带修掉同族的第二处隐式依赖 —— 它假定 t14.localhost 是个真实租户，而那个租户早就不存在了。

3) PC 端「开通租户」的登录账号默认值不再写死 admin，改为跟随租户编码生成 admin_<编码>；运营一旦手改就不再被编码覆盖。

验证：全量 python scripts/verify-all.py --with-e2e 通过（37 脚本 / 1597 断言 / 0 失败），跑完库里仍只有 1 个租户、0 处跨租户重名；PC 端 pnpm typecheck 0 错、pnpm lint 干净、check-wiring 未接线 0 条，浏览器实演默认值跟随与手改不回退。
 2026-10-13 10:21:40 +08:00
lovife 7df078e0ea docs: 同步交接摘要 / PRD / 原型，并记录品牌改名「深学在线」 
- 交接摘要补 §一·三十五~§一·三十八：角色与授权、需求收敛（4 角色 / 10 菜单 / 取消二期）、
  PC 端重搭后的 UI 修复与卡片式基线、品牌改名与新标识
- PRD 与功能逻辑卷只改标题行与产品代号线；**文件名不动** —— verify-docs.py 按路径读，
  全库还有 20+ 处按文件名引用，改名会连带炸脚本
- 原型 index / admin-web / teacher-app / student-app 的品牌区改「深学在线」，
  admin-web 的 .mark（10 处）换成内嵌的新标 data URI，保持原型"单文件自包含"的约定
- 根 AGENTS.md 与 frontend-pc 的规范同步：接线检查补第 ⑨ 项（SVG 资产是不是合法 XML ——
  SVG 注释里出现连续两个减号就 not well-formed，图标裂开而控制台一句话都不报）、
  「最容易写错的约定」6 -> 7 条（新增品牌标）
- deploy/docker-compose.yml 只改头注释里的项目名（compose 的 name 与七牛对象前缀都没动）
 2026-10-10 16:49:04 +08:00
lovife 1f3c485ceb feat(role,scope)!: 角色与授权可配 + 需求收敛（4 角色 / 10 菜单 / 删两模块） 
角色与授权（交接摘要 §一·三十五）：
- 权限判定合并两个来源：内置角色按代码（BuiltinRole）、自定义角色按库
  （sys_role_permission）。实现放 module 层的 DbRoleGrantSource，security 只依赖
  接口 RoleGrantSource —— 否则角色服务要调 permissionChecker，两个包迟早成环
- 权限判定必须加缓存：此前是零 IO，而压测基线是"SQL 条数恒定"。缓存放 Redis，
  空结果也缓存（否则已删角色的 token 会把库打穿）、Redis 挂了退化成直读库、TTL 只兜底
- V18 建 sys_role.user_type（账号的 user_type 一直从角色反推，自定义角色不在代码映射里）
  与 sys_role_menu；8 个接口 + 错误码 40045；契约 119 -> 129
- 内置角色只读（权限码是前后端契约，做成可改 = 一次误操作就能把管理员锁在系统外）；
  平台级能力两道防线（界面禁用 + 服务端 40301）；防自锁；改完立即生效（写授权清缓存）
- RoleProvisioner 从"已存在就 continue"改成幂等回填 + 每日 03:20 定时任务 ——
  修的是"代码改了权限、已开通租户永远停在发放那一刻"，这种漂移不报错也没测试会红
- scripts/e2e-m10-role.py 77/77

需求收敛（交接摘要 §一·三十六，本节的数字为准）：
- 删副班主任 / 审核员两个内置角色（6 -> 4）、历史整理器（module/cleanup）、
  加入申请（module/join + 学生端 pages/join）、collect_task_org.deputy_user_ids 整列；
  审核范围三级回退 -> 两级，连带 6 个 mapper 的 LIKE '%,id,%' 分支
- V19 迁移处理存量：先解 sys_user_role 绑定再软删角色；账号只在"除这两个角色外没有
  别的角色"时才软删。必须迁而不能只删代码 —— 角色码删掉后 mergePermissions 返回空集，
  存量账号会"能登录、处处 40301"，不抛异常不打日志
- 契约 129 -> 119、错误码 59 -> 54、权限码 30 -> 28、PC 菜单 12 -> 10、
  小程序页 10 -> 9、原型 32 -> 29 屏、E2E 39 -> 37 个（断言 1695 条）
- UserService.list 对不认识的角色码由"静默丢掉过滤条件"改成失败关闭
  （之前传个不存在的 roleCode 会返回全校账号，且看起来完全正常）
- 品牌元信息同步改名「深学在线」：pom 名称、/doc.html 标题、配置与启动类注释、
  存储自检探针内容；学生端 app 名与全局导航栏标题
 2026-10-10 16:48:54 +08:00
lovife 5b877451eb refactor(pc): 从 Gi Admin Pro + Arco 重搭为纯 Vue 3 + Naive UI 
旧模板的 193 个文件整体删除，换成纯 Vue 3.5 + Naive UI 2.42 的树。

- 去掉 auto-import（组件与 API 全显式 import）、v-hasPerm（改 user.has('码')，全库 8 处）、
  Stylelint；n-tag 的 type 统一过 utils/tag.ts 转换（Arco 色词直接透传会静默变灰）
- 图标改为构建期抽取：scripts/extract-pc-icons.py -> icons/icon-data.ts（37 个），
  内网离线部署不会白屏
- 重搭后修掉 6 类"编译 / lint / typecheck 全绿、界面上就是坏的"故障：
  ① NGrid 的 cols 写成像素值（不是断点名 -> 永远只 1 列，工作台因此错乱）
  ② n-tab-pane 用 tab 属性（只渲染空注释节点，整排 tab 一个字都不显示）
  ③ 漏 import 被当未知自定义元素（样式整块丢） ④ .n-card__content 类名不存在
  （高度链第一环失效，表格行在 DOM 里但屏幕上没有） ⑤ 填报单状态映射错位一格
  ⑥ 有标题的卡片没有上内边距（naive 的 padding-top 只给"内容区是长子"的卡片）
- 卡片式版面提成全局基线：styles/index.scss 的 xt-* 令牌 + .page-card / .toolbar /
  .section-title，页面只引用、不再各写一套
- 品牌：改名「深学在线」，文字标换成几何标（方 = 卷宗 / 环 = 在线，不用文字字形）；
  index.html 的页签图标从 404 的 /favicon.ico 改指真实存在的 /favicon.svg
 2026-10-10 16:48:46 +08:00
lovife 0bbac7d228 feat(pc,platform): 验收走查修复（平台按学校代管 + 菜单/403/日志范围/分页） 
客户在验收里点出来的问题，一次改完。两段改动：

一、平台运营与租户范围（后端为主）
- 新增请求头 X-Tenant-Id：平台运营是唯一跨租户身份，租户拦截器对它整体关掉了过滤，
  于是「组织架构 / 账号管理 / 工作台」拿到的是所有租户混在一起的数据 —— 而只有一所
  学校有数据时，它和学校管理员看到的完全一样，看不出错（这是最危险的一点）。
  现在这些页面必须先选定学校，服务端再把本次请求的租户上下文换成目标租户：
  只认平台身份（其它身份带头一律忽略）、目标租户必须存在且启用。
- OrgService.tree / UserService.list 补显式 tenant_id 条件（原来只靠拦截器，而拦截器对
  平台不生效）；TaskService.seesWholeTenant 改用新的 LoginUser.isPlatformStaff() ——
  isPlatformAdmin 回答"当前租户是不是平台租户"，代管时它为 false，会让平台退化成普通
  用户（任务列表掉进"班主任只看自己带的班"分支，得到空列表）；PLATFORM_ADMIN 补
  TASK_VIEW（PRD §3.2「查看填报进度看板：平台运营 ✅」）。
- 操作日志对平台永远是空的：SQL 写死 tenant_id = 当前租户，而平台的 tenantId 是 0。
  按契约 §13.4 补 tenantId 参数与 log:viewAll：平台默认看全量、可指定某所学校；
  学校管理员恒为本租户，传别家返回 40301（不静默忽略，否则会让人以为"筛过了"）。
- 开放接口"推送重试"从未生效（F-112）：定时扫描缺 @InterceptorIgnore，异常被 log.warn
  吞掉；同一方法里"接入方已停用"那条 update 也没有租户上下文，会每 10 秒重试到永远。
  E2E 补了"真的重试了"的断言（原来只断言"安排了下次重试"）。

二、PC 端走查体验
- 去掉 3 条无用菜单（名单管理 / 表单设计器 / 材料规则）：功能都在「收集任务」行内入口，
  菜单里那一条点进去只有指路；后端菜单键同步删除，entryAt 那套机制一并删掉。
- 班主任点工作台必弹 403：工作台无条件调了要 org:view / progress:viewAll 的两个接口。
  403 走 HTTP 状态码，try/catch 拦不住它的弹窗 —— 改成按权限决定发不发请求。
- 操作日志：分页器被裁在可视区外（新增 .g-list-card 让表体自己滚、表头钉住、分页器留在
  卡片底部）+ 去掉页面上那段免责声明；收集任务的状态切换改成单独一行 tab；去掉顶栏假数据
  铃铛；配色按客户要求还原。

顺带修两处"检查器自己不严"：check-wiring 新增第 ⑦ 项（PC 端引用的权限码必须存在于
PermissionDef —— 本轮我自己把 progress:viewAll 写成 progress:view:all，判断恒为 false，
而编译 / typecheck / lint / E2E 全都不红）；verify-docs 的表格列数检查不再把 GFM 转义
竖线当成列分隔符。两个检查器都拿"故意写错的样例"试过，确认真的会红。

验证：typecheck / mvn package / check-wiring（未接线声明 0 条）/ verify-docs（22 项）全过；
e2e-m0 36、e2e-m1-orgs 48、e2e-m0-user 55、e2e-m5-logs 44、e2e-m5-notify-wiring 43、
e2e-m1-tenant-domain 6、e2e-m8-open 61 全绿；浏览器按角色逐个真点复验。
详见 docs/交接摘要.md §一·三十三 与 §一·三十四。
 2026-10-09 17:29:20 +08:00
lovife db8aecc30a chore(e2e,docs): 新脚本的清理只删自己建的模板行（不碰演示态）+ docs/09 §8 补接线检查 2026-10-08 14:47:11 +08:00
lovife 9e78e1d239 feat(notify): 通知接线检查 + 修 F-101~F-111（模板对自动通知生效 / 催报真的会发 / 该发的通知都发了） 
起点：F-1/F-31/F-50/F-52 是同一个形状 —— 每处单看都对，编译/lint/review 全不红，只有从入口走一遍才暴露。先把这一类固化成命令，再按输出逐条修。

新增 scripts/check-wiring.py：权限码有没有地方校验、错误码有没有被引用、站内信模板有没有发送点、bizType 有没有被用过、菜单键 ↔ PC 端 XtMenu 双向核对。有意不接线的写进脚本上方例外表（带理由）。进 verify-all（第 5 项）与 CI 的 check 阶段。检查器自身修了三次假阳性：只数 @RequirePerm 漏掉服务层校验、按标识符数引用被同名常量骗过、注释里的提及被当成接线（改为先去 Java 注释再数）。

F-101 自动通知改走可配置模板（FR-1002 原来只兑现了手工发送那一半）：新增 NotifyTextResolver（单向依赖避开循环注入），库里改过的 > 内置；模板停用 = 这类通知不发且如实回 notifySent=false。F-102 加入申请三处通知（提交→审批人、通过/驳回→学生）。F-103 导出完成/失败通知发起人，正文不放签名 URL（模板里原本写着 {下载链接}，一并改掉）。F-104 自动催报从来没发出过任何一条（end_time = date::date 与库里的 23:59:59 永不相等，测试夹具用 SQL 摆的日期型恰好能匹配）+ 补 FR-1003 的「截止当日」。F-105 驳回达上限通知管理员（契约与注释都写了，代码只有一行日志）。F-106 字典/通知记录两个菜单没有任何角色持有（手册还写着去那里办）。F-107 6 个权限码挂到自己的接口。F-109 Map.of 不接受 null → 通知被吞成一行 warn。F-110/F-111 测试自身的两个坑。

验证：新增 e2e-m5-notify-wiring.py 43 条（改模板→真驳回→断言学生收到改过的那句、停用→一条不发、申请/审批/导出/催报/升级/菜单/权限各一节）；verify-all --with-e2e → 9 项全过 0 跳过，38 个脚本 / 1620 条断言 / 0 失败。
 2026-10-08 14:46:11 +08:00
lovife 4a5790d900 chore(clean): 测试数据三本账清完（库 / 磁盘 / 七牛桶）+ 100 条问题全部核销 
一、dev-clean-e2e.py：加「在用组织保护」后执行
  · 先算「仍被存活任务引用的组织」并保留 —— 当前演示态就挂在其中一个
    「E2E 24数控1班」上，删了它演示态就坏（保留 3 个，演示态完好：
    任务 1449 / 名册 3 人 / 组织 43 都在）
  · 已执行 --apply --demo-tasks --orphan-files：
    49 个 e2e 租户 + 147 个测试组织 + 84 个【演示·旧】任务，
    共 3714 行 / 27 个文件（业务表按 information_schema 动态枚举，不写死清单）

二、dev-clean-qiniu.py（新增）：清真实桶里本项目前缀的测试对象
  · 只动 xiaotutongxue/ 前缀；默认 dry-run；删前核实库中零引用、
    数量异常（>5000）直接停
  · 已执行：2036 个对象 / 116 MB 全部删除，删后复验 0 个（F-93「删库不删桶」）
  · 签名按官方文档逐字核对 —— 踩了两个 401 才对：旧 QBox 格式（一个换行 +
    "QBox " 前缀）不对，是「两个换行 + Qiniu 前缀」；batch 的 Body 必须进
    签名串（列举无 Body 能过、批删全 401 —— 同一签名函数一好一坏，线索在 Body）
  · 列举在 rsf.qiniuapi.com，不在 rs（打错 host 报「Bad method: list」）

三、xt-minio 容器已删（F-2）—— 代码早已不用 S3，deploy 里也没有它

四、文档核销与记录
  · docs/08：F-3/4/7/10（小节）与 F-14/26/29/30/31/38/51/57/64/65/71/72/93
    （表格行）全部标「已闭环」；F-5 补执行记录；F-28 备案维持两级（→D-11）；
    变更记录补两行 —— **F-1~F-100 至此无未决项**，剩余全部等外部输入
  · docs/01：新增 E4「国标职业库数据来源待客户确认」（F-34，字典页如实显示 0 项）
  · 交接摘要：新增 §一·三十一（17 项决策执行记录）
  · AGENTS.md：清理一节写清三个工具与「在用组织保护」

验证：python scripts/verify-all.py --with-e2e →
      通过 8 / 失败 0 / 跳过 0（37 个 E2E 脚本 / 1577 条断言 / 0 失败，291s；
      prodguard 9/9；test profile 能起）
 2026-09-30 12:38:55 +08:00
lovife f89cd998ef test(unit): 三个纯函数的最小单测（12 条）—— 本仓库第一批单测（F-9） 
后端验证一直靠 E2E（打真实接口，很硬但要起服务连库）。这批先给
「输入输出确定、没有 IO」的纯函数补最小单测，成本最低、回归收益最高；
其余继续靠 E2E，不为了覆盖率硬凑。

· IdentityNormalizerTest：姓名去所有空白但**保留间隔号**（少数民族姓名的
  「·」是真实的，顺手清掉等于改人名字）、全角转半角、证件号小写 x 收尾统一、
  null 不抛 NPE
· FileProcessServiceTest：扩展名必须自带点号（少一个字符不报错，只会产出
  「身份证jpg」这种客户双击打不开的文件 —— F-46）、空变量用「未填」占位
  （留空会出现「张--身份证.jpg」）、文件名里的 / 必须清掉（「学籍表(1/2)」
  带 / 根本写不进磁盘）、超长截到 90 且不吃掉扩展名、sanitize 收拢连续分隔符

每条断言都对应一个真实踩过的坑 —— 断言的是「有理由的规则」，不是覆盖率。

验证：mvn test → 12/12 通过（exit 0）
 2026-09-30 12:38:48 +08:00
lovife 57bf39d5a1 feat(notify,log): 催报分钟级限流 + 学生微信登录写登录日志（两处合规补漏） 
一、催报分钟级限流（F-29，契约 §3「10 次/分钟/任务」此前未实现）
  · UrgeService 加 Redis 计数：定向与一键催报共用，超限 42901
    且话说清等多久、24h 去重还在（去重防「学生被重复催」，限流防「老师连点
    把系统打爆」—— 两件事）；限流放在「确实有活可干」之后（空结果连点不计数）
  · Redis 不可用时放行不瘫痪（限流是保护，不是业务前提）

二、学生微信登录也写 sys_login_log（F-31 —— 此前只有 PC 账号密码登录留痕，
   按 §13.4 查「学生登录记录」永远为空，合规缺口）
  · 新增 WechatLoginLogger：小程序登录（MpLoginService）与 H5 授权回调/
    打桩登录（MpH5AuthController）三条路径都写
  · login_type=2 与 DDL 注释对齐（1 PC 2 小程序 3 开放接口）；H5 与小程序
    共用 2（DDL 只定义到 3，不造新值），要区分看 userAgent —— 字段里本来就带着
  · 写失败不影响登录（日志表满了不能没人能登录）；不记 code/openid

验证：e2e-m5-urge → 42/42（新增「连点第 11 次被限流」断言，先清计数保证确定性）
      e2e-m3-h5-auth → 24/24（新增「两次 stub-login 各留一条 login_type=2」断言，
      清理时连登录日志一起清）
 2026-09-30 12:38:48 +08:00
lovife 8f80744d63 feat(task): 规则模板 FORM 真正可套用 + 已归档任务可删（客户确认的两项） 
一、规则模板的 FORM 部分（F-57/F-64）—— 此前只能「跳过并说明」，等于装饰
  · FormSchemaService.saveRawVersion：用已存在的 schemaJson 存为新版本。
    与手工保存的区别：内容不再校验/归一化（它当初就是按本服务规则存出来的，
    再走一遍解析→序列化只会丢未建模字段）；状态检查与版本管理保留 —— 版本化
    逻辑只有一份
  · RuleTemplateService 的 FORM 分支接上它（不再 skipped）
  · 顺带补上另一半：saveAsTemplate 此前不存表单（存模板不存、套模板用不上，
    两头各缺一半）—— 现在把源任务的当前表单一并带走；没存过 = null =
    套用时按「用系统默认，不覆盖」跳过

二、已归档任务可删（F-14 / §17.2 D-9）—— 此前「已发布即删不掉」，
   演示/测试任务只能改名挪开，库只增不减
  · DELETE /tasks/{id} 支持 status=3：收集中/已截止仍拒（归档是最后的后悔药），
    拒绝的话说清「先归档」
  · 子表级联物理删 14 张表（TaskCascadeMapper 集中放置，表清单来自
    information_schema 的事实核对）—— 大头是名册（证件号密文）、材料、审核记录
  · ★ 任务行本身**软删**：它必须占住 task_code —— maxSeqByCodePrefix 靠
    「含软删行的最大序号」保证编码永不复用（编码同时是文件目录名，重号会把
    两批任务的文件混进同一目录）。第一版做成了物理删，e2e-m1-task 的
    「编码递增」断言当场抓到重号 —— 这条回归现在被 e2e-m1-task-delete
    的「删除后新建不重号」断言守住
  · 物理文件尽力删（先取路径再删行，顺序反了文件就永远留在磁盘上；
    删不掉只记日志不阻断）；全程留痕（sys_operation_log 记 DELETE_TASK +
    行数/文件数）

验证：e2e-m7-taskconfig → 75/75（新增 FORM 完整链路 7 条断言）
      e2e-m1-task-delete（新增）→ 20/20（拒删/删净/占号软删/留痕/再删报错/草稿直删）
      e2e-m1-task → 71/71（旧口径断言更新为新口径）
 2026-09-30 12:38:47 +08:00
lovife b991e3d68e docs(contract): V2.6 六处口径修正 + 新增 §17 实现补充与偏差记录（客户确认） 
17 项决策里的 A 组：契约按已确认的口径改写，不动代码。

一、六处口径修正
  · §2.7 notifyBizType：5/6 对调修正为「5 催报 / 6 导出完成」——
    旧表若按写实现，催报去重会静默失效（F-30）
  · §2.7 auditAction：补全 7 个动作，撤回=7（3 是批量通过；F-7）；
    §11.4 约束补「状态 2 可撤（撤的是初审）」、留痕改 action=7
  · §3.6/§9.5 collect_file.source：改为建表口径「谁传的」
    （1 本人/2 班主任代传/3 管理员代传/4 整理器；F-38/39 —— 代传可追溯）
  · §9.5 重写为「上传前置检查（预检/秒传/压缩建议）」，direct:false，
    明写「客户端可跳过；服务端上传本身做全部校验」（F-3/71/72）；
    §9.6 process 改为「有原始件时的重新规范化」；§9.9 OCR 标注一期缓做
  · §12.1 validation/run 改同步并返回统计
    （checkedSubmissions/issuesFound/unresolvedLeft/elapsedMs；F-51 ——
    全契约本就没有查 jobId 的接口，返回一个查不到的作业号没有意义）

二、新增 §17 实现补充与偏差记录
  · 17.1：41 个「代码有、§4 清单没有」的接口按六类分组
    （材料通道/微信授权/签名URL下载/界面必需/契约链条断在第一步/运维动作）；
    清单声明由 check-api-parity.py --extra 生成 —— 手抄件会过期，命令不会
  · 17.2：12 条已确认偏离 D-1~D-12（notifyBizType、source、上传链路、process、
    validation 同步、撤回动作码、§14 路径前缀、biz_type 落库字符串、归档可删、
    租户域名、通知两级、OCR 缓做）—— 每条带契约原口径/实现口径/依据编号

验证：python scripts/verify-docs.py → 22 项全部通过（含表格列数一致性）；
      check-api-parity.py --quiet → 契约 121 / 已实现 120（§17 不影响 §4 计数）
 2026-09-30 12:38:47 +08:00
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 601714c476 test(scripts): 补测"没测过的四项"+ 清理工具扩展（F-99 / F-5） 
一、load-test.py：把 docs/09 §9.5 里四项"没测过"的变成"测过"
   · --base：另起一个 --fill.storage.provider=local 的实例（18080）量上传，
     不把测试文件灌进真实七牛桶；
   · --fixture-only：量名册导入本身（造 Excel 与导入接口分开计时 ——
     脚本自己的成本不能算到系统头上）；
   · --only export-big：造 N 份已通过的单（门禁绑定→草稿→上传→提交→
     初审（班主任）→终审（管理员）→前置检查→创建→轮询），再逐卷解开验证 ZIP；
   · --soak/--rps：长跑，每分钟采 RSS（从系统取，不是应用自报的堆）与
     PG 连接数，比较前 1/3 与后 1/3 的均值 —— 判据是趋势，不是"跑完没崩"；
   · 上传夹具换成真 JPEG（原来的"JPEG 头+随机字节"在服务端解码即失败，
     量到的根本不是压缩成本）。

   数字（docs/09 §9.5 有完整复现命令）：
     上传 20 并发 40/40，串行 321ms（2850KB→1329KB，47%），并发 p50 620ms；
     5000 行导入 20.2s（RSS 782MB）；150 人 194.6MB 导出打包 13.2s，
     分卷 4 卷每卷可单独解开；长跑 51 样本 15300 请求 0 失败，
     RSS 603.9→582.9MB 平稳，PG 连接定时任务高峰后正常回落。

二、F-99：这一轮压测工具自己撒了 8 次谎（都是"度量/夹具出问题时
   现象长得像产品缺陷"）：前置未断言（--only upload 单跑全报"没有草稿"）、
   假 JPEG、猜列名（part_no/file_name/file_path）、拿 HTTP 码当业务码、
   跨租户同名 admin（库里 50 多个，改从 token 的 sub 取 uid）、
   夹具接口不查返回码（PUT orgs 被拒→任务没发布→学生端整齐报 40008）、
   PowerShell -First 截管道把"被堵"变成"卡住"、清理只删库行不删文件。
   修法：bind_users/call_ok（夹具每个调用都断言业务码）、make_img 真图、
   列名按 DDL、cleanup 连磁盘文件一起删。

三、dev-clean-e2e.py（F-5 落地）：
   · --orphan-files：清"库里没有任何一行指向"的磁盘文件（判据来自
     collect_file.std_path/raw_path + collect_export_file.file_path）——
     实测 uploads 里 281 个文件/276MB 而库里只剩 16 行，已清 255 个/275.4MB；
   · --demo-tasks：清【演示·旧】任务（只匹配带「旧」的 ——
     【演示】审核台是当前演示态在用的，原来那句 LIKE 会把它一起删掉）；
   · e2e 租户的业务行按 information_schema 动态枚举（写死清单必然漏新表）；
   · --only-orphan-files：最安全的一档，只碰磁盘不碰任何库行。
   ⚠️ e2e 租户与"E2E 24数控1班"组织刻意未删：当前演示态正挂在其中一个班下面。

验证：python scripts/verify-all.py --quick → 通过 5 / 失败 0 / 跳过 0；
      docs/09 §9.1~§9.5 已同步（含机器规格：12 物理核 / 59.6GB）。
 2026-09-30 11:10:05 +08:00
lovife f86a999c52 perf(gate): 门禁成功上限 200→600 —— 250 人同时核验曾挡住 37 个（F-100） 
契约 §1.6 只规定了失败侧（同 openid 10 次/小时、同 IP 20 次/分钟），
成功侧 200/分钟是本项目自己加的（防"拿匹配接口批量取数据"），
而当初注释里写的本意是"一个 200 人的年级同时扫码也不该被挡"。

实测（python scripts/load-test.py --only gate --rows 250）：
250 个不同学生同时核验（全部正确）→ 213 成功、37 被挡，
提示「当前网络访问过于集中，请稍等 1 分钟再试」。
"全校在同一个出口 IP 集中扫码"（开学第一课集体填报）正是会发生的场景，
而这些人没有一个做错了什么 —— 与 F-92「教室被挡住」同一类，量级放大到一所学校。

上调为 600 的依据：一所学校一次集中填报的峰值。它仍然是限速（600 条/分钟），
而防枚举靠的是失败侧那两个计数器 —— 原样未动，防猜测强度没有降低。

验证：
  250 人 → 250/250（改前 213/37）
  500 人 → 500/500（500 并发 p50 1.4s / p95 2.5s，是排队不是限流）
  scripts/e2e-m3-gate.py → 29/29
文档同步：docs/01 E2（二次修正备案）、docs/09 §9.3 / §9.1。

教训：自己加的"防御性限额"也要过一遍真实场景的量级 ——
否则它与它要防的东西一样，都是事故。
 2026-09-30 11:10:05 +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 bfd7676974 feat(roster): 名册导入模板下载（§8.5）—— 表头固定第 1 行、必填列标红、9 条填表规则页 
服务端生成（POI），不放前端静态目录：表头列必须与导入解析器的已知列名表一致，
两处各写一份必然分叉，而分叉的表现是「照着模板填的表导不进来」。

三条要求都不是装饰：
- 表头在第 1 行：导入时表头是自动探测的（客户给的文件里实测有表头在第 6 行的），
  但我们自己发的模板必须规矩，否则「下载模板 → 填写 → 传回」这条最正常的路径反被折腾；
- 必填列标红：填错的绝大多数原因是不知道这列必填，而错误要到导入时才报（那时已经填了 500 行）；
- 规则说明页：9 条里最值钱的是「身份证号必须是真的」与「在校生/非在校生决定要交哪些材料」，
  不写清就会先填完再被逐条打回。

「要交哪些材料」那一页用当前任务的材料清单推导（不写死）；表头列本身固定 21 列 ——
跟着任务变的话，客户换个任务下载到的模板就不一样，而「我上次填的那份」会突然不适用。

验证：scripts/e2e-m7-taskconfig.py 69/69（模板表头与导入列定义逐项比对）。
 2026-09-30 09:03:13 +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 b94db65ec4 docs: 部署与运维手册 + 用户手册与客服话术 
docs/09：环境与发布、密钥清单、迁移与回滚、排障、首次接入 CI 的检查单、本地能验到哪一步、
压测记录（含未测项）。

docs/10：学生/班主任/管理员三份操作手册 + 高频问题标准回答 + 30 分钟培训提纲 +
上线首日检查单；文案与错误码逐条取自代码并回核（抓到两处与实现不符），
核对固化成了 check-manual.py 并进 CI。
 2026-09-30 09:02:57 +08:00
lovife 30c3714d35 test(scripts): 36 个 E2E 与 6 个机械校验工具（1548 条断言）+ 一键交付自检 
新增：check-api-parity（契约 121 接口 ↔ 控制器，自带「必须恰好 121」自检）、
check-entity-columns（基类要求的列 vs 迁移建表列，F-35 那个坑踩了四次之后上的工具）、
check-manual（手册引用的错误码与提示文案对得上代码）、check-test-profile（test profile 真起一次）、
e2e-prodguard、load-test（四场景、按端点分别统计）、verify-all（一条命令跑完交付自检）、
dev-seed-audit（界面验收用的演示数据），以及 M1~M9 各轮 E2E。

压测抓到一个真缺陷并修掉（F-92）：门禁 IP 限流原来计「所有请求」，于是一个班连同一个
WiFi 时 60 个不同学生同时核验只过了 20 个 → 改为只计失败 + 单独的成功上限，20/60 → 60/60。

度量工具的偏差会伪装成产品缺陷（F-60/F-77/F-97），所以每个脚本都断言「动作自己的结论字段」
（submitted / created / canExport），而不是 HTTP 200 + code 0。

验证：verify-all.py --quick 5/5；--with-e2e 见 docs/09 §8。
 2026-09-30 09:02:57 +08:00
lovife 6945f194b5 chore(ci): CI/CD 三阶段 6 job + test/prod 环境 + 启动前的配置自检 
.gitlab-ci.yml：契约与实体对账 / 后端编译 / 管理端类型检查与构建 / 学生端 H5 构建 /
接口断言（全套 E2E 打真库）/ 生产环境自检；密钥每次随机生成，顺带证明应用没有偷偷
依赖 dev 默认值。

ProdEnvCheck 是 EnvironmentPostProcessor，跑在任何 bean 之前，拦 6 类「配错了也能启动」；
判「没配」与「配了」要 try { getProperty } catch（F-86）——
getProperty 会解析占位符、失败就抛，只读 PropertySource 又读不到 env 的值。

删掉 Gi 模板残留的 GitHub Pages 工作流（远端是 GitLab、用 pnpm，且它发布的是没有 API 的静态页）。

验证：scripts/e2e-prodguard.py 9/9（三种误配形态都拒绝启动）。
 2026-09-30 09:02:57 +08:00
lovife 168c76ed0e feat(pc): 工作台换成真实数据看板 + 「待建」页不再说谎 
工作台底部原来是一张写着「M0 后端已完成，界面建设中」的进度卡，而项目已是 120/121 个
接口可用——首页上说一件不真的事比空着更糟。改成真实看板：选任务 → 进度四格 +
分班进度 + 审核情况 + 驳回原因分布；提交率与通过率分两列；平均审核时长按量级换单位。

名单管理/材料规则/表单设计三个菜单项对应的功能早就做好了（入口在「收集任务」每行的
链接里），却一直显示「这个页面还没做」。给 XtMenu 加 entryAt：有入口就指路 + 给跳转，
没有才说没做（角色与授权确实没做，属二期）。并删掉那句会静默过期的「已实现页面」清单。

验证：浏览器实测四个菜单与看板出数；pnpm typecheck 通过、eslint 0 错。
 2026-09-30 09:02:56 +08:00
lovife c8837ee602 feat(file): 上传预检/秒传/批量处理/预览 + 缩略图（P2-7）与 H5 独立 dev server（P2-9） 
缩略图：StorageService.thumbUrl(path, expire, maxLongSide)，七牛在**签名之前**拼
imageView2/2/w/h（拼在签名之后必 401），本地存储回退原图，让调用方不必判断当前是什么存储。
实测 1454KB → 36KB（2.4%）、1600×1200 → 400×300。

F-73：秒传原来排在份数检查之后 → 网络重传得到「你超了」而不是「你已经传过了」。

H5 dev server：vite 加 /api 代理 + .env.development 把 VITE_API_BASE 设空串，
改一行不用再 build:h5；三端行为不同（dev→代理 / 构建产物→location.origin / 小程序→写死）。

验证：新增 e2e-m9-thumb.py 12/12（打到真实七牛）、e2e-m8-orgfile 54/54；
H5 与小程序两端构建都验过。
 2026-09-30 09:02:56 +08:00
lovife 9216bd66d2 feat(schedule): 定时任务 8 项 + 用量快照/压缩重试/到期提醒（V17） 
PRD 附录 E。每个任务都是两段式：先以平台身份（tenantId=0）扫候选，再逐个租户摆上下文
干活——写数据必须在第二段，否则 tenant_id 被写成 0，通知进平台租户且不报错。

V17 新建 sys_tenant_usage_snapshot（唯一索引保证幂等；tenant_id 必须显式写）并给
collect_file 补 process_retry_count / process_error / last_retry_time + 只索引
「还没处理出规范件」的部分索引；压缩失败重试必须封顶，否则原图损坏的文件会被每 10
分钟重试一次而永远不成功。

跨租户的候选查询全部集中在 ScheduleMapper 一个文件、一律 @InterceptorIgnore + 只读；
Map 结果的别名一律 AS "camelCase"（F-83：PG 会把未加引号的别名折成小写，
表现是任务照跑、日志一行 warn、什么都没做）。

验证：e2e-m7-schedule 38/38（含快照幂等与一致性、重试累加与封顶、到期提醒窗口）。
 2026-09-30 09:02:55 +08:00
lovife efde4627eb feat(task): 规则模板、任务克隆与统计、组织导入、租户用量（V15） 
克隆**配置**（表单/材料清单/命名模板/审核配置/覆盖班级）、刻意不克隆业务数据——
名册克隆过去会让同一证件号在两个任务里各有一行。
统计补上 abnormalCount 与 avgAuditHours（这两个字段以前恒为 null，因为问题表与审核记录
还不存在）；规则模板可按 parts 只应用一部分、材料清单覆盖式合并。

顺带修 F-44：TaskService.create 对缺必填项抛 NPE（对外 50000「系统繁忙」），
改为集中校验并指出是哪个字段；F-45：历史整理器导入改走 TaskService.create，
避免两处各生成一次 task_code 迟早撞号。

验证：e2e-m7-taskconfig 69/69（含待办范围判据的回归防线）。
 2026-09-30 09:02:55 +08:00
lovife aa30fd2383 feat(open): §14 开放接口（V16）—— HMAC 签名对接认定机构 
密钥存 AES 密文（HMAC 要能还原，不能只存哈希）；签名 = HMAC-SHA256 + 5 分钟时间窗
+ nonce 防重放，先验签再占 nonce；数据接口一律不返回明文证件号，文件走 30 分钟签名 URL；
推送重试的 next_retry_at 落库（内存定时器重启后就没了），推送挂在 afterCommit 上。

契约漏掉的接入方管理（F-67）一并补上；规则模板两个接口修回契约路径（F-68）。

验证：e2e-m8-open 60/60。
 2026-09-30 09:02:54 +08:00
lovife 0d3aae75fa feat(cleanup): 历史数据整理器（§13.2，V13）—— 解压解析、体检报告、导入为正式任务 
从「人长出来的」历史路径里解析姓名/证件号/材料/班级 → 与名册比对 → 按模板重打包 →
体检报告（autoHandled / needManual 由服务端算，前端只展示，不自己减）→ 幂等导入。

F-48 的教训：中文人名与业务短词无法用「包含」区分——噪声词只做精确匹配，
候选名按「完整中文串 2~4 字 + 不含数字 + 不含班级词」判定。
F-49：参数校验必须排在幂等判断之前（否则不合法的请求会因「之前导过一次」变成成功）。

验证：e2e-m7-cleanup 54/54（含「坏包要明确失败」与「无名单时串档恒为 0」）。
 2026-09-30 09:02:54 +08:00
lovife 7090ee7d65 feat(ops): 操作日志留痕、字典管理、名册改删（V9 / V10） 
PRD FR-506/FR-1202 的 P0 项：V9 给 sys_operation_log 补 target_type/target_id/
before_val/after_val，OperationLogService 显式留痕并统一强制脱敏；
已接入的敏感动作：名册改证件号/改名/删名册项、任务发布/暂停/恢复/截止/归档。

F-32 的教训落地：动作名由调用方显式给，不从 (原状态, 新状态) 反推——
「发布」与「恢复」都是 →收集中，反推必然把 resume 记成 PUBLISH_TASK。

字典：内置字典写在代码里（DictCatalog），库里只存客户自定义项与内置项停用开关，
两表分开才能「一键恢复默认」；表单下拉与字典共用同一份口径（BuiltinFields 加访问器）。

验证：e2e-m5-logs 44/44、e2e-m1-dict 53/53。
 2026-09-30 09:02:53 +08:00
lovife 29c8e932ae feat(notify): 消息中心、催报、通知模板与微信回调 + 校验问题清单（V8 / V14） 
消息中心 + 订阅额度（原子扣减，先扣再发——订阅消息是一次性授权）+ 催报（定向/一键，
按 bizType 去重 24 小时）；通知降级链只做能真正走通的两级（订阅消息 → 站内信），
公众号模板与短信如实少做并写明理由：永远失败的通道会把真正的原因淹掉。

校验问题清单对齐语义：已有→只更新内容不碰 resolved / 新增→插入 / 消失→标已解决；
上传时把「系统改过文件名」记成 VAL-06 自动修复，让 byRule.autoFixed 有真实数据。

微信回调必须偏离两条全局约定（匿名入口、响应体是 {"errcode":0}）：只写推送状态不读
业务数据 + 必须验签 + 凭发出时记的 id 反查租户（查不到就报错，绝不猜一个租户去写）。

验证：e2e-m5-notify 48/48、e2e-m5-urge 40/40、e2e-m7-validation 70/70。
 2026-09-30 09:02:53 +08:00
lovife bb91515590 feat(join): B1 名单加入申请 —— 学生提交 + 管理端审批（V7 存 AES 密文） 
按契约「服务端转 HMAC、不落明文」设计会写不进名册：collect_roster.id_card_no 是
NOT NULL 的密文列，而申请表只有 hash 与 mask（三条替代路都被排除）。
V7 给 collect_join_request 补 id_card_cipher（与名册同一把密钥/算法），审批时原样搬进名册，
明文全程只在提交请求的内存里存在过。V7 之前的老申请明确提示重新提交，不静默建一条
永远过不了校验的名册行。

另修 F-20：自述班级不能借用姓名规范化（姓名要「张 三」→「张三」，班级名里的空格有意义）。

验证：scripts/e2e-m2-join.py 50/50。
 2026-09-30 09:02:52 +08:00
lovife ad86e2d521 feat(mp): 学生端「我的填报 / 撤回 / 进度」与班主任端看板、审核卡片流、代传材料 
学生端：待办数、状态、驳回原因、截止提醒、撤回；进度页的材料清单与进度条
分母用「这个人本次真的要交什么」（不适用的必传材料不进分母，否则永远填不满）。

班主任端：已交率与已通过分开呈现（已提交 ≠ 已通过）、右滑通过 / 左滑不绑驳回、
一键通过只带无问题项；代传走一步 multipart，三道闸门（只给自负责的班 / 只给草稿单 /
必须留痕且学生可见），V12 给 collect_file 补 proxy_by / proxy_reason。

验证：e2e-m3-mytask 42/42、e2e-m5-teacher-dashboard 24/24、e2e-m5-proxy 33/33；
H5 build:h5 产物含新增各页。
 2026-09-30 09:02:52 +08:00
lovife 45271a3c08 feat(audit): 审核台前端与审核统计 —— 批量通过逐条给原因，驳回走附录 C 原因码 
待办台四个计数 + 分级过滤 + 批量通过（被跳过的条目逐条列原因，只说「过了 3 个」
会让人反复点那个大按钮）；详情抽屉含材料/问题清单/改动明细/时间轴/通过·驳回·撤回。

前端不做范围过滤：权限 ≠ 范围，由服务端用 1 = 0 守死，前端再筛一次只会制造假象。
canApprove=false 时按钮直接禁用并显示原因，而不是等他点了再弹 40032。

审核端看材料走单独一条通道（不复用学生那条），材料 URL 用 ?thumb=true 取缩略图，
默认 false —— 详情页要看防伪纹。

验证：vue-tsc / eslint 0 错；浏览器实测四个菜单与批量通过弹窗。
 2026-09-30 09:02:51 +08:00
lovife 6cca97efe6 feat(export): 导出与交付（M6）—— 前置检查、目录树预览、分卷打包与 7 天过期清理 
客户最关心的那条链：precheck（不通过就没有 force 分支，铁律 10）→ 目录树预览
（与真正打包共用同一份构建代码，预览不会说谎）→ 异步分卷（每卷都是完整可解的 ZIP）
→ 产物落表按行判可下载（过期回「已被清理、请重新导出」）。

契约没有但界面必需的 GET /exports/precheck 一并补上（否则按钮要点一次才知道能不能导）。

顺带修 F-11：severity 口径统一为 INFO=1/WARN=2/ERROR=3（三处注释曾互相矛盾，
按直觉写会把「提示」当阻断，正常数据也导不出来）。

验证：scripts/e2e-m6-export.py 60/60、e2e-m6-export-split.py 33/33；
ZIP 的 UTF-8 标志位（general purpose bit 11）与 sha256 都有断言。
 2026-09-30 09:02:50 +08:00
lovife 3195dc4d7b chore(git): 忽略调试期临时产物 —— _*.txt / _thumb-* / _lt-roster-* / shots/ 
排查问题时生成的日志与量测样本不是交付物，之前每次 git status 都要靠人记着别 add。
按仓库既有做法（backend/data/、__pycache__/）把它们写进 .gitignore。
 2026-09-30 09:02:50 +08:00
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
lovife e6cd1049d4 chore(tenant): 租户域名改为默认关闭（客户决定先不做）—— 能力保留，关得干净 
客户：先不做多租户了。

处理：fill.tenant-domain.enabled 默认 true → **false**，代码全部保留。
理由：
  · 这个能力是隔离的：关掉后 TenantDomainResolver 一律返回 null，
    登录走老路径、AuthInterceptor 那段校验根本不触发 —— 不影响任何既有行为
  · 它已经验过（§一·二十五 16/16），删掉等于扔掉一份验过、将来要用的东西
  · 要真用上它，前提是有正式域名 + 泛域名解析 + 泛域名证书；这些没定之前
    开它只会让人以为"域名能区分单位了"，实际并不能。等定了改一个配置 + 重启即可。

「关得干净」是本轮的验收点：E2E 改成**两种模式都能跑**，按当前模式选断言。
现在跑的是关闭态这一节（6 条）：
  ✓ t1.localhost + 不填租户码 → 40012（域名不参与判断）
  ✓ 同一域名 + 填租户码 → 照样能登；主域名 + 租户码 → 照样能登
  ✓ 主域名 + 不填租户码 → 仍是 40012（跨单位重名的原行为）
  ✓ 关掉之后不引入任何新校验：带 t1 的 token 访问 t14 域名照常通过
脚本自己探测模式（免租户码登录成功=开、40012=关），所以开着时跑它会跑那 16 条，
不会因为模式不对而假绿。

将来开启：填 base → 配泛域名解析+证书 → XT_TENANT_DOMAIN_ENABLED=true → 重启 → 跑 E2E。
两条硬约束不变：微信授权回调域名只能配一个（回调统一落主域名再按 scene 跳回）、
小程序域名固定白名单（小程序端永远靠 scene）。

随之暂缓：§一·二十五 的三条待拍板（正式域名 / 手填租户码 / 小程序确认）现在都不用追了；
PRD 与 03-接口设计的补文档也等真要做时再写（现在写进去只会多一条"设计了但没启用"）。

全量 666 条断言、0 失败（租户域名 16 → 6，因为跑的是关闭态那节）。
 2026-09-29 21:42:00 +08:00
lovife 5b2f2c109d docs(handoff): 补上 §一·二十五（租户域名）—— 上一版幂等判断被正文引用误判，整节没写进去 
上一版脚本用 "§一·二十五" in text 当"已存在就跳过"的判断，而 §一·二十四 的结尾
正好有「见下一节（§一·二十五）」这句话 → 误判为已存在 → 整节没落进文档。

教训：幂等判断要认**标题**（## §一·二十五），不能认"整篇里有没有这个词"；
并且写完要**自查一次**标题能否找到（这次加了）。

另：本次提交还顺带记录了一条同类教训 —— 在 PowerShell 里用 git commit -m "带中文引号的消息"
会被 shell 拆成多个 pathspec（这次就炸了）。本项目一直用消息文件，就是为此。
 2026-09-29 21:37:54 +08:00
lovife d05cec0a02 feat(tenant): 租户域名 —— 用子域前缀判断"这是哪个单位的站点"（t1.xxx.com / t2.xxx.com） 
客户新提：不同的租户采用不同的地址前缀来获取租户ID。

一、它解决什么
   在此之前"这次是哪个单位"都要人填或扫：PC 登录要手填租户码（跨单位重名时报 40012
   「请填写租户码」，而用户根本不知道该填什么）、H5 与小程序靠扫码 scene。
   而域名本身就是"我是谁"最自然的答案 —— 在 t1.xxx.com 上打开页面时，
   系统不该再问"你是哪个单位的"。
   前缀用 t{tenantId}，与扫码 scene 的 t{tid} **同一套约定**（scene 早就是 t1-k17），
   不引入第二套编号。

二、★ 唯一必须守住的规则：Host 定位，token 授权
   未登录 → Host 决定"去哪个单位里找这个人"
   已登录 → 一律以 token 里的 tenantId 为准，且 Host 不一致就拒绝
   不校验后者的话：在 t1.xxx.com 上拿 t2 的 token 就能读 t2 的数据 ——
   而界面一切正常（前端本来就会带 token），是个安静且极难发现的越权。
   所以 AuthInterceptor 里那段判断比"登录免填租户码"重要得多，E2E 专门守着它。

三、落地
   FillProperties.TenantDomain(enabled/base/scheme)  默认关，siteOf(tid) 拼站点地址
   support/TenantDomainResolver                      解析不出来返回 null（不是错误）
   TenantMapper.selectActiveById                     停用/已删的租户不解析
   UserMapper.selectByTenantIdAndUsername            域名路径按 id 找用户
   AuthService.locateUser                            域名优先；手填租户码与域名矛盾 → 明确报错
   AuthInterceptor                                   Host 与 token 租户不一致 → 403
   MpH5AuthController.redirectToApp                  按 scene 的 t{tid} 跳回该单位站点
   application-dev.yml                               enabled/base=localhost/scheme=http

   null 的语义很重要：解析不出来 ≠ 出错，而是"这是统一入口/单域名部署"，回退老路径。
   所以单域名部署仍然完全合法（enabled=false 即可）。

四、两条来自微信的硬约束（决定架构，不是可选）
   1. 公众号网页授权的「授权回调页面域名」**只能配一个** → 每租户一个子域时，
      回调统一落在主域名，再按 scene 里的 t{tid} 302 回该单位站点。
      正好复用既有的 state（scene 随 state 走）+ token 放 fragment 的机制。
   2. 小程序的 request 合法域名是**固定白名单**，配不了 *.xxx.com →
      小程序端用不了域名，继续靠 scene 里的 t{tid}。这点客户需要知道。

五、本地开发的坑（已处理）
   开发期 base 是 localhost，真按它回跳会把手机上的学生从穿透域名扔到 t1.localhost ——
   打不开，且是浏览器级失败，看不出是我们跳错了。所以回跳加了本机地址判断
   （localhost/127.0.0.1/192.168.*/10.*/*.local），本机 base 一律回退到 h5-base-url。

六、E2E：scripts/e2e-m1-tenant-domain.py → 16/16
   [1] t1.localhost + 不填租户码 → 登录成功（对照：不带域名 → 40012）；
       带端口/大小写/多一层子域都能解析
   [2] 域名与手填租户码矛盾 → 明确报错；一致则正常
   [3] ★ 拿 t1 的 token 访问 t14 域名 → 403，提示可理解
   [4] 边界：x1.localhost / t999999.localhost / example.com → 都回退老路径
   用 http.client 伪造 Host 头（urllib 会按 URL 自己算 Host，覆盖不掉）。

七、全量 676 条断言、0 失败（新增 16）；verify-docs 19 项通过

八、⏳ 需要拍板的三件事（已写进交接摘要 §一·二十五）
   1. 正式域名（base）+ 泛域名解析 + 泛域名证书 *.xxx.com（备案一个主域名即可覆盖子域）
   2. 要不要保留"手填租户码"（我保留了：统一入口、老客户端、运维排查都需要）
   3. 小程序端确认继续靠 scene
   另：这条新需求应补进 PRD 与 03-接口设计（目前只落在代码与本摘要里）——下一轮补。
 2026-09-29 21:37:11 +08:00
lovife f964cf45fe feat(scope): 报考范围聚合与一致性体检（M2-04/05）—— 把"人眼核对"换成"接口约束" 
一、先纠正上一节里我自己写错的待办
   §一·二十三 的下一步写着「sys_eval_plan 那几张表还没落地，需要先定计划从哪来」——
   这是错的。PRD V2.0（L508）已明确：那三张计划表**作废删除**，因为机构根本不下发
   计划清单，真实名单里报考三项老师已经填好（28/28）。所以范围 = 那三列的去重组合。
   教训与 §七 同类：引用/怀疑已有设计之前先查文档，不凭记忆。

二、落地
   后端 PlanScopeMapper / PlanScopeService / PlanScopeVO / PlanScopeSaveReq / Controller
   前端 apis/xt/plan-scope.ts + 名册抽屉里的「报考范围」区块
   实体补上 plan_scope_json / plan_scope_confirmed（V1 建过列，只是没映射）

三、这一步真正的价值：确认时要求**恰好覆盖全员**
   rosterIds 并集 ≠ 名册全员 → 40024 并点名。漏一个人，导出包就缺人，
   而打开导出包时**不会有人数出 27 个**。所以"排除某人"的正确做法是把他所在的分组
   标成 EXCLUDED，而不是从 rosterIds 里删掉 —— 删掉会校验失败，提示正好告诉他
   "请明确排除，不要悄悄丢掉"。
   体检也必须说得出**是哪几个人**（每条 issue 带 rosterIds，服务端还把名字写进 detail）。

四、五类体检实现四类，一类有理由地缓做
   ✅ SCOPE_UNFILLED（只判职业：「无」是合法值）
   ✅ SCOPE_LEVEL_MIXED（**只把少数派算异常**，多数派是"正常那一批"）
   ✅ SCOPE_TYPEO_MISMATCH
   ✅ SCOPE_OUT_OF_TASK（只在任务显式声明 jobName 时才判；**等级不比** ——
      名单写「四级/中级工」而任务写「四级」，精确比必然误报）
   ⛔ SCOPE_FREE_TEXT：要国标职业字典，而 sys_occupation_ref 一行数据都没有（FR-312 是 P2）。
      硬编一份列表会在机构用别的写法时全部误报，而误报会让人整体忽略体检 —— 比不做更糟。

   ⚠️ level 的口径：契约只给了值、没给语义，且 UNFILLED=1 与 FREE_TEXT=1 严重性明显不同。
   所以代码里只把 level 当排序/展示用，判 passed 时一视同仁 —— ignoredIssueCodes 的存在
   正说明"要不要放过"由人决定，不该按级别猜规则。

五、FR-311（追加名单告警，P0）一并做了
   范围确认后导入，出现范围外的报考组合 → 导入体检里出 SCOPE_OUT_OF_TASK 警告。
   范围内不告警 —— 两个方向都验了（不然就是"全报"或"全不报"）。

六、E2E：scripts/e2e-m2-scope.py → 38/38
   夹具刻意做出：6×车工/四级 + 1×车工/三级（少数派）+ 1×铣工（任务声明车工）+ 1×漏填。
   浏览器实测：分组表、4 条体检（级别 + 说明 + 涉及谁 + 忽略勾选）、
   确认按钮在未处理时禁用、勾选忽略后解禁、确认后显示「已于 … 确认」且体检变通过。

七、顺带抓到的两个（都在我的测试代码里）
   1. 夹具身份证号出生日期写成 0000 → 9 行全被阻断，而导入接口仍回 code=0（只回体检报告）
      → 看着像"导进去了"。所以 E2E 除了判 code 还必须判 created==9，已补。
   2. call() 回元组、upload_roster() 回字典，我在新脚本里弄混了。同类：新写的代码最容易在细节上错。

八、回归
   全量 660 条断言、0 失败（新增 38）；vue-tsc 0 错、eslint 0 错；verify-docs 19 项通过

九、客户端新提了一个架构要求（见 §一·二十五）：租户按域名前缀区分（t1.xxx.com / t2.xxx.com）
 2026-09-29 21:28:49 +08:00
lovife e85a25a97f feat(roster): 名册导入前端 —— 任务发布现在真的能在界面上走通了 
第 2 步。在此之前「配置 → 任务就绪」缺了**名册**那一环：班级能配、材料能配、
表单能配，但名册只能靠 SQL 造，于是任务在界面上**根本发布不了**（40016 名册非空）。

一、新增（frontend-pc/）
   src/apis/xt/roster.ts               导入（multipart）+ 分页 + 类型 + 状态字典
   src/views/task/TaskRosterDrawer.vue 「名单管理」抽屉：导入 → 体检报告 → 名册列表
   views/task/index.vue                 加「名单管理」入口；已截止/已归档只读仍可查看
   config/xt-routes.ts                  顶层「名单管理」菜单说明改为指向任务行

二、★ 验证了"发布真的通"（e2e-m2-roster.py 第 8 节）
   配覆盖班级 → 配必传材料 → **发布成功** → 状态变「收集中」→ stat 仍带分母。
   force=true 只跳过 P1 提醒，那 5 项阻断级校验 force 也绕不过 —— 所以是真链路。

三、界面上五个刻意的设计
   1. 先体检再导入（两步）：实测表头在第 1 行或第 6 行，一步导入只会看到
      "成功 0 条"，然后以为文件坏了
   2. 明说「前面那 5 行是标题与说明，已跳过，这不是导错了」—— 不解释的话
      用户会去改自己那份本来正确的表格
   3. 行号 + 列字母 + 原值 + 原因四样一起给，用户拿着就能回去改 Excel
   4. dryRun 默认 true（服务端也默认 true）：不显式要求就不写库
   5. 阻断行与警告行分两张表：混在一起会让人以为整批都没进
   原因后面跟**机器码**而不是中文标签（第一版给中文，和上面那句原因重复了一遍）

四、顺带修掉一处「界面在说谎」
   名册导进来了，任务列表却还显示「待导入名册」—— TaskStatVO 恒为 null 是 M1 的
   既有缺口（注释写着"名册为空时返回 null，由界面显示待导入名册"）。现在名册有了：
   · TaskService.fillStats()：一次算一页（两条批量查询，不逐任务查）
   · **名册为空时仍返回 null**，口径没有放宽 —— 显示 0% 看起来像"没人填"，
     而真相是"还没有分母"
   · abnormalCount / avgAuditHours 仍为 null（要 M4 的校验表 / M5 的审核记录）
   · e2e-m1-task 那条断言改成措辞更准的"名册为空时 stat 为 null"（意图不变），
     并在 e2e-m2-roster 补 4 条"名册有值后 stat 该有值"
   这条也是第 2 步**自己制造**的问题：能导名册之后，"待导入名册"从诚实变成说谎。

五、为什么顶层「名单管理」菜单还是"待建"
   名册是**按任务**的，独立页得先选任务（多一步且容易选错）；它和「配置班级」
   「材料规则」「表单设计」是同一层的配置。报考范围确认（M2-04/05）会接着做进
   同一个抽屉，那时也不需要新页面。所以改的是那句已过期的"对应里程碑 M2"。

六、浏览器验证（真链路，只绕开"手指点选"）
   文件框没法自动化，但可以把夹具放到 frontend-pc/public/ 再喂进去：
     fetch 字节 → new File → DataTransfer → input.files → dispatch change
   实测：3 人被正确导入、脱敏证件号、报考三项、扩展字段、状态列、搜索全对。
   夹具用完即删。

七、回归
   全量 622 条断言、0 失败（名册 E2E 62 → 67）
   frontend-pc: vue-tsc 0 错、eslint 目标文件 0 错
   verify-docs.py 19 项全通过

八、两个流程教训（已写进交接摘要）
   · `Test-Path jar` 不能当作"打包成功"：这次 mvn 失败而旧 jar 还在，
     于是检查得到"打包 ✓"，测试对着旧 jar 跑，四条新断言全红。
     必须看退出码 / BUILD SUCCESS。
   · `call()` 返回的是 (status, body) 元组不是字典 —— 我新写的那节忘了解包。
     与第 1 步"已存在判断写反"同类：新写的代码最容易在细节上错。

九、下一步（第 3 步）
   报考范围聚合与一致性体检（M2-04/05）—— 产品的核心增量。
   先确认：sys_eval_plan 那几张"评价计划"表还没落地（FR-311 未做），
   需要先定"计划从哪来"。
 2026-09-29 17:17:55 +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