chengmaandClaude Opus 5
6ae768463f
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>
项目文档索引
本目录保存项目级文档。长期稳定的基线文档按子项目放在 docs/client 和 docs/admin，
实施过程和完成记录放在 docs/task，两者不得混用。
项目由两部分组成
| 子项目 | 是什么 | 技术栈 | 规则文件 |
|---|---|---|---|
| Client | Windows 桌面客户端，控制安卓设备在拼多多采集和下单 | Python 3.10 + PyQt5 | client/AGENTS.md |
| Admin | 本地 Web 管理端，管理商品、货运单、采购任务和客户端 | Go + Gin + HTML 模板 | admin/AGENTS.md |
两者通过三个 HTTP 接口交互，契约以 Client 侧的接口契约 为准。
两个子项目技术栈完全不同，规则不通用。 别拿 Client 的经验套 Admin，反之亦然。
新人从这里开始
| 我要做 | 先读 |
|---|---|
| 上手 Client | Client 上手指南 + Client 术语表 |
| 上手 Admin | Admin 上手指南 + Admin 术语表 |
| 搞清楚整条业务链路 | Admin 需求 §3 |
按任务找文档
不用通读全部文档，按你要做的事挑：
Client（桌面客户端）
| 我要做的事 | 主要看 | 顺带看 |
|---|---|---|
| 第一次把项目跑起来 | 00 上手指南 | — |
| 改界面、加页面、调表格 | 05 界面交互规范 | 02 架构 §5 线程 |
| 加字段、改表、写 SQL | 03 数据模型 | 02 架构 §7 数据所有权 |
| 对接 Admin、写 Gateway | 04 接口契约 | 03 数据模型 §5 Outbox |
| 写自动化、控制手机 | 02 架构 §9 | 06 质量与安全 §4 |
| 碰采购、下单相关代码 | 06 质量与安全 §3 | 01 需求 §4.2 |
| 写测试 | 06 质量与安全 §2 | — |
| 搞不清这功能到底要不要做 | 01 产品需求基线 | — |
| 打包成 exe、改文件路径 | 01 需求 §8.1 | 03 数据模型 §2 |
Admin（Web 管理端）
| 我要做的事 | 主要看 | 顺带看 |
|---|---|---|
| 第一次把项目跑起来 | 00 上手指南 | — |
| 改页面、加表格列 | 05 界面规范 | 02 架构 §4 模板 |
| 加字段、改表、写 SQL | 03 数据模型 | 02 架构 §2 分层 |
| 改 Excel 导入 | 03 数据模型 §3.3 | 00 术语表 §3 upsert |
| 改给 Client 的接口 | 04 Client 接口实现 | Client 侧契约 |
| 写测试 | 06 质量与安全 §2 | — |
| 搞不清这功能到底要不要做 | 01 产品需求基线 | — |
通用
| 我要做的事 | 看这里 |
|---|---|
| 建工单、写归档 | 模板 + 根目录 AGENTS.md |
无论做哪一样，都必须先看一遍对应子项目的 AGENTS.md（技术栈和红线）。
Client 基线文档
| 文档 | 用途 |
|---|---|
| 00 上手指南 | 装环境、连手机、跑起来、常见报错 |
| 00 术语表 | Outbox、幂等、不可逆阶段等 |
| 01 产品需求基线 | 目标、范围、任务类型、打包策略 |
| 02 系统架构 | 分层、线程模型、Worker 模板 |
| 03 数据模型 | SQLite 表、状态机、pdd_data 结构 |
| 04 Admin 接口契约 | 两个子项目的接口边界，改动需同步 Admin |
| 05 界面交互规范 | PDD 任务页、设置页、表格交互 |
| 06 质量、安全与测试 | 测试策略、采购安全、发布门禁 |
Admin 基线文档
| 文档 | 用途 |
|---|---|
| 00 上手指南 | 装 Go、跑起来、常见报错 |
| 00 术语表 | 货运单、upsert、SKU 映射等 |
| 01 产品需求基线 | 业务链路、四个模块、状态定义 |
| 02 系统架构 | 分层、目录、模板组织、前端约束 |
| 03 数据模型 | SQLite 表、Excel 导入规则 |
| 04 Client 接口实现 | 服务端怎么实现那三个接口 |
| 05 界面规范 | 三段式布局、四个页面、弹窗 |
| 06 质量、安全与测试 | 测试、Web 安全、发布门禁 |
文档标注说明
基线文档中的条目按下面三档标注，没有标注的默认是 [必须]：
| 标注 | 含义 |
|---|---|
[必须] |
不许改。要改先走工单，并经用户确认 |
[建议] |
默认这么做；有更合适的做法可以换，但要在工单里说明原因 |
[待定] |
还没定下来。文档会给一个临时默认值，先按临时值做，别停工 |
文档生命周期
docs/client和docs/admin只记录不随单个任务频繁变化的产品和技术基线。- 日常需求、缺陷、进度、阻塞和方案变更以 Gitea 工单为事实来源。
- 单元任务完成后，按
AGENTS.md归档到docs/task/<工单号>-<简短名称>.md。 - 基线发生实质变化时，必须先更新对应 Gitea 工单并完成评审，再在同一任务中更新这里的相关文档。
- 接口契约改动必须两边同步：
docs/client/04-*和docs/admin/04-*在同一个工单里一起改。
文档和代码对不上怎么办
现在的代码还没做到文档描述的目标状态，对不上是正常的。 Client 的已知差异列在 02 架构 §3.1； Admin 目前尚未开始编码。
按下面处理，不要一发现不一致就停工：
| 情况 | 怎么办 |
|---|---|
| 差异已经列在差异清单里 | 按代码现状继续做，不用停 |
| 差异不在清单里，但只影响写法、不影响业务结果 | 按文档做，并在工单里记一句 |
| 差异会影响业务结果（金额、数量、状态、下单与否、数据结构） | 停下来，在工单里说明，等用户确认哪边是对的 |
判断不了算不算"影响业务结果"时，按最后一行处理。
文档状态
Client 和 Admin 文档均为 基线草案。
Admin 尚未开始编码；顺运宝同步方式、认证方式和部分字段仍需确认，
这些事项已在对应文档中标注为 [待定]，并给出了临时默认值。