@nocobase/plugin-ai 2.3.0-alpha.1 → 2.3.0-beta.10

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/runjs/context/ai.md

@@ -1,23 +1,51 @@
 ---
 title: "ctx.ai"
-description: "Use ctx.ai in RunJS to trigger AI employee tasks, either with inline task content or with tasks configured on an AI employee action."
-keywords: "ctx.ai,AI employee,triggerTask,triggerModelTask,RunJS,NocoBase"
+description: "Use ctx.ai in RunJS to trigger AI employee tasks in the global conversation or a specified AI Chat Box, either with inline task content or with tasks configured on an AI employee action."
+keywords: "ctx.ai,AI employee,uploadFile,attachments,triggerTask,triggerModelTask,onResponseLoadingChange,chatBoxUid,AI Chat Box,RunJS,NocoBase"
 ---
 
 # ctx.ai
 
 Use `ctx.ai` in RunJS to trigger **AI employee tasks**. It works well in JSBlock, JSAction, and other interactions where a button, form, or business flow needs to hand work to a specific AI employee.
 
-`ctx.ai` only triggers tasks. It does not return the execution result of the AI employee task. After the call, the task enters the AI employee conversation flow, and the result is handled by the AI employee session.
+`ctx.ai` uploads AI task attachments and triggers tasks. File uploads can be awaited, but task triggering does not return the execution result of the AI employee task. After the call, the task enters the AI employee conversation flow, and the result is handled by the AI employee session.
 
 :::warning Note
 
-`ctx.ai` is provided by the AI plugin. If the AI plugin is not enabled, or the current RunJS environment has not loaded the corresponding client capability, `ctx.ai` may not exist. You can check `ctx.ai?.triggerTask` or `ctx.ai?.triggerModelTask` before calling it.
+`ctx.ai` is provided by the AI plugin. If the AI plugin is not enabled, or the current RunJS environment has not loaded the corresponding client capability, `ctx.ai` may not exist. You can check `ctx.ai?.uploadFile`, `ctx.ai?.triggerTask`, or `ctx.ai?.triggerModelTask` before calling it.
 
 :::
 
 ## Methods
 
+### ctx.ai.uploadFile()
+
+Upload one file and return an attachment object that can be passed directly to an AI employee task.
+
+```ts
+const attachment = await ctx.ai.uploadFile(file, options);
+```
+
+| Parameter | Type | Description |
+|------|------|------|
+| `file` | `File` | Browser file object to upload. |
+| `options.onProgress` | `(percent: number) => void` | Upload progress callback. `percent` ranges from `0` to `100`. |
+| `options.signal` | `AbortSignal` | Signal used to cancel the upload. |
+
+The upload uses the file storage configured by the AI plugin and creates a record in `aiFiles`. The returned object includes fields such as `id`, `filename`, `url`, and `source`:
+
+```ts
+const attachment = await ctx.ai.uploadFile(file, {
+  onProgress(percent) {
+    console.log('upload progress', percent);
+  },
+});
+
+// attachment can be placed directly in message.attachments
+```
+
+The Promise is rejected when the upload fails. Removing an attachment from the local UI does not delete the record already created in `aiFiles`, matching the behavior of the default AI chat window.
+
 ### ctx.ai.triggerTask()
 
 Trigger an AI employee task directly.
@@ -30,8 +58,10 @@ ctx.ai.triggerTask(options: TriggerTaskOptions): void
 |------|------|------|
 | `aiEmployee` | `string \| AIEmployee` | AI employee. When a string is passed, NocoBase matches `AIEmployee.username` exactly, and the AI employee must be accessible to the current user. |
 | `tasks` | `Task[]` | Tasks to trigger. |
+| `chatBoxUid` | `string` | FlowModel uid of the AI Chat Box block that should receive the task. |
 | `open` | `boolean` | Whether to open the AI employee conversation panel. |
 | `auto` | `boolean` | Whether to use the auto-trigger semantics of an AI employee action. |
+| `onResponseLoadingChange` | `(loading: boolean) => void` | Model response loading callback. It only runs when this task is sent automatically. |
 
 Common `Task` fields:
 
