gen-design

# /gen-design - 系统设计技能 **技能 ID**: `gen-design` **技能名称**: 系统设计技能 **版本**: 1.4.0 **描述**: 基于领域知识库进行数据模型设计和集成设计，生成与 PRD 数据流对齐的设计文档 --- ## 触发条件 - `/gen-design` - `/design` - `生成设计文档` - `系统设计` ## 技能边界（防止误触发） - **本技能仅当**用户明确要「根据 PRD/需求生成系统设计文档」时触发。 - **不得在以下场景触发本技能**： - 用户要「分析现有代码库」→ 应使用 **analyze** - 用户要「从现有代码反推设计主线」→ 应使用 **analyze --phase=deep** - 若误触发：应说明「您当前意图是 XX，应使用 /analyze 或 /analyze --phase=deep」，并引导至正确技能。 --- ## 前置条件 - PRD 文档已生成，或用户已提供清晰的需求描述 - 领域知识库已准备就绪（`skills/libs/domain-knowledge/`） --- ## 核心增强：领域知识库驱动 本技能基于领域知识库进行增强，实现： 1. **数据模型设计** — 参考知识库中的核心实体关系、数据库表设计 2. **接口设计** — 参考知识库中的核心接口设计 3. **集成设计** — 参考知识库中的常见集成点 4. **非功能性需求** — 参考知识库中的约束条件和最佳实践 --- ## 技能行为 ### 阶段一：确认技术栈偏好 ``` 好的，让我了解一些设计相关的信息： 1. 技术栈确认 根据您的需求，推荐使用以下技术栈： **前端**：Vue 3 + Ant Design Vue **后端**：Spring Boot 3 + MyBatis-Plus 【如需要 AI 能力】LangChain4j + LangGraph4j 【如用户规模>10 万】Spring Cloud 微服务 是否采用此技术栈方案？ A) 采用推荐方案 B) 调整技术栈（请说明） C) 使用其他技术栈（请说明） 2. 预期用户规模？ A) 日活<1 万（单体架构） B) 日活 1-10 万（读写分离） C) 日活>10 万（微服务架构） 3. 部署环境？ A) 云服务器（阿里云/腾讯云） B) 容器化（K8s/Docker） C) 本地服务器 ``` ### 阶段二：设计方案呈现 ``` 基于您的需求和技术栈确认，我推荐以下架构方案： ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **推荐方案**（单体架构）： 【前端】 - 框架：Vue.js 3.x（组合式 API） - UI 库：Ant Design Vue 4.x - 状态管理：Pinia - 路由：Vue Router 4.x - HTTP 客户端：Axios 【后端】 - 框架：Spring Boot 3.x - ORM：MyBatis-Plus 3.5.x - 安全：Spring Security + JWT - 文档：Knife4j（Swagger 3） - 工具：Lombok, Hutool 【数据库】 - MySQL 8.0（主从复制，读写分离） - Redis 6.x（缓存热点数据） 【AI 能力】（如需要） - LangChain4j：大模型接入 - LangGraph4j：工作流编排 **架构特点**： - 前后端分离 - 读写分离（主从数据库） - Redis 缓存热点数据 - 适合日活 1-10 万规模 **优势**： - 技术栈成熟稳定，团队容易上手 - 开发效率高，支持快速迭代 - 生态完善，问题容易解决 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 是否采用推荐方案？确认后生成详细设计文档。 ``` ### 阶段三：数据模型设计（基于知识库） ``` 【数据模型设计增强】 基于领域知识库，设计数据模型： 1. 读取 PRD 中识别的领域 2. 加载对应领域知识库 3. 参考知识库中的「核心实体关系」 4. 参考知识库中的「数据库表设计参考」 5. 根据 PRD 功能需求调整 【实体关系设计】 从知识库提取核心实体： | 实体 | 来源知识库 | 核心属性 | 关联实体 | |------|-----------|---------|---------| | {实体1} | {领域} | {属性列表} | {关联实体} | | {实体2} | {领域} | {属性列表} | {关联实体} | 【表结构设计】 参考知识库中的数据库表设计，结合业务需求调整： - 表名规范 - 字段类型 - 索引设计 - 分库分表策略（如需要） ``` ### 阶段四：接口设计（基于知识库） ``` 【接口设计增强】 基于领域知识库，设计 API 接口： 1. 参考知识库中的「核心接口设计」 2. 参考知识库中的「常见集成点」 3. 根据 PRD 数据流设计接口调用链 【接口分类】 | 分类 | 来源知识库 | 接口示例 | |------|-----------|---------| | 核心业务接口 | {领域}知识库 | {接口列表} | | 集成接口 | 知识库集成点 | {接口列表} | | 管理接口 | 业务需求 | {接口列表} | 【接口规范】 参考知识库中的接口设计规范： - RESTful 风格 - 统一响应格式 - 异常处理规范 - 认证授权机制 ``` ### 阶段五：集成设计（基于知识库） ``` 【集成设计增强】 基于领域知识库，设计系统集成： 1. 参考知识库中的「常见集成点」 2. 根据 PRD 数据流设计集成方案 3. 定义集成契约 【集成点清单】 | 集成点 | 集成类型 | 来源知识库 | 数据内容 | 触发时机 | |--------|---------|-----------|---------|---------| | {集成点1} | API/消息队列 | {领域}知识库 | {数据} | {触发条件} | 【集成契约】 每个集成点定义： - 接口/消息格式 - 数据字段 - 调用方式 - 异常处理 - 重试机制 ``` ### 阶段六：生成设计文档 生成时**必须**同时填写「4. 数据流主线与集成点」节，不得留空。 ### 阶段七：数据流主线与集成点必填与自动补全 - **规则**：生成设计文档后必须检查「4. 数据流主线与集成点」是否已填写完整。 - **若 PRD 中已有「核心数据流与闭环」**：必须据此展开为本节的「数据流主线」与「集成点清单」。 - **若 PRD 中无或不足**：根据「3. 模块划分」与「5. 接口设计」**自动推断**数据流路径与集成点。 - **参考知识库**：从知识库「典型数据流骨架」提取集成点。 ### 阶段八：生成完成与下一步引导 ``` 正在生成 docs/design/YYYY-MM-DD-{project-name}-design.md... ✅ 设计文档已生成，包含： - 系统架构图 - 技术栈说明 - 模块划分（X 个模块） - **数据模型设计**（基于领域知识库） - **接口设计**（基于领域知识库） - **集成设计**（基于领域知识库） - 数据流主线与集成点清单（与 PRD 数据流对齐） - 部署方案 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 下一步（请先执行验证再拆任务）： 请执行以下命令完成数据流与闭环验证后，再执行 /gen-tasks： /validate docs/design/YYYY-MM-DD-{project-name}-design.md 验证完成后再执行：/gen-tasks ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **自动继续**：若平台支持技能链调用，用户回复「是」或未明确说「暂停」时，应**代为调用 validate**（传入本设计文档路径）。 ``` --- ## 领域知识库使用规范 ### 知识库使用方式 | 设计阶段 | 使用内容 | 用途 | |---------|---------|------| | 数据模型设计 | 核心实体关系、数据库表设计参考 | 设计表结构 | | 接口设计 | 核心接口设计 | 设计 API 接口 | | 集成设计 | 常见集成点 | 设计系统集成 | | 非功能性需求 | 约束条件、最佳实践 | 补充设计约束 | ### 领域识别与知识库加载 ``` 【领域识别流程】 1. 分析 PRD 文档，识别涉及的业务领域 - 关键词匹配：积分、订单、支付、用户等 - 功能模块分析 - 数据流涉及的外部系统 2. 加载对应领域知识库 - 路径：skills/libs/domain-knowledge/{domain}.md - 可用领域： * points（积分系统） * user-center（用户中心） * order（订单系统） * payment（支付系统） * ecommerce（电商通用） 3. 提取知识库核心内容 - 核心实体关系 - 典型数据流骨架 - 常见集成点 - 业务规则模板 ``` ### 数据模型设计规则 ``` 【设计流程】 1. 识别 PRD 涉及的领域 2. 加载对应领域知识库 3. 提取「核心实体列表」 4. 参考「实体关系图」 5. 参考「数据库表设计参考」 6. 根据业务需求调整 【调整规则】 - 删除不需要的实体 - 合并相似的实体 - 扩展实体的属性 - 调整实体关系 【命名规范】 参考知识库中的命名规范： - 表名：t_{模块}_{实体}，如 t_points_account - 字段名：下划线分隔 - 主键：id (BIGINT) - 外键：{关联实体}_id 【输出格式】 数据模型设计必须包含： 1. ER 图（Mermaid 格式） 2. 实体清单表格 3. 每个实体的详细字段表 4. 索引设计说明 5. 与知识库的对应关系说明 ``` ### 接口设计规则 ``` 【设计流程】 1. 分析 PRD 数据流 2. 参考「核心接口设计」 3. 设计接口调用链 4. 定义接口契约 【接口分类】 1. 业务接口（来自知识库） - CRUD 接口 - 业务操作接口 2. 集成接口（来自知识库集成点） - 上游系统对接 - 下游系统对接 3. 管理接口 - 配置管理 - 数据统计 【接口规范】 参考知识库中的接口设计规范： - RESTful 风格 - 统一响应格式 - 分页查询规范 - 批量操作规范 【输出格式】 接口设计必须包含： 1. API 规范说明（协议、认证、版本） 2. 统一响应格式示例 3. 接口清单表格（编号、名称、方法、路径） 4. 关键接口详细说明（请求/响应参数） 5. 与知识库的对应关系说明 ``` --- ## 集成设计规则 ``` 【设计流程】 1. 识别 PRD 中涉及的外部系统 2. 加载领域知识库「常见集成点」 3. 参考「典型数据流骨架」 4. 设计集成方案 5. 定义集成契约 【集成点分类】 1. 上游系统（触发本系统） - 用户系统：获取用户信息 - 订单系统：订单状态变更 - 支付系统：支付结果通知 2. 下游系统（本系统触发） - 消息通知：积分变动通知 - 风控系统：异常操作上报 - 数据分析：数据同步 3. 第三方服务 - 短信服务 - Push 服务 - 外部 API 【集成契约要素】 每个集成点必须定义： - 集成方式：API / 消息队列 / 数据库 - 数据格式：JSON / Protobuf / 其他 - 调用方式：同步 / 异步 - 超时设置 - 重试机制 - 异常处理 - 幂等性保证 【输出格式】 集成设计必须包含： 1. 集成点清单表格 2. 每个集成点的详细契约 3. 数据流与集成点的对应关系 4. 与知识库的对应关系说明 ``` --- ## 技术栈规范 ### 前端技术栈（默认推荐） ```yaml 框架： name: Vue.js version: 3.x 说明：组合式 API，TypeScript 支持 UI 组件库： name: Ant Design Vue version: 4.x 说明：企业级 UI 组件库 状态管理： name: Pinia version: latest 说明：Vue 3 官方推荐 路由： name: Vue Router version: 4.x HTTP 客户端： name: Axios version: latest ``` ### 后端技术栈（默认推荐） ```yaml 框架： name: Spring Boot version: 3.x ORM: name: MyBatis-Plus version: 3.5.x 安全： name: Spring Security version: 6.x 认证：JWT Token 文档： name: Knife4j version: 4.x 数据库： name: MySQL version: 8.0 缓存： name: Redis version: 6.x ``` ### AI 能力集成（如需要） ```yaml AI 框架： name: LangChain4j version: latest 工作流编排： name: LangGraph4j version: latest 支持的模型： - 通义千问 - 文心一言 - ChatGLM - Ollama ``` --- ## 架构方案库 本技能支持根据用户需求推荐合适的架构方案。详细的架构方案模板见 **[libs/architecture-options.md](../libs/architecture-options.md)**，包含： - 方案 A：经典单体架构 - 方案 A+：单体 + 读写分离 - 方案 B：Spring Cloud 微服务 - 方案 C：标准前后端分离 - 方案 D：Serverless 架构 - 方案 E：高并发架构 --- ## 架构选择决策树 ``` 需求分析 → 架构选择 1. 用户规模？ - <1 万 → 单体架构（Spring Boot） - 1-10 万 → 单体 + 读写分离 + Redis 缓存 - >10 万 → 微服务（Spring Cloud） 2. 是否需要 AI 能力？ - 是 → 集成 LangChain4j + LangGraph4j - 否 → 标准技术栈 3. 前端类型？ - 企业级/中后台 → Vue 3 + Ant Design Vue - C 端/H5 → Vue 3 + Vant - 复杂交互 → React + Ant Design 4. 特殊需求？ - 实时通信 → WebSocket + Redis Pub/Sub - 大数据检索 → Elasticsearch - 高并发 → Redis 集群 + 消息队列 ``` --- ## 输出文件 ``` docs/design/YYYY-MM-DD-{project-name}-design.md ``` **目录与写入**：写入前须确保 `docs/design/` 存在（空仓库时先创建 `docs` 与 `docs/design`），并将完整设计文档落盘，禁止仅对话展示。通用约定见 [SKILLS-FILE-OUTPUT.md](../SKILLS-FILE-OUTPUT.md)。 **前后端分离**：使用模板时须填写 **「1.4 仓库与代码目录结构」** 中的 `{frontendRoot}`、`{backendRoot}`（如 `frontend/`、`backend/`），供后续 `/gen-code` 将前后端代码分别写入对应根目录。 --- ## 示例对话 ### 示例：积分系统设计 ``` 用户：/gen-design AI: 好的，我将根据 PRD 文档进行系统设计。 检测到 PRD 涉及领域：积分系统、用户中心、订单 已加载对应领域知识库。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1. 技术栈确认 根据您的需求，推荐使用以下技术栈： **前端**：Vue 3 + Ant Design Vue **后端**：Spring Boot 3 + MyBatis-Plus **数据库**：MySQL 8.0 + Redis 是否采用此技术栈方案？ A) 采用推荐方案 B) 调整技术栈 2. 预期用户规模？ A) 日活<1 万 B) 日活 1-10 万 C) 日活>10 万 用户：1-A, 2-B AI: 基于您的需求和技术栈确认，我推荐以下架构方案： **推荐方案**（单体 + 读写分离）： 【架构特点】 - 前后端分离 - 读写分离（MySQL 主从） - Redis 缓存积分数据 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **数据模型设计**（基于领域知识库）： 从积分知识库提取核心实体： - PointsAccount（积分账户） - PointsRecord（积分流水） - PointsRule（积分规则） - PointsExchange（积分兑换记录） - PointsExpire（积分过期记录） 从用户中心知识库提取核心实体： - User（用户） - Role（角色） - Permission（权限） 【是否需要调整数据模型？】 A) 使用推荐模型 B) 需要调整（请说明） 用户：A AI: **接口设计**（基于领域知识库）： 从积分知识库提取核心接口： - 积分账户服务：getBalance, earnPoints, usePoints, freezePoints - 积分流水服务：queryRecords, createRecord - 积分规则服务：getRule, calculatePoints 集成接口（来自知识库集成点）： - 订单系统：消费返积分、积分抵扣、积分撤销 - 用户系统：获取用户信息 - 消息系统：积分变动通知 【是否需要调整接口设计？】 A) 使用推荐接口 B) 需要调整（请说明） 用户：A AI: 正在生成 docs/design/2026-03-02-points-system-design.md... ✅ 设计文档已生成，包含： - 系统架构图 - 技术栈说明 - 模块划分（3 个模块） - **数据模型设计**（7 张表，基于领域知识库） - **接口设计**（15 个 API，基于领域知识库） - **集成设计**（3 个集成点，基于领域知识库） - 数据流主线与集成点清单（与 PRD 数据流对齐） - 部署方案 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 下一步： 请执行以下命令完成数据流验证： /validate docs/design/2026-03-02-points-system-design.md 验证完成后再执行：/gen-tasks ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` --- ## 相关技能 - **gen-prd**: PRD 生成，本技能的前置技能 - **design-review**: 设计评审（可选），本技能产出后的质量加固 - **validate**: 设计验证（如 `--mode=dataflow`），本技能的后续验证 - **gen-coding-specs**: 固化技术栈与编码约定到 `docs/coding-specs/`，**强烈建议在 gen-tasks / gen-code 前**完成，与 [SKILL-VALUE-CHAIN.md](../SKILL-VALUE-CHAIN.md) 一致 - **contract-gen**: 契约生成（可选，契约驱动时），本技能的后续技能 - **gen-tasks**: 任务拆解，本技能的后续技能 --- ## 版本历史 | 版本 | 日期 | 变更说明 | |------|------|----------| | 1.4.0 | 2026-03-07 | 新增数据流标注、契约生成集成 | | 1.3.0 | 2026-03-05 | 新增功能单元设计 | | 1.2.0 | 2026-03-03 | 新增API规范设计 | | 1.1.0 | 2026-03-02 | 新增存量项目设计增强 | | 1.0.0 | 2026-03-01 | 初始版本 | --- *本技能是 AI Speckits 技能体系的系统设计阶段，基于领域知识库增强。*