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 版本与校验

PlantUML 示例模板（单层 package，功能块清晰，不体现 POJO 转换与 MyBatis 技术类）

@startuml
top to bottom direction
skinparam linetype ortho

package "Controller" #E3F2FD {
  class ExtensionManageController #E3F2FD {
    <<管理入口>>
    负责扩展新增、发布、下线请求边界
    接口前缀: /api/extension/

    --
    - ExtensionWriteService extensionWriteService
    --
    + ResVo<ExtensionVo> create(ExtensionCreateDto dto)
    + ResVo<ExtensionVo> publish(ExtensionPublishDto dto)
    + ResVo<ExtensionVo> disable(ExtensionDisableDto dto)
  }

  class ExtensionQueryController #E3F2FD {
    <<查询入口>>
    负责扩展详情与分页查询边界
    接口前缀: /api/extension/query/

    --
    - ExtensionQueryService extensionQueryService
    --
    + ResVo<ExtensionDetailVo> queryDetail(ExtensionDetailDto dto)
    + ResVo<PageResult<ExtensionVo>> queryPage(ExtensionPageDto dto)
  }
}

package "Service" #E8F5E9 {
  interface ExtensionWriteService #E8F5E9 {
    <<写职责>>
    编排扩展变更流程

    --
    + ExtensionVo create(ExtensionCreateDto dto)
    + ExtensionVo publish(ExtensionPublishDto dto)
    + ExtensionVo disable(ExtensionDisableDto dto)
  }

  class ExtensionWriteServiceImpl #E8F5E9 {
    <<写职责实现>>
    协调存储、规则、缓存和通知网关

    --
    - ExtensionStoreRepository extensionStoreRepository
    - VersionRuleRepository versionRuleRepository
    - ExtensionCacheRepository extensionCacheRepository
    - ExtensionNotifyGatewayRepository extensionNotifyGatewayRepository
    - ExtensionRule extensionRule
    --
    + ExtensionVo create(ExtensionCreateDto dto)
    + ExtensionVo publish(ExtensionPublishDto dto)
    + ExtensionVo disable(ExtensionDisableDto dto)
  }

  interface ExtensionQueryService #E8F5E9 {
    <<读职责>>
    提供扩展详情与分页查询能力

    --
    + ExtensionDetailVo queryDetail(ExtensionDetailDto dto)
    + PageResult<ExtensionVo> queryPage(ExtensionPageDto dto)
  }

  class ExtensionQueryServiceImpl #E8F5E9 {
    <<读职责实现>>
    协调存储与缓存读取扩展信息

    --
    - ExtensionStoreRepository extensionStoreRepository
    - ExtensionCacheRepository extensionCacheRepository
    --
    + ExtensionDetailVo queryDetail(ExtensionDetailDto dto)
    + PageResult<ExtensionVo> queryPage(ExtensionPageDto dto)
  }
}

package "Repository" #FFF3E0 {
  interface ExtensionStoreRepository #FFF3E0 {
    <<存储仓储>>
    负责扩展数据持久化读写

    --
    + Optional<ExtensionEntity> findById(Long id)
    + boolean existsByCode(String code)
    + PageResult<ExtensionEntity> queryPage(ExtensionPageDto dto)
    + ExtensionEntity save(ExtensionEntity entity)
  }

  class ExtensionStoreRepositoryImpl #FFF3E0 {
    <<存储实现>>
    实现扩展存储访问

    --
    + Optional<ExtensionEntity> findById(Long id)
    + boolean existsByCode(String code)
    + PageResult<ExtensionEntity> queryPage(ExtensionPageDto dto)
    + ExtensionEntity save(ExtensionEntity entity)
  }

  interface VersionRuleRepository #FFF3E0 {
    <<规则仓储>>
    提供版本匹配规则读取能力

    --
    + Optional<VersionRuleEntity> findByRange(String versionRange)
  }

  interface ExtensionCacheRepository #FFF3E0 {
    <<缓存仓储>>
    负责扩展缓存读写与失效
    载体: Redis key=ext:snapshot:{code}

    --
    + Optional<ExtensionSnapshot> getByCode(String code)
    + void put(ExtensionSnapshot snapshot)
    + void evictByCode(String code)
  }

  interface ExtensionNotifyGatewayRepository #FFF3E0 {
    <<通知网关仓储>>
    负责扩展变更通知下游系统
    通道: 外部通知 API

    --
    + void notifyChanged(ExtensionChangeEvent event)
  }

  class ExtensionNotifyGatewayRepositoryImpl #FFF3E0 {
    <<通知网关实现>>
    通过外部客户端发送变更通知
    通道: 外部通知 API

    --
    - ExtensionNotifyClient extensionNotifyClient
    --
    + void notifyChanged(ExtensionChangeEvent event)
  }

  class ExtensionEntity #FFF3E0 {
    <<持久化模型>>
    映射扩展数据表结构
    表: t_extension

    --
    - Long id
    - String code
    - String name
    - ExtensionStatus status
    - LocalDateTime createTime
    - LocalDateTime updateTime
    - String createBy
    - String createName
    - String updateBy
    - String updateName
  }

  class VersionRuleEntity #FFF3E0 {
    <<规则持久化模型>>
    映射版本匹配规则表结构
    表: t_extension_version_rule

    --
    - Long id
    - String versionRange
  }
}

