X-Agents/team-require/api/database-check.md

# 检查数据库连接并获取表结构

## 接口地址

```
POST /database/check
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| db_type | string | 是 | 数据库类型：`mysql`、`postgres`、`neo4j` |
| host | string | 是 | 数据库主机 |
| port | int | 是 | 数据库端口 |
| username | string | 是 | 用户名 |
| password | string | 否 | 密码 |
| database | string | 是 | 数据库名 |
| charset | string | 否 | 字符集，默认 `utf8mb4` |
| ssl_mode | string | 否 | SSL 模式 |
| database_id | string | 否 | 已存在的数据库ID，用于恢复字段映射 |
| uri | string | 否 | Neo4j 连接地址（如 bolt://localhost:7687），Neo4j 类型必填 |

## 请求示例（MySQL/PostgreSQL）

```json
{
  "db_type": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "root",
  "database": "students",
  "charset": "utf8mb4",
  "database_id": "xxx-xxx-xxx"
}
```

## 请求示例（Neo4j）

```json
{
  "db_type": "neo4j",
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password",
  "database": "neo4j"
}
```

## 返回参数

| 参数 | 类型 | 说明 |
|------|------|------|
| success | bool | 是否连接成功 |
| message | string | 消息 |
| database | string | 数据库名 |
| tables | array | 表结构列表（MySQL/PostgreSQL） |
| graphs | object | 图谱数据（Neo4j） |

### tables[] 详情（关系型数据库）

| 参数 | 类型 | 说明 |
|------|------|------|
| table_name | string | 表名 |
| table_comment | string | 表注释 |
| ddl | string | 建表 DDL（带 COMMENT 的映射后 DDL） |
| columns | array | 列信息列表 |

### columns[] 详情

| 参数 | 类型 | 说明 |
|------|------|------|
| column_name | string | 列名 |
| data_type | string | 数据类型 |
| column_type | string | 完整列类型 |
| is_nullable | string | 是否可空（YES/NO） |
| default_value | string | 默认值 |
| column_key | string | 主键标识（PRI/MUL/UNI） |
| extra | string | 额外信息（如 auto_increment） |
| column_comment | string | 列注释 |
| mapped_name | string | 字段中文映射名（已保存的映射） |

### graphs 详情（Neo4j）

| 参数 |类型| 说明 |
|------|------|------|
| labels | array | 标签列表 |
| relationshipTypes | array | 关系类型列表 |
| nodes | array | 节点属性定义 |
| relationships | array | 关系属性定义 |

### graphs.labels[]

| 参数 | 类型 | 说明 |
|------|------|------|
| name | string | 标签名称 |
| count | int | 节点数量 |

### graphs.relationshipTypes[]

| 参数 | 类型 | 说明 |
|------|------|------|
| name | string | 关系类型名称 |
| count | int | 关系数量 |

### graphs.nodes[]

| 参数 | 类型 | 说明 |
|------|------|------|
| label | string | 节点标签名 |
| properties | array | 属性列表 |

### graphs.relationships[]

| 参数 | 类型 | 说明 |
|------|------|------|
| type | string | 关系类型名 |
| startLabel | string | 起始节点标签 |
| endLabel | string | 目标节点标签 |
| properties | array | 属性列表 |

## 返回示例（MySQL/PostgreSQL）

```json
{
  "success": true,
  "message": "connection successful",
  "database": "students",
  "tables": [
    {
      "table_name": "users",
      "table_comment": "用户表",
      "ddl": "CREATE TABLE `users` (\n  `id` int(10) unsigned NOT NULL COMMENT '用户ID'\n  ...\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4",
      "columns": [
        {
          "column_name": "id",
          "data_type": "int",
          "column_type": "int(10) unsigned",
          "is_nullable": "NO",
          "default_value": "",
          "column_key": "PRI",
          "extra": "auto_increment",
          "column_comment": "",
          "mapped_name": "用户ID"
        }
      ]
    }
  ]
}
```

## 返回示例（Neo4j）

```json
{
  "success": true,
  "message": "connection successful",
  "database": "neo4j",
  "graphs": {
    "labels": [
      {"name": "User", "count": 100},
      {"name": "Order", "count": 50}
    ],
    "relationshipTypes": [
      {"name": "KNOWS", "count": 30},
      {"name": "OWNS", "count": 20}
    ],
    "nodes": [
      {
        "label": "User",
        "properties": [
          {"name": "id", "type": "string"},
          {"name": "name", "type": "string"}
        ]
      }
    ],
    "relationships": [
      {
        "type": "KNOWS",
        "startLabel": "User",
        "endLabel": "User",
        "properties": [
          {"name": "since", "type": "date"}
        ]
      }
    ]
  }
}
```

## 使用场景

1. **关系型数据库**：
   - 首次连接：不传 `database_id`，获取实时表结构
   - 恢复映射：传入 `database_id`，返回已保存的 `mapped_name` 和 `ddl`

2. **Neo4j 图数据库**：
   - 连接 Neo4j 并获取图谱概览数据（标签、关系类型、属性定义）
   - 用于前端图可视化展示