# 七月迭代 AI 实施与验收操作手册

> 适用范围：`.scratch/<feature-slug>/PRD.md` 及其 `issues/` 的拆票、实现、评审和验收。  
> 权威约束：`AGENTS.md`、父 PRD、Issue 和 `docs/7月迭代/独立方案/基础规范/DDD规范.md`。  
> 核心原则：按依赖 frontier 工作；小需求可整目录执行，高风险需求优先逐票执行；测试强度由 PRD 风险和已确认接缝决定。

## 一、完整流程总览

```text
已评审 PRD
  ↓
/to-tickets：草拟纵向切片和阻塞边
  ↓ 用户确认拆分
发布 .scratch/<feature-slug>/issues/*.md
  ↓
记录实现基线 commit
  ↓
/implement：逐票或整目录实现
  ├─ 在已确认接缝上按 TDD 做 red → green
  ├─ 开发中持续运行局部测试和编译检查
  ├─ 本组工作结束时运行一次全量测试
  ├─ 对基线至 HEAD 的累计 diff 执行 /code-review
  └─ 中文 commit
  ↓
独立验收：PRD、Issues、代码、测试证据和外部验收矩阵
  ↓
跨 PRD 联调与 INT-01～08 发布验收
```

## 二、每个需求开始前的固定检查

假设当前需求目录为：

```text
.scratch/<feature-slug>/
├── PRD.md
└── issues/
```

开始前检查：

1. `PRD.md` 状态为 `ready-for-agent`。
2. PRD 已完成评审，没有尚未决定的业务问题。
3. 工作区没有来源不明的未提交修改。
4. 当前需求的跨 PRD 前置能力已经发布为具体 Issue；不能只写“依赖公共基础”。
5. 当前完整用例已经明确 Audit Event、Domain Ledger、Integration Log、Outbox 的使用决定或 N/A 理由；涉及审计时已增量维护全系统审计覆盖基线。
6. 最终发布门禁已经引用具体公共基础 Ticket；需要事件时已确认事件类型、载荷版本、消费者幂等键、业务失败明细和通知策略。
7. 记录拆票前或实现前的 commit，供后续双轴评审使用：

```bash
git status --short --branch
git rev-parse HEAD
```

将第二条命令输出记作 `BASE_COMMIT`。不要依赖 `HEAD~N` 猜测基线。

## 三、生成 Issues

### 3.1 通用命令

在一个新会话中执行：

```text
/to-tickets .scratch/<feature-slug>/PRD.md
```

`AGENTS.md` 已要求规划会话自动读取 DDD 规范，因此无需每次重复粘贴 DDD 提示词。

### 3.2 拆票确认

`/to-tickets` 应先展示草稿，而不是直接写文件。确认每张票都具备：

- 一个可独立演示或验证的纵向行为；
- 明确的 `Blocked by`；
- 可观察的验收标准；
- 适用的 DDD 架构通道；
- 当前票收口的完整业务边界；
- 明确不迁移的旧代码范围。
- Audit Event、Domain Ledger、Integration Log、Outbox 的逐项决定或 N/A 理由；
- 依赖公共能力时引用具体 Ticket，并在本 PRD 最终发布票中收口装配和验收。

出现以下拆法时应要求重拆：

- “先建表 → 再写 Service → 再写 Handler”的水平分层；
- 一张票包含多个相互独立的业务流程；
- 阻塞项只写“公共基础设施”而没有具体 Issue；
- 为简单 Query 或单表写操作强行创建聚合、工厂或多层接口；
- 在拆票阶段改变已评审 PRD 的业务或架构决定。
- 把“公共能力已经实现”当作业务组合根已经装配，遗漏正式 Adapter、事件消费者、监控或审计覆盖基线。

确认草稿后回复：

```text
拆分粒度和阻塞关系确认，可以发布 Issues。
```

### 3.3 拆票完成检查

发布后检查：

```bash
find .scratch/<feature-slug>/issues -maxdepth 1 -type f -name '*.md' -print | sort
```

