# mdBook 文档编写与 Mermaid 使用指南

## 📝 文档编写基础

### 1. 添加新章节

在 `src/SUMMARY.md` 中添加章节链接：

```markdown
- [章节标题](./路径/文件.md)
    - [子章节](./子章节.md)
```

### 2. 创建 Markdown 文件

在 `src/` 目录下创建对应的 `.md` 文件，使用标准的 Markdown 语法编写。

### 3. 常用命令

```bash
# 构建文档
mdbook build

# 启动本地预览服务器（支持热重载）
mdbook serve

# 清理构建文件
mdbook clean
```

## 🎨 Mermaid 图表使用

Mermaid 已经成功安装并配置！你可以在任何 Markdown 文件中使用以下图表类型：

### 1. 流程图 (Flowchart)

````markdown
```mermaid
graph TD
    A[开始] --> B{是否登录?}
    B -->|是| C[显示主页]
    B -->|否| D[跳转登录页]
    C --> E[结束]
    D --> E
```
````

### 2. 时序图 (Sequence Diagram)

````markdown
```mermaid
sequenceDiagram
    participant 用户
    participant 前端
    participant 后端
    participant 数据库
    
    用户->>前端: 发起请求
    前端->>后端: API 调用
    后端->>数据库: 查询数据
    数据库-->>后端: 返回结果
    后端-->>前端: JSON 响应
    前端-->>用户: 渲染页面
```
````

### 3. 类图 (Class Diagram)

````markdown
```mermaid
classDiagram
    class OakObject {
        +String id
        +Date createdAt
        +save()
        +delete()
    }
    
    class User {
        +String name
        +String email
        +login()
    }
    
    class Post {
        +String title
        +String content
    }
    
    OakObject <|-- User
    OakObject <|-- Post
    User "1" --> "*" Post : 发布
```
````

### 4. 状态图 (State Diagram)

````markdown
```mermaid
stateDiagram-v2
    [*] --> 草稿
    草稿 --> 审核中: 提交审核
    审核中 --> 已发布: 审核通过
    审核中 --> 草稿: 审核拒绝
    已发布 --> 已归档: 归档
    已归档 --> [*]
```
````

### 5. 甘特图 (Gantt Chart)

````markdown
```mermaid
gantt
    title Oak 项目开发计划
    dateFormat  YYYY-MM-DD
    section 设计阶段
    需求分析           :done,    des1, 2025-01-01, 2025-01-15
    系统设计           :active,  des2, 2025-01-10, 2025-01-30
    section 开发阶段
    后端开发           :         dev1, 2025-02-01, 30d
    前端开发           :         dev2, 2025-02-15, 25d
    section 测试阶段
    单元测试           :         test1, after dev1, 10d
    集成测试           :         test2, after dev2, 15d
```
````

### 6. 饼图 (Pie Chart)

````markdown
```mermaid
pie title 技术栈分布
    "TypeScript" : 45
    "React" : 25
    "Node.js" : 20
    "MySQL" : 10
```
````

### 7. ER 图 (Entity Relationship Diagram)

````markdown
```mermaid
erDiagram
    USER ||--o{ POST : 发布
    USER {
        string id PK
        string name
        string email
    }
    POST ||--|{ COMMENT : 包含
    POST {
        string id PK
        string title
        string content
        string userId FK
    }
    COMMENT {
        string id PK
        string content
        string postId FK
        string userId FK
    }
    USER ||--o{ COMMENT : 评论
```
````

### 8. Git 图 (Git Graph)

````markdown
```mermaid
gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    branch feature
    checkout feature
    commit
    checkout main
    merge feature
```
````

## 🚀 完整示例

创建一个新的章节来展示 Oak 架构：

**在 SUMMARY.md 中添加：**
```markdown
- [Oak 架构设计](./architecture.md)
```

**创建 src/architecture.md：**

````markdown
# Oak 架构设计

## 系统架构图

```mermaid
graph TB
    subgraph 前端层
        A[React 组件] --> B[Oak Client SDK]
    end
    
    subgraph 应用层
        B --> C[API Gateway]
        C --> D[业务逻辑层]
        D --> E[对象模型层]
    end
    
    subgraph 数据层
        E --> F[(MySQL)]
        E --> G[(MongoDB)]
    end
    
    subgraph 基础设施
        H[权限系统]
        I[日志系统]
        J[缓存系统]
    end
    
    D --> H
    D --> I
    D --> J
```

## 请求处理流程

```mermaid
sequenceDiagram
    participant C as 客户端
    participant A as API Gateway
    participant B as 业务层
    participant D as 数据库
    
    C->>A: HTTP 请求
    A->>A: 验证权限
    A->>B: 调用业务逻辑
    B->>B: 数据验证
    B->>D: 执行查询
    D-->>B: 返回数据
    B->>B: 业务处理
    B-->>A: 返回结果
    A-->>C: JSON 响应
```
````

## 💡 提示与技巧

1. **实时预览**：运行 `mdbook serve`，在浏览器中打开 `http://localhost:3000`，编辑后会自动刷新

2. **图表样式**：Mermaid 支持主题配置，可以在 `book.toml` 中添加：
```toml
[output.html.mermaid]
theme = "default"  # 可选: default, dark, forest, neutral
```

3. **图表方向**：
   - `graph TD` 或 `graph TB`：从上到下
   - `graph LR`：从左到右
   - `graph RL`：从右到左
   - `graph BT`：从下到上

4. **节点形状**：
   - `[矩形]`
   - `(圆角矩形)`
   - `{菱形}`
   - `((圆形))`
   - `[[子程序]]`
   - `[(圆柱)]`

5. **在线编辑器**：使用 [Mermaid Live Editor](https://mermaid.live/) 在线测试图表

## 📚 更多资源

- [mdBook 官方文档](https://rust-lang.github.io/mdBook/)
- [Mermaid 官方文档](https://mermaid.js.org/)
- [mdbook-mermaid 仓库](https://github.com/badboy/mdbook-mermaid)