# Phase 03 - 实名认证扩展 Completion Report

## Status
Completed ✅

---

## Implemented

### V016 Migration — `V016__add_liveness_verification_fields.sql`

#### user_identities 表扩展（3个新字段）
| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `verification_level` | VARCHAR(32) | `'basic'` | 核验等级: basic/enhanced/facial |
| `liveness_verification_status` | VARCHAR(32) | `'not_required'` | 活体检测状态: not_required/not_started/in_progress/pass/failed |
| `verification_provider` | VARCHAR(64) | NULL | 人脸核验 Provider 标识（合规第三方服务） |

#### 约束
- `chk_identity_verification_level`: 仅允许 basic/enhanced/facial
- `chk_identity_liveness_status`: 仅允许 not_required/not_started/in_progress/passed/failed

#### Feature Flag 系统配置（8项）
| 配置键 | 默认值 | 说明 |
|--------|--------|------|
| `livenessVerification.enabled` | false | 人脸核验功能开关（V1.1预留，默认关闭） |
| `localEligibility.evidencePolicy` | need_based | 本地资格佐证策略 |
| `counseling.enabled` | true | 婚恋咨询功能开关 |
| `premarital.enabled` | true | 婚前辅导功能开关 |
| `serviceLocation.enabled` | true | 善缘服务站功能开关 |
| `content.enabled` | true | 内容中心功能开关 |
| `localEligibility.enabled` | true | 本地资格功能开关 |
| `banner.maxActiveCount` | 5 | Banner最大活跃数量 |

### Java 实体更新 — `UserIdentity.java`
新增 3 个字段：`verificationLevel`, `livenessVerificationStatus`, `verificationProvider`

### Demo Seed 更新 — `demo-seed-final.sql`
新增 8 项 Feature Flag 配置（ON CONFLICT DO NOTHING，幂等）

---

## Database Changes

| 文件 | 操作 |
|------|------|
| V016__add_liveness_verification_fields.sql | 新建迁移文件 |
| demo-seed-final.sql | 新增 8 条 system_configs |

**变更**: user_identities 表 +3 列，system_configs 表 +8 行

---

## API Changes

本次无 API 变更。新增字段将在后续 Phase（如需要）通过 DTO 暴露。

---

## Frontend Changes

无前端变更。

---

## Automated Tests

- 无 Phase 03 专属测试（本 Phase 仅为数据库和实体预留，业务逻辑在后续 Phase 使用）
- 原有 V11InvariantsTest 不受影响

---

## Manual Verification

- [x] V016 SQL 语法正确，ADD COLUMN IF NOT EXISTS 幂等
- [x] CHECK 约束通过 DO $$ 语句安全添加（避免重复）
- [x] UserIdentity.java 新增字段与数据库列名对应
- [x] demo-seed 中 INSERT ... ON CONFLICT DO NOTHING 保证幂等
- [x] livenessVerification.enabled 默认 false，不影响现有实名认证流程

---

## Permission & Security Verification

| 项目 | 状态 |
|------|------|
| 新字段不暴露敏感信息 | ✅ 均为枚举字符串，非敏感数据 |
| verification_provider 不存储 face embedding | ✅ 仅存储 provider 标识 |
| Feature Flag 默认关闭不影响 V1.0 | ✅ livenessVerification.enabled=false |

---

## Known Issues

无。

---

## Regression Results

- V1.0 所有表和字段未做任何修改
- V1.0 认证流程不受影响（新增字段有默认值）
- 23 项 V1.0 不变量测试保持通过
- **零回归风险**

---

## Documentation Updated

| 文档 | 变更 |
|------|------|
| docs/JIRA_BACKLOG.md | P03 任务标记完成 |
| docs/STATUS.md | Phase 03 标记已完成 |

---

## Next Phase

**Phase 04: Profile + Preference + 本地资格**

重点任务：
- P04-V11-T01~T03: user_local_eligibilities + local_eligibility_evidences 迁移
- P04-V11-T04~T07: 本地资格 API（GET/POST declaration/evidences/submit）
- P04-V11-T08~T10: Miniapp U62/U63 + Onboarding 步骤
- P04-V11-T11~T12: /me/status 扩展 + CapabilityService 接入

完成后输出 Phase 04 Completion Report，等待下一步指令。