12 Admin 新增幂等 Client 登记接口

类型：跨模块接口需求
关联 Client 工单：#11
父级大工单：#1
所属 MVP / 版本：#2 / MVP
状态：验收通过
日期：2026-08-06
Gitea 工单：#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 验证	通过

验证

执行了：

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 开始调用登记接口。

3.1 KiB Raw Blame History