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:
@@ -119,6 +119,9 @@ POST /api/v1/client/tasks/claim
|
||||
|
||||
```json
|
||||
{
|
||||
"client": {
|
||||
"name": "办公室-01"
|
||||
},
|
||||
"supported_types": ["collect", "purchase"],
|
||||
"device": {
|
||||
"address": "192.168.0.173:5555",
|
||||
@@ -142,6 +145,16 @@ POST /api/v1/client/tasks/claim
|
||||
|
||||
无可领取任务时返回 `204 No Content`。
|
||||
|
||||
`[必须]` **`204` 不是错误。** 新客户端第一次调 `claim` 必然是 204——
|
||||
它刚被登记,还没有人给它分配任务。Client 要把它当"暂时没活干"处理,
|
||||
不要报错,也不要因此触发重试风暴。
|
||||
|
||||
`client.name` 是给人看的显示名,可以不填(不填时 Admin 用 `X-Client-Id` 兜底)。
|
||||
它**只在首次登记时被采纳**,之后操作员在 Admin 改的名字不会被客户端覆盖。
|
||||
|
||||
> 怎么把这条链路跑通、怎么确认设备登记成功,见
|
||||
> [Admin 侧的设备登记联调手册](../admin/07-设备登记联调手册.md)。
|
||||
|
||||
规则:
|
||||
|
||||
- `[必须]` 领取必须在 Admin 内部原子完成,一次调用最多返回一个任务。
|
||||
|
||||
Reference in New Issue
Block a user