30c - 系统设计文档AI生成

请为以下系统生成 Mermaid C4 [Context/Container/Component] 图：

系统名称：[系统名称]
系统描述：[一句话描述系统功能]
主要用户角色：[列出用户角色及其主要操作]
外部系统依赖：[列出外部系统及其交互方式]
[仅 Container 图] 主要容器/服务：[列出服务名称、技术栈、职责]
[仅 Component 图] 目标容器：[指定要展开的容器名称]

要求：
- 使用 Mermaid C4Context / C4Container / C4Component 语法
- 节点标签使用中文，ID 使用英文
- 关系标注通信协议（HTTPS、gRPC、TCP 等）
- 包含 title 标题
- 外部系统使用 System_Ext，数据库使用 ContainerDb，消息队列使用 ContainerQueue

请用 Mermaid sequenceDiagram 语法生成以下交互流程的序列图：

场景名称：[场景名称，如"用户下单支付流程"]
参与者：[列出所有参与者及其角色]
交互流程：
1. [步骤 1 描述]
2. [步骤 2 描述]
...

要求：
- 使用 autonumber 自动编号
- 用户使用 actor 类型
- 同步调用使用 ->>，异步调用使用 -)
- 返回使用 -->>（虚线）
- 包含错误处理分支（使用 alt/else）
- 关键操作添加 Note 注释
- 参与者标签使用中文

请用 Mermaid flowchart 语法生成以下流程的流程图：

流程名称：[流程名称]
流程描述：[简要描述]
主要步骤：
1. [步骤描述]
2. [决策点及分支]
...

要求：
- 使用 TD（从上到下）或 LR（从左到右）布局
- 决策节点使用菱形 {}
- 关键路径用粗线 ==>
- 错误路径用虚线 -.->
- 成功节点用绿色 style，错误节点用红色 style
- 节点 ID 使用英文字母，标签使用中文

请用 Mermaid erDiagram 语法生成以下数据模型的 ER 图：

系统名称：[系统名称]
核心实体：[列出主要实体及其关键属性]
实体关系：[描述实体间的关系，如一对多、多对多]

