admin/danyang-match
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
69cf6a2cc79f9ec2faae8d72199acdf7b7575fee
danyang-match/docs/Phase-07-V11-Completion-Report.md
T

7.1 KiB
Raw Blame History

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

  • V019 SQL 语法正确，IF NOT EXISTS 幂等
  • home_banners 表字段与 V1.1 数据库设计文档一致
  • service_locations 表支持坐标/开放时间/联系方式
  • HomeApplicationService 编译通过
  • HomeController 正确提取 JWT userId
  • BannerMapper 使用 @Select 注解（非 XML）
  • Miniapp index.ts 使用 commonjs require（与现有 stores 一致）
  • 5种用户状态均有对应渲染分支
  • 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，等待下一步指令。

Reference in New Issue View Git Blame Copy Permalink