assist/README.md

# 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`。