danyang-match/docs/Phase-15-V11-Recovery-Completion-Report-2026-09-17.md

Phase 15（活动报名、审核与签到）V1.1 增量复验完成报告

• 日期：2026-09-17
• 模式：KEEP-VERIFY / EXTEND
• 范围：activity registration、checkin 服务与 U29～U32 页面
• 基线：Phase 14 收尾 755a570（全量回归 450 tests）
• 结论：关闭。三项计划事项全部落地，Gate 两项均达成

---

一、计划项达成情况

计划项	结论	证据
回归报名、审核、取消、签到码、重复签到和名额并发	✅	ActivityPhase15Test 21 例，覆盖取消/拒绝后重报名、重复报名、审核并发、重复扫码幂等、过期码、跨活动复用
增加非 matchmaking 活动和 capacity group 场景测试	✅	容量分组真正参与扣减（此前只落库回读）；婚恋课堂类不设实名/本地资格门槛
服务站操作员只能操作指定活动或站点任务	✅	新增 V040 activity_staff_assignments + 签到/审核数据范围校验（INV-020）

Gate

Gate	结论
重复请求和并发报名不超额	✅ 报名/审核/取消/签到全部改为单条条件 SQL，靠数据库保证原子性
签到不可跨活动复用	✅ 签到码作用域由 token 内 activityId 决定；且工作人员必须被显式指派到该活动

---

二、修复缺陷清单（16 处）

A. 签到（8 处，含 1 处必崩）

• D1 CRITICAL — 每一个签到码一生成即作废：generateCheckinToken 把 token 写入 Redis 值 "used"，而 scanCheckin 见到 "used" 立即拒绝 → 扫码签到 100% 失败。改为签发时写 issued，消费标记只在扫码成功后写入。
• D2 CRITICAL — 重复签到竞态：原为「读 → 判断 → updateById 全量覆盖」，并发扫码会重复写 checkin_at 与审计。改为 checkinIfNotCheckedIn 条件更新；重复扫码幂等返回 alreadyCheckedIn=true，不重复记审计。
• D3 HIGH — 签到无数据范围（计划项③）：任意持 activity.checkin 权限者可签到任意活动任意用户。新增 assertCheckinScope：被指派过活动的工作人员只能操作被指派的活动；无任何指派记录者为平台级人员。
• D4 HIGH — 手工签到无校验：manualCheckin 不校验活动是否存在/已取消（原实现只有 generate 校验时间窗）。补 requireCheckableActivity。
• D5 MEDIUM — 签到统计 NPE 与语义错：活动不存在时 activity.getTotalLimit() NPE；remainingCount 用「总名额 − 已签到」计算。改为抛明确错误，并输出语义正确的 notCheckedInCount。
• D6 MEDIUM — 非法 token 返回 500：Long.parseLong 未捕获 NumberFormatException。改为 IllegalArgumentException（400）。
• D7 MEDIUM — 签名比较非恒定时间：改用 MessageDigest.isEqual，避免侧信道逐字节爆破。
• D8 LOW — 未使用变量：getCheckinStats 中 regMapper 冗余赋值，已删。

B. 报名 / 审核 / 取消（5 处，含 1 处必崩）

• D9 CRITICAL — 取消后永远无法再报名：生产 UNIQUE(activity_id, user_id) 一直存在，而「取消/拒绝后重新报名」走的是 INSERT → 撞唯一键 500，用户取消一次即永久失去该活动资格。测试库此前缺该 UNIQUE，因此零覆盖。改为复用原记录 + 原子条件 UPDATE（reuseIfCapacityAvailable），并同样带容量条件。
• D10 HIGH — 后台审核列表看不到待审记录：getRegistrations 只查 status='approved' → 审核页面无 pending 可点，审核功能实际不可用。改为 findByActivity（全状态）。
• D11 MEDIUM — 报名窗口形同虚设：registration_start_at / registration_end_at 完全不校验，活动一发布就永远可报。新增 assertWithinRegistrationWindow。
• D12 MEDIUM — 取消无审计：取消是唯一没有审计日志的写操作。补 CANCEL_REGISTRATION 审计。
• D13 MEDIUM — 审核/取消非原子：rejectRegistration 为「读 pending → 全量 updateById」，两人同时操作会互相覆盖；cancelRegistration 亦然。改为 rejectIfPending / cancelIfActive 条件更新。

C. 容量分组（计划项②，1 处）

• D14 MEDIUM — 分组容量完全不生效：activity_capacity_groups 只落库回读，approved_count 永远是 0。新增 incrementIfAvailable / decrementIfPositive，在报名、审核通过、取消时真实扣减/回退（未配置分组的活动不受影响）。

D. 前端契约（2 处）

• F1 — 工作人员无处消费签到码：admin-web 完全没有签到页面，D1 修复后仍无法闭环。新增 ActivityCheckinView.vue（扫码/粘贴签到码 + 手工签到 + 统计）+ /activities/checkin 路由与导航。
• F2 — 小程序无法取消报名：后端 DELETE /activities/{id}/register 已存在，但 activityService.js 无封装、「我的活动」页无入口。补 cancelRegistration 封装。

