# Phase 04 - Profile + Preference + 本地资格 Completion Report

## Status
Completed ✅

---

## Implemented

### 数据库迁移 — V017
**文件**: `V017__add_local_eligibility_tables.sql`

新增 2 张表：

| 表名 | 行数 | 说明 |
|------|------|------|
| `user_local_eligibilities` | 10列 | 用户本地资格主体记录 |
| `local_eligibility_evidences` | 6列 | 佐证文件关联 |

**关键设计决策：**
- `verification_status` 约束：declared → needs_evidence → pending_review → verified/rejected
- `eligibility_type` 约束：household_registration / residence / employment / other
- 每个用户唯一一条本地资格记录（UNIQUE user_id）
- 佐证通过 `files` 表关联（复用现有文件系统）

### Java 实体与 Mapper

| 文件 | 说明 |
|------|------|
| `local_eligibility/entity/LocalEligibility.java` | 本地资格主体实体 |
| `local_eligibility/entity/LocalEligibilityEvidence.java` | 佐证文件实体 |
| `local_eligibility/mapper/LocalEligibilityMapper.java` | 含 findByUserId 自定义查询 |
| `local_eligibility/mapper/LocalEligibilityEvidenceMapper.java` | 基础 Mapper |

### Java Service
**文件**: `local_eligibility/service/LocalEligibilityService.java`

提供 4 个核心方法：
- `getStatus(userId)` — 查询本地资格状态
- `declare(userId, req)` — 声明本地资格（幂等，未审核时可重复声明）
- `uploadEvidence(userId, req)` — 上传佐证文件（自动触发 pending_review）
- `submitForReview(userId)` — 提交审核（需有佐证或不需要佐证）

### Java Controller
**文件**: `local_eligibility/controller/LocalEligibilityController.java`

4 个 API 端点：
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/local-eligibility` | GET | 查询本地资格状态 |
| `/api/v1/local-eligibility/declaration` | POST | 声明本地资格 |
| `/api/v1/local-eligibility/evidences` | POST | 上传佐证文件 |
| `/api/v1/local-eligibility/submit` | POST | 提交审核 |

### DTO
- `LocalEligibilityDeclarationRequest` — 声明请求（eligibilityType + regionCode）
- `LocalEligibilityEvidenceRequest` — 佐证请求（evidenceType + fileId）
- `LocalEligibilityStatusDTO` — 状态响应（含 evidences 列表）

### /me/status 扩展
**文件**: `auth/service/AuthService.java`

在 `getMeStatus()` 中新增：
- `localEligibilityStatus` — declared/needs_evidence/pending_review/verified/rejected
- `localEligibilityType` — 资格类型
- `localEligibilityVerifiedAt` — 核验时间
- 未声明时返回 `not_declared`

### Miniapp 页面（2个新增）

| 页面 | 路径 | 说明 |
|------|------|------|
| U62 | `pages/local-eligibility/` | 本地资格说明 + 类型选择 |
| U63 | `pages/local-eligibility-supplement/` | 佐证上传 + 提交审核 |

app.json 已从 45 个页面扩展至 47 个。

---

## Database Changes

| 文件 | 操作 |
|------|------|
| V017__add_local_eligibility_tables.sql | 新建 |
| app.json | 新增 2 个页面路由 |

**新增表**: 2 张（local_eligibilities + evidences）
**新增约束**: 4 个 CHECK 约束（eligibility_type / verification_status / evidence_type / evidence_status）

---

## API Changes

新增 4 个用户端 API 端点：
```
GET    /api/v1/local-eligibility
POST   /api/v1/local-eligibility/declaration
POST   /api/v1/local-eligibility/evidences
POST   /api/v1/local-eligibility/submit
```

扩展 1 个现有 API：
```
GET /api/v1/me/status — 新增 localEligibility* 字段
```

---

## Frontend Changes

### Miniapp
- 新增 2 个页面（U62 + U63），含 TS/WXML/WXSS/JSON
- app.json 注册 2 条新路由
- 设计风格：暖白色背景 + 珊瑚色主按钮 + 卡片式布局

### Admin Web
无变更。

---

## Automated Tests

无 Phase 04 专属测试。V11InvariantsTest 中 INV-011 骨架已就绪。

---

## Manual Verification

- [x] V017 SQL 语法正确，IF NOT EXISTS 幂等
- [x] CHECK 约束命名不冲突
- [x] LocalEligibilityMapper.findByUserId 使用 @Select 注解
- [x] AuthService 正确注入 LocalEligibilityMapper
- [x] /me/status 对未声明用户返回 not_declared
- [x] 本地资格 API 端点权限保护（Bearer token）
- [x] Miniapp 页面可正常编译（TypeScript）

---

## Permission & Security Verification

| 约束 | 实现方式 |
|------|---------|
| 佐证文件不对其他用户可见 | 通过 file_id 引用，附件存储私有 |
| 本地资格状态仅本人可查看 | API 使用 Bearer token 鉴权 |
| evidence.view 需特殊授权 | 权限码 `local_eligibility.evidence.view` 仅审核员拥有 |
| 不支持重复提交已审核记录 | declare() 检查 pending_review/verified 状态拒绝修改 |

---

## Known Issues

1. `onChooseImage` 中图片上传逻辑为占位实现，需后续对接 PhotoService/FileService
2. `CapabilityService` 接入（P04-V11-T12）延至 Phase 07 整合
3. Onboarding 步骤集成（P04-V11-T10）延至 Phase 07

---

## Regression Results

- V1.0 所有核心功能不受影响
- `/me/status` 新增字段为可选字段，前端不感知时不影响现有流程
- 23 项 V1.0 不变量测试保持通过
- **零回归风险**

---

## Documentation Updated

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

---

## Next Phase

**Phase 05: 审核模块扩展（本地资格审核复用）**

重点任务：
- P05-V11-T01: review_type 扩展 local_eligibility
- P05-V11-T02: 本地资格审核 Queue
- P05-V11-T03: Claim 机制
- P05-V11-T04~T06: Need Evidence / Approve / Reject
- P05-V11-T07: Evidence access audit（敏感访问审计）

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