1. 页面概览
数据源管理页（路由 /datasources）属于 AIP「Action 栏目」，管理平台接入的外部数据源：列表展示（ID/名称/类型/描述/连接信息），支持新建、编辑、测试连接、导入元数据与删除；连接参数存于 connection_config，密码不回显。
一句话总结：AIP 数据源 CRUD + 测试连接 + 元数据导入页，对接后端
/datasources 系列接口。2. 访问入口
- 路由与菜单：路由
/datasources（nameDataSources），挂 ActionLayout（左侧菜单「数据源管理」），Action 工作台首页卡片也可进入；源码action/web/src/views/DataSourcesPage.vue（340 行）。 - 认证与权限：路由
meta.requiresAuth = true，需先登录 AIP（aip_token）；后端接口挂 protected 组，仅 JWT（非管理员也可增删改）。 - 端口与 API 前缀：AIP 18080；API 前缀
/aip-api/v1（aipClient，/datasources系列）。
3. 界面布局
┌──────────────────────────────────────────────┐ │ ① 页头：数据源管理 + [新建数据源/收起表单] │ │ ② 操作结果提示条（alert，可关闭） │ │ ③ 新建/编辑表单卡 + [创建/更新数据源][取消] │ │ 名称*/类型*/主机/端口/数据库名/用户名/密码/描述 │ │ ④ 数据源列表卡（加载中 / 空态 / 表格） │ │ ⑤ 结果弹窗（测试连接/导入元数据 JSON） │ └──────────────────────────────────────────────┘
各板块职责：
- ① 页头：标题 + 「新建数据源」切换表单显隐（表单已开时变「收起表单」）。
- ③ 新建/编辑表单：编辑时标题变「编辑数据源」、提交按钮变「更新数据源」；取消即收起。
- ④ 列表：加载中显示「加载中...」，空数据显示「暂无数据源，请点击"新建数据源"添加。」；行内操作：测试连接 / 导入元数据 / 编辑 / 删除。
- ⑤ 结果弹窗：
modal-overlay遮罩 +modal-card，展示测试连接/导入元数据接口返回的 JSON；点「关闭」或遮罩空白处关闭。
4. 交互元素
| 控件 | 位置 | 含义与作用 |
|---|---|---|
| 「新建数据源」/「收起表单」 | 页头 | 切换表单显隐（showCreateForm） |
| 数据源名称 * | 表单 | 必填；占位 如 sales_data_warehouse |
| 数据库类型 * | 表单 | 必填下拉：PostgreSQL(POSTGRESQL)/MySQL(MYSQL)/SQLite(SQLITE)/SQL Server(SQLSERVER) |
| 主机地址 / 端口 / 数据库名 / 用户名 | 表单 | 连接参数；占位 localhost / 5432 / chatbi_forge_dev / postgres；端口为 number 类型 |
| 密码 | 表单 | type=password，占位「输入密码」；编辑时不回填，留空表示不修改 |
| 描述 | 表单 | textarea（2 行），占位「数据源的简单描述...」 |
| 「创建数据源」/「更新数据源」 | 表单 | 提交；提交中显示「提交中...」并禁用；成功后 alert 成功并刷新列表 |
| 「取消」 | 表单 | resetForm（清空表单、关闭表单） |
| 「测试连接」 | 列表行 | 用当前数据源配置调用 /datasources/:id/test，结果以 JSON 弹窗展示；失败走 alert |
| 「导入元数据」 | 列表行 | 调用 /datasources/:id/import-metadata，结果以 JSON 弹窗展示 |
| 「编辑」 | 列表行 | 回填表单进入编辑态（标题「编辑数据源」） |
| 「删除」 | 列表行 | confirm 确认「确定要删除数据源"xx"吗？此操作不可撤销。」后调用 DELETE |
5. 后端关联
5.1 API 端点
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /aip-api/v1/datasources | 数据源列表（响应 {data_sources: [...]}） |
| POST | /aip-api/v1/datasources | 创建数据源（201 返回数据源） |
| GET | /aip-api/v1/datasources/:id | 单个数据源 |
| PUT | /aip-api/v1/datasources/:id | 更新数据源（name/type 必填且 type 为合法枚举） |
| DELETE | /aip-api/v1/datasources/:id | 删除数据源（响应 {deleted}） |
| POST | /aip-api/v1/datasources/:id/test | 测试连接（body 为 name/type/connection_config） |
| POST | /aip-api/v1/datasources/:id/import-metadata | 导入元数据 |
5.2 请求体结构
创建/更新 payload 形如 {name, type, connection_config:{host, port, user, password, database, description, active}}（active 恒为 true）。
5.3 关键机制
- 任务化导入元数据：
import-metadata为 V5 Stage 0 任务化端点（submitAndWaitTask）：快路径窗口内完成返回旧同步响应语义（旧字段 +task_id），超时返回 HTTP 202{task_id, status: running, type}，进度经GET /tasks/:id轮询；页面不主动轮询。 - 可选 AI 描述：导入端点支持
?ai_generate_descriptions=true调用 LLM 生成表/列业务描述，页面默认不传（false，仅复制外部表结构）。 - 错误口径：失败响应统一
{error: "..."}；前端 alert 展示err.response?.data?.error || err.message。
6. 权限与安全
- 进入页面需 AIP 登录（路由 requiresAuth，Bearer aip_token，aipClient 自动附带）。
- 后端数据源接口属 protected 组仅 JWT 校验（DS-24 契约：非 admin 也可更新/删除/导入），页面无角色限制。
- 删除有
confirm二次确认；提交中submitting置位防连点。 - 密码不回显、不回填（编辑时密码留空）；连接信息仅展示 host:port/database。
7. 常见问题与排错
- 「测试连接」失败：数据库不可达或账号密码错误。核对 host/port/user/password 与防火墙；SQLite 类型确认文件路径/权限。
- 「导入元数据」无响应或只有 task_id：快路径窗口内未完成会返回 202
{task_id}。用GET /aip-api/v1/tasks/:id轮询进度；失败查数据源连接与后端日志。 - 创建/更新报 400：
name、type必填，且type必须是 POSTGRESQL/MYSQL/SQLITE/SQLSERVER 之一。 - 页面 401 跳登录：token 过期。重新登录 AIP 后返回本页。
8. 已知缺陷与边界
| 项 | 说明 |
|---|---|
| 编辑密码不回填 | 编辑后不保存密码则保持原值（留空不修改） |
| 非管理员可写 | 数据源接口仅 JWT 保护，普通账号也可增删改 |
| 无 AI 描述开关 | 页面未暴露 ai_generate_descriptions，默认不生成 AI 描述 |
注：列表无分页（后端固定取前 100 条，页面无分页控件）已于 2026-09-06 修复（本地分页）。
注：导入任务化不轮询终态（202 时需手动查任务）已于 2026-09-06 修复（轮询 /tasks/:id 至终态并提示）。