188 lines
5.6 KiB
Markdown
188 lines
5.6 KiB
Markdown
# 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，等待下一步指令。
|