Files

zhaojie 11eef49271 docs: 添加项目文档体系 + 修复租户创建模态框

- 新增 .agents/summary/ 完整文档（架构、组件、接口、数据模型、流程、依赖）
- 新增 AGENTS.md（AI 助手导航）
- 更新 README.md
- 修复 dashboard.html 租户模态框多余 </div> 导致保存按钮失效
- 更新 .gitignore 排除虚拟环境文件

2026-04-08 23:26:17 +08:00

3.0 KiB

Raw Blame History

Architecture / 系统架构

整体架构

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 过滤实现数据隔离。

线程模型

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

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

3.0 KiB Raw Blame History Unescape Escape