@lovrabet/cli 1.1.22 → 1.1.25

package/templates/rules/lovrabet_rules.mdc.tpl

@@ -4,7 +4,7 @@ alwaysApply: false
 ---
 # Lovrabet 开发生态 AI 助手指南
 
-## 🎯 核心原则
+## 核心原则
 
 你是一个专业的 Lovrabet 平台开发助手。你的目标是帮助开发者高效、正确地使用 Lovrabet SDK 和 MCP。
 
@@ -17,14 +17,14 @@ alwaysApply: false
 5. **类型安全**：充分利用 TypeScript，避免运行时错误
 
 
-## 📚 SDK 使用规范
+## SDK 使用规范
 
 ### 1. SDK 初始化
 
 ```typescript
 import { createClient } from '@lovrabet/sdk';
 
-// ✅ 正确：使用 createClient 函数
+// 正确：使用 createClient 函数
 const client = createClient({
   appCode: '<appcode>',
   accessKey: process.env.LOVRABET_ACCESS_KEY, // 服务端
@@ -38,13 +38,13 @@ const client = createClient({
   },
 });
 
-// ❌ 错误：使用 new 关键字
+// 错误：使用 new 关键字
 const client = new LovrabetClient({ ... });
 
-// ❌ 错误：使用不存在的 mode 参数
+// 错误：使用不存在的 mode 参数
 const client = createClient({ mode: 'webapi', ... });
 
-// ❌ 错误：缺少必需的 models 配置
+// 错误：缺少必需的 models 配置
 const client = createClient({ appCode: '<appcode>', accessKey: '<key>' });
 ```
 
@@ -55,16 +55,17 @@ const client = createClient({ appCode: '<appcode>', accessKey: '<key>' });
 - SDK 返回：只返回 `data`字段的内容
 
 **失败时**：抛出 `LovrabetError` 异常
-- 异常对象包含：`{ message: string, status?: number, code?: string, data?: any }`
+- 异常对象包含：`{ message: string, status?: number, code?: string, response?: any }`
+- `response` 包含服务端完整响应数据
 - 不会返回错误信息，而是抛出异常，需要使用 `try-catch` 包裹所有 SDK 调用
 
 **关键提示**：
-- ✅ 必须使用 `try-catch` 包裹所有 SDK 调用
-- ✅ 成功时直接获取业务数据（如 `{ id: 123, name: "..." }`）
-- ✅ 失败时捕获异常处理错误
+- 必须使用 `try-catch` 包裹所有 SDK 调用
+- 成功时直接获取业务数据（如 `{ id: 123, name: "..." }`）
+- 失败时捕获异常处理错误
 
 ```typescript
-// ✅ 正确：完整的错误处理
+// 正确：完整的错误处理
 try {
   const user = await client.models.<modelName>.getOne(<id>);
   console.log(user.name); // 直接使用返回的数据
@@ -73,65 +74,46 @@ try {
     console.error('业务错误:', error.message);
     console.error('错误代码:', error.code);
     console.error('HTTP状态:', error.status);
+    console.error('服务端响应:', error.response); // 完整的服务端响应
   }
 }
 
-// ❌ 错误：假设返回值包含 success 字段
+// 错误：假设返回值包含 success 字段
 const response = await client.models.<modelName>.getOne(<id>);
 if (response.success) { ... } // 错误！成功时只返回 data 内容
 ```
 
 ### 3. 数据模型操作
 
-**⚠️ 重要提示：优先使用 `filter()` 而不是 `getList()`**
+**重要提示：强烈建议使用 `filter()` 而不是 `getList()`**
 
-在 Cookie 认证模式下，应该优先使用 `filter()` 方法，因为它提供：
-- ✅ 更强大的查询能力（支持复杂条件、范围查询、模糊匹配）
-- ✅ 更好的性能（通过 `select` 参数只返回需要的字段）
-- ✅ 更简洁的返回结构（直接返回 `{ tableData, total }`）
+`filter()` 方法在 v1.1.22+ 已支持 **OpenAPI 和 WebAPI 两种模式**，强烈建议优先使用：
+- 更强大的查询能力（支持复杂条件、范围查询、模糊匹配）
+- 更好的性能（通过 `select` 参数只返回需要的字段）
+- 更简洁的返回结构（直接返回 `{ tableData, total }`）
+- 支持 11 种条件操作符和 `$and`/`$or` 逻辑组合
+  - 支持的操作符（11 种）：
+  - $eq, $ne, $gte ($gteq), $lte ($lteq), $in, $contain, $startWith, $endWith
+  - 逻辑操作符：$and, $or（支持嵌套）
 
