first commit

docs/doc.md

@@ -0,0 +1,182 @@
+# 接口文档（主要接口）
+
+以下文档覆盖 README 中“主要接口包括”的四项能力：测试连通、获取数据库信息、获取所有表及备注信息、获取表字段及备注信息。所有接口均遵循统一返回结构：
+
+```json
+{
+  "success": true,
+  "message": "描述信息",
+  "data": { "具体数据" },
+  "error": null
+}
+```
+
+## 1. 测试能否连通数据库
+- URL: `/api/v1/connections/test`
+- Method: `POST`
+- Content-Type: `application/json`
+- 请求体参数（DatabaseConnection）:
+  - db_type: string（mysql|oracle|sqlserver|postgresql）
+  - host: string
+  - port: number
+  - username: string
+  - password: string
+  - database: string，可选
+  - mode: string，可选（Oracle专用）
+  - threaded: boolean，可选（Oracle专用）
+  - extra_params: object，可选（附加参数）
+- 请求示例:
+
+```json
+{
+  "db_type": "mysql",
+  "host": "127.0.0.1",
+  "port": 3306,
+  "username": "root",
+  "password": "pass",
+  "database": "test_db"
+}
+```
+
+- 返回示例（成功）:
+
+```json
+{
+  "success": true,
+  "message": "数据库连通性测试成功",
+  "data": {
+    "ok": true,
+    "db_type": "mysql",
+    "connection_url": "mysql+pymysql://root:***@127.0.0.1:3306/test_db?charset=utf8mb4",
+    "server_version": "8.0.36"
+  },
+  "error": null
+}
+```
+
+- 返回示例（失败）:
+
+```json
+{
+  "success": false,
+  "message": "连接测试失败: 认证失败",
+  "data": null,
+  "error": "认证失败"
+}
+```
+
+## 2. 获取数据库信息
+- URL: `/api/v1/databases/info`
+- Method: `GET`
+- Query 参数:
+  - connection_id: string（创建连接时生成的连接ID）
+- 返回字段:
+  - database_name: string
+  - tables: string[]（所有表名）
+  - table_count: number（表数量）
+- 返回示例:
+
+```json
+{
+  "success": true,
+  "message": "获取数据库信息成功",
+  "data": {
+    "database_name": "test_db",
+    "tables": ["users", "orders", "products"],
+    "table_count": 3
+  },
+  "error": null
+}
+```
+
+## 3. 获取数据库中所有的表和表备注信息
+- URL: `/api/v1/tables/details`
+- Method: `GET`
+- Query 参数:
+  - connection_id: string
+- 返回字段:
+  - tables: 数组，每项包含
+    - table_name: string
+    - table_comment: string|null
+  - table_count: number
+- 返回示例:
+
+```json
+{
+  "success": true,
+  "message": "获取表及备注信息成功",
+  "data": {
+    "tables": [
+      { "table_name": "users", "table_comment": "用户信息表" },
+      { "table_name": "orders", "table_comment": "订单表" },
+      { "table_name": "products", "table_comment": "" }
+    ],
+    "table_count": 3
+  },
+  "error": null
+}
+```
+
+说明：不同数据库的备注来源
+- MySQL: INFORMATION_SCHEMA.TABLES.TABLE_COMMENT
+- PostgreSQL: pg_class/obj_description
+- SQL Server: sys.extended_properties('MS_Description')
+- Oracle: user_tab_comments
+
+## 4. 获取数据表中字段名和类型以及备注信息
+- URL: `/api/v1/tables/columns`
+- Method: `GET`
+- Query 参数:
+  - connection_id: string
+  - table_name: string
+- 返回字段:
+  - table_name: string
+  - columns: 数组，每项包含
+    - column_name: string
+    - data_type: string
+    - is_nullable: string|boolean（不同库返回值格式略有差异）
+    - column_default: string|null
+    - column_comment: string|null
+    - max_length: number|null
+    - numeric_precision: number|null（部分库返回）
+    - numeric_scale: number|null（部分库返回）
+- 返回示例（MySQL样例）:
+
+```json
+{
+  "success": true,
+  "message": "获取字段信息成功",
+  "data": {
+    "table_name": "users",
+    "columns": [
+      {
+        "column_name": "id",
+        "data_type": "int",
+        "is_nullable": "NO",
+        "column_default": null,
+        "column_comment": "主键ID",
+        "max_length": null,
+        "numeric_precision": 10,
+        "numeric_scale": 0
+      },
+      {
+        "column_name": "name",
+        "data_type": "varchar",
+        "is_nullable": "YES",
+        "column_default": null,
+        "column_comment": "用户名",
+        "max_length": 255,
+        "numeric_precision": null,
+        "numeric_scale": null
+      }
+    ]
+  },
+  "error": null
+}
+```
+
+说明：不同数据库的字段备注来源
+- MySQL: INFORMATION_SCHEMA.COLUMNS.COLUMN_COMMENT
+- PostgreSQL: col_description + format_type
+- SQL Server: sys.extended_properties('MS_Description')
+- Oracle: user_col_comments + user_tab_columns