# 数据库管理平台 - 功能总览

> 本文档梳理 `databasePage` 组件集群与 `DatabaseDetailPage` 的整体功能架构。

---

## 一、系统定位

这是一个面向业务用户的**数据库管理与智能问数一体化平台**，支持两种数据源模式：

| 模式 | 说明 | 核心差异 |
|------|------|----------|
| **外部数据源** | 远程 MySQL/PostgreSQL/Oracle/SQL Server/达梦 等 | 标准数据库连接，提供只读/CRUD 管理 |
| **内置数据源** | 平台内建 PostgreSQL 实例 | 支持 AI 技能、工具、环境切换(prod/test)、AI 训练 |

---

## 二、功能模块全景

### 1. 数据源管理

#### 1.1 数据源列表 (`DataSourceList.vue`)
- **卡片式展示**：名称、ID、类型徽章(内置/外部)、数据库类型、运行状态、库数/表数统计
- **无限滚动分页**：IntersectionObserver + useInfiniteScroll，每页 20 条
- **搜索与筛选**：按名称模糊搜索、按状态筛选(运行中/已停止)
- **数据源操作**：
  - 编辑(外部→CreateDataSource, 内置→CreateBuiltinDataSource)
  - 启用/停用(切换 status 0/1)
  - 删除(运行中自动先停用再删除)
- **业务执行入口**：点击打开智能问数聊天界面 (ChatDebugging)
- **查看详情入口**：右侧 Drawer 打开 DatabaseDetail (95% 宽度)

#### 1.2 外部数据源创建/编辑 (`CreateDataSource.vue`) - 4步向导
| 步骤 | 内容 | 核心功能 |
|------|------|----------|
| Step 1 | 选择数据库类型 | MySQL/PostgreSQL/Oracle/SQL Server/达梦，自动填充默认端口 |
| Step 2 | 配置连接信息 | 名称、描述(AI润色)、主机、端口、认证(基础认证/SSL)、用户名密码(AI生成名称)、测试连接 |
| Step 3 | 选择数据库和表 | 树形展开、多选、搜索过滤、分页加载表列表、全选/清空 |
| Step 4 | 确认信息 | 汇总展示已选数据库和表标签 |

#### 1.3 内置数据源创建/编辑/添加表 (`CreateBuiltinDataSource.vue`)
| 模式 | 步骤 | 说明 |
|------|------|------|
| create | 名称描述→业务场景→表结构 | AI 生成表结构，批量创建数据库和表 |
| edit | 名称描述→表结构 | 更新已有内置数据源 |
| addTable | 业务场景→表结构 | 在已有内置数据源下新增表 |

- **AI 能力**：AI 优化描述、AI 生成数据库名、AI 生成表名/表描述/字段描述
- **表结构编辑器**：左右分栏(左侧表列表, 右侧 TableDetailEditor 预览/编辑)
- **提交流程**：创建数据源 → 创建 PostgreSQL 连接 → 创建数据库 → 批量建表 → 检查 AI 训练状态

### 2. 数据库详情 (`DatabaseDetail.vue`)

左侧面板 + 右侧面板的经典布局：

#### 2.1 左侧 - 数据库与表管理
- **数据库选择器**：下拉切换当前数据库，悬浮显示数据库详情(ID/名称/数据源/类型)
- **数据表列表**：
  - 搜索过滤
  - 多选/全选 (Checkbox)
  - 无限滚动加载
  - AI 补全(选中多个表批量触发)
  - 更多操作: AI智能建表、智能导入表、删除库
- **底部功能按钮**：字段关联管理、AI补全管理

#### 2.2 右侧 - 详情视图(三种视图)

**视图 A: 表详情 (`fieldViewMode = fields`)**
- 字段列表表格: 字段名、类型、长度、可空、主键、默认值、注释、描述
- AI 训练状态徽章(已训练/未训练)
- 操作: 修改表、字段关联管理、表订阅(已订阅/未订阅)、刷新
- 用户 ID 字段关联提示(user_id/createById 等自动关联系统用户)

