openapi: 3.1.0
info:
  title: 蓝牙配网与账号绑定
  version: 1.1.1
  description: 蓝牙只传 Wi-Fi 与一次性绑定令牌，账号身份从登录态获取。实际响应统一使用 ok/code/request_id/server_time_ms/data 信封。
paths:
  /api/v1/web/ble-bind-tokens:
    post:
      summary: 为已登录账号签发5分钟一次性设备绑定令牌
      security:
        - Bearer: []
        - AccountCookie: []
      description: Cookie 请求必须同源并携带 X-CSRF-Token。省略 expected_binding_id 时设备必须未添加；省略 elder_id 时仅添加到账号。更换已绑定设备的使用老人必须同时提交 elder_id 和当前 expected_binding_id，账号需有原家庭及目标家庭设备管理权限。申请不改变原归属，设备实体确认后才原子完成转移；届时再次检查权限、归属版本、通话及升级。仅替换本人对该设备的未完成令牌。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [device_id]
              properties:
                device_id: {type: string, pattern: '^KP01-[0-9A-F]{12}$'}
                elder_id: {type: string, format: uuid, description: 可省略；省略表示先添加到账号，之后在设备管理中绑定老人。不会发送到蓝牙设备}
                expected_binding_id: {type: string, format: uuid, description: 更换使用老人时必填，为 binding-impact 返回的当前绑定 UUID。配网及普通添加不得携带。}
      responses:
        '200': {description: 'data: {bind_token: 43字符Base64URL令牌}'}
        '400': {description: 'DEVICE_ID_INVALID：设备编号格式错误；ELDER_ID_INVALID：老人编号格式错误；PROFILE_REQUIRED：显式选择的使用者不可管理'}
        '403': {description: '按具体原因返回账号、组织、设备状态或归属权限错误；与 mini/ble-device-state 一致，message 为可直接展示的中文原因，不再合并提示'}
        '404': {description: 'DEVICE_NOT_REGISTERED：平台没有该设备的注册记录'}
        '409': {description: 'DEVICE_NOT_RELEASED / DEVICE_ENROLLMENT_UNSUPPORTED / DEVICE_BINDING_STALE / ALREADY_BOUND；message 给出相应处理方式'}
        default: {description: 权限不足、设备已绑定、使用者未选择或服务暂不可用}
  /api/v1/web/ble-bind-status:
    post:
      summary: 由签发账号查询平台绑定结果
      security:
        - Bearer: []
        - AccountCookie: []
      description: 同源和CSRF要求同签发接口。平台成功不代表设备已经保存Wi-Fi；蓝牙断开后可用此接口确认云端结果。
      requestBody:
        $ref: '#/components/requestBodies/Token'
      responses:
        '200': {description: 'data.status 为 pending/success/failed，可附 message'}
        default: {description: 不属于当前账号的令牌不可查询}
  /api/v1/device/ble-bind:
    post:
      summary: 设备绑定并同步取得火山连接配置
      security:
        - DeviceRequest: []
      description: HTTPS，DEVREQ1九行HMAC签名；X-Device-ID、X-Key-Version、X-Timestamp-Ms、X-Nonce、X-Request-ID 必填。每次重试刷新nonce，保留实体确认事件的request ID。已提交令牌的重试返回同一有效绑定；不会抢占已有设备归属。
      requestBody:
        $ref: '#/components/requestBodies/Token'
      responses:
        '200':
          description: data直接带status及5个火山字段，无voice_status/voice。平台取齐才成功，设备保存配置与Wi-Fi后才报告蓝牙success；凭据不转发小程序。设备超时设45秒，平台取参等待上限35秒。
          content:
            application/json:
              schema:
                type: object
                required: [ok, data]
                properties:
                  ok: {const: true}
                  code: {type: string}
                  request_id: {type: string}
                  server_time_ms: {type: integer}
                  data:
                    type: object
                    additionalProperties: false
                    required: [status, instance_id, product_key, device_name, device_secret, RTCAppID]
                    properties:
                      status: {const: success}
                      instance_id: {type: string, minLength: 1}
                      product_key: {type: string, minLength: 1}
                      device_name: {type: string, minLength: 1}
                      device_secret: {type: string, minLength: 16, maxLength: 256}
                      RTCAppID: {type: string, minLength: 1, maxLength: 128}
        '409': {description: 'BINDING_CHANGED：等待期间解绑/归属变化；VOICE_MIGRATION_REQUIRED：需补交旧设备凭据。另有原令牌错误。'}
        '502': {description: 'VOICE_REGISTRATION_FAILED / VOICE_CONFIG_INVALID：未取得完整配置，已完成绑定保留。注册结果不确定由平台核对，不重复注册。'}
        '503': {description: 'VOICE_REGISTRATION_PAUSED：语音暂停，已完成绑定保留；也可能是绑定暂停。'}
        '504': {description: 'VOICE_REGISTRATION_TIMEOUT：取参超时，保留原令牌重试；已完成绑定保留。'}
        default: {description: 令牌无效、过期、归属变化或服务暂不可用；网络超时/5xx不应视为绑定失败}
components:
  securitySchemes:
    Bearer: {type: http, scheme: bearer}
    AccountCookie: {type: apiKey, in: cookie, name: __Host-platform-onboarding}
    DeviceRequest: {type: apiKey, in: header, name: Authorization, description: 'Device-HMAC-SHA256 后接64字符小写十六进制MAC'}
  requestBodies:
    Token:
      required: true
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required: [bind_token]
            properties:
              bind_token: {type: string, pattern: '^[A-Za-z0-9_-]{43}$'}