diff --git a/docs/config/handbook.ts b/docs/config/handbook.ts index e4574db6f11..cabc6a02b7b 100644 --- a/docs/config/handbook.ts +++ b/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', + }, ], }, { diff --git a/docs/en-US/handbook/auth-wecom/index.md b/docs/en-US/handbook/auth-wecom/index.md deleted file mode 100644 index 6ee4d27371d..00000000000 --- a/docs/en-US/handbook/auth-wecom/index.md +++ /dev/null @@ -1,95 +0,0 @@ -# Auth: WeCom - - - -## Introduction - -The Auth: WeCom plugin enables users to log in to NocoBase using their WeCom accounts, streamlining the authentication process for enterprise environments. - -## Activating the Plugin - -![](https://static-docs.nocobase.com/202406272056962.png) - -## Creating and Configuring a Custom WeCom Application - -Start by accessing the WeCom admin console to create a custom application tailored to your enterprise needs. - -![](https://static-docs.nocobase.com/202406272101321.png) - -![](https://static-docs.nocobase.com/202406272102087.png) - -Once the application is created, navigate to its details page. Scroll down to find and select the "WeCom Authorized Login" option. - -![](https://static-docs.nocobase.com/202406272104655.png) - -Ensure that the authorization callback domain is set to your NocoBase application domain. - -![](https://static-docs.nocobase.com/202406272105662.png) - -Next, return to the application’s details page and click on "网页授权及SDK"("Web Authorization and JS-SDK") - -![](https://static-docs.nocobase.com/202406272107063.png) - -Set and verify the callback domain to enable the OAuth2.0 web authorization for your application. - -![](https://static-docs.nocobase.com/202406272107899.png) - -Then, head over to the "企业可信IP"("Trusted IP") section within the details page. - -![](https://static-docs.nocobase.com/202406272108834.png) - -Here, configure the IP address associated with your NocoBase application. - -![](https://static-docs.nocobase.com/202406272109805.png) - -## Retrieving Keys from the WeCom Admin Console - -In the WeCom admin console, under "我的企业"("My Company") locate and copy the "企业ID"("Company ID") - -![](https://static-docs.nocobase.com/202406272111637.png) - -Then, navigate to "应用管理"("Application Management"), select the application you created earlier, and copy both the AgentId and Secret from the details page. - -![](https://static-docs.nocobase.com/202406272122322.png) - -## Integrating WeCom Authentication into NocoBase - -Go to the user authentication plugin management section in NocoBase. - -![](https://static-docs.nocobase.com/202406272115044.png) - -Click on "Add new" and select "WeCom" from the list. - -![](https://static-docs.nocobase.com/202406272115805.png) - -### Configuration Steps - -![](https://static-docs.nocobase.com/202406272116978.png) - -- When a phone number does not match an existing user, should a new user be created automatically - When the phone number does not match an existing user, a new user is automatically created. -- "Company ID, "AgentId" And "Secret" - Enter the key information copied in the previous step. -- Workbench application homepage link - Enter the Workbench application homepage link, then copy and proceed to the next step. - -## Configuring the WeCom Application Homepage - -In the WeCom admin console, paste the previously copied Workbench application homepage link into the corresponding field for the application’s homepage URL. - -![](https://static-docs.nocobase.com/202406272123631.png) - -![](https://static-docs.nocobase.com/202406272123048.png) - -## Logging In - -To log in, visit the NocoBase login page and click the button below the login form to start the third-party authentication process. - -![](https://static-docs.nocobase.com/202406272124608.png) - -:::warning -Please note that due to WeCom's restrictions on accessing sensitive information, such as phone numbers, the authorization process can only be completed within the WeCom client. For your first time logging in with WeCom, follow the steps below to authorize the initial login within the WeCom client. -::: - -## Initial Login Process - -To complete your first login, open the Workbench in the WeCom client, scroll to the bottom, select the application, and navigate to the application homepage you previously configured. This will complete the authorization, allowing you to use WeCom login in the NocoBase application thereafter. - - diff --git a/docs/en-US/handbook/user-data-sync/dev/resource.md b/docs/en-US/handbook/user-data-sync/dev/resource.md new file mode 100644 index 00000000000..c4992cd5dc0 --- /dev/null +++ b/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; + abstract create( + record: OriginRecord, + matchKey: string, + ): Promise; + + 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) + } + } +} +``` diff --git a/docs/en-US/handbook/user-data-sync/dev/source.md b/docs/en-US/handbook/user-data-sync/dev/source.md new file mode 100644 index 00000000000..f600a63bf86 --- /dev/null +++ b/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 { + return []; + } +} +``` + +`SyncSource` 提供了options属性，用于获取数据源的自定义配置。 + +```ts +import { SyncSource, UserData } from '@nocobase/plugin-user-data-sync'; + +class CustomSyncSource extends SyncSource { + async pull(): Promise { + //... + 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 { + // ... + 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) + +上方为通用的数据源配置，下方为可注册的自定义配置表单部分。 diff --git a/docs/en-US/handbook/user-data-sync/index.md b/docs/en-US/handbook/user-data-sync/index.md new file mode 100644 index 00000000000..8655464be4c --- /dev/null +++ b/docs/en-US/handbook/user-data-sync/index.md @@ -0,0 +1,45 @@ +# 用户数据同步 + + + +## 介绍 + +注册和管理用户数据同步来源，默认提供 HTTP API, 可以通过插件扩展其他数据来源。默认支持向**用户**和**部门**表同步数据，也可以通过插件扩展其他同步目标资源。 + +## 安装 + +内置插件，无需单独安装。 + +## 数据源管理和数据同步 + +![](https://static-docs.nocobase.com/202412041043465.png) + +:::info +在未安装提供用户数据同步来源的插件时，可以通过 HTTP API 同步用户数据。参考 [数据源 - HTTP API](./sources/api). +::: + +## 添加数据源 + +安装提供用户数据同步来源的插件之后，即可添加相应的数据源。只有启用的数据源才会显示同步和任务按钮。 + +> 以企业微信为例 + +![](https://static-docs.nocobase.com/202412041053785.png) + +## 同步数据 + +点击「同步」按钮，开始进行数据同步。 + +![](https://static-docs.nocobase.com/202412041055022.png) + +点击「任务」按钮可以查看同步状态。同步成功后可以到用户和部门列表查看数据。 + +![](https://static-docs.nocobase.com/202412041202337.png) + +同步失败的任务，可以点击「重试」。 + +![](https://static-docs.nocobase.com/202412041058337.png) + +同步失败时可以通过系统日志排查原因，同时在应用日志目录下的 `user-data-sync` 目录里保存有原始的数据同步记录。 + +![](https://static-docs.nocobase.com/202412041205655.png) diff --git a/docs/en-US/handbook/user-data-sync/sources/api.md b/docs/en-US/handbook/user-data-sync/sources/api.md new file mode 100644 index 00000000000..c765ec96142 --- /dev/null +++ b/docs/en-US/handbook/user-data-sync/sources/api.md @@ -0,0 +1,74 @@ +# 通过 HTTP API 同步用户数据 + +## 获取 API 密钥 + +参考 [API 密钥](../api-keys), 需要确保 API 密钥设置的角色具有用户数据同步权限。 + +## API 说明 + +### 示例 + +```bash +curl 'https://localhost:13000/api/userData:push' \ + -H 'Authorization: Bearer ' \ + --data-raw '{"dataType":"user","records":[]}' # 请求体见下文详细说明 +``` + +### Endpoint + +```bash +POST /api/userData:push +``` + +### 用户数据格式 + +#### UserData + +| 参数名 | 类型 | 说明 | +| ---------- | ---------------------------------- | ------------------------------------------------------------------------ | +| `dataType` | `'user' \| 'department'` | 必填，推送的数据类型，推送用户数据填 `user` | +| `matchKey` | `'username' \| 'email' \| 'phone'` | 选填，会根据提供字段和推送数据中对应的字段值去查询系统已有用户，进行匹配 | +| `records` | `UserRecord[]` | 必填，用户数据记录数组 | + +#### UserRecord + +| 参数名 | 类型 | 说明 | +| ------------- | ---------- | ------------------------------------------------------------------------------------ | +| `uid` | `string` | 必填，来源用户数据的唯一标识，用于关联来源原始数据和系统用户。对于同一个用户不可变。 | +| `nickname` | `string` | 可选，用户昵称 | +| `username` | `string` | 可选，用户名 | +| `email` | `string` | 可选，用户邮箱 | +| `phone` | `string` | 可选，手机号 | +| `departments` | `string[]` | 可选，用户所属部门 uid 数组 | +| `isDeleted` | `boolean` | 可选，记录是否删除 | +| `` | `any` | 可选，其他用户表中的自建字段数据 | + +### 部门数据格式 + +:::info +推送部门数据的前提是安装并开启[部门](../../departments)插件。 +::: + +#### DepartmentData + +| 参数名 | 类型 | 说明 | +| ---------- | ------------------------ | ------------------------------------------------- | +| `dataType` | `'user' \| 'department'` | 必填，推送的数据类型，推送部门数据填 `department` | +| `records` | `DepartmentRecord[]` | 必填，部门数据记录数组 | + +#### DepartmentRecord + +| 参数名 | 类型 | 说明 | +| ----------- | --------- | ------------------------------------------------------------------------------------ | +| `uid` | `string` | 必填，来源部门数据的唯一标识，用于关联来源原始数据和系统部门。对于同一个部门不可变。 | +| `title` | `string` | 必填，部门标题 | +| `parentUid` | `string` | 可选，上级部门 uid | +| `isDeleted` | `boolean` | 可选，记录是否删除 | +| `` | `any` | 可选，其他部门表中的自建字段数据 | + +:::info + +1. 数据多次推送幂等。 +2. 如果推送部门时，父部门还未创建，则无法关联上，可再次推送数据。 +3. 如果推送用户时，部门还未创建，则无法关联上所属部门，可在推送部门数据后，再次推送用户数据。 + ::: diff --git a/docs/en-US/handbook/wecom/auth.md b/docs/en-US/handbook/wecom/auth.md new file mode 100644 index 00000000000..2e8d3147b1f --- /dev/null +++ b/docs/en-US/handbook/wecom/auth.md @@ -0,0 +1,108 @@ +# 认证：企业微信 + + + +## 介绍 + +**企业微信**插件支持用户使用企业微信账号登录 NocoBase. + +## 激活插件 + +![](https://static-docs.nocobase.com/202406272056962.png) + +## 创建和配置企业微信自建应用 + +进入企业微信管理后台，创建企业微信自建应用。 + +![](https://static-docs.nocobase.com/202406272101321.png) + +![](https://static-docs.nocobase.com/202406272102087.png) + +点击应用进入详情页，下拉页面，点击「企业微信授权登录」。 + +![](https://static-docs.nocobase.com/202406272104655.png) + +设置授权回调域为 NocoBase 应用域名。 + +![](https://static-docs.nocobase.com/202406272105662.png) + +回到应用详情页，点击「网页授权及 JS-SDK」。 + +![](https://static-docs.nocobase.com/202406272107063.png) + +设置并验证可作为应用 OAuth2.0 网页授权功能的回调域名。 + +![](https://static-docs.nocobase.com/202406272107899.png) + +在应用详情页，点击「企业可信 IP」。 + +![](https://static-docs.nocobase.com/202406272108834.png) + +配置 NocoBase 应用 IP. + +![](https://static-docs.nocobase.com/202406272109805.png) + +## 从企业微信管理后台获取密钥 + +在企业微信管理后台 - 我的企业，复制「企业 ID」. + +![](https://static-docs.nocobase.com/202406272111637.png) + +在企业微信管理后台 - 应用管理，进入上一步创建的应用的详情页，复制 AgentId 和 Secret + +![](https://static-docs.nocobase.com/202406272122322.png) + +## 在 NocoBase 上添加企业微信认证 + +进入用户认证插件管理页面。 + +![](https://static-docs.nocobase.com/202406272115044.png) + +添加 - 企业微信 + +![](https://static-docs.nocobase.com/202406272115805.png) + +### 配置 + +![](https://static-docs.nocobase.com/202412041459250.png) + +| 配置项 | 说明 | 版本要求 | +| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------- | +| When a phone number does not match an existing user,
should a new user be created automatically | 当使用手机号匹配不到已有用户时，是否自动创建新用户 | - | +| Company ID | 企业 ID, 从企业微信管理后台获取 | - | +| AgentId | 从企业微信管理后台自建应用配置获取 | - | +| Secret | 从企业微信管理后台自建应用配置获取 | - | +| Origin | 当前应用域名 | - | +| Workbench application redirect link | 成功登录后跳转的应用路径 | `v1.4.0` | +| Automatic login | 在企业微信浏览器里打开应用链接时，自动登录。当配置有多个企业微信认证器的时候，只有一个能开启该选项。 | `v1.4.0` | +| Workbench application homepage link | 工作台应用主页链接 | - | + +## 配置企业微信应用首页 + +:::info +`v1.4.0` 以上版本，在启用「自动登录」选项的情况下，应用主页链接可以简化为: `https:///`，例如 `https://example.nocobase.com/admin`. + +也可以将分别配置手机和电脑端，例如 `https://example.nocobase.com/m` 和 `https://example.nocobase.com/admin`. +::: + +进入企业微信管理员后台，将复制的工作台应用主页链接填写到对应应用的应用主页地址栏。 + +![](https://static-docs.nocobase.com/202406272123631.png) + +![](https://static-docs.nocobase.com/202406272123048.png) + +## 登录 + +访问登录页面，点击登录表单下方按钮发起第三方登录。 + +![](https://static-docs.nocobase.com/202406272124608.png) + +:::warning +由于企业微信对于手机号等敏感信息的权限限制，只能在企业微信客户端内完成授权。第一次使用企业微信登录时，请参考以下步骤在企业微信客户端内完成首次登录授权。 +::: + +## 初次登录 + +从企业微信客户端进入工作台，下拉至底部，点击应用进入前面填写的应用主页，即可完成首次授权登录，之后就可以在 NocoBase 应用内使用企业微信登录。 + + diff --git a/docs/en-US/handbook/wecom/index.md b/docs/en-US/handbook/wecom/index.md new file mode 100644 index 00000000000..a8abd986859 --- /dev/null +++ b/docs/en-US/handbook/wecom/index.md @@ -0,0 +1,13 @@ +# 企业微信 + + + +## 介绍 + +**企业微信**插件提供企业微信集成的能力，包括认证方式、通知渠道和用户数据同步来源。 + +参考： + +- [认证：企业微信](./auth.md) +- [通知：企业微信](./notification.md) +- [同步来源：企业微信](./user-data-sync.md) diff --git a/docs/en-US/handbook/wecom/notification.md b/docs/en-US/handbook/wecom/notification.md new file mode 100644 index 00000000000..05508bdfe3e --- /dev/null +++ b/docs/en-US/handbook/wecom/notification.md @@ -0,0 +1,27 @@ +# 通知：企业微信 + + + +## 介绍 + +**企业微信**插件支持应用向企业微信用户发送通知消息。 + +## 添加和配置企业微信认证器 + +首先需要在 NocoBase 上添加和配置一个企业微信认证器，参考 [用户认证 - 企业微信](./auth)，只有经过企业微信登录的系统用户，才可以通过企业微信接收系统通知。 + +## 添加企业微信通知渠道 + +![](https://static-docs.nocobase.com/202412041522365.png) + +## 配置企业微信通知渠道 + +选择刚才配置的认证器。 + +![](https://static-docs.nocobase.com/202412041525284.png) + +## 工作流通知节点配置 + +选择配置好的企业微信通知渠道，支持三种消息类型：文本卡片，Markdown, 模版卡片。 + +![](https://static-docs.nocobase.com/202412041529319.png) diff --git a/docs/en-US/handbook/wecom/user-data-sync.md b/docs/en-US/handbook/wecom/user-data-sync.md new file mode 100644 index 00000000000..57ecfc66957 --- /dev/null +++ b/docs/en-US/handbook/wecom/user-data-sync.md @@ -0,0 +1,43 @@ +# 从企业微信同步用户数据 + + + +## 介绍 + +**企业微信**插件支持用户从企业微信同步用户和部门数据。 + +## 创建和配置企业微信自建应用。 + +首先需要在企业微信管理后台，创建企业微信自建应用，并获取**企业 ID**, **AgentId** 和 **Secret**. + +参考 [用户认证 - 企业微信](./auth)。 + +## 在 NocoBase 上添加同步数据源 + +用户和权限 - 同步 - 添加，填写获取的相关信息。 + +![](https://static-docs.nocobase.com/202412041251867.png) + +## 配置通讯录同步 + +进入企业微信管理后台 - 安全和管理 - 管理工具，点击通讯录同步。 + +![](https://static-docs.nocobase.com/202412041249958.png) + +按如图所示设置，并设置企业可信 IP. + +![](https://static-docs.nocobase.com/202412041250776.png) + +接下来就可以进行用户数据同步了。 + +## 设置接收事件服务器 + +如果希望企业微信侧的用户、部门数据变动可以及时同步给 NocoBase 应用，可以进一步设置。 + +在填写了前面的配置信息之后，可以复制通讯录回调通知地址。 + +![](https://static-docs.nocobase.com/202412041256547.png) + +填写到企业微信设置上，并获取 Token 和 EncodingAESKey, 完成 NocoBase 用户同步数据源配置。 + +![](https://static-docs.nocobase.com/202412041257947.png) diff --git a/docs/ja-JP/handbook/auth-wecom/index.md b/docs/ja-JP/handbook/auth-wecom/index.md deleted file mode 100644 index c16d9ac2db1..00000000000 --- a/docs/ja-JP/handbook/auth-wecom/index.md +++ /dev/null @@ -1,96 +0,0 @@ -# 認証：企業微信 - - - -## 概要 - -認証：企業微信プラグインは、ユーザーが企業微信アカウントを使用してNocoBaseにログインすることをサポートします。 - -## プラグインの有効化 - -![](https://static-docs.nocobase.com/202406272056962.png) - -## 企業微信自作アプリの作成と設定 - -企業微信管理バックエンドにアクセスし、企業微信自作アプリを作成します。 - -![](https://static-docs.nocobase.com/202406272101321.png) - -![](https://static-docs.nocobase.com/202406272102087.png) - -アプリをクリックして詳細ページに入り、ページをスクロールして「企業微信認可ログイン」をクリックします。 - -![](https://static-docs.nocobase.com/202406272104655.png) - -認可コールバックドメインをNocoBaseアプリのドメイン名に設定します。 - -![](https://static-docs.nocobase.com/202406272105662.png) - -アプリの詳細ページに戻り、「ウェブページ認可およびJS-SDK」をクリックします。 - -![](https://static-docs.nocobase.com/202406272107063.png) - -アプリのOAuth2.0ウェブ認可機能のコールバックドメインとして設定し、検証を行います。 - -![](https://static-docs.nocobase.com/202406272107899.png) - -アプリの詳細ページで「企業信頼IP」をクリックします。 - -![](https://static-docs.nocobase.com/202406272108834.png) - -NocoBaseアプリのIPを設定します。 - -![](https://static-docs.nocobase.com/202406272109805.png) - -## 企業微信管理バックエンドからのキーの取得 - -企業微信管理バックエンドの「私の企業」から「企業ID」をコピーします。 - -![](https://static-docs.nocobase.com/202406272111637.png) - -企業微信管理バックエンドの「アプリ管理」に移動し、前のステップで作成したアプリの詳細ページに進み、AgentIdとSecretをコピーします。 - -![](https://static-docs.nocobase.com/202406272122322.png) - -## NocoBaseに企業微信認証を追加 - -ユーザー認証プラグイン管理ページに移動します。 - -![](https://static-docs.nocobase.com/202406272115044.png) - -「追加 - 企業微信」を選択します。 - -![](https://static-docs.nocobase.com/202406272115805.png) - -### 設定 - -![](https://static-docs.nocobase.com/202406272116978.png) - -- 電話番号が既存のユーザーと一致しない場合、新しいユーザーを自動的に作成しますか？ - 既存のユーザーが電話番号で見つからない場合に新しいユーザーを自動的に作成するかどうかを設定します。 -- 会社ID、AgentIdおよびSecret - 前のステップでコピーしたキー情報を入力します。 -- ワークベンチアプリケーションのホームページリンク - ワークベンチアプリケーションのホームページリンクをコピーし、次のステップに進みます。 - -## 企業微信アプリのホームページ設定 - -企業微信管理者バックエンドにアクセスし、コピーしたワークベンチアプリケーションのホームページリンクを対応するアプリのホームページアドレス欄に記入します。 - -![](https://static-docs.nocobase.com/202406272123631.png) - -![](https://static-docs.nocobase.com/202406272123048.png) - -## ログイン - -ログインページにアクセスし、ログインフォームの下にあるボタンをクリックして第三者ログインを開始します。 - -![](https://static-docs.nocobase.com/202406272124608.png) - -:::warning -企業微信は電話番号などの敏感情報に対する権限制限があるため、企業微信クライアント内でのみ認証を完了できます。企業微信で初めてログインする場合は、以下の手順に従って企業微信クライアント内で初回ログイン認証を完了してください。 -::: - -## 初回ログイン - -企業微信クライアントからワークベンチに入り、下にスクロールして最下部に到達したら、「アプリ」をクリックして、事前に記入したアプリのホームページにアクセスします。これにより、初回認証ログインが完了します。その後、NocoBaseアプリ内で企業微信にログインできるようになります。 - - - diff --git a/docs/ja-JP/handbook/user-data-sync/dev/resource.md b/docs/ja-JP/handbook/user-data-sync/dev/resource.md new file mode 100644 index 00000000000..c4992cd5dc0 --- /dev/null +++ b/docs/ja-JP/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; + abstract create( + record: OriginRecord, + matchKey: string, + ): Promise; + + 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) + } + } +} +``` diff --git a/docs/ja-JP/handbook/user-data-sync/dev/source.md b/docs/ja-JP/handbook/user-data-sync/dev/source.md new file mode 100644 index 00000000000..f600a63bf86 --- /dev/null +++ b/docs/ja-JP/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 { + return []; + } +} +``` + +`SyncSource` 提供了options属性，用于获取数据源的自定义配置。 + +```ts +import { SyncSource, UserData } from '@nocobase/plugin-user-data-sync'; + +class CustomSyncSource extends SyncSource { + async pull(): Promise { + //... + 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 { + // ... + 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) + +上方为通用的数据源配置，下方为可注册的自定义配置表单部分。 diff --git a/docs/ja-JP/handbook/user-data-sync/index.md b/docs/ja-JP/handbook/user-data-sync/index.md new file mode 100644 index 00000000000..8655464be4c --- /dev/null +++ b/docs/ja-JP/handbook/user-data-sync/index.md @@ -0,0 +1,45 @@ +# 用户数据同步 + + + +## 介绍 + +注册和管理用户数据同步来源，默认提供 HTTP API, 可以通过插件扩展其他数据来源。默认支持向**用户**和**部门**表同步数据，也可以通过插件扩展其他同步目标资源。 + +## 安装 + +内置插件，无需单独安装。 + +## 数据源管理和数据同步 + +![](https://static-docs.nocobase.com/202412041043465.png) + +:::info +在未安装提供用户数据同步来源的插件时，可以通过 HTTP API 同步用户数据。参考 [数据源 - HTTP API](./sources/api). +::: + +## 添加数据源 + +安装提供用户数据同步来源的插件之后，即可添加相应的数据源。只有启用的数据源才会显示同步和任务按钮。 + +> 以企业微信为例 + +![](https://static-docs.nocobase.com/202412041053785.png) + +## 同步数据 + +点击「同步」按钮，开始进行数据同步。 + +![](https://static-docs.nocobase.com/202412041055022.png) + +点击「任务」按钮可以查看同步状态。同步成功后可以到用户和部门列表查看数据。 + +![](https://static-docs.nocobase.com/202412041202337.png) + +同步失败的任务，可以点击「重试」。 + +![](https://static-docs.nocobase.com/202412041058337.png) + +同步失败时可以通过系统日志排查原因，同时在应用日志目录下的 `user-data-sync` 目录里保存有原始的数据同步记录。 + +![](https://static-docs.nocobase.com/202412041205655.png) diff --git a/docs/ja-JP/handbook/user-data-sync/sources/api.md b/docs/ja-JP/handbook/user-data-sync/sources/api.md new file mode 100644 index 00000000000..c765ec96142 --- /dev/null +++ b/docs/ja-JP/handbook/user-data-sync/sources/api.md @@ -0,0 +1,74 @@ +# 通过 HTTP API 同步用户数据 + +## 获取 API 密钥 + +参考 [API 密钥](../api-keys), 需要确保 API 密钥设置的角色具有用户数据同步权限。 + +## API 说明 + +### 示例 + +```bash +curl 'https://localhost:13000/api/userData:push' \ + -H 'Authorization: Bearer ' \ + --data-raw '{"dataType":"user","records":[]}' # 请求体见下文详细说明 +``` + +### Endpoint + +```bash +POST /api/userData:push +``` + +### 用户数据格式 + +#### UserData + +| 参数名 | 类型 | 说明 | +| ---------- | ---------------------------------- | ------------------------------------------------------------------------ | +| `dataType` | `'user' \| 'department'` | 必填，推送的数据类型，推送用户数据填 `user` | +| `matchKey` | `'username' \| 'email' \| 'phone'` | 选填，会根据提供字段和推送数据中对应的字段值去查询系统已有用户，进行匹配 | +| `records` | `UserRecord[]` | 必填，用户数据记录数组 | + +#### UserRecord + +| 参数名 | 类型 | 说明 | +| ------------- | ---------- | ------------------------------------------------------------------------------------ | +| `uid` | `string` | 必填，来源用户数据的唯一标识，用于关联来源原始数据和系统用户。对于同一个用户不可变。 | +| `nickname` | `string` | 可选，用户昵称 | +| `username` | `string` | 可选，用户名 | +| `email` | `string` | 可选，用户邮箱 | +| `phone` | `string` | 可选，手机号 | +| `departments` | `string[]` | 可选，用户所属部门 uid 数组 | +| `isDeleted` | `boolean` | 可选，记录是否删除 | +| `` | `any` | 可选，其他用户表中的自建字段数据 | + +### 部门数据格式 + +:::info +推送部门数据的前提是安装并开启[部门](../../departments)插件。 +::: + +#### DepartmentData + +| 参数名 | 类型 | 说明 | +| ---------- | ------------------------ | ------------------------------------------------- | +| `dataType` | `'user' \| 'department'` | 必填，推送的数据类型，推送部门数据填 `department` | +| `records` | `DepartmentRecord[]` | 必填，部门数据记录数组 | + +#### DepartmentRecord + +| 参数名 | 类型 | 说明 | +| ----------- | --------- | ------------------------------------------------------------------------------------ | +| `uid` | `string` | 必填，来源部门数据的唯一标识，用于关联来源原始数据和系统部门。对于同一个部门不可变。 | +| `title` | `string` | 必填，部门标题 | +| `parentUid` | `string` | 可选，上级部门 uid | +| `isDeleted` | `boolean` | 可选，记录是否删除 | +| `` | `any` | 可选，其他部门表中的自建字段数据 | + +:::info + +1. 数据多次推送幂等。 +2. 如果推送部门时，父部门还未创建，则无法关联上，可再次推送数据。 +3. 如果推送用户时，部门还未创建，则无法关联上所属部门，可在推送部门数据后，再次推送用户数据。 + ::: diff --git a/docs/ja-JP/handbook/wecom/auth.md b/docs/ja-JP/handbook/wecom/auth.md new file mode 100644 index 00000000000..2e8d3147b1f --- /dev/null +++ b/docs/ja-JP/handbook/wecom/auth.md @@ -0,0 +1,108 @@ +# 认证：企业微信 + + + +## 介绍 + +**企业微信**插件支持用户使用企业微信账号登录 NocoBase. + +## 激活插件 + +![](https://static-docs.nocobase.com/202406272056962.png) + +## 创建和配置企业微信自建应用 + +进入企业微信管理后台，创建企业微信自建应用。 + +![](https://static-docs.nocobase.com/202406272101321.png) + +![](https://static-docs.nocobase.com/202406272102087.png) + +点击应用进入详情页，下拉页面，点击「企业微信授权登录」。 + +![](https://static-docs.nocobase.com/202406272104655.png) + +设置授权回调域为 NocoBase 应用域名。 + +![](https://static-docs.nocobase.com/202406272105662.png) + +回到应用详情页，点击「网页授权及 JS-SDK」。 + +![](https://static-docs.nocobase.com/202406272107063.png) + +设置并验证可作为应用 OAuth2.0 网页授权功能的回调域名。 + +![](https://static-docs.nocobase.com/202406272107899.png) + +在应用详情页，点击「企业可信 IP」。 + +![](https://static-docs.nocobase.com/202406272108834.png) + +配置 NocoBase 应用 IP. + +![](https://static-docs.nocobase.com/202406272109805.png) + +## 从企业微信管理后台获取密钥 + +在企业微信管理后台 - 我的企业，复制「企业 ID」. + +![](https://static-docs.nocobase.com/202406272111637.png) + +在企业微信管理后台 - 应用管理，进入上一步创建的应用的详情页，复制 AgentId 和 Secret + +![](https://static-docs.nocobase.com/202406272122322.png) + +## 在 NocoBase 上添加企业微信认证 + +进入用户认证插件管理页面。 + +![](https://static-docs.nocobase.com/202406272115044.png) + +添加 - 企业微信 + +![](https://static-docs.nocobase.com/202406272115805.png) + +### 配置 + +![](https://static-docs.nocobase.com/202412041459250.png) + +| 配置项 | 说明 | 版本要求 | +| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------- | +| When a phone number does not match an existing user,
should a new user be created automatically | 当使用手机号匹配不到已有用户时，是否自动创建新用户 | - | +| Company ID | 企业 ID, 从企业微信管理后台获取 | - | +| AgentId | 从企业微信管理后台自建应用配置获取 | - | +| Secret | 从企业微信管理后台自建应用配置获取 | - | +| Origin | 当前应用域名 | - | +| Workbench application redirect link | 成功登录后跳转的应用路径 | `v1.4.0` | +| Automatic login | 在企业微信浏览器里打开应用链接时，自动登录。当配置有多个企业微信认证器的时候，只有一个能开启该选项。 | `v1.4.0` | +| Workbench application homepage link | 工作台应用主页链接 | - | + +## 配置企业微信应用首页 + +:::info +`v1.4.0` 以上版本，在启用「自动登录」选项的情况下，应用主页链接可以简化为: `https:///`，例如 `https://example.nocobase.com/admin`. + +也可以将分别配置手机和电脑端，例如 `https://example.nocobase.com/m` 和 `https://example.nocobase.com/admin`. +::: + +进入企业微信管理员后台，将复制的工作台应用主页链接填写到对应应用的应用主页地址栏。 + +![](https://static-docs.nocobase.com/202406272123631.png) + +![](https://static-docs.nocobase.com/202406272123048.png) + +## 登录 + +访问登录页面，点击登录表单下方按钮发起第三方登录。 + +![](https://static-docs.nocobase.com/202406272124608.png) + +:::warning +由于企业微信对于手机号等敏感信息的权限限制，只能在企业微信客户端内完成授权。第一次使用企业微信登录时，请参考以下步骤在企业微信客户端内完成首次登录授权。 +::: + +## 初次登录 + +从企业微信客户端进入工作台，下拉至底部，点击应用进入前面填写的应用主页，即可完成首次授权登录，之后就可以在 NocoBase 应用内使用企业微信登录。 + + diff --git a/docs/ja-JP/handbook/wecom/index.md b/docs/ja-JP/handbook/wecom/index.md new file mode 100644 index 00000000000..a8abd986859 --- /dev/null +++ b/docs/ja-JP/handbook/wecom/index.md @@ -0,0 +1,13 @@ +# 企业微信 + + + +## 介绍 + +**企业微信**插件提供企业微信集成的能力，包括认证方式、通知渠道和用户数据同步来源。 + +参考： + +- [认证：企业微信](./auth.md) +- [通知：企业微信](./notification.md) +- [同步来源：企业微信](./user-data-sync.md) diff --git a/docs/ja-JP/handbook/wecom/notification.md b/docs/ja-JP/handbook/wecom/notification.md new file mode 100644 index 00000000000..05508bdfe3e --- /dev/null +++ b/docs/ja-JP/handbook/wecom/notification.md @@ -0,0 +1,27 @@ +# 通知：企业微信 + + + +## 介绍 + +**企业微信**插件支持应用向企业微信用户发送通知消息。 + +## 添加和配置企业微信认证器 + +首先需要在 NocoBase 上添加和配置一个企业微信认证器，参考 [用户认证 - 企业微信](./auth)，只有经过企业微信登录的系统用户，才可以通过企业微信接收系统通知。 + +## 添加企业微信通知渠道 + +![](https://static-docs.nocobase.com/202412041522365.png) + +## 配置企业微信通知渠道 + +选择刚才配置的认证器。 + +![](https://static-docs.nocobase.com/202412041525284.png) + +## 工作流通知节点配置 + +选择配置好的企业微信通知渠道，支持三种消息类型：文本卡片，Markdown, 模版卡片。 + +![](https://static-docs.nocobase.com/202412041529319.png) diff --git a/docs/ja-JP/handbook/wecom/user-data-sync.md b/docs/ja-JP/handbook/wecom/user-data-sync.md new file mode 100644 index 00000000000..57ecfc66957 --- /dev/null +++ b/docs/ja-JP/handbook/wecom/user-data-sync.md @@ -0,0 +1,43 @@ +# 从企业微信同步用户数据 + + + +## 介绍 + +**企业微信**插件支持用户从企业微信同步用户和部门数据。 + +## 创建和配置企业微信自建应用。 + +首先需要在企业微信管理后台，创建企业微信自建应用，并获取**企业 ID**, **AgentId** 和 **Secret**. + +参考 [用户认证 - 企业微信](./auth)。 + +## 在 NocoBase 上添加同步数据源 + +用户和权限 - 同步 - 添加，填写获取的相关信息。 + +![](https://static-docs.nocobase.com/202412041251867.png) + +## 配置通讯录同步 + +进入企业微信管理后台 - 安全和管理 - 管理工具，点击通讯录同步。 + +![](https://static-docs.nocobase.com/202412041249958.png) + +按如图所示设置，并设置企业可信 IP. + +![](https://static-docs.nocobase.com/202412041250776.png) + +接下来就可以进行用户数据同步了。 + +## 设置接收事件服务器 + +如果希望企业微信侧的用户、部门数据变动可以及时同步给 NocoBase 应用，可以进一步设置。 + +在填写了前面的配置信息之后，可以复制通讯录回调通知地址。 + +![](https://static-docs.nocobase.com/202412041256547.png) + +填写到企业微信设置上，并获取 Token 和 EncodingAESKey, 完成 NocoBase 用户同步数据源配置。 + +![](https://static-docs.nocobase.com/202412041257947.png) diff --git a/docs/zh-CN/handbook/auth-wecom/index.md b/docs/zh-CN/handbook/auth-wecom/index.md deleted file mode 100644 index c739ca85b51..00000000000 --- a/docs/zh-CN/handbook/auth-wecom/index.md +++ /dev/null @@ -1,95 +0,0 @@ -# 认证：企业微信 - - - -## 介绍 - -认证：企业微信 插件支持用户使用企业微信账号登录 NocoBase. - -## 激活插件 - -![](https://static-docs.nocobase.com/202406272056962.png) - -## 创建和配置企业微信自建应用 - -进入企业微信管理后台，创建企业微信自建应用。 - -![](https://static-docs.nocobase.com/202406272101321.png) - -![](https://static-docs.nocobase.com/202406272102087.png) - -点击应用进入详情页，下拉页面，点击「企业微信授权登录」。 - -![](https://static-docs.nocobase.com/202406272104655.png) - -设置授权回调域为 NocoBase 应用域名。 - -![](https://static-docs.nocobase.com/202406272105662.png) - -回到应用详情页，点击「网页授权及 JS-SDK」。 - -![](https://static-docs.nocobase.com/202406272107063.png) - -设置并验证可作为应用 OAuth2.0 网页授权功能的回调域名。 - -![](https://static-docs.nocobase.com/202406272107899.png) - -在应用详情页，点击「企业可信 IP」。 - -![](https://static-docs.nocobase.com/202406272108834.png) - -配置 NocoBase 应用 IP. - -![](https://static-docs.nocobase.com/202406272109805.png) - -## 从企业微信管理后台获取密钥 - -在企业微信管理后台 - 我的企业，复制「企业 ID」. - -![](https://static-docs.nocobase.com/202406272111637.png) - -在企业微信管理后台 - 应用管理，进入上一步创建的应用的详情页，复制 AgentId 和 Secret - -![](https://static-docs.nocobase.com/202406272122322.png) - -## 在 NocoBase 上添加企业微信认证 - -进入用户认证插件管理页面。 - -![](https://static-docs.nocobase.com/202406272115044.png) - -添加 - 企业微信 - -![](https://static-docs.nocobase.com/202406272115805.png) - -### 配置 - -![](https://static-docs.nocobase.com/202406272116978.png) - -- When a phone number does not match an existing user, should a new user be created automatically - 当使用手机号匹配不到已有用户时，是否自动创建新用户。 -- Company ID, AgentId 和 Secret - 填写上一步复制的密钥信息。 -- Workbench application homepage link - 工作台应用主页链接，复制并进入下一步。 - -## 配置企业微信应用首页 - -进入企业微信管理员后台，将复制的工作台应用主页链接填写到对应应用的应用主页地址栏。 - -![](https://static-docs.nocobase.com/202406272123631.png) - -![](https://static-docs.nocobase.com/202406272123048.png) - -## 登录 - -访问登录页面，点击登录表单下方按钮发起第三方登录。 - -![](https://static-docs.nocobase.com/202406272124608.png) - -:::warning -由于企业微信对于手机号等敏感信息的权限限制，只能在企业微信客户端内完成授权。第一次使用企业微信登录时，请参考以下步骤在企业微信客户端内完成首次登录授权。 -::: - -## 初次登录 - -从企业微信客户端进入工作台，下拉至底部，点击应用进入前面填写的应用主页，即可完成首次授权登录，之后就可以在 NocoBase 应用内使用企业微信登录。 - - diff --git a/docs/zh-CN/handbook/user-data-sync/dev/resource.md b/docs/zh-CN/handbook/user-data-sync/dev/resource.md new file mode 100644 index 00000000000..c4992cd5dc0 --- /dev/null +++ b/docs/zh-CN/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; + abstract create( + record: OriginRecord, + matchKey: string, + ): Promise; + + 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) + } + } +} +``` diff --git a/docs/zh-CN/handbook/user-data-sync/dev/source.md b/docs/zh-CN/handbook/user-data-sync/dev/source.md new file mode 100644 index 00000000000..f600a63bf86 --- /dev/null +++ b/docs/zh-CN/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 { + return []; + } +} +``` + +`SyncSource` 提供了options属性，用于获取数据源的自定义配置。 + +```ts +import { SyncSource, UserData } from '@nocobase/plugin-user-data-sync'; + +class CustomSyncSource extends SyncSource { + async pull(): Promise { + //... + 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 { + // ... + 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) + +上方为通用的数据源配置，下方为可注册的自定义配置表单部分。 diff --git a/docs/zh-CN/handbook/user-data-sync/index.md b/docs/zh-CN/handbook/user-data-sync/index.md new file mode 100644 index 00000000000..8655464be4c --- /dev/null +++ b/docs/zh-CN/handbook/user-data-sync/index.md @@ -0,0 +1,45 @@ +# 用户数据同步 + + + +## 介绍 + +注册和管理用户数据同步来源，默认提供 HTTP API, 可以通过插件扩展其他数据来源。默认支持向**用户**和**部门**表同步数据，也可以通过插件扩展其他同步目标资源。 + +## 安装 + +内置插件，无需单独安装。 + +## 数据源管理和数据同步 + +![](https://static-docs.nocobase.com/202412041043465.png) + +:::info +在未安装提供用户数据同步来源的插件时，可以通过 HTTP API 同步用户数据。参考 [数据源 - HTTP API](./sources/api). +::: + +## 添加数据源 + +安装提供用户数据同步来源的插件之后，即可添加相应的数据源。只有启用的数据源才会显示同步和任务按钮。 + +> 以企业微信为例 + +![](https://static-docs.nocobase.com/202412041053785.png) + +## 同步数据 + +点击「同步」按钮，开始进行数据同步。 + +![](https://static-docs.nocobase.com/202412041055022.png) + +点击「任务」按钮可以查看同步状态。同步成功后可以到用户和部门列表查看数据。 + +![](https://static-docs.nocobase.com/202412041202337.png) + +同步失败的任务，可以点击「重试」。 + +![](https://static-docs.nocobase.com/202412041058337.png) + +同步失败时可以通过系统日志排查原因，同时在应用日志目录下的 `user-data-sync` 目录里保存有原始的数据同步记录。 + +![](https://static-docs.nocobase.com/202412041205655.png) diff --git a/docs/zh-CN/handbook/user-data-sync/sources/api.md b/docs/zh-CN/handbook/user-data-sync/sources/api.md new file mode 100644 index 00000000000..c765ec96142 --- /dev/null +++ b/docs/zh-CN/handbook/user-data-sync/sources/api.md @@ -0,0 +1,74 @@ +# 通过 HTTP API 同步用户数据 + +## 获取 API 密钥 + +参考 [API 密钥](../api-keys), 需要确保 API 密钥设置的角色具有用户数据同步权限。 + +## API 说明 + +### 示例 + +```bash +curl 'https://localhost:13000/api/userData:push' \ + -H 'Authorization: Bearer ' \ + --data-raw '{"dataType":"user","records":[]}' # 请求体见下文详细说明 +``` + +### Endpoint + +```bash +POST /api/userData:push +``` + +### 用户数据格式 + +#### UserData + +| 参数名 | 类型 | 说明 | +| ---------- | ---------------------------------- | ------------------------------------------------------------------------ | +| `dataType` | `'user' \| 'department'` | 必填，推送的数据类型，推送用户数据填 `user` | +| `matchKey` | `'username' \| 'email' \| 'phone'` | 选填，会根据提供字段和推送数据中对应的字段值去查询系统已有用户，进行匹配 | +| `records` | `UserRecord[]` | 必填，用户数据记录数组 | + +#### UserRecord + +| 参数名 | 类型 | 说明 | +| ------------- | ---------- | ------------------------------------------------------------------------------------ | +| `uid` | `string` | 必填，来源用户数据的唯一标识，用于关联来源原始数据和系统用户。对于同一个用户不可变。 | +| `nickname` | `string` | 可选，用户昵称 | +| `username` | `string` | 可选，用户名 | +| `email` | `string` | 可选，用户邮箱 | +| `phone` | `string` | 可选，手机号 | +| `departments` | `string[]` | 可选，用户所属部门 uid 数组 | +| `isDeleted` | `boolean` | 可选，记录是否删除 | +| `` | `any` | 可选，其他用户表中的自建字段数据 | + +### 部门数据格式 + +:::info +推送部门数据的前提是安装并开启[部门](../../departments)插件。 +::: + +#### DepartmentData + +| 参数名 | 类型 | 说明 | +| ---------- | ------------------------ | ------------------------------------------------- | +| `dataType` | `'user' \| 'department'` | 必填，推送的数据类型，推送部门数据填 `department` | +| `records` | `DepartmentRecord[]` | 必填，部门数据记录数组 | + +#### DepartmentRecord + +| 参数名 | 类型 | 说明 | +| ----------- | --------- | ------------------------------------------------------------------------------------ | +| `uid` | `string` | 必填，来源部门数据的唯一标识，用于关联来源原始数据和系统部门。对于同一个部门不可变。 | +| `title` | `string` | 必填，部门标题 | +| `parentUid` | `string` | 可选，上级部门 uid | +| `isDeleted` | `boolean` | 可选，记录是否删除 | +| `` | `any` | 可选，其他部门表中的自建字段数据 | + +:::info + +1. 数据多次推送幂等。 +2. 如果推送部门时，父部门还未创建，则无法关联上，可再次推送数据。 +3. 如果推送用户时，部门还未创建，则无法关联上所属部门，可在推送部门数据后，再次推送用户数据。 + ::: diff --git a/docs/zh-CN/handbook/wecom/auth.md b/docs/zh-CN/handbook/wecom/auth.md new file mode 100644 index 00000000000..2e8d3147b1f --- /dev/null +++ b/docs/zh-CN/handbook/wecom/auth.md @@ -0,0 +1,108 @@ +# 认证：企业微信 + + + +## 介绍 + +**企业微信**插件支持用户使用企业微信账号登录 NocoBase. + +## 激活插件 + +![](https://static-docs.nocobase.com/202406272056962.png) + +## 创建和配置企业微信自建应用 + +进入企业微信管理后台，创建企业微信自建应用。 + +![](https://static-docs.nocobase.com/202406272101321.png) + +![](https://static-docs.nocobase.com/202406272102087.png) + +点击应用进入详情页，下拉页面，点击「企业微信授权登录」。 + +![](https://static-docs.nocobase.com/202406272104655.png) + +设置授权回调域为 NocoBase 应用域名。 + +![](https://static-docs.nocobase.com/202406272105662.png) + +回到应用详情页，点击「网页授权及 JS-SDK」。 + +![](https://static-docs.nocobase.com/202406272107063.png) + +设置并验证可作为应用 OAuth2.0 网页授权功能的回调域名。 + +![](https://static-docs.nocobase.com/202406272107899.png) + +在应用详情页，点击「企业可信 IP」。 + +![](https://static-docs.nocobase.com/202406272108834.png) + +配置 NocoBase 应用 IP. + +![](https://static-docs.nocobase.com/202406272109805.png) + +## 从企业微信管理后台获取密钥 + +在企业微信管理后台 - 我的企业，复制「企业 ID」. + +![](https://static-docs.nocobase.com/202406272111637.png) + +在企业微信管理后台 - 应用管理，进入上一步创建的应用的详情页，复制 AgentId 和 Secret + +![](https://static-docs.nocobase.com/202406272122322.png) + +## 在 NocoBase 上添加企业微信认证 + +进入用户认证插件管理页面。 + +![](https://static-docs.nocobase.com/202406272115044.png) + +添加 - 企业微信 + +![](https://static-docs.nocobase.com/202406272115805.png) + +### 配置 + +![](https://static-docs.nocobase.com/202412041459250.png) + +| 配置项 | 说明 | 版本要求 | +| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------- | +| When a phone number does not match an existing user,
should a new user be created automatically | 当使用手机号匹配不到已有用户时，是否自动创建新用户 | - | +| Company ID | 企业 ID, 从企业微信管理后台获取 | - | +| AgentId | 从企业微信管理后台自建应用配置获取 | - | +| Secret | 从企业微信管理后台自建应用配置获取 | - | +| Origin | 当前应用域名 | - | +| Workbench application redirect link | 成功登录后跳转的应用路径 | `v1.4.0` | +| Automatic login | 在企业微信浏览器里打开应用链接时，自动登录。当配置有多个企业微信认证器的时候，只有一个能开启该选项。 | `v1.4.0` | +| Workbench application homepage link | 工作台应用主页链接 | - | + +## 配置企业微信应用首页 + +:::info +`v1.4.0` 以上版本，在启用「自动登录」选项的情况下，应用主页链接可以简化为: `https:///`，例如 `https://example.nocobase.com/admin`. + +也可以将分别配置手机和电脑端，例如 `https://example.nocobase.com/m` 和 `https://example.nocobase.com/admin`. +::: + +进入企业微信管理员后台，将复制的工作台应用主页链接填写到对应应用的应用主页地址栏。 + +![](https://static-docs.nocobase.com/202406272123631.png) + +![](https://static-docs.nocobase.com/202406272123048.png) + +## 登录 + +访问登录页面，点击登录表单下方按钮发起第三方登录。 + +![](https://static-docs.nocobase.com/202406272124608.png) + +:::warning +由于企业微信对于手机号等敏感信息的权限限制，只能在企业微信客户端内完成授权。第一次使用企业微信登录时，请参考以下步骤在企业微信客户端内完成首次登录授权。 +::: + +## 初次登录 + +从企业微信客户端进入工作台，下拉至底部，点击应用进入前面填写的应用主页，即可完成首次授权登录，之后就可以在 NocoBase 应用内使用企业微信登录。 + + diff --git a/docs/zh-CN/handbook/wecom/index.md b/docs/zh-CN/handbook/wecom/index.md new file mode 100644 index 00000000000..a8abd986859 --- /dev/null +++ b/docs/zh-CN/handbook/wecom/index.md @@ -0,0 +1,13 @@ +# 企业微信 + + + +## 介绍 + +**企业微信**插件提供企业微信集成的能力，包括认证方式、通知渠道和用户数据同步来源。 + +参考： + +- [认证：企业微信](./auth.md) +- [通知：企业微信](./notification.md) +- [同步来源：企业微信](./user-data-sync.md) diff --git a/docs/zh-CN/handbook/wecom/notification.md b/docs/zh-CN/handbook/wecom/notification.md new file mode 100644 index 00000000000..05508bdfe3e --- /dev/null +++ b/docs/zh-CN/handbook/wecom/notification.md @@ -0,0 +1,27 @@ +# 通知：企业微信 + + + +## 介绍 + +**企业微信**插件支持应用向企业微信用户发送通知消息。 + +## 添加和配置企业微信认证器 + +首先需要在 NocoBase 上添加和配置一个企业微信认证器，参考 [用户认证 - 企业微信](./auth)，只有经过企业微信登录的系统用户，才可以通过企业微信接收系统通知。 + +## 添加企业微信通知渠道 + +![](https://static-docs.nocobase.com/202412041522365.png) + +## 配置企业微信通知渠道 + +选择刚才配置的认证器。 + +![](https://static-docs.nocobase.com/202412041525284.png) + +## 工作流通知节点配置 + +选择配置好的企业微信通知渠道，支持三种消息类型：文本卡片，Markdown, 模版卡片。 + +![](https://static-docs.nocobase.com/202412041529319.png) diff --git a/docs/zh-CN/handbook/wecom/user-data-sync.md b/docs/zh-CN/handbook/wecom/user-data-sync.md new file mode 100644 index 00000000000..57ecfc66957 --- /dev/null +++ b/docs/zh-CN/handbook/wecom/user-data-sync.md @@ -0,0 +1,43 @@ +# 从企业微信同步用户数据 + + + +## 介绍 + +**企业微信**插件支持用户从企业微信同步用户和部门数据。 + +## 创建和配置企业微信自建应用。 + +首先需要在企业微信管理后台，创建企业微信自建应用，并获取**企业 ID**, **AgentId** 和 **Secret**. + +参考 [用户认证 - 企业微信](./auth)。 + +## 在 NocoBase 上添加同步数据源 + +用户和权限 - 同步 - 添加，填写获取的相关信息。 + +![](https://static-docs.nocobase.com/202412041251867.png) + +## 配置通讯录同步 + +进入企业微信管理后台 - 安全和管理 - 管理工具，点击通讯录同步。 + +![](https://static-docs.nocobase.com/202412041249958.png) + +按如图所示设置，并设置企业可信 IP. + +![](https://static-docs.nocobase.com/202412041250776.png) + +接下来就可以进行用户数据同步了。 + +## 设置接收事件服务器 + +如果希望企业微信侧的用户、部门数据变动可以及时同步给 NocoBase 应用，可以进一步设置。 + +在填写了前面的配置信息之后，可以复制通讯录回调通知地址。 + +![](https://static-docs.nocobase.com/202412041256547.png) + +填写到企业微信设置上，并获取 Token 和 EncodingAESKey, 完成 NocoBase 用户同步数据源配置。 + +![](https://static-docs.nocobase.com/202412041257947.png)