pdlc-design

name	pdlc-design
description	创建技术设计文档（自动生成 + 自检 + handoff）
argument-hint	<功能ID | 功能描述>
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
layer	2
stage	design
produces	["docs/02_design/<subsystem>/<feature-id>-design.md"]
requires	["docs/01_requirements/prd/"]
next_step	pdlc-tdd
terminal_state	design_done

创建设计文档

根据已有的需求文档，在 docs/02_design/ 对应子目录下创建技术设计文档。

输入解析

从 $ARGUMENTS 中判断输入类型：

• 文件路径（以 /、./ 开头，或以 .md、.txt、.pdf 结尾，或实际存在的文件）：直接读取该文件作为需求来源，跳过 PRD 搜索
• 功能名关键词（默认）：按下方守卫检查搜索 PRD

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

1. 若输入为文件路径，直接读取文件内容作为需求，提取功能名和功能ID（如有），跳到步骤 4
2. 从用户输入中提取功能名称关键词
3. 在 docs/01_requirements/prd/ 目录下搜索包含该关键词的 PRD 文档
   • 匹配新格式：F<日期>-<编号>-*<关键词>*-prd.md
   • 匹配旧格式：YYYYMMDD-*<关键词>*-prd.md
   • 同时检查文件内容中是否包含该关键词
4. 未找到 → 输出以下信息后立即停止，不继续执行：

   ⛔ PDLC 守卫：未找到与「<功能名>」相关的 PRD 文档。
   设计文档必须基于已有的 PRD。请先运行：
   👉 /pdlc-prd <需求描述>
   

5. 找到 → 提取功能ID（如 F20260326-090000），读取该 PRD 内容，继续执行

输出位置

• API 设计 → docs/02_design/api/
• 架构设计 → docs/02_design/architecture/
• 数据库设计 → docs/02_design/database/

要求

1. 先阅读找到的 PRD 文档，全面理解需求
2. 参考 templates/api-design-template.md 获取 API 设计模板格式
3. 参考 docs/00_standards/ 目录了解项目规范（未命中 → 提示 consider /pdlc-standard add <category>/<topic>）
4. 文件名格式: <功能ID>-<功能名>-<类型>.md（如 F20260326-090000-user-auth-api.md），类型可以是 api / arch / db
   • 若 PRD 为旧格式无功能ID，则使用旧格式 YYYYMMDD-<功能名>-<类型>.md
5. 文档顶部必须包含 PDLC 追溯头：

   <!-- PDLC-TRACE -->
   <!-- 功能ID: F20260326-090000 -->
   <!-- 功能名称: user-auth -->
   <!-- 阶段: 设计 -->
   <!-- 前置文档: docs/01_requirements/prd/F20260326-090000-user-auth-prd.md -->
   

7. 必须包含：概述、接口/架构/表结构定义、错误码/异常处理、数据模型

8. API 设计需遵循 RESTful 规范，统一响应格式 { code, message, data }

9. 设计文档自审与自动修复（每份设计文档创建后立即执行，不可跳过）：

   • 重新阅读刚创建的设计文档，对照 PRD 逐项检查以下质量门禁：

   PRD 一致性检查：

   • PRD 中每条 P0/P1 功能是否都有对应的设计覆盖（接口/表结构/架构组件）
   • 接口的入参/出参是否与 PRD 描述的功能行为一致
   • 错误码是否覆盖了 PRD 中列出的异常场景

   API 设计检查（如有 API 文档）：

   • 接口 URL 命名是否遵循 RESTful 规范（名词复数、层级清晰）
   • 请求/响应结构是否完整（无缺失字段）
   • 统一响应格式 { code, message, data } 是否一致执行
   • 分页接口是否有 page/pageSize/total 参数
   • 鉴权方式是否明确说明

   数据库设计检查（如有 DB 文档）：

   • 每张表是否有主键定义
   • 外键关系是否与 ER 图一致
   • 常用查询字段是否有索引设计
   • 是否有 created_at、updated_at 等审计字段
   • 迁移 DDL 是否完整可执行

   跨文档一致性检查（如同时有 API + DB 文档）：

   • API 响应字段是否与数据库字段对应（字段名、类型）
   • API 的查询/筛选参数是否有对应的数据库索引支撑

   自动修复：

   • PRD 功能遗漏：自动补充对应的接口/表设计
   • 缺失的错误码：根据接口行为自动补充常见错误码（400/401/403/404/409/500）
   • 缺失的索引：根据查询模式自动补充索引设计
   • 缺失的审计字段：自动添加 created_at、updated_at
   • 缺失的分页参数：自动补充列表接口的分页设计
   • 修复后在文档末尾追加审查记录：

     ## 自审记录
     - 审查时间：<ISO 8601>
     - 对照 PRD：<PRD 文件路径>
     - 发现问题：X 项
     - 自动修复：X 项
     - 修复明细：
       - [已修复] <问题描述>
     

10. 创建完成后，提示用户下一步是编写测试用例（/pdlc-tdd <功能名>）

设计目标: $ARGUMENTS