逐票确认 `Status: ready-for-agent`、验收条件和阻塞边存在。父 PRD 不应被关闭或改写。

## 四、七月迭代建议拆票顺序

拆票顺序用于让后续 PRD 能引用已经存在的具体上游 Issue。它不代表所有票必须拆完后才能开始实现；没有阻塞的 frontier 可以先做。

### 第一批：独立小需求

```text
UR#60 店铺联系电话精确查询
UR#45 换货资产标识与独立搜索
UR#86 资产详情换货链
UR#55 套餐生效条件与购买快照
UR#46 预计最终到期时间（依赖 UR#55）
```

### 第二批：公共基础

```text
TECH 七月迭代公共开发基础
TECH 全局多视角审计与外部集成追踪
TECH 公共站内通知与受控跳转
```

### 第三批：共享业务核心

```text
UR#94 卡状态公共写入、事件触发与运营商回调
UR#37 企业微信审批公共能力
UR#38 代理主钱包信用额度与统一钱包边界
```

### 第四批：依赖公共基础的中小需求

```text
UR#40 下架套餐历史用户续费
UR#43 代理系列套餐批量授权
UR#47 卡片手动限速
UR#48 按资产类型限制 C 端支付方式
UR#49 设备 CSV 批量分配
UR#96 店铺业务员归属
UR#98 换货新资产继承店铺
```

### 第五批：卡状态、钱包与临期链

```text
UR#73 按运营商实名能力控制复机
UR#53 卡和设备实名状态筛选
UR#62 H5 购买与实名顺序配置
UR#97 代理主钱包低余额预警
UR#33 套餐临期查询与提醒
```

主要依赖链：

```text
UR#94 → UR#73、UR#53、UR#62
UR#38 + UR#96 + 公共通知 → UR#97
UR#55 → UR#46
UR#40 + UR#46 + UR#96 + 公共通知 → UR#33
```

### 第六批：复杂核心业务

```text
UR#35 退款企微审批与整单终结
UR#57 活跃退款资产禁止换货
UR#34 代理扫码充值与平台线下代充值
UR#36 批量订购套餐
UR#44 提交人和审批摘要
UR#42 统一导出与字段权限
```

主要依赖链：

```text
UR#37 + UR#38 + 审计 + 通知 → UR#35
UR#35 → UR#57
UR#37 + UR#38 + 审计 + 通知 → UR#34
UR#38 + UR#40 + 公共异步任务 → UR#36
UR#37 + UR#34 + UR#35 → UR#44
UR#33 + UR#46 + UR#44 + UR#37 → UR#42
```

最终以发布后的具体 Issue 阻塞边为准；上述关系只是跨 PRD 排序基线。

## 五、让 AI 实现 Issues

### 5.1 标准模式：一张票一个新会话

这是 `/to-tickets` 推荐的默认方式，适合复杂写、资金、状态机、外部系统、宽范围迁移和单票改动较大的需求：

```text
/implement .scratch/<feature-slug>/issues/<NN>-<ticket-slug>.md
```

优点是上下文干净、范围稳定、失败容易定位。完成后选择下一个所有 blocker 均已完成的 ticket。

### 5.2 省事模式：整目录执行

对于票数少、改动集中、依赖链清晰的小需求，可以执行：

```text
/implement .scratch/<feature-slug>/issues/
```

`/implement` 支持一组 tickets，但整目录模式不改变依赖规则。AI 必须先读取全部票，只执行 blocker 已完成的 frontier，并按依赖顺序推进。

可附加以下通用说明；它不包含任何特定需求内容：

