chore: establish V1.1 recovery baseline
This commit is contained in:
@@ -0,0 +1,187 @@
|
||||
# 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，等待下一步指令。
|
||||
Reference in New Issue
Block a user