预约与管理
预约接口支持用户在线预约健康站检测时段，支持权益卡核销， 并通过预约号生成到站码。
预约流程
- 调用「可预约日期」接口获取近 30 天可用日期列表
- 用户选择日期后，调用「可预约时段」接口获取当日时段及剩余名额
- 用户确认时段后，调用「创建预约」接口，返回预约号和到站码
- 用户到站后，在 App 内展示到站码，由健康站设备扫码核验
查询可预约日期
GET/api/v1/stations/{pointsCode}/available-dates
返回指定健康站未来 30 天内有可用时段的日期数组（YYYY-MM-DD 格式）。
响应示例：
{
"success": true,
"code": 0,
"data": ["2026-04-02", "2026-04-03", "2026-04-05", "2026-04-07"]
}查询可预约时段
GET/api/v1/stations/{pointsCode}/available-time-slots
查询参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
date | string | 是 | 日期，格式 YYYY-MM-DD |
响应示例：
{
"success": true,
"code": 0,
"data": [
{ "slot": "09:00-09:30", "remaining": 3, "available": true },
{ "slot": "09:30-10:00", "remaining": 0, "available": false },
{ "slot": "10:00-10:30", "remaining": 5, "available": true }
]
}创建预约
POST/api/v1/benefit-appointments
请求体（application/json）：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
points_code | string | 是 | 健康站编码 |
appointment_date | string | 是 | 预约日期，格式 YYYY-MM-DD |
time_slot | string | 是 | 时段，如 "10:00-10:30"（须为当日可用时段） |
family_member_id | integer | 是 | 为哪位家庭成员预约（家庭成员 ID） |
benefit_card_id | integer | 否 | 使用权益卡核销，传权益卡 ID |
remark | string | 否 | 备注信息，最长 200 字符 |
成功响应（201 Created）：
{
"success": true,
"code": 0,
"message": "预约成功",
"data": {
"id": 50001,
"appointment_no": "APT202604010001",
"status": "confirmed",
"checkin_code": "XB123456", // 到站核验码（6位）
"checkin_expires_at": "2026-04-02T18:00:00+08:00"
}
}checkin_code 在预约日当天有效。到站时在 App 内动态生成（含防截图机制）， 不建议缓存。预约列表
GET/api/v1/benefit-appointments
查询参数（均为可选）：
| 参数 | 类型 | 说明 |
|---|---|---|
status | string | 按状态过滤：confirmed / completed / cancelled |
page | integer | 页码，默认 1 |
预约详情
GET/api/v1/benefit-appointments/{id}
返回预约完整信息，包含健康站信息、预约时段、核验码、当前状态。
取消预约
POST/api/v1/benefit-appointments/{id}/cancel
取消指定预约。状态为 confirmed 的预约可取消，completed 或 cancelled 状态的预约不可操作（返回 422）。
如使用权益卡预约，取消后权益次数自动退回。
预约状态说明
| 状态值 | 含义 |
|---|---|
confirmed | 预约已确认，等待到站 |
checked_in | 已到站核验，检测进行中 |
completed | 检测完成，报告已生成 |
cancelled | 已取消（用户主动或过期自动取消） |
no_show | 预约日期已过，用户未到站 |