feat(mp): M3-01 门禁核验（名单是闸门）
M3 的第一块：学生必须先过名单核验，才能开始填报任何东西。
交付：
· POST /api/v1/mp/roster/match（§5.4）—— 姓名+证件号与名册匹配，命中才放行并绑定
· common/util/IdCardUtil —— 身份证校验位（三态裁决）
· support/ClientIp —— 取真实调用方 IP（限流用，X-Forwarded-For 第一段）
· module/roster/entity/CollectRoster —— 名册实体（M2 会继续用）
四条守住的规则：
1) 失败提示必须统一（40007），不区分"姓名错"还是"号码错"。
分开提示等于交付了一个身份证号枚举器：用任意姓名+目标号码试，
若提示"姓名不对"就说明号码在名单里，一个个试就能把全校号码试出来。
这不是体验取舍，是安全底线。E2E 专门断言两种失败的 msg 字符串完全一致。
2) 绑定并发安全：UPDATE ... WHERE bind_user_id IS NULL + 看影响行数。
不要改成"先 SELECT 判空再 UPDATE"——中间有窗口，两人会同时通过检查，
后绑的人静默覆盖先绑的人，而先绑的学生之后再也进不去。
E2E 用两个线程同时冲同一行，断言"恰好一个成功、一个 40072"（实测 [0, 40072]）。
3) 证件号明文只在 match() 里出现一次，失败日志只记 HMAC 与 uid（日志被翻出来
同样是泄露）；响应里永远只有 idCardMask，E2E 断言整个响应 JSON 不含明文。
4) 已绑定自己的人重复核验是幂等的 —— 学生刷新页面不该看到"该信息已被登记"。
IdCardUtil 的价值在三态而不在对错：
真实数据集实测：名册 28 人校验位全通过（可信基准）；某两个学生的文件名证件号
校验位失败（确定是号码错，可自动改正）；另一学生的两个号码都通过（是两个真人，
串档实锤，必须人工介入）。后两种看起来都是"号码对不上"，处理策略却完全相反——
一个能放心自动修，另一个自动修就是把两个真人的材料合并。区分它们的唯一办法
就是校验位。所以对外暴露 Verdict{VALID,CHECKSUM_FAILED,MALFORMED} 而非 boolean。
1900 年下界是业务判断，不是国标要求：网上流传的"示例有效身份证号"里有一批
出生年份在 1800 年代（如常被引用的 440524188001010014 → 1880 年），它们校验位
合法但不可能是认定考生。只算校验位会把它们判成 VALID。这个坑写 E2E 时真踩到了。
E2E 怎么拿 token：门禁要求已登录的学生，而登录（/mp/login）需要真实的 wx.login
code，脚本拿不到。所以用 dev 配置里的 JWT 密钥自己签一个 MP token（HS512，
claims 与 JwtService.issue 同构）—— 与 e2e-m0 用 dev RSA 公钥加密登录密码是同一类
做法：用开发配置里的凭据手搓测试夹具，不是绕过认证逻辑。prod 密钥不在仓库里，
这个手法自然失效。顺带：读配置要读两个文件，issuer 在主 application.yml 里，
只读 dev 会漏掉它，而症状是 401，完全指不到"配置没读到"。
回归抓到我一条脆断言：
e2e-m1-qrcode.py 的"token TTL 是 7000 秒"在连续第二次运行时失败（TTL=4633，
正好是两次运行的时间差）——它假设 token 是刚取的，实际沿用了缓存。
已改成"先清缓存强制重取，再断言 TTL∈[6900,7000]"，连跑两次都稳定通过。
教训与前面几次同类：断言要确定性地反映被测行为，而不是碰巧在某种顺序下通过。
已知缺口（写进交接摘要）：
· /mp/login 未做：它需要真实 wx.login code，脚本测不了，只能在小程序里测，
下一轮连同小程序核验页一起做。
· 形近字候选（FR-504c）未实现，needConfirmName 恒为 false。
· 名册导入未做（M2），E2E 用 SQL 直接造名册行。
· 小程序端还没有核验页（落地页的「开始填报」目前是明确的"开发中"提示）。
验收：e2e-m3-gate.py 29/29（含并发绑定与限流）；
九条 E2E 合计 418 项断言全通过。
This commit is contained in:
@@ -452,6 +452,54 @@ t{tenantId}-k{taskId}-o{orgId} 带班级
|
||||
|
||||
---
|
||||
|
||||
## 一·十一、M3-01 门禁核验（2026-09-29 上午，未提交）
|
||||
|
||||
> 范围：`POST /api/v1/mp/roster/match`（《03-接口设计》§5.4）+
|
||||
> `common/util/IdCardUtil`（校验位三态裁决）。**M3 的第一块。**
|
||||
|
||||
**验收**：`python scripts/e2e-m3-gate.py` → **29/29**；
|
||||
九条 E2E 合计 **418 项断言**全通过。
|
||||
|
||||
### 四条守住的规则
|
||||
|
||||
| # | 规则 | 为什么 |
|
||||
|:--:|---|---|
|
||||
| 1 | **失败提示必须统一（`40007`），不区分"姓名错"还是"号码错"** | 分开提示等于交付了一个**身份证号枚举器**：用任意姓名 + 目标号码试，若提示"姓名不对"就说明号码在名单里，一个一个试就能把全校身份证号试出来。这条不是体验取舍，是安全底线。E2E 专门断言"两种失败的 `msg` 字符串完全一致" |
|
||||
| 2 | **绑定并发安全**：`UPDATE ... WHERE bind_user_id IS NULL` + 看影响行数 | 不要改成"先 SELECT 判空再 UPDATE"：中间有窗口，两人会同时通过检查，**后绑的人静默覆盖先绑的人**，而先绑的学生之后再也进不去。E2E 用两个线程同时冲同一行，断言"恰好一个成功、一个 40072" |
|
||||
| 3 | **证件号明文只在 `match()` 里出现一次**，失败日志**只记 HMAC 与 uid** | 日志被翻出来同样是泄露。响应里永远只有 `idCardMask`，E2E 断言"整个响应 JSON 里不含明文" |
|
||||
| 4 | **已绑定自己的人重复核验是幂等的** | 学生刷新页面、返回再进来，不该看到"该信息已被登记"这种吓人的提示 |
|
||||
|
||||
### `IdCardUtil` 的价值在**三态**，不在对错
|
||||
|
||||
真实数据集实测过：名册 28 人校验位全通过（可信基准）；某两个学生的**文件名**证件号校验位失败（确定是号码错，**可自动改正**）；另一个学生的两个号码**都通过**（是两个真人 → **串档实锤，必须人工介入**）。
|
||||
|
||||
后两种**看起来都是"号码对不上"，处理策略完全相反** —— 一个能放心自动修，另一个自动修就是把两个真人的材料合并。区分它们的唯一办法就是校验位。所以对外暴露 `Verdict{VALID, CHECKSUM_FAILED, MALFORMED}` 而不是 `boolean`。
|
||||
|
||||
⚠️ **1900 年下界是业务判断，不是国标要求**：网上流传的"示例有效身份证号"里有一批出生年份在 1800 年代（如常被引用的 `440524188001010014` → 1880 年），**它们校验位合法**，但不可能是认定考生。只算校验位会把它们判成 VALID。这个坑在写 E2E 时真踩到了（两个线程都拿到 40007，因为测试数据用了那个号）。
|
||||
|
||||
### E2E 怎么拿 token（值得记下的手法）
|
||||
|
||||
门禁要求"已登录的学生"，而登录（`/mp/login`）需要真实的 `wx.login` code —— 脚本拿不到。所以 `e2e-m3-gate.py` **用 dev 配置里的 JWT 密钥自己签一个 MP token**（HS512，claims 与 `JwtService.issue` 同构）。这与 e2e-m0 用 dev RSA 公钥加密登录密码是同一类做法：用开发配置里的凭据手搓测试夹具，**不是绕过认证逻辑**。prod 的密钥不在仓库里，这个手法自然失效。
|
||||
|
||||
顺带：读配置要读**两个**文件 —— `jwt.secret`/`hmac-key` 在 `application-dev.yml`，而 `issuer` 在主 `application.yml`。只读一个会漏掉 issuer，而症状是 401，完全指不到"配置没读到"。
|
||||
|
||||
### 回归抓到我一条脆断言
|
||||
|
||||
`e2e-m1-qrcode.py` 里"token TTL 是 7000 秒"这条，在连续第二次运行时失败了（实测 TTL=4633 ≈ 两次运行的时间差）—— 它假设 token 是刚取的，而实际上沿用了缓存。**已改成"先清 token 缓存强制重取，再断言 TTL∈[6900,7000]"**，现在连跑两次都稳定通过。
|
||||
|
||||
> 教训与前面几次同类：断言要**确定性地**反映被测行为，而不是碰巧在某种执行顺序下通过。
|
||||
|
||||
### 已知缺口
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| **`/mp/login` 未做** | 它需要真实的 `wx.login` code，**脚本测不了**，只能在小程序里测。下一轮连同小程序核验页一起做 |
|
||||
| 形近字候选（FR-504c）未实现 | 姓名不一致时统一返回 40007。`needConfirmName` 恒为 false |
|
||||
| 名册导入未做（M2） | E2E 用 SQL 直接造名册行 |
|
||||
| 小程序端还没有核验页 | 落地页点「开始填报」目前是明确的"开发中"提示 |
|
||||
|
||||
---
|
||||
|
||||
**关键实现决策（不要在后继开发中改回去）**
|
||||
|
||||
| 决策 | 理由 |
|
||||
|
||||
Reference in New Issue
Block a user