

# 更新日志
| <font style="color:rgb(0, 0, 0);">更新时间</font> | <font style="color:rgb(0, 0, 0);">逻辑需求</font> | <font style="color:rgb(0, 0, 0);">变更内容</font> | <font style="color:rgb(0, 0, 0);">变更人</font> | <font style="color:rgb(0, 0, 0);">变更版本</font> |
| --- | --- | --- | --- | --- |
| 2026-05-14 | 1、统一异构数据源的接入、扫描、管理；<br/>2、优化数据资源组织与业务化分组：支持系统内置分组（按数据源）和自定义分组（可嵌套、重命名、删除、导出）；<br/>3、支持用户直接创建自定义数据资源：逻辑视图（View）和数据集（Dataset）。  | <font style="color:rgb(0, 0, 0);">文档覆盖了「数据连接」与「数据资源」两大模块的交互改造，具体做了以下几件事：</font><br/>1. <font style="color:rgb(0, 0, 0);"></font>**<font style="color:rgb(17, 24, 39);">数据连接详情页重构</font>**<font style="color:rgb(0, 0, 0);">：去掉原有的【库表结构】Tab，将基本信息拆分为「基础参数」与「高级参数」两组，新增「扫描管理」模块（扫描策略 + 扫描任务）</font><br/>2. **<font style="color:rgb(17, 24, 39);">调整数据资源详情抽屉</font>**<font style="color:rgb(0, 0, 0);">：以 Tab 形式集成「资源详情（基本信息 + 字段信息）」「数据预览（默认前 1000 条）」「物化配置」三块内容，用户无需离开列表即可查看资源结构和样例数据</font><br/>3. **数据资源组织与业务化分组**<font style="color:rgb(0, 0, 0);">支持系统内置分组（按数据源）和自定义分组（可嵌套、重命名、删除、导出）。 自定义分组可直接创建逻辑视图（View）或数据集（Dataset）。 </font><br/>4. **<font style="color:rgb(17, 24, 39);">新增「语义理解」能力</font>**<font style="color:rgb(0, 0, 0);">：在资源列表操作菜单和资源详情抽屉顶部提供入口，由 AI 自动解析资源的业务含义、字段语义和推荐使用场景，用户可采纳 AI 建议自动回填字段描述</font><br/>5.  **逻辑视图与数据集管理**逻辑视图：虚拟资产，不存数据，用于跨表/跨源查询。 数据集：可写入 数据库，支持 Schema 编辑器管理字段。 <br/>6. **扫描与元数据获取：**平台读取数据连接下的库/表/Schema。 提供扫描策略与扫描任务历史。 扫描结果决定可创建的逻辑视图元数据。  | 范灵秀 | 0.7.0 |


# **<font style="color:#000000;">逻辑设计</font>**
_<font style="color:#808080;">说明：本文档补充逻辑设计中未阐述清楚的部分，仅列出对整体交互一致性有影响的内容，单点字段规则详见各模块原型。</font>_

# **<font style="color:#000000;">一、功能概述</font>**
**一句话定义：**为 VEGA 虚拟化引擎提供「数据连接 → 数据资源」的统一接入与编排能力，让管理员能在同一界面完成数据源接入、资产组织和语义理解。

**功能目的：**解决数据源分散、资源命名不一致、缺少业务化分组与语义说明的问题，建立从物理连接到业务可消费资源的标准化通道。

**目标用户：**平台管理员、数据工程师、业务知识网络的搭建者。

**功能位置：**全局业务知识网络 → 通用业务知识网络 → 数据连接 / 数据资源 两个一级模块。

# **<font style="color:#000000;">二、典型使用场景</font>**
### **<font style="color:#404040;">场景 1：管理员接入新数据源并组织为业务资源</font>**
**触发条件（When）：**业务侧需要使用新数据源进行问数 / 分析，但平台尚未接入。

**问题原因（Why）：**原有交互需要在多个页面切换：连接 → 库表 → 资产命名，路径过长且缺少分组组织。

**用户目标（What to achieve）：**在同一个门户内完成「建立连接 → 扫描 → 自定义分组 → 创建资源」的闭环。

### **<font style="color:#404040;">场景 2：业务用户在自定义分组下快速创建逻辑视图</font>**
**触发条件：**需要将多张物理表抽象为一张面向业务的视图，例如「客户 360」。

**问题原因：**原型只能在系统内置分组下浏览，缺少创建入口；新建必须先切换分组才能看到按钮。

**用户目标：**在侧边栏分组旁直接创建资源，无需切换上下文；并能选择视图（不存数据）或数据集（OpenSearch 写入）。

