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. 做代码映射表

   • 每个关键文档步骤至少映射一个代码路径