-只在以下情况使用 `getList()`：
-- 使用 Token/AccessKey 认证模式（不支持 filter）
-- 需要 `tableColumns` 字段定义信息
-
-#### 查询列表
-
-```typescript
-// ⚠️ 不推荐：getList 功能有限，返回结构复杂
-const response = await client.models.<modelName>.getList({
-  currentPage: 1,
-  pageSize: 20,
-});
-
-console.log(response.paging.totalCount); // 总数
-console.log(response.tableData); // 数据列表
-console.log(response.tableColumns); // 列定义
-
-// ❌ 错误：使用 total 字段
-console.log(response.total); // getList 没有 total 字段
-
-// ✅ 正确：带排序
-import { SortOrder } from '@lovrabet/sdk';
-
-const sorted = await client.models.<modelName>.getList(
-  { currentPage: 1, pageSize: 20 },
-  [{ <fieldName>: SortOrder.DESC }]
-);
-```
-
-#### 高级过滤查询（v1.1.21+，仅 Cookie 模式，推荐使用）
+#### 高级过滤查询（v1.1.22+，OpenAPI 和 WebAPI 都支持，强烈推荐！）
 
 ```typescript
-// ✅ 推荐：filter 功能强大，性能更好
+// 强烈推荐：filter 功能强大，性能更好，两种模式都支持
 const result = await client.models.<modelName>.filter({
   where: {
     $and: [
-      { <fieldName>: { $gte: 18, $lte: 35 } },
-      { <fieldName>: { $in: ['<value1>', '<value2>'] } },
+      { age: { $gte: 18, $lte: 45 } }, // 年龄区间
+      { country: { $in: ['中国', '美国', '日本'] } }, // 国家在集合内
+      { vip: { $ne: null } }, // VIP 字段非空
+      { name: { $contain: 'hello' } }, // 名称模糊匹配
     ],
   },
-  select: ['<field1>', '<field2>', '<field3>'], // 注意：是 select，不是 fields
-  orderBy: [{ <fieldName>: SortOrder.DESC }], // 注意：是 orderBy，不是 sortList
+  select: ['id', 'name', 'age', 'country'], // 注意：是 select，不是 fields
+  orderBy: [
+    { lastLoginAt: SortOrder.DESC }, // 先按登录时间倒序
+    { name: SortOrder.ASC }, // 再按名称升序
+  ], // 注意：是 orderBy，不是 sortList
   currentPage: 1,
   pageSize: 20,
 });
@@ -139,28 +121,87 @@ const result = await client.models.<modelName>.filter({
 console.log(result.tableData); // 数据列表
 console.log(result.total); // 总数
 
-// ❌ 错误：参数名错误
+// 复杂嵌套条件
 const result = await client.models.<modelName>.filter({
-  fields: ['<field1>', '<field2>'], // 错误！应该是 select
-  sortList: [{ ... }], // 错误！应该是 orderBy
+  where: {
+    $and: [
+      { age: { $gte: 18 } },
+      {
+        $or: [
+          { country: { $eq: '中国' } },
+          { country: { $eq: '美国' } }
+        ]
+      }
+    ]
+  }
 });
-
-// 支持的操作符：$eq, $ne, $gte, $lte, $in, $contain, $startWith, $endWith, $and, $or
 ```
 
 #### SQL API（v1.1.19+）
 
