HH/apps/observations/README.md

# Observations App

Staff observation reporting module for Al Hammadi Hospital.

## Overview

This app allows any staff member at Al Hammadi to report issues they notice. Reporting can be anonymous (no login required), but the user may optionally provide Staff ID and Name.

PX360 staff will triage the observation and route it to the responsible department and/or create an action in the PX Action Center.

## Features

- **Anonymous Reporting**: No login required for submission
- **Optional Identification**: Staff can optionally provide their ID and name
- **Tracking System**: Unique tracking codes for public status lookup
- **Full Lifecycle Management**: Status tracking from NEW to CLOSED
- **Department Routing**: Assign observations to responsible departments
- **Action Center Integration**: Convert observations to PX Actions
- **Notification System**: Automated notifications for triage team and assignees
- **Bilingual Support**: English and Arabic category names

## Routes

### Public Routes (No Login Required)

| Route | Method | Description |
|-------|--------|-------------|
| `/observations/new/` | GET/POST | Submit new observation |
| `/observations/submitted/<tracking_code>/` | GET | Success page with tracking code |
| `/observations/track/` | GET | Track observation by code |

### Internal Routes (Login Required)

| Route | Method | Description |
|-------|--------|-------------|
| `/observations/` | GET | List all observations with filters |
| `/observations/<id>/` | GET | Observation detail with timeline |
| `/observations/<id>/triage/` | POST | Triage observation |
| `/observations/<id>/status/` | POST | Change observation status |
| `/observations/<id>/note/` | POST | Add internal note |
| `/observations/<id>/convert-to-action/` | GET/POST | Convert to PX Action |

### Category Management (Permission Required)

| Route | Method | Description |
|-------|--------|-------------|
| `/observations/categories/` | GET | List categories |
| `/observations/categories/create/` | GET/POST | Create category |
| `/observations/categories/<id>/edit/` | GET/POST | Edit category |
| `/observations/categories/<id>/delete/` | POST | Delete category |

## Permissions

| Permission | Description |
|------------|-------------|
| `observations.view_observation` | Can view observations |
| `observations.triage_observation` | Can triage observations |
| `observations.manage_categories` | Can manage observation categories |

## Models

### ObservationCategory
- `name_en`, `name_ar`: Bilingual names
- `description`: Category description
- `icon`: Bootstrap icon class
- `sort_order`: Display order
- `is_active`: Active status

### Observation
- `tracking_code`: Unique code (e.g., OBS-ABC123)
- `category`: FK to ObservationCategory
- `title`: Optional short title
- `description`: Required detailed description
- `severity`: LOW, MEDIUM, HIGH, CRITICAL
- `location_text`: Where the issue was observed
- `incident_datetime`: When the issue occurred
- `reporter_staff_id`, `reporter_name`, `reporter_phone`, `reporter_email`: Optional reporter info
- `status`: NEW, TRIAGED, ASSIGNED, IN_PROGRESS, RESOLVED, CLOSED, REJECTED, DUPLICATE
- `assigned_department`: FK to Department
- `assigned_to`: FK to User
- `action_id`: Link to PX Action if converted

### ObservationAttachment
- `observation`: FK to Observation
- `file`: Uploaded file
- `filename`, `file_type`, `file_size`: File metadata

### ObservationNote
- `observation`: FK to Observation
- `note`: Note text
- `created_by`: FK to User
- `is_internal`: Internal-only flag

### ObservationStatusLog
- `observation`: FK to Observation
- `from_status`, `to_status`: Status transition
- `changed_by`: FK to User
- `comment`: Optional comment

## Workflow

1. **Submission**: Staff submits observation via public form (anonymous or identified)
2. **Notification**: PX360 triage team receives notification
3. **Triage**: Staff triages observation, assigns department/owner
4. **Assignment**: Assigned user receives notification
5. **Resolution**: Issue is resolved and closed
6. **Action Center**: Optionally convert to PX Action for formal tracking

## Installation

1. Add to `INSTALLED_APPS` in settings:
```python
LOCAL_APPS = [
    ...
    'apps.observations',
]
```

2. Add URL configuration:
```python
urlpatterns = [
    ...
    path('observations/', include('apps.observations.urls')),
]
```

3. Run migrations:
```bash
python manage.py makemigrations observations
python manage.py migrate
```

4. Seed default categories:
```bash
python manage.py seed_observation_categories
```

## Management Commands

### seed_observation_categories
Seeds default observation categories with bilingual names.

```bash
# Seed categories (update existing)
python manage.py seed_observation_categories

# Clear and reseed
python manage.py seed_observation_categories --clear
```

## Testing

Run tests:
```bash
python manage.py test apps.observations
```

## Integration

### Action Center
Observations can be converted to PX Actions via the "Convert to Action" feature. This creates a linked action with:
- Title derived from observation
- Description with observation details
- Priority mapped from severity
- Link back to original observation

### Notifications
The app integrates with `apps.notifications` to send:
- New observation alerts to PX Admin group
- Assignment notifications to assigned users
- Resolution notifications to stakeholders

## Templates

Templates are located in `templates/observations/`:
- `public_new.html`: Public submission form
- `public_success.html`: Success page with tracking code
- `public_track.html`: Public tracking page
- `observation_list.html`: Internal list view
- `observation_detail.html`: Internal detail view
- `convert_to_action.html`: Convert to action form
- `category_list.html`: Category management list
- `category_form.html`: Category create/edit form

## API Endpoints

### AJAX Helper
- `GET /observations/api/users-by-department/?department_id=<id>`: Get users for a department

## Security

- Public forms include honeypot field for spam protection
- Internal views require authentication
- Category management requires specific permission
- RBAC filtering based on user's hospital/department