# Funstat BOT MCP 封装架构流程图

## 1. 整体系统架构图

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

    subgraph "Claude Code 层"
        C1[Claude Code 实例 1]
        C2[Claude Code 实例 2]
        C3[Claude Code 实例 N]
    end

    subgraph "MCP 服务器层"
        MCP[MCP Server]
        Queue[请求队列]
        Cache[结果缓存]
        RateLimit[速率限制器]
    end

    subgraph "Telegram 客户端层"
        T1[Telethon Client 1]
        T2[Telethon Client 2]
        T3[Telethon Client N]
    end

    subgraph "目标 BOT"
        BOT[@openaiw_bot]
    end

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

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

    MCP --> Queue
    Queue --> RateLimit
    RateLimit --> Cache
    Cache --> T1
    Cache --> T2
    Cache --> T3

    T1 --> BOT
    T2 --> BOT
    T3 --> BOT

    BOT -.响应.-> T1
    BOT -.响应.-> T2
    BOT -.响应.-> T3

    T1 -.结果.-> Cache
    T2 -.结果.-> Cache
    T3 -.结果.-> Cache

    Cache -.返回.-> MCP
    MCP -.返回.-> C1
    MCP -.返回.-> C2
    MCP -.返回.-> C3
```

## 2. 单次请求流程图

```mermaid
sequenceDiagram
    participant User as 普通用户
    participant Claude as Claude Code
    participant MCP as MCP Server
    participant Queue as 请求队列
    participant Rate as 速率限制
    participant Cache as 缓存层
    participant Tele as Telethon Client
    participant Bot as @openaiw_bot

    User->>Claude: "搜索 Python 相关群组"
    Claude->>MCP: funstat_search(query="python")

    MCP->>Cache: 检查缓存
    alt 缓存命中
        Cache-->>MCP: 返回缓存结果
        MCP-->>Claude: 返回结果
        Claude-->>User: 展示搜索结果
    else 缓存未命中
        MCP->>Queue: 加入请求队列
        Queue->>Rate: 检查速率限制

        alt 速率允许
            Rate->>Tele: 发送消息到 BOT
            Tele->>Bot: /search python
            Bot-->>Tele: 返回搜索结果
            Tele->>Cache: 保存到缓存
            Cache-->>MCP: 返回结果
            MCP-->>Claude: 返回结果
            Claude-->>User: 展示搜索结果
        else 超过限制
            Rate->>Queue: 延迟执行
            Queue-->>Rate: 等待后重试
            Rate->>Tele: 发送消息到 BOT
            Tele->>Bot: /search python
            Bot-->>Tele: 返回搜索结果
            Tele->>Cache: 保存到缓存
            Cache-->>MCP: 返回结果
            MCP-->>Claude: 返回结果
            Claude-->>User: 展示搜索结果
        end
    end
```

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

```mermaid
flowchart TD
    Start[收到多个请求] --> Queue{请求队列}
    Queue --> Check[检查当前速率]

    Check --> |速率<18/s| Exec[立即执行]
    Check --> |速率≥18/s| Wait[加入等待队列]

    Exec --> Cache1{检查缓存}
    Cache1 --> |命中| Return1[返回缓存结果]
    Cache1 --> |未命中| Send1[发送到 BOT]

    Send1 --> Receive1[接收 BOT 响应]
    Receive1 --> Save1[保存到缓存]
    Save1 --> Return2[返回结果]

    Wait --> Timer[定时器触发]
    Timer --> Check

    Return1 --> End[完成]
    Return2 --> End
```

## 4. 多账号负载均衡流程

```mermaid
flowchart TB
    Request[新请求] --> Balancer{负载均衡器}

    Balancer --> Check1{账号1状态}
    Balancer --> Check2{账号2状态}
    Balancer --> Check3{账号N状态}

    Check1 --> |可用且速率低| Select1[选择账号1]
    Check1 --> |不可用或速率高| Next1[检查下一个]

    Check2 --> |可用且速率低| Select2[选择账号2]
    Check2 --> |不可用或速率高| Next2[检查下一个]

    Check3 --> |可用且速率低| Select3[选择账号N]
    Check3 --> |不可用或速率高| Retry[重新均衡]

    Next1 --> Check2
    Next2 --> Check3
    Next3 --> Retry
    Retry --> Balancer

    Select1 --> Execute1[通过账号1发送]
    Select2 --> Execute2[通过账号2发送]
    Select3 --> Execute3[通过账号N发送]

    Execute1 --> BOT[@openaiw_bot]
    Execute2 --> BOT
    Execute3 --> BOT

    BOT --> Response[返回结果]
