# DB Connection Storage API Examples

数据库连接存储模块提供数据库连接、分组和SQL脚本的管理功能，支持树状分层组织和完整的CRUD操作。

## 重要说明

### 显示顺序 (display_order)

所有支持显示顺序的资源（连接分组、数据库连接）都实现了自动排序功能：

- **自动计算**: 创建资源时如果未提供 `display_order` 或值为 0，系统会自动计算合适的显示顺序
- **分组排序**: 新分组会排在同级分组的最后位置（最大显示顺序 + 1）
- **连接排序**: 新连接会排在同分组连接的最后位置（最大显示顺序 + 1）
- **手动指定**: 如果提供了具体的 `display_order` 值，系统会使用提供的值

## 基础信息

- **Base URL**: `http://localhost:8080/api/v1/storage`
- **Content-Type**: `application/json`
- **认证**: 根据项目配置

## API 端点示例

### 1. 数据库连接管理

#### 创建数据库连接

**参数说明**:
- `group_id` (string, 必需): 连接所属的分组ID（系统会验证此ID是否存在）
- `name` (string, 必需): 连接的名称，用于标识连接
- `description` (string, 可选): 连接的详细描述
- `kind` (string, 必需): 连接类别，示例值为 `database` / `server` / `other`。根据 `kind` 的值，请在请求体中提供对应的嵌套对象：
  - 当 `kind=="database"` 时，请使用 `db_detail` 对象（示例见下）。
  - 当 `kind=="server"` 时，请使用 `server_detail` 对象（示例见下）。
- `color` (string, 可选): 连接在UI中显示的颜色
- `auto_connect` (boolean, 可选): 是否自动连接，默认为 false
- `display_order` (int, 可选): 显示顺序，如果未提供或为0，系统会自动计算为同分组连接最大显示顺序 + 1

**验证逻辑**:
- 系统会自动验证`group_id`是否存在于连接分组表中
- 如果`group_id`不存在，将返回错误码`3001`，表示"分组不存在"
- `display_order` 会自动计算，确保新连接显示在同分组连接的最后位置