package "Domain" #F3E5F5 {
  class ExtensionRule #F3E5F5 {
    <<业务规则>>
    定义扩展状态流转约束

    --
    - ExtensionStatus status
    --
    + boolean canPublish()
    + boolean canDisable()
  }

  class ExtensionSnapshot #F3E5F5 {
    <<快照对象>>
    表达缓存中的扩展视图数据

    --
    - String code
    - String name
    - ExtensionStatus status
  }

  class ExtensionChangeEvent #F3E5F5 {
    <<变更事件>>
    表达扩展状态变更事件

    --
    - String code
    - ExtensionStatus status
    - ChannelType channelType
  }
}

package "Enums" #f0edc1 {
  enum ExtensionStatus #f0edc1 {
    <<状态枚举>>
    标识扩展生命周期状态

    DRAFT(0, "ext.status.draft")  草稿
    PUBLISHED(1, "ext.status.published")  已发布
    DISABLED(2, "ext.status.disabled")  已停用
  }

  enum ChannelType #f0edc1 {
    <<渠道枚举>>
    标识扩展通知渠道

    MQ(1, "ext.channel.mq")  消息队列
    HTTP(2, "ext.channel.http")  HTTP 回调
  }
}

package "External" #FFFDE7 {
  interface ExtensionNotifyClient #FFFDE7 {
    <<外部客户端>>
    连接下游通知系统

    --
    + void send(ExtensionChangeEvent event)
  }
}

ExtensionManageController -down-> ExtensionWriteService
ExtensionQueryController -down-> ExtensionQueryService
ExtensionWriteServiceImpl ..|> ExtensionWriteService
ExtensionQueryServiceImpl ..|> ExtensionQueryService

ExtensionWriteServiceImpl -down-> ExtensionStoreRepository
ExtensionWriteServiceImpl -down-> VersionRuleRepository
ExtensionWriteServiceImpl -down-> ExtensionCacheRepository
ExtensionWriteServiceImpl -down-> ExtensionNotifyGatewayRepository
ExtensionWriteServiceImpl -down-> ExtensionRule

ExtensionQueryServiceImpl -down-> ExtensionStoreRepository
ExtensionQueryServiceImpl -down-> ExtensionCacheRepository

ExtensionStoreRepositoryImpl ..|> ExtensionStoreRepository
ExtensionNotifyGatewayRepositoryImpl ..|> ExtensionNotifyGatewayRepository
ExtensionNotifyGatewayRepositoryImpl -down-> ExtensionNotifyClient

VersionRuleRepository ..> VersionRuleEntity
ExtensionCacheRepository ..> ExtensionSnapshot
ExtensionNotifyGatewayRepository ..> ExtensionChangeEvent

' 不确定项示例：
' 1) 是否需要按渠道拆分多个通知网关实现
' 2) queryPage 是否需要补充 queryByCursor

@enduml

PlantUML 输出模板

1. 布局与线型

@startuml
top to bottom direction
skinparam linetype ortho
@enduml

需要稳定布局时，优先使用方向约束连线（例如 -down->）。

2. 模块配色策略（优先）

先按业务模块分配颜色，再组织模块内节点。

推荐模块色板（按模块编号循环使用）：