```text
完整实现该目录下所有当前可执行的 tickets。先读取父 PRD、全部 tickets、AGENTS.md 和 CONTEXT.md，建立依赖图，只处理 Blocked by 已完成的 frontier，不跳过、不合并、不改变已评审范围。

使用父 PRD 或 ticket 中已经确认的测试接缝；如果没有确认测试接缝，在写测试前先询问。开发中持续运行最相关的局部测试和编译检查，整组工作完成后运行一次全量测试，再对实现前固定基线到 HEAD 的累计 diff 执行 code-review，最后按项目规范提交。

如果上下文不足、外部 blocker 未完成、必须改变 PRD/架构或无法安全继续，请停在 ticket 边界，报告已完成项和下一张可执行 ticket，不要猜测或跨范围实现。
```

### 5.3 何时不要整目录执行

出现任一情况时，改用逐票模式：

- 涉及金额、余额、退款、充值或佣金；
- 涉及复杂状态机、并发不变量或可靠事件；
- 涉及企微、支付、Gateway、运营商等外部副作用；
- 涉及全局审计切换或 expand–migrate–contract；
- issues 较多，无法合理放进一个清晰上下文；
- 多张票会同时大范围修改同一模块；
- AI 已出现遗忘前置条件、重复实现或范围漂移。

若整目录会话因上下文或阻塞停止，不需要从头再跑。新会话指定剩余 ticket 或再次指定目录，并要求先识别已经完成的票。

## 六、正确的测试节奏

测试要求以 `/tdd`、父 PRD 的 `Testing Decisions`、ticket 验收条件和项目现有测试方式为准。

### 6.1 开始实现前

- 使用 PRD/ticket 已经确认的公共测试接缝。
- 如果没有确认接缝，AI 必须在写测试前询问一次。
- 测试面向公共行为，不测试私有函数或内部调用次数。
- 不为了满足 TDD 给简单字段映射制造无价值的内部单元测试。

### 6.2 实现过程中

按纵向切片执行：

```text
一个失败测试 → 最小实现 → 测试通过 → 下一个行为
```

持续运行最相关的包测试或指定测试，例如：

```bash
go test ./internal/<package>/...
go test ./internal/<package>/... -run TestName
```

Go 的相关包测试同时承担本范围的编译检查。不要每修改一个文件就运行 `go test ./...`，也不要先写完全部测试再集中实现。

### 6.3 本组实现结束时

在提交前运行一次全量测试：

```bash
go test ./...
```

如果全量测试失败，必须区分：

- 本次修改引入的失败：修复后才能完成；
- 可复现的存量失败：记录命令、失败测试和与本次 diff 无关的证据，不得谎报全绿；
- 缺少数据库、Redis 或外部配置：标记为环境阻塞，并执行仍可运行的测试。

只有项目或 ticket 明确要求时才额外运行迁移、真实接口、生成文档或专项静态检查。不要凭空增加仓库没有约定的通用门禁。

## 七、Code Review 与提交

### 7.1 固定评审起点

使用实现前记录的 `BASE_COMMIT`：

```text
/code-review <BASE_COMMIT>
```

如果自动识别不到规格来源，同时提供：

```text
规格来源是 .scratch/<feature-slug>/PRD.md 和 .scratch/<feature-slug>/issues/。
```

`/code-review` 分开检查：

- Standards：是否符合 `AGENTS.md`、DDD 规范和代码标准；
- Spec：是否完整实现父 PRD 和 tickets，是否遗漏或越界。

阻断性问题修复后，应重新运行受影响的局部测试；若修复可能影响全局，重新运行全量测试。修复后的 diff 需要再次复核相关发现。

### 7.2 提交粒度

`/implement` 的硬要求是完成工作后提交当前分支，并不强制每张 ticket 都单独提交。选择原则：

- 逐票模式：通常一票一个中文 commit，便于回溯；
- 整目录模式：可以按独立可回滚切片提交，也可以在整个小需求完成后统一提交；
- 不要为了形式制造无法单独构建或测试的中间 commit；
- 不要把其他需求或用户已有修改混入提交。

## 八、独立验证

实现会话结束后，推荐开启一个新会话做只读验证，避免实现上下文影响判断。

### 8.1 通用验证提示词

