cmbuyer/docs/05-coding-rules.md

编码规则（Coding Rules）

每次写代码前先读完本文。 与技术细节冲突时，以技术栈 / 架构设计 的事实为准； 与「该不该做」冲突时，以需求为准。

0. 黄金法则

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

1. 本项目特有的红线

违反以下任意一条的改动一律拒绝，无论出于什么理由。

1.1 资金与不可逆动作

• 绝不编写点击支付、免密支付、先用后付或任何扣款控件的代码。
• 绝不在订单确认页上点击除「提交订单」与返回外的任何控件。
• 「提交订单」只在四个前置条件同时满足时点击一次：授权未消费且服务端提交围栏已 明确建立、闸门二通过、闸门三通过、控件唯一。
• 围栏接口超时、冲突、网络失败或响应不明时不得点击；围栏建立后不得释放授权、重新领取 或再次点击，只能恢复同一 order_submission 并调和结果。
• 点击后无论超时、跳外部支付还是遇安全校验，一律转人工、禁止重试，授权立即标记 已消费。
• 第一趟试选的代码路径不得引用 go_to_order_confirm() 与 submit_order()， 必须有测试证明不可达。
• 第一趟只可通过独立的 open_trial_sku_panel() capability 点击本项目真机证据与 App 版本绑定的 精确唯一入口；当前仅允许拼多多 8.17.0 上已取证的 快要抢光。不得向第一趟暴露通用 click、 set_quantity()、订单确认、提交或付款能力，不得把其他购买文案作为包含/同义匹配兜底。
• 规格面板内即使可见“提交订单”、微信支付、先用后付或 0 元下单，第一趟也只能把它们作为硬拒绝 判据，绝不能返回可点击对象或尝试继续。

1.2 匹配纪律

• 规格按维度等值匹配，必须防前缀碰撞（红/粉红、1/10）。
• 找不到精确值就停止转人工，绝不选相近项、绝不猜测。
• 「提交订单」控件必须文本精确相等且可点击祖先唯一，否则停止。
• 数量设置后必须读回复核精确等于要求值。

1.3 价格读取边界

• 价格只在规格面板（闸门一 / 二）和订单确认页（闸门三）读。
• 不从商品详情页正文、搜索结果卡片或任何其他位置读价格。
• 读不到就转人工，不用别处的数字凑合。
• 第二趟重读的单价必须与授权锁定价一致，不一致即停——人确认的是那个价格， 不是那个商品。
• 图片搜索（V2）的唯一产出是 goods_id，同样不读价。

1.4 安全与隐私

• 检测到验证码、风控、人脸、短信校验时立即停止，不尝试绕过。
• 检测到外部支付交接立即停止，不读取、不保存、不输入任何凭据。
• 只读非敏感摘要，不提取收货地址原文、手机号、支付凭据。
• 上传服务端的证据必须先脱敏。
• PDD 页面不可避免显示地址/掩码手机号时，原始 screenshot/XML 只允许写入采购工具本机隔离目录， 只由确定性脱敏器消费；业务代码、agent、fixture、日志和 HTTP sink 只能读取自动复检通过且 manifest 标记 privacy_tier=SANITIZED 的派生物。脱敏失败、分辨率/版本不符或派生 XML 仍命中手机号模式时 必须拒绝发布，不得用人工口头确认绕过。

1.5 页面判据

• 不得从前序项目、旧文档或推理直接写页面判据。 必须有本项目的真机取证。
• 每条判据必须记录取证时的拼多多 App 版本。
• 购买语义按钮不能按“作用相同”共享判据。快要抢光、免拼购买、单独购买、直接拼成 等 每个入口文案都必须分别取证；只允许精确唯一匹配，不允许包含、前缀、相似或坐标兜底。
• 判据失效时先重新取证，不要靠加兜底分支硬扛。

这些红线不是建议。04-architecture.md 第四节列出的每一条都必须有 单元测试证明。确需变更时先改架构文档并说明理由，再动代码。

2. 动手前

• 按链路确认：vision → requirements → tech-stack → architecture → tasks。
• 找到本任务对应的验收标准，写之前就知道「怎么算做对」。
• 涉及界面时先读 07-user-stories.md、08-interaction-checklist.md、routes.md。
• 涉及真机页面判据时，先取证，把证据路径和 App 版本写进任务文件，再写代码。
• 复杂任务先把方案、不可变约束、write_paths 和验证层级写入任务文件。
• 先找现有函数、组件、工具和测试，复用优先。
• 需求含糊或改动会偏离架构，先问。

