@nocobase/plugin-ai 2.2.0-beta.17 → 2.2.0-beta.18

package/dist/ai/docs/nocobase/ai-dev/watermark-plugin.md

@@ -85,6 +85,8 @@ yarn pm create @my-project/plugin-watermark
 
 AI generates a standard plugin directory structure under `packages/plugins/@my-project/plugin-watermark/`.
 
+Once the scaffold is created, start development mode so your code changes hot-reload: for a project created by `nb init`, run `nb source dev` from the project root (`<app-path>`); for a NocoBase source repository you cloned yourself, run `yarn dev` from the source root.
+
 ### 3. Write Server-Side Code
 
 AI will generate the following files:

package/dist/ai/docs/nocobase/api/cli/api/resource/create.md

@@ -1,12 +1,12 @@
 ---
 title: "nb api resource create"
-description: "nb api resource create command reference: create a record in a selected NocoBase resource."
+description: "nb api resource create command reference: create one or more records in a selected NocoBase resource."
 keywords: "nb api resource create,NocoBase CLI,create record,CRUD"
 ---
 
 # nb api resource create
 
-Create a record in a selected resource. Pass record data as a JSON object through `--values`.
+Create records in a selected resource. Pass record data as a JSON object through `--values`, or as a JSON array of objects to create multiple records in a single request.
 
 ## Usage
 
@@ -21,7 +21,7 @@ nb api resource create --resource <resource> --values <json> [flags]
 | `--resource` | string | Resource name, required |
 | `--data-source` | string | Data source key, default `main` |
 | `--source-id` | string | Source record ID for association resources |
-| `--values` | string | Data for the new record as a JSON object, required |
+| `--values` | string | Data for the new records: a JSON object, or a JSON array of objects to create multiple records; required |
 | `--whitelist` | string[] | Fields allowed to write; repeatable or pass a JSON array |
 | `--blacklist` | string[] | Fields forbidden to write; repeatable or pass a JSON array |
 
@@ -31,6 +31,7 @@ Also supports common connection parameters from [`nb api resource`](./index.md).
 
 ```bash
 nb api resource create --resource users --values '{"nickname":"Ada"}'
+nb api resource create --resource users --values '[{"nickname":"Ada"},{"nickname":"Grace"}]'
 nb api resource create --resource posts.comments --source-id 1 --values '{"content":"Hello"}'
 ```
 

package/dist/ai/docs/nocobase/plugin-development/build.md

@@ -6,7 +6,7 @@ keywords: "plugin build,plugin package,yarn build,tar,build.config.ts,Rsbuild,ts
 
 # Build and Package
 
-After plugin development is complete, you need to go through two steps — build (compile source code) and package (generate `.tar.gz`) — before distributing it to other NocoBase applications.
+After plugin development is complete, you need to go through two steps — build (compile source code) and package (generate `.tgz`) — before distributing it to other NocoBase applications.
 
 ## Build Plugin
 
@@ -26,13 +26,13 @@ If the plugin is created in a source code repository, the first build will trigg
 
 ## Package Plugin
 
-Packaging compresses the build artifacts into a `.tar.gz` file for easy upload to other environments:
+Packaging compresses the build artifacts into a `.tgz` file for easy upload to other environments:
 
 ```bash
 yarn nocobase tar @my-project/plugin-hello
 ```
 
-The package file is output to `storage/tar/@my-project/plugin-hello.tar.gz` by default.
+The package file is output to `storage/tar/` by default, named `<package-name>-<version>.tgz` — for example, `storage/tar/@my-project/plugin-hello-0.1.0.tgz`.
 
 You can also combine build and package into one step using the `--tar` flag:
 
@@ -42,7 +42,13 @@ yarn build @my-project/plugin-hello --tar
 
 ## Upload to Other NocoBase Applications
 
-Upload and extract the `.tar.gz` file to the target application's `./storage/plugins` directory. For detailed steps, see [Install and Upgrade Plugins](../get-started/install-upgrade-plugins.mdx).
+Upload and extract the `.tgz` file to the target application's `./storage/plugins` directory. For detailed steps, see [Install and Upgrade Plugins](../get-started/install-upgrade-plugins.mdx).
+
+If the target application was created with the NocoBase CLI (`nb init`), you can also import it directly with `nb plugin import` instead of extracting it manually:
+
+```bash
+nb plugin import /your/path/plugin-hello-0.1.0.tgz
+```
 
 ### Enable a Plugin by Default
 