**视图 B: 线上数据 (`fieldViewMode = online`)**
- 通过 `CustomizeDbTable` 组件查看/编辑生产环境真实数据
- 支持增删改查、导出 Excel、智能导入数据

**视图 C: 调试数据 (`fieldViewMode = debug`)**
- 同上，但操作测试环境数据

#### 2.3 右侧 - 字段关联管理视图
- 为当前表的字段建立与目标表字段的映射关系
- 目标表数据更新时自动同步到当前表
- 支持保存配置、添加/删除关联

#### 2.4 右侧 - AI 补全管理视图
- AI 补全任务列表: 任务名、类型、状态(待执行/运行中/成功/失败)、进度
- 任务详情弹窗: 训练结果(格式化代码展示)、耗时、场景描述
- 支持重新执行、删除任务

### 3. 内建表数据管理 (`CustomizeDbTable.vue`)
- 基于 `CommonDbTable` 的完整 CRUD 表格
- 动态列配置: 根据表结构自动生成字段类型、宽度、可编辑性
- **操作能力**: 新增行、编辑行、删除行、导出 Excel、导入数据、刷新
- **导入流程**: 下载模板 → 上传 Excel → AI 识别预览 → 确认导入(调用 postImportDocumentConfirm)
- 环境切换: `target` prop 控制 prod/test

### 4. 智能导入识别 (`TableRecognition.vue`)
- **Step 1: 上传文件**: 选择目标环境(prod/test)，上传 Excel (.xlsx/.xls, <500KB)
- **Step 2: 智能识别**: AI 解析 Excel，预览表结构/数据，支持编辑
- **两种模式**:
  - `table` 模式: 根据 Excel 内容自动生成数据表结构
  - `data` 模式: 根据规范模板识别并导入数据
- 空行过滤、字段标记、模板下载

### 5. 智能问数 / 业务执行 (`ChatDebugging.vue`)
- **三栏布局**: 左侧面板(可折叠) + 中间聊天区 + 右侧信息
- **左侧面板**:
  - 数字员工列表(可收起)
  - 新建会话按钮
  - 会话列表(点击切换、删除)
  - 技能列表(展开/折叠)
    - 技能名称 + 编辑按钮
    - 工具列表(名称、别名、编辑、删除)
    - 至少保留一个工具
- **中间聊天区** (`ChatBusiness` 组件):
  - 数据源插件嵌入输入区 (`DataSourcePlugIn`)
    - 数据库下拉选择
    - 环境切换(生产/测试，仅内置数据源)
  - SQL 消息控制器 (`SqlControllerMsg`)
  - 默认数据库查询提示词(常用查询/数据统计/新手指引)

#### 5.1 SQL 查询结果展示 (`SqlControllerMsg.vue`)
| 视图类型 | 说明 |
|----------|------|
| SQL 代码 | 展示可执行 SQL 语句，支持复制 |
| 图表可视化 | ChartGallery 组件渲染图表 |
| 查询数据 | JSON 格式原始数据，支持复制 |
| 文本说明 | 业务名称、描述、AI 解释 |
| 表格视图 | Ant Design Table 展示查询结果 |
| 添加到工具 | 将 SQL 查询保存为可复用工具 |

- **添加工具功能**:
  - 重复检测(按 sqlTemplate 归一化比对)
  - 仅生产环境可用
  - 技能创建/更新流程(无技能时自动创建 skill + MCP 配置)
  - 通过 EventBus 触发技能刷新

#### 5.2 数据源选择插件 (`DataSourcePlugIn.vue`)
- 紧凑的内联选择器: 数据源名称 → 数据库下拉 → 环境(prod/test)
- 监听 props 变化自动重置无效选择
- 暴露 getSelection/clearSelection/setEnvironment 方法

### 6. API 密钥管理 (`DataSourceKeys.vue` + `DataSourceKeySetting.vue`)
- **密钥列表**: 名称、API Key(脱敏显示/可切换显示)、状态开关(启用/禁用)、创建时间、操作(详情/编辑/删除)
- **两步创建流程**:
  1. 输入密钥名称 → 调用 postApiKey 创建
  2. 弹窗询问是否配置权限 → 打开权限配置