• Module-1：#E3F2FD
• Module-2：#E8F5E9
• Module-3：#FFF3E0
• Module-4：#F3E5F5
• Module-5：#FFFDE7
• Module-6：#f0edc1

示例：

package "配置模块" #E3F2FD {
  class ConfigController #E3F2FD
  class ConfigService #E3F2FD
}

package "策略模块" #E8F5E9 {
  class PolicyController #E8F5E9
  class PolicyService #E8F5E9
}

只有单模块时，可使用单色系并在包内按职责分组。

3. 类内说明统一写法

class ConfigController #E3F2FD {
  <<说明标题>>
  说明内容第一行
  说明内容第二行
  接口前缀: /api/config/

  --
  - ConfigService configService
  --
  + ResVo<ConfigVo> create(ConfigCreateDto dto)
}

Entity 表归属说明补充（强制）：

interface OrderRepository #FFF3E0 {
  <<订单仓储>>
  负责订单持久化读写

  --
  + Optional<OrderEntity> findById(Long id)
  + PageResult<OrderEntity> queryPage(OrderPageDto dto)
}

class OrderEntity #FFF3E0 {
  <<订单持久化模型>>
  映射订单表结构
  表: t_order

  --
  - Long id
}

interface OrderCacheRepository #FFF3E0 {
  <<订单缓存仓储>>
  负责订单缓存读写
  载体: Redis key=order:{id}

  --
  + Optional<OrderSnapshot> getById(Long id)
}

规则：

1. 说明写在节点内部顶部。 2. 说明区、字段区、方法区使用 -- 分隔。 3. 非必要不使用外部 note。 4. 每个节点（类/接口/枚举）都必须有说明块。 5. 关系型 Entity 必须包含 表: xxx 或 复用表: xxx。 6. Repository 节点不写 表: / 复用表: / 无表:；非表仓储如需补充载体，直接写普通说明文本即可。 7. Controller 节点说明必须包含接口前缀，例如：接口前缀: /api/config/。

4. 枚举写法

enum ConfigStatus #f0edc1 {
  <<状态说明>>
  ENABLED(1, "cfg.status.enabled")  启用
  DISABLED(0, "cfg.status.disabled")  禁用
}

规则：

1. 枚举只展示实例（常量），不展示成员变量与内部方法。 2. 枚举实例推荐显式绑定字段值与语义说明。 3. 默认不为枚举连线；除非用户明确要求且有落点。

5. 关系表达要求

• 连线必须有字段或方法签名落点。
• 禁止给连线添加 label。
• 禁止无落点关系。
• 关系类型必须使用：关联/聚合/组合/继承/实现/依赖（对应线型见规则）。

5.1 连线约束（6 种关系）

@startuml
class OrderService
class Order
class OrderItem
class OrderRequest
class BaseService
interface OrderGateway
class OrderGatewayImpl

' 关联 Association（实线）
OrderService --> Order

' 聚合 Aggregation（空心菱形）
Order o-- OrderItem

' 组合 Composition（实心菱形）
Order *-- OrderRequest

' 继承 Inheritance（空心三角箭头）
BaseService <|-- OrderService

' 实现 Realization（虚线空心三角箭头）
OrderGateway <|.. OrderGatewayImpl

' 依赖 Dependency（虚线箭头）
OrderService ..> OrderGateway
@enduml

5.2 泛型展示约束

方法签名和字段类型中的泛型，直接使用 <>：

class UserGroup {
  <<说明>>
  users: List<User>

  --
  - List<User> users
}

若出现 ~ 泛型（例如 Map~String, Role~）或 </> 实体，必须先重写为直接 <> 再渲染。

6. 信息不足时的写法

在 UML 文件内容内追加注释，保持可直接渲染：

' 不确定项：
' 1) 是否需要 Cursor 分页
' 2) 是否拆分读写 Service

PlantUML 版本与校验

1. 是否需要限定版本

建议：不在技能里硬编码“唯一版本”，而是要求固定到团队已验证的版本并提供校验方式。 原因：

• PlantUML 按年版本号滚动，更新频繁。
• 不同发行包（GPL/LGPL/ASL 等）特性与依赖不同。
• 只要输出语法在本地 jar 可通过渲染，技能输出就可用。

2. 最小校验（必须通过）

