HH/apps/appreciation

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

INSTALLED_APPS = [
    # ... other apps
    'apps.appreciation',
]

2. Run migrations

python manage.py makemigrations appreciation
python manage.py migrate appreciation

3. Seed initial data

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

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.

from apps.appreciation.signals import check_and_award_badges

# Manually check for badges (usually done automatically)
check_and_award_badges(appreciation)

Viewing Leaderboard

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

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

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.