- **权限配置** (`DataSourceKeySetting.vue`) - 3步向导:
  - Step 1: 选择数据源(单选) + 配置数据源级权限
  - Step 2: 选择数据库(单选, 非必填) + 配置数据库级权限
  - Step 3: 选择数据表(多选, 非必填) + 行内配置表级权限
  - Step 4: 完成页(ApiKeyPermissionPreview 汇总) → 批量提交权限
- **权限选项**: 按层级不同(connection/database/table)，每种有对应的读/写/管理等权限
- **API 调用文档**: 切换到文档视图查看调用说明

### 7. 表字段编辑器 (`TableDetailEditor.vue`)
- **表信息编辑**: 表名(AI生成)、表描述(AI优化)
- **字段列表表格**:
  - 序号、字段名、字段类型(分组下拉)、长度、主键、自增、可空、默认值、注释
  - AI 生成字段描述(逐字段)
  - 添加字段(首个字段自动设为主键+自增)
  - 删除字段(有id的字段记录到 deletedColumns)
  - 主键设置后不可取消(已有字段)
  - 自增字段自动切换为整数类型
- **两种模式**: `edit` (编辑) / `preview` (预览)
- **校验功能**: validateFields 供外部调用
- **字段类型** (面向 PostgreSQL): VARCHAR/TEXT/SERIAL/INTEGER/BIGINT/NUMERIC/TIMESTAMP/BOOLEAN/JSONB/INT2/INT4/INT8/SMALLINT/SMALLSERIAL/BIGSERIAL/BOOL/BIGSERIAL

### 8. 其他辅助组件

| 组件 | 功能 |
|------|------|
| `ChartGallery.vue` | 图表可视化渲染 |
| `AddToolModal.vue` | 添加工具弹窗(工具名、描述编辑+AI辅助) |
| `ApiKeyPermissionPreview.vue` | 权限汇总预览组件 |
| `ApiCallDocument.vue` | API 调用文档展示 |
| `DatabaseMessageList.vue` | 数据库消息列表 |
| `field-types-dictionary.json` | 字段类型字典 |

---

## 三、API 接口层 (server/database.ts)

### 数据源管理
| 函数 | 方法 | 用途 |
|------|------|------|
| `getConnectionList` | GET | 数据源列表(分页+搜索+筛选) |
| `getConnectionDetail` | GET | 数据源详情 |
| `postConnectionDetail` | POST | 创建数据源 |
| `putConnectionDetail` | PUT | 更新数据源 |
| `deleteConnection` | DELETE | 删除数据源 |
| `putConnectionChangeStatus` | PUT | 切换数据源状态(启用/停用) |
| `testConnection` | POST | 测试连接 |

### 内置数据库管理
| 函数 | 方法 | 用途 |
|------|------|------|
| `postCreateBuiltinPostgreSQLConnection` | POST | 创建内置 PostgreSQL 连接 |
| `postCreateDatabase` | POST | 创建数据库 |
| `putAlterDatabase` | PUT | 修改数据库 |
| `postCreateTable` | POST | 创建表 |
| `putAlterTable` | PUT | 修改表 |
| `postGenerateTable` | POST | AI 生成表结构 |
| `putUpdateBuiltinDatabase` | PUT | 更新内置数据库 |

### 数据库配置
| 函数 | 方法 | 用途 |
|------|------|------|
| `getConnectionConfig` | GET | 获取数据库配置(含 skillBool) |
| `getConnectionConfigList` | GET | 数据库配置列表 |
| `postConnectionConfig` | POST | 创建数据库配置 |
| `putConnectionConfig` | PUT | 更新数据库配置 |
| `deleteConnectionConfig` | DELETE | 删除数据库配置 |
| `getConnectionRealtimeStructure` | GET | 获取实时数据库结构 |