package/dist/ai/docs/nocobase/plugin-development/client/appendix/faq.md

@@ -12,7 +12,7 @@ This page collects common pitfalls when developing client plugins. If you run in
 
 ### Plugin not visible in the Plugin Manager after creation
 
-Make sure you ran `yarn pm create` instead of manually creating the directory. `yarn pm create` not only generates files but also registers the plugin in the `applicationPlugins` database table. If you created the directory manually, run `yarn nocobase upgrade` to trigger a rescan.
+Make sure you ran `yarn pm create` instead of manually creating the directory. Besides generating files, `yarn pm create` updates `tsconfig.paths.json` and runs `yarn postinstall`, which links the plugin into `node_modules` and regenerates the client plugin index so the application can discover it. A manually created directory skips that step — run `yarn nocobase upgrade` to rescan and register it in the `applicationPlugins` table.
 
 ### No changes on the page after enabling a plugin
 

package/dist/ai/docs/nocobase/plugin-development/client/examples/custom-action.md

@@ -49,6 +49,8 @@ yarn pm create @my-project/plugin-simple-action
 
 For detailed instructions, see [Writing Your First Plugin](../../write-your-first-plugin).
 
+Next, start development mode so your code changes hot-reload: for a project created by `nb init`, run `nb source dev` from the project root (`<app-path>`); for a NocoBase source repository you cloned yourself, run `yarn dev` from the source root.
+
 ## Step 2: Create Action Models
 
 Each action needs to declare the scenario it appears in via the `static scene` property:

package/dist/ai/docs/nocobase/plugin-development/client/examples/custom-block.md

@@ -51,6 +51,8 @@ yarn pm create @my-project/plugin-simple-block
 
 This will generate a basic file structure under `packages/plugins/@my-project/plugin-simple-block`. For detailed instructions, see [Writing Your First Plugin](../../write-your-first-plugin).
 
+Next, start development mode so your code changes hot-reload: for a project created by `nb init`, run `nb source dev` from the project root (`<app-path>`); for a NocoBase source repository you cloned yourself, run `yarn dev` from the source root.
+
 ## Step 2: Create the Block Model
 
 Create `src/client-v2/models/SimpleBlockModel.tsx`. This is the core of the entire plugin -- defining how the block renders and how it's configured.

package/dist/ai/docs/nocobase/plugin-development/client/examples/custom-field.md

@@ -52,6 +52,8 @@ yarn pm create @my-project/plugin-field-simple
 
 For detailed instructions, see [Writing Your First Plugin](../../write-your-first-plugin).
 
+Next, start development mode so your code changes hot-reload: for a project created by `nb init`, run `nb source dev` from the project root (`<app-path>`); for a NocoBase source repository you cloned yourself, run `yarn dev` from the source root.
+
 ## Step 2: Create the Field Model
 
 Create `src/client-v2/models/DisplaySimpleFieldModel.tsx`. This is the core of the plugin -- defining how the field renders and which field interface it binds to.

package/dist/ai/docs/nocobase/plugin-development/client/examples/fullstack-plugin.md

@@ -55,6 +55,8 @@ yarn pm create @my-project/plugin-custom-table-block-resource
 
 For detailed instructions, see [Writing Your First Plugin](../../write-your-first-plugin).
 
+Next, start development mode so your code changes hot-reload: for a project created by `nb init`, run `nb source dev` from the project root (`<app-path>`); for a NocoBase source repository you cloned yourself, run `yarn dev` from the source root.
+
 ## Step 2: Define the Data Table (Server-Side)
 
 Create `src/server/collections/todoItems.ts`. NocoBase will automatically load collection definitions from this directory:

package/dist/ai/docs/nocobase/plugin-development/client/examples/settings-page.md

@@ -52,6 +52,8 @@ yarn pm create @my-project/plugin-settings-page
 
 This will generate a basic file structure under `packages/plugins/@my-project/plugin-settings-page`, including `src/client-v2/`, `src/server/`, `src/locale/`, and other directories. For detailed instructions, see [Writing Your First Plugin](../../write-your-first-plugin).
 
