AI 练习项目 智能数仓问答

Data Agent 数据智能分析平台

1. 1 项目概述
2. 1.1 项目定位
3. 1.2 核心能力
4. 1.3 设计目标与非目标
5. 1.4 总体规模（截至 v0.15.3）
6. 2 系统架构
7. 2.1 架构总览
8. 2.2 六层分层（智能问答链路视角）
9. 2.3 工程目录结构
10. 2.4 技术栈
11. 3 功能模块说明
12. 3.1 认证与安全（模块 1）
13. 3.2 权限中心（模块 2）
14. 3.3 数据源管理（模块 3）
15. 3.4 语义层（模块 4）
16. 3.5 知识库（模块 5）
17. 3.6 模型管理（模块 6）
18. 3.7 工作流（模块 7）
19. 3.8 智能问答（模块 8，系统核心）
20. 3.9 作业调度（模块 9）
21. 3.10 消息与公告（模块 10）
22. 3.11 仪表盘（模块 11）
23. 3.12 系统管理（模块 12）
24. 3.13 手工文件管理（模块 13，v0.15.2）
25. 4 智能问答 32 步工作流
26. 4.1 阶段一 · 听懂问题
27. 4.2 阶段二 · 找对数据
28. 4.3 阶段三 · 查得出来
29. 4.4 阶段四 · 算得可信
30. 4.5 阶段五 · 说得明白
31. 4.6 关键可靠性设计
32. 5 数据库设计
33. 5.1 总览
34. 6 API 体系
35. 6.1 统一约定
36. 7 安全设计

1 项目概述

1.1 项目定位

Data Agent 是企业级数据分析智能体系统，位于「业务用户」与「业务数据源」之间的智能编排层：

• 向下：通过语义层理解指标口径与表结构，通过 MCP 网关安全访问数据源；
• 向上：承接业务语言，把模糊的自然语言问题转成可执行、可解释、可复现的查询与分析任务。

一句话概括：让业务用户用口语问数，让每一条结论都带口径、带 SQL、带权限标签。

1.2 核心能力

1.3 设计目标与非目标

设计目标：自然语言问数、口径可信、权限不可绕过、可解释可复现、越用越准。

本期非目标：不替代业务系统原生事务操作；不做实时写入回写（仅查询分析）；不覆盖非结构化数据的语义检索；禁止离线模式，所有功能必须经数据库 API 实现。

1.4 总体规模（截至 v0.15.3）

2 系统架构

2.1 架构总览

系统采用前后端分离 + 六层分层架构。浏览器端 Vue 3 单页应用通过 HTTP/JSON（Bearer Token）访问 FastAPI 应用层；应用层经 MCP 网关这一唯一出口访问数据源，经模型服务访问大模型与向量化能力；所有业务数据统一落在达梦 DM8。

2.2 六层分层（智能问答链路视角）

2.3 工程目录结构

AI AGENT/ ├── backend/ # FastAPI 后端 │ ├── app/ │ │ ├── config.py # 全局配置（APP_VERSION、数据库、模型等） │ │ ├── core/ # database（达梦连接）、安全、响应封装 │ │ ├── routers/ # 18 个路由模块（与前端模块一一对应） │ │ ├── services/ # 业务服务（chat/scheduler/knowledge/...） │ │ └── main.py # FastAPI 入口、静态资源、路由注册 │ ├── data/manual_files/ # 手工文件落盘目录 │ ├── uploads/theme/ # 登录页背景等主题资源 │ └── run.py # uvicorn 启动脚本（reload=False） ├── frontend/ # Vue3 + Vite + TS + Element Plus │ ├── src/api/ # 接口封装（axios） │ ├── src/views/ # 34 个页面组件 │ ├── src/router/ # hash 路由 + 菜单权限过滤 │ └── src/stores/ # Pinia 状态 ├── database/ │ └── init_tables.py # 表结构唯一真相源（建表 + 种子数据 + 幂等迁移） ├── scripts/ # 回归脚本 / 迁移脚本 / 交付导出脚本 ├── start_all.bat # 一键启动（自动拉起达梦 + 后端 + 前端） ├── restart_all.bat / stop_all.bat ├── PROJECT_SPECIFICATION.md # 项目规格书（规格真相源） └── DEV_CHANGELOG.md # 开发变更日志（v0.1.0 ~ v0.15.3 全量）

2.4 技术栈

3 功能模块说明

系统共 13 个功能模块，全部完成。下表为模块全景，其后按模块说明核心能力。

3.1 认证与安全（模块 1）

• 账号密码登录，JWT 鉴权；不开放自助注册（allow_register可配置）。
• 登录安全：连续失败 5 次锁定（可配置锁定时长，持久化到用户表），管理员可解锁与重置密码。
• 密码策略：最小长度、默认密码均可配置（系统设置 security 组）。
• 个人设置：修改密码、昵称、头像。

3.2 权限中心（模块 2）

