Mermaid图表专家Skill mermaid-diagram-specialist

---

名称：Mermaid 图表专家 类别：技术 描述：用于创建流程图、序列图、ERD 和架构可视化的 Mermaid 图表专家 用法：在创建技术文档、可视化工作流、记录架构或解释系统设计时使用 输入：过程描述、数据模型、架构要求、工作流步骤 输出：Markdown 中的 Mermaid 图表（流程图、序列图、ERD、C4、状态图等）

Mermaid 图表专家

概述

目的：为文档、架构可视化和过程映射创建全面的 Mermaid 图表的专家

类别：技术 主要用户：技术写作者、架构验证者、产品技术人员、技术领导

何时使用此技能

• 创建架构文档
• 可视化工作流和过程
• 记录数据模型（ERD）
• 解释序列流
• 创建状态机
• 记录组件关系
• 创建决策树
• 可视化用户旅程

先决条件

必需：

• 对要记录的系统/过程的理解
• 访问技术规范
• 了解所需的图表类型

可选：

• 设计系统颜色以确保一致性
• 现有文档作为参考

输入

技能需要：

• 过程/系统描述
• 实体和关系（用于ERD）
• 组件交互（用于序列图）
• 架构层次（用于C4图）
• 状态和转换（用于状态图）

工作流

步骤 1：图表类型选择

目标：根据需求选择合适的图表类型

可用图表类型：

1. 流程图：决策流、算法、过程
2. 序列图：API交互、消息流
3. ERD：数据库模式、实体关系
4. 类图：面向对象设计
5. 状态图：状态机、生命周期
6. 甘特图：项目时间线、进度安排
7. C4图：不同层次的架构
8. 饼图/条形图：数据可视化
9. Git图：版本控制流
10. 用户旅程图：用户体验流

决策矩阵：

• 有决策的过程 → 流程图
• API/系统交互 → 序列图
• 数据库结构 → ERD
• 系统架构 → C4图
• 对象关系 → 类图
• 状态转换 → 状态图
• 项目时间线 → 甘特图

验证：

• [ ] 图表类型与内容匹配
• [ ] 复杂度适当
• [ ] 考虑受众
• [ ] 目的明确

输出：选定的图表类型

步骤 2：流程图创建

目标：创建过程和决策流图表

语法：

flowchart TD
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Error --> Input
    Process --> Save[(Save to DB)]
    Save --> Success[/Success Response/]
    Success --> End([End])

节点形状：

• [Rectangle] - 过程步骤
• ([Rounded]) - 开始/结束
• {Diamond} - 决策
• [/Parallelogram/] - 输入/输出
• [(Database)] - 数据存储
• ((Circle)) - 连接器

方向选项：

• TD - 从上到下
• LR - 从左到右
• BT - 从下到上
• RL - 从右到左

示例 - 预订流程：

flowchart TD
    Start([用户发起预订]) --> CheckDates[检查日期可用性]
    CheckDates --> Available{日期可用？}
    Available -->|No| ShowError[/显示不可用消息/]
    ShowError --> End([结束])
    Available -->|Yes| CreateBooking[创建待处理预订]
    CreateBooking --> Payment[处理支付]
    Payment --> PaymentSuccess{支付成功？}
    PaymentSuccess -->|No| CancelBooking[取消预订]
    CancelBooking --> ShowError
    PaymentSuccess -->|Yes| ConfirmBooking[确认预订]
    ConfirmBooking --> SendEmail[/发送确认邮件/]
    SendEmail --> SaveDB[(保存到数据库)]
    SaveDB --> Success[/显示成功/]
    Success --> End

验证：

• [ ] 所有路径覆盖
• [ ] 决策点清晰
• [ ] 开始和结束定义
• [ ] 流动方向逻辑

输出：过程流程图

步骤 3：序列图创建

目标：记录 API 交互和消息流

语法：

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant DB
    participant Payment

    User->>Frontend: Click "Book"
    Frontend->>API: POST /api/bookings
    API->>DB: Check availability
    DB-->>API: Available
    API->>Payment: Process payment
    Payment-->>API: Payment successful
    API->>DB: Create booking
    DB-->>API: Booking created
    API-->>Frontend: 201 Created
    Frontend-->>User: Show confirmation

参与者类型：

• actor - 人类用户
• participant - 系统/服务
• database - 数据库

箭头类型：

• -> - 实线（同步）
• --> - 虚线（响应）
• ->> - 实箭头（异步消息）
• -->> - 虚箭头（异步响应）

