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:
+3
-1
@@ -34,7 +34,7 @@
|
||||
| 第一次把项目跑起来 | [00 上手指南](client/00-getting-started.md) | — |
|
||||
| 改界面、加页面、调表格 | [05 界面交互规范](client/05-ui-specification.md) | [02 架构](client/02-architecture.md) §5 线程 |
|
||||
| 加字段、改表、写 SQL | [03 数据模型](client/03-data-model.md) | [02 架构](client/02-architecture.md) §7 数据所有权 |
|
||||
| 对接 Admin、写 Gateway | [04 接口契约](client/04-admin-api-contract.md) | [03 数据模型](client/03-data-model.md) §5 Outbox |
|
||||
| 对接 Admin、写 Gateway | [04 接口契约](client/04-admin-api-contract.md) | [07 联调手册](admin/07-设备登记联调手册.md) |
|
||||
| 写自动化、控制手机 | [02 架构](client/02-architecture.md) §9 | [06 质量与安全](client/06-quality-security.md) §4 |
|
||||
| 碰采购、下单相关代码 | [06 质量与安全](client/06-quality-security.md) §3 | [01 需求](client/01-requirements.md) §4.2 |
|
||||
| 写测试 | [06 质量与安全](client/06-quality-security.md) §2 | — |
|
||||
@@ -50,6 +50,7 @@
|
||||
| 加字段、改表、写 SQL | [03 数据模型](admin/03-data-model.md) | [02 架构](admin/02-architecture.md) §2 分层 |
|
||||
| 改 Excel 导入 | [03 数据模型](admin/03-data-model.md) §3.3 | [00 术语表](admin/00-glossary.md) §3 upsert |
|
||||
| 改给 Client 的接口 | [04 Client 接口实现](admin/04-client-api.md) | [Client 侧契约](client/04-admin-api-contract.md) |
|
||||
| 和 Admin 联调、登记新设备 | [07 设备登记联调手册](admin/07-设备登记联调手册.md) | [Client 侧契约](client/04-admin-api-contract.md) §5 |
|
||||
| 写测试 | [06 质量与安全](admin/06-quality-security.md) §2 | — |
|
||||
| 搞不清这功能到底要不要做 | [01 产品需求基线](admin/01-requirements.md) | — |
|
||||
|
||||
@@ -86,6 +87,7 @@
|
||||
| [04 Client 接口实现](admin/04-client-api.md) | 服务端怎么实现那三个接口 |
|
||||
| [05 界面规范](admin/05-ui-specification.md) | 三段式布局、四个页面、弹窗 |
|
||||
| [06 质量、安全与测试](admin/06-quality-security.md) | 测试、Web 安全、发布门禁 |
|
||||
| [07 设备登记联调手册](admin/07-设备登记联调手册.md) | **给 Client 开发者**:怎么让新设备登记成功 |
|
||||
|
||||
## 文档标注说明
|
||||
|
||||
|
||||
Reference in New Issue
Block a user