# Architecture / 系统架构

## 整体架构

```mermaid
graph TB
    subgraph Clients["客户端"]
        Browser["浏览器 Dashboard"]
        FeishuBot["飞书机器人"]
        WSClient["WebSocket 客户端"]
    end

    subgraph EntryPoints["入口层"]
        Flask["Flask App :5000"]
        WS["WebSocket Server :8765"]
        FeishuLC["飞书长连接服务"]
    end

    subgraph WebLayer["Web 层"]
        Blueprints["16 个 Flask Blueprints"]
        Decorators["装饰器: handle_errors, require_json, resolve_tenant_id, rate_limit"]
        SM["ServiceManager (懒加载)"]
    end

    subgraph BusinessLayer["业务层"]
        DM["DialogueManager"]
        RCM["RealtimeChatManager"]
        KM["KnowledgeManager"]
        WOS["WorkOrderSyncService"]
        Agent["ReactAgent"]
        AM["AnalyticsManager"]
        AS["AlertSystem"]
    end

    subgraph CoreLayer["基础设施层"]
        DB["DatabaseManager (SQLAlchemy)"]
        LLM["LLMClient (Qwen API)"]
        Cache["CacheManager (Redis)"]
        Auth["AuthManager (JWT)"]
        Embed["EmbeddingClient (可选)"]
    end

    subgraph External["外部服务"]
        QwenAPI["Qwen/DashScope API"]
        FeishuAPI["飞书 API"]
        RedisServer["Redis"]
        Database["MySQL / SQLite"]
    end

    Browser --> Flask
    WSClient --> WS
    FeishuBot --> FeishuLC

    Flask --> Blueprints
    Blueprints --> Decorators
    Blueprints --> SM
    SM --> BusinessLayer

    WS --> RCM
    FeishuLC --> DM

    DM --> LLM
    DM --> KM
    RCM --> DM
    Agent --> LLM
    KM --> Embed
    WOS --> FeishuAPI

    DB --> Database
    LLM --> QwenAPI
    Cache --> RedisServer
```

## 架构模式

### Singleton Managers
核心服务均为单例模式：`DatabaseManager`, `ServiceManager`, `UnifiedConfig`。通过 `get_config()` / `db_manager` 全局访问。

### Blueprint-per-Domain
每个功能域一个 Flask Blueprint，共 16 个：
`workorders`, `alerts`, `knowledge`, `conversations`, `chat`, `agent`, `tenants`, `auth`, `analytics`, `monitoring`, `system`, `feishu_sync`, `feishu_bot`, `vehicle`, `core`, `test`

### Service Manager with Lazy Loading
`ServiceManager` 提供线程安全的懒初始化。Blueprint 通过它获取业务服务实例，避免循环导入和启动时的重量级初始化。

### Decorator-Driven API
通用横切关注点通过装饰器实现：
- `@handle_errors` — 统一异常处理
- `@require_json` — JSON 请求验证
- `@resolve_tenant_id` — 从请求中提取 tenant_id
- `@rate_limit` — 频率限制
- `@cache_response` — 响应缓存

### Multi-Tenant by Convention
所有核心表包含 `tenant_id` 字段，查询时按 tenant_id 过滤实现数据隔离。

## 线程模型

```mermaid
graph LR
    Main["主线程: Flask App"] 
    T1["守护线程: WebSocket Server"]
    T2["守护线程: 飞书长连接"]
    
    Main --> T1
    Main --> T2
```

`start_dashboard.py` 在主线程运行 Flask，WebSocket 和飞书长连接分别在守护线程中运行。