docs: revise storefront and home requirements

miniprogram/docs/superpowers/specs/2026-07-12-comprehensive-venue-frontend-integration-design.md

@@ -1,7 +1,9 @@
 # 综合场馆新增业务前端对接设计
 
 > 日期：2026-07-12
-> 范围：共用小程序前端 `场馆小程序/miniprogram` 中的综合场馆模块  
+>
+> 范围：共用小程序前端 `场馆小程序/miniprogram` 中的综合场馆模块，以及冰场馆首页近期课程区块移除
+>
 > 对接后端：`综合场馆小程序/backend`
 
 ## 1. 背景
@@ -18,29 +20,31 @@
 ## 2. 目标
 
 - 将综合场馆会员端课程链路统一迁移到排课接口和 `session_id`。
-- 修复首页近期排课、普通课程预约列表和详情的字段兼容问题。
+- 移除综合场馆和冰场馆首页的近期课程展示，课程仍通过各自课程页面访问。
 - 提供课包/次卡套餐浏览、购买、持卡查看、使用流水和次卡预约能力。
-- 提供储值卡浏览、购买和微信支付能力。
+- 在商城展示储蓄卡，提供浏览、购买和微信支付能力；支付成功后按面值增加账户余额。
 - 在个人中心展示余额，并提供充值、我的次卡、余额流水和消费记录入口。
-- 保持包场、门票、订单和冰场馆模块行为不变。
+- 除移除首页近期课程区块外，保持包场、门票、订单和冰场馆其他行为不变。
 
 ## 3. 非目标
 
 - 不包含“场地页面按参考小程序重写/UI 对标”。
 - 不实现或调整后台锁场功能。
-- 不修改冰场馆页面、API、登录态或业务流程。
+- 除冰场馆首页移除近期课程展示外，不修改冰场馆其他页面、API、登录态或业务流程。
 - 不重构门票、包场和订单为统一商品或统一预约领域模型。
 - 不修改综合场馆后端的课程模板、排课、次卡或储值卡业务规则。
 - 不在前端实现核销或人工取消；次卡预约的核销和取消由后台处理。
 - 不在前端缓存计算余额、次卡剩余次数或排课剩余名额，以上数据以后端为准。
 
+本文产品界面使用需求中的“储蓄卡”称谓；代码、接口和后端模型沿用现有“储值卡”命名。两者在本文中指同一业务：用户购买卡商品，微信支付成功后按卡面值增加账户余额。
+
 ## 4. 方案选择
 
 采用“独立业务模块 + 复用现有通用页面”方案：
 
 - 保留综合场馆既有页面与 API 分层。
 - 会员端课程对象统一命名为 `session`，但保留现有 `pages/comprehensive/courses` 路由目录，避免无业务价值的路由迁移。
-- 新增独立的次卡和储值卡 API 模块。
+- 新增独立的次卡和储值卡 API 模块；商城界面将储值卡商品展示为“储蓄卡”。
 - 新增商城、我的次卡、次卡可约排课和次卡预约详情页面。
 - 复用现有订单支付页和订单列表，不额外建立第二套支付或消费记录系统。
 - 普通课程预约与次卡预约分别建模和展示，不强行合并为一个含订单的前端对象。
@@ -81,7 +85,7 @@ src/pages/comprehensive/membership/booking-detail.vue
 
 | 页面 | 职责 |
 |---|---|
-| `mall/index` | 分区展示储值卡和课包/次卡；创建购买订单并跳转支付 |
+| `mall/index` | 分区展示储蓄卡和课包/次卡；创建购买订单并跳转支付 |
 | `membership/cards` | 展示用户持有的次卡、总次数、剩余次数和状态 |
 | `membership/card-detail` | 展示次卡信息、适用课程、使用流水及“去预约”入口 |
 | `membership/available-sessions` | 展示用户次卡覆盖的未来排课，支持选择用于预约的次卡 |
@@ -89,7 +93,8 @@ src/pages/comprehensive/membership/booking-detail.vue
 
 ### 5.2 现有页面调整
 
-- 首页读取 `upcoming_sessions`。
+- 综合场馆首页移除近期课程/排课区块，只保留轮播、公告活动等非课程内容。
+- 冰场馆首页移除近期课程区块；冰场课程列表和详情页保持不变。
 - 课程列表、详情和确认页使用排课接口及 `session_id`。
 - 我的预约增加普通课程预约与次卡预约的切换入口。
 - 普通课程预约列表和详情读取 `booking.session`。
@@ -147,7 +152,7 @@ src/pages/comprehensive/membership/booking-detail.vue
 
 原 `/api/courses` 不再使用。原普通预约请求中的 `{ course_id }` 改为 `{ session_id }`。
 
