docs: 新增设备登记联调手册,并定案 client.name

面向 Client 开发者的实操文档,目标是让一台新设备出现在 Admin 的
客户端列表里。文中所有请求和响应都是在真实运行的 Admin 上跑出来的。

新增 docs/admin/07-设备登记联调手册.md
- 先讲清"没有注册接口,登记是 claim 的副作用"
- **重点提示 204 不是错误**:新设备第一次 claim 必然 204,
  它同时意味着登记成功。这是最容易被 Client 误判成失败的地方
- 设备号必须持久化、永不变——变了 Admin 会当成新机器,
  列表里会堆一串僵尸记录
- 设备名只在首次登记时采纳,之后 Admin 侧改名不会被覆盖。
  这个行为会让人困惑("我改了 Client 怎么 Admin 没变"),先说清楚
- 四步验证流程 + 可直接复制的 curl + 手工插测试任务的 SQL
- 7 条常见问题,含"列表里多出好几台一样的机器"这类实际会碰到的
- 列出 Client 侧待办清单,标明前两条做完就能登记成功

定案 client.name(原 [待定])
Client 设置页本来就有「设备名」输入框(deviceNameInput,50 字上限),
只是没接进 ClientInfo。Admin 仍容忍它缺失,缺了用 X-Client-Id 兜底,
所以 Client 先不发也不影响登记。

同步更新
- docs/client/04-admin-api-contract.md §5:请求示例补 client 字段,
  加"204 不是错误"的必须项,并指向本手册
- docs/README.md:两处导航加入口,Client 侧"对接 Admin"那行也指过来

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-08-06 17:08:58 +08:00
co-authored by Claude Opus 5
parent 7ad82b7795
commit 62d46bf10a
4 changed files with 302 additions and 3 deletions
+6 -2
View File
@@ -96,8 +96,12 @@ X-Client-Id: client-001 ← 序列号,主键
}
```
> `[待定]` `client.name` 是对 Client 契约 §5 的一处小扩展,需在联合评审时确认。
> 未确认前 Admin 要容忍它缺失:没有就用 `X-Client-Id` 当显示名。
> **已定案:** `client.name` 是对 Client 契约 §5 的一处小扩展。
> Client 的设置页本来就有「设备名」输入框(`deviceNameInput`,50 字上限),
> 把它带上即可。**Admin 仍然容忍它缺失**——没有就用 `X-Client-Id` 当显示名,
> 所以 Client 先不发也不影响登记。
>
> 登记流程的完整说明见 [07 设备登记联调手册](07-设备登记联调手册.md)。
处理: