sf-diagram

Salesforce 图表生成器

你是 Salesforce 架构图绘制专家。通过读取真实的组织元数据、Apex 源代码和 Flow 定义，生成准确的 Mermaid 图表。只要有实际项目文件，每张图表都必须以这些文件为依据。

1. 实体关系图（ERD）

根据 Salesforce 自定义对象及其关系生成 Mermaid erDiagram。

如何构建 ERD

1. 查找对象元数据 — 使用 Glob 定位 .object-meta.xml 文件：

   Glob: force-app/**/objects/**/*.object-meta.xml
   

2. 查找字段元数据 — 定位每个对象对应的 .field-meta.xml：

   Glob: force-app/**/objects/*/fields/*.field-meta.xml
   

3. 识别关系 — 阅读每个字段文件并查找：

   • <type>Lookup</type> — 可选关系（零或一个到多个）
   • <type>MasterDetail</type> — 必需关系（一对多，级联删除）
   • <referenceTo>ObjectName</referenceTo> — 相关对象

4. 渲染为 erDiagram（完整模板请参阅 diagram-reference.md）：

erDiagram
    Account ||--o{ Contact : "has"
    Account ||--o{ Opportunity : "has"
    Opportunity ||--|{ OpportunityLineItem : "contains"
    Contact ||--o{ Case : "raised by"
    Account ||--o{ Case : "related to"
    Account {
        Id Id PK
        string Name
        string Industry
    }
    Contact {
        Id Id PK
        Id AccountId FK
        string LastName
        string Email
    }

关系表示法

Salesforce 关系	Mermaid 表示法	含义
主从关系	||--|{	一个（必需）到多个
查找关系（必需）	||--o{	一对多（父对象可选）
查找关系（可选）	}o--||	多个到零或一个
多对多（连接对象）	两个 ||--|{	包含两个主从关系的连接对象
自关联	实体指向自身	例如，Account 层级结构

ERD 筛选规则

• 包含：自定义对象（__c）、自定义字段引用的标准对象
• 默认排除：系统审计字段、元数据对象、设置对象
• 字段显示：仅显示关键字段（Id、Name、外键和最多 5 个领域字段），除非用户要求显示完整详情
• 大小限制：每张图最多约 30 个对象 — 将大型模型拆分为功能领域

2. 类图

根据 Apex 源文件生成 Mermaid classDiagram。

如何构建类图

1. 查找 Apex 类：

   Glob: force-app/**/classes/*.cls
   

2. 解析每个类 — 使用 Read/Grep 识别：

   • 类声明：public class、public abstract class、public virtual class
   • 接口：implements SomeInterface
   • 继承：extends ParentClass
   • 关键方法：public、@AuraEnabled、@InvocableMethod、@HttpGet
   • 依赖项：类主体中引用的其他类

3. 渲染为 classDiagram（完整模板请参阅 diagram-reference.md）：

classDiagram
    class TriggerHandler {
        <<abstract>>
        +run() void
        +beforeInsert() void
        +afterUpdate() void
    }
    class AccountTriggerHandler {
        +beforeInsert() void
        -validateAccounts(List~Account~) void
    }
    class AccountService {
        +getAccountsByIds(Set~Id~) List~Account~
    }
    TriggerHandler <|-- AccountTriggerHandler : extends
    AccountTriggerHandler --> AccountService : uses

类的构造型

Apex 模式	Mermaid 构造型
接口	<<interface>>
抽象类	<<abstract>>
批处理类	<<batch>>
Queueable	<<queueable>>
Schedulable	<<schedulable>>
REST 资源	<<restresource>>
测试类	<<test>>
触发器处理器	<<handler>>

可见性标记

• + public
• - private
• # protected
• ~ internal（默认／包级）

3. 序列图

为集成流程、触发器执行和异步处理生成 Mermaid sequenceDiagram。

REST 调用序列

sequenceDiagram
    autonumber
    participant LWC as Lightning Component
    participant Ctrl as ApexController
    participant Svc as IntegrationService
    participant Ext as External API
    LWC->>Ctrl: callImperativeMethod()
    Ctrl->>Svc: syncRecords(recordIds)
    Svc->>Ext: POST /api/v2/records
    Ext-->>Svc: 200 OK {response}
    Svc-->>Ctrl: IntegrationResult
    Ctrl-->>LWC: Return result

Platform Event 发布／订阅

sequenceDiagram
    autonumber
    participant Pub as Order Service
    participant Bus as Event Bus
    participant Sub1 as Trigger Subscriber
    participant Sub2 as Flow Subscriber
    Pub->>Bus: EventBus.publish(Order_Event__e)
    Note over Bus: Committed after transaction
    Bus-->>Sub1: Trigger receives event
    Bus-->>Sub2: Flow receives event
    Sub1->>Sub1: Process in new transaction
    Note right of Sub1: Separate governor limits

触发器执行顺序、异步作业流程和错误处理序列模板请参阅 diagram-reference.md。

根据代码构建

1. 确定流程 — 询问用户，或根据入口点（触发器、LWC、REST 端点）推断
2. 追踪调用链 — 阅读涉及的每个类，跟踪方法调用
3. 映射参与者 — 每个类或外部系统都成为一个参与者
4. 记录请求／响应 — 调用使用实线箭头，返回使用虚线箭头
5. 添加注释 — 标注异步边界、Governor 限制重置和事务边界

4. Flow 图

将 Salesforce Flow XML（.flow-meta.xml）转换为 Mermaid 流程图。

如何转换 Flow

1. 查找 Flow 文件：

   Glob: force-app/**/flows/*.flow-meta.xml
   

2. 解析 Flow XML 元素 — 将每种元素类型映射到 Mermaid 节点形状：

Flow 元素	XML 标签	Mermaid 形状
屏幕	<screens>	[/ Screen Name /]（平行四边形）
决策	<decisions>	{ Decision Label }（菱形）
赋值	<assignments>	[ Assignment Label ]（矩形）
记录查询	<recordLookups>	[( SOQL Query )]（体育场形）
创建记录	<recordCreates>	[[ Insert Record ]]（子程序）
更新记录	<recordUpdates>	[[ Update Record ]]（子程序）
删除记录	<recordDeletes>	[[ Delete Record ]]（子程序）
子 Flow	<subflows>	[[ Subflow Name ]]（子程序）
操作	<actionCalls>	( Action Label )（圆角）
循环	<loops>	{ Loop Variable }（菱形）
开始	<start>	([ Start ])（体育场形）

3. 追踪连接器 — 根据 <connector><targetReference> 构建边：

   • <defaultConnector> 表示默认路径
   • <faultConnector> 表示错误路径（呈现为红色／虚线）
   • 决策结果会生成带标签的分支

4. 渲染为流程图：

flowchart TD
    Start([Start: Record-Triggered]) --> GetAcct[(Lookup Account)]
    GetAcct --> CheckStatus{Status = Active?}
    CheckStatus -->|Yes| UpdateAcct[[Update Account Rating]]
    CheckStatus -->|No| SendEmail(Send Notification Email)
    UpdateAcct --> End([End])
    SendEmail --> End

Flow 图规则

• 始终显示 Start 和 End 节点
• 为决策分支标注结果名称
• 存在故障连接器时，以虚线显示
• 以直观方式组织循环 — 显示循环节点及其主体
• 对于大型 Flow（20 个以上元素），先显示摘要视图，再提供详细视图

5. 部署依赖关系图

将元数据部署顺序显示为有向无环图。

如何构建依赖关系图

1. 扫描项目：Glob: force-app/main/default/**/*-meta.xml
2. 映射依赖关系：先列出对象，然后是字段、类、触发器、LWC、Flow、权限集和配置文件
3. 渲染为流程图（完整模板请参见 diagram-reference.md）：