3. 事实来源纪律

• 只相信本目录文档、数据库迁移、admin/internal/domain/、真机取证产物和当前代码。
• 前序项目 cmroubao / cmpdd 是设计依据，不是事实来源。 引用其结论必须重新验证。
• 不从备份、草稿、旧导出文件里推断当前事实。
• 不虚构字段、接口、状态码、配置项。
• 数据结构变化必须同步更新 04-architecture.md、api.md 和相关任务。

4. 范围纪律

• MVP 只做 02-requirements.md 中列为 P0 的功能。
• V2 / V3 只记录，不实现。图搜、Excel、ERP、订单自动核对、AI 辅助全部不在 MVP。
• 需求明确排除的非目标不得实现。
• 不为「将来可能用到」提前抽象。
• Phase 1 真机结论出来之前不写 Phase 2 的页面——确认页显示什么，取决于真机上 能读到什么，尤其是规格面板上的单价。

5. 架构纪律

• 技术栈以 03-tech-stack.md 为准；新增依赖前先说明用途、替代方案和维护成本。
• 双端职责以 04-architecture.md 第二节为准：采购工具不持有业务权威，不自行决定 买哪个、不自行放宽金额上限。
• HTTP 契约以 api.md 为准，这是双端之间的唯一权威；契约改动必跑完整门禁。
• client/ 中的采购工具执行器只依赖 TaskSource / ResultSink 抽象，不认识来源。
• 两端校验结果不一致时转人工，不取任一方结论。

6. 代码规范

• 标识符使用英文。
• UI 文案、注释、文档使用中文，与现状保持一致。
• 金额一律用十进制字符串，不用浮点数。
• 错误必须处理，不吞错。真机自动化的失败必须可区分原因，不返回笼统的「失败」。
• 注释解释「为什么」，不复述「做了什么」。护栏必须连同理由一起注释，否则后人会 当它是碍事的代码删掉。
• 遵守项目已有格式化工具，不手工制造风格分裂。

7. 测试与验证

任务所有者必须亲自完成最终复核：

1. git status --short 核对实际修改集合，审阅 git diff 和 git diff --cached，对照 任务的 write_paths、不可变约束和验收要点。
2. git diff --check 检查空白与意外行尾变化。
3. 按 03-tech-stack.md 验证矩阵独立重跑任务相关验证；命中完整门禁 触发条件时再跑完整门禁。
4. 执行者、子 agent、工具或 CI 的摘要只能作为线索，不能替代任务所有者看到的差异和 可复现验证结果。
5. 需要真机验收但尚未完成时，记录等待事项并保持 DOING 或 BLOCKED，不得标 DONE。

完成前至少检查：

• 构建通过。
• 相关测试通过。
• 已按验证矩阵判断是否需要完整门禁，并完成所有已触发层级。
• 对得上需求验收标准。
• 没有夹带无关改动。
• 第 1 节的红线一条都没被放宽；涉及的红线有测试覆盖。
• git status、未暂存 / 已暂存 diff 与任务 write_paths 一致，无意外行尾变化。
• 涉及真机的判据已记录设备型号、Android 版本、拼多多 App 版本和证据路径。
• 涉及文档事实变化时，文档已同步。
• 涉及界面时，已验证关联 US / IX 的正常、加载、异常、权限和无障碍要求。
• 已在任务文件的 ## 执行记录 记录跑过的命令和结果。
• 回复里如实说明跑了什么命令、结果如何。

# 采购服务（admin/）
go test ./...
go vet ./...

# 采购工具（client/）
python -m unittest discover -s tests -t .
python -m compileall -q src tests

8. 绝不

• 绝不把密钥、token、密码写进代码或文档样例的真实值里。
• 绝不为了让测试通过而删除断言、降低验收标准。
• 绝不为了让流程跑通而放宽第 1 节的任何红线。
• 绝不擅自删除用户已有文件或重置工作区。
• 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。
• 绝不把「代码写完了」「看起来能跑」当作 DONE 的证据。

9. 拿不准就问

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

涉及资金边界、平台风控或真机不可逆动作的疑问，一律先问，不要先试。