HH/.opencode/plans/appreciation-review-workflow.md

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:

  {
    "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