@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-design/skills/workflow-api-call-guide/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: workflow-api-call-guide
+description: "Use after backend-tech-spec, before integration-verify. Generates a step-by-step API call guide for frontend developers. This is NOT a change list — no code changes, just calling instructions based on the confirmed API contract and backend tech spec."
+---
+
+# API 调用指南
+
+## 定位
+
+| 维度 | 说明 |
+|------|------|
+| **消费者** | 人类前端开发者 |
+| **权威源** | `api-contract.md`（API 签名唯一真相源，本 skill 不重新定义） |
+| **互补关系** | `workflow-change-plan` 产出 AI 可执行的 `变更清单.md`；本 skill 产出人类可读的 `api-call-guide.md`。两者互补，不可替代 |
+| **前置条件** | `api-contract.md` 必须已存在且审查通过 |
+
+## 跳过条件
+
+满足以下任一条件时，本 skill 不产生有意义产出，应跳过：
+
+1. `后端技术方案.meta.json` 中 `api_count == 0`（无新增或修改的 API）
+2. `api-contract.md` 不存在（本功能无 API 变更）
+3. 纯内部重构 / 仅修改现有实现不改变接口签名
+
+在完整 workflow 中不要直接跳过文件产出；应生成 no-op `api-call-guide.md` 和 `api-call-guide.meta.json`，其中 `api_required: false`、`covered_endpoint_count: 0`、`pending_items: []`，并写明跳过原因。这样后续 Merge Gate 可以被机器校验。
+
+## 产出位置
+
+- `.planning/features/{功能名}/api-call-guide.md`
+- `.planning/features/{功能名}/api-call-guide.meta.json`
+
+`api-call-guide.meta.json` 必须包含：
+
+```json
+{
+  "api_required": true,
+  "covered_endpoint_count": 0,
+  "frontend_consumable": true,
+  "mock_ready": true,
+  "pending_items": [],
+  "skip_reason": ""
+}
+```
+
+## 输入
+
+- `.planning/features/{功能名}/api-contract.md` — **API 签名唯一权威源**
+- `.planning/features/{功能名}/后端技术方案.md` — 后端实现细节和 seam 位置
+
+## 核心原则
+
+1. **不改代码** — 这是调用指南，不是变更清单。不要包含 DDL、代码任务、文件路径
+2. **API 签名必须引用 api-contract.md** — 不自行定义 endpoint、参数、响应结构。只引用，不重定义
+3. **步骤可执行** — 每个步骤描述前端应该怎么调这个 API，包含请求示例和响应解析
+4. **按业务流组织** — 按用户操作的业务顺序排列，不是按 API 方法名排序
+5. **标注 seam 范围** — 每个调用步骤标注对应接口和后端模块
+
+## 产出模板
+
+```
+# API 调用指南：{功能名}
+
+## 业务流概览
+
+```mermaid
+sequenceDiagram
+  用户->>前端: 填写订单
+  前端->>后端: POST /api/v1/orders
+  后端-->>前端: {order_id, status}
+  前端->>用户: 显示订单确认页
+  用户->>前端: 查看订单详情
+  前端->>后端: GET /api/v1/orders/{id}
+  后端-->>前端: {完整订单数据}
+```
+
+## 步骤 1：创建订单
+
+**接口**：POST /api/v1/orders（定义见 `api-contract.md` §1）
+**Seam**：OrderController.create()
+
+**调用时机**：用户填写完订单并点击「提交」
+
+**请求示例**：
+```javascript
+const response = await fetch('/api/v1/orders', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    user_id: currentUser.id,
+    items: cart.items.map(item => ({
+      product_id: item.productId,
+      quantity: item.quantity,
+      price: item.price
+    })),
+    remark: remarkInput.value
+  })
+});
+```
+
+**成功响应 201**：
+```javascript
+const data = await response.json();
+// data.order_id → 用于跳转到订单详情页
+// data.status → "pending"，可显示等待确认状态
+```
+
+**错误处理**：
+- 400: 参数校验失败，显示 `data.detail` 中的字段级错误
+- 422: 业务规则拒绝（如库存不足），显示 `data.error`
+
+## 步骤 2：查询订单详情
+
+**接口**：GET /api/v1/orders/{id}（定义见 `api-contract.md` §2）
+**Seam**：OrderController.getById()
+
+...
+
+## 异常流程
+
+| 场景 | 处理方式 |
+|------|---------|
+| 网络超时 | 显示「请求超时，请重试」，不自动重试 |
+| 订单不存在（404） | 显示「订单不存在」，跳转到订单列表 |
+| 服务器错误（500） | 显示「系统繁忙，请稍后重试」 |
+
+## 前端状态管理建议
+
+- 订单列表：使用 React Query / SWR 缓存，key 为 `['orders']`
+- 订单详情：使用 `['orders', orderId]` 作为缓存 key
+- 创建订单后：invalidate 订单列表缓存
+```
+
+## 完成门禁
+
+- [ ] 每个 API 契约中的接口都有对应调用步骤
+- [ ] 每个步骤引用 `api-contract.md` 中的接口定义（不自行定义）
+- [ ] 每个步骤包含请求示例和响应解析
+- [ ] 包含至少一个异常流程的响应示例
+- [ ] 没有包含代码变更任务（那是 change-plan 的职责）
+- [ ] meta.json 中 `frontend_consumable` 和 `mock_ready` 均为 true
+- [ ] meta.json 中 `pending_items` 为空数组
+- [ ] 无 API 变更时生成 no-op meta，`api_required` 为 false