```

## 5. 限流与重试机制

```mermaid
stateDiagram-v2
    [*] --> Idle: 服务启动

    Idle --> Receiving: 收到请求
    Receiving --> RateCheck: 检查速率

    RateCheck --> Available: 速率OK
    RateCheck --> Limited: 超过限制

    Available --> Sending: 发送请求
    Limited --> Waiting: 加入等待队列

    Sending --> Success: BOT响应成功
    Sending --> Error: 请求失败

    Success --> Caching: 缓存结果
    Caching --> Idle: 返回结果

    Error --> Retry: 重试计数<3
    Error --> Failed: 重试计数≥3

    Retry --> Backoff: 指数退避
    Backoff --> Sending: 延迟后重试

    Failed --> Idle: 返回错误

    Waiting --> Timer: 定时器触发
    Timer --> RateCheck: 重新检查
```

## 6. Telegram 请求限制详解

```mermaid
graph LR
    subgraph "个人账号限制"
        P1[用户 → BOT<br/>18-20 msg/s]
        P2[用户 → 群组<br/>20-30 msg/s]
        P3[用户 → 私聊<br/>30 msg/s]
    end

    subgraph "BOT 账号限制"
        B1[BOT → 用户<br/>30 msg/s]
        B2[BOT → 群组<br/>20 msg/s]
        B3[BOT API<br/>限流严格]
    end

    subgraph "解决方案"
        S1[多账号池<br/>N×18 msg/s]
        S2[请求缓存<br/>+30-40%]
        S3[智能调度<br/>+20-30%]
    end

    P1 --> S1
    P2 --> S2
    P3 --> S3
```

## 7. MCP 工具调用示例

```mermaid
sequenceDiagram
    participant U as 用户
    participant C as Claude
    participant M as MCP funstat_search
    participant T as Telethon
    participant B as @openaiw_bot

    U->>C: "帮我找 Python 学习群组"

    Note over C: 理解用户意图
    C->>M: funstat_search(query="python", type="group")

    M->>T: 发送 /search python
    T->>B: /search python

    Note over B: 查询数据库
    B-->>T: 返回群组列表（JSON）
    T-->>M: 解析响应

    Note over M: 格式化结果
    M-->>C: 返回群组数据

    Note over C: 生成友好回复
    C-->>U: "我找到了以下 Python 学习群组：<br/>1. Python 编程学习...<br/>2. Python 数据科学..."
```

## 8. 推荐架构：单账号 + 队列

```mermaid
graph TB
    subgraph "前端"
        Users[多个普通用户]
    end

    subgraph "MCP 服务层"
        MCP[MCP Server]

        subgraph "核心组件"
            Queue[FIFO 队列]
            Rate[速率限制<br/>18 req/s]
            Cache[Redis 缓存<br/>TTL: 1h]
        end
    end

    subgraph "Telegram 层"
        Tele[Telethon Client<br/>1个账号]
    end

    subgraph "目标"
        Bot[@openaiw_bot<br/>funstat数据库]
    end

    Users -->|并发请求| MCP
    MCP --> Queue
    Queue -->|FIFO| Rate

    Rate -->|检查缓存| Cache
    Cache -->|未命中| Tele
    Cache -->|命中| MCP

    Tele -->|MTProto| Bot
    Bot -.响应.-> Tele
    Tele -.保存.-> Cache
    Tele -.返回.-> MCP

    MCP -.结果.-> Users

    style Rate fill:#f9f,stroke:#333,stroke-width:2px
    style Cache fill:#bbf,stroke:#333,stroke-width:2px
    style Tele fill:#bfb,stroke:#333,stroke-width:2px
```

---

## 性能指标总结

| 架构方案 | 吞吐量 | 响应时间 | 成本 | 复杂度 |
|---------|--------|---------|------|--------|
| 单账号 + 队列 | 15-18 req/s | 1-2s | $5/月 | 低 |
| 多账号池 (3个) | 45-54 req/s | 1-2s | $15/月 | 中 |
| 智能调度 (10个) | 150-180 req/s | 0.5-1s | $50/月 | 高 |

## 使用示例

### 用户视角
```
用户: "帮我搜索区块链相关群组"
Claude: [自动调用 MCP 工具]
       "我找到了以下区块链群组：
        1. 区块链技术交流 (50万成员)
        2. 加密货币投资 (30万成员)
        ..."
```

### MCP 工具定义
```json
{
  "name": "funstat_search",
  "description": "搜索 Telegram 群组、用户、消息",
  "parameters": {
    "query": "搜索关键词",
    "type": "group/user/message",
    "limit": 10
  }
}
```

---

**这些流程图完整展示了整个系统的架构设计！** 你可以把这个文档保存下来，或者我可以把它上传到 MrDoc。