docs: Consolidate documentation - 52% reduction (56 → 27 files)
✅ Documentation Cleanup: - Deleted 30 obsolete/completed docs - Created NOTIFICATION_SYSTEM.md (consolidates all notification docs) - Reduced from 56 to 27 MD files (52% reduction) 🗑️ Removed Categories: - Completed features (ALL_ISSUES_FIXED, BASIC_CARD_COMPLETE, etc.) - Superseded plans (NOTIFICATION_STRATEGY, NOTIFICATION_REFACTOR_*, etc.) - Duplicate/fragmented docs (MARKDOWN_*, TEMPLATE_*, etc.) 📝 Consolidated: - All notification documentation → NOTIFICATION_SYSTEM.md - Architecture & flow - Markdown syntax reference - Variables reference - Backend integration details - API endpoints - Email queue system - Global system toggle - Q&A section ✅ Kept Essential Docs (27): - Core architecture guides - Addon development guides - Feature-specific docs (shipping, payment, tax) - Implementation guides (i18n, hooks) - Project docs (README, PROJECT_BRIEF, PROJECT_SOP) 📊 Result: - Clearer navigation - Less confusion - Single source of truth for notifications - Easier for new developers
This commit is contained in:
dwindown
295
NOTIFICATION_SYSTEM.md
Normal file
295
NOTIFICATION_SYSTEM.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# Notification System Documentation
|
||||
|
||||
**Status:** ✅ Complete & Fully Wired
|
||||
**Last Updated:** November 15, 2025
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
WooNooW features a modern, flexible notification system that supports multiple channels (Email, Push, WhatsApp, Telegram, SMS) with customizable templates and markdown support.
|
||||
|
||||
### Key Features
|
||||
- ✅ Multi-channel support (Email, Push, + Addons)
|
||||
- ✅ Custom markdown templates with visual builder
|
||||
- ✅ Variable system for dynamic content
|
||||
- ✅ Global system toggle (WooNooW vs WooCommerce)
|
||||
- ✅ Per-channel and per-event toggles
|
||||
- ✅ Email customization (colors, logo, branding)
|
||||
- ✅ Async email queue (prevents 30s timeout)
|
||||
- ✅ Full backend wiring complete
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Structure
|
||||
```
|
||||
Notifications
|
||||
├── Staff Notifications (toggle channels/events)
|
||||
├── Customer Notifications (toggle channels/events)
|
||||
├── Channel Configuration (global settings)
|
||||
│ ├── Email (template + connection)
|
||||
│ └── Push (template + connection)
|
||||
└── Activity Log (coming soon)
|
||||
```
|
||||
|
||||
### Notification Flow
|
||||
```
|
||||
Event → EmailManager → Check System Mode → Check Channel Toggle
|
||||
→ Check Event Toggle → EmailRenderer → Get Template → Replace Variables
|
||||
→ Parse Markdown → Apply Branding → Queue via MailQueue → Send
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Markdown Syntax
|
||||
|
||||
### Cards
|
||||
```markdown
|
||||
[card:info]
|
||||
Your content here
|
||||
[/card]
|
||||
|
||||
[card:success]
|
||||
Success message
|
||||
[/card]
|
||||
|
||||
[card:warning]
|
||||
Warning message
|
||||
[/card]
|
||||
```
|
||||
|
||||
### Buttons
|
||||
```markdown
|
||||
[button:solid](https://example.com)
|
||||
Click Me
|
||||
[/button]
|
||||
|
||||
[button:outline](https://example.com)
|
||||
Learn More
|
||||
[/button]
|
||||
```
|
||||
|
||||
### Images
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Variables
|
||||
|
||||
### Order Variables
|
||||
- `{order_number}` - Order number
|
||||
- `{order_date}` - Order date
|
||||
- `{order_total}` - Order total
|
||||
- `{order_status}` - Order status
|
||||
- `{order_items_table}` - Formatted table
|
||||
- `{order_items_list}` - Formatted list
|
||||
|
||||
### Customer Variables
|
||||
- `{customer_name}` - Customer full name
|
||||
- `{customer_first_name}` - First name
|
||||
- `{customer_last_name}` - Last name
|
||||
- `{customer_email}` - Email address
|
||||
|
||||
### Store Variables
|
||||
- `{store_name}` - Store name
|
||||
- `{store_url}` - Store URL
|
||||
- `{store_email}` - Store email
|
||||
|
||||
---
|
||||
|
||||
## Backend Integration
|
||||
|
||||
### API Endpoints
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
|--------|----------|---------|
|
||||
| GET | `/notifications/system-mode` | Get current mode |
|
||||
| POST | `/notifications/system-mode` | Switch mode |
|
||||
| GET | `/notifications/channels` | Get all channels |
|
||||
| POST | `/notifications/channels/toggle` | Toggle channel |
|
||||
| GET | `/notifications/events` | Get all events |
|
||||
| POST | `/notifications/events/update` | Update event |
|
||||
| GET | `/notifications/templates/{id}/{ch}` | Get template |
|
||||
| POST | `/notifications/templates` | Save template |
|
||||
| GET | `/notifications/email-settings` | Get email customization |
|
||||
| POST | `/notifications/email-settings` | Save email customization |
|
||||
|
||||
### Database Options
|
||||
|
||||
```php
|
||||
// System mode
|
||||
woonoow_notification_system_mode = 'woonoow' | 'woocommerce'
|
||||
|
||||
// Channel toggles
|
||||
woonoow_email_notifications_enabled = true | false
|
||||
woonoow_push_notifications_enabled = true | false
|
||||
|
||||
// Event settings
|
||||
woonoow_notification_settings = [
|
||||
'order_processing' => [
|
||||
'channels' => [
|
||||
'email' => ['enabled' => true, 'recipient' => 'customer']
|
||||
]
|
||||
]
|
||||
]
|
||||
|
||||
// Templates
|
||||
woonoow_notification_templates = [
|
||||
'order_processing_email_customer' => [
|
||||
'subject' => '...',
|
||||
'body' => '...'
|
||||
]
|
||||
]
|
||||
|
||||
// Email customization
|
||||
woonoow_email_settings = [
|
||||
'primary_color' => '#7f54b3',
|
||||
'logo_url' => '...',
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Email Queue System
|
||||
|
||||
### Purpose
|
||||
Prevents 30-second timeout when sending emails via SMTP.
|
||||
|
||||
### Implementation
|
||||
- **WooEmailOverride**: Intercepts `wp_mail()` calls
|
||||
- **MailQueue**: Queues emails via Action Scheduler
|
||||
- **Async Processing**: Emails sent in background
|
||||
|
||||
### Files
|
||||
- `includes/Core/Mail/WooEmailOverride.php`
|
||||
- `includes/Core/Mail/MailQueue.php`
|
||||
|
||||
### Initialization
|
||||
```php
|
||||
// In Bootstrap.php
|
||||
MailQueue::init();
|
||||
WooEmailOverride::init();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Classes
|
||||
|
||||
### NotificationManager
|
||||
**File:** `includes/Core/Notifications/NotificationManager.php`
|
||||
|
||||
- `should_send_notification()` - Validates all toggles
|
||||
- `send()` - Main sending method
|
||||
- `is_channel_enabled()` - Check global channel state
|
||||
- `is_event_channel_enabled()` - Check per-event state
|
||||
|
||||
### EmailManager
|
||||
**File:** `includes/Core/Notifications/EmailManager.php`
|
||||
|
||||
- `is_enabled()` - Check if WooNooW system active
|
||||
- `disable_wc_emails()` - Disable WooCommerce emails
|
||||
- Hooks into WooCommerce order status changes
|
||||
|
||||
### EmailRenderer
|
||||
**File:** `includes/Core/Notifications/EmailRenderer.php`
|
||||
|
||||
- `render()` - Render email from template
|
||||
- `replace_variables()` - Replace variables with data
|
||||
- `parse_cards()` - Parse markdown cards
|
||||
- Applies email customization
|
||||
|
||||
### TemplateProvider
|
||||
**File:** `includes/Core/Notifications/TemplateProvider.php`
|
||||
|
||||
- `get_template()` - Get custom or default template
|
||||
- `get_variables()` - Get available variables
|
||||
- `get_default_template()` - Get default template
|
||||
|
||||
---
|
||||
|
||||
## Global System Toggle
|
||||
|
||||
### Purpose
|
||||
Allow users to switch between WooNooW and WooCommerce notification systems.
|
||||
|
||||
### Modes
|
||||
|
||||
**WooNooW Mode** (default):
|
||||
- Custom templates with markdown
|
||||
- Multi-channel support
|
||||
- Full customization
|
||||
- WooCommerce emails disabled
|
||||
|
||||
**WooCommerce Mode**:
|
||||
- Standard WooCommerce emails
|
||||
- WooNooW notifications disabled
|
||||
- For users who prefer classic system
|
||||
|
||||
### Implementation
|
||||
```php
|
||||
// Check mode
|
||||
$mode = get_option('woonoow_notification_system_mode', 'woonoow');
|
||||
|
||||
// EmailManager respects mode
|
||||
if (!EmailManager::is_enabled()) {
|
||||
return; // Skip WooNooW notifications
|
||||
}
|
||||
|
||||
// NotificationManager checks mode
|
||||
if ($system_mode !== 'woonoow') {
|
||||
return false; // Use WooCommerce instead
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Q&A
|
||||
|
||||
### Q: Are templates saved and used when sending?
|
||||
**A:** ✅ Yes. Templates saved via API are fetched by EmailRenderer and used when sending.
|
||||
|
||||
### Q: Are channel toggles respected?
|
||||
**A:** ✅ Yes. NotificationManager checks both global and per-event toggles before sending.
|
||||
|
||||
### Q: Does the global system toggle work?
|
||||
**A:** ✅ Yes. EmailManager and NotificationManager both check the mode before processing.
|
||||
|
||||
### Q: Is email sending async?
|
||||
**A:** ✅ Yes. MailQueue queues emails via Action Scheduler to prevent timeouts.
|
||||
|
||||
### Q: Are variables replaced correctly?
|
||||
**A:** ✅ Yes. EmailRenderer replaces all variables with actual data from orders/customers.
|
||||
|
||||
### Q: Does markdown parsing work?
|
||||
**A:** ✅ Yes. Cards, buttons, and images are parsed correctly in both visual builder and email output.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **NEW_MARKDOWN_SYNTAX.md** - Markdown syntax reference
|
||||
- **NOTIFICATION_SYSTEM_QA.md** - Q&A and backend status
|
||||
- **BACKEND_WIRING_COMPLETE.md** - Backend integration details
|
||||
- **CUSTOM_EMAIL_SYSTEM.md** - Email system architecture
|
||||
- **FILTER_HOOKS_GUIDE.md** - Available hooks for customization
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Features
|
||||
- Activity Log page
|
||||
- WhatsApp addon
|
||||
- Telegram addon
|
||||
- SMS addon
|
||||
- A/B testing for templates
|
||||
- Scheduled notifications
|
||||
- Customer notification preferences page
|
||||
|
||||
### Addon Development
|
||||
See **ADDON_DEVELOPMENT_GUIDE.md** for creating custom notification channels.
|
||||
Reference in New Issue
Block a user