• RBAC：用户-角色-权限三级关联；菜单可见性 = 用户权限码 ∩ 页面叶子编码。
• 数据权限（get_permission_scope()）：给出 companyCodes × projectCodes 二维范围，贯穿问答过滤、手工文件目录、数据同步等所有模块。
• 目录权限：数据源目录的读/写授权（DS_DIRECTORY_PERMISSION）。

3.3 数据源管理（模块 3）

• 数据源连接配置、连接测试；表字段元数据采集（DS_TABLE_FIELD）。
• 数据源目录树 + 目录权限。
• 是语义层、调度同步、SQL 控制台的统一数据入口。

3.4 语义层（模块 4）

• 业务域（SEM_DOMAIN）→ 语义表（SEM_TABLE，含真实字段清单）→ 指标（SEM_METRIC，含口径、SQL 模板、多版本）。
• 大宽表（SEM_WIDE_TABLE）：SQL 编辑、刷新、物化，供问答「路径A」直接取数。
• 指标版本管理与文档关联（SEM_METRIC_VERSION、SEM_METRIC_DOC_RELATION）。

3.5 知识库（模块 5）

• 文档编辑、分片向量化（KB_CHUNK 存向量 JSON）、AI 训练（LLM 抽取摘要/关键词/问题拼入索引文本，失败降级 raw）。
• 语义检索双门槛：MIN_COS=0.45硬下限；有字面佐证（重叠 ≥0.12）只需过下限，无佐证需STRONG_COS=0.62。
• 问答沉淀（KB_QA_DEPOSIT）：SQL 是唯一可复用资产；历史 ANSWER 仅作快照展示，绝不直接当答案返回。
• 沉淀语义守卫：纯指代短问句（「这几个月呢」）不入沉淀。

3.6 模型管理（模块 6）

• LLM / Embedding / 自定义模型配置；连接探测（probe）+ 真实对话校验（mode=chat）。
• 余额查询：支持四类服务商自动解析，无公开接口的如实提示。
• 配额管控：规则/用量/告警三表（LLM_QUOTA_RULE/USAGE/ALERT）。
• 注意：probe 通过 ≠ Key 可用（部分服务商 /models 不校验），必须真实调用验证。

3.7 工作流（模块 7）

• 32 步五阶段可视化编辑（节点画布）：节点/连线/提示词模板。
• 配置驱动问答运行时：走审批生效（WF_PROMPT_HISTORY 记录提示词历史）。

3.8 智能问答（模块 8，系统核心）

• 会话管理：置顶/收藏/重命名/批量删除/回收站与彻底清理（v0.15.3）。
• 消息流：快捷提问、消息删除、导出、重新生成、引用来源展示。
• 配额：问答配额规则 + 用量统计，管理员可配置用户额度并重置今日用量。
• 32 步执行链路详见第 4 章。

3.9 作业调度（模块 9）

• 任务（SCH_TASK）→ 作业（SCH_JOB，含 SQL/脚本/同步三类）→ 作业参数（SCH_JOB_PARAM，支持dir类手工文件参数与派生占位符）。
• 调度用例（SCH_SCHEDULE_CASE）+ CRON 表达式 + 任务依赖 + 发布流程 + 冲突拦截。
• 运行实例（SCH_TASK_RUN / SCH_JOB_RUN）与重跑批次（SCH_RERUN_BATCH）。
• 数据同步（SCH_DATA_SYNC_CONFIG）：一表一同步、字段映射、并行分桶、同步日志。
• SQL 控制台：多段 SQL 执行、SQL 授权（SCH_SQL_GRANT）、执行历史。
• Python 运行环境与依赖包管理（SCH_PY_ENV / SCH_PY_PKG）。

3.10 消息与公告（模块 10）

• 站内消息（未读/已读）、公告发布（需审批）、审批中心（定义/实例/任务）、我的待办。

3.11 仪表盘（模块 11）

• 统计卡片、图表、最近活动；数据全部来自真实 API 聚合。

3.12 系统管理（模块 12）

• 文件管理（FILE_FOLDER/FILE_RECORD，通用网盘式结构）。
• 空间管理（数据资产目录、空间看板、配额与预警）。
• 日志管理（系统/调度/AI 问询三类日志）。
• 数据字典、系统设置（分组键值）、审计日志（全量操作留痕）。
• 主题管理：32 项可视化配置、6 套预设、实时预览；驱动登录页外观与全站令牌。
• MCP 网关（v0.13.8）：问答取数唯一出口，限流 5 QPS、熔断、高危拦截、监控大屏与日志页。

3.13 手工文件管理（模块 13，v0.15.2）

