# 文档生成

## 输入要求

1. **代码/项目**（必填）：需要生成文档的代码或项目描述
2. **文档类型**（必填）：函数文档/README/API文档/架构文档
3. **输出格式**（可选）：Markdown/HTML/reStructuredText，默认Markdown
4. **目标读者**（可选）：开发者/用户/运维，默认开发者
5. **语言**（可选）：中文/英文，默认中文

## 执行流程

### 第一步：Spec一致性检查

编写文档前检查与spec的一致性：

- **如有spec**：确保文档描述与spec中的scenario一致
- **发现不一致**：标注文档与spec的偏差，建议同步更新
- **无spec**：文档中标注"基于当前实现，建议补充spec"

```
✓ Spec一致性检查:
- 文档描述 vs Spec: [一致/不一致]
- 需要同步更新: [是/否]
```

### 第二步：内容分析

- 分析目标受众（开发者/用户/维护者）
- 确定文档类型和深度
- 识别关键信息点

### 第三步：结构设计

- 设计文档大纲和章节
- 确定示例和图示
- 规划交叉引用

### 第四步：内容编写

- 编写清晰简洁的说明
- 添加代码示例和截图
- 包含使用场景和最佳实践
- **引用Spec**：在相关章节引用spec中的scenario作为行为依据

### 第五步：引用来源与溯源

文档中的关键结论、行为说明、接口字段、配置项和限制条件必须可追溯；无法验证的内容必须标注"待确认"，不得虚构来源。

| 来源类型      | 引用格式                                  | 使用场景                             |
| ------------- | ----------------------------------------- | ------------------------------------ |
| 本地代码      | `来源：path/to/file.ext:line`             | 函数行为、参数、默认值、错误处理     |
| Spec/Scenario | `来源：spec.md / Scenario: xxx`           | 业务行为、验收标准、边界条件         |
| API/OpenAPI   | `来源：openapi.yaml#/paths/...`           | 接口路径、请求参数、响应字段、错误码 |
| 配置/环境     | `来源：.env.example / config/*.php`       | 环境变量、部署参数、默认配置         |
| 测试用例      | `来源：tests/...`                         | 示例输入输出、回归场景、异常路径     |
| 官方文档      | `来源：官方文档 URL + 访问日期`           | 框架/API/依赖行为说明                |
| 项目记忆      | `来源：project_memory.md / Decision: xxx` | 既有约定、历史决策、团队规范         |

推荐在文档末尾追加“资料来源”章节：

```markdown
## 资料来源

- `src/OrderService.php:42-88`：订单状态流转逻辑
- `spec.md / Scenario: cancel-paid-order`：已支付订单取消规则
- `openapi.yaml#/paths/~1orders~1{id}/post`：接口请求和响应结构
```

### 第六步：质量检查

- 检查准确性和完整性
- 验证代码示例可运行
- 确认格式一致性
- **Spec同步**：确认文档与spec无冲突

### 第七步：记录到项目记忆

文档生成完成后，将关键决策记录到项目记忆（参见 `project-memory-management.md`）：

- 记录文档结构和模板选择理由
- 记录 API 文档规范约定
- 更新项目文档索引，确保后续文档保持一致性

## 输出格式

### 函数文档示例

````markdown
## [函数名]

**功能**：[一句话说明]

**签名**：

```[语言]
[函数签名]
```
````

**参数**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| [参数] | [类型] | [是/否] | [说明] |

**返回值**：
| 类型 | 说明 |
|------|------|
| [类型] | [说明] |

**异常**：
| 异常 | 说明 |
|------|------|
| [异常] | [触发条件] |

**示例**：

```[语言]
[使用示例]
```

````

### README示例

```markdown
# [项目名]

[项目简介]

## 功能特性

- [特性1]
- [特性2]

## 安装

```bash
[安装命令]
````

## 使用

```[语言]
[使用示例]
```

## API文档

自动由代码注解/JSDoc/Python docstrings 提取生成。如项目接入 Swagger/OpenAPI，同时导出机器可读接口定义。

## 贡献

[贡献指南]

```

## 质量标准

- 文档必须准确反映代码功能，不能虚构不存在的功能
- 参数说明必须包含类型、必填性和取值范围
- 示例代码必须可直接运行，不能是伪代码
- README必须包含安装和使用说明，不能只有功能列表
- API文档必须包含错误码和异常情况
- 不得遗漏关键信息（如必要的配置项、环境要求）
- 关键结论必须有来源；缺少来源时必须标注"待确认"和下一步验证方法

## 失败回退机制

| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |
| - | - | - | - | - |
| 第一步：Spec一致性检查 | 无spec或spec与代码严重不一致 | 标注"基于当前实现反推"，跳过一致性检查 | 1 | 建议先走 Spec驱动开发 补全spec |
| 第二步：内容分析 | 代码量大，关键信息点超出单次分析能力 | 按模块分批分析，每批输出局部文档 | 0 | 建议缩小文档范围或分章节生成 |
| 第三步：结构设计 | 文档类型与目标读者组合产生结构冲突 | 优先服务主要读者，次要读者用附录补充 | 1 | 输出两套结构方案，由用户选择 |
| 第四步：内容编写 | 代码示例无法直接运行 | 标注"示例待验证"，提供伪代码框架 | 2 | 输出最小可运行示例 + 待补全标记 |
| 第五步：引用来源与溯源 | 关键结论找不到来源 | 标注"待确认"，列出需补充的代码/Spec/文档证据 | 1 | 不把该结论写成已确认事实 |
| 第六步：质量检查 | 发现文档与代码功能不一致 | 退回第四步修订内容 | 2 | 标注不一致清单，建议代码与文档同步评审 |
| 第七步：记录到项目记忆 | 项目记忆系统不可用 | 输出文档索引到本地文件 | 1 | 标注"索引未沉淀"，提示用户手动保存 |

## 关联 reference

- **frontend-design**（前端设计）— 生成设计系统、组件规范、页面交互说明时参考 `frontend-design`
- **code-review**（代码审查）— 生成前可用 `code-review` 确保代码逻辑正确
- **api-design**（API设计）— API设计完成后可用 `doc-generation` 生成接口文档
- **code-generation**（代码生成）— 生成代码后可用 `doc-generation` 生成配套文档
- **project-memory-management**（项目记忆管理）— 记录文档结构、模板选择理由、API 文档规范约定并更新文档索引
```