模块说明
book 提供预约体系：预约项目浏览（列表/分类/详情）、排班里链路（排班日期 → 时段选择 → 联系信息 → 提交预约）、会员预约管理（我的预约/详情/取消）、工作端核销（确认/拒绝/完成/签到）。
鉴权级别：列表/详情/排班查询公开（schedule、time 支持可选登录以展示个性化时段）；联系信息页与提交预约必须登录；会员管理必须登录；工作端必须员工身份。
接口一览
前台
| 方法 |
URL |
鉴权 |
说明 |
| GET |
/api/book |
公开 |
预约项目列表 |
| GET |
/api/book/{id} |
公开 |
预约项目详情 |
| GET |
/api/book/class |
公开 |
预约分类列表 |
| GET |
/api/book/schedule |
可选 |
排班日期列表 |
| GET |
/api/book/date |
公开 |
日期可选项 |
| GET |
/api/book/time |
可选 |
时段列表 |
| GET |
/api/book/contact |
必须 |
联系信息页数据 |
| POST |
/api/book/booking |
必须 |
提交预约 |
会员
| 方法 |
URL |
鉴权 |
说明 |
| GET |
/api/user/book |
必须 |
我的预约列表 |
| GET |
/api/user/book/{id} |
必须 |
预约详情 |
| POST |
/api/user/book/cancel |
必须 |
取消预约 |
工作端（work_required）
| 方法 |
URL |
鉴权 |
说明 |
| GET |
/api/book/work |
员工 |
工作端预约列表（多条件筛选） |
| GET |
/api/book/work/{id} |
员工 |
工作端预约详情 |
| POST |
/api/book/work/confirm |
员工 |
确认预约 |
| POST |
/api/book/work/reject |
员工 |
拒绝预约（可附原因） |
| POST |
/api/book/work/complete |
员工 |
完成预约 |
| POST |
/api/book/work/checkin |
员工 |
核销签到 |
预约列表与详情
列表 GET /api/book
| 参数 |
必填 |
说明 |
class_id |
否 |
分类 ID 筛选 |
page |
否 |
页码，默认 1 |
每页数量取站点配置 pagination.book（默认 10）。
{
"code": "OK",
"message": "",
"data": {
"title": "预约项目",
"class_exist": true,
"item_list": [ { "id": 1, "name": "...", "price": "...", "...": "" } ],
"pager": { "...": "分页信息" }
},
"errors": {},
"request_id": "9f2a5c8e1b3d7f40"
}
详情 GET /api/book/{id}
{
"code": "OK",
"message": "",
"data": {
"title": "项目名称",
"item": { "id": 1, "name": "...", "content": "<p>…</p>", "...": "" }
},
"errors": {},
"request_id": "9f2a5c8e1b3d7f40"
}
| 场景 |
响应 |
| 项目不存在 |
422 INVALID_PARAMS（illegal） |
分类 GET /api/book/class
返回 title + class_list（一维分类列表）。
排班里链路
排班日期 GET /api/book/schedule
| 参数 |
必填 |
说明 |
class_id |
是 |
分类 ID（缺失 → 422 INVALID_PARAMS） |
date |
否 |
指定日期（YYYY-MM-DD）；非法格式视为空 |
返回排班日期数据（buildScheduleJsonPayload，含可选日期与余量信息，以实际返回为准）。支持登录态传入（个性化展示）。
日期 GET /api/book/date
参数 id（项目 ID）、current_date；返回日期选择数据。公开。
时段 GET /api/book/time
| 参数 |
必填 |
说明 |
id |
是 |
项目 ID |
date |
是 |
预约日期（YYYY-MM-DD） |
current_time |
否 |
当前选中时段回显 |
返回时段列表数据（含可预约状态）。支持登录态传入。
联系信息页 GET /api/book/contact
| 参数 |
必填 |
说明 |
id |
是 |
项目 ID |
date |
是 |
预约日期 |
start_time |
是 |
开始时间（如 10:00） |
{
"code": "OK",
"message": "",
"data": {
"item": { "...": "预约项目信息" },
"date": "2026-01-02",
"start_time": "10:00",
"end_time": "11:00",
"price": "...",
"custom_fields": [ { "...": "自定义表单字段（站点配置）" } ]
},
"errors": {},
"request_id": "9f2a5c8e1b3d7f40"
}
| 场景 |
响应 |
| 缺少日期/时间 |
422 INVALID_PARAMS（book_time_empty） |
| 时段不可预约 |
422 BUSINESS_RULE_VIOLATION（book_time_wrong） |
| 会员被列入黑名单 |
403 FORBIDDEN（book_blacklisted） |
提交预约 POST /api/book/booking
| 参数 |
必填 |
说明 |
id |
是 |
项目 ID |
date |
是 |
预约日期（YYYY-MM-DD） |
start_time |
是 |
开始时间 |
contact_id |
否 |
联系信息 ID |
people_count |
否 |
人数，默认 1 |
remark |
否 |
备注 |
custom |
否 |
自定义字段（数组，或 JSON 字符串——小程序表单嵌套对象的兼容形态） |
{
"code": "OK",
"message": "预约成功",
"data": { "book_sn": "B202601020001" },
"errors": {},
"request_id": "9f2a5c8e1b3d7f40"
}
| 场景 |
响应 |
| 提交失败（时段冲突/库存不足等） |
422 BUSINESS_RULE_VIOLATION（具体原因） |
会员预约管理
- 列表
GET /api/user/book：参数 page；返回 book_list（已剔除小程序专用 view_url 字段）与 pager；
- 详情
GET /api/user/book/{id}：返回 book（含 book_tips 站点提示）；不存在或非本人均 403 FORBIDDEN；
- 取消
POST /api/user/book/cancel：参数 id、reason（可选原因）；不可取消（过了可取消时限等）→ 422 BUSINESS_RULE_VIOLATION；成功 message=取消成功。
工作端接口
工作端全部要求员工对 book 的权限（未登录 401 / 非员工 403）。
- 列表
GET /api/book/work：筛选参数 keyword（关键词）、item_id、status、date_start、date_end、page；返回 book_list、pager、item_list（项目筛选选项）、status_list（状态选项）、user_id；
- 详情
GET /api/book/work/{id}：不存在 422 INVALID_PARAMS；返回 book（含 book_tips）；
- 确认/拒绝/完成/签到：均为
POST，参数 id（拒绝另支持 reason）；状态不符等失败 → 422 BUSINESS_RULE_VIOLATION；成功返回操作成功文案。
注意事项
- 里链路时序：
schedule（选日期）→ time（选时段）→ contact（联系信息页，需登录）→ booking（提交）；date 为日期选择的辅助接口；
custom 字段同时兼容数组与 JSON 字符串两种形态（小程序 wx.request 表单兼容行为）；- 会员详情与工作端详情对"不存在"的响应不同（403 vs 422），客户端需注意区分；
book_sn 为预约单号，用于后续查询与核销。