# 数据源管理接口文档

## 目录
- [1. 数据源配置管理 (DatasourceConfigController)](#1-数据源配置管理)
- [2. 数据库连接实例管理 (DatasourceConnectionController)](#2-数据库连接实例管理)

---

## 1. 数据源配置管理

**Base URL**: `/datasource/config`

### 1.1 查询数据源配置列表

**接口**: `GET /datasource/config/list`

**描述**: 查询数据源配置列表，支持分页和多条件筛选

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| datasourceName | String | 否 | 数据源名称（模糊查询） |
| datasourceId | Long | 否 | 连接ID |
| datasourceType | String | 否 | 数据库类型 |
| status | Integer | 否 | 状态 |
| showTable | Boolean | 否 | 是否显示表数量 |
| pageNum | Integer | 否 | 页码（默认1） |
| pageSize | Integer | 否 | 每页数量（默认10） |

**响应示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "total": 10,
  "rows": [
    {
      "id": 1,
      "datasourceName": "测试数据库",
      "connectionId": 1,
      "databaseName": "test_db",
      "datasourceType": "PostgreSQL",
      "status": 0,
      "skillBool": true,
      "tableNum": 5,
      "createTime": "2025-01-01 10:00:00"
    }
  ]
}
```

### 1.2 获取数据源配置详情

**接口**: `GET /datasource/config/{id}`

**描述**: 获取指定数据源配置的详细信息

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 数据源配置ID |

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "datasourceName": "测试数据库",
    "connectionId": 1,
    "databaseName": "test_db",
    "datasourceType": "PostgreSQL",
    "status": 0,
    "skillBool": true,
    "tableNum": 5
  }
}
```

### 1.3 批量新增数据源配置

**接口**: `POST /datasource/config`

**描述**: 批量创建数据源配置并同步表结构

**请求体**:
```json
{
  "connectionId": 1,
  "datasourceNamePrefix": "业务",
  "enterpriseId": 1,
  "status": 0,
  "remark": "备注信息",
  "syncTables": true,
  "databases": [
    {
      "databaseName": "db1",
      "tableNames": ["table1", "table2"]
    },
    {
      "databaseName": "db2",
      "tableNames": ["table3"]
    }
  ]
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "成功创建2个数据源配置，正在后台异步同步3张表，请稍后刷新查看",
  "data": {
    "successCount": 2,
    "totalSyncTableCount": 3,
    "results": [
      {
        "databaseName": "db1",
        "datasourceConfig": { "id": 1, "datasourceName": "业务-db1" },
        "syncTableCount": 2
      }
    ]
  }
}
```

### 1.4 全量替换数据源配置

**接口**: `PUT /datasource/config`

**描述**: 全量替换指定连接下的数据源配置（未传入的配置将被删除）

**⚠️ 警告**: 会删除未传入的所有数据库配置及其相关表元数据，请谨慎操作！

**请求体**: 同1.3

**响应示例**:
```json
{
  "code": 200,
  "msg": "全量替换成功：创建1个，更新0个，删除1个，正在后台异步同步2张表",
  "data": {
    "createdCount": 1,
    "updatedCount": 0,
    "deletedCount": 1,
    "totalSyncTableCount": 2,
    "results": [...]
  }
}
```

### 1.5 批量修改数据源配置

**接口**: `PUT /datasource/config/batch`

**描述**: 批量修改数据源配置并重新同步表结构

**请求体**:
```json
{
  "status": 0,
  "remark": "批量更新",
  "syncTables": true,
  "datasources": [
    {
      "id": 1,
      "datasourceName": "新名称",
      "tableNames": ["table1", "table2"]
    }
  ]
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "成功修改1个数据源配置，正在后台异步同步2张表",
  "data": {
    "successCount": 1,
    "totalSyncTableCount": 2,
    "results": [...]
  }
}
```

### 1.6 删除数据源配置

**接口**: `POST /datasource/config/deletes`

**描述**: 批量删除数据源配置

**请求体**:
```json
{
  "ids": [1, 2, 3]
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

### 1.7 测试数据库连接

**接口**: `POST /datasource/config/testConnectionConfig`

**描述**: 测试数据库连接是否正常

**请求体**:
```json
{
  "host": "localhost",
  "port": 5432,
  "username": "postgres",
  "password": "password",
  "datasourceType": "PostgreSQL"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "连接成功"
}
```

### 1.8 修改数据源状态

**接口**: `PUT /datasource/config/changeStatus`

**描述**: 修改数据源配置的启用/禁用状态

**请求体**:
```json
{
  "id": 1,
  "status": 1
}
```

### 1.9 导出数据源配置

**接口**: `POST /datasource/config/export`

**描述**: 导出数据源配置列表为Excel文件

---

## 2. 数据库连接实例管理

**Base URL**: `/datasource/connection`

### 2.1 查询连接实例列表

**接口**: `GET /datasource/connection/list`

**描述**: 查询数据库连接实例列表，支持分页和筛选（已优化N+1查询问题）

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| datasourceName | String | 否 | 数据源名称（模糊查询） |
| status | Integer | 否 | 状态 |
| testStatus | Integer | 否 | 测试状态（0未测试/1成功/2失败） |
| sourceType | String | 否 | 连接来源（builtin/external） |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页数量 |

**响应示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "total": 5,
  "rows": [
    {
      "id": 1,
      "datasourceName": "内置PostgreSQL",
      "datasourceType": "PostgreSQL",
      "host": "localhost",
      "port": 5432,
      "status": 0,
      "testStatus": 1,
      "sourceType": "builtin",
      "databaseNum": 3,
      "tableNum": 15,
      "datasourceConfig": [...]
    }
  ]
}
```

### 2.2 获取连接实例详情

**接口**: `GET /datasource/connection/{id}`

**描述**: 获取指定连接实例的详细信息

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 连接实例ID |

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "datasourceName": "内置PostgreSQL",
    "host": "localhost",
    "port": 5432,
    "username": "postgres",
    "databaseNum": 3,
    "tableNum": 15,
    "datasourceConfig": [
      {
        "id": 1,
        "databaseName": "db1",
        "tables": [
          {"tableName": "table1", "tableId": 1}
        ],
        "skillBool": true
      }
    ]
  }
}
```

### 2.3 新增连接实例

**接口**: `POST /datasource/connection`

**描述**: 创建新的数据库连接实例

**请求体**:
```json
{
  "datasourceName": "测试连接",
  "datasourceType": "PostgreSQL",
  "connectionType": "user_password",
  "host": "localhost",
  "port": 5432,
  "username": "postgres",
  "password": "password",
  "status": 0,
  "remark": "备注信息"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "创建成功",
  "data": {
    "id": 1,
    "datasourceName": "测试连接"
  }
}
```

### 2.4 修改连接实例

**接口**: `PUT /datasource/connection`

**描述**: 修改数据库连接实例信息

**请求体**:
```json
{
  "id": 1,
  "datasourceName": "新名称",
  "host": "localhost",
  "port": 5432,
  "username": "postgres",
  "password": "new_password",
  "remark": "更新备注"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "更新成功"
}
```

### 2.5 删除连接实例

**接口**: `DELETE /datasource/connection/{id}`

**描述**: 删除指定的连接实例

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 连接实例ID |

**响应示例**:
```json
{
  "code": 200,
  "msg": "删除数据库实例成功"
}
```

### 2.6 测试连接

**接口**: `POST /datasource/connection/test`

**描述**: 测试数据库连接是否可用

**请求体**:
```json
{
  "id": 1,
  "host": "localhost",
  "port": 5432,
  "username": "postgres",
  "password": "password",
  "datasourceType": "PostgreSQL"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "连接成功"
}
```

### 2.7 修改连接状态

**接口**: `PUT /datasource/connection/changeStatus`

**描述**: 修改连接实例的启用/禁用状态

**请求体**:
```json
{
  "id": 1,
  "status": 1
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "状态修改成功"
}
```

### 2.8 实时查询数据库结构

**接口**: `GET /datasource/connection/realtime/structure/{id}`

**描述**: 实时查询连接下的所有数据库和表结构（直接连接数据库服务器查询）

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 连接实例ID |

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "databaseName": "db1",
      "tables": ["table1", "table2"],
      "tableCount": 2
    }
  ]
}
```

