033-architecture-diagrams

采用模块化、分步骤配置的 Java 图表生成器

通过模块化、分步骤的交互流程，生成全面的 Java 项目图表，涵盖 UML 时序图、UML 类图、C4 模型图、UML 状态机图、UML 部署图、ER（实体关系）图和有界上下文图，并使用 PlantUML 语法。这是一个交互式 SKILL。

此 Skill 涵盖哪些内容？

• 为应用程序工作流和 API 交互生成 UML 时序图
• 为包结构和类关系生成 UML 类图
• 生成 C4 模型图，包括 Context、Container 和 Component 图
• 为实体生命周期和业务工作流生成 UML 状态机图
• 生成 UML 部署图，涵盖运行时拓扑、节点、执行环境、已部署组件、数据存储、队列、外部系统和通信路径
• 使用 PlantUML Chen 表示法，根据 SQL 架构（DDL、迁移）生成 ER 图
• 为一个或多个代码仓库中的 DDD 上下文映射生成有界上下文图
• 所有图表类型的 PlantUML 语法
• 文件组织策略：单文件、分离文件，或与现有文档集成
• 使用 PlantUML 语法检查验证最终图表
• 使用可信的本地 PlantUML 安装或仓库认可的封装工具验证 PlantUML，并渲染为 PNG/SVG

约束

生成任何图表前，请确保项目通过验证。如果验证失败，请立即停止，直到解决所有验证错误后再继续。

• 强制要求：生成任何图表前，运行 ./mvnw validate 或 mvn validate
• 安全：如果验证失败，请立即停止，直到解决所有验证错误后再继续
• 读取图表参考资料前：先运行嵌入在此 SKILL.md 中的问题流程。逐一询问图表偏好问题，收集所选图表系列和输出偏好，然后仅阅读用户回答所选的实现参考资料
• C4 范围：C4 图表仅限 Context、Container 和 Component 图
• 供应链：生成的 PlantUML 图表必须仅使用可信的本地 include；C4 或图标库不得使用远程 !include URL
• 工具安全：仅使用可信的本地 PlantUML 工具或仓库认可的封装工具；不得在此 Skill 中拉取或运行远程容器镜像

何时使用此 Skill

• 生成 UML 图
• 创建时序图
• 创建类图
• 创建状态机图
• 创建部署图
• 创建 C4 图
• 生成 ER 图
• 创建有界上下文图
• 创建上下文映射图

工作流

1. 验证项目状态

生成任何图表前，运行 ./mvnw validate 或 mvn validate。

步骤约束：

• 如果验证失败，请停止并先解决错误

2. 在读取参考资料前询问图表评估问题

在读取任何图表系列实现参考资料前，运行此 XML 内嵌的问题流程。严格按照顺序逐一提问，每个问题都要等待用户回答，并记录所选图表系列、C4 范围、有界上下文的代码仓库范围、输出组织方式、文件格式和文档偏好，然后再继续。

重要：必须严格按照此处所示的顺序和措辞提问。向用户提出的第一个问题必须是“Question 1: What diagrams do you want to generate?”。在此之前不得提出其他问题。

图表选择

条件流程规则：

• 仅执行根据你在此处的选择而相关的图表生成步骤。
• 如果选择“Skip”，则不会生成任何图表。
• 每种图表类型都有各自的条件式后续问题。

---

问题 1：你想生成哪些图表？ 选项：

• UML 序列图
• UML 类图
• UML 状态机图
• C4 模型图（Context、Container、Component）
• UML 部署图
• ER 图（实体关系）
• 限界上下文图
• 所有图
• 跳过

---

问题 2：对于 UML 序列图，你想生成哪些类型？ 仅当你在问题 1 中选择了“UML 序列图”或“所有图”时，才询问此问题。

选项：

• 主要应用流程（用户旅程、身份验证、核心功能）
• API 交互（REST 端点、请求/响应模式）
• 复杂业务逻辑流程（多步骤流程、事务）
• 所有序列图类型
• 跳过

---

问题 3：对于 UML 类图，你想涵盖哪些范围？ 仅当你在问题 1 中选择了“UML 类图”或“所有图”时，才询问此问题。

选项：

• 所有包（完整项目结构）
• 仅核心业务逻辑包
• 指定包（我会说明具体包）
• 跳过

---

问题 4：对于 UML 类图，你偏好什么详细程度？ 仅当你在问题 1 中选择了“UML 类图”或“所有图”，且在问题 3 中未选择“跳过”时，才询问此问题。

选项：

• 高层级（仅包含类和关系）
• 详细（包含关键方法和属性）
• 完整详细（所有公共方法、属性和注解）

---

问题 5：对于 C4 模型图，你想生成哪些层级？ 仅当你在问题 1 中选择了“C4 模型图”或“所有图”时，才询问此问题。

选项：

• 完整 C4 模型（Context、Container、Component）
• 仅高层级图（Context 和 Container）
• 仅 Component 图
• 指定 C4 层级（Context、Container 和／或 Component）
• 跳过

---

