project-overview.md

项目概览与核心概念

SQLBot 是面向企业数据分析场景的智能问数系统。它让用户用自然语言提出业务问题，由系统结合数据源元数据、术语库、SQL 示例、权限上下文和大模型能力生成 SQL，查询数据，并返回表格、图表、分析说明或预测结果。

产品定位

SQLBot 不是传统报表工具的替代品，而是让“临时问题”和“探索式分析”更容易完成。典型使用路径是：

1. 管理员配置大模型、工作区、用户和数据源。
2. 数据负责人补充表字段说明、表关系、术语库和 SQL 示例。
3. 业务用户在问答界面提出自然语言问题。
4. 系统自动选择相关上下文，生成 SQL，执行查询并生成结果。
5. 有价值的结果可以继续分析、预测、推荐问题或沉淀到仪表盘。

核心概念

概念	说明
工作区	SQLBot 的资源隔离单元，用来组织用户、数据源、助手、权限和业务配置。
用户	登录和权限主体。管理员可管理系统资源，工作区管理员负责工作区内资源。
模型	大语言模型和 Embedding 模型配置。LLM 负责理解问题、生成 SQL 和分析文本，Embedding 用于召回相似上下文。
助手	面向特定问数场景的应用配置，可绑定数据源、提示词、外观和嵌入能力。
数据源	外部数据库或 Excel/CSV 数据的连接配置，是 SQL 生成和执行的目标。
元数据	数据库的表、字段、字段类型、注释、表关系等结构信息。
术语库	维护业务词、同义词和解释，帮助模型把自然语言映射到正确字段和计算口径。
数据训练	维护自然语言问题、参考 SQL 或说明示例，用于校准模型生成结果。
问答	用户发起的自然语言分析会话，包含问题、SQL、查询结果、图表、分析日志和推荐问题。
仪表盘	保存和展示问答结果中的图表与文本组件，用于沉淀稳定分析资产。
嵌入	将助手或问答能力嵌入到外部 Web 页面或弹窗中。
MCP	面向外部工具和智能体的调用入口，使其他应用能够访问 SQLBot 的问数能力。

RAG 与 Text-to-SQL

SQLBot 的问答质量不只依赖大模型本身。系统会在生成 SQL 前组织多类上下文：

• 数据源、表、字段和表关系；
• 用户问题对应的相似表和数据源 Embedding 召回；
• 业务术语和同义词；
• 已维护的 SQL 示例和数据训练内容；
• 当前用户、工作区、助手和权限上下文；
• 历史问答日志中可复用的生成信息。

这些上下文会进入生成 SQL、生成图表、分析说明、预测和推荐问题等模板，让模型输出更贴近当前业务口径。

主要用户角色

角色	关注点
系统管理员	部署 SQLBot，维护用户、认证、模型服务、系统参数和全局配置。
工作区管理员	接入数据源，维护元数据、术语库、SQL 示例、助手和工作区成员。
业务用户	通过自然语言查询数据，查看图表、分析结果和仪表盘。
二次开发者	基于现有前端、网关、数据服务和集成入口扩展功能。

当前能力边界

• 对外访问以 api-node:8000 为入口，前端和公开 API 均走该入口。
• Python FastAPI 服务仍承担主要数据面能力，包括数据源适配、Embedding、SQL 生成执行、流式问答、Excel/文件处理和 MCP。
• Node 网关当前以健康检查、请求追踪、OpenAPI 入口和兼容透传为主，未迁移接口会继续转发到 Python。
• 文档只描述当前仓库中已有的能力，不把未来迁移计划写成已完成能力。