### **<font style="color:#404040;">场景 3：业务用户检索资源并理解其业务含义</font>**
**触发条件：**用户在「全部」列表中找到候选资源，但不确定字段含义与数据形态。

**用户目标：**通过资源详情抽屉（资源详情 / 数据预览 / 物化配置）+【语义理解】按钮，快速判断该资源是否满足业务问数所需。

# **<font style="color:#000000;">三、关键概念</font>**
### **<font style="color:#404040;">数据连接 Data Connection</font>**
**定义：**对一个物理数据源（MySQL / Oracle / OpenSearch 等）的接入配置，包含连接参数、认证信息与扫描策略。

**作用：**决定平台「能连到哪儿」，是所有数据资源的物理来源。

**背景：**VEGA 架构采用非侵入式虚拟化，连接本身不搬运数据，仅维护元数据与凭证。

### **<font style="color:#404040;">数据资源 Data Resource</font>**
**定义：**对外暴露的可消费数据单元。包含两个子类：逻辑视图（View）与数据集（Dataset）。

**作用：**是业务知识网络与 AI 员工实际查询、引用的对象。

**背景：**在系统内置分组之外，新增「自定义分组」用于业务化组织资源。

### **<font style="color:#404040;">逻辑视图 View</font>**
**定义：**📊 逻辑派生资产，本质是一套查询逻辑，不存储实际数据。

**作用：**用于跨表 / 跨源的实时聚合、口径统一。

**背景：**执行时下推到对应数据源，不占用存储。

### **<font style="color:#404040;">数据集 Dataset</font>**
**定义：**📦 原生可写数据集，数据通过 API 直接写入。

**作用：**适用于平台沉淀型数据、外部系统推送、AI 加工结果落库。

**背景：**支持 Schema 编辑器：字段名、类型、主键、字段特征、特征设置等。

### **<font style="color:#404040;">扫描 Scan</font>**
**定义：**平台从数据连接读取库 / 表 / Schema 的过程，可按需设置扫描范围。

**作用：**决定连接下「能看到哪些数据资源」，是创建逻辑视图的元数据基础。

**背景：**在数据连接详情下，通过「扫描策略 + 扫描任务」两层模型管理。

### **<font style="color:#404040;">语义理解 Semantic Understanding</font>**
**定义：**由 AI 自动解析资源的业务含义、字段语义、潜在用途，并生成自然语言说明。

**作用：**降低业务用户理解资源结构的门槛，加速接入业务知识网络。

**背景：**入口出现在资源列表操作 与 资源详情抽屉顶部。

# **<font style="color:#000000;">四、功能结构 / 信息架构</font>**
整体架构按照「通用业务知识网络 → 模块 → 详情抽屉」三层组织：

+ 通用业务知识网络：左侧导航包含「数据连接」与「数据资源」两大模块。
+ 数据连接模块：连接列表 → 连接详情抽屉（基本信息 / 扫描管理）。
+ 数据资源模块：左侧分组树 + 右侧资源列表 + 资源详情抽屉。
+ 分组树由三类节点构成：
    - 【全部】：聚合所有内置 + 自定义资源。
    - 系统内置（按数据源）：自动按连接组织。
    - 自定义分组：用户创建，支持嵌套、重命名、删除、导出。
+ 资源详情抽屉：资源详情 / 数据预览 / 物化配置三 Tab，顶部带【语义理解】入口。

# **<font style="color:#000000;">五、操作流程</font>**
## **<font style="color:#000000;">操作 1：新建数据连接并查看详情</font>**
**入口：**「全局业务知识网络」 →「通用业务知识网络」 → 「数据连接」 → 列表右上角【新建】。

**步骤：**

+ 点击【新建】，按向导填写连接类型与参数，测试通过后保存。
+ 在连接列表中点击该连接行，打开「数据连接详情抽屉」。
+ 详情抽屉顶部显示「数据连接详情」标题；内容采用可折叠 Section。
+ 「基本信息」内分为两组小节：基础参数（连接名/类型/地址/端口/用户名/描述等）、高级参数（连接状态开关、健康度、表数量、字段数量、容量、最近扫描时间、创建/更新时间、创建人）。
+ 「扫描管理」展示扫描策略列表与扫描任务历史。

**结果：**用户可在一个抽屉内完成连接的查看、启停与扫描查看，去除原【库表结构】Tab。

**异常处理：**测试连接失败时在向导内 toast 提示原因；扫描任务失败时任务状态显示为 失败 红色徽标。

## **<font style="color:#000000;">操作 2：在自定义分组下新建逻辑视图 / 数据集</font>**
**入口：**「全局业务知识网络」 →「通用业务知识网络」 → 「数据资源」 → 左侧「自定义分组」标题旁的【+】下拉。