问题 6：对于 UML 状态机图，你想生成哪些类型？ 仅当你在问题 1 中选择了“UML 状态机图”或“所有图”时，才询问此问题。

选项：

• 实体生命周期（领域对象状态转换，例如 Order、User、Document）
• 业务工作流（流程状态机，例如审批、付款、配送）
• 系统行为（组件运行状态，例如连接、作业、事务）
• 用户交互（UI 组件状态转换，例如表单、向导、对话框）
• 所有状态机类型
• 跳过

---

问题 7：对于 ER 图，你想涵盖哪些架构范围？ 仅当你在问题 1 中选择了“ER 图（实体关系）”或“所有图”时，才询问此问题。

选项：

• 完整数据库架构（所有表）
• 仅核心领域表
• 指定表（我会说明具体表）
• 跳过

---

问题 8：限界上下文图应呈现哪些仓库？ 仅当你在问题 1 中选择了“限界上下文图”或“所有图”时，才询问此问题。

选项：

• 仅当前仓库
• 一个或多个本地仓库路径（我会提供路径）
• 一个或多个仓库 URL（我会提供 URL）
• 指定名称的仓库列表（我会提供名称和上下文）
• 跳过

对于范围内的每个仓库，收集可获取的信息：仓库名称或路径、限界上下文、领域或子领域、所属团队、应用类型、自有数据存储、提供的接口、使用的接口以及已知关系。

---

问题 9：对于 UML 部署图，应优先使用哪些源材料？ 仅当你在问题 1 中选择了“UML 部署图”或“所有图”时，才询问此问题。

选项：

• 现有部署图图片或拓扑草图（我会提供图片）
• 系统描述文件（我会提供文件路径）
• 仓库文档、配置或部署描述符
• 询问我缺少的部署拓扑细节
• 跳过 当提供部署图像或系统描述文件时，请先将其用作素材，再提出后备问题。仅询问缺失或含糊的部署事实，例如参与者、服务、CI/CD 系统、运行时节点、执行环境、已部署的制品或组件、外部系统、数据存储、队列、协议、端口、关系，以及基础设施或网络边界。

---

问题 10：您希望如何组织生成的图表文件？

选项：

• 单个目录（所有图表都放在 /diagrams 文件夹中）
• 按类型组织（每种图表类型使用单独的文件夹）
• 按包/领域组织（将相关图表归在一起）
• 集成到现有文档结构中

---

问题 11：您希望图表使用哪种文件格式？

选项：

• 仅 PlantUML 源文件（.puml）
• PlantUML 和 Markdown 文档
• PlantUML 和生成的图像（需要 PlantUML 渲染）
• 集成到现有文档文件中

---

问题 12：您希望为图表附带说明文档吗？

选项：

• 是，为每张图表提供全面说明
• 是，提供简要描述和使用说明
• 否，仅提供图表
• 将说明集成到现有文档中

---

回答完所有适用的问题后，请确认所选项并将其映射到参考文档：

• 如果选择 UML 序列图，请阅读 references/033-architecture-diagrams-uml-sequence.md。
• 如果选择 UML 类图，请阅读 references/033-architecture-diagrams-uml-class.md。
• 如果选择 C4 模型图，请阅读 references/033-architecture-diagrams-c4.md。
• 如果选择 UML 状态机图，请阅读 references/033-architecture-diagrams-state-machine.md。
• 如果选择 UML 部署图，请阅读 references/033-architecture-diagrams-deployment.md。
• 如果选择 ER 图，请阅读 references/033-architecture-diagrams-er.md。
• 如果选择限界上下文图，请阅读 references/033-architecture-diagrams-bounded-context.md。
• 如果选择所有图表，请阅读全部七份专门介绍图表系列的参考文档。
• 如果某类图表选择跳过，则不要阅读该类图表的参考文档。
• 不要阅读未选择的图表系列参考文档。

3. 阅读所选参考文档并生成 PlantUML 图表

仅使用所选的专门参考文档、项目输入和仓库上下文，以 PlantUML 语法创建所需图表。

4. 验证并完成输出

在最终交付前，检查生成的图表是否语法正确，并与所选范围一致。

使用已安装的 PlantUML CLI 或仓库认可的包装器验证并渲染生成的 .puml 文件。如果无法使用 PlantUML，请报告缺少的可信工具并提供设置指导，而不要下载或运行远程执行制品。

验证 PlantUML 语法，但不生成图像：

plantuml -checkonly diagrams

渲染 PNG 图像：

plantuml -tpng diagrams

渲染 SVG 图像：

plantuml -tsvg diagrams

将命令指向包含生成图表的目录或 .puml 文件。验证期间不要拉取或运行外部容器镜像。

参考

有关详细指南、示例和限制，请参阅：

• references/033-architecture-diagrams-uml-sequence.md
• references/033-architecture-diagrams-uml-class.md
• references/033-architecture-diagrams-c4.md
• references/033-architecture-diagrams-state-machine.md
• references/033-architecture-diagrams-deployment.md
• references/033-architecture-diagrams-er.md
• references/033-architecture-diagrams-bounded-context.md