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

综合场馆新增业务前端对接设计

日期：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. 工程边界

综合场馆模块继续使用以下分层：

src/pages/comprehensive/             页面与交互
src/modules/comprehensive/api/       接口请求与响应映射
src/modules/comprehensive/stores/    登录会员状态
src/modules/comprehensive/utils/     日期、金额和状态工具

新增 API 模块：

src/modules/comprehensive/api/membership.js
src/modules/comprehensive/api/storedValue.js

新增页面：

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。

统一排课视图模型：

{
  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

普通预约视图模型：

{
  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 }

套餐视图模型包含：

{
  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

用户次卡视图模型：

{
  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：

{
  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。

次卡预约视图模型：

{
  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 }

储值卡视图模型：

{
  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 普通课程预约

排课列表或首页
  → 排课详情（session.id）
  → 确认预约
  → POST /bookings/course { session_id }
  → 取得 order.id
  → 订单支付页
  → 余额支付或微信支付
  → 普通预约详情

8.2 次卡购买

商城选择次卡套餐
  → POST /membership/orders { plan_id }
  → 取得 order.id
  → 订单支付页
  → 余额支付或微信支付
  → 刷新 /membership/cards
  → 我的次卡

8.3 次卡预约

我的次卡详情或课程入口
  → 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 储值卡购买

商城选择储值卡
  → 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 是已知契约限制，本次通过不依赖该字段完成前端对接，不阻塞实施。