示例 - 身份验证流程：

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant Clerk
    participant DB

    User->>Frontend: 输入凭证
    Frontend->>Clerk: 登录请求
    Clerk->>Clerk: 验证凭证
    alt 凭证有效
        Clerk-->>Frontend: JWT 令牌
        Frontend->>API: 带令牌的请求
        API->>Clerk: 验证令牌
        Clerk-->>API: 令牌有效
        API->>DB: 获取用户数据
        DB-->>API: 用户数据
        API-->>Frontend: 用户会话
        Frontend-->>User: 登录成功
    else 凭证无效
        Clerk-->>Frontend: 身份验证错误
        Frontend-->>User: 显示错误
    end

验证：

• [ ] 所有参与者标识
• [ ] 消息流逻辑
• [ ] 返回消息显示
• [ ] Alt/loop 块使用正确

输出：序列图

步骤 4：ERD 创建

目标：记录数据库模式和关系

语法：

erDiagram
    USER ||--o{ BOOKING : creates
    ACCOMMODATION ||--o{ BOOKING : "booked for"
    USER {
        uuid id PK
        string email UK
        string name
        timestamp created_at
    }
    BOOKING {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        date check_in
        date check_out
        enum status
    }
    ACCOMMODATION {
        uuid id PK
        string name
        text description
        decimal price_per_night
    }

关系类型：

• ||--|| - 一对一
• ||--o{ - 一对多
• }o--o{ - 多对多
• ||--o| - 一对零或一

基数符号：

• || - 恰好一个
• o| - 零或一个
• }o - 零个或多个
• }| - 一个或多个

示例 - 完整 Hospeda ERD：

erDiagram
    USER ||--o{ BOOKING : creates
    USER ||--o{ REVIEW : writes
    USER ||--o{ ACCOMMODATION : owns
    ACCOMMODATION ||--o{ BOOKING : "has bookings"
    ACCOMMODATION ||--o{ REVIEW : "has reviews"
    ACCOMMODATION }o--o{ AMENITY : includes
    BOOKING ||--|| PAYMENT : "has payment"

    USER {
        uuid id PK
        string clerk_id UK
        string email UK
        string name
        enum role
        timestamp created_at
    }

    ACCOMMODATION {
        uuid id PK
        uuid owner_id FK
        string name
        text description
        decimal price_per_night
        int max_guests
        enum status
    }

    BOOKING {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        date check_in
        date check_out
        int guests
        enum status
        decimal total_price
    }

    REVIEW {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        int rating
        text comment
        timestamp created_at
    }

    PAYMENT {
        uuid id PK
        uuid booking_id FK
        string mercadopago_id UK
        decimal amount
        enum status
        timestamp processed_at
    }

    AMENITY {
        uuid id PK
        string name
        string icon
    }

验证：

• [ ] 所有实体定义
• [ ] 关系准确
• [ ] 基数正确
• [ ] 主键/外键标记

输出：ERD 图

步骤 5：C4 架构图

目标：记录不同级别的系统架构

上下文级别（系统在环境中）：

C4Context
    title System Context - Hospeda Platform

    Person(guest, "Guest", "Tourist looking for accommodation")
    Person(owner, "Owner", "Accommodation owner")
    System(hospeda, "Hospeda Platform", "Tourism booking platform")

    System_Ext(clerk, "Clerk", "Authentication provider")
    System_Ext(mercadopago, "Mercado Pago", "Payment processor")
    System_Ext(email, "Email Service", "Transactional emails")

    Rel(guest, hospeda, "Searches and books", "HTTPS")
    Rel(owner, hospeda, "Manages listings", "HTTPS")
    Rel(hospeda, clerk, "Authenticates users", "API")
    Rel(hospeda, mercadopago, "Processes payments", "API")
    Rel(hospeda, email, "Sends notifications", "SMTP")

容器级别（应用程序和数据存储）：

C4Container
    title Container - Hospeda Platform

    Person(user, "User")

    Container(web, "Web App", "Astro + React", "Public-facing website")
    Container(admin, "Admin Panel", "TanStack Start", "Management interface")
    Container(api, "API", "Hono", "Backend services")
    ContainerDb(db, "Database", "PostgreSQL", "Stores all data")

    Rel(user, web, "Uses", "HTTPS")
    Rel(user, admin, "Manages", "HTTPS")
    Rel(web, api, "Calls", "JSON/HTTPS")
    Rel(admin, api, "Calls", "JSON/HTTPS")
    Rel(api, db, "Reads/Writes", "SQL")

组件级别（内部结构）：

C4Component
    title Components - API Application

    Container(api, "API", "Hono")

    Component(routes, "Routes", "Hono Router", "HTTP endpoints")
    Component(services, "Services", "Business Logic", "Domain operations")
    Component(models, "Models", "Data Access", "DB operations")
    Component(middleware, "Middleware", "Cross-cutting", "Auth, logging, errors")

    Rel(routes, middleware, "Uses")
    Rel(routes, services, "Calls")
    Rel(services, models, "Uses")
    Rel(models, db, "Queries")

验证：

• [ ] 选择适当级别
• [ ] 所有系统/容器显示
• [ ] 关系清晰
• [ ] 外部系统标识

输出：C4 架构图

步骤 6：状态图创建

目标：记录状态机和生命周期

语法：

stateDiagram-v2
    [*] --> Pending
    Pending --> Confirmed : Payment Success
    Pending --> Cancelled : Payment Failed
    Pending --> Cancelled : User Cancels
    Confirmed --> CheckedIn : Check-in Date
    Confirmed --> Cancelled : Cancellation Request
    CheckedIn --> CheckedOut : Check-out Date
    CheckedOut --> Reviewed : User Submits Review
    CheckedOut --> [*] : 30 Days Elapsed
    Reviewed --> [*]
    Cancelled --> [*]

示例 - 预订生命周期：

stateDiagram-v2
    [*] --> Draft : Create Booking

    state "Pending Payment" as Pending
    state "Payment Processing" as Processing

    Draft --> Pending : Submit Booking
    Pending --> Processing : Initiate Payment

    Processing --> Confirmed : Payment Approved
    Processing --> PaymentFailed : Payment Declined

    PaymentFailed --> Pending : Retry Payment
    PaymentFailed --> Cancelled : Max Retries

    Confirmed --> Active : Check-in Date Reached
    Active --> Completed : Check-out Date Reached

    Confirmed --> CancelRequested : Cancellation Request
    CancelRequested --> RefundProcessing : Approve Cancellation
    RefundProcessing --> Cancelled : Refund Complete

    Completed --> [*]
    Cancelled --> [*]

    note right of Confirmed
        Owner notified
        Calendar blocked
    end note

    note right of Completed
        Review requested
        Payment released
    end note

验证：

• [ ] 所有状态定义
• [ ] 转换逻辑
• [ ] 开始/结束状态标记
• [ ] 注释解释关键状态

输出：状态图

步骤 7：样式和自定义

目标：对图表应用一致的样式

主题应用：

%%{init: {'theme':'base', 'themeVariables': {
  'primaryColor':'#3B82F6',
  'primaryTextColor':'#fff',
  'primaryBorderColor':'#2563EB',
  'lineColor':'#6B7280',
  'secondaryColor':'#10B981',
  'tertiaryColor':'#F59E0B'
}}}%%
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]

类样式：

flowchart TD
    A[Normal] --> B[Success]
    B --> C[Error]

    classDef successClass fill:#10B981,stroke:#059669,color:#fff
    classDef errorClass fill:#EF4444,stroke:#DC2626,color:#fff

    class B successClass
    class C errorClass

验证：

• [ ] 颜色匹配品牌
• [ ] 对比度足够
• [ ] 样式一致
• [ ] 在两种主题中可读

输出：样式化图表

输出

生成：

• Markdown 中的 Mermaid 图表代码
• 根据需要多种图表类型
• 样式化和主题化图表
• 文档就绪的可视化

成功标准：

• 图表准确表示系统
• 所有元素适当标记
• 关系清晰正确
• 样式与品牌一致
• 在 Markdown 中正确渲染

最佳实践

1. 简洁性：保持图表专注且不杂乱
2. 标签：对所有元素使用清晰、描述性标签
3. 方向：一致的流动方向（通常从上到下或从左到右）
4. 分组：使用子图分组相关元素
5. 颜色：使用颜色突出重要元素
6. 注释：添加注释解释复杂逻辑
7. 级别：根据受众使用适当的抽象级别
8. 更新：保持图表与代码同步
9. 注释：在 Mermaid 代码中添加注释以便维护
10. 测试：在目标平台验证图表渲染

常见模式

API 请求流程

sequenceDiagram
    Client->>+API: GET /resource
    API->>+Service: fetchResource()
    Service->>+Model: findById()
    Model->>+DB: SELECT query
    DB-->>-Model: Row data
    Model-->>-Service: Entity
    Service-->>-API: DTO
    API-->>-Client: JSON response

错误处理流程

flowchart TD
    Request[Incoming Request] --> Validate{Valid?}
    Validate -->|No| ValidationError[Validation Error]
    ValidationError --> ErrorHandler[Error Handler]
    Validate -->|Yes| Process[Process Request]
    Process --> DB{DB Success?}
    DB -->|No| DBError[Database Error]
    DBError --> ErrorHandler
    DB -->|Yes| Success[Success Response]
    ErrorHandler --> LogError[Log Error]
    LogError --> ErrorResponse[Error Response]

备注

• Mermaid 在 GitHub、GitLab、Notion 和大多数 Markdown 查看器中渲染
• 实时编辑器可在 mermaid.live 获取
• 最大复杂度：保持不超过 20 个节点以提高可读性
• 使用子图分组相关节点
• 在提交前在目标平台测试渲染
• 在 Markdown 文件中保留图表源代码，而非图像
• 与代码一起版本控制图表
• 在代码审查期间更新图表

---