feat: user-data-sync plugin docs

docs/config/handbook.ts

@@ -1366,6 +1366,40 @@ export default [
               },
             ],
           },
+          {
+            title: 'Synchronization',
+            'title.zh-CN': '同步',
+            children: [
+              {
+                title: 'Synchronization management',
+                'title.zh-CN': '同步管理',
+                link: '/handbook/user-data-sync',
+              },
+              {
+                title: 'Data sources',
+                'title.zh-CN': '数据源',
+                children: [
+                  {
+                    title: 'HTTP API',
+                    link: '/handbook/user-data-sync/sources/api',
+                  },
+                  {
+                    title: 'WeCom',
+                    'title.zh-CN': '企业微信',
+                    link: '/handbook/wecom/user-data-sync',
+                  },
+                ],
+              },
+              {
+                title: 'Development',
+                'title.zh-CN': '开发指南',
+                children: [
+                  '/handbook/user-data-sync/dev/source',
+                  '/handbook/user-data-sync/dev/resource',
+                ],
+              },
+            ],
+          },
         ],
       },
       {
@@ -1483,7 +1517,7 @@ export default [
             title: 'Authentication - WeCom',
             'title.zh-CN': '用户认证 - 企业微信',
             'title.ja-JP': 'ユーザー認証 - WeCom',
-            link: '/handbook/auth-wecom',
+            link: '/handbook/wecom/auth',
           },
           {
             title: 'Verification',
@@ -1539,6 +1573,11 @@ export default [
             'title.ja-JP': '通知：メール',
             link: '/handbook/notification-email',
           },
+          {
+            title: 'Notification: WeCom',
+            'title.zh-CN': '通知：企业微信',
+            link: '/handbook/wecom/notification',
+          },
         ],
       },
       {

docs/en-US/handbook/user-data-sync/dev/resource.md

@@ -0,0 +1,61 @@
+# 扩展同步目标资源
+
+## 概述
+
+NocoBase 默认支持将用户数据同步至**用户**和**部门**表，也支持按照需要扩展数据同步的目标资源，实现将数据写入其他表或其他自定义处理。
+
+:::warning{title=实验性}
+完整文档待补充
+:::
+
+## 目标资源处理接口
+
+```ts
+export abstract class UserDataResource {
+  name: string;
+  accepts: SyncAccept[];
+  db: Database;
+  logger: SystemLogger;
+
+  constructor(db: Database, logger: SystemLogger) {
+    this.db = db;
+    this.logger = logger;
+  }
+
+  abstract update(
+    record: OriginRecord,
+    resourcePks: PrimaryKey[],
+    matchKey?: string,
+  ): Promise<RecordResourceChanged[]>;
+  abstract create(
+    record: OriginRecord,
+    matchKey: string,
+  ): Promise<RecordResourceChanged[]>;
+
+  get syncRecordRepo() {
+    return this.db.getRepository('userDataSyncRecords');
+  }
+
+  get syncRecordResourceRepo() {
+    return this.db.getRepository('userDataSyncRecordsResources');
+  }
+}
+```
+
+## 注册目标资源
+
+`registerResource(resource: UserDataResource, options?: ToposortOptions)`
+
+```ts
+import { Plugin } from '@nocobase/server';
+import PluginUserDataSyncServer from '@nocobase/plugin-user-data-sync';
+
+class CustomUserResourcePluginServer extends Plugin {
+  async load() {
+    const userDataSyncPlugin = this.app.pm.get(PluginUserDataSyncServer);
+    if (userDataSyncPlugin && userDataSyncPlugin.enabled) {
+      userDataSyncPlugin.resourceManager.registerResource(new CustomDataSyncResource(this.db, this.app.logger)
+    }
+  }
+}
+```

docs/en-US/handbook/user-data-sync/dev/source.md

@@ -0,0 +1,143 @@
+# 扩展同步数据源
+
+## 概述
+
+NocoBase 支持按需要扩展用户数据同步数据源类型。
+
+## 服务端
+
+### 数据源接口
+
+内置的用户数据同步插件提供了数据源类型的注册和管理。扩展数据源类型，需要继承插件提供的 `SyncSource` 抽象类，并对相应的标准接口进行实现。
+
+```ts
+import { SyncSource, UserData } from '@nocobase/plugin-user-data-sync';
+
+class CustomSyncSource extends SyncSource {
+  async pull(): Promise<UserData[]> {
+    return [];
+  }
+}
+```
+
+`SyncSource` 提供了options属性，用于获取数据源的自定义配置。
+
+```ts
+import { SyncSource, UserData } from '@nocobase/plugin-user-data-sync';
+
+class CustomSyncSource extends SyncSource {
+  async pull(): Promise<UserData[]> {
+    //...
+    const { appid, secret } = this.options;
+    //...
+    return [];
+  }
+}
+```
+
+### UserData字段说明
+
+| 字段         | 说明                                      |
+| ------------ | ----------------------------------------- |
+| `dataType`   | 数据类型, 可选值为 `user` 和 `department` |
+| `uniqueKey`  | 唯一标识字段                              |
+| `records`    | 数据记录                                  |
+| `sourceName` | 数据源名称                                |
+
+若dataType为 `user`，则records包含以下字段：
+
+| 字段          | 说明           |
+| ------------- | -------------- |
+| `id`          | 用户 ID        |
+| `nickname`    | 用户昵称       |
+| `avatar`      | 用户头像       |
+| `email`       | 邮箱           |
+| `phone`       | 手机号         |
+| `departments` | 所属部门ID数组 |
+
+若dataType为 `department`，则records包含以下字段：
+| 字段 | 说明 |
+| -------- | ---------------------- |
+| `id` | 部门 ID |
+| `name` | 部门名称 |
+| `parentId` | 父级部门 ID |
+
+### 数据源接口实现示例
+
+```ts
+import { SyncSource, UserData } from '@nocobase/plugin-user-data-sync';
+
+class CustomSyncSource extends SyncSource {
+  async pull(): Promise<UserData[]> {
+    // ...
+    const ThirdClientApi = new ThirdClientApi(
+      this.options.appid,
+      this.options.secret,
+    );
+    const departments = await this.clientapi.getDepartments();
+    const users = await this.clientapi.getUsers();
+    // ...
+    return [
+      {
+        dataType: 'department',
+        uniqueKey: 'id',
+        records: departments,
+        sourceName: this.instance.name,
+      },
+      {
+        dataType: 'user',
+        uniqueKey: 'id',
+        records: users,
+        sourceName: this.instance.name,
+      },
+    ];
+  }
+}
+```
+
+### 数据源类型注册
+
+扩展的数据源需要向数据管理模块注册。
+
+```ts
+import UserDataSyncPlugin from '@nocobase/plugin-user-data-sync';
+
+class CustomSourcePlugin extends Plugin {
+  async load() {
+    const syncPlugin = this.app.pm.get(
+      UserDataSyncPlugin,
+    ) as UserDataSyncPlugin;
+    if (syncPlugin) {
+      syncPlugin.sourceManager.reigsterType('custom-source-type', {
+        syncSource: CustomSyncSource,
+        title: 'Custom Source',
+      });
+    }
+  }
+}
+```
+
+## 客户端
+
+客户端用户界面通过用户数据同步插件客户端提供的接口 `registerType` 进行注册：
+
+```ts
+import SyncPlugin from '@nocobase/plugin-user-data-sync/client';
+
+class CustomSourcePlugin extends Plugin {
+  async load() {
+    const sync = this.app.pm.get(SyncPlugin);
+    sync.registerType(authType, {
+      components: {
+        AdminSettingsForm, // 后台管理表单
+      },
+    });
+  }
+}
+```
+
+### 后台管理表单
+
+![](https://static-docs.nocobase.com/202412041429835.png)
+
+上方为通用的数据源配置，下方为可注册的自定义配置表单部分。