chengma/cmautobuy
2
0
Fork 0
Code Issues 89 Pull Requests Actions Packages Projects Releases Wiki Activity
48 Commits 1 Branch 0 Tags
fab20cfd2fab652aaa09272cbe3d738b3fade610
Commit Graph
48 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
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
chengma e60b0c91ac feat: 定义任务模型与 SQLite Repository (#8) 2026-08-06 16:21:39 +08:00
chengma d64ebef922 docs: 归档任务 #7 2026-08-06 16:11:29 +08:00
chengma 69f0812b9c feat: 实现 SQLite 初始化与 v1 迁移 (#7) 2026-08-06 16:10:57 +08:00
chengma 2fafa05d91 docs: 归档任务 #6 2026-08-06 15:58:35 +08:00
chengmaandClaude Opus 5 4f920f9d8b docs: 排除蝦皮原始报表，并同步主按钮文案 
raw_data 不进 Git
原始报表含逐商品台币销售额等商业数据，进了 Git 就是永久历史。
- .gitignore 排除 raw_data/
- 改掉三处"仓库里有一份样本"的失真表述，改为向项目负责人索取
- 06 §2.1 相应加强：既然大样本不进库，admin/testdata/ 下的脱敏小样本
  就必须提交，否则别人拉下来测试跑不了；并写明脱敏做法

主按钮文案 开始自动获取 → 获取任务 ⇄ 停止获取
只改按钮标签。"自动获取"作为功能名保留（状态栏、Tab 顺序、
协调器开关等处不动），05 §4.1 加了一句说明两者不是一回事。

已知遗留：pdd_ui.py 自身仍不一致——构造时用「获取任务」，
但状态机 485/487 行仍是「开始自动获取」/「停止自动获取」，
会覆盖掉构造时的文字。该文件有未提交改动，本次未触碰，
差异已记入 02 §3.1，需另开工单修。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-06 15:58:09 +08:00
chengma ed663904bb feat: 增加当前设备保存与设备号生成 (#6) 2026-08-06 15:57:59 +08:00
chengma f6da83666b docs: 更新任务 #5 空表格验收 2026-08-06 15:51:08 +08:00
chengmaandClaude Opus 5 9f2a2299c2 chore: 统一换行符配置 
现象：文件内容一个字没改，git diff 却显示整行整行地变。
根因是同一份文件在 Windows 和 WSL 之间来回编辑，被存成了
CRLF 和 LF 两种版本，diff 里全是假改动，review 时看不出真正改了什么。

配置说明
- 默认文本文件在仓库里统一存 LF
- .bat / .cmd / .ps1 保持 CRLF，否则 Windows 下可能执行异常
- .xlsx / .png / .exe / .db 等标记为 binary，绝不做换行符转换，
  否则文件会损坏

注意：本次只加配置，没有对已有文件做规范化。
需要在工作区干净时另外跑一次 git add --renormalize .

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-06 15:51:05 +08:00
chengma 1bc597fbd5 fix: 无设备时填充 Android 空表格 (#5) 2026-08-06 15:50:47 +08:00
chengmaandClaude Opus 5 90379347b4 docs: 建立 Admin 子项目的文档基线 
仓库从单子项目变成两个：client（Python + PyQt5 桌面端）和
admin（Go + Gin + HTML 模板 Web 管理端）。两者技术栈完全不同，
规则各自独立，只通过三个 HTTP 接口交互。

新增 admin/AGENTS.md 和 docs/admin/ 共 9 份文档，结构与 docs/client/ 对齐。

关键设计决策（均已与用户确认）
- 四模块：蝦皮数据 / 顺运宝数据 / 采购任务 / 客户端列表，
  统一三段式布局（工具条 / 带勾选的表格 / 状态条）
- 蝦皮数据拆成商品表 + SKU 表：报表本身就是两层结构，
  且 PDD 链接是商品级的，放 SKU 级会重复维护
- pdd_data 存商品级，一个 PDD 商品采一次，所有订单共用
- SKU 映射独立成表且可复用，同一蝦皮 SKU 只需人工匹配一次
- PDD 链接人工填写，采集按钮就放在填链接的编辑弹窗里
- 任务分配给指定客户端；不加心跳，注册在领取时完成，
  在线状态由 last_seen_at 派生
- SQLite 驱动固定 modernc.org/sqlite（纯 Go 免 cgo，go build 直接出 exe）
- 不引入前端框架和 npm 构建，只允许原生 JS 或 htmx

基于样本文件 raw_data/蝦皮数据样本.xlsx 实测得出的约束
- 11287 行 = 5195 商品汇总行 + 6092 SKU 行，导入必须分开处理
- 商品規格ID 零重复，是天然主键
- 规格原文两种格式各占 53.4% / 46.6%，只解析【】会漏掉一半
- 平均每商品仅 1.17 个 SKU，报表不是全量目录，
  因此必须支持手动新增，且货运单外键不能加硬约束

同步更新
- 根 AGENTS.md 开头的指针改为两个子项目对照表
- docs/README.md 重构为双子项目索引
- .gitignore 加 admin/data/、admin.exe、Excel 锁文件

说明：Gitea 尚未配置，本次无对应工单号。
raw_data/ 未提交，含台币销售额等商业数据，待用户决定。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-06 15:49:04 +08:00
chengma cbcfaca728 docs: 更新任务 #4 响应式搜索框验收 2026-08-06 15:40:23 +08:00
chengma ecc9d47c35 fix: 让任务关键词框自适应宽度 (#4) 2026-08-06 15:40:02 +08:00
chengma 665eddb7b5 docs: 归档任务 #5 2026-08-06 15:31:37 +08:00
chengma 41f7cbb6f3 feat: 实现设置页设备管理界面 (#5) 2026-08-06 15:31:05 +08:00
chengma 3190d1ff78 docs: 更新任务 #4 筛选栏验收 2026-08-06 14:36:57 +08:00
chengma 8f6e657820 fix: 调整任务筛选栏布局 (#4) 2026-08-06 14:36:35 +08:00
chengma aad20fece8 docs: 更新任务 #4 验收变更 2026-08-06 14:26:15 +08:00
chengma 2322b46315 fix: 无数据时保留任务表格空行 (#4) 2026-08-06 14:25:56 +08:00
chengma b6be66c91c docs: 归档任务 #4 2026-08-06 14:19:14 +08:00
chengma ad197004ed feat: 实现 PDD 任务列表 UI (#4) 2026-08-06 14:18:42 +08:00
chengma f7958c6391 chore: 提交现有客户端自动化代码 2026-08-06 14:07:55 +08:00
chengma 956fc727be docs: 归档任务 #3 2026-08-06 12:06:49 +08:00
chengma 5916de4b92 refactor: 拆分页面 UI 模块 (#3) 2026-08-06 12:06:16 +08:00
chengmaandClaude Opus 5 1f95de373a docs: 增加红线清单，并把约束下沉到代码文件 
起因：实测发现 Codex 不会主动把 338 行的规则手册当判断依据——
问“能用 PySide6 吗”答“可以评估”，问“加个 emoji 图标”直接给改法，
问“改错别字要建工单吗”结论对但依据是通用常识、不是 §0 的实际条件。
三次都表现为“知道代码事实，但不应用项目规则”。

对策一：红线上收
- 根 AGENTS.md 开头新增 5 条红线（Qt 绑定、下单开关、风控、凭据、
  不可逆阶段），并明确“不要论证其可行性，先停下来问用户”

对策二：把约束放到 agent 必然会打开的文件里
- pdd_ui.py / pdd_ui_event.py / settings_ui.py / settings_ui_event.py
  写入模块 docstring，说明各自职责和最易踩的硬性规则
- 四个文件目前只有 docstring，无实现

同步修正
- ui_event.py 已拆成按页面分的四个文件，更新 client/AGENTS.md
  的代码分层规则和 02 §3.1 的现状差异表

未包含：ui_main.py 和 demo1/auto_v1.py 的同类 docstring，
这两个文件承载尚未提交的代码，留待代码提交时一并处理。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-06 12:01:38 +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