diff --git a/miniprogram/docs/superpowers/specs/2026-07-12-comprehensive-venue-frontend-integration-design.md b/miniprogram/docs/superpowers/specs/2026-07-12-comprehensive-venue-frontend-integration-design.md index 572e902..94fdd9c 100644 --- a/miniprogram/docs/superpowers/specs/2026-07-12-comprehensive-venue-frontend-integration-design.md +++ b/miniprogram/docs/superpowers/specs/2026-07-12-comprehensive-venue-frontend-integration-design.md @@ -1,7 +1,9 @@ # 综合场馆新增业务前端对接设计 -> 日期:2026-07-12 -> 范围:共用小程序前端 `场馆小程序/miniprogram` 中的综合场馆模块 +> 日期:2026-07-12 +> +> 范围:共用小程序前端 `场馆小程序/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、商城展示和购买流程。