cmpdd/docs/05-coding-rules.md

编码规则（Coding Rules）

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

0. 黄金法则

1. 不臆造：Excel 字段、页面选择器、接口、依赖，不确定就查证或询问。
2. 守范围：只做当前任务要求的事，不顺手加 Web 后台、多设备、数据库等后续能力。
3. 照架构：使用既定技术栈和模块边界，不擅自引入新框架。
4. 小步改：一次只解决一个问题，不夹带无关重构。
5. 可验证：改完必须能运行、能测试、对得上验收标准。

1. 动手前

• 按链路确认：vision -> requirements -> tech-stack -> architecture -> tasks。
• 找到本任务对应的验收标准，写之前就知道“怎么算做对”。
• 先找现有函数、组件、工具和测试，复用优先。
• 涉及真机自动化时，先确认设备连接和当前 App 状态。
• 如果需求含糊，或改动会偏离原则 / 架构，先问。

2. 事实来源纪律

• Excel 表头以用户提供的真实样例或 04-architecture.md 当前约定为准。
• 拼多多页面状态以真机截图、UI XML 和实际运行日志为准。
• 不从旧截图、临时脚本、未确认样例里推断当前事实。
• 不虚构字段、按钮文本、订单号位置、状态码、配置项。
• 数据结构变化必须同步更新 04-architecture.md、api.md 和相关任务。

3. 范围纪律

• MVP 只做 02-requirements.md 中列为 P0 的功能。
• V2 / V3 功能只记录，不实现。
• 需求明确排除的非目标不得实现。
• 不为“将来可能用到”提前抽象。
• 不默认覆盖原始 Excel，除非用户明确要求。

4. 安全与合规纪律

• 绝不实现绕过验证码、风控、人脸、短信、安全校验或平台限制的逻辑。
• 绝不实现无配置、无二次校验、无金额上限的自动支付。
• 绝不记录支付密码、短信验证码、账号密码等敏感信息。
• 绝不调用、逆向或改造拼多多非公开接口。
• 自动支付必须显式开启，并在商品、SKU、数量、地址、金额校验通过后才能继续。
• 遇到安全校验时进入 待人工，由运营在真机上处理。

5. 架构纪律

• 技术栈以 03-tech-stack.md 为准。
• 新增依赖前先说明理由；未经确认不要引入重量级依赖。
• GUI、Excel、任务执行器、Android 控制模块职责必须分离。
• API/本地模块合约以 api.md 为准，界面结构以 routes.md 为准。
• 页面选择器集中在拼多多流程模块，不散落在 GUI 代码里。

6. 代码规范

• 标识符使用英文。
• UI 文案、注释、文档语言使用中文，除非引用库 API 或错误码。
• 错误必须处理，不吞错。
• 注释解释“为什么”，不复述“做了什么”。
• 日志要包含任务 ID 和当前步骤，但不能包含敏感信息。
• 遵守项目已有格式化工具，不手工制造风格分裂。

7. 测试与验证

完成前至少检查：

• 构建或语法检查通过。
• 相关测试通过。
• 对得上需求验收标准。
• 没有夹带无关改动。
• 涉及文档事实变化时，文档已同步。
• 涉及 Android 自动化时，说明是否已用真机验证。
• 回复里如实说明跑了什么命令、结果如何。

当前真实验证命令（Windows 用 python，Linux/WSL 用 python3）：

python -m compileall src
python -m unittest discover -s tests -t .
python src/main.py

8. 绝不

• 绝不把密钥、token、密码、支付密码、短信验证码写进代码或文档样例。
• 绝不为了让测试通过而删除断言、降低验收标准。
• 绝不擅自删除用户已有文件或重置工作区。
• 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。
• 绝不在自动化失败时盲目点击不确定区域继续下单。

9. 拿不准就问

问题要具体，说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。