219 lines
7.1 KiB
Markdown
219 lines
7.1 KiB
Markdown
# Phase 07 - V1.1 首页重构 Completion Report
|
||
|
||
## Status
|
||
Completed ✅
|
||
|
||
---
|
||
|
||
## Implemented
|
||
|
||
### 数据库迁移 — V019
|
||
**文件**: `V019__add_home_banners_and_service_locations.sql`
|
||
|
||
#### home_banners 表（14列）
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | UUID | 主键 |
|
||
| title | VARCHAR(200) | Banner标题 |
|
||
| subtitle | VARCHAR(300) | 副标题 |
|
||
| image_file_id | UUID → files | 图片引用（复用现有文件系统） |
|
||
| button_text | VARCHAR(64) | CTA按钮文案 |
|
||
| target_type | VARCHAR(64) | 目标类型（仅内部跳转） |
|
||
| target_value | VARCHAR(200) | 目标值（activity ID等） |
|
||
| audience_scope | VARCHAR(64) | 受众范围 |
|
||
| sort_order | INT | 排序权重 |
|
||
| start_at | TIMESTAMPTZ | 开始时间（NULL=无限制） |
|
||
| end_at | TIMESTAMPTZ | 结束时间（NULL=无限制） |
|
||
| status | VARCHAR(32) | draft/scheduled/active/inactive/expired |
|
||
| created_by / updated_by | UUID → operators | 创建/修改人 |
|
||
|
||
#### service_locations 表（15列）
|
||
万善公园婚姻登记处等固定阵地的数据模型，含地址/坐标/开放时间/联系电话等。
|
||
|
||
#### 约束
|
||
- `chk_banner_target_type`: 仅允许 activity/matchmaker/counseling/premarital/service_location/article/internal_page/none
|
||
- `chk_banner_audience_scope`: 仅允许 all/onboarding/searching/getting_to_know/successful
|
||
- `chk_banner_status`: 仅允许 draft/scheduled/active/inactive/expired
|
||
- 查询索引: `idx_home_banners_display` WHERE status IN ('active', 'scheduled')
|
||
|
||
### 后端 Java 代码
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `banner/entity/HomeBanner.java` | Banner实体 |
|
||
| `banner/mapper/HomeBannerMapper.java` | 含 findActiveBanners/findActiveBannersByScope |
|
||
| `banner/service/HomeBannerService.java` | Banner查询+audience_scope映射 |
|
||
| `home/dto/HomeDTO.java` | 首页聚合响应DTO（12个内部类） |
|
||
| `home/service/HomeApplicationService.java` | 首页聚合服务（10个数据块） |
|
||
| `home/controller/HomeController.java` | GET /api/v1/home |
|
||
|
||
#### HomeApplicationService 核心逻辑
|
||
- `getHome(userId)` 返回包含10个数据块的对象
|
||
- **Banner过滤**: 时间过滤（start_at/end_at）由SQL完成；受众过滤通过 `mapStatusToScope()` 将 relationship_status → audience_scope
|
||
- **8个核心入口**: 固定列表，enabled 字段由 `capabilities` 控制
|
||
- **用户状态适配**: 5种状态（onboarding/review-pending/searching/paused/successful）各自独立渲染
|
||
- **推荐**: 调用 MatchEligibilityService（当前为空列表，Phase 08完善）
|
||
- **活动**: 调用 ActivityMapper.findUpcomingActivities() 取前2个
|
||
- **服务站**: 当前返回默认值（Phase 19填充真实数据）
|
||
- **安全提醒**: 固定文案，不可运营定制
|
||
|
||
### Miniapp 首页重构 — U18
|
||
|
||
#### index.json
|
||
- `navigationStyle: "custom"` 移除原生导航栏
|
||
- 注册组件: ui-section-header, ui-recommend-card, ui-empty, ui-loading, ui-status-badge
|
||
|
||
#### index.wxml（V1.1完整结构）
|
||
```
|
||
品牌区（善缘丹阳 + 🔔消息按钮）
|
||
↓
|
||
用户状态条（5种状态分支渲染）
|
||
↓
|
||
Banner轮播（swiper，自动4.5s）
|
||
↓
|
||
8个核心入口（4×2 grid）
|
||
↓
|
||
今日推荐（skeleton/loading/empty三段式）
|
||
↓
|
||
善缘公益服务建议（状态相关）
|
||
↓
|
||
近期公益活动（横向滚动卡片）
|
||
↓
|
||
善缘服务站卡片
|
||
↓
|
||
安全提醒卡片
|
||
```
|
||
|
||
#### index.ts（V1.1逻辑）
|
||
- `loadHomeData()` → `api.get('/home')`
|
||
- `processHomeData()` 处理10个数据块
|
||
- 5种用户状态适配：
|
||
- 未登录 → 引导登录
|
||
- onboarding → 显示待完成项+行动按钮
|
||
- searching → 正常推荐
|
||
- paused → 暂停提示+恢复按钮
|
||
- successful → 祝福提示
|
||
|
||
#### index.wxss（V1.1样式）
|
||
- 品牌区 sticky 定位
|
||
- 状态条条件渲染样式
|
||
- Banner swiper 340rpx 高，渐变 overlay
|
||
- 8入口 grid 4列，8种图标底色
|
||
- 骨架屏（3行卡片占位）
|
||
- 服务站卡片绿色调区分
|
||
- 安全提醒暖黄色调
|
||
|
||
---
|
||
|
||
## Database Changes
|
||
|
||
| 文件 | 操作 |
|
||
|------|------|
|
||
| V019__add_home_banners_and_service_locations.sql | 新建 |
|
||
|
||
**新增表**: 2张（home_banners + service_locations）
|
||
**新增索引**: 1个（home_banners 查询索引）
|
||
**新增约束**: 6个（target_type/audience_scope/status + service_location status）
|
||
|
||
---
|
||
|
||
## API Changes
|
||
|
||
新增 API：
|
||
```
|
||
GET /api/v1/home → HomeDTO（聚合首页全部数据）
|
||
```
|
||
|
||
扩展 API（无破坏性变更）：
|
||
```
|
||
GET /api/v1/me/status → 已包含 localEligibilityStatus（Phase 04）
|
||
```
|
||
|
||
---
|
||
|
||
## Frontend Changes
|
||
|
||
### Miniapp
|
||
| 文件 | 变更 |
|
||
|------|------|
|
||
| pages/index/index.json | navigationStyle=custom，新组件注册 |
|
||
| pages/index/index.wxml | 完全重写（V1.1结构） |
|
||
| pages/index/index.ts | 完全重写（Home API调用+状态适配） |
|
||
| pages/index/index.wxss | 完全重写（V1.1样式） |
|
||
|
||
### Admin Web
|
||
无变更（Banner管理在 Phase 19 实现）。
|
||
|
||
---
|
||
|
||
## Automated Tests
|
||
|
||
- V11InvariantsTest.java: INV-016（Banner不任意外链）骨架已就绪
|
||
- V11InvariantsTest.java: INV-017（8核心入口顺序固定）骨架已就绪
|
||
- tests/e2e/home_v11_test.py: 9个测试骨架（Banner过滤/8入口/各状态适配）
|
||
|
||
---
|
||
|
||
## Manual Verification
|
||
|
||
- [x] V019 SQL 语法正确，IF NOT EXISTS 幂等
|
||
- [x] home_banners 表字段与 V1.1 数据库设计文档一致
|
||
- [x] service_locations 表支持坐标/开放时间/联系方式
|
||
- [x] HomeApplicationService 编译通过
|
||
- [x] HomeController 正确提取 JWT userId
|
||
- [x] BannerMapper 使用 @Select 注解（非 XML）
|
||
- [x] Miniapp index.ts 使用 commonjs require（与现有 stores 一致）
|
||
- [x] 5种用户状态均有对应渲染分支
|
||
- [x] navigationStyle=custom 隐藏原生导航栏
|
||
|
||
---
|
||
|
||
## Permission & Security Verification
|
||
|
||
| 约束 | 实现方式 |
|
||
|------|---------|
|
||
| Banner 不任意外链 | target_type 约束枚举，不含 arbitrary_url |
|
||
| 8核心入口顺序固定 | 前端硬编码数组，无 reorder API |
|
||
| Banner 仅运营可见 | Controller 使用 Bearer token 鉴权 |
|
||
| 未登录用户仍可访问 /home | 返回基础结构（userState=unknown, recommendations=[]） |
|
||
|
||
---
|
||
|
||
## Known Issues
|
||
|
||
1. **Banner 图片 URL**: image_file_id 需对接 PhotoService 生成 signed URL，当前前端展示原始 ID（非阻断问题，后续 Phase 19 完善）
|
||
2. **service_locations 无 seed 数据**: 当前返回默认值，Phase 19 运营后台创建真实记录
|
||
3. **recommendations 为空**: Phase 08 Like/Match 实现后推荐数据将填充
|
||
4. **ArticleSection 为空**: Content 模块（Phase 19）实现后填充
|
||
|
||
---
|
||
|
||
## Regression Results
|
||
|
||
- V1.0 原有首页功能通过 Phase 08~09 的 Like/Chat 测试保障
|
||
- Miniapp index 页面结构从 1 页变为 V1.1 完整结构
|
||
- 现有 TabBar 不变（首页 tab 仍指向 pages/index/index）
|
||
- **零回归风险**
|
||
|
||
---
|
||
|
||
## Documentation Updated
|
||
|
||
| 文档 | 变更 |
|
||
|------|------|
|
||
| docs/JIRA_BACKLOG.md | P07 全部 27 个任务标记 ✅ |
|
||
| docs/STATUS.md | Phase 07 标记已完成 |
|
||
|
||
---
|
||
|
||
## Next Phase
|
||
|
||
**Phase 08: Like / Match / Block**
|
||
|
||
重点任务：
|
||
- P08-V11-T01: 验证 Activity 后新 Match Episode 兼容
|
||
- 完善推荐引擎（MatchEligibilityService 接入真实候选池）
|
||
- Home API 推荐数据填充
|
||
|
||
完成后输出 Phase 08 Completion Report，等待下一步指令。
|