使用你本地的 ASL jar 做一次最小渲染确认即可。 要求先配置环境变量 ELITEFORGE_SKILL_JAVA_UML_PLANTUML_ASL_JAR 指向 ASL jar 的绝对路径。

test -n "${ELITEFORGE_SKILL_JAVA_UML_PLANTUML_ASL_JAR}" && java -jar "${ELITEFORGE_SKILL_JAVA_UML_PLANTUML_ASL_JAR}" -version

cat <<'EOF' > /tmp/uml-smoke.puml
@startuml
top to bottom direction
skinparam linetype ortho

class HealthCheck {
  <<说明>>
  用于验证 PlantUML 渲染是否可用

  --
  - String name  名称
  --
  + String ping()
}

enum HealthStatus {
  <<状态枚举>>
  OK(1, "health.ok")  正常
  FAIL(0, "health.fail")  异常
}
@enduml
EOF

java -jar "${ELITEFORGE_SKILL_JAVA_UML_PLANTUML_ASL_JAR}" -tsvg /tmp/uml-smoke.puml -o /tmp
ls -la /tmp/uml-smoke.svg

通过标准：

• java -jar ... -version 能输出版本信息。
• 渲染后 /tmp/uml-smoke.svg 存在且非 0 字节。

3. 常见失败点（只提示，不强行修复）

• 本地 jar 不是 ASL 版本但期望 ASL 特性。
• Graphviz 缺失导致复杂布局失败（类图通常可不依赖 Graphviz，但部分布局可能受影响）。
• PlantUML 版本过旧导致新语法不可用。

4. 技能执行时的要求

技能运行时必须先检测 ELITEFORGE_SKILL_JAVA_UML_PLANTUML_ASL_JAR 环境变量；未设置则直接结束并提醒用户先配置。 只要新增或修改了 UML 内容，必须执行渲染命令并确认 SVG 产物生成成功。 校验渲染可以在 /tmp 下进行；最终产物只允许输出一个 *.puml 与同级 *.svg，禁止额外 *.plantuml。 对话中不回显 UML 正文，只返回文件路径、渲染状态和错误信息。 渲染前必须检查并禁止 ~ 泛型写法与 </> 实体写法，检测到后先改为直接 <> 泛型再渲染。 可使用：

rg -n '(Map|List|Optional|Set)~[^~]+~|&lt;|&gt;' <your-file>.puml && exit 1 || true
[ "$(find <output-dir> -maxdepth 1 -name '*.puml' | wc -l | tr -d ' ')" = "1" ] || exit 1
test -z "$(find <output-dir> -maxdepth 1 -name '*.plantuml' -print -quit)" || exit 1

如果用户提到渲染失败或版本不一致，在环境变量已设置前提下执行最小校验。 校验失败时只给出失败信息与建议升级/切换版本，不强行猜测修复方案。

Java 25 UML 通用规则

1. 最高优先级规则

1. 必须先产出 UML 文件，再补充必要说明（路径/渲染结果）。 2. 仅生成 PlantUML 类图文件，源文件扩展名固定为 .puml。 3. 信息不足时，先输出“当前可确定部分”的 UML。 4. 宁可少画，不可错画。 5. 禁止臆造类、字段、方法、关系或枚举。 6. 关系必须能落到字段、方法参数或方法返回值。 7. 查询职责组件只要有列表查询，必须提供分页查询接口。

2. 总体设计原则

• 按 JDK 25 设计习惯建模。
• 满足高内聚、低耦合、单一职责、开闭原则、可测试、可维护。
• 禁止“大而全” Controller 或 Service。
• 操作职责与规则职责分离。
• 输出必须可真实落地实现。

3. 节点与命名规则

允许绘制节点

• 接口
• 实现类
• 领域类
• Record
• Entity
• 枚举

禁止绘制节点

• Dto
• Vo
• ResVo
• Page / PageResult / PageResponse 等分页容器节点
• *Converter / *Assembler / *MapperStruct 等 POJO 转换类节点
• *Mapper / *Example / *Criteria / SqlSession 等 MyBatis 技术类节点

说明：Dto / Vo / ResVo 仅允许出现在方法签名中。

POJO 命名约束

允许后缀：

• Dto
• Vo
• Entity
• Record
• 无后缀领域类