### 表数据管理
| 函数 | 方法 | 用途 |
|------|------|------|
| `getTableList` | GET | 表列表 |
| `getTableDetail` | GET | 表详情 |
| `getBuiltinTableData` | GET | 获取内置表数据(分页) |
| `postBuiltinTableRows` | POST | 新增表数据行 |
| `putBuiltinTableRows` | PUT | 更新表数据行 |
| `deleteBuiltinTableRows` | DELETE | 删除表数据行 |
| `getBuiltinTableExportExcel` | GET | 导出表数据为 Excel |

### 数据导入
| 函数 | 方法 | 用途 |
|------|------|------|
| `postImportDocumentPreview` | POST | 上传 Excel 预览识别结果 |
| `postImportDocumentConfirm` | POST | 确认导入数据 |

### 技能与工具
| 函数 | 方法 | 用途 |
|------|------|------|
| `getSkillByDatasource` | GET | 根据数据源获取技能 |
| `getSkillBySkillId` | GET | 根据技能ID获取工具列表 |
| `postSkillCreateOrGet` | POST | 创建或获取技能 |
| `putSkillUpdateOrGet` | PUT | 更新技能配置 |
| `postSkillToolUpdateOrGet` | POST | 创建/更新技能工具 |
| `postDeleteSkillTool` | POST | 删除技能工具 |
| `postSqlSkillConfirmTools` | POST | 确认并创建 SQL 工具 |

### AI 训练
| 函数 | 方法 | 用途 |
|------|------|------|
| `getAiTrainingList` | GET | AI 训练任务列表 |
| `postAiTrainingCreateBySelected` | POST | 创建 AI 训练任务 |
| `getAiTrainingDetail` | GET | 训练任务详情 |

### API 密钥
| 函数 | 方法 | 用途 |
|------|------|------|
| `getApiKeyList` | GET | 密钥列表 |
| `postApiKey` | POST | 创建密钥 |
| `putApiKey` | PUT | 更新密钥 |
| `deleteApiKey` | DELETE | 删除密钥 |
| `getApiKeyPermission` | GET | 获取密钥权限 |
| `postApiKeyPermissionGrantBatch` | POST | 批量授予权限 |

### 订阅
| 函数 | 方法 | 用途 |
|------|------|------|
| `postDatasourceSubscriptionToggle` | POST | 切换表订阅状态 |

### SQL 执行
| 函数 | 方法 | 用途 |
|------|------|------|
| `executeSql` | POST | 执行 SQL 查询 |

---

## 四、状态管理与通信

- **Pinia Store**: `useDatabaseChatStore` 管理选中数据库、环境、技能状态
- **EventBus**: `EVENTS.RELOAD_SKILL_DATA` 用于工具添加后刷新技能数据
- **权限控制**: `hasPermission()` 函数按权限标识控制按钮可见性

## 五、权限标识体系

| 权限标识 | 控制范围 |
|----------|----------|
| `database:create` | 创建数据源 |
| `database:edit` | 编辑数据源 |
| `database:delete` | 删除数据源 |
| `database:import` | 导入表/数据 |
| `database:export` | 导出表 |
| `database:table:create` | AI 智能建表 |
| `database:table:ai:complete` | AI 补全功能 |
| `database:apikey:view` | 查看密钥管理 |
| `database:apikey:create` | 创建密钥 |

---

## 六、关键技术特点

1. **AI 深度集成**: 描述润色、名称生成、表结构自动生成、字段描述生成、AI 补全、AI 训练
2. **双环境隔离**: 生产/测试环境切换，测试环境限制添加工具等敏感操作
3. **无限滚动**: IntersectionObserver + 哨兵元素实现列表分页加载
4. **三级权限体系**: 数据源 → 数据库 → 数据表，通过 API Key 控制访问粒度
5. **MCP 工具集成**: 内置数据源自动配置 MCP Server (`lzwcai-mcp-sqlexecutor`)，支持 AI 工具注册
6. **Excel 智能导入**: AI 识别 Excel 内容，自动匹配表结构，支持表结构和数据两种导入模式
