cmshoppe/docs/05-coding-rules.md

编码规则（Coding Rules）

每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。 与技术细节冲突时，以 技术栈 / 架构设计 的事实为准；与“该不该做”冲突时，以 需求 为准。

0. 黄金法则

1. 不臆造：选择器、字段、文件、接口不确定就查证或先用 prototypes/inspect_images.py 探查页面，不要猜 class 名。
2. 守范围：只做当前任务要求的事，不顺手加批量/并行等后续功能。
3. 照架构：复用 cdp.py，遵守 04-architecture.md 第四节“已验证结论”，不另起一套 CDP 交互。
4. 小步改：一次只解决一个问题，不夹带无关重构。
5. 可验证：改完必须能 py_compile，关键路径能在测试商品上跑通，对得上验收标准。

1. 动手前

• 按链路确认：vision -> requirements -> tech-stack -> architecture -> tasks。
• 找到本任务对应的验收标准，写之前就知道“怎么算做对”。
• 复用优先：已有 cdp.py 的 CDP、find_product_tab、create_tab、drag；已有 prototypes/demo.py/prototypes/set_*.py 中验证过的 JS 片段。
• 需求含糊或改动会偏离已验证事实时，先问。

2. 事实来源纪律

• CDP 交互只信 04-architecture.md 第四节的“已验证结论”和真实页面探查结果。
• 不从旧脚本注释或记忆里推断仍然有效的选择器；Shopee 页面可能已变，必要时重新探查。
• 不虚构 Shopee 接口、字段、按钮文案。
• 选择器 / 流程变化必须同步更新 04-architecture.md 和相关任务。

3. 范围纪律

• MVP 只做 02-requirements.md 中列为 P0 的功能（账号配置、绑定目录、启动登录、加载页、改标题、换封面、可选更新）。
• V2 / V3 功能（批量、多账号并行、日志、规则模板）只记录，不实现。
• 需求明确排除的非目标（自动登录、绕风控、爬取、数据库）不得实现。

4. 架构纪律

• 技术栈以 03-tech-stack.md 为准；GUI 框架未确认前不要写大量 UI 代码。
• 新增依赖前先说明理由；优先标准库（Tkinter、json、sqlite3、subprocess），Excel 用 openpyxl。
• 存储边界：应用设置进 config.json，账号/任务/结果进 SQLite，登录态只在 user-data-dir，同一事实只存一处。
• 模块职责以 04-architecture.md 为准：GUI 不写业务逻辑，业务在 appconfig/db/excel/config/chrome/cdp/editor。
• 模块/CLI 合约以 api.md 为准。

5. 代码规范

• 标识符使用英文；UI 文案、注释、文档保持中文，与现有脚本一致。
• 错误必须处理：CDP 超时、tab 找不到、上传失败、按钮禁用都要给明确提示，不吞错。
• 注释解释“为什么”（尤其 CDP 的坑：代理、Origin、就绪判断、拖拽落点），不复述“做了什么”。
• 复用现有脚本里已验证的 JS 字符串，不重写出不一致的版本。

6. 测试与验证

完成前至少检查：

• python -m py_compile 通过。
• 涉及 CDP 的改动，在测试商品（ITEM_ID 51100639510）上实跑验证。
• 对得上需求验收标准（如标题 value+modelvalue 双等于、封面在第一位）。
• 没有夹带无关改动。
• 涉及选择器/流程/配置 schema 变化时，文档已同步。
• 回复里如实说明跑了什么命令、结果如何。

python -m py_compile *.py
python prototypes/demo.py            # 单账号闭环验证（不提交）

7. 绝不

• 绝不把真实账号、密码、Cookie、token 写进代码、文档或日志。
• 绝不明文存密码；DB 里密码必须加密，且加密密钥不与密文同存。
• 绝不把 config.json、cmshopee.db、chrome_user_data_dir/ 提交版本库。
• 绝不自动登录 / 自动填账号密码；登录由人工完成，程序只检测登录态。
• 绝不在没有显式确认/开关的情况下点击「更新」提交线上。
• 绝不擅自删除用户文件或重置 user-data-dir。
• 绝不为通过验证而降低验收标准（如不验证 modelvalue 就当改成功）。

8. 安全与合规

• 登录凭证只存在于各账号 user-data-dir；不导出、不外传、不写入配置或日志。
• 涉及 Shopee 时，遵守 04-architecture.md 写明的页面规则与限流边界；不高频批量、不绕风控/验证码。
• 高风险动作（删满 9 张的封面、点击更新）必须有显式确认或开关，并先在测试商品验证。
• 自动化默认支持“只改不提交”（dry-run 思路）；提交、删除等不可逆动作要可控、可回退（刷新还原）。

9. 拿不准就问

问题要具体：说明卡在哪、有哪些选项、倾向哪个及原因。尤其 GUI 框架、端口分配、删图确认框结构这类影响后续的决策，先确认再写。