feat: complete device onboarding and mobile binding workflows

docs/onboarding-api-fields.md

@@ -0,0 +1,412 @@
+# 首次接入接口字段清单
+
+由 `node scripts/generate-onboarding-contract.mjs` 根据实际Go请求结构生成。共 31 项操作。完整响应结构见 [OpenAPI](../openapi/onboarding.yaml)，流程、签名、错误恢复见 [实施说明](onboarding-implementation.md)。
+
+## C01 校时挑战
+
+`POST /api/v1/device/time-challenges`
+
+调用身份：校时请求，无请求签名；设备必须核验TIME1响应MAC
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| device_id | string | 是 | 生产编号，KP01-加12位大写MAC；不是平台UUID |
+| key_version | integer | 是 | 设备认证密钥版本 |
+| boot_id | string | 是 | 每次启动生成并保持的UUID v4 |
+| client_nonce | string | 是 | 设备生成的16字节随机数，Base64URL无填充 |
+
+响应：根对象直接返回 `{payload_b64,mac_hex}`。
+
+## C02 首次认证和启动注册
+
+`POST /api/v1/device/register`
+
+调用身份：设备DEVREQ1签名
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| challenge_id | string | 是 | C01签名校时返回的一次性挑战 |
+| boot_id | string | 是 | 每次启动生成并保持的UUID v4 |
+| hardware_model | string | 是 | 生产登记型号，当前为KP01 |
+| hardware_revision | string | 是 | 硬件修订号，注册必须与库存一致 |
+| firmware_version | string | 是 | 固件版本，用于兼容诊断 |
+| sdk_version | string | 是 | SDK版本，用于兼容诊断 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `RegisterResponse.data`。
+
+## C03 创建临时设置会话
+
+`POST /api/v1/device/setup-sessions`
+
+调用身份：设备DEVREQ1签名
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| boot_id | string | 是 | 每次启动生成并保持的UUID v4 |
+| local_setup_id | string | 是 | 设备本次设置入口UUID v4；重试保持不变 |
+| transport_profile | string | 是 | 固定LOCAL_WEB，表示设备提供本地网页入口 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `SetupResponse.data`。
+
+## C04 获取一次性手机入口
+
+`POST /api/v1/device/handoffs`
+
+调用身份：设备DEVREQ1签名
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| setup_id | string | 是 | 云端15分钟临时设置会话UUID |
+| local_setup_id | string | 是 | 设备本次设置入口UUID v4；重试保持不变 |
+| code_challenge | string | 是 | SHA256(ASCII verifier)的Base64URL无填充值 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `HandoffResponse.data`。
+
+## C05 查询状态和命令
+
+`POST /api/v1/device/poll`
+
+调用身份：设备DEVREQ1签名
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| setup_id | string | 是 | 云端15分钟临时设置会话UUID |
+| boot_id | string | 是 | 每次启动生成并保持的UUID v4 |
+| known_revision | integer | 是 | 设备已知状态版本；允许0 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `PollResponse.data`。
+
+## C06 物理按键确认绑定
+
+`POST /api/v1/device/claim-confirmations`
+
+调用身份：设备DEVREQ1签名
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| claim_id | string | 是 | 待物理确认的绑定申请UUID |
+| challenge | string | 是 | C05给设备的短时按键挑战，手机不能获取 |
+| binding_digest | string | 是 | 云端生成的绑定摘要，按键回报原值 |
+| expected_binding_generation | integer | 是 | 提交时预期绑定代数，防止跨解绑或重新绑定重放 |
+| press_event_id | string | 是 | 该次真实物理按键事件UUID v4，重试保持不变 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `ConfirmationResponse.data`。
+
+## C07 绑定状态持久化回执
+
+`POST /api/v1/device/state-acks`
+
+调用身份：设备DEVREQ1签名
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| device_revision | integer | 是 | 云端设备状态版本号 |
+| binding_generation | integer | 是 | 绑定代数；解绑、重新绑定后旧代数无效 |
+| local_generation | integer | 是 | 本次启动的本地持久化序号，不能倒退 |
+| state_hash | string | 是 | STATE1规范字符串的SHA256小写十六进制摘要 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `StateAckResponse.data`。
+
+## C08 申请设备执行许可
+
+`POST /api/v1/device/activation-attempts`
+
+调用身份：设备DEVREQ1签名
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| activation_id | string | 是 | 该物理设备唯一的激活任务UUID |
+| config_version | integer | 是 | 配置版本，必须与当前云端版本一致 |
+| attempt_id | string | 是 | 设备生成的UUID v4，表示一次引擎初始化或首通执行 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `AttemptResponse.data`。
+
+## C09 回报设备执行结果
+
+`POST /api/v1/device/activation-results`
+
+调用身份：设备DEVREQ1签名
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| activation_id | string | 是 | 该物理设备唯一的激活任务UUID |
+| attempt_id | string | 是 | 设备生成的UUID v4，表示一次引擎初始化或首通执行 |
+| stage | string | 是 | SDK_REGISTER或CONVERSATION_TEST；与C08平台当前阶段一致 |
+| sdk_result | integer | 是 | SDK执行返回码；SUCCESS_OBSERVED时必须为0 |
+| outcome | string | 是 | SUCCESS_OBSERVED、DEFINITE_FAILURE或UNKNOWN；未知结果不得盲目重试 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `ResultResponse.data`。
+
+## C10 激活结果保存回执
+
+`POST /api/v1/device/activation-acks`
+
+调用身份：设备DEVREQ1签名
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| activation_id | string | 是 | 该物理设备唯一的激活任务UUID |
+| local_generation | integer | 是 | 本次启动的本地持久化序号，不能倒退 |
+| config_version | integer | 是 | 配置版本，必须与当前云端版本一致 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `ActivationAckResponse.data`。
+
+## C11 关闭临时设置入口
+
+`POST /api/v1/device/setup-close`
+
+调用身份：设备DEVREQ1签名
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| setup_id | string | 是 | 云端15分钟临时设置会话UUID |
+| reason | string | 是 | 关闭、轮换或人工处理原因，见对应枚举 |
+| final_revision | integer | 是 | 设备关闭设置入口前看到的最新状态版本 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `CloseResponse.data`。
+
+## 手机兑换一次性入口
+
+`POST /api/v1/web/handoffs/exchange`
+
+调用身份：同源网页；一次性token和verifier
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| token | string | 是 | 90秒内只能兑换一次的handoff令牌 |
+| verifier | string | 是 | 设备交给手机的PKCE校验值；32字节随机数的Base64URL无填充字符串 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `BrowserResponse.data`。
+
+## 恢复手机设置会话
+
+`GET /api/v1/web/setup/session`
+
+调用身份：设置Cookie + 写请求CSRF
+
+无请求正文。
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `BrowserResponse.data`。
+
+## 关联OIDC登录
+
+`POST /api/v1/web/setup/auth-link`
+
+调用身份：设置Cookie + CSRF + OIDC Bearer
+
+正文：`{}`。
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `BrowserResponse.data`。
+
+## 发送登录短信
+
+`POST /api/v1/web/auth/sms/send`
+
+调用身份：设置Cookie + 写请求CSRF
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| phone_e164 | string | 是 | 含国家区号的手机号，例如+8613800000000 |
+| purpose | string | 是 | 固定LOGIN |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `SMSResponse.data`。
+
+## 验证短信并登录
+
+`POST /api/v1/web/auth/sms/verify`
+
+调用身份：设置Cookie + 写请求CSRF
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| sms_challenge_id | string | 是 | 发送短信得到的挑战UUID |
+| code | string | 是 | 6位短信验证码；5分钟有效，最多验证5次 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `BrowserResponse.data`。
+
+## 查询可选择的家庭使用者
+
+`POST /api/v1/web/profiles`
+
+调用身份：设置Cookie + 写请求CSRF
+
+正文：`{}`。
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `ProfilesResponse.data`。
+
+## 创建家庭或使用者
+
+`POST /api/v1/web/profiles/create`
+
+调用身份：设置Cookie + 写请求CSRF
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| household_id | string | 条件或可选 | 家庭公开UUID；省略时须提供新家庭名称 |
+| household_name | string | 条件或可选 | 新建家庭的名称 |
+| preferred_name | string | 是 | 使用者称呼，用于设备人设和家庭展示 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `ProfileResponse.data`。
+
+## 提交绑定申请
+
+`POST /api/v1/web/claims`
+
+调用身份：设置Cookie + 写请求CSRF
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| elder_id | string | 是 | 使用者公开UUID，复用subject_profile |
+| expected_binding_generation | integer | 是 | 提交时预期绑定代数，防止跨解绑或重新绑定重放 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `ClaimResponse.data`。
+
+## 取消自己的绑定申请
+
+`POST /api/v1/web/claims/cancel`
+
+调用身份：设置Cookie + 写请求CSRF
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| claim_id | string | 是 | 待物理确认的绑定申请UUID |
+| expected_binding_generation | integer | 是 | 提交时预期绑定代数，防止跨解绑或重新绑定重放 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `StateOnlyResponse.data`。
+
+## 查询手机绑定进度
+
+`POST /api/v1/web/setup/status`
+
+调用身份：设置Cookie + 写请求CSRF
+
+正文：`{}`。
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `WebStatusResponse.data`。
+
+## 网页确认收到绑定结果
+
+`POST /api/v1/web/setup/ack`
+
+调用身份：设置Cookie + 写请求CSRF
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| binding_id | string | 是 | 当前已生效的绑定公开UUID |
+| binding_generation | integer | 是 | 绑定代数；解绑、重新绑定后旧代数无效 |
+| received_revision | integer | 是 | 网页已收到的设备状态版本 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `AckResponse.data`。
+
+## 设置结束后查询我的设备
+
+`GET /api/v1/web/onboarding/devices`
+
+调用身份：账号Cookie；设备列表也支持OIDC Bearer
+
+无请求正文。
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `DevicesResponse.data`。
+
+## 恢复账号会话及CSRF
+
+`GET /api/v1/web/account/session`
+
+调用身份：账号Cookie；设备列表也支持OIDC Bearer
+
+无请求正文。
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `AccountResponse.data`。
+
+## 退出本浏览器登录
+
+`POST /api/v1/web/auth/logout`
+
+调用身份：账号Cookie；设备列表也支持OIDC Bearer
+
+正文：`{}`。
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `LogoutResponse.data`。
+
+## 查询生产设备和激活状态
+
+`GET /api/v1/ops/device-inventory`
+
+调用身份：运维OIDC Bearer + X-Tenant-ID
+
+无请求正文。
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `DevicesResponse.data`。
+
+## 登记生产设备
+
+`POST /api/v1/ops/device-inventory`
+
+调用身份：运维OIDC Bearer + X-Tenant-ID
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| factory_mac | string | 是 | 12位大写十六进制MAC；相同MAC不能创建第二台物理设备 |
+| hardware_model | string | 是 | 生产登记型号，当前为KP01 |
+| hardware_revision | string | 是 | 硬件修订号，注册必须与库存一致 |
+| batch_no | string | 是 | 生产批次，方便追溯 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `InventoryResponse.data`。
+
+## 向工装交付加密密钥
+
+`POST /api/v1/ops/device-inventory/{id}/credential-deliveries`
+
+调用身份：运维OIDC Bearer + X-Tenant-ID
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| enrollment_job_id | string | 是 | 生产登记或密钥轮换任务UUID |
+| receiver_public_key_pem | string | 是 | 工装RSA公钥，PKIX PEM，2048至4096位，指数65537 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `DeliveryResponse.data`。
+
+## 确认烧录读回并放行
+
+`POST /api/v1/ops/device-inventory/{id}/release`
+
+调用身份：运维OIDC Bearer + X-Tenant-ID
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| enrollment_job_id | string | 是 | 生产登记或密钥轮换任务UUID |
+| evidence_ref | string | 是 | 烧录读回或人工对账的证据引用，不放密钥 |
+| expected_key_version | integer | 是 | 交付放行目标版本；轮换时为当前生效版本 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `ReleaseResponse.data`。
+
+## 准备轮换凭据
+
+`POST /api/v1/ops/device-inventory/{id}/credential-rotations`
+
+调用身份：运维OIDC Bearer + X-Tenant-ID
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| reason | string | 是 | 关闭、轮换或人工处理原因，见对应枚举 |
+| expected_key_version | integer | 是 | 交付放行目标版本；轮换时为当前生效版本 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `InventoryResponse.data`。
+
+## 人工记录激活对账结论
+
+`POST /api/v1/ops/onboarding-activations/{id}/reconcile`
+
+调用身份：运维OIDC Bearer + X-Tenant-ID
+
+| 字段 | 类型 | 必填 | 用途 |
+|---|---|---|---|
+| expected_version | integer | 是 | 运维列表中的激活任务版本，防止覆盖并发处理 |
+| conclusion | string | 是 | OBSERVED_REGISTERED、CONFIRMED_NOT_REGISTERED或DEVICE_ATTEMPT_STOPPED |
+| evidence_ref | string | 是 | 烧录读回或人工对账的证据引用，不放密钥 |
+| reason | string | 是 | 关闭、轮换或人工处理原因，见对应枚举 |
+| attempt_id | string | 条件或可选 | 设备生成的UUID v4，表示一次引擎初始化或首通执行 |
+| device_secret | string | 条件或可选 | 已核实的供应商单设备密钥，仅人工对账写入，加密保存 |
+| rtc_app_id | string | 条件或可选 | 供应商RTC应用ID；不填则使用已保存值 |
+
+响应：成功外层 `{ok,code,request_id,server_time_ms,data}`；失败 `{ok,code,request_id,message}`。data结构为 `StateOnlyResponse.data`。