danyang-match/docs/Phase-07-V11-Completion-Report.md

# 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，等待下一步指令。