docs: define idempotent Client registration contract (#12)

This commit is contained in:
chengma
2026-08-06 17:21:36 +08:00
parent 62d46bf10a
commit 02073eab37
8 changed files with 306 additions and 206 deletions
+5 -4
View File
@@ -172,8 +172,9 @@ Admin 的职责是把这三方的数据串起来,最终产出 Client 能执行
**注册方式:**
- `[必须]` 客户端**调用领取接口时自动注册**:新序列号就新增,已有就更新。
**不设单独的注册或心跳接口**,理由见 [04 Client 接口实现](04-client-api.md) §3。
- `[必须]` 设置页通过独立登记接口幂等新增或更新 Client;该接口不得领取或修改任务。
- `[必须]` 领取接口保留隐式登记作为旧 Client 的兼容兜底。
- `[必须]` 不设心跳接口,在线状态由登记、领取和提交产生的最近活动时间派生。
- `[必须]` `状态` 是**派生字段,不存库**:
最近活动时间在 N 分钟内算"在线",否则"离线"。`[建议]` N 默认 10 分钟。
- 名称由客户端上报,操作员可以在 Admin 这边改成好记的名字。
@@ -261,7 +262,7 @@ MVP 包含:
- 顺运宝数据的**手工录入或造数**(同步按钮占位);
- 规格匹配弹窗与可复用映射;
- 创建采购任务并分配客户端;
- 给 Client 的三个接口:领取、提交结果、提交失败;
- 给 Client 的四个接口:登记、领取、提交结果、提交失败;
- 客户端自动注册与在线状态。
MVP 之后:
@@ -303,7 +304,7 @@ MVP 之后:
- PDD 链接**人工填写**,入口在蝦皮数据模块的编辑弹窗,采集按钮也在那里。
- 任务**分配给指定客户端**,Client 只领分给自己的。
- **不加心跳接口**,注册在领取时完成,在线状态由最近活动时间派生。
- **不加心跳接口**;设置页显式登记,领取接口保留兼容登记,在线状态由最近活动时间派生。
- SKU 映射**独立成表且可复用**,同一蝦皮 SKU 只人工匹配一次。
- 货运单的"规格 SKU"**直接对应蝦皮 `商品規格ID`**,不需要转换。
但**不加外键**——本地查不到该 SKU 是常态,见 [03 数据模型](03-data-model.md) §4。