-首页 `GET /api/contents/home` 返回 `upcoming_sessions`，前端使用同一个 `toSession()` 映射。
+综合场馆首页仍可通过 `GET /api/contents/home` 获取轮播、公告活动和场馆信息，但页面不再读取或展示响应中的 `upcoming_sessions`。后端无需为此修改首页接口。
 
 ### 7.2 普通课程预约
 
@@ -281,14 +286,14 @@ src/pages/comprehensive/membership/booking-detail.vue
 
 次卡预约没有支付订单，不应补造空 `order` 对象，也不得跳转支付页。
 
-### 7.6 储值卡
+### 7.6 储蓄卡（后端命名：储值卡）
 
 | 功能 | 方法与路径 | 参数 |
 |---|---|---|
 | 储值卡列表 | `GET /api/stored-value/cards` | 无 |
 | 创建购买订单 | `POST /api/stored-value/orders` | `{ card_id }` |
 
-储值卡视图模型：
+储蓄卡商品使用后端储值卡接口，视图模型为：
 
 ```js
 {
@@ -301,7 +306,7 @@ src/pages/comprehensive/membership/booking-detail.vue
 }
 ```
 
-页面必须区分售价 `price` 和充值到账面值 `face_value`。创建订单后使用响应中的 `order.id` 跳转现有支付页。
+商城必须展示储蓄卡商品，并明确区分售价 `price` 和充值到账面值 `face_value`。创建订单后使用响应中的 `order.id` 跳转现有支付页。支付成功后由后端按 `face_value` 增加会员余额。
 
 后端实际实现禁止储值卡订单使用余额支付。因此支付页检测到 `order.business_type === "stored_value"` 时：
 
@@ -331,7 +336,7 @@ src/pages/comprehensive/membership/booking-detail.vue
 ### 8.1 普通课程预约
 
 ```text
-排课列表或首页
+排课列表
   → 排课详情（session.id）
   → 确认预约
   → POST /bookings/course { session_id }
@@ -373,10 +378,10 @@ src/pages/comprehensive/membership/booking-detail.vue
 - 后台核销后扣减次数；后台取消后释放该预约状态。
 - 后端当前未提供会员自行取消次卡预约接口，前端不显示取消按钮。
 
-### 8.4 储值卡购买
+### 8.4 储蓄卡购买与余额增加
 
 ```text
-商城选择储值卡
+商城选择储蓄卡（后端储值卡商品）
   → POST /stored-value/orders { card_id }
   → 取得 order.id
   → 订单支付页（仅微信支付）
@@ -416,7 +421,7 @@ src/pages/comprehensive/membership/booking-detail.vue
 
 无需登录即可访问：
 
-- 首页及排课列表、排课详情。
+- 综合场馆和冰场馆首页，以及各自的课程/排课列表、详情。
 - 商城商品列表。
 - 次卡套餐列表和储值卡列表。
 
@@ -508,9 +513,11 @@ src/pages/comprehensive/membership/booking-detail.vue
 
 ## 16. 验收标准
 
-### 16.1 排课链路
+### 16.1 首页与排课链路
 
-- 首页读取并展示 `upcoming_sessions`。
+- 综合场馆首页不展示近期课程或 `upcoming_sessions`。
+- 冰场馆首页不展示近期课程。
+- 两个场馆原有课程入口、课程列表和课程详情仍可正常访问。
 - 排课列表筛选继续支持日期、教练和场地类型。
 - 排课列表、详情和普通预约全程使用同一个 `session.id`。
 - 普通预约请求发送 `{ session_id }`，成功后进入支付页。
@@ -533,9 +540,9 @@ src/pages/comprehensive/membership/booking-detail.vue
 - 后台取消后刷新页面显示 `cancelled`。
 - 前端不提供次卡预约取消按钮。
 
-### 16.4 储值卡
+### 16.4 储蓄卡
 
-- 商城正确区分售价和到账面值。
+- 商城展示上架的储蓄卡商品，并正确区分售价和到账面值。
 - 创建储值卡订单后支付页只允许微信支付。
 - 支付成功后余额增加 `face_value`，而不是 `price`。
 - 余额流水出现“充值”记录。
@@ -553,11 +560,11 @@ src/pages/comprehensive/membership/booking-detail.vue
 - 包场预约流程不受影响。
 - 门票购买、持有和核销展示不受影响。
 - 已有订单详情、关闭订单、余额支付和微信支付流程不受影响。
-- 冰场馆模块的页面、接口、token 和状态不受影响。
+- 冰场馆首页近期课程区块被移除，冰场馆其他页面、接口、token 和状态不受影响。
 
 ## 17. 实施顺序
 
-1. 修改排课 API、首页字段和普通预约映射，恢复现有课程链路。
+1. 修改排课 API 和普通预约映射，恢复现有课程链路；移除综合场馆与冰场馆首页近期课程区块。
 2. 新增次卡 API 模块、商城套餐购买和我的次卡。
 3. 新增次卡可约排课、创建预约、预约列表和详情。
 4. 新增储值卡 API、商城展示和购买流程。