2026-06-26 15:30:37 +08:00
|
|
|
|
# 编码规则（Coding Rules）
|
|
|
|
|
|
|
|
|
|
|
|
> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。
|
|
|
|
|
|
> 与技术细节冲突时，以 [技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 的事实为准；与“该不该做”冲突时，以 [需求](02-requirements.md) 为准。
|
|
|
|
|
|
|
|
|
|
|
|
## 0. 黄金法则
|
|
|
|
|
|
|
|
|
|
|
|
1. **不臆造**：选择器、字段、文件、接口不确定就查证或先用 `prototypes/inspect_images.py` 探查页面，不要猜 class 名。
|
|
|
|
|
|
2. **守范围**：只做当前任务要求的事，不顺手加批量/并行等后续功能。
|
2026-06-26 17:05:18 +08:00
|
|
|
|
3. **照架构**：复用 `app/cdp.py`（迁移前参考根目录 `cdp.py`），遵守 `04-architecture.md` 第七节“已验证结论”，不另起一套 CDP 交互。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
4. **小步改**：一次只解决一个问题，不夹带无关重构。
|
|
|
|
|
|
5. **可验证**：改完必须能 `py_compile`，关键路径能在测试商品上跑通，对得上验收标准。
|
|
|
|
|
|
|
|
|
|
|
|
## 1. 动手前
|
|
|
|
|
|
|
|
|
|
|
|
- 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。
|
|
|
|
|
|
- 找到本任务对应的验收标准，写之前就知道“怎么算做对”。
|
2026-06-26 17:05:18 +08:00
|
|
|
|
- 复用优先：已有 CDP 底座（T-000 后为 `app/cdp.py`，当前来源为根目录 `cdp.py`）的 `CDP`、`find_product_tab`、`create_tab`、`drag`；已有 `prototypes/demo.py`/`prototypes/set_*.py` 中验证过的 JS 片段。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
- 需求含糊或改动会偏离已验证事实时，先问。
|
|
|
|
|
|
|
|
|
|
|
|
## 2. 事实来源纪律
|
|
|
|
|
|
|
2026-06-26 15:55:28 +08:00
|
|
|
|
- CDP 交互只信 `04-architecture.md` 第七节的“已验证结论”和真实页面探查结果。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
- 不从旧脚本注释或记忆里推断仍然有效的选择器；Shopee 页面可能已变，必要时重新探查。
|
|
|
|
|
|
- 不虚构 Shopee 接口、字段、按钮文案。
|
|
|
|
|
|
- 选择器 / 流程变化必须同步更新 `04-architecture.md` 和相关任务。
|
|
|
|
|
|
|
|
|
|
|
|
## 3. 范围纪律
|
|
|
|
|
|
|
2026-06-26 15:55:28 +08:00
|
|
|
|
- V1 只做 `02-requirements.md` 中列为 P0 的当前目标功能（5 Tab、账号管理、Excel 导入采集、AI 生成、批量确认后更新 Shopee、结果回写）。
|
|
|
|
|
|
- V2 / V3 功能（多账号并行、dry-run、完整运行日志、规则模板）只记录，不实现。
|
|
|
|
|
|
- 需求明确排除的非目标（自动登录、绕风控、商品数据批量爬取、外部数据库）不得实现。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
|
|
|
|
|
|
## 4. 架构纪律
|
|
|
|
|
|
|
2026-06-26 16:09:09 +08:00
|
|
|
|
- 技术栈以 `03-tech-stack.md` 为准；GUI 固定使用 PySide6，不引入第二套 UI 框架。
|
|
|
|
|
|
- 新增依赖前先说明理由；优先标准库（json、sqlite3、subprocess），GUI 用 PySide6，Excel 用 openpyxl。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
- 存储边界：应用设置进 `config.json`，账号/任务/结果进 SQLite，登录态只在 user-data-dir，同一事实只存一处。
|
|
|
|
|
|
- 模块职责以 `04-architecture.md` 为准：GUI 不写业务逻辑，业务在 `appconfig/db/excel/config/chrome/cdp/editor`。
|
2026-06-26 16:09:09 +08:00
|
|
|
|
- PySide6 后台任务必须通过 worker/QThread/signal 回传 UI；后台线程不得直接操作 Qt widget，不共享 SQLite connection。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
- 模块/CLI 合约以 `api.md` 为准。
|
|
|
|
|
|
|
|
|
|
|
|
## 5. 代码规范
|
|
|
|
|
|
|
|
|
|
|
|
- 标识符使用英文；UI 文案、注释、文档保持中文，与现有脚本一致。
|
|
|
|
|
|
- 错误必须处理：CDP 超时、tab 找不到、上传失败、按钮禁用都要给明确提示，不吞错。
|
|
|
|
|
|
- 注释解释“为什么”（尤其 CDP 的坑：代理、Origin、就绪判断、拖拽落点），不复述“做了什么”。
|
|
|
|
|
|
- 复用现有脚本里已验证的 JS 字符串，不重写出不一致的版本。
|
|
|
|
|
|
|
|
|
|
|
|
## 6. 测试与验证
|
|
|
|
|
|
|
|
|
|
|
|
完成前至少检查：
|
|
|
|
|
|
|
2026-06-26 17:05:18 +08:00
|
|
|
|
- [ ] `python -m compileall app main.py` 通过（T-000 前仅文档改动不要求）。
|
2026-06-26 16:37:58 +08:00
|
|
|
|
- [ ] T-006 完成后，纯逻辑改动有对应 `unittest`，至少覆盖正常路径和一个失败路径。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
- [ ] 涉及 CDP 的改动，在测试商品（ITEM_ID 51100639510）上实跑验证。
|
2026-06-26 16:27:33 +08:00
|
|
|
|
- [ ] 涉及 DB 的改动，覆盖 schema 初始化、重复初始化、短事务写入、失败状态写入。
|
|
|
|
|
|
- [ ] 涉及 Excel 的改动，覆盖 source_file_abs/source_sheet/source_row 回写定位。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
- [ ] 对得上需求验收标准（如标题 `value`+`modelvalue` 双等于、封面在第一位）。
|
|
|
|
|
|
- [ ] 没有夹带无关改动。
|
|
|
|
|
|
- [ ] 涉及选择器/流程/配置 schema 变化时，文档已同步。
|
|
|
|
|
|
- [ ] 回复里如实说明跑了什么命令、结果如何。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-06-26 17:05:18 +08:00
|
|
|
|
python -m compileall app main.py
|
2026-06-26 16:37:58 +08:00
|
|
|
|
python -m unittest discover -s tests # T-006 完成且 tests/ 存在后
|
2026-06-26 15:30:37 +08:00
|
|
|
|
python prototypes/demo.py # 单账号闭环验证（不提交）
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-06-26 16:37:58 +08:00
|
|
|
|
测试命令时机：
|
|
|
|
|
|
|
|
|
|
|
|
- T-006 前：`tests/` 尚未建立时，只要求运行与当前任务匹配的可用验证；不要因为 `python -m unittest discover -s tests` 缺目录而判失败。
|
|
|
|
|
|
- T-006 后：`python -m unittest discover -s tests` 成为纯逻辑改动的必跑项；新增/修改 appconfig、db、excel、prompts、config、chrome 纯逻辑时同步补测。
|
|
|
|
|
|
|
2026-06-26 15:30:37 +08:00
|
|
|
|
## 7. 绝不
|
|
|
|
|
|
|
|
|
|
|
|
- 绝不把真实账号、密码、Cookie、token 写进代码、文档或日志。
|
2026-06-26 16:27:33 +08:00
|
|
|
|
- 绝不把密码/API Key 写进代码、文档、日志或导出文件；本地配置/DB 可明文保存，必须 gitignore，UI 打码。
|
2026-06-26 16:37:58 +08:00
|
|
|
|
- 绝不把 `config.json`、`config/ai_models.json`、`cmshopee.db`、`chrome_user_data_dir/`、`images/` 提交版本库。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
- 绝不自动登录 / 自动填账号密码；登录由人工完成，程序只检测登录态。
|
2026-06-26 15:55:28 +08:00
|
|
|
|
- 绝不在缺少 ③ 批量确认弹窗确认的情况下点击「更新」提交线上。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
- 绝不擅自删除用户文件或重置 user-data-dir。
|
|
|
|
|
|
- 绝不为通过验证而降低验收标准（如不验证 `modelvalue` 就当改成功）。
|
|
|
|
|
|
|
|
|
|
|
|
## 8. 安全与合规
|
|
|
|
|
|
|
|
|
|
|
|
- 登录凭证只存在于各账号 user-data-dir；不导出、不外传、不写入配置或日志。
|
|
|
|
|
|
- 涉及 Shopee 时，遵守 `04-architecture.md` 写明的页面规则与限流边界；不高频批量、不绕风控/验证码。
|
2026-06-26 15:55:28 +08:00
|
|
|
|
- 高风险动作（删满 9 张的封面、点击更新）必须有显式确认，并先在测试商品验证。
|
|
|
|
|
|
- V1 无常驻提交开关；③ 的批量确认弹窗是提交线上前的确认边界。dry-run 属 V2。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
|
|
|
|
|
|
## 9. 拿不准就问
|
|
|
|
|
|
|
2026-06-26 16:09:09 +08:00
|
|
|
|
问题要具体：说明卡在哪、有哪些选项、倾向哪个及原因。尤其端口分配、删图确认框结构这类影响后续的决策，先确认再写。
|