禁止后缀：

• DO
• PO
• BO
• AO
• Query
• Param
• Form
• Request
• Response
• Resp

补充约束：

1. 请求语义统一归并到 Dto。 2. 响应语义统一归并到 Vo。 3. Controller 层统一返回 ResVo<T>。 4. Service 层只能返回 Vo 或 Dto。 5. 不体现 DTO/VO/Entity 等 POJO 转换链路，不绘制 toXxx/fromXxx 转换方法。

4. 审计字段规则

需要审计信息的对象，必须包含且仅按以下字段名与类型建模：

• LocalDateTime createTime
• LocalDateTime updateTime
• String createBy
• String createName
• String updateBy
• String updateName

禁止修改字段名、替换类型、新增同义审计字段。

5. 枚举建模规则

以下闭集概念优先建模为枚举，不用 String / Integer：

• 状态
• 类型
• 阶段
• 审核结果
• 操作类型
• 来源类型
• 渠道类型
• 启用/禁用标识
• 生命周期阶段
• 业务分类

禁止出现：

• String status
• Integer type
• int stateCode
• 魔法值字符串/数字
• 未约束常量类

枚举输出补充约束（强制）：

1. 枚举只展示枚举实例（常量），不展示成员变量与内部方法。 2. 枚举实例必须给出明确含义（可带值与说明）。 3. 默认不为枚举画任何连线；除非用户明确要求且关系有字段/方法落点。

6. 关系建模规则

关系语义（必须遵守）

• Association：实线，表示类之间关系
• Aggregation：空心菱形，表示整体-部分关系
• Composition：实心菱形，表示强整体-部分关系
• Inheritance：空心三角箭头，表示 is-a 关系
• Realization：虚线空心三角箭头，表示接口实现
• Dependency：虚线箭头，表示使用关系

落点规则

• 稳定结构关系：用成员变量体现。
• 临时协作关系：用方法参数或返回值体现。

判断标准：

• 长期持有、反复使用、属于对象结构：成员变量。
• 单次调用、局部流程、临时协作：方法签名。

禁止事项：

1. 关系没有字段或方法签名支撑时，禁止连线。 2. 禁止给连线加 label。 3. 禁止为“图完整”增加无必要连线。 4. 枚举默认可不连线。 5. 外部类关系必须落地在“外部类”分层内（见下）。

泛型展示规则（必须）

泛型在 UML 源中必须直接使用尖括号：

1. 方法签名与字段类型中的泛型必须写成 Map<String, Role>、ResVo<ExtensionVo> 这类 <> 形式。 2. 禁止输出 Map~...~ / List~...~ / Optional~...~。 3. 禁止输出 < / > 实体写法。

7. 分层建模规则

优先按以下层次组织：

• Controller
• Service
• Repository
• Domain
• Enums
• External

说明：

• 以上是基础分层，不是固定上限。
• Service 下游允许按功能类型拆分子块（例如：存储、规则、缓存、网关）。
• 不单独绘制 Persistence 层。
• 示例图优先使用单层 package，避免不必要 package 嵌套。

关键原则：

