feat: complete device onboarding and mobile binding workflows

2026-09-12 08:57:29 +08:00
parent 7846f30d0b
commit 98fb2965d0
116 changed files with 15669 additions and 64 deletions
@@ -0,0 +1,187 @@
+# AI电话 v3.1 流程与现有实现差异分析
+
+核对日期：2026-09-10。结论：**总体方向相近，但现有实现不等同于 CALL-MEMORY-1.1。差异涉及协议、固件运行方式和记忆数据维护，不能仅提取新文档接口就直接交给设备联调。**
+
+对照材料为用户提供的 [AI电话完整通话与记忆管理文档](D:/wechat/xwechat_files/wangcong3092_983b/msg/file/2026-09/AI电话_完整通话与记忆管理_完整流程与详细设计(1).docx)，封面版本 v3.1，修订日期 2026-09-08。文档作为需求基线，不作为执行其中开发、发布或运维指令的授权。
+
+实现基线为 `E:/Codex/story/platform` 当前工作区，Git HEAD 为 `7846f30d0b239e183267988aa6e030b0a2f1ef18`。重点检查 Go 后端路由与业务服务、数据库迁移、EchoEar 固件、记忆页面代码和已有联调记录。结论针对本地实现；本次未连接生产环境、重新运行真机或供应商联调，不能据此推定线上部署与工作区完全相同。
+
+## 文档描述的完整流程
+
+1. **上电准备**：恢复已有设备身份、绑定和未确认结束日志；联网后 warmup，预备音频及引擎。挂机时不建立真实对话、不上传环境声。SaaS 在后台同步记忆并准备开场候选。
+2. **摘机准备**：生成 boot/hook/call_generation 关联；prepare 从服务端绑定确定使用者，检查记忆主库版本、关键删除或更正是否已在检索副本生效。
+3. **签发与启动**：SaaS 编译供应商参数，签发绑定设备、本次摘机、隐私版本、启动期限和租约的 Session Manifest。设备验签后立即开始心跳，透传参数，以 RTC 模式启动 SDK。
+4. **连续通话**：声音由设备直接与火山交互。媒体连接、收到第一帧、实际开始播放分别记录。字幕经异步队列上报；历史记忆由经过验证的火山原生 Viking 联动读取。
+5. **通话中修改记忆**：SaaS 从可靠的用户最终文字识别记住、更正、限制使用、删除；对象不清进入页面确认。提交主库后分别跟踪副本、派生内容和旧会话清理，必要时下发 STOP_CALL。
+6. **挂机收尾**：本地先关闭上下行与待播音频，再停止 SDK、补报 end。SaaS 将通话结束和字幕完整度分开记录；字幕静默收齐初值 15 秒、绝对等待 60 秒。
+7. **维护记忆与准备下一通**：从用户证据提取候选，处理冲突和删除屏障，提交 SaaS 主库与 outbox；按主记录版本同步 Viking 事件及画像，验证检索可见性，再推进连续同步进度。下次摘机重新检查。
+
+文档强调四个结果分别成立：**通话结束、字幕收齐、记忆保存、检索可见**。普通新增同步慢可以按安全模式继续；更正、删除和权限变化不能沿用不安全的旧资料。
+
+## 现有流程
+
+当前 EchoEar 主路径为：
+
+```text
+上电恢复平台及火山凭据，尝试补报上次未结束会话，初始化音频与引擎
+  → 触摸或唤醒触发对话
+  → bootstrap + config + POST /device/v3/agent-sessions
+  → 后端冻结使用者、授权和上下文，返回 runtime + session_config
+  → 固件组装 session.update，使用 VOLC_MODE_WS 启动
+  → session.created/updated 后上报 session_started
+  → 通过 session_updated 周期续期，异步上传最终字幕
+  → volc_stop + session_ended/session_failed，清理播放器
+  → SaaS 摘要/故事/候选处理
+  → 另一路将通话文字 AddSession 到 Viking 自动抽取
+```
+
+入口依据：[固件创建会话](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:558)、[SDK 启动与退出](E:/Codex/story/platform/firmware/echoear-platform-agent/components/application/service/conv_service/src/volc_conv.c:389)、[后台任务装配](E:/Codex/story/platform/internal/app/app.go:427)。
+
+## 可以复用的实现
+
+| 能力 | 已有实现 | 对齐程度 |
+|---|---|---|
+| 设备认证与服务端确定使用者 | HMAC、防重放、设备有效绑定；会话保存 subject_id 和授权快照 | 方向一致，认证报文及绑定代数协议不同 |
+| 音频与业务链路分开 | 设备直接调用火山 SDK，平台接收控制信息与文字 | 方向一致，EchoEar 实际使用 WS |
+| 共享助手和用户记忆范围 | Bot 配置、稳定助手标识、租户与使用者派生的 Viking user_id | 已有基础，不能替代供应商侧防篡改授权验证 |
+| 异步文字上报 | SDK 回调投递内存队列，业务任务发 HTTPS，后端事务保存并去重 | 主思路一致，缺修订、缺口和持久重试协议 |
+| 结束恢复 | NVS 保存待结束会话，重启补报；后端支持结束状态及迟到最终文字 | 已有基础，缺未取得 SID 的取消及独立远端停止证明 |
+| 后台摘要与人工记忆维护 | 用户文字来源、摘要、故事、候选、人工确认、记忆版本、编辑/停用/删除、索引 outbox | 已有基础，与 Viking 自动抽取副本未统一 |
+
+证据：[会话归属与上下文快照](E:/Codex/story/platform/internal/orchestration/repository.go:293)、[字幕保存与原会话归属](E:/Codex/story/platform/internal/orchestration/transcript_batch.go:127)、[仅用户文字参与抽取](E:/Codex/story/platform/internal/extraction/processor.go:94)、[人工记忆维护](E:/Codex/story/platform/internal/saas/content_service.go:568)。
+
+## 关键差异及影响
+
+### 1 设备接口与认证不兼容
+
+文档附件 B 定义七个 `POST /api/v1/device/calls/*` 接口；当前注册的是 `/device/v2/*` 和 `/device/v3/agent-sessions*`。这七个新路径没有注册。
+
+认证也不只是换路径：
+
+| 项目 | v3.1 文档 | 当前实现 |
+|---|---|---|
+| 时间 | `X-Timestamp-Ms`，Unix 毫秒 | `X-Device-Timestamp`，RFC3339 |
+| 签名入口 | `Authorization: Device-HMAC-SHA256 ...` | `X-Device-Signature` |
+| 签名内容 | DEVREQ1 开头的九行，含设备、密钥版本、请求 ID | 方法、含查询串的 RequestURI、时间、nonce、body hash 五行 |
+| 签名编码 | 小写十六进制 | 无填充 Base64url |
+| 响应 | `ok/code/request_id/server_time_ms/data` | `request_id/data/error` |
+
+现有 HMAC 本身已经实现，但不兼容文档的线协议。直接按文档开发新固件会遇到路由或验签失败。
+
+证据：[设备路由](E:/Codex/story/platform/internal/httpapi/router.go:308)、[认证头及验签](E:/Codex/story/platform/internal/deviceauth/verifier.go:22)、[当前签名算法](E:/Codex/story/platform/internal/deviceauth/verifier.go:142)、[响应封装](E:/Codex/story/platform/internal/httpapi/response.go:8)。
+
+### 2 固件实际使用 WS 而文档固定 RTC
+
+文档附件 C 要求 `mode=RTC`，映射 `VOLC_MODE_RTC`。当前 EchoEar 能力声明只有 `low_load`，实际 `volc_start` 参数写的是 `VOLC_MODE_WS`。
+
+后端保留 high_quality/low_load 两类能力，并不等于当前固件已经按 RTC 流程运行。切换需要核对 RTC 参数通道、字幕格式、首音频、打断和 stop 行为，不能只改枚举后视为完成。
+
+证据：[固件能力声明](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:569)、[实际 SDK 模式](E:/Codex/story/platform/firmware/echoear-platform-agent/components/application/service/conv_service/src/volc_conv.c:439)、[后端传输校验](E:/Codex/story/platform/internal/orchestration/repository.go:614)。
+
+### 3 没有新版会话清单及摘机取消机制
+
+文档要求 `boot_id + hook_event_id` 唯一业务键，独立 `call_generation`、`binding_generation`、`media_attempt_id`，以及 `manifest_b64/manifest_mac`。即使 end 先于 prepare 到达，也要保存取消记录，阻止晚到 prepare 启动。
+
+当前创建请求使用 `Idempotency-Key`，返回 `session_nonce/config_digest/runtime/session_config`；具有请求幂等和配置摘要，但没有上述清单结构、按摘机取消、清单撤销及代数校验。当前摘要也不是文档要求的清单 HMAC。尚未取得 conversation_id 时没有等价的结束入口。
+
+证据：[请求与响应结构](E:/Codex/story/platform/internal/orchestration/types.go:95)、[创建幂等入口](E:/Codex/story/platform/internal/orchestration/hardware_agent.go:31)、[固件响应处理](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:584)。
+
+### 4 心跳起点与本地租约停止不同
+
+文档要求验清单后立即开始心跳，与 SDK 启动并行；默认周期 5 秒、租约不超过 45 秒。失联时固件依本地保守截止关闭音频；迟到许可不能复活会话。
+
+当前固件在上报 session_started 后设置下一次心跳，通过 `session_updated` 续期。默认周期为 15 秒；后端租约按 `HeartbeatInterval × 5` 计算，默认对应 75 秒。心跳网络失败时固件记录错误并再次尝试，没有看到该路径维护本地授权截止或到期静音。
+
+这意味着现有服务端超时回收不能等同于文档要求的设备本地有界停止。
+
+证据：[固件续期逻辑](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:693)、[启动成功后才轮询](E:/Codex/story/platform/firmware/echoear-platform-agent/components/application/service/conv_service/src/volc_conv.c:459)、[后端租约](E:/Codex/story/platform/internal/orchestration/hardware_agent.go:205)、[默认周期](E:/Codex/story/platform/internal/config/config.go:479)。
+
+### 5 供应商参数由固件拼装且开场配置未形成文档流程
+
+文档要求 SaaS 基于已验证 provider_profile 编译完整 `vendor_params_json`，设备只透传；热上下文与欢迎语分别产生，且附事实依赖版本。
+
+目前后端返回 authorized_context 等结构化字段，固件自行拼接固定话术、LLMConfig、S2SConfig、MemoryConfig 与回调参数。平台虽然有资料、最近摘要、open_topic 和上下文快照，但未形成独立欢迎语、开场候选依赖失效及 provider_profile 能力证据驱动的编译流程。
+
+当前上下文对部分字段按字符数裁剪，也未体现文档要求的按完整事实删减并保留否定、日期和条件的规则。
+
+证据：[端侧参数组装](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:457)、[上下文与摘要选择](E:/Codex/story/platform/internal/orchestration/repository.go:388)、[开场续聊与裁剪](E:/Codex/story/platform/internal/orchestration/companion_context.go:19)。
+
+### 6 Viking 写入路线与文档有实质冲突
+
+文档第 11 章要求 SaaS 是记忆事实维护方，Viking 保存已核验主库记录的检索副本。默认不让两边根据原始字幕各自抽取和维护同一份记忆。
+
+当前工作器在内容抽取任务中先排入独立 Viking 同步任务；Viking 服务读取 conversation_turn 中的用户和 AI 最终文字，再调用 `/api/memory/session/add`，并设置 `extract_memory_type` 让 Viking 抽取事件及画像。这条任务不以 SaaS curated_memory 提交完成为前置条件。
+
+因此当前是“平台内容整理 + Viking 会话自动抽取”两条路径。它不能保证平台更正、停用或删除某条人工记忆后，Viking 独立生成的事件和画像同步发生相同变化。
+
+证据：[工作器装配](E:/Codex/story/platform/internal/app/app.go:427)、[同步数据取自通话文字](E:/Codex/story/platform/internal/vikingmemory/service.go:175)、[AddSession 及抽取类型](E:/Codex/story/platform/internal/vikingmemory/client.go:127)。
+
+### 7 单条记忆修改删除未贯通 Viking 及旧会话
+
+当前平台已经有 `UpdateMemory/RequestMemoryDeletion`、版本比较、本地索引失效和删除任务。另有 `providermemory` 适配器，调用自定义 `/v1/memories:upsert`，它与 `vikingmemory` 是独立模块，不能把前者的完成视为 Viking 原生事件/画像已清理。
+
+已有接入说明明确指出：单条本地 curated memory 删除不会删除独立抽取的 Viking 事件/画像，统一管理界面尚未实现。文档要求的 source_suppression、单条投影映射、派生摘要清理及防旧源重抽取尚未贯通。
+
+此外，本次在相关源码和迁移中没有找到 `privacy_epoch`、已签发清单撤销目标、对应 `STOP_CALL` 及分阶段本地静音/SDK 停止回执。已有通话停止和授权撤回能力不能替代文档附件 L 的完整机制。
+
+证据：[单条删除入口](E:/Codex/story/platform/internal/saas/content_service.go:705)、[本地删除处理](E:/Codex/story/platform/internal/memorylifecycle/delete_processor.go:32)、[独立 provider 适配器](E:/Codex/story/platform/internal/providermemory/client.go:59)、[Viking 已知限制](E:/Codex/story/platform/docs/viking-memory-integration.md:23)。
+
+### 8 没有通话前同步水位与关键变更拦截
+
+文档要求用户级 memory_revision、viking_visible_revision、关键积压和 EMPTY/IN_SYNC/LAGGING_NORMAL/LAGGING_CRITICAL 等状态。供应商写入成功后还要验证检索可见，且中间版本失败不能被后续成功版本跳过。
+
+当前 NativeAccessForDevice 主要检查当前绑定和授权，再返回用户过滤配置；AddSession 成功后记录审计摘要。未看到针对主库记忆版本的连续可见进度、关键删除拦截、NATIVE_VIKING/HOT_ONLY/OFF 模式及关闭旧记忆的验证机制。Viking 获取配置失败当前可仅记录警告后继续创建，这与按关键积压判断是否允许启动不同。
+
+证据：[创建时 Viking 处理](E:/Codex/story/platform/internal/orchestration/hardware_agent.go:46)、[原生范围配置](E:/Codex/story/platform/internal/vikingmemory/service.go:84)、[写入与审计](E:/Codex/story/platform/internal/vikingmemory/service.go:208)。
+
+### 9 字幕可靠性及结束状态未达到新版要求
+
+已实现最终字幕上报、事务落库、重复检测和结束后补入，但当前 turn_key/sequence_no 的同一条内容变化会冲突；没有文档要求的 utterance_id/source_revision 修订和分片结构。
+
+固件当前使用 8 项内存消息队列，满时记日志；上报失败后释放消息，未看到对应的持久重试与 GAP_DECLARED。端侧上报把 interrupted 固定为 false，不能据此证明 AI 的整句话已播放。
+
+后端 session_ended 会直接完成业务状态并排入抽取，没有独立 DRAINING/COMPLETE/PARTIAL 状态及文档的 15/60 秒收齐窗口。固件退出时先设置 is_stop，但播放器停止在 SDK stop 和网络结束上报之后，未实现文档要求的先立即清空待播内容、分别报告停止证据的顺序。
+
+证据：[字幕结构与冲突规则](E:/Codex/story/platform/internal/orchestration/transcript_batch.go:24)、[端侧上报与失败处理](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:713)、[队列及满队列处理](E:/Codex/story/platform/firmware/echoear-platform-agent/components/application/service/conv_service/src/volc_conv.c:330)、[结束与抽取](E:/Codex/story/platform/internal/orchestration/hardware_agent.go:214)、[退出顺序](E:/Codex/story/platform/firmware/echoear-platform-agent/components/application/service/conv_service/src/volc_conv.c:483)。
+
+### 10 语音记忆变更确认与事项进度需要补充
+
+当前人工记忆编辑能力不等同于文档第 8 章：尚未找到从用户最终文字生成 intent/mutation、来源动作去重、NEEDS_CONFIRMATION、resolve/confirm 冻结方案、六阶段处理进度、PLAY_LOCAL_NOTICE 的整套实现。
+
+现有 open_topic 是摘要中的续聊线索；没有文档的稳定 OPEN_ITEM 标识、OPEN/COMPLETED/CANCELLED/UNKNOWN 及计划修订状态机。因此“第一通提计划、第二通报告完成、第三通不再追问”的结果尚不能由当前数据流程保证。
+
+证据：[现有记忆页面 API](E:/Codex/story/platform/internal/httpapi/router.go:267)、[现有摘要与 open_topic](E:/Codex/story/platform/internal/extraction/processor.go:284)、[续聊线索选择](E:/Codex/story/platform/internal/orchestration/companion_context.go:70)。
+
+## 设备接口对应关系
+
+下表只用于说明差异，**不是 CALL-MEMORY-1.1 已实现接口文档**。文档七个接口均为 POST，统一前缀 `/api/v1/device/calls/`。当前对应功能不代表字段、鉴权、幂等和状态语义兼容。
+
+| 文档接口 | 当前近似入口或调用 | 主要缺口 |
+|---|---|---|
+| CA01 `warmup` | `GET /device/v2/bootstrap`、`GET /device/v2/config` | 专门 warmup、绑定代数和 provider_profile 准备状态 |
+| CA02 `prepare` | `POST /device/v3/agent-sessions` | 摘机唯一键、签名清单、记忆进度校验、取消先到处理 |
+| CA03 `events` | `POST /device/v3/agent-sessions/{id}/events` 及 `/{id}/turns:batch` | 统一事件批次、逐条 ACK、连续序号、字幕修订/缺口/播放事件 |
+| CA04 `heartbeat` | EchoEar 发送 `session_updated` 到 v3 events；后端另有 v2 conversations heartbeat | 清单后立即心跳、manifest/media/privacy 绑定、绝对租约、本地到期关闭 |
+| CA05 `end` | EchoEar 发送 `session_ended/session_failed`；后端另有 `POST /device/v2/conversations/{id}/stop` | 无 SID 取消、原摘机标识、local_audio_stopped、独立 sdk_stop_status/remote_state |
+| CA06 `status` | `GET /device/v2/conversations/{id}` | boot/hook 查询、清单状态、字幕状态、隐私版本及命令 |
+| CA07 `command-acks` | `POST /device/v2/commands/{id}/ack` | 当前通话代数、MANIFEST_DISCARDED/LOCAL_AUDIO_OFF/SDK_STOPPED 与提示回执 |
+
+当前已注册入口见 [router.go](E:/Codex/story/platform/internal/httpapi/router.go:308)。EchoEar 真实调用需以 [platform_client.c](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:611) 为准，不能把后端存在的 v2 能力自动算成当前固件已使用。
+
+## 建议的对齐顺序
+
+1. **先冻结设备契约与真实供应商组合**：明确按文档 RTC 路线升级；核验动态上下文、原生检索、关闭路径、字幕归属和用户范围授权。文档附件 H 本身也把这些列为待实测能力，不能因代码中存在 MemoryConfig 字段就判定通过。
+2. **补齐启动与撤销协议**：设备 HMAC 契约、warmup/prepare、摘机幂等与取消、Session Manifest、双代数、媒体尝试、首次心跳、本地租约、STOP_CALL 和停止证明。
+3. **统一记忆主库和 Viking 投影**：以 SaaS 主记录为维护入口，补逐条映射、版本、关键积压、可见性、删除防复活及旧会话撤销；解决当前独立 AddSession 抽取与人工维护脱节。
+4. **完善记录和管理交互**：字幕修订与持久重试、收齐状态、变更确认及阶段进度、固定提示能力、OPEN_ITEM 与开场候选失效。
+5. **再形成正式设备接口交付件**：同步 OpenAPI、设备请求/响应、签名测试向量、重试/错误规则、事件/命令回执和真实板卡联调结果。
+
+优先回归文档 T04～T07、T12～T14、T20～T31、T39～T48；供应商验证重点为 H02/H03/H05/H06/H12。此处是建议验收范围，不表示本次已执行或通过。
+
+## 核对方法和边界
+
+- 完整读取了 Word 正文、表格及附件 A～L，并查看了全部 10 张内嵌流程图。
+- 使用实际路由、结构体、调用顺序和持久化代码验证主要差异，并检索相关后端、迁移、固件及前端是否存在新版核心协议字段。
+- 现有运行记录作为历史证据；其中明确保留了真机重启后实际回忆等待验证项。本次没有把旧记录扩大为新版本验收结论。
+- 当前环境的文档渲染器缺少 `soffice.exe`，未取得可核验页码，因此文档依据采用章节/附件定位；未改写或重新导出用户的 Word 文件。
+- 本次只新增这份分析，不修改业务代码；未运行生产调用、设备刷写或发布操作。已有工作区修改保留。
@@ -0,0 +1,27 @@
+# 用户端手机适配
+
+适配范围为 `CustomerPortal` 的全部 11 个页面：首页、聊天记录、故事与记忆、长者资料、提醒与待办、家庭管理、陪伴设备、内容分享、数据与授权、服务用量、设置与权限，以及这些页面的资料编辑、邀请、设备配置、审核和授权弹窗。
+
+- 900px 及以下使用抽屉导航，支持搜索、遮罩关闭、Escape、关闭后恢复焦点和窗口尺寸变化。桌面仍使用侧栏。
+- 600px 及以下将表单、列表操作和详情改为单列，长名称和资源编号可换行。家庭切换、年度活动日历与权限表在各自区域内横向滚动，手机日历默认定位到最近日期。
+- 聊天采用列表与摘要上下排列，选中后定位摘要，可返回聊天列表；手机上的“更多筛选”保留语音方式和起止日期筛选。
+- 表单控件使用适合触屏的尺寸，手机输入文字至少为 16px；年度日历日期格为 24px。弹窗使用动态视口高度和安全区域边距，长表单可以滚动到底部。
+- 手机覆盖规则集中在 `web/src/customer-responsive.css`，在现有主题之后加载，限定于用户端。
+
+## 回归检查
+
+在 `web` 目录执行 `npm run dev -- --host 127.0.0.1`。在项目根目录使用已安装的 Playwright 运行：
+
+```powershell
+$env:PLAYWRIGHT_REQUIRE_FROM = '包含 Playwright 依赖的目录/package.json'
+$env:VISUAL_WEB_URL = 'http://127.0.0.1:5173'
+node test/e2e/visual-customer-mobile.mjs
+```
+
+默认使用本机 Google Chrome；可通过 `CHROME_PATH` 指定浏览器可执行文件。未安装 Playwright 时，可先用 `npm install --prefix .tmp-mobile-qa --no-audit --no-fund playwright` 安装到忽略的临时目录，再把 `PLAYWRIGHT_REQUIRE_FROM` 设置为该目录下 `package.json` 的绝对路径。
+
+脚本覆盖 320、375、390、430、768、900、1024、1440px 的所有页面，以及横屏、登录、空数据、加载失败、短视口表单、导航交互和主要操作弹窗。`MOBILE_WIDTHS` 可指定逗号分隔的宽度；`MOBILE_INTERACTIONS_ONLY=1` 只执行对应宽度的交互检查。截图和检查结果保存在 `.design-evidence/customer-mobile/`。
+
+测试使用合成家庭数据拦截全部业务 API，非 GET 请求会直接失败，不依赖后端或修改业务数据。该检查验证布局和前端交互，不代替真实身份认证、后端业务验收或 iPhone Safari / Android 真机软键盘测试。
+
+构建检查：在 `web` 目录执行 `npm run build`。
@@ -1,7 +1,7 @@
 # 设备 API 兼容性约定

 > 当前设备接口主版本：`/device/v2`  
-> 当前接口契约：OpenAPI 0.77.0
+> 当前接口契约：OpenAPI 0.78.0
 > 适用对象：云端 API、终端固件、模拟终端和设备联调工具

 ## 1. 兼容目标
@@ -46,6 +46,7 @@ CI在拉取请求中以目标分支OpenAPI为基线执行破坏性变更检查

 | OpenAPI版本 | 设备兼容变更 | 兼容结论 |
 |---|---|---|
