outsource/mi-assessment
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e5e63bd7f2
mi-assessment/.kiro/specs/home-more-modules/requirements.md
zpc e5e63bd7f2
All checks were successful
continuous-integration/drone/push Build is passing
Details
ui
2026-03-25 11:54:32 +08:00

6.8 KiB
Raw Blame History

Requirements Document

Introduction

小程序首页「更多」区域目前硬编码了两个卡片（学习方案、详细咨询），需要改为后台可配置化。复用现有 home_navigations 表，通过新增 Position 和 ActionType 字段来区分不同区域和点击动作类型，实现前端动态加载和后台统一管理。

Glossary

  • Home_Navigation: home_navigations 数据库表中的一条记录，代表首页的一个导航入口卡片
  • Position: 导航入口所属区域标识。1=专业测评区域，2=更多区域
  • ActionType: 导航入口的点击动作类型。1=跳转页面（使用 LinkUrl），2=弹出客服二维码弹窗，3=即将上线（提示"即将上线"）
  • Navigation_API: 小程序端获取首页导航列表的 GET 接口 /api/home/getNavigationList
  • Admin_Navigation_API: 后台管理系统中 ContentController 下的首页导航管理接口集合
  • More_Section: 小程序首页「更多」区域，展示 Position=2 的导航入口卡片
  • Assessment_Section: 小程序首页「专业测评」区域，展示 Position=1 的导航入口卡片
  • QR_Popup: 客服二维码弹窗组件，当 ActionType=2 时点击卡片弹出

Requirements

Requirement 1: 数据库表扩展

User Story: As a 系统管理员, I want home_navigations 表支持区域和动作类型字段, so that 不同区域的导航入口可以独立配置和管理。

Acceptance Criteria

  1. THE Home_Navigation 实体 SHALL 包含 Position 字段（int 类型，默认值为 1）
  2. THE Home_Navigation 实体 SHALL 包含 ActionType 字段（int 类型，默认值为 1）
  3. WHEN Position 字段值为 1 时, THE Home_Navigation SHALL 归属于 Assessment_Section
  4. WHEN Position 字段值为 2 时, THE Home_Navigation SHALL 归属于 More_Section
  5. WHEN ActionType 字段值为 1 时, THE Home_Navigation SHALL 表示点击后跳转 LinkUrl 指定的页面
  6. WHEN ActionType 字段值为 2 时, THE Home_Navigation SHALL 表示点击后弹出 QR_Popup
  7. WHEN ActionType 字段值为 3 时, THE Home_Navigation SHALL 表示点击后提示"即将上线"
  8. THE 数据库迁移脚本 SHALL 将现有 3 条记录的 Position 设置为 1、ActionType 设置为 1
  9. THE 数据库迁移脚本 SHALL 插入 2 条 Position=2 的初始数据：「学习方案」（ActionType=3）和「详细咨询」（ActionType=2）

Requirement 2: 小程序 API 改造

User Story: As a 前端开发者, I want Navigation_API 支持按区域筛选导航列表, so that 前端可以分别获取不同区域的导航数据。

Acceptance Criteria

  1. WHEN Navigation_API 收到请求且 position 参数存在时, THE Navigation_API SHALL 仅返回指定 Position 的启用状态（Status=1）导航记录
  2. WHEN Navigation_API 收到请求且 position 参数不存在时, THE Navigation_API SHALL 返回所有启用状态（Status=1）的导航记录
  3. THE Navigation_API 返回的每条记录 SHALL 包含 position 和 actionType 字段
  4. THE Navigation_API SHALL 按 Sort 字段降序排列返回结果
  5. THE Navigation_API SHALL 过滤掉 IsDeleted=true 和 Status=0 的记录

Requirement 3: 小程序首页「更多」区域动态渲染

User Story: As a 小程序用户, I want 首页「更多」区域的卡片从后台动态加载, so that 管理员可以灵活配置该区域的内容。

