@lovrabet/sdk 1.1.19 → 1.1.21-beta.1

package/README.md

@@ -246,7 +246,7 @@ SDK 提供了 `client.api` 命名空间，用于执行自定义 SQL 查询和其
 
 ```typescript
 // 执行 SQL 查询，返回结果数组
-const results = await client.api.executeSql('fc8e7777-06e3847d');
+const results = await client.api.executeSql("fc8e7777-06e3847d");
 console.log(results);
 // [
 //   { creation_date: '2025-08-13', page_count: 2 },
@@ -259,9 +259,9 @@ console.log(results);
 
 ```typescript
 // 传递参数到 SQL
-const results = await client.api.executeSql('fc8e7777-xxxxx', {
-  userId: '123',
-  startDate: '2025-01-01'
+const results = await client.api.executeSql("fc8e7777-xxxxx", {
+  userId: "123",
+  startDate: "2025-01-01",
 });
 ```
 
@@ -275,9 +275,9 @@ interface PageStat {
 }
 
 // 使用泛型获得类型安全
-const stats = await client.api.executeSql<PageStat>('fc8e7777-06e3847d');
-stats.forEach(stat => {
-  console.log(stat.creation_date);  // TypeScript 自动补全
+const stats = await client.api.executeSql<PageStat>("fc8e7777-06e3847d");
+stats.forEach((stat) => {
+  console.log(stat.creation_date); // TypeScript 自动补全
   console.log(stat.page_count);
 });
 ```
@@ -286,31 +286,33 @@ stats.forEach(stat => {
 
 ```typescript
 // 获取第一条结果
-const results = await client.api.executeSql<PageStat>('fc8e7777-xxxxx');
+const results = await client.api.executeSql<PageStat>("fc8e7777-xxxxx");
 const firstResult = results[0];
 
 if (firstResult) {
-  console.log(`日期: ${firstResult.creation_date}, 数量: ${firstResult.page_count}`);
+  console.log(
+    `日期: ${firstResult.creation_date}, 数量: ${firstResult.page_count}`
+  );
 } else {
-  console.log('无结果');
+  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");
 ```
 
 #### 错误处理
 
 ```typescript
 try {
-  const results = await client.api.executeSql('fc8e7777-xxxxx');
+  const results = await client.api.executeSql("fc8e7777-xxxxx");
 } catch (error) {
   if (error instanceof LovrabetError) {
-    console.error('SQL执行失败:', error.message);
-    console.error('错误代码:', error.code);
+    console.error("SQL执行失败:", error.message);
+    console.error("错误代码:", error.code);
   }
 }
 ```
@@ -352,6 +354,10 @@ import {
   type TokenResult,
   type ListResponse,
   type ListParams,
+  type FilterParams,
+  type WhereCondition,
+  type FieldCondition,
+  type ConditionOperator,
   type SortList,
   type SelectOption,
   type SelectOptionsParams,
@@ -424,10 +430,143 @@ const options = await client.models.users.getSelectOptions({
 // 返回: [{ label: '张三', value: 'user001' }, { label: '李四', value: 'user002' }]
 ```
 
+### 🔍 高级过滤查询（推荐）
+
+`filter()` 方法提供比 `getList()` 更强大的查询能力，支持复杂的条件筛选、字段选择和排序。
+
+#### 基础用法
+
+```typescript
+// 简单条件查询
+const result = await client.models.users.filter({
+  where: {
+    age: { $gte: 18 } // 年龄 >= 18
+  },
+  currentPage: 1,
+  pageSize: 20
+});
+
+console.log(result.tableData); // 数据列表
+console.log(result.total);     // 总数量
+```
+
+#### 复杂条件组合
+
+```typescript
+import { SortOrder } from "@lovrabet/sdk";
+
+const result = await client.models.users.filter({
+  where: {
+    $and: [
+      // 年龄区间
+      { age: { $gte: 18, $lte: 45 } },
+      // 国家在集合内
+      { country: { $in: ['中国', '美国', '日本'] } },
+      // VIP 字段非空
+      { vip: { $ne: null } },
+      // 名称模糊匹配
+      { name: { $contain: 'hello' } }
+    ]
+  },
+  // 选择返回的字段
+  select: ['id', 'name', 'age', 'country', 'lastLoginAt'],
+  // 多字段排序：先按登录时间倒序，再按名称升序
+  orderBy: [
+    { lastLoginAt: SortOrder.DESC },
+    { name: SortOrder.ASC }
+  ],
+  currentPage: 1,
+  pageSize: 20
+});
+```
+
+#### 支持的操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$eq` | 等于 | `{ status: { $eq: 'active' } }` |
+| `$ne` | 不等于 | `{ status: { $ne: 'deleted' } }` |
+| `$gte` / `$gteq` | 大于等于 | `{ age: { $gte: 18 } }` |
+| `$lte` / `$lteq` | 小于等于 | `{ age: { $lte: 65 } }` |
+| `$in` | 在集合内 | `{ country: { $in: ['中国', '美国'] } }` |
+| `$contain` | 包含（模糊匹配） | `{ name: { $contain: 'test' } }` |
+| `$startWith` | 以...开头 | `{ name: { $startWith: 'Mr.' } }` |
+| `$endWith` | 以...结尾 | `{ email: { $endWith: '@example.com' } }` |
+
+#### 逻辑连接符
+
+```typescript
+// $and - 所有条件都满足
+const result = await client.models.users.filter({
+  where: {
+    $and: [
+      { age: { $gte: 18 } },
+      { status: { $eq: 'active' } }
+    ]
+  }
+});
+
+// $or - 任一条件满足
+const result = await client.models.users.filter({
+  where: {
+    $or: [
+      { country: { $eq: '中国' } },
+      { country: { $eq: '美国' } }
+    ]
+  }
+});
+
+// 嵌套条件
+const result = await client.models.users.filter({
+  where: {
+    $and: [
+      { age: { $gte: 18 } },
+      {
+        $or: [
+          { country: { $eq: '中国' } },
+          { country: { $eq: '美国' } }
+        ]
+      }
+    ]
+  }
+});
+```
+
+#### 字段选择
+
+```typescript
+// 只返回指定字段
+const result = await client.models.users.filter({
+  select: ['id', 'name', 'email'],
+  currentPage: 1,
+  pageSize: 20
+});
+
+// 访问 JSON 字段
+const result = await client.models.users.filter({
+  select: ['id', "value['name']", 'age'],
+  currentPage: 1,
+  pageSize: 20
+});
+```
+
+#### filter vs getList
+
+| 特性 | `filter()` | `getList()` |
+|------|-----------|------------|
+| 复杂条件查询 | ✅ 支持 $and, $or 等 | ❌ 仅支持简单参数 |
+| 字段选择 | ✅ 支持 select | ❌ 返回所有字段 |
+| 条件操作符 | ✅ 支持 11 种操作符 | ❌ 仅支持精确匹配 |
+| 排序 | ✅ 支持多字段排序 | ✅ 支持多字段排序 |
+| 分页 | ✅ 支持 | ✅ 支持 |
+| 性能 | 更优（减少数据传输） | 一般 |
+| 使用场景 | **推荐用于复杂查询** | 简单列表查询 |
+
 ### ⚠️ 操作限制
 
 **OpenAPI 模式暂不支持以下操作：**
 
+- ❌ `filter()` - 高级过滤查询（如需使用，请使用 WebAPI 模式）
 - ❌ `delete()` - 删除操作（如需删除，请使用 WebAPI 模式）
 - ❌ `getSelectOptions()` - 获取下拉选项（仅 WebAPI 模式支持）
 
@@ -507,23 +646,25 @@ const client = createClient({ token });
 
   ```typescript
   // 执行 SQL 查询
-  const data = await client.api.executeSql('fc8e7777-06e3847d');
+  const data = await client.api.executeSql("fc8e7777-06e3847d");
 
   // 应用层检查执行结果
   if (data.execSuccess && data.execResult) {
-    data.execResult.forEach(row => {
+    data.execResult.forEach((row) => {
       console.log(row);
     });
   }
   ```
 
   **核心特性：**
+
   - 支持参数化查询，防止 SQL 注入
   - 完整的 TypeScript 类型支持（泛型）
   - 返回 `{ execSuccess: boolean, execResult?: T[] }` 结构
   - 应用层负责检查 `execSuccess` 状态
 
   **适用场景：**
+
   - 复杂数据统计和聚合查询
   - 跨表关联查询
   - 自定义报表数据获取
@@ -531,66 +672,11 @@ const client = createClient({ token });
 
 - 🏗️ **API 命名空间架构** - 新增 `client.api` 命名空间，用于管理通用 API 调用
 
-  ```typescript
-  const client = createClient({ /* ... */ });
-
-  // 通过 api 命名空间访问
-  const data = await client.api.executeSql('sqlCode');
-  ```
-
-  - 统一的 API 调用入口
-  - 为未来扩展预留空间（executeFunction、callWebhook 等）
-  - 与 Model API 保持一致的设计风格
-
-**类型定义 (Type Definitions):**
-
-- 新增 `SqlExecuteRequest` 接口：
-
-  ```typescript
-  interface SqlExecuteRequest {
-    sqlCode: string | number;  // SQL 代码
-    params?: Record<string, string | number>;  // SQL 参数
-  }
-  ```
-
-- 新增 `SqlExecuteResult<T>` 接口：
-
-  ```typescript
-  interface SqlExecuteResult<T = Record<string, any>> {
-    execSuccess: boolean;  // SQL 执行是否成功
-    execResult?: T[];      // 查询结果数组
-  }
-  ```
-
-- 导出 `ApiNamespace` 类供高级用户使用
-
-**重要说明 (Important Notes):**
-
-:::warning SDK 返回值设计原则
-
-SDK 的 `executeSql()` 方法返回包含 `execSuccess` 和 `execResult` 的对象，**不直接返回结果数组**。
-
-这是因为：
-1. **分离职责** - SDK 负责 HTTP 通信，应用层负责业务逻辑判断
-2. **错误处理** - `execSuccess: false` 表示 SQL 执行失败（业务错误），HTTP 失败才抛异常
-3. **灵活性** - 应用层可以根据 `execSuccess` 自行决定如何处理
-
-```typescript
-// ✅ 正确使用方式
-const data = await client.api.executeSql('sqlCode');
-if (data.execSuccess && data.execResult) {
-  // 使用 execResult
-}
-
-// ❌ 错误使用方式
-const data = await client.api.executeSql('sqlCode');
-data.execResult.forEach(...);  // 没有检查 execSuccess！
-```
-:::
+详细说明参考：[说明文档](https://open.lovrabet.com/docs/lovrabet-sdk/sql-api)
 
 ---
 
-### v1.1.18 (2025-10-18)
+### v1.1.17 (2025-10-18)
 
 **新增功能 (New Features):**
 

package/dist/index.d.ts

@@ -8,6 +8,6 @@ export { ApiNamespace } from "./src/api/index";
 export { AuthManager, } from "./src/auth/index";
 export { generateOpenApiToken, TokenGenerator, isTokenExpiring, getTokenRemainingTime, type GenerateTokenParams, type TokenResult } from "./src/auth/index";
 export type { ClientConfig, LovrabetClient, ModelConfig, ModelsConfig, } from "./src/types/index";
-export type { ListParams, ListResponse, Environment, BaseModelMethods, SortList, SelectOption, SelectOptionsParams, } from "./src/types/index";
+export type { ListParams, ListResponse, FilterParams, WhereCondition, FieldCondition, ConditionOperator, Environment, BaseModelMethods, SortList, SelectOption, SelectOptionsParams, } from "./src/types/index";
 export type { SqlExecuteRequest, SqlExecuteResult, } from "./src/api/types";
 export { SortOrder, } from "./src/types/index";