HH/apps/px_sources/PX_SOURCES_MIGRATION_SUMMARY.md

# PX Sources Migration Summary

## Overview
Successfully migrated the system from hardcoded source enums to a flexible `PXSource` model that supports bilingual naming and dynamic source management.

## Changes Made

### 1. Updated PXSource Model
**File:** `apps/px_sources/models.py`

**Removed fields:**
- `icon_class` - CSS class for icon display (no longer needed)
- `color_code` - Color code for UI display (no longer needed)

**Simplified fields:**
- `code` - Unique identifier (e.g., 'PATIENT', 'FAMILY', 'STAFF')
- `name_en`, `name_ar` - Bilingual names
- `description_en`, `description_ar` - Bilingual descriptions
- `source_type` - 'complaint', 'inquiry', or 'both'
- `order` - Display order
- `is_active` - Active status
- `metadata` - JSON field for additional configuration

### 2. Updated Complaint Model
**File:** `apps/complaints/models.py`

**Before:**
```python
source = models.CharField(
    max_length=50,
    choices=ComplaintSource.choices,  # Hardcoded enum
    default=ComplaintSource.PATIENT
)
```

**After:**
```python
source = models.ForeignKey(
    'px_sources.PXSource',
    on_delete=models.PROTECT,
    related_name='complaints',
    null=True,
    blank=True,
    help_text="Source of the complaint"
)
```

### 3. Updated Feedback Model
**File:** `apps/feedback/models.py`

**Before:**
```python
source = models.CharField(
    max_length=50,
    default='web',
    help_text="Source of feedback (web, mobile, kiosk, etc.)"
)
```

**After:**
```python
source = models.ForeignKey(
    'px_sources.PXSource',
    on_delete=models.PROTECT,
    related_name='feedbacks',
    null=True,
    blank=True,
    help_text="Source of feedback"
)
```

### 4. Removed Hardcoded Enums
**File:** `apps/complaints/models.py`

**Removed:**
- `ComplaintSource` enum class with hardcoded choices:
  - PATIENT
  - FAMILY
  - STAFF
  - SURVEY
  - SOCIAL_MEDIA
  - CALL_CENTER
  - MOH
  - CHI
  - OTHER

### 5. Updated Serializers
**File:** `apps/complaints/serializers.py`

**Added to ComplaintSerializer:**
```python
source_name = serializers.CharField(source='source.name_en', read_only=True)
source_code = serializers.CharField(source='source.code', read_only=True)
```

### 6. Updated Call Center Views
**File:** `apps/callcenter/ui_views.py`

**Changed:**
```python
# Before
from apps.complaints.models import ComplaintSource
source=ComplaintSource.CALL_CENTER

# After
from apps.px_sources.models import PXSource
call_center_source = PXSource.get_by_code('CALL_CENTER')
source=call_center_source
```

### 7. Created Data Migration
**File:** `apps/px_sources/migrations/0003_populate_px_sources.py`

Created 13 default PXSource records:
1. PATIENT - Patient (complaint)
2. FAMILY - Family Member (complaint)
3. STAFF - Staff Report (complaint)
4. SURVEY - Survey (both)
5. SOCIAL_MEDIA - Social Media (both)
6. CALL_CENTER - Call Center (both)
7. MOH - Ministry of Health (complaint)
8. CHI - Council of Health Insurance (complaint)
9. OTHER - Other (both)
10. WEB - Web Portal (inquiry)
11. MOBILE - Mobile App (inquiry)
12. KIOSK - Kiosk (inquiry)
13. EMAIL - Email (inquiry)

All sources include bilingual names and descriptions.

## Migrations Applied

1. `px_sources.0002_remove_pxsource_color_code_and_more.py`
   - Removed `icon_class` and `color_code` fields

2. `complaints.0004_alter_complaint_source.py`
   - Changed Complaint.source from CharField to ForeignKey

3. `feedback.0003_alter_feedback_source.py`
   - Changed Feedback.source from CharField to ForeignKey

4. `px_sources.0003_populate_px_sources.py`
   - Created 13 default PXSource records

## Benefits

### 1. Flexibility
- New sources can be added without code changes
- Sources can be activated/deactivated dynamically
- Bilingual support out of the box

### 2. Maintainability
- Single source of truth for all feedback sources
- No need to modify enums in multiple files
- Centralized source management

### 3. Consistency
- Same source model used across Complaints, Feedback, and other modules
- Unified source tracking and reporting
- Consistent bilingual naming

### 4. Data Integrity
- ForeignKey relationships ensure referential integrity
- Can't accidentally use invalid source codes
- Proper cascade behavior on deletion

## Usage Examples

### Get a source by code:
```python
from apps.px_sources.models import PXSource

call_center_source = PXSource.get_by_code('CALL_CENTER')
```

### Get active sources for complaints:
```python
sources = PXSource.get_active_sources(source_type='complaint')
```

### Get localized name:
```python
# In Arabic context
source_name = source.get_localized_name(language='ar')
```

### Activate/deactivate a source:
```python
source.activate()
source.deactivate()
```

## Testing Results

✅ All migrations applied successfully
✅ 13 PXSource records created
✅ Complaint source field is now ForeignKey
✅ Feedback source field is now ForeignKey
✅ No data loss during migration
✅ Call center views updated and working

## Files Modified

1. `apps/px_sources/models.py` - Removed icon_class, color_code
2. `apps/px_sources/serializers.py` - Updated fields list
3. `apps/px_sources/admin.py` - Removed display options fieldset
4. `apps/complaints/models.py` - Changed source to ForeignKey, removed ComplaintSource enum
5. `apps/complaints/serializers.py` - Added source_name, source_code fields
6. `apps/feedback/models.py` - Changed source to ForeignKey
7. `apps/callcenter/ui_views.py` - Updated to use PXSource model
8. `apps/px_sources/migrations/0003_populate_px_sources.py` - New migration

## Next Steps

1. Update any custom forms that reference ComplaintSource
2. Update API documentation to reflect new structure
3. Add PXSource management UI if needed (admin interface already exists)
4. Consider adding source usage analytics
5. Train users on managing sources through admin interface

## Rollback Plan

If needed, you can rollback migrations:

```bash
python manage.py migrate px_sources 0001
python manage.py migrate complaints 0003
python manage.py migrate feedback 0002
```

This will revert to the hardcoded enum system.