@lovrabet/sdk 1.3.6 → 1.3.8

package/dist/src/client/index.d.ts

@@ -9,6 +9,55 @@ import { LovrabetClient } from './client';
  * 3. 配置优先级 - 明确的配置合并和覆盖规则
  * 4. 错误优先 - 在客户端创建阶段就发现配置问题
  *
+ * 四种调用方式：
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * 方式 1：字符串 — 引用预注册的配置名称
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *   适用场景：已在启动时通过 registerModels() 注册过配置，直接按名引用。
+ *   示例：
+ *     registerModels({ appCode: 'my-app', models: [...] }, 'prod');
+ *     const client = createClient('prod');
+ *   省略参数时等价于 createClient('default')。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * 方式 2：ModelsConfig — 纯模型配置对象（仅 appCode + models）
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *   适用场景：一次性创建客户端，无需预注册；传入最少字段即可。
+ *   判断依据：对象同时包含 appCode 和 models，且不包含 env 等 ClientConfig 字段。
+ *   示例：
+ *     const client = createClient({
+ *       appCode: 'my-app',
+ *       models: { chat: { modelId: 'gpt-4o' } },
+ *     });
+ *   额外字段（如 runtimeDomain、token）会被透传到最终配置。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * 方式 3：ClientConfig & { apiConfigName } — 引用注册配置 + 覆盖选项
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *   适用场景：想复用预注册的模型定义，但需要自定义环境、认证等。
+ *   合并策略：注册配置提供 appCode + models；其余字段由传入对象覆盖。
+ *   示例：
+ *     registerModels({ appCode: 'my-app', models: [...] }, 'prod');
+ *     const client = createClient({
+ *       apiConfigName: 'prod',   // 从注册表取模型
+ *       env: 'staging',          // 覆盖为 staging 环境
+ *       token: 'xxx',            // 附加认证信息
+ *     });
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * 方式 4：ClientConfig — 完整配置对象
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *   适用场景：不依赖任何预注册配置，显式传入全部所需字段。
+ *   示例：
+ *     const client = createClient({
+ *       appCode: 'my-app',
+ *       env: 'production',
+ *       models: { chat: { modelId: 'gpt-4o' } },
+ *       token: 'xxx',
+ *     });
+ *   env 缺省时自动填充 DEFAULTS.ENV；models 缺省时为 {}。
+ *
  * @param config - 客户端配置，支持以下类型：
  *   - string: 注册的配置名称（如 'default', 'prod'）
  *   - ModelsConfig: 纯模型配置对象

package/dist/src/http/http-client.d.ts

@@ -6,7 +6,9 @@ export declare class HttpClient {
     constructor(config: ClientConfig, authManager: AuthManager);
     /**
      * 获取 API 基础地址
-     * 优先级：serverUrl > window.__GLOBAL__.deploymentConfig.RUNTIME_API_DOMAIN > getApiEndpoint(env)
+     * 优先级：runtimeDomain > window.__GLOBAL__.deploymentConfig.RUNTIME_API_DOMAIN > getApiEndpoint(env)
+     *
+     * 注：serverUrl 为 runtimeDomain 的旧名称，向下兼容保留；两者均设置时以 runtimeDomain 优先。
      */
     getBaseUrl(): string;
     private getFullUrl;

package/dist/src/models/abstract-base-model.d.ts

@@ -37,31 +37,42 @@ export declare abstract class AbstractBaseModel implements BaseModelMethods {
     }): Promise<T>;
     create<T = any>(data: Record<string, any>): Promise<T>;
     /**
-     * 更新记录，支持单条和批量
-     * @param id - 单个 ID（string/number）或 ID 数组（最多 1000 条）
-     * @param data - 更新数据
-     * @returns 更新结果
+     * 更新记录，支持单条和批量。
      *
-     * @example
-     * // 单条更新
-     * await model.update(1001, { name: '张三' });
+     * **推荐写法（对象合并）**：将 id 与更新字段合并为一个对象传入：
+     * ```typescript
+     * await model.update({ id: 1001, name: '张三' });
+     * await model.update({ id: [1001, 1002], status: 'active' });
+     * ```
      *
-     * // 批量更新
+     * **兼容写法（id 分离）**：
+     * ```typescript
+     * await model.update(1001, { name: '张三' });
      * await model.update([1001, 1002, 1003], { status: 'active' });
+     * ```
      */
