docs(mcp): 完善模块关联配置的文档和示例

(cherry picked from commit e042d0464c47ab8441f363df1a1242e26a9c13f7)
2025-08-05 18:14:27 +08:00
parent 2139e38147
commit b71ad7b6f4
3 changed files with 183 additions and 6 deletions
--- a/server/mcp/execution_plan_schema.md
+++ b/server/mcp/execution_plan_schema.md
@@ -85,12 +85,25 @@ type AutoCodeField struct {
    Clearable       bool        `json:"clearable"`       // 是否可清空
    Sort            bool        `json:"sort"`            // 是否支持排序
    PrimaryKey      bool        `json:"primaryKey"`      // 是否主键
-    DataSource      *DataSource `json:"dataSource"`      // 数据源
+    DataSource      *DataSource `json:"dataSource"`      // 数据源配置（用于关联其他表）
    CheckDataSource bool        `json:"checkDataSource"` // 是否检查数据源
    FieldIndexType  string      `json:"fieldIndexType"`  // 索引类型
 }
 ```

+### 4. DataSource 结构体（关联表配置）
+
+```go
+type DataSource struct {
+    DBName       string `json:"dbName"`       // 关联的数据库名称
+    Table        string `json:"table"`        // 关联的表名
+    Label        string `json:"label"`        // 用于显示的字段名（如name、title等）
+    Value        string `json:"value"`        // 用于存储的值字段名（通常是id）
+    Association  int    `json:"association"`  // 关联关系：1=一对一，2=一对多
+    HasDeletedAt bool   `json:"hasDeletedAt"` // 关联表是否有软删除字段
+}
+```
+
 ## 使用示例

 ### 示例1：创建新包和批量创建多个模块
@@ -151,8 +164,15 @@ type AutoCodeField struct {
          "clearable": true,
          "sort": false,
          "primaryKey": false,
-          "dataSource": null,
-          "checkDataSource": false,
+          "dataSource": {
+            "dbName": "gva",
+            "table": "sys_users",
+            "label": "username",
+            "value": "id",
+            "association": 2,
+            "hasDeletedAt": true
+          },
+          "checkDataSource": true,
          "fieldIndexType": ""
        },
        {
@@ -360,6 +380,121 @@ type AutoCodeField struct {
 }
 ```