+Next, start development mode so your code changes hot-reload: for a project created by `nb init`, run `nb source dev` from the project root (`<app-path>`); for a NocoBase source repository you cloned yourself, run `yarn dev` from the source root.
+
 ## Step 2: Register the Settings Page
 
 Edit `src/client-v2/plugin.tsx`. In `load()`, use `this.pluginSettingsManager` to register the settings page. This is done in two steps -- first register the menu entry with `addMenuItem()`, then register the actual page with `addPageTabItem()`:

package/dist/ai/docs/nocobase/plugin-development/common/i18n.md

@@ -61,11 +61,11 @@ export class PluginSampleI18nServer extends Plugin {
           },
         ],
       });
-      await this.app.changeLanguage(answer1);
+      await this.app.i18n.changeLanguage(answer1);
       const answer2 = await input({
-        message: app.i18n.t('Enter your name'),
+        message: this.app.i18n.t('Enter your name'),
       });
-      console.log(app.i18n.t(`Your name is {{name}}`, { name: answer2 }));
+      console.log(this.app.i18n.t(`Your name is {{name}}`, { name: answer2 }));
     });
   }
 }

package/dist/ai/docs/nocobase/plugin-development/server/cache.md

@@ -212,7 +212,7 @@ export default class PluginCacheDemo extends Plugin {
     });
 
     // Create cache using newly registered store
