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:
Vendored
+103
@@ -0,0 +1,103 @@
|
||||
# 工单与归档模板
|
||||
|
||||
复制下面的模板去用,不要每次从零写。字段说明见 [AGENTS.md](../../AGENTS.md)。
|
||||
|
||||
- **建单时**用模板 A,贴到 Gitea 工单正文里。
|
||||
- **做完后**用模板 B,另存为 `docs/task/<工单号>-<简短名称>.md`。
|
||||
|
||||
模板里带 `(选填)` 的行,没有内容就整行删掉,不要留个空标题。
|
||||
|
||||
---
|
||||
|
||||
## 模板 A:单元任务工单(建单时用)
|
||||
|
||||
```markdown
|
||||
## 基本信息
|
||||
|
||||
- 类型:需求 / 缺陷 / 重构
|
||||
- 父级大工单:#
|
||||
- 所属 MVP / 版本:
|
||||
- 阶段:
|
||||
|
||||
## 要解决什么
|
||||
|
||||
<!-- 现在是什么情况,为什么要改。缺陷要写清怎么复现。 -->
|
||||
|
||||
## 做什么 / 不做什么
|
||||
|
||||
- 做:
|
||||
- 不做:
|
||||
|
||||
## 怎么做
|
||||
|
||||
<!-- 已经和用户确认过的方案。写清楚改哪几个文件、动不动数据库、动不动接口。 -->
|
||||
|
||||
## 验收标准
|
||||
|
||||
<!-- 一条一条能打勾的。别写"功能正常"这种没法验证的。 -->
|
||||
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
## 怎么验证
|
||||
|
||||
<!-- 具体到能复制粘贴的命令;需要真机的要写明。 -->
|
||||
|
||||
## 风险和回退(选填)
|
||||
|
||||
<!-- 可能出什么问题,出了怎么退回去。碰采购、数据库迁移、Admin 接口的必填。 -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板 B:完成归档(`docs/task/` 用)
|
||||
|
||||
```markdown
|
||||
# <工单号> <标题>
|
||||
|
||||
- 类型:需求 / 缺陷 / 重构
|
||||
- 父级大工单:#
|
||||
- 所属 MVP / 版本:
|
||||
- 状态:已完成
|
||||
- 日期:YYYY-MM-DD
|
||||
- Gitea 工单:<链接>
|
||||
|
||||
## 背景与目标
|
||||
|
||||
<!-- 原来什么问题,这次要达到什么。 -->
|
||||
|
||||
## 最终方案
|
||||
|
||||
<!-- 实际怎么做的。和建单时的方案有出入就写清楚差在哪、为什么改。 -->
|
||||
|
||||
## 改了哪些
|
||||
|
||||
<!-- 主要文件清单 + 一句话说明各改了什么。 -->
|
||||
|
||||
## 验收结果
|
||||
|
||||
| 验收标准 | 结果 |
|
||||
|---|---|
|
||||
| | 通过 / 未通过 |
|
||||
|
||||
## 测试
|
||||
|
||||
- 执行的命令:
|
||||
- 结果:
|
||||
- **没验证到的部分**:<!-- 必填。没有就写"无"。真机行为、迁移、并发这类经常漏,漏了要写出来。 -->
|
||||
|
||||
## 遗留问题(选填)
|
||||
|
||||
## 相关提交
|
||||
|
||||
- `<提交哈希>` <提交说明>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 写工单的几个提醒
|
||||
|
||||
1. **验收标准要能打勾。** "表格显示正常"没法验证;"1000 条数据下滚动到底能继续加载,且当前选中行不丢"可以验证。
|
||||
2. **"没验证到的部分"不许留空。** 真机没跑就写真机没跑。瞒下来的风险最后都会变成事故。
|
||||
3. **不确定的东西写进工单,不要只写在代码注释里。** 聊天记录和注释都不算数。
|
||||
4. **一个工单只干一件事。** 顺手改的无关内容单独开工单,别混进来。
|
||||
Reference in New Issue
Block a user