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

请用 Mermaid flowchart 语法生成以下流程的流程图：
[描述业务流程]

要求：
- 使用 TD（从上到下）布局
- 决策节点使用菱形 {}
- 关键路径用粗线 ==>
- 错误路径用虚线 -.->
- 节点 ID 使用英文，标签使用中文

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

要求：
- 使用 actor 表示用户
- 使用 participant 表示系统组件
- 同步调用用 ->> ，异步响应用 -->>
- 包含 alt/else 分支处理成功和失败场景
- 使用 Note 标注关键说明
- 使用 activate/deactivate 表示处理时间

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

实体：[如：订单/任务/连接]
状态列表：[列出所有可能的状态]
转换规则：[描述状态间的转换条件]

要求：
- 包含初始状态 [*] 和终止状态
- 每个转换标注触发条件
- 标注不可逆转换和可回退转换

@startuml
skinparam classAttributeIconSize 0

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

    class User extends BaseEntity {
        - email: String
        - name: String
        - passwordHash: String
        - role: UserRole
        + login(credentials: Credentials): Token
        + updateProfile(data: ProfileData): User
        + hasPermission(action: String): Boolean
    }

    enum UserRole {
        ADMIN
        USER
        GUEST
    }

    class Order extends BaseEntity {
        - userId: UUID
        - status: OrderStatus
        - totalAmount: Decimal
        + addItem(product: Product, qty: Int): OrderItem
        + cancel(): void
        + complete(): void
        + calculateTotal(): Decimal
    }

    enum OrderStatus {
        DRAFT
        PENDING
        PAID
        SHIPPING
        COMPLETED
        CANCELLED
    }

    class OrderItem {
        - orderId: UUID
        - productId: UUID
        - quantity: Int
        - unitPrice: Decimal
        + subtotal(): Decimal
    }

    class Product extends BaseEntity {
        - name: String
        - price: Decimal
        - stock: Int
        - category: String
        + isAvailable(): Boolean
        + reduceStock(qty: Int): void
    }
}

User "1" --> "*" Order : places
Order "1" *-- "*" OrderItem : contains
OrderItem "*" --> "1" Product : references
User --> UserRole
Order --> OrderStatus

@enduml

@startuml
title 订单创建流程

actor "用户" as User
participant "前端" as FE
participant "API Gateway" as GW
participant "订单服务" as OrderSvc
participant "库存服务" as StockSvc
participant "支付服务" as PaySvc
database "数据库" as DB
queue "消息队列" as MQ

User -> FE: 提交订单
activate FE

FE -> GW: POST /api/orders
activate GW

GW -> OrderSvc: createOrder(items)
activate OrderSvc

group 库存检查
    OrderSvc -> StockSvc: checkStock(items)
    activate StockSvc
    StockSvc -> DB: SELECT stock FROM products
    DB --> StockSvc: 库存数据
    alt 库存充足
        StockSvc --> OrderSvc: OK
    else 库存不足
        StockSvc --> OrderSvc: InsufficientStock
        OrderSvc --> GW: 400 库存不足
        GW --> FE: 错误提示
        FE --> User: 显示库存不足
    end
    deactivate StockSvc
end

OrderSvc -> DB: INSERT order
DB --> OrderSvc: order_id

OrderSvc -> StockSvc: reserveStock(items)
activate StockSvc
StockSvc -> DB: UPDATE stock SET reserved
StockSvc --> OrderSvc: reserved
deactivate StockSvc

OrderSvc -> MQ: publish(OrderCreated)
OrderSvc --> GW: 201 Created
deactivate OrderSvc

GW --> FE: order_id
deactivate GW

FE -> GW: POST /api/payments
GW -> PaySvc: initiatePayment(order_id)
activate PaySvc
PaySvc --> GW: payment_url
GW --> FE: redirect_url
FE --> User: 跳转支付页面
deactivate PaySvc
deactivate FE

@enduml

@startuml
skinparam component {
    BackgroundColor LightBlue
    BorderColor DarkBlue
}

package "前端层" {
    [React SPA] as FE
    [状态管理 (Zustand)] as State
    [API 客户端] as APIClient
}

package "API 层" {
    [API Gateway (Nginx)] as GW
    [认证中间件] as Auth
    [限流中间件] as RateLimit
}

package "服务层" {
    [用户服务] as UserSvc
    [订单服务] as OrderSvc
    [商品服务] as ProductSvc
    [通知服务] as NotifySvc
}

package "数据层" {
    database "PostgreSQL" as PG
    database "Redis" as Redis
    queue "RabbitMQ" as MQ
    storage "S3" as S3
}

FE --> State
FE --> APIClient
APIClient --> GW

GW --> Auth
GW --> RateLimit
Auth --> UserSvc

GW --> UserSvc
GW --> OrderSvc
GW --> ProductSvc

