# 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 登记接口