# 智能数据平台（AI Data Platform）需求文档
**版本：** v1.0.0 ｜ **日期：** 2026-04-08 ｜ **状态：** 草稿

---

## 一、项目背景
企业日常面对海量业务数据，传统分析模式存在以下问题：用户依赖数据团队写SQL，响应慢，无法即时决策，数据链路不透明，难以追溯数据来源，数据分析和报表生成流程繁琐，ETL 流程复杂且维护成本高。

为满足企业需求，亟需构建一套以自然语言为入口、以数据仓库为底座、以安全合规为保障的智能数据分析平台，让数据民主化，使业务人员无需懂 SQL 即可完成复杂的数据查询与分析。

## 二、项目目标
构建一套基于 AI 的对话式数据分析 + 数据采集 + 数据仓储 + 数据治理平台，实现从自然语言查询到结果可视化、导出、服务化以及基础数据安全管理的全流程能力，达到为上层应用提供数据支持，如舆情分析和AI Ops。

## 三、功能需求概览
### 聊天式查询（NL2SQL）
用户通过对话框输入自然语言，系统自动生成并执行 SQL，返回结构化结果，可多轮对话修正。单次查询行数上限 10,000（管理员可配置），超时 30 秒。

**核心要点：**

+ 语义层定义，需要手动维护
    - 统一指标，绑定唯一聚合逻辑、可用维度（时间/地区等）、过滤条件
    - 枚举值映射（如 status=1 自动转译为 "完成"）
    - join关系定义避免模型自由关联
+ RAG增强的Schema召回，数据库中表较多，无法全部放入Prompt 
    - 表和字段的向量化，按用户问题做相似度召回（Doris混合检索，使用关键词检索 + 向量语义检索）
    - 相似SQL的样本召回（方案待确定）
+ SQL 生成后须经语法验证、安全验证，失败自动重试（最多 3 次，需要携带错误信息修正）
+ 表关联关系的知识图谱，可用于join查询（方案待确定）
+ 查询历史记录，对比执行准确率

---

### 表格/报表结果展示
聊天式查询将结果直接返回再对话框中，需要以更专业化的表格与图表形式呈现，支持交互操作。

**核心要点：**

+ 表格使用专业表格插件展示，支持简单交互操作，例如过滤，宽度调整等
+ 使用 ECharts / DataV 渲染，需要根据字段类型自动推荐图表（折线/柱状/饼图），支持表格与图表的双向联动
+ 生成数据摘要（描述）内容
+ 表格使用Excel导出，全量数据导出（.xlsx, .csv），中文表头，数值保持格式
+ 图表使用PDF导出

---

### 结果固化（API/MCP）
将保存的查询封装为对外服务，供外部系统集成调用。

**核心要点：**

+ 一键"发布为 API"，自定义路径、参数等，可生成接口文档；
+ 版本管理或变更机制（查询逻辑或Schema变更）
+ 支持封装为 MCP Tool（含 `name`/`description`/`inputSchema`用户填写或自动从SQL中提取），供 AI Agent 调用
+ 统一 API 网关处理鉴权、限流、CORS、日志、调用监控（QPS、成功率、延迟、错误码分布）

---

### 基础 Guardrail
在 AI 处理链路中建立安全护栏，防止注入攻击与数据泄露。

**核心要点：**

| 环节 | 防护内容 |
| --- | --- |
| 输入过滤 | 提示词注入、SQL 注入尝试、敏感词、越权意图、超长输入（>2000字符）和LLM Prompt 的注入防护 |
| SQL 安全 | 仅允许 SELECT，禁止 DDL/DML，禁止危险函数，表名须在元数据白名单内 |
| 输出过滤 | 手机号/身份证自动打码，敏感词屏蔽，越权字段值拦截 |
| 审计日志 | 所有请求记录（含拒绝原因），只读不可删，保留 1 年 |


+ 过滤规则可在管理界面配置（敏感词库、黑名单函数），更新即时生效

---

### ETL 采集
构建全链路数据管道，数据分四层流转。

**数据分层：**

| 层次 | 说明 |
| --- | --- |
| ODS（贴源层） | 原始数据，不做业务加工，按日期分区 |
| DWD（明细层） | 字段标准化：手机号、身份证号脱敏<br/>去重：基于业务主键 + 时间戳的拉链表 / 最新记录去重逻辑<br/>质量探针：清洗过程中触发规则校验（非空、长度、正则） |
| DWS（汇总层） | 按维度预聚合（日期/省份/品牌/企业） |
| ADS（应用层） | 面向查询的宽表，字段含中文注释，NL2SQL 模块优先读取该层 |


**核心要点：**

+ 清洗规则配置化，无需改代码即可调整
+ 基于 Airflow 或轻量调度器管理 ETL 任务，支持手动触发与 DAG 可视化
+ 每次 ETL 后自动计算数据质量指标（记录数波动、空值率、时效性），异常告警
+ 支持使用Agent完成ETL

---

### 后续内容 （先不做）
+ 数据级别RBAC，实现行级（RLS）和列级（CLS）精细化数据权限控制。
    - 行级权限（RLS）：以 SQL WHERE 子句定义数据范围，在 SQL 执行前自动注入，用户无感知
    - 列级权限（CLS）：不可见字段自动脱敏（`***`）或直接拒绝查询；敏感字段不注入 NL2SQL Schema
    - 表级权限：白名单模式，无权表对用户完全透明
    - 权限管理界面：支持模拟特定用户查询结果（权限验证用）
    - 权限变更即时生效，触发缓存失效；所有变更写入不可删除的审计记录
+ 血缘下钻
    - 在查询结果中逐级深入分析，并追踪数据来源
    - 下钻路径可配置（时间：年→月→日；地区：省→市→区县）
    - 面包屑导航支持任意层级回退
    - 最小血缘：仅追踪当前数据的直接上游表，用户可点击"查看数据来源"查看
    - 血缘图谱页：DAG 有向图可视化，支持搜索表名、层级过滤

---

## 四、功能验证
| 类别 | 关键指标 |
| --- | --- |
| NL2SQL | NL2SQL 端到端 P95 ≤ 15s；API 调用 P99 ≤ 2s；并发 ≥ 200 用户；100条测试集，SQL 准确率 ≥ 85%；5轮多轮对话正确率 ≥ 90% |
| 结果展示 | 5万行 Excel 导出 ≤ 30s；PDF 含图表无乱码 |
| 安全Guardrails | SQL注入和LLM Promote注入； |
| 浏览器 | Chrome/Edge/Firefox 100+（不支持 IE） |