feat: 新增幂等 Client 登记接口 (#12)

PUT /api/v1/client/registration —— 设置页点"保存"时调用,
只登记客户端,不碰任务。

为什么需要它
原设计"注册就在 claim 里做"有个真问题:设置页保存被迫调 claim,
而 claim 可能真的领到一个任务——Admin 那边已把任务标成 claimed,
Client 必须可靠落库否则任务就丢了。一个"保存设置"的动作
不该承担"领取任务并保证不丢"的责任。这违反了本项目自己的原则
(05 §1:界面上只有一个会产生外部后果的命令)。

实现
- ClientProfileRequest + Validate() 由**登记和领取共用**,
  避免两个入口的结构和校验各写一份、迟早漂移
- 校验:名称 <=50 字(按字符不按字节,中文一个字三字节)、
  supported_types 非空且只含 collect/purchase、platform 只支持 android、
  purchase_mode 必填且只允许 dry_run/live、schema_versions 均为正整数
- 非法内容返回 422 INVALID_CLIENT_PROFILE,错误消息指明具体字段
- UpsertClient 加 explicit 参数区分名称规则:
  显式登记(用户点保存)带非空名称时更新名称;
  隐式登记(claim 顺带)永不更新,否则操作员改的名字会被反复冲掉

已验证(Go 1.23.0)
- 单元测试 40 个全过,含"登记不产生任何任务副作用"的快照比对
- 端到端逐条走完手册 §5.2~5.7:重复登记记录数恒为 1;
  更新/空名称行为正确;插入任务后登记 3 次任务字段完全未变且仍可领取;
  四种非法输入均 422 且不写库;claim 不受影响

一处行为变更需注意
名称归属规则改了:原来是"Admin 操作员永远赢",现在是"最后一次
显式操作赢"——用户在 Client 点保存会覆盖 Admin 侧改的名字。
按 #12 文档实现,已拆成三个独立测试盯住三种情况。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-08-06 17:31:38 +08:00
co-authored by Claude Opus 5
parent 02073eab37
commit 5a5c1f1f68
9 changed files with 516 additions and 79 deletions
+6
View File
@@ -260,6 +260,12 @@ Client 契约里散落的 Admin 侧硬要求,汇总在这里,**可以直接
- [ ] 登记接口不读取、领取或修改任务
- [ ] 显式登记更新非空名称,空名称更新保留已有名称
- [ ] 登记接口校验名称、任务类型、执行模式和结构版本
- [x] `PUT /registration` 幂等:重复调用不产生重复记录
- [x] 登记**不读取、不领取、不修改任何任务**,响应不含 `task`
- [x] 显式登记带非空名称更新名称;空名称保留原名;新建时用 client_id 兜底
- [x] claim 隐式登记**不更新名称**
- [x] 登记和 claim **共用同一套字段校验**,非法内容返回 `422 INVALID_CLIENT_PROFILE`
- [x] 校验不通过时不写库
- [ ] `claim` 一次只返回一个任务,且只返回分配给该客户端的
- [ ] `claim` 原子完成,并发下不会把同一任务发给两个客户端
- [ ] `claim` 无任务时返回 `204`,不是 `200` 加空对象