Acceptance Criteria

  1. WHEN 首页加载时, THE More_Section SHALL 调用 Navigation_API（position=2）获取导航数据
  2. THE More_Section SHALL 以每行 2 个卡片的网格布局展示导航入口
  3. WHEN 导航数据为奇数个时, THE More_Section SHALL 将最后一个卡片宽度设置为占满整行
  4. WHEN 导航数据为空时, THE More_Section SHALL 隐藏整个「更多」区块
  5. WHEN 用户点击 ActionType=1 的卡片时, THE More_Section SHALL 跳转到该卡片的 LinkUrl 页面
  6. WHEN 用户点击 ActionType=2 的卡片时, THE More_Section SHALL 弹出 QR_Popup 展示客服二维码
  7. WHEN 用户点击 ActionType=3 的卡片时, THE More_Section SHALL 显示"即将上线"提示（Toast，持续 2 秒）
  8. THE More_Section 的每个卡片 SHALL 展示导航名称和图标图片

Requirement 4: 小程序首页「专业测评」区域适配

User Story: As a 前端开发者, I want 「专业测评」区域也从按 Position 筛选的 API 获取数据, so that 两个区域的数据来源统一且互不干扰。

Acceptance Criteria

  1. WHEN 首页加载时, THE Assessment_Section SHALL 调用 Navigation_API（position=1）获取导航数据
  2. THE Assessment_Section SHALL 保持现有的卡片样式和交互逻辑
  3. WHEN 导航数据中某条记录的 ActionType=3 时, THE Assessment_Section SHALL 在该卡片上显示"即将上线"标签并禁止跳转
  4. THE Assessment_Section 的每个卡片 SHALL 以 ImageUrl 图片铺满整个卡片区域（mode="aspectFill"），不再使用渐变背景色+小图标+文字名称的组合方式，图片本身包含完整的卡片视觉内容

Requirement 5: 后台管理系统导航管理改造

User Story: As a 后台管理员, I want 在首页导航管理页面配置 Position 和 ActionType, so that 可以灵活管理不同区域的导航入口。

Acceptance Criteria

  1. THE Admin_Navigation_API 的列表查询接口 SHALL 支持按 Position 筛选
  2. THE Admin_Navigation_API 的创建接口 SHALL 接受 Position 和 ActionType 参数
  3. THE Admin_Navigation_API 的更新接口 SHALL 支持修改 Position 和 ActionType
  4. THE Admin_Navigation_API 的列表返回 SHALL 包含 Position 名称（专业测评区域/更多区域）和 ActionType 名称（跳转页面/弹客服二维码/即将上线）
  5. WHEN 创建导航时未指定 Position, THE Admin_Navigation_API SHALL 默认 Position 为 1
  6. WHEN 创建导航时未指定 ActionType, THE Admin_Navigation_API SHALL 默认 ActionType 为 1
  7. THE 后台管理前端导航管理页面 SHALL 提供 Position 下拉选择器（专业测评区域/更多区域）
  8. THE 后台管理前端导航管理页面 SHALL 提供 ActionType 下拉选择器（跳转页面/弹客服二维码/即将上线）
  9. WHEN ActionType 选择为"跳转页面"时, THE 后台管理前端 SHALL 显示 LinkUrl 输入框为必填
  10. WHEN ActionType 选择为"弹客服二维码"或"即将上线"时, THE 后台管理前端 SHALL 隐藏或禁用 LinkUrl 输入框

Requirement 6: 客服二维码弹窗

User Story: As a 小程序用户, I want 点击「详细咨询」卡片时弹出客服二维码, so that 可以方便地联系客服。

Acceptance Criteria

  1. WHEN 用户点击 ActionType=2 的导航卡片时, THE QR_Popup SHALL 以居中弹窗形式展示客服二维码图片
  2. THE QR_Popup SHALL 提供关闭按钮，点击后关闭弹窗
  3. THE QR_Popup SHALL 支持点击遮罩层关闭弹窗
  4. THE QR_Popup 的二维码图片 URL SHALL 从业务配置（configs 表 service_qrcode 配置项）中读取