# 使用案例（模拟对话）

[English](./en/usage-scenarios.md)

以下示例围绕同一个电商项目展开，贯穿从需求澄清到上线后维护的完整流程。

**前提**：项目已执行 `flow2spec init`，`flow2spec.config.json` 使用默认配置（`subAgent: false`；`changeTracking.feat/implement: true`，`changeTracking.fix: false`）。`f2s-*` 技能不改动配置根 `rules/`、`skills/` 文件。

---

## 场景一：新需求 → 澄清 → 技术方案

**你**

> /f2s-req-clarify 产品给了一份退款需求，但没说清楚部分退款和全额退款走不走同一接口，退款成功后积分是否回撤。文档在 `.Knowledge/req-docs/退款需求v1.md`。

**Agent**

> 已读取需求文档，有几个点需要确认：
>
> 1. 部分退款与全额退款是否复用同一接口，通过 `amount` 区分，还是拆成两个端点？
> 2. 退款成功后积分是否回撤？回撤失败是否阻断退款流程？
> 3. 退款申请是同步到账还是异步（T+1）？
> 4. 卖家侧是否需要审核步骤？

**你**

> 1. 同一接口用 amount 区分；2. 积分回撤，失败不阻断，异步重试；3. 异步 T+1；4. 不需要审核。

**Agent**

> 澄清完成。执行 `/f2s-req-tech` 输出技术方案。

**你**

> /f2s-req-tech

**Agent**

> 已生成 `.Knowledge/req-docs/退款功能_技术方案.md`，包含：
> - 接口设计：`POST /refunds`，`amount` 字段区分全额/部分
> - 状态机：`PENDING → SUCCESS / FAILED`
> - 积分回撤：异步队列，失败进死信，告警人工处理
> - 错误码清单
>
> 下一步：说"按方案实现 `.Knowledge/req-docs/退款功能_技术方案.md`"触发编码。

---

## 场景二：架构说明沉淀进知识库

**你**

> /f2s-doc-arch 帮我出一份订单服务架构初稿，重点看创建流、支付回调、幂等与消息投递；代码在 `src/order`、`src/payment`。

**Agent**

> 已扫描相关目录，生成 `.Knowledge/stock-docs/订单服务架构说明_初稿.md`，包含：
> - 模块边界与依赖关系
> - 创建流时序
> - 支付回调幂等机制（基于 `payment_callback_log` 表）
> - 消息投递重试策略
>
> 确认无误后执行 `/f2s-doc-final` 规范化格式。

**你**

> /f2s-doc-final .Knowledge/stock-docs/订单服务架构说明_初稿.md

**Agent**

> 已生成 `.Knowledge/stock-docs/订单服务架构说明_终稿.md`，按终稿模板整理，标注了待补充项。

**你**

> f2s-kb-build .Knowledge/stock-docs/订单服务架构说明_终稿.md

**Agent**

> 已完成知识库同步：
> - 新增 `.Knowledge/topics/order-service.md`
> - 更新 `.Knowledge/manifest-routing.json`（新增路由规则）
> - 生成 `.Knowledge/matchers/order-service.json`（关键词：订单创建、支付回调、幂等、消息投递）
> - 更新 `.Knowledge/index.md`
>
> 后续与订单服务相关的任务会自动命中此主题。

---

## 场景三：按技术方案实现

**你**

> 按方案实现：`.Knowledge/req-docs/退款功能_技术方案.md`，只改 `src/refund/`，不要动支付模块。

**Agent**

> 已读取方案。实现任务列表：
>
> 1. 新建 `RefundController`，实现 `POST /refunds`
> 2. 新建 `RefundService`，含状态机流转逻辑
> 3. 新建 `RefundRepository`，对应 `refund` 表
> 4. 新建 `PointRollbackProducer`，向积分队列发送回撤消息
> 5. 单元测试覆盖状态机流转
>
> 实现前确认：
> - `refund` 表是否已存在，还是需要生成 migration？
> - 积分队列 Topic 名称是什么？

**你**

> 表已存在，不用 migration；Topic 是 `point-rollback-events`。

**Agent**

> 已完成以上 5 项，均在 `src/refund/` 内，未触碰 `src/payment/`。
>
> **待完成（需人工）**：
> - `point-rollback-events` 消费端（积分服务侧）
> - 死信监控告警规则配置
>
> 建议执行 `/f2s-kb-feat` 将本次新增能力同步进知识库。

---

## 场景四：实现后补录知识库

**你**

> /f2s-kb-sync 退款功能上线了，帮我把支付失败重试队列命名、死信表字段、监控告警口径沉淀进知识库，先给大纲我确认再写。

**Agent**

> 知识库更新大纲（待确认）：
>
> **更新主题**：`order-service`（已有）
>
> - 新增「支付失败重试机制」：队列名 `payment-retry-queue`，最大重试 3 次，间隔 30s / 120s / 300s
> - 新增「死信表」：表名 `payment_dead_letter`，字段 `order_id / error_code / retry_count / created_at`
> - 新增「监控口径」：告警阈值 `retry_count >= 3`，通知渠道 DingTalk
>
> 确认后写入，或告诉我需要修改的地方。

**你**

> 确认写入。

**Agent**

> 已更新 `.Knowledge/topics/order-service.md`，`manifest-routing` 未变动（主题已存在）。

---

## 场景五：发现违规实现，修复并同步知识库

**你**

> /f2s-kb-fix `RefundService` 里直接 `new RestTemplate()` 了，违反 Spring Bean 注入约定。

**Agent**

> 已修复：`RefundService.java` 第 34 行改为构造注入，`RefundConfig` 补充 `@Bean` 声明。
>
> 同步知识库：`.Knowledge/stock-docs/` 中「HTTP 客户端约定」节更新，注明 `RestTemplate` 必须通过 Bean 注入，禁止直接实例化。

---

## 场景六：Git 合并后知识库冲突

**你**

> /f2s-kb-merge `.Knowledge/index.md` 和 `.Knowledge/stock-docs/订单服务架构说明_终稿.md` 合并后有冲突标记，业务代码我已手动合完。

**Agent**

> 已扫描两个文件的冲突标记：
>
> - `index.md`：2 处冲突，均为主题描述字段，取 HEAD 版本（内容较新），已自动处理。
> - `订单服务架构说明_终稿.md`：1 处冲突，「监控告警阈值」两个分支不同（3 次 vs 5 次），需你确认。

**你**

> 用 3 次。

**Agent**

> 已按确认结果清理全部冲突标记，文件可提交。

---

## 相关文档

- [使用说明](./使用说明.md)
- [命令说明](./命令说明.md)
- [目录与路径约定](./目录与路径约定.md)
- [体系与原理](./体系与原理.md)
- [项目里程碑](./项目里程碑.md)