要求：
- 每个实体包含字段名、类型、约束（PK/FK/UK）和中文注释
- 关系使用正确的基数符号（||--o{ 一对多，}o--o{ 多对多）
- 关系标签使用中文动词描述
- 包含常见字段（id、created_at、updated_at）
- 枚举类型标注可选值

请用 Mermaid stateDiagram-v2 语法生成以下实体的状态机图：

实体名称：[实体名称，如"订单"]
状态列表：[列出所有可能的状态]
状态转换：
- [源状态] → [目标状态]：[触发条件]
...

要求：
- 使用 stateDiagram-v2 语法
- 包含初始状态 [*] 和终止状态 [*]
- 关键状态添加 note 注释说明业务规则
- 自动触发的转换标注条件（如超时、定时任务）
- 可重试的操作使用自循环箭头

@startuml
skinparam classAttributeIconSize 0
skinparam classFontSize 14

package "领域模型" {
    abstract class BaseEntity {
        - id: UUID
        - createdAt: DateTime
        - updatedAt: DateTime
        + getId(): UUID
    }

    class User extends BaseEntity {
        - email: String
        - name: String
        - passwordHash: String
        - role: UserRole
        + authenticate(password: String): Boolean
        + changePassword(oldPwd: String, newPwd: String): void
        + hasPermission(permission: String): Boolean
    }

    enum UserRole {
        ADMIN
        CUSTOMER
        MERCHANT
    }

    class Order extends BaseEntity {
        - userId: UUID
        - status: OrderStatus
        - totalAmount: Decimal
        - shippingAddress: Address
        + addItem(product: Product, quantity: int): void
        + removeItem(itemId: UUID): void
        + calculateTotal(): Decimal
        + submit(): void
        + cancel(): void
    }

    enum OrderStatus {
        DRAFT
        PENDING_PAYMENT
        PAID
        PROCESSING
        SHIPPED
        DELIVERED
        COMPLETED
        CANCELLED
    }

    class OrderItem {
        - orderId: UUID
        - productId: UUID
        - quantity: int
        - unitPrice: Decimal
        + getSubtotal(): Decimal
    }

    class Product extends BaseEntity {
        - name: String
        - description: String
        - price: Decimal
        - stock: int
        - categoryId: UUID
        + isAvailable(): Boolean
        + reduceStock(quantity: int): void
        + restoreStock(quantity: int): void
    }

    User "1" --> "*" Order : 下单
    Order "1" *-- "*" OrderItem : 包含
    Product "1" --> "*" OrderItem : 被购买
    User --> UserRole
    Order --> OrderStatus
}
@enduml

请用 PlantUML 语法生成以下领域模型的类图：

领域名称：[领域名称]
核心实体：
- [实体名称]：[属性列表]、[方法列表]
...
实体关系：
- [实体A] 与 [实体B] 的关系：[关系类型和描述]
...

要求：
- 使用 package 分组相关类
- 抽象类使用 abstract class
- 枚举使用 enum
- 标注访问修饰符（+ public, - private, # protected）
- 关系使用正确的 UML 符号（--> 关联, *-- 组合, o-- 聚合, ..|> 实现, --|> 继承）
- 关系标注基数（"1" --> "*"）和中文描述
- 使用 skinparam 美化样式

@startuml
skinparam componentStyle uml2
skinparam backgroundColor #FEFEFE

package "前端层" {
    [Web 应用\n(React + Next.js)] as Web
    [管理后台\n(React + Ant Design)] as Admin
    [移动端\n(React Native)] as Mobile
}

package "API 网关层" {
    [API Gateway\n(Kong / AWS API Gateway)] as Gateway
    [认证中间件\n(JWT + OAuth 2.0)] as AuthMiddleware
    [限流中间件\n(Rate Limiter)] as RateLimiter
}

package "业务服务层" {
    [用户服务\n(Go)] as UserSvc
    [订单服务\n(Go)] as OrderSvc
    [商品服务\n(Go)] as ProductSvc
    [支付服务\n(Go)] as PaymentSvc
    [通知服务\n(Node.js)] as NotifySvc
}

package "基础设施层" {
    database "PostgreSQL\n(主从复制)" as DB
    database "Redis\n(集群模式)" as Cache
    queue "RabbitMQ\n(镜像队列)" as MQ
    storage "MinIO / S3\n(对象存储)" as Storage
}

package "外部服务" {
    cloud "支付宝/微信支付" as PayGateway
    cloud "短信服务" as SMS
    cloud "邮件服务" as Email
}

Web --> Gateway
Admin --> Gateway
Mobile --> Gateway

Gateway --> AuthMiddleware
Gateway --> RateLimiter
AuthMiddleware --> UserSvc

Gateway --> OrderSvc
Gateway --> ProductSvc
Gateway --> PaymentSvc

OrderSvc --> DB
OrderSvc --> Cache
OrderSvc --> MQ
ProductSvc --> DB
ProductSvc --> Cache
UserSvc --> DB
PaymentSvc --> PayGateway

MQ --> NotifySvc
NotifySvc --> SMS
NotifySvc --> Email

ProductSvc --> Storage
@enduml

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

LAYOUT_WITH_LEGEND()

title 电商平台 - 容器图

Person(customer, "客户", "浏览商品、下单、支付")
Person(admin, "管理员", "管理商品、订单、用户")

System_Boundary(ecommerce, "电商平台") {
    Container(web, "Web 应用", "React + Next.js", "提供用户界面和服务端渲染")
    Container(api, "API 网关", "Kong", "路由、认证、限流")
    Container(order_svc, "订单服务", "Go + gRPC", "处理订单生命周期")
    Container(product_svc, "商品服务", "Go + gRPC", "管理商品目录和库存")
    Container(user_svc, "用户服务", "Go + gRPC", "用户认证和权限管理")
    ContainerDb(db, "PostgreSQL", "关系型数据库", "存储业务数据，主从复制")
    ContainerDb(cache, "Redis", "缓存集群", "会话、热点数据、分布式锁")
    ContainerQueue(mq, "RabbitMQ", "消息队列", "异步任务、事件驱动")
}

System_Ext(payment, "支付网关", "支付宝/微信支付")
System_Ext(logistics, "物流系统", "第三方物流 API")

Rel(customer, web, "访问", "HTTPS")
Rel(admin, web, "管理操作", "HTTPS")
Rel(web, api, "API 调用", "HTTPS/JSON")
Rel(api, order_svc, "路由", "gRPC")
Rel(api, product_svc, "路由", "gRPC")
Rel(api, user_svc, "路由", "gRPC")
Rel(order_svc, db, "读写", "TCP/5432")
Rel(order_svc, cache, "缓存", "TCP/6379")
Rel(order_svc, mq, "发布事件", "AMQP")
Rel(order_svc, payment, "支付请求", "HTTPS")
Rel(order_svc, logistics, "物流推送", "HTTPS")
@enduml

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Dynamic.puml

LAYOUT_WITH_LEGEND()

title 用户下单支付 - 动态视图

ContainerDb(db, "PostgreSQL", "")
Container(web, "Web 应用", "React")
Container(api, "API 网关", "Kong")
Container(order, "订单服务", "Go")
Container(product, "商品服务", "Go")
Container(pay, "支付服务", "Go")
System_Ext(payment, "支付网关", "")

Rel(web, api, "1. 提交订单", "POST /orders")
Rel(api, product, "2. 检查库存", "gRPC")
Rel(product, db, "3. 查询库存", "SQL")
Rel(api, order, "4. 创建订单", "gRPC")
Rel(order, db, "5. 写入订单", "SQL")
Rel(order, product, "6. 锁定库存", "gRPC")
Rel(web, api, "7. 发起支付", "POST /payments")
Rel(api, pay, "8. 处理支付", "gRPC")
Rel(pay, payment, "9. 调用支付网关", "HTTPS")
Rel(pay, order, "10. 更新订单状态", "gRPC")
Rel(order, db, "11. 更新状态为已支付", "SQL")
@enduml

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Deployment.puml

LAYOUT_WITH_LEGEND()

title 电商平台 - 部署图

Deployment_Node(cdn, "CloudFront CDN", "AWS") {
    Container(static, "静态资源", "HTML/CSS/JS")
}

Deployment_Node(aws, "AWS 云环境", "us-east-1") {
    Deployment_Node(alb, "Application Load Balancer", "AWS ALB") {
        Container(lb, "负载均衡器", "L7 路由")
    }

    Deployment_Node(ecs, "ECS Fargate", "容器集群") {
        Deployment_Node(api_task, "API 任务", "3 实例") {
            Container(api, "API 网关", "Kong")
        }
        Deployment_Node(svc_task, "业务服务任务", "各 2 实例") {
            Container(order, "订单服务", "Go")
            Container(product, "商品服务", "Go")
        }
    }

    Deployment_Node(data, "数据层", "") {
        Deployment_Node(rds, "RDS", "Multi-AZ") {
            ContainerDb(db, "PostgreSQL 16", "主从复制")
        }
        Deployment_Node(elasticache, "ElastiCache", "集群模式") {
            ContainerDb(redis, "Redis 7", "3 主 3 从")
        }
    }
}

Rel(cdn, alb, "HTTPS")
Rel(alb, api, "HTTP/8080")
Rel(api, order, "gRPC/50051")
Rel(api, product, "gRPC/50052")
Rel(order, db, "TCP/5432")
Rel(order, redis, "TCP/6379")
@enduml

@startuml
skinparam activityFontSize 14
title 订单处理流程

start

:接收订单请求;

if (用户已认证?) then (是)
    :验证订单数据;

    if (数据有效?) then (是)
        fork
            :检查库存;
        fork again
            :验证收货地址;
        fork again
            :计算运费;
        end fork

        if (库存充足?) then (是)
            :锁定库存;
            :创建订单记录;
            :生成支付链接;

            :等待用户支付;

            if (支付成功?) then (是)
                :确认订单;
                :扣减库存;
                :发送确认通知;
                #palegreen:订单创建成功;
            else (否/超时)
                :释放库存锁定;
                :取消订单;
                #salmon:订单已取消;
            endif
        else (否)
            :返回库存不足错误;
            #salmon:订单创建失败;
        endif
    else (否)
        :返回数据验证错误;
        #salmon:请求无效;
    endif
else (否)
    :返回 401 未认证;
    #salmon:认证失败;
endif

stop
@enduml

@startuml
' ===== 自定义主题 =====
!define DARKBLUE #1a237e
!define LIGHTBLUE #e3f2fd
!define GREEN #2e7d32
!define ORANGE #ef6c00
!define RED #c62828

skinparam backgroundColor #FAFAFA
skinparam defaultFontName "Source Han Sans SC"
skinparam defaultFontSize 13

skinparam component {
    BackgroundColor LIGHTBLUE
    BorderColor DARKBLUE
    FontColor DARKBLUE
    ArrowColor DARKBLUE
}

skinparam database {
    BackgroundColor #FFF3E0
    BorderColor ORANGE
    FontColor ORANGE
}

skinparam queue {
    BackgroundColor #E8F5E9
    BorderColor GREEN
    FontColor GREEN
}

skinparam cloud {
    BackgroundColor #FFEBEE
    BorderColor RED
    FontColor RED
}

' ===== 使用自定义主题的图表 =====
[API 网关] as API
[订单服务] as Order
database "PostgreSQL" as DB
queue "RabbitMQ" as MQ
cloud "支付网关" as Pay

API --> Order
Order --> DB
Order --> MQ
Order --> Pay
@enduml

请分析以下需求文档，提取系统架构设计所需的关键信息：

---
[粘贴需求文档 / PRD / 用户故事]
---

请按以下结构输出：

## 1. 功能需求摘要
- 核心功能列表（按优先级排序）
- 用户角色和权限模型

## 2. 非功能需求
- 性能要求（QPS、响应时间、并发用户数）
- 可用性要求（SLA、RTO、RPO）
- 安全要求（认证方式、数据加密、合规需求）
- 可扩展性要求（预期增长、峰值倍数）

## 3. 技术约束
- 团队技术栈偏好
- 预算限制
- 部署环境要求
- 第三方集成需求

## 4. 架构关注点
- 需要重点设计的子系统
- 关键的架构决策点
- 潜在的技术风险

## 5. 建议的架构视图
- 推荐生成哪些类型的架构图
- 每种图的关注重点

基于以下架构关注点，请生成完整的系统设计文档：

系统名称：[系统名称]
系统描述：[一句话描述]
架构关注点：
[粘贴步骤 1 的输出]

请生成以下内容：

### 1. 系统上下文图（Mermaid C4Context）
- 展示系统与外部用户、外部系统的关系

### 2. 容器图（Mermaid C4Container）
- 展示系统内部的主要容器/服务及其技术栈

### 3. 核心业务流程序列图（Mermaid sequenceDiagram）
- 为最关键的 [N] 个业务流程各生成一张序列图

### 4. 数据模型 ER 图（Mermaid erDiagram）
- 展示核心实体及其关系

### 5. 关键状态机图（Mermaid stateDiagram-v2）
- 为核心实体（如订单、用户）生成状态机图

### 6. 部署架构图（Mermaid flowchart + subgraph）
- 展示生产环境的部署拓扑

要求：
- 所有图表使用 Mermaid 语法
- 每张图前添加简要说明（2-3 句话解释图表内容和设计决策）
- 图表标签使用中文
- 关系标注通信协议

#!/bin/bash
# validate-mermaid.sh - 验证 Markdown 文件中的 Mermaid 图表语法
 
set -e
 
# 安装 mermaid-cli（如果未安装）
if ! command -v mmdc &> /dev/null; then
    npm install -g @mermaid-js/mermaid-cli
fi
 
# 提取 Markdown 中的 Mermaid 代码块
extract_mermaid() {
    local file=$1
    local count=0
    local in_block=false
    local temp_dir=$(mktemp -d)
 
    while IFS= read -r line; do
        if [[ "$line" =~ ^\`\`\`mermaid ]]; then
            in_block=true
            count=$((count + 1))
            continue
        fi
        if [[ "$line" =~ ^\`\`\` ]] && $in_block; then
            in_block=false
            continue
        fi
        if $in_block; then
            echo "$line" >> "$temp_dir/diagram_$count.mmd"
        fi
    done < "$file"
 
    echo "$temp_dir"
}
 
# 验证每个 Mermaid 文件
validate_diagrams() {
    local dir=$1
    local errors=0
 
    for mmd_file in "$dir"/*.mmd; do
        [ -f "$mmd_file" ] || continue
        echo "验证: $(basename $mmd_file)"
 
        if mmdc -i "$mmd_file" -o "/dev/null" 2>/dev/null; then
            echo "  ✅ 语法正确"
        else
            echo "  ❌ 语法错误"
            errors=$((errors + 1))
        fi
    done
 
    return $errors
}
 
# 主流程
for md_file in "$@"; do
    echo "=== 检查文件: $md_file ==="
    temp_dir=$(extract_mermaid "$md_file")
    validate_diagrams "$temp_dir" || echo "⚠️ 发现语法错误"
    rm -rf "$temp_dir"
done

# .github/workflows/validate-diagrams.yml
name: Validate Architecture Diagrams
 
on:
  pull_request:
    paths:
      - 'docs/architecture/**/*.md'
      - 'docs/design/**/*.md'
 
jobs:
  validate-mermaid:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
 
      - name: Install Mermaid CLI
        run: npm install -g @mermaid-js/mermaid-cli
 
      - name: Validate Mermaid Diagrams
        run: |
          find docs/ -name "*.md" -exec grep -l '```mermaid' {} \; | while read file; do
            echo "Validating: $file"
            # 提取并验证每个 Mermaid 代码块
            python3 scripts/extract-mermaid.py "$file" | while read mmd_file; do
              mmdc -i "$mmd_file" -o /tmp/output.svg || exit 1
            done
          done
 
      - name: Render Diagrams to SVG
        if: success()
        run: |
          mkdir -p docs/generated-diagrams
          find docs/ -name "*.mmd" -exec sh -c '
            mmdc -i "$1" -o "docs/generated-diagrams/$(basename $1 .mmd).svg" \
              --theme neutral \
              --backgroundColor transparent
          ' _ {} \;
 
  validate-plantuml:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup PlantUML
        run: |
          sudo apt-get update
          sudo apt-get install -y plantuml
 
      - name: Validate PlantUML Diagrams
        run: |
          find docs/ -name "*.puml" -exec plantuml -checkonly {} \;

# [系统名称] - 系统设计文档
 
## 文档信息
| 项目 | 内容 |
|------|------|
| 文档版本 | v1.0 |
| 创建日期 | [日期] |
| 最后更新 | [日期] |
| 作者 | [作者] + AI 辅助 |
| 状态 | 草稿 / 评审中 / 已批准 |
 
## 1. 系统概述
[2-3 段描述系统目标、核心功能和技术愿景]
 
## 2. 架构概览
 
### 2.1 系统上下文
[C4 Context 图 + 说明]
 
### 2.2 容器架构
[C4 Container 图 + 说明]
 
### 2.3 组件详情
[C4 Component 图 + 说明（针对核心容器）]
 
## 3. 核心业务流程
[序列图 × N + 每个流程的文字说明]
 
## 4. 数据模型
[ER 图 + 实体说明表]
 
## 5. 状态机设计
[状态图 + 状态转换规则表]
 
## 6. 部署架构
[部署图 + 环境说明]
 
## 7. 架构决策记录（ADR）
[关键 ADR 列表，详见 30b 节]
 
## 8. 非功能需求设计
### 8.1 性能设计
### 8.2 安全设计
### 8.3 可用性设计
### 8.4 可观测性设计
 
## 附录
- 术语表
- 参考文档

project/
├── docs/
│   ├── architecture/
│   │   ├── README.md                    # 架构文档入口
│   │   ├── context.md                   # 系统上下文（含 C4 Context 图）
│   │   ├── containers.md                # 容器架构（含 C4 Container 图）
│   │   ├── components/
│   │   │   ├── order-service.md         # 订单服务组件图
│   │   │   └── user-service.md          # 用户服务组件图
│   │   ├── sequences/
│   │   │   ├── order-flow.md            # 下单流程序列图
│   │   │   └── payment-flow.md          # 支付流程序列图
│   │   ├── data-model.md                # 数据模型 ER 图
│   │   ├── deployment.md                # 部署架构图
│   │   └── adrs/                        # 架构决策记录
│   │       ├── 001-api-gateway.md
│   │       └── 002-database-choice.md
│   └── generated/                       # CI 自动生成的 SVG/PNG
│       ├── context.svg
│       ├── containers.svg
│       └── ...
├── scripts/
│   ├── render-diagrams.sh               # 图表渲染脚本
│   └── validate-diagrams.sh             # 图表验证脚本
└── .github/
    └── workflows/
        └── architecture-docs.yml        # 架构文档 CI/CD

# .github/workflows/architecture-drift-check.yml
name: Architecture Drift Check
 
on:
  pull_request:
    paths:
      - 'src/**'
      - 'services/**'
 
jobs:
  check-drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Check for architecture-impacting changes
        run: |
          # 检测是否有架构相关的代码变更
          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)
 
          # 检查是否新增/删除了服务
          if echo "$CHANGED_FILES" | grep -q "services/.*/main.go\|services/.*/index.ts"; then
            echo "⚠️ 检测到服务层变更，请确认架构图是否需要更新"
            echo "相关架构文档："
            echo "  - docs/architecture/containers.md"
            echo "  - docs/architecture/deployment.md"
          fi
 
          # 检查是否修改了数据模型
          if echo "$CHANGED_FILES" | grep -q "models/\|schema/\|migrations/"; then
            echo "⚠️ 检测到数据模型变更，请确认 ER 图是否需要更新"
            echo "相关架构文档："
            echo "  - docs/architecture/data-model.md"
          fi
 
          # 检查是否修改了 API 路由
          if echo "$CHANGED_FILES" | grep -q "routes/\|api/\|handlers/"; then
            echo "⚠️ 检测到 API 变更，请确认序列图是否需要更新"
            echo "相关架构文档："
            echo "  - docs/architecture/sequences/"
          fi
 
      - name: Comment on PR
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '🏗️ **架构文档同步提醒**\n\n检测到可能影响架构的代码变更，请确认相关架构图是否需要更新。\n\n使用 AI 快速更新：\n```\n请根据以下代码变更，更新对应的架构图：\n[粘贴 diff]\n```'
            })

你是一个架构文档维护助手。以下是最近的代码变更（git diff）：

---
[粘贴 git diff 内容]
---

以下是当前的架构图（Mermaid 代码）：

---
[粘贴当前架构图代码]
---

请分析代码变更对架构图的影响，并输出：

1. **变更影响分析**：这些代码变更是否影响架构图？如果是，影响了哪些部分？
2. **更新后的架构图**：如果需要更新，输出完整的更新后 Mermaid 代码
3. **变更说明**：简要说明架构图做了哪些修改及原因

如果代码变更不影响架构图（如 bug 修复、样式调整），请明确说明"无需更新架构图"。

请对以下架构图进行健康检查：

[粘贴架构图代码]

检查项目：
1. **完整性**：是否所有已知的服务/组件都在图中？
2. **准确性**：服务间的通信协议和方向是否正确？
3. **一致性**：图中的命名是否与代码库中的命名一致？
4. **时效性**：是否有已废弃的组件仍在图中？
5. **可读性**：布局是否清晰？是否有交叉线过多的问题？

已知的服务列表（从代码库提取）：
[列出当前代码库中的服务/模块列表]

请输出检查报告和建议的修改。

请分析以下项目结构和关键文件，逆向生成系统架构图：

项目结构：
[粘贴 tree 命令输出或目录结构]

关键配置文件：
[粘贴 docker-compose.yml / kubernetes manifests / package.json 等]

关键入口文件：
[粘贴主要入口文件的 import 和路由定义]

请生成：
1. C4 Container 图（Mermaid）：展示所有服务/容器及其关系
2. 数据流图（Mermaid flowchart）：展示数据在系统中的流转路径
3. 部署图（Mermaid flowchart + subgraph）：展示部署拓扑

每张图前添加 2-3 句说明。

请根据以下 API 端点定义，为每个核心业务流程生成 Mermaid 序列图：

API 端点列表：
[粘贴 OpenAPI/Swagger 定义或 API 路由列表]

服务间调用关系：
[描述哪些服务会调用哪些服务]

请为以下流程各生成一张序列图：
1. [流程 1 名称]
2. [流程 2 名称]
...

要求：
- 使用 autonumber
- 标注 HTTP 方法和路径
- 包含错误处理分支（alt/else）
- 异步操作使用 activate/deactivate 标注

请为以下微服务系统生成完整的架构图集：

系统名称：[名称]
服务列表：
- [服务名]：[技术栈]，[职责描述]
...

通信方式：
- 同步：[gRPC / REST / GraphQL]
- 异步：[Kafka / RabbitMQ / SQS]

基础设施：
- 数据库：[类型和用途]
- 缓存：[类型和用途]
- 消息队列：[类型和用途]

请生成：
1. 服务拓扑图（flowchart）：展示所有服务及其通信关系
2. 数据所有权图：展示每个服务拥有的数据存储
3. 事件流图：展示异步事件在服务间的流转
4. 服务依赖矩阵：展示服务间的依赖关系

所有图使用 Mermaid 语法。

请为以下 Serverless 应用生成架构图：

云平台：[AWS / GCP / Azure]
触发器类型：
- API Gateway → Lambda/Cloud Function
- S3/GCS 事件 → Lambda/Cloud Function
- SQS/Pub/Sub → Lambda/Cloud Function
- 定时任务 → Lambda/Cloud Function

函数列表：
- [函数名]：[触发器]，[职责]，[下游依赖]
...

请生成：
1. 事件驱动架构图（flowchart）：展示触发器→函数→下游的完整链路
2. 数据流图：展示数据从输入到输出的完整路径
3. 成本热力图：标注每个组件的预估月成本

使用 Mermaid 语法，用 subgraph 分组不同的云服务类别。

请为以下事件驱动系统生成架构图：

事件列表：
- [事件名称]：[发布者] → [消费者列表]
...

事件存储：[Kafka / EventStore / DynamoDB Streams]

请生成：
1. 事件流图（flowchart LR）：展示事件从发布到消费的完整路径
2. 事件溯源时间线（sequence diagram）：展示关键业务场景的事件序列
3. 聚合边界图：展示领域聚合及其发布/订阅的事件

使用 Mermaid 语法。

❌ 错误：
flowchart TD
    user-service --> order-service
    
✅ 修复：
flowchart TD
    user_service[user-service] --> order_service[order-service]

💡 规则：节点 ID 不能包含连字符（-），使用下划线或驼峰命名，
   在方括号中放置显示标签。

❌ 错误：
C4Context
    Person(customer)
    System(ecommerce)
    
✅ 修复：
C4Context
    Person(customer, "客户", "浏览和购买商品")
    System(ecommerce, "电商平台", "提供在线购物服务")

💡 规则：C4 元素需要至少 2 个参数（alias, label），
   建议提供 3 个参数（alias, label, description）。

❌ 错误：
sequenceDiagram
    A -> B: 请求
    B --> A: 响应
    
✅ 修复：
sequenceDiagram
    A ->> B: 请求
    B -->> A: 响应

💡 规则：Mermaid 序列图使用 ->> 表示实线箭头（同步调用），
   -->> 表示虚线箭头（返回），-> 和 --> 是无箭头的线。

❌ 错误：
erDiagram
    USER 1--* ORDER : "下单"
    
✅ 修复：
erDiagram
    USER ||--o{ ORDER : "下单"

💡 规则：Mermaid ER 图使用特定的基数符号：
   ||  精确一个
   o|  零或一个
   }o  零或多个
   }|  一或多个
   |{  一或多个（反向）
   o{  零或多个（反向）

❌ 错误：
flowchart TD
    subgraph AWS
        subgraph VPC
            A[服务 A]
        end subgraph
    end subgraph
    
✅ 修复：
flowchart TD
    subgraph AWS["AWS 云环境"]
        subgraph VPC["VPC"]
            A[服务 A]
        end
    end

💡 规则：subgraph 的结束标记只需要 end，不需要 end subgraph。
   subgraph 的标题放在方括号中。

❌ 错误：
stateDiagram-v2
    [*] --> Pending Payment
    Pending Payment --> Paid
    
✅ 修复：
stateDiagram-v2
    [*] --> PendingPayment
    state "Pending Payment" as PendingPayment
    PendingPayment --> Paid

💡 规则：状态名不能包含空格，使用 state "显示名" as 别名 语法。

❌ 错误：
skinparam componentStyle uml2
[API 网关] --> [订单服务]

✅ 修复：
@startuml
skinparam componentStyle uml2
[API 网关] --> [订单服务]
@enduml

💡 规则：PlantUML 代码必须以 @startuml 开头，@enduml 结尾。

❌ 错误：
@startuml
!include C4_Container.puml

✅ 修复：
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

💡 规则：使用完整的 GitHub raw URL 引入 C4-PlantUML 库，
   或在本地项目中使用相对路径并确保文件存在。

❌ 错误：
@startuml
[用户服务] --> [订单服务] : 调用
note right : 这里有个问题——破折号导致解析错误
@enduml

✅ 修复：
@startuml
[用户服务] --> [订单服务] : 调用
note right : 这里有个问题 - 使用英文短横线
@enduml

💡 规则：PlantUML 对某些中文标点符号（如中文破折号——、中文冒号：）
   支持不佳，建议在标签和注释中使用英文标点。

❌ 错误：
@startuml
package "业务层" {
    [订单服务 (Go)] as Order
}
@enduml

✅ 修复：
@startuml
package "业务层" {
    [订单服务\n(Go)] as Order
}
@enduml

💡 规则：组件名中的圆括号可能被解析为别名语法，
   使用 \n 换行或避免在组件名中使用圆括号。

以下 Mermaid/PlantUML 代码有语法错误，无法正确渲染：

```[mermaid/plantuml]
[粘贴有错误的代码]

### 7.4 预防语法错误的 Prompt 技巧

在生成图表时，通过以下 Prompt 技巧减少语法错误：

---

## 8. 图表渲染与发布工具链详解

### 8.1 Mermaid CLI（mmdc）

Mermaid CLI 是在 CI/CD 管线中渲染 Mermaid 图表的标准工具：

```bash
# 安装
npm install -g @mermaid-js/mermaid-cli

# 基本用法：将 .mmd 文件渲染为 SVG
mmdc -i diagram.mmd -o diagram.svg

# 渲染为 PNG（指定宽度）
mmdc -i diagram.mmd -o diagram.png -w 1920

# 渲染为 PDF
mmdc -i diagram.mmd -o diagram.pdf

# 使用指定主题
mmdc -i diagram.mmd -o diagram.svg --theme dark
# 可选主题：default, forest, dark, neutral

# 使用自定义配置
mmdc -i diagram.mmd -o diagram.svg --configFile mermaid.config.json

# 批量渲染
find docs/ -name "*.mmd" -exec sh -c '
    mmdc -i "$1" -o "${1%.mmd}.svg" --theme neutral
' _ {} \;

{
  "theme": "neutral",
  "themeVariables": {
    "primaryColor": "#1a73e8",
    "primaryTextColor": "#ffffff",
    "primaryBorderColor": "#1557b0",
    "lineColor": "#5f6368",
    "secondaryColor": "#e8f0fe",
    "tertiaryColor": "#f1f3f4",
    "fontSize": "14px",
    "fontFamily": "Source Han Sans SC, sans-serif"
  },
  "flowchart": {
    "htmlLabels": true,
    "curve": "basis",
    "padding": 15
  },
  "sequence": {
    "diagramMarginX": 50,
    "diagramMarginY": 10,
    "actorMargin": 50,
    "width": 150,
    "height": 65,
    "boxMargin": 10,
    "useMaxWidth": true
  },
  "er": {
    "diagramPadding": 20,
    "layoutDirection": "TB",
    "minEntityWidth": 100,
    "minEntityHeight": 75,
    "entityPadding": 15,
    "useMaxWidth": true
  }
}

# Docker 自托管部署
docker run -d -p 8000:8000 yuzutech/kroki
 
# 通过 API 渲染 Mermaid 图表
curl -X POST https://kroki.io/mermaid/svg \
  -H "Content-Type: text/plain" \
  -d 'flowchart TD
    A[开始] --> B{条件}
    B -->|是| C[执行]
    B -->|否| D[跳过]' \
  -o diagram.svg
 
# 通过 API 渲染 PlantUML 图表
curl -X POST https://kroki.io/plantuml/svg \
  -H "Content-Type: text/plain" \
  -d '@startuml
[API] --> [DB]
@enduml' \
  -o diagram.svg
 
# 支持的格式（部分）：
# mermaid, plantuml, graphviz, d2, c4plantuml,
# dbml, erd, excalidraw, structurizr, vegalite...

{
  "mcpServers": {
    "kroki": {
      "command": "npx",
      "args": ["-y", "mcp-kroki"],
      "env": {
        "KROKI_URL": "https://kroki.io"
      }
    }
  }
}

# Docker 部署 PlantUML Server
docker run -d -p 8080:8080 plantuml/plantuml-server:jetty
 
# 通过 URL 编码渲染
# 访问 http://localhost:8080/svg/SoWkIImgAStDuNBAJrBGjLDmpCbCJbMmKiX8pSd9vt98pKi1IW80
 
# 通过 API 渲染
curl -X POST http://localhost:8080/svg \
  -H "Content-Type: text/plain" \
  -d '@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml' \
  -o sequence.svg

// docusaurus.config.js
module.exports = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
  themeConfig: {
    mermaid: {
      theme: {
        light: 'neutral',
        dark: 'dark',
      },
      options: {
        maxTextSize: 50000,
        fontFamily: 'Source Han Sans SC, sans-serif',
      },
    },
  },
};

// .vitepress/config.js
import { withMermaid } from 'vitepress-plugin-mermaid';
 
export default withMermaid({
  mermaid: {
    theme: 'neutral',
  },
  mermaidPlugin: {
    class: 'mermaid',
  },
});

我们要构建一个 B2B SaaS 项目管理平台，核心功能包括：
- 多租户支持（每个企业一个工作空间）
- 项目和任务管理（看板视图、列表视图、甘特图）
- 团队协作（评论、@提及、文件附件）
- 权限管理（工作空间管理员、项目经理、成员、访客）
- 实时通知（应用内 + 邮件 + Slack/飞书集成）
- API 开放平台（供第三方集成）

技术约束：
- 团队熟悉 TypeScript 全栈（Next.js + Node.js）
- 预算有限，优先使用 Serverless 架构
- 目标用户 1000 家企业，每家 50-200 人
- 需要 SOC 2 合规