---
name: dev-deliver
description: 开发流程 - 交付阶段，生成接口文档、使用文档、部署文档等交付物
---

# 交付

> 开发流程第六阶段：基于实际代码和文档生成交付文档。

## 调用方式

`/dev-deliver`，也可说"生成交付文档"或"准备交付"。

## 产出目录

`docs/deliverables/`

## 执行流程

### Checklist

- [ ] 前置检查：读取所有前序产出物
- [ ] 生成接口文档
- [ ] 生成使用文档
- [ ] 生成部署文档
- [ ] 生成变更摘要
- [ ] 用户审阅并保存

### 1. 前置检查

读取所有前序阶段的产出物：
- `docs/requirements/` — 需求文档
- `docs/design/` — 设计文档
- `docs/plans/` — 步骤计划
- `docs/dev-logs/` — 开发日志
- `docs/test-reports/` — 测试报告

如果某些阶段缺失，提示用户但不阻止执行。基于已有信息生成交付文档。

### 2. 生成接口文档

**基于实际代码扫描：**
- 读取项目源代码文件
- 识别 API 端点、路由定义
- 提取函数签名和参数
- 识别请求/响应格式
- 提取错误码定义

**生成格式：**

```markdown
## 接口文档

### API 接口 N：<名称>

**方法**：POST
**路径**：/api/xxx
**描述**：xxx

**请求参数**：
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|

**响应格式**：
[实际响应结构]

**错误码**：
| 错误码 | 描述 |
|--------|------|
```

如果项目不是 API/库类型，调整为文档对应的接口形式（函数接口、模块接口等）。

### 3. 生成使用文档

**基于项目配置文件：**
- 读取 package.json / pyproject.toml / Makefile 等
- 识别依赖和版本要求
- 提取安装/构建命令
- 读取配置文件示例

**生成格式：**

```markdown
## 使用文档

### 环境要求
- Node.js >= 18
- npm >= 9

### 安装
[实际安装命令]

### 配置
[实际配置说明]

### 基本用法
[使用示例]
```

### 4. 生成部署文档

**基于项目结构和配置：**
- 识别部署相关文件（Dockerfile、docker-compose.yml 等）
- 提取环境变量定义
- 识别外部依赖服务
- 提取构建和部署命令

**生成格式：**

```markdown
## 部署文档

### 环境变量
| 变量名 | 必填 | 描述 | 默认值 |
|--------|------|------|--------|

### 部署步骤
1. xxx
2. yyy

### 依赖服务
- 数据库：xxx
- 缓存：xxx
```

### 5. 生成变更摘要

**基于需求文档和开发日志：**

```markdown
## 变更摘要

### 新增
- 功能 A（涉及文件：src/xxx.ts）

### 修改
- 功能 B 优化（涉及文件：src/yyy.ts）

### 已知问题
- [问题 1]：描述及临时解决方案
```

### 6. 用户审阅

- 将完整交付文档展示给用户
- 分段确认：接口文档 → 使用文档 → 部署文档 → 变更摘要
- 收集反馈并修改
- 循环直到用户确认

### 7. 保存文档

按以下格式保存完整交付文档：

```markdown
# 交付文档：<项目名称>

> 创建日期：YYYY-MM-DD
> 版本：1.0.0
> 状态：已交付

## 1. 项目概览
## 2. 接口文档
## 3. 使用文档
## 4. 部署文档
## 5. 变更摘要
```

保存到 `docs/deliverables/YYYY-MM-DD-<项目名>.md`

### 8. 发布执行（可选）

根据项目类型，询问用户是否需要执行发布操作：

```
是否执行发布操作？
[1] git tag + push
[2] npm publish / docker push
[3] 跳过，仅保留文档
```

如选择发布，协助用户执行对应的命令（通过 Bash tool），并记录操作日志。

### 9. 反馈收集（闭环）

交付完成后，收集本轮开发的反馈：

```markdown
## 反馈记录

> 对应交付：docs/deliverables/xxx.md
> 反馈日期：YYYY-MM-DD

### 评分（1-5）
- 需求理解准确度：
- 实现符合预期度：
- 整体满意度：

### 问题与优化点
- [ ] 问题 1
- [ ] 问题 2

### 是否启动新一轮迭代
- [ ] 是 → 更新 workflow-status.md 为"需求分析"阶段
- [ ] 否 → 标记流程结束
```

保存到 `docs/feedback/YYYY-MM-DD-<项目名>.md`。

更新 `docs/workflow-status.md`：
- 如用户选择迭代：当前阶段 = "需求分析"，提示 `/dev-requirement`
- 如用户结束：状态 = "已完成"

## 关键行为

- 接口文档必须基于实际代码，不凭空编造
- 环境变量从代码中实际提取（搜索 process.env、os.environ 等）
- 部署步骤基于项目实际配置（Dockerfile、CI/CD 等）
- 如无法从代码提取，明确标注"需手动补充"