```text
请独立验证 .scratch/<feature-slug>/PRD.md 及其 issues/ 的实现结果。固定评审起点是 <BASE_COMMIT>。

本轮先只审查和验证，不修改代码。完整读取 AGENTS.md、父 PRD、全部 tickets、相关 commits 和从基线到 HEAD 的累计 diff。

核对父 PRD、每张 ticket、DDD 架构通道、迁移边界和测试证据；运行最能证明验收条件的相关测试。确认实现会话已经在最终代码上成功运行过 go test ./...；如果没有可信证据、最终代码后来又变化，或本次验证发现可能影响全局的问题，再运行全量测试。

输出：通过项及证据、未通过项、范围外问题、环境或外部阻塞、仍需人工验收的项目，以及最终结论（通过／未通过／外部阻塞）。不要把代码存在当作行为验证，也不要把未执行的外部联调标记为通过。
```

### 8.2 验证失败后的处理

- 实现遗漏：回到对应 ticket，用 `/implement <ticket-path>` 修复。
- 拆票遗漏：新增补救 ticket，确认后实现；不要静默扩大旧票。
- PRD 发生变化：先更新并重新评审 PRD，再调整 tickets。
- 纯环境阻塞：保留自动化证据，列入联调或发布前验收，不伪造完成。

## 九、完成状态判定

### 9.1 Ticket 完成

- 所有 blocker 已完成；
- 验收条件有行为或测试证据；
- 没有擅自改变架构或扩大迁移范围；
- 相关测试通过，或存量/环境失败已准确记录。
- 本票涉及的审计、领域流水、外部集成和可靠事件决定已经实现或按评审理由标记 N/A，覆盖基线同步更新。

### 9.2 PRD 完成

- 该 PRD 的所有 tickets 完成；
- PRD 的 User Stories、Implementation Decisions 和 Testing Decisions 无遗漏；
- 累计 diff 通过 Standards + Spec 双轴 review；
- 最终代码已经完成约定的全量测试；
- 文档、迁移和人工验收项按 PRD 处理。
- 最终发布票已验证正式 Adapter/消费者在生产组合根装配，事件版本与幂等键已登记，监控阈值有具体数值和责任人。

### 9.3 七月迭代完成

单个仓库代码完成不等于整轮迭代完成。所有 PRD 完成后，还需按标准评审稿执行：

```text
INT-01 资产实名、复机与状态同步
INT-02 换货完整链路
INT-03 套餐授权、购买、续费、到期与临期
INT-04 CSV 批量任务与导出
INT-05 支付、代理钱包、信用和余额预警
INT-06 企业微信审批、退款和线下充值
INT-07 Gateway 卡限速
INT-08 七月迭代全链路与停机发布验收
```

INT-08 还必须汇总验证：全系统审计覆盖基线无空白、旧 Writer 停写、系统配置与 Outbox 恢复使用正式审计 Adapter；所有实际生产的 Outbox 事件均已有消费者、版本和幂等键；生产告警阈值已经依据容量基线填写。任一项未闭环均不能用“公共基础已完成”代替。

最终结论必须区分：

- 本地自动化完成；
- 后端实现完成；
- 前后端联调完成；
- 外部测试环境验收完成；
- 存量数据回填和停机发布演练完成。

只有标准评审稿要求的全部门禁通过，才能标记“七月迭代完成”。

## 十、日常最简操作卡

### 生成 Issues

```text
/to-tickets .scratch/<feature-slug>/PRD.md
```

确认草稿后：

```text
拆分粒度和阻塞关系确认，可以发布 Issues。
```

### 实现单票

```text
/implement .scratch/<feature-slug>/issues/<NN>-<ticket-slug>.md
```

### 实现整个小需求

```text
/implement .scratch/<feature-slug>/issues/
```

### 双轴评审

```text
/code-review <BASE_COMMIT>
```

### 独立验收

使用第八章的通用验证提示词，将 `<feature-slug>` 和 `<BASE_COMMIT>` 替换为实际值。
