# https://github.com/nocobase/nocobase 项目说明书

生成时间：2026-05-13 22:57:37 UTC

## 目录

- [NocoBase 概述](#nocobase-overview)
- [系统架构与设计模式](#system-architecture)
- [数据建模与集合管理](#data-modeling)
- [外部数据源与多数据库支持](#external-data-sources)
- [权限系统与 ACL](#acl-permissions)
- [工作流引擎](#workflow-engine)
- [AI 集成与智能员工](#ai-integration)
- [界面构建器](#interface-builder)
- [文件管理与存储](#file-manager)
- [插件开发指南](#plugin-development)

<a id='nocobase-overview'></a>

## NocoBase 概述

### 相关页面

相关主题：[系统架构与设计模式](#system-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/nocobase/nocobase/blob/main/README.md)
- [README.zh-CN.md](https://github.com/nocobase/nocobase/blob/main/README.zh-CN.md)
- [package.json](https://github.com/nocobase/nocobase/blob/main/package.json)
- [packages/core/client/src/user/Help.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/user/Help.tsx)
- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)
</details>

# NocoBase 概述

## 什么是 NocoBase

NocoBase 是一个开源的 AI + 无代码平台，用于快速构建业务系统。与从零开始生成所有内容不同，AI 在经过生产验证的基础设施和所见即所得（WYSIWYG）的无代码界面上工作，既能保证开发速度，又能确保系统的稳定性和可靠性。

资料来源：[README.md:1-10]()

### 核心价值主张

NocoBase 的核心价值在于将人工智能与无代码技术相结合，让开发者和业务用户能够：

- **快速构建**：通过可视化配置而非传统编码方式快速搭建业务系统
- **AI 赋能**：借助 AI Agent 实现自动化和智能化的业务流程
- **灵活扩展**：支持插件化架构，可根据需求扩展功能
- **协作共建**：AI 和人类协同工作，共同构建系统

资料来源：[README.md:47-52]()

---

## 系统架构

### 整体架构图

```mermaid
graph TB
    subgraph 前端层["前端层 (Client)"]
        PC[PC 端客户端]
        Mobile[移动端插件<br/>@nocobase/plugin-mobile]
        Theme[主题编辑器<br/>@nocobase/plugin-theme-editor]
    end
    
    subgraph 核心层["核心模块 (Core)"]
        Schema[Schema 组件系统]
        PM[插件管理器<br/>PluginManager]
        FlowEngine[流程引擎<br/>FlowEngine]
        Variables[变量系统]
        SchemaSettings[Schema 配置]
        SchemaInitializer[Schema 初始化器]
    end
    
    subgraph 插件层["插件生态"]
        AI[AI 插件<br/>@nocobase/plugin-ai]
        Auth[认证插件]
        Database[数据库插件]
        API[API 插件]
    end
    
    subgraph 服务层["服务端 (Server)"]
        Server[服务端核心]
        DatabaseEngine[(数据库引擎)]
    end
    
    PC --> Schema
    PC --> PM
    Mobile --> Schema
    Theme --> Schema
    
    Schema --> SchemaSettings
    Schema --> SchemaInitializer
    
    PM --> AI
    PM --> Auth
    PM --> Database
    
    AI --> Server
    Server --> DatabaseEngine
    
    PC --> Server
```

### 目录结构

NocoBase 采用 monorepo 结构，主要目录如下：

| 目录 | 说明 |
|------|------|
| `packages/core/` | 核心包，包含客户端和服务端基础模块 |
| `packages/core/client/` | 前端核心代码 |
| `packages/core/flow-engine/` | 流程引擎实现 |
| `packages/plugins/` | 官方插件集合 |
| `packages/plugins/@nocobase/plugin-mobile/` | 移动端支持插件 |
| `packages/plugins/@nocobase/plugin-ai/` | AI 能力插件 |
| `packages/plugins/@nocobase/plugin-theme-editor/` | 主题编辑器插件 |

资料来源：[package.json:1-20]()

---

## 核心模块详解

### 插件管理系统 (PluginManager)

NocoBase 的核心架构基于插件系统，插件管理器（PluginManager）负责插件的加载、启停和管理。

```mermaid
graph LR
    subgraph 插件详情["插件详情组件"]
        PInfo[基本信息]
        DCheck[依赖兼容性检查]
        CHLog[更新日志]
    end
    
    PM[PluginManager] --> PInfo
    PM --> DCheck
    PM --> CHLog
    
    DCheck --> |兼容性状态| Alert[警告提示]
    DCheck --> Table[依赖表格]
```

每个插件包含以下元信息：

| 属性 | 说明 |
|------|------|
| `packageName` | 插件包名称 |
| `version` | 当前版本号 |
| `description` | 插件描述 |
| `author` | 作者信息 |
| `license` | 开源许可证 |
| `homepage` | 项目主页 |
| `isCompatible` | 与系统的兼容性状态 |

资料来源：[packages/core/client/src/pm/PluginDetail.tsx:1-50]()

### Schema 组件系统

Schema 是 NocoBase 中用于描述界面配置的核心概念，通过声明式的 Schema 定义，可以配置页面的布局、字段、动作等元素。

#### Schema 组成部分

| 组件 | 功能 |
|------|------|
| SchemaSettings | Schema 的配置面板，用于设置组件属性 |
| SchemaInitializer | Schema 的初始化器，决定可以在何处添加新元素 |
| GeneralSchemaDesigner | 通用的 Schema 设计器组件 |
| LinkageFilter | 联动过滤器，用于配置条件联动规则 |

资料来源：[packages/core/client/src/schema-settings/index.md:1-20]()
资料来源：[packages/core/client/src/schema-component/antd/linkageFilter/index.md:1-15]()

### 变量系统 (Variables)

NocoBase 提供丰富的内置变量系统，支持在配置中引用各种运行时上下文。

```mermaid
graph TD
    V[内置变量] --> User[用户变量]
    V --> Role[角色变量]
    V --> DateTime[时间变量]
    V --> URL[URL 参数]
    V --> System[系统变量]
    
    User --> |$nUserId| UserId[当前用户 ID]
    User --> |$nUserRoles| UserRoles[当前用户角色]
    User --> |$nUserEmail| UserEmail[用户邮箱]
    
    DateTime --> |$nDate| CurrentDate[当前日期]
    DateTime --> |$nExactDate| ExactDateTime[精确时间]
    
    System --> |$system| SystemInfo[系统信息]
```

**内置变量列表：**

| 变量名 | 说明 | 状态 |
|--------|------|------|
| `$nUserId` | 当前登录用户 ID | 活跃 |
| `$nRoleId` | 当前用户角色 ID | 活跃 |
| `$nDate` | 当前日期时间 | 活跃 |
| `$nExactDate` | 精确时间戳 | 活跃 |
| `$date` | 日期（已废弃） | 废弃 |
| `$system` | 系统变量（已废弃） | 废弃 |
| `currentTime` | 当前时间（已废弃） | 废弃 |
| `urlSearchParams` | URL 查询参数 | 活跃 |

资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts:1-80]()

### 流程引擎 (Flow Engine)

流程引擎是 NocoBase 处理复杂业务流程的核心模块，支持可视化的工作流配置。

#### FlowSettings 配置结构

```typescript
interface FlowSettingsConfig {
  footer?: React.ReactNode | ((originNode, { OkBtn, CancelBtn }) => React.ReactNode) | null;
  [key: string]: any;
}
```

**Footer 自定义方式：**

| 类型 | 示例 | 说明 |
|------|------|------|
| 直接渲染 | `<footer>内容</footer>` | 静态内容 |
| 包裹式 | `footer: (originNode) => (<div>包裹 {originNode}</div>)` | 在原有按钮外添加内容 |
| 函数式 | `footer: (originNode, { OkBtn, CancelBtn }) => (<Space><CancelBtn /><OkBtn /></Space>)` | 完全自定义按钮组合 |
| 隐藏 | `footer: null` | 隐藏底部按钮栏 |

资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-50]()

---

## 主要功能特性

### 1. 协作式构建

NocoBase 强调 AI 和人类协作构建系统的理念：

- AI Agent 可以帮助完成代码生成、API 调用、文档阅读等任务
- 人类开发者通过可视化的无代码界面进行配置和调整
- 两者相互配合，提高开发效率

资料来源：[README.md:53-58]()

### 2. 移动端支持

通过 `@nocobase/plugin-mobile` 插件，NocoBase 支持移动端应用的构建：

| 组件 | 说明 |
|------|------|
| MobileTabBar | 移动端底部导航栏 |
| MobileTabBar.Item | 导航项 |
| MobileTabBar.Link | 链接导航项，支持内部页面和外部页面跳转 |
| DesktopMode | 桌面端访问移动端页面时的占位组件 |

移动端支持 Schema 配置，可以实现复杂的移动端页面布局。

资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md:1-25]()
资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md:1-20]()

### 3. 主题定制

`@nocobase/plugin-theme-editor` 插件提供了主题编辑功能，支持通过 Ant Design Token 定制界面样式。

资料来源：[packages/plugins/@nocobase/plugin-theme-editor/src/client/antd-token-previewer/component-demos/typography/typographyFull.tsx:1-30]()

### 4. AI Agent 能力

`@nocobase/plugin-ai` 插件集成了 AI 能力，支持：

- 文档阅读和检索
- 代码生成和执行
- 数据库操作的智能辅助
- 多数据源支持

**AI 插件特性：**

| 功能 | 说明 |
|------|------|
| 文档工具 | 读取项目文档和 API 文档 |
| 代码执行 | 支持 RunJS 等代码执行环境 |
| 数据库操作 | 辅助生成 SQL 和数据库操作 |
| 多语言支持 | 支持中英文等不同语言的交互 |

资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/tools/docs.ts:1-50]()
资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/ai-employees/prompts.ts:1-40]()

---

## 快速链接

### 官方资源

| 资源 | 链接 |
|------|------|
| 官方网站 | https://www.nocobase.com/ |
| 在线演示 | https://demo.nocobase.com/new |
| 开发文档 | https://docs.nocobase.com/ |
| 用户论坛 | https://forum.nocobase.com/ |
| 更新日志 | https://www.nocobase.com/en/blog/timeline |

资料来源：[README.md:20-40]()
资料来源：[packages/core/client/src/user/Help.tsx:1-50]()

---

## 技术栈概览

### 前端技术

- **框架**：React
- **UI 库**：Ant Design
- **状态管理**：Zustand
- **移动端**：React Native（通过 WebView 混合方案）

### 后端技术

- **运行时**：Node.js
- **框架**：Koa.js
- **数据库**：支持多种数据库（MySQL、PostgreSQL、SQLite 等）

### 构建工具

- **包管理**：pnpm
- **构建**：Turborepo
- **类型检查**：TypeScript

资料来源：[package.json:1-100]()

---

## 总结

NocoBase 是一个现代化的开源无代码平台，通过以下核心特性为业务系统开发提供强大支持：

1. **插件化架构**：高度可扩展的插件系统，支持按需加载功能
2. **Schema 驱动的配置**：声明式的界面配置方式
3. **AI 赋能**：集成 AI Agent，提升开发效率
4. **多端支持**：同时支持桌面端和移动端
5. **灵活的主题定制**：通过 Token 系统实现品牌定制

无论是小型业务系统还是大型企业应用，NocoBase 都能提供灵活、高效的解决方案。

---

<a id='system-architecture'></a>

## 系统架构与设计模式

### 相关页面

相关主题：[NocoBase 概述](#nocobase-overview), [插件开发指南](#plugin-development)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/client/src/application.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/application.ts)
- [packages/core/server/src/application.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/application.ts)
- [packages/core/server/src/plugin.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/plugin.ts)
- [packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)
- [packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)
- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)
</details>

# 系统架构与设计模式

## 概述

NocoBase 采用分层模块化架构设计，核心遵循**插件化架构**（Plugin Architecture）和**配置驱动架构**（Configuration-driven Architecture）两大设计理念。系统分为服务端（Server）和客户端（Client）两大主体，通过插件机制实现功能扩展，通过 Schema 配置驱动实现前端界面与业务逻辑的解耦。

## 核心架构分层

### 架构层次总览

```graph TD
    A[客户端 Client] --> B[应用层 Application]
    A --> C[Schema 组件层]
    A --> D[Schema 配置层]
    B --> E[插件管理层 PM]
    C --> F[数据区块 Provider]
    D --> G[Schema 设计器]
    E --> H[插件 Plugin]
    H --> I[服务端插件]
    H --> J[客户端插件]
```

### 服务端架构

服务端基于 **Plugin 插件基类**构建，所有业务模块均以插件形式注册。插件系统提供了完整的生命周期管理，包括 `load`、`enable`、`disable` 等状态转换。

```graph TD
    A[Application] --> B[Plugin Manager]
    A --> C[数据层 Data]
    A --> D[认证层 Auth]
    B --> E[Plugin 实例]
    E --> F[install]
    E --> G[load]
    E --> H[enable]
    E --> I[disable]
```

服务端 `Application` 类负责统一管理插件的加载与初始化流程，通过 `pm`（Plugin Manager）实现插件的注册、启用、停用等操作。资料来源：[packages/core/server/src/application.ts]()

### 客户端架构

客户端采用 **React Context** 进行状态管理和依赖注入，主要包括以下几个核心模块：

| 模块 | 职责 | 核心文件 |
|------|------|----------|
| Application | 应用初始化与全局状态 | application.ts |
| SchemaComponent | Schema 驱动的组件渲染 | schema-component/index.md |
| SchemaSettings | Schema 配置编辑器 | schema-settings/index.md |
| SchemaInitializer | Schema 初始化器 | schema-initializer/index.md |
| PM (Plugin Manager) | 插件管理与详情展示 | PluginDetail.tsx |

## 插件系统设计

### 插件架构模式

NocoBase 的插件系统采用**观察者模式**与**依赖注入模式**相结合的架构。每个插件包含服务端和客户端两部分，通过统一的插件管理器进行协调。

```mermaid
graph TD
    subgraph 服务端
        A1[Plugin 基类] --> A2[install 方法]
        A1 --> A3[load 方法]
        A1 --> A4[enable 方法]
    end
    
    subgraph 客户端
        B1[React Component] --> B2[Configuration]
        B1 --> B3[Settings]
        B1 --> B4[Initializer]
    end
    
    A1 --> B1
```

### 插件元数据管理

插件详情组件 `PluginDetail` 展示插件的完整信息，包括版本、依赖兼容性、许可证等。依赖兼容性检查机制确保插件间的版本匹配。

```typescript
// 插件详情信息结构
interface PluginInfo {
  packageName: string;      // 包名
  version: string;          // 版本号
  description?: string;    // 描述
  author?: string;         // 作者
  homepage?: string;       // 主页
  license?: string;        // 许可证
  depsCompatible?: boolean; // 依赖兼容性
}
```

资料来源：[packages/core/client/src/pm/PluginDetail.tsx]()

### 依赖兼容性检查

插件系统内置依赖兼容性检查机制，通过 `externalVersion.js` 文件记录插件的外部依赖版本信息。检查结果通过 `isCompatible` 字段标识，兼容性检查失败时会显示错误提示。

## Schema 驱动架构

### Schema 设计理念

NocoBase 的前端界面完全由 **Schema 配置**驱动。Schema 是 JSON 格式的配置对象，定义了界面的结构、行为和样式。这种设计实现了**界面与逻辑的分离**，使非开发人员也能通过配置自定义系统功能。

```mermaid
graph LR
    A[Schema JSON] --> B[Schema 解析器]
    B --> C[SchemaComponent]
    B --> D[SchemaSettings]
    B --> E[SchemaInitializer]
    C --> F[用户界面]
```

### Schema 组件层级

| 组件类型 | 用途 | 配置属性 |
|----------|------|----------|
| SchemaComponent | 根据 Schema 渲染 UI | `x-component` |
| SchemaSettings | 组件的配置面板 | `x-settings` |
| SchemaInitializer | 组件的初始化器 | `x-initializer` |

### SchemaToolbar 组件

`GeneralSchemaDesigner` 是 Schema 设计器的核心组件，负责渲染 Schema 的工具栏界面，包括标题、拖拽手柄、初始化器和配置下拉菜单。

```typescript
interface SchemaToolbarProps {
  title?: string | string[];
  template?: boolean;
  draggable?: boolean;
  showDataSource?: boolean;
  templateName?: string;
}
```

资料来源：[packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx]()

## 流程引擎架构

### FlowSettings 配置系统

流程引擎（Flow Engine）采用**配置化设计**，通过 `FlowSettings` 类管理流程节点组件和作用域变量。

```typescript
class FlowSettings {
  public components: Record<string, any> = {};  // 节点组件映射
  public scopes: Record<string, any> = {};      // 作用域变量
  private antdComponentsLoaded = false;
  public enabled: boolean;
  #forceEnabled = false;
}
```

资料来源：[packages/core/flow-engine/src/flowSettings.ts]()

### 流程配置 Footer 自定义

流程设置支持四种 Footer 配置模式：

| 模式 | 类型 | 说明 |
|------|------|------|
| 默认 | `React.ReactNode` | 原生 React 节点 |
| 增强 | 函数式 | `(originNode, { OkBtn, CancelBtn }) => ReactNode` |
| 完全自定义 | 函数式 | 重新组合按钮布局 |
| 隐藏 | `null` | 隐藏底部区域 |

## 变量系统

### 内置变量机制

系统提供内置变量支持，通过 `useBuiltInVariables` Hook 获取。内置变量包括用户上下文、日期时间、URL 参数等。

```typescript
// 内置变量列表
const builtinVariables = [
  { name: '$nUser', ctx: currentUserCtx },
  { name: '$nRole', ctx: currentRoleCtx },
  { name: '$nDate', ctx: datetimeCtx },
  { name: '$nExactDate', ctx: exactDateTimeCtx },
  { name: '$nUrlSearchParams', ctx: urlSearchParamsCtx },
  { name: '$env', ctx: envVariableCtx },
];
```

已废弃的兼容变量包括 `$date`、`$system`、`currentTime`，建议使用新版变量名替代。

资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts]()

## 设计模式总结

### 核心设计模式

| 模式名称 | 应用场景 | 实现方式 |
|----------|----------|----------|
| 插件模式 | 功能扩展 | Plugin 基类 + PM 管理器 |
| 配置驱动 | UI 生成 | Schema JSON 配置 |
| 依赖注入 | 状态共享 | React Context Provider |
| 观察者模式 | 事件通知 | 插件生命周期事件 |
| 策略模式 | 流程节点 | FlowSettings components |
| 工厂模式 | Schema 组件 | x-component 类型映射 |

### 模块间通信

```mermaid
sequenceDiagram
    participant App as Application
    participant PM as Plugin Manager
    participant Plugin as Plugin
    participant Schema as SchemaComponent
    
    App->>PM: 注册插件
    PM->>Plugin: 实例化
    Plugin->>Plugin: load()
    Plugin->>Schema: 注册组件
    Schema->>Schema: 渲染界面
```

## 移动端适配

系统通过 `DesktopMode` 组件实现移动端与桌面端的视图切换，当检测到非移动端设备访问移动端页面时，渲染桌面端适配组件。

```tsx
<DesktopMode>
  <Mobile />
</DesktopMode>
```

## 系统信息与帮助

`Help` 组件负责展示系统信息，包括版本号（`data?.data?.version`）、文档链接、许可证信息等。根据语言设置（`isSimplifiedChinese`）动态切换中英文文档地址。

资料来源：[packages/core/client/src/user/Help.tsx]()

---

## 总结

NocoBase 的系统架构围绕**插件化**和**配置驱动**两大核心理念构建，实现了高度的模块化和可扩展性。服务端通过 Plugin 基类实现功能模块化管理，客户端通过 Schema 配置实现界面的动态渲染，两者通过统一的插件管理器协调工作，形成一个完整的有机整体。

---

<a id='data-modeling'></a>

## 数据建模与集合管理

### 相关页面

相关主题：[外部数据源与多数据库支持](#external-data-sources), [权限系统与 ACL](#acl-permissions)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/database/src/collection.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/database/src/collection.ts)
- [packages/core/database/src/field.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/database/src/field.ts)
- [packages/core/database/src/repository.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/database/src/repository.ts)
- [packages/plugins/@nocobase/plugin-data-source-manager](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-manager)
- [packages/core/client/src/collection-manager/Configuration/components/Summary.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/collection-manager/Configuration/components/Summary.tsx)
- [packages/core/client/src/schema-initializer/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-initializer/index.md)
</details>

# 数据建模与集合管理

## 概述

NocoBase 的数据建模与集合管理模块是整个平台的核心基础设施，负责定义数据结构、管理数据关系、提供数据访问接口。该模块采用面向集合（Collection）的数据建模范式，支持多数据源管理，并提供了完整的 CRUD 操作能力。

数据建模系统的主要职责包括：

- **集合定义**：定义数据集合的结构、字段和约束
- **字段管理**：支持多种字段类型和数据验证规则
- **数据访问**：通过 Repository 模式提供统一的数据操作接口
- **多数据源**：支持连接不同类型的数据源（主数据库、远程服务等）
- **Schema 管理**：将数据模型与前端 Schema 绑定，实现 UI 联动

资料来源：[packages/core/database/src/collection.ts]()

## 核心概念

### 集合（Collection）

集合是 NocoBase 中数据组织的基本单元，类似于传统数据库中的表概念。每个集合包含以下关键属性：

| 属性 | 说明 | 类型 |
|------|------|------|
| name | 集合名称，唯一标识 | string |
| fields | 字段定义数组 | Field[] |
| title | 显示名称 | string |
| description | 描述信息 | string |
| filterTargetKey | 过滤目标键 | string |
| treeCollection | 是否为树形结构 | boolean |

集合通过 Database 实例进行注册和管理，支持热插拔式的数据模型变更。

### 字段（Field）

字段是集合中的数据列定义，支持多种数据类型：

- **普通字段**：字符串、数字、布尔值、日期等
- **关系字段**：belongsTo、hasOne、hasMany、belongsToMany
- **特殊字段**：json、radio、checkbox、sequence 等

资料来源：[packages/core/database/src/field.ts]()

## 架构设计

```mermaid
graph TD
    A[数据建模层] --> B[CollectionManager]
    A --> C[数据源管理器]
    B --> D[Collection 集合]
    D --> E[Field 字段]
    D --> F[Repository 数据访问]
    C --> G[主数据源]
    C --> H[远程数据源]
    G --> I[MySQL/PostgreSQL/SQLite]
    H --> J[外部 API]
```

### 层次结构

NocoBase 数据建模系统分为三个主要层次：

1. **Schema 层**：定义数据结构的元信息
2. **Collection 层**：将 Schema 实例化为可操作的集合
3. **Repository 层**：提供数据访问的抽象接口

```mermaid
classDiagram
    class Collection {
        +name: string
        +fields: Field[]
        +repository: Repository
        +create(data)
        +update(id, data)
        +delete(id)
        +find(params)
    }
    
    class Field {
        +name: string
        +type: string
        +options: object
        +validate(data)
    }
    
    class Repository {
        +create(data)
        +find(params)
        +update(id, data)
        +destroy(id)
        +count(params)
    }
    
    class Database {
        +registerCollections()
        +getCollection(name)
    }
    
    Collection "1" --> "*" Field : contains
    Collection --> Repository
    Database --> Collection : manages
```

资料来源：[packages/core/database/src/collection.ts:1-100]()

## 集合管理

### CollectionManager

CollectionManager 是集合管理的核心类，负责维护所有已注册的集合实例：

```typescript
// 伪代码示例
class CollectionManager {
  collections: Map<string, Collection>;
  
  getCollection(name: string): Collection;
  registerCollection(collection: Collection): void;
  removeCollection(name: string): void;
  getCollections(options?: FilterOptions): Collection[];
}
```

### 集合注册流程

```mermaid
sequenceDiagram
    participant User as 用户/开发者
    participant DB as Database
    participant CM as CollectionManager
    participant Col as Collection
    
    User->>DB: registerCollection(config)
    DB->>CM: addCollection(name, config)
    CM->>Col: new Collection(config)
    Col->>Col: parse fields
    Col->>Col: create repository
    CM->>DB: collection registered
    DB-->>User: success
```

资料来源：[packages/core/database/src/collection.ts]()

### 集合配置组件

在前端，集合配置通过 Summary 组件展示：

```tsx
const Summary: React.FC<SummaryProps> = ({ label, schema }) => {
  // 展示集合配置的摘要信息
  return (
    <div style={styles.container}>
      <div style={styles.title}>
        {label}: <Tag>{compile(schema.title)}</Tag>
      </div>
      {schema.description && <div>{compile(schema.description)}</div>}
    </div>
  );
};
```

该组件负责渲染集合的名称和描述信息，支持国际化配置。

资料来源：[packages/core/client/src/collection-manager/Configuration/components/Summary.tsx]()

## 字段系统

### 字段类型

NocoBase 支持丰富的字段类型，定义在 field.ts 中：

| 类型 | 说明 | 适用场景 |
|------|------|----------|
| string | 字符串 | 文本输入 |
| integer | 整数 | 数量、ID |
| bigInt | 大整数 | 雪花ID |
| float/double | 浮点数 | 金额 |
| boolean | 布尔值 | 开关状态 |
| date/datetime | 日期/时间 | 时间记录 |
| json | JSON 对象 | 复杂数据结构 |
| belongsTo | 一对一关联 | 用户-角色 |
| hasMany | 一对多关联 | 帖子-评论 |
| belongsToMany | 多对多关联 | 用户-权限 |

### 字段定义

```typescript
interface FieldOptions {
  type: string;
  name: string;
  title?: string;
  description?: string;
  defaultValue?: any;
  uiSchema?: object;
  validation?: ValidationRule[];
  unique?: boolean;
  allowNull?: boolean;
  primaryKey?: boolean;
}
```

字段支持级联配置，包括验证规则、默认值、UI 组件绑定等。

资料来源：[packages/core/database/src/field.ts]()

## Repository 数据访问层

### Repository 模式

Repository 提供统一的数据访问接口，封装了底层数据库操作：

```typescript
interface IRepository {
  // 创建
  create(data: object, options?: CreateOptions): Promise<object>;
  createMany(data: object[], options?: CreateOptions): Promise<object[]>;
  
  // 查询
  find(params: FindParams): Promise<object[]>;
  findOne(params: FindParams): Promise<object | null>;
  findById(id: any): Promise<object>;
  count(params?: FilterParams): Promise<number>;
  
  // 更新
  update(params: UpdateParams): Promise<object[]>;
  updateById(id: any, data: object): Promise<object>;
  
  // 删除
  destroy(params: FilterParams): Promise<number>;
  destroyById(id: any): Promise<void>;
  
  // 关联操作
  add(field: string, id: any, relatedIds: any[]): Promise<void>;
  set(field: string, id: any, relatedIds: any[]): Promise<void>;
  remove(field: string, id: any, relatedIds: any[]): Promise<void>;
}
```

### 查询构建器

Repository 内置强大的查询构建能力：

```typescript
// 基础查询
repository.find({
  filter: { status: 'active' },
  fields: ['id', 'name'],
  sort: ['createdAt'],
  page: 1,
  pageSize: 20
});

// 关联查询
repository.find({
  filter: { 'profile.nickname.$contains': 'admin' },
  appends: ['profile']
});
```

资料来源：[packages/core/database/src/repository.ts]()

## 数据源管理

### 数据源管理器插件

plugin-data-source-manager 负责管理多数据源连接：

```mermaid
graph LR
    A[应用层] --> B[数据源管理器]
    B --> C[主数据源<br/>Main Database]
    B --> D[远程数据源<br/>Remote Data Source]
    B --> E[第三方服务]
    
    C --> F[MySQL/PostgreSQL]
    D --> G[REST API]
    D --> H[GraphQL]
```

### 数据源配置

| 配置项 | 说明 | 示例 |
|--------|------|------|
| name | 数据源名称 | 'main' |
| type | 数据源类型 | 'mysql' |
| host | 主机地址 | 'localhost' |
| port | 端口号 | 3306 |
| database | 数据库名 | 'nocobase' |
| username | 用户名 | 'root' |

### 数据源隔离

NocoBase 支持逻辑隔离的数据源架构，每个数据源可以：

- 拥有独立的连接池
- 使用不同的数据库引擎
- 配置独立的迁移策略
- 实现独立的缓存策略

## Schema 集成

### Schema 与集合绑定

数据模型通过 Schema 与前端组件绑定：

```typescript
const schema = {
  type: 'object',
  'x-collection': 'users',
  properties: {
    name: {
      type: 'string',
      'x-field': 'name'
    },
    email: {
      type: 'string',
      'x-field': 'email'
    }
  }
};
```

### Schema 初始化器

Schema 初始化器提供了动态插入 Schema 的能力：

```typescript
// 插入 Schema 配置
const initializerConfig = {
  title: 'Form Item',
  type: 'object',
  'x-component': 'FormItem',
  properties: {
    field1: {
      type: 'string',
      'x-component': 'Input'
    }
  }
};
```

支持动态显示/隐藏、动态加载子节点等高级功能。

资料来源：[packages/core/client/src/schema-initializer/index.md]()

## 内置变量与上下文

### 变量系统

数据模型支持在运行时使用内置变量：

```typescript
const builtinVariables = [
  { name: '$nDate', ctx: datetimeCtx },
  { name: '$nExactDate', ctx: exactDateTimeCtx },
  { name: '$nRole', ctx: currentRoleCtx },
  { name: '$nUser', ctx: currentUserCtx },
  { name: '$nUrlSearchParams', ctx: urlSearchParamsCtx }
];
```

### 上下文变量

| 变量名 | 说明 | 返回值 |
|--------|------|--------|
| $nDate | 当前日期时间 | ISO 8601 格式 |
| $nExactDate | 精确时间戳 | 带毫秒 |
| $nRole | 当前用户角色 | 角色对象 |
| $nUser | 当前用户信息 | 用户对象 |
| $nUrlSearchParams | URL 参数 | 参数对象 |

资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts]()

## 工作流程

### 数据操作完整流程

```mermaid
graph TD
    A[前端请求] --> B[Schema 验证]
    B --> C{请求类型}
    C -->|Create| D[数据验证]
    C -->|Read| E[查询构建]
    C -->|Update| F[变更检测]
    C -->|Delete| G[软删除检查]
    
    D --> H[事务开始]
    E --> I[Repository.find]
    F --> H
    G --> H
    
    H --> J[数据库操作]
    J --> K[事务提交]
    K --> L[返回结果]
    
    I --> L
```

### 集合管理器初始化流程

```mermaid
sequenceDiagram
    participant App as 应用启动
    participant DB as Database
    participant CM as CollectionManager
    participant Plugin as 插件加载
    
    App->>DB: initialize()
    DB->>CM: 创建实例
    CM->>Plugin: 加载数据源插件
    Plugin->>CM: registerCollection()
    CM->>CM: 创建 Collection 实例
    CM->>CM: 解析字段定义
    CM->>CM: 创建 Repository
    Plugin-->>DB: 注册完成
    DB-->>App: 数据库就绪
```

## 最佳实践

### 集合命名规范

- 使用小写字母和下划线：`user_profiles`
- 避免使用保留字：`order`, `user`, `group`
- 使用单数名词：`user` 而非 `users`
- 有意义的名称：`order_items` 而非 `oi`

### 字段设计建议

1. **主键设计**：每个集合应定义主键字段
2. **时间戳**：建议包含 `createdAt` 和 `updatedAt` 字段
3. **软删除**：使用 `deletedAt` 而非物理删除
4. **索引**：频繁查询字段添加索引配置

### 关系设计原则

```typescript
// 一对多关系示例
const postCollection = {
  name: 'posts',
  fields: [
    { type: 'string', name: 'title' },
    { 
      type: 'hasMany', 
      name: 'comments',
      foreignKey: 'postId'
    }
  ]
};

// 评论表定义
const commentCollection = {
  name: 'comments',
  fields: [
    { type: 'string', name: 'content' },
    { type: 'integer', name: 'postId' },
    { 
      type: 'belongsTo', 
      name: 'post',
      foreignKey: 'postId'
    }
  ]
};
```

## 总结

NocoBase 的数据建模与集合管理系统提供了完整的数据建模解决方案：

1. **灵活的集合定义**：支持多种字段类型和复杂的数据结构
2. **强大的数据访问**：通过 Repository 模式提供统一的 CRUD 接口
3. **多数据源支持**：可连接多种类型的数据库和外部服务
4. **Schema 驱动**：与前端组件无缝集成，实现数据与 UI 联动
5. **变量系统**：运行时支持丰富的上下文变量

该系统设计遵循低耦合、高内聚的原则，便于扩展和维护，是 NocoBase 作为无代码平台的核心支撑模块。

---

<a id='external-data-sources'></a>

## 外部数据源与多数据库支持

### 相关页面

相关主题：[数据建模与集合管理](#data-modeling), [系统架构与设计模式](#system-architecture)

# 外部数据源与多数据库支持

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/plugins/@nocobase/plugin-data-source-external-mysql](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-external-mysql)
- [packages/plugins/@nocobase/plugin-data-source-external-postgres](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-external-postgres)
- [packages/plugins/@nocobase/plugin-data-source-external-mariadb](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-data-source-external-mariadb)
- [packages/plugins/@nocobase/plugin-collection-fdw](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-collection-fdw)
</details>

> **说明**：当前检索到的上下文信息中，未包含上述外部数据源插件的详细源码实现内容。以下内容基于 NocoBase 核心代码库中与多数据源相关的公开信息进行整理。

---

## 概述

NocoBase 采用**数据模型驱动**的架构设计，而非传统的表单或表格驱动方式。这种设计模式将数据结构与用户界面完全解耦，使得系统能够同时支持主数据库、外部数据库以及第三方 API 作为数据来源。

资料来源：[README.md](https://github.com/nocobase/nocobase/blob/main/README.md)

## 核心特性

### 数据源类型支持

NocoBase 的多数据库支持涵盖以下数据源类型：

| 数据源类型 | 说明 | 支持状态 |
|-----------|------|---------|
| 主数据库 | 系统内置的主数据存储 | 完整支持 |
| MySQL | 外部 MySQL 数据库连接 | 插件支持 |
| PostgreSQL | 外部 PostgreSQL 数据库连接 | 插件支持 |
| MariaDB | 外部 MariaDB 数据库连接 | 插件支持 |
| 第三方 API | REST API 作为数据来源 | 插件支持 |

### 数据库标识符引用规则

不同数据库引擎对 SQL 标识符（如表名、字段名）的引用规则存在差异。NocoBase 在生成 SQL 语句时会根据数据源类型自动应用正确的引用规则。

```ts
/**
 * 标识符引用规则根据数据源类型确定
 * - MySQL 使用反引号 (`)
 * - PostgreSQL 使用双引号 (")
 * - SQLite 使用双引号 (")
 */
```

资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/ai-employees/prompts.ts](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/server/ai-employees/prompts.ts)

### 环境配置参数

AI 代理在处理数据库操作时会参考以下环境配置：

- **main_database**: 主数据库引擎类型，影响 SQL 语法和标识符引用方式
- **locale**: 通信语言和地区格式化设置
- **quotingRules**: 不同数据源的 SQL 标识符引用规则

## 插件体系架构

外部数据源功能通过独立的插件实现，便于按需加载和维护：

```mermaid
graph TD
    A[NocoBase 核心] --> B[plugin-data-source-external-mysql]
    A --> C[plugin-data-source-external-postgres]
    A --> D[plugin-data-source-external-mariadb]
    A --> E[plugin-collection-fdw]
    
    B --> F[MySQL 连接器]
    C --> G[PostgreSQL 连接器]
    D --> H[MariaDB 连接器]
    E --> I[联邦集合支持]
```

### 插件列表

| 插件名称 | 功能描述 | 数据源类型 |
|---------|---------|-----------|
| plugin-data-source-external-mysql | MySQL 外部数据源连接 | MySQL |
| plugin-data-source-external-postgres | PostgreSQL 外部数据源连接 | PostgreSQL |
| plugin-data-source-external-mariadb | MariaDB 外部数据源连接 | MariaDB |
| plugin-collection-fdw | 外部数据封装器支持 | 多类型 |

## 数据源管理界面

NocoBase 提供了插件详情管理界面，支持查看和管理已安装数据源插件：

### 插件信息展示

在插件详情页面中，可查看以下关键信息：

| 字段 | 说明 |
|-----|------|
| PackageName | 插件包名称 |
| Version | 当前版本号 |
| Description | 插件描述 |
| Author | 作者信息 |
| License | 开源许可证 |
| Homepage | 项目主页 |
| Repository | 代码仓库地址 |

资料来源：[packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)

### 依赖兼容性检查

插件管理界面包含依赖兼容性验证功能：

- 验证 `dist/externalVersion.js` 文件是否存在
- 检查插件依赖版本是否满足要求
- 在依赖不兼容时显示警告信息

```tsx
{data?.data?.depsCompatible === false ? (
  <Typography.Text type="danger">
    {t('`dist/externalVersion.js` not found or failed to `require`. Please rebuild this plugin.')}
  </Typography.Text>
) : (
  <>
    {!data?.data?.['isCompatible'] && (
      <Alert
        showIcon
        type={'error'}
        message={t('Plugin dependencies check failed, you should change the dependent version to meet the version requirements.')}
      />
    )}
  </>
)}
```

## 使用场景

### 统一数据管理

通过外部数据源功能，用户可以在 NocoBase 平台上：

1. **连接现有数据库** - 无需迁移数据，直接连接已有的 MySQL、PostgreSQL 或 MariaDB 数据库
2. **跨库查询** - 在单一界面中操作来自不同数据库的数据
3. **API 集成** - 将第三方 REST API 作为数据来源使用

### 数据结构与界面分离

NocoBase 的核心优势在于：

- UI 和数据结构完全解耦
- 可以为同一张表或记录创建任意数量和形式的区块和操作
- 支持在同一系统中混合使用多种数据源

## 相关文档

- [官方文档](https://docs.nocobase.com/)
- [在线演示](https://demo.nocobase.com/new)
- [用户案例](https://www.nocobase.com/en/blog/tags/customer-stories)

---

> **注意**：如需获取特定数据源插件的详细技术实现，建议查阅各插件目录下的源代码文件，或参考官方技术文档。

---

<a id='acl-permissions'></a>

## 权限系统与 ACL

### 相关页面

相关主题：[数据建模与集合管理](#data-modeling)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/client/src/application/hooks/useAclSnippets.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/application/hooks/useAclSnippets.ts)
- [packages/core/client/src/variables/hooks/useBuiltinVariables.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/variables/hooks/useBuiltinVariables.ts)
- [packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)
- [packages/plugins/@nocobase/plugin-acl](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-acl)
- [packages/core/server/src/acl/acl.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/acl/acl.ts)
- [packages/core/server/src/acl/role.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/server/src/acl/role.ts)
</details>

# 权限系统与 ACL

## 概述

NocoBase 的权限系统基于 **ACL（Access Control List，访问控制列表）** 机制实现。该系统采用角色（Role）和资源（Resource）两层的权限管理模式，支持细粒度的操作级别控制。权限系统贯穿整个应用，从服务端到客户端均有完整的权限校验链路，确保数据安全和操作合规。

## 核心概念

| 概念 | 说明 |
|------|------|
| **角色（Role）** | 一组权限的集合，用户通过关联角色获得相应权限 |
| **资源（Resource）** | 需要被保护的实体，如数据表、字段、插件等 |
| **操作（Action）** | 对资源的具体操作，如 view、create、update、delete |
| **Snippet** | 权限片段，用于灵活组合和管理权限规则 |

资料来源：[packages/core/server/src/acl/role.ts:1-20]()

## 架构设计

### 整体架构

```mermaid
graph TD
    A[用户请求] --> B[ACL 中间件]
    B --> C{权限校验}
    C -->|通过| D[业务逻辑处理]
    C -->|拒绝| E[返回 403 错误]
    D --> F[数据响应]
    
    G[角色管理] --> H[角色权限配置]
    H --> I[Snippet 定义]
    I --> C
```

### 服务端架构

服务端 ACL 模块位于 `packages/core/server/src/acl/` 目录，包含以下核心组件：

- **ACL 类**：权限系统的核心管理器，负责加载权限规则、执行权限校验
- **Role 类**：角色实体，封装角色的权限配置信息
- **中间件**：拦截请求并进行权限验证

```mermaid
graph LR
    A[Request] --> B[ACL Middleware]
    B --> C[ACL Manager]
    C --> D[Role Manager]
    D --> E[Snippet Matcher]
    E --> F{Permission Check}
    F -->|Match| G[Allow]
    F -->|No Match| H[Deny]
```

资料来源：[packages/core/server/src/acl/acl.ts:1-30]()

### 客户端架构

客户端通过 React Context 提供 ACL 上下文，使用 Hook 方式暴露权限判断能力：

```tsx
// ACL Provider 提供全局上下文
<ACLProvider>
  <App />
</ACLProvider>

// 子组件中使用权限 Hook
const { allow, snippets } = useACLRoleContext();
```

资料来源：[packages/core/client/src/application/hooks/useAclSnippets.ts:10-20]()

## 角色与权限

### 角色定义

角色是权限管理的基本单位，每个角色包含以下属性：

| 属性 | 类型 | 说明 |
|------|------|------|
| name | string | 角色标识名称 |
| title | string | 角色显示名称 |
| snippets | string[] | 权限片段列表 |
| allowAll | boolean | 是否允许所有操作 |

资料来源：[packages/core/server/src/acl/role.ts:20-40]()

### 预定义内置变量

NocoBase 在权限上下文中注入了多个内置变量，用于权限判断和动态规则：

| 变量名 | 说明 | 用途 |
|--------|------|------|
| `$nRole` | 当前角色 | 获取当前用户的角色信息 |
| `$nUser` | 当前用户 | 获取当前登录用户信息 |
| `$nDate` | 当前日期 | 日期相关的权限条件 |
| `$nExactDate` | 精确当前时间 | 时间戳相关的权限条件 |
| `$nenv` | 环境变量 | 服务器环境变量访问 |

资料来源：[packages/core/client/src/variables/hooks/useBuiltinVariables.ts:20-50]()

### Snippet 匹配机制

系统使用 `ignore` 库实现 Snippet 的模式匹配，支持通配符和否定前缀：

```typescript
const ig = ignore().add(snippets);
const appAllowed = allowAll || ig.ignores(aclSnippet);
```

匹配规则：
- `allowAll` 为 `true` 时，跳过 Snippet 校验，直接放行
- 使用 `ignore` 库的标准 glob 匹配规则
- 支持 `!` 前缀表示显式拒绝

资料来源：[packages/core/client/src/application/hooks/useAclSnippets.ts:12-18]()

## 权限配置

### Schema 中的权限声明

在数据 Schema 中通过 `x-acl-action` 字段声明权限要求：

```typescript
const schema: ISchema = {
  type: 'void',
  'x-acl-action': 'collections:view',  // 声明需要的权限
  'x-decorator': 'DetailsBlockProvider',
  'x-component': 'CardItem',
};
```

资料来源：[packages/core/client/src/schema-initializer/utils.ts:15-25]()

### 权限操作类型

| 操作 | 说明 | 适用资源 |
|------|------|----------|
| `view` | 查看资源 | 表单、详情、列表 |
| `create` | 创建新资源 | 表单、列表 |
| `update` | 修改现有资源 | 表单、详情 |
| `delete` | 删除资源 | 列表、操作按钮 |
| `get` | 获取单个资源 | 详情块 |

资料来源：[packages/core/client/src/schema-initializer/utils.ts:22-30]()

## 插件系统集成

### 插件兼容性检查

NocoBase 的插件管理界面集成了 ACL 权限校验，插件详情页提供依赖兼容性检查功能：

```tsx
{
  key: 'dependencies',
  label: t('Dependencies compatibility check'),
  children: (
    <>
      <Table
        columns={dependenciesCompatibleTableColumns}
        dataSource={data?.data?.depsCompatible}
      />
    </>
  ),
}
```

资料来源：[packages/core/client/src/pm/PluginDetail.tsx:80-100]()

### 插件权限声明

插件可通过配置文件声明所需的权限：

```json
{
  "name": "@nocobase/plugin-sample",
  "permissions": [
    "collections:view",
    "collections:create",
    "!system:admin"
  ]
}
```

## 工作流程

### 权限校验流程

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant Middleware as ACL 中间件
    participant ACL as ACL 管理器
    participant Role as 角色管理器
    participant Resource as 资源

    Client->>Middleware: 请求资源
    Middleware->>ACL: 发起权限校验
    ACL->>Role: 获取用户角色
    Role-->>ACL: 返回角色配置
    ACL->>ACL: 匹配 Snippet
    ACL-->>Middleware: 校验结果
    Middleware->>Resource: 允许/拒绝访问
```

### 客户端权限 Hook 使用

```typescript
import { useAclSnippets } from '@nocobase/client';

function MyComponent() {
  const { allow } = useAclSnippets();
  
  // 检查特定权限
  if (!allow('collections:view')) {
    return <NoPermission />;
  }
  
  return <Content />;
}
```

资料来源：[packages/core/client/src/application/hooks/useAclSnippets.ts:1-25]()

## 最佳实践

### 1. 合理设计角色

建议采用最小权限原则，按业务职能划分角色：

| 角色 | 权限范围 | 适用场景 |
|------|----------|---------- |
| admin | 所有权限 | 系统管理员 |
| operator | 业务操作权限 | 普通业务人员 |
| viewer | 仅查看权限 | 数据查看者 |

### 2. 使用 Snippet 组合

将常用权限组合定义为 Snippet，便于复用：

```typescript
// 定义 Snippet
snippets: [
  'collections:view',
  'collections:create',
  'collections:update',
]

// 使用通配符
snippets: [
  'collections:*',      // 所有集合操作
  '!collections:delete' // 排除删除
]
```

### 3. Schema 权限声明

在开发插件或自定义页面时，应明确声明所需的权限：

```typescript
const schema = {
  type: 'void',
  'x-acl-action': `${collectionName}:view`,
  'x-settings': 'settings:acl',
};
```

## 相关配置

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `ACL_ENABLED` | 是否启用 ACL | `true` |
| `ACL_DEFAULT_ROLE` | 默认角色 | `guest` |

### 插件依赖

权限系统作为核心插件 `@nocobase/plugin-acl` 提供，独立于业务插件存在：

```
@nocobase/plugin-acl
├── server/src/acl/       # 服务端实现
├── client/src/acl/      # 客户端实现
└── index.ts             # 插件入口
```

资料来源：[packages/plugins/@nocobase/plugin-acl](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-acl)

## 总结

NocoBase 的权限系统采用成熟的 ACL 模型，通过角色、权限片段和资源操作的三层结构实现了灵活且强大的访问控制。系统支持服务端的中间件校验和客户端的上下文感知，两端协同确保权限策略的一致性和安全性。开发者应遵循最小权限原则，合理设计角色和 Snippet，在 Schema 中明确声明权限需求，以构建安全可靠的应用系统。

---

<a id='workflow-engine'></a>

## 工作流引擎

### 相关页面

相关主题：[AI 集成与智能员工](#ai-integration), [界面构建器](#interface-builder)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)
- [packages/core/flow-engine/src/components/FlowModelRenderer.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/components/FlowModelRenderer.tsx)
- [packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx)
- [packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx)
- [packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json)
</details>

# 工作流引擎

## 概述

NocoBase 工作流引擎是一个强大的业务流程自动化模块，允许用户通过可视化画布设计、配置和管理自动化工作流程。工作流引擎支持在数据保存前后触发、执行队列任务、审批流程以及自定义操作事件，为业务系统提供灵活的自动化能力。

工作流引擎的核心职责包括：

- 提供可视化的流程设计画布
- 管理流程节点的执行逻辑
- 处理流程执行状态和历史记录
- 支持条件分支和循环控制
- 与系统各模块集成实现自动化触发

资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-50]()

## 架构设计

### 核心组件

工作流引擎由多个核心组件构成，各组件协同完成流程设计、执行和监控功能。

```mermaid
graph TD
    A[FlowSettings 配置面板] --> B[FlowModel 模型层]
    B --> C[FlowModelRenderer 渲染器]
    C --> D[CanvasContent 画布内容]
    D --> E[ExecutionCanvas 执行画布]
    
    F[FlowContext 上下文] --> B
    G[节点组件] --> D
    H[任务队列] --> E
```

### 目录结构

工作流引擎主要代码分布在以下位置：

| 层级 | 路径 | 说明 |
|------|------|------|
| 核心引擎 | `packages/core/flow-engine/` | 流程引擎核心逻辑和组件 |
| 工作流插件 | `packages/plugins/@nocobase/plugin-workflow/` | 工作流可视化设计和执行 |
| 审批插件 | `packages/plugins/@nocobase/plugin-workflow-approval/` | 审批流程支持 |
| 请求插件 | `packages/plugins/@nocobase/plugin-workflow-request/` | HTTP 请求节点支持 |

资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:1-30]()

## FlowSettings 配置系统

`FlowSettings` 是工作流引擎的配置管理核心类，负责注册和管理流程相关的 UI 组件和作用域。

```typescript
export class FlowSettings {
  public components: Record<string, any> = {};
  public scopes: Record<string, any> = {};
  private antdComponentsLoaded = false;
  public enabled: boolean;
  #forceEnabled = false; // 强制启用状态
}
```

### 配置属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `components` | `Record<string, any>` | 注册的流程组件集合 |
| `scopes` | `Record<string, any>` | 流程作用域配置 |
| `antdComponentsLoaded` | `boolean` | Antd 组件加载状态 |
| `enabled` | `boolean` | 流程启用状态 |
| `#forceEnabled` | `boolean` | 强制启用覆盖状态 |

### 底部栏配置

FlowSettings 支持通过 `footer` 属性自定义底部操作栏的展示形式：

```typescript
// 1. 静态自定义 - 直接替换
footer: <div>自定义底部内容</div>

// 2. 包裹式自定义 - 在原节点基础上添加内容
footer: (originNode, { OkBtn, CancelBtn }) => (
  <div style={{ display: 'flex', justifyContent: 'space-between' }}>
    <span>Additional info</span>
    {originNode}
  </div>
)

// 3. 函数式自定义 - 完全重新组合按钮
footer: (originNode, { OkBtn, CancelBtn }) => (
  <Space>
    <CancelBtn title="Close" />
    <Button type="link">Help</Button>
    <OkBtn title="Apply" />
  </Space>
)

// 4. 隐藏底部
footer: null
```

资料来源：[packages/core/flow-engine/src/flowSettings.ts:1-80]()

## 流程渲染器

### FlowModelRenderer

`FlowModelRenderer` 是核心的流程模型渲染组件，负责将流程模型渲染为可视化的流程配置界面。

```typescript
export const FlowModelRenderer: React.FC<FlowModelRendererProps> = React.memo((props) => {
  // 构建渲染内容：统一在渲染前触发 beforeRender 事件（带缓存）
  const content = (
    <FlowModelRendererWithAutoFlows
      model={model}
      showFlowSettings={showFlowSettings}
      flowSettingsVariant={flowSettingsVariant}
      hideRemoveInSettings={hideRemoveInSettings}
      showTitle={showTitle}
      inputArgs={inputArgs}
      showErrorFallback={showErrorFallback}
      settingsMenuLevel={settingsMenuLevel}
      extraToolbarItems={extraToolbarItems}
      fallback={fallback}
      useCache={resolvedUseCache}
    />
  );

  // 当需要错误回退时，将整体包裹在 ErrorBoundary 和 FlowModelProvider 中
  if (showErrorFallback) {
    return (
      <FlowModelProvider model={model}>
        <ErrorBoundary FallbackComponent={FlowErrorFallback}>{content}</ErrorBoundary>
      </FlowModelProvider>
    );
  }

  return content;
});
```

### MemoFlowModelRenderer

对于需要优化渲染性能的场景，引擎提供了 `MemoFlowModelRenderer` 包装版本，仅在父级重渲且 props 浅比较未变时跳过渲染，不影响内部响应式更新。

```typescript
export const MemoFlowModelRenderer = React.memo(FlowModelRenderer);
MemoFlowModelRenderer.displayName = 'MemoFlowModelRenderer';
```

### Props 配置

| 属性 | 类型 | 说明 |
|------|------|------|
| `model` | `Model` | 流程数据模型 |
| `showFlowSettings` | `boolean` | 是否显示流程设置 |
| `flowSettingsVariant` | `string` | 设置面板变体 |
| `hideRemoveInSettings` | `boolean` | 在设置中隐藏删除按钮 |
| `showTitle` | `boolean` | 是否显示标题 |
| `inputArgs` | `any[]` | 输入参数列表 |
| `showErrorFallback` | `boolean` | 是否显示错误回退 |
| `settingsMenuLevel` | `'first' \| 'second'` | 设置菜单层级 |
| `extraToolbarItems` | `ReactNode` | 额外工具栏项 |
| `fallback` | `ComponentType` | 自定义回退组件 |
| `useCache` | `boolean` | 是否启用缓存 |

资料来源：[packages/core/flow-engine/src/components/FlowModelRenderer.tsx:1-100]()

## 执行上下文

### FlowContext

`FlowContext` 提供流程执行时的运行时上下文，贯穿整个流程执行生命周期。

```typescript
<FlowContext.Provider
  value={{
    workflow: workflow.type ? workflow : null,
    nodes,
    execution,
    viewJob,
    setViewJob,
  }}
>
  {children}
</FlowContext.Provider>
```

### 上下文属性

| 属性 | 说明 |
|------|------|
| `workflow` | 当前执行的流程对象 |
| `nodes` | 流程节点配置列表 |
| `execution` | 执行实例信息 |
| `viewJob` | 当前查看的任务节点 |
| `setViewJob` | 设置查看任务的方法 |

资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:1-60]()

## 可视化画布

### CanvasContent

画布内容组件负责渲染流程节点的可视化展示和交互。

```typescript
<div className="workflow-canvas-wrapper">
  <ErrorBoundary>
    <div className="workflow-canvas">
      <div className="workflow-canvas-content">
        <div className={styles.terminalClass}>{lang('Start')}</div>
        {renderNodes(entry, nodes)}
        <div className={styles.terminalClass}>{lang('End')}</div>
      </div>
    </div>
  </ErrorBoundary>
  {copiedNode ? (
    <div className={styles.clipboardPreviewClass}>
      <div className="workflow-clipboard-header">
        <span>{lang('Copied node')}</span>
      </div>
      <div className="workflow-clipboard-card">
        <div className="workflow-clipboard-type">{copiedTypeTitle}</div>
        <div className="workflow-clipboard-title">{copiedNode.title ?? copiedNode.type}</div>
      </div>
    </div>
  ) : null}
  <div className="workflow-canvas-zoomer">
    <Slider vertical reverse defaultValue={100} step={10} min={10} value={zoom} onChange={setZoom} />
  </div>
</div>
```

### 画布功能

| 功能 | 说明 |
|------|------|
| 节点渲染 | 渲染流程中的所有节点和连接线 |
| 剪贴板预览 | 显示复制的节点信息 |
| 缩放控制 | 支持 10%-100% 的画布缩放 |
| 错误边界 | 捕获节点渲染中的错误 |

### ExecutionCanvas 执行画布

执行画布展示流程的实际执行状态和结果。

```typescript
<Breadcrumb
  items={[
    { title: <Link to={app.pluginSettingsManager.getRoutePath('workflow')}>{lang('Workflow')}</Link> },
    { title: <Link to={getWorkflowDetailPath(workflow.id)}>{workflow.title}</Link> },
    { title: <ExecutionsDropdown /> },
  ]}
/>
<Tag color={statusOption.color}>{compile(statusOption.label)}</Tag>
<time>{str2moment(execution.updatedAt).format('YYYY-MM-DD HH:mm:ss')}</time>
```

### 执行状态展示

| 元素 | 说明 |
|------|------|
| 面包屑导航 | 显示从流程列表到具体执行的路径 |
| 状态标签 | 以颜色区分执行状态 |
| 时间戳 | 显示最后更新时间 |
| 取消按钮 | 可取消未完成的执行 |

资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx:1-80]()
资料来源：[packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:1-70]()

## 触发机制

工作流支持多种触发方式，满足不同业务场景的自动化需求。

```mermaid
graph LR
    A[数据保存] --> B[触发前 Pre-Action]
    A --> C[触发后 Post-Action]
    D[按钮点击] --> E[自定义事件]
    F[定时任务] --> G[队列执行]
```

### 触发类型

| 触发类型 | 说明 | 支持模式 |
|----------|------|----------|
| 保存后触发 | 数据保存成功后自动执行 | 本地模式 |
| 提交后触发 | 表单提交成功后执行 | 全模式 |
| 删除前触发 | 数据删除前执行（仅本地模式） | 本地模式 |
| 按钮点击 | 点击按钮直接触发 | 自定义事件 |
| 后台队列 | 作为排队任务后台执行 | 全模式 |

资料来源：[packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:1-50]()

## 国际化支持

工作流引擎内置多语言支持，核心翻译键值如下：

| 键值 | 中文 | 英文 |
|------|------|------|
| `Workflow` | 工作流 | 工作流 |
| `Workflow tasks` | 工作流任务 | 工作流任务 |
| `Workflow todos` | 工作流待办 | 工作流待办 |
| `View result` | 查看结果 | 查看结果 |
| `Workflow executed` | 工作流已执行 | 工作流已执行 |
| `Execution status` | 执行状态 | 执行状态 |

资料来源：[packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:50-100]()

## 相关插件

### plugin-workflow

基础工作流插件，提供核心的流程设计、执行和管理功能。

- 可视化流程画布设计
- 节点配置和管理
- 执行历史记录
- 流程复制和粘贴

### plugin-workflow-approval

审批流程插件，扩展工作流引擎支持审批业务场景。

- 审批节点类型
- 审批人指定
- 审批意见记录

### plugin-workflow-request

HTTP 请求插件，支持在工作流中发起外部 API 调用。

- HTTP 请求节点
- 响应数据处理
- 错误处理机制

## 最佳实践

### 性能优化

1. **使用 MemoFlowModelRenderer**：在父组件频繁重渲但实际数据未变的场景，使用 Memo 版本避免不必要的重渲
2. **合理设置 useCache**：启用缓存可减少重复计算，但需注意数据一致性问题
3. **showErrorFallback 策略**：在复杂节点场景启用错误边界，避免单个节点错误导致整个流程崩溃

### 错误处理

1. **ErrorBoundary 包装**：确保节点渲染错误被正确捕获
2. **FlowErrorFallback 自定义**：根据业务需求提供友好的错误展示
3. **FlowModelProvider 上下文**：在错误回退中仍可获取模型上下文进行恢复操作

## 总结

NocoBase 工作流引擎采用模块化设计，通过 FlowSettings 配置系统、FlowModelRenderer 渲染器、CanvasContent 画布和 ExecutionCanvas 执行画布等核心组件，为业务系统提供了完整的流程自动化能力。引擎支持多种触发机制、可视化设计和执行监控，结合审批和请求等扩展插件，能够满足复杂业务场景的流程自动化需求。

---

<a id='ai-integration'></a>

## AI 集成与智能员工

### 相关页面

相关主题：[工作流引擎](#workflow-engine), [权限系统与 ACL](#acl-permissions)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/plugins/@nocobase/plugin-ai](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai) - 插件源码未在当前上下文提供
- [packages/plugins/@nocobase/plugin-ai-knowledge-base](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai-knowledge-base) - 插件源码未在当前上下文提供
- [docs/docs/cn/ai-employees/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/cn/ai-employees/index.md) - 文档源码未在当前上下文提供
- [docs/docs/cn/ai-employees/knowledge-base/rag.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/cn/ai-employees/knowledge-base/rag.md) - 文档源码未在当前上下文提供
</details>

# AI 集成与智能员工

## 概述

根据当前检索到的上下文信息，未能获取到 AI 插件和智能员工相关的具体源码文件。以下信息基于 NocoBase 仓库中可访问的通用架构和功能模块进行说明。

### 当前可访问的上下文信息

从仓库中检索到的相关文件主要包括：

| 文件路径 | 说明 |
|---------|------|
| `packages/core/client/src/user/Help.tsx` | 用户帮助菜单，集成外部文档链接 |
| `packages/core/client/src/pm/PluginDetail.tsx` | 插件详情管理组件 |
| `packages/core/client/src/variables/hooks/useBuiltinVariables.ts` | 内置变量系统（含日期、用户、URL参数等） |
| `README.md` | 项目主文档，提及 AI Agent Access 功能 |
| `packages/core/flow-engine/src/flowSettings.ts` | 流程引擎配置系统 |

## AI 集成架构

根据项目 README 中的描述，NocoBase 是一个开源的 AI + No-Code 平台，用于快速构建业务系统。AI 功能建立在经过生产验证的基础设施和所见即所得的 No-Code 界面上。

> Coding agents get a... (文档内容在此处截断)

## 变量系统与 AI 上下文

NocoBase 的内置变量系统为 AI 集成提供了上下文数据支持：

```typescript
// 资料来源：packages/core/client/src/variables/hooks/useBuiltinVariables.ts:1-100

const builtinVariables = [
  {
    name: '$date',
    ctx: datetimeCtx,  // 日期时间上下文
  },
  {
    name: '$nExactDate',
    ctx: exactDateTimeCtx,  // 精确日期时间
  },
  {
    name: '$system',
    ctx: {
      now: () => dayjs().toISOString(),
    },
  },
  {
    name: 'currentTime',
    ctx: () => dayjs().toISOString(),
  },
  {
    name: urlSearchParamsName,
    ctx: urlSearchParamsCtx,
    defaultValue,
  },
];
```

| 变量名称 | 用途 | 状态 |
|---------|------|------|
| `$date` | 当前日期时间 | 已弃用 |
| `$nExactDate` | 精确日期时间 | 活跃 |
| `$system` | 系统信息（含 now 方法） | 已弃用 |
| `currentTime` | 当前时间戳 | 已弃用 |
| URL 参数变量 | 动态 URL 参数 | 活跃 |

## 文档资源链接

根据 Help 组件配置，NocoBase 提供了以下官方文档资源：

| 资源类型 | 简体中文链接 | 英文链接 |
|---------|-------------|---------|
| 官网首页 | https://www.nocobase.com/cn/ | https://www.nocobase.com |
| 用户手册 | https://v2.docs.nocobase.com/cn/guide/ | https://v2.docs.nocobase.com/guide/ |

> 资料来源：packages/core/client/src/user/Help.tsx:1-60

## 流程引擎配置

AI 智能员工的执行逻辑可能通过流程引擎实现。当前可访问的流程配置支持自定义底部按钮：

```typescript
// 资料来源：packages/core/flow-engine/src/flowSettings.ts:1-50

interface FlowSettingsConfig {
  footer?:
    | React.ReactNode
    | ((originNode: React.ReactNode, extra: { OkBtn: React.FC; CancelBtn: React.FC }) => React.ReactNode)
    | null;
  [key: string]: any;
}
```

## 插件系统

NocoBase 的插件管理器支持查看插件详情，包括依赖兼容性检查：

> 资料来源：packages/core/client/src/pm/PluginDetail.tsx:1-100

| 检查项 | 说明 |
|-------|------|
| 包名称 | 插件的唯一标识符 |
| 版本号 | 当前安装的版本 |
| 依赖兼容性 | 检查 `dist/externalVersion.js` 是否存在 |
| 许可证 | 开源许可证类型 |

## 注意事项

**当前页面内容不完整**

由于以下关键源码文件未在当前检索上下文中提供，无法生成详细的 AI 集成与智能员工技术文档：

1. `packages/plugins/@nocobase/plugin-ai` - AI 核心插件
2. `packages/plugins/@nocobase/plugin-ai-knowledge-base` - AI 知识库插件
3. `docs/docs/cn/ai-employees/index.md` - AI 员工文档首页
4. `docs/docs/cn/ai-employees/knowledge-base/rag.md` - RAG 检索增强生成文档

## 后续步骤

如需完整的技术文档，请提供以下任一方式：

1. **重新检索** - 请求检索上述缺失的 AI 相关源码文件
2. **访问源码** - 直接访问 GitHub 仓库中的 AI 插件目录
3. **访问文档** - 查看官方文档站点 https://docs.nocobase.com/

---

*本页面基于 NocoBase 仓库 v1.0+ 版本编写，部分内容因源码文件不可用而标记为待补充。*

---

<a id='interface-builder'></a>

## 界面构建器

### 相关页面

相关主题：[数据建模与集合管理](#data-modeling), [工作流引擎](#workflow-engine)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)
- [packages/core/client/src/schema-initializer/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-initializer/index.md)
- [packages/core/client/src/schema-component/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/index.md)
- [packages/core/client/src/schema-component/antd/linkageFilter/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/linkageFilter/index.md)
- [packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)
- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)
- [packages/core/client/src/variables/hooks/useBuiltinVariables.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/variables/hooks/useBuiltinVariables.ts)
- [packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md)
</details>

# 界面构建器

## 概述

界面构建器（Interface Builder）是 NocoBase 平台的核心模块之一，用于通过可视化的方式构建业务系统的用户界面。它基于 Schema 驱动的架构设计，允许用户通过声明式配置定义界面结构、数据源、交互行为等，而无需编写大量代码。

界面构建器的核心理念是通过数据驱动的方式实现 UI 的声明式构建，所有界面配置都以 JSON Schema 格式存储在数据库中，支持运行时动态修改和渲染。

## 核心架构

### 整体架构图

```mermaid
graph TD
    A[用户界面] --> B[Schema 配置]
    B --> C[Schema 解析器]
    C --> D[组件映射表]
    D --> E[React 组件]
    E --> A
    
    F[Schema 设置面板] --> B
    G[Schema 初始化器] --> B
    H[Schema 工具栏] --> B
    
    I[数据源配置] --> J[变量系统]
    J --> C
```

### 主要模块

| 模块 | 功能 | 源码位置 |
|------|------|----------|
| Schema Settings | 界面属性的配置面板 | `packages/core/client/src/schema-settings/` |
| Schema Initializer | 向 Schema 中动态插入新节点 | `packages/core/client/src/schema-initializer/` |
| Schema Component | Schema 渲染的核心组件库 | `packages/core/client/src/schema-component/` |
| Schema Toolbar | 工具栏，提供设计态操作入口 | `packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx` |
| LinkageFilter | 联动规则的条件配置组件 | `packages/core/client/src/schema-component/antd/linkageFilter/` |

## Schema 配置结构

### Schema 基本结构

Schema 是界面构建器的核心配置单元，采用 JSON Schema 格式定义界面的层级结构和属性。

```typescript
{
  type: 'string',
  'x-decorator': 'FormItem',
  'x-component': 'Input',
  'x-component-props': {
    placeholder: '{{t("Please enter")}}',
  },
  'x-designable-bahavior': 'editable'
}
```

### x-designable-bahavior 行为类型

| 行为类型 | 说明 | 源码引用 |
|----------|------|----------|
| `editable` | 可切换 designable 状态 | `schema-component/index.md` |
| `readonly` | 只读状态，不可切换 | `schema-component/index.md` |
| `none` | 完全禁用设计态 | `schema-component/index.md` |

资料来源：[schema-component/index.md:8-11]()

## Schema 初始化器

Schema 初始化器负责在设计时动态向 Schema 中插入新的节点或配置，是实现可视化配置的关键组件。

### 功能特性

- **动态可见性**：根据条件动态显示或隐藏配置项
- **子节点动态加载**：支持按需加载子配置节点
- **Schema 插入**：支持多种类型的 Schema 插入模式

### 插入模式

| 模式 | 说明 | 示例位置 |
|------|------|----------|
| Basic | 基础插入模式 | `demos/insert-schema-basic.tsx` |
| Action | 动作类插入 | `demos/insert-schema-action.tsx` |
| FormItem | 表单项插入 | `demos/insert-schema-form-item.tsx` |

资料来源：[schema-initializer/index.md:12-20]()

## Schema 设置面板

Schema 设置面板提供配置界面的入口，允许用户修改 Schema 节点的各种属性。

### GeneralSchemaDesigner 组件

`GeneralSchemaDesigner` 是核心的 Schema 设计器组件，提供了完整的可视化编辑能力。

```typescript
interface SchemaToolbarProps {
  title?: string | string[];
  showDataSource?: boolean;
  dataSource?: any;
  template?: boolean;
  draggable?: boolean;
  disableInitializer?: boolean;
}
```

资料来源：[GeneralSchemaDesigner.tsx:145-153]()

### 工具栏功能

| 功能 | 说明 | 交互方式 |
|------|------|----------|
| 拖拽手柄 | 支持 Schema 节点拖拽排序 | `DragHandler` 组件 |
| 初始化器 | 插入新的 Schema 节点 | `InitializerComponent` |
| 设置下拉菜单 | 访问节点属性配置 | `SchemaSettingsDropdown` |
| 数据源显示 | 显示当前节点所属数据源 | 标题区域 |

资料来源：[GeneralSchemaDesigner.tsx:40-75]()

### 标题渲染逻辑

```typescript
// 数据源和标题组合显示
{dataSource ? `${compile(dataSource?.displayName)} > ${compile(title)}` : compile(title)}
```

## 组件类型系统

### 内置组件类型

NocoBase 提供了多种内置组件类型，可直接在 Schema 中引用：

| 类型 | 用途 | 源码 |
|------|------|------|
| FormItem | 表单项装饰器 | 内置 |
| Input | 文本输入 | antd |
| Select | 下拉选择 | antd |
| Markdown | Markdown 编辑器 | 自定义 |

### LinkageFilter 组件

`LinkageFilter` 用于前端联动规则的条件配置，支持变量、操作符的联动变化。

```typescript
type FilterActionProps<T = {}> = ActionProps & {
  options?: any[];
  form?: Form;
  onSubmit?: (values: T) => void;
  onReset?: (values: T) => void;
}
```

资料来源：[linkageFilter/index.md:7-13]()

## 变量系统

### 内置变量

界面构建器支持丰富的内置变量，用于在配置中引用运行时数据：

| 变量名 | 说明 | 类型 |
|--------|------|------|
| `$nDate` | 当前日期时间 | ISO 8601 格式 |
| `$nExactDate` | 精确时间戳 | ISO 8601 格式 |
| `$date` | 日期（已废弃） | 兼容性支持 |
| `$system` | 系统变量（已废弃） | 兼容性支持 |
| `$urlSearchParams` | URL 查询参数 | 对象 |
| `currentTime` | 当前时间（已废弃） | 兼容性支持 |

资料来源：[useBuiltinVariables.ts:30-70]()

### 变量上下文结构

```typescript
{
  name: '$nDate',
  ctx: () => dayjs().toISOString(),
  defaultValue?: any
}
```

## 流程设置集成

界面构建器与流程引擎深度集成，支持在配置面板中嵌入流程节点设置。

### FlowSettings 配置结构

```typescript
interface FlowSettingsProps {
  footer?: React.ReactNode | 
    ((originNode: React.ReactNode, extra: { 
      OkBtn: React.FC; 
      CancelBtn: React.FC 
    }) => React.ReactNode) | null;
  onCancel?: () => void | Promise<void>;
  onSaved?: () => void | Promise<void>;
}
```

资料来源：[flowSettings.ts:40-52]()

### 自定义 Footer 示例

```tsx
// 在底部工具栏添加内容
footer: (originNode, { OkBtn, CancelBtn }) => (
  <div style={{ display: 'flex', justifyContent: 'space-between' }}>
    <span>Additional info</span>
    {originNode}
  </div>
)

// 隐藏底部
footer: null
```

## 移动端适配

### 桌面模式组件

当在桌面端访问移动端页面时，系统会渲染 `DesktopMode` 组件进行适配。

```tsx
<DesktopMode>
  <Mobile />
</DesktopMode>
```

资料来源：[packages/plugins/@nocobase/plugin-mobile/src/client/desktop-mode/index.md]()

### 移动端 TabBar

移动端使用自定义的 `MobileTabBar` 组件，支持链接跳转功能：

| 功能 | 说明 |
|------|------|
| Inner Link | 内部页面跳转 |
| Outer Page | 外部页面跳转 |
| Selected | 选中状态管理 |

资料来源：[mobile-layout/index.md]()

## 设计态与运行态

### 状态切换机制

```mermaid
stateDiagram-v2
    [*] --> Designable: 设计态开启
    Designable --> [*]: 保存配置
    Designable --> Readonly: 切换为只读
    Readonly --> Designable: 重新编辑
    Readonly --> [*]: 退出编辑
```

### Designable 上下文

通过 `useDesignable()` Hook 可以获取当前设计态状态：

```typescript
const { designable } = useDesignable();
```

## 配置示例

### 基本 Schema 配置

```typescript
{
  type: 'object',
  properties: {
    name: {
      type: 'string',
      'x-decorator': 'FormItem',
      'x-component': 'Input',
      'x-component-props': {
        placeholder: '{{t("Name")}}',
      },
    },
  },
}
```

### Markdown 编辑器配置

```typescript
{
  content: {
    type: 'string',
    'x-decorator': 'FormItem',
    'x-component': (props) => {
      return ctx.markdown.edit({
        ...props,
        value: props.value || ctx.model.props.value,
        mode: 'sv',
        height: '82vh',
      });
    },
  },
}
```

资料来源：[packages/core/client/src/flow/flows/editMarkdownFlow.tsx]()

## 最佳实践

### 性能优化

1. **减少不必要的渲染**：使用 `React.memo` 包装自定义组件
2. **延迟加载**：对于复杂配置，使用动态导入
3. **状态管理**：合理使用 Context 避免过度 prop drilling

### 可维护性

1. **Schema 分离**：将复杂的 Schema 拆分为多个子 Schema
2. **组件复用**：提取公共配置为可复用组件
3. **类型定义**：为自定义配置提供完整的 TypeScript 类型支持

## 相关资源

- [Schema Settings 文档](./schema-settings/index.md)
- [Schema Initializer 文档](./schema-initializer/index.md)
- [Schema Component 文档](./schema-component/index.md)
- [流程引擎文档](../flow-engine/index.md)

---

<a id='file-manager'></a>

## 文件管理与存储

### 相关页面

相关主题：[数据建模与集合管理](#data-modeling), [界面构建器](#interface-builder)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/client/src/schema-component/antd/upload/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/upload/index.md)
- [packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts)
- [packages/plugins/@nocobase/plugin-file-manager](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-file-manager) - *未在本次检索中获取到详细内容*
- [packages/plugins/@nocobase/plugin-file-storage-s3-pro](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-file-storage-s3-pro) - *未在本次检索中获取到详细内容*
- [docs/docs/cn/file-manager/index.md](https://github.com/nocobase/nocobase/blob/main/docs/docs/cn/file-manager/index.md) - *未在本次检索中获取到详细内容*
</details>

# 文件管理与存储

## 概述

NocoBase 的文件管理与存储系统是一个模块化的基础设施，用于处理用户上传的文件、文档解析、以及与各种云存储服务的集成。该系统通过插件化的架构设计，支持灵活扩展存储后端，同时提供统一的客户端上传组件和服务器端处理逻辑。

文件管理在 NocoBase 中扮演着关键角色，因为作为一个无代码平台，用户经常需要上传附件、文档、图片等资源，并对其进行管理和应用。

## 核心组件架构

### 上传组件（Upload）

NocoBase 的前端上传组件基于 ant-design 的 Upload 组件进行封装，提供增强的功能和更好的用户体验。

**组件类型定义：**

```ts
type UploadProps = Omit<AntdUploadProps, 'onChange'> & {
  onChange?: (fileList: UploadFile[]) => void;
  serviceErrorMessage?: string;
  value?: any;
  size?: string;
};

type UploadReadPrettyProps = AntdUploadProps;
```

资料来源：[packages/core/client/src/schema-component/antd/upload/index.md:1-9]()

**主要功能特性：**

| 功能 | 描述 |
|------|------|
| 基础上传 | 支持单文件和文件列表上传 |
| 规则验证 | 支持文件类型、大小等上传规则配置 |
| 读写分离 | 提供不同的展示和编辑模式 |
| 错误处理 | 支持自定义服务错误消息 |

### 文档加载器

在 AI 插件中，文件管理系统还负责文档的解析和加载。

```ts
private get aiFilesRepo() {
  return this.plugin.db.getRepository('aiFiles');
}

private get fileManager(): PluginFileManagerServer {
  return this.plugin.app.pm.get('file-manager');
}
```

资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:76-81]()

## 存储插件体系

### 文件管理器插件

文件管理器插件（`plugin-file-manager`）是 NocoBase 核心的文件管理模块，负责：

- 文件元数据管理
- 文件上传处理
- 存储后端抽象
- 访问权限控制

### 存储后端插件

NocoBase 采用插件化的存储后端设计，支持多种存储服务：

| 存储类型 | 插件包 | 说明 |
|----------|--------|------|
| S3 兼容存储 | `plugin-file-storage-s3-pro` | 支持 AWS S3、MinIO 等 S3 兼容服务 |
| 本地存储 | 内置支持 | 开发环境使用 |
| 其他云存储 | 可扩展 | 通过插件机制支持 |

## 数据流架构

```mermaid
graph TD
    A[客户端上传组件] --> B[Upload API 端点]
    B --> C[文件管理器插件]
    C --> D[存储后端选择]
    D --> E[本地磁盘]
    D --> F[S3 兼容存储]
    D --> G[其他云存储]
    E --> H[文件元数据存储]
    F --> H
    G --> H
    H --> I[数据库记录]
```

## 客户端上传组件使用

### 基础用法

```tsx
import { Upload } from '@nocobase/client';

// 基础上传示例
<Upload />
```

### 多文件上传

```tsx
// 多文件上传模式
<Upload multiple />
```

### 带规则验证

```tsx
// 配置上传规则
<Upload 
  rules={[
    { type: 'fileType', value: ['image/jpeg', 'image/png'] },
    { type: 'fileSize', value: 10 * 1024 * 1024 } // 10MB
  ]}
/>
```

### 只读展示

```tsx
// 用于展示已上传文件
<UploadReadPretty value={fileList} />
```

## 服务器端处理

### 文件管理器服务端

文件管理器服务端负责处理上传请求、管理存储后端、以及维护文件元数据：

```ts
private get aiFilesRepo() {
  return this.plugin.db.getRepository('aiFiles');
}

private get fileManager(): PluginFileManagerServer {
  return this.plugin.app.pm.get('file-manager');
}
```

服务器端提供以下核心能力：

1. **文件存储抽象** - 通过统一的接口支持多种存储后端
2. **元数据管理** - 使用 `aiFiles` 仓库管理文件元数据
3. **访问控制** - 集成 NocoBase 的权限系统
4. **文档解析** - 支持 AI 插件的文档加载需求

### 文档解析元数据

```ts
private getParseMeta(meta?: Record<string, any>): DocumentParseMeta | null {
  if (!meta || typeof meta !== 'object') {
    return null;
  }
  return meta[DOCUMENT_PARSE_META_KEY] ?? null;
}
```

资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:47-52]()

## 配置与扩展

### 创建自定义存储后端

开发者可以通过实现以下接口来创建自定义存储后端：

```ts
interface StorageBackend {
  upload(file: Buffer, metadata: FileMetadata): Promise<string>;
  download(path: string): Promise<Buffer>;
  delete(path: string): Promise<void>;
  getUrl(path: string): string;
}
```

### 注册文件处理插件

```ts
// 在插件的 install 方法中注册
this.app.pm.get('file-manager').registerBackend('custom', CustomStorageBackend);
```

## 与 AI 系统的集成

NocoBase 的文件管理系统与 AI 插件深度集成，支持：

- **文档加载** - 从存储中加载文档进行 AI 处理
- **文件解析** - 解析各种文档格式提取内容
- **向量化存储** - 支持将文件内容向量化后存储

```ts
return [
  new Document({
    pageContent: text,
    metadata: {
      source: sourceFile.filename,
      extname,
    },
  }),
];
```

资料来源：[packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:32-40]()

## 最佳实践

### 前端配置建议

1. **合理设置文件大小限制** - 根据业务需求和存储成本设置
2. **使用适当的文件类型白名单** - 提高系统安全性
3. **配置错误提示信息** - 提供清晰的用户反馈

### 存储策略建议

1. **生产环境使用云存储** - 如 S3、阿里云 OSS 等
2. **配置合理的缓存策略** - 减少存储成本
3. **定期清理过期文件** - 释放存储空间

## 相关资源

- [NocoBase 官方文档](https://docs.nocobase.com/)
- [文件管理器插件源码](https://github.com/nocobase/nocobase/tree/main/packages/plugins/@nocobase/plugin-file-manager)
- [S3 存储插件源码](https://github.com/nocobase/nocobase/tree/main/packages/plugins/@nocobase/plugin-file-storage-s3-pro)

---

<a id='plugin-development'></a>

## 插件开发指南

### 相关页面

相关主题：[系统架构与设计模式](#system-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/client/src/pm/PluginDetail.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginDetail.tsx)
- [packages/core/client/src/pm/PluginManagerLink.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/pm/PluginManagerLink.tsx)
- [packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx)
- [packages/core/client/src/schema-initializer/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-initializer/index.md)
- [packages/core/flow-engine/src/flowSettings.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/flowSettings.ts)
- [packages/core/flow-engine/src/runjs-context/contexts/base.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/flow-engine/src/runjs-context/contexts/base.ts)
- [packages/core/client/src/variables/hooks/useBuiltinVariables.ts](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/variables/hooks/useBuiltinVariables.ts)
- [packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/mobile-layout/index.md)
- [packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-mobile/src/client/pages/index.md)
- [packages/core/client/src/schema-component/antd/linkageFilter/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/antd/linkageFilter/index.md)
- [packages/core/client/src/schema-settings/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-settings/index.md)
- [packages/core/client/src/schema-component/index.md](https://github.com/nocobase/nocobase/blob/main/packages/core/client/src/schema-component/index.md)
</details>

# 插件开发指南

## 概述

NocoBase 采用插件化架构，所有功能均以插件形式实现。插件系统是 NocoBase 的核心组成部分，允许开发者通过编写插件来扩展系统功能，实现模块化的功能管理与部署。

NocoBase 的插件分为两类：

- **客户端插件**：负责用户界面、页面路由、Schema 组件、Schema 初始化器等前端功能
- **服务器端插件**：负责数据模型、API 接口、业务逻辑、数据库操作等后端功能

一个完整的插件可以同时包含客户端和服务器端代码，通过统一的插件机制进行注册和管理。

## 插件架构

### 核心架构图

```mermaid
graph TB
    subgraph 客户端 Client
        UI[用户界面]
        SC[Schema 组件]
        SI[Schema 初始化器]
        SS[Schema 设置]
        PM_UI[插件管理器 UI]
    end

    subgraph 服务器端 Server
        API[API 接口]
        DB[数据库操作]
        MODEL[数据模型]
        HOOKS[Hooks 钩子]
    end

    subgraph 核心 Core
        PM[插件管理器 PluginManager]
        PM_API[插件 API]
    end

    UI --> PM_UI
    SC --> SS
    SI --> SS
    PM_UI --> PM
    PM --> PM_API
    API --> PM_API
    DB --> PM_API
    MODEL --> PM_API
    HOOKS --> PM_API

    style PM fill:#e1f5fe
    style PM_API fill:#e1f5fe
```

### 插件生命周期

```mermaid
stateDiagram-v2
    [*] --> 安装: npm install
    安装 --> 启用: enable()
    启用 --> 加载: load()
    加载 --> 运行: activate()
    运行 --> 禁用: deactivate()
    禁用 --> 启用: activate()
    启用 --> 卸载: disable()\nuninstall()
    运行 --> 卸载: disable()\nuninstall()
    卸载 --> [*]
```

## 目录结构

一个典型的插件项目目录结构如下：

```
packages/plugins/@nocobase/plugin-sample/
├── src/
│   ├── client/                    # 客户端代码
│   │   ├── index.ts               # 客户端插件入口
│   │   ├── pages/                 # 页面组件
│   │   ├── components/            # 自定义组件
│   │   ├── schema-components/    # Schema 组件
│   │   ├── schema-initializers/   # Schema 初始化器
│   │   ├── schema-settings/       # Schema 设置
│   │   ├── demos/                 # 文档示例
│   │   └── index.md               # 文档
│   └── server/                    # 服务器端代码
│       ├── index.ts               # 服务器端插件入口
│       ├── actions/               # 自定义 actions
│       ├── collections/           # 数据模型定义
│       └── migrations/            # 数据库迁移
├── package.json
└── README.md
```

## 服务器端插件开发

### 插件类基础

服务器端插件继承自 `Plugin` 基类，通过覆写生命周期方法来实现功能：

```typescript
import { Plugin } from '@nocobase/server';

export class SamplePlugin extends Plugin {
  async load() {
    // 加载阶段：注册数据模型、API 路由等
    this.app.collection({
      name: 'samples',
      fields: [
        { type: 'string', name: 'title' },
        { type: 'text', name: 'description' },
      ],
    });

    this.app.acl.allow('samples', 'list');
  }

  async activate() {
    // 激活阶段：执行初始化逻辑
  }

  async deactivate() {
    // 停用阶段：清理资源
  }
}

export default SamplePlugin;
```

### 数据模型定义

```typescript
this.app.collection({
  name: 'articles',
  fields: [
    { type: 'belongsTo', name: 'author' },
    { type: 'hasMany', name: 'comments' },
    { type: 'string', name: 'title' },
    { type: 'richtext', name: 'content' },
    { type: 'date', name: 'publishedAt' },
    { type: 'boolean', name: 'isPublished' },
  ],
});
```

### API 路由注册

```typescript
this.app.resourcer.define({
  name: 'articles',
  actions: {
    async list(ctx, next) {
      // 自定义列表逻辑
      await next();
    },
    async create(ctx, next) {
      ctx.request.body.author = ctx.state.currentUser.id;
      await next();
    },
  },
});
```

### Hooks 机制

NocoBase 提供了丰富的 Hooks 用于扩展功能：

| Hook 名称 | 说明 | 使用场景 |
|---------|------|---------|
| `beforeSave` | 保存前执行 | 数据校验、默认值设置 |
| `afterSave` | 保存后执行 | 关联操作、日志记录 |
| `beforeFind` | 查询前执行 | 权限过滤、条件追加 |
| `afterFind` | 查询后执行 | 数据转换、字段处理 |
| `beforeRemove` | 删除前执行 | 关联删除、权限校验 |
| `afterRemove` | 删除后执行 | 清理操作、通知发送 |

```typescript
this.app.on('afterSave', async (event, model) => {
  if (model.get('type') === 'published') {
    // 发送通知等操作
  }
});
```

### 资源上下文 API

插件可以通过 `ctx.resource` 访问当前资源上下文：

```typescript
// 设置资源当前数据（仅前端）
ctx.resource.setData(value);

// 从后端刷新数据
await ctx.resource.refresh();

// 订阅资源事件
ctx.resource.on('refresh', () => {});

// 设置资源名称
ctx.resource.setResourceName('users');

// 设置主键/过滤键
ctx.resource.setFilterByTk(id);

// 执行资源动作
await ctx.resource.runAction('create', data);
```

## 客户端插件开发

### 插件入口

```typescript
import { Plugin } from '@nocobase/client';

export class SamplePlugin extends Plugin {
  async load() {
    // 注册页面路由
    this.app.router.add('sample', {
      path: '/sample',
      Component: SamplePage,
    });

    // 注册 Schema 组件
    this.app.schemaInitializerManager.add('SampleInitializer', {
      // ...
    });

    // 注册 Schema 设置
    this.app.schemaSettingsManager.add('SampleSetting', {
      // ...
    });
  }
}

export default SamplePlugin;
```

### Schema 组件

Schema 是 NocoBase 前端配置的核心机制，用于描述界面结构和行为：

```mermaid
graph LR
    A[Schema 配置] --> B[组件渲染]
    A --> C[数据绑定]
    A --> D[事件处理]
    A --> E[样式配置]
```

#### Schema 基础结构

```typescript
const schema = {
  type: 'void',
  'x-component': 'SampleCard',
  'x-component-props': {
    title: '{{ title }}',
  },
  properties: {
    content: {
      type: 'void',
      'x-component': 'Markdown',
      'x-content': '{{ content }}',
    },
  },
};
```

#### Schema 组件类型

| 类型 | 说明 | 示例 |
|-----|------|------|
| `void` | 容器组件 | `Grid`, `Card`, `Form` |
| `string` | 文本输入 | `Input`, `Textarea` |
| `number` | 数字输入 | `InputNumber` |
| `boolean` | 开关选择 | `Switch` |
| `date` | 日期选择 | `DatePicker` |

### Schema 初始化器

Schema 初始化器用于在设计器中插入 Schema 节点：

```typescript
this.app.schemaInitializerManager.add('SampleBlockInitializer', {
  title: '示例区块',
  icon: 'PlusOutlined',
  sections: {
    basic: {
      title: '基础',
      items: [
        {
          title: '表格',
          schema: {
            type: 'void',
            'x-component': 'Table',
          },
        },
      ],
    },
  },
});
```

#### 动态显示和隐藏

```typescript
{
  'x-initializer': 'SampleInitializer',
  'x-initializer-props': {
    filter: (node) => node.schema?.['x-designer'] === 'SampleDesigner',
  },
}
```

### Schema 设置

Schema 设置用于配置 Schema 节点的属性：

```typescript
this.app.schemaSettingsManager.add('SampleSetting', {
  title: '示例设置',
  items: [
    {
      name: 'title',
      title: '标题',
      component: {
        name: 'Input',
        props: {
          placeholder: '{{ t("Title") }}',
        },
      },
    },
    {
      name: 'description',
      title: '描述',
      component: {
        name: 'TextArea',
        props: {
          rows: 4,
        },
      },
    },
    {
      name: 'divider',
      type: 'divider',
    },
    {
      name: 'delete',
      title: '删除',
      component: {
        name: 'Delete',
        props: {
          danger: true,
        },
      },
    },
  ],
});
```

### Schema 设计器

Schema 设计器提供可视化编辑 Schema 的能力：

```typescript
import { GeneralSchemaDesigner } from '@nocobase/client';

const SampleDesigner = () => {
  return (
    <GeneralSchemaDesigner
      title="示例设计器"
      schemaSettings={['SampleSetting', 'divider', 'delete']}
    />
  );
};
```

## 插件管理器

NocoBase 提供了内置的插件管理器，支持插件的安装、启用、禁用和卸载。

### 插件信息展示

插件详情页面展示以下信息：

| 字段 | 说明 |
|-----|------|
| 名称 (Name) | 插件内部名称 |
| 显示名称 (DisplayName) | 用户友好的名称 |
| 包名 (PackageName) | npm 包名 |
| 版本 (Version) | 当前版本号 |
| 作者 (Author) | 插件作者 |
| 仓库 (Repository) | 源码仓库地址 |
| 主页 (Homepage) | 文档或项目主页 |
| 许可证 (License) | 开源许可证 |
| 描述 (Description) | 插件功能描述 |

### 依赖兼容性检查

插件管理器会检查插件依赖的兼容性：

```typescript
// 检查是否包含 externalVersion.js
if (data?.data?.depsCompatible === false) {
  return <Alert type="error" message="dist/externalVersion.js 未找到或加载失败，请重新构建插件。" />;
}

// 检查依赖版本是否兼容
if (!data?.data?.['isCompatible']) {
  return <Alert type="error" message="插件依赖检查失败，请调整依赖版本。" />;
}
```

## 变量系统

NocoBase 提供了内置变量系统，支持在配置中使用动态值：

### 内置变量

| 变量名 | 说明 | 示例 |
|-------|------|------|
| `$nRecord` | 当前记录数据 | `$nRecord.title` |
| `$nUser` | 当前用户信息 | `$nUser.id`, `$nUser.name` |
| `$nRole` | 当前角色信息 | `$nRole.name` |
| `$nDate` | 当前日期时间 | `$nDate.format('YYYY-MM-DD')` |
| `$nExactDate` | 精确时间戳 | `$nExactDate` |
| `$date` | 日期（已废弃） | - |
| `$system` | 系统变量（已废弃） | - |
| `currentTime` | 当前时间（已废弃） | - |
| `$nVisible` | 可见性控制 | `$nVisible` |

### 变量上下文

```typescript
{
  name: '$nUser',
  ctx: {
    id: () => currentUser.id,
    name: () => currentUser.name,
    email: () => currentUser.email,
  },
}
```

## 流程引擎集成

插件可以与流程引擎集成，实现复杂的业务流程：

### 自定义动作

```typescript
import { FlowSettings } from '@nocobase/plugin-workflow';

class SamplePlugin extends Plugin {
  async load() {
    // 注册流程设置组件
    this.app.setFlowSettings({
      components: {
        SampleNode: SampleNodeComponent,
      },
      scopes: {
        sampleScope: SampleScopeComponent,
      },
    });
  }
}
```

### 自定义 Footer

流程设置支持自定义底部按钮区域：

```typescript
// 方式一：追加内容
footer: (originNode, { OkBtn, CancelBtn }) => (
  <div style={{ display: 'flex', justifyContent: 'space-between' }}>
    <span>Additional info</span>
    {originNode}
  </div>
)

// 方式二：完全自定义
footer: (originNode, { OkBtn, CancelBtn }) => (
  <Space>
    <CancelBtn title="Close" />
    <OkBtn title="Apply" />
  </Space>
)

// 方式三：隐藏底部
footer: null
```

## 移动端插件开发

NocoBase 支持移动端页面的开发，通过 MobileTabBar 提供底部导航：

### MobileTabBar 组件

```typescript
import { MobileTabBar } from '@nocobase/plugin-mobile';

// 使用 Link 跳转
<MobileTabBar.Link
  to="/pages/home/index"
  icon={<HomeOutlined />}
  title="首页"
/>

// 外部链接
<MobileTabBar.Link
  to="https://example.com"
  external
  icon={<GlobalOutlined />}
  title="外部链接"
/>
```

### Schema 定义

```typescript
{
  type: 'void',
  'x-component': 'MobileTabBar',
  'x-component-props': {
    activeKey: '{{ activeKey }}',
  },
  properties: {
    home: {
      type: 'void',
      'x-component': 'MobileTabBar.Item',
      'x-component-props': {
        key: 'home',
        icon: 'HomeOutlined',
        link: '/pages/home/index',
      },
    },
  },
}
```

### Desktop Mode

当在桌面端访问移动端页面时，可以使用 DesktopMode 组件：

```typescript
import { DesktopMode } from '@nocobase/plugin-mobile';

<DesktopMode>
  <MobilePage />
</DesktopMode>
```

## 联动规则

NocoBase 支持在表单中使用联动规则，实现字段间的动态关联：

### LinkageFilter 组件

```typescript
type FilterActionProps<T = {}> = ActionProps & {
  options?: any[];           // 可选的操作符
  form?: Form;              // 表单实例
  onSubmit?: (values: T) => void;   // 提交回调
  onReset?: (values: T) => void;    // 重置回调
};
```

### 基本用法

左侧支持变量、操作符，右侧变量组件跟随左侧变量联动：

```typescript
{
  type: 'void',
  'x-component': 'LinkageFilter',
  'x-component-props': {
    options: [
      { label: '等于', value: '=' },
      { label: '包含', value: 'contains' },
    ],
    onSubmit: (values) => {
      // 处理筛选
    },
  },
}
```

## 最佳实践

### 1. 插件命名规范

```json
{
  "name": "@nocobase/plugin-{feature-name}",
  "version": "1.0.0",
  "displayName": "{{t('Feature Name')}}",
  "description": "{{t('Plugin description')}}"
}
```

### 2. 国际化支持

```typescript
// 使用 t() 函数进行翻译
title: t('Sample Plugin'),
description: t('This is a sample plugin for demonstration'),

// 支持中文
data?.data?.lang === 'zh-CN' ? '中文链接' : 'English Link'
```

### 3. Schema 组件开发

```typescript
import { SchemaComponent } from '@nocobase/client';

const SampleComponent = (props) => {
  return (
    <SchemaComponent
      schema={{
        type: 'void',
        'x-component': 'Card',
        properties: {
          content: {
            type: 'void',
            'x-component': 'Markdown',
            'x-content': props.content,
          },
        },
      }}
    />
  );
};
```

### 4. 错误处理

```typescript
// 插件加载失败处理
async load() {
  try {
    await this.registerCollections();
    await this.registerActions();
  } catch (error) {
    console.error('Plugin load error:', error);
    throw error;
  }
}

// 依赖检查
if (data?.data?.depsCompatible === false) {
  throw new Error('插件依赖不兼容，请重新构建');
}
```

### 5. 性能优化

```typescript
// 使用 React.memo 优化组件
const SchemaToolbar = React.memo((props) => {
  // ...
});

// 使用 useCallback 缓存回调
const onVisibleChange = useCallback((nextVisible: boolean) => {
  startTransition(() => {
    setVisible(nextVisible);
  });
}, []);
```

## 注册插件到系统

### 服务器端注册

```typescript
// packages/plugins/@nocobase/plugin-sample/src/server/index.ts
import { SamplePlugin } from './SamplePlugin';

export default SamplePlugin;
```

### 客户端注册

```typescript
// packages/plugins/@nocobase/plugin-sample/src/client/index.ts
import { SampleClientPlugin } from './SampleClientPlugin';

export default SampleClientPlugin;
```

### 插件启用

在 `packages/core/server/src/plugins/index.ts` 中添加插件：

```typescript
import sample from '@nocobase/plugin-sample';

export const plugins = [
  // ...其他插件
  sample,
];
```

## 总结

NocoBase 的插件系统提供了完整的扩展能力：

- **模块化架构**：前后端分离的插件开发模式
- **Schema 机制**：灵活的界面配置系统
- **生命周期管理**：完整的插件安装、启用、停用流程
- **依赖管理**：自动化的依赖检查和兼容性验证
- **多端支持**：同时支持桌面端和移动端插件开发

开发者可以通过继承基类、重写生命周期方法、注册组件和配置来实现各种业务需求。

---

---

## Doramagic 踩坑日志

项目：nocobase/nocobase

摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：REST API: Multiple select field not working in edit form。

## 1. 安全/权限坑 · 来源证据：REST API: Multiple select field not working in edit form

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：REST API: Multiple select field not working in edit form
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_36b6b605781f4652849d06443cd76da9 | https://github.com/nocobase/nocobase/issues/8836 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：v2.1.0-alpha.33

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-alpha.33
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_71fc97aec74e43618fab9e19d0aa9a9f | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.33 | 来源类型 github_release 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：v2.1.0-beta.30

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-beta.30
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3eea74dae9c548fc8058563df21058d3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.30 | 来源类型 github_release 暴露的待验证使用条件。

## 4. 配置坑 · 来源证据：v2.0.51

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.0.51
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_06f3ce01049e42f586931cf6e9a46335 | https://github.com/nocobase/nocobase/releases/tag/v2.0.51 | 来源类型 github_release 暴露的待验证使用条件。

## 5. 配置坑 · 来源证据：v2.1.0-alpha.32

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-alpha.32
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7055255c88f94ecc84dfc5c09fc6c3a3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.32 | 来源类型 github_release 暴露的待验证使用条件。

## 6. 配置坑 · 来源证据：v2.1.0-beta.29

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-beta.29
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c4b7dfdc1a164f5cb82fec5622b80342 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.29 | 来源类型 github_release 暴露的待验证使用条件。

## 7. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:306829688 | https://github.com/nocobase/nocobase | README/documentation is current enough for a first validation pass.

## 8. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | last_activity_observed missing

## 9. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium

## 10. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:306829688 | https://github.com/nocobase/nocobase | No sandbox install has been executed yet; downstream must verify before user use.

## 11. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium

## 12. 安全/权限坑 · 来源证据：v2.0.52

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.52
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1ca2b2aac82447ea8ca5b5536fff978e | https://github.com/nocobase/nocobase/releases/tag/v2.0.52 | 来源类型 github_release 暴露的待验证使用条件。

## 13. 安全/权限坑 · 来源证据：v2.1.0-alpha.31

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-alpha.31
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7a2bc590f0974b79880f86db553b3a2e | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.31 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 14. 安全/权限坑 · 来源证据：v2.1.0-beta.27

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.27
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_43d1bbbbee81474cb8e2e4f722fdb398 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.27 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 15. 安全/权限坑 · 来源证据：v2.1.0-beta.32

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.32
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_31e3065c9e884205a29f181cbbc50458 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.32 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 16. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | issue_or_pr_quality=unknown

## 17. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | release_recency=unknown

<!-- canonical_name: nocobase/nocobase; human_manual_source: deepwiki_human_wiki -->