客户端接入

客户端接口面向普通用户（通过 JWT 鉴权），涵盖权益卡激活、权益项查询、 预约管理、评价等完整使用链路。Base URL 前缀为 /api/v1/。

概述

检测已绑定卡片

用于用户首次进入权益卡页面时，检测是否有由合作方预先绑定但尚未激活的卡片。 存在时提示用户快速激活。

成功响应：

{
  "success": true,
  "data": {
    "has_bound_card": true,
    "card": {
      "card_number": "XB12 **** **** 3456",  // 脱敏展示
      "card_name": "健康权益卡·铂金版",
      "card_level": "PLATINUM",
      "issuer_name": "晓葆健康",
      "bound_at": "2026-03-01 10:00:00"
    }
  }
}

当 has_bound_card 为 false 时，引导用户手动输入卡号激活。

激活权益卡

手动激活流程分两步：先调用 /validate 预览卡片信息，用户二次确认后再调用 /activate 正式激活。

步骤 1：验证卡号（不执行激活）

步骤 2：正式激活

请求体（两个接口相同）：

激活成功响应（200 OK）：

{
  "success": true,
  "data": {
    "user_benefit_card_id": 1001,
    "card_number": "XB12 **** **** 3456",
    "card_name": "健康权益卡·铂金版",
    "card_level": "PLATINUM",
    "status": "ACTIVE",
    "activated_at": "2026-04-01 10:00:00",
    "expires_at": "2027-04-01 23:59:59",
    "benefit_items": [
      {
        "user_benefit_item_id": 191,
        "benefit_code": "LIGHT_PHYSICAL_EXAM",
        "benefit_name": "轻体检服务",
        "total_quantity": 12,
        "remaining_quantity": 12,
        "quantity_unit": "TIMES"
      }
    ]
  }
}

快速激活已绑定卡片（合作方预绑定场景）：

请求体只需 card_number（无需激活码），响应结构同上。

查询权益卡列表

成功响应：

{
  "success": true,
  "data": {
    "total_count": 2,
    "valid_count": 1,
    "cards": [
      {
        "user_benefit_card_id": 1001,
        "card_name": "健康权益卡·铂金版",
        "card_level": "PLATINUM",
        "status": "ACTIVE",
        "expires_at": "2027-04-01 23:59:59",
        "benefit_items_count": 3
      }
    ]
  }
}

权益卡详情

返回权益卡完整详情，包含每个权益项的剩余次数、使用记录统计、过期时间等。

查询权益项详情

权益项是权益卡内的具体服务单元（如「轻体检 × 12 次」），包含剩余次数和可用性判断。

路径参数：id 为 user_benefit_item_id（非权益项模板 ID）。

成功响应：

{
  "success": true,
  "data": {
    "user_benefit_item_id": 191,
    "benefit_item_id": 27,
    "benefit_item_code": "LIGHT_PHYSICAL_EXAM",
    "remaining_quantity": 12,
    "used_quantity": 0,
    "quantity_unit": "TIMES",
    "status": "ACTIVE",
    "benefit_item": {
      "benefit_name": "轻体检服务",
      "benefit_description": "支持全国 5000+ 健康站",
      "benefit_icon": "heart-pulse-line",
      "fulfillment_method": "APPOINTMENT"
    },
    "is_available": true,
    "unavailable_reason": null
  }
}

is_available 为 false 时，unavailable_reason会说明原因（如「等待期未满」「已过期」「次数已用完」）。

预约接口

对于 fulfillment_method = APPOINTMENT 或 FORM_BOOKING 的权益项， 用户需先创建预约，服务方根据预约记录安排服务。

查询可预约时段：

创建预约：

成功响应（201 Created）：

{
  "success": true,
  "data": {
    "appointment_id": 50001,
    "status": "SCHEDULED",
    "appointment_time": "2026-04-10T10:00:00+08:00",
    "appointment_type": "HEALTH_STATION",
    "health_station_name": "晓葆健康站（朝阳门店）",
    "family_member_name": "张三",
    "created_at": "2026-04-01 10:00:00"
  }
}

取消预约

请求体（可选）：

已完成（COMPLETED）的预约不可取消，返回 422。

评价服务

服务完成后（履约状态为 COMPLETED），用户可对本次服务进行评价。 评价后不可修改。

路径参数：id 为 fulfillment_record_id（履约记录 ID，可从预约详情中获取）。

成功响应：

{
  "success": true,
  "data": {
    "fulfillment_record_id": 1001,
    "rating": 5,
    "rating_comment": "服务很好，医生专业",
    "rating_at": "2026-04-01 12:00:00"
  }
}