gqt/venue-miniapp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: revise storefront and home requirements

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