HH/NOTIFICATION_INBOX_README.md

# Notification Inbox Implementation

## Overview
A complete in-app notification inbox system has been implemented for PX360. Every email sent to a user now automatically creates a corresponding in-app notification.

## Features Implemented

### 1. Database Model: `UserNotification`
- **Location**: `apps/notifications/models.py`
- **Fields**:
  - User (ForeignKey to User)
  - Title & Message (Bilingual: EN/AR)
  - Notification Type (complaint_assigned, sla_reminder, etc.)
  - Read/Dismissed Status with timestamps
  - Related Object (GenericForeignKey)
  - Action URL for navigation
  - Link to Email Log

### 2. Automatic Notification Creation
- **Modified**: `apps/notifications/services.py`
- The `send_email()` method now automatically creates an in-app notification for every email sent
- Notifications are linked to the email log for tracking

### 3. API Endpoints
- `GET /notifications/api/list/` - List notifications (with pagination)
- `GET /notifications/api/unread-count/` - Get unread count
- `GET /notifications/api/latest/` - Get latest 5 unread (for dropdown)
- `POST /notifications/api/mark-read/<id>/` - Mark single as read
- `POST /notifications/api/mark-all-read/` - Mark all as read
- `POST /notifications/api/dismiss/<id>/` - Dismiss single
- `POST /notifications/api/dismiss-all/` - Dismiss all

### 4. Notification Inbox Page
- **URL**: `/notifications/inbox/`
- **Template**: `templates/notifications/inbox.html`
- Features:
  - Filter tabs: All | Unread | Read
  - List view with icons, titles, timestamps
  - Mark as read / Dismiss actions
  - Bulk actions (Mark all read, Dismiss all)
  - Pagination (20 per page)
  - Empty state
  - Bilingual support (EN/AR)

### 5. Topbar Integration
- **Modified**: `templates/layouts/partials/topbar.html`
- Real-time unread count badge
- Dynamic dropdown showing latest 5 notifications
- "View All" link to inbox
- Auto-refresh every 30 seconds

### 6. Context Processor
- **Modified**: `apps/core/context_processors.py`
- Adds `notification_count` to all authenticated requests
- Shows unread count in topbar badge

### 7. Admin Interface
- **Modified**: `apps/notifications/admin.py`
- Full CRUD for UserNotification model
- Filter by type, read status, dismissed status
- Bulk actions: Mark as read, Dismiss
- Search by user email, title, message

### 8. Cleanup Command
- **Command**: `python manage.py cleanup_notifications`
- **Options**:
  - `--days=30` - Configure retention period (default: 30)
  - `--dry-run` - Preview what would be deleted
- Deletes notifications older than 30 days
- Run via cron daily

## File Structure

```
apps/notifications/
├── models.py                    # Added UserNotification model
├── views.py                     # Added inbox views and API endpoints
├── urls.py                      # Added notification inbox URLs
├── admin.py                     # Added UserNotificationAdmin
├── services.py                  # Modified send_email() to auto-create notifications
└── management/commands/
    └── cleanup_notifications.py # Cleanup old notifications

templates/notifications/
└── inbox.html                   # Notification inbox page

templates/layouts/
├── partials/topbar.html         # Updated with dynamic notification dropdown
└── base.html                    # Added notification polling JavaScript

apps/core/
└── context_processors.py        # Added notification_count to context
```

## Usage

### For Users:
1. **View Notifications**: Click bell icon in topbar
2. **See All**: Click "View All" in dropdown or visit `/notifications/inbox/`
3. **Mark as Read**: Click notification or "Mark as read" button
4. **Dismiss**: Click X button to hide notification
5. **Navigate**: Click notification to go to related page

### For Developers:

#### Creating Notifications Manually:
```python
from apps.notifications.services import create_in_app_notification

notification = create_in_app_notification(
    user=user,
    title="New Complaint Assigned",
    message="You have been assigned a new complaint",
    notification_type="complaint_assigned",
    related_object=complaint,
    action_url=f"/complaints/{complaint.id}/"
)
```

#### Auto-Created Notifications:
All emails sent via `NotificationService.send_email()` automatically create notifications:
```python
from apps.notifications.services import NotificationService

NotificationService.send_email(
    email=user.email,
    subject="New Complaint",
    message="A new complaint has been assigned to you",
    notification_type="complaint_assigned",  # This creates in-app notification
    user=user  # Optional: explicit user
)
```

## Configuration

### Settings (add to settings.py):
```python
# Notification retention period (days)
NOTIFICATION_RETENTION_DAYS = 30
```

### Cron Job (cleanup):
Add to crontab to run daily at 3 AM:
```bash
0 3 * * * cd /path/to/project && /path/to/venv/bin/python manage.py cleanup_notifications
```

## Testing Checklist

- [ ] Send an email and check if notification appears
- [ ] Open notification inbox page
- [ ] Mark notification as read
- [ ] Dismiss notification
- [ ] Check topbar badge updates
- [ ] Click notification to navigate
- [ ] Test bilingual content (switch language)
- [ ] Run cleanup command with --dry-run
- [ ] Admin interface works
- [ ] API endpoints return correct data

## Future Enhancements (Optional)

1. **Real-time Updates**: Implement WebSocket for instant notifications
2. **Push Notifications**: Add browser push notification support
3. **Email Preferences**: Allow users to choose email vs in-app only
4. **Notification Settings**: Granular control per notification type
5. **Mobile App**: Push notifications for mobile app

## Summary

✅ **Model**: UserNotification with all required fields
✅ **Auto-creation**: Every email creates in-app notification
✅ **Inbox Page**: Full-featured notification center at `/notifications/inbox/`
✅ **Topbar**: Dynamic dropdown with real-time count
✅ **API**: Complete REST API for all operations
✅ **Admin**: Full Django admin integration
✅ **Cleanup**: Automated deletion of old notifications (30 days)
✅ **Bilingual**: EN/AR support throughout
✅ **Context**: notification_count available in all templates

The notification inbox is now fully functional and ready for use!