332 lines
9.7 KiB
Markdown
332 lines
9.7 KiB
Markdown
# Appreciation App
|
|
|
|
A comprehensive appreciation system for sending and tracking appreciation to users and physicians in the PX360 healthcare platform.
|
|
|
|
## Features
|
|
|
|
### Core Functionality
|
|
- **Send Appreciation**: Users can send appreciation to colleagues and physicians
|
|
- **Multi-Recipient Support**: Send to both users and physicians
|
|
- **Categories**: Categorize appreciations (Excellent Care, Team Player, Innovation, etc.)
|
|
- **Visibility Control**: Private, Department, Hospital, or Public visibility
|
|
- **Anonymous Option**: Send appreciations anonymously
|
|
- **Multi-Language**: Full English and Arabic support
|
|
|
|
### Notifications
|
|
- Automatic email notifications to recipients
|
|
- SMS notifications when phone number is available
|
|
- Integration with the notification system
|
|
|
|
### Gamification
|
|
- **Badges System**: Automatically award badges based on achievements
|
|
- First Appreciation (1 appreciation)
|
|
- Rising Star (5 appreciations)
|
|
- Shining Star (10 appreciations)
|
|
- Super Star (25 appreciations)
|
|
- Legendary (50 appreciations)
|
|
- Monthly Champion (10 appreciations in a month)
|
|
- Consistent (4-week streak)
|
|
- Well-Loved (10 different senders)
|
|
- **Leaderboard**: Hospital and department rankings
|
|
- **Statistics**: Track received, sent, and acknowledged appreciations
|
|
|
|
### Analytics
|
|
- Monthly statistics tracking
|
|
- Category breakdown analysis
|
|
- Hospital and department rankings
|
|
- Appreciation trends over time
|
|
|
|
## Models
|
|
|
|
### Appreciation
|
|
Main model for tracking appreciation messages.
|
|
|
|
Fields:
|
|
- `sender`: User who sent the appreciation
|
|
- `recipient`: Generic foreign key to User or Physician
|
|
- `category`: Optional category
|
|
- `message_en`: English message
|
|
- `message_ar`: Arabic message
|
|
- `visibility`: Private, Department, Hospital, or Public
|
|
- `is_anonymous`: Whether sender is anonymous
|
|
- `status`: Draft, Sent, Acknowledged
|
|
- `hospital`: Hospital association
|
|
- `department`: Department association
|
|
- `sent_at`: When appreciation was sent
|
|
- `acknowledged_at`: When appreciation was acknowledged
|
|
|
|
### AppreciationCategory
|
|
Categories for organizing appreciations.
|
|
|
|
Fields:
|
|
- `hospital`: Hospital association (null for system-wide)
|
|
- `code`: Unique code
|
|
- `name_en`: English name
|
|
- `name_ar`: Arabic name
|
|
- `icon`: Font Awesome icon
|
|
- `color`: Hex color code
|
|
- `order`: Display order
|
|
|
|
### AppreciationBadge
|
|
Badges that can be earned.
|
|
|
|
Fields:
|
|
- `hospital`: Hospital association (null for system-wide)
|
|
- `code`: Unique code
|
|
- `name_en`: English name
|
|
- `name_ar`: Arabic name
|
|
- `icon`: Font Awesome icon
|
|
- `color`: Hex color code
|
|
- `criteria_type`: Type of criteria (received_count, received_month, streak_weeks, diverse_senders)
|
|
- `criteria_value`: Value required to earn badge
|
|
|
|
### UserBadge
|
|
Tracking badges earned by recipients.
|
|
|
|
Fields:
|
|
- `recipient`: Generic foreign key to User or Physician
|
|
- `badge`: Badge earned
|
|
- `appreciation_count`: Count when badge was earned
|
|
- `earned_at`: When badge was earned
|
|
|
|
### AppreciationStats
|
|
Monthly statistics for recipients.
|
|
|
|
Fields:
|
|
- `recipient`: Generic foreign key to User or Physician
|
|
- `hospital`: Hospital association
|
|
- `department`: Department association
|
|
- `year`: Year
|
|
- `month`: Month
|
|
- `received_count`: Number of appreciations received
|
|
- `sent_count`: Number of appreciations sent
|
|
- `acknowledged_count`: Number of appreciations acknowledged
|
|
- `category_breakdown`: JSON breakdown by category
|
|
- `hospital_rank`: Rank within hospital
|
|
- `department_rank`: Rank within department
|
|
|
|
## API Endpoints
|
|
|
|
### Appreciations
|
|
- `GET /api/v1/appreciation/appreciations/` - List appreciations (filtered by user)
|
|
- `POST /api/v1/appreciation/appreciations/` - Create appreciation
|
|
- `GET /api/v1/appreciation/appreciations/{id}/` - Get appreciation detail
|
|
- `PATCH /api/v1/appreciation/appreciations/{id}/acknowledge/` - Acknowledge appreciation
|
|
- `GET /api/v1/appreciation/appreciations/my_appreciations/` - Get appreciations received by current user
|
|
- `GET /api/v1/appreciation/appreciations/sent_by_me/` - Get appreciations sent by current user
|
|
- `GET /api/v1/appreciation/appreciations/summary/` - Get summary statistics
|
|
|
|
### Categories
|
|
- `GET /api/v1/appreciation/categories/` - List categories
|
|
- `POST /api/v1/appreciation/categories/` - Create category (admin only)
|
|
- `GET /api/v1/appreciation/categories/{id}/` - Get category detail
|
|
- `PUT /api/v1/appreciation/categories/{id}/` - Update category (admin only)
|
|
- `DELETE /api/v1/appreciation/categories/{id}/` - Delete category (admin only)
|
|
|
|
### Badges
|
|
- `GET /api/v1/appreciation/badges/` - List badges
|
|
- `GET /api/v1/appreciation/user-badges/` - Get badges earned by current user
|
|
- `GET /api/v1/appreciation/user-badges/{id}/` - Get user badge detail
|
|
|
|
### Leaderboard
|
|
- `GET /api/v1/appreciation/leaderboard/` - Get hospital leaderboard
|
|
- `GET /api/v1/appreciation/leaderboard/?department_id={id}` - Get department leaderboard
|
|
|
|
### Statistics
|
|
- `GET /api/v1/appreciation/stats/` - Get statistics
|
|
- `GET /api/v1/appreciation/stats/{year}/{month}/` - Get statistics for specific month
|
|
- `GET /api/v1/appreciation/stats/trends/` - Get trends over time
|
|
|
|
## Setup
|
|
|
|
### 1. Add app to INSTALLED_APPS
|
|
|
|
```python
|
|
INSTALLED_APPS = [
|
|
# ... other apps
|
|
'apps.appreciation',
|
|
]
|
|
```
|
|
|
|
### 2. Run migrations
|
|
|
|
```bash
|
|
python manage.py makemigrations appreciation
|
|
python manage.py migrate appreciation
|
|
```
|
|
|
|
### 3. Seed initial data
|
|
|
|
```bash
|
|
python manage.py seed_appreciation_data
|
|
```
|
|
|
|
This will create default categories and badges.
|
|
|
|
### 4. Add URLs to main URL configuration
|
|
|
|
The URLs are automatically included through the app's URL configuration.
|
|
|
|
## Usage
|
|
|
|
### Sending an Appreciation
|
|
|
|
```python
|
|
from apps.appreciation.models import Appreciation, AppreciationCategory
|
|
from django.contrib.auth import get_user_model
|
|
|
|
User = get_user_model()
|
|
|
|
# Get users
|
|
sender = User.objects.get(username='sender')
|
|
recipient = User.objects.get(username='recipient')
|
|
category = AppreciationCategory.objects.get(code='excellent_care')
|
|
|
|
# Create appreciation
|
|
appreciation = Appreciation.objects.create(
|
|
sender=sender,
|
|
recipient_content_type=ContentType.objects.get_for_model(User),
|
|
recipient_object_id=recipient.id,
|
|
category=category,
|
|
message_en='Thank you for your excellent care!',
|
|
message_ar='شكراً لرعايتك المتميزة!',
|
|
visibility='public',
|
|
is_anonymous=False,
|
|
hospital=sender.hospital,
|
|
department=sender.department,
|
|
status=Appreciation.AppreciationStatus.SENT,
|
|
)
|
|
```
|
|
|
|
### Awarding Badges
|
|
|
|
Badges are automatically awarded when appreciations are sent. The signal handler checks badge criteria and awards badges when conditions are met.
|
|
|
|
```python
|
|
from apps.appreciation.signals import check_and_award_badges
|
|
|
|
# Manually check for badges (usually done automatically)
|
|
check_and_award_badges(appreciation)
|
|
```
|
|
|
|
### Viewing Leaderboard
|
|
|
|
```python
|
|
from apps.appreciation.views import LeaderboardView
|
|
|
|
# Get hospital leaderboard
|
|
view = LeaderboardView()
|
|
leaderboard = view.get_queryset()
|
|
for entry in leaderboard:
|
|
print(f"{entry.rank}: {entry.recipient_name} - {entry.received_count}")
|
|
```
|
|
|
|
## Customization
|
|
|
|
### Adding Custom Categories
|
|
|
|
```python
|
|
from apps.appreciation.models import AppreciationCategory
|
|
|
|
category = AppreciationCategory.objects.create(
|
|
hospital=hospital, # or None for system-wide
|
|
code='custom_category',
|
|
name_en='Custom Category',
|
|
name_ar='فئة مخصصة',
|
|
description_en='Description',
|
|
description_ar='الوصف',
|
|
icon='fa-star',
|
|
color='#FF5733',
|
|
order=10,
|
|
)
|
|
```
|
|
|
|
### Adding Custom Badges
|
|
|
|
```python
|
|
from apps.appreciation.models import AppreciationBadge
|
|
|
|
badge = AppreciationBadge.objects.create(
|
|
hospital=hospital, # or None for system-wide
|
|
code='custom_badge',
|
|
name_en='Custom Badge',
|
|
name_ar='شارة مخصصة',
|
|
icon='fa-medal',
|
|
color='#FFD700',
|
|
criteria_type='received_count',
|
|
criteria_value=100,
|
|
)
|
|
```
|
|
|
|
## UI Templates
|
|
|
|
The app includes a comprehensive UI template at `templates/appreciation/appreciation_list.html`.
|
|
|
|
Features:
|
|
- Dashboard with statistics cards
|
|
- Tabbed interface for different views
|
|
- Send appreciation modal
|
|
- Appreciation detail modal
|
|
- Leaderboard display
|
|
- Badge gallery
|
|
- Responsive design
|
|
|
|
Access the appreciation page at: `/appreciation/`
|
|
|
|
## Admin Interface
|
|
|
|
The app includes a comprehensive admin interface for managing:
|
|
- Appreciations
|
|
- Categories
|
|
- Badges
|
|
- User badges
|
|
- Statistics
|
|
|
|
All models are registered in `admin.py` with filters and search functionality.
|
|
|
|
## Signals
|
|
|
|
The app uses Django signals to handle:
|
|
|
|
1. **post_save** on Appreciation:
|
|
- Send notifications to recipients
|
|
- Update statistics
|
|
- Check and award badges
|
|
|
|
## Permissions
|
|
|
|
- **Create**: Any authenticated user can send appreciation
|
|
- **View**: Users can view their own appreciations
|
|
- **Admin**: Admin users can view all appreciations
|
|
- **Category Management**: Admin only
|
|
- **Badge Management**: Admin only
|
|
|
|
## Best Practices
|
|
|
|
1. **Use Categories**: Always select an appropriate category when sending appreciation
|
|
2. **Be Specific**: Write detailed messages explaining why the appreciation is being sent
|
|
3. **Respect Privacy**: Use appropriate visibility settings
|
|
4. **Regular Review**: Regularly check and acknowledge received appreciations
|
|
5. **Celebrate Achievements**: Use the leaderboard and badges to celebrate top performers
|
|
|
|
## Troubleshooting
|
|
|
|
### Notifications not sending
|
|
- Check that the notification system is configured
|
|
- Verify recipient email/phone numbers are correct
|
|
- Check logs for errors in signals.py
|
|
|
|
### Badges not awarding
|
|
- Run `python manage.py check_badges` to manually trigger badge checks
|
|
- Verify criteria are met
|
|
- Check that badges are active
|
|
|
|
### Statistics not updating
|
|
- Check that signals are connected
|
|
- Verify AppreciationStatus is set to SENT
|
|
- Manually trigger statistics recalculation if needed
|
|
|
|
## Support
|
|
|
|
For issues or questions, please refer to the main PX360 documentation or contact the development team.
|