### 2.9 实时查询数据库列表

**接口**: `GET /datasource/connection/realtime/databases/{id}`

**描述**: 实时查询连接下的所有数据库名称

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 连接实例ID |

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": ["db1", "db2", "db3"]
}
```

### 2.10 实时查询表列表

**接口**: `GET /datasource/connection/realtime/tables/{id}`

**描述**: 实时查询指定数据库下的所有表

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 连接实例ID |

**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| databaseName | String | 是 | 数据库名称 |

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": ["table1", "table2", "table3"]
}
```

### 2.11 创建内置PostgreSQL连接

**接口**: `POST /datasource/connection/create_builtin_postgresql`

**描述**: 创建内置PostgreSQL数据库连接（使用配置文件中的连接信息）

**请求体**:
```json
{
  "datasourceName": "内置PostgreSQL数据库",
  "remark": "系统内置数据库"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "✅测试通过，连接通过",
  "data": {
    "id": 1,
    "datasourceName": "内置PostgreSQL数据库"
  }
}
```

### 2.12 修改内置数据库连接

**接口**: `PUT /datasource/connection/update_builtin_database`

**描述**: 修改内置PostgreSQL连接信息

**请求体**:
```json
{
  "connectionId": 1,
  "datasourceName": "新名称",
  "remark": "更新备注"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "✅保存成功"
}
```

