feat: 重构前后端架构，添加Go后端和Python Agent服务

- 新增 Go 语言后端服务(server/)，包含用户认证、Agent管理、数据库连接等API - 新增 Python Agent 服务(agent/)，实现Agent核心逻辑和工具集 - 前端从原生HTML迁移到Vue.js框架(web/src/) - 添加 Docker Compose 支持(docker-compose.yml) - 添加项目架构文档(docs/ARCHITECTURE.md) - 添加环境变量示例(.env.example)和本地启动脚本(start-local.ps1) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 16:39:42 +08:00
parent 6fe3c412f4
commit b2bc9988a9
90 changed files with 9317 additions and 469 deletions
--- a/team-require/api/README.md
+++ b/team-require/api/README.md
@@ -0,0 +1,14 @@
+# API 接口文档
+
+## 目录
+
+### Database 相关
+
+- [检查数据库连接并获取表结构](database-check.md)
+- [创建数据库配置](database-create.md)
+- [获取数据库列表](database-list.md)
+- [获取子表列表](subtable-list.md)
+
+---
+
+> 接口如有更新，请同步更新此文档
--- a/team-require/api/database-check.md
+++ b/team-require/api/database-check.md
@@ -0,0 +1,103 @@
+# 检查数据库连接并获取表结构
+
+## 接口地址
+
+```
+POST /database/check
+```
+
+## 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| db_type | string | 是 | 数据库类型：`mysql`、`postgres` |
+| host | string | 是 | 数据库主机 |
+| port | int | 是 | 数据库端口 |
+| username | string | 是 | 用户名 |
+| password | string | 否 | 密码 |
+| database | string | 是 | 数据库名 |
+| charset | string | 否 | 字符集，默认 `utf8mb4` |
+| ssl_mode | string | 否 | SSL 模式 |
+| database_id | string | 否 | 已存在的数据库ID，用于恢复字段映射 |
+
+## 请求示例
+
+```json
+{
+  "db_type": "mysql",
+  "host": "localhost",
+  "port": 3306,
+  "username": "root",
+  "password": "root",
+  "database": "students",
+  "charset": "utf8mb4",
+  "database_id": "xxx-xxx-xxx"  // 可选，用于恢复字段映射
+}
+```
+
+## 返回参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| success | bool | 是否连接成功 |
+| message | string | 消息 |
+| database | string | 数据库名 |
+| tables | array | 表结构列表 |
+
+### 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 | 字段中文映射名（已保存的映射） |
+
+## 返回示例
+
+```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"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 使用场景
+
+1. **首次连接**：不传 `database_id`，获取实时表结构
+2. **恢复映射**：传入 `database_id`，返回已保存的 `mapped_name` 和 `ddl`
--- a/team-require/api/database-create.md
+++ b/team-require/api/database-create.md
@@ -0,0 +1,104 @@
+# 创建数据库配置
+
+## 接口地址
+
+```
+POST /database/add
+```
+
+## 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | string | 是 | 数据库名称 |
+| description | string | 否 | 描述 |
+| db_type | string | 是 | 数据库类型 |
+| host | string | 是 | 主机 |
+| port | int | 是 | 端口 |
+| username | string | 是 | 用户名 |
+| password | string | 否 | 密码 |
+| database | string | 是 | 数据库名 |
+| charset | string | 否 | 字符集 |
+| ssl_mode | string | 否 | SSL 模式 |
+| sub_tables | array | 否 | 子表配置列表 |
+
+### sub_tables[] 详情
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| parent_table | string | 是 | 原始表名 |
+| sub_table_name | string | 是 | 子表别名 |
+| sub_table_comment | string | 否 | 子表注释 |
+| mapping_type | string | 否 | 映射类型 |
+| relation_field | string | 否 | 关联字段 |
+| relation_type | string | 否 | 关联类型 |
+| fields | array | 否 | 字段映射列表 |
+
+### fields[] 详情
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| column_name | string | 是 | 列名 |
+| mapped_name | string | 是 | 中文映射名 |
+
+## 请求示例
+
+```json
+{
+  "name": "学生数据库",
+  "description": "用于存储学生信息",
+  "db_type": "mysql",
+  "host": "localhost",
+  "port": 3306,
+  "username": "root",
+  "password": "root",
+  "database": "students",
+  "charset": "utf8mb4",
+  "sub_tables": [
+    {
+      "parent_table": "users",
+      "sub_table_name": "用户表",
+      "sub_table_comment": "用户信息",
+      "fields": [
+        {"column_name": "id", "mapped_name": "用户ID"},
+        {"column_name": "name", "mapped_name": "用户名"}
+      ]
+    }
+  ]
+}
+```
+
+## 返回参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| id | string | 数据库记录ID |
+| name | string | 数据库名称 |
+| db_type | string | 数据库类型 |
+| host | string | 主机 |
+| port | int | 端口 |
+| ... | ... | 其他字段 |
+
+## 返回示例
+
+```json
+{
+  "id": "xxx-xxx-xxx",
+  "name": "学生数据库",
+  "description": "用于存储学生信息",
+  "db_type": "mysql",
+  "host": "localhost",
+  "port": 3306,
+  "username": "root",
+  "password": "root",
+  "database": "students",
+  "table_count": 1,
+  "charset": "utf8mb4",
+  "created_at": "2026-03-06T15:00:00Z"
+}
+```
+
+## 说明
+
+- 创建时会自动连接数据库获取表结构 DDL
+- 如果传入了 `fields`（字段映射），会自动生成带 COMMENT 的新 DDL 并存储
--- a/team-require/api/database-list.md
+++ b/team-require/api/database-list.md
@@ -0,0 +1,51 @@
+# 获取数据库列表
+
+## 接口地址
+
+```
+GET /database/list
+```
+
+## 请求参数
+
+无
+
+## 返回参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| list | array | 数据库列表 |
+
+### list[] 详情
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| id | string | 数据库ID |
+| name | string | 数据库名称 |
+| description | string | 描述 |
+| db_type | string | 数据库类型 |
+| host | string | 主机 |
+| port | int | 端口 |
+| database | string | 数据库名 |
+| table_count | int | 子表数量 |
+| created_at | string | 创建时间 |
+
+## 返回示例
+
+```json
+{
+  "list": [
+    {
+      "id": "xxx-xxx",
+      "name": "学生数据库",
+      "description": "用于存储学生信息",
+      "db_type": "mysql",
+      "host": "localhost",
+      "port": 3306,
+      "database": "students",
+      "table_count": 5,
+      "created_at": "2026-03-06T15:00:00Z"
+    }
+  ]
+}
+```
--- a/team-require/api/subtable-list.md
+++ b/team-require/api/subtable-list.md
@@ -0,0 +1,75 @@
+# 获取子表列表
+
+## 接口地址
+
+```
+GET /sub-table/database/:database_id
+```
+
+## 路径参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| database_id | string | 是 | 数据库ID |
+
+## 返回参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| list | array | 子表列表 |
+
+### list[] 详情
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| id | string | 子表ID |
+| database_id | string | 关联的数据库ID |
+| parent_table | string | 原始表名 |
+| sub_table_name | string | 子表别名 |
+| sub_table_comment | string | 子表注释 |
+| mapping_type | string | 映射类型 |
+| relation_field | string | 关联字段 |
+| relation_type | string | 关联类型 |
+| fields | array | 字段映射列表 |
+| ddl | string | 建表 DDL（带 COMMENT） |
+| created_at | string | 创建时间 |
+
+### fields[] 详情
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| column_name | string | 列名 |
+| mapped_name | string | 中文映射名 |
+
+## 返回示例
+
+```json
+{
+  "list": [
+    {
+      "id": "xxx-xxx",
+      "database_id": "database-xxx",
+      "parent_table": "users",
+      "sub_table_name": "用户表",
+      "sub_table_comment": "用户信息",
+      "mapping_type": "horizontal",
+      "relation_field": "id",
+      "relation_type": "one_to_many",
+      "fields": [
+        {"column_name": "id", "mapped_name": "用户ID"},
+        {"column_name": "name", "mapped_name": "用户名"}
+      ],
+      "ddl": "CREATE TABLE `users` (\n  `id` int(10) unsigned NOT NULL COMMENT '用户ID'\n  ...\n)",
+      "created_at": "2026-03-06T15:00:00Z"
+    }
+  ]
+}
+```
+
+## 使用场景
+
+用于恢复映射状态：
+1. 用户点击已存在的数据库的 "Map Tables" 按钮
+2. 调用此接口获取已保存的子表信息
+3. 根据 `parent_table` 勾选已选择的表
+4. 根据 `fields` 恢复字段映射
--- a/team-require/web/columns-api.md
+++ b/team-require/web/columns-api.md
@@ -0,0 +1,92 @@
+# 后端需求 - 表结构返回 columns 数据
+
+## 问题描述
+
+前端在 Edit Mapping 页面需要展示表的列信息（字段名、类型、COMMENT等），但前端自行解析 DDL 存在困难。
+
+## 需求
+
+后端在获取表结构列表时，需要同时返回：
+
+1. **DDL 语句**（已有的需求，继续保留）
+2. **结构化的 columns 数据**（新增）
+
+### 返回数据结构
+
+```json
+{
+  "success": true,
+  "tables": [
+    {
+      "table_name": "exam_scores",
+      "table_comment": "考试成绩表",
+      "ddl": "CREATE TABLE `exam_scores` (...)",
+      "columns": [
+        {
+          "column_name": "id",
+          "data_type": "int",
+          "column_type": "int(10) unsigned",
+          "is_nullable": "NO",
+          "default_value": null,
+          "column_key": "PRI",
+          "extra": "auto_increment",
+          "column_comment": ""
+        },
+        {
+          "column_name": "student_id",
+          "data_type": "int",
+          "column_type": "int(10) unsigned",
+          "is_nullable": "NO",
+          "default_value": null,
+          "column_key": "",
+          "extra": "",
+          "column_comment": ""
+        },
+        {
+          "column_name": "subject",
+          "data_type": "varchar",
+          "column_type": "varchar(50)",
+          "is_nullable": "NO",
+          "default_value": null,
+          "column_key": "",
+          "extra": "",
+          "column_comment": "科目"
+        },
+        {
+          "column_name": "score",
+          "data_type": "double",
+          "column_type": "double",
+          "is_nullable": "YES",
+          "default_value": null,
+          "column_key": "",
+          "extra": "",
+          "column_comment": "分数"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| column_name | string | 列名 |
+| data_type | string | 数据类型（如 int, varchar, double） |
+| column_type | string | 完整列类型（如 int(10) unsigned） |
+| is_nullable | string | 是否可空（YES/NO） |
+| default_value | string | 默认值 |
+| column_key | string | 主键标识（PRI/MUL/UNI） |
+| extra | string | 额外信息（如 auto_increment） |
+| column_comment | string | 列注释 |
+
+## 影响范围
+
+- 文件：`server/internal/service/database_service.go`
+- 函数：`getMySQLTables`, `getPostgresTables`
+- 数据模型：`server/internal/model/sub_table_info.go` 的 `ColumnInfo` 结构体
+
+## 优先级
+
+高 - 前端 Edit Mapping 页面字段映射功能依赖此数据
--- a/team-require/web/field-mapping.md
+++ b/team-require/web/field-mapping.md
@@ -0,0 +1,89 @@
+# 后端需求 - 字段映射保存与读取
+
+## 问题描述
+
+前端 Edit Mapping 页面中，用户输入的字段中文映射名（mapped_name）在保存后，第二次打开时丢失了。
+
+## 原因分析
+
+1. **保存时**：前端只保存了表级别信息，没有保存字段的中文映射
+2. **加载时**：前端每次都从 `/database/check` 重新获取表结构，没有读取已保存的映射数据
+
+## 需求
+
+### 1. 保存字段映射
+
+前端保存时需要传递每个字段的中文映射名，后端需要存储这些数据。
+
+请求结构：
+```json
+{
+  "name": "数据库名",
+  "sub_tables": [
+    {
+      "parent_table": "users",
+      "sub_table_name": "用户表",
+      "sub_table_comment": "用户表",
+      "fields": [
+        {
+          "column_name": "id",
+          "mapped_name": "编号"
+        },
+        {
+          "column_name": "username",
+          "mapped_name": "用户名"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 2. 返回字段映射
+
+后端在返回表结构时，需要同时返回已保存的字段映射信息。
+
+返回结构：
+```json
+{
+  "success": true,
+  "tables": [
+    {
+      "table_name": "users",
+      "table_comment": "用户表",
+      "ddl": "...",
+      "columns": [
+        {
+          "column_name": "id",
+          "data_type": "int",
+          "column_type": "int(10)",
+          "column_comment": "",
+          "mapped_name": "编号"
+        },
+        {
+          "column_name": "username",
+          "data_type": "varchar",
+          "column_type": "varchar(50)",
+          "column_comment": "用户名",
+          "mapped_name": "用户名"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 3. 数据存储
+
+- 可以在 `sub_table_info` 表中增加 `fields` JSON 字段存储字段映射
+- 或者创建新的关联表 `sub_table_fields`
+
+## 影响范围
+
+- `server/internal/service/database_service.go` - Create/Update 方法
+- `server/internal/model/` - 数据模型修改
+- 子表映射的数据存储结构
+
+## 优先级
+
+高 - 用户输入的映射数据丢失影响使用体验
--- a/team-require/web/mapping-state.md
+++ b/team-require/web/mapping-state.md
@@ -0,0 +1,43 @@
+# 后端需求 - 保存和恢复映射状态
+
+## 问题描述
+
+用户第一次选择表并设置字段映射后，第二次点击 "Map Tables" 按钮进入界面时，之前选择的表和设置的字段映射都丢失了。
+
+## 需求
+
+前端打开已存在的数据库映射时，需要恢复以下状态：
+
+### 1. 已选择的表列表
+
+后端需要在数据库记录中保存用户选择了哪些表（不仅仅是子表信息），或者在查询时返回该数据库关联的所有子表。
+
+### 2. 字段映射
+
+每个子表保存的字段映射（mapped_name）需要在前端重新加载时显示。
+
+## 期望的行为
+
+1. 用户点击已存在的数据库的 "Map Tables" 按钮
+2. 前端获取实时表结构
+3. 同时加载该数据库已保存的子表信息（包括选择的表和字段映射）
+4. 前端合并数据，显示：
+   - 已选择的表（勾选状态）
+   - 每个字段之前设置的 mapped_name
+
+## 技术实现建议
+
+在数据库表中增加或利用已有字段：
+
+- `sub_table_info` 表已包含 `Fields` JSON 字段存储字段映射
+- 需要在创建/更新数据库时保存选择的表列表
+- 或者在查询时返回该数据库下所有已创建的子表
+
+## 影响范围
+
+- 数据库创建/更新接口
+- 子表映射查询接口
+
+## 优先级
+
+高 - 影响用户体验，第二次进入无法看到之前的工作成果
--- a/team-require/web/todo-2026-3-6.md
+++ b/team-require/web/todo-2026-3-6.md
@@ -0,0 +1,27 @@
+# Web 前端需求 TODO
+
+## 2026年3月
+
+### 2026-03-06
+
+- [x] **DDL 获取功能** - 后端需在获取表结构时返回 DDL 语句 ✔
+  - 相关文件：`server/internal/service/database_service.go`
+  - 函数：`getMySQLTables`, `getPostgresTables`
+  - 详细需求：[ddl-fetch.md](./ddl-fetch.md)
+
+- [x] **返回结构化 columns 数据** - 后端需返回完整的列信息（column_name, data_type, column_type, is_nullable, default_value, column_key, extra, column_comment）✔
+  - 相关文件：`server/internal/service/database_service.go`
+  - 函数：`getMySQLTables`, `getPostgresTables`
+  - 详细需求：[columns-api.md](./columns-api.md)
+
+- [x] **保存和读取字段映射** - 后端需支持保存/读取字段的中文映射名（mapped_name） ✔
+  - 相关文件：`server/internal/service/database_service.go`, `server/internal/model/`
+  - 详细需求：[field-mapping.md](./field-mapping.md)
+
+- [x] **保存和恢复映射状态** - 第二次进入 Map Tables 时需恢复之前选择的表和字段映射 ✔
+  - 相关文件：`server/internal/service/database_service.go`, `server/internal/model/`
+  - 详细需求：[mapping-state.md](./mapping-state.md)
+
+---
+
+> 需求完成后请完成者打 ✔