/pdlc-deploy

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 --> <!-- @include templates/prompts/noninteractive.md -->

> ⛔ **部署面向生产、不可逆·外发**：真实执行部署属破坏性范畴。**`--autonomous` 对涉及真实部署动作的环节无效**——仍必须人工显式确认。本命令默认只产出部署**文档**，不代表授权自动上线。

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

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

1. 从用户输入中提取服务/功能名称关键词 2. 在 `docs/07_reviews/code/` 目录下搜索包含该关键词的评审记录

• 匹配新格式：`F<日期>-<编号>-*<关键词>*-review.md`
• 匹配旧格式：`YYYYMMDD-*<关键词>*-review.md`
• 同时检查文件内容中是否包含该关键词

3. **未找到评审记录** → 输出以下信息后**立即停止，不继续执行**：

   ⛔ PDLC 守卫：未找到与「<功能名>」相关的评审记录。
   部署文档必须基于已完成评审的代码。请先运行：
   👉 /pdlc-review <评审目标>

4. **找到** → 提取功能ID（如 `F20260326-090000`），读取评审记录内容，继续执行

工作流程

1. 阅读目标服务/应用的 README.md 和技术栈信息 2. 阅读 `docs/02_design/architecture/` 下的架构设计文档（如有） 3. 阅读评审记录，确认功能状态 4. **【必须创建文件】** 在 `docs/05_deployment/guides/` 下创建部署手册

• **使用模板**: `templates/deploy-doc-template.md`（结构完整、章节齐全）
• **文件名格式**: `<功能ID>-<功能名>-deploy.md`（如 `F20260326-090000-user-auth-deploy.md`）
• 若无功能ID，则使用旧格式 `YYYYMMDD-<服务名>-deploy.md`
• **文档顶部必须包含 PDLC 追溯头**：

     <!-- PDLC-TRACE -->
     <!-- 功能ID: F20260326-090000 -->
     <!-- 功能名称: user-auth -->
     <!-- 阶段: 部署 -->
     <!-- 前置文档: docs/07_reviews/code/F20260326-090000-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 -->