feat: 更新文档和 JSON Schema，增强数据源和驱动程序定义，移除过时字段，添加新属性

hotlong · hotlong · commit 9804e085d507 · 2026-01-20T04:31:14.000+08:00
diff --git a/content/docs/references/data/core/Object.mdx b/content/docs/references/data/core/Object.mdx
@@ -12,8 +12,8 @@ description: Object Schema Reference
 | **pluralLabel** | `string` | optional | Plural Label (e.g. "Accounts") |
 | **description** | `string` | optional | Internal description |
 | **icon** | `string` | optional | Lucide icon name |
-| **datasource** | `string` | optional | Datasource name |
-| **tableName** | `string` | optional | Physical DB table override |
+| **datasource** | `string` | optional | Target Datasource ID (e.g. "postgres", "salesforce"). references sys_datasource. |
+| **tableName** | `string` | optional | Physical table/collection name in the target datasource |
 | **isSystem** | `boolean` | optional | Is system object (protected) |
 | **fields** | `Record<string, object>` | ✅ | Map of field definitions |
 | **indexes** | `object[]` | optional | Database indexes definition |
diff --git a/content/docs/references/misc/config/MenuItem.mdx b/content/docs/references/misc/config/MenuItem.mdx
@@ -0,0 +1,12 @@
+---
+title: MenuItem
+description: MenuItem Schema Reference
+---
+
+## Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **label** | `string` | ✅ | Display label for the menu item |
+| **path** | `string` | ✅ | Navigation path (route) for the menu item |
+| **icon** | `string` | optional | Optional icon identifier for the menu item |
diff --git a/content/docs/references/system/DriverDefinition.mdx b/content/docs/references/system/DriverDefinition.mdx
@@ -0,0 +1,15 @@
+---
+title: DriverDefinition
+description: DriverDefinition Schema Reference
+---
+
+## Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **id** | `string` | ✅ | Unique driver identifier (e.g. "postgres") |
+| **label** | `string` | ✅ | Display label (e.g. "PostgreSQL") |
+| **description** | `string` | optional |  |
+| **icon** | `string` | optional |  |
+| **configSchema** | `Record<string, any>` | ✅ | JSON Schema for connection configuration |
+| **capabilities** | `object` | optional |  |
diff --git a/content/docs/references/system/config/Manifest.mdx b/content/docs/references/system/config/Manifest.mdx
@@ -14,5 +14,6 @@ description: Manifest Schema Reference
 | **description** | `string` | optional | Package description |
 | **permissions** | `string[]` | optional | Array of required permission strings |
 | **objects** | `string[]` | optional | Glob patterns for ObjectQL schemas files |
-| **contributes** | `object` | optional | Platform contributions (e.g. kinds) |
+| **datasources** | `string[]` | optional | Glob patterns for Datasource definitions |
+| **contributes** | `object` | optional | Platform contributions |
 | **extensions** | `Record<string, any>` | optional | Extension points and contributions |
diff --git a/content/docs/references/system/integration/Datasource.mdx b/content/docs/references/system/integration/Datasource.mdx
@@ -9,7 +9,7 @@ description: Datasource Schema Reference
 | :--- | :--- | :--- | :--- |
 | **name** | `string` | ✅ | Unique datasource identifier |
 | **label** | `string` | optional | Display label |
-| **driver** | `Enum<'postgres' \| 'mysql' \| 'sqlserver' \| 'oracle' \| 'sqlite' \| 'mongo' \| 'redis' \| 'excel' \| 'csv' \| 'airtable' \| 'rest_api' \| 'graphql' \| 'odata' \| 'salesforce' \| 'sap' \| 'workday'>` | ✅ | Underlying driver type |
+| **driver** | `string` | ✅ | Underlying driver type |
 | **config** | `Record<string, any>` | ✅ | Driver specific configuration |
 | **capabilities** | `object` | optional | Capability overrides |
 | **description** | `string` | optional | Internal description |
diff --git a/content/docs/references/system/integration/DriverType.mdx b/content/docs/references/system/integration/DriverType.mdx
@@ -1,23 +1,7 @@
 ---
 title: DriverType
-description: DriverType Schema Reference
+description: Underlying driver identifier
 ---
 
-## Allowed Values
+Underlying driver identifier
 
