funstat-mcp/docs/architecture_diagrams.md

# funstat BOT MCP 封装 - 架构流程图

## 1. 整体系统架构

```mermaid
graph TB
    subgraph "用户层"
        U1[用户 1]
        U2[用户 2]
        U3[用户 N...]
    end

    subgraph "Claude Code"
        C1[Claude Instance 1]
        C2[Claude Instance 2]
        C3[Claude Instance N]
    end

    subgraph "MCP Server"
        MCP[MCP 工具接口]
        Q[请求队列<br/>Rate Limiter]
        S[智能调度器]
        Cache[结果缓存<br/>Redis/内存]
    end

    subgraph "Telegram 客户端层"
        TC1[Telethon Client 1]
        TC2[Telethon Client 2]
        TC3[Telethon Client N]
    end

    subgraph "Telegram 生态"
        Bot[@openaiw_bot<br/>funstat/infostat]
    end

    U1 --> C1
    U2 --> C2
    U3 --> C3

    C1 --> MCP
    C2 --> MCP
    C3 --> MCP

    MCP --> Q
    Q --> S
    S --> Cache

    S --> TC1
    S --> TC2
    S --> TC3

    TC1 --> Bot
    TC2 --> Bot
    TC3 --> Bot

    Bot --> TC1
    Bot --> TC2
    Bot --> TC3

    TC1 --> S
    TC2 --> S
    TC3 --> S

    S --> Cache
    Cache --> MCP
    MCP --> C1
    MCP --> C2
    MCP --> C3

    style MCP fill:#e1f5ff
    style Q fill:#fff9c4
    style S fill:#c8e6c9
    style Cache fill:#ffccbc
    style Bot fill:#f3e5f5
```

---

## 2. 单次请求完整流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant C as Claude Code
    participant M as MCP Server
    participant RL as Rate Limiter
    participant Cache as 缓存
    participant TC as Telethon Client
    participant Bot as @openaiw_bot

    U->>C: 发起查询<br/>"搜索 python 群组"
    C->>M: openaiw_search_groups(query="python")

    M->>Cache: 检查缓存
    alt 缓存命中
        Cache-->>M: 返回缓存结果
        M-->>C: 返回结果
        C-->>U: 展示结果
    else 缓存未命中
        M->>RL: 请求令牌
        RL->>RL: 检查速率限制

        alt 未达到限制
            RL-->>M: 授予令牌
            M->>TC: send_message("/search python")
            TC->>Bot: 发送消息
            Bot->>Bot: 处理查询
            Bot-->>TC: 返回搜索结果
            TC-->>M: 解析响应
            M->>Cache: 存储结果
            M-->>C: 返回结果
            C-->>U: 展示结果
        else 达到限制
            RL->>RL: 等待令牌补充
            Note over RL: 等待 50-100ms
            RL-->>M: 授予令牌
            M->>TC: send_message("/search python")
            TC->>Bot: 发送消息
            Bot-->>TC: 返回结果
            TC-->>M: 解析响应
            M-->>C: 返回结果
            C-->>U: 展示结果
        end
    end
```

---

## 3. 批量并发请求处理流程

```mermaid
graph TB
    subgraph "并发请求"
        R1[请求 1<br/>搜索群组]
        R2[请求 2<br/>查询用户]
        R3[请求 3<br/>热门群组]
        R4[请求 N...]
    end

    subgraph "请求队列"
        Q[FIFO Queue<br/>最大 1000]
    end

    subgraph "速率限制器"
        RL[Token Bucket<br/>18 令牌/秒]
        T1[令牌 1]
        T2[令牌 2]
        T3[令牌 3]
    end

    subgraph "账号池"
        A1[账号 1<br/>空闲]
        A2[账号 2<br/>使用中]
        A3[账号 3<br/>空闲]
    end

    subgraph "负载均衡"
        LB{负载均衡器<br/>最少使用策略}
    end

    R1 --> Q
    R2 --> Q
    R3 --> Q
    R4 --> Q

    Q --> RL

    RL --> T1
    RL --> T2
    RL --> T3

    T1 --> LB
    T2 --> LB
    T3 --> LB

    LB --> A1
    LB --> A2
    LB --> A3

    A1 --> Bot1[@openaiw_bot]
    A2 --> Bot2[@openaiw_bot]
    A3 --> Bot3[@openaiw_bot]

    style Q fill:#fff9c4
    style RL fill:#c8e6c9
    style LB fill:#e1f5ff
    style Bot1 fill:#f3e5f5
    style Bot2 fill:#f3e5f5
    style Bot3 fill:#f3e5f5
