From 44b9e90339b6eca8c0d5cda9f8daac84411afffe Mon Sep 17 00:00:00 2001
From: gqt <3217233537@qq.com>
Date: Sun, 12 Jul 2026 18:49:55 +0800
Subject: [PATCH] docs: add comprehensive frontend integration design

---
 ...nsive-venue-frontend-integration-design.md | 579 ++++++++++++++++++
 1 file changed, 579 insertions(+)
 create mode 100644 miniprogram/docs/superpowers/specs/2026-07-12-comprehensive-venue-frontend-integration-design.md

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
new file mode 100644
index 0000000..572e902
--- /dev/null
+++ b/miniprogram/docs/superpowers/specs/2026-07-12-comprehensive-venue-frontend-integration-design.md
@@ -0,0 +1,579 @@
+# 综合场馆新增业务前端对接设计
+
+> 日期：2026-07-12  
+> 范围：共用小程序前端 `场馆小程序/miniprogram` 中的综合场馆模块  
+> 对接后端：`综合场馆小程序/backend`
+
+## 1. 背景
+
+综合场馆后端已经完成以下新增需求：
+
+- 将会员端可预约对象从旧的课程记录拆分为“课程模板 + 排课 `CourseSession`”，会员端以排课为操作对象。
+- 新增课包/次卡套餐购买、用户持卡、适用排课查询、次卡预约及使用流水。
+- 新增储值卡商品、储值卡购买订单及支付后余额充值。
+- 延续已有余额、余额流水、订单、普通课程预约、包场和门票能力。
+
+共用小程序前端仍使用旧课程接口和旧字段，且尚无综合场馆的次卡、储值卡商城和次卡预约页面。因此需要调整现有课程链路，并新增商城、次卡和个人中心相关能力。
+
+## 2. 目标
+
+- 将综合场馆会员端课程链路统一迁移到排课接口和 `session_id`。
+- 修复首页近期排课、普通课程预约列表和详情的字段兼容问题。
+- 提供课包/次卡套餐浏览、购买、持卡查看、使用流水和次卡预约能力。
+- 提供储值卡浏览、购买和微信支付能力。
+- 在个人中心展示余额，并提供充值、我的次卡、余额流水和消费记录入口。
+- 保持包场、门票、订单和冰场馆模块行为不变。
+
+## 3. 非目标
+
+- 不包含“场地页面按参考小程序重写/UI 对标”。
+- 不实现或调整后台锁场功能。
+- 不修改冰场馆页面、API、登录态或业务流程。
+- 不重构门票、包场和订单为统一商品或统一预约领域模型。
+- 不修改综合场馆后端的课程模板、排课、次卡或储值卡业务规则。
+- 不在前端实现核销或人工取消；次卡预约的核销和取消由后台处理。
+- 不在前端缓存计算余额、次卡剩余次数或排课剩余名额，以上数据以后端为准。
+
+## 4. 方案选择
+
+采用“独立业务模块 + 复用现有通用页面”方案：
+
+- 保留综合场馆既有页面与 API 分层。
+- 会员端课程对象统一命名为 `session`，但保留现有 `pages/comprehensive/courses` 路由目录，避免无业务价值的路由迁移。
+- 新增独立的次卡和储值卡 API 模块。
+- 新增商城、我的次卡、次卡可约排课和次卡预约详情页面。
+- 复用现有订单支付页和订单列表，不额外建立第二套支付或消费记录系统。
+- 普通课程预约与次卡预约分别建模和展示，不强行合并为一个含订单的前端对象。
+
+该方案与现有 `modules/comprehensive` 目录结构一致，能明确区分课程模板 ID、排课 ID、普通订单预约和无订单的次卡预约，同时将改动限制在新增需求范围内。
+
+## 5. 工程边界
+
+综合场馆模块继续使用以下分层：
+
+```text
+src/pages/comprehensive/             页面与交互
+src/modules/comprehensive/api/       接口请求与响应映射
+src/modules/comprehensive/stores/    登录会员状态
+src/modules/comprehensive/utils/     日期、金额和状态工具
+```
+
+新增 API 模块：
+
+```text
+src/modules/comprehensive/api/membership.js
+src/modules/comprehensive/api/storedValue.js
+```
+
+新增页面：
+
+```text
+src/pages/comprehensive/mall/index.vue
+src/pages/comprehensive/membership/cards.vue
+src/pages/comprehensive/membership/card-detail.vue
+src/pages/comprehensive/membership/available-sessions.vue
+src/pages/comprehensive/membership/booking-detail.vue
+```
+
+以上页面需注册到 `src/pages.json`。
+
+### 5.1 页面职责
+
+| 页面 | 职责 |
+|---|---|
+| `mall/index` | 分区展示储值卡和课包/次卡；创建购买订单并跳转支付 |
+| `membership/cards` | 展示用户持有的次卡、总次数、剩余次数和状态 |
+| `membership/card-detail` | 展示次卡信息、适用课程、使用流水及“去预约”入口 |
+| `membership/available-sessions` | 展示用户次卡覆盖的未来排课，支持选择用于预约的次卡 |
+| `membership/booking-detail` | 展示次卡预约状态、排期和所用次卡，不展示订单信息 |
+
+### 5.2 现有页面调整
+
+- 首页读取 `upcoming_sessions`。
+- 课程列表、详情和确认页使用排课接口及 `session_id`。
+- 我的预约增加普通课程预约与次卡预约的切换入口。
+- 普通课程预约列表和详情读取 `booking.session`。
+- 个人中心增加余额、充值、我的次卡、余额流水和消费记录入口。
+- 支付页识别储值卡订单，并强制使用微信支付。
+- 我的订单继续作为消费记录页面，展示新增的会员卡和储值卡订单类型。
+
+## 6. 排课模型与标识规则
+
+会员端所有可预约课程均为排课 `session`：
+
+- `session.id`：排课 ID，用于排课详情、普通课程预约和次卡预约。
+- `session.course_id`：课程模板 ID，仅用于展示、关联和识别课程定义，不能作为预约请求参数。
+- 页面路由中的课程详情 `id` 实际表示 `session.id`。
+- 前端不得把 `course_id` 回退用作排课 ID。
+
+统一排课视图模型：
+
+```js
+{
+  id,
+  course_id,
+  title,
+  cover_image,
+  coach_id,
+  coach_name,
+  start_at,
+  end_at,
+  capacity,
+  booked_count,
+  remaining_count,
+  price,
+  status,
+  status_label,
+  courts,
+  detail_html,
+  created_at,
+  updated_at
+}
+```
+
+列表接口没有的详情字段使用空值填充，使列表和详情可以复用 `toSession()`，但页面不得依赖列表响应中的 `detail_html`。
+
+## 7. 接口设计
+
+所有接口继续使用综合场馆现有请求封装，基础路径为综合场馆后端的 `/api`，响应仍由请求层解包为 `body.data`。
+
+### 7.1 排课
+
+| 功能 | 方法与路径 | 参数 |
+|---|---|---|
+| 排课列表 | `GET /api/sessions` | `page`、`page_size`、`date`、`coach_id`、`court_type` |
+| 排课详情 | `GET /api/sessions/{session_id}` | 排课 ID |
+| 创建普通课程预约 | `POST /api/bookings/course` | `{ session_id }` |
+
+原 `/api/courses` 不再使用。原普通预约请求中的 `{ course_id }` 改为 `{ session_id }`。
+
+首页 `GET /api/contents/home` 返回 `upcoming_sessions`，前端使用同一个 `toSession()` 映射。
+
+### 7.2 普通课程预约
+
+| 功能 | 方法与路径 |
+|---|---|
+| 预约列表 | `GET /api/bookings/courses` |
+| 预约详情 | `GET /api/bookings/courses/{booking_id}` |
+| 用户取消 | `POST /api/bookings/courses/{booking_id}/cancel` |
+
+普通预约视图模型：
+
+```js
+{
+  id,
+  session_id,
+  order_id,
+  status,
+  status_label,
+  expire_at,
+  checked_in_at,
+  cancelled_at,
+  cancel_by,
+  cancel_reason,
+  can_cancel,
+  cancel_deadline_at,
+  created_at,
+  session,
+  order
+}
+```
+
+前端不再读取 `booking.course_id` 或 `booking.course`。
+
+### 7.3 次卡套餐购买
+
+| 功能 | 方法与路径 | 参数 |
+|---|---|---|
+| 套餐列表 | `GET /api/membership/plans` | 无 |
+| 创建购买订单 | `POST /api/membership/orders` | `{ plan_id }` |
+
+套餐视图模型包含：
+
+```js
+{
+  id,
+  name,
+  price,
+  total_count,
+  is_active,
+  courses: [{ id, title }],
+  created_at
+}
+```
+
+创建成功后使用响应中的 `order.id` 跳转现有支付页。次卡购买订单允许余额支付和微信支付。只有后端确认订单支付成功后，用户持卡才可用于预约。
+
+### 7.4 我的次卡与使用流水
+
+| 功能 | 方法与路径 | 参数 |
+|---|---|---|
+| 我的次卡 | `GET /api/membership/cards` | `page`、`page_size` |
+| 次卡使用流水 | `GET /api/membership/cards/{card_id}/usage-records` | `page`、`page_size` |
+
+用户次卡视图模型：
+
+```js
+{
+  id,
+  plan_id,
+  plan_name,
+  total_count,
+  remaining_count,
+  status,
+  status_label,
+  order_id,
+  created_at
+}
+```
+
+后端当前没有单张用户次卡详情接口。`card-detail` 使用从卡列表传入或重新在卡列表中查得的卡片数据，并单独请求使用流水。页面不得请求未定义的 `/membership/cards/{card_id}`。
+
+使用流水重点展示 `kind_label`、`count`、`remark`、`booking_id`、`order_id` 和 `created_at`。
+
+### 7.5 次卡可约排课与预约
+
+| 功能 | 方法与路径 | 参数 |
+|---|---|---|
+| 次卡可约排课 | `GET /api/membership/available-courses` | `page`、`page_size` |
+| 创建次卡预约 | `POST /api/membership/bookings` | `{ card_id, session_id }` |
+| 次卡预约列表 | `GET /api/membership/bookings` | `page`、`page_size` |
+| 次卡预约详情 | `GET /api/membership/bookings/{booking_id}` | 预约 ID |
+
+`available-courses` 虽保留旧路径命名，但返回对象是排课。前端将其映射为 `availableSession`：
+
+```js
+{
+  id,
+  course_id,
+  title,
+  cover_image,
+  coach_name,
+  start_at,
+  end_at,
+  capacity,
+  booked_count,
+  remaining_count,
+  price,
+  available_card_ids
+}
+```
+
+其中 `id` 为 `session_id`。前端不自行根据套餐课程计算是否可约，只使用后端返回的列表及 `available_card_ids`。
+
+次卡预约视图模型：
+
+```js
+{
+  id,
+  card_id,
+  session_id,
+  status,
+  status_label,
+  checked_in_at,
+  cancelled_at,
+  cancel_reason,
+  created_at,
+  card,
+  session
+}
+```
+
+次卡预约没有支付订单，不应补造空 `order` 对象，也不得跳转支付页。
+
+### 7.6 储值卡
+
+| 功能 | 方法与路径 | 参数 |
+|---|---|---|
+| 储值卡列表 | `GET /api/stored-value/cards` | 无 |
+| 创建购买订单 | `POST /api/stored-value/orders` | `{ card_id }` |
+
+储值卡视图模型：
+
+```js
+{
+  id,
+  name,
+  price,
+  face_value,
+  is_active,
+  created_at
+}
+```
+
+页面必须区分售价 `price` 和充值到账面值 `face_value`。创建订单后使用响应中的 `order.id` 跳转现有支付页。
+
+后端实际实现禁止储值卡订单使用余额支付。因此支付页检测到 `order.business_type === "stored_value"` 时：
+
+- 不显示或禁用余额支付选项。
+- 默认选择微信支付。
+- 不调用 `/orders/{id}/pay/balance`。
+- 支付完成后重新查询后端余额，不在前端直接加上面值。
+
+### 7.7 个人中心
+
+| 展示内容 | 数据来源 |
+|---|---|
+| 当前余额 | `GET /api/members/balance` |
+| 余额流水 | `GET /api/members/balance-records` |
+| 我的次卡 | `GET /api/membership/cards` |
+| 消费记录 | `GET /api/orders` |
+
+余额流水和消费记录保持为两个概念：
+
+- 余额流水展示余额账户的充值、消费和退款等变动。
+- 消费记录复用订单列表，展示课程、包场、门票、会员卡和储值卡订单。
+
+储值卡支付成功后，余额流水由后端产生 `kind="recharge"`、`kind_label="充值"` 的正数记录，前端沿用通用余额流水映射和正负金额样式。
+
+## 8. 业务流程
+
+### 8.1 普通课程预约
+
+```text
+排课列表或首页
+  → 排课详情（session.id）
+  → 确认预约
+  → POST /bookings/course { session_id }
+  → 取得 order.id
+  → 订单支付页
+  → 余额支付或微信支付
+  → 普通预约详情
+```
+
+### 8.2 次卡购买
+
+```text
+商城选择次卡套餐
+  → POST /membership/orders { plan_id }
+  → 取得 order.id
+  → 订单支付页
+  → 余额支付或微信支付
+  → 刷新 /membership/cards
+  → 我的次卡
+```
+
+### 8.3 次卡预约
+
+```text
+我的次卡详情或课程入口
+  → GET /membership/available-courses
+  → 选择排课
+  → 确定 available_card_ids 中的 card_id
+  → POST /membership/bookings { card_id, session_id }
+  → 次卡预约详情
+```
+
+选择规则：
+
+- `available_card_ids` 只有一个值时直接使用该卡。
+- 有多个值时展示卡片选择器，由用户确认具体次卡。
+- 从某张次卡详情进入时预选该卡，并过滤 `available_card_ids` 不包含该卡 ID 的排课。
+- 预约成功只占名额，不立即减少次数。
+- 后台核销后扣减次数；后台取消后释放该预约状态。
+- 后端当前未提供会员自行取消次卡预约接口，前端不显示取消按钮。
+
+### 8.4 储值卡购买
+
+```text
+商城选择储值卡
+  → POST /stored-value/orders { card_id }
+  → 取得 order.id
+  → 订单支付页（仅微信支付）
+  → 后端确认支付并按 face_value 充值
+  → 重新查询余额和余额流水
+```
+
+关闭未支付储值卡订单不改变余额。
+
+## 9. 我的预约展示
+
+“我的预约”页面保留课程、包场和门票业务入口，并在课程预约内区分：
+
+- 普通课程预约：来自 `/bookings/courses`，展示订单金额和订单状态，可按后端 `can_cancel` 取消。
+- 次卡预约：来自 `/membership/bookings`，展示次卡名称和剩余次数，金额位置显示“次卡预约”，不展示订单操作。
+
+两类预约分别维护请求状态和分页，不将次卡预约伪装成普通预约。切换分类时加载对应接口。
+
+次卡预约状态包括：
+
+- `booked`：已预约，等待到场处理。
+- `checked_in`：已核销，后台已扣减次数。
+- `cancelled`：已由后台取消。
+
+## 10. 预约场地字段兼容
+
+排课列表和排课详情返回 `courts`，可以正常展示场地。
+
+普通预约与次卡预约响应中的嵌套 `session` 当前不包含 `courts`。本次前端实施采用以下规则：
+
+- 预约列表和预约详情不依赖 `session.courts`，暂不展示场地名称。
+- 显示标题、教练、上课时间、状态及订单或次卡信息。
+- 映射函数可兼容接收未来新增的 `courts`，但不得假设该字段存在。
+- 后端未来补充 `courts` 后，前端可再恢复预约详情中的场地展示。
+
+## 11. 登录与访问控制
+
+无需登录即可访问：
+
+- 首页及排课列表、排课详情。
+- 商城商品列表。
+- 次卡套餐列表和储值卡列表。
+
+必须登录才能执行：
+
+- 创建普通课程预约。
+- 购买次卡或储值卡。
+- 使用次卡预约。
+- 查看我的次卡、次卡流水、预约、余额、余额流水和订单。
+
+受限操作发现未登录时调用现有综合场馆登录流程。登录成功后继续原操作，并保留当前选中的商品、排课和次卡；登录失败或用户取消时停留在当前页面。
+
+401 或业务码 `40001` 继续由综合场馆请求层清理综合场馆 token，不影响冰场馆登录态。
+
+## 12. 可用性与提交控制
+
+### 12.1 普通预约
+
+普通预约按钮至少满足以下条件才可用：
+
+- `status === "published"`。
+- `remaining_count > 0`。
+- `start_at` 晚于当前时间。
+
+最终可预约性以后端创建预约接口校验结果为准。
+
+### 12.2 次卡预约
+
+- 只从 `/membership/available-courses` 选择排课。
+- 不在前端根据套餐课程列表推导可预约范围。
+- 选中的 `card_id` 必须存在于该排课的 `available_card_ids`。
+
+### 12.3 防重复提交
+
+以下操作设置独立的 `isSubmitting` 或等价状态，并在请求期间禁用操作按钮：
+
+- 创建普通课程预约。
+- 创建次卡购买订单。
+- 创建储值卡购买订单。
+- 创建次卡预约。
+- 发起订单支付。
+
+提交状态在 `finally` 中恢复。接口成功后的页面跳转只执行一次。
+
+## 13. 支付处理
+
+- 余额支付接口成功后可视为后端已经完成支付及业务确认。
+- 微信 `uni.requestPayment` 成功后重新查询订单详情，以后端订单状态为准。
+- 微信支付取消或失败时保留待支付订单，用户可从我的订单再次进入支付。
+- 储值卡订单仅允许微信支付。
+- 次卡购买订单允许余额支付和微信支付。
+- 支付成功后不在前端直接修改余额、持卡列表或剩余次数，而是重新请求对应接口。
+
+## 14. 错误处理
+
+请求层继续统一展示后端 `message`。页面在以下业务错误后刷新相关数据，避免保留过期按钮状态：
+
+- 排课已开始、已取消或未上架。
+- 排课名额已满。
+- 用户已存在普通预约或次卡预约。
+- 次卡不可用、次数已用完或不覆盖该课程。
+- 次卡套餐或储值卡已下架。
+- 余额不足。
+- 订单已支付、已关闭或已过期。
+
+页面级错误状态至少区分：
+
+- 首次加载中。
+- 正常内容。
+- 空数据。
+- 请求失败，可重试。
+- 提交中，按钮禁用。
+
+## 15. 分页与刷新
+
+以下列表使用现有分页约定 `page`、`page_size`、`items`、`total`：
+
+- 排课列表。
+- 普通课程预约。
+- 次卡预约。
+- 我的次卡。
+- 次卡使用流水。
+- 余额流水。
+- 消费记录。
+
+下拉刷新时重置为第 1 页并替换列表；触底加载时追加下一页；以当前项目统一规则 `items.length < total` 判断是否还有更多数据。加载更多请求期间不得重复发起同一页请求。
+
+次卡套餐列表和储值卡列表目前不分页，直接加载全部上架商品。
+
+## 16. 验收标准
+
+### 16.1 排课链路
+
+- 首页读取并展示 `upcoming_sessions`。
+- 排课列表筛选继续支持日期、教练和场地类型。
+- 排课列表、详情和普通预约全程使用同一个 `session.id`。
+- 普通预约请求发送 `{ session_id }`，成功后进入支付页。
+- 普通预约列表和详情正确读取 `booking.session`，不再访问旧 `booking.course`。
+
+### 16.2 次卡购买与持卡
+
+- 商城可以展示上架的次卡套餐、价格、总次数和适用课程。
+- 创建次卡订单后可以选择余额或微信支付。
+- 支付成功后可以在“我的次卡”看到卡片及正确剩余次数。
+- 次卡详情可以查看使用流水，并进入可约排课页面。
+
+### 16.3 次卡预约
+
+- 可约排课只显示后端返回的、用户次卡覆盖的未来排课。
+- 一个排课有多张可用次卡时可以选择具体卡。
+- 次卡预约请求发送 `{ card_id, session_id }`。
+- 次卡预约成功后不创建前端支付流程，也不立即减少次数。
+- 后台核销后刷新页面显示 `checked_in`，卡片剩余次数同步减少。
+- 后台取消后刷新页面显示 `cancelled`。
+- 前端不提供次卡预约取消按钮。
+
+### 16.4 储值卡
+
+- 商城正确区分售价和到账面值。
+- 创建储值卡订单后支付页只允许微信支付。
+- 支付成功后余额增加 `face_value`，而不是 `price`。
+- 余额流水出现“充值”记录。
+- 关闭未支付订单不会改变余额。
+
+### 16.5 个人中心和消费记录
+
+- 个人中心展示后端最新余额。
+- 可以进入充值、我的次卡、余额流水和消费记录。
+- 订单列表正确显示“会员卡”和“储值卡”业务类型。
+- 余额流水与订单消费记录分开呈现。
+
+### 16.6 回归
+
+- 包场预约流程不受影响。
+- 门票购买、持有和核销展示不受影响。
+- 已有订单详情、关闭订单、余额支付和微信支付流程不受影响。
+- 冰场馆模块的页面、接口、token 和状态不受影响。
+
+## 17. 实施顺序
+
+1. 修改排课 API、首页字段和普通预约映射，恢复现有课程链路。
+2. 新增次卡 API 模块、商城套餐购买和我的次卡。
+3. 新增次卡可约排课、创建预约、预约列表和详情。
+4. 新增储值卡 API、商城展示和购买流程。
+5. 修改支付页，落实储值卡仅微信支付。
+6. 完善个人中心余额、充值、次卡、流水和消费记录入口。
+7. 完成分页、刷新、错误状态和全链路回归验证。
+
+## 18. 后端契约依赖
+
+本设计以当前综合场馆后端实际实现为准，依赖以下既有行为：
+
+- `/api/sessions` 返回会员端排课。
+- 普通预约接收 `session_id`，预约响应嵌套字段名为 `session`。
+- 次卡套餐绑定课程模板，但可约接口返回模板覆盖的具体排课。
+- 次卡预约时占用名额，后台核销时扣减次数。
+- 储值卡订单禁止余额支付，微信支付成功后按面值充值。
+- 余额、余额流水和订单状态均可在支付或后台操作后重新查询。
+
+普通预约和次卡预约的嵌套 `session` 暂无 `courts` 是已知契约限制，本次通过不依赖该字段完成前端对接，不阻塞实施。