chengma/cmautobuy
2
0
Fork 0
Code Issues 89 Pull Requests Actions Packages Projects Releases Wiki Activity
75 Commits 1 Branch 0 Tags
107366f1f01bd9fa30b5ce18691e5bbf5db3720a
Commit Graph
75 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
chengma 107366f1f0 docs: 补充任务 #28 实现提交 2026-08-07 16:14:59 +08:00
chengma 77ec0d997b docs: 补充任务 #28 链接校验记录 2026-08-07 16:14:44 +08:00
chengma f1c2700fde fix: 校验 PDD 采集商品链接 (#28) 2026-08-07 16:14:43 +08:00
chengma 0044442f5d docs: 归档任务 #28 2026-08-07 16:13:48 +08:00
chengma 4aff22c009 feat: 实现 PDD 商品采集基础服务 (#28) 2026-08-07 16:12:39 +08:00
chengma d2decc7a29 docs: 记录任务 #29 验收结果 2026-08-07 15:57:57 +08:00
chengma 52f11eecdc docs: 归档任务 #29 2026-08-07 15:55:18 +08:00
chengma 6d863a1a8a feat: 检测 Android 设备 PDD 安装状态 (#29) 2026-08-07 15:54:12 +08:00
chengma a6e3fe0417 docs: 完成 Android 设备工单验收 (#21 #22 #25 #26 #27) 2026-08-07 15:20:48 +08:00
chengmaandClaude Opus 5 fbfa2fce3d docs: 归档任务 #19 
如实记录打回两次的过程，以及两次都是架构角色的检查指令给窄了：
第一次给的 grep 只覆盖「四个模块」，漏掉「四个页面」这个变体；
第二次改成直接给 6 处确切行号，并点明哪两处的「四个」是对的不许改。

未验证四项：浏览器实机交互、主题与缩放、采购任务真实创建路径
（入口尚未实现，验证用的是手工插库）、目标列规格顺序与工单示意图不同。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 15:17:32 +08:00
chengmaandClaude Opus 5 f0d7da37cf feat: 采集采购页，采集与采购统一展示 (#19) 
原来的采购任务页是骨架：var rows []gin.H 从不查库，页面永远为空；
TODO 写的还是只查 task_type = 'purchase'。所以 #18 建出来的采集任务
在界面上哪儿都看不到——用户点完「创建采集任务」只能盯着
collect_status 猜。

模块名定为「采集采购」（用户指定），直接点出这页装的是哪两类任务，
比泛称「任务」更能让人一眼知道点进去看什么。路由 /tasks 不变，
改路由会让已有书签和文档链接全失效，没有收益。

列不按类型并列——两种任务字段完全不同，并列会让采集任务行一半是空列。
改成固定列 + 一列「目标」把业务信息概括成一句话：
  采集  PDD 737116531267
  采购  SO-001 · M/黑色 · 2件 · ≤¥42.00
拼接逻辑在 service 层，模板只负责显示。

统计和列表共用同一个筛选条件拼装函数。分开写的话总有一天会忘了
给统计也加条件，数字和表格对不上，操作员会以为页面坏了。

无主任务的客户端列显示「—」。#17 之后采集任务默认无主，这列会大量为空。

详情弹窗只读，采购专有字段（数量、价格上限、目标规格）在采集任务里
整段不出现，不显示空行。复用 #18 的弹窗机制，app.js 无需改动。

顺带清掉 PDD 页加进来之后一直没跟上的模块计数：多处「四个模块/四个页面」
改成五个。其中 06-quality-security.md 那两处是验证清单，
照着做的人只会测四个页面，PDD 页永远不在回归范围里。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 15:16:05 +08:00
chengma c07fe56ac3 docs: 归档任务 #27 2026-08-07 15:13:07 +08:00
chengma 57503978bd fix: 修复 Wi-Fi ADB 拔线后刷新丢失 (#27) 2026-08-07 15:12:32 +08:00
chengma ffaeb55a25 docs: 归档任务 #26 2026-08-07 14:53:57 +08:00
chengma dc9b000a36 fix: 启动时恢复已保存的 Android 设备 (#26) 2026-08-07 14:53:28 +08:00
chengmaandClaude Opus 5 e40ce5a13c fix: 商品卡在「采集中」无法恢复 (#24) 
MarkCollecting 原本只在 pending/failed 时成功，而全库只有客户端提交结果
才会把 collecting 改走。客户端离线、崩溃、任务被删都是常态——一旦发生，
这个商品就永久报废，界面上没有任何入口能救，只能改数据库。

改成 collecting 超过 15 分钟视为已超时，允许重新创建采集任务。

判定在读取那一刻现算，仍是同一条原子 UPDATE，不加后台清理协程：
后台扫要处理"扫到一半客户端正好提交了"的竞态，本项目已经在并发上
栽过两次，能不引入并发就不引入。

15 分钟写成有名字的常量并注明理由：采集本身几十秒到两分钟，加上排队
等客户端来领。宁可短也不要长——采集是只读的，多采一次没有副作用，
而卡死的代价是商品永久报废。

已知取舍：超时后老任务还在队列里，客户端上线可能两个都领走、采两次。
可接受（只读，后一次覆盖前一次），已写进代码注释和 03-data-model.md，
免得后来人当成 bug 去"修"成加锁或加租约——租约和心跳是被明确移除的设计。

时间比较用字符串，依赖 NowISO 产出定宽 UTC。已在 NowISO 上加注释：
改成带时区偏移的本地时间会让这个比较静默失效，不报错但判断全错。

界面两处：超时的显示「采集中（超时）」，否则操作员盯着「采集中」
不知道它已经死了；跳过原因按正在采集/已采集/已删除分类计数，
一个都没建成时告诉操作员还要等多久。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 14:42:54 +08:00
chengma ec7705fd17 docs: 归档任务 #25 2026-08-07 14:42:37 +08:00
chengma d478e690b6 feat: 支持 USB 设备转 Wi-Fi ADB (#25) 2026-08-07 14:42:00 +08:00
chengmaandClaude Opus 5 bf81bad741 docs: 记录 #18 #23 验收通过 
#18 归档状态改为验收通过，补上实现与归档的提交哈希，并链到 #23。
#23 新增归档：为什么用 .search-narrow 类而不是改被五个页面共用的
.toolbar input[type="text"]；搜索按钮靠左是收窄的自然结果，没有额外样式。

两份都保留了"未验证到的部分"——浏览器实机交互、主题与缩放，
用户已实机确认后验收。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 14:19:44 +08:00
chengmaandClaude Opus 5 96267f4a18 feat: PDD 商品页工具条文案与宽度调整 (#23) 
三处：
- 「创建」改成「添加 PDD 商品」。同一条工具条上还有「创建采集任务」，
  两个都以「创建」开头，第一次用的人分不清哪个是加商品、哪个是发起采集。
- 搜索框收到 30%。
- 「搜索」按钮紧挨输入框——这是收窄的自然结果：表单里没有会伸展的
  元素之后，多余空间留在按钮之后，按钮就不会被顶到很右边。

用 .search-narrow 类而不是改 .toolbar input[type="text"]：
后者被五个页面共用（蝦皮/顺运宝/任务/客户端/PDD 各一个搜索框），
改了会把另外四页一起改掉。

用 flex 而不是 width：工具条是 flex 布局，width 会被 flex-grow 盖掉。
min-width: 160px 仍从通用规则继承，窄屏时不会缩到没法输入。

表单上的 grow 类保留，它负责把「删除」按钮顶到最右侧。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 14:15:35 +08:00
chengma c96228fb72 docs: 归档任务 #22 2026-08-07 14:14:48 +08:00
chengma 27a09e524c feat: 保存当前使用的 Android 设备 (#22) 2026-08-07 14:13:40 +08:00
chengmaandClaude Opus 5 d2de7331bb fix: 修复迁移被原地改写导致老库缺表 (#20) 
#16 原地改写了 migration v1 而不是新增一条。Migrate 只在
user_version < 版本数时才跑，老库版本号已越过 v1，改写后的语句
永远不会重跑——程序拿着对不上的库静默启动，点到 PDD 商品页才 500。

修法：v1 逐字恢复成 7ad82b7 的原样，#16 的结构改动全部挪进 v3。
全新库也走 v1→v2→v3，与老库升级跑的是同一份 v3 代码，
不需要维护两条路径。

v3 必须认两种 user_version=2：#16 的原地改写让这个版本号对应
两种不同结构（原始 v1 建的没有 pdd_products，改写后的 v1 建的已经有）。
所以 v3 每一步先查 PRAGMA table_info / sqlite_master 看实际结构
再决定做不做，只有版本号推进是无条件的；已是最终结构的库
只推版本号，日志也照实说，不谎称"新增 pdd_products"。

旧 sku_mappings 数据丢弃并打日志：新主键需要 pdd_option_key，
那是 Go 的 OptionKey() 用 json.Marshal 算的，SQL 复现不了。
硬凑一个键出来，轻则映射静默失效，重则撞上别的规格静默买错东西——
后者正是 #16 存在的全部意义。

collecting 映射成 pending：原样保留会让 MarkCollecting 永远不成功，
那个商品再也建不了采集任务，界面上表现为按钮永远置灰且无法解开。

表重建按 SQLite 官方 12 步顺序：先建 _new 再 RENAME。
实测 ALTER TABLE RENAME TO 会自动重写别的表里指向它的外键子句，
先 RENAME 让位会把 shopee_skus 的外键改成指向一张马上被删的表。

另加两道闸：启动时 CheckSchema 缺表即拒绝启动（不是警告后继续）；
admin/AGENTS.md 写死"migrations 只追加、不得修改已发布条目"。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 12:23:24 +08:00
chengma 03f91c2488 docs: 归档任务 #21 2026-08-07 11:54:05 +08:00
chengma 45fde81b8b feat: 实现 Android 设备搜索 (#21) 2026-08-07 11:53:03 +08:00
chengmaandClaude Opus 5 4975c6898d docs: 归档任务 #18 
记录审查时实跑的结果：4 并发建采集任务只产生 1 条、商品标题 XSS 在
列表页和弹窗均已转义、13 规格弹窗渲染正常。

如实记录打回过程：架构角色先按 §7.3"单处笔误"例外自改 §4.3，
发现该例外不成立（全库 5 处），剩余 3 处按 §7.2 打回。

未验证四项：浏览器实机交互、主题与缩放、20+ 规格弹窗滚动、artifact_ref。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 11:27:06 +08:00
chengmaandClaude Opus 5 eb8d357f5a feat: PDD 商品页面 (#18) 
打通 Client↔Admin 闭环的一环：录入 PDD 链接 → 创建采集任务 →
客户端领走去采 → 规格和价格显示在页面上。#16 写的 MarkCollecting 和
SoftDeletePddProduct 至此才有生产调用方。

链接解析严格、不做容错兜底：goods_id 上有 UNIQUE 约束，防重全靠它。
猜一个的话同一商品会存成好几行、采好几遍，规格映射还说不清指向哪一行。
短链一律拒绝，卡域名是为了拦"粘了淘宝链接"这种失误。

创建采集任务先占状态再建任务：MarkCollecting 只在 pending/failed 时成功，
同时充当"有没有人已经在采"的判断，与建任务在同一事务里，
所以并发点多次只会建出一个任务（实测 4 并发 → 1 条）。

submit.go 的 collectedData 增加 Dimensions —— 没有它就只能按 Go 的 map
遍历，而 map 无序，同一商品每次刷新"颜色/尺码"的先后都可能变。

顺带修 #16 一处缺陷：EnsurePddProduct 复活分支清空了 skus_json 却漏了
title，导致复活后状态显示"未采集"但标题还留着旧值。

审查打回一次：清理"PDD 链接唯一的录入口"这一过期说法（全库 5 处），
以及 shopee.go 里"空 → no_link"的过期 TODO —— no_link 已在 #16
从 CHECK 约束删除，照写会直接撞约束。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 11:27:06 +08:00
chengmaandClaude Opus 5 fab20cfd2f docs: 归档任务 #16 #17 
按 AGENTS.md §9 补上两份归档。内容是审查时实跑的结果，不是复述报告。

#16 PDD 商品数据独立成表
- 记录三处超出工单但必要的决定：TaskExists → GetTaskInfo、
  采错商品做成整体回滚的硬拒绝、复活时清空旧采集结果
- 记录审查时补验的 HTTP 层端到端：422 拒绝后幂等记录 0 条
  （若残留会导致客户端重试永远拿到缓存的失败响应）
- 三项未验证：界面未实现、MarkCollecting/SoftDeletePddProduct 无生产调用方、
  artifact_ref 未规范化

#17 claim 支持领取无主任务
- 记录契约变更：§5.1 从「只分配给指定 Client」改为两种并存
- 记录优先级测试的构造方式（无主任务 created_at 更早，
  没有优先级规则时会红）
- 遗留：tasks 表缺「需要真实下单」标记，本次把无主任务开放后风险被放大，
  开启真实下单前必须补

两个工单保持 open，等用户验收。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 11:02:21 +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
chengmaandClaude Opus 5 ab988b39de docs: 新增多模型协作规则，回填 Gitea 约定 
CLAUDE.md（新增）
按"错了多久才会被发现"划分角色，而不是按任务难度：
设计错要几周后买错货才发现，实现错跑测试就红，复述错人一看就知道。
所以 Opus 设计和审查、Sonnet 实现、Haiku 只读查询。

关键几条：
- 工单里每条约束必须写清"在防什么"。下游没有上游的上下文，
  理由不明的约束会被当成冗余优化掉
- 实现角色不得改工单范围、不得删改看不懂的约束或测试
  （本项目测试名就是规则本身，删掉等于删掉一条业务规则）
- 审查五步，第一步是架构角色亲自跑验证，不采信报告结论
- 打回必须说清：哪条没达到、当前是什么、期望是什么
- 同一个点打回两次仍不达标，问题在工单不在实现，
  这时该改工单或自己接手，继续打回只是消耗

AGENTS.md §0 重写
Gitea 一直可用（#1~#13 在正常使用），但 §0 还留着 <待填写>，
于是"未配置"成了跳过建单的长期借口。这次 PDD 那批就是靠聊天里的
草稿直接开工的，没有工单号。

- §0.1 填上真实地址和仓库；写明工单层级靠标题前缀区分，
  不使用标签和里程碑（13 条工单实测两者均为空，也不要去建）
- §0.2 聊天里的草稿不算工单；不得默认直通，
  不得因为上次直通过就默认这次也行
- §0.3 防呆：任何地方看到本仓库的工单链接就说明 Gitea 可用，
  必须立刻回填 §0.1 并停止直通。提交信息里不得再出现
  "Gitea 未配置 / 无工单号"这类说法

两份文档边界划清：CLAUDE.md 只讲协作方式，项目规则一律指向
AGENTS.md 不复述——复述一次就走样一次。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 10:28:05 +08:00
chengmaandClaude Opus 5 998c06a2bf feat: PDD 商品数据独立成表 (#16) 
原来 pdd_data 是 shopee_products 上的一个 JSON 字段，两个蝦皮商品指向
同一个 PDD 链接时会各存一份、各采一次；collect_status 描述的是 PDD 商品的
状态，却挂在蝦皮商品上，两份可能不一致。

更要紧的是 PDD 商品变动频繁（A 下架就得换 B），而 sku_mappings 只按
shopee_sku_id 做键——换商品后旧映射还在，B 恰好有同名规格但完全是另一件货
时会静默买错，事后查不出来。

改动
- 新增 pdd_products 表：id 主键 + goods_id UNIQUE + 4 个状态值（去掉
  no_link，「未填链接」改由 shopee_products.pdd_goods_id 为空表达）+
  软删除可复活
- shopee_products 去掉 pdd_data / collect_status / collect_error /
  collected_at，pdd_goods_id 改为引用
- sku_mappings 主键改为 (shopee_sku_id, pdd_goods_id)，新增 pdd_option_key。
  查映射永远带上当前 PDD 商品，换商品后天然查不到旧映射，不需要删数据；
  换回原商品时旧映射直接复用
- 新增 OptionKey()：用 json.Marshal 实现（Go 序列化 map 按键名排序，
  天然规范化），不自己拼字符串——规格文字里可能含 = 或 ;。
  存映射和查 SKU 必须用同一个函数，各写一遍会静默算出不同结果
- 采集结果改落 pdd_products，新增两条校验：
  返回的 goods_id 与请求不符 → 整体回滚拒绝（422），不静默存下；
  skus 为空数组 → 置 failed 而非 collected，否则界面显示"已采集"
  但数据毫无用处

实施时超出工单但必要的三处
- TaskExists 重构为 GetTaskInfo：原函数只返回蝦皮 goods_id，
  而采集结果要按 PDD goods_id 落库，不改取不到正确的键
- 复活时一并清空旧采集结果（skus_json / collect_msg / collected_at），
  否则复活后会显示"已采集"但数据是删除前的
- 删除 repository/shopee.go：两个函数签名全变且已迁到 pdd.go，留着是死代码

已验证（Go 1.23.0）
- go vet / gofmt / go test 全过，55 个测试
- 端到端补验了工单未覆盖的 HTTP 层：goods_id 不符返回 422
  COLLECT_GOODS_MISMATCH 且整体回滚（skus_json 空、任务仍 claimed、
  幂等记录 0 条）；skus 为空返回 200 但状态 failed

遗留
- MarkCollecting / SoftDeletePddProduct 暂无调用方，等界面工单接上
- artifact_ref 存 diagnostics 原始 JSON，未按 client-001:artifacts/... 规范化，
  因 Client 侧尚未定义 diagnostics 结构
- 界面未实现（工单明确排除），四个页面仍为骨架

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 10:27:39 +08:00
chengma 036144ec8e docs: 记录 #11 验收通过 2026-08-06 18:00:34 +08:00
chengma 988444407a docs: 归档任务 #11 2026-08-06 17:58:13 +08:00
chengma fab5778049 feat: 保存并登记当前 Client (#11) 2026-08-06 17:57:49 +08:00
chengma 262f48c778 docs: 归档 Client 登记接口验收结果 (#12) 2026-08-06 17:41:19 +08:00
chengma 42d6478646 docs: 记录 Admin 热重载验收通过 (#13) 2026-08-06 17:36:22 +08:00
chengma 446510bfb9 docs: 归档 Admin 热重载任务 (#13) 2026-08-06 17:35:05 +08:00
chengma 7a6c647eda chore: 为 Admin 启动脚本增加热重载 (#13) 2026-08-06 17:34:56 +08:00
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
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 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 0279ffd60e docs: 更新 Client 现状差异表 
核对代码后重写 02 §3.1，删掉两行已完成的、更新其余行的现状描述。

已对齐（移出差异表）
- 顶级导航：已是 2 个（pdd任务 / 参数设置）
- PDD 任务页：已有表格、筛选、搜索、状态条和 canFetchMore 增量加载
- 顺带核对：db_schema.py 已建 4 张表，status 的 8 个取值与
  03 §3 完全一致，也没有残留已废弃的 sync_state / lease_token / admin_status

仍是差异的行更新了现状描述，主按钮文案那行的行号从 485/487 改为 470/472。

新发现一处文档自相矛盾：02 §3 建议目录写 src/ui/main_window.py，
但 client/AGENTS.md 的代码分层规则写 src/ui_main.py，代码按后者走。
已在表下说明，建议把建议目录改成与代码一致，需另开工单决定。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-06 16:55:55 +08:00
chengma 11f9d91179 docs: 归档任务 #10 2026-08-06 16:39:00 +08:00
chengma c412e8afe2 feat(client): add Admin Gateway mock contract (#10) 2026-08-06 16:38:28 +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
chengma 0d38eedee1 docs: 归档任务 #9 2026-08-06 16:32:14 +08:00
chengma 583e441e17 feat(client): connect PDD task list to SQLite (#9) 2026-08-06 16:31:34 +08:00
chengma be6ee3d880 docs: 归档任务 #8 2026-08-06 16:22:30 +08:00