package/plugins/devflow-design/skills/workflow-api-contract/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: workflow-api-contract
+description: "Use after requirement-baseline, before dual-track fork. Defines shared API contracts (endpoints, request/response shapes, data models) that both Track A and Track B reference. This is the fork point — contract changes after this step are exception paths."
+---
+
+# API 契约生成器
+
+## 定位
+
+| 维度 | 说明 |
+|------|------|
+| **消费者** | Track A（后端）、Track B（前端）、`api-call-guide`、`change-plan`、`integration-verify` |
+| **角色** | **双轨分叉点** — Track A 和 Track B 唯一共享的接口定义。契约确定后变更走 `api-supplement` 异常路径 |
+| **权威性** | 所有下游 skill 必须引用本契约中的 API 签名，不得自行定义 |
+
+## 跳过条件
+
+满足以下条件时，本 skill 不产生有意义产出，应跳过：
+
+1. 本功能无新增或修改的 API（纯内部重构、配置变更、存储优化等）
+2. baseline.md 中所有 FP 的 `seam_type` 均不涉及 API 层
+
+在完整 workflow 中不要直接跳过文件产出；应生成 no-op API 契约，并在 meta 中写入 `api_required: false`、`endpoint_count: 0`、`pending_contract_count: 0`。后续 `api-call-guide` 和 `integration-verify` 也生成 no-op 产物，保证状态机和 artifact registry 可校验。
+
+## 产出位置
+
+- `.planning/features/{功能名}/api-contract.md`
+- `.planning/features/{功能名}/api-contract.meta.json`
+
+## 输入
+
+- `.planning/requirements/baseline.md` — 需求基线（FP/BR/BC）
+- `.planning/navigation/INDEX.md` 和相关 codebase navigation — 粗定位已有接口
+- `.planning/code-index/`（如存在）— 查询已有 route/handler/API symbol 与 `routes_to` / `calls` 关系，确认接口复用和冲突
+
+使用 code-index 时，必须回读 `evidence_path:evidence_line` 附近源码后再把既有接口写入契约；不得只凭 Markdown navigation 或 relation 摘要判断。
+
+## 核心原则
+
+1. **只定义接口契约，不谈实现细节** — 不写数据表结构、不写具体代码、不写业务流程内部逻辑
+2. **分叉后不变更** — 一旦确定，Track A/B 都基于此契约工作。变更走 `api-supplement` 异常路径
+3. **接口签名必须完整** — 包括 endpoint、method、请求参数（含类型约束）、响应结构（含状态码）
+4. **数据模型共享** — 核心业务实体定义在这里，前后端共用一个数据模型
+5. **切片对齐** — 若 baseline 包含 `SL-*`，先读取 `skill://workflow-pipeline/references/slice-safety-guide.md`，只为当前执行切片定义 API。后置切片接口不得提前进入契约。
+6. **既有接口优先查事实索引** — 当 `.planning/code-index/` 存在时，先用 Symbol/Relation 定位候选接口、调用方和处理器，再读取源码证据；缺失或过期时再按 navigation 和 `rg` 兜底。
+
+## 产出模板
+
+```
+# API 契约：{功能名}
+
+## 当前执行切片
+
+- Slice ID: SL-001
+- 纳入 FP/BR/BC: FP-001, BR-001, BC-001
+- 后置切片: SL-002（仅作上下文）
+
+## 接口列表
+
+| # | Method | Endpoint | 说明 | 所属 FP |
+|---|--------|----------|------|---------|
+| 1 | POST | /api/v1/orders | 创建订单 | FP-001 |
+| 2 | GET | /api/v1/orders/{id} | 查询订单 | FP-001 |
+
+## 接口详情
+
+### 1. POST /api/v1/orders
+
+**说明**：创建订单
+**FP**：FP-001
+
+**请求体**：
+```json
+{
+  "user_id": "string (uuid)",
+  "items": [
+    {
+      "product_id": "string (uuid)",
+      "quantity": "integer (>=1)",
+      "price": "number (分)"
+    }
+  ],
+  "remark": "string (optional, max 200)"
+}
+```
+
+**响应 201**：
+```json
+{
+  "order_id": "string (uuid)",
+  "status": "string (pending/confirmed/shipped)",
+  "total_amount": "number (分)",
+  "created_at": "string (ISO 8601)"
+}
+```
+
+**响应 400/422**：
+```json
+{
+  "error": "string",
+  "detail": {}
+}
+```
+
+### 2. GET /api/v1/orders/{id}
+...
+
+## 共享数据模型
+
+### Order（订单）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| order_id | string (uuid) | 订单 ID |
+| user_id | string (uuid) | 用户 ID |
+| status | enum(pending/confirmed/shipped/cancelled) | 订单状态 |
+| items | array[OrderItem] | 订单项 |
+| total_amount | number (分) | 总金额（整数分） |
+| created_at | string (ISO 8601) | 创建时间 |
+| updated_at | string (ISO 8601) | 更新时间 |
+
+### OrderItem（订单项）
+...
+
+## 接口依赖关系
+
+| 调用顺序 | 接口 | 说明 |
+|---------|------|------|
+| 1 | POST /api/v1/orders | 先创建订单 |
+| 2 | GET /api/v1/orders/{id} | 后查状态 |
+
+## 未解决的接口问题
+
+- 订单取消是否需要单独的 PUT 接口？
+- 分页查询的 page_size 默认值？
+```
+
+## 完成门禁
+
+- [ ] 每个涉及 API 的 FP 至少映射到一个接口
+- [ ] 若存在 `SL-*`，每个接口都标注当前 Slice ID，且未包含后置切片接口
+- [ ] 每个接口有完整的请求/响应结构
+- [ ] 若 `.planning/code-index/` 存在，已有接口复用/冲突判断已查询 code-index 并回读源码 evidence；未使用时已说明原因
+- [ ] 核心数据模型已定义字段和类型
+- [ ] 没有包含实现细节（SQL、表结构、代码片段）
+- [ ] meta.json 中 `endpoint_count` 已记录接口总数
+- [ ] meta.json 中 `api_required` 已记录是否存在 API 变更
+- [ ] meta.json 中 `review_status` 为 `passed`
+- [ ] meta.json 中 `pending_contract_count` 为 0
+- [ ] meta.json 中 `breaking_change_count`、`permission_rule_count`、`error_case_count` 已记录