-    update<T = any>(id: string | number | (string | number)[], data: Record<string, any>): Promise<T>;
+    update<T = any>(idOrData: string | number | (string | number)[] | {
+        id: string | number | (string | number)[];
+        [key: string]: any;
+    }, data?: Record<string, any>): Promise<T>;
     /**
-     * 删除记录，支持单条和批量
-     * @param id - 单个 ID（string/number）或 ID 数组（最多 1000 条）
+     * 删除记录，支持单条和批量。
      *
-     * @example
-     * // 单条删除
-     * await model.delete(1001);
+     * **推荐写法（对象传入）**：
+     * ```typescript
+     * await model.delete({ id: 1001 });
+     * await model.delete({ id: [1001, 1002, 1003] });
+     * ```
      *
-     * // 批量删除
+     * **兼容写法（直接传 id）**：
+     * ```typescript
+     * await model.delete(1001);
      * await model.delete([1001, 1002, 1003]);
+     * ```
      */
-    delete(id: string | number | (string | number)[]): Promise<void>;
+    delete(idOrParams: string | number | (string | number)[] | {
+        id: string | number | (string | number)[];
+    }): Promise<void>;
     getSelectOptions(params: SelectOptionsParams): Promise<SelectOption[]>;
     excelExport<T = any>(params?: ListParams): Promise<T>;
     aggregate<T = any>(params?: AggregateParams): Promise<ListResponse<T>>;

package/dist/src/types/index.d.ts

@@ -386,7 +386,21 @@ export interface ModelsConfig {
 export interface ClientConfig {
     /** 应用代码，用于标识不同的应用 */
     appCode?: string;
-    /** 自定义服务器 URL，可选 */
+    /**
+     * 运行态 API 域名，优先级最高，可覆盖环境默认端点与部署配置注入的地址。
+     * 适用于私有化部署或本地联调。
+     *
+     * 与 rabetbase-cli/.rabetbase.json 中的 `runtimeDomain` 字段命名对齐。
+     *
+     * @example 'https://runtime.my-company.com'
+     */
+    runtimeDomain?: string;
+    /**
+     * @deprecated 请使用 `runtimeDomain` 替代。
+     * 为向下兼容而保留，优先级低于 `runtimeDomain`；
+     * 两者均设置时以 `runtimeDomain` 为准。
+     * 下一个大版本将移除此字段。
+     */
     serverUrl?: string;
     /** 运行环境，默认为 'production'（向下兼容 'online'） */
     env?: Environment;
@@ -511,33 +525,43 @@ export interface BaseModelMethods {
     /**
      * 更新数据，支持单条和批量
      * @template T 返回数据的类型
-     * @param id 单个 ID（string/number）或 ID 数组（最多 1000 条）
-     * @param data 要更新的数据对象
-     * @returns 返回更新后的数据
-     * @example
+     *
+     * **推荐写法（对象合并）**：将 id 与更新字段合并为一个对象传入：
      * ```typescript
-     * // 单条更新
-     * await model.update(1001, { name: '张三' });
+     * await model.update({ id: 1001, name: '张三' });
+     * await model.update({ id: [1001, 1002], status: 'active' });
+     * ```
      *
-     * // 批量更新
-     * await model.update([1001, 1002, 1003], { status: 'active' });
+     * **兼容写法（id 分离）**：
+     * ```typescript
+     * await model.update(1001, { name: '张三' });
+     * await model.update([1001, 1002], { status: 'active' });
      * ```
      */
+    update<T = any>(dataWithId: {
+        id: string | number | (string | number)[];
+        [key: string]: any;
+    }): Promise<T>;
     update<T = any>(id: string | number | (string | number)[], data: Record<string, any>): Promise<T>;
     /**
      * 删除数据，支持单条和批量
-     * @param id 单个 ID（string/number）或 ID 数组（最多 1000 条）
-     * @returns Promise<void>
      * @throws Error OpenAPI 模式暂不支持此操作，仅 WebAPI 模式可用
-     * @example
+     *
+     * **推荐写法（对象传入）**：
      * ```typescript
-     * // 单条删除
-     * await model.delete(1001);
+     * await model.delete({ id: 1001 });
+     * await model.delete({ id: [1001, 1002, 1003] });
+     * ```
      *
-     * // 批量删除
+     * **兼容写法（直接传 id）**：
+     * ```typescript
+     * await model.delete(1001);
      * await model.delete([1001, 1002, 1003]);
      * ```
      */
+    delete(params: {
+        id: string | number | (string | number)[];
+    }): Promise<void>;
     delete(id: string | number | (string | number)[]): Promise<void>;
     /**
      * 获取下拉选项

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrabet/sdk",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "license": "SEE LICENSE IN LICENSE",
   "main": "dist/index.js",
   "module": "dist/index.js",