### 2.13 执行SQL语句

**接口**: `POST /datasource/connection/{datasourceId}/execute_sql`

**描述**: 在指定数据源上执行SQL语句，支持参数化查询和环境切换

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| datasourceId | Long | 是 | 数据源配置ID |

**请求头**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Datasource-API-Key | String | 否 | API密钥（用于权限验证） |

**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| target | String | 否 | 目标环境（prod/test，默认prod） |

**请求体**:
```json
{
  "sql": "SELECT * FROM users WHERE age > ?",
  "params": [18],
  "databaseName": "test_db"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "success": true,
    "affectedRows": 10,
    "duration": 25,
    "target": "prod",
    "databaseName": "test_db",
    "msg": "执行成功，此次操作影响10行数据",
    "rows": [
      {"id": 1, "name": "张三", "age": 25}
    ],
    "affectedRowsDetail": {
      "operationType": "SELECT",
      "tables": ["users"],
      "count": 10
    }
  }
}
```

**说明**:
- 支持参数化查询，使用 `?` 占位符
- 自动识别SQL类型（SELECT/INSERT/UPDATE/DELETE等）
- 支持DDL操作（CREATE/ALTER/DROP）
- 内置连接支持自动同步到测试库

### 2.14 创建数据库

**接口**: `POST /datasource/connection/{connectionId}/create_database`

**描述**: 在指定连接上创建新数据库（目前仅支持PostgreSQL）

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| connectionId | Long | 是 | 连接实例ID |

**请求头**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Datasource-API-Key | String | 否 | API密钥 |

**请求体**:
```json
{
  "databaseName": "new_database",
  "encoding": "UTF8",
  "owner": "postgres"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "创建数据库成功"
}
```

**说明**:
- 需要连接级别的 CREATE_DATABASE 权限
- 内置连接会自动创建对应的测试库（_test后缀）
- 创建成功后会自动创建数据源配置

### 2.15 创建表

**接口**: `POST /datasource/connection/{connectionId}/create_table`

**描述**: 在指定数据库中创建新表

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| connectionId | Long | 是 | 连接实例ID |

**请求头**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Datasource-API-Key | String | 否 | API密钥 |

**请求体**:
```json
{
  "databaseName": "test_db",
  "tableName": "users",
  "tableComment": "用户表",
  "columns": [
    {
      "columnName": "id",
      "columnType": "BIGINT",
      "isPrimaryKey": true,
      "isNullable": false,
      "columnComment": "主键ID"
    },
    {
      "columnName": "name",
      "columnType": "VARCHAR",
      "columnLength": 100,
      "isNullable": false,
      "columnComment": "用户名"
    },
    {
      "columnName": "age",
      "columnType": "INTEGER",
      "isNullable": true,
      "columnComment": "年龄"
    }
  ]
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "创建表成功"
}
```

**说明**:
- 需要数据库级别的 CREATE 权限
- 内置连接会自动在测试库中创建相同表结构
- 创建成功后会自动同步表元数据

### 2.16 创建数据库和表

**接口**: `POST /datasource/connection/{connectionId}/create_database_table`

**描述**: 同时创建数据库和表（一次性操作）

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| connectionId | Long | 是 | 连接实例ID |

**请求头**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Datasource-API-Key | String | 否 | API密钥 |