```

---

## 4. 多账号负载均衡策略

```mermaid
stateDiagram-v2
    [*] --> 收到请求

    收到请求 --> 检查账号池

    检查账号池 --> 选择策略

    选择策略 --> 轮询: Round Robin
    选择策略 --> 最少使用: Least Used
    选择策略 --> 加权: Weighted

    轮询 --> 选择账号1
    最少使用 --> 检查使用率
    加权 --> 根据权重选择

    检查使用率 --> 选择最空闲账号

    选择账号1 --> 发送请求
    选择最空闲账号 --> 发送请求
    根据权重选择 --> 发送请求

    发送请求 --> 检查结果

    检查结果 --> 成功: 正常响应
    检查结果 --> FloodWait: Flood Wait 错误
    检查结果 --> 失败: 其他错误

    成功 --> 更新统计
    FloodWait --> 标记账号: 等待中
    失败 --> 故障转移

    故障转移 --> 选择下一个账号
    选择下一个账号 --> 发送请求

    标记账号 --> 选择其他账号
    选择其他账号 --> 发送请求

    更新统计 --> [*]
```

---

## 5. 限流与重试机制

```mermaid
flowchart TD
    Start[开始请求] --> CheckCache{检查缓存?}

    CheckCache -->|命中| ReturnCache[返回缓存结果]
    CheckCache -->|未命中| GetToken[获取令牌]

    GetToken --> HasToken{有令牌?}

    HasToken -->|是| SelectAccount[选择账号]
    HasToken -->|否| WaitToken[等待令牌<br/>50ms]

    WaitToken --> GetToken

    SelectAccount --> SendRequest[发送请求]

    SendRequest --> CheckResponse{检查响应}

    CheckResponse -->|成功| ParseResponse[解析响应]
    CheckResponse -->|FloodWait| HandleFlood{重试次数<3?}
    CheckResponse -->|网络错误| HandleError{重试次数<3?}
    CheckResponse -->|超时| HandleTimeout[返回超时提示]

    HandleFlood -->|是| WaitFlood[等待 Flood 时间]
    HandleFlood -->|否| ReturnError[返回错误]

    HandleError -->|是| RetryRequest[重试请求]
    HandleError -->|否| ReturnError

    WaitFlood --> RetryRequest
    RetryRequest --> SendRequest

    ParseResponse --> CacheResult[缓存结果]
    CacheResult --> ReturnResult[返回结果]

    ReturnCache --> End[结束]
    ReturnResult --> End
    ReturnError --> End
    HandleTimeout --> End

    style Start fill:#e1f5ff
    style End fill:#c8e6c9
    style CheckCache fill:#fff9c4
    style CacheResult fill:#ffccbc
```

---

## 6. 请求限制说明

### 单账号限制
- **速率**: ~18-20 请求/秒
- **队列**: 最多 100 个待处理请求
- **超时**: 20 秒无响应则超时

### 多账号限制（3 个账号）
- **总速率**: ~54-60 请求/秒
- **队列**: 最多 500 个待处理请求
- **故障转移**: 自动切换到其他账号

### 缓存机制
- **热门查询**: 缓存 1 小时
- **用户信息**: 缓存 24 小时
- **命中率**: 预计 30-40%

---

## 7. 普通用户调用方式

### 方式 1: 通过 Claude Code (推荐)

```
用户: 帮我搜索 "python" 相关的 Telegram 群组

Claude: [自动调用 openaiw_search_groups]
        查询中...

        找到以下群组：
        1. Python 学习交流群
        2. Python 开发者社区
        ...
```

### 方式 2: 通过 API 调用

```bash
curl -X POST http://localhost:8080/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python"}'
```

### 方式 3: 通过 Web 界面

```
访问: http://localhost:8080/web
输入查询 → 点击搜索 → 查看结果
```

---

## 8. 性能指标

| 配置 | 账号数 | 吞吐量 | 延迟 | 成本 |
|-----|-------|--------|------|------|
| 小规模 | 1 | 15-18 req/s | 1-2s | $5/月 |
| 中等 | 3 | 45-54 req/s | 1-3s | $15/月 |
| 大规模 | 10 | 150-180 req/s | 1-2s | $50/月 |