---
name: pdlc-deploy
description: 创建部署文档
argument-hint: <服务名 | 应用名>
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
layer: 2
stage: deploy
produces:
  - docs/05_deployment/**
requires: []
next_step: null
terminal_state: deploy_done
---

# 创建部署文档

<!-- @include templates/prompts/iron-law.md -->

为指定服务或应用创建部署手册。

## PDLC 前置检查（必须执行，不可跳过）

1. 从用户输入中提取服务/功能名称关键词
2. 在 `docs/07_reviews/code/` 目录下搜索包含该关键词的评审记录
   - 匹配新格式：`F<日期>-<NN>-*<关键词>*-review.md`
   - 匹配旧格式：`YYYYMMDD-*<关键词>*-review.md`
   - 同时检查文件内容中是否包含该关键词
3. **未找到评审记录** → 输出以下信息后**立即停止，不继续执行**：
   ```
   ⛔ PDLC 守卫：未找到与「<功能名>」相关的评审记录。
   部署文档必须基于已完成评审的代码。请先运行：
   👉 /pdlc-review <评审目标>
   ```
4. **找到** → 提取功能ID（如 `F20260326-01`），读取评审记录内容，继续执行

## 工作流程

1. 阅读目标服务/应用的 README.md 和技术栈信息
2. 阅读 `docs/02_design/architecture/` 下的架构设计文档（如有）
3. 阅读评审记录，确认功能状态
4. **【必须创建文件】** 在 `docs/05_deployment/guides/` 下创建部署手册
   - **使用模板**: `templates/deploy-doc-template.md`（结构完整、章节齐全）
   - **文件名格式**: `<功能ID>-<功能名>-deploy.md`（如 `F20260326-01-user-auth-deploy.md`）
     - 若无功能ID，则使用旧格式 `YYYYMMDD-<服务名>-deploy.md`
   - **文档顶部必须包含 PDLC 追溯头**：
     ```
     <!-- PDLC-TRACE -->
     <!-- 功能ID: F20260326-01 -->
     <!-- 功能名称: user-auth -->
     <!-- 阶段: 部署 -->
     <!-- 前置文档: docs/07_reviews/code/F20260326-01-user-auth-review.md -->
     ```

## 文档内容

- 前置条件（环境要求、依赖服务）
- 环境配置（环境变量、配置文件）
- 构建步骤
- 部署步骤
- 健康检查验证
- 回滚方案
- 常见问题排查

## 部署文档自审与自动修复（创建后立即执行，不可跳过）

重新阅读刚创建的部署文档，逐项检查以下质量门禁：

### 关键章节检查
- [ ] 前置条件：是否列出了所有运行时依赖（数据库版本、中间件版本、系统配置）
- [ ] 环境变量：是否列出了每个环境变量的名称、用途、示例值、是否必填
- [ ] 构建步骤：是否可直接复制执行，无需额外推断
- [ ] 部署步骤：是否区分了首次部署与升级部署
- [ ] 健康检查：是否定义了健康检查 URL、预期响应、超时时间
- [ ] 回滚方案：是否有明确的回滚步骤（不是简单写「回滚到上一版本」）
- [ ] 数据库迁移：如涉及 DB 变更，是否有迁移执行和回滚步骤
- [ ] 常见问题排查：是否有至少 3 个常见错误场景及解决方案

### 可执行性检查
- [ ] 所有命令是否完整可复制（无省略号 `...`、无占位符未说明）
- [ ] 端口号、域名、路径是否使用了变量或占位符并在前置条件中说明
- [ ] 步骤顺序是否合理（不会因顺序错误导致部署失败）

### 自动修复
- 缺失的健康检查：根据服务类型（HTTP/gRPC）自动补充标准健康检查配置
- 缺失的回滚方案：自动补充基于版本的回滚步骤模板
- 缺失的环境变量说明：从代码中扫描 `process.env`/`os.Getenv`/`System.getenv` 等，自动补充
- 模糊的操作步骤：改写为具体命令
- 缺失的常见问题：自动补充 3 个通用排查项（端口占用、权限不足、依赖不可达）
- 修复后在文档末尾追加审查记录：
  ```
  ## 自审记录
  - 审查时间：<ISO 8601>
  - 发现问题：X 项
  - 自动修复：X 项
  - 修复明细：
    - [已修复] <问题描述>
  ```

## 要求

<!-- @include templates/prompts/output-language.md -->
- 步骤要具体可执行，不要模糊描述
- 包含回滚方案
- 如需 Docker 部署，同时生成 Dockerfile 和 docker-compose.yml

目标: $ARGUMENTS

<!-- @include templates/prompts/state-update.md -->
<!-- @include templates/prompts/handoff.md -->