LogoMermaid Kit
  • 功能
  • 价格
  • 博客
  • 路线图
使用 Mermaid 图表实现规范驱动开发
2025/12/01

使用 Mermaid 图表实现规范驱动开发

使用 Mermaid 图表实现规范驱动开发

引言

在现代软件开发中，规范驱动开发（Spec-Driven Development，简称 SDD）已经成为确保项目质量和团队协作效率的重要方法论。SDD 的核心理念是"先定义规范，再编写代码"——通过详细的规范文档明确系统需求、架构设计和接口定义，让开发过程有章可循。

然而，传统的文字规范文档往往存在几个痛点：

  • 理解成本高：纯文字描述难以快速把握系统全貌

  • 维护困难：规范更新时，文档容易与实际实现脱节

  • 协作不便：团队成员对同一份规范的理解可能存在偏差

这正是可视化规范的价值所在。通过图表将抽象的系统设计转化为直观的视觉呈现，我们可以大幅提升规范的可读性和可维护性。

为什么选择 Mermaid？

Mermaid 作为一款基于文本的图表生成工具，在规范驱动开发中具有独特优势：

  • 纯文本格式：图表以代码形式存在，可以直接嵌入 Markdown 文档

  • 版本控制友好：像管理代码一样管理图表，轻松追踪变更历史

  • 零依赖协作：团队成员无需专门的绘图工具，只需文本编辑器

  • 渲染一致性：在 GitHub、GitLab、Notion 等平台上都能正确显示

  • 学习成本低：语法简洁直观，上手快速

如果你想快速体验 Mermaid 的强大功能，可以访问 MermaidKit，这是一个专门为 Mermaid 图表设计的在线工具平台。

规范驱动开发流程概览

SDD 的核心理念

规范驱动开发强调在编码之前，通过详细的规范文档明确以下内容：

  1. 需求规范：用户需求、业务流程、功能边界

  2. 架构规范：系统架构、模块划分、技术选型

  3. 接口规范：API 定义、数据结构、交互协议

  4. 测试规范：测试用例、验收标准、质量指标

典型的 SDD 工作流程

让我们用 Mermaid 流程图来展示一个完整的 SDD 流程：

graph TB    Start([项目启动]) --> Requirements[需求分析与规范]    Requirements --> Architecture[架构设计与规范]    Architecture --> API[接口设计与规范]    API --> Review{规范评审}    Review -->|通过| Development[开发实现]    Review -->|需修改| Requirements    Development --> Testing[测试验证]    Testing --> Validate{是否符合规范}    Validate -->|是| Deploy[部署上线]    Validate -->|否| Development    Deploy --> End([项目完成])        style Requirements fill:#e1f5ff    style Architecture fill:#e1f5ff    style API fill:#e1f5ff    style Development fill:#fff4e1    style Testing fill:#ffe1e1

在这个流程中，每个阶段都可以通过 Mermaid 图表来可视化规范内容，确保团队对需求和设计有统一的认知。

Mermaid 在需求规范阶段的应用

需求规范是 SDD 的起点，清晰的需求可视化能够帮助团队准确理解业务目标。

用户旅程图（User Journey）

用户旅程图展示用户与系统交互的完整流程，帮助我们理解用户体验和关键触点。

journey    title 用户注册与登录流程    section 访问网站      打开首页: 5: 用户      浏览功能介绍: 4: 用户    section 注册账号      点击注册按钮: 5: 用户      填写注册信息: 3: 用户      验证邮箱: 3: 用户, 系统      注册成功: 5: 用户    section 首次登录      输入账号密码: 4: 用户      系统验证: 3: 系统      进入个人中心: 5: 用户

系统边界与流程（Flowchart）

流程图用于定义系统的功能边界和业务逻辑：

flowchart TD    User[用户] --> WebApp[Web 应用]    WebApp --> AuthService[认证服务]    WebApp --> BusinessService[业务服务]        AuthService --> Database[(用户数据库)]    BusinessService --> Database    BusinessService --> Cache[(Redis 缓存)]    BusinessService --> MessageQueue[消息队列]        MessageQueue --> EmailService[邮件服务]    MessageQueue --> NotificationService[通知服务]        subgraph "系统边界"        AuthService        BusinessService        Database        Cache        MessageQueue    end        subgraph "第三方服务"        EmailService        NotificationService    end

状态机设计（State Diagram）

对于具有复杂状态流转的功能，状态图是最佳选择：

