SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场velt-notifications-best-practices

velt-notifications-best-practices

前端与建站

查看项目

更新于 10-16 05:22

技能介绍

用途

该技能是 Velt 通知系统在 React 与 Next.js 应用中的综合实现指南，包含跨 10 个类别、按影响优先级排列的 18 条规则，用于指导自动化代码生成与集成模式。

适用时机

在以下场景中可参考该指南：

  • 为 React/Next.js 应用添加应用内通知
  • 设置 VeltNotificationsTool 和 VeltNotificationsPanel
  • 配置通知标签页（For You、All、Documents、People）
  • 通过 hooks 或 REST API 访问通知数据
  • 管理用户通知偏好与渠道
  • 通过 REST API 读取或写入按用户的通知配置（文档级或组织级）
  • 使用 SendGrid 设置邮件通知
  • 通过 REST API 创建自定义通知
  • 通过 webhook 集成外部服务
  • 配置通知延迟与批处理以减少噪音

规则类别与优先级

  1. Core Setup（核心设置）——CRITICAL，前缀 core-
  2. Panel Configuration（面板配置）——HIGH，前缀 panel-
  3. Data Access（数据访问）——HIGH，前缀 data-
  4. Settings Management（设置管理）——MEDIUM-HIGH，前缀 settings-
  5. Configuration（配置）——MEDIUM，前缀 config-
  6. Notification Triggers（通知触发）——MEDIUM，前缀 triggers-
  7. Delivery Channels（投递渠道）——MEDIUM，前缀 delivery-
  8. UI Customization（UI 定制）——MEDIUM，前缀 ui-
  9. Wireframe Variables（线框变量）——MEDIUM，前缀 wireframe-variables-
  10. Debugging & Testing（调试与测试）——LOW-MEDIUM，前缀 debug-

快速参考

1. 核心设置（CRITICAL）

  • core-setup——启用通知并添加 VeltNotificationsTool

2. 面板配置（HIGH）

  • panel-tabs——配置通知面板标签页（forYou、all、documents、people）
  • panel-display——控制面板打开模式（popover 与 sidebar）

3. 数据访问（HIGH）

  • data-hooks——使用 React hooks 访问通知数据
  • data-rest-api——使用 REST API 进行服务端通知管理
  • data-notification-data-provider——注册 NotificationDataProvider，将自定义通知的获取与删除路由到自有后端；仅适用于 notificationSource === 'custom' 的通知；管线顺序为 notification → user → comment

4. 设置管理（MEDIUM-HIGH）

  • settings-channels——配置通知投递渠道
  • settings-config-rest-api——通过 REST API 在文档级或组织级读写按用户的通知配置

5. 配置（MEDIUM）

  • config-cross-organization——跨组织通知：enableCrossOrganization/disableCrossOrganization、CrossOrganizationConfig（organizationIds、excludeOrganizationIds）、"For You" 信息流合并、getCrossOrganizationConfig$() 订阅

6. 通知触发（MEDIUM）

  • triggers-custom——通过 REST API 创建自定义通知

7. 投递渠道（MEDIUM）

  • delivery-email——使用 SendGrid 设置邮件通知
  • delivery-webhooks——通过 webhook 集成外部服务
  • delivery-delay-batching——配置可选的服务器端延迟与批处理管线

8. UI 定制（MEDIUM）

  • ui-wireframes——使用线框（wireframes）定制通知组件

9. 线框变量（MEDIUM）

  • wireframe-variables-notifications-panel——使用模板变量绑定 Notifications Panel 线框插槽（标签页、设置、按行未读、空状态）
  • wireframe-variables-notifications-tool——使用模板变量绑定 Notifications Tool 线框插槽（铃铛图标替换、未读徽标、面板打开激活态）

10. 调试与测试（LOW-MEDIUM）

  • debug-common-issues——常见问题与解决方案

使用方式

阅读各规则文件以获取详细说明与代码示例：

  • rules/shared/core/core-setup.md
  • rules/shared/panel/panel-tabs.md

每个规则文件包含：

  • 简要说明其重要性
  • 带解释的错误代码示例
  • 带解释的正确代码示例
  • 指向官方文档的源链接

编译文档

  • AGENTS.md——所有规则的压缩索引及文件路径（建议从此开始）
  • AGENTS.full.md——展开全部规则的完整详细指南