182 lines
6.9 KiB
Markdown
182 lines
6.9 KiB
Markdown
# 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
|