cmbuyer/docs/05-coding-rules.md

# 编码规则（Coding Rules）

> 每次写代码前先读完本文。
> 与技术细节冲突时，以[技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 的事实为准；
> 与「该不该做」冲突时，以[需求](02-requirements.md)为准。

## 0. 黄金法则

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

## 1. 本项目特有的红线

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

### 1.1 资金与不可逆动作

- **绝不**编写点击支付、免密支付、先用后付或任何扣款控件的代码。
- **绝不**在订单确认页上点击除「提交订单」与返回外的任何控件。
- 「提交订单」只在**四个前置条件**同时满足时点击一次：授权未消费且服务端提交围栏已
  明确建立、闸门二通过、闸门三通过、控件唯一。
- 围栏接口超时、冲突、网络失败或响应不明时不得点击；围栏建立后不得释放授权、重新领取
  或再次点击，只能恢复同一 `order_submission` 并调和结果。
- 点击后无论超时、跳外部支付还是遇安全校验，**一律转人工、禁止重试**。授权保持已围栏；
  只有明确结果或人工调和后才记为已消费/已解决。
- T-103 的 `SkuSelectionFlow` 不得引用数量、订单确认、提交围栏、`submit_order_once()` 或付款能力，
  必须有静态调用链和测试证明不可达。
- `open_sku_panel()` 只可点击本项目真机证据与 App 版本绑定的精确唯一入口；当前仅允许拼多多
  `8.17.0` 上已取证的 `快要抢光`。不得暴露通用 `click`，不得把其他购买文案按包含/同义/坐标兜底。
- 规格面板中的“提交订单”、微信支付、先用后付或 0 元下单在 T-103 只能作为硬拒绝判据，绝不能
  返回可点击对象。后续生产单趟也只能在各段已取证且四条件全通过时触发封装的一次性提交能力。

### 1.2 匹配纪律

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

### 1.3 价格读取边界

- 价格**只在规格面板（闸门一 / 二）和订单确认页（闸门三）读**。
- **不从商品详情页正文、搜索结果卡片或任何其他位置读价格。**
- 读不到就转人工，**不用别处的数字凑合**。
- 同一趟设置并复核数量后，闸门二重读的规格必须不变，并唯一读取目标数量的规格面板总额，直接
  验证不超授权最高总价；后续闸门三应付总额必须与该面板总额严格相等并再次不超上限。2026-08-06
  真机已证明多件优惠非线性，不得用闸门一金额乘数量猜 Gate2 总额，也不得要求 Gate2 等于 Gate1。
- 图片搜索（V2）的唯一产出是 `goods_id`，同样不读价。

### 1.4 安全与隐私

- 检测到验证码、风控、人脸、短信校验时立即停止，**不尝试绕过**。
- 检测到外部支付交接立即停止，**不读取、不保存、不输入任何凭据**。
- 页面已显示的地址和手机号允许随**内部原始截图**上传采购服务，供已登录管理员核对；不做遮罩或裁剪。
- 地址和手机号不得被解析为结构化业务字段，也不得写入普通日志、Git、Vikunja、fixture 或错误消息。
  原始完整 XML 只留采购工具本机；真机流程可在内存中读取，但只能返回规格、选中态、价格和页面状态摘要。
- 截图上传器只能接收显式文件，不得枚举原始目录或顺带上传 XML/manifest/其他文件；服务端必须校验
  设备身份和 SHA-256，证据只允许已登录管理员访问，不得提供公开静态目录。
- **支付凭据仍不得读取、保存或上传。** 外部支付交接不在“内部原图允许上传”的例外范围内。
- T-103 停止遮罩器开发并专注真机选择/读价；生产原始截图上传由 T-204 实现。

### 1.5 页面判据

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

> 这些红线不是建议。[`04-architecture.md`](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 真机结论出来之前，不写依赖真机可读字段的生产执行功能。** T-201 管理会话、只创建
  `DRAFT` 的 T-202，以及 T-203 只锁定现有任务字段的服务端开始采购授权事务可以并行；T-205 起
  的实际 attempt / 页面证据等待 T-103。T-201 / T-202 不得夹带授权、机器结果、提交或付款字段。

## 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`](03-tech-stack.md) 验证矩阵独立重跑任务相关验证；命中完整门禁
   触发条件时再跑完整门禁。
4. 执行者、子 agent、工具或 CI 的摘要只能作为线索，**不能替代任务所有者看到的差异和
   可复现验证结果**。
5. 需要真机验收但尚未完成时，记录等待事项并保持 `DOING` 或 `BLOCKED`，**不得标 `DONE`**。

完成前至少检查：

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

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

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

## 8. 绝不

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

## 9. 拿不准就问

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

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