+### 示例3：模块关联关系配置详解
+
+以下示例展示了如何配置不同类型的关联关系：
+
+```json
+{
+  "packageName": "order",
+  "packageType": "package",
+  "needCreatedPackage": true,
+  "needCreatedModules": true,
+  "packageInfo": {
+    "desc": "订单管理模块",
+    "label": "订单管理",
+    "template": "package",
+    "packageName": "order"
+  },
+  "modulesInfo": [
+    {
+      "package": "order",
+      "tableName": "orders",
+      "structName": "Order",
+      "packageName": "order",
+      "description": "订单",
+      "abbreviation": "order",
+      "humpPackageName": "order",
+      "gvaModel": true,
+      "autoMigrate": true,
+      "autoCreateResource": true,
+      "autoCreateApiToSql": true,
+      "autoCreateMenuToSql": true,
+      "autoCreateBtnAuth": true,
+      "generateWeb": true,
+      "generateServer": true,
+      "fields": [
+        {
+          "fieldName": "UserID",
+          "fieldDesc": "下单用户",
+          "fieldType": "uint",
+          "fieldJson": "userId",
+          "columnName": "user_id",
+          "fieldSearchType": "EQ",
+          "form": true,
+          "table": true,
+          "desc": true,
+          "require": true,
+          "dataSource": {
+            "dbName": "gva",
+            "table": "sys_users",
+            "label": "username",
+            "value": "id",
+            "association": 2,
+            "hasDeletedAt": true
+          },
+          "checkDataSource": true
+        },
+        {
+          "fieldName": "ProductID",
+          "fieldDesc": "商品",
+          "fieldType": "uint",
+          "fieldJson": "productId",
+          "columnName": "product_id",
+          "fieldSearchType": "EQ",
+          "form": true,
+          "table": true,
+          "desc": true,
+          "require": true,
+          "dataSource": {
+            "dbName": "gva",
+            "table": "products",
+            "label": "name",
+            "value": "id",
+            "association": 2,
+            "hasDeletedAt": false
+          },
+          "checkDataSource": true
+        },
+        {
+          "fieldName": "Status",
+          "fieldDesc": "订单状态",
+          "fieldType": "int",
+          "fieldJson": "status",
+          "columnName": "status",
+          "fieldSearchType": "EQ",
+          "form": true,
+          "table": true,
+          "desc": true,
+          "require": true,
+          "dictType": "order_status"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## DataSource 配置说明
+
+### 关联关系类型
+- **association: 1** - 一对一关联（如用户与用户档案）
+- **association: 2** - 一对多关联（如用户与订单）
+
+### 配置要点
+1. **dbName**: 通常为 "gva"（默认数据库）
+2. **table**: 关联表的实际表名
+3. **label**: 用于前端显示的字段（如用户名、商品名称）
+4. **value**: 用于存储关联ID的字段（通常是 "id"）
+5. **hasDeletedAt**: 关联表是否支持软删除
+6. **checkDataSource**: 建议设为true，会验证关联表是否存在
+
+### 常见关联场景
+- 用户关联：`{"table": "sys_users", "label": "username", "value": "id"}`
+- 角色关联：`{"table": "sys_authorities", "label": "authorityName", "value": "authorityId"}`
+- 部门关联：`{"table": "sys_departments", "label": "name", "value": "id"}`
+- 分类关联：`{"table": "categories", "label": "name", "value": "id"}`
+
 ## 重要注意事项

 1. **PackageType**: 只能是 "plugin" 或 "package"
@@ -369,6 +504,7 @@ type AutoCodeField struct {
 5. **搜索类型**: FieldSearchType支持：EQ, NE, GT, GE, LT, LE, LIKE, BETWEEN等
 6. **索引类型**: FieldIndexType支持：index, unique等
 7. **GvaModel**: 设置为true时会自动包含ID、CreatedAt、UpdatedAt、DeletedAt字段
+8. **关联配置**: 使用dataSource时，确保关联表已存在，建议开启checkDataSource验证

 ## 常见错误避免

--- a/server/mcp/gag_usage_example.md
+++ b/server/mcp/gag_usage_example.md
@@ -79,6 +79,38 @@
            "dataSource": {},
            "checkDataSource": false,
            "fieldIndexType": ""
+          },
+          {
+            "fieldName": "AuthorID",
+            "fieldDesc": "作者",
+            "fieldType": "uint",
+            "fieldJson": "authorId",
+            "dataTypeLong": "",
+            "comment": "作者ID",
+            "columnName": "author_id",
+            "fieldSearchType": "EQ",
+            "fieldSearchHide": false,
+            "dictType": "",
+            "form": true,
+            "table": true,
+            "desc": true,
+            "excel": true,
+            "require": true,
+            "defaultValue": "",
+            "errorText": "请选择作者",
+            "clearable": true,
+            "sort": false,
+            "primaryKey": false,
+            "dataSource": {
+              "dbName": "gva",
+              "table": "library_authors",
+              "label": "name",
+              "value": "id",
+              "association": 2,
+              "hasDeletedAt": true
+            },
+            "checkDataSource": true,
+            "fieldIndexType": ""
          }
        ]
      },
--- a/server/mcp/gva_auto_generate.go
+++ b/server/mcp/gva_auto_generate.go
@@ -189,8 +189,8 @@ func (t *AutomationModuleAnalyzer) New() mcp.Tool {
      "clearable": "是否可清空(bool)",
      "sort": "是否排序(bool)",
      "primaryKey": "是否主键(bool)",
-      "dataSource": "数据源(object)",
-      "checkDataSource": "检查数据源(bool)",
+      "dataSource": "数据源配置(object) - 用于配置字段的关联表信息，结构：{\"dbName\":\"数据库名\",\"table\":\"关联表名\",\"label\":\"显示字段\",\"value\":\"值字段\",\"association\":1或2(1=一对一,2=一对多),\"hasDeletedAt\":true/false}。\n\n**获取表名提示：**\n- 可在 server/model 和 plugin/xxx/model 目录下查看对应模块的 TableName() 接口实现获取实际表名\n- 例如：SysUser 的表名为 \"sys_users\"，ExaFileUploadAndDownload 的表名为 \"exa_file_upload_and_downloads\"\n- 插件模块示例：Info 的表名为 \"gva_announcements_info\"\n\n**获取数据库名提示：**\n- 主数据库：通常使用 \"gva\"（默认数据库标识）\n- 多数据库：可在 config.yaml 的 db-list 配置中查看可用数据库的 alias-name 字段\n- 如果用户未提及关联多数据库信息 则使用默认数据库 默认数据库的情况下 dbName此处填写为空",
+      "checkDataSource": "是否检查数据源(bool) - 启用后会验证关联表的存在性",
      "fieldIndexType": "索引类型(string)"
    }]
  }, {
@@ -214,7 +214,16 @@ func (t *AutomationModuleAnalyzer) New() mcp.Tool {
 9. 智能字典创建功能：当字段使用字典类型(DictType)时，系统会：
   - 自动检查字典是否存在，如果不存在则创建字典
   - 根据字典类型和字段描述智能生成默认选项，支持状态、性别、类型、等级、优先级、审批、角色、布尔值、订单、颜色、尺寸等常见场景
-   - 为无法识别的字典类型提供通用默认选项`),
+   - 为无法识别的字典类型提供通用默认选项
+10. **模块关联配置**：当需要配置模块间的关联关系时，使用dataSource字段：
+   - **dbName**: 关联的数据库名称
+   - **table**: 关联的表名
+   - **label**: 用于显示的字段名（如name、title等）
+   - **value**: 用于存储的值字段名（通常是id）
+   - **association**: 关联关系类型（1=一对一关联，2=一对多关联）
+   - **hasDeletedAt**: 关联表是否有软删除字段
+   - **checkDataSource**: 设为true时会验证关联表的存在性
+   - 示例：{"dbName":"gva","table":"sys_users","label":"username","value":"id","association":2,"hasDeletedAt":true}`),
 		mcp.WithString("action",
 			mcp.Required(),
 			mcp.Description("执行操作：'analyze' 分析现有模块信息，'confirm' 请求用户确认创建，'execute' 执行创建操作（支持批量创建多个模块）"),