docs: 添加项目文档体系 + 修复租户创建模态框
- 新增 .agents/summary/ 完整文档（架构、组件、接口、数据模型、流程、依赖） - 新增 AGENTS.md（AI 助手导航） - 更新 README.md - 修复 dashboard.html 租户模态框多余 </div> 导致保存按钮失效 - 更新 .gitignore 排除虚拟环境文件
This commit is contained in:
109
.agents/summary/architecture.md
Normal file
109
.agents/summary/architecture.md
Normal file
@@ -0,0 +1,109 @@
|
|||||||
|
# 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 和飞书长连接分别在守护线程中运行。
|
||||||
51
.agents/summary/codebase_info.md
Normal file
51
.agents/summary/codebase_info.md
Normal file
@@ -0,0 +1,51 @@
|
|||||||
|
# Codebase Info
|
||||||
|
|
||||||
|
## 基本信息
|
||||||
|
|
||||||
|
- **项目名称**: TSP 智能助手 (TSP Assistant)
|
||||||
|
- **语言**: Python 3.11+
|
||||||
|
- **框架**: Flask 3.x + SQLAlchemy 2.x + WebSocket
|
||||||
|
- **代码风格**: 变量名英文，注释/UI/日志中文
|
||||||
|
- **数据库**: SQLAlchemy ORM（开发用 SQLite，生产用 MySQL via PyMySQL）
|
||||||
|
- **入口文件**: `start_dashboard.py`
|
||||||
|
|
||||||
|
## 技术栈
|
||||||
|
|
||||||
|
| 层级 | 技术 |
|
||||||
|
|---|---|
|
||||||
|
| Web | Flask 3.x + Flask-CORS |
|
||||||
|
| ORM | SQLAlchemy 2.x |
|
||||||
|
| 实时通信 | `websockets` (port 8765) |
|
||||||
|
| 缓存 | Redis 5.x + hiredis |
|
||||||
|
| LLM | OpenAI-compatible API (Qwen/通义千问 via DashScope) |
|
||||||
|
| Embedding | `sentence-transformers` + `BAAI/bge-small-zh-v1.5` (可选) |
|
||||||
|
| NLP | jieba (分词) + scikit-learn (TF-IDF) |
|
||||||
|
| 飞书 SDK | `lark-oapi` 1.3.x (长连接模式) |
|
||||||
|
| 认证 | JWT (`pyjwt`) + SHA-256 |
|
||||||
|
| 监控 | psutil |
|
||||||
|
|
||||||
|
## 目录结构概览
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── config/ # UnifiedConfig 单例，从 .env 加载
|
||||||
|
├── core/ # 数据库、LLM、缓存、认证、ORM 模型
|
||||||
|
├── dialogue/ # 对话管理、实时聊天
|
||||||
|
├── knowledge_base/ # 知识库 CRUD、搜索、导入
|
||||||
|
├── analytics/ # 监控、预警、Token 统计
|
||||||
|
├── integrations/ # 飞书客户端、工单同步
|
||||||
|
├── agent/ # ReAct Agent（工具调度）
|
||||||
|
├── vehicle/ # 车辆数据管理
|
||||||
|
├── utils/ # 通用工具
|
||||||
|
└── web/ # Flask 应用层
|
||||||
|
├── app.py # 应用工厂 + 中间件
|
||||||
|
├── service_manager.py # 懒加载服务注册
|
||||||
|
├── decorators.py # 通用装饰器
|
||||||
|
├── blueprints/ # 按领域划分的 API 蓝图 (16 个)
|
||||||
|
├── static/ # 前端资源
|
||||||
|
└── templates/ # Jinja2 模板
|
||||||
|
```
|
||||||
|
|
||||||
|
## 启动流程
|
||||||
|
|
||||||
|
`start_dashboard.py` → 设置日志 → 检查数据库 → 启动 WebSocket 线程 → 启动飞书长连接线程 → 启动 Flask 应用
|
||||||
79
.agents/summary/components.md
Normal file
79
.agents/summary/components.md
Normal file
@@ -0,0 +1,79 @@
|
|||||||
|
# Components / 核心组件
|
||||||
|
|
||||||
|
## 业务组件
|
||||||
|
|
||||||
|
### DialogueManager (`src/dialogue/dialogue_manager.py`)
|
||||||
|
对话管理核心。处理用户消息，调用 LLM 生成回复，根据意图自动创建工单。连接知识库检索和 LLM 调用。
|
||||||
|
|
||||||
|
### RealtimeChatManager (`src/dialogue/realtime_chat.py`)
|
||||||
|
实时聊天管理器。管理 WebSocket 会话，维护 `ChatMessage` 数据结构，协调 DialogueManager 处理消息流。
|
||||||
|
|
||||||
|
### KnowledgeManager (`src/knowledge_base/knowledge_manager.py`)
|
||||||
|
知识库管理。支持 CRUD、TF-IDF 关键词搜索、可选 Embedding 语义搜索、文件导入、人工验证。已验证条目在检索时获得更高置信度。
|
||||||
|
|
||||||
|
### WorkOrderSyncService (`src/integrations/workorder_sync.py`)
|
||||||
|
工单同步服务。实现本地工单与飞书多维表格的双向同步。定义 `WorkOrderStatus` 和 `WorkOrderPriority` 枚举。
|
||||||
|
|
||||||
|
### ReactAgent (`src/agent/react_agent.py`)
|
||||||
|
ReAct 风格 LLM Agent。注册工具（知识搜索、车辆查询、分析、飞书消息），通过思考-行动-观察循环完成复杂任务。
|
||||||
|
|
||||||
|
### AnalyticsManager (`src/analytics/analytics_manager.py`)
|
||||||
|
数据分析管理器。工单趋势、预警统计、满意度分析，支持按租户筛选。
|
||||||
|
|
||||||
|
### AlertSystem (`src/analytics/alert_system.py`)
|
||||||
|
预警系统。自定义 `AlertRule`，支持多级别（`AlertLevel`）和多类型（`AlertType`）预警，批量管理。
|
||||||
|
|
||||||
|
## 基础设施组件
|
||||||
|
|
||||||
|
### DatabaseManager (`src/core/database.py`)
|
||||||
|
数据库管理单例。封装 SQLAlchemy session 管理，提供 `get_session()` 上下文管理器。支持 SQLite（开发）和 MySQL（生产）。
|
||||||
|
|
||||||
|
### LLMClient (`src/core/llm_client.py`)
|
||||||
|
LLM 调用客户端。封装 OpenAI-compatible API 调用（默认 Qwen/DashScope），支持流式和非流式响应。
|
||||||
|
|
||||||
|
### UnifiedConfig (`src/config/unified_config.py`)
|
||||||
|
配置单例。从 `.env` 加载环境变量，映射到 typed dataclasses：
|
||||||
|
`DatabaseConfig`, `LLMConfig`, `ServerConfig`, `FeishuConfig`, `AIAccuracyConfig`, `EmbeddingConfig`, `RedisConfig`
|
||||||
|
|
||||||
|
### AuthManager (`src/core/auth_manager.py`)
|
||||||
|
认证管理。JWT token 生成/验证，SHA-256 密码哈希。
|
||||||
|
|
||||||
|
### ServiceManager (`src/web/service_manager.py`)
|
||||||
|
服务注册中心。线程安全的懒加载，Blueprint 通过它获取业务服务实例。
|
||||||
|
|
||||||
|
## 集成组件
|
||||||
|
|
||||||
|
### FeishuService (`src/integrations/feishu_service.py`)
|
||||||
|
飞书 API 客户端。获取 tenant_access_token，发送消息，操作多维表格。
|
||||||
|
|
||||||
|
### FeishuLongConnService (`src/integrations/feishu_longconn_service.py`)
|
||||||
|
飞书事件订阅长连接服务。接收飞书机器人消息事件，转发给 DialogueManager 处理。
|
||||||
|
|
||||||
|
## Web 层组件
|
||||||
|
|
||||||
|
### Flask Blueprints (`src/web/blueprints/`)
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
subgraph API["API Blueprints"]
|
||||||
|
WO["workorders — 工单 CRUD + AI 建议"]
|
||||||
|
AL["alerts — 预警管理"]
|
||||||
|
KN["knowledge — 知识库管理"]
|
||||||
|
CV["conversations — 对话历史"]
|
||||||
|
CH["chat — HTTP 聊天 + 会话管理"]
|
||||||
|
AG["agent — Agent 模式交互"]
|
||||||
|
TN["tenants — 租户管理"]
|
||||||
|
AU["auth — 登录/注册/JWT"]
|
||||||
|
AN["analytics — 数据分析导出"]
|
||||||
|
MO["monitoring — Token/AI 监控"]
|
||||||
|
SY["system — 系统配置/备份/优化"]
|
||||||
|
FS["feishu_sync — 飞书同步配置"]
|
||||||
|
FB["feishu_bot — 飞书 Webhook 事件"]
|
||||||
|
VH["vehicle — 车辆数据"]
|
||||||
|
CO["core — 监控规则/批量操作"]
|
||||||
|
TE["test — API 连接测试"]
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
### WebSocketServer (`src/web/websocket_server.py`)
|
||||||
|
独立 WebSocket 服务器（port 8765）。处理客户端连接，转发消息给 RealtimeChatManager。
|
||||||
136
.agents/summary/data_models.md
Normal file
136
.agents/summary/data_models.md
Normal file
@@ -0,0 +1,136 @@
|
|||||||
|
# Data Models / 数据模型
|
||||||
|
|
||||||
|
## ORM 模型 (`src/core/models.py`)
|
||||||
|
|
||||||
|
所有模型继承 SQLAlchemy `Base`，核心表均包含 `tenant_id` 字段用于多租户隔离。
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
erDiagram
|
||||||
|
Tenant ||--o{ WorkOrder : "tenant_id"
|
||||||
|
Tenant ||--o{ ChatSession : "tenant_id"
|
||||||
|
Tenant ||--o{ KnowledgeEntry : "tenant_id"
|
||||||
|
Tenant ||--o{ Alert : "tenant_id"
|
||||||
|
Tenant ||--o{ Analytics : "tenant_id"
|
||||||
|
|
||||||
|
WorkOrder ||--o{ Conversation : "work_order_id"
|
||||||
|
WorkOrder ||--o{ WorkOrderProcessHistory : "work_order_id"
|
||||||
|
WorkOrder ||--o{ WorkOrderSuggestion : "work_order_id"
|
||||||
|
|
||||||
|
ChatSession ||--o{ Conversation : "session_id"
|
||||||
|
|
||||||
|
Tenant {
|
||||||
|
int id PK
|
||||||
|
string tenant_id UK
|
||||||
|
string name
|
||||||
|
text description
|
||||||
|
bool is_active
|
||||||
|
text config "JSON: feishu, system_prompt"
|
||||||
|
}
|
||||||
|
|
||||||
|
WorkOrder {
|
||||||
|
int id PK
|
||||||
|
string tenant_id FK
|
||||||
|
string order_id UK
|
||||||
|
string title
|
||||||
|
text description
|
||||||
|
string category
|
||||||
|
string priority
|
||||||
|
string status
|
||||||
|
string feishu_record_id "飞书记录ID"
|
||||||
|
string assignee
|
||||||
|
text ai_suggestion
|
||||||
|
string assigned_module
|
||||||
|
string module_owner
|
||||||
|
string vin_sim "车架号"
|
||||||
|
}
|
||||||
|
|
||||||
|
ChatSession {
|
||||||
|
int id PK
|
||||||
|
string tenant_id FK
|
||||||
|
string session_id UK
|
||||||
|
string source "websocket/api/feishu_bot"
|
||||||
|
}
|
||||||
|
|
||||||
|
Conversation {
|
||||||
|
int id PK
|
||||||
|
string tenant_id FK
|
||||||
|
int work_order_id FK
|
||||||
|
string session_id FK
|
||||||
|
string role "user/assistant/system"
|
||||||
|
text content
|
||||||
|
}
|
||||||
|
|
||||||
|
KnowledgeEntry {
|
||||||
|
int id PK
|
||||||
|
string tenant_id FK
|
||||||
|
string question
|
||||||
|
text answer
|
||||||
|
string category
|
||||||
|
bool is_verified
|
||||||
|
float confidence_score
|
||||||
|
}
|
||||||
|
|
||||||
|
Alert {
|
||||||
|
int id PK
|
||||||
|
string tenant_id FK
|
||||||
|
string level
|
||||||
|
string type
|
||||||
|
text message
|
||||||
|
bool is_resolved
|
||||||
|
}
|
||||||
|
|
||||||
|
VehicleData {
|
||||||
|
int id PK
|
||||||
|
string vehicle_id
|
||||||
|
string vin
|
||||||
|
text data "JSON"
|
||||||
|
}
|
||||||
|
|
||||||
|
Analytics {
|
||||||
|
int id PK
|
||||||
|
string tenant_id FK
|
||||||
|
string metric_type
|
||||||
|
float value
|
||||||
|
text details "JSON"
|
||||||
|
}
|
||||||
|
|
||||||
|
User {
|
||||||
|
int id PK
|
||||||
|
string username UK
|
||||||
|
string password_hash
|
||||||
|
string role "admin/user"
|
||||||
|
}
|
||||||
|
|
||||||
|
WorkOrderProcessHistory {
|
||||||
|
int id PK
|
||||||
|
int work_order_id FK
|
||||||
|
string action
|
||||||
|
text details
|
||||||
|
}
|
||||||
|
|
||||||
|
WorkOrderSuggestion {
|
||||||
|
int id PK
|
||||||
|
int work_order_id FK
|
||||||
|
text suggestion
|
||||||
|
float confidence
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 配置 Dataclasses (`src/config/unified_config.py`)
|
||||||
|
|
||||||
|
| Dataclass | 关键字段 |
|
||||||
|
|-----------|---------|
|
||||||
|
| `DatabaseConfig` | `url` |
|
||||||
|
| `LLMConfig` | `api_key`, `base_url`, `model`, `temperature`, `max_tokens`, `timeout` |
|
||||||
|
| `ServerConfig` | `host`, `port`, `websocket_port`, `debug`, `log_level` |
|
||||||
|
| `FeishuConfig` | `app_id`, `app_secret`, `app_token`, `table_id` |
|
||||||
|
| `AIAccuracyConfig` | `auto_approve_threshold`, `manual_review_threshold` |
|
||||||
|
| `EmbeddingConfig` | `enabled`, `model`, `dimension`, `similarity_threshold` |
|
||||||
|
| `RedisConfig` | `host`, `port`, `db`, `password`, `pool_size`, `default_ttl`, `enabled` |
|
||||||
|
|
||||||
|
## 业务枚举
|
||||||
|
|
||||||
|
- `WorkOrderStatus`: 工单状态流转
|
||||||
|
- `WorkOrderPriority`: 工单优先级
|
||||||
|
- `AlertLevel`: 预警级别
|
||||||
|
- `AlertType`: 预警类型
|
||||||
90
.agents/summary/dependencies.md
Normal file
90
.agents/summary/dependencies.md
Normal file
@@ -0,0 +1,90 @@
|
|||||||
|
# Dependencies / 外部依赖
|
||||||
|
|
||||||
|
## 核心依赖
|
||||||
|
|
||||||
|
| 包 | 版本 | 用途 |
|
||||||
|
|---|---|---|
|
||||||
|
| flask | 3.0.3 | Web 框架 |
|
||||||
|
| flask-cors | 5.0.0 | 跨域支持 |
|
||||||
|
| sqlalchemy | 2.0.32 | ORM |
|
||||||
|
| pymysql | 1.1.1 | MySQL 驱动 |
|
||||||
|
| websockets | 15.0.1 | WebSocket 服务器 |
|
||||||
|
| redis | 5.0.1 | 缓存客户端 |
|
||||||
|
| hiredis | 2.3.2 | Redis 高性能解析器 |
|
||||||
|
|
||||||
|
## LLM / NLP
|
||||||
|
|
||||||
|
| 包 | 版本 | 用途 |
|
||||||
|
|---|---|---|
|
||||||
|
| jieba | 0.42.1 | 中文分词 |
|
||||||
|
| scikit-learn | 1.4.2 | TF-IDF 向量化 |
|
||||||
|
| numpy | 1.26.4 | 数值计算 |
|
||||||
|
|
||||||
|
## 飞书集成
|
||||||
|
|
||||||
|
| 包 | 版本 | 用途 |
|
||||||
|
|---|---|---|
|
||||||
|
| lark-oapi | 1.3.5 | 飞书 SDK（事件订阅 2.0，长连接模式） |
|
||||||
|
|
||||||
|
## 数据处理
|
||||||
|
|
||||||
|
| 包 | 版本 | 用途 |
|
||||||
|
|---|---|---|
|
||||||
|
| pandas | 2.2.2 | 数据分析 |
|
||||||
|
| openpyxl | 3.1.5 | Excel 读写 |
|
||||||
|
| ujson | 5.10.0 | 高性能 JSON |
|
||||||
|
|
||||||
|
## 安全 / 认证
|
||||||
|
|
||||||
|
| 包 | 版本 | 用途 |
|
||||||
|
|---|---|---|
|
||||||
|
| pyjwt | 2.9.0 | JWT token |
|
||||||
|
| bcrypt | 4.2.1 | 密码哈希 |
|
||||||
|
| cryptography | 43.0.1 | 加密支持 |
|
||||||
|
|
||||||
|
## 数据验证
|
||||||
|
|
||||||
|
| 包 | 版本 | 用途 |
|
||||||
|
|---|---|---|
|
||||||
|
| pydantic | 2.9.2 | 数据验证 |
|
||||||
|
| marshmallow | 3.23.3 | 序列化/反序列化 |
|
||||||
|
|
||||||
|
## 监控 / 工具
|
||||||
|
|
||||||
|
| 包 | 版本 | 用途 |
|
||||||
|
|---|---|---|
|
||||||
|
| psutil | 5.9.8 | 系统监控 |
|
||||||
|
| python-dotenv | 1.0.1 | 环境变量加载 |
|
||||||
|
| structlog | 24.4.0 | 结构化日志 |
|
||||||
|
| aiohttp | 3.10.10 | 异步 HTTP |
|
||||||
|
| httpx | 0.27.2 | HTTP 客户端 |
|
||||||
|
|
||||||
|
## 可选依赖
|
||||||
|
|
||||||
|
| 包 | 用途 | 条件 |
|
||||||
|
|---|---|---|
|
||||||
|
| sentence-transformers | 本地 Embedding 模型 | `EMBEDDING_ENABLED=True` |
|
||||||
|
| torch | PyTorch（sentence-transformers 依赖） | `EMBEDDING_ENABLED=True` |
|
||||||
|
|
||||||
|
## 开发依赖
|
||||||
|
|
||||||
|
| 包 | 版本 | 用途 |
|
||||||
|
|---|---|---|
|
||||||
|
| pytest | 8.3.3 | 测试框架 |
|
||||||
|
| pytest-asyncio | 0.24.0 | 异步测试 |
|
||||||
|
| pytest-cov | 6.0.0 | 覆盖率 |
|
||||||
|
| black | 24.8.0 | 代码格式化 |
|
||||||
|
| flake8 | 7.1.1 | Linting |
|
||||||
|
| mypy | 1.11.1 | 类型检查 |
|
||||||
|
| isort | 5.13.2 | Import 排序 |
|
||||||
|
|
||||||
|
## 外部服务依赖
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
App["TSP Assistant"] --> Qwen["Qwen/DashScope API"]
|
||||||
|
App --> FeishuAPI["飞书 Open API"]
|
||||||
|
App --> Redis["Redis Server"]
|
||||||
|
App --> DB["MySQL / SQLite"]
|
||||||
|
App --> HF["HuggingFace (可选, 首次下载模型)"]
|
||||||
|
```
|
||||||
56
.agents/summary/index.md
Normal file
56
.agents/summary/index.md
Normal file
@@ -0,0 +1,56 @@
|
|||||||
|
# TSP 智能助手 — 文档索引
|
||||||
|
|
||||||
|
> **面向 AI 助手的使用指南**: 本文件是文档体系的入口。根据问题类型查阅对应文件即可获取详细信息。大多数问题只需本文件 + 1~2 个子文件即可回答。
|
||||||
|
|
||||||
|
## 文档目录
|
||||||
|
|
||||||
|
| 文件 | 内容摘要 | 适用问题 |
|
||||||
|
|------|---------|---------|
|
||||||
|
| [codebase_info.md](codebase_info.md) | 项目基本信息、技术栈、目录结构、启动流程 | "这个项目是什么？" "用了什么技术？" "怎么启动？" |
|
||||||
|
| [architecture.md](architecture.md) | 系统架构图、架构模式（单例/Blueprint/装饰器/多租户）、线程模型 | "系统怎么组织的？" "请求怎么流转？" "多租户怎么实现？" |
|
||||||
|
| [components.md](components.md) | 所有核心组件的职责说明（业务层、基础设施层、Web 层） | "DialogueManager 做什么？" "有哪些 Blueprint？" |
|
||||||
|
| [interfaces.md](interfaces.md) | REST API 列表、WebSocket 接口、外部集成时序图、装饰器接口 | "工单 API 有哪些？" "飞书怎么集成的？" |
|
||||||
|
| [data_models.md](data_models.md) | ORM 模型 ER 图、字段说明、配置 Dataclass、业务枚举 | "WorkOrder 有哪些字段？" "数据库表结构？" |
|
||||||
|
| [workflows.md](workflows.md) | 6 个关键流程的时序图（启动、对话、工单同步、知识搜索、飞书消息、Agent） | "消息怎么处理的？" "工单怎么同步到飞书？" |
|
||||||
|
| [dependencies.md](dependencies.md) | 所有 Python 依赖分类说明、外部服务依赖图 | "用了哪些库？" "有哪些外部依赖？" |
|
||||||
|
| [review_notes.md](review_notes.md) | 文档一致性/完整性检查结果、待补充区域、改进建议 | "文档有什么遗漏？" "哪些地方需要补充？" |
|
||||||
|
|
||||||
|
## 快速导航
|
||||||
|
|
||||||
|
### 按任务类型
|
||||||
|
|
||||||
|
- **修 Bug / 改功能** → `components.md` 找到对应组件 → `architecture.md` 理解依赖关系
|
||||||
|
- **加新 API** → `interfaces.md` 了解现有 API 模式 → `architecture.md` 中的装饰器模式
|
||||||
|
- **改数据库** → `data_models.md` 查看表结构和关系
|
||||||
|
- **理解流程** → `workflows.md` 查看时序图
|
||||||
|
- **加新依赖** → `dependencies.md` 了解现有依赖
|
||||||
|
- **部署/配置** → `codebase_info.md` 查看启动方式
|
||||||
|
|
||||||
|
### 按代码位置
|
||||||
|
|
||||||
|
- `src/core/` → `components.md` 基础设施组件 + `data_models.md`
|
||||||
|
- `src/web/blueprints/` → `interfaces.md` API 列表 + `components.md` Blueprint 说明
|
||||||
|
- `src/dialogue/` → `components.md` 对话组件 + `workflows.md` 对话流程
|
||||||
|
- `src/integrations/` → `interfaces.md` 外部集成 + `workflows.md` 飞书流程
|
||||||
|
- `src/config/` → `data_models.md` 配置 Dataclass
|
||||||
|
- `start_dashboard.py` → `workflows.md` 启动流程
|
||||||
|
|
||||||
|
## 文件间关系
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
INDEX["index.md (本文件)"] --> CI["codebase_info.md"]
|
||||||
|
INDEX --> ARCH["architecture.md"]
|
||||||
|
INDEX --> COMP["components.md"]
|
||||||
|
INDEX --> INTF["interfaces.md"]
|
||||||
|
INDEX --> DM["data_models.md"]
|
||||||
|
INDEX --> WF["workflows.md"]
|
||||||
|
INDEX --> DEP["dependencies.md"]
|
||||||
|
INDEX --> RN["review_notes.md"]
|
||||||
|
|
||||||
|
ARCH --> COMP
|
||||||
|
COMP --> INTF
|
||||||
|
COMP --> DM
|
||||||
|
INTF --> WF
|
||||||
|
DM --> WF
|
||||||
|
```
|
||||||
104
.agents/summary/interfaces.md
Normal file
104
.agents/summary/interfaces.md
Normal file
@@ -0,0 +1,104 @@
|
|||||||
|
# Interfaces / 接口与集成
|
||||||
|
|
||||||
|
## REST API 概览
|
||||||
|
|
||||||
|
所有 API 以 `/api/` 为前缀，返回 JSON。认证通过 Flask session 或 JWT。
|
||||||
|
|
||||||
|
### 工单 (workorders)
|
||||||
|
| Method | Path | 说明 |
|
||||||
|
|--------|------|------|
|
||||||
|
| GET | `/api/workorders` | 工单列表（分页） |
|
||||||
|
| POST | `/api/workorders` | 创建工单 |
|
||||||
|
| GET | `/api/workorders/<id>` | 工单详情 |
|
||||||
|
| PUT | `/api/workorders/<id>` | 更新工单 |
|
||||||
|
| DELETE | `/api/workorders/<id>` | 删除工单 |
|
||||||
|
| POST | `/api/workorders/ai-suggestion` | 生成 AI 建议 |
|
||||||
|
| POST | `/api/workorders/import` | 批量导入 |
|
||||||
|
|
||||||
|
### 知识库 (knowledge)
|
||||||
|
| Method | Path | 说明 |
|
||||||
|
|--------|------|------|
|
||||||
|
| GET | `/api/knowledge` | 知识条目列表 |
|
||||||
|
| POST | `/api/knowledge` | 添加条目 |
|
||||||
|
| GET | `/api/knowledge/search` | 搜索知识库 |
|
||||||
|
| GET | `/api/knowledge/stats` | 统计信息 |
|
||||||
|
| POST | `/api/knowledge/upload` | 文件导入 |
|
||||||
|
| PUT | `/api/knowledge/<id>/verify` | 验证条目 |
|
||||||
|
|
||||||
|
### 对话 (chat / conversations)
|
||||||
|
| Method | Path | 说明 |
|
||||||
|
|--------|------|------|
|
||||||
|
| POST | `/api/chat/sessions` | 创建会话 |
|
||||||
|
| GET | `/api/chat/sessions` | 活跃会话列表 |
|
||||||
|
| POST | `/api/chat/message` | 发送消息 |
|
||||||
|
| POST | `/api/chat/message/stream` | 流式消息 (SSE) |
|
||||||
|
| GET | `/api/conversations` | 对话历史 |
|
||||||
|
|
||||||
|
### 租户 (tenants)
|
||||||
|
| Method | Path | 说明 |
|
||||||
|
|--------|------|------|
|
||||||
|
| GET | `/api/tenants` | 租户列表 |
|
||||||
|
| POST | `/api/tenants` | 创建租户 |
|
||||||
|
| PUT | `/api/tenants/<id>` | 更新租户 |
|
||||||
|
| DELETE | `/api/tenants/<id>` | 删除租户 |
|
||||||
|
| GET | `/api/tenants/feishu-groups` | 飞书群列表 |
|
||||||
|
|
||||||
|
### 认证 (auth)
|
||||||
|
| Method | Path | 说明 |
|
||||||
|
|--------|------|------|
|
||||||
|
| POST | `/api/auth/login` | 登录 |
|
||||||
|
| POST | `/api/auth/logout` | 登出 |
|
||||||
|
| GET | `/api/auth/status` | 认证状态 |
|
||||||
|
| POST | `/api/auth/register` | 注册 |
|
||||||
|
|
||||||
|
### Agent
|
||||||
|
| Method | Path | 说明 |
|
||||||
|
|--------|------|------|
|
||||||
|
| POST | `/api/agent/chat` | Agent 对话 |
|
||||||
|
| GET | `/api/agent/status` | Agent 状态 |
|
||||||
|
| POST | `/api/agent/tools/execute` | 执行工具 |
|
||||||
|
|
||||||
|
### 飞书同步 (feishu-sync)
|
||||||
|
| Method | Path | 说明 |
|
||||||
|
|--------|------|------|
|
||||||
|
| GET | `/api/feishu-sync/status` | 同步状态 |
|
||||||
|
| POST | `/api/feishu-sync/from-feishu` | 从飞书拉取 |
|
||||||
|
| POST | `/api/feishu-sync/<id>/to-feishu` | 推送到飞书 |
|
||||||
|
| GET/POST | `/api/feishu-sync/config` | 同步配置 |
|
||||||
|
|
||||||
|
## WebSocket 接口
|
||||||
|
|
||||||
|
- **端口**: 8765
|
||||||
|
- **协议**: JSON 消息
|
||||||
|
- **功能**: 实时聊天，客户端连接后通过 JSON 消息与 RealtimeChatManager 交互
|
||||||
|
|
||||||
|
## 外部集成
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant User as 用户
|
||||||
|
participant Feishu as 飞书
|
||||||
|
participant LongConn as 飞书长连接服务
|
||||||
|
participant DM as DialogueManager
|
||||||
|
participant LLM as Qwen API
|
||||||
|
participant KB as KnowledgeManager
|
||||||
|
|
||||||
|
User->>Feishu: 发送消息
|
||||||
|
Feishu->>LongConn: 事件推送
|
||||||
|
LongConn->>DM: 处理消息
|
||||||
|
DM->>KB: 知识库检索
|
||||||
|
KB-->>DM: 相关知识
|
||||||
|
DM->>LLM: 生成回复
|
||||||
|
LLM-->>DM: AI 回复
|
||||||
|
DM->>Feishu: 回复消息
|
||||||
|
```
|
||||||
|
|
||||||
|
## 装饰器接口
|
||||||
|
|
||||||
|
| 装饰器 | 位置 | 功能 |
|
||||||
|
|--------|------|------|
|
||||||
|
| `@handle_errors` | `decorators.py` | 统一异常捕获，返回标准错误响应 |
|
||||||
|
| `@require_json(fields)` | `decorators.py` | 验证请求体为 JSON 且包含必填字段 |
|
||||||
|
| `@with_service(name)` | `decorators.py` | 从 ServiceManager 注入服务实例 |
|
||||||
|
| `@rate_limit(max, period)` | `decorators.py` | 基于 IP 的频率限制 |
|
||||||
|
| `@cache_response(timeout)` | `decorators.py` | 响应缓存 |
|
||||||
41
.agents/summary/review_notes.md
Normal file
41
.agents/summary/review_notes.md
Normal file
@@ -0,0 +1,41 @@
|
|||||||
|
# Review Notes / 审查记录
|
||||||
|
|
||||||
|
## 一致性检查 ✅
|
||||||
|
|
||||||
|
- 所有文档中的组件名称、文件路径与代码库一致
|
||||||
|
- 数据模型字段与 `src/core/models.py` 中的 ORM 定义匹配
|
||||||
|
- API 路径与 Blueprint 注册的路由一致
|
||||||
|
- 配置项与 `.env.example` 中的变量对应
|
||||||
|
|
||||||
|
## 完整性检查
|
||||||
|
|
||||||
|
### 已充分覆盖的区域 ✅
|
||||||
|
- 系统架构和线程模型
|
||||||
|
- 核心业务组件（对话、工单、知识库、Agent）
|
||||||
|
- 数据模型和 ER 关系
|
||||||
|
- REST API 接口概览
|
||||||
|
- 外部集成（飞书、LLM）
|
||||||
|
- 启动流程和关键工作流
|
||||||
|
|
||||||
|
### 需要补充的区域 ⚠️
|
||||||
|
|
||||||
|
| 区域 | 说明 | 建议 |
|
||||||
|
|------|------|------|
|
||||||
|
| `src/core/cache_manager.py` | 缓存策略细节未深入分析 | 补充 Redis 缓存键命名规范和 TTL 策略 |
|
||||||
|
| `src/core/vector_store.py` | 向量存储实现细节 | 补充 Embedding 索引结构说明 |
|
||||||
|
| `src/core/embedding_client.py` | Embedding 客户端接口 | 补充模型加载和推理流程 |
|
||||||
|
| `src/web/static/js/` | 前端模块化结构 | 补充前端模块职责说明 |
|
||||||
|
| `src/repositories/` | 数据访问层（steering 中提到但未深入） | 补充 Repository 模式和自动 tenant_id 过滤机制 |
|
||||||
|
| 错误处理 | `error_handlers.py` 的统一响应格式 | 补充 API 错误码规范 |
|
||||||
|
| 部署配置 | Docker / Nginx 配置细节 | 补充 `nginx.conf` 和 docker-compose 说明 |
|
||||||
|
|
||||||
|
### 语言支持限制
|
||||||
|
- 代码注释和 UI 文本为中文，文档已采用中英混合风格覆盖
|
||||||
|
- 无其他语言支持限制
|
||||||
|
|
||||||
|
## 建议
|
||||||
|
|
||||||
|
1. 为 `src/repositories/` 层补充文档，说明自动 tenant_id 过滤的实现
|
||||||
|
2. 补充前端 JS 模块的职责划分文档
|
||||||
|
3. 考虑为 API 添加 OpenAPI/Swagger 规范
|
||||||
|
4. 补充部署相关的 Docker 和 Nginx 配置说明
|
||||||
127
.agents/summary/workflows.md
Normal file
127
.agents/summary/workflows.md
Normal file
@@ -0,0 +1,127 @@
|
|||||||
|
# Workflows / 关键流程
|
||||||
|
|
||||||
|
## 1. 应用启动流程
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant Main as start_dashboard.py
|
||||||
|
participant Log as setup_logging
|
||||||
|
participant DB as DatabaseManager
|
||||||
|
participant WS as WebSocket Thread
|
||||||
|
participant FS as 飞书长连接 Thread
|
||||||
|
participant Flask as Flask App
|
||||||
|
|
||||||
|
Main->>Log: 初始化日志（按启动时间分目录）
|
||||||
|
Main->>DB: check_database_connection()
|
||||||
|
alt 连接失败
|
||||||
|
Main->>Main: sys.exit(1)
|
||||||
|
end
|
||||||
|
Main->>WS: 启动守护线程 (port 8765)
|
||||||
|
Main->>FS: 启动守护线程 (飞书长连接)
|
||||||
|
Main->>Main: sleep(2) 等待初始化
|
||||||
|
Main->>Flask: app.run(port=5000, threaded=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. 用户对话流程 (WebSocket)
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant Client as 浏览器
|
||||||
|
participant WS as WebSocketServer
|
||||||
|
participant RCM as RealtimeChatManager
|
||||||
|
participant DM as DialogueManager
|
||||||
|
participant KB as KnowledgeManager
|
||||||
|
participant LLM as LLMClient
|
||||||
|
|
||||||
|
Client->>WS: WebSocket 连接
|
||||||
|
Client->>WS: JSON 消息
|
||||||
|
WS->>RCM: 转发消息
|
||||||
|
RCM->>DM: process_message()
|
||||||
|
DM->>KB: search() 知识库检索
|
||||||
|
KB-->>DM: 匹配结果
|
||||||
|
DM->>LLM: 调用 Qwen API（含知识上下文）
|
||||||
|
LLM-->>DM: AI 回复
|
||||||
|
DM-->>RCM: 回复内容
|
||||||
|
RCM-->>WS: 发送回复
|
||||||
|
WS-->>Client: JSON 回复
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. 工单创建与飞书同步
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant User as 用户/AI
|
||||||
|
participant API as workorders Blueprint
|
||||||
|
participant DB as Database
|
||||||
|
participant Sync as WorkOrderSyncService
|
||||||
|
participant Feishu as 飞书多维表格
|
||||||
|
|
||||||
|
User->>API: POST /api/workorders
|
||||||
|
API->>DB: 创建工单记录
|
||||||
|
DB-->>API: 工单 ID
|
||||||
|
|
||||||
|
opt 飞书同步已配置
|
||||||
|
API->>Sync: sync_to_feishu(workorder_id)
|
||||||
|
Sync->>Feishu: 创建/更新记录
|
||||||
|
Feishu-->>Sync: feishu_record_id
|
||||||
|
Sync->>DB: 更新 feishu_record_id
|
||||||
|
end
|
||||||
|
|
||||||
|
API-->>User: 工单创建成功
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. 知识库搜索流程
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
Q["用户查询"] --> TF["TF-IDF 关键词匹配"]
|
||||||
|
Q --> EMB{"Embedding 启用?"}
|
||||||
|
|
||||||
|
EMB -->|是| VEC["向量语义搜索"]
|
||||||
|
EMB -->|否| SKIP["跳过"]
|
||||||
|
|
||||||
|
TF --> MERGE["合并结果"]
|
||||||
|
VEC --> MERGE
|
||||||
|
SKIP --> MERGE
|
||||||
|
|
||||||
|
MERGE --> RANK["按相似度排序"]
|
||||||
|
RANK --> VERIFIED{"已验证条目优先"}
|
||||||
|
VERIFIED --> RESULT["返回 Top-K 结果"]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. 飞书机器人消息处理
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant User as 飞书用户
|
||||||
|
participant Feishu as 飞书服务器
|
||||||
|
participant LC as FeishuLongConnService
|
||||||
|
participant DM as DialogueManager
|
||||||
|
participant LLM as LLMClient
|
||||||
|
participant FS as FeishuService
|
||||||
|
|
||||||
|
User->>Feishu: @机器人 发送消息
|
||||||
|
Feishu->>LC: 长连接事件推送
|
||||||
|
LC->>LC: 消息去重
|
||||||
|
LC->>LC: resolve_tenant_by_chat_id()
|
||||||
|
LC->>DM: 处理消息（带 tenant_id）
|
||||||
|
DM->>LLM: 生成回复
|
||||||
|
LLM-->>DM: AI 回复
|
||||||
|
DM->>FS: 发送飞书消息
|
||||||
|
FS->>Feishu: API 回复
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. Agent 工具调度
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
INPUT["用户输入"] --> THINK["Thought: 分析意图"]
|
||||||
|
THINK --> ACT["Action: 选择工具"]
|
||||||
|
ACT --> EXEC["执行工具"]
|
||||||
|
EXEC --> OBS["Observation: 获取结果"]
|
||||||
|
OBS --> DONE{"任务完成?"}
|
||||||
|
DONE -->|否| THINK
|
||||||
|
DONE -->|是| ANSWER["Final Answer: 返回结果"]
|
||||||
|
```
|
||||||
|
|
||||||
|
ReactAgent 注册的工具包括：知识库搜索、车辆查询、数据分析、飞书消息发送等。
|
||||||
8
.gitignore
vendored
8
.gitignore
vendored
@@ -42,3 +42,11 @@ test_*.py
|
|||||||
|
|
||||||
# 缓存
|
# 缓存
|
||||||
.cache/
|
.cache/
|
||||||
|
|
||||||
|
# Virtual environment
|
||||||
|
bin/
|
||||||
|
lib/
|
||||||
|
lib64
|
||||||
|
include/
|
||||||
|
pyvenv.cfg
|
||||||
|
To
|
||||||
|
|||||||
96
AGENTS.md
Normal file
96
AGENTS.md
Normal file
@@ -0,0 +1,96 @@
|
|||||||
|
# AGENTS.md — TSP 智能助手
|
||||||
|
|
||||||
|
> AI 助手代码导航指南。详细文档见 `.agents/summary/index.md`。
|
||||||
|
|
||||||
|
## 项目概述
|
||||||
|
|
||||||
|
TSP 智能助手是一个 AI 驱动的多租户客服与工单管理系统。Python 3.11+ / Flask 3.x / SQLAlchemy 2.x。入口文件 `start_dashboard.py`。
|
||||||
|
|
||||||
|
## 目录导航
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── config/unified_config.py # UnifiedConfig 单例，所有配置从 .env 加载
|
||||||
|
├── core/
|
||||||
|
│ ├── models.py # 所有 SQLAlchemy ORM 模型（11 个表）
|
||||||
|
│ ├── database.py # DatabaseManager 单例，session 管理
|
||||||
|
│ ├── llm_client.py # LLMClient — OpenAI-compatible API (Qwen)
|
||||||
|
│ ├── auth_manager.py # JWT + SHA-256 认证
|
||||||
|
│ ├── cache_manager.py # Redis 缓存
|
||||||
|
│ └── vector_store.py # Embedding 向量存储
|
||||||
|
├── dialogue/
|
||||||
|
│ ├── dialogue_manager.py # 核心对话处理，调用 LLM + 知识库
|
||||||
|
│ └── realtime_chat.py # WebSocket 实时聊天管理
|
||||||
|
├── knowledge_base/
|
||||||
|
│ └── knowledge_manager.py # 知识库 CRUD + TF-IDF/Embedding 搜索
|
||||||
|
├── integrations/
|
||||||
|
│ ├── feishu_service.py # 飞书 API 客户端
|
||||||
|
│ ├── feishu_longconn_service.py # 飞书长连接事件订阅
|
||||||
|
│ └── workorder_sync.py # 工单 ↔ 飞书多维表格双向同步
|
||||||
|
├── agent/react_agent.py # ReAct Agent（工具调度循环）
|
||||||
|
├── analytics/
|
||||||
|
│ ├── analytics_manager.py # 数据分析
|
||||||
|
│ └── alert_system.py # 预警规则引擎
|
||||||
|
└── web/
|
||||||
|
├── app.py # Flask 应用工厂 + 路由
|
||||||
|
├── service_manager.py # 懒加载服务注册中心
|
||||||
|
├── decorators.py # @handle_errors, @require_json, @resolve_tenant_id, @rate_limit
|
||||||
|
├── websocket_server.py # 独立 WebSocket 服务器 (port 8765)
|
||||||
|
└── blueprints/ # 16 个 Flask Blueprint（每个领域一个文件）
|
||||||
|
```
|
||||||
|
|
||||||
|
## 关键模式
|
||||||
|
|
||||||
|
### 多租户
|
||||||
|
所有核心表含 `tenant_id` 字段。`@resolve_tenant_id` 装饰器从请求中提取。查询时必须过滤 `tenant_id`。
|
||||||
|
|
||||||
|
### 服务获取
|
||||||
|
Blueprint 通过 `ServiceManager` 懒加载获取服务实例，不要直接实例化业务类。
|
||||||
|
|
||||||
|
### API 装饰器栈
|
||||||
|
典型 API 端点模式：
|
||||||
|
```python
|
||||||
|
@bp.route('/api/xxx', methods=['POST'])
|
||||||
|
@handle_errors()
|
||||||
|
@require_json(['field1', 'field2'])
|
||||||
|
def create_xxx():
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
### 配置
|
||||||
|
所有配置通过 `get_config()` 获取，从 `.env` 加载。不要硬编码配置值。参考 `.env.example` 了解所有可用变量。
|
||||||
|
|
||||||
|
## 入口与启动
|
||||||
|
|
||||||
|
- `start_dashboard.py` — 主入口，启动 Flask + WebSocket + 飞书长连接（3 个线程）
|
||||||
|
- `start_feishu_bot.py` — 独立飞书机器人入口
|
||||||
|
- `init_database.py` — 数据库初始化
|
||||||
|
|
||||||
|
## 数据库
|
||||||
|
|
||||||
|
- 开发: SQLite (`data/tsp_assistant.db`)
|
||||||
|
- 生产: MySQL via PyMySQL
|
||||||
|
- ORM: SQLAlchemy 2.x，模型定义在 `src/core/models.py`
|
||||||
|
- 核心表: `Tenant`, `WorkOrder`, `ChatSession`, `Conversation`, `KnowledgeEntry`, `Alert`, `Analytics`, `VehicleData`, `User`
|
||||||
|
|
||||||
|
## 外部集成
|
||||||
|
|
||||||
|
- **LLM**: Qwen/DashScope (OpenAI-compatible API)，通过 `LLMClient` 调用
|
||||||
|
- **飞书**: `lark-oapi` SDK，长连接模式接收消息，API 模式发送消息和操作多维表格
|
||||||
|
- **Redis**: 可选缓存层，`REDIS_ENABLED` 控制
|
||||||
|
|
||||||
|
## 详细文档
|
||||||
|
|
||||||
|
完整文档体系在 `.agents/summary/` 目录：
|
||||||
|
- `index.md` — 文档索引（推荐作为 AI 上下文入口）
|
||||||
|
- `architecture.md` — 架构图和设计模式
|
||||||
|
- `components.md` — 组件职责
|
||||||
|
- `interfaces.md` — API 列表
|
||||||
|
- `data_models.md` — 数据模型 ER 图
|
||||||
|
- `workflows.md` — 关键流程时序图
|
||||||
|
- `dependencies.md` — 依赖说明
|
||||||
|
|
||||||
|
## Custom Instructions
|
||||||
|
<!-- This section is for human and agent-maintained operational knowledge.
|
||||||
|
Add repo-specific conventions, gotchas, and workflow rules here.
|
||||||
|
This section is preserved exactly as-is when re-running codebase-summary. -->
|
||||||
95
README.md
95
README.md
@@ -10,6 +10,7 @@ AI 驱动的多租户客服与工单管理系统，支持飞书机器人、WebSo
|
|||||||
- **多租户** — 数据按 tenant_id 隔离，每个租户独立的系统提示词和飞书群绑定
|
- **多租户** — 数据按 tenant_id 隔离，每个租户独立的系统提示词和飞书群绑定
|
||||||
- **数据分析** — 工单趋势、预警统计、满意度分析，支持按租户筛选
|
- **数据分析** — 工单趋势、预警统计、满意度分析，支持按租户筛选
|
||||||
- **预警系统** — 自定义规则、多级别预警、批量管理
|
- **预警系统** — 自定义规则、多级别预警、批量管理
|
||||||
|
- **Agent 模式** — ReAct 风格 LLM Agent，支持工具调度（知识搜索、车辆查询、飞书消息等）
|
||||||
- **系统管理** — 模块权限控制、流量/成本/安全配置、Token 监控
|
- **系统管理** — 模块权限控制、流量/成本/安全配置、Token 监控
|
||||||
|
|
||||||
## 快速开始
|
## 快速开始
|
||||||
@@ -23,25 +24,58 @@ python start_dashboard.py
|
|||||||
|
|
||||||
访问 http://localhost:5000，默认账号 `admin` / `admin123`。
|
访问 http://localhost:5000，默认账号 `admin` / `admin123`。
|
||||||
|
|
||||||
|
## 系统架构
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TB
|
||||||
|
subgraph Clients["客户端"]
|
||||||
|
Browser["浏览器 Dashboard"]
|
||||||
|
FeishuBot["飞书机器人"]
|
||||||
|
WSClient["WebSocket"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph App["应用层"]
|
||||||
|
Flask["Flask :5000"]
|
||||||
|
WS["WebSocket :8765"]
|
||||||
|
FeishuLC["飞书长连接"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Services["业务层"]
|
||||||
|
DM["对话管理"]
|
||||||
|
KM["知识库"]
|
||||||
|
WOS["工单同步"]
|
||||||
|
Agent["ReAct Agent"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Infra["基础设施"]
|
||||||
|
DB["SQLAlchemy"]
|
||||||
|
LLM["Qwen API"]
|
||||||
|
Cache["Redis"]
|
||||||
|
end
|
||||||
|
|
||||||
|
Clients --> App
|
||||||
|
App --> Services
|
||||||
|
Services --> Infra
|
||||||
|
```
|
||||||
|
|
||||||
## 项目结构
|
## 项目结构
|
||||||
|
|
||||||
```
|
```
|
||||||
src/
|
src/
|
||||||
├── config/ # 配置管理（unified_config + config_service）
|
├── config/ # 配置管理（unified_config）
|
||||||
├── core/ # 基础设施（数据库、LLM、缓存、认证）
|
├── core/ # 基础设施（数据库、LLM、缓存、认证、ORM 模型）
|
||||||
├── dialogue/ # 对话管理（realtime_chat、message_pipeline）
|
├── dialogue/ # 对话管理（realtime_chat、dialogue_manager）
|
||||||
├── knowledge_base/ # 知识库（搜索、导入、验证）
|
├── knowledge_base/ # 知识库（搜索、导入、验证）
|
||||||
├── repositories/ # 数据访问层（自动 tenant_id 过滤）
|
|
||||||
├── analytics/ # 监控与分析（预警、Token、AI 成功率）
|
├── analytics/ # 监控与分析（预警、Token、AI 成功率）
|
||||||
├── integrations/ # 外部集成（飞书客户端、工单同步）
|
├── integrations/ # 外部集成（飞书客户端、工单同步）
|
||||||
├── agent/ # ReAct Agent（工具调度）
|
├── agent/ # ReAct Agent（工具调度）
|
||||||
|
├── vehicle/ # 车辆数据管理
|
||||||
|
├── utils/ # 通用工具
|
||||||
└── web/ # Web 层
|
└── web/ # Web 层
|
||||||
├── app.py # Flask 应用
|
├── app.py # Flask 应用
|
||||||
├── blueprints/ # API 蓝图（每个领域一个文件）
|
├── blueprints/ # API 蓝图（16 个，每个领域一个文件）
|
||||||
├── service_manager.py
|
├── service_manager.py # 懒加载服务注册
|
||||||
├── static/js/ # 前端模块
|
├── static/ # 前端资源 (JS/CSS)
|
||||||
│ ├── dashboard.js # 核心
|
|
||||||
│ └── modules/ # 功能模块
|
|
||||||
└── templates/ # Jinja2 模板
|
└── templates/ # Jinja2 模板
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -50,12 +84,47 @@ src/
|
|||||||
| 变量 | 说明 | 默认值 |
|
| 变量 | 说明 | 默认值 |
|
||||||
|------|------|--------|
|
|------|------|--------|
|
||||||
| `SECRET_KEY` | Flask session 密钥 | 随机生成 |
|
| `SECRET_KEY` | Flask session 密钥 | 随机生成 |
|
||||||
|
| `DATABASE_URL` | 数据库连接串 | SQLite |
|
||||||
| `LLM_BASE_URL` | LLM API 地址 | DashScope |
|
| `LLM_BASE_URL` | LLM API 地址 | DashScope |
|
||||||
| `LLM_API_KEY` | LLM API 密钥 | - |
|
| `LLM_API_KEY` | LLM API 密钥 | — |
|
||||||
| `LLM_MODEL` | 模型名称 | qwen-plus-latest |
|
| `LLM_MODEL` | 模型名称 | qwen-plus-latest |
|
||||||
| `FEISHU_APP_ID` | 飞书应用 ID | - |
|
| `FEISHU_APP_ID` | 飞书应用 ID | — |
|
||||||
| `FEISHU_APP_SECRET` | 飞书应用密钥 | - |
|
| `FEISHU_APP_SECRET` | 飞书应用密钥 | — |
|
||||||
|
| `FEISHU_APP_TOKEN` | 飞书多维表格 App Token | — |
|
||||||
|
| `FEISHU_TABLE_ID` | 飞书多维表格 Table ID | — |
|
||||||
| `REDIS_HOST` | Redis 地址 | localhost |
|
| `REDIS_HOST` | Redis 地址 | localhost |
|
||||||
| `ADMIN_PASSWORD` | 默认管理员密码 | admin123 |
|
| `REDIS_ENABLED` | 启用 Redis 缓存 | True |
|
||||||
|
| `EMBEDDING_ENABLED` | 启用 Embedding 语义搜索 | True |
|
||||||
|
| `EMBEDDING_MODEL` | Embedding 模型 | BAAI/bge-small-zh-v1.5 |
|
||||||
|
|
||||||
完整变量列表见 `.env.example`。
|
完整变量列表见 `.env.example`。
|
||||||
|
|
||||||
|
## 技术栈
|
||||||
|
|
||||||
|
| 层级 | 技术 |
|
||||||
|
|---|---|
|
||||||
|
| Web 框架 | Flask 3.x + Flask-CORS |
|
||||||
|
| ORM | SQLAlchemy 2.x (MySQL / SQLite) |
|
||||||
|
| 实时通信 | websockets (port 8765) |
|
||||||
|
| 缓存 | Redis 5.x + hiredis |
|
||||||
|
| LLM | Qwen/DashScope (OpenAI-compatible) |
|
||||||
|
| Embedding | sentence-transformers + BAAI/bge-small-zh-v1.5 (可选) |
|
||||||
|
| NLP | jieba + scikit-learn (TF-IDF) |
|
||||||
|
| 飞书 | lark-oapi 1.3.x |
|
||||||
|
| 认证 | JWT + SHA-256 |
|
||||||
|
|
||||||
|
## 数据库
|
||||||
|
|
||||||
|
- **开发**: SQLite (`data/tsp_assistant.db`)
|
||||||
|
- **生产**: MySQL via PyMySQL
|
||||||
|
- **核心表**: Tenant, WorkOrder, ChatSession, Conversation, KnowledgeEntry, Alert, Analytics, VehicleData, User
|
||||||
|
|
||||||
|
## 部署
|
||||||
|
|
||||||
|
- Docker + docker-compose (MySQL 8, Redis 7, Nginx, Prometheus, Grafana)
|
||||||
|
- Nginx 反向代理 (80/443 → 5000)
|
||||||
|
- 默认端口: Flask 5000, WebSocket 8765, Redis 6379, MySQL 3306
|
||||||
|
|
||||||
|
## 详细文档
|
||||||
|
|
||||||
|
完整技术文档见 `.agents/summary/` 目录，推荐从 `index.md` 开始阅读。
|
||||||
|
|||||||
@@ -2315,7 +2315,6 @@
|
|||||||
<div class="form-text">机器人回复时使用的角色设定，不同租户可以有不同的品牌定位</div>
|
<div class="form-text">机器人回复时使用的角色设定，不同租户可以有不同的品牌定位</div>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
|
||||||
<div class="modal-footer">
|
<div class="modal-footer">
|
||||||
<button type="button" class="btn btn-secondary" data-bs-dismiss="modal">取消</button>
|
<button type="button" class="btn btn-secondary" data-bs-dismiss="modal">取消</button>
|
||||||
<button type="button" class="btn btn-primary" onclick="dashboard.saveTenant()">保存</button>
|
<button type="button" class="btn btn-primary" onclick="dashboard.saveTenant()">保存</button>
|
||||||
|
|||||||
Reference in New Issue
Block a user