# Plan: Appreciation Review & Activation Workflow

## Current State

The appreciation system already exists with:
- **Models**: `Appreciation`, `AppreciationCategory`, `AppreciationBadge`, `AppreciationStats`
- **Public submission**: `/appreciation/public/submit/` — creates with `status=SENT` immediately
- **Email notifications**: Goes to the recipient (staff member) via signals
- **Department model**: Has `manager` (User FK) and `respondent` (Staff FK)
- **Staff model**: Has `is_head` boolean flag

## Problem

Current workflow immediately sends public appreciations to recipients without staff review. The user wants:
1. Appreciations saved as **pending** for staff review
2. Staff selects the actual staff member and assigns to department
3. Staff "activates" the appreciation
4. **Department head** receives email notification upon activation

## Solution

### 1. Modify Public Submission (DRAFT instead of SENT)

**File**: `apps/appreciation/ui_views.py` — `public_appreciation_submit`

**Changes**:
- Create appreciation with `status=DRAFT` instead of `SENT`
- Remove `appreciation.send()` call
- Store raw submitted data in `metadata` JSON field:
  ```json
  {
    "submitted_by_name": "...",
    "submitted_by_phone": "...",
    "submitted_by_email": "...",
    "staff_name_mentioned": "...",
    "source": "public_form"
  }
  ```
- Keep `message_en` clean (just the message, not the formatted metadata string)

### 2. Add Review List Page

**New file**: `templates/appreciation/review_list.html`
**Modified file**: `apps/appreciation/ui_views.py` — add `appreciation_review_list` view

**Features**:
- Table of appreciations with `status=DRAFT`
- Columns: Reference, Hospital, Category, Message, Submitted Date, Actions
- "Review" button links to detail page
- "Activate" button (shortcut to activate without detail page)
- Filters: Hospital, Category, Date range
- Pagination

**Permissions**: PX Staff, Hospital Admin, PX Admin

### 3. Add Review Detail Page

**New file**: `templates/appreciation/review_detail.html`
**Modified file**: `apps/appreciation/ui_views.py` — add `appreciation_review` view

**Features**:
- Display appreciation details (message, submitted info from metadata)
- **Staff selection**: Dropdown of staff members (TomSelect)
  - Filtered by hospital
  - Searchable by name, staff ID
- **Department**: Auto-populated from selected staff's department
  - Or manual override dropdown
- **Category**: Dropdown (can change from default)
- "Activate & Send" button
  - Sets `status=SENT`
  - Sets `recipient` to selected Staff
  - Sets `department` to staff's department
  - Triggers notification signal
- "Save as Draft" button (keep as DRAFT, update fields)

### 4. Update Email Notification to Department Head

**File**: `apps/appreciation/signals.py` — `send_appreciation_notification`

**Changes**:
- **Current**: Sends to `appreciation.recipient` (staff member)
- **New**: Also send to department head
  - Department head = `appreciation.department.manager` (User)
  - OR Staff in department with `is_head=True` → then get their user
- Send separate email to department head with subject: "New Appreciation for [Staff Name] in [Department]"
- Keep existing recipient email unchanged

### 5. Update Sidebar Navigation

**File**: `templates/layouts/partials/sidebar.html`

**Changes**:
- Add "Review Appreciations" link under Appreciations section
- Only visible to staff with review permissions (PX Staff, Admin roles)
- Show badge count of pending (DRAFT) appreciations

### 6. Update Appreciation List View

**File**: `apps/appreciation/ui_views.py` — existing list view

**Changes**:
- Add filter for `status` (DRAFT, SENT, ACKNOWLEDGED)
- Show DRAFT appreciations only to reviewers
- Show status badge (color-coded)

### 7. URL Routes

**File**: `apps/appreciation/urls.py`

**New routes**:
- `/appreciation/review/` — Review list
- `/appreciation/review/<uuid:pk>/` — Review detail
- `/appreciation/review/<uuid:pk>/activate/` — Activate action (POST)

### 8. Permissions

- **Public**: Can submit appreciations (no login)
- **Reviewers** (PX Staff, Hospital Admin, PX Admin): Can review and activate
- **Department Heads**: Receive email notifications on activation
- **Recipients** (Staff): View their appreciations after activation

## Database Changes

**No schema changes needed**. The existing `status` field already has `DRAFT` choice. Just need to:
- Use `metadata` JSON field to store submission data
- Use existing `recipient` generic FK to link to Staff

## Files to Modify

1. `apps/appreciation/ui_views.py` — Modify public submit, add review views
2. `apps/appreciation/signals.py` — Update notification to include department head
3. `apps/appreciation/urls.py` — Add review routes
4. `templates/layouts/partials/sidebar.html` — Add review navigation
5. `templates/core/public_submit.html` — Update appreciation form (if needed)

## New Files to Create

1. `templates/appreciation/review_list.html` — Review list page
2. `templates/appreciation/review_detail.html` — Review detail page
3. `templates/appreciation/emails/department_head_notification.html` — Email template for dept head
4. `templates/appreciation/emails/department_head_notification.txt` — Plain text version

## Expected User Flow

1. **Patient** visits public page → selects "Appreciation" → fills form (name, phone, message, staff name mentioned) → submits
2. **System** saves appreciation as DRAFT with metadata
3. **PX Staff** logs in → sees "Review Appreciations" in sidebar with badge count → clicks
4. **Staff** views list of draft appreciations → clicks "Review" on one
5. **Staff** sees form with:
   - Patient info (from metadata)
   - Staff selector (searchable dropdown)
   - Department (auto-filled)
   - Category selector
6. **Staff** selects staff member → clicks "Activate & Send"
7. **System**:
   - Sets status to SENT
   - Links recipient to selected Staff
   - Sets department from staff
   - Triggers signal
8. **Signal handler** sends emails:
   - To recipient (staff member) — existing
   - To department head — NEW
9. **Department Head** receives email: "New appreciation for [Staff] in [Department]"
10. **Staff** (recipient) receives email: "You've received an appreciation!"

## Email Recipients

When appreciation is activated, send to:
1. **Recipient** (staff member who received appreciation) — existing behavior
2. **Department Head** — NEW:
   - Primary: `department.manager` (User) if exists and has email
   - Fallback: Staff in department with `is_head=True` → get their user → send to user.email
   - If no department head found, skip (don't fail)

## User Clarifications

1. **Hospital selection**: Patient selects from dropdown (keep current)
2. **Staff mention**: Patient mentions staff name as free text (keep current)
3. **Department head**: BOTH `department.manager` (User) AND Staff with `is_head=True` → get user → send to user.email
4. **Tracking code**: Not needed
5. **Department head UI access**: Not specified — will only send emails for now