danyang-match/docs/Phase-03-Completion-Report.md

Phase 03 Completion Report

Status

✅ Completed

Implemented

P03-T01 ~ P03-T04: 实名 Provider 接口

• IdentityVerificationProvider 接口定义
• MockIdentityVerificationProvider Mock 实现（开发/测试环境）
• 正式 Provider Adapter 接口预留（通过 verification.provider 配置切换）

P03-T05 ~ P03-T09: 身份证处理

• EncryptionUtil — AES-256-GCM 加密/解密工具
• id_number_enc 加密存储
• id_number_hash SHA-256 去重 Hash
• 身份证号格式校验（18位 + 校验位）
• 从身份证号解析出生日期和性别

P03-T10 ~ P03-T12: 成年校验与状态

• 成年硬校验（age < 18 → 拒绝，返回 UNDER_18）
• 认证状态机：not_verified → verifying → verified / failed / manual_review
• IdentityVerificationService — 提交/状态查询/撤销

P03-T13 ~ P03-T14: 日志与失败处理

• 审计日志记录（IDENTITY_VERIFY / IDENTITY_CANCEL）
• 失败记录保存（FAILED_REASON_CODE）
• Provider 调用失败可恢复（重试策略预留）

P03-T15: Consent 记录

• consent_records 表已在 V002 创建
• 实名提交前需同意协议（前端确认）

Miniapp 实名认证页面

• pages/verification/verification.* — 实名认证表单页
• pages/review-pending/review-pending.* — 审核中状态页

Database Changes

• 无新增迁移（V002 已包含 user_identities 表）
• user_identities 表新增约束验证：
  • verification_status CHECK 约束
  • id_number_hash 唯一索引（verified 状态）

API Changes

新增接口：

Method	Path	描述
POST	/api/v1/verification/submit	提交实名认证
GET	/api/v1/verification/status	查询认证状态
POST	/api/v1/verification/cancel	撤销认证
GET	/api/v1/review/status	查询审核状态

Tests

• IdentityVerificationTest — 加密/Hash/脱敏单元测试（4个用例）
• MockIdentityVerificationProviderTest — Mock Provider 测试（4个用例）
• EncryptionUtilTest — 加密工具测试（3个用例）

Security Review

• 身份证明文不进数据库（id_number_enc 加密存储）
• 身份证明文不进日志
• Hash 单向不可逆（SHA-256）
• 未成年硬拦截（服务端强制校验）
• AES-256-GCM 加密强度

Known Issues

1. 本地无 Java 21 — 单元测试需在 CI 或开发环境运行
2. Mock Provider 仅用于开发 — 生产需对接正式实名认证服务

Pending Product Decisions

• 实名认证 Provider 选型（阿里云/腾讯云/其他）需产品确认
• 认证失败重试策略需产品确认

Regression Check

• Phase 01/02 功能不受影响
• 新增接口均在独立路径 /api/v1/verification/*

Docs Updated

• docs/STATUS.md
• CHANGELOG.md
• docs/Phase-03-Completion-Report.md

Next Phase

Phase 04: 用户资料（UserProfile CRUD、照片上传、兴趣标签、择偶条件、隐私设置）