@builder6/pages 3.2.3 → 3.2.12

package/README.md

@@ -1,21 +1,438 @@
 # Builder6 Pages Module
 
+Builder6 Pages 模块为 Builder6 平台提供动态页面管理和渲染能力，支持使用 Amis 低代码框架构建页面，以及 Liquid 模板引擎进行页面定制。该模块是 Builder6 低代码平台的前端核心组件。
 
-## Steedos Dependencies
+## 功能特性
 
-```yml
-objects:
-  - b6_pages
-  - b6_projects
-``` 
+- **动态页面管理**: 通过数据库配置管理页面，无需重启服务
+- **Amis 集成**: 集成百度 Amis 低代码前端框架
+- **Liquid 模板**: 支持 LiquidJS 模板引擎进行页面定制
+- **Tailwind CSS**: 内置 Tailwind CSS 支持，快速样式开发
+- **组件库集成**: 支持 Steedos Widgets 组件库
+- **页面缓存**: LRU 缓存提升页面加载性能
+- **数据加载器**: DataLoader 优化数据查询性能
+- **项目管理**: 支持页面项目分组管理
+- **响应式设计**: 支持移动端和桌面端适配
+- **实时预览**: 页面编辑器支持实时预览
+
+## 安装
+
+```bash
+npm install @builder6/pages
+```
+
+或
+
+```bash
+yarn add @builder6/pages
+```
 
-## Env Variables
+## 环境变量
 
-```shell
+### 基本配置
+
+```bash
+# 应用根 URL
 B6_ROOT_URL=http://localhost:5100
+
+# Amis 包名称（npm 包名或本地路径）
 B6_AMIS_PACKAGE=amis
+
+# Amis 版本
 B6_AMIS_VERSION=6.10.0
+
+# UNPKG CDN 地址（用于加载前端资源）
 B6_UNPKG_URL=https://unpkg.steedos.cn
-# B6_WIDGETS_VERSION=6.3.11-beta.19
+```
+
+### 组件库配置
+
+```bash
+# Steedos Widgets 版本
+B6_WIDGETS_VERSION=6.3.11
+
+# 使用特定的组件库包
 # B6_WIDGETS_VERSION=@steedos-widgets/liveblocks