-    const redisCache = await this.app.createCache({
+    const redisCache = await this.app.cacheManager.createCache({
       name: 'redisCache',
       store: 'redis',
       prefix: 'app:',

package/dist/ai/docs/nocobase/plugin-development/server/collections.md

@@ -197,12 +197,6 @@ When a plugin is first activated, the system will automatically synchronize Coll
 yarn nocobase upgrade
 ```
 
-If exceptions or dirty data occur during synchronization, you can rebuild the table structure by reinstalling the application:
-
-```bash
-yarn nocobase install -f
-```
-
 If you need to migrate existing data during plugin upgrades -- such as renaming fields, splitting tables, backfilling default values, etc. -- you should handle it through [Migration](./migration.md) scripts rather than manually modifying the database.
 
 ## Making a Collection Appear in the UI Data Table List

package/dist/ai/docs/nocobase/plugin-development/server/command.md

@@ -30,7 +30,7 @@ export default function (app: Application) {
   app
     .command('echo')
     .option('-v, --version')
-    .action(async ([options]) => {
+    .action(async (options) => {
       console.log('Hello World!');
       if (options.version) {
         console.log('Current version:', await app.version.get());
@@ -68,7 +68,7 @@ export default class PluginHelloServer extends Plugin {
       app
         .command('echo')
         .option('-v, --version')
-        .action(async ([options]) => {
+        .action(async (options) => {
           console.log('Hello World!');
           if (options.version) {
             console.log('Current version:', await app.version.get());

package/dist/ai/docs/nocobase/plugin-development/server/context.md

@@ -56,7 +56,7 @@ resourceManager.use(async (ctx) => {
 
 ```ts
 resourceManager.use(async (ctx) => {
-  await ctx.cache.set('key', 'value', { ttl: 60 }); // Cache for 60 seconds
+  await ctx.cache.set('key', 'value', 60 * 1000); // Cache for 60 seconds (TTL is in milliseconds)
   const val = await ctx.cache.get('key');
   ctx.body = val;
 });
@@ -113,7 +113,7 @@ resourceManager.use(async (ctx) => {
 
 ```ts
 resourceManager.use(async (ctx) => {
-  const canEdit = await ctx.can('edit', 'posts');
+  const canEdit = ctx.can({ resource: 'posts', action: 'edit' });
   if (!canEdit) {
     ctx.throw(403, 'Forbidden');
   }

package/dist/ai/docs/nocobase/plugin-development/server/i18n.md

@@ -68,13 +68,13 @@ export class PluginSampleI18nServer extends Plugin {
         ]
       });
 
-      await this.app.changeLanguage(answer1);
+      await this.app.i18n.changeLanguage(answer1);
 
       const answer2 = await input({
-        message: app.i18n.t('Enter your name')
+        message: this.app.i18n.t('Enter your name')
       });
 
-      console.log(app.i18n.t('Your name is {{name}}', { name: answer2 }));
+      console.log(this.app.i18n.t('Your name is {{name}}', { name: answer2 }));
     });
   }
 }
@@ -129,7 +129,7 @@ export class PluginSampleI18nServer extends Plugin {
   load() {
     this.app.use(async (ctx, next) => {
       if (ctx.path === '/api/plugin-i18n') {
-        ctx.body = this.plugin.t('Hello');
+        ctx.body = this.t('Hello');
       }
       await next();
     });

package/dist/ai/docs/nocobase/plugin-development/write-your-first-plugin.md

@@ -28,50 +28,83 @@ yarn pm create @my-project/plugin-hello
 After the command runs successfully, it will generate basic files in the `packages/plugins/@my-project/plugin-hello` directory. The default structure is as follows:
 
 ```bash
-├─ /packages/plugins/@my-project/plugin-hello
-  ├─ package.json
-  ├─ README.md
-  ├─ client-v2.d.ts
-  ├─ client-v2.js
-  ├─ server.d.ts
-  ├─ server.js
-  └─ src
-     ├─ index.ts                 # Default export server-side plugin
-     ├─ client-v2                 # Client-side code location
-     │  ├─ index.tsx             # Default exported client-side plugin class
-     │  ├─ plugin.tsx            # Plugin entry (extends @nocobase/client-v2 Plugin)
-     │  ├─ models                # Optional: frontend models (such as flow nodes)
-     │  │  └─ index.ts
-     │  └─ utils
-     │     ├─ index.ts
-     │     └─ useT.ts
-     ├─ server                   # Server-side code location
-     │  ├─ index.ts              # Default exported server-side plugin class
-     │  ├─ plugin.ts             # Plugin entry (extends @nocobase/server Plugin)
-     │  ├─ collections           # Optional: server-side collections
-     │  ├─ migrations            # Optional: data migrations
-     │  └─ utils
-     │     └─ index.ts
-     ├─ utils
-     │  ├─ index.ts
-     │  └─ tExpr.ts
-     └─ locale                   # Optional: multi-language
-        ├─ en-US.json
-        └─ zh-CN.json
+packages/plugins/@my-project/plugin-hello/
+├─ package.json
+├─ README.md
+├─ .npmignore
+├─ client-v2.d.ts            # v2 client entry type declaration
+├─ client-v2.js              # v2 client entry
+├─ client.d.ts               # v1 client entry type declaration
+├─ client.js                 # v1 client entry
+├─ server.d.ts               # Server entry type declaration
+├─ server.js                 # Server entry
+└─ src
+   ├─ index.ts               # Default export server-side plugin
+   ├─ client-v2              # v2 client-side code location
+   │  ├─ index.tsx           # Default exported client-side plugin class
+   │  ├─ plugin.tsx          # Plugin entry (extends @nocobase/client-v2 Plugin)
+   │  └─ client.d.ts
+   ├─ client                 # v1 client-side code location
+   │  ├─ index.tsx
+   │  ├─ plugin.tsx
+   │  ├─ locale.ts
+   │  ├─ models
+   │  │  └─ index.ts
+   │  └─ client.d.ts
+   ├─ server                 # Server-side code location
+   │  ├─ index.ts            # Default exported server-side plugin class
+   │  ├─ plugin.ts           # Plugin entry (extends @nocobase/server Plugin)
+   │  └─ collections         # Server-side collections (empty directory initially)
+   └─ locale                 # Locale resources
+      ├─ en-US.json
+      └─ zh-CN.json
 ```
 
-After creation, you can access the plugin manager page in your browser (default URL: http://localhost:13000/admin/settings/plugin-manager) to confirm whether the plugin appears in the list.
+The scaffold generates a minimal skeleton — `src/client-v2/` contains only entry files. The `models/` directory and `locale.ts` used in the following steps are ones you create yourself.
+
+Next, start development mode so your code changes hot-reload:
+
+- If the project was created with the NocoBase CLI (`nb init`), run this from the project root (`<app-path>`):
+
+  ```bash
+  nb source dev
+  ```
+
+- If you cloned the NocoBase source repository yourself, run this from the source root:
+
+  ```bash
+  yarn dev
+  ```
+
+Once it is running, access the plugin manager page in your browser (default URL: http://localhost:13000/admin/settings/plugin-manager) to confirm whether the plugin appears in the list.
 
 ## Step 2: Implement a Simple Client Block
 
 Next, we'll add a custom block model to the plugin to display a welcome message.
 
-1. **Create a new block model file** `client-v2/models/HelloBlockModel.tsx`:
+1. **Create the translation helper file** `src/client-v2/locale.ts`. `tExpr` declares a namespaced translation expression, and `useT` provides the translation function inside components:
+
+```ts
+import { tExpr as _tExpr, useFlowEngine } from '@nocobase/flow-engine';
+// @ts-ignore
+import pkg from '../../package.json';
+
+export function useT() {
+  const engine = useFlowEngine();
+  return (str: string) => engine.context.t(str, { ns: [pkg.name, 'client'] });
+}
+
+export function tExpr(key: string) {
+  return _tExpr(key, { ns: [pkg.name, 'client'] });
+}
+```
+
+2. **Create a new block model file** `src/client-v2/models/HelloBlockModel.tsx`:
 
 ```tsx pure
-import { BlockModel } from '@nocobase/client-v2';
 import React from 'react';
-import { tExpr } from '../utils';
+import { BlockModel } from '@nocobase/client-v2';
+import { tExpr } from '../locale';
 
 export class HelloBlockModel extends BlockModel {
   renderComponent() {
@@ -89,18 +122,27 @@ HelloBlockModel.define({
 });
 ```
 
-2. **Register the block model**. Edit `client-v2/models/index.ts` to export the new model for frontend runtime loading:
+3. **Register the block model**. Creating the model file is not enough on its own — the frontend runtime does not scan the `models/` directory automatically, so you have to register it explicitly in the plugin entry. Edit `src/client-v2/plugin.tsx` and declare how the model is loaded via `registerModelLoaders` inside `load()`:
 
-```ts
-import { ModelConstructor } from '@nocobase/flow-engine';
-import { HelloBlockModel } from './HelloBlockModel';
+```tsx pure
+import { Plugin } from '@nocobase/client-v2';
+
+export class PluginHelloClientV2 extends Plugin {
+  async load() {
+    this.flowEngine.registerModelLoaders({
+      HelloBlockModel: {
+        loader: () => import('./models/HelloBlockModel'),
+      },
+    });
+  }
+}
 
-export default {
-  HelloBlockModel,
-} as Record<string, ModelConstructor>;
+export default PluginHelloClientV2;
 ```
 
-After saving the code, if you're running a development script, you should see hot-reload logs in the terminal output.
+`registerModelLoaders` takes lazy-loading functions, so a model is only loaded once it is actually used. The key (`HelloBlockModel`) must match the model class name — the runtime uses it to pick the model class out of the module's named exports.
+
+After saving the code, if you're running development mode, you should see hot-reload logs in the terminal output.
 
 ## Step 3: Activate and Test the Plugin
 
@@ -162,7 +204,7 @@ If the plugin is created in a source code repository, the first build will trigg
 
 :::
 
-After the build completes, the package file is located at `storage/tar/@my-project/plugin-hello.tar.gz` by default.
+After the build completes, the package file is located under `storage/tar/` by default, named `<package-name>-<version>.tgz` — for example, `storage/tar/@my-project/plugin-hello-0.1.0.tgz`.
 
 :::tip
 
@@ -174,6 +216,12 @@ It's recommended to write test cases to verify core logic before publishing a pl
 
 Upload and extract the package file to the target application's `./storage/plugins` directory. For detailed steps, see [Install and Upgrade Plugins](../get-started/install-upgrade-plugins.mdx).
 
+If the target application was created with the NocoBase CLI (`nb init`), you can also import it directly with `nb plugin import` instead of extracting it manually:
+
+```bash
+nb plugin import /your/path/plugin-hello-0.1.0.tgz
+```
+
 ## Related Links
 
 - [Plugin Development Overview](./index.md) — Understand NocoBase microkernel architecture and plugin lifecycle

package/dist/ai/docs/nocobase/users-permissions/sync/index.md

@@ -8,6 +8,13 @@ pkg: '@nocobase/plugin-user-data-sync'
 
 This feature allows you to register and manage user data synchronization sources. By default, an HTTP API is provided, but additional data sources can be supported through plugins. It supports syncing data to the **Users** and **Departments** collections by default, with the possibility to extend synchronization to other target resources using plugins.
 
+## Available data sources
+
+- [DingTalk](./sources/dingtalk.md) — Synchronize DingTalk users and departments, with incremental updates through HTTP callbacks or Stream mode.
+- [LDAP](./sources/ldap.md) — Synchronize LDAP users and optional organizational units by reusing an LDAP authenticator.
+- [WeCom](./sources/wecom.md) — Synchronize users and departments from WeCom.
+- [HTTP API](./sources/api.md) — Push user and department data through the synchronization API.
+
 ## Data Source Management and Synchronization
 
 
@@ -51,4 +58,4 @@ For failed synchronization tasks, you can click **Retry**.
 In case of synchronization failures, you can troubleshoot the issue through system logs. Additionally, raw synchronization records are stored in the `user-data-sync` directory under the application logs folder.
 
 
-![](https://static-docs.nocobase.com/202412041205655.png)
+![](https://static-docs.nocobase.com/202412041205655.png)

package/dist/ai/docs/nocobase/users-permissions/sync/sources/dingtalk.md

@@ -0,0 +1,138 @@
+---
+pkg: '@nocobase/plugin-auth-dingtalk'
+title: "Synchronize User Data from DingTalk"
+description: "Synchronize DingTalk users and departments to NocoBase and receive incremental changes through HTTP callbacks or Stream mode."
+keywords: "DingTalk,user synchronization,department synchronization,Stream mode,event subscription,NocoBase"
+---
+
+# Synchronize User Data from DingTalk
+
+<PluginInfo commercial="true" name="auth-dingtalk"></PluginInfo>
+
+## Introduction
+
+The **DingTalk** plugin synchronizes users and departments from a DingTalk organization to NocoBase. It supports full synchronization on demand and incremental updates through either an HTTP callback or a Stream connection.
+
+## Before you begin
+
+1. Install and enable the **DingTalk** and **User Data Synchronization** plugins.
+2. Create an internal application in the DingTalk developer console.
+3. Grant the contact permissions and configure the data permission scope described below.
+4. Copy the application's Client ID and Client Secret. See [Authentication: DingTalk](/auth-verification/auth-dingtalk/) for the credential setup.
+
+## Configure contact permissions and the data permission scope
+
+Open **Permission Management** for the application in the DingTalk developer console and grant the following contact permissions.
+
+| Permission | Identifier | Required | Purpose |
+| --- | --- | --- | --- |
+| Read department information | `qyapi_get_department_list` | Yes | Read the department list, names, and hierarchy. |
+| Read department members | `qyapi_get_department_member` | Yes | Read the member list of each department. |
+| Read member information | `qyapi_get_member` | Yes | Read member details and department memberships. |
+| Employee mobile number information | `fieldMobile` | When using mobile numbers | Synchronize mobile numbers. This permission is required when **User unique identifier field** is `mobile`. |
+| Email and other personal information | `fieldEmail` | No | Grant this permission when user email addresses need to be synchronized. |
+
+After granting the permissions, configure the application's **Data Permission Scope** (also called **Contact Permission Scope** or **Visibility Range** in some console versions) to include the departments and employees that may be synchronized. Select all employees for a full organization synchronization. If only selected departments or employees are included, NocoBase synchronizes only those entries.
+
+:::warning
+API permissions determine which fields the application can read, while the data permission scope determines which departments and employees it can read. Both must be configured. Event subscriptions do not replace contact read permissions: after receiving an event, NocoBase still calls DingTalk APIs to retrieve the latest user or department information.
+:::
+
+If the same DingTalk application is also used for sign-in, grant the personal-information permissions described in [Authentication: DingTalk](/auth-verification/auth-dingtalk/). Those sign-in permissions are not required solely for user data synchronization.
+
+## Add a DingTalk synchronization source
+
+Go to **Users & Permissions > Synchronize**, click **Add new**, and select **DingTalk** as the type.
+
+Configure the following fields:
+
+| Field | Description |
+| --- | --- |
+| Source name | A unique name for this synchronization source. |
+| Enabled | Starts event reception for this source and enables synchronization tasks. |
+| Client ID | The Client ID of the DingTalk internal application. Environment variables and secrets are supported. |
+| Client Secret | The Client Secret of the DingTalk internal application. Environment variables and secrets are supported. |
+| User unique identifier field | Select `mobile` or `unionId`. Keep the selected field stable after the first synchronization. Users without a value for the selected field are skipped. |
+| Event receiving mode | Select **HTTP callback** or **Stream mode** for incremental user and department changes. |
+
+Save and enable the source, then click **Sync** to complete the initial full synchronization before relying on incremental events.
+
+## Choose an event receiving mode
+
+### Stream mode
+
+Stream mode establishes an outbound persistent connection from the NocoBase server to DingTalk. It does not require a public callback URL, Token, or EncodingAESKey.
+
+1. In the DingTalk developer console, open the application's event subscription settings and select **Stream mode**.
+2. Subscribe to the user and department change events required by the application.
+3. In NocoBase, select **Stream mode**, save the source, and enable it.
+
+The Stream client starts when the source is enabled. Updating, disabling, or deleting the source refreshes or closes the corresponding connection.
+
+:::info
+The NocoBase server must be able to establish outbound connections to DingTalk. A reverse proxy or public inbound callback endpoint is not required for Stream mode.
+:::
+
+### HTTP callback
+
+HTTP callback mode receives DingTalk events through a NocoBase callback URL.
+
+1. Select **HTTP callback** in NocoBase.
+2. Enter the Token and EncodingAESKey configured for the DingTalk event subscription.
+3. Save the source and copy the generated **Event callback URL**.
+4. Configure that URL in the DingTalk developer console and subscribe to the required user and department events.
+
+The callback URL must be reachable by DingTalk. In a production environment, expose it through HTTPS and make sure the reverse proxy forwards the request path unchanged.
+
+## Supported incremental events
+
+Both event receiving modes handle the following DingTalk events:
+
+| Event | Result in NocoBase |
+| --- | --- |
+| `user_add_org` | Create or update the user. |
+| `user_modify_org` | Update the user. |
+| `user_leave_org` | Delete the synchronized user. |
+| `org_dept_create` | Create or update the department. |
+| `org_dept_modify` | Update the department and synchronize its users. |
+| `org_dept_remove` | Delete the synchronized department. |
+
+## Synchronized fields
+
+### Department fields
+
+| DingTalk field | NocoBase field or purpose |
+| --- | --- |
+| `dept_id` | Source-unique department identifier. |
+| `name` | Department name. |
+| `parent_id` | Parent department used to build the department hierarchy. If the parent is outside the data permission scope, the department is synchronized as a root department. |
+
+### User fields
+
+| DingTalk field | NocoBase field or purpose |
+| --- | --- |
+| `mobile` or `unionid` | Generates the source-unique user identifier and username according to **User unique identifier field**. A user without the selected field is skipped. |
+| `name` | User nickname. |
+| `mobile` | Phone number. Requires the **Employee mobile number information** permission. |
+| `email`, falling back to `org_email` | Email address. Requires the **Email and other personal information** permission. |
+| `dept_id_list` | Department memberships. Only departments within the data permission scope are retained. |
+| `dept_order_list` | Primary department. |
+| `leader_in_dept` | Whether the user is an owner of the corresponding department. |
+
+### Department owners
+
+DingTalk uses `leader_in_dept` in the user details to indicate whether the user is an owner of each department they belong to. NocoBase synchronizes this flag separately for each department: the same user can own multiple departments, and an owned department does not have to be the user's primary department. Only departments within the data permission scope are included.
+
+When an owner flag is removed in DingTalk, the corresponding owner flag in NocoBase is removed by the next synchronization. Owner status changed manually in NocoBase may be overwritten by DingTalk data during the next synchronization.
+
+Full and incremental synchronization use the same field mapping. Other DingTalk user fields, such as avatar, job title, and employee number, are not currently synchronized.
+
+## Troubleshooting
+
+- If synchronization returns no data or an entire department is missing, verify the three required contact read permissions and confirm that the department is included in the data permission scope.
+- If a user is present but their mobile number or email address is empty, verify the **Employee mobile number information** or **Email and other personal information** permission respectively.
+- If DingTalk reports that a department or employee is outside the permission scope, expand the application's data permission scope instead of only resubscribing to events.
+- If users are skipped, verify that they have a value for the configured unique identifier field.
+- For Stream mode, check the application logs for `Dingtalk stream client starting`, `Dingtalk stream client started`, or connection errors.
+- For HTTP callback mode, verify that the callback URL is publicly reachable and that Token and EncodingAESKey match the DingTalk configuration.
+- Run a manual full synchronization after changing the application's permissions or visibility range.