package/plugins/devflow-design/skills/workflow-api-supplement/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: workflow-api-supplement
+description: "Use when Track B (frontend-tech-spec) discovers API gaps that the shared API contract doesn't cover. This is an EXCEPTION PATH — not a normal pipeline step. Submits API supplement requests for Track A evaluation."
+---
+
+# API 补充需求（异常路径）
+
+## 定位
+
+| 维度 | 说明 |
+|------|------|
+| **触发方** | Track B（`workflow-frontend-tech-spec`） |
+| **接收方** | Track A（后端开发者） |
+| **触发条件** | 前端方案完成时发现 API 缺口，且 `frontend-tech-spec.meta.json` 中 `api_gaps_count > 0` |
+| **与其他 skill 关系** | 是 `api-contract` 的补丁流程。正常流程下 API 在契约阶段已完整定义，本 skill 仅在遗漏时触发 |
+
+## 触发条件（程序化检测）
+
+orchestrator 通过以下方式检测是否需要触发本 skill：
+
+1. 读取 `前端技术方案.meta.json` 的 `api_gaps_count` 字段
+2. 若 `api_gaps_count > 0` → 触发补充评估，产出补充请求并要求 Track A 回写 `api-contract.md`
+3. 若 `api_gaps_count == 0` → 生成 no-op `api-supplement-requests.md` 和 meta，供 `integration-verify` 机器校验
+4. 若字段不存在 → 阻断进入 `integration-verify`，要求先补齐 `前端技术方案.meta.json`
+
+`workflow-frontend-tech-spec` 的完成门禁应包含：检查前端需要的 API 是否都在 `api-contract.md` 中有定义，缺失数量写入 `api_gaps_count`。
+
+## 输入
+
+- `.planning/features/{功能名}/api-contract.md` — 已有 API 契约
+- `.planning/features/{功能名}/前端技术方案.md` — 刚刚完成的前端方案
+- `.planning/features/{功能名}/UI-SPEC.md` — UI 设计规范
+
+## 产出
+
+- `.planning/features/{功能名}/api-supplement-requests.md`
+- `.planning/features/{功能名}/api-supplement-requests.meta.json`
+
+即使没有 API 补充需求，也要生成 no-op meta：
+
+```json
+{
+  "api_supplement_count": 0,
+  "unresolved_supplement_count": 0,
+  "contract_updated": false,
+  "no_supplement_required": true
+}
+```
+
+## 输出模板
+
+```
+# API 补充需求：{功能名}
+
+## 来源
+前端方案中发现 {count} 个 API 契约未覆盖的接口需求。
+
+## 补充需求列表
+
+### SR-1: PATCH /api/v1/orders/{id}/cancel
+
+**理由**：前端订单详情页需要取消订单功能，但 API 契约中只有 POST（创建）和 GET（查询）。
+
+**预期签名**：
+```
+PATCH /api/v1/orders/{id}/cancel
+Request: {} (空，服务端校验权限)
+Response 200: { order_id, status: "cancelled", cancelled_at }
+```
+
+**是否可以改用已有接口**：
+- ❌ POST /api/v1/orders — 创建非取消
+- ❌ GET /api/v1/orders/{id} — 只读查询
+
+**建议**：需要新增接口。
+
+### SR-2: GET /api/v1/orders 响应增加 total_count 字段
+
+**理由**：前端分页列表需要显示总条数，但契约中的分页响应只有 data 数组。
+
+**预期变更**：在响应中增加 `total_count: integer` 字段
+
+**是否可以改用已有接口**：前端可以自己算，但数据量大时不准确。
+
+**建议**：后端增加 total_count 字段，不改前端逻辑。
+
+## 提交给 Track A 评估
+
+| # | 需求 | 类型 | 推荐方案 | Track A 决策 |
+|---|------|------|---------|-------------|
+| SR-1 | 新增取消订单接口 | 新增接口 | 新建 PATCH | {待评估} |
+| SR-2 | 分页加 total_count | 响应扩展 | 加字段 | {待评估} |
+
+## Track A 决策记录
+
+| # | 决策 | 理由 | 处理方式 |
+|---|------|------|---------|
+| SR-1 | ① 加接口 | 取消是独立业务逻辑，不应复用创建接口 | 新增 PATCH，安排后端开发 |
+| SR-2 | ② 已有接口拼 | 前端用 data.length + 约定 pageSize 计算 | 不改契约 |
+```
+
+## 评估规则
+
+提交给 Track A 后，Track A 按以下优先级评估：
+
+1. **用已有接口拼** — 不改契约，前端自己组合已有接口满足需求
+2. **扩展已有接口** — 在现有接口上加可选参数或字段（不破坏兼容性）
+3. **加新接口** — 新建 endpoint，独立开发和部署
+4. **暂缓** — 这个版本不做，放入下一轮
+
+**所有决策必须回写 `api-contract.md`**，确保契约保持单一真相源。
+
+## 完成门禁
+
+- [ ] 每个补充需求描述了"缺什么"和"为什么缺"
+- [ ] 每个补充需求检查了是否可复用已有接口
+- [ ] 每个补充需求有推荐的评估方案
+- [ ] 不超过 3 个补充需求（超过说明 API 契约阶段不完整）
+- [ ] Track A 决策已回写 `api-contract.md`
+- [ ] meta.json 中 `unresolved_supplement_count` 为 0
+- [ ] 若存在补充需求，`contract_updated` 为 true；若没有补充需求，`no_supplement_required` 为 true

