velt-notifications-best-practices（velt 通知最佳实践）

Velt Notifications Best Practices

Comprehensive implementation guide for Velt's notification system in React and Next.js applications. Contains 15 rules across 8 categories, prioritized by impact to guide automated code generation and integration patterns.

When to Apply

Reference these guidelines when:

• Adding in-app notifications to a React/Next.js application
• Setting up the VeltNotificationsTool and VeltNotificationsPanel
• Configuring notification tabs (For You, All, Documents, People)
• Accessing notification data via hooks or REST APIs
• Managing user notification preferences and channels
• Reading or writing per-user notification config via REST API (document-level or org-level)
• Setting up email notifications with SendGrid
• Creating custom notifications via REST API
• Integrating with external services via webhooks
• Configuring notification delay and batching to reduce noise

Rule Categories by Priority

Quick Reference

1. Core Setup (CRITICAL)

• core-setup — Enable notifications and add VeltNotificationsTool

2. Panel Configuration (HIGH)

• panel-tabs — Configure notification panel tabs (forYou, all, documents, people)
• panel-display — Control panel open mode (popover vs sidebar)

3. Data Access (HIGH)

• data-hooks — Use React hooks to access notification data
• data-rest-api — Use REST APIs for server-side notification management
• data-notification-data-provider — Register NotificationDataProvider to route custom notification fetch and delete through your own backend; applies only to notificationSource === 'custom' notifications; pipeline order is notification → user → comment

4. Settings Management (MEDIUM-HIGH)

• settings-channels — Configure notification delivery channels
• settings-config-rest-api — Read and write per-user notification config at document or org level via REST API

5. Notification Triggers (MEDIUM)

• triggers-custom — Create custom notifications via REST API

6. Delivery Channels (MEDIUM)

• delivery-email — Set up email notifications with SendGrid
• delivery-webhooks — Integrate with external services via webhooks
• delivery-delay-batching — Configure opt-in server-side delay and batching pipeline

7. UI Customization (MEDIUM)

• ui-wireframes — Customize notification components with wireframes

8. Debugging & Testing (LOW-MEDIUM)

• debug-common-issues — Common issues and solutions

How to Use

Read individual rule files for detailed explanations and code examples:

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

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Source pointers to official documentation

Compiled Documents

• AGENTS.md — Compressed index of all rules with file paths (start here)
• AGENTS.full.md — Full verbose guide with all rules expanded inline