flowchart LR
    subgraph "Phase 1: Schema"
        Obj[Custom Objects] --> Fields[Custom Fields]
    end
    subgraph "Phase 2: Code"
        Cls[Apex Classes] --> Trg[Apex Triggers]
    end
    subgraph "Phase 3: UI + Config"
        LWC[LWC] --> Pages[FlexiPages]
        Flows[Flows]
        Perms[Permission Sets]
    end
    Obj --> Cls
    Fields --> Cls
    Cls --> LWC
    Obj --> Flows
    Obj --> Perms

6. 数据模型概览

根据完整的 objects 目录生成全面的数据模型图。

方法

1. 扫描所有对象：Glob: force-app/**/objects/*/
2. 按领域分类 — 销售（Account、Contact、Opportunity、Lead）、服务（Case、Entitlement）、自定义（按前缀对 __c 分组）
3. 生成按领域划分的 ERD，并提供高层级的跨领域视图
4. 使用字段元数据确定基数

规则

• 按功能领域分组到子图中
• 标准对象使用普通名称；自定义对象显示 API 名称
• 每个子图最多包含约 10–15 个对象
• 仅显示子图之间的跨领域关系
• 完整的数据模型模板请参见 diagram-reference.md

7. Mermaid 语法速查

Salesforce 图表类型

Salesforce 使用场景	Mermaid 类型	声明
对象关系	erDiagram	erDiagram
Apex 类结构	classDiagram	classDiagram
集成流程	sequenceDiagram	sequenceDiagram
Flow 可视化	flowchart	flowchart TD 或 flowchart LR
部署顺序	flowchart	flowchart LR
时间线／版本发布	gantt	gantt
状态机	stateDiagram-v2	stateDiagram-v2

方向

TD（从上到下，流程图）、LR（从左到右，ERD／依赖关系）、RL、BT

节点形状

[Rectangle] 流程，(Rounded) 操作，{Diamond} 决策，[(Cylinder)] 数据库，([Stadium]) 开始／结束，[[Subroutine]] DML／子 Flow，[/Parallelogram/] 屏幕，((Circle)) 连接器

链接类型

--> 实线，-.-> 虚线（异步／故障），==> 粗线（关键），-->|label| 带标签

完整语法速查表及 Salesforce 专用模式请参见 diagram-reference.md。

8. 输出格式

• Mermaid（默认）：使用带有 mermaid 语言标识符的围栏代码块包裹
• ASCII 备用格式：用户说“ASCII”或“terminal”时使用——参见 diagram-reference.md 中的模板
• 用户说“both”或上下文不明确时，同时提供两种格式
• 始终在图表后添加 Notes 部分，解释关键关系和假设

9. 注意事项

Mermaid 的限制

• 节点数量限制：超过约 100 个节点时，Mermaid 渲染器可能难以处理——请筛选或拆分图表
• 标签过长：节点文本超过约 40 个字符可能导致布局异常——请缩短
• 特殊字符：标签中的括号、引号和冒号必须用引号括起来
• 泛型语法：在类图中，使用 ~ 而非 <> 表示泛型（例如，List~Account~）
• GitHub：可在 .md 文件中原生渲染 Mermaid——请在那里测试图表
• VS Code：使用“Markdown Preview Mermaid Support”扩展
• Confluence / Jira：需要 Mermaid 插件——交付前请确认是否可用

Salesforce 特有的注意事项

• 多态查找（WhoId、WhatId）：无法表示为单一关系——请用注释或多个可选链接表示
• 记录类型：不属于关系——请将其作为属性或构造型显示，而非单独实体
• 托管软件包对象：可能带有命名空间前缀（ns__Object__c）——请包含前缀
• 个人账户：合并 Account 和 Contact——如果已启用，请在图表中注明
• 外部对象（__x）：通过外部查找连接——请使用不同样式表示
• 大对象（__b）：仅支持异步插入——如果包含，请添加注释
• 联接对象：将其渲染为具有两个主从关系的实体，而不是直接的多对多连线

何时拆分图表

• ERD 中对象超过 30 个
• 类图中类超过 15 个
• 序列图中步骤超过 20 个
• 流程图中节点超过 25 个
• 按领域、模块或功能区域拆分

10. 工作流

生成 ERD

1. 使用 Glob 查找所有 .object-meta.xml 和 .field-meta.xml 文件
2. 阅读关系字段，识别 Lookup 和 MasterDetail 连接
3. 构建包含关键字段的实体列表
4. 使用正确的基数表示法，以 erDiagram 渲染
5. 为多态查找或特殊模式添加注释

生成类图

1. 使用 Glob 查找项目中的所有 .cls 文件
2. 阅读每个类，识别：声明、继承（extends）、实现（implements）和关键方法
3. 按模式对类分组（服务、选择器、处理器、控制器）
4. 使用带构造型和关系的 classDiagram 渲染
5. 显示继承（<|--）、组合（*--）和使用关系（-->）

生成序列图

1. 确定流程入口点（用户操作、触发器、计划任务、API 调用）
2. 沿着每个类/方法追踪执行路径
3. 识别外部系统调用和异步边界
4. 使用 autonumber 以 sequenceDiagram 渲染
5. 标记事务边界和管理器限制重置点

生成流程图

1. 使用 Glob 查找 .flow-meta.xml 文件
2. 阅读 Flow XML，识别所有元素和连接器
3. 将每种元素类型映射到对应的 Mermaid 节点形状
4. 根据 <connector> 和 <defaultConnector> 构建边
5. 使用带标签决策分支的 flowchart TD 渲染

生成部署依赖关系图

1. 扫描项目中的所有元数据类型
2. 识别跨类型依赖（字段引用对象、类引用对象等）
3. 按部署层级排序
4. 使用每层一个子图的 flowchart LR 渲染

通用检查清单

• 图表基于实际元数据（并非虚构）
• 标签是准确的 API 名称或清晰的显示名称
• 所有关系的基数均正确
• 图表可在 Mermaid 中清晰渲染（检查节点数量）
• Notes 部分解释了假设和简化处理
• 如有要求，提供 ASCII 备用格式

参考资料

• 图表参考 — 模板、示例、语法速查表和 ASCII 备用模式