**请求体**:
```json
{
  "databaseName": "new_db",
  "encoding": "UTF8",
  "owner": "postgres",
  "tables": [
    {
      "tableName": "users",
      "tableComment": "用户表",
      "columns": [
        {
          "columnName": "id",
          "columnType": "BIGINT",
          "isPrimaryKey": true,
          "isNullable": false,
          "columnComment": "主键ID"
        }
      ]
    },
    {
      "tableName": "orders",
      "tableComment": "订单表",
      "columns": [...]
    }
  ]
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "创建成功"
}
```

**说明**:
- 需要连接级别的 CREATE_DATABASE 权限和数据库级别的 CREATE 权限
- 支持一次创建多个表
- 内置连接会自动创建测试库和测试表

### 2.17 修改数据库

**接口**: `PUT /datasource/connection/{connectionId}/alter_database`

**描述**: 修改数据库属性（重命名、更改所有者、更改编码）

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| connectionId | Long | 是 | 连接实例ID |

**请求头**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Datasource-API-Key | String | 否 | API密钥 |

**请求体**:
```json
{
  "databaseName": "old_db",
  "newName": "new_db",
  "newOwner": "postgres",
  "newEncoding": "UTF8"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "修改数据库成功"
}
```

**说明**:
- 需要数据库级别的 ALTER 权限
- 至少需要指定一个修改项（newName/newOwner/newEncoding）
- 内置连接会同步修改测试库

### 2.18 修改表

**接口**: `PUT /datasource/connection/{connectionId}/alter_table`

**描述**: 修改表结构（添加列、删除列、重命名列、修改列类型等）

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| connectionId | Long | 是 | 连接实例ID |

**请求头**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Datasource-API-Key | String | 否 | API密钥 |

**请求体**:
```json
{
  "databaseName": "test_db",
  "tableName": "users",
  "tableComment": "更新的表注释",
  "operations": [
    {
      "operation": "ADD_COLUMN",
      "column": {
        "columnName": "email",
        "columnType": "VARCHAR",
        "columnLength": 255,
        "isNullable": true,
        "columnComment": "邮箱"
      }
    },
    {
      "operation": "DROP_COLUMN",
      "column": {
        "columnName": "old_field"
      }
    },
    {
      "operation": "RENAME_COLUMN",
      "column": {
        "columnName": "old_name",
        "newColumnName": "new_name"
      }
    },
    {
      "operation": "ALTER_COLUMN_TYPE",
      "column": {
        "columnName": "age",
        "columnType": "BIGINT"
      }
    }
  ]
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "修改表成功"
}
```

**支持的操作类型**:
- `ADD_COLUMN`: 添加列
- `DROP_COLUMN`: 删除列
- `RENAME_COLUMN`: 重命名列
- `ALTER_COLUMN_TYPE`: 修改列类型
- `SET_NOT_NULL`: 设置列为非空
- `DROP_NOT_NULL`: 设置列为可空
- `SET_DEFAULT`: 设置默认值
- `DROP_DEFAULT`: 删除默认值

**说明**:
- 需要表级别的 ALTER 权限
- 支持批量操作
- 内置连接会同步修改测试表
- 如果列有 columnId，系统会自动检测并插入重命名操作

### 2.19 生成表结构

**接口**: `POST /datasource/connection/generate_table`

**描述**: 使用AI根据需求描述生成表结构（异步任务）

**请求体**:
```json
{
  "requirement": "创建一个用户管理系统，需要用户表、角色表和权限表，用户表包含用户名、密码、邮箱、手机号等字段",
  "databaseId": 1
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "taskId": 123,
    "status": "PENDING",
    "message": "任务已提交，等待AI生成表结构"
  }
}
```

**说明**:
- 异步任务，需要轮询任务状态
- AI会根据需求描述自动生成表结构
- 可以指定关联的数据库ID

### 2.20 文档导入预览

**接口**: `POST /datasource/connection/{connectionId}/import_document/preview`

**描述**: 上传Excel/CSV文件，AI识别表结构并预览前10条数据

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| connectionId | Long | 是 | 连接实例ID |

