添加数据种子元数据文档，支持隐式和显式命名格式

Author: hotlong

docs/spec/data.md

@@ -0,0 +1,50 @@
+# Data Seeding Metadata
+
+Data source files allow you to seed the database with initial data. This is useful for lookup tables, configuration, or demo content.
+
+## 1. Overview
+
+- **Implicit Naming**: Name the file `<object_name>.data.yml` to automatically map it to an object.
+- **Explicit Naming**: Use the `object` and `records` properties in the YAML content.
+- **Auto-deduplication**: Currently, data seeding attempts to create records. Duplicate key errors are typically ignored (depending on driver implementation), allowing for basic idempotency.
+
+## 2. File Format
+
+### Option A: Implicit (Recommended)
+
+File Name: `status.data.yml`
+Target Object: `status`
+
+```yaml
+- code: "draft"
+  label: "Draft"
+  is_active: true
+
+- code: "published"
+  label: "Published"
+  is_active: true
+```
+
+### Option B: Explicit
+
+File Name: `initial_setup.data.yml` (can be anything)
+
+```yaml
+object: status
+records:
+  - code: "draft"
+    label: "Draft"
+  
+  - code: "published"
+    label: "Published"
+```
+
+### Option C: Multiple Objects (Bundled)
+
+Not currently supported in a single file. Please use separate files.
+
+## 3. Best Practices
+
+1.  **Use Immutable IDs**: If possible, provide explicit IDs (`_id`) to ensure consistent referencing across environments.
+2.  **Versioning**: Include a metadata field if you need to track data versions.
+3.  **Order Matters**: If you have relationships, ensure the parent data is loaded before child data (ObjectQL loads data files in alphabetical order).

docs/spec/index.md

@@ -86,6 +86,9 @@ src/
   reports/            # Analytics
     *.report.yml       # Report definitions
     *.dashboard.yml    # Dashboard configurations
+
+  data/               # Initial Seeding
+    *.data.yml         # Seed data
 
   navigation/         # App structure
     *.app.yml         # Application definitions

packages/core/src/app.ts

@@ -321,13 +321,18 @@ export class ObjectQL implements IObjectQL {
 
         for (const entry of dataEntries) {
             // Expected format:
-            // object: User
-            // records:
-            //   - name: Admin
-            //     email: admin@example.com
+            // 1. { object: 'User', records: [...] }
+            // 2. [ record1, record2 ] (with name property added by loader inferred from filename)
 
-            const objectName = entry.object;
-            const records = entry.records;
+            let objectName = entry.object;
+            let records = entry.records;
+
+            if (Array.isArray(entry)) {
+                records = entry;
+                if (!objectName && (entry as any).name) {
+                    objectName = (entry as any).name;
+                }
+            }
 
             if (!objectName || !records || !Array.isArray(records)) {
                 console.warn(`Skipping invalid data entry:`, entry);

packages/core/src/loader.ts

@@ -22,7 +22,8 @@ export class ObjectLoader {
                     if (!doc) return;
 
                     if (doc.name && doc.fields) {
-                        registerObject(ctx.registry, doc, ctx.file, ctx.packageName || ctx.registry.getEntry('package-map', ctx.file)?.package);
+                        const packageEntry = ctx.registry.getEntry('package-map', ctx.file);
+                        registerObject(ctx.registry, doc, ctx.file, ctx.packageName || (packageEntry && packageEntry.package));
                     } else {
                         for (const [key, value] of Object.entries(doc)) {
                             if (typeof value === 'object' && (value as any).fields) {
@@ -116,20 +117,14 @@ export class ObjectLoader {
 
                         // Use 'name' from doc, or filename base (without extension)
                         let id = doc.name;
-                        if (!id && type !== 'data') {
+                        if (!id) {
                             const basename = path.basename(ctx.file); 
                             // e.g. "my-view.view.yml" -> "my-view"
                             // Regex: remove .type.yml or .type.yaml
                             const re = new RegExp(`\\.${type}\\.(yml|yaml)$`);
                             id = basename.replace(re, '');
                         }
 
-                        // Data entries might not need a name, but for registry we need an ID.
-                        // For data, we can use filename if not present.
-                         if (!id && type === 'data') {
-                            id = path.basename(ctx.file);
-                         }
-
                         // Ensure name is in the doc for consistency
                         if (!doc.name) doc.name = id;
 

packages/driver-knex/src/index.ts

@@ -92,8 +92,21 @@ export class KnexDriver implements Driver {
         }
 
         if (query.sort && Array.isArray(query.sort)) {
-            for (const [field, dir] of query.sort) {
-                builder.orderBy(this.mapSortField(field), dir);
+            for (const item of query.sort) {
+                let field: string | undefined;
+                let dir: string | undefined;
+
+                if (Array.isArray(item)) {
+                     [field, dir] = item;
+                } else if (typeof item === 'object' && item !== null) {
+                    // Support object format { field: 'name', order: 'asc' }
+                     field = (item as any).field;
+                     dir = (item as any).order || (item as any).direction || (item as any).dir;
+                }
+
+                if (field) {
+                    builder.orderBy(this.mapSortField(field), dir);
+                }
             }
         }
 

packages/types/src/registry.ts

@@ -18,7 +18,10 @@ export class MetadataRegistry {
     }
 
     unregister(type: string, id: string) {
-        this.store.get(type)?.delete(id);
+        const map = this.store.get(type);
+        if (map) {
+            map.delete(id);
+        }
     }
 
     unregisterPackage(packageName: string) {
@@ -39,7 +42,10 @@ export class MetadataRegistry {
     }
 
     get<T = any>(type: string, id: string): T | undefined {
-        return this.store.get(type)?.get(id)?.content as T;
+        const map = this.store.get(type);
+        if (!map) return undefined;
+        const entry = map.get(id);
+        return entry ? entry.content as T : undefined;
     }
 
     list<T = any>(type: string): T[] {
@@ -49,6 +55,7 @@ export class MetadataRegistry {
     }
 
     getEntry(type: string, id: string): Metadata | undefined {
-        return this.store.get(type)?.get(id);
+        const map = this.store.get(type);
+        return map ? map.get(id) : undefined;
     }
 }

tsconfig.base.json

@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "target": "ES2020",
+    "target": "ES2019",
     "module": "commonjs",
     "declaration": true,
     "strict": true,