pdd-generate-spec

name	pdd-generate-spec
description	根据功能点矩阵生成开发规格与验收标准。当用户需要生成功能点技术规格、编写spec.md或checklist.md时调用。支持中文触发：生成规格、开发规格、技术规格、PDD规格、验收标准。

PDD-Generate Spec - 开发规格生成技能

核心概念

根据功能点矩阵和业务分析报告，为每个功能点生成详细的开发规格文档(spec.md)和验收标准(checklist.md)。

输入: feature-matrix.md(功能点矩阵) | 业务分析报告 | 输出: spec.md(开发规格) | checklist.md(验收标准) | 不负责: 代码实现/测试执行

规格文档模板

• spec.md 模板: 见 references/spec-template.md（接口定义/数据模型/业务逻辑/前端页面/权限安全/Options/路由/依赖，共9章）
• checklist.md 模板: 见 references/checklist-template.md（业务/技术/集成验收三部分）

生成流程

1. 读取功能点矩阵: 从 dev-specs/feature-matrix.md 读取功能点定义
2. 分析功能点详情: 提取功能描述|输入字段|输出信息|业务规则|状态转换|测试策略
3. 设计接口定义: RESTful规范|HTTP方法语义|URL命名|请求/响应格式|错误码体系
4. 设计数据模型: 实体识别|属性定义|关系映射|索引设计|审计字段(create_time/update_time/create_by/update_by/del_flag/status)
5. 定义业务逻辑: 核心流程|边界条件|异常处理|状态机转换
6. 设计前端页面: 页面结构|表单布局|列表展示|交互流程
7. 定义权限与安全: 接口权限|数据权限|输入校验|SQL注入防护
8. 编写验收标准: 业务场景覆盖|技术指标达标|集成测试通过
9. 输出规格文档: 保存到 dev-specs/FP-{序号}/spec.md 和 checklist.md

Guardrails / 质量护栏

必须遵守: 接口定义符合RESTful规范 | 数据模型包含审计字段 | 业务规则标注优先级 | 验收标准可测试可验证 | 外键字段定义前端组件类型(禁止UUID手动输入) | Options接口在Spec中声明 | 路由注册顺序遵守约定 | 枚举值用snake_case小写英文

避免事项: ❌ 接口路径不符RESTful | ❌ 数据模型缺审计字段 | ❌ 业务规则模糊 | ❌ 验收标准不可测试 | ❌ 外键字段用Input而非Select | ❌ Options路由在/{id}之后 | ❌ 枚举用大写/中文 | ❌ datetime声明为str

与其他技能协作

协作技能	协作方式	传入数据	期望输出
pdd-extract-features	Sequential	功能点矩阵	功能点详情
pdd-ba	Sequential	业务分析报告	用例/流程/状态
system-architect	Consultation	架构需求	架构建议
software-architect	Consultation	模块需求	模块设计
pdd-implement-feature	Sequential	spec.md + checklist.md	代码实现

人工审核规范

审核节点: 开发规格生成完成后需人工审核 审核内容: 接口设计合理性 | 数据模型完整性 | 业务逻辑正确性 | 验收标准完备性 审核粒度: 批量审核（快速浏览标志需详审项）| 关键功能点详细审核（P0优先级|复杂状态转换|外部系统集成|敏感数据） 输出文件: review-spec.md | 结果类型: passed / rejected / conditional

Iron Law / 铁律

1. 规格驱动实现: 生成的spec.md必须是后续代码实现的唯一依据，所有接口定义、数据模型、业务规则都必须在规格中明确声明，不得让实现者自行推断。
2. 验收标准可测试性: checklist.md中的每条验收标准都必须是客观的、可验证的，不得出现"界面美观""响应迅速"等主观描述。
3. 前后端一致性: 规格中的接口定义必须同时适用于后端实现和前端调用，前端API层应能直接基于规格生成。
4. 完整性与简洁性平衡: 规格必须足够详细以指导实现(不遗漏关键细节)，但也要避免过度详细导致维护成本过高。
5. 变更追溯性: 规格中每个决策(如选择某种数据结构、设计某个接口)都应有简要的理由说明或引用来源，便于后续审查和理解。

违规示例: ❌ 接口只写路径而未定义请求参数和响应结构 | ❌ 验收标准写"用户体验良好"而非具体指标 | ❌ 后端规格与前端实际调用字段名不一致 | ❌ 规格过于简略致实现者频繁询问 | ❌ 联合索引未说明查询场景 合规示例: ✅ 每个接口含完整请求/响应定义和错误码列表 | ✅ 验收标准明确"列表接口响应时间<500ms(1000条数据)" | ✅ 前后端使用同一份接口规格作为开发依据 | ✅ 关键决策有注释、常规内容用表格 | ✅ 索引设计附说明"支持按status+create_time的组合查询"

Rationalization / 理性化对照

完整对照表见 references/rationalization.md。核心要点：接口再简单也要定义完整请求/响应结构；每条验收标准必须量化或明确判定方法；规格生成时同步考虑前后端双向适用性；将"显而易见"的细节（尤其边界条件）显式写入规格；采用"概览+详细表格"分层策略。

Red Flags / 红旗警告

Layer 1: 输入检查

• INPUT-GS-001: 功能点矩阵为空或缺少功能点详情 → 🔴 终止并提示先完成功能点提取
• INPUT-GS-002: 业务分析报告缺少用例或状态定义 → 🔴 提示补充完整业务分析后再生成规格
• INPUT-GS-003: 功能点复杂度标记(P0/P1/P2)与实际描述不符 → 🟡 记录并标注偏差

Layer 2: 执行检查

• EXEC-GS-001: 接口定义缺少请求参数或响应结构 → 🔴 补充完整接口定义
• EXEC-GS-002: 数据模型缺少审计字段(create_time等)或主键 → 🔴 补充标准审计字段和主键
• EXEC-GS-003: 验收标准存在无法客观验证的条目 → 🟡 重写为可量化/可判定标准
• EXEC-GS-004: 规格业务规则与业务分析报告矛盾 → 🔴 以业务分析为准修正或记录冲突请用户确认
• EXEC-GS-005: 外键字段未定义前端组件类型(如department_id用Input) → 🔴 改为Select并声明Options API数据源
• EXEC-GS-006: 枚举值使用大写或中文编码 → 🟡 改为snake_case小写英文
• EXEC-GS-007: datetime字段在Pydantic Schema中声明为str → 🟡 改为datetime类型并添加序列化配置

Layer 3: 输出检查

• OUTPUT-GS-001: spec.md缺少必要章节(接口定义/数据模型/业务逻辑) → 🔴 补充缺失章节
• OUTPUT-GS-002: checklist.md验收标准少于5条或不足以覆盖主要功能 → 🔴 补充更完善的验收标准
• OUTPUT-GS-003: 规格保存路径不符合规范(不在dev-specs/FP-{序号}/下) → 🟡 移到正确目录
• OUTPUT-GS-004: spec.md缺少前端实现约定章节(第6章) → 🔴 补充前端组件映射和操作按钮矩阵
• OUTPUT-GS-005: spec.md缺少关联数据源章节(第7章) → 🔴 补充Options接口定义
• OUTPUT-GS-006: spec.md缺少依赖检查清单(第9章) → 🟡 补充前置依赖和后续依赖

处理流程: 🔴 CRITICAL → 立即停止，报告问题详情，等待指示 | 🟡 WARN → 记录警告到规格日志，尝试自动修复，在最终报告中标注 | 🔵 INFO → 记录信息，正常继续