UserSvc --> PG
UserSvc --> Redis
OrderSvc --> PG
OrderSvc --> MQ
ProductSvc --> PG
ProductSvc --> S3
NotifySvc --> MQ

@enduml

@startuml
node "CDN (CloudFront)" as CDN {
    artifact "静态资源" as Static
}

node "负载均衡器 (ALB)" as LB

cloud "Kubernetes 集群" {
    node "Pod: API Gateway" as GWPod {
        artifact "Nginx" as Nginx
    }
    node "Pod: 应用服务 x3" as AppPod {
        artifact "Node.js App" as App
    }
    node "Pod: Worker x2" as WorkerPod {
        artifact "Background Worker" as Worker
    }
}

database "RDS (PostgreSQL)" as RDS {
    artifact "主库" as Primary
    artifact "只读副本" as Replica
}

node "ElastiCache (Redis)" as Cache

queue "SQS" as Queue

CDN --> LB
LB --> GWPod
GWPod --> AppPod
AppPod --> RDS
AppPod --> Cache
AppPod --> Queue
WorkerPod --> Queue
WorkerPod --> RDS

@enduml

@startuml
title 用户注册流程

start

:用户填写注册表单;

if (邮箱格式有效?) then (是)
    :检查邮箱是否已注册;
    if (邮箱已存在?) then (是)
        :提示邮箱已注册;
        stop
    else (否)
    endif
else (否)
    :提示邮箱格式错误;
    stop
endif

:密码强度检查;

if (密码强度足够?) then (是)
    fork
        :创建用户记录;
    fork again
        :发送验证邮件;
    fork again
        :初始化用户配置;
    end fork

    :返回注册成功;
    :跳转到邮箱验证页面;
else (否)
    :提示密码强度不足;
    stop
endif

stop

@enduml

@startuml
left to right direction

actor "顾客" as Customer
actor "管理员" as Admin
actor "支付网关" as Payment

rectangle "电商系统" {
    usecase "浏览商品" as UC1
    usecase "搜索商品" as UC2
    usecase "下单购买" as UC3
    usecase "在线支付" as UC4
    usecase "查看订单" as UC5
    usecase "管理商品" as UC6
    usecase "处理退款" as UC7
    usecase "查看报表" as UC8
}

Customer --> UC1
Customer --> UC2
Customer --> UC3
Customer --> UC5
UC3 --> UC4 : <<include>>
UC4 --> Payment

Admin --> UC6
Admin --> UC7
Admin --> UC8

@enduml

workspace "电商系统" "在线购物平台的架构文档" {

    model {
        customer = person "顾客" "浏览商品、下单、支付的终端用户"
        admin = person "管理员" "管理商品、处理订单的后台用户"

        ecommerce = softwareSystem "电商系统" "提供在线购物服务" {
            webapp = container "Web 应用" "React SPA" "TypeScript, React" "Web Browser"
            apiGateway = container "API Gateway" "请求路由和认证" "Nginx"
            userService = container "用户服务" "用户注册、登录、权限管理" "Node.js, Express"
            orderService = container "订单服务" "订单创建、状态管理" "Node.js, Express"
            productService = container "商品服务" "商品 CRUD、库存管理" "Node.js, Express"
            database = container "数据库" "存储所有业务数据" "PostgreSQL" "Database"
            cache = container "缓存" "热点数据缓存" "Redis" "Database"
            messageQueue = container "消息队列" "异步任务处理" "RabbitMQ" "Queue"
        }

        paymentGateway = softwareSystem "支付网关" "第三方支付处理" "External"
        emailService = softwareSystem "邮件服务" "发送通知邮件" "External"

        # 关系定义
        customer -> webapp "浏览商品、下单"
        admin -> webapp "管理后台"
        webapp -> apiGateway "API 请求" "HTTPS"
        apiGateway -> userService "用户相关请求"
        apiGateway -> orderService "订单相关请求"
        apiGateway -> productService "商品相关请求"
        userService -> database "读写用户数据" "SQL"
        orderService -> database "读写订单数据" "SQL"
        productService -> database "读写商品数据" "SQL"
        orderService -> cache "缓存订单状态" "Redis Protocol"
        orderService -> messageQueue "发布订单事件" "AMQP"
        orderService -> paymentGateway "发起支付" "HTTPS"
        ecommerce -> emailService "发送通知" "SMTP"
    }

    views {
        systemContext ecommerce "Context" {
            include *
            autoLayout
        }
        container ecommerce "Containers" {
            include *
            autoLayout
        }
        theme default
    }
}

请为以下系统生成 C4 模型的完整架构文档：

系统名称：[名称]
系统描述：[一句话描述系统功能]

用户角色：
- [角色 1]：[描述]
- [角色 2]：[描述]

