cmautobuy

44 Commits 1 Branch 0 Tags

3 Commits

Include renames

Author	SHA1	Message	Date
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

Author

SHA1

Message

Date

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