Feature Guide

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 条失败路径。
• 文档中路径、参数、接口在当前分支可定位到实现。
• 流程图与泳道图覆盖主链路且不与实现冲突。