项目文档索引

本目录保存项目级文档。长期稳定的 Client 基线文档放在 docs/client，实施过程和完成记录放在 docs/task，两者不得混用。

新人从这里开始

文档	用途
00 上手指南	装环境、装依赖、连手机、把程序跑起来、常见报错
00 术语表	Outbox、幂等、SKU 等专业词的一句话解释

按任务找文档

不用通读全部文档，按你要做的事挑：

我要做的事	主要看	顺带看
第一次把项目跑起来	00 上手指南	—
改界面、加页面、调表格	05 界面交互规范	02 架构 §5 线程
加字段、改表、写 SQL	03 数据模型	02 架构 §7 数据所有权
对接 Admin、写 Gateway	04 接口契约	03 数据模型 §5 Outbox
写自动化、控制手机	02 架构 §9	06 质量与安全 §4
碰采购、下单相关代码	06 质量与安全 §3	01 需求 §4.2
写测试	06 质量与安全 §2	—
搞不清这功能到底要不要做	01 产品需求基线	—
打包成 exe、改文件路径	01 需求 §8.1	03 数据模型 §2
建工单、写归档	模板	根目录 AGENTS.md

无论做哪一样，都必须先看一遍 client/AGENTS.md（技术栈和红线）。

Client 基线文档

文档	用途
01 产品需求基线	定义目标、范围、业务流程和验收边界
02 系统架构	定义模块、依赖、线程模型和故障恢复原则
03 数据模型	定义 SQLite 表、状态和 pdd_data JSON 结构
04 Admin 接口契约	定义 Client 与 Admin 的版本化接口边界
05 界面交互规范	定义 PDD 任务页、设置页和表格交互
06 质量、安全与测试	定义测试策略、采购安全、日志和发布门禁

文档标注说明

基线文档中的条目按下面三档标注，没有标注的默认是 [必须]：

标注	含义
[必须]	不许改。要改先走工单，并经用户确认
[建议]	默认这么做；有更合适的做法可以换，但要在工单里说明原因
[待定]	还没定下来。文档会给一个临时默认值，先按临时值做，别停工

文档生命周期

• docs/client 只记录不随单个任务频繁变化的产品和技术基线。
• 日常需求、缺陷、进度、阻塞和方案变更以 Gitea 工单为事实来源。
• 单元任务完成后，按 AGENTS.md 归档到 docs/task/<工单号>-<简短名称>.md。
• 基线发生实质变化时，必须先更新对应 Gitea 工单并完成评审，再在同一任务中更新这里的相关文档。

文档和代码对不上怎么办

现在的代码还没做到文档描述的目标状态，对不上是正常的，已知差异列在 02 架构 §3.1。

按下面处理，不要一发现不一致就停工：

情况	怎么办
差异已经列在 §3.1 差异清单里	按代码现状继续做，不用停
差异不在清单里，但只影响写法、不影响业务结果	按文档做，并在工单里记一句
差异会影响业务结果（金额、数量、状态、下单与否、数据结构）	停下来，在工单里说明，等用户确认哪边是对的

判断不了算不算"影响业务结果"时，按最后一行处理。

文档状态

当前 Client 文档为 基线草案。Admin 尚未完成，真实采购的最终下单开关、认证方式和部分字段仍需评审确认；这些事项已在对应文档中标注为 [待定]，并给出了临时默认值。