122 lines
3.7 KiB
Markdown
122 lines
3.7 KiB
Markdown
# Notifications Feature Capsule
|
|
|
|
## Quick Summary
|
|
|
|
Email and toast notification system for maintenance due/overdue items and expiring documents. Uses Resend for email delivery and provides admin-editable email templates. User-scoped data with per-entry email notification toggles.
|
|
|
|
## API Endpoints
|
|
|
|
### User Endpoints
|
|
- `GET /api/notifications/summary` - Get notification summary (counts for login toast)
|
|
- `GET /api/notifications/maintenance` - Get due/overdue maintenance items
|
|
- `GET /api/notifications/documents` - Get expiring/expired documents
|
|
|
|
### Admin Endpoints
|
|
- `GET /api/admin/email-templates` - List all email templates
|
|
- `GET /api/admin/email-templates/:key` - Get single email template
|
|
- `PUT /api/admin/email-templates/:key` - Update email template
|
|
- `POST /api/admin/email-templates/:key/preview` - Preview template with sample variables
|
|
|
|
## Structure
|
|
|
|
- **api/** - HTTP endpoints, routes, validators
|
|
- **domain/** - Business logic, services, types
|
|
- **data/** - Repository, database queries
|
|
- **migrations/** - Feature-specific schema
|
|
- **tests/** - All feature tests
|
|
|
|
## Email Templates
|
|
|
|
### Predefined Templates (4 total)
|
|
1. **maintenance_due_soon** - Sent when maintenance is due within 30 days or 500 miles
|
|
2. **maintenance_overdue** - Sent when maintenance is past due
|
|
3. **document_expiring** - Sent when document expires within 30 days
|
|
4. **document_expired** - Sent when document has expired
|
|
|
|
### Template Variables
|
|
Templates use `{{variableName}}` syntax for variable substitution.
|
|
|
|
**Maintenance templates:**
|
|
- userName, vehicleName, category, subtypes, dueDate, dueMileage
|
|
|
|
**Document templates:**
|
|
- userName, vehicleName, documentType, documentTitle, expirationDate
|
|
|
|
## Dependencies
|
|
|
|
### Internal
|
|
- `core/auth` - Authentication plugin
|
|
- `core/logging` - Structured logging
|
|
- `core/config` - Database pool and secrets
|
|
|
|
### External
|
|
- `resend` - Email delivery service
|
|
|
|
### Database
|
|
- Tables: `email_templates`, `notification_logs`
|
|
- FK: `maintenance_schedules(email_notifications)`, `documents(email_notifications)`
|
|
|
|
## Business Rules
|
|
|
|
### Notification Triggers
|
|
|
|
**Maintenance Due Soon:**
|
|
- Next due date within 30 days OR
|
|
- Next due mileage within 500 miles of current odometer
|
|
|
|
**Maintenance Overdue:**
|
|
- Next due date in the past OR
|
|
- Current odometer exceeds next due mileage
|
|
|
|
**Document Expiring Soon:**
|
|
- Expiration date within 30 days
|
|
|
|
**Document Expired:**
|
|
- Expiration date in the past
|
|
|
|
### Email Notification Toggle
|
|
- Per-entry toggle on `maintenance_schedules.email_notifications`
|
|
- Per-entry toggle on `documents.email_notifications`
|
|
- Default: `false` (opt-in)
|
|
|
|
### Login Toast Summary
|
|
- Shows count of maintenance items requiring attention
|
|
- Shows count of documents requiring attention
|
|
- Displayed once per session on successful login
|
|
|
|
## Security Requirements
|
|
|
|
1. All queries user-scoped (filter by user_id)
|
|
2. Prepared statements (never concatenate SQL)
|
|
3. User endpoints require JWT authentication
|
|
4. Admin endpoints require admin role
|
|
5. Template editing restricted to admins
|
|
6. Email logs track all sent notifications
|
|
|
|
## Email Service Configuration
|
|
|
|
### Environment Variables
|
|
- `RESEND_API_KEY` - Resend API key (required, stored in secrets)
|
|
- `FROM_EMAIL` - Sender email address (default: noreply@motovaultpro.com)
|
|
|
|
### Email Delivery
|
|
- Uses Resend API for transactional emails
|
|
- Converts plain text templates to HTML with line breaks
|
|
- Tracks all sent emails in `notification_logs` table
|
|
- Logs failures with error messages for debugging
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run feature tests
|
|
npm test -- features/notifications
|
|
```
|
|
|
|
## Future Enhancements
|
|
|
|
- Batch notification processing (scheduled job)
|
|
- Notification frequency controls (daily digest, etc.)
|
|
- User preference for notification types
|
|
- SMS notifications (via Twilio or similar)
|
|
- Push notifications (via FCM or similar)
|