跳到主要内容
版本：0.4.x(Latest)

基本介绍​

通知能力有三个入口：

入口使用者说明
services.Notifications()源码插件普通能力批量读取可见通知消息视图
services.Admin().Notifications()可信源码插件发送通知、删除通知、按业务来源删除通知
service: notifications动态插件通过notifications服务读取消息视图和发送受管控的通知

最新根能力目录没有services.Notify()方法。需要发送通知的源码插件应使用管理命令，因为发送消息会产生宿主写入和投递副作用。

能力阶段：运行期

类型支持：源码插件、动态插件

能力设计​

数据模型​

类型字段说明
SendInputRecipients目标用户标识集合
SendInputSourceType、SourceID业务来源类型和来源记录标识
SendInputTitle、Content通知标题和内容
SendInputCategory收件箱分类，未指定时可回退到other
SendInputSenderUserID可选发送者，缺省时适配器可使用CapabilityContext操作者
SendResultMessageID、DeliveryCount创建的消息标识和投递数量

内置来源类型包括notice和plugin，通用分类回退值为other。

读写分离设计​

通知能力遵循读写分离模式：普通Notifications()提供只读视图能力，Admin().Notifications()提供受管控的写入命令。发送属于受管控的写命令，因为会产生宿主写入和投递副作用。

本地化与发送​

通知内容需要插件自行处理本地化。发送前可借助国际化能力解析文案，通知能力本身不负责模板渲染。

接口定义​

源码插件接口​

入口方法说明
Notifications()BatchGetMessages批量读取可见通知消息视图
Admin().Notifications()Send发送受管控的通知
Admin().Notifications()DeleteMessages删除可见通知消息
Admin().Notifications()DeleteBySource按业务来源删除通知

动态插件接口​

动态插件通过hostServices.notifications声明授权的方法：

动态方法说明
messages.batch_get批量读取可见通知消息视图
messages.send发送受管控的通知

能力使用​

源码插件使用​

源码插件通过services.Notifications()读取通知视图，并显式传入领域要求的CapabilityContext：

// 批量读取通知消息
result, err := services.Notifications().BatchGetMessages(ctx, capabilityCtx, messageIDs)

可信源码插件发送和管理通知：

// 发送通知
result, err := services.Admin().Notifications().Send(ctx, capabilityCtx, notifycap.SendInput{
    Recipients: []string{userID},
    SourceType: notifycap.SourceTypePlugin,
    SourceID:   reportID,
    Title:      "报告生成完成",
    Content:    "您的报告已生成，请查看",
    Category:   notifycap.CategoryCode("report"),
})

// 按业务来源删除通知
err := services.Admin().Notifications().DeleteBySource(ctx, capabilityCtx, notifycap.SourceTypePlugin, []string{reportID})

动态插件使用​

动态插件在plugin.yaml中声明notifications服务和授权方法：

hostServices:
  - service: notifications
    methods:
      - messages.batch_get
      - messages.send
    resources:
      - ref: inbox:business-alert

messages.send是资源型方法，必须声明resources[].ref。宿主可据此限制插件可发送的消息场景或分类。在动态插件侧使用：

notifySvc := pluginbridge.Default().Notifications()

// 批量读取通知消息
result, err := notifySvc.BatchGetMessages(ctx, capabilityCtx, messageIDs)

// 发送通知
sendResult, err := notifySvc.Send(ctx, capabilityCtx, notifycap.SendInput{
    Recipients: []string{userID},
    SourceType: notifycap.SourceTypePlugin,
    SourceID:   taskID,
    Title:      "任务完成",
    Content:    "您的导出任务已完成",
    Category:   notifycap.CategoryCode("report"),
})

设计约束​

  • 普通能力只读。 Notifications()用于读取视图，不负责发送。
  • 发送属于受管控的写命令。 源码插件发送通知走Admin().Notifications().Send，动态插件走notifications.messages.send。
  • 删除按可见性和来源治理。 DeleteMessages和DeleteBySource都应在宿主领域适配器中检查目标可见性。
  • 通知内容应自行本地化。 发送前可以使用国际化能力解析文案，通知能力不负责模板渲染。

相关服务​