mermaid-diagram-specialist

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([User Initiates Booking]) --> CheckDates[Check Date Availability]
    CheckDates --> Available{Dates Available?}
    Available -->|No| ShowError[/Show Unavailable Message/]
    ShowError --> End([End])
    Available -->|Yes| CreateBooking[Create Pending Booking]
    CreateBooking --> Payment[Process Payment]
    Payment --> PaymentSuccess{Payment Success?}
    PaymentSuccess -->|No| CancelBooking[Cancel Booking]
    CancelBooking --> ShowError
    PaymentSuccess -->|Yes| ConfirmBooking[Confirm Booking]
    ConfirmBooking --> SendEmail[/Send Confirmation Email/]
    SendEmail --> SaveDB[(Save to Database)]
    SaveDB --> Success[/Show 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: Enter credentials
    Frontend->>Clerk: Login request
    Clerk->>Clerk: Validate credentials
    alt Credentials valid
        Clerk-->>Frontend: JWT token
        Frontend->>API: Request with token
        API->>Clerk: Verify token
        Clerk-->>API: Token valid
        API->>DB: Fetch user data
        DB-->>API: User data
        API-->>Frontend: User session
        Frontend-->>User: Logged in
    else Credentials invalid
        Clerk-->>Frontend: Auth error
        Frontend-->>User: Show error
    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 文件中，而不是图片中
• 将图表与代码一同纳入版本控制
• 在代码审查期间更新图表

---