---
name: feature-guide
description: 生成 PowerX 功能使用指导文档（人性化、可执行、与实现对齐）。强制包含业务背景、模块关系、流程图、泳道图、页面/接口/命令步骤、验收、排障、回滚与代码映射。
---

# PowerX 功能使用指导文档技能（Feature Guide）

## 适用场景

当你需要为 PowerX 平台能力编写“可直接执行、跨角色可协作”的功能文档时使用本技能。典型场景：

- 新功能上线，需要给研发/QA/运维/项目负责人一份可照着操作的手册。
- 功能已经实现，但现有文档偏实现细节，缺少端到端操作链路。
- 需要把“Web Admin 页面 + Admin/Tenant API + 后端实现 + 观测指标”串成闭环。

## 目标

输出一份**可执行 + 可验收 + 可追溯**的 PowerX 文档，满足：

1. 先讲清“为什么做”（业务背景/痛点/目标）。
2. 再讲清“谁在什么环境下怎么用”（角色、范围、限制）。
3. 给出“从 0 到跑通”的操作步骤（页面、接口、命令、预期结果、失败处理）。
4. 关键行为可追溯到代码实现（路由/handler/service/config/test）。
5. 包含流程图与泳道图，帮助跨角色理解协作与边界。

## 必须遵守的文档结构（强制）

最终文档必须按以下顺序组织章节：

1. **功能背景与目标**
2. **角色与适用范围**（谁看、在哪个环境用）
3. **整体架构与模块关系**（含模块关系图）
4. **核心流程**（含流程图）
5. **跨角色协作流程**（含泳道图）
6. **前置条件与依赖**（配置、权限、数据、Feature Flag）
7. **操作步骤（按场景拆分）**
   - 页面操作步骤（Web Admin）
   - 接口调用步骤（Admin/Tenant API）
   - 本地联调步骤（backend/web-admin/脚本）
8. **预期结果与验收标准**
9. **代码实现映射**（路由/服务/配置/测试）
10. **常见问题与排障**
11. **回滚与风险控制**
12. **变更记录**（版本、日期、责任人）

## 图示规范（强制）

### 1) 流程图（必须）

- 使用 Mermaid `flowchart LR` 或 `flowchart TD`
- 必须包含“输入/处理/输出/失败分支”
- 至少体现 1 条失败分支与回退路径

### 2) 泳道图（必须）

- 使用 Mermaid `flowchart LR` + `subgraph` 模拟泳道
- 至少 3 条泳道（示例：Web Admin、PowerX Backend、External System）
- 必须标明跨泳道调用方向与返回结果

## 写作风格规范（强制）

- 先结论后细节。
- 每个步骤必须包含：
  - **动作**（做什么）
  - **入口/命令**（在哪做）
  - **预期结果**（看到什么算成功）
  - **失败处理**（失败后看哪里）
- 面向使用者写作，不假设读者了解全部实现细节。
- 禁止脱离实现：文档关键行为都必须能在代码中定位。

## PowerX 代码对齐检查清单（发布前必过）

- [ ] 文档中的路由前缀与实际一致（如 `/api/v1/admin`、`/api/v1/tenant`）。
- [ ] 配置项名称、默认值与优先级说明一致（`.env`/配置文件/运行时覆盖）。
- [ ] 页面入口与按钮文案与当前 Web Admin UI 一致。
- [ ] 接口请求/响应示例与 DTO/handler 行为一致。
- [ ] 文档提到的 feature flag / 权限 / 开关在当前分支真实存在。
- [ ] 至少 1 条测试或脚本命令可验证主链路。
- [ ] 观测项（日志字段、指标名、trace_id）可在运行环境检索。

## 执行步骤（建议流程）

1. **收集上下文**
   - 读取 `specs/<feature-id>/spec.md|plan.md|tasks.md|quickstart.md`（如存在）
   - 读取后端路由注册、关键 handler/service、配置结构、测试用例
   - 读取 Web Admin 页面入口与交互流程（如涉及前端）

2. **梳理功能地图**
   - 功能入口：页面/API/命令
   - 核心链路：handler -> service -> repository/integration
   - 输出与观测：日志、指标、事件、trace

3. **先画图再写步骤**
   - 先产出模块关系图、主流程图、泳道图
   - 再填操作步骤，确保步骤连续可执行

4. **补齐验收与排障**
   - 每个场景定义“成功判定”
   - 列出常见失败场景与定位命令

5. **做代码映射表**
   - 每个关键文档步骤至少映射一个代码路径

## 输出模板

- 使用模板：`templates/feature-guide-template.md`
- 允许按具体功能微调章节名，但不得删除“流程图、泳道图、代码映射、验收、排障”章节。

## 默认输出路径规范（强制）

未被用户显式指定输出路径时，使用以下规则：

1. 输入为 `specs/<feature-id>/...` 时：
   - 若 `<feature-id>` 或 spec 主题属于“部署/运维”（如 deploy、docker、systemd、ops、backup、migration）：
     - 默认输出目录：`docs/guides/deploy/<feature-id>/`
   - 其他功能：
     - 默认输出目录：`docs/guides/features/<feature-id>/`
   - 默认主文档：`guide.md`
2. 目录不存在时，先创建目录再写入。
3. 目标文件已存在时，默认执行“覆盖更新”（保留结构，按当前实现刷新）。
4. 仅在用户明确要求时，才写入 `specs/` 下临时文档。

## Use Case 拆分规则（强制）

必须根据实际场景自动判断是否拆分多文档：

1. 仅 1 条独立主链路：输出 `guide.md` 单文档。
2. 多条可独立验收链路：输出
   - `guide.md`（总览：背景、模块、依赖、验收总则、索引）
   - `usecase-<slug>.md`（每条链路一份）
3. `<slug>` 规则：
   - 优先稳定标识（`us1`、`scenario-a`）+ 语义短名
   - 仅使用小写字母、数字、连字符
4. `guide.md` 必须包含 Use Case 索引表（文件名 + 适用角色 + 验收口径）。

## 示例要求（最少）

文档至少包含：

- 1 个页面操作示例（路径、按钮、成功提示）
- 1 个接口调用示例（curl + 响应片段）
- 1 个本地联调示例（启动命令 + 日志/指标检查）

## 完成定义（DoD）

满足以下条件才算文档完成：

- [ ] 新同学不看代码，也可按文档独立跑通主流程。
- [ ] QA 可按文档复现至少 1 条成功路径与 1 条失败路径。
- [ ] 文档中路径、参数、接口在当前分支可定位到实现。
- [ ] 流程图与泳道图覆盖主链路且不与实现冲突。