+**注意事项**：
+
+1. **传入 SQL ID**：不是传入原始 SQL 语句，而是在 Lovrabet 后台登记后获得的 SQL ID（格式如 `fc8e7777-06e3847d`）
+2. **SQL 登记**：去 Lovrabet 后台 → 自定义 SQL → 创建 SQL 并登记，获得唯一 ID
+3. **参数传递**：SQL 支持参数化查询，通过第二个参数传入对象，对象的 key 对应 SQL 中的参数名
+4. **检查执行状态**：必须检查 `data.execSuccess && data.execResult`，不要直接使用 `execResult`
+
+**正确示例**：
+
 ```typescript
-// ✅ 正确：executeSql 返回 { execSuccess, execResult }
-const data = await client.api.executeSql<MyType>(<sql-code>);
+// 基础查询（无参数）
+const data = await client.api.executeSql('fc8e7777-06e3847d');
 
 if (data.execSuccess && data.execResult) {
   data.execResult.forEach(row => console.log(row));
 }
 
-// ❌ 错误：假设直接返回数组
-const results = await client.api.executeSql(<sql-code>);
-results.forEach(...); // 错误！返回的是对象，不是数组
+// 参数化查询（推荐）
+const data = await client.api.executeSql('fc8e7777-06e3847d', {
+  userId: '123',           // SQL 中使用 #{userId}
+  startDate: '2025-01-01', // SQL 中使用 #{startDate}
+  endDate: '2025-12-31'    // SQL 中使用 #{endDate}
+});
+
+if (data.execSuccess && data.execResult) {
+  console.log('查询成功', data.execResult);
+}
+```
+
+#### 用户列表 API（v1.1.19+）
+
+**说明**：获取平台用户列表，内置 30 秒缓存。
+
+```typescript
+// 获取用户列表
+const userList = await client.api.user.getList();
+
+// 返回 User[] 数组
+userList.forEach(user => {
+  console.log(user.code);       // 用户代码
+  console.log(user.userName);   // 用户名
+  console.log(user.nickName);   // 昵称（可选）
+  console.log(user.mobile);     // 手机号
+  console.log(user.email);      // 邮箱（可选）
+  console.log(user.avatar);     // 头像（可选）
+});
+
+// 带类型提示
+import type { User } from '@lovrabet/sdk';
+
+const userList: User[] = await client.api.user.getList();
+
+// 查找特定用户
+const targetUser = userList.find(u => u.code === 'user123');
+if (targetUser) {
+  console.log(targetUser.userName);
+}
+
+// 生成用户下拉选项
+const userOptions = userList.map(u => ({
+  label: u.nickName || u.userName,
+  value: u.code
+}));
 ```
 
 #### 其他 CRUD 操作
@@ -185,28 +226,46 @@ const options = await client.models.<modelName>.getSelectOptions({
 });
 ```
 
-### 4. 认证模式限制
+### 4. 认证模式支持（v1.1.22+ 更新）
 
-**Token/AccessKey 模式**：
-- ✅ getList, getOne, create, update, executeSql
+**OpenAPI 模式（accessKey/token）**：
+- 支持：getList, getOne, create, update
+- 支持：**filter**（v1.1.22+ 新增）
+- 支持：executeSql
+- 不支持：user.getList
+- 不支持：delete（暂不支持）
+- 不支持：getSelectOptions（暂不支持）
 
-**Cookie 模式（额外支持）**：
-- ✅ delete, filter, getSelectOptions
+**WebAPI 模式（Cookie）**：
+- 支持：getList, getOne, create, update
+- 支持：filter
+- 支持：delete
+- 支持：getSelectOptions
+- 支持：executeSql
+- 支持：user.getList
 
 ```typescript
-// ❌ 错误：在 Token 模式使用 filter
+// 正确：v1.1.22+ OpenAPI 模式支持 filter
+const client = createClient({ accessKey: '<key>', ... });
+await client.models.<modelName>.filter({ ... }); // 可以使用
+
+// 错误：OpenAPI 模式不支持 delete
 const client = createClient({ token: '<token>', ... });
-await client.models.<modelName>.filter({ ... }); // 会失败
+await client.models.<modelName>.delete('<id>'); // 会抛出错误
+
+// 正确：使用 WebAPI 模式进行删除
+const client = createClient({ appCode: '<appcode>', ... }); // 不提供认证信息，使用 Cookie
+await client.models.<modelName>.delete('<id>'); // 可以使用
 ```
 
-## 🔧 MCP 使用规范
+## MCP 使用规范
 
 ### 关键原则
 
 **必须先获取数据集元数据，再编写代码！**
 
 ```typescript
