@lovrabet/cli 1.2.4 → 1.2.5-beta.1

package/templates/skills/.shared/guides/05-api-integration/guide.md

@@ -0,0 +1,327 @@
+# API 集成指南
+
+> **目标**：使用 `lovrabet api pull` 集成数据集 API，自动生成类型和调用代码
+
+## 🎯 为什么这个技能重要？
+
+手动编写 API 调用代码容易出错：
+- 字段名可能拼写错误
+- 类型定义不完整
+- 数据集更新后代码不同步
+
+使用 `lovrabet api pull` 可以：
+- 自动生成 TypeScript 类型
+- 生成标准的 API 调用代码
+- 保持代码与数据集定义同步
+
+---
+
+## 🚀 快速开始
+
+### 第1步：初始化项目配置
+
+```bash
+# 如果还没有初始化 Lovrabet 配置
+lovrabet init --appcode <你的appcode>
+```
+
+### 第2步：拉取 API 定义
+
+```bash
+# 拉取所有数据集的 API 定义
+lovrabet api pull
+
+# 只拉取指定的数据集
+lovrabet api pull --datasetcode customer,order
+
+# 指定输出目录
+lovrabet api pull --output ./src/api
+```
+
+### 第3步：使用生成的 API
+
+```typescript
+// 引入生成的 API 文件
+import { customerApi, orderApi } from '@/api/lovrabet';
+
+// 使用自动生成的类型
+import type { Customer, Order } from '@/api/lovrabet/types';
+
+// 调用 API
+const customers = await customerApi.filter({
+  where: { status: { $eq: 'active' } },
+  select: ['id', 'name', 'email'],
+  currentPage: 1,
+  pageSize: 20,
+});
+
+// 类型安全
+customers.tableData.forEach((customer: Customer) => {
+  console.log(customer.name); // TypeScript 会提供完整的类型提示
+});
+```
+
+---
+
+## 📋 工作流详解
+
+### 完整的 API 集成流程
+
+```
+1. lovrabet init         初始化配置
+2. lovrabet api pull     拉取 API 定义
+3. 编写业务代码          使用生成的 API
+4. 数据集更新后          重新运行 api pull
+```
+
+### 第1步：初始化配置
+
+```bash
+# 创建 .lovrabetrc 配置文件
+lovrabet init
+
+# 或指定 appcode
+lovrabet init --appcode app-xxx
+```
+
+生成的 `.lovrabetrc` 文件：
+
+```json
+{
+  "appcode": "app-xxx",
+  "env": "online",
+  "outputDir": "./src/api"
+}
+```
+
+### 第2步：拉取 API 定义
+
+```bash
+# 基本用法
+lovrabet api pull
+
+# 完整参数
+lovrabet api pull \
+  --appcode app-xxx \
+  --env online \
+  --output ./src/api \
+  --datasetcode customer,order
+```
+
+参数说明：
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--appcode` | 应用代码 | 从 .lovrabetrc 读取 |
+| `--env` | 环境 (online/daily) | online |
+| `--output` | 输出目录 | ./src/api |
+| `--datasetcode` | 指定数据集（逗号分隔） | 全部 |
+
+### 第3步：查看生成的文件
+
+```
+src/api/
+├── lovrabet/
+│   ├── index.ts           # 导出入口
+│   ├── customer.ts        # 客户数据集 API
+│   ├── order.ts           # 订单数据集 API
+│   └── types.ts           # TypeScript 类型定义
+```
+
+### 第4步：使用生成的代码
+
+```typescript
+// 引入 API 和类型
+import { customerApi } from '@/api/lovrabet';
+import type { Customer } from '@/api/lovrabet/types';
+
+// 在组件中使用
+function CustomerList() {
+  const [customers, setCustomers] = useState<Customer[]>([]);
+
+  useEffect(() => {
+    // 数据集: 客户 | 数据表: customer
+    customerApi.filter({
+      where: { status: { $eq: 'active' } },
+      currentPage: 1,
+      pageSize: 20,
+    }).then(result => {
+      setCustomers(result.tableData);
+    });
+  }, []);
+
+  return (
+    <Table>
+      {customers.map(c => (
+        <tr key={c.id}>
+          <td>{c.name}</td>
+          <td>{c.email}</td>
+        </tr>
+      ))}
+    </Table>
+  );
+}
+```
+
+---
+
+## 🔄 数据集更新后
+
+当数据集定义发生变化时（新增字段、修改类型等）：
+
+```bash
+# 重新拉取 API 定义
+lovrabet api pull
+
+# 检查生成的类型是否更新
+cat src/api/lovrabet/types.ts
+```
+
+**注意**：重新生成会覆盖现有文件，如果需要自定义修改，请创建单独的封装文件。
+
+---
+
+## ⚠️ 常见问题
+
+### 问题 1：提示 "未找到 appcode 配置"
+
+```bash
+# 解决方法：先运行 init
+lovrabet init --appcode <你的appcode>
+```
+
+### 问题 2：生成的类型为空
+
+检查：
+1. appcode 是否正确
+2. 是否有权限访问该数据集
+3. 数据集是否已发布
+
+```bash
+# 查看详细日志
+lovrabet logs
+```
+
+### 问题 3：如何自定义 API 调用
+
+创建单独的封装文件，不要直接修改生成的文件：
+
+```typescript
+// src/api/customer.ts (自定义封装)
+import { customerApi as baseCustomerApi } from '@/api/lovrabet';
+import type { Customer } from '@/api/lovrabet/types';
+
+export const customerApi = {
+  // 使用生成的 API
+  ...baseCustomerApi,
+
+  // 自定义方法
+  async getActiveCustomers(page = 1) {
+    return baseCustomerApi.filter({
+      where: { status: { $eq: 'active' } },
+      currentPage: page,
+      pageSize: 20,
+    });
+  },
+
+  async searchCustomers(keyword: string) {
+    return baseCustomerApi.filter({
+      where: {
+        $or: [
+          { name: { $contain: keyword } },
+          { email: { $contain: keyword } },
+        ],
+      },
+    });
+  },
+};
+```
+
+---
+
+## 📝 实战示例
+
+### 示例 1：用户管理页面
+
+```bash
+# 1. 拉取用户数据集 API
+lovrabet api pull --datasetcode users
+
+# 2. 创建页面组件
+```
+
+```typescript
+// src/pages/users/index.tsx
+import { useState, useEffect } from 'react';
+import { Table, Button, message } from 'antd';
+import { usersApi } from '@/api/lovrabet';
+import type { User } from '@/api/lovrabet/types';
+
+export function UserList() {
+  const [users, setUsers] = useState<User[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [pagination, setPagination] = useState({ current: 1, pageSize: 20, total: 0 });
+
+  const loadUsers = async (page = 1) => {
+    setLoading(true);
+    try {
+      // 数据集: 用户 | 数据表: users
+      const result = await usersApi.filter({
+        currentPage: page,
+        pageSize: 20,
+        select: ['id', 'username', 'email', 'status', 'createTime'],
+        orderBy: [{ createTime: 'desc' }],
+      });
+      setUsers(result.tableData);
+      setPagination({ ...pagination, current: page, total: result.total });
+    } catch (error) {
+      message.error('加载失败');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    loadUsers();
+  }, []);
+
+  return (
+    <div>
+      <Table
+        dataSource={users}
+        loading={loading}
+        rowKey="id"
+        pagination={{
+          ...pagination,
+          onChange: (page) => loadUsers(page),
+        }}
+        columns={[
+          { title: '用户名', dataIndex: 'username' },
+          { title: '邮箱', dataIndex: 'email' },
+          { title: '状态', dataIndex: 'status' },
+          { title: '创建时间', dataIndex: 'createTime' },
+        ]}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## ✅ 自检清单
+
+使用 API 集成时，确认：
+
+- [ ] 已运行 `lovrabet init` 初始化配置
+- [ ] 已运行 `lovrabet api pull` 生成 API
+- [ ] 生成的类型文件包含正确的类型定义
+- [ ] 代码中添加了数据集和数据表注释
+- [ ] 使用 filter() 时遵循查询规范
+
+---
+
+## 🔗 相关资源
+
+- [Pull 工作流](./pull-workflow.md) - api pull 详细流程
+- [类型生成](./type-generation.md) - TypeScript 类型生成说明

package/templates/skills/.shared/guides/06-menu-management/guide.md

@@ -0,0 +1,305 @@
+# 菜单管理指南
+
+> **目标**：使用 `lovrabet menu sync` 和 `menu update` 管理应用菜单
+
+## 🎯 为什么这个技能重要？
+
+菜单是应用的导航结构，需要与平台保持同步：
+- 新增页面后需要同步到平台
+- 菜单图标需要更新到 CDN
+- 菜单配置错误会导致页面无法访问
+
+---
+
+## 📋 两个命令
+
+| 命令 | 作用 | 使用场景 |
+|------|------|---------|
+| `lovrabet menu sync` | 同步菜单到平台 | 新增/修改页面后 |
+| `lovrabet menu update` | 更新菜单 CDN 资源 | 更新菜单图标后 |
+
+---
+
+## 🚀 Menu Sync - 同步菜单
+
+### 何时使用
+
+- 创建了新页面
+- 修改了页面路由
+- 调整了菜单结构
+- 修改了菜单权限配置
+
+### 使用方法
+
+```bash
+# 基本用法
+lovrabet menu sync
+
+# 查看同步状态
+lovrabet menu sync --dry-run
+```
+
+### 工作流程
+
+```
+1. 扫描本地页面结构
+2. 分析路由配置
+3. 生成菜单配置
+4. 同步到 Lovrabet 平台
+5. 确认同步结果
+```
+
+### 菜单配置示例
+
+在页面文件中配置菜单：
+
+```typescript
+// src/pages/dashboard/index.tsx
+export default function Dashboard() {
+  return <div>仪表盘</div>;
+}
+
+// 菜单配置（通过文件注释或单独配置）
+/**
+ * @menu
+ * {
+ *   "title": "仪表盘",
+ *   "icon": "DashboardOutlined",
+ *   "path": "/dashboard",
+ *   "order": 1
+ * }
+ */
+```
+
+或者在 `.lovrabetrc` 中配置：
+
+```json
+{
+  "appcode": "app-xxx",
+  "menus": [
+    {
+      "title": "仪表盘",
+      "path": "/dashboard",
+      "icon": "DashboardOutlined",
+      "order": 1
+    },
+    {
+      "title": "用户管理",
+      "path": "/users",
+      "icon": "UserOutlined",
+      "order": 2
+    }
+  ]
+}
+```
+
+### 同步结果
+
+```bash
+$ lovrabet menu sync
+
+正在扫描页面...
+找到 5 个页面
+
+正在同步菜单...
+✓ 仪表盘 → /dashboard
+✓ 用户管理 → /users
+✓ 订单管理 → /orders
+✓ 系统设置 → /settings
+✓ 数据统计 → /statistics
+
+菜单同步成功！
+```
+
+---
+
+## 🔄 Menu Update - 更新 CDN 资源
+
+### 何时使用
+
+- 更新了菜单图标
+- 修改了菜单样式
+- 更新了静态资源
+
+### 使用方法
+
+```bash
+# 基本用法
+lovrabet menu update
+
+# 指定环境
+lovrabet menu update --env daily
+```
+
+### 工作流程
+
+```
+1. 打包菜单相关静态资源
+2. 上传到 CDN
+3. 更新平台配置
+4. 验证资源可访问
+```
+
+---
+
+## 📝 完整示例
+
+### 场景：添加新页面后同步菜单
+
+```bash
+# 1. 创建新页面
+lovrabet add page
+
+# 输入页面信息:
+# 页面名称: 产品管理
+# 路由路径: /products
+# 菜单图标: ShoppingOutlined
+
+# 2. 同步菜单到平台
+lovrabet menu sync
+
+# 输出:
+# 正在扫描页面...
+# 找到 6 个页面
+#
+# 正在同步菜单...
+# ✓ 仪表盘 → /dashboard
+# ✓ 用户管理 → /users
+# ✓ 订单管理 → /orders
+# ✓ 产品管理 → /products  [新增]
+# ✓ 系统设置 → /settings
+# ✓ 数据统计 → /statistics
+#
+# 菜单同步成功！
+
+# 3. 如果有自定义菜单图标，更新 CDN
+lovrabet menu update
+```
+
+---
+
+## ⚠️ 常见问题
+
+### 问题 1：菜单同步后看不到新菜单
+
+检查：
+1. 是否已清除浏览器缓存
+2. 是否需要重新登录
+3. 菜单权限配置是否正确
+
+```bash
+# 清除缓存并重新登录
+# 1. 退出登录
+lovrabet logout
+
+# 2. 重新登录
+lovrabet auth
+```
+
+### 问题 2：菜单图标不显示
+
+```bash
+# 更新 CDN 资源
+lovrabet menu update
+
+# 检查图标名称是否正确
+# 使用 Ant Design 图标名称，如:
+# - DashboardOutlined
+# - UserOutlined
+# - ShoppingOutlined
+```
+
+### 问题 3：菜单顺序不对
+
+在 `.lovrabetrc` 中调整 `order` 字段：
+
+```json
+{
+  "menus": [
+    { "title": "仪表盘", "order": 1 },
+    { "title": "用户管理", "order": 2 },
+    { "title": "产品管理", "order": 3 }
+  ]
+}
+```
+
+然后重新同步：
+
+```bash
+lovrabet menu sync
+```
+
+---
+
+## 📋 菜单配置规范
+
+### 图标使用
+
+使用 Ant Design 图标名称：
+
+```typescript
+import {
+  DashboardOutlined,
+  UserOutlined,
+  ShoppingOutlined,
+  SettingOutlined,
+  FileTextOutlined,
+  BarChartOutlined,
+} from '@ant-design/icons';
+```
+
+| 功能 | 推荐图标 |
+|------|---------|
+| 仪表盘 | DashboardOutlined |
+| 用户管理 | UserOutlined |
+| 订单/交易 | FileTextOutlined |
+| 产品/商品 | ShoppingOutlined |
+| 数据统计 | BarChartOutlined |
+| 系统设置 | SettingOutlined |
+
+### 路由规范
+
+```typescript
+// ✅ 正确：使用小写和连字符
+/products
+/user-management
+/order-list
+
+// ❌ 错误：使用驼峰或大写
+/Products
+/userManagement
+/OrderList
+```
+
+### 标题规范
+
+```typescript
+// ✅ 正确：简洁明了
+"仪表盘"
+"用户管理"
+"订单列表"
+
+// ❌ 错误：冗余或过于简单
+"系统仪表盘页面"
+"用户"
+"订单"
+```
+
+---
+
+## ✅ 自检清单
+
+菜单同步前，确认：
+
+- [ ] 页面路由已正确配置
+- [ ] 菜单标题简洁明了
+- [ ] 使用了正确的 Ant Design 图标名称
+- [ ] 菜单顺序（order）已设置
+- [ ] 权限配置正确（如需要）
+
+---
+
+## 🔗 相关资源
+
+- [Sync 工作流](./sync-workflow.md) - menu sync 详细流程
+- [Update 工作流](./update-workflow.md) - menu update 详细流程