核心功能：
- [功能 1]
- [功能 2]
- [功能 3]

外部依赖：
- [外部系统 1]：[用途]
- [外部系统 2]：[用途]

请生成：
1. Structurizr DSL 代码（包含 model 和 views）
2. Mermaid C4Context 图（系统上下文）
3. Mermaid C4Container 图（容器视图）
4. 每个核心容器的 PlantUML 组件图

每个图附带 2-3 句说明，解释图中的关键设计决策。

请分析以下代码库结构，逆向生成 C4 模型：

项目结构：
[粘贴目录树]

关键配置文件：
[粘贴 package.json / Cargo.toml / docker-compose.yml]

请生成：
1. 系统上下文图（识别外部依赖和用户角色）
2. 容器图（识别服务、数据库、消息队列等）
3. 核心服务的组件图
4. 关键数据模型的类图

对于每个识别到的架构决策，请说明你的推断依据。

@startuml
title 数据流图 - Level 1

' 外部实体
actor "用户" as User
actor "支付网关" as Payment
actor "物流系统" as Logistics

' 处理过程
rectangle "1.0\n用户管理" as P1
rectangle "2.0\n商品管理" as P2
rectangle "3.0\n订单处理" as P3
rectangle "4.0\n支付处理" as P4

' 数据存储
database "D1: 用户数据" as D1
database "D2: 商品数据" as D2
database "D3: 订单数据" as D3

' 数据流
User --> P1 : 注册/登录
P1 --> D1 : 存储用户信息
User --> P2 : 浏览商品
D2 --> P2 : 商品列表
User --> P3 : 提交订单
D1 --> P3 : 用户信息
D2 --> P3 : 商品信息
P3 --> D3 : 创建订单
P3 --> P4 : 支付请求
P4 --> Payment : 发起支付
Payment --> P4 : 支付结果
P4 --> D3 : 更新订单状态
P3 --> Logistics : 配送请求
Logistics --> D3 : 配送状态

@enduml

请为以下系统生成数据流图（DFD）：

系统名称：[名称]
核心业务流程：[描述]

请生成：
1. Level 0 上下文图（Mermaid flowchart）：系统作为黑盒，展示外部实体和数据流
2. Level 1 顶层 DFD（Mermaid flowchart）：分解为 4-6 个主要处理过程
3. 数据字典：列出每条数据流的名称、内容、格式

要求：
- 外部实体用圆形 (()) 表示
- 处理过程用矩形 [] 表示
- 数据存储用圆柱形 [( )] 表示
- 每条数据流标注数据内容
- 数据流方向必须正确（不能有无源数据流或无目标数据流）

请分析以下需求文档，识别所有需要状态管理的实体：

[粘贴需求文档]

对于每个实体，请列出：
1. 实体名称
2. 所有可能的状态
3. 状态转换触发条件
4. 是否有并发状态（如订单同时处于"已支付"和"配送中"）

请为 [实体名称] 生成完整的状态机图（Mermaid stateDiagram-v2）：

状态列表：[列出所有状态]
业务规则：
- [规则 1：如"只有已支付的订单才能发货"]
- [规则 2：如"退款只能在发货后 7 天内申请"]

要求：
- 包含初始状态和所有终止状态
- 标注每个转换的触发条件
- 标注不可逆转换（用注释说明）
- 识别并标注可能的异常状态
- 如果有复合状态，使用 state 嵌套

请审查以下状态机图，检查：

[粘贴状态机图代码]

1. 是否有"死胡同"状态（进入后无法离开，也不是终止状态）？
2. 是否有不可达状态（没有任何路径可以到达）？
3. 是否有遗漏的状态转换（业务上应该存在但图中没有）？
4. 是否有冲突的转换（同一状态在同一条件下可以转到多个状态）？
5. 所有终止状态是否都有明确的到达路径？

请分析以下需求文档，提取所有数据实体：

[粘贴需求文档]

对于每个实体，请列出：
1. 实体名称（中英文）
2. 核心属性（名称、类型、约束）
3. 主键和唯一键
4. 与其他实体的关系（1:1 / 1:N / M:N）
5. 是否需要软删除

请基于以下实体列表生成 Mermaid ER 图：

[粘贴实体列表]

