Skip to content

Commit 1db0e6b

Browse files
sheldon66sheldon66
authored
feat: add notifiaction doc (#164)
* chore: update cSpell.words and npm.packageManager in .vscode/settings.json * docs: update parameter name in notification development guide
1 parent c3021af commit 1db0e6b

File tree

6 files changed

+262
-1
lines changed

6 files changed

+262
-1
lines changed

‎.vscode/settings.json

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
{
2-
"cSpell.words": ["Noco"]
2+
"cSpell.words": [
3+
"Noco"
4+
],
5+
"npm.packageManager": "yarn"
36
}

‎docs/config/handbook.ts

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1358,6 +1358,15 @@ export default [
13581358
link: '/handbook/multi-app-manager',
13591359
// children: ['/plugins/api-doc'],
13601360
},
1361+
{
1362+
title: 'Notification',
1363+
'title.zh-CN': '通知',
1364+
children: [
1365+
'/handbook/notification/overview',
1366+
'/handbook/notification/handbook',
1367+
'/handbook/notification/development',
1368+
],
1369+
},
13611370
],
13621371
},
13631372
{

‎docs/zh-CN/api/notifications/core.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Notifications core
2+
3+
## Client
4+
5+
### registerChannelType
6+
7+
注册渠道类型
8+
9+
#### 签名
10+
11+
```typescript
12+
const registerChannelType = (options: ChannelOptions) => void
13+
14+
type ChannelType = {
15+
title: string;
16+
name: string;
17+
components: {
18+
ChannelConfigForm: ComponentType;
19+
ContentConfigForm?: ComponentType<{ variableOptions: any }>;
20+
};
21+
};
22+
```
23+
24+
| `` | 参数名 | 类型 | 默认值 | 描述 |
25+
| ----------------- | ---------- | ---- | ---------------- |
26+
| `options.title` | `string` | - | 渠道标题 |
27+
| `options.name` | `string` | - | 中间件配置项 |
28+
| `options.only` | `string[]` | - | 仅允许指定的操作 |
29+
| `options.except` | `string[]` | - | 排除指定的操作 |
30+
| `options.handler` | `Function` | - | 处理函数 |
31+
32+
## Server
33+
34+
### registerChanelType
35+
36+
注册服务端渠道类型
37+
38+
```typescript
39+
const registerChannelType = (options: ServerChannelOptions) => void
40+
41+
type ServerChannelOptions = {
42+
name: string;
43+
Server: new () => NotificationServer;
44+
};
45+
```
46+
47+
服务端需要实现`NotifiactionSever`，主要包括服务端发送方法
48+
49+
#### 签名
50+
51+
```ts
52+
export type SendFnType = (args: {
53+
message: SendOptions;
54+
channel: {
55+
id: string;
56+
options: Record<string, any>;
57+
notificationType: string;
58+
};
59+
}) => Promise<
60+
Array<{
61+
receiver: string;
62+
content: any;
63+
status: 'success' | 'fail';
64+
reason?: string;
65+
}>
66+
>;
67+
```

‎docs/zh-CN/handbook/notification/development.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# 开发指南
2+
3+
## 调用通知发信API: send
4+
5+
```ts
6+
import { Plugin } from '@nocobase/server';
7+
import NotificationsServerPlugin from '@nocobase/plugin-notification-manager';
8+
9+
export default class extends Plugin {
10+
async load() {
11+
12+
//获取通知插件实例
13+
const notificationServer = this.app.pm.get(NotificationsServerPlugin);
14+
15+
//调用发信API
16+
notificationServer.send({channelId, message})
17+
18+
}
19+
}
20+
```
21+
22+
`send`函数入参说明
23+
24+
| 参数 | 说明 |
25+
| ----------- | -----------------|
26+
| `channelName` | 已配置好的渠道标识 |
27+
| `message` | 消息体，具体格式 |
28+
29+
`send`函数返回值是`Promise<Data>`，其中Data的格式是
30+
31+
32+
| 参数 | 说明 |
33+
| ----------- | -----------------|
34+
| `status` | `failure`-表示发送失败， `success`-表示发送成功|
35+
|`reason`| 如果消息发送失败此值为失败原因，否则为空|
36+
| `message` | 消发送的消息体数据 |
37+
38+
## 通知插件扩展
39+
40+
扩展通知插件主要分两部分：客户端渠道配置表单和消息配置表单，以及服务端的send函数扩展
41+
42+
### 客户端扩展
43+
44+
调用通知客户端内核的`registerChannelType`方法,方法入参
45+
46+
| 参数 | 说明 |
47+
| ----------- | ----------------- |
48+
| `title` | 扩展渠道类型显示名称 |
49+
| `name` | 扩展渠道类型标识 |
50+
| `components.ChannelConfigForm` | 渠道配置表单组件 |
51+
| `components.ContentConfigForm` | 消息配置表单组件，接收`variableOptions`(当前环境变量) 作为组件属性 |
52+
53+
54+
以下是smtp邮件扩展客户端注册的示例代码：
55+
56+
```ts
57+
import { Plugin } from '@nocobase/client';
58+
import NotificationManager from '@nocobase/plugin-notification-manager/client';
59+
import { tval } from '@nocobase/utils/client';
60+
import { ChannelConfigForm } from './ConfigForm';
61+
import { ContentConfigForm } from './MessageConfigForm';
62+
export class PluginNotificationsMailClient extends Plugin {
63+
async afterAdd() {}
64+
65+
async beforeLoad() {}
66+
async load() {
67+
const notification = this.pm.get(NotificationManager);
68+
notification.manager.registerChannelType({
69+
title: tval('SMTP mail', { ns: NAMESPACE }),
70+
name: channelType,
71+
components: {
72+
ChannelConfigForm: ChannelConfigForm,
73+
ContentConfigForm: ContentConfigForm,
74+
},
75+
});
76+
}
77+
}
78+
79+
export default PluginNotificationsMailClient;
80+
```
81+
82+
### 服务端扩展
83+
84+
服务端插件扩展类需要实现send方法
85+
86+
`send`函数入参说明
87+
88+
| 参数 | 说明 |
89+
| ----------- | -----------------|
90+
| `channel.name` | 渠道标识 |
91+
| `channel.title` | 渠道名称 |
92+
| `channel.options` | 客户端注册的`ChannelConfigForm`组件返回的配置项 |
93+
| `message` | 客户端注册的`ContentConfigForm`组件返回的配置项 |
94+
95+
`send`函数返回值是`Promise<Data>`，其中Data的格式是
96+
97+
| 属性 | 说明 |
98+
| ----------- | -----------------|
99+
| `status` | `failure`-表示发送失败， `success`-表示发送成功|
100+
|`reason`| 如果消息发送失败此值为失败原因，否则为空|
101+
102+
以下为`send`方法实现类实例：
103+
104+
```ts
105+
export class MailServer extends NotificationServerBase {
106+
transpoter: Transporter;
107+
constructor() {
108+
super();
109+
}
110+
send: SendFnType<Message> = async function (args) {
111+
const { message, channel } = args;
112+
const { host, port, secure, account, password, from } = channel.options;
113+
114+
};
115+
}
116+
```
117+
118+
以下扩展插件注册示例：
119+
120+
```ts
121+
export class PluginNotificationsMailServer extends Plugin {
122+
async afterAdd() {}
123+
124+
async beforeLoad() {}
125+
126+
async load() {
127+
const notificationServer = this.pm.get(NotificationsServerPlugin) as NotificationsServerPlugin;
128+
notificationServer.notificationManager.registerTypes(channelType, {
129+
server: new MailServer(),
130+
});
131+
}
132+
133+
async install() {}
134+
135+
async afterEnable() {}
136+
137+
async afterDisable() {}
138+
139+
async remove() {}
140+
}
141+
```
142+

‎docs/zh-CN/handbook/notification/handbook.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# 使用手册
2+
3+
## 场景：发送邮件通知
4+
5+
在插件管理器页面启用通知邮件插件
6+
![Snipaste_2024-09-20_06-52-31-2024-09-20-06-56-54](https://static-docs.nocobase.com/Snipaste_2024-09-20_06-52-31-2024-09-20-06-56-54.png)
7+
8+
进入通知的渠道管理页面，点击右上角新增，选择SMTP邮件类型
9+
![屏幕截图_18-9-2024_11555_localhost-2024-09-18-11-06-19](https://static-docs.nocobase.com/屏幕截图_18-9-2024_11555_localhost-2024-09-18-11-06-19.jpeg)
10+
11+
然后会弹出对应类型的渠道配置表单，按照提示配置好渠道参数后点击提交
12+
![屏幕截图_18-9-2024_111926_localhost-2024-09-18-11-19-52](https://static-docs.nocobase.com/屏幕截图_18-9-2024_111926_localhost-2024-09-18-11-19-52.jpeg)
13+
14+
配置好以后，渠道管理页面会新增一条对应的渠道
15+
![20240920071434-2024-09-20-07-14-35](https://static-docs.nocobase.com/20240920071434-2024-09-20-07-14-35.png)
16+
17+
配置一个工作流，如何配置可以参考工作流使用手册 [工作流快速入门](https://docs-cn.nocobase.com/handbook/workflow/quick-start)
18+
19+
新增一个通知节点
20+
![20240920071659-2024-09-20-07-17-00](https://static-docs.nocobase.com/20240920071659-2024-09-20-07-17-00.png)
21+
22+
配置
23+
24+
![20240920072038-2024-09-20-07-20-39](https://static-docs.nocobase.com/20240920072038-2024-09-20-07-20-39.png)
25+
26+
点击提交
27+
28+
![20240920072100-2024-09-20-07-21-01](https://static-docs.nocobase.com/20240920072100-2024-09-20-07-21-01.png)
29+
30+
工作流启用后，触发工作流的执行，接收人邮箱可以收到对应的邮件通知。同时到日志管理页面可以看到发送日志
31+
![20240920083418-2024-09-20-08-34-19](https://static-docs.nocobase.com/20240920083418-2024-09-20-08-34-19.png)

‎docs/zh-CN/handbook/notification/overview.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# 概述
2+
3+
## 介绍
4+
5+
NocoBase 的通知模块，为用户提供通知渠道管理，日志查看，扩展插件注册等功能，主要由以下部分组成：
6+
7+
- 管理插件 `@nocobase/plugin-notification-manager` ：提供渠道管理，日志查看，通知扩展插件注册等功能
8+
- 工作流节点插件 `@nocobase/plugin-workflow-notification` 在工作流中扩展通知节点
9+
- 通知扩展插件：扩展通知模块以支持各种不同类型的通知，如邮件，站内信等，如`@nocobase/plugin-notification-mail-smtp`是一个smtp邮件扩展

0 commit comments

Comments
 (0)