chengmaandClaude Opus 5
1f95de373a
起因：实测发现 Codex 不会主动把 338 行的规则手册当判断依据—— 问“能用 PySide6 吗”答“可以评估”，问“加个 emoji 图标”直接给改法， 问“改错别字要建工单吗”结论对但依据是通用常识、不是 §0 的实际条件。 三次都表现为“知道代码事实，但不应用项目规则”。 对策一：红线上收 - 根 AGENTS.md 开头新增 5 条红线（Qt 绑定、下单开关、风控、凭据、 不可逆阶段），并明确“不要论证其可行性，先停下来问用户” 对策二：把约束放到 agent 必然会打开的文件里 - pdd_ui.py / pdd_ui_event.py / settings_ui.py / settings_ui_event.py 写入模块 docstring，说明各自职责和最易踩的硬性规则 - 四个文件目前只有 docstring，无实现 同步修正 - ui_event.py 已拆成按页面分的四个文件，更新 client/AGENTS.md 的代码分层规则和 02 §3.1 的现状差异表 未包含：ui_main.py 和 demo1/auto_v1.py 的同类 docstring， 这两个文件承载尚未提交的代码，留待代码提交时一并处理。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
项目文档索引
本目录保存项目级文档。长期稳定的 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 尚未完成，真实采购的最终下单开关、认证方式和部分字段仍需评审确认；这些事项已在对应文档中标注为 [待定]，并给出了临时默认值。