eliteforge-java-uml

EliteForge Java UML

目标

• 生成可落地、结构清晰、边界明确、关系准确的 Java 25 UML 类设计。
• 优先保证正确性和可实现性，宁可少画，不可错画。

Environment Variables

• ELITEFORGE_SKILL_JAVA_UML_PLANTUML_ASL_JAR [required] Absolute path to the ASL PlantUML jar used to render and validate generated UML SVG output.

执行顺序（每次都做）

1. 识别业务中的聚合根、核心对象、规则对象、持久化对象、查询职责组件、操作职责组件。
2. 区分分层：基础层采用 Controller、Service、Repository、Domain、Enums、External；Service 下游可按功能类型拆分子块（如存储/规则/缓存/网关），不限制为固定单一层次。
3. 识别闭集概念并优先建模为枚举（状态、类型、阶段、来源等）。
4. 为每个业务模块分配颜色，同模块统一同色系，不同模块区分色系。
5. 判断哪些对象需要审计字段，并补齐固定 6 个字段（见参考规则）。
6. 校验每条关系是否有落点：字段或方法签名（参数/返回值）。
7. 删除技术噪音节点：POJO 转换类（*Converter/*Assembler/*MapperStruct）与 MyBatis 技术类（*Mapper/*Example/*Criteria/SqlSession）不入图。
8. 校验查询职责组件是否满足分页约束（queryPage 或 queryByCursor）。
9. 校验表归属说明：关系型持久化模型的 Entity 节点必须明确写 表: xxx（复用同表可写 复用表: xxx）；Repository 节点不写表归属注释。
10. 校验 Controller 节点说明：必须标注接口前缀 接口前缀: /api/.../；职责拆分的 Controller 必须分别标注自己的前缀。
11. 先生成并写入 .puml 文件；信息不足时先写入可确定部分，再在图内注释不确定项。
12. 检查泛型写法：方法签名与字段类型中的泛型必须直接使用 <>；禁止出现 ~ 泛型和 </> 实体。
13. 按自检清单逐条检查后再给最终结果。

强制输出约束

• 仅生成 PlantUML 类图文件，源文件扩展名固定为 .puml。
• 必须先写入 UML 文件，再补充必要说明（路径/渲染结果）。
• 禁止为了“看起来完整”而臆造类、字段、方法、关系、枚举。
• 禁止绘制 Dto / Vo / ResVo 节点；它们只允许出现在方法签名中。
• 禁止绘制 Page / PageResult / PageResponse 等分页容器节点。
• 禁止体现 POJO 转换链路；禁止绘制 *Converter/*Assembler/*MapperStruct 节点和 toXxx/fromXxx 转换方法。
• 禁止绘制 MyBatis 技术类（*Mapper/*Example/*Criteria/SqlSession）与 XML 映射细节。
• 禁止无落点连线、禁止连线 label、禁止无必要噪音连线。
• 列表查询必须分页；禁止 findAll / selectAll / queryAll / listAll / loadAll。
• 关系型持久化模型的 Entity 节点说明必须标注表归属：表: xxx（可写 复用表: xxx）；Repository 节点禁止标注 表: / 复用表: / 无表:。
• Controller 节点说明必须标注接口前缀：接口前缀: /api/.../。
• 所有节点（类/接口/枚举）必须写类内说明：<<说明标题>> + 至少 1 行说明。
• 枚举只展示实例（常量），不展示成员变量和内部方法。
• 方法签名与字段类型中的泛型必须直接使用 <>；禁止出现 ~ 泛型和 </> 实体。
• 颜色必须按模块划分；禁止只按技术层固定上色而忽略模块边界。
• 不单独绘制 Persistence 层；Entity 归入 Repository 的功能子块，避免技术实现细节入图。
• 技能运行时必须先检测 ELITEFORGE_SKILL_JAVA_UML_PLANTUML_ASL_JAR 环境变量；未设置则直接结束，并提醒用户先配置。
• 只要新增或修改了 UML 内容，必须使用 ELITEFORGE_SKILL_JAVA_UML_PLANTUML_ASL_JAR 重新渲染成功，否则不输出最终结果。
• 最终产物只允许输出一个 *.puml 源文件与同级 *.svg，禁止额外生成 *.plantuml。
• 对话中不回显 UML 正文；仅返回输出文件路径、渲染结果与必要错误信息。

参考文件读取策略

• 处理普通 UML 设计请求时，先读 references/uml-core-rules.md。
• 用户强调布局、颜色、可读性、类内说明时，再读 references/plantuml-template.md。
• 用户要求“给我一个可直接改的模板/示例”时，读 references/plantuml-example-template.md。
• 用户担心渲染失败或版本兼容时，读 references/plantuml-validation.md。

输出风格基线

• 默认使用 top to bottom direction + skinparam linetype ortho。
• 先按模块上色，再在模块内组织分层节点；除非用户明确要求，避免使用外部 note。
• 枚举默认不连线，减少噪音。

输出模板

@startuml
top to bottom direction
skinparam linetype ortho

' 先放分层包，再放类定义与关系
' 信息不足时，用注释列出不确定项，仍保持 PlantUML 输出

@enduml

参考资料

• 通用 UML 规则与自检
• PlantUML 输出模板
• PlantUML 示例模板
• PlantUML 版本与校验