+
+# 自定义组件库 URL
+B6_WIDGETS_URL=https://unpkg.steedos.cn/@steedos-widgets/core@latest
+```
+
+### 高级配置
+
+```bash
+# 页面缓存大小（条目数）
+B6_PAGES_CACHE_SIZE=500
+
+# 启用页面编辑器
+B6_PAGES_EDITOR_ENABLED=true
+
+# 默认主题
+B6_PAGES_THEME=default
+
+# 自定义 CSS URL
+B6_PAGES_CUSTOM_CSS_URL=https://example.com/custom.css
+```
+
+## 使用示例
+
+### 在 NestJS 应用中集成
+
+```typescript
+import { Module } from '@nestjs/common';
+import { PagesModule } from '@builder6/pages';
+
+@Module({
+  imports: [PagesModule],
+})
+export class AppModule {}
+```
+
+### 创建页面
+
+```typescript
+import { PagesService } from '@builder6/pages';
+
+constructor(private pagesService: PagesService) {}
+
+async createPage() {
+  const page = await this.pagesService.create({
+    name: 'dashboard',
+    label: '仪表板',
+    is_system: false,
+    type: 'amis', // 'amis' 或 'liquid'
+    schema: {
+      type: 'page',
+      title: '仪表板',
+      body: [
+        {
+          type: 'service',
+          api: '/api/v6/stats',
+          body: [
+            {
+              type: 'cards',
+              source: '$items',
+              card: {
+                body: [
+                  {
+                    type: 'tpl',
+                    tpl: '${label}: ${value}'
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      ]
+    },
+    project: 'project_id'
+  });
+  
+  return page;
+}
+```
+
+### 使用 Amis Schema
+
+```typescript
+// 表单页面示例
+const formPageSchema = {
+  type: 'page',
+  title: '用户表单',
+  body: {
+    type: 'form',
+    api: 'post:/api/v6/users',
+    body: [
+      {
+        type: 'input-text',
+        name: 'name',
+        label: '姓名',
+        required: true
+      },
+      {
+        type: 'input-email',
+        name: 'email',
+        label: '邮箱',
+        required: true
+      },
+      {
+        type: 'select',
+        name: 'role',
+        label: '角色',
+        options: [
+          { label: '管理员', value: 'admin' },
+          { label: '用户', value: 'user' }
+        ]
+      }
+    ]
+  }
+};
+
+// CRUD 页面示例
+const crudPageSchema = {
+  type: 'page',
+  title: '用户列表',
+  body: {
+    type: 'crud',
+    api: '/api/v6/users',
+    columns: [
+      { name: 'name', label: '姓名' },
+      { name: 'email', label: '邮箱' },
+      { name: 'role', label: '角色', type: 'mapping', map: {
+        admin: '<span class="label label-success">管理员</span>',
+        user: '<span class="label label-info">用户</span>'
+      }}
+    ],
+    bulkActions: [
+      {
+        label: '批量删除',
+        actionType: 'ajax',
+        api: 'delete:/api/v6/users/${ids|raw}',
+        confirmText: '确定要删除？'
+      }
+    ]
+  }
+};
+```
+
+### 使用 Liquid 模板
+
+```typescript
+async renderLiquidPage(pageId: string, context: any) {
+  // 页面内容使用 Liquid 模板
+  const template = `
+    <div class="container mx-auto p-4">
+      <h1 class="text-2xl font-bold">{{ title }}</h1>
+      <ul>
+      {% for item in items %}
+        <li>{{ item.name }} - {{ item.description }}</li>
+      {% endfor %}
+      </ul>
+    </div>
+  `;
+  
+  const rendered = await this.pagesService.renderLiquid(template, context);
+  return rendered;
+}
+```
+
+## 数据模型
+
+### b6_pages 对象
+
+页面配置存储在 `b6_pages` 对象中：
+
+```typescript
+interface Page {
+  _id: string;
+  name: string;               // 页面唯一标识
+  label: string;              // 页面显示名称
+  description?: string;       // 页面描述
+  is_system: boolean;         // 是否系统页面
+  type: 'amis' | 'liquid';   // 页面类型
+  schema?: object;            // Amis schema（type=amis时）
+  template?: string;          // Liquid 模板（type=liquid时）
+  path?: string;              // 页面路径
+  icon?: string;              // 页面图标
+  visible?: boolean;          // 是否可见
+  sort?: number;              // 排序
+  project?: string;           // 所属项目
+  owner: string;              // 所有者
+  space: string;              // 租户空间
+  created: Date;
+  modified: Date;
+}
+```
+
+### b6_projects 对象
+
+项目配置存储在 `b6_projects` 对象中：
+
+```typescript
+interface Project {
+  _id: string;
+  name: string;               // 项目名称
+  label: string;              // 项目显示名称
+  description?: string;       // 项目描述
+  owner: string;              // 所有者
+  members?: string[];         // 项目成员
+  space: string;              // 租户空间
+  created: Date;
+  modified: Date;
+}
+```
+
+## API 端点
+
+模块提供以下主要 API 端点：
+
+### 页面管理
+
+- **GET `/api/v6/pages`**: 获取页面列表
+- **GET `/api/v6/pages/:id`**: 获取页面详情
+- **POST `/api/v6/pages`**: 创建页面
+- **PUT `/api/v6/pages/:id`**: 更新页面
+- **DELETE `/api/v6/pages/:id`**: 删除页面
+
+### 页面渲染
+
+- **GET `/page/:name`**: 渲染页面（根据 name）
+- **GET `/page/:projectId/:name`**: 渲染项目下的页面
+
+### 项目管理
+
+- **GET `/api/v6/projects`**: 获取项目列表
+- **GET `/api/v6/projects/:id`**: 获取项目详情
+- **POST `/api/v6/projects`**: 创建项目
+- **PUT `/api/v6/projects/:id`**: 更新项目
+- **DELETE `/api/v6/projects/:id`**: 删除项目
+
+## Amis 集成
+
+### 使用 Amis 组件
+
+Builder6 Pages 集成了完整的 Amis 组件库，支持所有 Amis 组件：
+
+- **布局组件**: Page, Container, Grid, Flex, Wrapper
+- **表单组件**: Form, Input, Select, DatePicker, Upload
+- **展示组件**: Table, Cards, List, Chart, Image
+- **功能组件**: Service, Dialog, Drawer, Wizard
+- **交互组件**: Button, Action, Nav, Tabs
+
+### Amis API 配置
+
+```typescript
+// 配置 API 数据源
+const pageSchema = {
+  type: 'page',
+  body: {
+    type: 'service',
+    api: {
+      method: 'get',
+      url: '/api/v6/users',
+      headers: {
+        'Authorization': 'Bearer ${token}'
+      }
+    },
+    body: [
+      {
+        type: 'table',
+        source: '$items',
+        columns: [
+          { name: 'name', label: '姓名' },
+          { name: 'email', label: '邮箱' }
+        ]
+      }
+    ]
+  }
+};
+```
+
+## Tailwind CSS 支持
+
+模块内置 Tailwind CSS 支持，可以直接使用 Tailwind 类名：
+
+```html
+<div class="container mx-auto px-4">
+  <h1 class="text-3xl font-bold text-gray-900 mb-4">
+    Welcome to Builder6
+  </h1>
+  <p class="text-gray-600 leading-relaxed">
+    Build pages with ease using Amis and Tailwind CSS.
+  </p>
+</div>
+```
+
+### 自定义 Tailwind 配置
+
+可以通过环境变量加载自定义 CSS：
+
+```bash
+B6_PAGES_CUSTOM_CSS_URL=https://cdn.example.com/custom-tailwind.css
+```
+
+## 性能优化
+
+### 页面缓存
+
+使用 LRU 缓存优化页面加载性能：
+
+```bash
+# 设置缓存大小
+B6_PAGES_CACHE_SIZE=1000
+```
+
+### DataLoader
+
+使用 DataLoader 优化数据查询，避免 N+1 查询问题。
+
+## 使用场景
+
+- **管理后台**: 快速构建管理后台界面
+- **数据看板**: 创建数据可视化仪表板
+- **表单应用**: 构建各类表单应用
+- **工作流界面**: 工作流审批界面
+- **报表系统**: 动态报表和统计页面
+- **移动应用**: 响应式移动端页面
+
+## Steedos 依赖
+
+该模块依赖以下 Steedos 对象：
+
+```yaml
+objects:
+  - b6_pages      # 页面配置
+  - b6_projects   # 项目管理
+```
+
+## 依赖项
+
+### 主要依赖
+
+- `liquidjs`: ^10.24.0 - Liquid 模板引擎
+- `dataloader`: ^2.2.3 - 数据加载优化
+- `lru-cache`: ^11.2.4 - LRU 缓存
+- `tailwindcss`: ^3.4.19 - CSS 框架
+- `autoprefixer`: ^10.4.23 - CSS 自动前缀
+- `cssnano`: ^7.1.2 - CSS 压缩
+
+### Peer Dependencies
+
+- `@builder6/core`: ^3.0.10 - 核心功能模块
+- `@builder6/moleculer`: ^3.0.10 - 微服务框架
+- `@nestjs/common`: ^11.0.0 - NestJS 核心
+- `@nestjs/core`: ^11.0.0 - NestJS 核心
+- `@nestjs/swagger`: ^11.0.7 - API 文档
+- `@steedos/auth`: ^3.0 - Steedos 认证
+- `@steedos/objectql`: ^3.0 - Steedos 对象查询
+
+## 开发
+
+### 构建
+
+```bash
+npm run build
 ```
+
+### 监听模式
+
+```bash
+npm run build:watch
+```
+
+### 格式化代码
+
+```bash
+npm run format
+```
+
+## 参考资源
+
+- [Amis 官方文档](https://aisuda.bce.baidu.com/amis/zh-CN/docs/index)
+- [LiquidJS 文档](https://liquidjs.com/)
+- [Tailwind CSS 文档](https://tailwindcss.com/docs)
+- [Steedos Widgets](https://github.com/steedos/widgets)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder6/pages",
-  "version": "3.2.3",
+  "version": "3.2.12",
   "main": "dist/plugin.module.js",
   "license": "MIT",
   "files": [
@@ -33,5 +33,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "544e8b41e82e41a3a7534cd30219c00d60285c63"
+  "gitHead": "6d6e13fed8d4b3c6de14f84dcb6287c5661ea6f6"
 }