---

三、测试保真度修复（3 处）

• T1 约束漂移盲区：测试库 activity_registrations 缺 UNIQUE(activity_id, user_id)、chk_reg_status、chk_checkin_status —— 这正是 D9 必崩缺陷长期不可见的根因。已补齐。
• T2 占位假绿：CheckinServiceTest 有 3 条 assertTrue(true); // 占位测试，恰好覆盖「重复签到」「Token 过期」「二维码不含敏感明文」三条核心不变量。已改为解析真实源码与真实生产 DDL 的静态守卫（5 例）。
• T3 表集合：activity_registrations 此前不在 EntityMigrationParityTest 的必选集合；新增 activity_staff_assignments。二者均移入 REQUIRED_IN_TEST_SCHEMA。

另外同步了 MigrationValidationTest 的迁移基线（39 → 40）：该守卫会拒绝任何超出基线的新迁移文件，是设计内的收敛机制。

附带教训：新实体 ActivityStaffAssignment 最初继承了 BaseEntity，而 V040 表是 (activity_id, operator_id) 复合主键（无 id / updated_at / deleted_at）。MyBatis-Plus 会对非 null 字段一律写入列清单 → 生产每次 insert 都撞 column does not exist。已改为不继承 BaseEntity，由 EntityMigrationParityTest 当场拦下。

---

四、证据

定向测试：43 tests / 0 failures（ActivityPhase15Test 21 + CheckinServiceTest 5 + EntityMigrationParityTest 6 + ActivityConstraintGuardTest 11）

负向验证（注入真实缺陷 → 守卫必须变红，随后全部还原）：

注入	变红的用例
① 生成签到码时写回 TOKEN_STATE_USED（还原 D1）	generatedTokenCanBeScanned / duplicateScanIsIdempotent / checkinTokenDoesNotCrossActivities + 守卫 generateMustNotMarkTokenAsUsed
② 报名退回 INSERT 不复用记录（还原 D9）	canReRegisterAfterCancel / canReRegisterAfterReject（DuplicateKeyException）
③ 容量分组不参与扣减（还原 D14）	capacityGroupIsEnforced / cancelReleasesCapacityGroup

共 8 条精准变红，归因与注入一一对应；还原后确认工作区无 NEGATIVE-VERIFICATION 残留。

全量回归：Tests run: 474, Failures: 0, Errors: 0, Skipped: 3 / BUILD SUCCESS（基线 450 → 474，净 +24）

前端：admin-web vue-tsc --noEmit 0 error；vite build 通过（1737 modules transformed，新增 ActivityCheckinView 已打包）

---

五、变更清单

新增文件

• backend/src/main/resources/db/migration/V040__add_activity_staff_assignments.sql
• backend/src/main/java/.../activity/entity/ActivityStaffAssignment.java
• backend/src/main/java/.../activity/mapper/ActivityStaffAssignmentMapper.java
• backend/src/test/java/.../activity/ActivityPhase15Test.java
• admin-web/src/modules/activity/ActivityCheckinView.vue

修改文件

• CheckinService.java（重写签到流程）
• ActivityService.java（重报名复用、分组扣减、报名窗口、审核/取消原子化、数据范围）
• ActivityRegistrationMapper.java（+findByActivity / reuseIfCapacityAvailable / checkinIfNotCheckedIn / cancelIfActive / rejectIfPending）
• ActivityCapacityGroupMapper.java（+findByActivityId / incrementIfAvailable / decrementIfPositive）
• schema-h2.sql（报名表 UNIQUE + 两个 CHECK、新增指派表）
• CheckinServiceTest.java（3 条假绿 → 5 条真实守卫）
• ActivityConstraintGuardTest.java（+2 条约束漂移守卫）
• EntityMigrationParityTest.java、MigrationValidationTest.java（基线）
• admin-web/src/router/index.ts、MainLayout.vue（签到路由与导航）
• miniapp/services/activityService.js（+cancelRegistration）

---

六、遗留（供后续阶段）

1. my-activities（U30）仍是占位骨架：只有 onLoad/onShow 空实现，用户无法查看报名状态或自助取消（service 层已备好 cancelRegistration）。
2. 签到码以"复制文本"形式下发：小程序 U31 提供的是复制按钮而非二维码；后台签到台为手动粘贴。若需扫码枪/摄像头扫码，需另加扫码输入方式。
3. 容量分组归属规则较粗：当前按 group_code 与性别匹配，未匹配到分组时不施加约束；ruleDefinition（JSON）尚未参与判定。
4. activity.checkin 与指派的联动：目前"有指派记录者受限、无指派记录者不受限"，若后续要求所有签到人员必须显式指派，需改为强制校验。

---

Phase 15 已关闭。Phase 16（活动互选与双方开启沟通确认）未自动进入，等待用户确认。