package/plugins/devflow-design/skills/workflow-backend-tech-spec/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: workflow-backend-tech-spec
+description: "Use when a requirement baseline needs a backend technical design, including API, data model, affected modules, integration points, and risks."
+---
+
+## Legacy Command Metadata
+
+Original slash-command metadata retained only as workflow invocation guidance.
+
+```yaml
+argument-hint: <功能名>
+user-invocable: true
+pattern: generator+tool-wrapper
+inputs:
+- .planning/features/{功能名}/api-contract.md
+- .planning/requirements/baseline.md
+- .planning/features/{功能名}/功能点梳理.md (optional, Track B context when already available)
+- .planning/PROJECT.md
+- .planning/navigation/INDEX.md
+- .planning/rules/INDEX.md
+- .planning/execution-contract.md
+- .planning/toolchain.md
+- .planning/lessons/README.md
+- .context/spec/index.md
+- .context/spec/stacks/
+- .context/spec/backend/index.md
+- .context/spec/backend/
+- .context/workflow/
+- .context/lessons/README.md（如存在）
+- .planning/milestones/
+- references/affected-module-exploration.md
+output: .planning/features/{功能名}/后端技术方案.md
+allowed-tools:
+- Read
+- Write
+- Edit
+- Bash
+- Grep
+- Glob
+- ask
+```
+
+# 后端技术方案生成器
+
+根据需求基线和项目现有代码，生成聚焦于影响分析的后端技术方案。
+
+## 核心原则
+
+**遇到不确定的地方，必须询问用户，不要自己做决定。**
+
+常见需要询问的场景：
+- 存在多个类似功能，不知道用哪个
+- 业务规则有歧义
+- 存在多种实现方案
+- 不确定是否复用现有功能
+- 涉及调用外部/上游 API，但没有对应的接口文档（URL、认证方式、请求/响应结构、错误码）
+
+## 工作流程
+
+### 第一阶段：理解需求
+
+1. 读取 `.planning/requirements/baseline.md` 理解需求
+2. 读取 `.planning/PROJECT.md` 了解项目上下文
+3. 如果 baseline.md 不存在，询问用户需求或在 `.planning/milestones/` 中查找相关历史
+4. 读取 `references/project-rule-contract.md`，按 Spec Read Contract 发现并加载目标项目的后端规则包：`.planning/rules/INDEX.md` → `.context/spec/index.md` → 命中的 stack spec → 命中的 backend codebase spec → navigation → code-index（如存在且需要关系事实）→ 源码
+5. 读取 `references/code-explore-guide.md`，按项目导航和规则包做通用后端探索
+6. 读取 baseline 的 `反向审视与用户拍板`、`待确认事项`、`下游输入契约`：
+   - 已确认的冲突/复用/替代方案决策必须进入技术方案
+   - 影响 scope、语义、归属、兼容性或实现成本的未确认项，不得被当成已确认需求
+   - 若未确认项阻塞后端方案，询问用户；`--auto` 或无法询问时写入待确认事项和风险
+7. 读取 `.planning/features/{功能名}/api-contract.md`。在双轨模式下，后端方案必须以 API 契约和需求基线作为权威输入，不得等待 Track B 的 `功能点梳理.md` 才开始。
+8. 若 `功能点梳理.md` 已存在，可作为测试可读上下文补充读取；若不存在，不阻塞 Track A。
+9. 若 baseline、api-contract 或 `功能点梳理.md` 包含 `SL-*` 切片计划，读取 `skill://workflow-pipeline/references/slice-safety-guide.md`，只为当前执行切片生成后端方案。后置切片只可作为依赖上下文或后续范围，不得生成库表、接口、任务或运行时设计。
+
+### 第二阶段：探索现有代码
+
+在设计前，探索相关实现：
+
+1. **读取 PROJECT.md 的 Project Layout 章节**，确定后端代码所在目录
+2. 按 `references/project-rule-contract.md` 的顺序读取项目规则包，优先使用 `.planning/rules/INDEX.md` 和 `.context/spec/index.md` 匹配 stack/codebase spec，兼容 `.context/spec/`、`.context/workflow/`、`.context/lessons/` 和根目录 `AGENTS.md` / `CLAUDE.md`
+3. 读取 `.planning/navigation/INDEX.md` → 筛选后端/服务类型代码库 → 加载对应 `{name}.md` 导航文件，按目标项目实际结构识别领域/模型、服务、持久化、接口、任务、集成、配置和迁移入口
+4. 若 `.planning/code-index/` 存在，用 Symbol Index 和 Relation Graph 查询相关入口、调用链、读写资源、测试和外部集成候选；读取 `evidence_path:evidence_line` 后再写现状结论
+5. **现有功能复用检查**：编写任何新逻辑前，必须先在项目中搜索是否已有相同或相似功能的实现。优先使用 code-index 查询 symbols/relations；缺失或过期时再按导航和 `rg` 兜底。搜索范围包括：
+   - `pkg/` 目录（已有外部集成封装，如支付、红包、短信、二维码等）
+   - Service 层（已有业务能力）
+   - Repository 层（已有数据访问模式）
+   - 工具方法/公共函数
+   **严禁绕过已有封装用裸 HTTP 重写已有集成。**
+6. 按导航、code-index 和规则包定向搜索相关功能的现有实现，不硬编码语言、框架或业务目录结构
+7. **寻找最佳实践标杆**：在搜索到的同类功能中，识别实现质量最高的一个作为设计参考。分析其：
+   - 分层结构（handler→service→repository→dao 的接口定义方式）
+   - 错误处理与传递模式
+   - 参数封装与命名惯例
+   - 测试覆盖模式
+   - API 路由与 Swagger 注解风格
+   新功能设计应与此标杆保持一致，避免偏离项目已验证的成熟模式。
+8. 检查三层复用机会：业务能力、已有依赖/库、项目模式；与 baseline 的复用决策保持一致
+9. **识别可抽象能力**：分析新功能中哪些部分具备独立复用价值，应抽象为 `pkg/` 级能力模块。判断标准：
+   - 是否在多个业务场景中会被调用（如支付、红包、短信、推送）？
+   - 是否对接了外部系统，需要统一的 Client 接口封装？
+   - 是否有独立的配置、认证、错误处理逻辑？
+   满足任一条件的，应在方案中定义能力接口（Client interface + 参数/结果结构体），参考已有 `pkg/wx_red_pack`、`pkg/wx_pay` 的模式设计。
+10. **执行被影响方探索**：读取 `references/affected-module-exploration.md`，对 baseline 第8.2节"关联历史功能/模块"表格列出的每个受影响模块，按清单逐项读取代码并产出：现状流程图、现有字段/方法表格、集成点列表、复用/扩展/新增决策。探索产出直接填入输出文档的"现有功能说明"（第四章）和"影响范围"（第六章）。**探索产出检查不通过，不得进入 Phase 3。**
+
+**关键：如果发现多个相似功能，必须询问用户使用哪个。**
+如果与 baseline 中的用户拍板结果冲突，停止并要求重新确认，不要自行改判。
+
+### 第二阶段.5 — Seam 确认（必做）
+
+在设计方案前，确认当前的"缝"在哪里。
+
+### 第二阶段.6 — Slice Scope Guard
+
+如果输入包含当前执行切片：
+
+- 在文档开头写明 active `Slice ID`、切片名称、纳入 FP/BR/BC、后置 FP/BR/BC。
+- API、库表、Job、外部集成、消息、权限、迁移设计只允许覆盖当前切片。
+- 共享表或服务若服务于后置切片，必须说明它在当前切片中的可验证用途；否则移到后续范围。
+- 若后端方案必须同时设计多个 slice 才能自洽，停止并要求回到 `workflow-requirement-baseline` 重新切片。
+
+**1. 识别候选 seam**
+
+根据 baseline 的 `seam_type`（Phase 3.5 产出）识别每个 FP 的切入位置：
+
+| FP | baseline seam_type | 候选模块 | 预期操作 |
+|----|-------------------|---------|---------|
+| FP-001 | 扩展 | OrderService | 扩展已有接口 |
+| FP-003 | 新建 | OrderWorkflow（拟新建） | 新建独立模块 |
+
+**2. 向用户确认**
+
+用一句话确认，不要抛技术细节：
+
+> "FP-001 订单审批，我打算在 `OrderService` 加一个 `process()` 方法。这个模块还被其他功能共用吗？"
+>
+> "FP-003 新建的审批流程，我建议新建一个 `OrderWorkflow` 模块。你确认这个位置？"
+
+**3. 记录 seam 决策**
+
+将用户确认的结果写入方案文档的"影响范围"章节：
+
+```markdown
+## Seam 决策记录
+| FP | Seam 位置 | 决策 | 确认人 |
+|----|----------|------|--------|
+| FP-001 | OrderService.process() | 扩展已有接口，不影响现有调用方 | 用户确认 |
+| FP-003 | OrderWorkflow（新建） | 新建独立模块 | 用户确认 |
+```
+
+**门禁**：每个 FP 必须有 seam 确认记录，否则不得进入 Phase 3。
+
+### 第三阶段：生成文档
+
+1. 创建 `.planning/features/{功能名}/` 目录
+2. 读取 `assets/backend-spec-template.md` 模板
+3. 按模板结构填充内容，并写入 `需求基线衔接`、`后端规范影响`、`能力抽象建议` 章节
+4. 文件名格式：`.planning/features/{功能名}/后端技术方案.md`
+
+If an older baseline still points to root `features/{功能名}/`, treat that as a legacy read path. New backend tech-spec output stays under `.planning/features/{功能名}/`.
+
+### 第三阶段.5 — ADR 创建（按需）
+
+在生成文档后、用户确认前，检查是否存在"值得记录为 ADR"的决策。
+
+**ADR 触发条件（三个必须同时满足）：**
+
+1. **难逆转** — 改主意代价大（表结构变更、接口重设计、模块拆分决策）
+2. **无上下文会困惑** — 后人会问"为什么这么选"
+3. **有真实权衡** — 有替代方案并且选了其中一个
+
+**ADR 格式：**
+
+```markdown
+# ADR-001: 使用 OrderWorkflow 而非扩展 OrderService
+
+## 状态
+已确认 / 待定 / 已废弃
+
+## 上下文
+{当时面临的问题和约束}
+
+## 被否决的方案
+{方案 B：扩展 OrderService
+ 理由：会导致 OrderService 接口膨胀，影响 3 个现有调用方}
+
+## 决策
+{方案 A：新建 OrderWorkflow 模块，提供单一 process() 接口}
+
+## 后果
+- 正面：接口隔离，不影响现有调用方
+- 负面：多一层抽象，增加模块数量
+- 兼容性：无影响
+```
+
+**ADR 存放路径**：`.planning/architecture/adr/{序号}-{主题}.md`
+
+**不满足条件时不要创建 ADR。** 常规决策（字段名选择、参数顺序等）直接写在方案里即可。
+
+### 第四阶段：用户确认
+
+1. 展示生成的文档
+2. 询问是否需要修改
+3. 迭代直到用户满意
+
+### 第五阶段：结构化元数据
+
+完成后写入 `.planning/features/{功能名}/后端技术方案.meta.json`，字段定义见 `feature-development.yaml` 中 `steps[backend-tech-spec].meta_output.fields`：`api_count`, `table_count`, `migration_count`。
+
+## 注意事项
+
+1. **不要包含代码实现** — 只描述"做什么"，不写"怎么做"
+2. **不要包含上线步骤** — 那是运维层面的内容
+3. **不要包含测试用例** — 那是测试阶段的内容
+4. **保持简洁** — 每个章节控制在必要的内容
+5. **必须询问不确定的事项** — 不要猜测或自行决定
+6. **必须描述现有功能** — 新功能如果影响现有功能，必须先描述现有功能的流程、字段、逻辑
+7. **统计类功能要详细** — 对于涉及统计表的变更，必须说明：现有字段及含义、现有统计 SQL/逻辑、Job 调度频率、新增字段及统计逻辑
+8. **只关注后端逻辑** — 流程图只描述后端服务的处理流程，不要包含前端行为
+9. **必须体现项目规则包** — 若目标项目存在 `.planning/rules/` 或 `.context/spec/`，后端方案必须列出适用规范、相关经验教训、工具链要求、测试策略和审查门禁
+10. **历史口径使用 `.planning`** — 与历史相关的判断优先来自 `.planning/milestones/`、`.planning/requirements/`、`.planning/lessons/` 和阶段 `CONTEXT.md`；`features/` 或 `.context/lessons/` 只作为目标项目存在时的兼容来源
+11. **现有功能复用优先** — 编写任何新逻辑前，必须先在项目内搜索已有实现，避免重复造轮子。重点检查：`pkg/` 外部集成封装、Service 层业务能力、Repository 层数据访问模式、公共工具方法。发现已有封装时直接复用，严禁绕过直接写裸调用
+12. **遵循最佳实践标杆** — 新功能的设计（分层、命名、错误处理、参数封装、测试模式）必须与项目内已有标杆功能保持一致，不得引入与项目验证过的成熟模式相悖的新模式。若需偏离，必须在方案中说明理由
+13. **能力抽象** — 新功能中具有独立复用价值的部分（外部集成、通用业务能力），必须抽象为 `pkg/` 级模块，定义清晰的 Client 接口和参数/结果结构体，形成可被后续功能消费的项目能力资产
+
+## 强制审查门禁（MANDATORY — 不可跳过）
+
+### 反问审查
+
+- [ ] 每个不确定的接口设计、库表变更、Job 逻辑是否已向用户确认？（禁止猜测，禁止自行决定）
+- [ ] 涉及调用上游 API 的，是否已向用户索要接口文档并确认对接方案？（不可猜测 API 契约，包括 URL、认证、请求/响应结构、错误码）
+- [ ] 涉及的每个能力点（外部集成、业务逻辑、数据访问、工具方法），是否已在项目内完成复用搜索？**若已有封装却被绕过直接重写，方案不合格。**
+- [ ] `references/affected-module-exploration.md` 的探索产出检查是否全部通过？（现状流程图、字段/方法表格、集成点列表、复用/扩展/新增决策）**若不通过，必须先补充代码探索，不得继续写文档。**
+- [ ] 若 `.planning/code-index/` 存在，复用/影响范围/调用链/读写资源判断是否已查询 code-index 并回读源码 evidence？若未使用，是否说明缺失或过期原因？
+- [ ] 是否已找到项目内最佳实践标杆，并确认新功能的分层结构、命名、错误处理、参数封装模式与标杆一致？（若偏离，理由是否已写明？）
+- [ ] 新功能中具有独立复用价值的部分，是否已识别并抽象为 `pkg/` 级能力模块？接口定义、参数/结果结构体是否清晰？
+- [ ] 方案影响的现有功能是否已描述其**现状流程/字段/逻辑**？（先描述现状，再分析影响）
+- [ ] 涉及统计表的变更，现有字段及含义、现有 SQL/逻辑、Job 调度频率是否已说明？
+- [ ] 若存在 `SL-*`，方案是否只覆盖当前执行切片，且后置切片未进入实现范围？
+
+### 反向对照审查（源自 spec-writer 模式）
+
+| 嗅探 | 检查 |
+|------|------|
+| 复用嗅探 | 每个新增能力是否已在项目内（pkg/Service/Repository/工具方法）完成复用检查？ |
+| 冲突嗅探 | 新增字段/API 路径/表名/枚举是否与现有约定冲突？ |
+| 重叠嗅探 | 是否会与已有功能形成"两套并存"？ |
+| 背离嗅探 | 新功能的分层/命名/错误处理/参数模式是否偏离项目标杆？若偏离，理由是否充分？ |
+| 内聚嗅探 | 可独立复用的能力（外部集成/通用业务）是否被内聚在业务代码中未抽离为 `pkg/` 模块？ |
+
+### 产物完整性
+
+- [ ] 方案包含：功能要点、影响范围、库表设计（DDL+ER）、流程设计、风险点
+- [ ] 不含前端组件、前端路由（那属于前端技术方案）
+- [ ] 若存在 `.planning/rules/` 或 `.context/spec/`，适用规范+经验教训+工具链+测试策略已列出
+- [ ] 审查结论已写入方案末尾
+
+**审查结论不通过时不得报告 "Step 3c 完成"。**