# Patient Experience — Module Workflows

Documentation of the **current implementation** workflow, lifecycle, and business process for each Patient Experience module. Each file follows the same 14-section structure (Purpose → How a Case Starts → Complete Lifecycle → Status Definitions → Workflow Actions → Decision Points → Assignment Flow → Investigation Process → Communication Flow → Escalation Flow → Resolution Process → Closure Process → Exception Flows → End-to-End Example), plus a dedicated **Department-Response Sub-Flow** section where applicable.

> This is **not** a redesign. Every claim is cited as `file:line`. Where code disagrees with `docs/workflows.md` (or `README.md`), the code wins and the gap is flagged.

## Modules

| Module | Document | App location | Lifecycle shape |
|---|---|---|---|
| Complaints | [complaints.md](./complaints.md) | `apps/complaints/` (`Complaint`) | `open → in_progress → partially_resolved → resolved → closed` (+ cancelled, pending_external, ovr_pending) — richest: multi-dept + manager review + investigation |
| Inquiries | [inquiries.md](./inquiries.md) | `apps/complaints/` (`Inquiry`) | `open → in_progress → resolved → closed` — single dept, one-level review, resolve requires PX response |
| Suggestions | [suggestions.md](./suggestions.md) | `apps/feedback/` (`Feedback` w/ `FeedbackType.SUGGESTION`) | `submitted → reviewed → acknowledged → closed` (+ reopened) — centrally owned by PX; no dept response |
| Observations | [observations.md](./observations.md) | `apps/observations/` (`Observation`) | `open → in_progress → resolved → closed` — single dept, staff safety/quality reporting |
| Appreciations | [appreciations.md](./appreciations.md) | `apps/appreciation/` (`Appreciation`) | `draft → activated → ai_analyzed → sent → acknowledged` — **outbound** recognition, not case management |

## Cross-module notes

- The **department-response sub-flow** (send → receive → respond → review → accept/reject) exists in Complaints, Inquiries, and Observations. Complaints is the only one with a **manager-review tier**; the others are single-level. **Suggestions and Appreciations do not use it** (suggestions notify departments for awareness only; appreciations deliver recognition outbound).
- A shared architectural reference for the three department-response modules is [`docs/workflows.md`](../workflows.md). However, several statements there are now **stale** (see each module's appendix) — most notably the Inquiry and Observation "PX accepts/rejects" loop, whose backing fields were removed (`migrations/0039` for Inquiry, `0020` for Observation).
- Each module has an **activation gate**: an item cannot be worked on or sent to a department until it leaves its initial state (open → in_progress for cases; draft → activated for appreciations).

## Key implementation findings (flagged in each module)

- **Complaints**: No model-level `clean()`/`CheckConstraint` enforcement despite `docs/workflows.md` claiming so; transition map lives only in `ComplaintService.VALID_STATUS_TRANSITIONS` (PX Admin bypasses). Manager-review tier lives in `apps/organizations/ui_views.py:4101`, not `apps/complaints/`. Reopen creates a **new** complaint.
- **Inquiries**: No `clean()`/`CheckConstraint` at all; arbitrary status strings persistable via change-status. `dept_response_acceptance_status` removed (`0039`) — the PX accept/reject loop no longer exists. Bug in `inquiry_send_to_staff` (calls nonexistent method). Auto dept-response escalation disabled.
- **Suggestions**: Transitions enforced **only** in the change-status view (not DB/model/admin). **No outbound communication to the suggester** by design — inbound-only. Reopen unreachable via staff UI after close. `FeedbackForm` unused for creation.
- **Observations**: `dept_response_acceptance_status` removed (`0020`) — PX accept/reject no longer implemented. `observation_send_to` has an `AttributeError` (reads nonexistent `reference_number`). Test suite stale. Auto escalation disabled. `observation_respond` bypasses the transition validator and status log.
- **Appreciations**: `VALID_APPRECIATION_TRANSITIONS` is dead code (never referenced); enforcement is per-method `ValueError` only. REST `create` and complaint conversion call `send()` on a DRAFT → `ValueError` (likely bug); the UI activation-gate flow is the working path. AI_ANALYZED is content enrichment, not sentiment.

## Permission roles (shared)

User-role predicates all delegate to `User.has_role(group_name)` (`apps/accounts/models.py:141`):

| Predicate | Group |
|---|---|
| `is_px_admin()` | "PX Admin" |
| `is_hospital_admin()` | "Hospital Admin" |
| `is_department_manager()` | "Department Manager" |
| `is_px_management()` | "PX Management" |
| `is_px_employee()` | "PX Employee" |
| `is_champion()` / `is_department_respondent()` | via `staff_profile.champion_departments` |

A **department champion** is the primary department respondent in the send-to-department flows; resolved via `get_champion_and_manager(department)` (`apps/organizations/department_contacts.py`).