**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| target | String | 否 | 目标环境（prod/test，默认prod） |

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file | MultipartFile | 是 | Excel或CSV文件 |

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "tableStructure": {
      "databaseName": "test_db",
      "tableName": "users",
      "tableComment": "用户表",
      "columns": [
        {
          "columnName": "name",
          "columnType": "VARCHAR",
          "columnLength": 100,
          "columnComment": "姓名"
        }
      ]
    },
    "previewData": [
      ["name", "age", "gender"],
      ["张三", "25", "male"],
      ["李四", "30", "female"]
    ],
    "allData": [...],
    "fileName": "users.xlsx",
    "target": "prod"
  }
}
```

**说明**:
- 支持 Excel (.xlsx, .xls) 和 CSV 文件
- AI自动识别列名、类型和注释
- 返回前10条数据用于预览
- 完整数据保存在 allData 中，用于确认导入

### 2.21 文档导入确认

**接口**: `POST /datasource/connection/{connectionId}/import_document/confirm`

**描述**: 确认导入，创建表并插入数据

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| connectionId | Long | 是 | 连接实例ID |

**请求头**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Datasource-API-Key | String | 否 | API密钥 |

**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| target | String | 否 | 目标环境（prod/test，默认prod） |

**请求体**:
```json
{
  "tableStructure": {
    "databaseName": "test_db",
    "tableName": "users",
    "tableComment": "用户表",
    "columns": [
      {
        "columnName": "name",
        "columnType": "VARCHAR",
        "columnLength": 100,
        "columnComment": "姓名"
      }
    ]
  },
  "allData": [
    ["name", "age", "gender"],
    ["张三", "25", "male"],
    ["李四", "30", "female"]
  ]
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "文档导入成功",
  "data": {
    "tableName": "users",
    "databaseName": "test_db",
    "target": "prod",
    "insertedRows": 100
  }
}
```

**说明**:
- 需要数据库级别的 CREATE 权限
- 如果表已存在，只插入数据
- 支持批量插入（每批1000条）
- 自动类型转换和数据验证
- 内置连接会同步到测试库

### 2.22 查询表结构和数据

**接口**: `GET /datasource/connection/builtin/table/{tableId}`

**描述**: 根据表ID查询表结构和数据（分页）

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| tableId | Long | 是 | 表ID |

**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | Integer | 否 | 页码（默认1） |
| pageSize | Integer | 否 | 每页数量（默认100） |
| target | String | 否 | 目标环境（prod/test，默认prod） |

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "tables": {
      "tableName": "users",
      "tableComment": "用户表",
      "columns": [
        {
          "columnName": "id",
          "columnType": "BIGINT",
          "columnComment": "主键",
          "columnLength": null,
          "isPrimaryKey": true,
          "isNullable": false
        },
        {
          "columnName": "name",
          "columnType": "VARCHAR",
          "columnComment": "姓名",
          "columnLength": 100,
          "isPrimaryKey": false,
          "isNullable": false
        }
      ]
    },
    "content": [
      [1, "张三", 25],
      [2, "李四", 30]
    ],
    "pageNum": 1,
    "pageSize": 100,
    "total": 2,
    "target": "prod",
    "databaseName": "test_db"
  }
}
```

**说明**:
- 返回表结构和数据（二维数组格式）
- 列按 ordinalPosition 排序
- 支持分页查询
- 可切换正式库和测试库

### 2.23 新增表数据

**接口**: `POST /datasource/connection/builtin/table/{tableId}/rows`

**描述**: 向指定表插入一条数据

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| tableId | Long | 是 | 表ID |

**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| target | String | 否 | 目标环境（prod/test，默认prod） |

**请求体**:
```json
{
  "data": {
    "name": "张三",
    "age": 25,
    "email": "zhangsan@example.com",
    "created_at": "2025-01-01 10:00:00"
  }
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "插入成功"
}
```

**说明**:
- 只能插入表中存在的列
- 自动进行类型转换
- 支持环境切换（正式库/测试库）

### 2.24 更新表数据

**接口**: `PUT /datasource/connection/builtin/table/{tableId}/rows`

**描述**: 根据主键更新表数据

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| tableId | Long | 是 | 表ID |

**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| target | String | 否 | 目标环境（prod/test，默认prod） |

**请求体**:
```json
{
  "data": {
    "name": "李四",
    "age": 30,
    "email": "lisi@example.com"
  },
  "primaryKey": {
    "id": 1
  }
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "更新成功"
}
```

**说明**:
- 必须提供完整的主键条件
- 只更新 data 中指定的字段
- 支持复合主键
- 自动进行类型转换

### 2.25 删除表数据

**接口**: `DELETE /datasource/connection/builtin/table/{tableId}/rows`

