Document and enforce driver ID compatibility requirements

Updated documentation and driver interface schema to clarify that all drivers must return an 'id' field as a string and must not expose implementation-specific IDs like '_id'. Added comments and examples in both English and Chinese guides, and updated JSDoc in the driver interface schema to enforce this requirement.

Author: hotlong

content/docs/guides/custom-driver.cn.mdx

@@ -18,6 +18,17 @@ description: 学习如何使用驱动接口为 ObjectStack 实现自定义数据
 
 所有驱动程序必须实现规范中定义的 `DriverInterface`。
 
+### 重要：ID 兼容性规范
+
+ObjectStack 协议强制要求所有记录必须包含一个类型为 `string` 的 `id` 字段。
+底层数据库可能使用不同的惯例（例如 MongoDB 使用 `_id`，SQL 使用 `int` 类型的 ID）。
+**驱动程序负责将这些转换为标准的字符串 `id`。**
+
+- **输入**: 当 `update` 或 `delete` 方法接收 `id` 参数时，将其视为唯一主键。
+- **输出**: 当 `find`、`create` 或 `update` 返回记录时，确保：
+  - 必须包含 `id` 字段（字符串）。
+  - 应移除或映射实现特定的 ID（如 `_id`）。
+
 ```typescript
 import { DriverInterface, DriverOptions } from '@objectstack/spec';
 import { QueryAST, QueryResult } from '@objectstack/objectql';
@@ -49,8 +60,14 @@ export class MyCustomDriver implements DriverInterface {
 async find(object: string, query: QueryAST, options?: DriverOptions): Promise<QueryResult> {
     // 1. 将 QueryAST 转换为数据库的查询语言（例如 SQL）
     // 2. 执行查询
-    // 3. 返回对象数组结果
-    return []; 
+    const results = await db.query(...);
+
+    // 3. 规范化 ID (MongoDB 风格示例)
+    return results.map(doc => ({
+        ...doc,
+        id: doc._id.toString(), // 映射 _id -> id
+        _id: undefined          // 隐藏实现细节
+    })); 
 }
 ```
 

content/docs/guides/custom-driver.mdx

@@ -18,6 +18,17 @@ In this guide, we will walk through creating a simple **In-Memory Driver** as an
 
 All drivers must implement the `DriverInterface` defined in the specification.
 
+### Important: ID Compatibility
+
+The ObjectStack protocol mandates that all records MUST have an `id` field of type `string`. 
+Underlying databases might use different conventions (e.g., `_id` in MongoDB, `int` IDs in SQL).
+**The Driver is responsible for mapping these to the standard string `id`.**
+
+- **Input:** When receiving an `id` in `update` or `delete`, treat it as the primary key.
+- **Output:** When returning records from `find`, `create`, or `update`, ensure:
+  - There is an `id` field (string).
+  - Implementation-specific IDs (like `_id`) should be removed or mapped.
+
 ```typescript
 import { DriverInterface, DriverOptions } from '@objectstack/spec';
 import { QueryAST, QueryResult } from '@objectstack/objectql';
@@ -49,8 +60,14 @@ The `find` method receives a `QueryAST` object, which contains structured query
 async find(object: string, query: QueryAST, options?: DriverOptions): Promise<QueryResult> {
     // 1. Convert QueryAST to your database's query language (e.g., SQL)
     // 2. Execute query
-    // 3. Return results as an array of objects
-    return []; 
+    const results = await db.query(...);
+
+    // 3. Normalize ID (Example for Mongo-like DB)
+    return results.map(doc => ({
+        ...doc,
+        id: doc._id.toString(), // Map _id -> id
+        _id: undefined          // Hide implementation details
+    })); 
 }
 ```
 

packages/driver-memory/src/memory-driver.ts

@@ -87,6 +87,7 @@ export class InMemoryDriver implements DriverInterface {
   async create(object: string, data: Record<string, any>, options?: DriverOptions) {
     const table = this.getTable(object);
 
+    // COMPATIBILITY: Driver must return 'id' as string
     const newRecord = {
       id: this.generateId(),
       ...data,

packages/spec/src/system/driver.zod.ts

@@ -153,6 +153,8 @@ export const DriverInterfaceSchema = z.object({
    *   sort: [{ field: 'created_at', order: 'desc' }],
    *   top: 10
    * });
+   * @returns Array of records.
+   *          MUST return `id` as string. MUST NOT return implementation details like `_id`.
    */
   find: z.function()
     .args(z.string(), QuerySchema, DriverOptionsSchema.optional())
@@ -166,6 +168,8 @@ export const DriverInterfaceSchema = z.object({
    * @param object - The name of the object.
    * @param query - QueryAST.
    * @param options - Driver options.
+   * @returns The record or null.
+   *          MUST return `id` as string. MUST NOT return implementation details like `_id`.
    */
   findOne: z.function()
     .args(z.string(), QuerySchema, DriverOptionsSchema.optional())
@@ -179,6 +183,7 @@ export const DriverInterfaceSchema = z.object({
    * @param data - Key-value map of field data.
    * @param options - Driver options.
    * @returns The created record, including server-generated fields (id, created_at, etc.).
+   *          MUST return `id` as string. MUST NOT return implementation details like `_id`.
    */
   create: z.function()
     .args(z.string(), z.record(z.any()), DriverOptionsSchema.optional())
@@ -193,6 +198,7 @@ export const DriverInterfaceSchema = z.object({
    * @param data - The fields to update.
    * @param options - Driver options.
    * @returns The updated record.
+   *          MUST return `id` as string. MUST NOT return implementation details like `_id`.
    */
   update: z.function()
     .args(z.string(), z.string().or(z.number()), z.record(z.any()), DriverOptionsSchema.optional())