chengma/cmautobuy
2
0
Fork 0
Code Issues 89 Pull Requests Actions Packages Projects Releases Wiki Activity
37 Commits 1 Branch 0 Tags
5a5c1f1f683e118005cf4edc366c65e0819ee747
Commit Graph
4 Commits
Author SHA1 Message Date
chengmaandClaude Opus 5 5a5c1f1f68 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>
 2026-08-06 17:31:38 +08:00
chengmaandClaude Opus 5 7ad82b7795 feat: 实现结果提交接口与幂等处理 
补齐 submit_result / submit_failure，Admin 侧的三个接口全部可用，
Client 的完整一圈（领取 → 执行 → 提交）现在能走通了。

实现
- 幂等：idempotency_keys 表。同键同内容返回上次的响应且不重复落库，
  同键不同内容返回 409。幂等记录与业务写入在**同一事务**，
  分开写的话业务成功但幂等没记上，重试会被重复处理
- 无条件接受（契约 §4.1，最容易写错的一条）：
  任务已取消、已重派给别人，都照样接受结果——客户端中途不查任务状态，
  必然会提交"Admin 这边已经不要了"的结果，而它可能真的已经下过单，
  这些数据必须留痕
- 采集任务的结果落到商品级 shopee_products.pdd_data 并置 collected；
  失败则置 failed 并把原因写进 collect_error，操作员才看得见
- 失败状态映射：retry_wait→assigned，其余同名
- 三个接口都刷新 last_seen_at

新增 task_claims 表（migrations v2）
契约要求"只有从未分配给该客户端的任务才返回 403"，但 assigned_client
只记当前归属，重派后就查不出原来那台领过——而契约又要求那种情况必须接受。
没有这张表这条规则根本没法判断。顺带得到一份审计记录。

修复第二个并发 bug：事务必须 BEGIN IMMEDIATE
并发提交报 SQLITE_BUSY。根因是 Go 的 db.Begin() 默认发 BEGIN DEFERRED，
事务开始时不拿写锁，多个事务各自先读再想升级成写就互相卡死，
这种情况 busy_timeout 救不了。DSN 加 _txlock=immediate 后事务一开始
就排队拿锁。实测 6 个并发事务：默认失败 5/6，加参数后 0/6。
已写进 docs/admin/03-data-model.md §2.1。

已验证（Go 1.23.0）
- 30 个单元测试全过，并发用例重复 20 次稳定通过
- 端到端：claim 200 → 提交 200 → 重复提交返回完全相同的响应 →
  同键不同内容 409 → 没领过的客户端 403 → 任务不存在 404 →
  缺 Idempotency-Key 400；库里 task=succeeded、幂等 1 条、领取历史 1 条

说明：Gitea 尚未配置，本次无对应工单号。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-06 17:04:49 +08:00
chengmaandClaude Opus 5 6ae768463f feat: 实现客户端注册与任务领取接口 
Admin 的第一个业务功能。选它打头是因为它是穿透所有层的最薄一条竖切
（HTTP → handler/api → service → repository → SQLite → handler/web → 页面），
一个工单把分层模式立起来，后面四个模块照抄；同时它是与 Client 联调的接口，
能解锁另一条并行的工作线。

实现
- POST /tasks/claim：注册 + 领取。注册就在这里做，没有单独的注册接口，
  也没有心跳（理由见 docs/admin/04-client-api.md §3）
- 领取用条件更新 + 检查影响行数防并发，SQLite 没有 SELECT FOR UPDATE
- 客户端列表页：查询、按名称搜索、批量删除
- 在线状态是**算出来的**（last_seen_at 在 10 分钟内），数据库里没有该字段
- CSRF 中间件：双提交 Cookie，手写 82 行不引依赖。
  **只挂页面路由**，/api/v1/client/* 不能加——Client 不是浏览器、没有 Cookie
- 14 个单元测试

修复一个真 bug：PRAGMA 必须写进 DSN
并发领取测试报 database is locked (SQLITE_BUSY)。根因是
PRAGMA busy_timeout 每连接生效，而 database/sql 是连接池——
db.Exec("PRAGMA ...") 只作用于当时那条连接，池子新开的连接没执行过。
单线程正常、一并发就炸。改成 DSN 传参后并发测试跑 20 次全过。
这个坑已写进 docs/admin/03-data-model.md §2.1。

与工单的两处差异
- 去掉 name_is_custom 列后，"人工改的名字不被覆盖"改用更简单的做法：
  ON CONFLICT DO UPDATE SET 里不含 name，即只在首次注册时写入。
  效果相同，零额外字段、零迁移。已同步 04 §3
- 验收项"不向 dry_run 客户端分配真实下单任务"**未实现**：
  tasks 表没有字段标记任务是否需要真实下单。当前真实下单开关默认关闭、
  MVP 全是演练模式，暂不出问题，但开真实下单前必须补该字段，需另开工单

已验证（Go 1.23.0）
- go vet / gofmt / go test 全过，并发测试重复 20 次稳定通过
- 端到端：无任务 claim 204；插入任务后 claim 200 且 payload 含
  goods_url/goods_id/options/quantity/max_price_cent、无租约无 Admin 状态；
  重复 claim 204；缺 X-Client-Id 400；POST 无 CSRF token 403；
  列表页两台客户端在线状态与统计正确

说明：Gitea 尚未配置，本次无对应工单号。
submit_result / submit_failure 及其幂等处理留给下一个工单。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-06 16:56:18 +08:00
chengmaandClaude Opus 5 799ee33045 feat: 搭建 Admin 项目骨架（Go + Gin + html/template） 
可运行的骨架：四个页面能打开、数据库自动建表、给 Client 的三个接口
按契约响应。业务逻辑留 35 处 TODO(骨架)，每处标明要点和文档章节。

结构（对应 docs/admin/02-architecture.md §2/§3）
- handler/web + handler/api 分开：页面要 CSRF、出错渲染错误页；
  接口要认证、出错返回 JSON。混在一起迟早写错
- service 不认识 *gin.Context，方便不起服务器直接单测
- 只有 repository 能写 SQL
- 模板用 {{define "目录/名字"}}，一次全部 ParseFS 进来不冲突
- 模板和静态资源用 //go:embed 打进二进制

已实测（Go 1.23.0，本机验证）
- go build / go vet / gofmt 全部通过
- 单文件产物 34MB，无需 cgo
- 四个页面 + 静态资源均 200，/ 正确 302 到 /shopee
- 建表 7 张 + 索引 10 个，user_version=1，二次启动不重复建表
- claim 带 X-Client-Id 返回 204（无任务可领），
  缺 X-Client-Id 返回 400 + 契约格式的 JSON 错误体

依赖版本被 Go 1.23.0 卡死，已钉住并写进文档
- gin v1.11.0        （v1.12.0 起要求 Go >= 1.25.0）
- modernc.org/sqlite v1.38.0（v1.40.0 起要求 >= 1.24.0，v1.48.0 起 >= 1.25.0）
- excelize v2.9.1    （尚未入 go.mod，写导入功能时再加）
直接 go get 不带版本会拉到最新版并报 requires go >= 1.25.0，
所以文档里的命令一律带版本号。要升依赖就得先升 Go。

一处主动调整：迁移语句从「一个字符串装多条 SQL」改成 [][]string 逐条执行。
database/sql 的 Exec 对一次多条语句的支持因驱动而异，拆开最稳妥，
报错还能精确到第几条。

说明：Gitea 尚未配置，本次无对应工单号。
admin/testdata/ 只有 README，脱敏小样本需人工制作。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-06 16:33:45 +08:00