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>
This commit is contained in:
chengma
2026-08-06 11:44:39 +08:00
co-authored by Claude Opus 5
commit 0b645ee8b3
14 changed files with 2842 additions and 0 deletions
+32
View File
@@ -0,0 +1,32 @@
# 本地数据:数据库、日志、截图、控件树 XML
# 位置和用途见 docs/client/03-data-model.md §2.1
client/data/
data/
# 打包产物
build/
dist/
*.spec
# Python
__pycache__/
*.py[cod]
*.egg-info/
.venv/
venv/
# 跑 demo 脚本时在当前目录生成的调试产物
# (src/demo1/auto_v1.py 会写这些,不要提交)
/*.xml
/*.png
client/*.xml
client/*.png
# 编辑器
.vscode/
.idea/
*.swp
# Windows
Thumbs.db
Desktop.ini