HH/docs/workflows/index.md

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	apps/complaints/ (Complaint)	open → in_progress → partially_resolved → resolved → closed (+ cancelled, pending_external, ovr_pending) — richest: multi-dept + manager review + investigation
Inquiries	inquiries.md	apps/complaints/ (Inquiry)	open → in_progress → resolved → closed — single dept, one-level review, resolve requires PX response
Suggestions	suggestions.md	apps/feedback/ (Feedback w/ FeedbackType.SUGGESTION)	submitted → reviewed → acknowledged → closed (+ reopened) — centrally owned by PX; no dept response
Observations	observations.md	apps/observations/ (Observation)	open → in_progress → resolved → closed — single dept, staff safety/quality reporting
Appreciations	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. 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).