76 lines
4.3 KiB
Markdown
76 lines
4.3 KiB
Markdown
|
# 项目文档索引
|
|||
|
|
|
|||
|
|
本目录保存项目级文档。长期稳定的 Client 基线文档放在 `docs/client`，实施过程和完成记录放在 `docs/task`，两者不得混用。
|
|||
|
|
|
|||
|
|
## 新人从这里开始
|
|||
|
|
|
|||
|
|
| 文档 | 用途 |
|
|||
|
|
|---|---|
|
|||
|
|
| [00 上手指南](client/00-getting-started.md) | 装环境、装依赖、连手机、把程序跑起来、常见报错 |
|
|||
|
|
| [00 术语表](client/00-glossary.md) | Outbox、幂等、SKU 等专业词的一句话解释 |
|
|||
|
|
|
|||
|
|
## 按任务找文档
|
|||
|
|
|
|||
|
|
**不用通读全部文档**，按你要做的事挑：
|
|||
|
|
|
|||
|
|
| 我要做的事 | 主要看 | 顺带看 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 第一次把项目跑起来 | [00 上手指南](client/00-getting-started.md) | — |
|
|||
|
|
| 改界面、加页面、调表格 | [05 界面交互规范](client/05-ui-specification.md) | [02 架构](client/02-architecture.md) §5 线程 |
|
|||
|
|
| 加字段、改表、写 SQL | [03 数据模型](client/03-data-model.md) | [02 架构](client/02-architecture.md) §7 数据所有权 |
|
|||
|
|
| 对接 Admin、写 Gateway | [04 接口契约](client/04-admin-api-contract.md) | [03 数据模型](client/03-data-model.md) §5 Outbox |
|
|||
|
|
| 写自动化、控制手机 | [02 架构](client/02-architecture.md) §9 | [06 质量与安全](client/06-quality-security.md) §4 |
|
|||
|
|
| 碰采购、下单相关代码 | [06 质量与安全](client/06-quality-security.md) §3 | [01 需求](client/01-requirements.md) §4.2 |
|
|||
|
|
| 写测试 | [06 质量与安全](client/06-quality-security.md) §2 | — |
|
|||
|
|
| 搞不清这功能到底要不要做 | [01 产品需求基线](client/01-requirements.md) | — |
|
|||
|
|
| 打包成 exe、改文件路径 | [01 需求](client/01-requirements.md) §8.1 | [03 数据模型](client/03-data-model.md) §2 |
|
|||
|
|
| 建工单、写归档 | [模板](templates/task.md) | 根目录 [AGENTS.md](../AGENTS.md) |
|
|||
|
|
|
|||
|
|
无论做哪一样，都必须先看一遍 [client/AGENTS.md](../client/AGENTS.md)（技术栈和红线）。
|
|||
|
|
|
|||
|
|
## Client 基线文档
|
|||
|
|
|
|||
|
|
| 文档 | 用途 |
|
|||
|
|
|---|---|
|
|||
|
|
| [01 产品需求基线](client/01-requirements.md) | 定义目标、范围、业务流程和验收边界 |
|
|||
|
|
| [02 系统架构](client/02-architecture.md) | 定义模块、依赖、线程模型和故障恢复原则 |
|
|||
|
|
| [03 数据模型](client/03-data-model.md) | 定义 SQLite 表、状态和 `pdd_data` JSON 结构 |
|
|||
|
|
| [04 Admin 接口契约](client/04-admin-api-contract.md) | 定义 Client 与 Admin 的版本化接口边界 |
|
|||
|
|
| [05 界面交互规范](client/05-ui-specification.md) | 定义 PDD 任务页、设置页和表格交互 |
|
|||
|
|
| [06 质量、安全与测试](client/06-quality-security.md) | 定义测试策略、采购安全、日志和发布门禁 |
|
|||
|
|
|
|||
|
|
## 文档标注说明
|
|||
|
|
|
|||
|
|
基线文档中的条目按下面三档标注，没有标注的默认是 `[必须]`：
|
|||
|
|
|
|||
|
|
| 标注 | 含义 |
|
|||
|
|
|---|---|
|
|||
|
|
| `[必须]` | 不许改。要改先走工单，并经用户确认 |
|
|||
|
|
| `[建议]` | 默认这么做；有更合适的做法可以换，但要在工单里说明原因 |
|
|||
|
|
| `[待定]` | 还没定下来。文档会给一个临时默认值，先按临时值做，别停工 |
|
|||
|
|
|
|||
|
|
## 文档生命周期
|
|||
|
|
|
|||
|
|
- `docs/client` 只记录不随单个任务频繁变化的产品和技术基线。
|
|||
|
|
- 日常需求、缺陷、进度、阻塞和方案变更以 Gitea 工单为事实来源。
|
|||
|
|
- 单元任务完成后，按 `AGENTS.md` 归档到 `docs/task/<工单号>-<简短名称>.md`。
|
|||
|
|
- 基线发生实质变化时，必须先更新对应 Gitea 工单并完成评审，再在同一任务中更新这里的相关文档。
|
|||
|
|
|
|||
|
|
## 文档和代码对不上怎么办
|
|||
|
|
|
|||
|
|
现在的代码还没做到文档描述的目标状态，**对不上是正常的**，已知差异列在 [02 架构](client/02-architecture.md) §3.1。
|
|||
|
|
|
|||
|
|
按下面处理，不要一发现不一致就停工：
|
|||
|
|
|
|||
|
|
| 情况 | 怎么办 |
|
|||
|
|
|---|---|
|
|||
|
|
| 差异已经列在 §3.1 差异清单里 | 按代码现状继续做，不用停 |
|
|||
|
|
| 差异不在清单里，但只影响写法、不影响业务结果 | 按文档做，并在工单里记一句 |
|
|||
|
|
| 差异会影响业务结果（金额、数量、状态、下单与否、数据结构） | **停下来**，在工单里说明，等用户确认哪边是对的 |
|
|||
|
|
|
|||
|
|
判断不了算不算"影响业务结果"时，按最后一行处理。
|
|||
|
|
|
|||
|
|
## 文档状态
|
|||
|
|
|
|||
|
|
当前 Client 文档为 **基线草案**。Admin 尚未完成，真实采购的最终下单开关、认证方式和部分字段仍需评审确认；这些事项已在对应文档中标注为 `[待定]`，并给出了临时默认值。
|