Codex Local
bf1233d5df
ci / verify (push) Canceled after 0s
Add customer and operator login, BLE provisioning, device fleet controls, call memory, memoir generation, and refreshed family and maintenance portals. Include API contracts, migrations, firmware sources, tests, assets, and deployment documentation.
98 lines
6.0 KiB
YAML
98 lines
6.0 KiB
YAML
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}$'}
|