zhaojie
11eef49271
- 新增 .agents/summary/ 完整文档（架构、组件、接口、数据模型、流程、依赖） - 新增 AGENTS.md（AI 助手导航） - 更新 README.md - 修复 dashboard.html 租户模态框多余 </div> 导致保存按钮失效 - 更新 .gitignore 排除虚拟环境文件
110 lines
3.0 KiB
Markdown
110 lines
3.0 KiB
Markdown
# 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 和飞书长连接分别在守护线程中运行。
|