@lovrabet/sdk 1.2.0-beta.2 → 1.2.3

package/README.md

@@ -31,16 +31,15 @@ import { createClient } from "@lovrabet/sdk";
 const client = createClient({
   appCode: "your-app-code",
   accessKey: process.env.LOVRABET_ACCESS_KEY,
-  models: {
-    users: {
-      tableName: "users",
-      datasetCode: "your-dataset-code",
-    },
-  },
+  models: [
+    { tableName: "users", datasetCode: "abc123def456", alias: "users" },
+    { tableName: "posts", datasetCode: "ghi789jkl012" },
+  ],
 });
 
-// CRUD 操作
-const users = await client.models.users.getList();
+// CRUD 操作（通过 alias 或 datasetCode 访问）
+const users = await client.models.users.getList();              // 通过 alias
+const posts = await client.models["dataset_ghi789jkl012"].getList(); // 通过 datasetCode
 const user = await client.models.users.getOne("user-id");
 const newUser = await client.models.users.create({ name: "John" });
 ```
@@ -79,12 +78,9 @@ const client = createClient({
   appCode: "your-app-code",
   token: token,
   timestamp: timestamp,
-  models: {
-    users: {
-      tableName: "users",
-      datasetCode: "your-dataset-code",
-    },
-  },
+  models: [
+    { tableName: "users", datasetCode: "abc123def456", alias: "users" },
+  ],
 });
 
 // 使用
@@ -99,12 +95,9 @@ import { createClient } from "@lovrabet/sdk";
 // 不提供认证信息，自动使用 Cookie
 const client = createClient({
   appCode: "your-app-code",
-  models: {
-    users: {
-      tableName: "users",
-      datasetCode: "your-dataset-code",
-    },
-  },
+  models: [
+    { tableName: "users", datasetCode: "abc123def456", alias: "users" },
+  ],
 });
 
 // 请求会自动带上 Cookie
@@ -173,20 +166,21 @@ console.log(`Token 剩余 ${remaining / 1000} 秒`);
 ```typescript
 import { registerModels, createClient } from "@lovrabet/sdk";
 
-// 注册配置
+// 注册配置（数组格式）
 registerModels({
   appCode: "your-app-code",
-  models: {
-    users: { tableName: "users", datasetCode: "ds-001" },
-    posts: { tableName: "posts", datasetCode: "ds-002" },
-  },
+  models: [
+    { tableName: "users", datasetCode: "abc123def456", alias: "users", name: "用户" },
+    { tableName: "posts", datasetCode: "ghi789jkl012", alias: "posts", name: "文章" },
+  ],
 });
 
 // 创建客户端（无参数）
 const client = createClient();
 
-// 使用
+// 使用（通过 alias 访问）
 const users = await client.models.users.getList();
+const posts = await client.models.posts.getList();
 ```
 
 ### 多环境管理
@@ -198,9 +192,9 @@ import { registerModels, createClient } from "@lovrabet/sdk";
 registerModels(
   {
     appCode: "prod-app",
-    models: {
-      /* ... */
-    },
+    models: [
+      { tableName: "users", datasetCode: "prod_abc123", alias: "users" },
+    ],
   },
   "prod"
 );
@@ -208,9 +202,9 @@ registerModels(
 registerModels(
   {
     appCode: "dev-app",
-    models: {
-      /* ... */
-    },
+    models: [
+      { tableName: "users", datasetCode: "dev_abc123", alias: "users" },
+    ],
   },
   "dev"
 );
@@ -226,16 +220,16 @@ const devClient = createClient("dev");
 // 创建客户端
 const client = createClient({
   appCode: "your-app-code",
-  models: {
-    /* ... */
-  },
+  models: [
+    { tableName: "users", datasetCode: "abc123def456", alias: "users" },
+  ],
 });
 
 // 后续更新 token
 client.setToken(newToken, newTimestamp);
 
 // 切换环境
-client.switchEnv("daily");
+client.setEnvironment("daily");
 ```
 
 ### 执行自定义 SQL