stateDiagram-v2    [*] --> 未激活    未激活 --> 已激活: 邮箱验证成功    已激活 --> 正常使用: 首次登录    正常使用 --> 已冻结: 违规行为    正常使用 --> 已注销: 用户主动注销    已冻结 --> 正常使用: 申诉成功    已冻结 --> 已封禁: 严重违规    已注销 --> [*]    已封禁 --> [*]

Mermaid 在架构设计阶段的应用

架构设计规范需要清晰地展示系统的结构层次和组件关系。

系统架构图（Graph）

使用 Mermaid 的图形语法来展示系统的整体架构：

graph TB    subgraph "前端层"        WebUI[Web 界面]        MobileApp[移动应用]    end        subgraph "API 网关层"        Gateway[API Gateway]    end        subgraph "服务层"        UserService[用户服务]        OrderService[订单服务]        PaymentService[支付服务]        NotifyService[通知服务]    end        subgraph "数据层"        MySQL[(MySQL)]        Redis[(Redis)]        MongoDB[(MongoDB)]    end        subgraph "基础设施"        RabbitMQ[消息队列]        ElasticSearch[搜索引擎]    end        WebUI --> Gateway    MobileApp --> Gateway    Gateway --> UserService    Gateway --> OrderService    Gateway --> PaymentService        UserService --> MySQL    UserService --> Redis    OrderService --> MySQL    OrderService --> RabbitMQ    PaymentService --> MySQL        RabbitMQ --> NotifyService    NotifyService --> ElasticSearch

组件关系图（Class Diagram）

类图不仅适用于面向对象设计，也可以用来展示模块和组件的依赖关系：

classDiagram    class AuthenticationModule {        +login(credentials)        +logout()        +refreshToken()        +validateToken()    }        class UserModule {        +getProfile()        +updateProfile()        +deleteAccount()    }        class OrderModule {        +createOrder()        +getOrderList()        +cancelOrder()    }        class PaymentModule {        +processPayment()        +refund()        +getPaymentHistory()    }        class DatabaseAdapter {        +query()        +insert()        +update()        +delete()    }        class CacheAdapter {        +get()        +set()        +delete()        +expire()    }        AuthenticationModule --> DatabaseAdapter    AuthenticationModule --> CacheAdapter    UserModule --> DatabaseAdapter    UserModule --> CacheAdapter    OrderModule --> DatabaseAdapter    OrderModule --> PaymentModule    PaymentModule --> DatabaseAdapter

数据流图（Flowchart）

展示数据在系统中的流转过程：

flowchart LR    Client[客户端请求] --> Gateway[API 网关]    Gateway --> Auth{身份验证}    Auth -->|失败| Error401[返回 401]    Auth -->|成功| RateLimit{流量控制}    RateLimit -->|超限| Error429[返回 429]    RateLimit -->|通过| Router[路由分发]        Router --> Service[业务服务]    Service --> Cache{缓存查询}    Cache -->|命中| Response[返回结果]    Cache -->|未命中| Database[(数据库)]    Database --> UpdateCache[更新缓存]    UpdateCache --> Response        Response --> Logger[日志记录]    Logger --> Monitor[监控上报]    Monitor --> Client

Mermaid 在接口规范阶段的应用

接口规范是前后端协作的桥梁，清晰的接口文档能够大幅提升开发效率。

API 交互流程（Sequence Diagram）

序列图是展示 API 调用时序的最佳工具：

sequenceDiagram    participant Client as 客户端    participant Gateway as API 网关    participant Auth as 认证服务    participant User as 用户服务    participant DB as 数据库        Client->>Gateway: POST /api/login    activate Gateway    Gateway->>Auth: 验证凭证    activate Auth    Auth->>DB: 查询用户信息    activate DB    DB-->>Auth: 返回用户数据    deactivate DB        alt 验证成功        Auth->>Auth: 生成 JWT Token        Auth-->>Gateway: 返回 Token    else 验证失败        Auth-->>Gateway: 认证失败    end    deactivate Auth    deactivate Gateway        Note over Client,DB: 后续请求携带 Token        Client->>Gateway: GET /api/user/profile<br>Header: Authorization: Bearer {token}    activate Gateway    Gateway->>Auth: 验证 Token    activate Auth    Auth-->>Gateway: Token 有效    deactivate Auth    Gateway->>User: 获取用户信息    activate User    User->>DB: 查询数据    activate DB    DB-->>User: 返回数据    deactivate DB    User-->>Gateway: 用户信息    deactivate User    Gateway-->>Client: 200 OK + 用户数据    deactivate Gateway

状态转换（State Diagram）

订单或工单等具有状态流转的业务场景：