**描述**: 根据主键批量删除表数据

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| tableId | Long | 是 | 表ID |

**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| target | String | 否 | 目标环境（prod/test，默认prod） |

**请求体**:
```json
{
  "primaryKeys": [
    {"id": 1},
    {"id": 2},
    {"id": 3}
  ]
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "删除成功"
}
```

**说明**:
- 支持批量删除
- 必须提供完整的主键条件
- 支持复合主键
- 自动进行类型转换

---

## 3. 通用说明

### 3.1 权限验证

部分接口需要在请求头中携带 `X-Datasource-API-Key` 进行权限验证。

**三层权限模型**:
1. **连接级别权限**: CREATE_DATABASE, DROP_DATABASE
2. **数据库级别权限**: CREATE, ALTER, DROP
3. **表级别权限**: SELECT, INSERT, UPDATE, DELETE, ALTER

**权限验证规则**:
- 创建/删除数据库：需要连接级别权限
- 创建/修改/删除表：需要数据库级别权限
- 数据操作（增删改查）：需要表级别权限
- 修改表结构：需要表级别的 ALTER 权限

### 3.2 环境切换

支持 `target` 参数切换正式环境(prod)和测试环境(test)。

**内置连接特性**:
- 自动创建测试库（数据库名_test）
- DDL操作自动同步到测试库
- 可独立操作测试库数据

**使用场景**:
- `target=prod`: 操作正式库（默认）
- `target=test`: 操作测试库（仅内置连接支持）

### 3.3 响应格式

所有接口统一返回格式：

**成功响应**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

**失败响应**:
```json
{
  "code": 500,
  "msg": "错误信息"
}
```

**分页响应**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "total": 100,
  "rows": [...]
}
```

### 3.4 数据类型支持

**PostgreSQL类型映射**:
- 整数类型: SMALLINT, INTEGER, BIGINT, SERIAL, BIGSERIAL
- 小数类型: DECIMAL, NUMERIC, REAL, DOUBLE PRECISION, MONEY
- 布尔类型: BOOLEAN
- 字符类型: VARCHAR, CHAR, TEXT
- 日期时间: DATE, TIME, TIMESTAMP
- JSON类型: JSON, JSONB
- 数组类型: ARRAY
- UUID类型: UUID

**类型转换规则**:
- 字符串 → 数字：自动转换
- 字符串 → 布尔：true/false/1/0
- 字符串 → 日期：ISO格式自动解析
- null/空字符串：根据列定义处理

### 3.5 异步任务

部分操作为异步执行：
- 表结构同步（syncTables）
- AI生成表结构（generate_table）

**异步任务特点**:
- 立即返回任务ID
- 后台执行，不阻塞主线程
- 需要轮询任务状态或查看日志

### 3.6 批量操作

支持批量操作的接口：
- 批量创建数据源配置
- 批量修改数据源配置
- 批量删除数据源配置
- 批量删除表数据
- 批量插入数据（文档导入）

**批量操作限制**:
- 单次批量插入最多1000条
- 批量操作失败会返回详细错误信息

### 3.7 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 操作成功 |
| 500 | 服务器内部错误 |
| 400 | 参数错误 |
| 401 | 未授权（API Key无效） |
| 403 | 权限不足 |
| 404 | 资源不存在 |

### 3.8 最佳实践

**1. 连接管理**:
- 创建连接后先测试连接
- 使用内置连接时启用测试库功能
- 定期检查连接状态

**2. 数据源配置**:
- 使用有意义的数据源名称前缀
- 合理使用异步同步功能
- 定期清理无用配置

**3. SQL执行**:
- 使用参数化查询防止SQL注入
- 大批量操作建议分批执行
- 先在测试库验证再操作正式库

**4. 权限管理**:
- 遵循最小权限原则
- 定期审计API Key权限
- 敏感操作使用独立API Key

**5. 文档导入**:
- 先预览再确认导入
- 检查AI识别的表结构是否正确
- 大文件建议分批导入

**6. 表结构修改**:
- 重要操作前备份数据
- 使用测试库验证修改操作
- 注意列重命名的自动检测机制

### 3.9 注意事项

1. **内置连接特性**:
   - 仅内置PostgreSQL连接支持测试库功能
   - 测试库名称为：原数据库名_test
   - DDL操作会自动同步到测试库

2. **权限验证**:
   - 当前权限验证已临时禁用（代码中 `if (true) return null;`）
   - 生产环境需启用权限验证

3. **数据类型**:
   - 目前仅完整支持PostgreSQL
   - 其他数据库类型支持有限

4. **异步操作**:
   - 表结构同步为异步操作
   - 需要等待同步完成后才能看到表元数据

5. **文件上传**:
   - 支持Excel (.xlsx, .xls) 和CSV格式
   - 文件大小建议不超过10MB
   - 超大文件建议分批导入

---

## 4. 使用示例

### 4.1 完整流程示例：创建数据库并导入数据

**步骤1：创建连接实例**
```bash
POST /datasource/connection
{
  "datasourceName": "测试连接",
  "datasourceType": "PostgreSQL",
  "host": "localhost",
  "port": 5432,
  "username": "postgres",
  "password": "password"
}
```

**步骤2：测试连接**
```bash
POST /datasource/connection/test
{
  "id": 1,
  "host": "localhost",
  "port": 5432,
  "username": "postgres",
  "password": "password",
  "datasourceType": "PostgreSQL"
}
```

**步骤3：创建数据库和表**
```bash
POST /datasource/connection/1/create_database_table
{
  "databaseName": "my_app",
  "encoding": "UTF8",
  "tables": [
    {
      "tableName": "users",
      "tableComment": "用户表",
      "columns": [
        {
          "columnName": "id",
          "columnType": "BIGINT",
          "isPrimaryKey": true,
          "isNullable": false,
          "columnComment": "用户ID"
        },
        {
          "columnName": "username",
          "columnType": "VARCHAR",
          "columnLength": 50,
          "isNullable": false,
          "columnComment": "用户名"
        }
      ]
    }
  ]
}
```

**步骤4：查询数据源配置**
```bash
GET /datasource/config/list?datasourceName=my_app
```

**步骤5：插入数据**
```bash
POST /datasource/connection/builtin/table/1/rows
{
  "data": {
    "id": 1,
    "username": "admin"
  }
}
```

### 4.2 文档导入示例

**步骤1：上传文件预览**
```bash
POST /datasource/connection/1/import_document/preview
Content-Type: multipart/form-data