@@ -40,12 +70,160 @@ Common `Task` fields:
 | `title` | `string` | Task title. |
 | `message.system` | `string` | System message, used to constrain the AI employee's role and output requirements. |
 | `message.user` | `string` | User message, which is the main instruction for this task. |
+| `message.attachments` | `Attachment[]` | Attachments used by the task, usually returned by `ctx.ai.uploadFile()`. |
 | `message.workContext` | `ContextItem[]` | Page block context used by the task. |
 | `autoSend` | `boolean` | Whether to send the task message automatically. |
 | `webSearch` | `boolean` | Whether Web search is allowed for this task. |
 | `model` | `{ llmService: string; model: string } \| null` | Model used by this task. |
 | `skillSettings` | `SkillSettings` | Skills and tools available to this task. |
 
+### Track the Response Loading State
+
+Pass `onResponseLoadingChange` in the top-level options to track the model response loading state for this task. The callback receives `true` when NocoBase starts waiting for the model response, and `false` when the response completes, is canceled, or fails. If the React component has declared `setResponseLoading` with `useState`, you can write:
+
+```tsx
+ctx.ai.triggerTask({
+  aiEmployee: 'nathan',
+  open: true,
+  tasks: [
+    {
+      title: ctx.t('Review current page'),
+      message: {
+        user: 'Review the current page and summarize the main risks.',
+      },
+      autoSend: true,
+    },
+  ],
+  onResponseLoadingChange(loading) {
+    setResponseLoading(loading);
+  },
+});
+```
+
+`onResponseLoadingChange` only tracks the model response started directly by this `triggerTask()` call. With `autoSend: false`, the task is placed in the chat draft and the callback does not run. If the user sends the draft later, that manual send does not reuse this callback.
+
+In a React component inside a JS block, this state update rerenders the component while it remains mounted.
+
+### Target an AI Chat Box
+
+Set `chatBoxUid` on the top-level `triggerTask()` options to trigger the task in a mounted AI Chat Box block instead of the global AI employee dialog.
+
+```ts
+ctx.ai.triggerTask({
+  aiEmployee: 'nathan',
+  chatBoxUid: 'AI_CHAT_BOX_BLOCK_UID',
+  open: true,
+  tasks: [
+    {
+      title: ctx.t('Review current page'),
+      message: {
+        user: 'Review the current page and summarize the main risks.',
+      },
+    },
+  ],
+});
+```
+
+The uid must belong to the outer AI Chat Box block currently mounted on the page. Do not put this routing value inside `tasks`. If the target block cannot be found, NocoBase reports an error and does not fall back to the global dialog. When `chatBoxUid` is omitted, the task uses the global AI employee dialog.
+
+### Upload and Send Attachments in JSBlock
+
+The following example renders file upload, task instructions, and a send button in JSBlock. Uploaded files are passed to the AI employee through `message.attachments`:
+
+```tsx
+if (!ctx.ai?.uploadFile || !ctx.ai?.triggerTask) {
+  ctx.message.error(ctx.t('AI employee task API is not available.'));
+  return;
+}
+
+const { React } = ctx.libs;
+const { useState } = React;
+const { Button, Card, Input, Space, Upload } = ctx.libs.antd;
+const { InboxOutlined, SendOutlined } = ctx.libs.antdIcons;
+
+const AttachmentTask = () => {
+  const [prompt, setPrompt] = useState('');
+  const [fileList, setFileList] = useState([]);
+
+  const uploadAttachment = async ({ file, onError, onProgress, onSuccess }) => {
+    try {
+      const attachment = await ctx.ai.uploadFile(file, {
+        onProgress(percent) {
+          onProgress?.({ percent });
+        },
+      });
+      onSuccess?.(attachment);
+    } catch (error) {
+      onError?.(error instanceof Error ? error : new Error(ctx.t('File upload failed')));
+    }
+  };
+
+  const sendTask = () => {
+    const attachments = fileList
+      .filter((file) => file.status === 'done' && file.response)
+      .map((file) => file.response);
+
+    if (!prompt.trim()) {
+      ctx.message.warning(ctx.t('Enter task instructions'));
+      return;
+    }
+
+    ctx.ai.triggerTask({
+      aiEmployee: 'viz',
+      open: true,
+      tasks: [
+        {
+          title: ctx.t('Analyze uploaded files'),
+          message: {
+            user: prompt.trim(),
+            attachments,
+          },
+          autoSend: true,
+        },
+      ],
+    });
+    setPrompt('');
+    setFileList([]);
+  };
+
+  const uploading = fileList.some((file) => file.status === 'uploading');
+
+  return (
+    <Card title={ctx.t('AI file analysis')}>
+      <Space direction="vertical" size="middle" style={{ width: '100%' }}>
+        <Upload.Dragger
+          multiple
+          fileList={fileList}
+          customRequest={uploadAttachment}
+          onChange={({ fileList: nextFileList }) => setFileList(nextFileList)}
+        >
+          <p className="ant-upload-drag-icon"><InboxOutlined /></p>
+          <p>{ctx.t('Click or drag files here to upload')}</p>
+        </Upload.Dragger>
+        <Input.TextArea
+          value={prompt}
+          onChange={(event) => setPrompt(event.target.value)}
+          placeholder={ctx.t('Describe the task for the AI employee')}
+          autoSize={{ minRows: 3, maxRows: 8 }}
+        />
+        <Button
+          type="primary"
+          icon={<SendOutlined />}
+          disabled={uploading || !prompt.trim()}
+          onClick={sendTask}
+        >
+          {ctx.t('Send to AI')}
+        </Button>
+      </Space>
+    </Card>
+  );
+};
+
+ctx.render(<AttachmentTask />);
+```
+
+With `autoSend: false`, the attachments and task instructions are placed in the AI chat draft instead of being sent immediately.
+
 ### Add Page Block Context
 
 `message.workContext` currently passes page blocks. Put the FlowModel uid of the target page block into it:
