story/openapi/onboarding.yaml

openapi: 3.1.0
info:
  title: SaaS 首次认证、绑定和激活接口
  version: 0.78.0
  description: ONBOARDING-1.1。仅用于生产登记为physical_confirm的设备；旧设备维持原协议。详细规则见docs/onboarding-implementation.md。
paths:
  /api/v1/device/time-challenges:
    post:
      operationId: onboardingC01POSTapiv1devicetimechallenges
      summary: C01 校时挑战
      tags:
        - Onboarding
      description: 专用HTTP或HTTPS校时；无需时间戳及请求签名；成功直接返回payload_b64和mac_hex，设备必须核验TIME1。
      security: []
      parameters:
        - in: header
          name: X-Request-ID
          required: false
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeChallengeResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeChallengeInput'
  /api/v1/device/register:
    post:
      operationId: onboardingC02POSTapiv1deviceregister
      summary: C02 首次认证和启动注册
      tags:
        - Onboarding
      description: HTTPS，无query参数；正文不超过8KiB。随机nonce每次发送更新，X-Request-ID在重试时保持。
      security:
        - DeviceRequest: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Device-ID
          required: true
          schema:
            type: string
          description: X-Device-ID
        - in: header
          name: X-Key-Version
          required: true
          schema:
            type: string
          description: X-Key-Version
        - in: header
          name: X-Timestamp-Ms
          required: true
          schema:
            type: string
          description: X-Timestamp-Ms
        - in: header
          name: X-Nonce
          required: true
          schema:
            type: string
          description: X-Nonce
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterInput'
  /api/v1/device/setup-sessions:
    post:
      operationId: onboardingC03POSTapiv1devicesetupsessions
      summary: C03 创建临时设置会话
      tags:
        - Onboarding
      description: HTTPS，无query参数；正文不超过8KiB。随机nonce每次发送更新，X-Request-ID在重试时保持。
      security:
        - DeviceRequest: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Device-ID
          required: true
          schema:
            type: string
          description: X-Device-ID
        - in: header
          name: X-Key-Version
          required: true
          schema:
            type: string
          description: X-Key-Version
        - in: header
          name: X-Timestamp-Ms
          required: true
          schema:
            type: string
          description: X-Timestamp-Ms
        - in: header
          name: X-Nonce
          required: true
          schema:
            type: string
          description: X-Nonce
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetupInput'
  /api/v1/device/handoffs:
    post:
      operationId: onboardingC04POSTapiv1devicehandoffs
      summary: C04 获取一次性手机入口
      tags:
        - Onboarding
      description: HTTPS，无query参数；正文不超过8KiB。随机nonce每次发送更新，X-Request-ID在重试时保持。
      security:
        - DeviceRequest: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Device-ID
          required: true
          schema:
            type: string
          description: X-Device-ID
        - in: header
          name: X-Key-Version
          required: true
          schema:
            type: string
          description: X-Key-Version
        - in: header
          name: X-Timestamp-Ms
          required: true
          schema:
            type: string
          description: X-Timestamp-Ms
        - in: header
          name: X-Nonce
          required: true
          schema:
            type: string
          description: X-Nonce
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandoffResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HandoffInput'
  /api/v1/device/poll:
    post:
      operationId: onboardingC05POSTapiv1devicepoll
      summary: C05 查询状态和命令
      tags:
        - Onboarding
      description: HTTPS，无query参数；正文不超过8KiB。随机nonce每次发送更新，X-Request-ID在重试时保持。
      security:
        - DeviceRequest: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Device-ID
          required: true
          schema:
            type: string
          description: X-Device-ID
        - in: header
          name: X-Key-Version
          required: true
          schema:
            type: string
          description: X-Key-Version
        - in: header
          name: X-Timestamp-Ms
          required: true
          schema:
            type: string
          description: X-Timestamp-Ms
        - in: header
          name: X-Nonce
          required: true
          schema:
            type: string
          description: X-Nonce
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PollInput'
  /api/v1/device/claim-confirmations:
    post:
      operationId: onboardingC06POSTapiv1deviceclaimconfirmations
      summary: C06 物理按键确认绑定
      tags:
        - Onboarding
      description: HTTPS，无query参数；正文不超过8KiB。随机nonce每次发送更新，X-Request-ID在重试时保持。
      security:
        - DeviceRequest: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Device-ID
          required: true
          schema:
            type: string
          description: X-Device-ID
        - in: header
          name: X-Key-Version
          required: true
          schema:
            type: string
          description: X-Key-Version
        - in: header
          name: X-Timestamp-Ms
          required: true
          schema:
            type: string
          description: X-Timestamp-Ms
        - in: header
          name: X-Nonce
          required: true
          schema:
            type: string
          description: X-Nonce
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmationResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmationInput'
  /api/v1/device/state-acks:
    post:
      operationId: onboardingC07POSTapiv1devicestateacks
      summary: C07 绑定状态持久化回执
      tags:
        - Onboarding
      description: HTTPS，无query参数；正文不超过8KiB。随机nonce每次发送更新，X-Request-ID在重试时保持。
      security:
        - DeviceRequest: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Device-ID
          required: true
          schema:
            type: string
          description: X-Device-ID
        - in: header
          name: X-Key-Version
          required: true
          schema:
            type: string
          description: X-Key-Version
        - in: header
          name: X-Timestamp-Ms
          required: true
          schema:
            type: string
          description: X-Timestamp-Ms
        - in: header
          name: X-Nonce
          required: true
          schema:
            type: string
          description: X-Nonce
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateAckResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StateAckInput'
  /api/v1/device/activation-attempts:
    post:
      operationId: onboardingC08POSTapiv1deviceactivationattempts
      summary: C08 申请设备执行许可
      tags:
        - Onboarding
      description: HTTPS，无query参数；正文不超过8KiB。随机nonce每次发送更新，X-Request-ID在重试时保持。
      security:
        - DeviceRequest: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Device-ID
          required: true
          schema:
            type: string
          description: X-Device-ID
        - in: header
          name: X-Key-Version
          required: true
          schema:
            type: string
          description: X-Key-Version
        - in: header
          name: X-Timestamp-Ms
          required: true
          schema:
            type: string
          description: X-Timestamp-Ms
        - in: header
          name: X-Nonce
          required: true
          schema:
            type: string
          description: X-Nonce
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttemptResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttemptInput'
  /api/v1/device/activation-results:
    post:
      operationId: onboardingC09POSTapiv1deviceactivationresults
      summary: C09 回报设备执行结果
      tags:
        - Onboarding
      description: HTTPS，无query参数；正文不超过8KiB。随机nonce每次发送更新，X-Request-ID在重试时保持。
      security:
        - DeviceRequest: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Device-ID
          required: true
          schema:
            type: string
          description: X-Device-ID
        - in: header
          name: X-Key-Version
          required: true
          schema:
            type: string
          description: X-Key-Version
        - in: header
          name: X-Timestamp-Ms
          required: true
          schema:
            type: string
          description: X-Timestamp-Ms
        - in: header
          name: X-Nonce
          required: true
          schema:
            type: string
          description: X-Nonce
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResultInput'
  /api/v1/device/activation-acks:
    post:
      operationId: onboardingC10POSTapiv1deviceactivationacks
      summary: C10 激活结果保存回执
      tags:
        - Onboarding
      description: HTTPS，无query参数；正文不超过8KiB。随机nonce每次发送更新，X-Request-ID在重试时保持。
      security:
        - DeviceRequest: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Device-ID
          required: true
          schema:
            type: string
          description: X-Device-ID
        - in: header
          name: X-Key-Version
          required: true
          schema:
            type: string
          description: X-Key-Version
        - in: header
          name: X-Timestamp-Ms
          required: true
          schema:
            type: string
          description: X-Timestamp-Ms
        - in: header
          name: X-Nonce
          required: true
          schema:
            type: string
          description: X-Nonce
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivationAckResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivationAckInput'
  /api/v1/device/setup-close:
    post:
      operationId: onboardingC11POSTapiv1devicesetupclose
      summary: C11 关闭临时设置入口
      tags:
        - Onboarding
      description: HTTPS，无query参数；正文不超过8KiB。随机nonce每次发送更新，X-Request-ID在重试时保持。
      security:
        - DeviceRequest: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Device-ID
          required: true
          schema:
            type: string
          description: X-Device-ID
        - in: header
          name: X-Key-Version
          required: true
          schema:
            type: string
          description: X-Key-Version
        - in: header
          name: X-Timestamp-Ms
          required: true
          schema:
            type: string
          description: X-Timestamp-Ms
        - in: header
          name: X-Nonce
          required: true
          schema:
            type: string
          description: X-Nonce
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloseResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloseInput'
  /api/v1/web/handoffs/exchange:
    post:
      operationId: onboardingPOSTapiv1webhandoffsexchange
      summary: 手机兑换一次性入口
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: Origin
          required: true
          schema:
            type: string
          description: 必须与ONBOARDING_ENTRY_URL同源
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeInput'
  /api/v1/web/setup/session:
    get:
      operationId: onboardingGETapiv1websetupsession
      summary: 恢复手机设置会话
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - SetupCookie: []
      parameters:
        - in: header
          name: X-Request-ID
          required: false
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
  /api/v1/web/setup/auth-link:
    post:
      operationId: onboardingOIDCPOSTapiv1websetupauthlink
      summary: 关联已登录账号
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，必须提供设置会话 Cookie 和对应 CSRF；身份可来自 OIDC Bearer 或已登录账号 Cookie。
      security:
        - SetupCookie: []
          Bearer: []
        - SetupCookie: []
          AccountCookie: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
          description: X-CSRF-Token
        - in: header
          name: Origin
          required: true
          schema:
            type: string
          description: 必须与ONBOARDING_ENTRY_URL同源
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Empty'
  /api/v1/web/auth/captcha:
    post:
      operationId: onboardingSetupCaptcha
      summary: 获取或刷新设备绑定登录的图片验证码
      description: HTTPS、同源和 CSRF 校验；绑定当前设备设置会话，2 分钟有效，刷新和验证均使旧图失效。
      security: [{ SetupCookie: [] }]
      parameters:
        - { in: header, name: X-Request-ID, required: true, schema: { type: string, format: uuid } }
        - { in: header, name: X-CSRF-Token, required: true, schema: { type: string } }
        - { in: header, name: Origin, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, additionalProperties: false }
      responses:
        '200':
          description: PNG 图片、captcha_id 和 expires_at_ms，不返回答案
          content:
            application/json:
              schema:
                type: object
                required: [ok, data]
                properties:
                  ok: { type: boolean }
                  data:
                    type: object
                    required: [captcha_id, mode, expires_at_ms]
                    properties:
                      captcha_id: { type: string, format: uuid }
                      mode: { type: string, enum: [image, tencent, slide] }
                      captcha_app_id: { type: string, description: 腾讯云 Web 验证码公开 ID }
                      image: { type: string }
                      thumb_image: { type: string, pattern: '^data:image/png;base64,' }
                      image_width: { type: integer, minimum: 1 }
                      image_height: { type: integer, minimum: 1 }
                      thumb_width: { type: integer, minimum: 1 }
                      thumb_height: { type: integer, minimum: 1 }
                      thumb_x: { type: integer, minimum: 0, description: 拼图块的初始展示横坐标 }
                      thumb_y: { type: integer, minimum: 0, description: 拼图块所在水平轨道 }
                      expires_at_ms: { type: integer, format: int64 }
        default: { description: 校验失败或会话过期 }
  /api/v1/web/auth/captcha/verify:
    post:
      operationId: onboardingVerifyLocalSlideCaptcha
      summary: 校验设备设置会话的本地滑块位置
      description: HTTPS、同源、CSRF 和设备设置会话校验；每次提交即消费挑战。成功票据只对当前设置会话、客户端和策略版本有效，不能超过原 2 分钟期限。
      security: [{ SetupCookie: [] }]
      parameters:
        - { in: header, name: X-Request-ID, required: true, schema: { type: string, format: uuid } }
        - { in: header, name: X-CSRF-Token, required: true, schema: { type: string } }
        - { in: header, name: Origin, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './login-captcha.yaml#/components/schemas/SlideCaptchaVerifyInput' }
      responses:
        '200':
          description: 一次性位置校验票据
          content:
            application/json:
              schema: { $ref: './login-captcha.yaml#/components/schemas/SlideCaptchaVerifyResponse' }
        default: { description: 校验失败或会话过期 }
  /api/v1/web/auth/sms/send:
    post:
      operationId: onboardingPOSTapiv1webauthsmssend
      summary: 发送登录短信
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - SetupCookie: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
          description: X-CSRF-Token
        - in: header
          name: Origin
          required: true
          schema:
            type: string
          description: 必须与ONBOARDING_ENTRY_URL同源
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMSResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SMSSendInput'
  /api/v1/web/auth/sms/verify:
    post:
      operationId: onboardingPOSTapiv1webauthsmsverify
      summary: 验证短信并登录
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - SetupCookie: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
          description: X-CSRF-Token
        - in: header
          name: Origin
          required: true
          schema:
            type: string
          description: 必须与ONBOARDING_ENTRY_URL同源
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SMSVerifyInput'
  /api/v1/web/profiles:
    post:
      operationId: onboardingPOSTapiv1webprofiles
      summary: 查询可选择的家庭使用者
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - SetupCookie: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
          description: X-CSRF-Token
        - in: header
          name: Origin
          required: true
          schema:
            type: string
          description: 必须与ONBOARDING_ENTRY_URL同源
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfilesResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Empty'
  /api/v1/web/profiles/create:
    post:
      operationId: onboardingPOSTapiv1webprofilescreate
      summary: 创建家庭或使用者
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - SetupCookie: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
          description: X-CSRF-Token
        - in: header
          name: Origin
          required: true
          schema:
            type: string
          description: 必须与ONBOARDING_ENTRY_URL同源
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileInput'
  /api/v1/web/claims:
    post:
      operationId: onboardingPOSTapiv1webclaims
      summary: 提交绑定申请
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - SetupCookie: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
          description: X-CSRF-Token
        - in: header
          name: Origin
          required: true
          schema:
            type: string
          description: 必须与ONBOARDING_ENTRY_URL同源
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimInput'
  /api/v1/web/claims/cancel:
    post:
      operationId: onboardingPOSTapiv1webclaimscancel
      summary: 取消自己的绑定申请
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - SetupCookie: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
          description: X-CSRF-Token
        - in: header
          name: Origin
          required: true
          schema:
            type: string
          description: 必须与ONBOARDING_ENTRY_URL同源
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateOnlyResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelInput'
  /api/v1/web/setup/status:
    post:
      operationId: onboardingPOSTapiv1websetupstatus
      summary: 查询手机绑定进度
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - SetupCookie: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
          description: X-CSRF-Token
        - in: header
          name: Origin
          required: true
          schema:
            type: string
          description: 必须与ONBOARDING_ENTRY_URL同源
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebStatusResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Empty'
  /api/v1/web/setup/ack:
    post:
      operationId: onboardingPOSTapiv1websetupack
      summary: 网页确认收到绑定结果
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - SetupCookie: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
          description: X-CSRF-Token
        - in: header
          name: Origin
          required: true
          schema:
            type: string
          description: 必须与ONBOARDING_ENTRY_URL同源
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AckResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebAckInput'
  /api/v1/web/onboarding/devices:
    get:
      operationId: onboardingGETapiv1webonboardingdevices
      summary: 设置结束后查询我的设备
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - AccountCookie: []
        - Bearer: []
      parameters:
        - in: header
          name: X-Request-ID
          required: false
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicesResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
  /api/v1/web/account/session:
    get:
      operationId: onboardingCSRFGETapiv1webaccountsession
      summary: 恢复账号会话及CSRF
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - AccountCookie: []
        - Bearer: []
      parameters:
        - in: header
          name: X-Request-ID
          required: false
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
  /api/v1/web/auth/logout:
    post:
      operationId: onboardingPOSTapiv1webauthlogout
      summary: 退出本浏览器登录
      tags:
        - Onboarding
      description: HTTPS，同源浏览器，Cookie不可读，CSRF仅保存在当前标签页。
      security:
        - AccountCookie: []
        - Bearer: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-CSRF-Token
          required: true
          schema:
            type: string
          description: X-CSRF-Token
        - in: header
          name: Origin
          required: true
          schema:
            type: string
          description: 必须与ONBOARDING_ENTRY_URL同源
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogoutResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Empty'
  /api/v1/ops/device-inventory:
    get:
      operationId: onboardingGETapiv1opsdeviceinventory
      summary: 查询生产设备和激活状态
      tags:
        - Onboarding
      description: 必须使用运维OIDC身份。对账仅ops_admin；其它写操作ops_admin或ops_operator。
      security:
        - Bearer: []
      parameters:
        - in: header
          name: X-Request-ID
          required: false
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Tenant-ID
          required: true
          schema:
            type: string
          description: 租户公开UUID；服务端核验运维角色
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicesResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
    post:
      operationId: onboardingPOSTapiv1opsdeviceinventory
      summary: 创建设备并直接进入等待绑定
      tags:
        - Onboarding
      description: 必须使用运维OIDC身份。对账仅ops_admin；其它写操作ops_admin或ops_operator。
      security:
        - Bearer: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: header
          name: X-Tenant-ID
          required: true
          schema:
            type: string
          description: 租户公开UUID；服务端核验运维角色
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            type: string
          description: 16至160字符，重试保持相同值
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryInput'
  /api/v1/ops/device-inventory/{id}/credential-deliveries:
    post:
      operationId: onboardingPOSTapiv1opsdeviceinventoryidcredentialdeliveries
      summary: 向工装交付加密密钥
      tags:
        - Onboarding
      description: 必须使用运维OIDC身份。对账仅ops_admin；其它写操作ops_admin或ops_operator。
      security:
        - Bearer: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: 平台设备公开UUID
        - in: header
          name: X-Tenant-ID
          required: true
          schema:
            type: string
          description: 租户公开UUID；服务端核验运维角色
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliveryInput'
  /api/v1/ops/device-inventory/{id}/release:
    post:
      operationId: onboardingPOSTapiv1opsdeviceinventoryidrelease
      summary: 确认烧录读回并放行
      tags:
        - Onboarding
      description: 必须使用运维OIDC身份。对账仅ops_admin；其它写操作ops_admin或ops_operator。
      security:
        - Bearer: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: 平台设备公开UUID
        - in: header
          name: X-Tenant-ID
          required: true
          schema:
            type: string
          description: 租户公开UUID；服务端核验运维角色
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReleaseInput'
  /api/v1/ops/device-inventory/{id}/credential-rotations:
    post:
      operationId: onboardingPOSTapiv1opsdeviceinventoryidcredentialrotations
      summary: 准备轮换凭据
      tags:
        - Onboarding
      description: 必须使用运维OIDC身份。对账仅ops_admin；其它写操作ops_admin或ops_operator。
      security:
        - Bearer: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: 平台设备公开UUID
        - in: header
          name: X-Tenant-ID
          required: true
          schema:
            type: string
          description: 租户公开UUID；服务端核验运维角色
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            type: string
          description: 16至160字符，重试保持相同值
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RotationInput'
  /api/v1/ops/onboarding-activations/{id}/reconcile:
    post:
      operationId: onboardingPOSTapiv1opsonboardingactivationsidreconcile
      summary: 人工记录激活对账结论
      tags:
        - Onboarding
      description: 必须使用运维OIDC身份。对账仅ops_admin；其它写操作ops_admin或ops_operator。
      security:
        - Bearer: []
      parameters:
        - in: header
          name: X-Request-ID
          required: true
          schema:
            type: string
          description: UUID v4；业务重试保持相同值和原始正文
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: 激活任务UUID
        - in: header
          name: X-Tenant-ID
          required: true
          schema:
            type: string
          description: 租户公开UUID；服务端核验运维角色
      responses:
        '200':
          description: 成功；业务状态请读取data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateOnlyResponse'
        default:
          description: 失败；400/401/403/409/410/413/415/429/500/503，见code恢复；禁止根据超时推断供应商没有执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReconcileInput'
