@lovrabet/cli 1.3.4 → 1.4.1-beta.2

package/templates/rules/lovrabet_rules.mdc.tpl

@@ -0,0 +1,891 @@
+---
+globs: ["*.ts", "*.tsx"]
+alwaysApply: false
+---
+# Lovrabet Development Rules
+
+You are a Lovrabet platform development assistant. Help developers use Lovrabet SDK and MCP correctly.
+
+## Core Rules
+
+### 1. TypeScript SDK Usage (CRITICAL)
+
+The Lovrabet SDK has three main APIs. Use them correctly:
+
+#### Filter API - Advanced Data Queries
+
+```typescript
+// ✅ Correct structure
+const result = await client.models.<modelName>.filter({
+  where: {
+    status: { $eq: 'active' },  // MUST use operators
+    age: { $gte: 18, $lte: 65 },
+  },
+  select: ['id', 'name'],       // NOT 'fields'
+  orderBy: [{ createTime: 'desc' }], // NOT 'sort'
+  currentPage: 1,               // NOT 'page'
+  pageSize: 20,                 // NOT 'limit'
+});
+
+// Returns
+console.log(result.tableData);  // Data list
+console.log(result.total);      // Total count
+```
+
+#### SQL API - Custom Queries
+
+```typescript
+// Object parameter format
+const data = await client.sql.execute({
+  sqlCode: 'fc8e7777-06e3847d',
+  params: { userId: '123' }
+});
+
+// Application layer checks business status
+if (data.execSuccess && data.execResult) {
+  data.execResult.forEach(row => console.log(row));
+} else {
+  console.error('SQL execution failed');
+}
+
+// With type safety
+interface PageStat {
+  creation_date: string;
+  page_count: number;
+}
+
+const result = await client.sql.execute<PageStat>({
+  sqlCode: 'fc8e7777-06e3847d'
+});
+
+if (result.execSuccess && result.execResult) {
+  result.execResult.forEach(stat => {
+    console.log(stat.creation_date); // TypeScript autocomplete
+    console.log(stat.page_count);
+  });
+}
+```
+
+**返回值结构**：
+- SDK 返回：`{ execSuccess: boolean, execResult?: T[] }`（业务数据层）
+- HTTP 错误：抛出 `LovrabetError` 异常
+- 应用层职责：检查 `execSuccess` 状态，处理业务结果
+
+#### BFF API - Backend Functions
+
+```typescript
+const dashboard = await client.bff.execute({
+  scriptName: 'getUserDashboard',
+  params: { userId: '123' }
+});
+
+// With type safety
+interface DashboardData {
+  userCount: number;
+  orderCount: number;
+  totalAmount: number;
+}
+
+const dashboard = await client.bff.execute<DashboardData>({
+  scriptName: 'getUserDashboard',
+  params: { userId: '123' }
+});
+
+console.log(dashboard.userCount); // TypeScript autocomplete
+
+// Complete error handling
+try {
+  const result = await client.bff.execute({
+    scriptName: 'someEndpoint',
+    params: { /* ... */ }
+  });
+  // Use result directly (it's already the business data)
+} catch (error) {
+  if (error instanceof LovrabetError) {
+    console.error('BFF call failed:', error.message);
+  }
+}
+```
+
+**返回值结构**：
+- SDK 返回：业务数据对象（直接是业务数据层，不是包装器）
+- HTTP 错误：抛出 `LovrabetError` 异常
+- 应用层职责：直接使用返回的业务数据
+
+**Common Errors to Avoid:**
+- `where: { status: 'active' }` → Use `where: { status: { $eq: 'active' } }`
+- `fields: ['id']` → Use `select: ['id']`
+- `orderBy: 'createTime desc'` → Use `orderBy: [{ createTime: 'desc' }]`
+- `where: { name: 'LIKE %keyword%' }` → Use `where: { name: { $contain: 'keyword' } }`
+- SQL: Wrong format → Use `client.sql.execute({ sqlCode, params })`
+- BFF: Wrong format → Use `client.bff.execute({ scriptName, params })`
+- Filter: `getList()` → Use `filter()` (getList is deprecated)
+
+### 2. MCP SQL Workflow (STRICT ORDER)
+
+When creating custom SQL, follow this 5-step workflow:
+
+```
+Step 1 → Step 2 → Step 3 → Step 4 → Step 5
+Query → Generate → Validate → Save → Test
+```
+
+1. **Query**: Use `list_sql_queries` to check if SQL exists
+2. **Generate**: Use `get_dataset_detail` to get table structure FIRST
+3. **Validate**: Use `validate_sql_content` to verify syntax
+4. **Save**: Use `save_or_update_custom_sql` to save
+5. **Test**: Use `execute_custom_sql` to test execution
+
+**NEVER skip any step!**
+
+### 3. AntD UI Standards (No AI Style)
+
+**Prohibited:**
+- emoji: ✨🚀💡🎯📊🔥🎉
+- AI-style text: "太棒了！", "让我们开始吧！"
+- Fancy colors: #FF00FF, gradients
+- Exclamation marks in buttons
+- Cute terms: "小伙伴", "亲", "宝宝"
+
+**Required:**
+- Use AntD token colors
+- Professional text: "保存", "取消", "操作成功"
+- @ant-design/icons for icons (not emoji)
+
+### 4. Code Comments
+
+Always add dataset/table comments before SDK calls:
+
+```typescript
+// 数据集: 用户信息 | 数据表: users
+const users = await client.models.users.filter({
+  where: { status: { $eq: 'active' } },
+});
+```
+
+### 5. API Integration (Optional)
+
+Use `lovrabet api pull` to generate TypeScript types and API code:
+
+```bash
+# Pull API definitions for all datasets
+lovrabet api pull
+
+# Pull specific datasets
+lovrabet api pull --datasetcode customer,order
+
+# Specify output directory
+lovrabet api pull --output ./src/api
+```
+
+**Generated files structure:**
+```
+src/api/
+├── lovrabet/
+│   ├── index.ts           # Export entry
+│   ├── customer.ts        # Customer dataset API
+│   ├── order.ts           # Order dataset API
+│   └── types.ts           # TypeScript type definitions
+```
+
+**Usage:**
+```typescript
+// Import generated API and types
+import { customerApi } from '@/api/lovrabet';
+import type { Customer } from '@/api/lovrabet/types';
+
+// Use with type safety
+const customers = await customerApi.filter({
+  where: { status: { $eq: 'active' } },
+  currentPage: 1,
+  pageSize: 20,
+});
+
+customers.tableData.forEach((customer: Customer) => {
+  console.log(customer.name); // TypeScript autocomplete
+});
+```
+
+
+## 页面开发规范
+
+### 1. 页面顶部注释（强制）
+
+**所有通过 CLI 生成的页面必须在文件顶部包含以下注释**：
+
+```typescript
+/**
+ * Generated by Lovrabet CLI v{CliVersion}
+ * Created: {CreatedAt}
+ * Page: {PageName}
+ */
+```
+
+**注释格式说明**：
+- `CliVersion`：生成该页面的 CLI 版本号，便于追踪和兼容性检查
+- `CreatedAt`：页面创建时间，便于维护和追溯
+- `PageName`：页面路径（如 `user-profile`），用于菜单和路由
+
+### 2. displayName（强制）
+
+**所有页面组件导出时必须设置 `displayName`**，值为简洁的项目支持语言名称：
+
+```tsx
+export default function UserProfile() {
+  // ...
+}
+
+UserProfile.displayName = '用户详情';
+```
+
+**规则**：
+- `displayName` 使用项目支持的语言（中文、英文等），简洁明了
+- 推荐 2-4 个字的业务名称，如"用户列表"、"订单详情"、"User List"
+
+### 3. 保留注释要求
+
+**禁止删除或修改页面顶部的生成注释**。如需追加修改记录，使用 `@modified` 标签：
+
+```typescript
+// ✅ 正确：保留原始注释，追加自己的说明
+/**
+ * Generated by Lovrabet CLI v1.2.5-beta.2
+ * Created: 01-18-2026, 21:33:08
+ * Page: user-profile
+ *
+ * @modified 2025-01-20 添加批量删除功能
+ */
+
+// ❌ 错误：删除原始注释
+```
+
+
+## SDK 使用规范
+
+### 1. SDK 初始化
+
+```typescript
+import { createClient } from '@lovrabet/sdk';
+
+// 正确：使用 createClient 函数
+const client = createClient({
+  appCode: '<appcode>',
+  accessKey: process.env.LOVRABET_ACCESS_KEY, // 服务端
+  models: [
+    { tableName: 'users', datasetCode: 'abc123def456', alias: 'users' },
+    { tableName: 'orders', datasetCode: 'xyz789ghi012', alias: 'orders' },
+  ],
+});
+
+// 错误：使用 new 关键字
+const client = new LovrabetClient({ ... });
+
+// 错误：使用不存在的 mode 参数
+const client = createClient({ mode: 'webapi', ... });
+```
+
+### 2. SDK 返回值行为（核心原则！）
+
+**SDK 设计原则：始终返回 data（业务数据层），应用层自行处理**
+
+#### 核心原则
+
+- **成功时**：SDK 方法返回 API 响应中的 `data` 字段内容（业务数据层），而不是完整的响应包装器
+- **失败时**：抛出 `LovrabetError` 异常（HTTP 级别错误）
+- **业务状态检查**：应用层负责检查业务逻辑状态（如 `execSuccess`），提取业务结果（如 `execResult`）
+
+#### SDK 内部处理机制
+
+```typescript
+// SDK 内部：processResponse 处理响应
+export const processResponse = async <ResponseData>(response: Response) => {
+  const result = await response.json();
+  
+  if (!result.success) {
+    throw new LovrabetError(errorMessage, { ... });
+  }
+  
+  return result.data; // ✅ 只返回 data，不是完整的 response
+};
+```
+
+#### 使用示例
+
+```typescript
+// ✅ 正确：Filter API - 直接使用返回的数据
+try {
+  const result = await client.models.users.filter({
+    where: { status: { $eq: 'active' } },
+  });
+  console.log(result.tableData); // 直接使用，result 就是 data
+  console.log(result.total);
+} catch (error) {
+  if (error instanceof LovrabetError) {
+    console.error('HTTP 请求失败:', error.message);
+  }
+}
+
+// ✅ 正确：SQL API - 应用层检查业务状态
+try {
+  const data = await client.sql.execute({
+    sqlCode: 'fc8e7777-06e3847d',
+  });
+  
+  // 应用层负责检查业务逻辑状态
+  if (data.execSuccess && data.execResult) {
+    data.execResult.forEach(row => console.log(row));
+  } else {
+    console.error('SQL 查询失败');
+  }
+} catch (error) {
+  if (error instanceof LovrabetError) {
+    console.error('HTTP 请求失败:', error.message);
+  }
+}
+
+// ✅ 正确：BFF API - 直接使用返回的业务数据
+try {
+  const dashboard = await client.bff.execute({
+    scriptName: 'getUserDashboard',
+    params: { userId: '123' },
+  });
+  console.log(dashboard.userCount); // 直接使用业务数据
+} catch (error) {
+  if (error instanceof LovrabetError) {
+    console.error('HTTP 请求失败:', error.message);
+  }
+}
+
+// ❌ 错误：假设 SDK 返回完整响应对象
+const response = await client.sql.execute({ sqlCode: 'xxx' });
+if (response.success && response.data?.execSuccess) {
+  // SDK 不会返回这种嵌套结构
+}
+```
+
+### 3. Filter 查询构建规范
+
+#### 支持的条件操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$eq` | 等于 | `{ status: { $eq: 'active' } }` |
+| `$ne` | 不等于 | `{ status: { $ne: 'deleted' } }` |
+| `$gte` | 大于等于 | `{ age: { $gte: 18 } }` |
+| `$lte` | 小于等于 | `{ age: { $lte: 65 } }` |
+| `$gt` | 大于 | `{ price: { $gt: 100 } }` |
+| `$lt` | 小于 | `{ price: { $lt: 1000 } }` |
+| `$in` | 在集合内 | `{ type: { $in: ['A', 'B'] } }` |
+| `$contain` | 包含（模糊） | `{ name: { $contain: 'keyword' } }` |
+| `$startWith` | 以...开头 | `{ email: { $startWith: 'admin' } }` |
+| `$endWith` | 以...结尾 | `{ domain: { $endWith: '.com' } }` |
+| `$and` | 且（所有满足） | `{ $and: [条件1, 条件2] }` |
+| `$or` | 或（任一满足） | `{ $or: [条件1, 条件2] }` |
+
+#### 逻辑操作符示例
+
+```typescript
+// ✅ $and - 所有条件都要满足
+where: {
+  $and: [
+    { age: { $gte: 18 } },
+    { status: { $eq: 'active' } }
+  ]
+}
+
+// ✅ $or - 任一条件满足即可
+where: {
+  $or: [
+    { status: { $eq: 'pending' } },
+    { status: { $eq: 'processing' } }
+  ]
+}
+
+// ✅ 嵌套组合
+where: {
+  $and: [
+    { age: { $gte: 18 } },
+    {
+      $or: [
+        { country: { $eq: '中国' } },
+        { country: { $eq: '美国' } }
+      ]
+    }
+  ]
+}
+```
+
+#### 常见错误
+
+| 错误写法 | 正确写法 |
+|---------|---------|
+| `where: { status: 'active' }` | `where: { status: { $eq: 'active' } }` |
+| `fields: ['id']` | `select: ['id']` |
+| `orderBy: 'createTime desc'` | `orderBy: [{ createTime: 'desc' }]` |
+| `where: { name: 'LIKE %kw%' }` | `where: { name: { $contain: 'kw' } }` |
+| `page: 1, limit: 20` | `currentPage: 1, pageSize: 20` |
+
+### 4. 性能优化（禁止循环查询）
+
+**禁止在循环中调用单条查询 API**：
+
+```typescript
+// ❌ 错误：N+1 查询
+for (const order of orders) {
+  const user = await userDS.findOne({ id: order.user_id });
+  order.username = user?.username;
+}
+
+// ✅ 正确：批量查询
+const userIds = [...new Set(orders.map(o => o.user_id))];
+const userResult = await userDS.filter({
+  where: { id: { $in: userIds } }
+});
+const userMap = Object.fromEntries(
+  (userResult.tableData || []).map(u => [u.id, u])
+);
+for (const order of orders) {
+  order.username = userMap[order.user_id]?.username;
+}
+```
+
+**批量写入使用自定义 SQL**：
+
+```typescript
+// ❌ 错误：循环写入
+for (const item of items) {
+  await ds.create(item);
+}
+
+// ✅ 正确：使用自定义 SQL
+await context.client.sql.execute({
+  sqlCode: 'batch-insert-sql-code',
+  params: { items: JSON.stringify(items) }
+});
+```
+
+#### 文案示例
+
+```typescript
+// ✅ 正确：简洁专业
+const messages = {
+  success: '操作成功',
+  error: '操作失败',
+  confirm: '确定要删除这条记录吗？',
+  cancel: '取消',
+  submit: '提交',
+  save: '保存',
+  loading: '加载中...',
+  noData: '暂无数据',
+};
+
+// ❌ 错误：AI 味道
+const messages = {
+  success: '🎉 太棒了！操作成功！',
+  error: '哎呀，出错了 😢',
+  confirm: '你真的要删除吗？确定吗？',
+  cancel: '再想想吧~',
+  submit: '提交表单 ✨',
+  save: '保存更改 💾',
+  loading: '马上就好~请稍等 ⏳',
+  noData: '空空如也~还没有数据哦',
+};
+```
+
+### 颜色规范
+
+#### 使用 AntD Token
+
+```typescript
+// ✅ 正确：使用 AntD token
+import { theme } from 'antd';
+
+const { token } = theme.useToken();
+
+const styles = {
+  primary: token.colorPrimary,
+  success: token.colorSuccess,
+  error: token.colorError,
+  warning: token.colorWarning,
+  text: token.colorText,
+  border: token.colorBorder,
+};
+
+// ❌ 错误：自定义花哨颜色
+const styles = {
+  primary: '#FF00FF',      // 霓虹粉
+  success: '#00FF00',      // 亮绿色
+  accent: '#FFD700',       // 金色
+  gradient: 'linear-gradient(45deg, #ff6b6b, #feca57)',  // 渐变
+};
+```
+
+### 组件使用规范
+
+#### 按钮
+
+```typescript
+// ✅ 正确：简洁明了
+<Button type="primary" onClick={handleSave}>
+  保存
+</Button>
+<Button danger onClick={handleDelete}>
+  删除
+</Button>
+
+// ❌ 错误：花哨风格
+<Button type="primary" onClick={handleSave}>
+  💾 保存更改
+</Button>
+<Button danger onClick={handleDelete}>
+  🗑️ 哎呀，要删除吗？
+</Button>
+```
+
+#### 表格
+
+```typescript
+// ✅ 正确：使用 ProTable 或 Table + Pagination
+import { Table } from 'antd';
+
+<Table
+  columns={columns}
+  dataSource={data}
+  pagination={{
+    current: currentPage,
+    pageSize: pageSize,
+    total: total,
+    showSizeChanger: true,
+    showQuickJumper: true,
+    showTotal: (total) => `共 ${total} 条`,
+  }}
+/>
+
+// ❌ 错误：花哨的空状态
+<Table
+  columns={columns}
+  dataSource={data}
+  locale={{
+    emptyText: (
+      <div>
+        <span>🎭 </span>
+        <span>还没有数据哦~</span>
+      </div>
+    ),
+  }}
+/>
+```
+
+#### 消息提示
+
+```typescript
+// ✅ 正确：简洁专业
+import { message } from 'antd';
+
+message.success('保存成功');
+message.error('操作失败，请重试');
+message.warning('请填写必填项');
+message.info('正在处理...');
+
+// ❌ 错误：AI 味道
+message.success('🎉 太棒了！保存成功！');
+message.error('😱 哎呀出错了！请再试一次');
+message.warning('⚠️ 嘿！别忘了填写必填项哦');
+message.info('🔔 正在为你处理中，请稍等~');
+```
+
+#### Modal 确认
+
+```typescript
+// ✅ 正确：专业简洁
+import { Modal } from 'antd';
+
+Modal.confirm({
+  title: '确认删除',
+  content: '确定要删除这条记录吗？',
+  okText: '确定',
+  cancelText: '取消',
+  onOk: handleDelete,
+});
+
+// ❌ 错误：AI 味道
+Modal.confirm({
+  title: '🤔 确认要删除吗？',
+  content: '删除后可就找不回来了哦！你确定要删除这条记录吗？',
+  okText: '是的，删除！',
+  cancelText: '再想想~',
+  icon: <ExclamationCircleOutlined style={{ color: '#FFD700' }} />,
+});
+```
+
+### 表单规范
+
+```typescript
+// ✅ 正确：简洁清晰的错误提示
+<Form>
+  <Form.Item
+    name="username"
+    label="用户名"
+    rules={[
+      { required: true, message: '请输入用户名' },
+      { min: 3, message: '用户名至少3个字符' },
+    ]}
+  >
+    <Input placeholder="请输入用户名" />
+  </Form.Item>
+</Form>
+
+// ❌ 错误：花哨的错误提示
+<Form>
+  <Form.Item
+    name="username"
+    label="👤 用户名"
+    rules={[
+      { required: true, message: '哎呀！别忘了填写用户名哦~' },
+      { min: 3, message: '用户名太短啦，至少要3个字符呢！' },
+    ]}
+  >
+    <Input placeholder="输入用户名试试看~ ✨" />
+  </Form.Item>
+</Form>
+```
+
+### 空状态规范
+
+```typescript
+// ✅ 正确：简洁专业
+import { Empty } from 'antd';
+
+<Empty
+  description="暂无数据"
+  image={Empty.PRESENTED_IMAGE_SIMPLE}
+/>
+
+// 带操作按钮
+<Empty
+  description="暂无数据"
+  image={Empty.PRESENTED_IMAGE_SIMPLE}>
+  <Button type="primary">创建数据</Button>
+</Empty>
+
+// ❌ 错误：AI 味道
+<Empty
+  description={
+    <div>
+      <div>🎭 还没有数据哦~</div>
+      <div style={{ fontSize: 12, color: '#999' }}>
+        快来创建第一条数据吧！✨
+      </div>
+    </div>
+  }
+/>
+```
+
+### 图标使用规范
+
+```typescript
+// ✅ 正确：使用 @ant-design/icons
+import {
+  UserOutlined,
+  DeleteOutlined,
+  EditOutlined,
+  SearchOutlined,
+} from '@ant-design/icons';
+
+// 按钮图标（可选，保持简洁）
+<Button icon={<PlusOutlined />}>新建</Button>
+
+// ❌ 错误：使用 emoji 作为图标
+<Button>🆕 新建</Button>
+<Button>✏️ 编辑</Button>
+<Button>🗑️ 删除</Button>
+```
+
+### 检查清单
+
+在编写 UI 代码时，确保：
+
+- [ ] 没有 emoji
+- [ ] 没有感叹号
+- [ ] 文案简洁专业
+- [ ] 使用 AntD token 颜色
+- [ ] 使用 @ant-design/icons 而非 emoji
+- [ ] 按钮文案为动词（保存/删除/编辑）
+- [ ] 提示文案中性（操作成功/操作失败）
+- [ ] 没有过度动画效果
+
+
+
+## 禁止事项
+
+### 页面相关
+1. **不要删除页面顶部注释** - CLI 生成的注释必须保留，用于版本追踪和维护
+2. **不要修改页面顶部注释内容** - 如需追加说明，使用 `@modified` 标签
+3. **不要使用不规范的组件命名** - 组件名必须使用 PascalCase
+
+### SDK 相关
+1. **不要臆测 API** - 使用不存在的方法或参数
+2. **不要臆测字段** - 未通过 MCP 确认字段是否存在
+3. **不要混淆认证模式** - 在错误的模式使用功能（如 OpenAPI 模式使用 delete）
+4. **不要忽略错误处理** - 所有 SDK 调用必须 try-catch
+5. **不要假设返回值结构** - 注意不同方法返回值的差异
+6. **不要在循环中调用 API** - 使用 Promise.all 批量处理
+7. **不要在每次渲染时调用 API** - 使用 useEffect 控制
+8. **不要使用 getList()** - 列表查询必须使用 filter()
+
+### Filter 查询相关
+9. **不要忘记使用操作符** - where 条件必须使用 `$eq`、`$gte` 等操作符
+10. **不要使用错误的参数名** - 是 `select` 不是 `fields`，是 `orderBy` 不是 `sortList`
+11. **不要使用 SQL 语法** - 不支持 `LIKE`、`>=` 等，必须用 `$contain`、`$gte` 等
+12. **不要忽略参数格式** - `orderBy` 和 `select` 必须是数组，不能是字符串
+
+### SQL 相关
+13. **不要跳过 MCP SQL 工作流步骤** - 必须按顺序：查询→生成→验证→保存→测试
+14. **不要忘记检查 execSuccess** - `client.sql.execute()` 返回的数据必须检查 `execSuccess` 状态（应用层职责）
+15. **不要假设 sql.execute 返回数组** - 返回的是 `{ execSuccess, execResult }` 对象（业务数据层）
+16. **不要假设SQL code存在 = SQL正确** - 必须验证SQL内容中的表名和字段名与实际数据库结构匹配
+17. **不要仅检查SQL code是否存在** - 必须获取SQL内容，对比表名和字段名，修复SQL内容本身
+18. **不要在自定义 SQL 中使用 INSERT/UPDATE/DELETE** - 只允许 SELECT 查询
+19. **不要假设 SDK 返回完整响应对象** - SDK 返回的是 `data`（业务数据层），不是 `{ success, data }` 结构
+
+### UI 相关
+20. **不要使用 emoji** - 包括按钮、标题、提示文案等所有地方
+21. **不要使用 AI 味道的文案** - 如"太棒了！"、"让我们开始吧！"、"试试看！"
+22. **不要使用花哨的颜色** - 只使用 AntD token 颜色
+23. **不要使用感叹号** - 标题和按钮文案中禁止使用 "!"
+24. **不要使用自定义动画** - 只使用 AntD 内置动画
+25. **不要使用非专业称呼** - 如"小伙伴"、"亲"、"宝宝" 等
+
+
+
+## 快速参考
+
+### SDK 方法返回值
+
+| 方法 | 返回结构 | 参数格式 | 认证限制 |
+|------|----------|----------|----------|
+| `filter()` | `{ tableData, total }` | `filter(params)` | OpenAPI + WebAPI |
+| `getOne()` | 单个对象 | `getOne(id)` 或 `getOne({ id })` | OpenAPI + WebAPI |
+| `create/update()` | 操作结果对象 | `create(data)` / `update(id, data)` | OpenAPI + WebAPI |
+| `delete()` | 删除结果 | `delete(id)` | 仅 WebAPI |
+| `getSelectOptions()` | `[{ label, value }]` | `getSelectOptions(params)` | 仅 WebAPI |
+| `sql.execute()` | `{ execSuccess, execResult }` | `execute({ sqlCode, params })` | OpenAPI + WebAPI |
+| `bff.execute()` | 业务数据对象 | `execute({ scriptName, params })` | OpenAPI + WebAPI |
+| `user.getList()` | `User[]` | `getList()` | 仅 WebAPI |
+
+**注意**：
+- 所有方法返回的都是 `data`（业务数据层），不是完整的响应对象
+- SQL 和 BFF 的返回值需要应用层检查业务状态（如 `execSuccess`）
+
+### 记住
+
+#### 页面开发
+- **保留顶部注释**：CLI 生成的注释包含版本、时间、页面名，禁止删除
+- **组件命名 PascalCase**：`UserProfile` 而非 `userProfile`
+- **追加修改说明**：使用 `@modified` 标签记录手动修改
+
+#### SDK 核心
+- **返回值原则**：SDK 始终返回 `data`（业务数据层），不是完整的响应包装器
+- **成功时**：返回 API 响应的 `data` 字段内容
+- **失败时**：抛出 `LovrabetError` 异常（HTTP 级别错误）
+- **业务状态检查**：应用层负责检查业务逻辑状态（如 `execSuccess`）
+- **所有调用**：必须用 `try-catch` 包裹
+- **先获取元数据**：使用 MCP 确认字段存在
+
+#### Filter 查询
+- **列表查询用 filter**：必须使用 `filter()` 方法，禁止使用 `getList()`
+- **注意参数名**：`select`（不是 `fields`），`orderBy`（不是 `sortList`），`currentPage`/`pageSize`（不是 `page`/`limit`）
+- **必须使用操作符**：`where: { status: { $eq: 'active' } }`，不是 `where: { status: 'active' }`
+- **参数必须是数组**：`select: ['id', 'name']`，不是 `select: 'id,name'`
+
+#### SQL API
+- **使用方式**：`client.sql.execute({ sqlCode, params })` - 对象参数格式
+- **返回值检查**：应用层必须检查 `execSuccess` 状态
+
+#### BFF API
+- **使用方式**：`client.bff.execute({ scriptName, params })` - 直接客户端访问
+- **返回值**：直接是业务数据对象，无需检查 `execSuccess`
+
+#### MCP SQL 流程
+- **严格执行 5 步流程**：查询→生成→验证→保存→测试
+- **SQL验证必须系统化**：创建或使用SQL时，必须对比SQL内容与实际表结构，验证表名和字段名
+- **SQL code存在 ≠ SQL正确**：必须获取SQL内容，验证表名、字段名、JOIN条件是否正确
+
+#### UI 规范
+- **禁止 emoji**：所有地方都不使用 emoji
+- **文案简洁专业**："保存"而不是"保存吧！"，"操作成功"而不是"太棒了！"
+- **使用 AntD token**：颜色使用 `token.colorPrimary` 等，不自定义花哨颜色
+
+
+
+## 示例代码说明
+
+**重要**：本文档中所有代码示例使用的是**占位符**（用 `<>` 包裹），而非真实字段名或值。
+
+### 占位符说明
+
+- `<appcode>` - 应用代码，需替换为实际的 appcode
+- `<modelName>` - 模型名称，如 `users`、`orders` 等
+- `<dataset-code>` - 数据集代码
+- `<table-name>` - 表名
+- `<table-alias>` - 表别名（SQL 中使用）
+- `<id>` - 记录 ID
+- `<field>`, `<field1>`, `<field2>` - 字段名称
+- `<fieldName>` - 字段名称（用于排序等）
+- `<field-name>` - 具体字段名
+- `<wrong-field>`, `<correct-field>` - 错误/正确的字段名（SQL 验证示例）
+- `<wrong-pk>`, `<correct-pk>` - 错误/正确的主键字段名
+- `<wrong-table>`, `<correct-table>` - 错误/正确的表名
+- `<value>`, `<value1>`, `<value2>` - 字段值
+- `<sql-code>` - SQL 代码
+- `<sql-name>` - SQL 名称
+- `<value-field>` - 用作选项值的字段
+- `<label-field>` - 用作显示文本的字段
+
+### 如何使用
+
+在实际编写代码前，**必须**：
+
+1. 使用 MCP 工具获取数据集详情
+2. 查看实际的字段列表和字段类型
+3. 用真实的字段名替换占位符
+4. 确保字段类型匹配
+
+**切记**：不要直接复制示例代码中的占位符到实际项目中！
+
+
+**学习资源**：
+- [官方文档](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)
+
+---
+
+## 更新日志
+
+### v2.1.0 (2025-01-24)
+- ✨ **完善 SDK 返回值行为说明** - 明确 SDK 返回 `data`（业务数据层），应用层负责检查业务状态
+- ✨ **补充 SQL API 详细说明** - 明确返回值结构和应用层职责，添加类型安全示例
+- ✨ **补充 BFF API 详细说明** - 添加完整的使用示例和错误处理
+- ✨ **补充 Filter API 逻辑操作符** - 添加 `$and`、`$or` 嵌套组合示例
+- ✨ **新增 API 集成指南** - 添加 `lovrabet api pull` 使用说明
+- 📝 更新"快速参考"和"记住"部分，明确 SDK 返回值结构和使用方式
+- 🧹 **清理向后兼容说明** - 移除所有向后兼容和别名用法说明，避免大模型产生幻觉
+
+### v2.0.0 (2025-01-17)
+- ✨ **新增 SDK Filter 查询构建规范（强制）** - 详细说明 filter 的正确用法，列举 10 种常见错误
+- ✨ **新增 MCP SQL 创建工作流（强制顺序）** - 明确 5 步流程顺序：查询→生成→验证→保存→测试
+- ✨ **新增 AntD UI 开发规范（禁止 AI 风格）** - 禁止 emoji、AI 味道文案、花哨颜色等
+- 📝 重组禁止事项为 4 大类（SDK / Filter / SQL / UI），共 24 条
+- 📝 更新"记住"部分，分 4 大类总结关键要点
+
+### v1.0.0 (2025-11-15)
+- 📋 完整的 SDK 使用规范
+- 🔧 MCP Tools 使用指南
+- ⚡ 性能优化建议
+- 🛡️ 错误处理最佳实践
+
+---
+
+> update：2025-01-24
+