**步骤：**

+ 点击侧边栏自定义分组上的 +，下拉显示：新建分组 / 新建逻辑视图 / 新建数据集。
+ 选择【新建逻辑视图】或【新建数据集】，打开右侧抽屉，分两步：
    - 第一步「基本信息」：名称（必填）、描述、所属分组、类型说明卡片（View vs Dataset）。
    - 第二步「详细配置」：
        * 逻辑视图：选择数据源 → 选择基础表 → 编写查询逻辑（参考截图原型）。
        * 数据集：Schema 编辑器（字段名、类型 STRING/INTEGER 等、主键复选框、字段特征、特征设置、操作）。
+ 点击【保存】，新资源出现在当前分组下。

**结果：**无需切换分组也可创建；自定义分组旁的入口与「新建分组」按钮整合到同一下拉中。

## **<font style="color:#000000;">操作 3：管理自定义分组</font>**
**入口：**鼠标悬停到任意自定义分组节点。

**步骤：**

+ 分组节点 hover 时，节点右侧显示 ⋯（更多）按钮。
+ 点击 ⋯ 出现下拉菜单：重命名 / 删除 / 导出。
+ 「删除」需二次确认，且当分组下还有资源时给出阻止性提示。

**结果：**操作图标默认隐藏，仅在 hover 时出现，避免视觉噪音。

## **<font style="color:#000000;">操作 4：浏览全部资源并查看资源详情</font>**
**步骤：**

+ 点击【全部】，右侧混合展示系统内所有数据资源（内置 + 自定义）。
+ 点击资源名称 或 操作-查看，同页面打开「资源详情抽屉」。
+ 抽屉以 Tab 切换三大块：资源详情 / 数据预览 / 物化配置。
+ 「资源详情」-基本信息：默认展示 ID、名称、技术名称、分组、类型、查询类型、数据源、状态、创建/更新时间等；点击【展开更多信息】显示资源条数、所属部门、信息系统、数据等级、责任人、更新频率。
+ 「资源详情」-字段信息：字段显示名称、字段技术名称、字段类型、原始类型、字段描述、原始描述、字段特征类型、字段特征。
+ 「数据预览」：按字段信息默认展示前 1000 条数据。
+ 「物化配置」：当前留空。

**结果：**用户在不离开列表的前提下，完成资源结构、样例数据的速览。

## **<font style="color:#000000;">操作 5：调用语义理解</font>**
**入口：**① 资源列表行操作菜单 - 语义理解；② 资源详情抽屉顶部 - 【✨ 语义理解】按钮。

**步骤：**

+ 点击【语义理解】，系统调用 AI 对该资源进行业务语义解析。
+ 解析结果以面板/弹层形式呈现：业务概述、字段语义建议、推荐使用场景。
+ 用户可「采纳」AI 给出的字段描述，自动回填到字段信息。

# **<font style="color:#000000;">六、验证规则</font>**
| **<font style="color:rgb(255, 255, 255);">字段 / 操作</font>** | **<font style="color:rgb(255, 255, 255);">规则</font>** | **<font style="color:rgb(255, 255, 255);">提示文案</font>** |
| --- | --- | --- |
| 资源名称 | 必填，2-32 字符，同分组内不可重复 | 请输入资源名称 / 名称已存在 |
| 技术名称 | 必填，小写字母 / 数字 / 下划线，长度 ≤ 64 | 技术名称格式不合法 |
| 数据集字段名 | 必填，符合标识符规则；至少 1 个主键 | 请至少指定一个主键字段 |
| 删除自定义分组 | 分组下存在资源时不允许删除 | 请先迁移或删除该分组下的资源 |
| 连接启停 Switch | 停用后该连接下所有资源进入只读 | 停用将影响 N 个数据资源，确认继续？ |
| 语义理解 | 5 分钟内对同一资源最多调用 3 次 | 请求过于频繁，请稍后再试 |


# **<font style="color:#000000;">附录</font>**
交互稿：[https://www.figma.com/design/HrkIHXGb1yW2hZq6Lf4Slx/%E4%B8%9A%E5%8A%A1%E7%9F%A5%E8%AF%86%E7%BD%91%E7%BB%9C?node-id=2753-4866&t=1KkvrvcHMglfo5W7-1](https://www.figma.com/design/HrkIHXGb1yW2hZq6Lf4Slx/%E4%B8%9A%E5%8A%A1%E7%9F%A5%E8%AF%86%E7%BD%91%E7%BB%9C?node-id=2753-4866&t=1KkvrvcHMglfo5W7-1)



