docs: 归档 Client 登记接口验收结果 (#12)

docs/task/12-admin-新增幂等-client-登记接口.md

@@ -0,0 +1,70 @@
+# 12 Admin 新增幂等 Client 登记接口
+
+- 类型：跨模块接口需求
+- 关联 Client 工单：#11
+- 父级大工单：#1
+- 所属 MVP / 版本：#2 / MVP
+- 状态：验收通过
+- 日期：2026-08-06
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/12
+
+## 背景与目标
+
+Client 设置页保存当前设备时，需要只登记或更新 Client，不能通过领取接口顺带登记，否则可能领取任务并造成任务丢失。本任务新增独立、幂等且没有任务副作用的登记接口。
+
+## 最终方案
+
+- 新增 `PUT /api/v1/client/registration`。
+- 使用 `X-Client-Id` 作为 Client 唯一键，相同编号重复请求执行 upsert。
+- 登记与 claim 共用 `ClientProfileRequest` 和字段校验。
+- 显式登记携带非空名称时更新名称；空名称更新保留原名称，新建时用 Client ID 兜底。
+- 更新 Android 设备信息、能力、`last_seen_at` 和 `updated_at`。
+- 登记接口不读取、领取、修改或返回任务。
+- claim 保留隐式登记兼容行为，但不覆盖已有 Client 名称。
+- 不增加心跳、租约或 Client 状态查询接口。
+
+## 改了哪些
+
+- `admin/handler/api/client_api.go`：增加登记路由和 Handler。
+- `admin/service/profile.go`：增加请求结构、字段校验和模型转换。
+- `admin/service/service.go`：增加显式登记编排。
+- `admin/repository/client.go`：实现显式/隐式登记名称规则和 upsert。
+- `admin/service/profile_test.go`、`client_test.go`：增加校验、幂等、名称和无任务副作用测试。
+- `docs/client/04-admin-api-contract.md`、`docs/admin/04-client-api.md`、`docs/admin/07-设备登记联调手册.md`：确认接口契约和联调方式。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 新 Client 登记返回 200 并写入 clients | 通过 |
+| 相同 Client ID 重复登记不新增记录 | 通过 |
+| 显式登记更新非空名称 | 通过 |
+| 空名称更新保留已有名称 | 通过 |
+| 更新设备、能力和最近活动时间 | 通过 |
+| 登记不读取、领取、修改或返回任务 | 通过 |
+| claim 隐式登记保持兼容 | 通过 |
+| 非法资料返回统一错误结构 | 通过 |
+| token 和硬件指纹不进入日志 | 通过 |
+| Admin 全量检查和隔离 HTTP 验证 | 通过 |
+
+## 验证
+
+执行了：
+
+```powershell
+go vet ./...
+go test ./...
+```
+
+另外使用 Gin `httptest` 和隔离 SQLite 数据库验证：合法登记返回 `200`；相同编号登记两次后记录数保持 1；数据库中的名称、设备地址和能力正确；空 `supported_types` 返回 `422 INVALID_CLIENT_PROFILE`。隔离验证文件已删除，没有改动正式数据库。
+
+## 已知技术债
+
+- 当前没有长期保留的 Handler 层登记接口测试，HTTP 行为主要由 Service 测试、联调手册实跑记录和本次隔离验证覆盖。
+- `admin/handler/api/client_api.go` 中仍有“共三个接口”“没有独立登记接口”等过期注释，应在后续小型整理任务中修正。
+- 上述问题不影响 Client #11 开始调用登记接口。
+
+## 相关提交
+
+- `02073ea` 定义幂等 Client 登记契约
+- `5a5c1f1` 新增幂等 Client 登记接口