 chengma
|
51062f4c7b
|
feat: 领取 Admin 采集任务并保存本地 (#30)
|
2026-08-07 16:42:31 +08:00 |
|
|
chengmaandClaude Opus 5
|
dd387e3ee5
|
feat: claim 支持领取无主任务 (#17)
PDD 商品页要能「创建采集任务」而不指定客户端——采集只是浏览商品页，
没有副作用，哪台设备采都一样。但原来的查询是
WHERE assigned_client = ? AND status = 'assigned'
无主任务（assigned_client 为空 + pending）永远没人能领，建出来就是死的。
改动
- ClaimNextTask 同时查两种：指定给本机的 + 无主的
- 排序 ORDER BY (assigned_client IS NULL), priority DESC, created_at
——指定给本机的优先。显式分配是人为决定，应当先兑现
- 原子更新两种情况合成一条语句：对"指定给我的"写 assigned_client
是写同一个值无副作用；对无主的，这一步就是"谁领到就标记谁"
- 表结构不用动（assigned_client 本来可空，status 已有 pending）
推翻了一条已定案的规则
Client 契约 §5.1 原写「Admin 只把任务分配给指定的 Client」，
现改为两种并存并说明各自适用场景：
- 采集任务不指定客户端
- 采购任务可指定可留空。涉及钱和账号——不同设备可能登着不同的
拼多多账号，需要指定账号时必须显式分配，留空即接受"谁先抢到谁下单"
Client 侧对两种没有区别，不需要知道任务原来有没有主。
已验证（Go 1.23.0）
- 新增 7 个测试，全量 62 个全过
- 并发抢占用例重复 20 次稳定：8 个客户端抢同一条无主任务，
正好 1 个拿到，且 assigned_client 记的就是那个赢家
- 既有测试未受影响，"只领分配给自己的"仍然成立
一处仍未解决的风险（已记入 #17 风险表）
tasks 表没有字段标记"该任务需要真实下单"，所以契约里
"不向 dry_run 客户端分配真实下单任务"实际无法执行。
真实下单开关关闭时不出问题，开启前必须补该字段。
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
2026-08-07 10:53:32 +08:00 |
|
|
chengma
|
02073eab37
|
docs: define idempotent Client registration contract (#12)
|
2026-08-06 17:21:36 +08:00 |
|
|
chengmaandClaude Opus 5
|
62d46bf10a
|
docs: 新增设备登记联调手册，并定案 client.name
面向 Client 开发者的实操文档，目标是让一台新设备出现在 Admin 的
客户端列表里。文中所有请求和响应都是在真实运行的 Admin 上跑出来的。
新增 docs/admin/07-设备登记联调手册.md
- 先讲清"没有注册接口，登记是 claim 的副作用"
- **重点提示 204 不是错误**：新设备第一次 claim 必然 204，
它同时意味着登记成功。这是最容易被 Client 误判成失败的地方
- 设备号必须持久化、永不变——变了 Admin 会当成新机器，
列表里会堆一串僵尸记录
- 设备名只在首次登记时采纳，之后 Admin 侧改名不会被覆盖。
这个行为会让人困惑（"我改了 Client 怎么 Admin 没变"），先说清楚
- 四步验证流程 + 可直接复制的 curl + 手工插测试任务的 SQL
- 7 条常见问题，含"列表里多出好几台一样的机器"这类实际会碰到的
- 列出 Client 侧待办清单，标明前两条做完就能登记成功
定案 client.name（原 [待定]）
Client 设置页本来就有「设备名」输入框（deviceNameInput，50 字上限），
只是没接进 ClientInfo。Admin 仍容忍它缺失，缺了用 X-Client-Id 兜底，
所以 Client 先不发也不影响登记。
同步更新
- docs/client/04-admin-api-contract.md §5：请求示例补 client 字段，
加"204 不是错误"的必须项，并指向本手册
- docs/README.md：两处导航加入口，Client 侧"对接 Admin"那行也指过来
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
2026-08-06 17:08:58 +08:00 |
|
|
chengmaandClaude Opus 5
|
0b645ee8b3
|
docs: 建立面向初级程序员的文档基线
按初级程序员可读、可维护的目标重写项目文档，并定案三项设计决策。
新增
- docs/client/00-getting-started.md 上手指南：装环境、跑起来、常见报错
- docs/client/00-glossary.md 术语表：Outbox、幂等、不可逆阶段等
- docs/templates/task.md 工单与归档模板
- client/requirements.txt 固定依赖版本
- .gitignore 屏蔽 data/、打包产物和调试产物
设计定案
- 本地库只存已领取任务，不再镜像 Admin 任务池；已完成任务永久保留
- 去掉租约、心跳和状态回查；Admin 接口从 5 个降到 3 个
（本项目人工付款，重复下单只产生未付款订单，由人工审核处理）
- 打包采用 PyInstaller one-dir：launcher.exe + app/ + data/，便携模式
文档改进
- 补齐可直接抄的代码模板：Worker 线程、事务写库、幂等键、增量加载、错误提示、路径解析
- 状态机由 ASCII 图改为完整转换表，并补充崩溃恢复规则
- 消除文档与现有代码的冲突，02 新增“现状与目标差异”清单
- 待确认事项一律给出临时默认值，避免阻塞开发
- AGENTS.md 新增“小改动直通”，工单必填项由 8 项压缩到 6 项
说明：Gitea 尚未配置，本次无对应工单号；AGENTS.md §0 的 Gitea 信息待补。
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
2026-08-06 11:44:39 +08:00 |
|