@@ -245,24 +239,32 @@ SDK 提供了 `client.api` 命名空间，用于执行自定义 SQL 查询和其
 #### 基础查询
 
 ```typescript
-// 执行 SQL 查询，返回结果数组
-const results = await client.api.executeSql("fc8e7777-06e3847d");
-console.log(results);
-// [
-//   { creation_date: '2025-08-13', page_count: 2 },
-//   { creation_date: '2025-08-19', page_count: 3 },
-//   ...
-// ]
+// 执行 SQL 查询，返回 SqlExecuteResult 对象
+const data = await client.api.executeSql("fc8e7777-06e3847d");
+
+// 检查执行结果
+if (data.execSuccess && data.execResult) {
+  console.log(data.execResult);
+  // [
+  //   { creation_date: '2025-08-13', page_count: 2 },
+  //   { creation_date: '2025-08-19', page_count: 3 },
+  //   ...
+  // ]
+}
 ```
 
 #### 参数化查询
 
 ```typescript
 // 传递参数到 SQL
-const results = await client.api.executeSql("fc8e7777-xxxxx", {
+const data = await client.api.executeSql("fc8e7777-xxxxx", {
   userId: "123",
   startDate: "2025-01-01",
 });
+
+if (data.execSuccess && data.execResult) {
+  // 处理结果
+}
 ```
 
 #### 带类型提示
@@ -275,33 +277,40 @@ interface PageStat {
 }
 
 // 使用泛型获得类型安全
-const stats = await client.api.executeSql<PageStat>("fc8e7777-06e3847d");
-stats.forEach((stat) => {
-  console.log(stat.creation_date); // TypeScript 自动补全
-  console.log(stat.page_count);
-});
+const data = await client.api.executeSql<PageStat>("fc8e7777-06e3847d");
+
+if (data.execSuccess && data.execResult) {
+  data.execResult.forEach((stat) => {
+    console.log(stat.creation_date); // TypeScript 自动补全
+    console.log(stat.page_count);
+  });
+}
 ```
 
 #### 处理查询结果
 
 ```typescript
-// 获取第一条结果
-const results = await client.api.executeSql<PageStat>("fc8e7777-xxxxx");
-const firstResult = results[0];
-
-if (firstResult) {
-  console.log(
-    `日期: ${firstResult.creation_date}, 数量: ${firstResult.page_count}`
-  );
-} else {
-  console.log("无结果");
-}
+// 获取查询结果
+const data = await client.api.executeSql<PageStat>("fc8e7777-xxxxx");
+
+if (data.execSuccess && data.execResult) {
+  const results = data.execResult;
+  const firstResult = results[0];
+
+  if (firstResult) {
+    console.log(
+      `日期: ${firstResult.creation_date}, 数量: ${firstResult.page_count}`
+    );
+  } else {
+    console.log("无结果");
+  }
 
-// 过滤结果
-const activeItems = results.filter((item) => item.status === "active");
+  // 过滤结果
+  const activeItems = results.filter((item) => item.status === "active");
 
-// 查找特定结果
-const targetItem = results.find((item) => item.id === "123");
+  // 查找特定结果
+  const targetItem = results.find((item) => item.id === "123");
+}
 ```
 
 #### 错误处理
@@ -349,9 +358,25 @@ import {
   // API 命名空间
   ApiNamespace,
 
+  // 认证管理（高级用法）
+  AuthManager,
+
+  // 模型类（高级用法和扩展）
+  AbstractBaseModel,
+  OpenApiModel,
+  WebApiModel,
+  ModelFactory,
+
+  // 排序枚举
+  SortOrder,
+
   // TypeScript 类型
   type ClientConfig,
+  type LovrabetClient,
+  type ModelConfig,
+  type ModelsConfig,
   type TokenResult,
+  type GenerateTokenParams,
   type ListResponse,
   type ListParams,
   type FilterParams,
@@ -363,7 +388,8 @@ import {
   type SelectOptionsParams,
   type SqlExecuteRequest,
   type SqlExecuteResult,
-  type SortOrder,
+  type Environment,
+  type BaseModelMethods,
 } from "@lovrabet/sdk";
 ```
 
