Jeason
45badfee82
任务 3.2+3.3: 飞书入口迁移到 MessagePipeline - feishu_bot.py 改用 pipeline.handle_message（去掉 30 行会话管理代码） - feishu_longconn_service.py 改用 pipeline.handle_message（去掉 25 行） - 各入口只负责协议适配，业务逻辑统一在 Pipeline 任务 5: 统一配置管理 - 新增 src/config/config_service.py（ConfigService 单例） - 优先级：环境变量 > system_settings.json > 代码默认值 - 支持点号分隔的嵌套 key、自动类型转换 任务 8: 密码哈希升级 - SHA-256 bcrypt（User.set_password/check_password） - AuthManager.hash_password/verify_password 同步升级 - 兼容旧密码：登录时检测 SHA-256 格式，验证通过后自动升级为 bcrypt - auth_manager.secret_key 改为从环境变量读取 任务 9: 前端事件总线 - TSPDashboard 新增 on/off/emit 方法 - 模块间可通过事件通信，不再只靠直接读写共享状态 README.md 重写 - 功能概览、技术栈、快速开始、项目结构 - 架构要点、多租户、飞书机器人、环境变量 - 开发和部署说明
142 lines
4.8 KiB
Markdown
142 lines
4.8 KiB
Markdown
# TSP 智能助手
|
||
|
||
AI 驱动的多租户客服与工单管理系统，支持飞书机器人、WebSocket 实时对话、知识库语义搜索。
|
||
|
||
## 功能概览
|
||
|
||
- **智能对话** — WebSocket 实时聊天 + 飞书机器人（长连接模式），按租户隔离知识库
|
||
- **工单管理** — 创建、编辑、删除、飞书多维表格双向同步，AI 生成处理建议
|
||
- **知识库** — TF-IDF + 可选 Embedding 语义搜索，支持文件导入、人工验证
|
||
- **多租户** — 数据按 tenant_id 隔离，每个租户独立的系统提示词和飞书群绑定
|
||
- **数据分析** — 工单趋势、预警统计、满意度分析，支持按租户筛选
|
||
- **预警系统** — 自定义规则、多级别预警、批量管理
|
||
- **系统管理** — 模块权限控制、流量/成本/安全配置、Token 监控
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 |
|
||
|---|---|
|
||
| Web | Flask 3.x + Blueprint 架构 |
|
||
| 数据库 | SQLAlchemy 2.x（SQLite 开发 / MySQL 生产） |
|
||
| 实时通信 | websockets（独立服务端口 8765） |
|
||
| 缓存 | 内存缓存 + Redis（可选） |
|
||
| LLM | OpenAI 兼容 API（默认通义千问） |
|
||
| Embedding | sentence-transformers BGE（本地，可选） |
|
||
| 飞书 | lark-oapi SDK（事件订阅 2.0 长连接） |
|
||
| 前端 | Bootstrap 5 + 模块化 JS（无框架） |
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 1. 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 2. 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env 填入 LLM API Key、飞书凭证等
|
||
|
||
# 3. 初始化数据库
|
||
python init_database.py
|
||
|
||
# 4. 启动服务
|
||
python start_dashboard.py
|
||
```
|
||
|
||
访问 http://localhost:5000，默认账号 `admin` / `admin123`。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/
|
||
├── config/ # 配置管理（unified_config + config_service）
|
||
├── core/ # 基础设施（数据库、LLM、缓存、认证）
|
||
├── dialogue/ # 对话管理（realtime_chat、message_pipeline）
|
||
├── knowledge_base/ # 知识库（搜索、导入、验证）
|
||
├── repositories/ # 数据访问层（自动 tenant_id 过滤）
|
||
├── analytics/ # 监控与分析（预警、Token、AI 成功率）
|
||
├── integrations/ # 外部集成（飞书客户端、工单同步）
|
||
├── agent/ # ReAct Agent（工具调度）
|
||
├── vehicle/ # 车辆数据管理
|
||
└── web/ # Web 层
|
||
├── app.py # Flask 应用（页面路由 + Blueprint 注册）
|
||
├── blueprints/ # API 蓝图（每个领域一个文件）
|
||
├── service_manager.py # 服务注册（线程安全懒加载）
|
||
├── static/js/ # 前端模块
|
||
│ ├── dashboard.js # 核心（类定义、事件总线、路由）
|
||
│ └── modules/ # 功能模块（chat、alerts、knowledge 等）
|
||
└── templates/ # Jinja2 模板
|
||
```
|
||
|
||
## 架构要点
|
||
|
||
- **Repository 模式** — `src/repositories/` 封装数据访问，自动附加 tenant_id 过滤
|
||
- **MessagePipeline** — `src/dialogue/message_pipeline.py` 统一消息处理流程，各入口只做协议适配
|
||
- **统一 LLM 客户端** — `src/core/llm_client.py` 同时支持同步和异步调用
|
||
- **配置三层** — 环境变量 > system_settings.json > 代码默认值
|
||
- **前端模块化** — Object.assign(prototype) 扩展，事件总线通信
|
||
|
||
## 多租户
|
||
|
||
每个租户拥有独立的：
|
||
- 知识库数据
|
||
- 对话历史
|
||
- 工单数据
|
||
- 系统提示词（机器人角色设定）
|
||
- 飞书群绑定（不同群自动路由到不同租户的知识库）
|
||
|
||
在「租户管理」页面创建租户、绑定飞书群、设置提示词。
|
||
|
||
## 飞书机器人
|
||
|
||
支持两种接入模式（建议只启用一种）：
|
||
|
||
| 模式 | 说明 | 配置 |
|
||
|------|------|------|
|
||
| 长连接 | 无需公网 IP，推荐 | `python start_feishu_bot.py` |
|
||
| Webhook | 需要公网域名 | 飞书后台配置回调 URL |
|
||
|
||
机器人收到消息后自动：
|
||
1. 根据群 ID 查找绑定的租户
|
||
2. 使用该租户的知识库搜索
|
||
3. 使用该租户的系统提示词生成回复
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `SECRET_KEY` | Flask session 密钥 | 随机生成 |
|
||
| `LLM_BASE_URL` | LLM API 地址 | DashScope |
|
||
| `LLM_API_KEY` | LLM API 密钥 | - |
|
||
| `LLM_MODEL` | 模型名称 | qwen-plus-latest |
|
||
| `FEISHU_APP_ID` | 飞书应用 ID | - |
|
||
| `FEISHU_APP_SECRET` | 飞书应用密钥 | - |
|
||
| `REDIS_HOST` | Redis 地址 | localhost |
|
||
| `REDIS_PASSWORD` | Redis 密码 | - |
|
||
| `ADMIN_PASSWORD` | 默认管理员密码 | admin123 |
|
||
|
||
完整变量列表见 `.env.example`。
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
# 代码格式化
|
||
black . && isort .
|
||
|
||
# 类型检查
|
||
mypy .
|
||
|
||
# 运行测试
|
||
pytest
|
||
```
|
||
|
||
## 部署
|
||
|
||
```bash
|
||
# Docker 部署
|
||
docker-compose up -d
|
||
|
||
# 包含：Flask + MySQL + Redis + Nginx + Prometheus + Grafana
|
||
```
|
||
|
||
详见 `nginx.conf` 和 `docker-compose.yml`。
|