• 三层目录：公司代码 / (项目代码 | COMMON) / YYYYMM，按用户权限自动生成。
• 表格真实落盘（backend/data/manual_files）+ 数据库登记；csv/xlsx 纯标准库解析预览（.xls 如实提示不支持）。
• 文件登记含入湖跟踪（入湖作业、目标表、行数、状态）。
• Python 作业dir参数：DEFAULT_VALUE = 公司|项目|月份，派生占位符${名__files}/${名__count}/${名__exists}；内置参数manualRoot。
• 示例作业「手工表格入湖」：建表 +DELETE ... WHERE SRC_FILE = ?幂等写入。

4 智能问答 32 步工作流

问答链路分五阶段共 32 步。只有步骤 12（路径 B）由 LLM 生成 SQL，路径 A（大宽表直取）与复用路径不经 LLM。

4.1 阶段一

1. 业务用户提出问题
2. 意图理解、任务规划、加载用户权限域
3. 大模型拆解问题要素
4. 向语义层查询指标定义与表信息
5. 语义层返回指标口径并提示多版本
6. 口径存在歧义时发起澄清确认
7. 业务确认查询条件与业务范围
8. 锁定口径并裁剪查询范围

4.2 阶段二

1. 检索候选表、字段注释与数据血缘
2. 语义层返回表结构与关联关系，判断走大宽表还是 LLM 生成
3. 按用户权限自动过滤表、字段与行数据
4. 注入上下文，交由大模型生成查询语句（仅路径 B 执行）
5. Data Agent 产出查询草稿

4.3 阶段三

1. 静态校验查询语句，拦截高危查询
2. 封装标准化查询并转发至数据源
3. 数据源层行级权限二次校验与脱敏
4. 执行查询
5. 返回结果集与性能统计

4.4 阶段四

1. 结果校验与异常识别
2. 校验不通过时回退重试
3. 大模型做业务归因推理
4. 生成结论并推荐下钻维度
5. 并行发起下钻查询
6. 返回下钻明细与各维度贡献度
7. 交叉验证主指标与下钻明细是否对齐

4.5 阶段五

1. 渲染图表与报告导出
2. 聚合数据图表并生成业务结论
3. 返回自然语言结论与数据依据
4. 为结论附加可复核信息
5. 交付完整分析给业务用户
6. 沉淀问答并回灌知识库（数据打标 + 复用机制）
7. 知识库隔离检索，支撑后续复用

4.6 关键可靠性设计

• SQL 接地三道防线：LLM 生成 SQL 必须注入目标表真实字段清单；_validate_sql_columns()读ALL_TAB_COLUMNS兜底校验；校验失败按规则回退到指标 SQL 模板（回退必须换语句，禁止假重试）。
• 多轮上下文：追问自动继承上一轮的意图/指标/维度（显式维度优先）。
• 维度枚举：枚举型问题分 list/count 两型作答；分组维度按月聚合走SUBSTR(col,1,6)，避免按天拆分。
• 复用机制：默认关闭（可按用户开启）；regenerate 永不复用；复用与绕过全程审计留痕。
• 降级如实：LLM 不可用、语义层无命中、执行失败均如实告知并记录 degraded，绝不伪造数据。

5 数据库设计

5.1 总览

• 数据库：达梦 DM8；用户 INSPECT；业务模式AGENT_BI（95 张表）+ 源模拟模式SAP（15 张表），共 110 张表、1488 列。
• 命名规范：表名/列名全大写下划线；后端出参小驼峰；分页统一data.items。
• 主键：全部为ID INT IDENTITY(1,1) PRIMARY KEY；逻辑外键（命名*_ID/*_CODE）不建物理外键约束，由应用层保证。
• 时间：CREATED_AT DATETIME DEFAULT SYSDATE、UPDATED_AT。
• 大字段：JSON/长文本用 CLOB；向量以 JSON 存 CLOB。

5.4 数据库设计约定（开发纪律）

• database/init_tables.py是表结构唯一真相源：CREATE TABLE IF NOT EXISTS+_ensure_columns()幂等补列，老库可直接原地升级。
• 达梦不支持ADD COLUMN IF NOT EXISTS：新增列必须「先查 ALL_TAB_COLUMNS，再逐个 ALTER TABLE + COMMENT」。
• 索引无IF NOT EXISTS（-2260 已存在），需 try/except 兜底。
• 保留字：ROWS、COMMENT建表/查询时避免直接使用。
• 存量库不补新种子键：新增配置项一律用独立幂等迁移脚本（scripts/_migrate_*.py）。
• 库字符集为 GBK：脚本读写中文需显式PYTHONIOENCODING=utf-8并包TextIOWrapper。

6 API 体系

6.1 统一约定

• 统一响应：{ "code": 0, "message": "ok", "data": ... }；业务失败 code 非 0，鉴权失败 401，越权 403，参数错误 422。
• 分页：请求page / page_size（可选keyword过滤），响应data.items[]+data.total。
• 认证：Authorization: Bearer <token>；GET /api/auth/config、GET /api/system/theme等为公开接口。
• 错误可读：所有错误返回中文可读 message，禁止裸抛堆栈。

6.2 接口分布（v0.15.3 实测 433 个）

7 安全设计