要求：
- 使用 Mermaid erDiagram 语法
- 标注 PK（主键）、FK（外键）、UK（唯一键）
- 关系使用正确的基数表示（||--o{ 等）
- 关系标签使用中文动词
- 包含审计字段（created_at, updated_at）
- M:N 关系使用中间表

请分析以下 ER 图的范式级别：

[粘贴 ER 图代码]

请检查：
1. 是否满足第一范式（1NF）：所有属性是否原子性？
2. 是否满足第二范式（2NF）：是否有部分依赖？
3. 是否满足第三范式（3NF）：是否有传递依赖？
4. 是否有合理的反范式设计（如冗余字段提升查询性能）？
5. 索引建议：哪些字段需要索引？

自然语言描述
    ↓ AI（Claude / GPT / Gemini）
图表代码（Mermaid / PlantUML / Structurizr DSL）
    ↓ 渲染引擎
可视化图表（SVG / PNG）
    ↓ 人工审查
修正后的图表
    ↓ 嵌入文档
Markdown / Confluence / Notion

# 使用 mcp-mermaid MCP Server
# 安装
npm install -g @anthropic/mcp-mermaid
 
# 在 Claude Code 中
> 请分析当前项目的架构，生成 Mermaid 组件图
> 请为 src/services/ 目录下的服务生成序列图，展示用户登录流程
> 请根据 schema.prisma 生成 ER 图

请为当前项目的 design.md 生成以下补充图表：
1. C4 Container 图
2. 核心 API 的序列图
3. 数据模型的 ER 图
4. 部署架构图

使用 Mermaid 语法，直接嵌入 design.md 中。

请为以下系统设计文档生成完整的图表集：

[粘贴 design.md 或架构描述]

请生成以下图表（全部使用 Mermaid 语法）：

1. **系统上下文图**（C4 Level 1）：系统与外部用户/系统的关系
2. **容器图**（C4 Level 2）：系统内部的服务、数据库、消息队列
3. **核心流程序列图**：[指定 2-3 个核心流程]
4. **数据模型 ER 图**：所有实体及其关系
5. **状态机图**：[指定有状态实体]
6. **部署架构图**：生产环境的部署拓扑
7. **数据流图**：数据从输入到存储到输出的路径

每个图表附带：
- 2-3 句说明
- 图表中的关键设计决策标注

## 系统架构
 
```mermaid
graph TD
    A[前端] --> B[API Gateway]
    B --> C[服务层]
    C --> D[(数据库)]
```
 
上图展示了系统的基本分层架构。前端通过 API Gateway 访问后端服务，
服务层负责业务逻辑处理，数据持久化到数据库。

# .github/workflows/plantuml.yml
name: Render PlantUML
on:
  push:
    paths:
      - 'docs/**/*.puml'
 
jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Render PlantUML
        uses: grassedge/generate-plantuml-action@v1
        with:
          path: docs
          message: "Render PlantUML diagrams"

以下是当前的架构图和最近的代码变更。请判断架构图是否需要更新：

当前架构图：
[粘贴 Mermaid/PlantUML 代码]

最近的代码变更：
[粘贴 git diff 或变更摘要]

请分析：
1. 变更是否影响了架构图中的组件或关系？
2. 如果需要更新，请输出更新后的图表代码
3. 如果不需要更新，请说明原因

# D2 架构图示例
direction: right

user: 用户 {
  shape: person
}

frontend: 前端 (React) {
  shape: rectangle
  style.fill: "#e1f5fe"
}

api: API Gateway {
  shape: rectangle
  style.fill: "#fff3e0"
}

services: 服务层 {
  user-svc: 用户服务
  order-svc: 订单服务
  product-svc: 商品服务
}

db: PostgreSQL {
  shape: cylinder
}

cache: Redis {
  shape: cylinder
  style.fill: "#fce4ec"
}

user -> frontend: HTTPS
frontend -> api: REST API
api -> services.user-svc
api -> services.order-svc
api -> services.product-svc
services.user-svc -> db
services.order-svc -> db
services.order-svc -> cache
services.product-svc -> db

系统：项目管理工具
用户角色：管理员、项目成员、访客
核心功能：工作空间管理、项目管理、任务看板（Todo/In Progress/Done）、
         任务分配、评论、通知、报表
技术栈：Next.js + PostgreSQL + Redis
部署：Vercel + Supabase

1. 将项目目录结构、package.json、docker-compose.yml 提供给 AI
2. AI 分析后生成：
   - 系统上下文图（识别出 3 个外部依赖）
   - 容器图（识别出 5 个服务 + 2 个数据库 + 1 个消息队列）
   - 核心服务的组件图
3. 将 Prisma schema 提供给 AI，生成 ER 图
4. 将核心 API 路由提供给 AI，生成关键流程的序列图
5. 人工审查所有图表，修正 AI 的推断错误
6. 将图表嵌入项目 README 和 docs/ 目录

1. 架构师用 AI 生成初始 Structurizr DSL 代码
2. DSL 文件存入 Git 仓库（docs/architecture/workspace.dsl）
3. CI/CD 中自动渲染为 SVG 并部署到内部文档站
4. 每次架构变更时：
   a. 开发者修改 DSL 文件
   b. AI 审查变更是否与代码一致
   c. PR 中自动生成图表预览
   d. 架构师审批后合并
5. 每月用 AI 扫描代码库，检查 DSL 是否需要更新