# 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` 对象（示例见下）。
  
  server_detail 字段说明（创建/更新时）：
  - `type` (string, 可选): 服务器类型，例如 `ssh`、`jump_host` 等，用于前端展示或选择不同连接适配逻辑。
  - `version` (string, 可选): 服务器相关的协议/软件版本（可选，用于调试/显示）。
  - `server` (string, 必需): 服务器地址或主机名（IP 或域名）。
  - `port` (int, 可选): 服务器端口，未提供时使用默认端口（如 SSH 默认 22）。
  - `username` (string, 可选): 连接服务器时使用的用户名。
  - `auth_type` (string, 可选): 认证类型，示例值 `password` / `private_key`。
  - `password` (string, 可选): 若 `auth_type=="password"`，用于认证的密码（前端应遵循密码不回显的安全策略；如需传密请使用加密前缀 `enc:`）。
  - `private_key` (string, 可选): 若 `auth_type=="private_key"`，用于认证的私钥内容或引用；前端在编辑时不要回显私钥内容，仅在创建/更新时提交新值。
  - `use_sudo` (boolean, 可选): 是否在执行远程命令时使用 sudo 权限（仅在需要时设置为 true）。
  
  前端使用建议：
  - `server` 为必填显示项，前端应校验格式（非空、可选的 host/port 规范）。
  - 当 `auth_type` 为 `private_key` 时，前端不要在编辑表单回填已有私钥，只显示占位符并在用户输入时发送新值。
  - 密码/私钥类字段建议前端以安全输入框处理，且不在列表/详情页面回显明文。

  示例（创建 `kind=="server"` 的连接）:

```bash
curl -X POST http://localhost:8080/api/v1/storage/connections/create \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group_1",
    "name": "Jump Host - 管理服务器",
    "description": "用于运维的跳板机",
    "kind": "server",
    "color": "#FF7043",
    "auto_connect": false,
    "server_detail": {
      "type": "ssh",
      "server": "jump.example.com",
      "port": 22,
      "username": "ops_user",
      "auth_type": "private_key",
      "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
      "use_sudo": true
    }
  }'
```

**响应示例（kind=="server"）**:
```json
{
  "code": 0,
  "message": "创建连接成功",
  "data": {
    "id": "conn_987654",
    "group_id": "group_1",
    "name": "Jump Host - 管理服务器",
    "description": "用于运维的跳板机",
    "kind": "server",
    "server_detail": {
      "type": "ssh",
      "version": "7.9",
      "server": "jump.example.com",
      "port": 22,
      "username": "ops_user",
      "auth_type": "private_key",
      "use_sudo": true
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```
- `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"
  }
}
```

前端使用/行为说明：
- 更新为部分更新：前端只需发送要修改的字段，未包含的字段后端会保持原值；若要清空某个可选字段（例如 `description`），可发送空字符串 `"description": ""`。
- 对于 `db_detail` 或 `server_detail` 中的可选子字段：当前实现语义为“字段缺失 = 不修改”。建议前端在不想修改某个敏感字段（如密码）时不要在请求中包含该字段；若确实需要清空，请先在后端与产品确认 `null` 的语义。
- 密码字段：若前端不希望修改密码，请不要在 `db_detail.password` 中发送空字符串或任何值；保持字段缺失。

响应字段使用建议：
- 前端在收到更新后的 `data` 时应以 `data` 为最终状态刷新本地缓存或界面（不要只局部合并以避免不一致）。

响应说明：
- `data` 为连接数组，包含所有分组下的连接（已按 `display_order` 和 `name` 排序）。前端可用它填充连接列表页或缓存用于本地搜索。
- 建议前端按 `group_id` 聚合显示，或者在 UI 上提供按分组展开/收起的视图。


**响应说明**: 返回类型为 `ConnectionDetailsResponse`：仅按 `kind` 字段填充对应的嵌套 detail（`db_detail` 或 `server_detail`）。

字段含义与前端使用建议：
- `group_id`: 前端在创建连接时应传入用户选择的分组ID；若用户在 UI 中没有选分组，可默认使用 `root_default`。
- `name`: 建议前端限制最大长度并防止空字符串提交。
- `kind`: 决定哪些嵌套详情需要填写；前端应根据选择的 `kind` 动态展示 `db_detail` 或 `server_detail` 表单。
- `db_detail.password`: 建议前端支持明文与加密串两种输入方式，并在展示列表时不要回显明文密码。
- `auto_connect`: 若为 true，前端可在启动时尝试自动恢复连接（若后端支持）。

