Files

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

- 新增 .agents/summary/ 完整文档（架构、组件、接口、数据模型、流程、依赖）
- 新增 AGENTS.md（AI 助手导航）
- 更新 README.md
- 修复 dashboard.html 租户模态框多余 </div> 导致保存按钮失效
- 更新 .gitignore 排除虚拟环境文件

2026-04-08 23:26:17 +08:00

3.9 KiB

Raw Permalink Blame History

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 端点模式：

@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 — 依赖说明

3.9 KiB Raw Permalink Blame History Unescape Escape