assist/README.md

# TSP 智能助手

AI 驱动的多租户客服与工单管理系统，支持飞书机器人、WebSocket 实时对话、知识库语义搜索。

## 功能概览

- **智能对话** — WebSocket 实时聊天 + 飞书机器人（长连接模式），按租户隔离知识库
- **工单管理** — 创建、编辑、删除、飞书多维表格双向同步，AI 生成处理建议
- **知识库** — TF-IDF + 可选 Embedding 语义搜索，支持文件导入、人工验证
- **多租户** — 数据按 tenant_id 隔离，每个租户独立的系统提示词和飞书群绑定
- **数据分析** — 工单趋势、预警统计、满意度分析，支持按租户筛选
- **预警系统** — 自定义规则、多级别预警、批量管理
- **Agent 模式** — ReAct 风格 LLM Agent，支持工具调度（知识搜索、车辆查询、飞书消息等）
- **系统管理** — 模块权限控制、流量/成本/安全配置、Token 监控

## 快速开始

```bash
pip install -r requirements.txt
cp .env.example .env   # 编辑填入 LLM API Key、飞书凭证等
python init_database.py
python start_dashboard.py
```

访问 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/
├── config/              # 配置管理（unified_config）
├── core/                # 基础设施（数据库、LLM、缓存、认证、ORM 模型）
├── dialogue/            # 对话管理（realtime_chat、dialogue_manager）
├── knowledge_base/      # 知识库（搜索、导入、验证）
├── analytics/           # 监控与分析（预警、Token、AI 成功率）
├── integrations/        # 外部集成（飞书客户端、工单同步）
├── agent/               # ReAct Agent（工具调度）
├── vehicle/             # 车辆数据管理
├── utils/               # 通用工具
└── web/                 # Web 层
    ├── app.py           # Flask 应用
    ├── blueprints/      # API 蓝图（16 个，每个领域一个文件）
    ├── service_manager.py  # 懒加载服务注册
    ├── static/          # 前端资源 (JS/CSS)
    └── templates/       # Jinja2 模板
```

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `SECRET_KEY` | Flask session 密钥 | 随机生成 |
| `DATABASE_URL` | 数据库连接串 | SQLite |
| `LLM_BASE_URL` | LLM API 地址 | DashScope |
| `LLM_API_KEY` | LLM API 密钥 | — |
| `LLM_MODEL` | 模型名称 | qwen-plus-latest |
| `FEISHU_APP_ID` | 飞书应用 ID | — |
| `FEISHU_APP_SECRET` | 飞书应用密钥 | — |
| `FEISHU_APP_TOKEN` | 飞书多维表格 App Token | — |
| `FEISHU_TABLE_ID` | 飞书多维表格 Table ID | — |
| `REDIS_HOST` | Redis 地址 | localhost |
| `REDIS_ENABLED` | 启用 Redis 缓存 | True |
| `EMBEDDING_ENABLED` | 启用 Embedding 语义搜索 | True |
| `EMBEDDING_MODEL` | Embedding 模型 | BAAI/bge-small-zh-v1.5 |

完整变量列表见 `.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` 开始阅读。