响应字段详解（供前端展示/缓存）：
- `data.id`: 唯一标识符，前端应在后续所有对该连接的操作中使用该 ID。
- `data.kind`: 用于选择详情模板（数据库/服务器），前端不应根据 detail 字段来推断 kind，需以该字段为准。
- `data.db_detail` / `data.server_detail`: 仅在 `kind` 匹配时返回；前端在编辑时将其值回填到相应表单。
- `data.created_at`/`data.updated_at`: 建议前端在详情页以用户本地时区格式展示，同时保留 ISO 字符串用于调试或排序。

错误提示与前端处理建议：
- 当收到 `code != 0` 时，前端应展示 `message` 并根据错误码提示用户（例如 3001 表示分组不存在，提示用户选择或创建分组）。

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

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

```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"
    }
  ]
}
```
响应字段详解（单条获取）：
- `db_detail`：当 `kind=="database"` 时提供，包含连接必要信息；若为 `server`，则为 `server_detail`。
- `auto_connect`：若为 true，前端可在列表或详情页提供“连接中/已启用自动连接”的视觉标识。
- `color`：若为空，前端可使用默认颜色或根据 `kind` 显示不同图标色。
- `last_connected`：用于显示连接活跃度；如果为空/零值，说明从未成功连接。

安全与隐私说明：
- 响应中 `password` 字段可能被后端以明文或加密形式返回（取决于实现）；前端不得在公共页面回显明文密码，编辑时应在输入框中显示为空或占位符，用户输入新密码会覆盖原值。

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

**参数说明**:
- `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, 必需): 要更新的数据库连接的唯一标识符
- 顶层可更新字段（可选）：`group_id`, `name`, `description`, `color`, `auto_connect`, `display_order`。
- detail 字段应放在嵌套对象中：当 `kind=="database"` 时使用 `db_detail`；当 `kind=="server"` 时使用 `server_detail`。

- `db_detail` 可包含的可选字段：`type`, `version`, `server`, `port`, `username`, `password`, `database`, `connection_string`, `use_ssh_tunnel`。
- `server_detail` 可包含的可选字段：`type`, `version`, `server`, `port`, `username`, `auth_type`, `private_key`, `use_sudo`。

**说明**: 更新操作支持部分字段更新——所有 detail 子字段均为可选（使用 JSON 字段缺失或 `null` 表示不修改）。示例：

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

**响应示例**:
```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, 必需): 要删除的数据库连接的唯一标识符

- `group_id` (string, 可选但推荐): 连接所属分组ID。路由处理器会接受并传递该字段到后端用于校验/日志（示例请求体请同时提供 `group_id` 与 `id`）。

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

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

前端使用建议：
- 删除操作为幂等性设计：如果被删除对象不存在，后端会返回错误；前端应在执行删除前弹出确认对话框并提示可能的级联影响（脚本/分组等）。
- `group_id` 为推荐字段，主要用于前端调用时做额外校验或展示上下文（例如提示当前来自哪个分组）。


#### 移动数据库连接

**参数说明**:
- `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"
  }
}
```

前端使用建议：
- 移动操作完成后后端返回更新后的 `DBConnectionResponse`，前端应以返回数据为准更新列表视图和分组计数。
- 此操作会更新 `display_order` 和 `group_id`，若前端有本地缓存请同步更新或重新请求受影响分组的数据。


### 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"
  }
}
```

前端建议：
- `parent_id` 可选，若前端未选择父分组可传空字符串表示根分组。
- 创建成功后返回的 `id` 为分组唯一标识，前端应在 UI 中使用该 ID 进行后续操作（例如在创建连接时引用）。


**错误响应示例**:
```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"
  }
}
```

响应字段与前端展示建议：
- `connections` 列表中包含分组下的连接简要信息，前端可以直接用于渲染分组卡片或在分组树展开时展示子连接列表。
- `children` 包含子分组数组，前端可递归渲染分组树。
- 当 `load_connections` 为 false 时，`connections` 可能为空数组；前端在请求界面上提供“仅加载结构/同时加载连接”的选项可以减少首次加载的网络成本。


#### 更新连接分组

**参数说明**:
- `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，系统会自动分配合适的显示顺序