-// ✅ 正确流程
+// 正确流程
 // 1. 获取数据集详情
 const detail = await use_mcp_tool("get_dataset_detail", {
   appcode: "<appcode>",
@@ -227,36 +286,36 @@ await client.models.<modelName>.create({
   <field2>: <value2>, // 已确认字段存在
 });
 
-// ❌ 错误：跳过元数据获取
+// 错误：跳过元数据获取
 await client.models.<modelName>.create({
   <field>: <value>, // 未确认字段是否存在
 });
 ```
 
 
-## ⚡ 性能优化规则
+## 性能优化规则
 
 ### 1. 减少 API 调用和数据传输
 
 ```typescript
-// ✅ 推荐：使用 filter + select 只返回需要的字段
+// 推荐：使用 filter + select 只返回需要的字段
 const result = await client.models.<modelName>.filter({
   where: { <field>: <value> },
   select: ['<field1>', '<field2>', '<field3>'], // 只返回3个字段，减少数据传输
 });
 
-// ⚠️ 不推荐：getList 返回所有字段，浪费带宽
+// 不推荐：getList 返回所有字段，浪费带宽
 const response = await client.models.<modelName>.getList({
   <field>: <value>,
   pageSize: 20,
 }); // 返回所有字段，无法筛选
 
-// ✅ 批量操作，避免循环
+// 批量操作，避免循环
 const items = await Promise.all(
   ids.map(id => client.models.<modelName>.getOne(id))
 );
 
-// ❌ 避免 N+1 问题
+// 避免 N+1 问题
 for (const id of ids) {
   const item = await client.models.<modelName>.getOne(id); // 逐个等待
 }
@@ -265,10 +324,10 @@ for (const id of ids) {
 ### 2. 缓存和防抖
 
 ```typescript
-// ✅ 缓存不常变化的数据
+// 缓存不常变化的数据
 const cache = new Map();
 
-// ✅ 搜索使用防抖
+// 搜索使用防抖
 import { debounce } from 'lodash';
 const search = debounce(async (keyword) => {
   const result = await client.models.<modelName>.filter({
@@ -279,12 +338,12 @@ const search = debounce(async (keyword) => {
 ```
 
 
-## 🛡️ 错误处理规则
+## 错误处理规则
 
 ### 必须使用 try-catch
 
 ```typescript
-// ✅ 正确：完整的错误处理
+// 正确：完整的错误处理
 import { LovrabetError } from '@lovrabet/sdk';
 
 try {
@@ -294,6 +353,8 @@ try {
   if (error instanceof LovrabetError) {
     console.error('业务错误:', error.message);
     console.error('错误代码:', error.code);
+    console.error('HTTP状态:', error.status);
+    console.error('服务端响应:', error.response);
     alert('操作失败，请稍后重试');
   } else {
     console.error('未知错误:', error);
@@ -301,16 +362,16 @@ try {
   }
 }
 
-// ❌ 错误：没有错误处理
+// 错误：没有错误处理
 const item = await client.models.<modelName>.create({ <field>: <value> });
 ```
 
-## 💡 用户体验规则
+## 用户体验规则
 
 ### 加载状态管理
 
 ```typescript
-// ✅ 显示加载状态
+// 显示加载状态
 const [loading, setLoading] = useState(false);
 
 async function loadData() {
@@ -330,10 +391,10 @@ async function loadData() {
 
 
 
-## 📋 类型安全规则
+## 类型安全规则
 
 ```typescript
-// ✅ 定义类型并使用泛型
+// 定义类型并使用泛型
 interface DataType {
   id: string;
   <field1>: string;
@@ -343,52 +404,57 @@ interface DataType {
 const response = await client.models.<modelName>.getList<DataType>({ pageSize: 20 });
 
 response.tableData.forEach(item => {
-  console.log(item.<field1>); // ✅ 类型安全
-  console.log(item.unknownField); // ❌ 编译错误
+  console.log(item.<field1>); // 类型安全
+  console.log(item.unknownField); // 编译错误
 });
 ```
 
 
 
-## 🚫 禁止事项
+## 禁止事项
 
-1. ❌ **不要臆测 API** - 使用不存在的方法或参数
-2. ❌ **不要臆测字段** - 未通过 MCP 确认字段是否存在
-3. ❌ **不要混淆认证模式** - 在错误的模式使用功能
-4. ❌ **不要忽略错误处理** - 所有 SDK 调用必须 try-catch
-5. ❌ **不要假设返回值结构** - 注意不同方法返回值的差异
-6. ❌ **不要在循环中调用 API** - 使用 Promise.all 批量处理
-7. ❌ **不要在每次渲染时调用 API** - 使用 useEffect 控制
-8. ❌ **不要在 Cookie 模式下使用 getList** - 应该使用功能更强大的 filter
+1. **不要臆测 API** - 使用不存在的方法或参数
+2. **不要臆测字段** - 未通过 MCP 确认字段是否存在
+3. **不要混淆认证模式** - 在错误的模式使用功能（如 OpenAPI 模式使用 delete）
+4. **不要忽略错误处理** - 所有 SDK 调用必须 try-catch
+5. **不要假设返回值结构** - 注意不同方法返回值的差异
+6. **不要在循环中调用 API** - 使用 Promise.all 批量处理
+7. **不要在每次渲染时调用 API** - 使用 useEffect 控制
+8. **不要使用 getList** - 应该使用功能更强大的 `filter()`（v1.1.22+ 两种模式都支持）
+9. **不要忘记检查 execSuccess** - executeSql 返回的数据必须检查 `execSuccess` 状态
+10. **不要假设 executeSql 返回数组** - 返回的是 `{ execSuccess, execResult }` 对象
 
 
 
-## 📖 快速参考
+## 快速参考
 
 ### SDK 方法返回值
 
 | 方法 | 返回结构 | 认证限制 |
 |------|----------|----------|
-| `getList()` | `{ paging, tableData, tableColumns }` | 所有模式 |
-| `filter()` | `{ tableData, total }` | 仅 Cookie |
-| `executeSql()` | `{ execSuccess, execResult }` | 所有模式 |
-| `getOne()` | 单个对象 | 所有模式 |
-| `create/update()` | 操作结果对象 | 所有模式 |
-| `delete()` | 删除结果 | 仅 Cookie |
-| `getSelectOptions()` | `[{ label, value }]` | 仅 Cookie |
+| `filter()` (推荐) | `{ tableData, total }` | **OpenAPI + WebAPI**（v1.1.22+）|
+| `getList()` | `{ paging, tableData, tableColumns }` | OpenAPI + WebAPI |
+| `executeSql()` | `{ execSuccess, execResult }` | OpenAPI + WebAPI |
+| `user.getList()` | `User[]` | OpenAPI + WebAPI |
+| `getOne()` | 单个对象 | OpenAPI + WebAPI |
+| `create/update()` | 操作结果对象 | OpenAPI + WebAPI |
+| `delete()` | 删除结果 | 仅 WebAPI |
+| `getSelectOptions()` | `[{ label, value }]` | 仅 WebAPI |
 
 ### 记住
 
-- ✅ **成功**：SDK 返回 API 响应的 `data` 字段内容
-- ✅ **失败**：抛出 `LovrabetError` 异常（不是返回错误）
-- ✅ **所有调用**：必须用 `try-catch` 包裹
-- ✅ **先获取元数据**：使用 MCP 确认字段存在
-- ✅ **注意参数名**：`select`（不是 `fields`），`orderBy`（不是 `sortList`）
-- ✅ **优先使用 filter**：Cookie 模式下用 `filter()` 而不是 `getList()`
+- **成功**：SDK 返回 API 响应的 `data` 字段内容
+- **失败**：抛出 `LovrabetError` 异常（不是返回错误）
+- **所有调用**：必须用 `try-catch` 包裹
+- **先获取元数据**：使用 MCP 确认字段存在
+- **注意参数名**：`select`（不是 `fields`），`orderBy`（不是 `sortList`）
+- **强烈推荐 filter**：两种模式都支持，用 `filter()` 而不是 `getList()`（v1.1.22+）
+- **executeSql 检查状态**：应用层必须检查 `execSuccess` 状态
+- **用户列表**：使用 `client.api.user.getList()` 获取平台用户
 
 
 
-## 📝 示例代码说明
+## 示例代码说明
 
 **重要**：本文档中所有代码示例使用的是**占位符**（用 `<>` 包裹），而非真实字段名或值。
 
@@ -420,6 +486,6 @@ response.tableData.forEach(item => {
 
 
 **学习资源**：
-- 📖 [官方文档](https://open.lovrabet.com/docs/lovrabet-sdk/intro)
-- 📋 [API 参考](https://open.lovrabet.com/docs/lovrabet-sdk/api-reference)
-- 🔍 [Filter API](https://open.lovrabet.com/docs/lovrabet-sdk/filter-api)
+- [官方文档](https://open.lovrabet.com/docs/lovrabet-sdk/intro)
+- [API 参考](https://open.lovrabet.com/docs/lovrabet-sdk/api-reference)
+- [Filter API](https://open.lovrabet.com/docs/lovrabet-sdk/filter-api)