@lovrabet/sdk 1.1.26 → 1.2.0-beta.2

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

@@ -74,6 +74,24 @@ export declare class LovrabetClient implements ILovrabetClient {
      * 2. 支持动态获取配置中的所有模型
      */
     getModelList(): string[];
+    /**
+     * 获取所有模型的详细信息，包含别名和名称
+     * 用于 UI 展示人类友好的模型列表
+     *
+     * @returns 模型详情数组，每个元素包含：
+     *   - value: 用于访问的 dataset_xxx 格式
+     *   - label: 人类友好的显示名称，格式为 "alias[name]" 或 "dataset_xxx"
+     *   - alias: 别名（如果有）
+     *   - name: 模型名称（如果有）
+     *   - datasetCode: 原始 datasetCode
+     */
+    getModelListDetails(): Array<{
+        value: string;
+        label: string;
+        alias?: string;
+        name?: string;
+        datasetCode: string;
+    }>;
     /**
      * 根据索引或名称获取模型实例
      * 为什么提供这个方法：

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

@@ -5,13 +5,22 @@ import type { HttpClient } from '../http/http-client';
  * 定义所有模型的通用接口和基础实现
  */
 export declare abstract class AbstractBaseModel implements BaseModelMethods {
+    /** 数据集代码（用于 API 调用） */
+    protected datasetCode: string;
+    /** @deprecated 使用 datasetCode 代替 */
     protected modelName: string;
     protected httpClient: HttpClient;
     protected config: ModelConfig;
     protected appCode: string;
     protected globalConfig: ClientConfig;
-    constructor(modelName: string, httpClient: HttpClient, globalConfig: ClientConfig);
-    private resolveModelConfig;
+    /**
+     * 构造函数
+     * @param datasetCode 数据集代码
+     * @param httpClient HTTP 客户端
+     * @param globalConfig 全局配置
+     * @param modelConfig 模型配置（直接传入，不再从 globalConfig 中查找）
+     */
+    constructor(datasetCode: string, httpClient: HttpClient, globalConfig: ClientConfig, modelConfig: ModelConfig);
     protected abstract getApiPath(method: string): string;
     protected abstract buildRequestBody(method: string, data: any, sortList?: SortList): any;
     getList<T = any>(params?: ListParams, sortList?: SortList): Promise<ListResponse<T>>;

package/dist/src/models/model-factory.d.ts

@@ -1,4 +1,4 @@
-import type { BaseModelMethods, ClientConfig } from '../types';
+import type { BaseModelMethods, ClientConfig, ModelConfig } from '../types';
 import type { HttpClient } from '../http/http-client';
 /**
  * 模型工厂类
@@ -7,8 +7,12 @@ import type { HttpClient } from '../http/http-client';
 export declare class ModelFactory {
     /**
      * 创建模型实例
+     * @param datasetCode 数据集代码（作为模型标识）
+     * @param httpClient HTTP 客户端
+     * @param globalConfig 全局配置
+     * @param modelConfig 模型配置（直接传入，不再从 globalConfig 中查找）
      */
-    static createModel(modelName: string, httpClient: HttpClient, globalConfig: ClientConfig): BaseModelMethods;
+    static createModel(datasetCode: string, httpClient: HttpClient, globalConfig: ClientConfig, modelConfig: ModelConfig): BaseModelMethods;
     /**
      * 判断是否为 OpenAPI 模式
      */

package/dist/src/models/model-manager.d.ts

@@ -1,17 +1,83 @@
-import type { ModelManager as IModelManager, ClientConfig, BaseModelMethods } from '../types';
+import type { ModelManager as IModelManager, ClientConfig, BaseModelMethods, ModelConfig } from '../types';
 import type { HttpClient } from '../http/http-client';
+/**
+ * 模型管理器
+ *
+ * 支持三种访问方式：
+ * 1. dataset_{datasetCode} - 标准方式，直接通过 datasetCode 访问
+ * 2. alias - 通过配置的别名访问
+ * 3. key（老格式）- 通过对象配置的 key 访问（key 作为默认 alias）
+ */
 export declare class ModelManager implements IModelManager {
     private httpClient;
     private config;
     private modelCache;
+    private datasetCodeMap;
+    private aliasMap;
     constructor(httpClient: HttpClient, config: ClientConfig);
-    private getModel;
+    /**
+     * 构建内部映射表
+     */
+    private buildMaps;
+    /**
+     * 解析访问名称，返回 datasetCode
+     * @param accessName 访问名称，可能是 dataset_{datasetCode} 格式或 alias
+     *
+     * 支持两种访问方式：
+     * 1. dataset_{datasetCode} - 标准格式，明确表示这是一个 datasetCode
+     * 2. alias - 通过别名访问（老格式中 key 作为默认 alias）
+     */
+    private resolveDatasetCode;
+    /**
+     * 通过 datasetCode 获取模型实例
+     */
+    private getModelByDatasetCode;
     getCachedModels(): string[];
     clearCache(): void;
-    addModel(modelName: string, config: {
+    /**
+     * 动态添加模型配置
+     * 支持两种调用方式：
+     * 1. addModel(modelConfig) - 新格式
+     * 2. addModel(name, config) - 老格式（向下兼容）
+     */
+    addModel(modelNameOrConfig: string | ModelConfig, config?: {
         tableName: string;
         datasetCode: string;
     }): void;
+    /**
+     * 获取所有可用模型的 datasetCode 列表（带 dataset_ 前缀）
+     * 返回格式与访问方式一致，便于 AI/LLM 直接使用
+     */
     list(): string[];
+    /**
+     * 获取所有可用的别名列表
+     */
+    listAliases(): string[];
+    /**
+     * 获取所有模型的详细信息，包含别名和名称
+     * 用于 UI 展示人类友好的模型列表
+     *
+     * @returns 模型详情数组，每个元素包含：
+     *   - value: 用于访问的 dataset_xxx 格式
+     *   - label: 人类友好的显示名称，格式为 "alias[name]" 或 "dataset_xxx"
+     *   - alias: 别名（如果有）
+     *   - name: 模型名称（如果有）
+     *   - datasetCode: 原始 datasetCode
+     */
+    listDetails(): Array<{
+        value: string;
+        label: string;
+        alias?: string;
+        name?: string;
+        datasetCode: string;
+    }>;
+    /**
+     * 根据索引、datasetCode 或 alias 获取模型实例
+     *
+     * 支持三种访问方式：
+     * 1. 数字索引 - 按 datasetCode 列表顺序获取
+     * 2. dataset_{datasetCode} - 直接通过 datasetCode 访问
+     * 3. alias - 通过别名访问
+     */
     get(indexOrName: number | string): BaseModelMethods;
 }

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

@@ -176,16 +176,33 @@ export interface SelectOptionsParams {
 export interface ModelConfig {
     /** 数据表名称 */
     tableName: string;
-    /** 数据集代码 */
+    /** 数据集代码（唯一标识） */
     datasetCode: string;
     /** 数据集名称 */
     name?: string;
+    /** 别名，用于人类友好的访问方式（可选） */
+    alias?: string;
 }
 /**
  * 模型配置集合接口
  * @description 包含应用代码和所有模型配置的集合
+ *
+ * 支持两种格式：
+ * 1. 数组格式（推荐）：ModelConfig[]
+ * 2. 对象格式（向下兼容）：Record<string, ModelConfig>，key 作为默认 alias
+ *
  * @example
  * ```typescript
+ * // 新格式（数组）
+ * const config: ModelsConfig = {
+ *   appCode: 'my-app',
+ *   models: [
+ *     { tableName: 'users', datasetCode: 'dataset_abc', alias: 'users' },
+ *     { tableName: 'posts', datasetCode: 'dataset_def' }
+ *   ]
+ * };
+ *
+ * // 老格式（对象，向下兼容）
  * const config: ModelsConfig = {
  *   appCode: 'my-app',
  *   models: {
@@ -198,8 +215,12 @@ export interface ModelConfig {
 export interface ModelsConfig {
     /** 应用代码，用于标识不同的应用 */
     appCode: string;
-    /** 模型配置映射，键为模型名称，值为模型配置 */
-    models: Record<string, ModelConfig>;
+    /**
+     * 模型配置
+     * - 数组格式（推荐）：直接使用 datasetCode 访问
+     * - 对象格式（兼容）：key 作为默认 alias
+     */
+    models: ModelConfig[] | Record<string, ModelConfig>;
 }
 /**
  * 客户端配置接口
@@ -237,8 +258,12 @@ export interface ClientConfig {
     secretKey?: string;
     /** 是否需要认证，默认为 true */
     requiresAuth?: boolean;
-    /** 模型配置映射，直接传入的模型配置 */
-    models?: Record<string, ModelConfig>;
+    /**
+     * 模型配置
+     * - 数组格式（推荐）：直接使用 datasetCode 访问
+     * - 对象格式（兼容）：key 作为默认 alias
+     */
+    models?: ModelConfig[] | Record<string, ModelConfig>;
     /**
      * 引用已注册的 API 配置名称
      * @description 当指定此字段时，会从配置注册表中获取对应的模型配置
@@ -399,13 +424,18 @@ export interface ModelManager {
     clearCache(): void;
     /**
      * 动态添加模型配置
-     * @param modelName 模型名称
-     * @param config 模型配置信息
+     * @param modelNameOrConfig 模型名称（老格式）或 ModelConfig（新格式）
+     * @param config 模型配置信息（老格式时使用）
      */
-    addModel(modelName: string, config: {
+    addModel(modelNameOrConfig: string | ModelConfig, config?: {
         tableName: string;
         datasetCode: string;
     }): void;
+    /**
+     * 获取所有可用的别名列表
+     * @returns 返回已配置的所有别名数组
+     */
+    listAliases(): string[];
     /**
      * 获取所有可用模型列表
      * @returns 返回已配置的所有模型名称数组
@@ -429,6 +459,25 @@ export interface ModelManager {
      * ```
      */
     get(indexOrName: number | string): BaseModelMethods;
+    /**
+     * 获取所有模型的详细信息，包含别名和名称
+     * @returns 模型详情数组，用于 UI 展示人类友好的模型列表
+     * @example
+     * ```typescript
+     * const details = client.getModelListDetails();
+     * // [
+     * //   { value: 'dataset_xxx', label: 'projects[项目]', alias: 'projects', name: '项目', datasetCode: 'xxx' },
+     * //   { value: 'dataset_yyy', label: 'dataset_yyy', datasetCode: 'yyy' }
+     * // ]
+     * ```
+     */
+    listDetails(): Array<{
+        value: string;
+        label: string;
+        alias?: string;
+        name?: string;
+        datasetCode: string;
+    }>;
 }
 /**
  * 认证请求头接口

package/package.json

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