@@ -384,13 +410,13 @@ interface ClientConfig {
 ### CRUD 操作
 
 ```typescript
-// 查询列表（返回 paging/tableData/tableColumns）
+// 查询列表（返回 tableData/total/currentPage/pageSize）
 const response = await client.models.users.getList({
   currentPage: 1,
   pageSize: 20,
 });
-console.log(response.paging.totalCount);
-console.log(response.tableColumns);
+console.log(response.total);     // 总数量
+console.log(response.tableData); // 数据列表
 
 // 查询列表（带排序）
 const sortedUsers = await client.models.users.getList(
@@ -575,9 +601,9 @@ try {
 const webApiClient = createClient({
   appCode: "your-app-code",
   // 不提供 token/accessKey，自动使用 Cookie 认证
-  models: {
-    /* ... */
-  },
+  models: [
+    { tableName: "users", datasetCode: "abc123def456", alias: "users" },
+  ],
 });
 
 await webApiClient.models.users.delete("user-id"); // ✅ 可以使用
@@ -631,6 +657,64 @@ const client = createClient({ token });
 
 ## 📝 What's New
 
+### v1.2.2 (2025-12-30)
+
+**重大更新 (Major Changes):**
+
+- 🏗️ **模型管理器重构** - 支持基于 `datasetCode` 的统一访问方式
+
+  ```typescript
+  // 新格式：数组配置（推荐）
+  const client = createClient({
+    appCode: "your-app-code",
+    models: [
+      { tableName: "users", datasetCode: "ds-001", alias: "users", name: "用户" },
+      { tableName: "posts", datasetCode: "ds-002" }
+    ]
+  });
+
+  // 多种访问方式
+  client.models.users.getList();           // 通过 alias 访问
+  client.models["dataset_ds-001"].getList(); // 通过 datasetCode 访问
+  client.getModel(0).getList();            // 通过索引访问
+  ```
+
+  **核心改进：**
+  - 使用 `datasetCode` 作为模型的唯一标识符
+  - 支持 `dataset_{datasetCode}` 前缀格式的标准化访问
+  - 新增数组格式配置，同时保持对象格式向下兼容
+  - 老格式对象配置中的 key 自动作为默认 alias
+
+- ✨ **模型管理器增强** - 新增多个辅助方法
+
+  ```typescript
+  // 获取模型详细信息（用于 UI 展示）
+  const details = client.getModelListDetails();
+  // [
+  //   { value: 'dataset_ds-001', label: 'users[用户]', alias: 'users', name: '用户' },
+  //   { value: 'dataset_ds-002', label: 'dataset_ds-002' }
+  // ]
+
+  // 获取所有别名
+  const aliases = client.models.listAliases();
+  ```
+
+- 🔧 **环境管理方法更新**
+
+  ```typescript
+  // 切换环境（方法名变更）
+  client.setEnvironment("daily");  // 新方法名
+  client.getEnvironment();         // 获取当前环境
+  ```
+
+**代码质量 (Code Quality):**
+
+- 清理过期文档
+- 增强类型安全
+- 统一代码规范
+
+---
+
 ### v1.1.24 (2025-12-03)
 
 **新增功能 (New Features):**
@@ -667,7 +751,9 @@ const client = createClient({ token });
   const client = createClient({
     appCode: "your-app-code",
     accessKey: process.env.LOVRABET_ACCESS_KEY, // OpenAPI 模式下使用 filter（v1.1.22+）
-    models: { users: { tableName: "users", datasetCode: "ds-001" } },
+    models: [
+      { tableName: "users", datasetCode: "abc123def456", alias: "users" },
+    ],
   });
 
   // 现在可以使用 filter 进行复杂查询