• Entity 是持久化模型，不属于 Domain。
• Domain 只表达业务语义对象/结果。
• 不把持久化结构混入领域对象。
• Entity 放入 Repository 的功能子块。
• 不绘制 POJO 转换节点（*Converter/*Assembler/*MapperStruct）。
• 不绘制 MyBatis 技术节点（*Mapper/*Example/*Criteria/SqlSession）和 XML 映射细节。
• 所有外部类（第三方库/框架类型、通用结果容器、JDK 类型除外）必须放入 External 分层并单独绘制。

Domain 层细分规则（必须，贫血模型友好）

当 Domain 规模较大时，必须按业务逻辑拆分为多个清晰的子块，避免单一大块。 不要求使用 DDD 聚合等术语，仅需按业务场景/流程/模块边界划分。

拆分原则：

1. 先按业务流程或功能模块聚类，再按职责细分。 2. 不能为了“整齐”硬拆；拆分必须有业务语义边界。 3. 每个子块仍需遵守“类内说明 + 关系落点”规则。

8. Repository / 查询规则

查询职责组件（Repository / Service / Controller）只要有列表查询，必须提供分页接口。

允许能力：

• 按 ID 查询
• 按唯一键查询
• exists 查询
• count 查询
• 条件分页查询
• 游标分页查询

禁止方法：

• findAll()
• selectAll()
• queryAll()
• listAll()
• loadAll()

列表查询方法名必须体现分页语义，例如：

• queryPage
• queryByCursor

查询条件统一收敛到一个 Dto，禁止参数分散重复。

Entity 表归属说明（强制）

1. 每个关系型持久化 Entity 节点的说明区必须显式标注表归属。 2. 关系型持久化 Entity 必须写：表: <table_name>；若多个 Entity 复用同一表，明确写“复用表: <table_name>”。 3. 一对多表场景可写：表: t_order, t_order_item。 4. Repository 节点禁止写 表: / 复用表: / 无表:；如需补充缓存键空间、外部 API、消息主题等载体信息，使用普通说明文本即可。 5. 禁止省略 Entity 表归属说明，否则视为不合格 UML。

9. Controller / Service 规则

Controller

1. 负责输入输出边界，不承担复杂编排。 2. 管理入口与运行时读取入口职责差异明显时可拆分。 3. Controller 节点说明必须标注接口前缀，格式：接口前缀: /api/.../。

Service

1. 按职责拆分，不机械拆分类数量。 2. 模块简单可单 Service。 3. 管理/解析或读/写职责差异明显时可拆分。 4. 实现类不机械重复接口已定义方法，只保留必要新增成员和方法。

create / update / save

1. 明确区分新增与修改时优先 create(...) + update(...)。 2. 语义是幂等保存时才使用 save(...)。 3. 用户已要求拆分 create/update 后，不保留单一 save。

10. 节点说明与模块配色规则

节点说明（强制）

1. 每个节点（类、接口、枚举）都必须有内嵌说明块。 2. 说明块位于节点顶部，格式：<<说明标题>> + 至少 1 行说明内容。 3. 禁止只写字段和方法而不写说明。 4. Controller 说明块必须包含接口前缀行（接口前缀: /api/.../）。

模块配色（强制）

1. 颜色优先按业务模块划分，不同模块使用不同色系。 2. 同一模块内节点应保持同色系，必要时用浅深区分职责。 3. 只有单模块时，才退化到单色系 + 分层组织。

11. 生成步骤

1. 识别聚合根、核心对象、规则对象、持久化对象、查询组件、操作组件。 2. 识别应建模为枚举的概念。 3. 按模块划分节点，并给模块分配颜色。 4. 识别需要审计字段的对象。 5. 区分 Domain 与 Repository 功能子块（存储/规则/缓存/网关等），仅保留业务仓储抽象与 Entity。 6. 校验关系是否真有落点。 7. 删除 POJO 转换链路与 MyBatis 技术节点。 8. 校验查询能力是否满足分页约束。 9. 校验关系型持久化 Entity 节点说明是否包含 表: xxx / 复用表: xxx，并确认 Repository 未误写表归属注释。 10. 校验 Controller 节点说明是否包含接口前缀 接口前缀: /api/.../。 11. 生成并写入 .puml 文件（不在对话回显 UML 正文）。 12. 用户强调可读性时，应用统一模板风格。

12. 自检清单

1. 是否已产出 .puml 文件。 2. 是否误绘制 Dto / Vo / ResVo 节点。 3. 是否存在无落点关系。 4. 是否把 Entity 错放到 Domain。 5. 是否出现 findAll / listAll / queryAll / loadAll。 6. 是否用 String/Integer 表达本应枚举的概念。 7. 是否使用统一类内说明风格。 8. 每个类/接口/枚举是否都有说明块。 9. 枚举是否仅展示实例（常量），且未展示成员变量与内部方法。 10. 颜色是否按模块划分（而非只按技术层）。 11. 关系型 Entity 是否标注了 表: xxx / 复用表: xxx。 12. Repository 节点是否误写了 表: / 复用表: / 无表:。 13. Controller 节点是否都标注了 接口前缀: /api/.../。 14. 是否存在多余连线、冗余节点、重复语义字段。 15. 是否误绘制 POJO 转换类或 toXxx/fromXxx 转换链路。 16. 是否误绘制 MyBatis 技术类或 XML 映射细节。 17. 是否存在“为了完整而臆造”的内容。