chengmaandClaude Opus 5
0b645ee8b3
按初级程序员可读、可维护的目标重写项目文档，并定案三项设计决策。 新增 - 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>
104 lines
2.5 KiB
Markdown
104 lines
2.5 KiB
Markdown
# 工单与归档模板
|
||
|
||
复制下面的模板去用，不要每次从零写。字段说明见 [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. **一个工单只干一件事。** 顺手改的无关内容单独开工单，别混进来。
|