+| 0.78.0 | 新增独立 `/api/v1/device/*` 首次接入协议；physical_confirm设备使用DEVREQ1签名和v3首通许可；旧设备的HMAC、v2路径和一键认领规则保留 | 新库存显式选择新协议；旧设备兼容 |
 | 0.77.0 | 新增v3平台代注册端点；Windows硬件智能体客户端不再接收Product Secret，既有v2接口不变 | v2完全兼容；硬件v3客户端升级 |
 | 0.68.0 | 生产基础设施状态增加实际应用运行环境与身份服务模式证明；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
 | 0.67.0 | 发布候选快照增加生产基础设施强制门禁及主机部署模式、异地备份、外部告警、模拟服务状态；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
@@ -79,3 +80,7 @@ CI在拉取请求中以目标分支OpenAPI为基线执行破坏性变更检查
 | 0.34.0 | 增加短期RTC凭证续签动作 | 由0.41.0补充能力协商，消除旧终端收到未知动作的风险 |

 每次OpenAPI版本更新都必须同步本表；设备端破坏性变更还必须给出v2保留期限、v3升级方式、灰度范围和回滚条件。
+
+## 首次接入协议隔离
+
+`ONBOARDING-1.2-SAAS` 仅适用于生产登记为 `physical_confirm` 的新设备，不依靠固件版本猜测协议。工装写入该契约标识、物理编号、raw32字节认证密钥和版本。新设备调用 `/device/v3/agent-sessions`；同一路径新旧认证由已登记身份区分，认证失败不降级。旧 `/device/v2/conversations` 创建不向新设备开放。新设备恢复出厂前须授权解绑，重置响应不含旧claim码。
@@ -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`。
@@ -0,0 +1,9 @@
+# 首次接入实现记录
+
+2026-09-11：本轮本地代码实施与验证已完成。正式说明见 [实施与联调说明](onboarding-implementation.md)，全部接口字段见 [字段清单](onboarding-api-fields.md)。
+
+已交付：53–57迁移、31项HTTP操作、设备独立认证、生产交付/放行/轮换、手机登录与家庭资料、按键确认绑定、双端ACK、激活outbox与补偿、配置回执与首通验证、代数及重放保护、手机页与运维页、OpenAPI及生成类型、调用工具、测试向量、灰度和恢复说明。
+
+验证：全量Go单元测试、go vet、10个模块独立PostgreSQL/Redis集成测试、OpenAPI本地引用检查、前端TypeScript/生产构建、12个浏览器截图检查点通过。前端构建仍提示现有主bundle较大，构建成功；未在本轮重构整个前端拆包。
+
+未发布生产。只在本地新建隔离数据库演练迁移，实际.env和已有业务库未改。真实短信、供应商账户、目标SDK、物理按键及NVS持久化由后续联调验收，不以合成测试结果代替。
@@ -0,0 +1,63 @@
+# 首次认证、绑定与激活：实施说明
+
+更新：2026-09-12。设备契约 ONBOARDING-1.1，按用户要求移除 recovery_action、retry_after_ms、next_action。详细输入、输出和示例见[设备端接口](设备端注册绑定接口.md)；完整操作见[字段清单](onboarding-api-fields.md)及[OpenAPI](../openapi/onboarding.yaml)。发布结果见[发布记录](onboarding-release-20260912.md)。
+
+## 已实现功能
+
+- 生产库存登记、MAC 唯一性、单设备独立密钥、工装加密交付、放行及凭据轮换。
+- 专用 HTTP 校时、TIME1 响应签名、HTTPS 启动注册、DEVREQ1 请求签名和 Redis nonce 防重放。
+- 临时设置会话、PKCE 一次性交接入口、OIDC 登录、家庭与使用者选择、手机申请及设备物理按键确认。
+- 绑定事务、绑定代数、权限校验、持久化回执、双端 ACK 收尾、重启和断网恢复。
+- 激活配置、设备 SDK 执行许可、结果上报、结果保存确认、首次通话和人工对账。
+- 旧设备认证保留；解绑、隐私删除和凭据轮换使旧归属请求失效。
+
+手机入口为 `/onboarding/entry#token=<handoff_token>&verifier=<verifier>`，由设备本地页面打开。手机临时流程为 `/onboarding/setup`，已绑定设备为 `/onboarding/devices`；生产登记和对账为 `/maintenance?area=onboarding`。
+
+## 设备认证
+
+C01 请求包含 device_id、key_version、boot_id、client_nonce，无请求时间戳或请求 HMAC。成功根对象直接返回 payload_b64、mac_hex。设备核验 `HMAC-SHA256(raw_device_key, "TIME1\n" + payload_b64)`，解码并核对本设备、本次启动及新随机数，再设置时间。包有效期120秒；固件还应执行原附件中的单调时钟往返限时、可信时间下限检查。
+
+C02–C11 使用严格验证服务器证书的 HTTPS。DEVREQ1 九行使用 LF 分隔，末尾无换行：版本、方法、路径、设备编号、密钥版本、UTC毫秒、nonce、请求UUID、原始正文SHA256。完整签名规则以设备文档为准。
+
+请求正文最大8KiB，拒绝多份JSON、重复字段、未知字段、缺少字段、null必填字段和非法UTF-8。设备请求不带query。版本及计数为0至2147483647，SDK返回码允许有符号32位整数。
+
+业务重试保持请求UUID及原始正文不变，重新生成时间戳、nonce及签名。响应缓存同时检查当前启动、设备密钥、绑定代数、权限和原业务对象。C01不使用普通业务响应封装；其他成功外层为 `{ok,code,request_id,server_time_ms,data}`，失败为 `{ok,code,request_id,message}`。
+
+## 绑定与收尾
+
+手机申请不直接建立归属，C06真实按键确认后才提交绑定与激活任务。绑定变更提升同一条单调递增代数，旧请求不能恢复旧归属。
+
+C07保存设备已接收状态。仅设备ACK时至少等待30秒；网页也ACK时从双方均完成起至少等待3秒。C07重复请求重新计算setup_can_close，但不延长原accepted_at。C11最终检查最新版本及关闭条件。
+
+## 激活状态机
+
+1. 绑定后，worker或C05准备加密配置；worker不会调用供应商注册。配置包含附件E.2字段，iot内是instance_id、product_key、product_secret、device_name。
+2. C05激活命令仅返回config_b64、config_mac。设备验证CFG1 HMAC及包内设备、绑定代数、版本、到期时间。
+3. 设备申请C08许可，平台在数据库持久化执行编号及30秒开始执行期限。未注册时对应SDK_REGISTER；已经注册并C10确认保存后对应CONVERSATION_TEST，不新增输入字段。
+4. C09报告SUCCESS_OBSERVED、DEFINITE_FAILURE或UNKNOWN，阶段须匹配执行编号。UNKNOWN和到期未报结果均阻止新的不确定执行；仅许可过期不能当作失败。
+5. 注册成功是物理设备事实，保留至解绑以后。C10确认结果保存，随后首通成功使当前绑定进入READY。重新绑定必须重新进行首通，不能使用上一代READY证明。
+6. 配置有效期24小时，更新版本前确认没有不确定执行。相同绑定下续期配置ACK后可复用已记录的首通证明。
+
+默认首通由设备SDK直接执行，C09携带设备认证后的观察结果。若首通走既有平台v3通话接口，则仍传原通话必填字段及intent=activation_test、activation_id、attempt_id，不需要permit_token；平台按关联会话核验开始、首音频、结束事件。每个执行编号最多关联一次会话。
+
+C09不上传DeviceSecret。设备SDK生成的单设备凭据应按原文在设备本地保存。平台既有代管通话如需该密钥，仍使用原有预配或运维核验凭据机制；本次没有从精简接口推导新的密钥上传字段。
+
+## 人工对账
+
+需要ops_admin，填写任务版本、证据引用、处理原因。供应商注册结果不明时，核实注册成功用OBSERVED_REGISTERED；确认没有注册且已停止执行用CONFIRMED_NOT_REGISTERED。DeviceSecret是可选的既有平台凭据补录字段。DEVICE_ATTEMPT_STOPPED仅可释放已停止的首次通话尝试，不能借此跳过注册对账。许可到期后还需经过3分钟等待窗口，平台不会伪造供应商查询结果。
+
+## 发布配置
+
+数据库迁移000053至000058增加首次接入所需身份、会话、激活和回执记录；000052是原有设备重置计数迁移。
+
+服务器使用原有compose.yaml、compose.override.yaml及compose.subtitle.yaml，再叠加[compose.onboarding.yaml](../deploy/server/compose.onboarding.yaml)。只更新API、worker、web及网关；原凭据和已有业务配置保留。ONBOARDING_MASTER_KEY_FILE指向服务器单独生成的64位hex主密钥文件。API和worker必须读取同一份主密钥和供应商产品配置。
+
+ONBOARDING_ENABLED、ONBOARDING_ACTIVATION_ENABLED控制新流程；ONBOARDING_PAUSE_CLAIMS暂停新绑定申请。ONBOARDING_TRUSTED_PROXY_CIDRS应为实际网关Docker网段；ONBOARDING_ALLOW_LOCAL_HTTP在线上保持false。Nginx仅放行HTTP的C01，其余HTTP仍跳转HTTPS。
+
+已有OIDC账号可以绑定。短信仅在配置真实发送通道后开启。自动创建账号的租户白名单默认空，按实际运营范围配置ONBOARDING_SELF_SIGNUP_TENANT_IDS。
+
+## 验证
+
+`go test ./...`、`go vet ./...`、`scripts/test-onboarding-integration.ps1`、`npm run generate:api`和`npm run build`均已通过。集成测试为各模块创建独立迁移数据库，不改本地业务数据库。覆盖设备11接口、按键绑定、跨代重放、未知结果、30秒许可、保存顺序、配置续期、直接SDK和既有SaaS会话路径。
+
+测试中的SDK观察结果和短信是合成数据；实物按键、断电持久化及真实供应商SDK尚需设备端联调。
@@ -0,0 +1,45 @@
+# 设备认证与绑定接口发布记录
+
+发布时间：2026-09-12 01:01:44（北京时间）。
+
+已部署版本：`0.81.0-rc.onboarding1`。设备协议：`ONBOARDING-1.1`，按本次要求删除辅助流程字段。当前发布目录为 `/opt/data-terminal-cloud/releases/0.81.0-rc.onboarding1`，`/opt/data-terminal-cloud/current` 已切换到该目录。
+
+## 在线地址
+
+- 平台：[https://121.41.46.238](https://121.41.46.238)
+- 运维首次接入：[登记与放行](https://121.41.46.238/maintenance?area=onboarding)
+- 手机绑定：[设置页面](https://121.41.46.238/onboarding/setup)，须先从设备生成的一次性交接入口进入；单独打开不能替代设备授权。
+- 已绑定设备：[我的设备](https://121.41.46.238/onboarding/devices)
+- 业务接口根地址：`https://121.41.46.238/api/v1/device/`
+- 专用校时：`POST http://121.41.46.238/api/v1/device/time-challenges`
+
+完整字段、中文解释、数据来源与示例见[设备端接口文档](设备端注册绑定接口.md)。
+
+## 本次实现及部署
+
+设备 C01–C11 输入输出已对齐。校时成功直接返回签名包；平台按任务状态发放30秒SDK执行许可；注册与首通分别上报；C10确认结果保存；未知结果及执行中断电重启进入待对账，禁止重复注册。SaaS worker负责准备配置，不再替这些新设备调用供应商注册。
+
+更新API、worker、前端和Nginx。保留服务器现有供应商、字幕、记忆和登录配置，以及旧设备协议。认证主密钥只在服务器凭据目录保存，权限为root所有、运行用户组65532可读（0640），没有放入源码、镜像或项目压缩包。
+
+数据库从51升至58，迁移状态正常。发布前已备份PostgreSQL、Redis、对象存储和登录服务数据，加密备份：`/var/backups/data-terminal-cloud/platform-20260911T165021Z.tar.gz.enc`。原发布目录 `0.80.2-rc.profile-ui3` 保留。
+
+## 验证结果
+
+- 全量Go测试和go vet通过；10个模块的隔离PostgreSQL/Redis集成测试通过。
+- 最后补充的断电许可保护已重新运行设备接口集成测试及相关API、HTTP、通话模块测试。
+- 前端TypeScript和生产构建通过。
+- 线上20项检查通过，使用正常证书校验，无关闭TLS验证。
+- API和worker健康检查通过；在线版本接口返回本发布版本。
+- 11条设备路由的未授权或缺字段响应符合契约，没有已删除的辅助字段。
+- HTTP校时接口返回平台JSON错误而非HTTPS重定向；其他HTTP业务与手机入口仍跳转HTTPS。
+- 手机绑定、我的设备、运维入口和对应新版前端静态资源可访问。
+
+设备完整认证、按键绑定、配置签名及激活成功路径在隔离数据库中验证。线上探测未使用真实设备密钥、未创建测试设备或业务账号。真实板卡、SDK注册、物理按键和断电持久化尚需设备端联调。短信发送通道未配置，本次保留OIDC账号登录，短信开关关闭。
+
+## 后续维护
+
+启动命令需包含原有三个Compose文件，并最后叠加 `deploy/server/compose.onboarding.yaml`；该文件固定本次API、worker和前端镜像。不要只运行旧的两文件部署命令，否则会遗漏首次接入运行配置。
+
+暂停新业务优先关闭ONBOARDING_ENABLED、ONBOARDING_ACTIVATION_ENABLED或开启ONBOARDING_PAUSE_CLAIMS，保留认证主密钥与历史数据。已有新协议设备投入使用后，不能直接回滚为不识别新设备的旧应用；应保留数据库迁移并采取前向修复。
+
+源码基线：`7846f30d0b239e183267988aa6e030b0a2f1ef18`，本次包含工作区实现，以项目包清单及文件哈希为准。未新建Git提交。
@@ -0,0 +1,476 @@
+# 设备注册与绑定接口简版
+
+按当前 SaaS 代码整理，适用协议 `ONBOARDING-1.2-SAAS`。
+
+正常流程：**后台登记并放行 → 设备联网认证 → 打开手机绑定页 → 用户登录并提交绑定 → 设备按键确认 → 保存绑定结果 → 激活语音服务。**
+
+`register` 成功表示设备身份认证通过；`binding_state=BOUND` 才表示绑定成功；`activation_state=READY` 表示语音服务已就绪。
+
+## 阅读约定
+
+- 每个接口只列用途、输入和输出。输入示例为请求 JSON；输出示例为响应 `data` 的主要字段，已省略部分状态和时间字段。
+- `<…>` 都是占位值，须替换为实际返回值或设备生成值；UUID、密钥、签名不能照抄占位值。版本号也必须使用最新返回值。
+- 路径前加实际 SaaS 域名，例如 `https://saas.example`。请求使用 `Content-Type: application/json`；下面 POST 请求统一携带 `X-Request-ID`（UUID v4）。
+- 设备接口除校时外，需要设备签名请求头；手机接口使用浏览器 Cookie，兑换入口后的 POST 还需 `X-CSRF-Token`，并按同源请求调用；运维接口需要运维登录凭证和 `X-Tenant-ID`。具体签名见[设备注册接口说明](设备注册接口说明.md)。
+- 这是代码中的接口清单，实际可用性取决于部署开关；短信登录需要已配置并开启短信服务。
+
+响应外层统一如下，后文的“输出”放在 `data` 中：
+
+```json
+{"ok":true,"code":"OK","message":"","request_id":"<本次请求UUID>","server_time_ms":1789092000000,"recovery_action":"NONE","retry_after_ms":0,"data":{}}
+```
+
+## 一、后台预登记：运维后台或生产工装调用
+
+### 1. 登记一台生产设备
+
+`POST /api/v1/ops/device-inventory`
+
+**用途：** 在平台建立设备档案，生成设备编号和凭据交付任务。MAC、型号、硬件版本用于识别设备；批次用于追溯。另需请求头 `Idempotency-Key`，避免重复建档。
+
+输入：
+
+```json
+{"factory_mac":"AABBCCDDEEFF","hardware_model":"KP01","hardware_revision":"A1","batch_no":"20260911-01"}
+```
+
+输出：设备生产编号、平台编号、交付任务和是否放行。
+
+```json
+{"device_id":"KP01-AABBCCDDEEFF","platform_device_id":"<平台设备UUID>","enrollment_job_id":"<交付任务UUID>","released":false}
+```
+
+### 2. 获取设备认证凭据交付包
+
+`POST /api/v1/ops/device-inventory/{id}/credential-deliveries`
+
+**用途：** 将设备认证密钥加密交给生产工装。`{id}` 使用上一步的 `platform_device_id`；公钥属于接收工装。
+
+输入：
+
+```json
+{"enrollment_job_id":"<交付任务UUID>","receiver_public_key_pem":"<工装RSA公钥PEM>"}
+```
+
+输出：加密交付包。工装解密后可取得 `device_id`、`device_key_b64`、`key_version` 等设备认证资料。
+
+```json
+{"algorithm":"RSA-OAEP-SHA256+A256GCM","enrollment_job_id":"<交付任务UUID>","wrapped_key_b64":"<加密的数据密钥>","ciphertext_b64":"<凭据密文>","expires_at_ms":1789092600000}
+```
+
+### 3. 确认凭据写入并放行
+
+`POST /api/v1/ops/device-inventory/{id}/release`
+
+**用途：** 确认设备凭据已写入并读回校验，允许设备开始联网认证。`evidence_ref` 是校验记录的引用。
+
+输入：
+
+```json
+{"enrollment_job_id":"<交付任务UUID>","evidence_ref":"factory-check/20260911/001","expected_key_version":1}
+```
+
+输出：该设备已放行。
+
+```json
+{"device_id":"KP01-AABBCCDDEEFF","platform_device_id":"<平台设备UUID>","enrollment_job_id":"<交付任务UUID>","released":true}
+```
+
+## 二、设备认证与绑定：设备调用
+
+### 4. 获取平台时间和注册挑战
+
+`POST /api/v1/device/time-challenges`
+
+**用途：** 取得可信时间和本次注册需要的一次性凭证。`boot_id` 标识本次启动，`client_nonce` 是设备生成的 16 字节随机数，以 Base64URL 无填充编码。
+
+输入：
+
+```json
+{"device_id":"KP01-AABBCCDDEEFF","key_version":1,"boot_id":"<本次启动UUID>","client_nonce":"<16字节随机数的Base64URL>"}
+```
+
+输出：带签名的校时数据包。设备验签并解码后读取 `challenge_id`、`server_time_ms`、`expires_at_ms`，同时核对设备编号、启动编号和随机数。
+
+```json
+{"payload_b64":"<校时数据的Base64URL>","mac_hex":"<平台响应签名>"}
+```
+
+### 5. 设备注册／启动认证
+
+`POST /api/v1/device/register`
+
+**用途：** 校验设备身份，记录本次启动和软件版本，返回绑定及激活状态。设备编号通过请求头 `X-Device-ID` 传入。首次联网和重新启动都调用。
+
+输入：
+
+```json
+{"challenge_id":"<上一步challenge_id>","boot_id":"<本次启动UUID>","hardware_model":"KP01","hardware_revision":"A1","firmware_version":"1.0.0","sdk_version":"1.0.0"}
+```
+
+输出：协议版本和当前设备状态。下面表示认证通过，但尚未绑定。
+
+```json
+{"contract_version":"ONBOARDING-1.2-SAAS","state":{"device_id":"KP01-AABBCCDDEEFF","binding_state":"UNBOUND","activation_state":"NOT_STARTED","next_action":"WAIT_BIND"}}
+```
+
+### 6. 创建一次绑定设置会话
+
+`POST /api/v1/device/setup-sessions`
+
+**用途：** 为本次手机绑定建立临时会话。`local_setup_id` 由设备生成，表示本次设置入口；`transport_profile` 固定为 `LOCAL_WEB`。
+
+输入：
+
+```json
+{"boot_id":"<本次启动UUID>","local_setup_id":"<本次设置入口UUID>","transport_profile":"LOCAL_WEB"}
+```
+
+输出：云端会话编号，有效期最长 15 分钟；`poll_after_ms` 表示建议多久后查询状态。
+
+```json
+{"setup_id":"<设置会话UUID>","expires_at_ms":1789092900000,"poll_after_ms":2000,"mode":"ENROLL"}
+```
+
+### 7. 获取手机绑定页面入口
+
+`POST /api/v1/device/handoffs`
+
+**用途：** 获取手机绑定页地址和一次性入口令牌。设备生成 `verifier`，将其 SHA256 结果以 Base64URL 无填充编码后，作为 `code_challenge`。
+
+输入：
+
+```json
+{"setup_id":"<设置会话UUID>","local_setup_id":"<本次设置入口UUID>","code_challenge":"<verifier的SHA256结果的Base64URL>"}
+```
+
+输出：页面地址、一次性令牌和到期时间。令牌最长 90 秒有效，只能兑换一次；`verifier` 保留在设备侧，由设备一并交给手机。
+
+```json
+{"entry_url":"https://saas.example/onboarding/entry","handoff_token":"<一次性令牌>","expires_at_ms":1789092090000}
+```
+
+手机实际打开：
+
+```text
+https://saas.example/onboarding/entry#token=<handoff_token>&verifier=<设备生成的verifier>
+```
+
+### 8. 查询绑定进度／领取平台命令
+
+`POST /api/v1/device/poll`
+
+**用途：** 设备定期查询是否有人申请绑定，以及是否有激活配置。`known_revision` 是设备已知的状态版本，首次可传 0。
+
+输入：
+
+```json
+{"setup_id":"<设置会话UUID>","boot_id":"<本次启动UUID>","known_revision":0}
+```
+
+输出示例：手机已经提交绑定申请，平台要求设备提示用户按键确认。`payload` 中的确认字段用于下一接口。
+
+```json
+{"state":{"binding_state":"CLAIM_PENDING"},"command":{"command_id":"<绑定申请UUID>","type":"CONFIRM_CLAIM","expires_at_ms":1789092120000,"payload":{"claim_id":"<绑定申请UUID>","challenge":"<平台按键挑战>","binding_digest":"<平台绑定摘要>","expected_binding_generation":0,"masked_account":"尾号1234"}},"poll_after_ms":2000}
+```
+
+没有命令时 `command=null`。绑定后可能返回 `APPLY_ACTIVATION`，其中包含激活任务、配置版本、配置包及校验值；见第四部分。
+
+### 9. 设备按键确认绑定
+
+`POST /api/v1/device/claim-confirmations`
+
+**用途：** 用户真实按下设备确认键后，设备上报确认，平台正式建立归属关系。前四个字段取自上一步命令，`press_event_id` 标识本次实际按键。
+
+输入：
+
+```json
+{"claim_id":"<绑定申请UUID>","challenge":"<平台按键挑战>","binding_digest":"<平台绑定摘要>","expected_binding_generation":0,"press_event_id":"<本次按键事件UUID>"}
+```
+
+输出：`BOUND` 表示正式绑定成功；`binding_generation` 是绑定代数，绑定或解绑发生后会变化。
+
+```json
+{"claim_id":"<绑定申请UUID>","already_applied":false,"state":{"binding_state":"BOUND","binding_generation":1,"next_action":"RESUME_ACTIVATION"}}
+```
+
+### 10. 设备确认已保存绑定结果
+
+`POST /api/v1/device/state-acks`
+
+**用途：** 设备将最新平台状态保存到本地后回执。状态版本、绑定代数和摘要使用平台返回值；`local_generation` 是本次启动的本地保存序号，不能倒退。
+
+输入：
+
+```json
+{"device_revision":5,"binding_generation":1,"local_generation":1,"state_hash":"<平台返回的state_hash>"}
+```
+
+输出：平台已收到保存回执；设备继续查询状态，等允许后关闭临时设置入口。
+
+```json
+{"accepted_revision":5,"setup_can_close":false,"close_after_ms":30000,"next_action":"POLL_FOR_CLOSE"}
+```
+
+### 11. 关闭本次临时设置入口
+
+`POST /api/v1/device/setup-close`
+
+**用途：** 绑定流程收尾，关闭临时设置入口。正常完成时等待 `poll` 返回 `setup_can_close=true`，再传 `SUCCESS`；其他原因可为 `TIMEOUT`、`CANCELLED`、`NETWORK_SWITCH`。
+
+输入：
+
+```json
+{"setup_id":"<设置会话UUID>","reason":"SUCCESS","final_revision":5}
+```
+
+输出：允许关闭；关闭入口不等于语音激活完成，激活可继续进行。
+
+```json
+{"close_allowed":true,"state":{"binding_state":"BOUND"}}
+```
+
+## 三、手机绑定页面：SaaS 前端调用
+
+用户看到的页面是 `/onboarding/setup`，正常由带一次性凭证的 `/onboarding/entry` 进入。登录账号及目标设备由会话确定，无需前端在绑定请求中再传手机号或设备编号。
+
+### 12. 兑换设备提供的一次性入口
+
+`POST /api/v1/web/handoffs/exchange`
+
+**用途：** 手机用设备提供的令牌和校验值建立绑定会话。服务端通过 Cookie 保持该会话，并返回后续 POST 使用的 `csrf_token`。
+
+输入：
+
+```json
+{"token":"<设备提供的handoff_token>","verifier":"<设备提供的verifier>"}
+```
+
+输出：注意此接口的响应 `data` 内还有一层 `data`，这是当前代码的实际结构。
+
+```json
+{"csrf_token":"<后续请求使用的CSRF值>","data":{"setup_id":"<设置会话UUID>","device_id":"KP01-AABBCCDDEEFF","sms_enabled":true,"state":{"binding_state":"UNBOUND","binding_generation":0}}}
+```
+
+### 13. 发送手机登录验证码
+
+`POST /api/v1/web/auth/sms/send`
+
+**用途：** 给用户手机号发送登录验证码。`phone_e164` 含国家区号，`purpose` 固定为 `LOGIN`。
+
+输入：
+
+```json
+{"phone_e164":"+8613800000000","purpose":"LOGIN"}
+```
+
+输出：验证码任务编号、过期时间、多久后可重发；不会在接口响应中返回验证码。
+
+```json
+{"sms_challenge_id":"<短信验证UUID>","expires_at_ms":1789092300000,"resend_after_ms":60000}
+```
+
+### 14. 验证短信并登录
+
+`POST /api/v1/web/auth/sms/verify`
+
+**用途：** 验证用户输入的短信验证码，建立登录状态。
+
+输入：
+
+```json
+{"sms_challenge_id":"<短信验证UUID>","code":"123456"}
+```
+
+输出：登录成功，并返回更新后的 CSRF 值；前端后续请求改用该值。
+
+```json
+{"csrf_token":"<更新后的CSRF值>","data":{"authenticated":true,"setup_id":"<设置会话UUID>"}}
+```
+
+### 15. 查询可以绑定的家庭和使用者
+
+`POST /api/v1/web/profiles`
+
+**用途：** 列出当前用户有权选择的家庭和设备使用者。
+
+输入：
+
+```json
+{}
+```
+
+输出：家庭和使用者列表。选择目标后，后续绑定使用 `elder_id`。
+
+```json
+{"items":[{"household_id":"<家庭UUID>","household_name":"我的家庭","elder_id":"<使用者UUID>","preferred_name":"爸爸"}]}
+```
+
+### 16. 创建家庭／设备使用者
+
+`POST /api/v1/web/profiles/create`
+
+**用途：** 没有可选使用者时创建档案。新建家庭传 `household_name`；已有家庭则改传 `household_id`。`preferred_name` 是使用者称呼。
+
+输入示例：新建家庭和使用者。
+
+```json
+{"household_name":"我的家庭","preferred_name":"爸爸"}
+```
+
+输出：新建的家庭和使用者编号。
+
+```json
+{"household_id":"<家庭UUID>","elder_id":"<使用者UUID>"}
+```
+
+### 17. 提交设备绑定申请
+
+`POST /api/v1/web/claims`
+
+**用途：** 申请把当前设备绑定给选中的使用者。`elder_id` 来自上面两个接口，`expected_binding_generation` 来自最新设备状态。
+
+输入：
+
+```json
+{"elder_id":"<使用者UUID>","expected_binding_generation":0}
+```
+
+输出：申请编号和状态。`CLAIM_PENDING` 表示等待设备按键确认，还没有正式绑定。
+
+```json
+{"claim_id":"<绑定申请UUID>","expires_at_ms":1789092120000,"state":{"binding_state":"CLAIM_PENDING","binding_generation":0}}
+```
+
+### 18. 查询手机页面上的绑定进度
+
+`POST /api/v1/web/setup/status`
+
+**用途：** 手机刷新等待确认、已绑定和激活进度。`device_saved` 表示设备是否已确认保存绑定结果。
+
+输入：
+
+```json
+{}
+```
+
+输出示例：设备已经绑定并保存结果。
+
+```json
+{"binding_id":"<正式绑定UUID>","device_saved":true,"authenticated":true,"state":{"device_revision":5,"binding_generation":1,"binding_state":"BOUND"}}
+```
+
+### 19. 手机确认已收到绑定成功结果
+
+`POST /api/v1/web/setup/ack`
+
+**用途：** 告诉平台手机页面已收到绑定成功结果，配合设备完成设置收尾。三个字段均取自上一步响应。
+
+输入：
+
+```json
+{"binding_id":"<正式绑定UUID>","binding_generation":1,"received_revision":5}
+```
+
+输出：回执已接收。
+
+```json
+{"accepted":true}
+```
+
+## 四、绑定后的语音激活：设备继续调用
+
+配置由平台后台任务准备，通过前面的 `POST /api/v1/device/poll` 下发。设备不用直接调用供应商注册接口。
+
+`poll` 的激活命令输出示例（仍是响应 `data` 内的字段）：
+
+```json
+{"command":{"command_id":"<激活任务UUID>","type":"APPLY_ACTIVATION","payload":{"activation_id":"<激活任务UUID>","config_version":1,"config_digest":"<配置摘要>","config_b64":"<编码后的配置包>","config_mac":"<配置签名>","key_version":1,"config_saved":false,"engine_initialized":false}}}
+```
+
+配置包解码后包含设备编号、绑定代数、配置版本、到期时间、IoT 连接资料、单设备密钥、机器人及 RTC 配置。设备校验后保存，用于连接语音服务。
+
+### 20. 确认已保存激活配置
+
+`POST /api/v1/device/activation-acks`
+
+**用途：** 设备校验并保存配置后回执。任务、版本和摘要取自激活命令；绑定代数取自当前状态。
+
+输入：
+
+```json
+{"activation_id":"<激活任务UUID>","config_version":1,"binding_generation":1,"local_generation":2,"config_digest":"<配置摘要>"}
+```
+
+输出：配置保存已确认。
+
+```json
+{"accepted":true,"config_version":1}
+```
+
+### 21. 申请执行初始化／首次通话测试
+
+`POST /api/v1/device/activation-attempts`
+
+**用途：** 执行 SDK 初始化或首次通话测试前，申请本次执行许可。`attempt_id` 由设备生成；`stage` 为 `ENGINE_INIT` 或 `CONVERSATION_TEST`。首次通话必须由用户主动发起，并传 `user_initiated=true`。
+
+输入示例：申请初始化 SDK。
+
+```json
+{"activation_id":"<激活任务UUID>","config_version":1,"attempt_id":"<本次执行UUID>","stage":"ENGINE_INIT","user_initiated":false}
+```
+
+输出：本次执行许可和到期时间。许可最长 120 秒，首次通话测试最长 60 秒。
+
+```json
+{"activation_id":"<激活任务UUID>","attempt_id":"<本次执行UUID>","stage":"ENGINE_INIT","permit_token":"<短时执行许可>","permit_expires_at_ms":1789092120000,"maximum_test_seconds":60}
+```
+
+### 22. 上报初始化／首次通话测试结果
+
+`POST /api/v1/device/activation-results`
+
+**用途：** 上报执行结果。`outcome` 为 `SUCCESS`、`DEFINITE_FAILURE` 或 `UNKNOWN`；成功时 `sdk_result` 必须为 0。
+
+输入示例：真实首次通话完成后上报成功，`evidence` 引用平台已记录的会话和事件。初始化结果使用 `stage=ENGINE_INIT`，`evidence` 可传 `{}`。
+
+```json
+{"activation_id":"<激活任务UUID>","attempt_id":"<首次通话执行UUID>","stage":"CONVERSATION_TEST","sdk_result":0,"outcome":"SUCCESS","evidence":{"conversation_id":"<测试会话UUID>","started_event_id":"<开始事件ID>","first_audio_event_id":"<首音频事件ID>","ended_event_id":"<结束事件ID>"}}
+```
+
+输出示例：首次通话验收通过，设备可正常使用。仅初始化成功不会直接返回 `READY`。
+
+```json
+{"duplicate":false,"state":{"binding_state":"BOUND","activation_state":"READY","next_action":"ENTER_READY"}}
+```
+
+首次通话本身复用既有 `POST /device/v3/agent-sessions` 及会话事件接口；不能只调用本节的结果接口就完成验收。原有通话字段和新增测试许可字段见[实施说明中的首通流程](onboarding-implementation.md#6-激活首通和人工恢复)。
+
+## 五、页面恢复和可选操作
+
+这些操作按需要使用，不是每次首次绑定都必须调用。
+
+| 接口 | 用途 | 输入示例 | 输出示例（响应 data，节选） |
+|---|---|---|---|
+| `GET /api/v1/web/setup/session` | 页面刷新后恢复设置会话，取得新的 CSRF 值 | 无正文，浏览器携带设置 Cookie | `{"csrf_token":"<新CSRF值>","data":{"authenticated":true,"state":{"binding_state":"CLAIM_PENDING"}}}` |
+| `POST /api/v1/web/setup/auth-link` | 使用已有 OIDC 登录状态，作为短信登录的另一种方式 | 正文 `{}`，另带 `Authorization: Bearer <登录令牌>` | `{"csrf_token":"<新CSRF值>","data":{"authenticated":true,"setup_id":"<设置会话UUID>"}}` |
+| `POST /api/v1/web/claims/cancel` | 用户取消自己的待确认绑定申请 | `{"claim_id":"<绑定申请UUID>","expected_binding_generation":0}` | `{"state":{"binding_state":"UNBOUND"}}` |
+| `GET /api/v1/web/onboarding/devices` | 设置完成后，通过登录账号查询已绑定设备 | 无正文，携带账号 Cookie 或 OIDC 登录令牌 | `{"items":[{"device_id":"KP01-AABBCCDDEEFF","activation_state":"READY","household_name":"我的家庭","preferred_name":"爸爸"}]}` |
+
+## 最常用字段怎么理解
+
+| 字段 | 含义／来源 |
+|---|---|
+| `device_id` | 生产设备编号，例如 `KP01-AABBCCDDEEFF` |
+| `platform_device_id` | 平台设备 UUID，用于后台设备接口中的 `{id}` |
+| `boot_id` | 设备本次启动编号，重启后重新生成 |
+| `setup_id` | 本次临时绑定流程编号，由平台创建 |
+| `elder_id` | 使用者档案编号，由手机选择或创建 |
+| `claim_id` | 待设备按键确认的绑定申请编号 |
+| `binding_id` | 已正式生效的绑定记录编号，由手机状态接口返回 |
+| `binding_generation` | 绑定代数，用于区分绑定、解绑后的不同归属状态 |
+| `device_revision` | 平台状态版本，用于判断拿到的是哪一版状态 |
+| `activation_id` | 激活任务编号，通过设备 `poll` 命令取得 |
+| `attempt_id` | 设备生成的一次初始化或首次通话执行编号 |
+
+接口路径与请求字段依据[当前 HTTP 路由](../internal/onboarding/http.go)、[设备流程](../internal/onboarding/setup.go)、[手机流程](../internal/onboarding/web.go)、[短信登录](../internal/onboarding/sms.go)、[激活流程](../internal/onboarding/activation.go)及[生产登记](../internal/onboarding/inventory.go)核对。完整 31 项首次接入操作（含管理、退出和异常处理）见[字段清单](onboarding-api-fields.md)。
@@ -0,0 +1,261 @@
+# 设备注册接口说明
+
+适用版本：`ONBOARDING-1.2-SAAS`；对应当前仓库实现，OpenAPI `0.78.0`。
+
+设备注册用于验证设备身份、登记本次启动和固件/SDK版本，并返回当前绑定及激活进度。首次联网和每次重新启动时使用本流程。注册成功后，用户绑定与语音服务激活继续按照返回状态处理。
+
+## 1. 调用前提与顺序
+
+设备必须已在 SaaS 完成生产登记、认证凭据交付和放行，并持有以下信息：
+
+| 信息 | 示例 | 用途 |
+|---|---|---|
+| device_id | KP01-AABBCCDDEEFF | 生产设备编号，格式为 KP01- 加 12 位大写 MAC |
+| device_key_b64 | 工装交付的密钥编码 | 解码为 raw 32 字节后，用于 HMAC 签名和校时验签 |
+| key_version | 1 | 当前生效认证密钥的版本 |
+| hardware_model | KP01 | 库存登记的设备型号 |
+| hardware_revision | A1 | 库存登记的硬件修订号 |
+
+只有生产模式为 `physical_confirm` 且已放行的设备使用此协议；旧设备维持原有协议。未登记的编号不会通过本注册接口自动建档。
+
+调用顺序：
+
+1. 本次启动生成一个 `boot_id`，整个启动期间保持不变。
+2. C01 获取校时挑战，验证响应签名及随机数，取得可信时间和 `challenge_id`。
+3. C02 使用设备密钥签名并提交注册请求。
+4. 根据返回状态继续：未绑定设备创建设置会话；已绑定设备进入恢复激活或就绪流程。
+
+下文以 `https://saas.example` 表示部署后的 SaaS 域名。示例中的编号、时间和版本均为说明用值，联调时须使用实际返回值。
+
+## 2. C01：获取校时挑战
+
+```http
+POST /api/v1/device/time-challenges
+Content-Type: application/json
+```
+
+此接口不要求请求 HMAC。建议使用 HTTPS；服务端为启动校时保留 HTTP 访问能力。设备必须验证响应中的 TIME1 签名，才可采用其中的时间。C02 必须使用 HTTPS。
+
+请求正文：
+
+```json
+{
+  "device_id": "KP01-AABBCCDDEEFF",
+  "key_version": 1,
+  "boot_id": "10000000-0000-4000-8000-000000000001",
+  "client_nonce": "AAECAwQFBgcICQoLDA0ODw"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| device_id | string | 是 | 与生产登记一致的设备编号 |
+| key_version | integer | 是 | 当前生效密钥版本，必须大于等于 1 |
+| boot_id | string | 是 | 标准小写 UUID v4；本次启动标识 |
+| client_nonce | string | 是 | 16 字节随机数的 Base64URL 无填充编码；用于确认校时响应属于本次请求 |
+
+`X-Request-ID` 可选；传入时必须是标准小写 UUID v4，省略时由平台生成。它用于追踪 C01 请求；校时挑战本身按设备、密钥版本、boot_id、client_nonce 去重。
+
+成功响应的 `data`：
+
+```json
+{
+  "payload_b64": "<校时JSON原始字节的Base64URL无填充编码>",
+  "mac_hex": "<64位小写十六进制签名>"
+}
+```
+
+校验公式：
+
+```text
+raw_key = Base64URLDecode(device_key_b64)
+expected_mac = HexLower(HMAC-SHA256(raw_key, UTF8("TIME1\n" + payload_b64)))
+```
+
+其中 `\n` 是一个 LF 换行字节。先核对 mac_hex，再解码 payload_b64。解码内容为：
+
+```json
+{
+  "device_id": "KP01-AABBCCDDEEFF",
+  "boot_id": "10000000-0000-4000-8000-000000000001",
+  "client_nonce": "AAECAwQFBgcICQoLDA0ODw",
+  "challenge_id": "10000000-0000-4000-8000-000000000002",
+  "server_time_ms": 1789099200000,
+  "expires_at_ms": 1789099320000
+}
+```
+
+设备核对 device_id、boot_id、client_nonce 与本地请求完全一致，保存 challenge_id，并用 server_time_ms 建立时间基准。挑战从签发起有效 120 秒，不能重复用于不同的成功注册操作；同一 client_nonce 重试不会延长有效期。过期后换新的 client_nonce 重新获取。
+
+## 3. C02：提交设备注册
+
+| 项目 | 内容 |
+|---|---|
+| 请求地址 | `POST https://saas.example/api/v1/device/register` |
+| 调用方 | 已登记、已放行的设备 |
+| 认证方式 | DEVREQ1 / HMAC-SHA256 |
+| 请求正文 | JSON，UTF-8 无 BOM，最大 8 KiB |
+| URL参数 | 不接受 query 参数 |
+| 时间要求 | 请求时间与服务端时间差不超过正负 120 秒 |
+
+**请求头**
+
+| 请求头 | 必填 | 示例/用途 |
+|---|---|---|
+| Content-Type | 是 | `application/json` |
+| X-Device-ID | 是 | `KP01-AABBCCDDEEFF`，生产设备编号 |
+| X-Key-Version | 是 | `1`，签名使用的当前密钥版本 |
+| X-Timestamp-Ms | 是 | 当前可信 UTC 毫秒时间戳 |
+| X-Nonce | 是 | 每次发送新生成的 16 字节随机数，Base64URL 无填充编码 |
+| X-Request-ID | 是 | 标准小写 UUID v4，标识本次注册业务请求；网络重试保持不变 |
+| Authorization | 是 | `Device-HMAC-SHA256 <64位小写十六进制签名>` |
+
+整数请求头使用标准十进制，不带正号、空格或前导零。X-Nonce 与 C01 的 client_nonce 用途不同：前者用于每次 HTTP 发送防重放，后者用于校验对应的校时响应。
+
+**请求正文**
+
+```json
+{
+  "challenge_id": "10000000-0000-4000-8000-000000000002",
+  "boot_id": "10000000-0000-4000-8000-000000000001",
+  "hardware_model": "KP01",
+  "hardware_revision": "A1",
+  "firmware_version": "1.2.0",
+  "sdk_version": "1.0.0"
+}
+```
+
+| 字段 | 类型 | 必填 | 数据用途和约束 |
+|---|---|---|---|
+| challenge_id | string | 是 | C01 响应中取得的挑战 UUID v4；必须属于同一设备、密钥版本和 boot_id，且尚未使用、未过期 |
+| boot_id | string | 是 | 本次启动的 UUID v4；与 C01 相同，用于识别重启和关闭旧临时设置流程 |
+| hardware_model | string | 是 | 设备型号；必须与 SaaS 生产登记完全一致 |
+| hardware_revision | string | 是 | 硬件修订号；必须与 SaaS 生产登记完全一致 |
+| firmware_version | string | 是 | 当前固件版本，1–32 个 UTF-8 字节；用于版本记录和诊断 |
+| sdk_version | string | 是 | 当前 SDK 版本，1–64 个 UTF-8 字节；用于版本记录和诊断 |
+
+device_id 通过请求头传入。设备注册由库存确定租户，不需要用户登录令牌、手机号、家庭编号或使用者编号。不要提交设备明文密钥、供应商 ProductSecret 或 Wi-Fi 密码。请求中不接受未定义的字段。
+
+## 4. C02 签名计算
+
+先把最终要发送的 JSON 编码为 UTF-8 原始字节，再计算 `body_hash = SHA256(body)` 的小写十六进制值。按以下顺序构造 **9 行**文本，行间只用 LF，末尾不加换行：
+
+```text
+DEVREQ1
+POST
+/api/v1/device/register
+<X-Device-ID>
+<X-Key-Version>
+<X-Timestamp-Ms>
+<X-Nonce>
+<X-Request-ID>
+<body_hash>
+```
+
+```text
+signature = HexLower(HMAC-SHA256(raw_key, UTF8(上述9行文本)))
+Authorization = "Device-HMAC-SHA256 " + signature
+```
+
+raw_key 是解码后的 32 字节设备密钥，不能直接用 device_key_b64 的字符串字节。签名中的路径不包含域名。签名后不能再修改正文中的空格、换行或字段顺序。
+
+项目提供 [Python 签名调用工具](../scripts/onboarding-request.py) 和 [固定测试向量](../test/fixtures/onboarding-devreq1.json)。将上面的注册正文保存为 UTF-8 无 BOM 的 `register.json`，使用实际有效的 challenge_id、boot_id 和设备版本：
+
+```powershell
+python scripts/onboarding-request.py --device-id KP01-AABBCCDDEEFF --key-file device-key.b64 --key-version 1 --path /api/v1/device/register --body-file register.json --request-id 10000000-0000-4000-8000-000000000003
+```
+
+命令默认只输出本次签名请求头；加 `--send https://你的SaaS域名` 才会发送一次请求。工具使用运行它的电脑当前时间，使用前须保证电脑时间准确。固定测试向量使用合成密钥和固定时间，用于校验算法，不能直接发送到真实设备。
+
+## 5. C02 成功响应
+
+HTTP 200，以下为一台尚未绑定设备的示例：
+
+```json
+{
+  "ok": true,
+  "code": "OK",
+  "message": "",
+  "request_id": "10000000-0000-4000-8000-000000000003",
+  "server_time_ms": 1789099201000,
+  "recovery_action": "NONE",
+  "retry_after_ms": 0,
+  "data": {
+    "contract_version": "ONBOARDING-1.2-SAAS",
+    "state": {
+      "device_id": "KP01-AABBCCDDEEFF",
+      "platform_device_id": "10000000-0000-4000-8000-000000000004",
+      "device_revision": 3,
+      "binding_generation": 0,
+      "binding_state": "UNBOUND",
+      "activation_state": "NOT_STARTED",
+      "next_action": "WAIT_BIND",
+      "state_hash": "<当前状态的64位小写SHA256摘要>"
+    }
+  }
+}
+```
+
+示例中的 state_hash 是占位说明；设备须使用真实响应中的摘要。
+
+| 响应字段 | 用途 |
+|---|---|
+| ok / code / message | 请求是否成功及业务结果说明 |
+| request_id | 与请求对应，方便联调和日志定位 |
+| server_time_ms | 响应生成时的服务器 UTC 毫秒时间 |
+| recovery_action / retry_after_ms | 错误恢复建议及推荐退避时间，成功时为 NONE / 0 |
+| data.contract_version | 本次接口使用的协议版本 |
+| state.device_id | 设备认证使用的生产编号 |
+| state.platform_device_id | 既有 SaaS 管理接口使用的设备公开 UUID，与生产编号分开 |
+| state.device_revision | 当前状态版本，设备同步和状态 ACK 使用 |
+| state.binding_generation | 当前绑定代数；解绑、重新绑定后变化，用于使旧绑定请求和配置失效 |
+| state.binding_state | UNBOUND=未绑定；CLAIM_PENDING=等待设备物理确认；BOUND=已绑定 |
+| state.activation_state | NOT_STARTED=未开始开通；CONTACT_POSSIBLE=供应商执行中或结果待确认；REGISTERED_OBSERVED=已观察到注册成功、待设备验收；READY=验收完成；RECONCILE_REQUIRED=待对账；BLOCKED=当前开通受阻；RESERVED 为预留状态 |
+| state.next_action | WAIT_BIND=继续设置和绑定流程；RESUME_ACTIVATION=恢复激活；ENTER_READY=进入就绪流程 |
+| state.state_hash | 当前绑定和激活状态摘要，用于后续状态持久化回执 |
+
+注册成功表示 SaaS 已接受设备本次启动认证。是否已经绑定看 binding_state，是否完成通话验收看 activation_state。C02 不返回新的设备密钥或供应商语音凭据。
+
+## 6. 服务端处理和重试规则
+
+服务端先校验设备、放行状态、租户、密钥、HMAC、时间和随机数，再校验挑战归属及版本字段。成功后消费挑战，记录 boot_id、最近注册时间、固件版本和 SDK 版本，并返回设备状态。
+
+新的 boot_id 会关闭上一次启动的临时设置会话并取消待确认的绑定申请；已经完成的正式绑定保留。
+
+| 情况 | 设备端处理 |
+|---|---|
+| 请求超时、回包丢失 | 保持原 X-Request-ID 和原始正文，更新 X-Timestamp-Ms、X-Nonce 并重新签名 |
+| 前一次已经成功 | 在同一启动、绑定代数及有效权限范围内，24 小时内可返回缓存的原业务结果；外层响应时间重新生成 |
+| 相同请求号更改正文 | 返回 REQUEST_BODY_CONFLICT；不得用同一个请求号提交另一份版本信息或挑战 |
+| 挑战无效或过期 | 重新 C01，取得新挑战后使用新的 X-Request-ID 发起新的注册请求 |
+| 设备重启 | 生成新的 boot_id，重新执行 C01/C02，不重放上一次启动的注册请求 |
+| 注册缓存已过期或绑定代数已变化 | 恢复当前启动流程并查询最新状态，不依赖旧缓存结果 |
+
+## 7. 常见错误
+
+| HTTP | code | 说明与处理 |
+|---|---|---|
+| 400 | REQUEST_ID_REQUIRED | C02 缺少或使用了非 UUID v4 请求号 |
+| 400 | HTTPS_REQUIRED | C02 必须通过 HTTPS 访问 |
+| 400 | QUERY_FORBIDDEN | 去掉 URL query 参数 |
+| 400 | INVALID_JSON / VALIDATION_FAILED | 检查正文结构、重复字段、型号、硬件版本和版本字符串长度 |
+| 401 | DEVICE_AUTHENTICATION_FAILED | 检查编号、已放行状态、密钥版本、raw key、签名、时间和 nonce；重复发送同一 nonce 也会被拒绝 |
+| 403 | RESOURCE_ACCESS_DENIED | 当前租户、设备或业务操作不可访问，核对设备状态 |
+| 409 | CHALLENGE_INVALID | 挑战不属于当前设备/密钥/启动，或已消费、过期；重新 C01 |
+| 409 | REQUEST_BODY_CONFLICT | 同一请求号对应的正文发生变化 |
+| 409 | BINDING_GENERATION_CONFLICT | 当前启动或绑定状态已变化，恢复当前流程 |
+| 410 | CHALLENGE_EXPIRED | C01 返回的同一校时挑战已到期；换新的 client_nonce |
+| 410 | REQUEST_RESULT_EXPIRED | 注册请求的缓存结果已超过有效期 |
+| 413 | REQUEST_TOO_LARGE | 请求正文超过 8 KiB |
+| 415 | JSON_REQUIRED | Content-Type 必须为 application/json |
+| 429 | RATE_LIMITED | 按 Retry-After / retry_after_ms 退避；当前建议等待 60 秒 |
+| 503 | AUTHENTICATION_UNAVAILABLE / RATE_LIMIT_UNAVAILABLE | 认证防重放或限速依赖暂不可用，保留业务请求并退避重试 |
+| 500 | INTERNAL_ERROR | 内部处理异常，记录 request_id，按原请求号与正文重试 |
+
+失败时统一返回 `ok=false`、对应 code，data 为 null。恢复动作是通用建议；对于 CHALLENGE_INVALID 等具体错误，应按上表执行。
+
+## 8. 注册后的接口
+
+未绑定设备接着调用 `POST /api/v1/device/setup-sessions`，创建手机绑定入口所需的临时会话。后续完整字段见 [首次接入接口字段清单](onboarding-api-fields.md)，部署与开关见 [实施说明](onboarding-implementation.md)。
+
+本说明依据当前源码核对：[注册处理](../internal/onboarding/setup.go)、[设备认证及校时](../internal/onboarding/auth.go)、[签名计算](../internal/onboarding/crypto.go)、[HTTP响应](../internal/onboarding/http.go)。当前是代码接口说明，实际域名和开放范围由部署配置决定。
@@ -0,0 +1,24 @@
+# 设备端接口对齐记录
+
+更新：2026-09-12。当前代码已按[设备端接口文档](设备端注册绑定接口.md)同步实现，原有差异清单已由下表取代。
+
+| 位置 | 当前实现 |
+|---|---|
+| 协议及外层 | ONBOARDING-1.1；不返回 recovery_action、retry_after_ms、next_action |
+| 公共状态 | 仅设备编号、状态版本、绑定代数、绑定状态、激活状态、状态摘要 |
+| C01 | 无时间戳请求签名；HTTP专用入口；成功根对象仅 payload_b64、mac_hex，单设备 TIME1 HMAC |
+| C03 / C05 | 删除 mode 和轮询收尾辅助字段；known_revision 必填 |
+| 激活配置 | 命令 payload 仅 config_b64、config_mac；包内使用 iot.product_secret；设备 SDK 执行注册 |
+| C07 | 仅 accepted_revision、setup_can_close；重复回执重新计算关闭条件，保留原保存时间 |
+| C08 | 仅任务、配置版本、执行编号输入；返回 allowed、执行编号、30秒到期时间、state；平台按任务事实确定阶段 |
+| C09 | 仅任务、执行编号、SDK_REGISTER/CONVERSATION_TEST、SDK返回码、结果分类输入；返回任务、state、reconcile_required |
+| C10 | 仅任务、保存序号、配置版本输入；注册成功后确认保存结果；返回 accepted、state |
+| C11 | 继续检查最终版本与收尾条件；关闭临时入口不删除绑定 |
+
+默认设备 SDK 直接执行与上报首通观察结果；不要求额外上传 evidence。如采用平台既有 v3 通话服务，则平台依据已关联的会话、开始、首音频和结束事件核验结果，不向 C09 增加字段。设备供应商密钥不通过 C09 上传；既有平台代管通话仍需要其原有凭据配置。
+
+原文保留的 TRANSFER_PENDING 等枚举不代表本次新增了完整转移流程。当前首次绑定下发的命令为 CONFIRM_CLAIM 和 APPLY_ACTIVATION。短信通道与真实板卡、供应商 SDK 需使用真实环境分别验证。
+
+本地验证：全量 Go 测试、go vet、10 个模块的隔离 PostgreSQL/Redis 集成测试、前端 TypeScript 和生产构建通过。设备 HTTP 测试覆盖 C01–C11 成功字段、缺失或额外字段拒绝、HMAC、HTTPS限制、注册和首通、未知结果、跨绑定重放及收尾等待。
+
+线上结果见[发布记录](onboarding-release-20260912.md)。
@@ -0,0 +1,798 @@
+# 设备端注册、绑定与激活接口说明
+
+更新日期：2026-09-12。
+
+依据原始《AI电话_首次配网注册与激活_完整流程与详细设计(1)》附件 A、B、C、E、I 整理，仅列设备直接调用 SaaS 的 C01～C11。按本次要求省去辅助流程控制字段，不添加原文没有规定的请求或响应字段。
+
+本文件保留字段列表、中文含义、获取来源和示例。服务端已按此接口契约实现，版本为 `ONBOARDING-1.1`，并按本次要求移除三个辅助流程控制字段。实现与验证记录见[接口对齐说明](设备端接口_文档与当前代码差异.md)；线上发布结果另见[发布记录](onboarding-release-20260912.md)。
+
+## 通用规则
+
+- 设备已完成生产登记，持有出厂写入的 `device_id`、32 字节 `device_key`、`key_version`。
+- 全部接口使用 POST，正文为 JSON，不带 query 参数；普通报文上限 8 KiB，配置包上限 32 KiB。
+- C01 是无可信时间时可通过专用 HTTP 入口调用的校时接口。其余接口使用严格验证证书和主机名的 HTTPS。
+- `<…>` 为占位值，必须使用实际返回值或生成值；示例中的编号、版本、时间不是可直接请求线上服务的数据。
+- `string` 为字符串，`integer` 为整数，`boolean` 为 true/false，`object` 为 JSON 对象。UUID 按原文为标准 36 字符 UUID v4；Base64URL 无填充编码末尾不带 `=`。
+- 版本、计数按原文范围为 0～2147483647，时间为 Unix 毫秒。字段表中的全部输入均为原文必填字段。
+
+### 请求头
+
+C02～C11 使用下列认证头。C01 的设备编号和密钥版本放在正文中，不要求先提交可信时间戳或普通设备请求签名。
+
+| 字段 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- |
+| `Content-Type` | 正文格式 | 固定 `application/json`，C01 也使用。 |
+| `X-Device-ID` | 生产设备编号 | 从出厂配置读取，例如 `KP01-AABBCCDDEEFF`。 |
+| `X-Key-Version` | 设备认证密钥版本 | 从本机已保存凭据读取，十进制填写。 |
+| `X-Timestamp-Ms` | 本次发送时间 | C01 验证并校时后，读取当前可信 UTC 毫秒时间。 |
+| `X-Nonce` | 本次发送随机数 | 每次 HTTP 发送生成新的 16 字节安全随机数，做 Base64URL 无填充编码。 |
+| `X-Request-ID` | 业务请求编号 | 由设备生成 UUID v4；同一次业务操作重试保留，原始正文也保留。 |
+| `Authorization` | 设备请求认证码 | 使用本机 `device_key` 计算签名，填写 `Device-HMAC-SHA256 <64位小写十六进制HMAC>`。 |
+
+签名按附件 B 的 DEVREQ1 规则计算，以下 9 行以 LF 连接，末尾不再加换行：
+
+```text
+DEVREQ1
+<大写HTTP方法>
+<实际path>
+<device_id>
+<key_version十进制>
+<timestamp_ms十进制>
+<nonce的Base64URL>
+<request_id>
+<原始请求正文的SHA256小写十六进制>
+```
+
+密钥使用原始 32 字节，不发送密钥本身。网络重试更新随机数、发送时间和签名，但不重新生成同一操作的业务编号、按键事件编号或执行编号。
+
+### 普通响应外层
+
+C02～C11 使用此封装，C01 不使用。成功时读取 `data`，失败时读取 `code`、`message`；设备归属和激活结果以业务状态为准。
+
+| 字段 | 类型 | 中文含义 | 来源／怎么用 |
+| --- | --- | --- | --- |
+| `ok` | boolean | 本次请求是否成功 | 平台生成；不能单独用它判断设备已完成绑定或激活。 |
+| `code` | string | 业务结果码 | 平台返回，成功为 `OK`，失败为对应错误码。 |
+| `request_id` | string（UUID） | 请求追踪编号 | 平台返回与本次请求关联的编号，供查找请求记录。 |
+| `data` | object | 成功业务输出 | 字段按各接口下表读取。 |
+| `server_time_ms` | integer | 平台时间 | 平台生成；原文成功响应中提供，不能替代 C01 的首次可信校时。 |
+| `message` | string | 错误中文说明 | 失败时由平台提供，便于提示原因。 |
+
+```json
+{
+  "ok": true,
+  "code": "OK",
+  "request_id": "<请求UUID>",
+  "data": {},
+  "server_time_ms": 1789092000000
+}
+```
+
+失败示例：
+
+```json
+{
+  "ok": false,
+  "code": "CLAIM_EXPIRED",
+  "request_id": "<请求UUID>",
+  "message": "绑定确认已过期，请重新发起"
+}
+```
+
+### 公共设备状态 `state`
+
+下表相对于 `data.state`。按本次删减后的口径列出，状态版本、绑定代数和摘要必须来自同一版返回状态。
+
+| 字段 | 类型 | 中文含义 | 来源／后续使用 |
+| --- | --- | --- | --- |
+| `device_id` | string | 生产设备编号 | 来自平台生产记录，设备与本机编号核对。 |
+| `device_revision` | integer | 平台设备状态版本 | 由平台维护；后续用于 C05、C07、C11。 |
+| `binding_generation` | integer | 绑定代数 | 平台随绑定关系变化而更新，初始 0，首次绑定后 1；用于防止旧归属信息被继续使用。 |
+| `binding_state` | string | 绑定状态 | 平台根据归属关系返回，取值见下表。 |
+| `activation_state` | string | 激活状态 | 平台根据激活任务返回，只有 READY 表示服务已就绪。 |
+| `state_hash` | string | 本版状态摘要 | 平台按附件 I.1 计算；设备保存该版状态后在 C07 原样回传。 |
+
+| 字段 | 取值及中文含义 |
+| --- | --- |
+| `binding_state` | `UNBOUND` 未绑定；`CLAIM_PENDING` 等待按键；`BOUND` 已绑定；`TRANSFER_PENDING` 转移处理中。 |
+| `activation_state` | `NOT_STARTED` 未开始；`RESERVED` 已预留；`CONTACT_POSSIBLE` 可能已执行；`REGISTERED_OBSERVED` 已确认注册；`READY` 已就绪；`RECONCILE_REQUIRED` 待对账；`BLOCKED` 被阻止。 |
+
+`state_hash` 按原文对以下内容以 LF 连接后计算 SHA256，输出小写十六进制，末尾无换行：
+
+```text
+STATE1
+<device_id>
+<device_revision>
+<binding_generation>
+<binding_state>
+<activation_state>
+```
+
+`device_revision` 是平台状态版本，`binding_generation` 是归属代数，`local_generation` 是设备本地保存序号，`config_version` 是激活配置版本；不能互相代填。
+
+## 接口总览
+
+下面路径前统一加 `/api/v1/device`。
+
+| 编号 | POST 路径 | 用途 |
+| --- | --- | --- |
+| C01 | `/time-challenges` | 校时并获取注册挑战 |
+| C02 | `/register` | 认证设备并登记启动 |
+| C03 | `/setup-sessions` | 创建设置会话 |
+| C04 | `/handoffs` | 获取可交给手机的一次性绑定入口 |
+| C05 | `/poll` | 查询状态及命令 |
+| C06 | `/claim-confirmations` | 设备按键确认绑定 |
+| C07 | `/state-acks` | 确认已保存绑定状态 |
+| C08 | `/activation-attempts` | 申请一次 SDK 执行许可 |
+| C09 | `/activation-results` | 上报激活执行结果 |
+| C10 | `/activation-acks` | 确认激活结果已保存 |
+| C11 | `/setup-close` | 记录设置收尾并关闭入口 |
+
+## C01 校时并取得注册挑战
+
+`POST /api/v1/device/time-challenges`
+
+用途：让设备在时钟不正确时先取得可信时间，再使用严格 HTTPS。只返回时间和挑战，不返回用户资料、登录令牌或火山密钥。
+
+### 输入字段
+
+| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- | --- | --- |
+| `device_id` | string | 是 | 生产设备编号 | 读取出厂配置：`KP01-` 加 12 位大写十六进制 MAC。 |
+| `key_version` | integer | 是 | 认证密钥版本 | 读取本机保存的凭据版本，不是密钥内容。 |
+| `boot_id` | string（UUID） | 是 | 本次启动编号 | 设备每次启动生成并保留，后续 C02、C03、C05 沿用。 |
+| `client_nonce` | string | 是 | 本次校时随机数 | 设备生成 16 字节安全随机数并做 Base64URL 编码，每次校时重试换新值。 |
+
+输入示例：
+
+```json
+{
+  "device_id": "KP01-AABBCCDDEEFF",
+  "key_version": 1,
+  "boot_id": "<本次启动UUID>",
+  "client_nonce": "<16字节随机数的Base64URL>"
+}
+```
+
+### 输出字段
+
+下表为校时响应根对象。
+
+| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
+| --- | --- | --- | --- |
+| `payload_b64` | string | 校时数据包 | 平台将下方六个字段序列化并编码；设备用原字符串验签后解码。 |
+| `mac_hex` | string | 校时数据认证码 | 平台用本设备密钥计算 TIME1 HMAC，设备使用同一密钥验证。 |
+
+输出示例：
+
+```json
+{
+  "payload_b64": "<校时数据包的Base64URL>",
+  "mac_hex": "<64位小写十六进制HMAC>"
+}
+```
+
+`payload_b64` 验签后解码字段：
+
+| 字段 | 类型 | 中文含义 | 来源／怎么用 |
+| --- | --- | --- | --- |
+| `device_id` | string | 设备编号回显 | 核对等于本次请求及本机编号。 |
+| `boot_id` | string（UUID） | 启动编号回显 | 核对等于设备本次启动编号。 |
+| `client_nonce` | string | 随机数回显 | 核对等于本次新请求的随机数。 |
+| `challenge_id` | string（UUID） | 注册挑战编号 | 由平台生成并返回，保存后传入 C02。 |
+| `server_time_ms` | integer | 经过认证的平台时间 | 平台可信时钟生成；全部校验通过后设置设备时钟。 |
+| `expires_at_ms` | integer | 挑战到期时间 | 平台签发时间加 120 秒，到期后重新 C01。 |
+
+```json
+{
+  "device_id": "KP01-AABBCCDDEEFF",
+  "boot_id": "<本次启动UUID>",
+  "client_nonce": "<本次请求随机数>",
+  "challenge_id": "<注册挑战UUID>",
+  "server_time_ms": 1789092000000,
+  "expires_at_ms": 1789092120000
+}
+```
+
+校验公式：`HMAC-SHA256(device_key, UTF8("TIME1\n" + payload_b64))`，其中 `\n` 表示一个 LF 换行。附件 B 要求设备核对全部回显字段、单调计时 RTT 不超过 10 秒、时间不早于固件或已保存可信时间允许的下限；通过后校时，再开始 HTTPS。
+
+## C02 设备认证与启动登记
+
+`POST /api/v1/device/register`
+
+用途：认证已有设备身份并登记本次启动；重复请求不新建设备、不清空既有归属。
+
+### 输入字段
+
+| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- | --- | --- |
+| `challenge_id` | string（UUID） | 是 | 注册挑战 | 取 C01 验签后解码对象中的 `challenge_id`。 |
+| `boot_id` | string（UUID） | 是 | 本次启动编号 | 沿用同一次 C01 的 `boot_id`。 |
+| `hardware_model` | string，≤32字节 | 是 | 设备型号 | 从出厂配置读取，按真实型号填写。 |
+| `hardware_revision` | string，≤16字节 | 是 | 硬件版本 | 读取出厂记录的硬件修订号。 |
+| `firmware_version` | string，≤32字节 | 是 | 固件版本 | 读取设备当前实际运行的固件版本。 |
+| `sdk_version` | string，≤64字节 | 是 | SDK版本 | 读取设备实际集成的 SDK 版本信息。 |
+
+输入示例：
+
+```json
+{
+  "challenge_id": "<C01挑战UUID>",
+  "boot_id": "<本次启动UUID>",
+  "hardware_model": "KP01",
+  "hardware_revision": "A1",
+  "firmware_version": "1.0.0",
+  "sdk_version": "1.0.0"
+}
+```
+
+### 输出字段
+
+下表字段位于普通响应的 `data` 中。
+
+| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
+| --- | --- | --- | --- |
+| `state` | object | 当前设备状态 | 平台返回已有记录的最新状态，完整字段见公共状态表。 |
+| `contract_version` | string | 协议版本 | 原文规定 `ONBOARDING-1.1`；用于确认两侧接口口径。 |
+
+输出示例：
+
+```json
+{
+  "state": {
+    "device_id": "KP01-AABBCCDDEEFF",
+    "device_revision": 3,
+    "binding_generation": 0,
+    "binding_state": "UNBOUND",
+    "activation_state": "NOT_STARTED",
+    "state_hash": "<本版状态SHA256摘要>"
+  },
+  "contract_version": "ONBOARDING-1.1"
+}
+```
+
+## C03 创建设置会话
+
+`POST /api/v1/device/setup-sessions`
+
+用途：为本次设置建立平台会话；已绑定设备可恢复上下文，但不能借此重新认领。
+
+### 输入字段
+
+| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- | --- | --- |
+| `boot_id` | string（UUID） | 是 | 本次启动编号 | 沿用已完成 C02 的启动编号。 |
+| `local_setup_id` | string（UUID） | 是 | 本地设置编号 | 设备为本次设置流程生成；重试和 C04 沿用。 |
+| `transport_profile` | string | 是 | 本地交互方式 | 按原文固定传 `LOCAL_WEB`。 |
+
+输入示例：
+
+```json
+{
+  "boot_id": "<本次启动UUID>",
+  "local_setup_id": "<设备生成的本地设置UUID>",
+  "transport_profile": "LOCAL_WEB"
+}
+```
+
+### 输出字段
+
+下表字段位于普通响应的 `data` 中。
+
+| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
+| --- | --- | --- | --- |
+| `setup_id` | string（UUID） | 平台设置会话编号 | 平台生成，后续传 C04、C05、C11；不同于设备生成的 local_setup_id。 |
+| `expires_at_ms` | integer | 设置会话到期时间 | 平台生成；默认 15 分钟，原文绝对上限 30 分钟，设备以返回期限为准。 |
+| `poll_after_ms` | integer | 建议轮询间隔，毫秒 | 平台返回；绑定期间原文默认 2000。 |
+| `state` | object | 当前设备状态 | 平台返回，完整字段见公共状态表。 |
+
+输出示例：
+
+```json
+{
+  "setup_id": "<平台设置会话UUID>",
+  "expires_at_ms": 1789092900000,
+  "poll_after_ms": 2000,
+  "state": {
+    "device_id": "KP01-AABBCCDDEEFF",
+    "device_revision": 3,
+    "binding_generation": 0,
+    "binding_state": "UNBOUND",
+    "activation_state": "NOT_STARTED",
+    "state_hash": "<本版状态SHA256摘要>"
+  }
+}
+```
+
+## C04 取得一次性手机入口
+
+`POST /api/v1/device/handoffs`
+
+用途：设备取得 SaaS 绑定入口，并交给当前已授权的本地会话。
+
+### 输入字段
+
+| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- | --- | --- |
+| `setup_id` | string（UUID） | 是 | 平台设置会话编号 | 取 C03 的 `data.setup_id`。 |
+| `local_setup_id` | string（UUID） | 是 | 本地设置编号 | 沿用 C03 请求中的同名字段。 |
+| `code_challenge` | string | 是 | 入口校验摘要 | 设备生成32字节随机值并编码为 verifier；对 verifier 的 ASCII 字节算 SHA256，再编码为 Base64URL。 |
+
+输入示例：
+
+```json
+{
+  "setup_id": "<C03设置会话UUID>",
+  "local_setup_id": "<C03本地设置UUID>",
+  "code_challenge": "<32字节SHA256结果的Base64URL>"
+}
+```
+
+### 输出字段
+
+下表字段位于普通响应的 `data` 中。
+
+| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
+| --- | --- | --- | --- |
+| `handoff_token` | string | 一次性入口令牌 | 平台生成32字节随机值并编码；设备把它放进入口链接。 |
+| `expires_at_ms` | integer | 令牌到期时间 | 平台生成，原文有效期90秒；不能由设备自行延长。 |
+| `entry_url` | string | SaaS绑定页面地址 | 由平台固定配置的 HTTPS 白名单入口。 |
+
+输出示例：
+
+```json
+{
+  "handoff_token": "<平台一次性令牌>",
+  "expires_at_ms": 1789092090000,
+  "entry_url": "https://saas.example/onboarding/entry"
+}
+```
+
+设备自己保留 `verifier`，不是向平台多传一个字段。交给手机的完整链接为：
+
+```text
+<entry_url>#token=<handoff_token>&verifier=<设备生成的verifier>
+```
+
+## C05 查询状态和命令
+
+`POST /api/v1/device/poll`
+
+用途：设备查询当前状态，领取绑定确认命令或激活配置；查询本身不代表用户按键或 SDK 执行完成。
+
+### 输入字段
+
+| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- | --- | --- |
+| `setup_id` | string（UUID） | 是 | 平台设置会话编号 | 取 C03 返回的设置会话编号。 |
+| `boot_id` | string（UUID） | 是 | 本次启动编号 | 沿用本次已经注册的启动编号。 |
+| `known_revision` | integer | 是 | 设备已知状态版本 | 取最近返回的 `state.device_revision`；首次不知道时传0。按原文该字段必填。 |
+
+输入示例：
+
+```json
+{
+  "setup_id": "<C03设置会话UUID>",
+  "boot_id": "<本次启动UUID>",
+  "known_revision": 3
+}
+```
+
+### 输出字段
+
+下表字段位于普通响应的 `data` 中。
+
+| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
+| --- | --- | --- | --- |
+| `state` | object | 当前设备状态 | 平台返回，完整字段见公共状态表。 |
+| `command` | object 或 null | 当前命令 | 平台产生；没有命令时为 null，原文兼容 NONE 类型。命令子字段见下表。 |
+| `poll_after_ms` | integer | 下次轮询间隔，毫秒 | 由平台返回；绑定阶段默认2秒，普通待机不保持高频轮询。 |
+
+输出示例：
+
+```json
+{
+  "state": {
+    "device_id": "KP01-AABBCCDDEEFF",
+    "device_revision": 3,
+    "binding_generation": 0,
+    "binding_state": "UNBOUND",
+    "activation_state": "NOT_STARTED",
+    "state_hash": "<本版状态SHA256摘要>"
+  },
+  "command": null,
+  "poll_after_ms": 2000
+}
+```
+
+### `command` 命令字段
+
+| 字段 | 类型 | 中文含义 | 来源／怎么用 |
+| --- | --- | --- | --- |
+| `command_id` | string（UUID） | 命令编号 | 平台生成，设备识别重复命令；原文未规定它必须等于申请或激活任务编号。 |
+| `type` | string | 命令类型 | 原文为 NONE、CONFIRM_CLAIM、APPLY_ACTIVATION、UPDATE_STATE、CLOSE_SETUP；按返回类型处理。 |
+| `expires_at_ms` | integer | 命令到期时间 | 平台生成，设备按可信时间判断有效性。 |
+| `payload` | object | 命令数据 | 由平台生成；下面只展开原文明确给出的两种命令内容。 |
+
+`CONFIRM_CLAIM` 的 `payload`：
+
+| 字段 | 类型 | 中文含义 | 来源／怎么用 |
+| --- | --- | --- | --- |
+| `claim_id` | string（UUID） | 绑定申请编号 | 平台产生，设备从此处获取后传 C06。 |
+| `challenge` | string | 按键挑战 | 平台生成32字节随机值编码，真实按键后 C06 原样回传。 |
+| `binding_digest` | string | 固定绑定内容摘要 | 平台计算64位 SHA256 小写十六进制，设备不改写，C06 原样回传。 |
+| `masked_account` | string | 脱敏账号提示 | 平台生成，例如“尾号1234”，供用户确认当前申请。 |
+| `expected_binding_generation` | integer | 预期绑定代数 | 平台在建立申请时确定；C06 原样回传。 |
+
+```json
+{
+  "command_id": "<命令UUID>",
+  "type": "CONFIRM_CLAIM",
+  "expires_at_ms": 1789092120000,
+  "payload": {
+    "claim_id": "<绑定申请UUID>",
+    "challenge": "<32字节随机值的Base64URL>",
+    "binding_digest": "<固定绑定内容SHA256>",
+    "masked_account": "尾号1234",
+    "expected_binding_generation": 0
+  }
+}
+```
+
+`APPLY_ACTIVATION` 的 `payload` 按原文只列配置封装：
+
+| 字段 | 类型 | 中文含义 | 来源／怎么用 |
+| --- | --- | --- | --- |
+| `config_b64` | string | 激活配置包 | 平台生成配置 JSON 并编码；设备验签后解码，下方列出解码字段。 |
+| `config_mac` | string | 配置认证码 | 平台计算 `HMAC-SHA256(device_key, UTF8("CFG1\n" + config_b64))` 的十六进制值；其中 \n 表示一个 LF，设备用本机密钥验证。 |
+
+配置包验签解码后的字段，依据附件 E.2：
+
+| 字段 | 类型 | 中文含义 | 来源／怎么用 |
+| --- | --- | --- | --- |
+| `contract_version` | string | 配置协议版本 | 原文为 `ONBOARDING-1.1`。 |
+| `device_id` | string | 配置所属设备 | 平台读取生产记录，设备核对与本机一致。 |
+| `activation_id` | string（UUID） | 激活任务编号 | 平台创建并保留；设备从配置包中取出，后续 C08、C09、C10 使用。 |
+| `config_version` | integer | 激活配置版本 | 平台生成；后续 C08、C10 使用，不自行写死。 |
+| `binding_generation` | integer | 配置对应绑定代数 | 平台维护；与当前公共状态核对，防止使用旧归属配置。 |
+| `expires_at_ms` | integer | 配置到期时间 | 由平台签发，设备不得用过期配置开始新的首次激活；原文未在此规定统一24小时有效期。 |
+| `iot` | object | 供应商注册资料 | 平台组装，子字段如下。 |
+| `iot.instance_id` | string | 供应商实例编号 | 来自平台保存的实例配置。 |
+| `iot.product_key` | string | 供应商产品标识 | 来自平台保存的产品配置。 |
+| `iot.product_secret` | string | 受保护的产品注册密钥 | 这是原文 E.2 明确列出的字段；设备通过受保护配置取得，供原文 SDK 注册流程使用；与当前代码方案的差异见单独说明。 |
+| `iot.device_name` | string | 物理设备在供应商侧的固定名称 | 由 SaaS 首次激活前生成并永久记录，设备原样使用；不随账号、重试、重启更换。 |
+| `bot_id` | string | 共享智能体编号 | 来自平台配置，设备按对应 SDK 要求使用。 |
+
+原文要求配置仅经设备 HTTPS 下发，落地使用加密 NVS，不交给手机或写入普通日志。该表没有增加当前代码中的其他运行配置字段。
+
+## C06 设备按键确认绑定
+
+`POST /api/v1/device/claim-confirmations`
+
+用途：用户真实按下设备确认键后，设备提交本次确认，平台正式建立归属关系。
+
+### 输入字段
+
+| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- | --- | --- |
+| `claim_id` | string（UUID） | 是 | 绑定申请编号 | 取 C05 同一确认命令的 `payload.claim_id`。 |
+| `challenge` | string | 是 | 按键挑战 | 取该命令的 `payload.challenge`，原样回传。 |
+| `binding_digest` | string，64位hex | 是 | 绑定内容摘要 | 取该命令同名字段，原样回传。 |
+| `expected_binding_generation` | integer | 是 | 预期绑定代数 | 取该命令同名字段，不能自行加一。 |
+| `press_event_id` | string（UUID） | 是 | 本次真实按键事件编号 | 设备在真实按键发生时生成并保存，网络重试沿用。 |
+
+输入示例：
+
+```json
+{
+  "claim_id": "<C05申请UUID>",
+  "challenge": "<C05按键挑战>",
+  "binding_digest": "<C05绑定摘要>",
+  "expected_binding_generation": 0,
+  "press_event_id": "<设备实际按键UUID>"
+}
+```
+
+### 输出字段
+
+下表字段位于普通响应的 `data` 中。
+
+| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
+| --- | --- | --- | --- |
+| `claim_id` | string（UUID） | 已处理的绑定申请 | 平台返回，设备核对是本次申请。 |
+| `state` | object | 处理后的归属及激活状态 | 平台返回；保存对应版本、代数和摘要后调用 C07。 |
+| `already_applied` | boolean | 该确认是否已经提交过 | 由平台识别重复相同申请的结果；不可据此产生第二次绑定。 |
+
+输出示例：
+
+```json
+{
+  "claim_id": "<绑定申请UUID>",
+  "state": {
+    "device_id": "KP01-AABBCCDDEEFF",
+    "device_revision": 4,
+    "binding_generation": 1,
+    "binding_state": "BOUND",
+    "activation_state": "RESERVED",
+    "state_hash": "<本版状态SHA256摘要>"
+  },
+  "already_applied": false
+}
+```
+
+## C07 确认绑定状态已保存
+
+`POST /api/v1/device/state-acks`
+
+用途：报告设备已经保存平台状态，不根据此回执修改 owner。
+
+### 输入字段
+
+| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- | --- | --- |
+| `device_revision` | integer | 是 | 已保存状态版本 | 取同一版 `state.device_revision`。 |
+| `binding_generation` | integer | 是 | 已保存绑定代数 | 取同一版 `state.binding_generation`。 |
+| `local_generation` | integer | 是 | 本地保存序号 | 由设备本地保存模块产生并在保存成功后记录，不用平台版本号代替。 |
+| `state_hash` | string，64位hex | 是 | 已保存状态摘要 | 取同一版 `state.state_hash` 并核对实际保存内容。 |
+
+输入示例：
+
+```json
+{
+  "device_revision": 4,
+  "binding_generation": 1,
+  "local_generation": 1,
+  "state_hash": "<已保存状态摘要>"
+}
+```
+
+### 输出字段
+
+下表字段位于普通响应的 `data` 中。
+
+| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
+| --- | --- | --- | --- |
+| `accepted_revision` | integer | 平台接受的保存版本 | 平台确认后返回，设备可记录该版已完成回执。 |
+| `setup_can_close` | boolean | 是否可以收尾 | 平台根据回执和流程条件判断；设备按结果执行收尾。 |
+
+输出示例：
+
+```json
+{
+  "accepted_revision": 4,
+  "setup_can_close": false
+}
+```
+
+原文收尾条件：页面与设备都确认后等待3秒，或设备确认后最多30秒。这里保留原文的布尔判断，不新增等待时间或后续动作字段。
+
+## C08 申请 SDK 执行许可
+
+`POST /api/v1/device/activation-attempts`
+
+用途：平台先记录本次可能执行的事实，再决定是否允许本次 SDK 调用，避免不确定结果下重复执行。
+
+### 输入字段
+
+| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- | --- | --- |
+| `activation_id` | string（UUID） | 是 | 激活任务编号 | 从 C05 激活配置包解码后的 `activation_id` 取得。 |
+| `config_version` | integer | 是 | 本次使用的配置版本 | 从同一份已验证配置的 `config_version` 取得。 |
+| `attempt_id` | string（UUID） | 是 | 一次 SDK 执行编号 | 设备为本次实际执行生成并保留；本次请求重试沿用，不重新申请第二次执行。 |
+
+输入示例：
+
+```json
+{
+  "activation_id": "<配置包中的激活任务UUID>",
+  "config_version": 1,
+  "attempt_id": "<设备生成的执行UUID>"
+}
+```
+
+### 输出字段
+
+下表字段位于普通响应的 `data` 中。
+
+| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
+| --- | --- | --- | --- |
+| `allowed` | boolean | 是否允许本次执行 | 平台判断后返回；只有 true 才能开始此次 SDK 调用。 |
+| `attempt_id` | string（UUID） | 许可对应执行编号 | 平台返回本次执行编号，后续 C09 使用。 |
+| `permit_expires_at_ms` | integer | 许可到期时间 | 原文 I.1 规定许可有效期30秒；超窗重新查询，不能推断先前调用一定没有执行。 |
+| `state` | object | 当前设备状态 | 平台返回，完整字段见公共状态表。 |
+
+输出示例：
+
+```json
+{
+  "allowed": true,
+  "attempt_id": "<本次执行UUID>",
+  "permit_expires_at_ms": 1789092030000,
+  "state": {
+    "device_id": "KP01-AABBCCDDEEFF",
+    "device_revision": 5,
+    "binding_generation": 1,
+    "binding_state": "BOUND",
+    "activation_state": "CONTACT_POSSIBLE",
+    "state_hash": "<本版状态SHA256摘要>"
+  }
+}
+```
+
+## C09 上报激活执行结果
+
+`POST /api/v1/device/activation-results`
+
+用途：上报已获许可的实际 SDK 执行结果。超时或无法确定结果时上报 UNKNOWN，不能当作明确失败重复执行。
+
+### 输入字段
+
+| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- | --- | --- |
+| `activation_id` | string（UUID） | 是 | 激活任务编号 | 沿用 C08 所属任务编号。 |
+| `attempt_id` | string（UUID） | 是 | 实际执行编号 | 沿用 C08 已申请并返回的执行编号，不在上报时重新生成。 |
+| `stage` | string | 是 | 执行阶段 | 按原文 I.1 填 `SDK_REGISTER` 或 `CONVERSATION_TEST`，由设备依据本次实际执行操作确定。 |
+| `sdk_result` | integer | 是 | SDK返回码 | 读取本次实际 SDK 调用或回调结果，不编造结果码。 |
+| `outcome` | string | 是 | 本次结果分类 | 原文取值：`SUCCESS_OBSERVED` 已观察到成功、`DEFINITE_FAILURE` 明确失败、`UNKNOWN` 未知。 |
+
+输入示例：
+
+```json
+{
+  "activation_id": "<激活任务UUID>",
+  "attempt_id": "<C08执行UUID>",
+  "stage": "SDK_REGISTER",
+  "sdk_result": 0,
+  "outcome": "SUCCESS_OBSERVED"
+}
+```
+
+### 输出字段
+
+下表字段位于普通响应的 `data` 中。
+
+| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
+| --- | --- | --- | --- |
+| `activation_id` | string（UUID） | 结果所属任务 | 平台返回，设备与本次任务核对。 |
+| `state` | object | 处理后的设备状态 | 平台返回，判断仍在激活、待处理或已 READY。 |
+| `reconcile_required` | boolean | 是否需要对账 | 平台根据本次结果判定；true 时不要自行开始第二次同类激活执行。 |
+
+输出示例：
+
+```json
+{
+  "activation_id": "<激活任务UUID>",
+  "state": {
+    "device_id": "KP01-AABBCCDDEEFF",
+    "device_revision": 6,
+    "binding_generation": 1,
+    "binding_state": "BOUND",
+    "activation_state": "REGISTERED_OBSERVED",
+    "state_hash": "<本版状态SHA256摘要>"
+  },
+  "reconcile_required": false
+}
+```
+
+首次通话测试时使用 `stage=CONVERSATION_TEST`。结果分类只表示这一次执行的事实，不等同于设备最终状态；服务是否可用仍读取 `state.activation_state`。
+
+## C10 确认激活结果已保存
+
+`POST /api/v1/device/activation-acks`
+
+用途：设备确认激活结果已在本地保存；重复相同回执不产生新的激活副作用。
+
+### 输入字段
+
+| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- | --- | --- |
+| `activation_id` | string（UUID） | 是 | 已保存结果所属任务 | 沿用配置包及 C09 对应的激活任务编号。 |
+| `local_generation` | integer | 是 | 本地保存序号 | 由设备保存模块在本次结果保存成功后记录，不使用配置版本代替。 |
+| `config_version` | integer | 是 | 结果对应配置版本 | 沿用本次激活实际使用的配置包版本。 |
+
+输入示例：
+
+```json
+{
+  "activation_id": "<激活任务UUID>",
+  "local_generation": 2,
+  "config_version": 1
+}
+```
+
+### 输出字段
+
+下表字段位于普通响应的 `data` 中。
+
+| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
+| --- | --- | --- | --- |
+| `accepted` | boolean | 回执是否被接受 | 由平台验证后返回。 |
+| `state` | object | 当前设备状态 | 平台返回，完整字段见公共状态表。 |
+
+输出示例：
+
+```json
+{
+  "accepted": true,
+  "state": {
+    "device_id": "KP01-AABBCCDDEEFF",
+    "device_revision": 6,
+    "binding_generation": 1,
+    "binding_state": "BOUND",
+    "activation_state": "REGISTERED_OBSERVED",
+    "state_hash": "<本版状态SHA256摘要>"
+  }
+}
+```
+
+## C11 设置流程收尾
+
+`POST /api/v1/device/setup-close`
+
+用途：请求或报告本次设置流程收尾。关闭临时入口不清空已提交的绑定或激活任务。
+
+### 输入字段
+
+| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
+| --- | --- | --- | --- | --- |
+| `setup_id` | string（UUID） | 是 | 要关闭的设置会话 | 取本次 C03 返回的 `setup_id`。 |
+| `reason` | string | 是 | 关闭原因 | 设备按实际情况填 SUCCESS、TIMEOUT、CANCELLED 或 NETWORK_SWITCH。 |
+| `final_revision` | integer | 是 | 关闭前最后收到的状态版本 | 取最后成功收到的 `state.device_revision`，不是设备本地保存序号。 |
+
+输入示例：
+
+```json
+{
+  "setup_id": "<C03设置会话UUID>",
+  "reason": "SUCCESS",
+  "final_revision": 6
+}
+```
+
+### 输出字段
+
+下表字段位于普通响应的 `data` 中。
+
+| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
+| --- | --- | --- | --- |
+| `close_allowed` | boolean | 是否允许关闭 | 平台判定并返回，设备据此执行关闭。 |
+| `state` | object | 当前设备状态 | 平台返回并保留正式绑定及激活事实，便于后续恢复。 |
+
+输出示例：
+
+```json
+{
+  "close_allowed": true,
+  "state": {
+    "device_id": "KP01-AABBCCDDEEFF",
+    "device_revision": 6,
+    "binding_generation": 1,
+    "binding_state": "BOUND",
+    "activation_state": "REGISTERED_OBSERVED",
+    "state_hash": "<本版状态SHA256摘要>"
+  }
+}
+```
+
+## 字段从哪里取得
+
+| 要使用的字段 | 取值来源 |
+| --- | --- |
+| `device_id`、`device_key`、`key_version` | 设备出厂写入的身份及凭据。 |
+| `boot_id` | 设备每次启动生成。 |
+| `challenge_id` | C01 验签后的校时包。 |
+| `local_setup_id` | 设备为一次本地设置生成。 |
+| `setup_id` | C03 平台返回。 |
+| `claim_id`、`challenge`、`binding_digest`、预期绑定代数 | 同一条 C05 确认命令，不跨命令拼接。 |
+| `press_event_id` | 设备真实按键时生成。 |
+| `activation_id`、`config_version` | C05 激活配置包验签解码后取得。 |
+| `attempt_id` | 设备为一次 SDK 执行生成，C08 申请、C09 沿用。 |
+| `local_generation` | 设备保存模块记录本地保存完成的序号。 |
+| `device_revision`、`binding_generation`、`state_hash` | 平台返回的同一版公共状态。 |
+
+## 平台如何确定 C08 执行阶段
+
+C08 不增加阶段字段。平台按任务中已确认的事实判定：尚未观察到注册成功时，许可用于 `SDK_REGISTER`；已注册且 C10 确认保存后，许可用于 `CONVERSATION_TEST`。C09 的阶段必须匹配平台为该执行编号记录的阶段。已完成 READY 的同代绑定不再发放首次激活许可。
+
+原文未给出部分命令的完整 payload，当前实际下发 `CONFIRM_CLAIM`、`APPLY_ACTIVATION` 两种命令，其余保留枚举不作为新增接口功能。
+来源：[原始流程文档](<D:/wechat/xwechat_files/wangcong3092_983b/msg/file/2026-09/AI电话_首次配网注册与激活_完整流程与详细设计(1).docx>)，重点是附件 B（认证及校时）、C（设备接口）、E（状态和配置）、I.1（逐接口输入与输出）。
@@ -0,0 +1,473 @@
+# 首次配网设备认证与绑定 SaaS 修改方案
+
+版本：方案草案 1.0　日期：2026 年 9 月 11 日
+
+本方案用于把当前平台改造成支持设备首次认证、手机登录交接、实体按键确认绑定和独立 AI 激活的 SaaS。修改以现有 Go 服务、PostgreSQL、Redis、React、OIDC、设备绑定及供应商凭据模块为基础，分阶段交付，保留旧设备协议。
+
+最终用户流程是：设备联网并认证，手机进入 SaaS 登录并选择使用者，用户按设备按键确认，SaaS 保存绑定，设备保存结果并回执，AI 服务随后独立开通。激活失败时显示“已绑定，AI 服务待处理”，用户不必重新配网或绑定。
+
+本文是一份待实施的设计，不代表接口、数据库或页面已经修改。依据为用户提供的 ONBOARDING-1.1 首次接入文档、上一份差异分析和当前工作区代码。接口、数据表、配置项及模块名称标注为新增或拟新增的，均属于本方案建议。
+
+## 1 方案采用的实现路线
+
+| 决策 | 采用的方案 | 原因及影响 |
+|---|---|---|
+| 设备身份 | 保留数据库 UUID，新增唯一工厂编号和 MAC 映射 | 兼容现有业务外键、通话和管理接口 |
+| 新设备认证 | 新增 DEVREQ1 验签，使用原始 32 字节密钥 | 与附件认证算法衔接；旧设备原签名和密钥解释不变 |
+| 账号归属 | 延续租户、家庭、使用者模型；绑定人从当前登录态取得 | 复用权限服务，防止跨租户或任意指定 owner |
+| 绑定方式 | 新设备必须走当前申请的设备按键确认 | 绑定码、运维分配等旧入口不能绕过该规则 |
+| 手机登录 | 首先接入现有 OIDC 完成联调，完整交付补短信登录和注册 | 先验证绑定业务；短信未完成时不宣称覆盖附件的全部手机流程 |
+| AI 激活 | 推荐保留 SaaS 代注册，再向设备下发 DeviceSecret | 复用当前供应商集成；ProductSecret 留在服务端 |
+| 任务执行 | 绑定与 outbox 同事务，外部调用在独立 worker 中执行 | 回包丢失或进程退出仍能恢复原任务 |
+| 上线方式 | 按设备或产线批次启用新协议，先发布兼容保护版本 | 保证旧设备持续运行，也保证新设备不能降级绕过确认 |
+
+由于激活执行位置与原文档不同，建议把最终新契约暂命名为 `ONBOARDING-1.2-SAAS`，待双方联调后冻结。该名称是本方案的拟定版本，不是现有已发布协议。
+
+### 1.1 与附件的明确调整
+
+1. C01 至 C07、C11 的业务顺序和 DEVREQ1/TIME1/STATE1 计算保留；公共状态额外返回 platform_device_id，说明内部 UUID 与工厂编号的关系。
+2. C08 至 C10 调整为设备引擎初始化或首通测试的许可、结果和配置保存回执；供应商注册由 SaaS worker 执行并记录证据。不得继续用设备上报 SDK_REGISTER 来表示服务端代注册结果。
+3. 激活配置使用 device_secret，不下发 product_secret；完整性仍采用 CFG1，包含设备、绑定代数、任务、版本和期限。
+4. OIDC 是第一阶段的账号接入路径；短信是完整交付的一部分。两者最后映射到同一平台账号和家庭权限模型。
+5. 新设备进行日常通话时继续复用现有会话服务，设备入口增加显式协议路由与统一身份解析，不能让设备在进入通话阶段突然改用未经配置的另一套密钥。
+
+若后续要求逐字段保持 ONBOARDING-1.1，则需要另行选择设备执行动态注册路线，恢复附件的 C08 至 C10 和 ProductSecret 配置语义；不能把两种执行模式混在同一个协议版本里。当前方案仅规划 SaaS 代注册这一条实施主线。
+
+### 1.2 SaaS 与设备的工作边界
+
+SaaS 实现库存、凭据、认证、会话交接、账号权限、绑定提交、状态回执、激活任务、对账和运维页面。设备配合生成及保存启动标识、调用新接口、按键确认指定申请、保存状态并 ACK，以及使用平台下发的运行凭据。
+
+家庭 Wi-Fi 密码、AP/NAPT、SSID 扫描、GPIO 和本地 NVS 的实现不进入 SaaS。接口联调需要设备配合，但本方案不安排具体硬件开发。
+
+## 2 修改后的流程及完成条件
+
+| 阶段 | SaaS 提交的事实 | 进入下一阶段的条件 | 失败时保留什么 |
+|---|---|---|---|
+| 生产登记 | 库存、固定身份和受保护凭据 | 烧录校验并受控放行 | 原设备身份，不生成新设备副本 |
+| 设备认证 | 时间挑战已消费、当前启动报告已更新 | 合法 HMAC、挑战、型号和设备状态 | 已有绑定和激活任务 |
+| 手机交接 | setup 已建立、handoff 已兑换 | 有效入口和匹配 verifier | 设备和网络已有结果 |
+| 申请绑定 | 固定账号和使用者的 PENDING claim | 当前账号有管理权限且设备未绑定 | 已完成登录，不提前建立归属 |
+| 提交绑定 | 唯一有效绑定、代数、状态和激活待办 | 设备确认匹配当前 claim | 即使回包丢失，绑定仍成立 |
+| 保存与收尾 | 设备和手机回执、设置入口关闭事实 | 回执条件满足或到达关闭上限 | 绑定、设备凭据和原激活任务 |
+| AI 激活 | 供应商结果、运行配置和验收证据 | 按阶段检查，不以 HTTP 200 统一判断 | 账号绑定及可能已占用的供应商权益 |
+
+手机可以在绑定完成后离开设置页。设备本地保存失败只修复落盘，AI 激活失败只修复激活。普通重配网保留绑定；解绑和转移使用独立业务流程。
+
+## 3 数据库修改
+
+数据库变更先增加字段和新表，再回填，再启用约束及新功能。以下为逻辑设计，正式 migration 编号在开发时按仓库最新序号分配。
+
+### 3.1 扩展现有记录
+
+| 现有记录 | 拟增加的数据 | 约束及用途 |
+|---|---|---|
+| device | enrollment_mode、onboarding_contract、factory_device_id、factory_mac、binding_generation、onboarding_revision | 旧数据默认为 legacy；工厂编号和 MAC 各自唯一；绑定代数和状态版本独立 |
+| device_binding | generation、source、claim_id | device 与 generation 唯一；保留当前有效绑定唯一索引；claim_id 只对应一次提交 |
+| 账号身份映射 | 统一的身份提供方、稳定主体和 user_account 关联 | 保留现有 OIDC 映射；短信身份不伪造成某个外部 OIDC 用户 |
+| 审计及事件 | setup/claim/activation/attempt 的关联字段或结构化详情 | 追踪整条首次接入链路，不保存 token、验证码或密钥正文 |
+
+onboarding_revision 在新协议中输出为 device_revision，避免更改现有 device.version、activation_revision、配置 revision 的语义。新表全部使用内部 UUID 做外键，并建立与 tenant_id 一致的组合约束。
+
+### 3.2 新增的逻辑记录
+
+| 拟新增表 | 关键字段 | 必须具备的约束 |
+|---|---|---|
+| device_inventory | device_id、factory_device_id、factory_mac、tenant_id、型号、批次、生产状态、放行记录 | MAC 和工厂编号唯一；一个库存只关联一个平台设备 |
+| device_onboarding_credential | device_id、key_version、encrypted_key、nonce、key_ref、status、activated_at | device/key_version 唯一；只允许一个当前有效版本；密钥是原始 32 字节 |
+| device_enrollment_job | job_id、device_id、request_digest、烧录包引用、校验及交付状态 | 重复登记不换身份；受保护交付结果可按原任务恢复 |
+| device_time_challenge | device_id、key_version、boot_id、client_nonce、签发和到期时间、consumed_by_request | 绑定设备与启动；挑战只消费一次；可关联同一已提交注册请求 |
+| device_onboarding_state | device_id、binding_state、activation_state、current_activation_id、last_boot_id、state_hash | 每设备一条；与 revision 和当前有效绑定在事务内一致更新 |
+| device_setup_session | setup_id、device_id、boot_id、local_setup_id、mode、expires_at、absolute_expires_at、closed_at | 当前流程模式为 ENROLL 或 RECOVERY；已绑定设备只能恢复 |
+| device_handoff | token_hash、setup_id、code_challenge、expires_at、consumed_at | token 哈希唯一；一次兑换；不得生成第二个可复活的入口 |
+| web_setup_session | session_hash、setup_id、认证账号引用、CSRF 信息、期限、撤销时间 | 浏览器只访问当前流程；登录后旋转会话标识 |
+| device_binding_claim | claim_id、device_id、setup_id、目标账号/家庭/使用者、challenge_hash、加密挑战、binding_digest、expected_generation、status、expires_at、press_event_id、result_binding_id | 每设备最多一条 PENDING；已成功申请长期去重；按键事件不能确认第二个申请 |
+| device_state_snapshot / device_state_ack | device_id、revision、binding_generation、state_hash、local_generation、boot_id、保存及接收时间 | 快照不可变；重复相同 ACK 无副作用；旧 ACK 不覆盖当前状态 |
+| device_setup_web_ack | setup_id、binding_id、binding_generation、received_revision、received_at | 记录页面看到了哪次绑定；与设备 ACK 独立 |
+| device_activation_job | activation_id、device_id、provider_identity_id、状态、配置版本、当前 attempt、权益引用 | 每设备只有一个当前激活任务；终态和历史保留 |
+| device_activation_attempt | attempt_id、activation_id、executor、stage、permit_deadline、fence_version、结果和证据 | executor 区分 SERVER/DEVICE；attempt 唯一；超时不自动授予第二次可能重复的调用 |
+| provider_device_identity / activation_entitlement | 固定 device_name、供应商产品、状态、预留或对账证据 | 设备身份不因换用户重建；额度扣占必须事务化且有业务去重键 |
+
+可以复用现有供应商凭据表保存加密 DeviceSecret，在请求供应商之前先持久化 provider_device_identity。权益模型与当前 License 内容表分开处理，不能把文件导入记录当成供应商已确认授权。
+
+新 credential 表避免直接破坏现有 device_credential 按设备唯一的结构。旧密钥继续由旧解析器读取，新密钥由版本化解析器读取；共用加密基础时分别定义包含协议和版本的 AAD。
+
+### 3.3 唯一约束示意
+
+以下 SQL 用于表达约束，不是可直接执行的 migration：
+
+```sql
+CREATE UNIQUE INDEX device_binding_claim_one_pending
+ON device_binding_claim (device_id)
+WHERE status = 'PENDING';
+
+CREATE UNIQUE INDEX device_binding_generation_unique
+ON device_binding (device_id, generation);
+
+CREATE UNIQUE INDEX device_activation_one_current
+ON device_activation_job (device_id)
+WHERE is_current = true;
+```
+
+不要在部分索引条件中使用 now()。创建新申请前，在设备锁内把已过期 PENDING 更新为 EXPIRED；后台清理只能辅助，不能作为并发正确性的前提。
+
+### 3.4 绑定代数和历史回填
+
+新设备初始 generation=0；首次绑定变为 1；解绑增加一次；重新绑定再增加一次。第一版转移走“原账号授权解绑，再由目标账号和设备确认新绑定”，不提供绕过确认的一步换主。
+
+存量绑定按稳定的 bound_at、id 顺序建立迁移映射，考虑中间解绑事件，为当前归属确定唯一有效代数。不能把所有历史记录统一回填为 1。历史证据不足的设备保留 legacy 模式，待受控迁移时设置并审计基线；不凭推测补造过去的按键或验收证据。
+
+## 4 生产登记和认证修改
+
+### 4.1 新增生产管理入口
+
+以下路径为本方案新增建议，由受控生产服务账号或具备相应能力的运维账号调用，鉴权与设备请求分开。
+
+| 方法与路径 | 请求数据 | 返回和效果 |
+|---|---|---|
+| POST /api/v1/ops/device-inventory | factory_mac、hardware_model、hardware_revision、batch_no、目标租户；Idempotency-Key | 服务端生成 factory_device_id，建立或核对原库存；返回内部 UUID 和 enrollment_job_id |
+| POST /api/v1/ops/device-inventory/{id}/credential-deliveries | enrollment_job_id、受控产线接收方和交付用途 | 返回仅产线可解密的烧录包或受控交付引用；不在普通列表返回密钥 |
+| POST /api/v1/ops/device-inventory/{id}/release | 校验记录引用、expected_version | 已完成烧录校验后放行，允许首次云端认证 |
+| POST /api/v1/ops/device-inventory/{id}/credential-rotations | reason、expected_key_version、交付接收方 | 创建新版本交付任务，确认后切换版本，旧版本撤销 |
+
+同 MAC 再登记时返回同一库存和设备；型号、租户或板卡记录冲突返回 409，不静默覆盖。返修使用原登记任务或受控恢复任务；不因响应丢失重新生成密钥。烧录包有效期、访问授权和销毁均可审计，普通幂等响应只保存任务引用。
+
+放行前设备可以处于现有 FACTORY 状态；放行后同步为 CLAIMABLE，避免被当前认证门禁拒绝。尚未通过生产校验的设备不得因请求 C01 而自动放行。
+
+### 4.2 新鉴权组件
+
+新增 `internal/onboardingauth`，读取以下头：X-Device-ID、X-Key-Version、X-Timestamp-Ms、X-Nonce、X-Request-ID、Authorization。DEVREQ1 九行签名按附件原始 body 字节计算；时间容差 ±120 秒；nonce 按设备和版本至少保存 5 分钟。
+
+处理顺序固定为：限制体积和格式 → 查生产放行记录和凭据版本 → 恒定时间验签 → 时间窗口 → 原子 nonce 防重放 → 设备及租户当前状态 → 业务幂等 → 业务事务。新设备请求拒绝 query 参数，JSON 拒绝重复键、非法 UTF-8 和超过 12 层嵌套，普通报文 8 KiB、配置 32 KiB。
+
+限流在昂贵验签之前先按来源执行，通过认证后再按设备执行。Redis 不可用时不能跳过防重放，返回可重试的服务不可用。公开工厂编号和 MAC 只用于定位记录，不构成认证证据。
+
+身份解析器输出内部 device UUID、tenant UUID、工厂编号、协议和密钥版本。现有内部服务继续按 UUID 访问数据库，新协议对外的 device_id 使用工厂编号，platform_device_id 明确返回管理及历史资源所用的 UUID。
+
+### 4.3 C01 与 C02
+
+C01 允许专用 HTTP 校时入口，只返回 `payload_b64` 与 `mac_hex`，签名域为 TIME1；其他业务必须 HTTPS。部署时给 C01 单独路由，不能把整个 /api/v1/device/ 路径开放为明文业务入口。
+
+挑战包含 device_id、key_version 的服务端关联、boot_id、client_nonce、challenge_id、server_time_ms、expires_at_ms；有效期 120 秒。设备校验新 nonce、回显和 RTT 是联调条件。服务器不接受将 C01 响应当成登录凭证。
+
+C02 使用挑战完成已有身份的上线登记，保存固件和 SDK 版本、当前 boot_id。库存登记已经关联内部设备记录，因此此处更新既有记录，不让公开调用创建设备身份。注册时核对型号和生产记录，不以设备自报值覆盖库存型号。
+
+C02 的 challenge 消费、注册结果和幂等提交在同一事务内完成。已成功请求重试先定位原业务结果，同时复核当前绑定代数和权限；挑战已消费不影响读取该成功结果，新 request_id 则须新挑战。
+
+### 4.4 幂等执行器的必要修改
+
+现有 `internal/idempotency/executor.go` 在命中缓存时直接返回 response_body。新协议必须增加事务内 replay guard，并支持调用方控制事务的 ExecuteTx，保证检查当前状态和读取重试结果之间没有换绑竞争。
+
+作用域建议为 tenant/internal_device/contract/method/path/request_id，摘要采用原始 body。保存 24 小时的是短期请求结果；claim_id、activation_id、attempt_id 的业务唯一记录不随缓存过期删除。
+
+固定操作结果与当前状态分别处理：操作未变化且代数仍有效时返回原结果；设备已换绑、停用或权限变化时返回 409/403 并要求查询最新状态，不把旧状态包装成新结果。对只读 poll/status 不缓存过时状态，每次查询使用新的请求号。
+
+handoff token、设备密钥和 DeviceSecret 不明文存进通用 response_body。短时响应恢复采用独立加密存储，绑定有效期和当前权限；普通幂等记录只保存资源引用。
+
+## 5 设备接口修改清单
+
+以下 11 个 POST 路径保留附件的路径命名；字段标注“新增”的属于拟定 1.2 契约变化，不得对 1.1 客户端隐式启用。C01 使用专用校时协议，其余使用新 HMAC。
+
+| 编号和路径 | body 核心字段 | 实施后的行为 |
+|---|---|---|
+| C01 /api/v1/device/time-challenges | device_id、key_version、boot_id、client_nonce | 返回签名时间及挑战，未知/未放行设备拒绝 |
+| C02 /api/v1/device/register | challenge_id、boot_id、hardware_model、hardware_revision、firmware_version、sdk_version | 验证现有身份，返回契约版本及公共 state |
+| C03 /api/v1/device/setup-sessions | boot_id、local_setup_id、transport_profile=LOCAL_WEB | 未绑定建立 ENROLL；已绑定建立 RECOVERY，恢复原激活任务 |
+| C04 /api/v1/device/handoffs | setup_id、local_setup_id、code_challenge | 仅 ENROLL 签发 90 秒一次性手机入口 |
+| C05 /api/v1/device/poll | setup_id、boot_id、known_revision | 当前 state、有效命令和 poll_after_ms；绑定阶段默认 2 秒 |
+| C06 /api/v1/device/claim-confirmations | claim_id、challenge、binding_digest、expected_binding_generation、press_event_id | 指定申请确认；事务提交绑定或返回同一有效结果 |
+| C07 /api/v1/device/state-acks | device_revision、binding_generation、local_generation、state_hash | 记录设备保存事实，返回 accepted_revision、setup_can_close |
+| C08 /api/v1/device/activation-attempts | activation_id、config_version、attempt_id；新增 stage | 只签发 ENGINE_INIT/CONVERSATION_TEST 的设备许可；供应商注册许可由 worker 内部执行 |
+| C09 /api/v1/device/activation-results | activation_id、attempt_id、stage、sdk_result、outcome；测试附新增 evidence | 核对同设备尝试和真实会话证据，更新相应阶段；拒绝设备伪报 SERVER_REGISTER |
+| C10 /api/v1/device/activation-acks | activation_id、local_generation、config_version；新增 binding_generation、config_digest | 核对当前绑定和配置，记录设备保存运行配置 |
+| C11 /api/v1/device/setup-close | setup_id、reason、final_revision | 关闭临时入口和未完成申请；保留已绑定关系及激活任务 |
+
+新增协议版本通过生产记录固定，并在 C02 返回。固件只支持 1.1 时不得把 1.2 当作可忽略的小字段更新；必须完成版本能力校验后再使用。
+
+### 5.1 公共状态示例
+
+以下是拟定响应示例，UUID 为演示值，state_hash 由正式状态计算，不能把示例占位符作为测试向量。
+
+```json
+{
+  "ok": true,
+  "code": "OK",
+  "request_id": "f25fcabb-53e4-42c2-ad5b-048775f54414",
+  "server_time_ms": 1788681600000,
+  "data": {
+    "contract_version": "ONBOARDING-1.2-SAAS",
+    "state": {
+      "device_id": "KP01-84FCE6123456",
+      "platform_device_id": "b71dd44c-9a4d-4fdc-a4c3-e6921462c443",
+      "device_revision": 4,
+      "binding_generation": 1,
+      "binding_state": "BOUND",
+      "activation_state": "RESERVED",
+      "next_action": "RESUME_ACTIVATION",
+      "state_hash": "<STATE1计算得到的64位小写hex>"
+    }
+  }
+}
+```
+
+新路径使用附件的 ok/code/data 响应封装，旧 API 保留原封装。不要全局修改 WriteJSON 使旧前端和旧设备同时发生响应变化。
+
+### 5.2 首次接入命令
+
+新增独立的 onboarding 命令队列，复用已有投递和去重经验，但不直接塞入只允许四种旧命令的 device_command 约束。
+
+- CONFIRM_CLAIM：固定 claim_id、挑战、binding_digest、masked_account、expected_binding_generation 和期限。
+- APPLY_ACTIVATION：固定 activation_id、config_version、binding_generation、config_digest、config_b64、config_mac 和期限；设备重复收到只同步同版配置。
+- UPDATE_STATE：请求同步较新状态，不改变 owner。
+- CLOSE_SETUP：请求结束临时设置流程，不等于解绑。
+
+命令按设备、setup 模式、代数和到期时间过滤；取消或换绑后立刻失效。挑战及含 DeviceSecret 的命令载荷加密保存，重复投递可恢复原内容，普通日志仅记录命令 ID 和摘要。
+
+## 6 手机接口和账号修改
+
+### 6.1 七个目标接口
+
+以下字段是完整方案拟定的数据契约，补齐附件未写全的短信及回执部分。新 Web 写接口均使用 HTTPS、当前会话、Origin/CSRF 检查与 X-Request-ID。
+
+| POST 路径 | 请求数据 | 响应及限制 |
+|---|---|---|
+| /api/v1/web/handoffs/exchange | token、verifier | 设置临时 Cookie，返回 setup_id、脱敏设备信息及当前阶段；不要求预先登录 |
+| /api/v1/web/auth/sms/send | phone_e164、purpose=LOGIN | 返回 sms_challenge_id、expires_at_ms、resend_after_ms；不泄露号码是否已有账号 |
+| /api/v1/web/auth/sms/verify | sms_challenge_id、code | 原子消费验证码，登录或建立身份映射，旋转 Cookie；保留服务端 setup |
+| /api/v1/web/claims | elder_id、expected_binding_generation | 服务端解析使用者所属家庭，返回 claim_id、期限、等待按键状态 |
+| /api/v1/web/setup/status | 空对象，使用当前 Cookie | 当前 setup 的绑定、设备保存、激活进度和可恢复动作 |
+| /api/v1/web/setup/ack | binding_id、binding_generation、received_revision | 记录页面已看到该绑定；旧绑定的回执不能用于新绑定收尾 |
+| /api/v1/web/claims/cancel | claim_id、expected_binding_generation | 仅取消该会话有权管理的 PENDING；已提交时返回当前已绑定状态 |
+
+第一阶段暂不开放 sms/send 和 sms/verify，改由 OIDC 登录接续接口完成身份衔接。完整发布前补短信提供方适配和真实联调，不能用模拟验证码对外发布。
+
+### 6.2 OIDC 接续及账号权限
+
+第一阶段拟新增 `POST /api/v1/web/setup/auth-link`：接收当前已验证的 OIDC Bearer 凭据，同时核对 setup Cookie 和 CSRF，将平台账号与本 setup 关联并旋转会话。它是 OIDC 适配接口，不替代 handoff 兑换。
+
+完整方案增加统一平台会话解析层。OIDC 身份和已验证短信身份均映射到稳定的平台主体，再从 user_account、household_member 获取权限。仅向明确开放的家庭/档案路由增加平台会话鉴权；Cookie 写请求必须检查 CSRF。旧 Bearer 入口继续按现有方式工作。
+
+现有部分服务直接按 issuer/subject 查询账号，需集中到共同的账号访问解析器，或在可信会话适配层使用明确的自有身份命名空间。不得把未经外部提供方签发的用户伪装为其 OIDC subject，也不得允许手机号自动合并另一账号。
+
+设备库存确定目标租户。首次用户只可在允许自助入驻的消费租户中建立普通客户账号及家庭；企业租户没有邀请或授权时拒绝自动加入。注册不授予运维或租户管理能力。手机号绑定到已有 OIDC 账号须经过双方身份验证，不按相同显示名称合并。
+
+用户已有家庭和使用者时直接选择；没有时通过现有家庭及档案服务创建。完成登记后必须再次校验使用者属于同租户且当前账号拥有设备管理能力。
+
+### 6.3 入口页和浏览器会话
+
+新建 `/onboarding/entry`、`/onboarding/setup`、`/onboarding/result` 页面。entry 读取 fragment 中的 token 和 verifier，立即 replaceState 清除地址，然后同源 HTTPS 兑换；禁用第三方脚本、统计和凭据缓存。登录页不访问设备私网 HTTP。
+
+handoff 90 秒、claim 120 秒；setup 默认 15 分钟且绝对不超过 30 分钟。Cookie 建议为 `__Host-onboarding`，Secure、HttpOnly、Path=/、无 Domain，并按 OIDC 顶层回跳验证 SameSite=Lax 的实际行为。
+
+登录成功后旋转 session ID 并保留数据库中的 setup；手机号、验证码、Token 不写 URL 或普通日志。发送验证码默认间隔 60 秒、验证码 5 分钟、单挑战最多 5 次验证，为拟定初值，另设手机号/IP/浏览器/全局发送限额。
+
+兑换响应丢失时，有 Cookie 就查询当前状态；无 Cookie 就从同设备重新取入口，已经消费的 token 不复活。setup 关闭后普通账号会话仍可从设备列表查看进度，避免用户只能通过一次性入口访问已绑定设备。
+
+## 7 绑定提交和所有归属写入口
+
+### 7.1 统一的绑定服务
+
+新增 `internal/devicebinding`，提供接收 pgx.Tx 的归属操作，供新 claim、旧绑定码、运维、正式解绑转移、恢复出厂和隐私删除共用。已有事务由调用方持有，公共服务不能私自另开事务导致部分提交。
+
+新设备的 ConfirmClaim 应完成：
+
+1. 验证设备请求，并按固定顺序锁定设备、setup 和 claim；目标权限行按统一顺序读取和锁定。多设备任务按 UUID 排序取锁。
+2. 检查同申请是否已经成功：仅当前有效绑定和代数一致时返回原结果；归属已变化返回 409，要求同步当前状态。
+3. 检查 setup 为有效 ENROLL、设备未绑定且未停用、claim 未取消且未过期、当前账号仍有使用者管理权限。
+4. 核验 challenge、binding_digest、expected_binding_generation、press_event_id，并确保按键事件没有被另一申请使用。
+5. 写入唯一有效绑定，binding_generation 增加一次，消费 claim，更新 onboarding state 和 revision，保存不可变快照。
+6. 创建或关联固定激活任务，写入 `device.bound`/`device.activation.requested` outbox，事件去重键含设备与绑定代数；同时记录审计。
+7. 提交后返回 BOUND。设备落盘 ACK 和供应商调用均发生在本事务之后。
+
+取消和确认采用相同锁顺序。已绑定后再取消，只返回“绑定已完成”，不删除 owner。不同账号同时申请时返回 CLAIM_BUSY，不泄露另一个账号的完整信息。
+
+### 7.2 其他写入口的处理
+
+| 当前入口 | 新设备的规则 | 旧设备的兼容处理 |
+|---|---|---|
+| /api/v1/device-claims 绑定码 | 拒绝直接建归属，返回 DEVICE_CONFIRMATION_REQUIRED 和受控流程说明 | 保留原流程，但重试复核有效绑定 |
+| 运维 Create/Patch 的预分配 | 对新模式禁止直接指定家庭/使用者；普通运维不能模拟设备按键 | 原设备按现有权限执行，并统一记录代数变化 |
+| 运维删除/吊销 | 撤销归属及旧会话/命令，记录不可用状态；不能把设备重新开放给任意账号 | 保持原停用业务，复用新失效清理 |
+| binding-change | 新模式走原账号授权解绑，目标账号重新申请并由设备确认 | 旧模式保持现有变更前检查，写入代数与审计 |
+| /device/v3/factory-reset | 新模式只执行已获原账号或受控售后授权的完整重置；无授权不能解绑 | 保留旧产品行为并明确其语义；不可作为普通重配网接口 |
+| 隐私删除处理器 | 解除对应使用者设备关系、递增代数、撤销旧流程与个性化配置 | 同样接入统一归属服务，避免绕过代数更新 |
+
+最后一项来自当前 `internal/privacy/delete_processor.go` 的直接解绑写入，实施时必须覆盖。不能只修改可见绑定页面。
+
+新设备普通重配网保留身份、owner 和供应商身份；需要云端记录时仅报告网络操作结果。受控售后解绑的申请、执行账号、理由和证据独立审计，不纳入首次绑定的快捷入口。
+
+## 8 状态回执和收尾
+
+binding_state 为 UNBOUND、CLAIM_PENDING、BOUND、TRANSFER_PENDING；activation_state 为 NOT_STARTED、RESERVED、CONTACT_POSSIBLE、REGISTERED_OBSERVED、READY、RECONCILE_REQUIRED、BLOCKED。现有 lifecycle 字段保留作兼容投影，由同一状态服务更新，避免多个模块各写一套最终事实。
+
+device_revision 只随新协议公开状态变化；last_seen 更新不必增加该版本。STATE1 使用 device_id、device_revision、binding_generation、binding_state、activation_state 五个字段，前置 STATE1 后共六行；platform_device_id 等新增展示字段不加入原 hash 公式。
+
+每次版本变更保存状态快照。C07 收到同版本同 hash 返回成功；过期代数或未知 hash 返回 409 并提示同步。local_generation 在设备和有效启动上下文中验证；若设备存储发生恢复，不以降低云端代数的方式迁就本地状态。
+
+绑定与激活可继续并行：C07 ACK 只表示保存当前状态，Web ACK 表示看到了当前绑定。收尾以同一 binding_id/generation 的有效设备保存证据和页面接收证据为依据；页面收到较早 revision 不得被误当成看到了另一次绑定。
+
+设备和页面都确认后等待 3 秒关闭；只有设备确认时最多 30 秒；AI 激活不延长该时间。C11 失败时设备可按本地安全上限关闭 AP，随后补报；SaaS 保存关闭事实但不删除原激活任务。
+
+setup 过期或关闭后不再签发 handoff 和新 claim；认证设备可通过 C03 建 RECOVERY 上下文，再经 C05 获取自身状态、原任务和必要配置。恢复入口不授予新的账号所有权。
+
+## 9 激活模块改造
+
+### 9.1 将现有同步 Provision 拆成持久化阶段
+
+当前 `internal/hardwareprovision/service.go` 在数据库事务持锁期间调用供应商注册。改造后分为：
+
+1. 短事务内固定 provider_device_identity 和 activation_id，核验当前绑定与权益，创建 SERVER_REGISTER attempt，持久化 CONTACT_POSSIBLE，提交。
+2. worker 在事务外调用供应商，携带稳定 device_name；不持有数据库长事务。
+3. 新短事务保存明确结果和证据，加密 DeviceSecret，更新状态并发布 APPLY_ACTIVATION 命令。
+
+worker 取到 outbox 重试事件时先检查业务任务状态。已有 CONTACT_POSSIBLE 但没有明确结果，进入对账；租约过期不能直接重新调用供应商。fence_version 用于拒绝旧 worker 覆盖新状态，但不把本地租约当成远端请求已取消的证据。
+
+### 9.2 成功与未知结果
+
+| 结果 | 处理 |
+|---|---|
+| 明确未发出请求的本地前置失败 | 保存错误；修复后可按策略创建新 attempt |
+| 明确注册成功并取得合法凭据 | 保存供应商身份与 REGISTERED_OBSERVED；不直接写 READY |
+| 明确授权不足/过期 | BLOCKED，显示服务待处理；保留绑定 |
+| 注册请求超时、崩溃或回包未知 | RECONCILE_REQUIRED；保留原身份、任务和可能占用的权益 |
+| 设备未保存配置 | 保持已知供应商结果，重发相同有效配置或生成新的配置版本 |
+| 设备引擎初始化失败 | 记录 DEVICE/ENGINE_INIT 尝试，保留已知注册结果；不凭此释放供应商权益 |
+| 已验证首通测试成功 | 满足证据、权限和保存条件后进入 READY |
+
+对账通过经验证的供应商查询能力或受控人工证据完成。若供应商不提供可靠查询，不虚构自动对账 API；保持待处理，由运维基于供应商记录执行有审计的结论操作。
+
+供应商身份按物理设备固定。换绑定时更新个性化配置版本并使旧代数失效，不重新分配 provider device_name 或盲目再注册。旧 attempt 的晚到结果可记录物理设备供应商事实，但不能恢复上一位用户的配置或推进新用户的 READY。
+
+### 9.3 设备配置和 SDK 兼容验证
+
+新的配置包含 contract_version、device_id、activation_id、config_version、binding_generation、expires_at_ms、config_digest、instance_id、product_key、device_name、device_secret、bot_id。通过设备 HTTPS 通道交付，并以 CFG1 HMAC 验证完整性。
+
+ProductSecret 只在 SaaS worker 的供应商适配器中使用。配置不放进 Web status、普通 outbox payload 或明文幂等缓存。outbox 只记录引用，设备拉取时重新核对代数、任务和有效期。
+
+必须验证当前 SDK 能使用已注册 DeviceSecret，且不会无条件触发另一轮动态注册。若该能力不成立，阻断此激活路线的发布并回到协议设计，不在代码里静默双重注册。此项只影响真实激活发布，不阻止先完成认证与绑定。
+
+### 9.4 首通测试与日常通话
+
+不能让“只有 READY 才能创建任何会话”和“必须完成首通测试才能 READY”互相阻塞。新设备达到 REGISTERED_OBSERVED、有效绑定、运行配置已 ACK 且用户明确发起测试后，允许携带 C08 的短时测试许可创建专用测试会话。
+
+拟扩展现有 `/device/v3/agent-sessions`：仅新协议支持 intent=activation_test、activation_id、attempt_id、permit_token；正常设备通话仍检查当前绑定、配置、权限与服务状态。测试路径有时长/次数限制，不构成绕过普通服务权限的入口。
+
+C09 的测试 evidence 至少关联 conversation_id、首次有效下行音频观测、音频检查结果、SDK/固件版本和结束状态；服务端与该次会话记录核对。只收到 session_started 或媒体连接事件不能写 READY。挂机准备不自动采集环境音，测试必须由用户明确触发。
+
+### 9.5 新旧设备如何调用现有会话接口
+
+新增统一 DevicePrincipal 适配：先根据已登记的设备身份与 enrollment_mode 选择唯一允许的认证方案，再交给现有内部服务。新设备在无 query 的现有 v3 会话/事件及 v2 上报路径可使用 DEVREQ1，旧设备继续旧五行签名；不根据 User-Agent 判断协议，不在验签失败后回退另一算法。
+
+含 query 的旧 GET 接口不供新协议复用，新设备使用 C02/C05 等新 POST 路径。若以后需要 OTA 下载、媒体查询等功能，必须另列适配清单或提供无 query 的新入口；不能宣称本次首次接入方案已经覆盖所有旧设备能力。
+
+现有 `/device/v3/hardware-agent-credentials:provision` 对旧模式保持原约定；新模式只读取已有已确认凭据，未准备完成返回当前任务状态或引导 C05，不能再次触发同步注册。凭据读取同样必须检查当前有效绑定。
+
+## 10 前端和代码修改位置
+
+| 模块或路径 | 修改内容 |
+|---|---|
+| internal/onboardingauth 新增 | DEVREQ1、TIME1、版本密钥解析、限长校验和新身份上下文 |
+| internal/onboarding 新增 | C01 至 C07、C11、setup/handoff、状态快照和命令投递 |
+| internal/devicebinding 新增 | 统一的事务内绑定、解绑、代数推进和旧上下文失效 |
+| internal/activationjob 新增 | 固定任务、attempt、许可、权益、结果和对账 |
+| internal/websession / internal/smsauth 新增 | OIDC 接续、短信验证、平台会话和 CSRF |
+| internal/httpapi/router.go 及新增 handlers | 按契约挂载新路由、独立响应封装、显式鉴权分组 |
+| internal/opsdevice/service.go | 工厂库存入口、凭据交付及所有归属写入的模式限制 |
+| internal/saas/device_claim.go、device_binding_service.go | 旧入口新设备门禁、共同绑定事务和权限复核 |
+| internal/devicereset/service.go | 区分普通重配网和获授权完整重置，撤销旧流程 |
+| internal/privacy/delete_processor.go | 隐私解绑接入代数和状态失效流程 |
+| internal/hardwareprovision/service.go | 从同步注册拆到 worker，保留已确认凭据读取和加密能力 |
+| internal/idempotency/executor.go | ExecuteTx、事务内缓存命中权限/代数检查、敏感响应引用 |
+| internal/outbox 和 worker 注册处 | 绑定/激活事件处理；网络重试与外部未知结果分开 |
+| internal/identity、internal/app、internal/config | 账号解析统一、服务装配、新配置和按设备开关 |
+| web/src/pages 下新增 Onboarding 页面 | 入口兑换、登录接续、档案选择、按键等待、保存和激活进度 |
+| web/src/pages/SaaSWorkspace.tsx | 新设备不展示直接绑定码流程；正常账号设备列表显示分阶段状态 |
+| web/src/pages/OpsDeviceWorkspace.tsx | 工厂编号/MAC、绑定历史、ACK、激活异常、受控对账操作 |
+| web/src/api/client.ts、schema.d.ts | 从更新后的契约同步请求与返回类型 |
+| openapi/openapi.yaml 和兼容说明 | 增加新契约及身份编码；保留 v2/v3 旧契约和旧测试 |
+| internal/contractgovernance | 新增 ONBOARDING 契约检查、敏感字段边界和接口覆盖检查 |
+
+前台文案按实际事实显示：正在认证、等待按键、已绑定但设备保存中、AI 服务准备中、待处理、可用。设备重连和手动刷新复用原 setup/claim/activation，不自动发新验证码或再建任务。
+
+运维页面新增读取接口建议：`GET /api/v1/ops/devices/{id}/onboarding`、`GET /api/v1/ops/devices/{id}/activation-jobs`。受控对账建议 `POST /api/v1/ops/activation-jobs/{id}/reconciliations`，提交 conclusion、evidence_ref、reason、expected_version；权限限制到专门能力，不能用一个普通“重试”按钮解除未知结果。
+
+## 11 错误与恢复规则
+
+| 错误或状态 | HTTP | 客户端下一步 |
+|---|---|---|
+| DEVICE_AUTHENTICATION_FAILED | 401 | 停止敏感请求；检查密钥、时钟或受控恢复 |
+| DEVICE_ACCESS_DENIED | 403 | 设备停用、租户或账号权限问题，显示联系支持 |
+| REQUEST_BODY_CONFLICT | 409 | 同请求号不同内容，修复调用方 |
+| DEVICE_CONFIRMATION_REQUIRED | 409 | 进入按键绑定流程，不能改用旧接口绕过 |
+| CLAIM_BUSY | 409 | 等当前申请结束或由有权会话取消 |
+| CLAIM_EXPIRED / HANDOFF_EXPIRED | 410 | 重新申请短期对象，保持设备和既有绑定 |
+| BINDING_GENERATION_CONFLICT / STATE_MISMATCH | 409 | 查询当前状态，丢弃旧配置或旧确认 |
+| CONTRACT_UNSUPPORTED | 426 | 使用双方支持的固件和契约，不猜测枚举含义 |
+| RATE_LIMITED | 429 | 按 retry_after_ms 退避 |
+| ACTIVATION_RECONCILE_REQUIRED | 200 状态查询或 409 新调用申请 | 展示待对账；禁止自动再注册 |
+| DEPENDENCY_UNAVAILABLE | 503 | 保留业务 ID、原 body，更新时间和 nonce 后重试 |
+
+错误响应携带 request_id、retry_after_ms、recovery_action 和可公开的错误原因，默认退避 2、5、15、30 秒，最大 60 秒并加抖动。配置不得通过错误详情泄露。
+
+## 12 分阶段开发和交付物
+
+每阶段完成其必需测试后进入下一阶段，工期由团队人数和供应商适配验证后排定，不用未经评估的天数替代验收条件。
+
+| 阶段 | 工作项 | 可验收的交付物 | 依赖 |
+|---|---|---|---|
+| P0 兼容保护与契约 | 固定 ID/密钥/代数/租户规则；新增数据结构；所有旧归属入口加入模式门禁；OpenAPI 草案 | 数据迁移演练和旧接口回归通过，新模式尚未对产线开放 | 无 |
+| P1 生产登记与认证 | 库存去重、凭据交付/放行、C01/C02、新 HMAC、幂等 guard | 模拟设备可受控登记并重复认证；测试向量与旧设备均通过 | P0 |
+| P2 完整绑定流程 | C03 至 C07/C11、handoff、OIDC 接续、申请和确认事务、ACK、收尾页面 | 两个账号并发、回包丢失和断电恢复均不重复绑定；前台显示已绑定待开通 | P1 |
+| P3 独立激活 | outbox worker、固定供应商身份、尝试与对账、C08 至 C10、配置 ACK、首通测试 | 明确成功与未知结果均可恢复，只有真实验收后 READY | P2；SDK 凭据模式及供应商行为验证 |
+| P4 完整手机入口与发布 | 短信/账号注册、租户策略、正常列表恢复、运维对账、灰度观测 | 文档目标手机流程完成，真实短信和设备联调通过后扩大批次 | P2；P3 通过后才发布完整 AI 可用流程 |
+
+建议按以上阶段拆 PR。P0/P1 可以独立评审，P2 可先用模拟激活验收，不等待真实火山调用。短信适配可在接口固定后与 P3 由团队独立实施，但完整验收必须等真实提供方接入。
+
+完整交付应包含：迁移脚本、API 契约、后端与页面修改、设备调用示例和 HMAC 向量、故障测试记录、灰度及恢复手册、供应商模式验证结论。不能只以新增路由都返回 200 作为完成标准。
+
+## 13 迁移 灰度和回退
+
+1. 发布 P0 兼容保护版本，所有新开关默认关闭，旧设备正常回归。数据库只增加结构，保留原列和旧凭据。
+2. 回填旧设备 legacy 标记、既有供应商身份和可验证的绑定历史。不能把旧 ACTIVE 自动当成新 READY；有真实证据才迁入 READY，否则保留旧模式直到完成迁移验收。
+3. 在测试租户、单个受控工厂批次启用 enrollment_mode=physical_confirm。已有设备迁移必须核对实际 MAC、身份映射、密钥交付和固件能力，不能靠数据库批量切标记完成。
+4. 分别控制新建入口、认领、激活外部执行、恢复查询四类开关。暂停新建不关闭已提交绑定的查询/ACK，不让设备因发布回退而失去恢复原任务的路径。
+5. 灰度检查注册成功率、handoff 兑换率、确认成功率、状态保存延迟、激活对账积压、nonce 拒绝和 409 分类；指标只记录关联 ID，不包含秘密。
+6. 回退到至少包含 P0 保护和恢复能力的版本；不执行删除新表的 down migration，不把 physical_confirm 设备改回 legacy 来绕过故障。
+7. 停止新的供应商调用后，保留 CONTACT_POSSIBLE/RECONCILE_REQUIRED，等待已有调用和对账处理。不得回收可能已经占用的权益。
+
+建议配置分别表达入组范围、入口启用、激活 worker 启用、恢复读取保留和短信发送启用。前端按钮隐藏只控制展示，所有权限与模式门禁在服务端执行。
+
+## 14 测试和验收清单
+
+| 测试类别 | 必测情形 | 通过标准 |
+|---|---|---|
+| 生产身份 | 同 MAC 重试、登记回包丢失、型号/租户冲突、返修、密钥轮换中断 | 同一设备不变；冲突不覆盖；可恢复原交付任务 |
+| 新旧鉴权 | 附件 H 向量、旧 UTF-8 密钥、原始 JSON 空格变化、版本错误、query、超限 JSON | 各自按契约通过；错误不回退另一算法 |
+| 时间和重放 | 首次错误时钟、旧挑战、同 nonce、不同 boot_id、Redis 中断 | 不接受旧挑战或跳过防重放，不关闭业务 TLS |
+| 幂等和权限 | 同请求同 body、同请求不同 body、缓存命中前停用/换绑、24 小时后旧 claim | 有效操作不重复；旧权限和旧状态不可复活 |
+| Handoff | 双兑换、过期、verifier 错误、Cookie 回包丢失、OIDC 回跳 | 一次兑换且可恢复；不把入口当所有权 |
+| 短信与租户 | 重发、穷举、供应商超时、注册重试、已有 OIDC 账号、企业租户无邀请 | 不重复建账号、不自动越权、不错误合并身份 |
+| 绑定竞争 | 双账号认领、确认与取消并发、权限撤销、申请过期后的按键 | 唯一有效归属；无当前设备确认不能提交 |
+| 状态保存 | 提交后丢包、设备 ACK 重复或旧版本、页面 ACK 旧绑定、保存中断电 | 云端绑定不回滚；只承认对应代数和状态证据 |
+| 旧入口覆盖 | 绑定码、运维预分配、解绑/转移、恢复出厂、隐私删除 | 新模式无确认绕过；代数和旧上下文一致失效 |
+| 激活 worker | 外部调用前崩溃、调用中崩溃、成功后数据库失败、重复 outbox、租约过期 | 同一可能已调用的任务不被自动再次执行 |
+| 供应商与权益 | 额度不足、已注册查询、未知结果、人工对账、换绑期间晚到结果 | 保留身份和可能占用权益，证据可追踪 |
+| 首通及运行时 | DeviceSecret 模式、测试许可重放、媒体已连无首音频、正常首通、立即挂机 | 不重复注册；无真实测试证据不 READY；待机不采音 |
+| 浏览器恢复 | 手机切网、门户关闭、普通浏览器重开、登录超时、设备已绑定后再进旧入口 | 恢复当前状态，不要求重做已成功步骤 |
+| 发布回退 | 新旧设备同时在线、停用新建入口、P0 版本回退、恢复服务继续 | 旧设备可用，新设备既有绑定和任务不丢失 |
+
+后端使用 PostgreSQL/Redis 集成测试验证并发与事务，不用 mock 替代唯一约束和进程中断测试。前端使用现有 Playwright 流程验证手机和桌面页面。真实供应商、短信和设备联调记录单列，静态代码或模拟服务通过不等于实机通过。
+
+## 15 关键代码依据
+
+- [运维建档与预分配](E:/Codex/story/platform/internal/opsdevice/service.go:244)
+- [当前设备签名验证](E:/Codex/story/platform/internal/deviceauth/verifier.go:69)
+- [现有幂等响应直接重放](E:/Codex/story/platform/internal/idempotency/executor.go:145)
+- [当前绑定码提交](E:/Codex/story/platform/internal/saas/device_claim.go:27)
+- [当前解绑和转移](E:/Codex/story/platform/internal/saas/device_binding_service.go:67)
+- [恢复出厂的解绑写入](E:/Codex/story/platform/internal/devicereset/service.go:168)
+- [隐私删除中的解绑写入](E:/Codex/story/platform/internal/privacy/delete_processor.go:302)
+- [供应商注册当前执行方式](E:/Codex/story/platform/internal/hardwareprovision/service.go:127)
+- [可复用的事务 outbox](E:/Codex/story/platform/internal/outbox/store.go:40)
+- [现有 OIDC 入口](E:/Codex/story/platform/web/src/auth/oidc.ts:6)
+- [当前账号与租户映射](E:/Codex/story/platform/internal/identity/repository.go:71)
+- [原始差异分析](E:/Codex/story/platform/docs/首次配网设备认证与绑定_SaaS支撑功能分析.md)
@@ -0,0 +1,278 @@
+# 首次配网设备认证与绑定 SaaS 支撑功能分析
+
+分析日期：2026 年 9 月 11 日
+
+依据：附件《AI电话 首次配网 注册与激活 完整流程与详细设计》，整合日期 2026 年 9 月 8 日，公共契约 ONBOARDING-1.1；以及当前工作区 SaaS 的路由、服务、数据库迁移和前端代码。
+
+结论：现有平台具备设备建档、独立密钥、设备鉴权、家庭和使用者权限、绑定关系、设备配置与命令、供应商凭据和审计等基础，但尚未实现附件要求的完整首次接入流程。主要新增工作是可信首次校时、设备注册协议、云端设置会话、手机入口交接、登录后按键确认绑定，以及绑定状态保存回执。激活任务也需要独立的持久化状态和异常恢复机制。
+
+本分析只列 SaaS 要承担的工作及其设备协议边界。Wi-Fi 扫描、密码保存、AP、NAPT、GPIO 和设备存储的具体实现由设备承担。SaaS 不接收家庭 Wi-Fi 密码。本文区分附件要求、当前实现和实施建议；附件中的设计不代表这些功能已经上线。
+
+核对方式：读取正文、附件 A 至 K 和 5 张流程图；静态检查实际路由和实现。附件列出的 18 个云端接口均未在当前 router 中以相同方法和路径注册，但部分能力有现有服务可复用。附件 H 的 HMAC 示例和三组热点名称向量已离线复算一致。没有进行真实设备、短信服务或供应商联调。
+
+## 1 SaaS 应负责的完整业务顺序
+
+1. 受控生产流程登记设备身份和密钥，建立唯一库存记录。
+2. 设备联网后请求可信时间，再携带设备认证信息完成注册和状态恢复。
+3. SaaS 为未绑定设备创建设置会话，签发短时手机交接入口。
+4. 手机兑换入口并登录账号；服务端保存当前设备上下文，提供有权限的使用者列表。
+5. 手机选择使用者并创建绑定申请，此时设备尚未归属于该账号。
+6. SaaS 向设备下发当前申请的确认挑战；用户按键后，设备回传对应申请的确认。
+7. SaaS 在一次事务内提交绑定、消费申请、增加绑定代数、更新状态版本、写入激活待办。
+8. 设备保存绑定并回执；手机读取结果并回执。设置入口按收尾条件关闭。
+9. AI 激活任务独立继续；失败、页面关闭或设置会话过期，都不撤销已提交绑定。
+
+必须分别展示三个结果：设备身份已认证、账号已绑定、AI 服务是否可用。SaaS 收到 HTTP 请求成功、设备本地保存成功、真实首音频验证成功，也分别记录。
+
+## 2 功能清单与现有实现对照
+
+“可复用”表示存在相应基础逻辑，不表示已经符合 ONBOARDING-1.1 的报文和全部业务约束。
+
+| SaaS 功能 | 附件要求和用途 | 当前实现 | 需要的工作 |
+|---|---|---|---|
+| 生产身份与库存 | 按完整设备 ID 和出厂 MAC 唯一登记；返修恢复原记录；密钥轮换留审计 | 运维接口可建档、生成随机 UUID 和密钥、轮换凭据 | 增加生产身份映射、MAC 唯一约束和幂等生产登记；区分库存与首次上线 |
+| 设备认证 | 按设备和密钥版本验证 DEVREQ1 HMAC，检查时间、nonce、停用和吊销 | 已有 HMAC、时间窗口、防重放、加密密钥存储、状态限制 | 新增 ONBOARDING-1.1 认证适配；现有签名格式不能直接兼容 |
+| 首次可信校时 | 用单设备密钥签名时间挑战，设备验签后再严格使用 HTTPS | bootstrap 返回服务器时间，但须先通过现有认证 | 新增 C01；不能把现有 bootstrap 当作无可信时间时的校时入口 |
+| 设备注册与恢复 | 只接受已登记的生产身份；重复注册返回原设备、绑定和激活状态 | 设备由运维创建；bootstrap 更新在线报告并返回绑定 | 新增 C02、挑战消费、业务幂等及完整公共状态 |
+| 云端设置会话 | 关联设备、启动、本地会话、期限和流程阶段 | 未发现 setup_session 完整实现 | 新增 C03 和设置会话；已绑定设备只进入恢复模式 |
+| 手机入口交接 | handoff 与 verifier 摘要匹配，短时、一次性兑换，生成浏览器会话 | 未发现此交接流程 | 新增 C04、Web exchange 和 HTTPS 入口页 |
+| 账号登录与使用者权限 | 短信登录或注册、保留 setup、校验有权管理的老人档案 | 已有 OIDC 登录、平台账号映射、家庭成员权限、使用者档案 | 若严格遵循附件需补短信入口与注册映射；也可复用 OIDC，但须修改双方认可的登录契约 |
+| 绑定申请 | 登录后固定设备、账号、使用者、绑定代数和挑战；每设备一条有效申请 | 一次性绑定码表存在，但不绑定某次设备按键挑战 | 新增待确认申请；不能直接把现有 claim_code 当作新 claim |
+| 设备确认后提交绑定 | 核验 claim、challenge、digest、按键事件和当前权限后原子提交 | 当前 POST /api/v1/device-claims 提交绑定码后直接写绑定 | 新增 C06；保留并扩展行锁、有效绑定唯一约束与审计 |
+| 状态版本和保存回执 | 独立 binding_generation、device_revision、local_generation、state_hash；记录设备与页面 ACK | 已有 device.version、activation_revision、配置 revision | 新增明确的绑定代数和状态快照；现有版本不能直接互相替代 |
+| 流程命令与进度查询 | CONFIRM_CLAIM、APPLY_ACTIVATION、UPDATE_STATE、CLOSE_SETUP | 已有配置、重启、诊断、OTA 命令 | 增加流程命令及权限、过期、去重规则；通用命令 ACK 不等于绑定确认 |
+| 独立激活任务 | 固定设备供应商身份与任务；保存调用许可、尝试结果、未知状态和对账证据 | 已有平台代注册、供应商凭据加密保存和复用 | 新增任务和尝试记录；统一平台代注册与设备 SDK 注册的路线 |
+| 中断恢复与设置收尾 | 页面关闭、断电、回包丢失后按原任务恢复；关闭 setup 不解除归属 | 有一般设备查询、解绑、重置和部分请求幂等基础 | 新增 C07/C10/C11、Web status/ack/cancel 及完整恢复规则 |
+| 运维处理和验收 | 查阶段、绑定、ACK、激活和失败原因，处理停用、返修、对账 | 设备运维、状态迁移、审计和通用 outbox 已有 | 增加首次接入诊断视图和激活对账；将绑定事件接入 outbox |
+
+## 3 认证和生产登记的具体要求
+
+### 3.1 区分生产登记与设备首次注册
+
+上一轮提取的 `POST /api/v1/ops/devices` 是运维建档入口。附件的 `POST /api/v1/device/register` 是设备证明已有身份并报告上线的入口。两者调用者、鉴权和数据用途不同，不能替换使用。
+
+生产侧至少保存：设备固定编号、出厂 MAC、型号、硬件版本、凭据版本、受控密钥引用、生产及返修记录。设备注册请求不能仅凭公开 MAC 获取新密钥，也不能让请求方自行指定账号归属。
+
+现有 Create 每次生成新 UUID 和随机 serial_digest，没有按输入 MAC 重复登记的能力。建议保留数据库内部 UUID，新增唯一的工厂编号与 MAC 映射，由新协议在边界解析 `KP01-84FCE6123456` 一类编号；无需为匹配外部编号直接重写全部内部外键。
+
+现有 FACTORY 状态不允许通过通用设备认证。若生产登记先进入该状态，还需明确出厂放行到可认证状态的流程，或为新库存认证设置单独的准入规则，不能让新设备被自己的初始状态永久挡住。
+
+### 3.2 HMAC 契约存在实质差异
+
+| 项目 | 附件 ONBOARDING-1.1 | 当前平台 |
+|---|---|---|
+| 设备编号 | KP01- 加完整 12 位大写 MAC | UUID |
+| HMAC 密钥字节 | 原始 32 字节 device_key | 当前运维 Create 返回 64 位 hex 字符串，并把该字符串的 UTF-8 字节作为 HMAC 密钥 |
+| 时间字段 | X-Timestamp-Ms，Unix 毫秒 | X-Timestamp，RFC3339 |
+| 密钥版本 | X-Key-Version，参与签名和密钥选择 | 密钥库有版本，但当前请求签名不包含版本头 |
+| 业务请求号 | X-Request-ID，参与签名和幂等 | 现有五行签名不包含业务请求号；部分业务另用 Idempotency-Key |
+| 签名正文 | DEVREQ1 开头的九行，包含设备 ID、版本、请求号；路径不含 query | 方法、包含 query 的 RequestURI、时间、nonce、body 哈希，共五行 |
+| 签名传输 | Authorization: Device-HMAC-SHA256 加小写 hex | X-Signature，Base64url 无填充 |
+| 时间容差 | ±120 秒 | 默认 ±5 分钟，可配置 |
+| nonce | 16 随机字节的 Base64url，按设备和版本保存至少 5 分钟 | 接受 16 至 128 字符；当前按设备和 nonce 防重放 |
+
+Header 名称的大小写不是差异重点；签名所包含的内容、编码、密钥字节和时间含义才是兼容性问题。
+
+建议以独立协议适配层支持新路径，复用密钥加密存储和设备状态查询。旧设备继续使用旧契约，避免在同一入口中静默尝试不同签名算法。密钥迁移需要显式标记编码与版本，不能把当前返回的字符串自动解码后用于旧接口。
+
+### 3.3 首次校时与注册提交
+
+C01 接收公开 device_id、key_version、boot_id、client_nonce，返回只包含时间及挑战的签名响应。未知设备通用拒绝。挑战 120 秒有效，签名域为 `TIME1`，不签发账号、绑定或供应商凭据。
+
+C02 验证设备请求后，原子消费与当前设备、启动关联的 challenge_id，并提交注册结果。同一 request_id、同一原始 body 的已成功重试应返回匹配结果；不同 body 返回冲突。已消费挑战不能阻止读取同一已提交结果，但不能授权一次新注册操作。
+
+## 4 手机登录交接需要新增的功能
+
+SaaS 必须维护独立的 setup 上下文，不能只把 device_id 放入登录页 URL。一次 setup 关联设备、boot_id、本地 local_setup_id、模式、期限和当前阶段；默认 15 分钟，绝对上限 30 分钟。
+
+handoff 默认 90 秒有效，数据库保存 token 哈希，并绑定 setup 与 code_challenge。兑换时核对 verifier 摘要、过期状态和一次性消费状态，再建立浏览器会话。它只证明进入了某次设备流程，不授予设备所有权。
+
+HTTPS 入口页从 URL fragment 读取 token 与 verifier，立即清理地址，再同源 POST 兑换。入口固定白名单、禁止任意跳转，页面不加载第三方统计脚本，凭据响应禁止缓存。SaaS HTTPS 页面不反向请求设备的本地 HTTP 接口。
+
+登录前后都需保留服务端 setup；登录成功后更新会话身份并防止会话固定。按附件实现 Cookie 时，应配置 Secure、HttpOnly 和适合该跳转链路的 SameSite，并执行 Origin/CSRF 检查。短信需按手机号、IP、浏览器流程限流，约束验证码期限和尝试次数。
+
+现有 OIDC 登录和家庭权限可以作为账号基础，但 OIDC 自带的 PKCE 不等于附件中的设备 handoff。若继续复用 OIDC，仍要实现“设备流程交接”和“登录后继续原 setup”。
+
+新用户还需要能创建或进入家庭、创建或选择使用者。现有家庭与档案接口可复用：`POST /api/v1/households`、`GET/POST /api/v1/households/{id}/subjects`。附件没有完整规定账号首次加入租户和家庭的策略，这部分必须补入实施设计。
+
+## 5 绑定事务与状态同步
+
+### 5.1 一次绑定申请固定哪些数据
+
+| 数据 | 为什么需要 |
+|---|---|
+| device_id、setup_id | 确定当前设备和操作流程 |
+| 登录账号、tenant_id、household_id、subject_id | 确定归属范围和使用者；账号从登录态取得 |
+| claim_id | 为一次明确申请提供长期业务去重标识 |
+| challenge、expires_at | 限定本次物理确认窗口，默认 120 秒 |
+| binding_digest | 固定被确认的账号和使用者内容；目标变化就重建申请 |
+| expected_binding_generation | 防止旧申请在设备已经换绑后继续生效 |
+| press_event_id | 防止旧按键事件重复确认另一笔操作 |
+| 状态、取消与消费时间、提交结果引用 | 处理取消、确认、超时和网络重试竞争 |
+
+服务端检查的是经过设备认证的“指定申请确认”，不是相信浏览器上传 `button_pressed=true`。配网前的按键授权也不能作为登录后绑定申请的确认。
+
+### 5.2 在一次事务中完成绑定
+
+建议事务顺序：锁定设备及申请 → 识别同申请的已提交结果 → 核验当前权限、代数和未过期挑战 → 检查唯一有效归属 → 写入绑定 → 绑定代数增加一次 → 消费 claim → 更新 device_revision → 写入激活 outbox 事件和审计 → 提交。
+
+复用当前 device_binding 的有效记录唯一索引和行锁，同时为待确认申请增加唯一约束。取消与确认并发时以事务提交结果为准：取消未完成申请不能删除已提交绑定。
+
+现有绑定码逻辑可以保留为独立入口，但不能绕过新协议的按键确认。新模式需明确哪些设备允许使用旧绑定入口，以及运维强制分配归属是否属于受控例外，否则只增加一个安全入口并不能保证所有绑定都经过同样规则。
+
+重试判断不仅要比较原目标，还要确认绑定仍是当前有效归属。当前旧 claim 的已使用分支会读取原 used_binding_id；新流程必须补上绑定代数和当前状态检查，避免设备已解绑或换绑后再返回旧状态作为可用配置。
+
+### 5.3 两种版本与两种回执
+
+`binding_generation` 只在归属发生变化时递增；`device_revision` 在对设备公开的业务状态变化时递增。`local_generation` 是设备存储版本，由设备报告。普通网络更新不能增加绑定代数，普通配置 revision 也不能冒充绑定代数。
+
+C07 验证 device_revision、binding_generation、local_generation 和 state_hash，记录设备已保存哪一版状态。Web ack 记录手机已看到哪次绑定结果。二者均不改变 owner；设备保存失败也不能回滚服务端绑定。
+
+前台应分别显示“待按键确认”“账号已绑定，设备保存中”“账号已绑定，AI 服务准备中”“AI 服务待处理”“AI 服务可用”。轮询超时后仍能从账号设备列表恢复查看。
+
+## 6 激活支撑与现有路线差异
+
+### 6.1 绑定与激活分别提交
+
+附件要求：一台设备一个当前 activation_job，固定 activation_id 和供应商 device_name；每次实际调用有 attempt_id。绑定事务只写待办，后台再处理外部服务。现有通用 outbox 可复用，但当前 ClaimDevice 并未写入这一类激活待办。
+
+至少需要以下业务状态：NOT_STARTED、RESERVED、CONTACT_POSSIBLE、REGISTERED_OBSERVED、READY、RECONCILE_REQUIRED、BLOCKED。绑定状态则单独使用 UNBOUND、CLAIM_PENDING、BOUND、TRANSFER_PENDING。
+
+当前 FACTORY/CLAIMABLE/BOUND/PROVISIONING/ACTIVE/LOST/REVOKED 是另一组设备生命周期状态。不能仅靠一张枚举映射表就认定两套状态相同，特别是当前 ACTIVE 并没有附件要求的真实首音频验收含义。
+
+### 6.2 外部结果未知时的恢复
+
+外部调用前持久化“可能已调用”的记录；记录许可原始有效期和调用尝试。超时、断电、回包丢失进入 RECONCILE_REQUIRED，禁止自动换 device_name、释放可能占用的名额或并行再次激活。结果成功也应区分 SDK 注册成功和真实通话验证成功。
+
+现有 Provision 在数据库事务和锁持有期间调用 registrar.Register，然后存储凭据并提交。如果供应商已处理但回包丢失，事务可能回滚，尚无附件所需的持久化未知结果和对账任务。确定性的 device_name 与已保存凭据复用可以减少重复身份，但不能替代完整的外部调用结果恢复。
+
+### 6.3 实施前需要统一供应商凭据路线
+
+附件第 8 章和 E.2 描述向设备下发 ProductSecret，由设备执行动态注册。当前代码把 ProductSecret 保留在 SaaS，由平台注册后只向设备下发 DeviceSecret。这是执行位置与凭据边界的差异，不能用增加几个返回字段掩盖。
+
+实施建议：优先在现有平台代注册方案上补持久化任务、尝试记录和对账，并同步修订附件中的激活契约。若最终明确选择设备执行注册，则按该路线重新设计调用许可、配置封装和结果回执。两种路线的供应商行为都需要针对实际 SDK/接口版本验证，本文不据文档宣称其已通过实机验证。
+
+代码中还有 License 内容导入、分配和 ACK 相关模块；当前主 router 未接入相应 License ACK/分配闭环，不能视为已有 ONBOARDING-1.1 的授权对账能力。附件采用权益或名额管理，也没有定义向设备交付 License 文件。应先统一授权模型，再确定复用范围。
+
+## 7 附件明确要求的云端接口
+
+下列 18 条均为附件规定的目标接口，当前没有同路径路由。生产登记、运维管理以及已有家庭/使用者管理接口不包含在这个数量中。
+
+### 7.1 设备调用 SaaS
+
+除 C01 使用专用时间签名协议外，均按附件 B 使用设备 HMAC 和 HTTPS。表中字段为 body，设备 ID、密钥版本和请求号等还须按契约放入认证头。
+
+| 编号 | POST 路径 | 核心输入 | SaaS 负责输出或提交 |
+|---|---|---|---|
+| C01 | /api/v1/device/time-challenges | device_id、key_version、boot_id、client_nonce | 签名时间与短时 challenge_id |
+| C02 | /api/v1/device/register | challenge_id、boot_id、hardware_model、hardware_revision、firmware_version、sdk_version | 认证已有生产身份；返回当前状态和契约版本 |
+| C03 | /api/v1/device/setup-sessions | boot_id、local_setup_id、transport_profile=LOCAL_WEB | setup_id、期限、轮询间隔、状态 |
+| C04 | /api/v1/device/handoffs | setup_id、local_setup_id、code_challenge | 一次性 token、期限、固定 HTTPS 入口 |
+| C05 | /api/v1/device/poll | setup_id、boot_id、known_revision | 当前状态、有效流程命令、轮询间隔 |
+| C06 | /api/v1/device/claim-confirmations | claim_id、challenge、binding_digest、expected_binding_generation、press_event_id | 提交绑定或返回同一已提交结果 |
+| C07 | /api/v1/device/state-acks | device_revision、binding_generation、local_generation、state_hash | 保存设备落盘证据及可否收尾 |
+| C08 | /api/v1/device/activation-attempts | activation_id、config_version、attempt_id | 持久化可能调用状态，返回 30 秒执行许可 |
+| C09 | /api/v1/device/activation-results | activation_id、attempt_id、stage、sdk_result、outcome | 更新注册/通话验收状态或转入对账 |
+| C10 | /api/v1/device/activation-acks | activation_id、local_generation、config_version | 保存激活配置落盘回执 |
+| C11 | /api/v1/device/setup-close | setup_id、reason、final_revision | 关闭临时流程，保留绑定和激活任务 |
+
+公共状态包含 device_id、device_revision、binding_generation、binding_state、activation_state、next_action、state_hash。C05 的状态恢复权限不能随手机 token 或原 setup 过期而消失；需要时先创建仅用于恢复的新 setup。
+
+### 7.2 手机调用 SaaS
+
+| POST 路径 | 核心输入或上下文 | 用途 |
+|---|---|---|
+| /api/v1/web/handoffs/exchange | token、verifier | 登录前兑换一次性入口，创建当前 setup 的浏览器会话 |
+| /api/v1/web/auth/sms/send | 手机号和当前流程；附件未完整定义字段 schema | 发送登录验证码并限流 |
+| /api/v1/web/auth/sms/verify | 手机号、验证码和当前流程；附件未完整定义字段 schema | 验证、登录或注册，更新会话并保留 setup |
+| /api/v1/web/claims | elder_id、expected_binding_generation、登录会话 | 创建待设备按键确认的绑定申请 |
+| /api/v1/web/setup/status | 浏览器当前 setup | 查询自己的绑定和激活进度 |
+| /api/v1/web/setup/ack | 浏览器当前 setup 及收到结果的上下文 | 确认页面已收到结果 |
+| /api/v1/web/claims/cancel | 当前 setup 的待确认申请 | 取消待确认申请；不解绑已经归属的设备 |
+
+设备收到的 masked_account 只用于提示核对，不接受它作为认证依据。用户身份从登录会话取得；不能信任浏览器提交的 owner_user_id，也不能允许浏览器仅凭任意 device_id 查询其他家庭的状态。
+
+### 7.3 可复用的当前入口
+
+| 当前接口或模块 | 可复用范围 | 无法直接替代的部分 |
+|---|---|---|
+| POST /api/v1/ops/devices | 运维建档、初始平台凭据 | 生产 MAC 幂等登记和 C02 设备认证注册 |
+| POST /api/v1/ops/devices/{id}/credentials/rotate | 受控凭据更新 | ONBOARDING-1.1 按版本认证和产线恢复协议 |
+| GET /device/v2/bootstrap | 在线报告、当前绑定和固件兼容检查 | 首次时间挑战、setup、绑定代数与完整恢复状态 |
+| GET /device/v2/config | 配置查询与版本基础 | CFG1 配置、绑定代数和明确的本地保存 ACK |
+| POST /api/v1/device-claims | 家庭权限、绑定码、绑定写入与唯一约束 | 登录后的待确认申请及实体确认挑战 |
+| GET /device/v2/commands 及命令 ACK | 命令投递和回执基础 | 四种首次接入命令与具体绑定确认语义 |
+| POST /device/v3/hardware-agent-credentials:provision | 平台代注册、固定设备名、加密凭据及复用 | 独立激活任务、执行许可、未知结果对账和 READY 验收 |
+| binding-impact / binding-change | 当前家庭权限、解绑与变更前检查 | 新确认流程、绑定代数与所有旧入口失效策略 |
+| OIDC、家庭和使用者服务 | 账号认证、成员权限、档案管理 | 手机 handoff、setup Cookie、附件指定短信 schema |
+
+## 8 数据模型和后台页面
+
+以下是逻辑记录划分，可按现有结构扩展，不要求每一项都另建一张表。
+
+| 逻辑记录 | 关键数据和约束 |
+|---|---|
+| 生产库存和凭据 | 唯一工厂 ID/MAC、内部设备 UUID、租户归属、型号、密钥引用及版本、生产/返修状态 |
+| 时间挑战 | 设备、版本、boot_id、client_nonce、签发/失效/消费时间及注册结果关联 |
+| 设备当前状态 | 独立绑定和激活状态、device_revision、binding_generation、当前任务、最后在线时间 |
+| 设置会话和交接入口 | setup/local_setup/boot 关联、模式、权限、绝对期限、token 哈希、verifier 摘要、消费状态 |
+| 绑定申请和绑定历史 | 目标账号/家庭/使用者、挑战、digest、按键事件、期限、代数；唯一有效申请和归属 |
+| 状态快照和回执 | 状态 hash、设备保存版本、页面看到的结果、ACK 时间；旧版本不能覆盖新版本 |
+| 激活任务和尝试 | 固定供应商身份、权益预留、attempt、许可期限、调用阶段、结果证据、待对账原因 |
+| 幂等结果和 outbox | 设备/接口/请求号作用域、原始 body 摘要、提交结果；长期业务唯一键；待办重试和消费去重 |
+| 审计记录 | 操作者、设备、setup、claim、activation/attempt、旧/新状态及错误码；不记录密钥和验证码 |
+
+用户侧至少需要：入口恢复页、登录页、家庭/使用者选择页、等待按键确认页、绑定完成及设备保存状态、AI 服务进度、正常账号设备列表。
+
+运维侧至少需要：按工厂编号/MAC 查库存与设备、出厂放行与凭据轮换、首次接入阶段诊断、当前绑定及历史代数、设备/页面 ACK 状态、激活异常与人工对账记录、停用和报失处置。
+
+## 9 附件在当前 SaaS 中还需明确的设计点
+
+1. **租户和 owner 映射。** 当前设备、家庭和档案受租户约束，归属主要通过 household/subject 表达。附件没有规定新手机号注册到哪个租户、能否认领其他租户库存，以及 owner 是家庭还是单一账号。建议按生产归属解析租户，并继续验证家庭管理权限；不要直接让手机号或 elder_id 决定租户。
+2. **身份编码迁移。** 外部 KP01 编号与现有 UUID 保持稳定映射；产线、认证、售后和旧客户端不得各自生成新身份。
+3. **绑定代数的变更规则。** 附件规定归属变化递增，但需要进一步固定“解绑后再绑定”和“一步转移”的递增及历史记录规则。所有写入口必须统一。
+4. **普通重新配网与恢复出厂。** 当前 /device/v3/factory-reset 会解除绑定并生成新绑定码。附件规定普通重配网保留 owner，转让走原账号授权。因此普通重配网不能调用此接口，完整恢复出厂的归属权限也需要单独定规则。
+5. **激活执行位置与授权模型。** 统一平台代注册还是设备 SDK 注册、ProductSecret 的位置、名额与供应商权益的对应关系，以及什么证据足以解除未知结果状态。
+6. **接口详细 schema。** 短信输入、取消目标、浏览器 ACK 的版本匹配、部分恢复错误及晚到结果规则仍需写入 OpenAPI。公共约定要求变更请求带 X-Request-ID，浏览器这些写操作也应明确其用法。
+7. **状态快照和 ACK。** 明确 device_revision 对应的历史状态保留策略；当前状态继续推进时，设备应同步最新版本，不能把旧 ACK 写成新版本已保存。
+8. **存量入口。** 现有绑定码、运维分配、解绑转移和恢复出厂均会影响归属。新协议不能只覆盖新页面而遗漏其他写入口。
+
+## 10 建议开发顺序与验收
+
+第一阶段先完成认证与绑定：生产身份映射 → 新鉴权与时间挑战 → 注册和公共状态 → setup/handoff → 登录与使用者选择 → 待确认申请 → 设备确认事务 → 两侧回执与收尾。此阶段可返回“已绑定，AI 服务待开通”，不阻塞于真实供应商联调。
+
+第二阶段补齐激活：绑定 outbox → 固定激活任务与身份 → 调用尝试和许可 → 结果上报与对账 → 激活配置 ACK → 首音频验收后的 READY。
+
+第三阶段完成运营闭环：停用和密钥轮换、返修、原账号解绑与新账号确认、旧代数隔离、失败恢复入口、诊断视图及生产环境限流监控。
+
+必须覆盖的验收结果：
+
+- 同 MAC/工厂 ID 重复生产登记和重复上线，不增加设备副本，也不清空已有绑定。
+- 错密钥、错版本、过期时间、重放 nonce 被拒绝；同请求号不同 body 返回冲突。
+- handoff 仅能兑换一次，过期不能复活；登录和浏览器切换后可恢复正确设备上下文。
+- 无设备确认不能绑定；双账号并发仅一条有效申请和一个有效归属。
+- 旧 challenge、旧按键、被取消 claim、旧绑定代数不能建立新归属。
+- 绑定提交后回包丢失，返回同一有效结果；设备保存失败只补写和 ACK，不撤销绑定。
+- 页面关闭、setup 到期或热点关闭后，设备仍能恢复原激活任务。
+- 供应商结果未知保留原任务、设备名和可能占用的权益；不自动释放后再次分配。
+- SDK 注册成功与真实通话 READY 分开；授权不足保留账号绑定。
+- 普通重配网保留归属；正式解绑或转移使旧会话、旧申请和旧用户配置失效。
+
+## 11 当前代码依据
+
+- [实际路由与设备鉴权分组](E:/Codex/story/platform/internal/httpapi/router.go:297)
+- [运维登记设备和生成平台凭据](E:/Codex/story/platform/internal/opsdevice/service.go:244)
+- [当前设备 HMAC 验证和签名正文](E:/Codex/story/platform/internal/deviceauth/verifier.go:69)
+- [设备凭据加密存储与轮换](E:/Codex/story/platform/internal/deviceauth/database_secret.go:115)
+- [bootstrap 的现有状态字段和报告](E:/Codex/story/platform/internal/device/repository.go:32)
+- [当前提交绑定码后直接绑定的逻辑](E:/Codex/story/platform/internal/saas/device_claim.go:27)
+- [有效设备绑定唯一约束](E:/Codex/story/platform/migrations/000005_device_conversation.up.sql:65)
+- [当前 claim 数据结构](E:/Codex/story/platform/migrations/000007_device_claim.up.sql:3)
+- [当前设备生命周期状态](E:/Codex/story/platform/internal/deviceactivation/state.go:15)
+- [当前解绑和转移事务](E:/Codex/story/platform/internal/saas/device_binding_service.go:67)
+- [当前命令类型约束](E:/Codex/story/platform/migrations/000011_device_command.up.sql:8)
+- [平台代注册与供应商凭据保存](E:/Codex/story/platform/internal/hardwareprovision/service.go:127)
+- [License 模块](E:/Codex/story/platform/internal/hardwarelicense/service.go:250)
+- [恢复出厂解除绑定](E:/Codex/story/platform/internal/devicereset/service.go:168)
+- [现有前端 OIDC 登录](E:/Codex/story/platform/web/src/auth/oidc.ts:6)
+- [通用 outbox 执行基础](E:/Codex/story/platform/internal/outbox/worker.go:1)