file: users.xlsx
target: test
```

**步骤2：确认导入**
```bash
POST /datasource/connection/1/import_document/confirm?target=test
{
  "tableStructure": {
    "databaseName": "my_app",
    "tableName": "imported_users",
    "columns": [...]
  },
  "allData": [...]
}
```

### 4.3 SQL执行示例

**查询数据**
```bash
POST /datasource/connection/1/execute_sql?target=prod
{
  "sql": "SELECT * FROM users WHERE age > ? AND status = ?",
  "params": [18, "active"],
  "databaseName": "my_app"
}
```

**更新数据**
```bash
POST /datasource/connection/1/execute_sql?target=test
{
  "sql": "UPDATE users SET status = ? WHERE id = ?",
  "params": ["inactive", 1],
  "databaseName": "my_app"
}
```

---

## 5. 附录

### 5.1 数据库类型枚举

| 枚举值 | 显示名称 | 默认端口 | 默认测试库 |
|--------|----------|----------|------------|
| POSTGRESQL | PostgreSQL | 5432 | postgres |
| MYSQL | MySQL | 3306 | mysql |
| ORACLE | Oracle | 1521 | - |
| SQLSERVER | SQL Server | 1433 | master |

### 5.2 状态码枚举

| 状态码 | 说明 |
|--------|------|
| 0 | 正常 |
| 1 | 停用 |

### 5.3 测试状态枚举

| 状态码 | 说明 |
|--------|------|
| 0 | 未测试 |
| 1 | 连接成功 |
| 2 | 连接失败 |

### 5.4 连接来源枚举

| 来源类型 | 说明 |
|----------|------|
| builtin | 内置连接（支持测试库） |
| external | 外部连接 |

---

## 6. 更新日志

### v1.0.0 (2025-12-26)
- 初始版本
- 支持数据源配置管理
- 支持数据库连接实例管理
- 支持SQL执行
- 支持DDL操作（创建/修改数据库和表）
- 支持文档导入（Excel/CSV）
- 支持AI生成表结构
- 支持内置PostgreSQL测试库功能
- 支持三层权限模型
- 优化N+1查询问题

---

**文档维护**: 技术团队  
**最后更新**: 2025-12-26  
**版本**: v1.0.0
