docs: 增加红线清单,并把约束下沉到代码文件

起因:实测发现 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>
This commit is contained in:
chengma
2026-08-06 12:01:38 +08:00
co-authored by Claude Opus 5
parent 0b645ee8b3
commit 1f95de373a
7 changed files with 121 additions and 5 deletions
+26
View File
@@ -0,0 +1,26 @@
"""PDD 任务页的界面结构。
这一页显示**本机已领取的全部任务**(正在做的和早已做完的),
提供搜索、筛选、详情,以及启动/停止自动获取。
完整规范见 `docs/client/05-ui-specification.md`。
改动本文件前必读 `client/AGENTS.md`。以下几条最容易踩:
- 本文件只负责显示和把用户操作转发出去,**不写业务逻辑**,
不发 Admin 请求、不查数据库、不碰手机。这些放 `pdd_ui_event.py`。
- 任务表格必须用**模型/视图**(`QAbstractTableModel` + `TableView`),
并用 `remote_task_id` 作为任务身份。**不要用表格行号**——
行号会随排序和筛选变化,拿它当身份必出错。
- 不要为每个单元格创建常驻 `QWidget`(几万行会把内存吃光)。
“详情”那一列用委托绘制。
- 不要把完整的 `pdd_data` 放进表格模型,那是详情数据,
查看详情时再从数据库读。
- 表格数据只增不减(已完成任务永久保留),所以增量加载是必须的,
照抄 `docs/client/05-ui-specification.md` §5.3 的模板。
- 空状态要分情况:从没领过任务、筛选无结果、加载失败,文案不能一样。
- 图标用 `FluentIcon`,**不得用表情符号**。
- 页面 `objectName` 固定为 `pddTaskPage`,不要改。
注意:本页唯一会产生外部后果(真的去操作手机、可能下单)的命令是
“开始自动获取”。其余操作全部只读本地数据库。
"""
+21
View File
@@ -0,0 +1,21 @@
"""PDD 任务页的事件绑定。
把 `pdd_ui.py` 里控件的信号,接到查询、任务引擎等实际动作上。
改动本文件前必读 `client/AGENTS.md`。以下几条最容易踩:
- **禁止在 Qt 主线程做任何阻塞的事**:Admin 请求、uiautomator2/ADB 调用、
`time.sleep()`、轮询、大 XML 解析、批量写文件。做了界面就会卡死转圈。
- 长任务统一用 `QObject` + `moveToThread` 的 Worker 写法,
模板照抄 `docs/client/02-architecture.md` §5.1。
**不要**用 `QThread` 子类、`QRunnable` 或 Python 的 `threading`。
- 后台结果只能通过**信号**回到主线程,Worker 里一行界面代码都不许有。
- 窗口关闭时要断开信号并置标志位,否则迟到的后台结果会访问
已经销毁的控件、直接崩溃。做法见同文档 §5.2。
- 数据库读写走 Repository,**不要在这里拼业务 SQL**。
- “开始自动获取”会真的去操作手机、可能下单;“搜索”只读本地数据库。
两者必须分开,不得共用入口。
- 普通成功不弹窗,更新界面即可;可恢复错误用 `InfoBar`
(模板见 `docs/client/05-ui-specification.md` §9.1);
只有必须让用户当场做决定时才用模态对话框。
"""
+22
View File
@@ -0,0 +1,22 @@
"""设置页的界面结构。
分四组:Admin、Android 设备、自动化、安全与诊断。
完整规范见 `docs/client/05-ui-specification.md` §8。
改动本文件前必读 `client/AGENTS.md`。以下几条最容易踩:
- **认证状态只显示“已配置/未配置”或掩码值,绝不回显完整 token。**
- 本文件只负责显示和输入转发,“测试连接”这类会联网、会连手机的动作
放 `settings_ui_event.py`,且必须走后台线程。
- 表单必须有**可见标签**,占位符不能当标签用(占位符一输入就没了,
用户会忘记这个框是干嘛的)。
- 用可滚动布局和 Fluent 设置卡片;MVP 采用显式“保存设置”按钮,
不要在同一页混用即时保存。
- 校验失败时保留用户已输入的内容,并把焦点移到第一个出错的字段,
不要清空重来。
- 图标用 `FluentIcon`,**不得用表情符号**。
- 页面 `objectName` 固定为 `settingsPage`,不要改。
注意:设备连接**不是**独立的顶级页面,统一放在本页,
见 `docs/client/01-requirements.md` §3。
"""
+25
View File
@@ -0,0 +1,25 @@
"""设置页的事件绑定。
处理保存设置、测试 Admin 连接、测试设备连接等动作。
改动本文件前必读 `client/AGENTS.md`。以下几条最容易踩:
- **凭据(token、密码)不写进 SQLite 的 `app_settings`,也不写进日志。**
存到 Windows 凭据管理器,见 `docs/client/06-quality-security.md` §7。
`data/` 目录是明文的、设计上就是整个拷走的,拷一次等于泄露一次。
- “测试连接”会联网、会连手机,**必须走后台线程**,
用 `QObject` + `moveToThread`(模板见 `docs/client/02-architecture.md` §5.1)。
在主线程里直接连,界面会卡住好几秒。
- 非敏感设置存 `app_settings` 表,键名沿用 `<分组>.<名称>` 的写法,
清单见 `docs/client/03-data-model.md` §6。
- 涉及路径的设置(日志目录、Artifact 目录)一律基于 `data_dir()`,
**不要硬编码,也不要用 `os.getcwd()`**——打包成 exe 后会失效,
见 `docs/client/03-data-model.md` §2.2。
- 保存前要校验:数量上限、价格偏差、轮询周期这些填错了会直接影响
采购安全,不能存进去再说。
- 测试结果用 `InfoBar` 反馈,失败时说清“哪一步失败、下一步做什么”,
不要把原始异常堆栈贴到界面上。
注意:真实下单开关属于红线,默认关闭,不得在这里做成
一个随手能打开的普通开关,见根目录 `AGENTS.md` 红线第 2 条。
"""