components:
  securitySchemes:
    DeviceRequest:
      type: apiKey
      in: header
      name: Authorization
      description: Device-HMAC-SHA256小写十六进制签名；DEVREQ1九行规范；其余必填签名头见操作参数
    Bearer:
      type: http
      scheme: bearer
    SetupCookie:
      type: apiKey
      in: cookie
      name: __Host-onboarding
    AccountCookie:
      type: apiKey
      in: cookie
      name: __Host-platform-onboarding
  schemas:
    TimeChallengeInput:
      type: object
      additionalProperties: false
      properties:
        device_id:
          type: string
          description: 生产编号，KP01-加12位大写MAC；不是平台UUID
          pattern: ^KP01-[0-9A-F]{12}$
        key_version:
          type: integer
          format: int64
          description: 设备认证密钥版本
        boot_id:
          type: string
          description: 每次启动生成并保持的UUID v4
        client_nonce:
          type: string
          description: 设备生成的16字节随机数，Base64URL无填充
      required:
        - device_id
        - key_version
        - boot_id
        - client_nonce
    ActivationAckInput:
      type: object
      additionalProperties: false
      properties:
        activation_id:
          type: string
          description: 该物理设备唯一的激活任务UUID
        local_generation:
          type: integer
          format: int64
          description: 本次启动的本地持久化序号，不能倒退
        config_version:
          type: integer
          format: int64
          description: 配置版本，必须与当前云端版本一致
      required:
        - activation_id
        - local_generation
        - config_version
    AttemptInput:
      type: object
      additionalProperties: false
      properties:
        activation_id:
          type: string
          description: 该物理设备唯一的激活任务UUID
        config_version:
          type: integer
          format: int64
          description: 配置版本，必须与当前云端版本一致
        attempt_id:
          type: string
          description: 设备生成的UUID v4，表示一次引擎初始化或首通执行
      required:
        - activation_id
        - config_version
        - attempt_id
    ResultInput:
      type: object
      additionalProperties: false
      properties:
        activation_id:
          type: string
          description: 该物理设备唯一的激活任务UUID
        attempt_id:
          type: string
          description: 设备生成的UUID v4，表示一次引擎初始化或首通执行
        stage:
          type: string
          description: SDK_REGISTER或CONVERSATION_TEST；与C08平台当前阶段一致
          enum:
            - SDK_REGISTER
            - CONVERSATION_TEST
        sdk_result:
          type: integer
          format: int64
          description: SDK执行返回码；SUCCESS_OBSERVED时必须为0
        outcome:
          type: string
          description: SUCCESS_OBSERVED、DEFINITE_FAILURE或UNKNOWN；未知结果不得盲目重试
          enum:
            - SUCCESS_OBSERVED
            - DEFINITE_FAILURE
            - UNKNOWN
      required:
        - activation_id
        - attempt_id
        - stage
        - sdk_result
        - outcome
    InventoryInput:
      type: object
      additionalProperties: false
      properties:
        factory_mac:
          type: string
          description: 12位大写十六进制MAC；相同MAC不能创建第二台物理设备
          pattern: ^[0-9A-F]{12}$
        hardware_model:
          type: string
          description: 生产登记型号，当前为KP01
        hardware_revision:
          type: string
          description: 硬件修订号，注册必须与库存一致
        batch_no:
          type: string
          description: 生产批次，方便追溯
      required:
        - factory_mac
        - hardware_model
        - hardware_revision
        - batch_no
    DeliveryInput:
      type: object
      additionalProperties: false
      properties:
        enrollment_job_id:
          type: string
          description: 生产登记或密钥轮换任务UUID
        receiver_public_key_pem:
          type: string
          description: 工装RSA公钥，PKIX PEM，2048至4096位，指数65537
      required:
        - enrollment_job_id
        - receiver_public_key_pem
    ReleaseInput:
      type: object
      additionalProperties: false
      properties:
        enrollment_job_id:
          type: string
          description: 生产登记或密钥轮换任务UUID
        evidence_ref:
          type: string
          description: 烧录读回或人工对账的证据引用，不放密钥
        expected_key_version:
          type: integer
          format: int64
          description: 交付放行目标版本；轮换时为当前生效版本
      required:
        - enrollment_job_id
        - evidence_ref
        - expected_key_version
    RotationInput:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
          description: 关闭、轮换或人工处理原因，见对应枚举
        expected_key_version:
          type: integer
          format: int64
          description: 交付放行目标版本；轮换时为当前生效版本
      required:
        - reason
        - expected_key_version
    ReconcileInput:
      type: object
      additionalProperties: false
      properties:
        expected_version:
          type: integer
          format: int64
          description: 运维列表中的激活任务版本，防止覆盖并发处理
        conclusion:
          type: string
          description: OBSERVED_REGISTERED、CONFIRMED_NOT_REGISTERED或DEVICE_ATTEMPT_STOPPED
          enum:
            - OBSERVED_REGISTERED
            - CONFIRMED_NOT_REGISTERED
            - DEVICE_ATTEMPT_STOPPED
        evidence_ref:
          type: string
          description: 烧录读回或人工对账的证据引用，不放密钥
        reason:
          type: string
          description: 关闭、轮换或人工处理原因，见对应枚举
        attempt_id:
          type: string
          description: 设备生成的UUID v4，表示一次引擎初始化或首通执行
        device_secret:
          type: string
          description: 已核实的供应商单设备密钥，仅人工对账写入，加密保存
        rtc_app_id:
          type: string
          description: 供应商RTC应用ID；不填则使用已保存值
      required:
        - expected_version
        - conclusion
        - evidence_ref
        - reason
    RegisterInput:
      type: object
      additionalProperties: false
      properties:
        challenge_id:
          type: string
          description: C01签名校时返回的一次性挑战
        boot_id:
          type: string
          description: 每次启动生成并保持的UUID v4
        hardware_model:
          type: string
          description: 生产登记型号，当前为KP01
        hardware_revision:
          type: string
          description: 硬件修订号，注册必须与库存一致
        firmware_version:
          type: string
          description: 固件版本，用于兼容诊断
        sdk_version:
          type: string
          description: SDK版本，用于兼容诊断
      required:
        - challenge_id
        - boot_id
        - hardware_model
        - hardware_revision
        - firmware_version
        - sdk_version
    SetupInput:
      type: object
      additionalProperties: false
      properties:
        boot_id:
          type: string
          description: 每次启动生成并保持的UUID v4
        local_setup_id:
          type: string
          description: 设备本次设置入口UUID v4；重试保持不变
        transport_profile:
          type: string
          description: 固定LOCAL_WEB，表示设备提供本地网页入口
          enum:
            - LOCAL_WEB
      required:
        - boot_id
        - local_setup_id
        - transport_profile
    HandoffInput:
      type: object
      additionalProperties: false
      properties:
        setup_id:
          type: string
          description: 云端15分钟临时设置会话UUID
        local_setup_id:
          type: string
          description: 设备本次设置入口UUID v4；重试保持不变
        code_challenge:
          type: string
          description: SHA256(ASCII verifier)的Base64URL无填充值
      required:
        - setup_id
        - local_setup_id
        - code_challenge
    PollInput:
      type: object
      additionalProperties: false
      properties:
        setup_id:
          type: string
          description: 云端15分钟临时设置会话UUID
        boot_id:
          type: string
          description: 每次启动生成并保持的UUID v4
        known_revision:
          type: integer
          format: int64
          description: 设备已知状态版本；允许0
      required:
        - setup_id
        - boot_id
        - known_revision
    ConfirmationInput:
      type: object
      additionalProperties: false
      properties:
        claim_id:
          type: string
          description: 待物理确认的绑定申请UUID
        challenge:
          type: string
          description: C05给设备的短时按键挑战，手机不能获取
        binding_digest:
          type: string
          description: 云端生成的绑定摘要，按键回报原值
        expected_binding_generation:
          type: integer
          format: int64
          description: 提交时预期绑定代数，防止跨解绑或重新绑定重放
        press_event_id:
          type: string
          description: 该次真实物理按键事件UUID v4，重试保持不变
      required:
        - claim_id
        - challenge
        - binding_digest
        - expected_binding_generation
        - press_event_id
    StateAckInput:
      type: object
      additionalProperties: false
      properties:
        device_revision:
          type: integer
          format: int64
          description: 云端设备状态版本号
        binding_generation:
          type: integer
          format: int64
          description: 绑定代数；解绑、重新绑定后旧代数无效
        local_generation:
          type: integer
          format: int64
          description: 本次启动的本地持久化序号，不能倒退
        state_hash:
          type: string
          description: STATE1规范字符串的SHA256小写十六进制摘要
      required:
        - device_revision
        - binding_generation
        - local_generation
        - state_hash
    CloseInput:
      type: object
      additionalProperties: false
      properties:
        setup_id:
          type: string
          description: 云端15分钟临时设置会话UUID
        reason:
          type: string
          description: 关闭、轮换或人工处理原因，见对应枚举
          enum:
            - SUCCESS
            - TIMEOUT
            - CANCELLED
            - NETWORK_SWITCH
        final_revision:
          type: integer
          format: int64
          description: 设备关闭设置入口前看到的最新状态版本
      required:
        - setup_id
        - reason
        - final_revision
    SMSSendInput:
      type: object
      additionalProperties: false
      properties:
        phone_e164:
          type: string
          description: 含国家区号的手机号，例如+8613800000000
          pattern: ^\+[1-9][0-9]{7,14}$
        purpose:
          type: string
          description: LOGIN 由服务端按手机号是否已有凭据选择注册或登录模板；CHANGE_PASSWORD 用于现有的短信登录后重置密码流程。更换手机号不可使用本接口。
          enum:
            - LOGIN
            - CHANGE_PASSWORD
        captcha_id:
          type: string
          format: uuid
          description: 当前登录或设备设置会话的人机验证挑战 ID
        captcha_code:
          type: string
          pattern: '^[0-9]{6}$'
          description: 图片中的 6 位数字；每次新的发送都须使用未消费的图片验证码
        captcha_ticket:
          type: string
          maxLength: 4096
          writeOnly: true
          description: 腾讯云模式使用对应端 SDK/插件票据；本地滑块模式使用 captcha/verify 返回的票据。绑定当前会话并一次性消费。
        captcha_randstr:
          type: string
          maxLength: 256
          writeOnly: true
          description: 腾讯云 Web 模式必填；微信小程序插件不需要
      anyOf:
        - required: [captcha_code]
        - required: [captcha_ticket]
      required:
        - phone_e164
        - purpose
        - captcha_id
    SMSVerifyInput:
      type: object
      additionalProperties: false
      properties:
        sms_challenge_id:
          type: string
          description: 发送短信得到的挑战UUID
        code:
          type: string
          description: 6位短信验证码；5分钟有效，最多验证5次
          pattern: ^[0-9]{6}$
      required:
        - sms_challenge_id
        - code
    ExchangeInput:
      type: object
      additionalProperties: false
      properties:
        token:
          type: string
          description: 90秒内只能兑换一次的handoff令牌
        verifier:
          type: string
          description: 设备交给手机的PKCE校验值；32字节随机数的Base64URL无填充字符串
      required:
        - token
        - verifier
    ClaimInput:
      type: object
      additionalProperties: false
      properties:
        elder_id:
          type: string
          description: 使用者公开UUID，复用subject_profile
        expected_binding_generation:
          type: integer
          format: int64
          description: 提交时预期绑定代数，防止跨解绑或重新绑定重放
      required:
        - elder_id
        - expected_binding_generation
    CancelInput:
      type: object
      additionalProperties: false
      properties:
        claim_id:
          type: string
          description: 待物理确认的绑定申请UUID
        expected_binding_generation:
          type: integer
          format: int64
          description: 提交时预期绑定代数，防止跨解绑或重新绑定重放
      required:
        - claim_id
        - expected_binding_generation
    WebAckInput:
      type: object
      additionalProperties: false
      properties:
        binding_id:
          type: string
          description: 当前已生效的绑定公开UUID
        binding_generation:
          type: integer
          format: int64
          description: 绑定代数；解绑、重新绑定后旧代数无效
        received_revision:
          type: integer
          format: int64
          description: 网页已收到的设备状态版本
      required:
        - binding_id
        - binding_generation
        - received_revision
    ProfileInput:
      type: object
      additionalProperties: false
      properties:
        initial_consents:
          type: object
          additionalProperties: false
          required: [types, confirmed]
          properties:
            types:
              type: array
              maxItems: 5
              uniqueItems: true
              items:
                type: string
                enum: [transcript_storage, raw_audio_storage, story_extraction, personalized_memory, family_sharing]
            confirmed:
              type: boolean
              description: 用户明确确认所选授权；不选任何项目时仍可创建资料
        household_id:
          type: string
          description: 家庭公开UUID；省略时须提供新家庭名称
        household_name:
          type: string
          description: 新建家庭的名称
        preferred_name:
          type: string
          description: 使用者称呼，用于设备人设和家庭展示
      required:
        - preferred_name
    Empty:
      type: object
      additionalProperties: false
    State:
      type: object
      properties:
        device_id:
          type: string
          description: 生产编号，KP01-加12位大写MAC；不是平台UUID
        device_revision:
          type: integer
          format: int64
          description: 云端设备状态版本号
        binding_generation:
          type: integer
          format: int64
          description: 绑定代数；解绑、重新绑定后旧代数无效
        binding_state:
          type: string
          enum:
            - UNBOUND
            - CLAIM_PENDING
            - BOUND
            - TRANSFER_PENDING
        activation_state:
          type: string
          enum:
            - NOT_STARTED
            - RESERVED
            - CONTACT_POSSIBLE
            - REGISTERED_OBSERVED
            - READY
            - RECONCILE_REQUIRED
            - BLOCKED
        state_hash:
          type: string
          description: STATE1规范字符串的SHA256小写十六进制摘要
    Command:
      type: object
      properties:
        command_id:
          type: string
          description: 命令标识
        type:
          type: string
          enum:
            - CONFIRM_CLAIM
            - APPLY_ACTIVATION
        expires_at_ms:
          type: integer
          format: int64
          description: 命令到期UTC毫秒
        payload:
          oneOf:
            - type: object
              properties:
                claim_id:
                  type: string
                  description: 申请编号
                challenge:
                  type: string
                  description: C05给设备的短时按键挑战，手机不能获取
                binding_digest:
                  type: string
                  description: 云端生成的绑定摘要，按键回报原值
                expected_binding_generation:
                  type: integer
                  format: int64
                  description: 提交时预期绑定代数，防止跨解绑或重新绑定重放
                masked_account:
                  type: string
                  description: 脱敏的申请账号
            - type: object
              properties:
                config_b64:
                  type: string
                  description: 原始配置JSON的Base64URL无填充编码
                config_mac:
                  type: string
                  description: HMAC-SHA256(raw设备密钥, CFG1换行config_b64)
    ActivationConfig:
      type: object
      properties:
        contract_version:
          type: string
          description: ONBOARDING-1.1
        device_id:
          type: string
          description: 生产编号，KP01-加12位大写MAC；不是平台UUID
        activation_id:
          type: string
          description: 任务编号
        config_version:
          type: integer
          format: int64
          description: 版本
        binding_generation:
          type: integer
          format: int64
          description: 当前绑定代数
        expires_at_ms:
          type: integer
          format: int64
          description: 24小时配置有效期
        iot:
          type: object
          properties:
            instance_id:
              type: string
              description: 供应商实例
            product_key:
              type: string
              description: 产品编号
            device_name:
              type: string
              description: 冻结的物理设备名
            device_secret:
              type: string
              description: 平台代注册取得的本设备火山密钥；不再下发product_secret
            RTCAppID:
              type: string
              description: 平台代注册取得的RTC应用ID
        bot_id:
          type: string
          description: 智能体ID
    WebStatus:
      type: object
      properties:
        setup_id:
          type: string
          description: 临时会话UUID
        state:
          $ref: '#/components/schemas/State'
        binding_id:
          type: string
          description: 当前已生效的绑定公开UUID
        claim_id:
          type: string
          description: 待物理确认的绑定申请UUID
        device_saved:
          type: boolean
        authenticated:
          type: boolean
        closed:
          type: boolean
        sms_enabled:
          type: boolean
        expires_at_ms:
          type: integer
          format: int64
          description: 设置入口到期时间
    Browser:
      type: object
      properties:
        csrf_token:
          type: string
          description: 保存在当前标签页sessionStorage；写请求放X-CSRF-Token
        data:
          $ref: '#/components/schemas/WebStatus'
    Failure:
      type: object
      properties:
        ok:
          type: boolean
          const: false
        code:
          type: string
          description: 稳定业务错误码
        message:
          type: string
          description: 用户可读说明
        request_id:
          type: string
          description: 请求追踪UUID
    DevicesItem:
      type: object
      properties:
        platform_device_id:
          type: string
          description: 平台设备UUID
        device_id:
          type: string
          description: 物理设备编号
        model:
          type: string
          description: 型号
        binding_generation:
          type: integer
          format: int64
          description: 当前绑定代数
        device_revision:
          type: integer
          format: int64
          description: 状态版本
        released:
          type: boolean
          description: 设备已完成内部初始化，可以开始绑定
        bound:
          type: boolean
          description: 当前是否存在有效绑定
        activation_id:
          type: string
          description: 激活任务UUID
        activation_state:
          type: string
          description: 激活状态
        activation_version:
          type: integer
          format: int64
          description: 对账使用的预期任务版本
        key_version:
          type: integer
          format: int64
          description: 当前生效设备认证密钥版本
        pending_key_version:
          type: integer
          format: int64
          description: 待交付或放行的版本，没有则0
        current_attempt_id:
          type: string
          description: 当前供应商注册尝试UUID
        enrollment_job_id:
          type: string
          description: 最新生产或轮换任务UUID
        last_error_code:
          type: string
          description: 故障原因码
        provider_device_name:
          type: string
          description: 冻结的供应商物理名
        household_name:
          type: string
          description: 家庭名，仅我的设备
        preferred_name:
          type: string
          description: 使用者称呼，仅我的设备
    TimeChallengeResponse:
      type: object
      properties:
        payload_b64:
          type: string
          description: TIME1校时JSON的Base64URL无填充
        mac_hex:
          type: string
          description: HMAC-SHA256(raw32设备密钥, TIME1换行payload_b64)
    RegisterResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            state:
              $ref: '#/components/schemas/State'
            contract_version:
              type: string
              description: ONBOARDING-1.1
    SetupResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            setup_id:
              type: string
              description: 设置UUID
            expires_at_ms:
              type: integer
              format: int64
              description: 15分钟到期
            poll_after_ms:
              type: integer
              format: int64
              description: 首次2000
            state:
              $ref: '#/components/schemas/State'
    HandoffResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            handoff_token:
              type: string
              description: 90秒一次性令牌
            expires_at_ms:
              type: integer
              format: int64
              description: 到期毫秒
            entry_url:
              type: string
              description: 固定HTTPS入口；设备将token和verifier放fragment
    PollResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            state:
              $ref: '#/components/schemas/State'
            command:
              oneOf:
                - $ref: '#/components/schemas/Command'
                - type: 'null'
            poll_after_ms:
              type: integer
              format: int64
              description: 下一次轮询间隔
    ConfirmationResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            claim_id:
              type: string
              description: 申请UUID
            state:
              $ref: '#/components/schemas/State'
            already_applied:
              type: boolean
    StateAckResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            accepted_revision:
              type: integer
              format: int64
              description: 已接受版本
            setup_can_close:
              type: boolean
    AttemptResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            allowed:
              type: boolean
            attempt_id:
              type: string
              description: 执行UUID
            permit_expires_at_ms:
              type: integer
              format: int64
              description: 30秒有效期
            state:
              $ref: '#/components/schemas/State'
    ResultResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            activation_id:
              type: string
              description: 任务UUID
            state:
              $ref: '#/components/schemas/State'
            reconcile_required:
              type: boolean
    ActivationAckResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            accepted:
              type: boolean
            state:
              $ref: '#/components/schemas/State'
    CloseResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            close_allowed:
              type: boolean
            state:
              $ref: '#/components/schemas/State'
    ClaimResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            claim_id:
              type: string
              description: 申请UUID
            expires_at_ms:
              type: integer
              format: int64
              description: 120秒有效期
            state:
              $ref: '#/components/schemas/State'
    StateOnlyResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            state:
              $ref: '#/components/schemas/State'
    AckResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            accepted:
              type: boolean
    SMSResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            sms_challenge_id:
              type: string
              description: 验证码挑战UUID
            expires_at_ms:
              type: integer
              format: int64
              description: 5分钟
            resend_after_ms:
              type: integer
              format: int64
              description: '60000'
    ProfileResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            elder_id:
              type: string
              description: 使用者公开UUID
            household_id:
              type: string
              description: 家庭公开UUID
    ProfilesResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            items:
              type: array
              items:
                type: object
                properties:
                  household_id:
                    type: string
                    description: 家庭公开UUID
                  household_name:
                    type: string
                    description: 家庭名
                  elder_id:
                    type: string
                    description: 使用者UUID，空值表示家庭无使用者
                  preferred_name:
                    type: string
                    description: 称呼
    DevicesResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/DevicesItem'
            limit:
              type: integer
              format: int64
              description: 运维列表最多200条；按设备创建时间倒序
    InventoryResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            device_id:
              type: string
              description: 生产编号，KP01-加12位大写MAC；不是平台UUID
            platform_device_id:
              type: string
              description: 平台公开UUID，沿用现有设备管理接口
            enrollment_job_id:
              type: string
              description: 生产或轮换任务UUID
            key_version:
              type: integer
              format: int64
              description: 目标凭据版本
            contract_version:
              type: string
              description: ONBOARDING-1.1
            released:
              type: boolean
    DeliveryResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            algorithm:
              type: string
              description: RSA-OAEP-SHA256+A256GCM
            enrollment_job_id:
              type: string
              description: 任务UUID
            wrapped_key_b64:
              type: string
              description: RSA包装的AES数据密钥
            ciphertext_b64:
              type: string
              description: 前12字节为nonce，后接AES-GCM密文和16字节认证标签；AAD为任务UUID
            expires_at_ms:
              type: integer
              format: int64
              description: 交付包到期时间
    ReleaseResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            device_id:
              type: string
              description: 生产编号，KP01-加12位大写MAC；不是平台UUID
            platform_device_id:
              type: string
              description: 平台公开UUID，沿用现有设备管理接口
            enrollment_job_id:
              type: string
              description: 生产或轮换任务UUID
            key_version:
              type: integer
              format: int64
              description: 目标凭据版本
            contract_version:
              type: string
              description: ONBOARDING-1.1
            released:
              type: boolean
    LogoutResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            signed_out:
              type: boolean
    AccountResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          type: object
          properties:
            csrf_token:
              type: string
              description: 账号会话写请求CSRF
            authenticated:
              type: boolean
    BrowserResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          $ref: '#/components/schemas/Browser'
    WebStatusResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        code:
          type: string
          const: OK
        request_id:
          type: string
          format: uuid
        server_time_ms:
          type: integer
          format: int64
          description: UTC毫秒
        data:
          $ref: '#/components/schemas/WebStatus'