docs: 添加项目文档体系 + 修复租户创建模态框

- 新增 .agents/summary/ 完整文档（架构、组件、接口、数据模型、流程、依赖） - 新增 AGENTS.md（AI 助手导航） - 更新 README.md - 修复 dashboard.html 租户模态框多余 </div> 导致保存按钮失效 - 更新 .gitignore 排除虚拟环境文件
2026-04-08 23:26:17 +08:00
parent 26737747d9
commit 11eef49271
13 changed files with 979 additions and 14 deletions
--- a/.agents/summary/architecture.md
+++ b/.agents/summary/architecture.md
@@ -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 和飞书长连接分别在守护线程中运行。
--- a/.agents/summary/codebase_info.md
+++ b/.agents/summary/codebase_info.md
@@ -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 应用
--- a/.agents/summary/components.md
+++ b/.agents/summary/components.md
@@ -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。
--- a/.agents/summary/data_models.md
+++ b/.agents/summary/data_models.md
@@ -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`: 预警类型
--- a/.agents/summary/dependencies.md
+++ b/.agents/summary/dependencies.md
@@ -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 (可选, 首次下载模型)"]
+```
--- a/.agents/summary/index.md
+++ b/.agents/summary/index.md
@@ -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
+```
--- a/.agents/summary/interfaces.md
+++ b/.agents/summary/interfaces.md
@@ -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` | 响应缓存 |
--- a/.agents/summary/review_notes.md
+++ b/.agents/summary/review_notes.md
@@ -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 配置说明
--- a/.agents/summary/workflows.md
+++ b/.agents/summary/workflows.md
@@ -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 注册的工具包括：知识库搜索、车辆查询、数据分析、飞书消息发送等。