-* `postgres`
-* `mysql`
-* `sqlserver`
-* `oracle`
-* `sqlite`
-* `mongo`
-* `redis`
-* `excel`
-* `csv`
-* `airtable`
-* `rest_api`
-* `graphql`
-* `odata`
-* `salesforce`
-* `sap`
-* `workday`
diff --git a/content/docs/references/ui/app/App.mdx b/content/docs/references/ui/app/App.mdx
@@ -16,7 +16,6 @@ description: App Schema Reference
 | **active** | `boolean` | optional | Whether the app is enabled |
 | **isDefault** | `boolean` | optional | Is default app |
 | **navigation** | `object \| object \| object \| object \| object[]` | optional | Structured navigation menu tree |
-| **menus** | `any[]` | optional | Deprecated: Use navigation instead |
 | **homePageId** | `string` | optional | ID of the navigation item to serve as landing page |
 | **requiredPermissions** | `string[]` | optional | Permissions required to access this app |
 | **objects** | `any[]` | optional | Objects belonging to this app |
diff --git a/packages/spec/json-schema/App.json b/packages/spec/json-schema/App.json
@@ -266,10 +266,6 @@
           },
           "description": "Structured navigation menu tree"
         },
-        "menus": {
-          "type": "array",
-          "description": "Deprecated: Use navigation instead"
-        },
         "homePageId": {
           "type": "string",
           "description": "ID of the navigation item to serve as landing page"
diff --git a/packages/spec/json-schema/Datasource.json b/packages/spec/json-schema/Datasource.json
@@ -15,24 +15,6 @@
         },
         "driver": {
           "type": "string",
-          "enum": [
-            "postgres",
-            "mysql",
-            "sqlserver",
-            "oracle",
-            "sqlite",
-            "mongo",
-            "redis",
-            "excel",
-            "csv",
-            "airtable",
-            "rest_api",
-            "graphql",
-            "odata",
-            "salesforce",
-            "sap",
-            "workday"
-          ],
           "description": "Underlying driver type"
         },
         "config": {
diff --git a/packages/spec/json-schema/DriverDefinition.json b/packages/spec/json-schema/DriverDefinition.json
@@ -0,0 +1,66 @@
+{
+  "$ref": "#/definitions/DriverDefinition",
+  "definitions": {
+    "DriverDefinition": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique driver identifier (e.g. \"postgres\")"
+        },
+        "label": {
+          "type": "string",
+          "description": "Display label (e.g. \"PostgreSQL\")"
+        },
+        "description": {
+          "type": "string"
+        },
+        "icon": {
+          "type": "string"
+        },
+        "configSchema": {
+          "type": "object",
+          "additionalProperties": {},
+          "description": "JSON Schema for connection configuration"
+        },
+        "capabilities": {
+          "type": "object",
+          "properties": {
+            "joins": {
+              "type": "boolean",
+              "default": false
+            },
+            "transactions": {
+              "type": "boolean",
+              "default": false
+            },
+            "fullTextSearch": {
+              "type": "boolean",
+              "default": false
+            },
+            "aggregation": {
+              "type": "boolean",
+              "default": false
+            },
+            "dynamicSchema": {
+              "type": "boolean",
+              "default": false
+            },
+            "readOnly": {
+              "type": "boolean",
+              "default": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "id",
+        "label",
+        "configSchema"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}
diff --git a/packages/spec/json-schema/DriverType.json b/packages/spec/json-schema/DriverType.json
@@ -3,24 +3,7 @@
   "definitions": {
     "DriverType": {
       "type": "string",
-      "enum": [
-        "postgres",
-        "mysql",
-        "sqlserver",
-        "oracle",
-        "sqlite",
-        "mongo",
-        "redis",
-        "excel",
-        "csv",
-        "airtable",
-        "rest_api",
-        "graphql",
-        "odata",
-        "salesforce",
-        "sap",
-        "workday"
-      ]
+      "description": "Underlying driver identifier"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"
diff --git a/packages/spec/json-schema/Manifest.json b/packages/spec/json-schema/Manifest.json
@@ -38,38 +38,50 @@
           },
           "description": "Array of required permission strings"
         },
-        "menus": {
+        "objects": {
           "type": "array",
           "items": {
-            "type": "object",
-            "properties": {
-              "label": {
-                "type": "string",
-                "description": "Display label for the menu item"
-              },
-              "path": {
-                "type": "string",
-                "description": "Navigation path (route) for the menu item"
-              },
-              "icon": {
-                "type": "string",
-                "description": "Optional icon identifier for the menu item"
-              }
-            },
-            "required": [
-              "label",
-              "path"
-            ],
-            "additionalProperties": false
+            "type": "string"
           },
-          "description": "Navigation menu structure"
+          "description": "Glob patterns for ObjectQL schemas files"
         },
-        "objects": {
+        "datasources": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Glob patterns for ObjectQL schemas files"
+          "description": "Glob patterns for Datasource definitions"
+        },
+        "contributes": {
+          "type": "object",
+          "properties": {
+            "kinds": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "The generic identifier of the kind (e.g., \"sys.bi.report\")"
+                  },
+                  "globs": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "File patterns to watch (e.g., [\"**/*.report.ts\"])"
+                  }
+                },
+                "required": [
+                  "id",
+                  "globs"
+                ],
+                "additionalProperties": false
+              }
+            }
+          },
+          "additionalProperties": false,
+          "description": "Platform contributions"
         },
         "extensions": {
           "type": "object",
diff --git a/packages/spec/json-schema/Object.json b/packages/spec/json-schema/Object.json
@@ -28,11 +28,11 @@
         "datasource": {
           "type": "string",
           "default": "default",
-          "description": "Datasource name"
+          "description": "Target Datasource ID (e.g. \"postgres\", \"salesforce\"). references sys_datasource."
         },
         "tableName": {
           "type": "string",
-          "description": "Physical DB table override"
+          "description": "Physical table/collection name in the target datasource"
         },
         "isSystem": {
           "type": "boolean",
diff --git a/packages/spec/src/data/object.zod.ts b/packages/spec/src/data/object.zod.ts
@@ -45,9 +45,12 @@ const ObjectSchemaBase = z.object({
   description: z.string().optional().describe('Internal description'),
   icon: z.string().optional().describe('Lucide icon name'),
 
-  /** Storage Config */
-  datasource: z.string().default('default').describe('Datasource name'),
-  tableName: z.string().optional().describe('Physical DB table override'),
+  /** 
+   * Storage / Virtualization Config 
+   * Defines where the data actually lives.
+   */
+  datasource: z.string().default('default').describe('Target Datasource ID (e.g. "postgres", "salesforce"). references sys_datasource.'),
+  tableName: z.string().optional().describe('Physical table/collection name in the target datasource'),
   isSystem: z.boolean().default(false).describe('Is system object (protected)'),
   
   /** Fields Definition */
diff --git a/packages/spec/src/system/datasource.zod.ts b/packages/spec/src/system/datasource.zod.ts
@@ -1,16 +1,48 @@
 import { z } from 'zod';
 
 /**
- * Driver Type Enum
- * Defines the underlying technology of the datasource.
+ * Driver Type Enum (Built-in)
+ * Standard drivers supported by the core platform.
+ * Plugins can register additional drivers using different identifiers.
  */
-export const DriverType = z.enum([
+export const BuiltInDrivers = [
   'postgres', 'mysql', 'sqlserver', 'oracle', 'sqlite', // SQL
   'mongo', 'redis', // NoSQL
   'excel', 'csv', 'airtable', // Spreadsheet / Low-code
   'rest_api', 'graphql', 'odata', // Web Services
   'salesforce', 'sap', 'workday' // Enterprise SaaS
-]);
+] as const;
+
+/**
+ * Driver Identifier
+ * Can be a built-in driver or a plugin-contributed driver (e.g., "com.vendor.snowflake").
+ */
+export const DriverType = z.string().describe('Underlying driver identifier');
+
+/**
+ * Driver Definition Schema
+ * Metadata describing a Database Driver.
+ * Plugins use this to register new connectivity options.
+ */
+export const DriverDefinitionSchema = z.object({
+  id: z.string().describe('Unique driver identifier (e.g. "postgres")'),
+  label: z.string().describe('Display label (e.g. "PostgreSQL")'),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+  
+  /**
+   * Configuration Schema (JSON Schema)
+   * Describes the structure of the `config` object needed for this driver.
+   * Used by the UI to generate the connection form.
+   */
+  configSchema: z.record(z.any()).describe('JSON Schema for connection configuration'),
+  
+  /**
+   * Default Capabilities
+   * What this driver supports out-of-the-box.
+   */
+  capabilities: z.lazy(() => DatasourceCapabilities).optional(),
+});
 
 /**
  * Datasource Capabilities Schema
diff --git a/packages/spec/src/system/manifest.zod.ts b/packages/spec/src/system/manifest.zod.ts
@@ -49,6 +49,11 @@ export const ManifestSchema = z.object({
    */
   objects: z.array(z.string()).optional().describe('Glob patterns for ObjectQL schemas files'),
   
+  /**
+   * Defines system level DataSources.
+   */
+  datasources: z.array(z.string()).optional().describe('Glob patterns for Datasource definitions'),
+
   /**
    * Contribution Points (VS Code Style).
    * formalized way to extend the platform capabilities.
