# 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. -->