```bash
curl -X POST http://localhost:8080/api/v1/storage/connections/create \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group_1",
    "name": "MySQL Production DB",
    "description": "生产环境主数据库",
    "kind": "database",
    "color": "#4285F4",
    "auto_connect": false,
    "db_detail": {
      "type": "mysql",
      "version": "8.0",
      "server": "prod-db.example.com",
      "port": 3306,
      "username": "app_user",
      "password": "enc:secure_password",
      "database": "myapp_prod",
      "use_ssh_tunnel": false
    }
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "创建连接成功",
  "data": {
    "id": "conn_123456",
    "group_id": "group_1",
    "name": "MySQL Production DB",
    "description": "生产环境主数据库",
    "kind": "database",
    "db_detail": {
      "type": "mysql",
      "version": "8.0",
      "server": "prod-db.example.com",
      "port": 3306,
      "username": "app_user",
      "database": "myapp_prod",
      "last_connected": null
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

#### 获取所有数据库连接

**参数说明**:
- 无特殊参数，请求体可以为空对象 `{}`

```bash
curl -X POST http://localhost:8080/api/v1/storage/connections/list \
  -H "Content-Type: application/json" \
  -d '{}'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "获取所有连接成功",
  "data": [
    {
      "id": "conn_123456",
      "group_id": "group_1",
      "name": "MySQL Production DB",
      "description": "生产环境主数据库",
      "db_detail": {
        "type": "mysql",
        "version": "8.0",
        "server": "prod-db.example.com",
        "port": 3306,
        "username": "app_user",
        "database": "myapp_prod",
        "last_connected": "2024-01-15T09:15:00Z"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "conn_789012",
      "group_id": "group_2",
      "name": "PostgreSQL Development DB",
      "description": "开发环境数据库",
      "db_detail": {
        "type": "postgresql",
        "version": "13.0",
        "server": "dev-db.example.com",
        "port": 5432,
        "username": "dev_user",
        "database": "myapp_dev",
        "last_connected": "2024-01-14T16:30:00Z"
      },
      "created_at": "2024-01-14T08:45:00Z",
      "updated_at": "2024-01-14T08:45:00Z"
    }
  ]
}
```

#### 获取指定数据库连接

**参数说明**:
- `id` (string, 必需): 数据库连接的唯一标识符

```bash
curl -X POST http://localhost:8080/api/v1/storage/connections/get \
  -H "Content-Type: application/json" \
  -d '{
    "id": "conn_123456"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "获取连接成功",
  "data": {
    "id": "conn_123456",
    "group_id": "group_1",
    "name": "MySQL Production DB",
    "description": "生产环境主数据库",
    "db_detail": {
      "type": "mysql",
      "version": "8.0",
      "server": "prod-db.example.com",
      "port": 3306,
      "username": "app_user",
      "database": "myapp_prod",
      "last_connected": "2024-01-15T09:15:00Z"
    },
    "auto_connect": false,
    "color": "#4285F4",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

#### 更新数据库连接

**参数说明**:
- `id` (string, 必需): 要更新的数据库连接的唯一标识符
- `name` (string, 可选): 新的连接名称
- `description` (string, 可选): 新的连接描述
- `server` (string, 可选): 新的数据库服务器主机地址
- `password` (string, 可选): 新的数据库连接密码（可为明文或加密/编码后的字符串）
- 其他字段 (可选): 支持部分字段更新，只需要提供要更新的字段

**说明**: 更新操作支持部分字段更新，只需要提供要更新的字段，未提供的字段将保持原有值。

```bash
curl -X POST http://localhost:8080/api/v1/storage/connections/update \
  -H "Content-Type: application/json" \
  -d '{
    "id": "conn_123456",
    "name": "MySQL Production DB (Updated)",
    "description": "生产环境主数据库 - 已更新配置",
    "db_detail": {
      "server": "new-prod-db.example.com",
      "password": "enc:new_secure_password"
    }
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "更新连接成功",
  "data": {
    "id": "conn_123456",
    "group_id": "group_1",
    "name": "MySQL Production DB (Updated)",
    "description": "生产环境主数据库 - 已更新配置",
    "db_detail": {
      "type": "mysql",
      "version": "8.0",
      "server": "new-prod-db.example.com",
      "port": 3306,
      "username": "app_user",
      "database": "myapp_prod",
      "last_connected": "2024-01-15T09:15:00Z"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:45:00Z"
  }
}
```

#### 删除数据库连接

**参数说明**:
- `id` (string, 必需): 要删除的数据库连接的唯一标识符

```bash
curl -X POST http://localhost:8080/api/v1/storage/connections/delete \
  -H "Content-Type: application/json" \
  -d '{
    "id": "conn_123456"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "删除连接成功",
  "data": null
}
```

#### 移动数据库连接

**参数说明**:
- `id` (string, 必需): 要移动的数据库连接的唯一标识符
- `target_group_id` (string, 必需): 目标分组ID，要将连接移动到的分组位置

```bash
curl -X POST http://localhost:8080/api/v1/storage/connections/move \
  -H "Content-Type: application/json" \
  -d '{
    "id": "conn_123456",
    "target_group_id": "group_3"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "移动连接成功",
  "data": {
    "id": "conn_123456",
    "group_id": "group_3",
    "name": "MySQL Production DB",
    "description": "生产环境主数据库",
    "db_detail": {
      "type": "mysql",
      "version": "8.0",
      "server": "prod-db.example.com",
      "port": 3306,
      "username": "app_user",
      "database": "myapp_prod",
      "last_connected": "2024-01-15T09:15:00Z"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}
```

### 2. 连接分组管理

#### 创建连接分组

**参数说明**:
- `parent_id` (string, 可选): 父分组ID，如果不提供则创建为根分组
- `parent_name` (string, 可选): 父分组名称，用于提供更详细的错误信息和父分组ID一致性验证
- `name` (string, 必需): 新分组的名称
- `description` (string, 可选): 分组的详细描述
- `icon` (string, 可选): 分组图标
- `display_order` (int, 可选): 显示顺序，如果未提供或为0，系统会自动计算为同级分组最大显示顺序 + 1

**验证逻辑**:
- 如果提供了`parent_id`，系统会验证该ID是否存在
- 如果同时提供了`parent_id`和`parent_name`，系统会验证ID和名称是否匹配
- 如果父分组不存在或ID与名称不匹配，将返回详细的错误信息
- `display_order` 会自动计算，确保新分组显示在同级分组的最后位置

```bash
curl -X POST http://localhost:8080/api/v1/storage/connection_groups/create \
  -H "Content-Type: application/json" \
  -d '{
    "parent_id": "group_root",
    "parent_name": "根分组",
    "name": "生产环境",
    "description": "生产环境数据库连接",
    "icon": "server",
    "display_order": 1
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "创建分组成功",
  "data": {
    "id": "group_789",
    "parent_id": "group_root",
    "name": "生产环境",
    "description": "生产环境数据库连接",
    "icon": "server",
    "display_order": 1,
    "connections": [],
    "children": [],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

**错误响应示例**:
```json
{
  "code": 3001,
  "message": "父分组不存在",
  "error": "父分组（名称: 开发环境）不存在，ID: group_dev123，错误详情: record not found"
}
```

```json
{
  "code": 3003,
  "message": "父分组ID和名称不匹配",
  "error": "父分组ID和名称不匹配，ID: group_root，预期名称: 开发环境，实际名称: 根分组"
}
```

#### 获取连接分组树结构

**参数说明**:
- 无特殊参数，请求体可以为空对象 `{}`

```bash
curl -X POST http://localhost:8080/api/v1/storage/connection_groups/tree \
  -H "Content-Type: application/json" \
  -d '{}'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "获取分组树结构成功",
  "data": {
    "id": "group_root",
    "parent_id": "",
    "name": "根分组",
    "description": "所有连接的根分组",
    "icon": "database",
    "display_order": 0,
    "connections": [],
    "children": [
      {
        "id": "group_789",
        "parent_id": "group_root",
        "name": "生产环境",
        "description": "生产环境数据库连接",
        "icon": "server",
        "display_order": 1,
        "connections": [
          {
            "id": "conn_123456",
            "name": "MySQL Production DB",
            "db_detail": {
              "type": "mysql",
              "server": "prod-db.example.com"
            }
          }
        ],
        "children": []
      },
      {
        "id": "group_790",
        "parent_id": "group_root",
        "name": "开发环境",
        "description": "开发环境数据库连接",
        "icon": "code",
        "display_order": 2,
        "connections": [
          {
            "id": "conn_789012",
            "name": "PostgreSQL Development DB",
            "db_detail": {
              "type": "postgresql",
              "server": "dev-db.example.com"
            }
          }
        ],
        "children": []
      }
    ]
  }
}
```

#### 获取指定连接分组

**参数说明**:
- `id` (string, 必需): 要获取的分组的唯一标识符

```bash
curl -X POST http://localhost:8080/api/v1/storage/connection_groups/get \
  -H "Content-Type: application/json" \
  -d '{
    "id": "group_789"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "获取分组成功",
  "data": {
    "id": "group_789",
    "parent_id": "group_root",
    "name": "生产环境",
    "description": "生产环境数据库连接",
    "icon": "server",
    "display_order": 1,
      "connections": [
      {
        "id": "conn_123456",
        "name": "MySQL Production DB",
        "db_detail": {
          "type": "mysql",
          "server": "prod-db.example.com",
          "port": 3306,
          "username": "app_user",
          "database": "myapp_prod"
        }
      }
    ],
    "children": [],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

#### 更新连接分组

**参数说明**:
- `id` (string, 必需): 要更新的分组的唯一标识符
- `name` (string, 可选): 新的分组名称
- `description` (string, 可选): 新的分组描述
- `icon` (string, 可选): 新的分组图标
- `display_order` (int, 可选): 新的显示顺序

```bash
curl -X POST http://localhost:8080/api/v1/storage/connection_groups/update \
  -H "Content-Type: application/json" \
  -d '{
    "id": "group_789",
    "name": "生产环境_V2",
    "description": "生产环境数据库连接 (v2)",
    "icon": "cloud-server"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "更新分组成功",
  "data": {
    "id": "group_789",
    "parent_id": "group_root",
    "name": "生产环境_V2",
    "description": "生产环境数据库连接 (v2)",
    "icon": "cloud-server",
    "display_order": 1,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:45:00Z"
  }
}
```

#### 删除连接分组

**参数说明**:
- `id` (string, 必需): 要删除的分组的唯一标识符
- `cascade_delete_children` (boolean, 可选): 是否级联删除子分组，默认为false
- `cascade_delete_connections` (boolean, 可选): 是否级联删除分组下的数据库连接，默认为false

**注意事项**:
- **根目录保护**: 系统根目录（ID: `root_default`）不能被删除
- 如果 `cascade_delete_children` 为 true，会递归删除该分组下的所有子分组
- 如果 `cascade_delete_connections` 为 true，会删除该分组下的所有数据库连接
- 如果两个参数都为 false（默认值），只有在分组为空（无子分组且无连接）时才能删除
- 删除操作会同时删除关联的SQL脚本文件

```bash
curl -X POST http://localhost:8080/api/v1/storage/connection_groups/delete \
  -H "Content-Type: application/json" \
  -d '{
    "id": "group_789",
    "cascade_delete_children": true,
    "cascade_delete_connections": true
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "删除分组成功",
  "data": null
}
```

#### 移动连接分组

**参数说明**:
- `id` (string, 必需): 要移动的分组的唯一标识符
- `target_parent_id` (string, 必需): 目标父分组ID，要将分组移动到的父分组位置

```bash
curl -X POST http://localhost:8080/api/v1/storage/connection_groups/move \
  -H "Content-Type: application/json" \
  -d '{
    "id": "group_789",
    "target_parent_id": "group_456"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "移动分组成功",
  "data": {
    "id": "group_789",
    "parent_id": "group_456",
    "name": "生产环境",
    "description": "生产环境数据库连接",
    "icon": "server",
    "display_order": 1,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}
```

### 3. SQL脚本管理

#### 创建SQL脚本

**参数说明**:
- `connection_id` (string, 必需): 关联的数据库连接ID，SQL脚本将与此连接绑定
- `group_id` (string, 必需): 脚本所属的分组ID
- `name` (string, 必需): SQL脚本的名称
- `description` (string, 可选): SQL脚本的详细描述
- `content` (string, 可选): SQL脚本的内容，如果不提供则创建空脚本
- `favorite` (boolean, 可选): 是否标记为收藏

**验证逻辑**:
- 系统会自动验证 `connection_id` 是否存在于数据库连接表中
- 系统会自动验证 `group_id` 是否存在于脚本分组表中
- 如果 `connection_id` 不存在，将返回错误码表示"数据库连接不存在"
- 如果 `group_id` 不存在，将返回错误码表示"脚本分组不存在"

```bash
curl -X POST http://localhost:8080/api/v1/storage/scripts/create \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_123456",
    "group_id": "script_group_1",
    "name": "用户管理查询",
    "description": "用户管理相关SQL脚本",
    "content": "SELECT * FROM users WHERE status = 'active';",
    "favorite": true
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "创建SQL脚本成功",
  "data": {
    "id": "script_456",
    "connection_id": "conn_123456",
    "group_id": "script_group_1",
    "name": "用户管理查询",
    "description": "用户管理相关SQL脚本",
    "content": "SELECT * FROM users WHERE status = 'active';",
    "favorite": true,
    "last_executed": null,
    "execution_count": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

#### 获取SQL脚本

**参数说明**:
- `id` (string, 必需): SQL脚本的唯一标识符

```bash
curl -X POST http://localhost:8080/api/v1/storage/scripts/get \
  -H "Content-Type: application/json" \
  -d '{
    "id": "script_456"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "获取SQL脚本成功",
  "data": {
    "id": "script_456",
    "connection_id": "conn_123456",
    "group_id": "script_group_1",
    "name": "用户管理查询",
    "description": "用户管理相关SQL脚本",
    "content": "SELECT * FROM users WHERE status = 'active';",
    "favorite": true,
    "last_executed": "2024-01-15T11:00:00Z",
    "execution_count": 2,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  }
}
```

#### 更新SQL脚本

**参数说明**:
- `id` (string, 必需): 要更新的SQL脚本的唯一标识符
- `name` (string, 可选): 新的脚本名称
- `description` (string, 可选): 新的脚本描述
- `content` (string, 可选): 新的脚本内容
- `favorite` (boolean, 可选): 是否标记为收藏

```bash
curl -X POST http://localhost:8080/api/v1/storage/scripts/update \
  -H "Content-Type: application/json" \
  -d '{
    "id": "script_456",
    "name": "用户管理查询_V2",
    "description": "用户管理相关SQL脚本 (更新版)",
    "content": "SELECT * FROM users WHERE status = 'active';\n\n-- 用户统计\nSELECT COUNT(*) as total_users FROM users;",
    "favorite": true
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "更新SQL脚本成功",
  "data": {
    "id": "script_456",
    "connection_id": "conn_123456",
    "group_id": "script_group_1",
    "name": "用户管理查询_V2",
    "description": "用户管理相关SQL脚本 (更新版)",
    "content": "SELECT * FROM users WHERE status = 'active';\n\n-- 用户统计\nSELECT COUNT(*) as total_users FROM users;",
    "favorite": true,
    "last_executed": "2024-01-15T11:00:00Z",
    "execution_count": 2,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:40:00Z"
  }
}
```

#### 删除SQL脚本

**参数说明**:
- `id` (string, 必需): 要删除的SQL脚本的唯一标识符

```bash
curl -X POST http://localhost:8080/api/v1/storage/scripts/delete \
  -H "Content-Type: application/json" \
  -d '{
    "id": "script_456"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "删除SQL脚本成功",
  "data": null
}
```

#### 获取指定连接的所有SQL脚本

**参数说明**:
- `connection_id` (string, 必需): 数据库连接的唯一标识符，要列出此连接下的所有SQL脚本

```bash
curl -X POST http://localhost:8080/api/v1/storage/scripts/list_by_connection \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_123456"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "获取SQL脚本列表成功",
  "data": [
    {
      "id": "script_456",
      "connection_id": "conn_123456",
      "group_id": "script_group_1",
      "name": "用户管理查询",
      "description": "用户管理相关SQL脚本",
      "favorite": true,
      "last_executed": "2024-01-15T11:00:00Z",
      "execution_count": 2,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:35:00Z"
    },
    {
      "id": "script_789",
      "connection_id": "conn_123456",
      "group_id": "script_group_1",
      "name": "订单统计",
      "description": "订单数据统计报表",
      "favorite": false,
      "last_executed": "2024-01-15T10:45:00Z",
      "execution_count": 5,
      "created_at": "2024-01-15T09:00:00Z",
      "updated_at": "2024-01-15T09:15:00Z"
    }
  ]
}
```

#### 更新SQL脚本执行统计

**参数说明**:
- `id` (string, 必需): 要更新统计的SQL脚本的唯一标识符

```bash
curl -X POST http://localhost:8080/api/v1/storage/scripts/update_stats \
  -H "Content-Type: application/json" \
  -d '{
    "id": "script_456"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "更新SQL脚本执行统计成功",
  "data": {
    "id": "script_456",
    "last_executed": "2024-01-15T12:30:00Z",
    "execution_count": 3
  }
}
```

### 4. 脚本分组管理

#### 创建脚本分组

**参数说明**:
- `parent_id` (string, 可选): 父分组ID，如果不提供则创建为根分组
- `name` (string, 必需): 新分组的名称
- `description` (string, 可选): 分组的详细描述

```bash
curl -X POST http://localhost:8080/api/v1/storage/script_groups/create \
  -H "Content-Type: application/json" \
  -d '{
    "parent_id": "script_group_root",
    "name": "报表查询",
    "description": "数据报表相关查询脚本"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "创建脚本分组成功",
  "data": {
    "id": "script_group_123",
    "parent_id": "script_group_root",
    "name": "报表查询",
    "description": "数据报表相关查询脚本",
    "scripts": [],
    "children": [],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

#### 获取脚本分组树结构

**参数说明**:
- 无特殊参数，请求体可以为空对象 `{}`

```bash
curl -X POST http://localhost:8080/api/v1/storage/script_groups/tree \
  -H "Content-Type: application/json" \
  -d '{}'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "获取脚本分组树结构成功",
  "data": {
    "id": "script_group_root",
    "parent_id": "",
    "name": "根分组",
    "description": "所有脚本的根分组",
    "scripts": [],
    "children": [
      {
        "id": "script_group_1",
        "parent_id": "script_group_root",
        "name": "用户管理",
        "description": "用户相关查询",
        "scripts": [
          {
            "id": "script_456",
            "name": "用户管理查询",
            "favorite": true
          }
        ],
        "children": []
      },
      {
        "id": "script_group_123",
        "parent_id": "script_group_root",
        "name": "报表查询",
        "description": "数据报表相关查询脚本",
        "scripts": [],
        "children": []
      }
    ]
  }
}
```

#### 获取指定脚本分组

**参数说明**:
- `id` (string, 必需): 脚本分组的唯一标识符

```bash
curl -X POST http://localhost:8080/api/v1/storage/script_groups/get \
  -H "Content-Type: application/json" \
  -d '{
    "id": "script_group_1"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "获取脚本分组成功",
  "data": {
    "id": "script_group_1",
    "parent_id": "script_group_root",
    "name": "用户管理",
    "description": "用户相关查询",
    "scripts": [
      {
        "id": "script_456",
        "name": "用户管理查询",
        "favorite": true
      }
    ],
    "children": [],
    "created_at": "2024-01-15T09:00:00Z",
    "updated_at": "2024-01-15T09:00:00Z"
  }
}
```

#### 更新脚本分组

**参数说明**:
- `id` (string, 必需): 要更新的脚本分组的唯一标识符
- `name` (string, 可选): 新的分组名称
- `description` (string, 可选): 新的分组描述

```bash
curl -X POST http://localhost:8080/api/v1/storage/script_groups/update \
  -H "Content-Type: application/json" \
  -d '{
    "id": "script_group_1",
    "name": "用户管理查询",
    "description": "用户相关查询和分析"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "更新脚本分组成功",
  "data": {
    "id": "script_group_1",
    "parent_id": "script_group_root",
    "name": "用户管理查询",
    "description": "用户相关查询和分析",
    "created_at": "2024-01-15T09:00:00Z",
    "updated_at": "2024-01-15T11:30:00Z"
  }
}
```

#### 删除脚本分组

**参数说明**:
- `id` (string, 必需): 要删除的脚本分组的唯一标识符
- `cascade_delete_children` (boolean, 可选): 是否级联删除子分组，默认为false
- `cascade_delete_scripts` (boolean, 可选): 是否级联删除分组下的SQL脚本，默认为false

**注意事项**:
- **根目录保护**: 系统根目录（ID: `root_default`）不能被删除
- 如果 `cascade_delete_children` 为 true，会递归删除该分组下的所有子分组
- 如果 `cascade_delete_scripts` 为 true，会删除该分组下的所有SQL脚本
- 如果两个参数都为 false（默认值），只有在分组为空（无子分组且无脚本）时才能删除
- 删除操作会同时删除关联的SQL脚本文件

```bash
curl -X POST http://localhost:8080/api/v1/storage/script_groups/delete \
  -H "Content-Type: application/json" \
  -d '{
    "id": "script_group_1",
    "cascade_delete_children": true,
    "cascade_delete_scripts": true
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "删除脚本分组成功",
  "data": null
}
```

#### 移动脚本分组

**参数说明**:
- `id` (string, 必需): 要移动的脚本分组的唯一标识符
- `target_parent_id` (string, 必需): 目标父分组ID

```bash
curl -X POST http://localhost:8080/api/v1/storage/script_groups/move \
  -H "Content-Type: application/json" \
  -d '{
    "id": "script_group_1",
    "target_parent_id": "script_group_123"
  }'
```

**响应示例**:
```json
{
  "code": 0,
  "message": "移动脚本分组成功",
  "data": {
    "id": "script_group_1",
    "parent_id": "script_group_123",
    "name": "用户管理查询",
    "description": "用户相关查询和分析",
    "created_at": "2024-01-15T09:00:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}
```

## 错误响应示例

```json
{
  "code": 2003,
  "message": "连接不存在",
  "error": "connection with id 'conn_123' not found"
}
```

```json
{
  "code": 1001,
  "message": "参数错误",
  "error": "group_id is required"
}
```

## 错误码说明

- `1001`: 参数错误
- `1002`: 资源未找到
- `2001`: 连接池已满
- `2002`: 连接池已关闭
- `2003`: 连接不存在
- `2004`: 连接已存在
- `3001`: 分组不存在（创建连接或分组时如果指定的父分组ID不存在会返回此错误）
- `3002`: 分组已存在
- `3003`: 父分组ID和名称不匹配（创建分组时如果指定的父分组ID和名称不匹配会返回此错误）
- `4001`: SQL脚本不存在
- `4002`: SQL脚本已存在

## 数据结构说明

### 字段说明

- **display_order**: 整数类型，用于控制显示顺序。创建时如果未提供或为0，系统会自动计算合适的值，确保新资源显示在同级资源的最后位置。

### DBConnectionResponse
```json
{
  "id": "string",
  "group_id": "string",
  "name": "string",
  "description": "string",
  "db_detail": {
    "type": "mysql|postgresql|oracle|sqlserver",
    "version": "string",
    "server": "string",
    "port": "integer",
    "username": "string",
    "database": "string",
    "connection_string": "string",
    "use_ssh_tunnel": "boolean",
    "last_connected": "datetime"
  },
  "color": "string",
  "auto_connect": "boolean",
  "display_order": "integer",
  "scripts": ["ScriptResponse"],
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### ConnectionGroupResponse
```json
{
  "id": "string",
  "parent_id": "string",
  "name": "string",
  "description": "string",
  "icon": "string",
  "display_order": "integer",
  "connections": ["DBConnectionResponse"],
  "children": ["ConnectionGroupResponse"],
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### ScriptResponse
```json
{
  "id": "string",
  "connection_id": "string",
  "group_id": "string",
  "name": "string",
  "description": "string",
  "content": "string",
  "favorite": "boolean",
  "last_executed": "datetime",
  "execution_count": "integer",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### ScriptGroupResponse
```json
{
  "id": "string",
  "parent_id": "string",
  "name": "string",
  "description": "string",
  "scripts": ["ScriptResponse"],
  "children": ["ScriptGroupResponse"],
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

## 注意事项

1. 密码字段在响应中会被隐藏或加密
2. 删除操作会级联删除相关资源，请谨慎使用
3. 支持分组的树状层次结构，便于组织和管理
4. 所有时间字段使用ISO 8601格式
5. 所有API都使用POST方法，即使是获取数据操作
6. `display_order` 字段支持自动计算，创建资源时如果未提供该字段或值为0，系统会自动分配合适的显示顺序