stateDiagram-v2    [*] --> 待支付: 创建订单        待支付 --> 已取消: 超时/用户取消    待支付 --> 待发货: 支付成功        待发货 --> 已取消: 用户申请退款    待发货 --> 待收货: 商家发货        待收货 --> 已完成: 确认收货    待收货 --> 退款中: 申请退货        退款中 --> 已退款: 退款成功    退款中 --> 待收货: 拒绝退款        已取消 --> [*]    已完成 --> [*]    已退款 --> [*]        note right of 待支付        15分钟内未支付        自动取消    end note        note right of 待收货        7天后自动        确认收货    end note

实体关系图（ER Diagram）

数据库设计和 API 数据模型的可视化：

erDiagram    USER ||--o{ ORDER : places    USER {        int user_id PK        string email UK        string username        string password_hash        datetime created_at        datetime updated_at    }        ORDER ||--|{ ORDER_ITEM : contains    ORDER {        int order_id PK        int user_id FK        decimal total_amount        string status        datetime created_at    }        ORDER_ITEM }o--|| PRODUCT : references    ORDER_ITEM {        int item_id PK        int order_id FK        int product_id FK        int quantity        decimal price    }        PRODUCT {        int product_id PK        string name        text description        decimal price        int stock    }        USER ||--o{ PAYMENT : makes    PAYMENT ||--|| ORDER : for    PAYMENT {        int payment_id PK        int order_id FK        int user_id FK        decimal amount        string method        string status        datetime paid_at    }

Mermaid 在开发与测试阶段的应用

开发和测试阶段同样需要清晰的规范指导。

测试用例流程（Flowchart）

将测试用例可视化，确保测试覆盖完整：

flowchart TD    Start([开始测试]) --> SetupEnv[准备测试环境]    SetupEnv --> CreateUser[创建测试用户]        CreateUser --> Test1{测试1: 正常登录}    Test1 -->|通过| Test2{测试2: 错误密码}    Test1 -->|失败| LogError1[记录错误]        Test2 -->|通过| Test3{测试3: 账号不存在}    Test2 -->|失败| LogError2[记录错误]        Test3 -->|通过| Test4{测试4: Token 刷新}    Test3 -->|失败| LogError3[记录错误]        Test4 -->|通过| Test5{测试5: 登出功能}    Test4 -->|失败| LogError4[记录错误]        Test5 -->|通过| Cleanup[清理测试数据]    Test5 -->|失败| LogError5[记录错误]        LogError1 --> Cleanup    LogError2 --> Cleanup    LogError3 --> Cleanup    LogError4 --> Cleanup    LogError5 --> Cleanup        Cleanup --> Report[生成测试报告]    Report --> End([测试完成])

项目时间线（Gantt Chart）

用甘特图规划开发和测试进度：

gantt    title 用户认证系统开发计划    dateFormat YYYY-MM-DD    section 需求与设计    需求分析           :done,    req1, 2024-01-01, 3d    架构设计           :done,    arch1, 2024-01-04, 3d    接口设计           :done,    api1, 2024-01-07, 2d    设计评审           :crit, done, review1, 2024-01-09, 1d        section 开发阶段    数据库设计         :active,  db1, 2024-01-10, 2d    用户模块开发       :         dev1, 2024-01-12, 4d    认证模块开发       :         dev2, 2024-01-14, 5d    API 网关集成      :         dev3, 2024-01-19, 3d        section 测试阶段    单元测试          :         test1, 2024-01-16, 6d    集成测试          :         test2, 2024-01-22, 3d    压力测试          :crit,    test3, 2024-01-25, 2d        section 上线部署    部署准备          :         deploy1, 2024-01-27, 2d    生产环境部署       :crit,    deploy2, 2024-01-29, 1d    上线验证          :         verify1, 2024-01-30, 1d

Git 分支策略（Git Graph）

可视化团队的 Git 工作流：

gitGraph    commit id: "初始化项目"    branch develop    checkout develop    commit id: "配置开发环境"        branch feature/user-module    checkout feature/user-module    commit id: "创建用户模型"    commit id: "实现用户 CRUD"        checkout develop    branch feature/auth-module    checkout feature/auth-module    commit id: "实现登录逻辑"    commit id: "实现 JWT 验证"        checkout develop    merge feature/user-module    commit id: "合并用户模块"        checkout feature/auth-module    commit id: "添加 Token 刷新"        checkout develop    merge feature/auth-module    commit id: "合并认证模块"        branch release/v1.0    checkout release/v1.0    commit id: "准备发布 v1.0"    commit id: "修复发布前 bug"        checkout main    merge release/v1.0 tag: "v1.0.0"        checkout develop    merge release/v1.0    commit id: "同步 main 修复"

完整的 SDD 项目实战：用户认证系统

让我们通过一个完整的用户认证系统项目，演示如何在整个 SDD 流程中运用 Mermaid 图表。

第一步：需求规范

需求概述：构建一个支持邮箱注册、登录、Token 刷新的认证系统。

用户旅程图已在前文展示，这里补充功能需求状态机：

stateDiagram-v2    [*] --> 未注册用户    未注册用户 --> 已注册未激活: 提交注册信息    已注册未激活 --> 已激活: 点击邮箱验证链接    已注册未激活 --> 未注册用户: 激活链接过期    已激活 --> 已登录: 输入正确凭证    已登录 --> 已激活: 登出    已登录 --> 已登录: 刷新 Token

第二步：架构设计

系统采用微服务架构，认证服务独立部署：

graph TB    subgraph "客户端"        WebClient[Web 前端]        MobileClient[移动端]    end        subgraph "网关层"        Gateway[Nginx + API Gateway]    end        subgraph "认证服务"        AuthAPI[认证 API]        TokenService[Token 服务]        EmailService[邮件服务]    end        subgraph "数据存储"        PostgreSQL[(PostgreSQL<br>用户数据)]        Redis[(Redis<br>Session & Token)]    end        WebClient --> Gateway    MobileClient --> Gateway    Gateway --> AuthAPI    AuthAPI --> TokenService    AuthAPI --> EmailService    AuthAPI --> PostgreSQL    TokenService --> Redis    EmailService --> Redis

第三步：接口设计

注册接口时序：

sequenceDiagram    participant C as 客户端    participant A as 认证服务    participant D as 数据库    participant R as Redis    participant E as 邮件服务        C->>A: POST /api/auth/register<br>{email, password, username}    activate A    A->>D: 检查邮箱是否已存在    activate D    D-->>A: 邮箱未注册    deactivate D        A->>A: 生成密码哈希    A->>D: 插入用户记录 (status=inactive)    activate D    D-->>A: 用户创建成功    deactivate D        A->>A: 生成激活 Token    A->>R: 存储激活 Token (TTL=24h)    activate R    R-->>A: 存储成功    deactivate R        A->>E: 发送激活邮件    activate E    E-->>A: 发送成功    deactivate E        A-->>C: 201 Created<br>{message: "请检查邮箱激活账号"}    deactivate A

数据模型：

erDiagram    USERS {        uuid id PK        string email UK        string username        string password_hash        enum status        timestamp email_verified_at        timestamp created_at        timestamp updated_at    }        SESSIONS {        uuid session_id PK        uuid user_id FK        string access_token        string refresh_token        timestamp expires_at        timestamp created_at    }        USERS ||--o{ SESSIONS : has

第四步：开发实现

核心认证流程：

flowchart TD    Start[接收登录请求] --> ValidateInput{验证输入格式}    ValidateInput -->|无效| Return400[返回 400 错误]    ValidateInput -->|有效| QueryUser[查询用户]        QueryUser --> UserExists{用户是否存在}    UserExists -->|否| Return401[返回 401 错误]    UserExists -->|是| CheckPassword{验证密码}        CheckPassword -->|错误| Return401    CheckPassword -->|正确| CheckStatus{检查账号状态}        CheckStatus -->|未激活| Return403[返回 403 错误]    CheckStatus -->|已封禁| Return403    CheckStatus -->|正常| GenerateTokens[生成 Tokens]        GenerateTokens --> StoreSession[存储 Session]    StoreSession --> Return200[返回 200 + Tokens]        Return400 --> End[结束]    Return401 --> End    Return403 --> End    Return200 --> End

第五步：测试验证

测试用例覆盖：

mindmap  root((认证系统测试))    注册功能      正常注册流程      邮箱已存在      密码强度验证      邮件发送验证    登录功能      正确凭证登录      错误密码      账号不存在      未激活账号      已封禁账号    Token 管理      Access Token 验证      Refresh Token 刷新      Token 过期处理      并发 Token 请求    安全测试      SQL 注入防护      XSS 防护      暴力破解防护      CSRF 防护

第六步：部署上线

部署架构：

graph TB    subgraph "负载均衡"        LB[Load Balancer]    end        subgraph "应用服务器"        App1[Auth Service - 1]        App2[Auth Service - 2]        App3[Auth Service - 3]    end        subgraph "数据库集群"        Primary[(PostgreSQL<br>Primary)]        Replica1[(PostgreSQL<br>Replica 1)]        Replica2[(PostgreSQL<br>Replica 2)]    end        subgraph "缓存集群"        RedisM[(Redis Master)]        RedisS1[(Redis Slave 1)]        RedisS2[(Redis Slave 2)]    end        LB --> App1    LB --> App2    LB --> App3        App1 --> Primary    App2 --> Primary    App3 --> Primary        Primary --> Replica1    Primary --> Replica2        App1 --> RedisM    App2 --> RedisM    App3 --> RedisM        RedisM --> RedisS1    RedisM --> RedisS2

通过这个完整的项目案例，我们可以看到 Mermaid 如何贯穿 SDD 的全流程，从需求到部署，每个阶段都有对应的可视化图表支撑。

总结

规范驱动开发结合 Mermaid 图表，为我们提供了一套高效、可维护的软件开发方法论：

  1. 降低沟通成本：图表比文字更直观，减少理解偏差

  2. 提升协作效率：纯文本格式便于版本控制和团队协作

  3. 保障开发质量：清晰的规范指导开发，减少返工

  4. 便于知识传承：可视化的文档更易于新成员理解

在实践中，建议将 Mermaid 图表嵌入到项目的文档系统中（如 README.md、Wiki 等），让规范"活"在代码仓库里，随代码一起演进。

如果你希望更高效地创建和管理 Mermaid 图表，不妨访问 MermaidKit，体验专为 Mermaid 设计的可视化编辑和协作功能。让我们一起用可视化的方式，构建更优质的软件系统！

全部文章

作者

avatar for Henry
Henry

分类

  • 最佳实践
引言为什么选择 Mermaid？规范驱动开发流程概览SDD 的核心理念典型的 SDD 工作流程Mermaid 在需求规范阶段的应用用户旅程图（User Journey）系统边界与流程（Flowchart）状态机设计（State Diagram）Mermaid 在架构设计阶段的应用系统架构图（Graph）组件关系图（Class Diagram）数据流图（Flowchart）Mermaid 在接口规范阶段的应用API 交互流程（Sequence Diagram）状态转换（State Diagram）实体关系图（ER Diagram）Mermaid 在开发与测试阶段的应用测试用例流程（Flowchart）项目时间线（Gantt Chart）Git 分支策略（Git Graph）完整的 SDD 项目实战：用户认证系统第一步：需求规范第二步：架构设计第三步：接口设计第四步：开发实现第五步：测试验证第六步：部署上线总结
LogoMermaid Kit

几分钟搞定你的 Mermaid 架构图

Email
产品
  • 功能
  • 价格
  • 常见问题
公司
  • 关于我们
  • 联系我们
  • 邮件列表
法律
  • Cookie政策
  • 隐私政策
  • 服务条款
© 2026 Mermaid Kit All Rights Reserved.
英语中文日语中文（台湾）
graph TB
    Start([项目启动]) --> Requirements[需求分析与规范]
    Requirements --> Architecture[架构设计与规范]
    Architecture --> API[接口设计与规范]
    API --> Review{规范评审}
    Review -->|通过| Development[开发实现]
    Review -->|需修改| Requirements
    Development --> Testing[测试验证]
    Testing --> Validate{是否符合规范}
    Validate -->|是| Deploy[部署上线]
    Validate -->|否| Development
    Deploy --> End([项目完成])
    
    style Requirements fill:#e1f5ff
    style Architecture fill:#e1f5ff
    style API fill:#e1f5ff
    style Development fill:#fff4e1
    style Testing fill:#ffe1e1
journey
    title 用户注册与登录流程
    section 访问网站
      打开首页: 5: 用户
      浏览功能介绍: 4: 用户
    section 注册账号
      点击注册按钮: 5: 用户
      填写注册信息: 3: 用户
      验证邮箱: 3: 用户, 系统
      注册成功: 5: 用户
    section 首次登录
      输入账号密码: 4: 用户
      系统验证: 3: 系统
      进入个人中心: 5: 用户
flowchart TD
    User[用户] --> WebApp[Web 应用]
    WebApp --> AuthService[认证服务]
    WebApp --> BusinessService[业务服务]
    
    AuthService --> Database[(用户数据库)]
    BusinessService --> Database
    BusinessService --> Cache[(Redis 缓存)]
    BusinessService --> MessageQueue[消息队列]
    
    MessageQueue --> EmailService[邮件服务]
    MessageQueue --> NotificationService[通知服务]
    
    subgraph "系统边界"
        AuthService
        BusinessService
        Database
        Cache
        MessageQueue
    end
    
    subgraph "第三方服务"
        EmailService
        NotificationService
    end
stateDiagram-v2
    [*] --> 未激活
    未激活 --> 已激活: 邮箱验证成功
    已激活 --> 正常使用: 首次登录
    正常使用 --> 已冻结: 违规行为
    正常使用 --> 已注销: 用户主动注销
    已冻结 --> 正常使用: 申诉成功
    已冻结 --> 已封禁: 严重违规
    已注销 --> [*]
    已封禁 --> [*]
graph TB
    subgraph "前端层"
        WebUI[Web 界面]
        MobileApp[移动应用]
    end
    
    subgraph "API 网关层"
        Gateway[API Gateway]
    end
    
    subgraph "服务层"
        UserService[用户服务]
        OrderService[订单服务]
        PaymentService[支付服务]
        NotifyService[通知服务]
    end
    
    subgraph "数据层"
        MySQL[(MySQL)]
        Redis[(Redis)]
        MongoDB[(MongoDB)]
    end
    
    subgraph "基础设施"
        RabbitMQ[消息队列]
        ElasticSearch[搜索引擎]
    end
    
    WebUI --> Gateway
    MobileApp --> Gateway
    Gateway --> UserService
    Gateway --> OrderService
    Gateway --> PaymentService
    
    UserService --> MySQL
    UserService --> Redis
    OrderService --> MySQL
    OrderService --> RabbitMQ
    PaymentService --> MySQL
    
    RabbitMQ --> NotifyService
    NotifyService --> ElasticSearch
classDiagram
    class AuthenticationModule {
        +login(credentials)
        +logout()
        +refreshToken()
        +validateToken()
    }
    
    class UserModule {
        +getProfile()
        +updateProfile()
        +deleteAccount()
    }
    
    class OrderModule {
        +createOrder()
        +getOrderList()
        +cancelOrder()
    }
    
    class PaymentModule {
        +processPayment()
        +refund()
        +getPaymentHistory()
    }
    
    class DatabaseAdapter {
        +query()
        +insert()
        +update()
        +delete()
    }
    
    class CacheAdapter {
        +get()
        +set()
        +delete()
        +expire()
    }
    
    AuthenticationModule --> DatabaseAdapter
    AuthenticationModule --> CacheAdapter
    UserModule --> DatabaseAdapter
    UserModule --> CacheAdapter
    OrderModule --> DatabaseAdapter
    OrderModule --> PaymentModule
    PaymentModule --> DatabaseAdapter
flowchart LR
    Client[客户端请求] --> Gateway[API 网关]
    Gateway --> Auth{身份验证}
    Auth -->|失败| Error401[返回 401]
    Auth -->|成功| RateLimit{流量控制}
    RateLimit -->|超限| Error429[返回 429]
    RateLimit -->|通过| Router[路由分发]
    
    Router --> Service[业务服务]
    Service --> Cache{缓存查询}
    Cache -->|命中| Response[返回结果]
    Cache -->|未命中| Database[(数据库)]
    Database --> UpdateCache[更新缓存]
    UpdateCache --> Response
    
    Response --> Logger[日志记录]
    Logger --> Monitor[监控上报]
    Monitor --> Client
sequenceDiagram
    participant Client as 客户端
    participant Gateway as API 网关
    participant Auth as 认证服务
    participant User as 用户服务
    participant DB as 数据库
    
    Client->>Gateway: POST /api/login
    activate Gateway
    Gateway->>Auth: 验证凭证
    activate Auth
    Auth->>DB: 查询用户信息
    activate DB
    DB-->>Auth: 返回用户数据
    deactivate DB
    
    alt 验证成功
        Auth->>Auth: 生成 JWT Token
        Auth-->>Gateway: 返回 Token
    else 验证失败
        Auth-->>Gateway: 认证失败
    end
    deactivate Auth
    deactivate Gateway
    
    Note over Client,DB: 后续请求携带 Token
    
    Client->>Gateway: GET /api/user/profile<br>Header: Authorization: Bearer {token}
    activate Gateway
    Gateway->>Auth: 验证 Token
    activate Auth
    Auth-->>Gateway: Token 有效
    deactivate Auth
    Gateway->>User: 获取用户信息
    activate User
    User->>DB: 查询数据
    activate DB
    DB-->>User: 返回数据
    deactivate DB
    User-->>Gateway: 用户信息
    deactivate User
    Gateway-->>Client: 200 OK + 用户数据
    deactivate Gateway
stateDiagram-v2
    [*] --> 待支付: 创建订单
    
    待支付 --> 已取消: 超时/用户取消
    待支付 --> 待发货: 支付成功
    
    待发货 --> 已取消: 用户申请退款
    待发货 --> 待收货: 商家发货
    
    待收货 --> 已完成: 确认收货
    待收货 --> 退款中: 申请退货
    
    退款中 --> 已退款: 退款成功
    退款中 --> 待收货: 拒绝退款
    
    已取消 --> [*]
    已完成 --> [*]
    已退款 --> [*]
    
    note right of 待支付
        15分钟内未支付
        自动取消
    end note
    
    note right of 待收货
        7天后自动
        确认收货
    end note
erDiagram
    USER ||--o{ ORDER : places
    USER {
        int user_id PK
        string email UK
        string username
        string password_hash
        datetime created_at
        datetime updated_at
    }
    
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER {
        int order_id PK
        int user_id FK
        decimal total_amount
        string status
        datetime created_at
    }
    
    ORDER_ITEM }o--|| PRODUCT : references
    ORDER_ITEM {
        int item_id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal price
    }
    
    PRODUCT {
        int product_id PK
        string name
        text description
        decimal price
        int stock
    }
    
    USER ||--o{ PAYMENT : makes
    PAYMENT ||--|| ORDER : for
    PAYMENT {
        int payment_id PK
        int order_id FK
        int user_id FK
        decimal amount
        string method
        string status
        datetime paid_at
    }
flowchart TD
    Start([开始测试]) --> SetupEnv[准备测试环境]
    SetupEnv --> CreateUser[创建测试用户]
    
    CreateUser --> Test1{测试1: 正常登录}
    Test1 -->|通过| Test2{测试2: 错误密码}
    Test1 -->|失败| LogError1[记录错误]
    
    Test2 -->|通过| Test3{测试3: 账号不存在}
    Test2 -->|失败| LogError2[记录错误]
    
    Test3 -->|通过| Test4{测试4: Token 刷新}
    Test3 -->|失败| LogError3[记录错误]
    
    Test4 -->|通过| Test5{测试5: 登出功能}
    Test4 -->|失败| LogError4[记录错误]
    
    Test5 -->|通过| Cleanup[清理测试数据]
    Test5 -->|失败| LogError5[记录错误]
    
    LogError1 --> Cleanup
    LogError2 --> Cleanup
    LogError3 --> Cleanup
    LogError4 --> Cleanup
    LogError5 --> Cleanup
    
    Cleanup --> Report[生成测试报告]
    Report --> End([测试完成])
gantt
    title 用户认证系统开发计划
    dateFormat YYYY-MM-DD
    section 需求与设计
    需求分析           :done,    req1, 2024-01-01, 3d
    架构设计           :done,    arch1, 2024-01-04, 3d
    接口设计           :done,    api1, 2024-01-07, 2d
    设计评审           :crit, done, review1, 2024-01-09, 1d
    
    section 开发阶段
    数据库设计         :active,  db1, 2024-01-10, 2d
    用户模块开发       :         dev1, 2024-01-12, 4d
    认证模块开发       :         dev2, 2024-01-14, 5d
    API 网关集成      :         dev3, 2024-01-19, 3d
    
    section 测试阶段
    单元测试          :         test1, 2024-01-16, 6d
    集成测试          :         test2, 2024-01-22, 3d
    压力测试          :crit,    test3, 2024-01-25, 2d
    
    section 上线部署
    部署准备          :         deploy1, 2024-01-27, 2d
    生产环境部署       :crit,    deploy2, 2024-01-29, 1d
    上线验证          :         verify1, 2024-01-30, 1d
gitGraph
    commit id: "初始化项目"
    branch develop
    checkout develop
    commit id: "配置开发环境"
    
    branch feature/user-module
    checkout feature/user-module
    commit id: "创建用户模型"
    commit id: "实现用户 CRUD"
    
    checkout develop
    branch feature/auth-module
    checkout feature/auth-module
    commit id: "实现登录逻辑"
    commit id: "实现 JWT 验证"
    
    checkout develop
    merge feature/user-module
    commit id: "合并用户模块"
    
    checkout feature/auth-module
    commit id: "添加 Token 刷新"
    
    checkout develop
    merge feature/auth-module
    commit id: "合并认证模块"
    
    branch release/v1.0
    checkout release/v1.0
    commit id: "准备发布 v1.0"
    commit id: "修复发布前 bug"
    
    checkout main
    merge release/v1.0 tag: "v1.0.0"
    
    checkout develop
    merge release/v1.0
    commit id: "同步 main 修复"
stateDiagram-v2
    [*] --> 未注册用户
    未注册用户 --> 已注册未激活: 提交注册信息
    已注册未激活 --> 已激活: 点击邮箱验证链接
    已注册未激活 --> 未注册用户: 激活链接过期
    已激活 --> 已登录: 输入正确凭证
    已登录 --> 已激活: 登出
    已登录 --> 已登录: 刷新 Token
graph TB
    subgraph "客户端"
        WebClient[Web 前端]
        MobileClient[移动端]
    end
    
    subgraph "网关层"
        Gateway[Nginx + API Gateway]
    end
    
    subgraph "认证服务"
        AuthAPI[认证 API]
        TokenService[Token 服务]
        EmailService[邮件服务]
    end
    
    subgraph "数据存储"
        PostgreSQL[(PostgreSQL<br>用户数据)]
        Redis[(Redis<br>Session & Token)]
    end
    
    WebClient --> Gateway
    MobileClient --> Gateway
    Gateway --> AuthAPI
    AuthAPI --> TokenService
    AuthAPI --> EmailService
    AuthAPI --> PostgreSQL
    TokenService --> Redis
    EmailService --> Redis
sequenceDiagram
    participant C as 客户端
    participant A as 认证服务
    participant D as 数据库
    participant R as Redis
    participant E as 邮件服务
    
    C->>A: POST /api/auth/register<br>{email, password, username}
    activate A
    A->>D: 检查邮箱是否已存在
    activate D
    D-->>A: 邮箱未注册
    deactivate D
    
    A->>A: 生成密码哈希
    A->>D: 插入用户记录 (status=inactive)
    activate D
    D-->>A: 用户创建成功
    deactivate D
    
    A->>A: 生成激活 Token
    A->>R: 存储激活 Token (TTL=24h)
    activate R
    R-->>A: 存储成功
    deactivate R
    
    A->>E: 发送激活邮件
    activate E
    E-->>A: 发送成功
    deactivate E
    
    A-->>C: 201 Created<br>{message: "请检查邮箱激活账号"}
    deactivate A
erDiagram
    USERS {
        uuid id PK
        string email UK
        string username
        string password_hash
        enum status
        timestamp email_verified_at
        timestamp created_at
        timestamp updated_at
    }
    
    SESSIONS {
        uuid session_id PK
        uuid user_id FK
        string access_token
        string refresh_token
        timestamp expires_at
        timestamp created_at
    }
    
    USERS ||--o{ SESSIONS : has
flowchart TD
    Start[接收登录请求] --> ValidateInput{验证输入格式}
    ValidateInput -->|无效| Return400[返回 400 错误]
    ValidateInput -->|有效| QueryUser[查询用户]
    
    QueryUser --> UserExists{用户是否存在}
    UserExists -->|否| Return401[返回 401 错误]
    UserExists -->|是| CheckPassword{验证密码}
    
    CheckPassword -->|错误| Return401
    CheckPassword -->|正确| CheckStatus{检查账号状态}
    
    CheckStatus -->|未激活| Return403[返回 403 错误]
    CheckStatus -->|已封禁| Return403
    CheckStatus -->|正常| GenerateTokens[生成 Tokens]
    
    GenerateTokens --> StoreSession[存储 Session]
    StoreSession --> Return200[返回 200 + Tokens]
    
    Return400 --> End[结束]
    Return401 --> End
    Return403 --> End
    Return200 --> End
mindmap
  root((认证系统测试))
    注册功能
      正常注册流程
      邮箱已存在
      密码强度验证
      邮件发送验证
    登录功能
      正确凭证登录
      错误密码
      账号不存在
      未激活账号
      已封禁账号
    Token 管理
      Access Token 验证
      Refresh Token 刷新
      Token 过期处理
      并发 Token 请求
    安全测试
      SQL 注入防护
      XSS 防护
      暴力破解防护
      CSRF 防护
graph TB
    subgraph "负载均衡"
        LB[Load Balancer]
    end
    
    subgraph "应用服务器"
        App1[Auth Service - 1]
        App2[Auth Service - 2]
        App3[Auth Service - 3]
    end
    
    subgraph "数据库集群"
        Primary[(PostgreSQL<br>Primary)]
        Replica1[(PostgreSQL<br>Replica 1)]
        Replica2[(PostgreSQL<br>Replica 2)]
    end
    
    subgraph "缓存集群"
        RedisM[(Redis Master)]
        RedisS1[(Redis Slave 1)]
        RedisS2[(Redis Slave 2)]
    end
    
    LB --> App1
    LB --> App2
    LB --> App3
    
    App1 --> Primary
    App2 --> Primary
    App3 --> Primary
    
    Primary --> Replica1
    Primary --> Replica2
    
    App1 --> RedisM
    App2 --> RedisM
    App3 --> RedisM
    
    RedisM --> RedisS1
    RedisM --> RedisS2