@@ -163,9 +341,15 @@ ctx.ai.triggerModelTask(uid: string, taskIndex: number, options?: TriggerModelTa
 | `taskIndex` | `number` | Task index, starting from `0`. |
 | `options.open` | `boolean` | Whether to open the AI employee conversation panel. |
 | `options.auto` | `boolean` | Whether to use the auto-trigger semantics of an AI employee action. |
+| `options.attachments` | `Attachment[]` | Attachments dynamically appended to the configured task. |
+| `options.onResponseLoadingChange` | `(loading: boolean) => void` | Model response loading callback. It only runs when the configured task is sent automatically. |
 
 This method reads the AI employee and task configuration from the target model. It is useful when the task has already been configured on an AI employee action on the page, and RunJS only needs to trigger it.
 
+The public `triggerModelTask()` options do not accept `chatBoxUid`. To target an AI Chat Box, configure `chatBoxUid` on the preset task of the AI employee action. `triggerModelTask()` continues to reuse that preset value.
+
+`options.onResponseLoadingChange` behaves the same as the option on `triggerTask()`. Whether it runs depends on the configured task's `autoSend` value. It does not run when that task uses `autoSend: false`.
+
 ```ts
 if (!ctx.ai?.triggerModelTask) {
   ctx.message.error(ctx.t('AI employee task API is not available.'));
@@ -176,6 +360,7 @@ const weeklyReviewActionUid = 'AI_EMPLOYEE_ACTION_MODEL_UID';
 
 ctx.ai.triggerModelTask(weeklyReviewActionUid, 0, {
   open: true,
+  attachments,
 });
 
 ctx.message.success(ctx.t('Configured AI employee task triggered.'));
@@ -195,9 +380,14 @@ If the target model does not exist, has no AI employee configured, or the specif
 ## Notes
 
 - `triggerTask()` and `triggerModelTask()` are fire-and-forget. They do not return the execution result of the AI employee task.
+- `uploadFile()` returns a Promise. Wait for the upload to finish before triggering a task that uses the attachment.
 - `aiEmployee` strings only match `AIEmployee.username` exactly. They do not match nicknames, job titles, or translated names.
 - `triggerModelTask()` uses a `0`-based `taskIndex`.
 - `triggerModelTask()` reads task configuration from the target AI employee action model. If the task needs work context, configure `message.workContext` on that task.
+- Top-level `triggerTask().chatBoxUid` must reference an AI Chat Box block currently mounted on the page.
+- `triggerModelTask()` keeps using `chatBoxUid` configured on its preset task.
+- Dynamic `triggerModelTask()` attachments are appended to the preset task's existing `message.attachments` without changing the saved task configuration.
+- `onResponseLoadingChange` only tracks a model response automatically sent by the current call. It does not track a message the user sends manually later.
 
 ## Related
 

package/dist/ai/docs/nocobase/security/guide.md

@@ -213,17 +213,30 @@ If you need to store sensitive files, it is recommended to use a cloud storage s
 
 ![](https://static-docs.nocobase.com/202501031623549.png)
 
-For local storage or other public storage that can be accessed directly through same-origin application URLs, you should also pay extra attention to the risks introduced by active content files. Files such as `html`, `xhtml`, and `svg` may be parsed and executed directly by the browser. If an attacker can upload such a file and trick a user into opening it, the attacker may use your trusted application domain to host a malicious page or script.
+For local storage or other storage that can be accessed directly through same-origin application URLs, you should also pay extra attention to the risks introduced by active content files. Files such as `html`, `xhtml`, and `svg` may be parsed and executed directly by the browser. If an attacker can upload such a file and trick a user into opening it, the attacker may use your trusted application domain to host a malicious page or script.
 
 NocoBase upload validation does not trust the `Content-Type` sent by the request. It prefers the MIME type detected on the server side. A file extension only represents the filename and should not be treated as the authoritative file content type. Therefore, when serving public uploaded files, you also need to make sure the file access path has proper security response headers.
 
-If you deploy with Docker or use the nginx configuration generated by NocoBase, the upload directory already includes this protection: all uploaded files return `X-Content-Type-Options: nosniff`, and active content files such as `html`, `xhtml`, `svg`, `svgz`, and `pdf` are returned as downloads through `Content-Disposition: attachment`.
+If you deploy with Docker or use the nginx configuration generated by NocoBase, legacy `/storage/uploads/` URLs are restricted to signed-in users. All uploaded files also return `X-Content-Type-Options: nosniff`, and active content files such as `html`, `xhtml`, `svg`, `svgz`, and `pdf` are returned as downloads through `Content-Disposition: attachment`. New `/files/` URLs continue to enforce record-level file permissions.
+
+If an existing integration still depends on anonymous access to legacy URLs, set `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` and restart the application to restore public access to `/storage/uploads/`. This compatibility switch is disabled by default, affects only legacy URLs, and does not change record-level permissions for `/files/`. Public access may expose uploaded files, so confirm that they contain no sensitive content before enabling it.
 
 If you use a custom proxy, CDN, object storage, or expose the local upload directory directly, make sure these rules are not bypassed. You can use the following nginx configuration as a reference:
 
 ```nginx
+location = /_nocobase_legacy_file_auth {
+    internal;
+    proxy_pass http://127.0.0.1:13000/api/auth:checkLegacyFileAccess;
+    proxy_pass_request_body off;
+    proxy_set_header Content-Length "";
+    proxy_set_header Cookie $http_cookie;
+    proxy_set_header Authorization $http_authorization;
+}
+
 location ~* ^/storage/uploads/(.*\.(?:htm|html|svg|svgz|xhtml|pdf))$ {
     alias /path/to/nocobase/storage/uploads/$1;
+    auth_request /_nocobase_legacy_file_auth;
+    add_header Cache-Control "private, no-store" always;
     add_header Content-Disposition "attachment" always;
     add_header X-Content-Type-Options "nosniff" always;
     autoindex off;
@@ -231,6 +244,8 @@ location ~* ^/storage/uploads/(.*\.(?:htm|html|svg|svgz|xhtml|pdf))$ {
 
 location /storage/uploads/ {
     alias /path/to/nocobase/storage/uploads/;
+    auth_request /_nocobase_legacy_file_auth;
+    add_header Cache-Control "private, no-store" always;
     add_header X-Content-Type-Options "nosniff" always;
     autoindex off;
 }

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.