marwan/HH
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update and nug fixes

Browse Source
This commit is contained in:
ismail 2026-07-11 19:24:28 +03:00
parent d63ed6f956
commit 6baa34dec3
127 changed files with 11986 additions and 5999 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.env.example
View File

@ -2,6 +2,7 @@
DEBUG=True
SECRET_KEY=your-secret-key-here-change-in-production
ALLOWED_HOSTS=localhost,127.0.0.1
SITE_URL=http://localhost:8000
# Database
DATABASE_URL=postgresql://px360:px360@db:5432/px360

1
.env.production.example
View File

@ -11,6 +11,7 @@ DJANGO_SETTINGS_MODULE=config.settings.prod
DEBUG=False
SECRET_KEY=CHANGE-ME-generate-with-python3-c-from-django.core.management.utils-import-get_random_secret_key-print-get_random_secret_key
ALLOWED_HOSTS=your-production-domain.com
SITE_URL=https://your-production-domain.com
ADMIN_URL=CHANGE-ME-use-a-non-obvious-url/
# --- PostgreSQL (External Server) ---

1
.env.staging.example
View File

@ -10,6 +10,7 @@ DJANGO_SETTINGS_MODULE=config.settings.prod
DEBUG=False
SECRET_KEY=CHANGE-ME-generate-with-python3-c-from-django.core.management.utils-import-get_random_secret_key-print-get_random_secret_key
ALLOWED_HOSTS=px360test.tenhal.sa
SITE_URL=https://px360test.tenhal.sa
ADMIN_URL=admin/
# --- PostgreSQL ---

1
.target-last-build Normal file
View File

@ -0,0 +1 @@
hh-dev:hh-dev-build-1783592335|1783592388

23
Dockerfile
View File

@ -12,6 +12,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
python3-dev \
musl-dev \
libpq-dev \
nodejs \
npm \
&& rm -rf /var/lib/apt/lists/*
COPY pyproject.toml ./
@ -19,14 +21,13 @@ COPY pyproject.toml ./
RUN pip install --upgrade pip setuptools wheel && \
pip install -e "."
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN apt-get update && apt-get install -y --no-install-recommends \
nodejs \
npm \
&& rm -rf /var/lib/apt/lists/*
RUN npm install && npm run build:css
RUN npm run build:css
RUN python manage.py collectstatic --noinput || true
@ -43,6 +44,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
libpq5 \
postgresql-client \
curl \
libpango-1.0-0 \
libpangoft2-1.0-0 \
libglib2.0-0 \
&& rm -rf /var/lib/apt/lists/*
ARG UID=1000
@ -51,14 +55,17 @@ RUN groupadd -g ${UID} -r appuser && useradd -u ${UID} -r -g appuser -m appuser
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
COPY --from=builder /app /app
# App source WITHOUT node_modules (.dockerignore excludes it), + builder's built artifacts.
COPY . /app
COPY --from=builder /app/static/dist /app/static/dist
COPY --from=builder /app/staticfiles /app/staticfiles
RUN pip uninstall -y pip setuptools wheel && \
rm -rf /usr/local/lib/python3.12/site-packages/pip* \
/usr/local/lib/python3.12/site-packages/setuptools* \
/usr/local/lib/python3.12/site-packages/wheel*
COPY entrypoint.prod.sh /app/entrypoint.prod.sh
RUN chmod +x /app/entrypoint.prod.sh && \
mkdir -p logs media staticfiles && \
chown -R appuser:appuser /app

5
apps/analytics/kpi_pdf_service.py
View File

@ -161,7 +161,7 @@ def _get_logo_base64():
from django.conf import settings
from PIL import Image as PILImage
logo_path = settings.BASE_DIR / "static" / "img" / "hh-logo.png"
logo_path = settings.BASE_DIR / "static" / "img" / "HH_P_ICON.png"
logo_img = PILImage.open(logo_path)
logo_img.thumbnail((500, 500), PILImage.LANCZOS)
buf = io.BytesIO()
@ -217,4 +217,5 @@ def generate_kpi_report_pdf(report):
}
html_string = render_to_string("analytics/kpi_report_weasyprint.html", context)
return HTML(string=html_string).write_pdf()
from django.conf import settings
return HTML(string=html_string, base_url=str(settings.BASE_DIR / "static")).write_pdf()

40
apps/appreciation/forms.py Normal file
View File

@ -0,0 +1,40 @@
"""Forms for the appreciation module."""
from django import forms
from apps.appreciation.models import Appreciation
from apps.organizations.models import Department
class AppreciationForm(forms.ModelForm):
"""Internal form for creating an appreciation (department-targeted)."""
class Meta:
model = Appreciation
fields = ["hospital", "department", "message_en"]
widgets = {
"hospital": forms.Select(
attrs={"class": "w-full px-4 py-3 border border-slate-200 rounded-xl text-sm focus:ring-2 focus:ring-navy/20 outline-none"}
),
"message_en": forms.Textarea(
attrs={
"rows": 5,
"class": "w-full px-4 py-3 border border-slate-200 rounded-xl text-sm focus:ring-2 focus:ring-navy/20 outline-none",
"placeholder": "Write your message of appreciation...",
}
),
"department": forms.Select(
attrs={"class": "w-full px-4 py-3 border border-slate-200 rounded-xl text-sm focus:ring-2 focus:ring-navy/20 outline-none"}
),
}
def __init__(self, *args, hospital=None, **kwargs):
super().__init__(*args, **kwargs)
if hospital:
self.fields["hospital"].initial = hospital
dept_qs = Department.objects.filter(status="active").select_related("hospital").order_by(
"hospital__name", "name"
)
self.fields["department"].queryset = dept_qs
self.fields["department"].label_from_instance = lambda obj: (
f"{obj.name} — {obj.hospital.name}" if obj.hospital else obj.name
)

130
apps/appreciation/tasks.py Normal file
View File

@ -0,0 +1,130 @@
"""Celery tasks for the appreciation module."""
import logging
from celery import shared_task
logger = logging.getLogger(__name__)
@shared_task
def send_appreciation_notifications(
appreciation_id,
staff_id=None,
note="",
email_subject="",
email_body="",
host="",
):
"""Send email + SMS to champion, manager, and appreciated staff in the background.
Replaces the synchronous notification loop that used to block the
appreciation_send_to response.
"""
from apps.appreciation.models import Appreciation
from apps.notifications.services import NotificationService, get_email_header_html
from apps.organizations.department_contacts import get_champion_and_manager, _staff_contact
from apps.organizations.models import Staff
try:
appreciation = Appreciation.objects.select_related("department", "hospital").get(pk=appreciation_id)
except Appreciation.DoesNotExist:
logger.error(f"Appreciation {appreciation_id} not found for notification task")
return
department = appreciation.department
if not department:
logger.warning(f"Appreciation {appreciation_id} has no department, skipping notifications")
return
targets = get_champion_and_manager(department)
link = f"https://{host}/appreciation/detail/{appreciation.pk}/"
notified = []
# Notify champion + manager
for target in targets:
display_name = (
target["staff"].get_full_name() if target.get("staff")
else (target["user"].get_full_name() if target.get("user") else target["label"])
)
if target.get("email"):
try:
send_subject = email_subject or f"Appreciation Sent to Department - {appreciation.reference_number}"
send_body = email_body or (
f"Appreciation #{appreciation.reference_number} has been sent to your department ({department.name})."
)
NotificationService.send_email(
email=target["email"],
subject=send_subject,
message=send_body + f"\n\n{link}",
html_message=f"""
<div style="font-family: 'Segoe UI', Tahoma, sans-serif; max-width: 600px; margin: 0 auto; border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
{get_email_header_html()}
<div style="padding: 20px;">
<h2 style="color: #005696; font-size: 18px; margin: 0 0 12px 0;">Appreciation Sent to Department</h2>
<p>Appreciation <strong>#{appreciation.reference_number}</strong> has been sent to your department <strong>({department.name})</strong>.</p>
<p><strong>Message:</strong> {appreciation.message_en or 'N/A'}</p>
{f'<p><strong>Note:</strong> {note}</p>' if note else ''}
<p><strong>Role:</strong> {target['label']}</p>
<p><a href="{link}">View Appreciation</a></p>
</div>
</div>
""",
related_object=appreciation,
)
except Exception:
logger.exception(f"Failed to send email to {target.get('email')}")
if target.get("phone"):
try:
NotificationService.send_sms(
target["phone"],
f"PX360: Appreciation #{appreciation.reference_number} sent to {department.name}. {link}",
related_object=appreciation,
)
except Exception:
pass
notified.append(f"{display_name} ({target['label']})")
# Notify the appreciated staff member
if staff_id:
try:
appreciated_staff = Staff.objects.get(id=staff_id)
except Staff.DoesNotExist:
appreciated_staff = None
if appreciated_staff:
s_email, s_phone = _staff_contact(appreciated_staff)
s_name = appreciated_staff.get_full_name()
if s_email:
try:
NotificationService.send_email(
email=s_email,
subject=f"An Appreciation Has Been Submitted About You - {appreciation.reference_number}",
message=f"An appreciation (#{appreciation.reference_number}) has been submitted about you.\n\nMessage: {appreciation.message_en or 'N/A'}\n\nView: {link}",
html_message=f"""
<div style="font-family: 'Segoe UI', Tahoma, sans-serif; max-width: 600px; margin: 0 auto; border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
{get_email_header_html()}
<div style="padding: 20px;">
<h2 style="color: #005696; font-size: 18px; margin: 0 0 12px 0;">You've Been Appreciated!</h2>
<p>An appreciation <strong>#{appreciation.reference_number}</strong> has been submitted about you.</p>
<p><strong>Message:</strong> {appreciation.message_en or 'N/A'}</p>
{f'<p><strong>Note:</strong> {note}</p>' if note else ''}
<p><a href="{link}">View Appreciation</a></p>
</div>
</div>
""",
related_object=appreciation,
)
notified.append(f"{s_name} (Staff)")
except Exception:
logger.exception(f"Failed to send email to staff {s_email}")
if s_phone:
try:
NotificationService.send_sms(
s_phone,
f"PX360: An appreciation has been submitted about you. {link}",
related_object=appreciation,
)
except Exception:
pass
logger.info(f"Appreciation {appreciation_id} notifications sent to: {', '.join(notified)}")

96
apps/appreciation/tests_workflow_fixes.py Normal file
View File

@ -0,0 +1,96 @@
"""
Tests for the appreciation send-flow fix (Fix 1.1):
- The REST API create path no longer crashes (it used to call send() on DRAFT).
- activate() + send() from DRAFT lands at SENT.
- The activation gate is still intact: send() alone from DRAFT raises ValueError.
"""
from unittest.mock import patch
from django.contrib.auth.models import Group
from django.contrib.contenttypes.models import ContentType
from django.test import TestCase
from rest_framework.test import APIClient
from apps.accounts.models import User
from apps.appreciation.models import Appreciation, AppreciationStatus
from apps.organizations.models import Hospital
class AppreciationModelSendFlowTests(TestCase):
"""Model-level proof that the activate-then-send pattern works from DRAFT."""
def setUp(self):
self.hospital = Hospital.objects.create(name="Apr Test Hospital", code="APR", status="active")
self.user = User.objects.create_user(email="sender@example.com", password="pass12345")
def _make_draft(self):
return Appreciation.objects.create(
hospital=self.hospital,
sender=self.user,
recipient_content_type=ContentType.objects.get_for_model(User),
recipient_object_id=self.user.id,
message_en="Great work!",
)
def test_send_alone_from_draft_still_raises(self):
"""The activation gate is intact: bare send() from DRAFT is rejected."""
ap = self._make_draft()
self.assertEqual(ap.status, AppreciationStatus.DRAFT.value)
with self.assertRaises(ValueError):
ap.send()
@patch("apps.notifications.services.send_email")
@patch("apps.notifications.services.send_sms")
def test_activate_then_send_lands_at_sent(self, mock_sms, mock_email):
"""Fix 1.1 pattern: activate() -> send() moves DRAFT to SENT cleanly."""
ap = self._make_draft()
ap.activate(activated_by=self.user)
self.assertEqual(ap.status, AppreciationStatus.ACTIVATED.value)
self.assertIsNotNone(ap.activated_at)
ap.send()
self.assertEqual(ap.status, AppreciationStatus.SENT.value)
self.assertIsNotNone(ap.sent_at)
class AppreciationAPICreateTests(TestCase):
"""Fix 1.1 — the REST API create path (which calls send on a fresh DRAFT)."""
def setUp(self):
self.hospital = Hospital.objects.create(name="API Hospital", code="AP2", status="active")
px_group = Group.objects.create(name="PX Admin")
self.user = User.objects.create_user(email="api@example.com", password="pass12345")
self.user.groups.add(px_group)
self.recipient = User.objects.create_user(
email="nurse@example.com", password="pass12345", hospital=self.hospital
)
self.client = APIClient()
self.client.force_authenticate(user=self.user)
# Don't re-raise view exceptions: the response serializer has a
# pre-existing GFK serialization bug (unrelated to this fix) that
# raises TypeError during rendering. We assert on DB state instead.
self.client.raise_request_exception = False
@patch("apps.notifications.services.send_email")
@patch("apps.notifications.services.send_sms")
@patch("apps.complaints.tasks.notify_staff_new_item.delay")
def test_api_create_lands_at_sent(self, mock_notify, mock_sms, mock_email):
url = "/appreciation/api/appreciations/"
data = {
"recipient_type": "user",
"recipient_id": str(self.recipient.id),
"message_en": "Thank you for your excellent care.",
"hospital_id": str(self.hospital.id),
"visibility": "private",
"is_anonymous": False,
}
self.client.post(url, data, format="json")
# The create path used to raise ValueError on send(); it now activates
# then sends, landing at SENT. We assert on DB state because the response
# serializer has a pre-existing GFK serialization issue (raw `recipient`)
# unrelated to this fix.
ap = Appreciation.objects.get()
self.assertEqual(ap.status, AppreciationStatus.SENT.value)
self.assertIsNotNone(ap.activated_at)
self.assertIsNotNone(ap.sent_at)
self.assertEqual(ap.activated_by, self.user)

155
apps/appreciation/ui_views.py
View File

@ -117,15 +117,16 @@ def appreciation_detail(request, pk):
categories = AppreciationCategory.objects.filter(is_active=True).order_by("order", "name_en")
# Users + departments for the shared "Send to Department" modal
send_to_users = User.objects.filter(is_active=True)
# Sendable departments for the "Send to Department" modal
from apps.organizations.department_contacts import has_contact_target
hospital_departments = []
if appreciation.hospital:
send_to_users = send_to_users.filter(hospital=appreciation.hospital)
hospital_departments = Department.objects.filter(
hospital=appreciation.hospital, status="active"
).order_by("name")
send_to_users = send_to_users.select_related("department").order_by("first_name", "last_name")
hospital_departments = [
d for d in Department.objects.filter(
hospital=appreciation.hospital, status="active"
).select_related("champion", "manager", "manager__staff_profile").order_by("name")
if has_contact_target(d)
]
from django.contrib.contenttypes.models import ContentType
appreciation_ct = ContentType.objects.get_for_model(appreciation)
@ -137,7 +138,6 @@ def appreciation_detail(request, pk):
"staff_list": staff_queryset,
"departments": departments,
"categories": categories,
"send_to_users": send_to_users,
"hospital_departments": hospital_departments,
"can_activate": appreciation.status == AppreciationStatus.DRAFT,
"can_send": appreciation.status in (AppreciationStatus.ACTIVATED, AppreciationStatus.AI_ANALYZED),
@ -150,6 +150,46 @@ def appreciation_detail(request, pk):
return render(request, "appreciation/appreciation_detail.html", context)
@login_required
def appreciation_create(request):
"""Internal form for creating a new appreciation (department-targeted)."""
user = request.user
if not (
user.is_px_admin()
or user.is_hospital_admin()
or user.is_px_management()
or user.is_px_employee()
):
messages.error(request, _("You don't have permission to create appreciations."))
return redirect("appreciation:appreciation_list")
from .forms import AppreciationForm
hospital = user.hospital
if request.method == "POST":
form = AppreciationForm(request.POST, hospital=hospital)
if form.is_valid():
appreciation = form.save(commit=False)
appreciation.sender = user
appreciation.hospital = form.cleaned_data["hospital"]
appreciation.status = AppreciationStatus.DRAFT
appreciation.save()
form.save_m2m()
messages.success(request, _("Appreciation created successfully."))
return redirect("appreciation:appreciation_detail", pk=appreciation.pk)
else:
messages.error(request, _("Please correct the errors below."))
else:
form = AppreciationForm(hospital=hospital)
context = {
"form": form,
"hospital": hospital,
}
return render(request, "appreciation/appreciation_create.html", context)
@login_required
@require_http_methods(["POST"])
def appreciation_activate(request, pk):
@ -168,33 +208,6 @@ def appreciation_activate(request, pk):
messages.error(request, _("Permission denied."))
return redirect("appreciation:appreciation_list")
staff_id = request.POST.get("staff")
department_id = request.POST.get("department")
category_id = request.POST.get("category")
if not staff_id:
messages.error(request, _("Please select a staff member before activating."))
return redirect("appreciation:appreciation_detail", pk=appreciation.pk)
staff = Staff.objects.filter(id=staff_id).select_related("department", "user").first()
if staff:
if staff.user:
user_ct = ContentType.objects.get_for_model(staff.user)
appreciation.recipient_content_type = user_ct
appreciation.recipient_object_id = staff.user.id
else:
staff_ct = ContentType.objects.get_for_model(staff)
appreciation.recipient_content_type = staff_ct
appreciation.recipient_object_id = staff.id
if not department_id and staff.department:
department_id = str(staff.department.id)
if department_id:
appreciation.department_id = department_id
if category_id:
appreciation.category_id = category_id
appreciation.status = AppreciationStatus.ACTIVATED
appreciation.activated_at = timezone.now()
appreciation.activated_by = user
@ -410,52 +423,33 @@ def appreciation_send_to(request, pk):
if note:
appreciation.custom_message = note
# Notify champion + manager (email + SMS)
notified = []
link = f"https://{request.get_host()}/appreciation/detail/{appreciation.pk}/"
for target in targets:
display_name = (
target["staff"].get_full_name() if target.get("staff")
else (target["user"].get_full_name() if target.get("user") else target["label"])
)
if target.get("email"):
send_subject = email_subject or f"Appreciation Sent to Department - {appreciation.reference_number}"
send_body = email_body or (
f"Appreciation #{appreciation.reference_number} has been sent to your department ({department.name})."
)
NotificationService.send_email(
email=target["email"],
subject=send_subject,
message=send_body + f"\n\n{link}",
html_message=f"""
<div style="font-family: 'Segoe UI', Tahoma, sans-serif; max-width: 600px; margin: 0 auto; border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
{get_email_header_html()}
<div style="padding: 20px;">
<h2 style="color: #005696; font-size: 18px; margin: 0 0 12px 0;">Appreciation Sent to Department</h2>
<p>Appreciation <strong>#{appreciation.reference_number}</strong> has been sent to your department <strong>({department.name})</strong>.</p>
<p><strong>Message:</strong> {appreciation.message_en or 'N/A'}</p>
{f'<p><strong>Note:</strong> {note}</p>' if note else ''}
<p><strong>Role:</strong> {target['label']}</p>
<p><a href="{link}">View Appreciation</a></p>
</div>
</div>
""",
related_object=appreciation,
)
if target.get("phone"):
try:
NotificationService.send_sms(
target["phone"],
f"PX360: Appreciation #{appreciation.reference_number} sent to {department.name}. {link}",
related_object=appreciation,
)
except Exception:
pass
notified.append(f"{display_name} ({target['label']})")
message = f"Appreciation sent to {department.name} — {', '.join(notified)}."
# Set the appreciated staff member as the recipient (if selected)
staff_id = request.POST.get("staff_id", "").strip()
if staff_id:
try:
appreciated_staff = Staff.objects.get(id=staff_id)
from django.contrib.contenttypes.models import ContentType as CT
staff_ct = CT.objects.get_for_model(Staff)
appreciation.recipient_content_type = staff_ct
appreciation.recipient_object_id = appreciated_staff.id
except Staff.DoesNotExist:
pass
# Advance to SENT (validates status is ACTIVATED/AI_ANALYZED)
appreciation.send()
# Advance to SENT (validates status is ACTIVATED/AI_ANALYZED)
appreciation.send()
# Send notifications (email + SMS to champion, manager, staff) in the background
from apps.appreciation.tasks import send_appreciation_notifications
send_appreciation_notifications.delay(
str(appreciation.pk),
staff_id=staff_id or None,
note=note,
email_subject=email_subject,
email_body=email_body,
host=request.get_host(),
)
message = f"Appreciation sent to {department.name}."
StaffActivityService.log_from_request(
request,
@ -1287,4 +1281,5 @@ def appreciation_pdf(request, pk):
'appreciation/appreciation_pdf.html',
{'object': obj},
f'appreciation_{obj.reference_number}.pdf',
obj=obj,
)

1
apps/appreciation/urls.py
View File

@ -31,6 +31,7 @@ urlpatterns = [
# UI Routes
path('', ui_views.appreciation_list, name='appreciation_list'),
path('new/', ui_views.appreciation_create, name='appreciation_create'),
path('detail/<uuid:pk>/', ui_views.appreciation_detail, name='appreciation_detail'),
path('detail/<uuid:pk>/activate/', ui_views.appreciation_activate, name='appreciation_activate'),
path('detail/<uuid:pk>/send/', ui_views.appreciation_send, name='appreciation_send'),

4
apps/appreciation/views.py
View File

@ -194,7 +194,9 @@ class AppreciationViewSet(viewsets.ModelViewSet):
is_anonymous=data["is_anonymous"],
)
# Send appreciation
# Activate + send. activate() honors the activation gate (DRAFT ->
# ACTIVATED) and records the activator; send() then moves to SENT.
appreciation.activate(activated_by=request.user)
appreciation.send()
try:

51
apps/complaints/admin.py
View File

@ -15,7 +15,7 @@ from .models import (
ComplaintSLAConfig,
ComplaintThreshold,
ComplaintUpdate,
EscalationRule,
Inquiry,
ExplanationSLAConfig,
ComplaintInvolvedDepartment,
@ -35,10 +35,9 @@ class ExplanationSLAConfigAdmin(admin.ModelAdmin):
"reminder_hours_before",
"second_reminder_enabled",
"second_reminder_hours_before",
"auto_escalate_enabled",
"is_active",
)
list_filter = ("is_active", "second_reminder_enabled", "auto_escalate_enabled")
list_filter = ("is_active", "second_reminder_enabled")
fieldsets = (
(
None,
@ -53,7 +52,6 @@ class ExplanationSLAConfigAdmin(admin.ModelAdmin):
)
},
),
("Escalation", {"fields": ("auto_escalate_enabled", "escalation_hours_overdue", "max_escalation_levels")}),
)
@ -450,6 +448,8 @@ class InquiryAdmin(admin.ModelAdmin):
"created_by",
"assigned_to",
"created_at",
"resolved_at",
"closed_at",
]
list_filter = ["status", "category", "source", "hospital", "created_by", "created_at"]
search_fields = [
@ -473,15 +473,19 @@ class InquiryAdmin(admin.ModelAdmin):
("Inquiry Details", {"fields": ("subject", "message", "category", "source")}),
("Creator Tracking", {"fields": ("created_by",)}),
("Status & Assignment", {"fields": ("status", "assigned_to")}),
("Resolution & Closure", {"fields": ("resolved_at", "resolved_by", "closed_at", "closed_by")}),
("Response", {"fields": ("response", "responded_at", "responded_by")}),
("Metadata", {"fields": ("created_at", "updated_at")}),
)
readonly_fields = ["responded_at", "created_at", "updated_at"]
readonly_fields = ["responded_at", "resolved_at", "resolved_by", "closed_at", "closed_by", "created_at", "updated_at"]
def get_queryset(self, request):
qs = super().get_queryset(request)
return qs.select_related("patient", "hospital", "department", "assigned_to", "responded_by", "created_by")
return qs.select_related(
"patient", "hospital", "department", "assigned_to",
"responded_by", "resolved_by", "closed_by", "created_by",
)
def subject_preview(self, obj):
"""Show preview of subject"""
@ -506,7 +510,7 @@ class ComplaintSLAConfigAdmin(admin.ModelAdmin):
(
"Source-Based Timing (Hours After Creation)",
{
"fields": ("first_reminder_hours_after", "second_reminder_hours_after", "escalation_hours_after"),
"fields": ("first_reminder_hours_after", "second_reminder_hours_after"),
"description": 'When set, these override the "Hours Before Deadline" timing. Used for source-based SLAs (e.g., MOH, CCHI).',
},
),
@ -576,39 +580,6 @@ class ComplaintCategoryAdmin(admin.ModelAdmin):
hospitals_display.short_description = "Hospitals"
@admin.register(EscalationRule)
class EscalationRuleAdmin(admin.ModelAdmin):
"""Escalation Rule admin"""
list_display = ["name", "hospital", "escalate_to_role", "trigger_on_overdue", "order", "is_active"]
list_filter = [
"hospital",
"escalate_to_role",
"trigger_on_overdue",
"severity_filter",
"priority_filter",
"is_active",
]
search_fields = ["name", "description", "hospital__name_en"]
ordering = ["hospital", "order"]
fieldsets = (
("Hospital", {"fields": ("hospital",)}),
("Rule Details", {"fields": ("name", "description")}),
("Trigger Conditions", {"fields": ("trigger_on_overdue", "trigger_hours_overdue")}),
("Escalation Target", {"fields": ("escalate_to_role", "escalate_to_user")}),
("Filters", {"fields": ("severity_filter", "priority_filter"), "classes": ("collapse",)}),
("Order & Status", {"fields": ("order", "is_active")}),
("Metadata", {"fields": ("created_at", "updated_at"), "classes": ("collapse",)}),
)
readonly_fields = ["created_at", "updated_at"]
def get_queryset(self, request):
qs = super().get_queryset(request)
return qs.select_related("hospital", "escalate_to_user")
@admin.register(ComplaintThreshold)
class ComplaintThresholdAdmin(admin.ModelAdmin):
"""Complaint Threshold admin"""

119
apps/complaints/forms.py
View File

@ -19,7 +19,6 @@ from apps.complaints.models import (
ComplaintType,
Inquiry,
ComplaintSLAConfig,
EscalationRule,
ComplaintThreshold,
ComplaintInvolvedDepartment,
ComplaintInvolvedStaff,
@ -78,9 +77,7 @@ class PublicComplaintForm(forms.ModelForm):
label=_("Relation to Patient"),
choices=[
("patient", "Patient"),
("relative", "Relative"),
("friend", "Friend"),
("other", "Other"),
("relative", "Relative")
],
required=True,
widget=forms.Select(attrs={"class": "form-control"}),
@ -776,12 +773,8 @@ class SLAConfigForm(HospitalFieldMixin, forms.ModelForm):
"hospital",
"source",
"severity",
"priority",
"sla_hours",
"first_reminder_hours_after",
"second_reminder_hours_after",
"reminder_hours_before",
"second_reminder_enabled",
"second_reminder_hours_before",
"is_active",
]
@ -789,12 +782,8 @@ class SLAConfigForm(HospitalFieldMixin, forms.ModelForm):
"hospital": forms.Select(attrs={"class": "form-select"}),
"source": forms.Select(attrs={"class": "form-select"}),
"severity": forms.Select(attrs={"class": "form-select"}),
"priority": forms.Select(attrs={"class": "form-select"}),
"sla_hours": forms.NumberInput(attrs={"class": "form-control", "min": "1"}),
"first_reminder_hours_after": forms.NumberInput(attrs={"class": "form-control", "min": "0"}),
"second_reminder_hours_after": forms.NumberInput(attrs={"class": "form-control", "min": "0"}),
"reminder_hours_before": forms.NumberInput(attrs={"class": "form-control", "min": "0"}),
"second_reminder_enabled": forms.CheckboxInput(attrs={"class": "form-check-input"}),
"second_reminder_hours_before": forms.NumberInput(attrs={"class": "form-control", "min": "0"}),
"is_active": forms.CheckboxInput(attrs={"class": "form-check-input"}),
}
@ -804,31 +793,25 @@ class SLAConfigForm(HospitalFieldMixin, forms.ModelForm):
hospital = cleaned_data.get("hospital")
source = cleaned_data.get("source")
severity = cleaned_data.get("severity")
priority = cleaned_data.get("priority")
sla_hours = cleaned_data.get("sla_hours")
first_reminder = cleaned_data.get("first_reminder_hours_after")
second_reminder = cleaned_data.get("second_reminder_hours_after")
reminder_hours_before = cleaned_data.get("reminder_hours_before")
second_reminder_hours_before = cleaned_data.get("second_reminder_hours_before")
# Validate SLA hours is positive
if sla_hours and sla_hours <= 0:
raise ValidationError({"sla_hours": "SLA hours must be greater than 0"})
# Validate first reminder hours
if first_reminder and first_reminder > 0:
if first_reminder >= sla_hours:
raise ValidationError({"first_reminder_hours_after": "First reminder must be less than SLA hours"})
# Validate first reminder hours (must be less than SLA hours)
if reminder_hours_before and reminder_hours_before > 0:
if reminder_hours_before >= sla_hours:
raise ValidationError({"reminder_hours_before": "First reminder must be less than SLA hours"})
# Validate second reminder hours
if second_reminder and second_reminder > 0:
if second_reminder >= sla_hours:
raise ValidationError({"second_reminder_hours_after": "Second reminder must be less than SLA hours"})
if first_reminder and second_reminder <= first_reminder:
raise ValidationError({"second_reminder_hours_after": "Second reminder must be after first reminder"})
# Validate legacy reminder hours < SLA hours
if sla_hours and reminder_hours_before and reminder_hours_before >= sla_hours:
raise ValidationError({"reminder_hours_before": "Reminder hours must be less than SLA hours"})
if second_reminder_hours_before and second_reminder_hours_before > 0:
if second_reminder_hours_before >= sla_hours:
raise ValidationError({"second_reminder_hours_before": "Second reminder must be less than SLA hours"})
if reminder_hours_before and second_reminder_hours_before >= reminder_hours_before:
raise ValidationError({"second_reminder_hours_before": "Second reminder must be closer to deadline than first"})
# Check for unique combination (excluding current instance when editing)
filters = {}
@ -838,8 +821,6 @@ class SLAConfigForm(HospitalFieldMixin, forms.ModelForm):
filters["source"] = source
if severity:
filters["severity"] = severity
if priority:
filters["priority"] = priority
if filters:
queryset = ComplaintSLAConfig.objects.filter(**filters)
@ -851,84 +832,6 @@ class SLAConfigForm(HospitalFieldMixin, forms.ModelForm):
return cleaned_data
class EscalationRuleForm(HospitalFieldMixin, forms.ModelForm):
"""Form for creating and editing escalation rules"""
class Meta:
model = EscalationRule
fields = [
"hospital",
"name",
"description",
"escalation_level",
"max_escalation_level",
"trigger_on_overdue",
"trigger_hours_overdue",
"reminder_escalation_enabled",
"reminder_escalation_hours",
"escalate_to_role",
"escalate_to_user",
"severity_filter",
"priority_filter",
"is_active",
]
widgets = {
"hospital": forms.Select(attrs={"class": "form-select"}),
"name": forms.TextInput(attrs={"class": "form-control"}),
"description": forms.Textarea(attrs={"class": "form-control", "rows": 3}),
"escalation_level": forms.NumberInput(attrs={"class": "form-control", "min": "1"}),
"max_escalation_level": forms.NumberInput(attrs={"class": "form-control", "min": 1}),
"trigger_on_overdue": forms.CheckboxInput(attrs={"class": "form-check-input"}),
"trigger_hours_overdue": forms.NumberInput(attrs={"class": "form-control", "min": 0}),
"reminder_escalation_enabled": forms.CheckboxInput(attrs={"class": "form-check-input"}),
"reminder_escalation_hours": forms.NumberInput(attrs={"class": "form-control", "min": 0}),
"escalate_to_role": forms.Select(attrs={"class": "form-select", "id": "escalate_to_role"}),
"escalate_to_user": forms.Select(attrs={"class": "form-select"}),
"severity_filter": forms.Select(attrs={"class": "form-select"}),
"priority_filter": forms.Select(attrs={"class": "form-select"}),
"is_active": forms.CheckboxInput(attrs={"class": "form-check-input"}),
}
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
# Filter users for escalate_to_user field based on hospital
from apps.accounts.models import User
# Get hospital context
hospital = None
if self.data.get("hospital"):
try:
hospital = Hospital.objects.get(id=self.data["hospital"])
except Hospital.DoesNotExist:
pass
elif self.initial.get("hospital"):
hospital = self.initial.get("hospital")
elif self.instance and self.instance.pk and self.instance.hospital_id:
hospital = self.instance.hospital
elif self.user and self.user.is_px_admin():
hospital = getattr(self.request, "tenant_hospital", None)
elif self.user and self.user.hospital:
hospital = self.user.hospital
if hospital:
from apps.core.utils import get_assignable_users
self.fields["escalate_to_user"].queryset = get_assignable_users(hospital)
else:
self.fields["escalate_to_user"].queryset = User.objects.none()
def clean(self):
cleaned_data = super().clean()
escalate_to_role = cleaned_data.get("escalate_to_role")
escalate_to_user = cleaned_data.get("escalate_to_user")
# If role is 'specific_user', user must be specified
if escalate_to_role == "specific_user" and not escalate_to_user:
raise ValidationError({"escalate_to_user": "Please select a user when role is set to Specific User"})
return cleaned_data
class ComplaintThresholdForm(HospitalFieldMixin, forms.ModelForm):
"""
Form for creating and editing complaint thresholds.

153
apps/complaints/management/commands/close_stale_complaints.py Normal file
View File

@ -0,0 +1,153 @@
"""
Bulk-close stale complaints.
Closes complaints older than a cutoff that are still in an active (non-terminal)
status, without triggering patient-facing side effects (no resolution-survey
emails/SMS, no per-instance notifications) — the canonical ComplaintService
change_status() path is deliberately bypassed for this administrative cleanup.
An audit trail is still written: one ComplaintUpdate per complaint + one
batch AuditEvent.
Usage:
python manage.py close_stale_complaints --dry-run
python manage.py close_stale_complaints
python manage.py close_stale_complaints --before 2026-01-01 --user ismail@tenhal.sa
"""
from datetime import datetime
from django.contrib.auth import get_user_model
from django.core.management.base import BaseCommand, CommandError
from django.db import transaction
from django.db.models import Count
from django.utils import timezone
from apps.complaints.models import Complaint, ComplaintStatus, ComplaintUpdate
from apps.core.services import AuditService
User = get_user_model()
DEFAULT_BEFORE = "2026-01-01"
DEFAULT_USER_EMAIL = "ismail@tenhal.sa"
ACTIVE_STATUSES = [ComplaintStatus.OPEN, ComplaintStatus.IN_PROGRESS]
class Command(BaseCommand):
help = "Bulk-close stale complaints older than a cutoff (default: pre-2026, open/in_progress)."
def add_arguments(self, parser):
parser.add_argument("--before", default=DEFAULT_BEFORE,
help="Cutoff date (YYYY-MM-DD). Complaints created before this are eligible.")
parser.add_argument("--user", default=DEFAULT_USER_EMAIL,
help="Email/username to attribute the close to (default: %(default)s).")
parser.add_argument("--note", default="Bulk close: stale complaint (administrative cleanup)",
help="Audit note attached to each closed complaint.")
parser.add_argument("--dry-run", action="store_true",
help="Show what would be closed without changing anything.")
def _resolve_user(self, ref):
for field in ("email", "username"):
try:
return User.objects.get(**{field: ref})
except User.DoesNotExist:
continue
try:
return User.objects.get(pk=ref)
except (User.DoesNotExist, ValueError):
pass
user = User.objects.filter(is_superuser=True).order_by("id").first()
if user:
self.stdout.write(self.style.WARNING(
f"User '{ref}' not found; falling back to superuser {user.email or user.username}."))
return user
raise CommandError(f"Could not resolve a user for '{ref}' and no superuser exists.")
def handle(self, *args, **options):
before_str = options["before"]
try:
naive = datetime.strptime(before_str + " 00:00:00", "%Y-%m-%d %H:%M:%S")
except ValueError as exc:
raise CommandError(f"--before must be YYYY-MM-DD: {exc}") from exc
before = timezone.make_aware(naive, timezone.get_current_timezone())
before_label = before_str
user = self._resolve_user(options["user"])
note = options["note"]
dry_run = options["dry_run"]
qs = Complaint.objects.filter(created_at__lt=before, status__in=ACTIVE_STATUSES)
total = qs.count()
self.stdout.write(self.style.MIGRATE_HEADING(
f"close_stale_complaints (before={before_label}, user={user.email or user.username}, "
f"dry_run={dry_run})"))
self.stdout.write(f"Eligible complaints: {total}")
if total == 0:
self.stdout.write(self.style.SUCCESS("Nothing to do."))
return
# Breakdown
self.stdout.write("\nBy current status:")
for row in qs.values("status").annotate(n=Count("id")).order_by("-n"):
self.stdout.write(f" {row['status']:<20} {row['n']}")
self.stdout.write("\nBy year (created_at):")
for row in qs.extra(select={"y": "date_part('year', created_at)::int"}
).values("y").annotate(n=Count("id")).order_by("y"):
self.stdout.write(f" {int(row['y'])} {row['n']}")
self.stdout.write("\nSample (5 oldest):")
for c in qs.order_by("created_at")[:5]:
self.stdout.write(f" id={c.id} status={c.status} created={c.created_at.date()}")
if dry_run:
self.stdout.write(self.style.WARNING("\nDRY-RUN: no changes made. Re-run without --dry-run to apply."))
return
now = timezone.now()
with transaction.atomic():
# Capture targets + old status for audit before the UPDATE
targets = list(qs.values_list("id", "status"))
ids = [t[0] for t in targets]
updated = qs.update(
status=ComplaintStatus.CLOSED,
closed_at=now,
closed_by=user,
updated_at=now,
)
# Audit per complaint (bulk_create bypasses signals → no notifications)
ComplaintUpdate.objects.bulk_create([
ComplaintUpdate(
complaint_id=cid,
update_type="status_change",
message=note,
old_status=old,
new_status=ComplaintStatus.CLOSED,
created_by=user,
metadata={"bulk_close": True, "source": "close_stale_complaints"},
)
for cid, old in targets
])
# Batch audit event — kept OUTSIDE atomic so a logging failure can never
# roll back the data change above. Uses a valid AuditEvent.EVENT_TYPES value.
AuditService.log_event(
event_type="complaint_closed",
description=(
f"Bulk closed {updated} stale complaints (created before {before_label}) "
f"by {user.email or user.username}"
),
user=user,
metadata={
"count": updated,
"before": before_label,
"complaint_ids": ids,
"note": note,
},
)
self.stdout.write(self.style.SUCCESS(f"\nClosed {updated} complaint(s)."))
remaining = Complaint.objects.filter(created_at__lt=before, status__in=ACTIVE_STATUSES).count()
self.stdout.write(f"Remaining eligible (open/in_progress before {before_label}): {remaining}")

56
apps/complaints/management/commands/seed_complaint_configs.py
View File

@ -8,14 +8,13 @@ from apps.complaints.models import (
ComplaintCategory,
ComplaintSLAConfig,
ComplaintThreshold,
EscalationRule,
InquirySLAConfig,
)
from apps.organizations.models import Hospital
class Command(BaseCommand):
help = 'Seed default complaint configurations (categories, SLA configs, thresholds, escalation rules)'
help = 'Seed default complaint configurations (categories, SLA configs, thresholds)'
def add_arguments(self, parser):
parser.add_argument(
@ -47,7 +46,6 @@ class Command(BaseCommand):
self.stdout.write(f"\nProcessing hospital: {hospital.name}")
self.seed_sla_configs(hospital)
self.seed_thresholds(hospital)
self.seed_escalation_rules(hospital)
self.seed_inquiry_dept_response_sla(hospital)
self.stdout.write(self.style.SUCCESS('\nSuccessfully seeded complaint configurations!'))
@ -202,58 +200,6 @@ class Command(BaseCommand):
self.stdout.write(f" Created {created_count} thresholds")
def seed_escalation_rules(self, hospital):
"""Seed escalation rules for a hospital"""
self.stdout.write(f" Seeding escalation rules...")
rules = [
{
'name': 'Default Escalation to Department Manager',
'description': 'Escalate overdue complaints to department manager',
'trigger_on_overdue': True,
'trigger_hours_overdue': 0,
'escalate_to_role': 'department_manager',
'order': 1,
},
{
'name': 'Critical Escalation to Hospital Admin',
'description': 'Escalate critical complaints to hospital admin after 4 hours overdue',
'trigger_on_overdue': True,
'trigger_hours_overdue': 4,
'escalate_to_role': 'hospital_admin',
'severity_filter': 'critical',
'order': 2,
},
{
'name': 'Final Escalation to PX Admin',
'description': 'Escalate to PX Admin after 24 hours overdue',
'trigger_on_overdue': True,
'trigger_hours_overdue': 24,
'escalate_to_role': 'px_admin',
'order': 3,
},
]
created_count = 0
for rule_data in rules:
rule, created = EscalationRule.objects.get_or_create(
hospital=hospital,
name=rule_data['name'],
defaults={
'description': rule_data['description'],
'trigger_on_overdue': rule_data['trigger_on_overdue'],
'trigger_hours_overdue': rule_data['trigger_hours_overdue'],
'escalate_to_role': rule_data['escalate_to_role'],
'severity_filter': rule_data.get('severity_filter', ''),
'order': rule_data['order'],
'is_active': True
}
)
if created:
created_count += 1
self.stdout.write(f" Created {created_count} escalation rules")
def seed_inquiry_dept_response_sla(self, hospital):
"""Seed department response SLA defaults for inquiry configs"""
self.stdout.write(f" Seeding inquiry dept response SLA defaults...")

20
apps/complaints/migrations/0037_remove_escalationrule.py Normal file
View File

@ -0,0 +1,20 @@
# Generated by Django 6.0.1 on 2026-07-06 20:41
from django.db import migrations
class Migration(migrations.Migration):
dependencies = [
('complaints', '0036_alter_complaint_relation_to_patient'),
]
operations = [
migrations.RemoveIndex(
model_name='escalationrule',
name='complaints__hospita_3c8bac_idx',
),
migrations.DeleteModel(
name='EscalationRule',
),
]

37
apps/complaints/migrations/0038_remove_complaintexplanation_acceptance_notes_and_more.py Normal file
View File

@ -0,0 +1,37 @@
# Generated by Django 6.0.1 on 2026-07-07 09:26
from django.db import migrations
class Migration(migrations.Migration):
dependencies = [
('complaints', '0037_remove_escalationrule'),
]
operations = [
migrations.RemoveField(
model_name='complaintexplanation',
name='acceptance_notes',
),
migrations.RemoveField(
model_name='complaintexplanation',
name='acceptance_status',
),
migrations.RemoveField(
model_name='complaintexplanation',
name='accepted_at',
),
migrations.RemoveField(
model_name='complaintexplanation',
name='accepted_by',
),
migrations.RemoveField(
model_name='complaintexplanation',
name='escalated_at',
),
migrations.RemoveField(
model_name='complaintexplanation',
name='escalated_to_manager',
),
]

29
apps/complaints/migrations/0039_remove_inquiry_dept_response_acceptance_notes_and_more.py Normal file
View File

@ -0,0 +1,29 @@
# Generated by Django 6.0.1 on 2026-07-07 10:11
from django.db import migrations
class Migration(migrations.Migration):
dependencies = [
('complaints', '0038_remove_complaintexplanation_acceptance_notes_and_more'),
]
operations = [
migrations.RemoveField(
model_name='inquiry',
name='dept_response_acceptance_notes',
),
migrations.RemoveField(
model_name='inquiry',
name='dept_response_acceptance_status',
),
migrations.RemoveField(
model_name='inquiry',
name='dept_response_accepted_at',
),
migrations.RemoveField(
model_name='inquiry',
name='dept_response_accepted_by',
),
]

18
apps/complaints/migrations/0040_alter_complaint_relation_to_patient.py Normal file
View File

@ -0,0 +1,18 @@
# Generated by Django 6.0.1 on 2026-07-08 10:02
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('complaints', '0039_remove_inquiry_dept_response_acceptance_notes_and_more'),
]
operations = [
migrations.AlterField(
model_name='complaint',
name='relation_to_patient',
field=models.CharField(blank=True, choices=[('patient', 'Patient'), ('relative', 'Relative')], help_text="Complainant's relationship to the patient", max_length=20, verbose_name='Complinant'),
),
]

23
apps/complaints/migrations/0041_inquiry_closed_at_inquiry_resolved_at.py Normal file
View File

@ -0,0 +1,23 @@
# Generated by Django 6.0.1 on 2026-07-09 09:04
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('complaints', '0040_alter_complaint_relation_to_patient'),
]
operations = [
migrations.AddField(
model_name='inquiry',
name='closed_at',
field=models.DateTimeField(blank=True, db_index=True, help_text='When the inquiry was closed', null=True),
),
migrations.AddField(
model_name='inquiry',
name='resolved_at',
field=models.DateTimeField(blank=True, db_index=True, help_text='When the inquiry was resolved', null=True),
),
]

26
apps/complaints/migrations/0042_inquiry_closed_by_inquiry_resolved_by.py Normal file
View File

@ -0,0 +1,26 @@
# Generated by Django 6.0.1 on 2026-07-09 09:14
import django.db.models.deletion
from django.conf import settings
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('complaints', '0041_inquiry_closed_at_inquiry_resolved_at'),
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
migrations.AddField(
model_name='inquiry',
name='closed_by',
field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='closed_inquiries', to=settings.AUTH_USER_MODEL),
),
migrations.AddField(
model_name='inquiry',
name='resolved_by',
field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='resolved_inquiries', to=settings.AUTH_USER_MODEL),
),
]

237
apps/complaints/models.py
View File

@ -221,9 +221,7 @@ class Complaint(UUIDModel, TimeStampedModel, SoftDeleteModel):
max_length=20,
choices=[
("patient", _("Patient")),
("relative", _("Relative")),
("friend", _("Friend")),
("other", _("Other")),
("relative", _("Relative"))
],
blank=True,
verbose_name=_("Complinant"),
@ -809,7 +807,6 @@ class Complaint(UUIDModel, TimeStampedModel, SoftDeleteModel):
hospital=self.hospital,
source__isnull=True, # Explicitly check for null source
severity=self.severity,
priority=self.priority,
is_active=True,
)
sla_hours = sla_config.sla_hours
@ -817,10 +814,10 @@ class Complaint(UUIDModel, TimeStampedModel, SoftDeleteModel):
except ComplaintSLAConfig.DoesNotExist:
pass # Fall through to next option
# Try severity/priority-based config without source filter (backward compatibility)
# Try severity-based config without source filter (backward compatibility)
try:
sla_config = ComplaintSLAConfig.objects.get(
hospital=self.hospital, severity=self.severity, priority=self.priority, is_active=True
hospital=self.hospital, severity=self.severity, is_active=True
)
sla_hours = sla_config.sla_hours
return timezone.now() + timedelta(hours=sla_hours)
@ -852,16 +849,15 @@ class Complaint(UUIDModel, TimeStampedModel, SoftDeleteModel):
hospital=self.hospital,
source__isnull=True,
severity=self.severity,
priority=self.priority,
is_active=True,
)
except ComplaintSLAConfig.DoesNotExist:
pass # Fall through to next option
# Try severity/priority-based config without source filter (backward compatibility)
# Try severity-based config without source filter (backward compatibility)
try:
return ComplaintSLAConfig.objects.get(
hospital=self.hospital, severity=self.severity, priority=self.priority, is_active=True
hospital=self.hospital, severity=self.severity, is_active=True
)
except ComplaintSLAConfig.DoesNotExist:
pass # No config found
@ -1125,16 +1121,11 @@ class Complaint(UUIDModel, TimeStampedModel, SoftDeleteModel):
"""
Get the public tracking URL for this complaint.
"""
from django.contrib.sites.shortcuts import get_current_site
from django.conf import settings
from django.urls import reverse
try:
site = get_current_site(None)
domain = site.domain
except:
domain = "localhost:8000"
return f"https://{domain}{reverse('complaints:public_complaint_track')}?reference={self.reference_number}"
base = settings.SITE_URL.rstrip("/")
return f"{base}{reverse('complaints:public_complaint_track')}?reference={self.reference_number}"
class ComplaintAttachment(UUIDModel, TimeStampedModel):
@ -1313,112 +1304,6 @@ class ComplaintSLAConfig(UUIDModel, TimeStampedModel):
pri_display = self.priority if self.priority else "Any Priority"
return f"{self.hospital.name} - {source_display} - {sev_display}/{pri_display} - {self.sla_hours}h"
def get_first_reminder_hours_after(self, complaint_created_at=None):
if self.first_reminder_hours_after > 0:
return self.first_reminder_hours_after
else:
return max(0, self.sla_hours - self.reminder_hours_before)
def get_second_reminder_hours_after(self, complaint_created_at=None):
if self.second_reminder_hours_after > 0:
return self.second_reminder_hours_after
elif self.second_reminder_enabled:
return max(0, self.sla_hours - self.second_reminder_hours_before)
else:
return 0
def get_escalation_hours_after(self, complaint_created_at=None):
if self.escalation_hours_after > 0:
return self.escalation_hours_after
else:
return None
class EscalationRule(UUIDModel, TimeStampedModel):
"""
Configurable escalation rules for complaints.
Defines who receives escalated complaints based on conditions.
Supports multi-level escalation with configurable hierarchy.
"""
hospital = models.ForeignKey("organizations.Hospital", on_delete=models.CASCADE, related_name="escalation_rules")
name = models.CharField(max_length=200)
description = models.TextField(blank=True)
# Escalation level (supports multi-level escalation)
escalation_level = models.IntegerField(default=1, help_text="Escalation level (1 = first level, 2 = second, etc.)")
max_escalation_level = models.IntegerField(
default=3, help_text="Maximum escalation level before stopping (default: 3)"
)
# Trigger conditions
trigger_on_overdue = models.BooleanField(default=True, help_text="Trigger when complaint is overdue")
trigger_hours_overdue = models.IntegerField(default=0, help_text="Trigger X hours after overdue (0 = immediately)")
# Reminder-based escalation
reminder_escalation_enabled = models.BooleanField(
default=False, help_text="Enable escalation after reminder if no action taken"
)
reminder_escalation_hours = models.IntegerField(
default=24, help_text="Escalate X hours after reminder if no action"
)
# Escalation target
escalate_to_role = models.CharField(
max_length=50,
choices=[
("department_manager", "Department Manager"),
("hospital_admin", "Hospital Admin"),
("medical_director", "Medical Director"),
("admin_director", "Administrative Director"),
("px_admin", "PX Admin"),
("ceo", "CEO"),
("specific_user", "Specific User"),
],
help_text="Role to escalate to",
)
escalate_to_user = models.ForeignKey(
"accounts.User",
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name="escalation_target_rules",
help_text="Specific user if escalate_to_role is 'specific_user'",
)
# Conditions
severity_filter = models.CharField(
max_length=20,
choices=SeverityChoices.choices,
blank=True,
help_text="Only escalate complaints with this severity (blank = all)",
)
priority_filter = models.CharField(
max_length=20,
choices=PriorityChoices.choices,
blank=True,
help_text="Only escalate complaints with this priority (blank = all)",
)
order = models.IntegerField(default=0, help_text="Escalation order (lower = first)")
is_active = models.BooleanField(default=True)
class Meta:
ordering = ["hospital", "order"]
indexes = [
models.Index(fields=["hospital", "is_active"]),
]
def __str__(self):
return f"{self.hospital.name} - {self.name}"
class ComplaintThreshold(UUIDModel, TimeStampedModel):
@ -1863,6 +1748,28 @@ class Inquiry(UUIDModel, TimeStampedModel, SoftDeleteModel):
help_text="Timestamp when inquiry was first activated (moved from OPEN to IN_PROGRESS)",
)
# Resolution / closure tracking (stamped in save() on status transition)
resolved_at = models.DateTimeField(
null=True, blank=True, db_index=True, help_text="When the inquiry was resolved"
)
resolved_by = models.ForeignKey(
"accounts.User",
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name="resolved_inquiries",
)
closed_at = models.DateTimeField(
null=True, blank=True, db_index=True, help_text="When the inquiry was closed"
)
closed_by = models.ForeignKey(
"accounts.User",
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name="closed_inquiries",
)
# SLA tracking
due_at = models.DateTimeField(null=True, blank=True, db_index=True, help_text="SLA deadline")
is_overdue = models.BooleanField(default=False, db_index=True)
@ -1973,32 +1880,6 @@ class Inquiry(UUIDModel, TimeStampedModel, SoftDeleteModel):
null=True, blank=True, help_text="When dept response was escalated to manager",
)
# Department response acceptance review
dept_response_acceptance_status = models.CharField(
max_length=20,
choices=[
("pending", _("Pending Review")),
("acceptable", _("Acceptable")),
("not_acceptable", _("Not Acceptable")),
],
default="pending",
help_text="Review status of the department response",
)
dept_response_accepted_by = models.ForeignKey(
"accounts.User",
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name="reviewed_inquiry_dept_responses",
help_text="User who reviewed the department response",
)
dept_response_accepted_at = models.DateTimeField(
null=True, blank=True, help_text="When the department response was reviewed",
)
dept_response_acceptance_notes = models.TextField(
blank=True, help_text="Notes about the acceptance decision",
)
# Contact tracking — matches the 3-stage timeline in the Excel reports
# Each stage has: date, time, staff, duration
@ -2097,6 +1978,27 @@ class Inquiry(UUIDModel, TimeStampedModel, SoftDeleteModel):
]
def save(self, *args, **kwargs):
# Track previous status to stamp resolved_at / closed_at on transition
if self.pk:
try:
old = Inquiry.objects.get(pk=self.pk)
self._status_was = old.status
except Inquiry.DoesNotExist:
self._status_was = None
else:
self._status_was = None
# Stamp timestamps + actor on entry into resolved / closed
acting_user = getattr(self, "_acting_user", None)
if self.status == "resolved" and self._status_was != "resolved":
self.resolved_at = timezone.now()
if acting_user is not None:
self.resolved_by = acting_user
if self.status == "closed" and self._status_was != "closed":
self.closed_at = timezone.now()
if acting_user is not None:
self.closed_by = acting_user
if not self.reference_number:
from apps.core.reference import generate_reference
@ -2415,43 +2317,6 @@ class ComplaintExplanation(UUIDModel, TimeStampedModel):
null=True, blank=True, help_text="Second reminder sent to staff about overdue explanation"
)
escalated_to_manager = models.ForeignKey(
"self",
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name="escalated_from_staff",
help_text="Escalated to this explanation (manager's explanation request)",
)
escalated_at = models.DateTimeField(null=True, blank=True, help_text="When explanation was escalated to manager")
# Acceptance review fields
class AcceptanceStatus(models.TextChoices):
PENDING = "pending", _("Pending Review")
ACCEPTABLE = "acceptable", _("Acceptable")
NOT_ACCEPTABLE = "not_acceptable", _("Not Acceptable")
acceptance_status = models.CharField(
max_length=20,
choices=AcceptanceStatus.choices,
default=AcceptanceStatus.PENDING,
help_text="Review status of the explanation",
)
accepted_by = models.ForeignKey(
"accounts.User",
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name="reviewed_explanations",
help_text="User who reviewed and marked the explanation",
)
accepted_at = models.DateTimeField(null=True, blank=True, help_text="When the explanation was reviewed")
acceptance_notes = models.TextField(blank=True, help_text="Notes about the acceptance decision")
class Meta:
ordering = ["-created_at"]
verbose_name = "Complaint Explanation"

27
apps/complaints/services/complaint_service.py
View File

@ -123,12 +123,21 @@ class ComplaintService:
complaint.assigned_to = user
complaint.assigned_at = timezone.now()
# Record first-activation timestamp regardless of starting status.
# Previously this was only set in the OPEN branch, which left the workflow
# stepper showing "not activated" for already-IN_PROGRESS complaints.
first_activation = complaint.activated_at is None
if first_activation:
complaint.activated_at = timezone.now()
if complaint.status == ComplaintStatus.OPEN:
complaint.status = ComplaintStatus.IN_PROGRESS
complaint.activated_at = timezone.now()
complaint.save(update_fields=["assigned_to", "assigned_at", "status", "activated_at"])
update_fields = ["assigned_to", "assigned_at", "status"]
else:
complaint.save(update_fields=["assigned_to", "assigned_at"])
update_fields = ["assigned_to", "assigned_at"]
if first_activation:
update_fields.append("activated_at")
complaint.save(update_fields=update_fields)
assign_message = f"Complaint activated and assigned to {user.get_full_name()}"
if previous_assignee:
@ -201,6 +210,14 @@ class ComplaintService:
):
raise ComplaintServiceError("You don't have permission to assign complaints.")
# Complaints can only be assigned to Patient Experience team members.
if not target_user.groups.filter(
name__in=["PX Employee", "PX Admin", "PX Management"]
).exists():
raise ComplaintServiceError(
"Complaints can only be assigned to Patient Experience team members."
)
old_assignee = complaint.assigned_to
old_status = complaint.status
@ -385,6 +402,10 @@ class ComplaintService:
if not new_status:
raise ComplaintServiceError("Please select a status.")
# Require activation before any status change other than closing the complaint.
if not complaint.activated_at and new_status != ComplaintStatus.CLOSED and new_status != "closed":
raise ComplaintServiceError("Complaint must be activated before changing its status.")
old_status = complaint.status
# Enforce valid status transitions

6
apps/complaints/signals.py
View File

@ -41,11 +41,11 @@ def sync_department_from_staff(sender, instance, **kwargs):
@receiver(post_save, sender=Complaint)
def send_complaint_creation_sms(sender, instance, created, **kwargs):
"""Dispatch the complaint-received SMS task when a complaint is created."""
"""Dispatch the complaint-received SMS/email task when a complaint is created."""
if not created:
return
if not instance.contact_phone:
logger.info(f"Complaint #{instance.id} created but no phone number provided. Skipping SMS.")
if not instance.contact_phone and not instance.contact_email:
logger.info(f"Complaint #{instance.id} created but no phone/email provided. Skipping notification.")
return
try:
from .tasks import send_complaint_creation_sms_task

766
apps/complaints/tasks.py
View File

@ -362,7 +362,6 @@ def check_overdue_complaints():
Runs every 15 minutes (configured in config/celery.py).
Updates is_overdue flag for complaints past their SLA deadline.
Triggers automatic escalation based on escalation rules.
"""
from apps.complaints.models import Complaint, ComplaintStatus
@ -372,22 +371,16 @@ def check_overdue_complaints():
).select_related("hospital", "patient", "department")
overdue_count = 0
escalated_count = 0
for complaint in active_complaints:
if complaint.check_overdue():
overdue_count += 1
logger.warning(f"Complaint {complaint.id} is overdue: {complaint.title} (due: {complaint.due_at})")
# Trigger automatic escalation
result = escalate_complaint_auto.delay(str(complaint.id))
if result:
escalated_count += 1
if overdue_count > 0:
logger.info(f"Found {overdue_count} overdue complaints, triggered {escalated_count} escalations")
logger.info(f"Found {overdue_count} overdue complaints")
return {"overdue_count": overdue_count, "escalated_count": escalated_count}
return {"overdue_count": overdue_count}
@shared_task
@ -669,294 +662,8 @@ def create_action_from_complaint(complaint_id):
return {"status": "error", "reason": error_msg}
@shared_task
def escalate_complaint_auto(complaint_id):
"""
Disabled: auto-escalation is turned off. Manual escalation only.
Kept for backward compatibility — returns immediately.
"""
logger.info(f"Auto-escalation is disabled. Skipping for complaint {complaint_id}.")
return {"status": "auto_escalation_disabled", "complaint_id": complaint_id}
@shared_task
def _escalate_complaint_auto_original(complaint_id):
"""
Automatically escalate complaint based on escalation rules.
This task is triggered when a complaint becomes overdue.
It finds matching escalation rules and reassigns the complaint.
Supports multi-level escalation with tracking.
Args:
complaint_id: UUID of the Complaint
Returns:
dict: Result with escalation status
"""
from apps.complaints.models import Complaint, ComplaintUpdate, EscalationRule
from apps.accounts.models import User
try:
complaint = Complaint.objects.select_related("hospital", "department", "assigned_to").get(id=complaint_id)
# Get current escalation level from metadata
current_level = complaint.metadata.get("escalation_level", 0)
# Calculate hours overdue
hours_overdue = (timezone.now() - complaint.due_at).total_seconds() / 3600
# Get applicable escalation rules for this hospital, ordered by escalation_level
rules = EscalationRule.objects.filter(
hospital=complaint.hospital, is_active=True, trigger_on_overdue=True
).order_by("escalation_level", "order")
# Filter rules by severity and priority if specified
if complaint.severity:
rules = rules.filter(Q(severity_filter="") | Q(severity_filter=complaint.severity))
if complaint.priority:
rules = rules.filter(Q(priority_filter="") | Q(priority_filter=complaint.priority))
# Find matching rule for next escalation level
matching_rule = None
for rule in rules:
# Check if this is the next escalation level
if rule.escalation_level == current_level + 1:
# Check if we've exceeded trigger hours
if hours_overdue >= rule.trigger_hours_overdue:
# Check if we've exceeded max level
max_level = rule.max_escalation_level
if current_level >= max_level:
logger.info(f"Complaint {complaint_id} has reached max escalation level {max_level}")
return {"status": "max_level_reached", "max_level": max_level, "current_level": current_level}
matching_rule = rule
break
if not matching_rule:
logger.info(
f"No matching escalation rule found for complaint {complaint_id} "
f"(current level: {current_level}, hours overdue: {hours_overdue:.1f})"
)
return {"status": "no_matching_rule", "current_level": current_level}
# Determine escalation target
escalation_target = None
if matching_rule.escalate_to_role == "department_manager":
if complaint.department and complaint.department.manager:
escalation_target = complaint.department.manager
if not escalation_target:
from apps.complaints.services.complaint_service import ComplaintService
escalation_target, fallback_path = ComplaintService.get_escalation_target(complaint)
if escalation_target:
logger.info(
f"Department manager not found for complaint {complaint_id}, "
f"using fallback via {fallback_path}: {escalation_target.get_full_name()}"
)
elif matching_rule.escalate_to_role == "hospital_admin":
# Find hospital admin for this hospital
escalation_target = User.objects.filter(
hospital=complaint.hospital, groups__name="Hospital Admin", is_active=True
).first()
elif matching_rule.escalate_to_role == "px_admin":
# Find PX admin
escalation_target = User.objects.filter(groups__name="PX Admin", is_active=True).first()
elif matching_rule.escalate_to_role == "ceo":
# Find CEO for this hospital
escalation_target = User.objects.filter(
hospital=complaint.hospital, groups__name="CEO", is_active=True
).first()
elif matching_rule.escalate_to_role == "specific_user":
escalation_target = matching_rule.escalate_to_user
if not escalation_target:
logger.warning(
f"Could not find escalation target for rule {matching_rule.name} "
f"({matching_rule.escalate_to_role}) on complaint {complaint_id}"
)
return {"status": "no_target_found", "rule": matching_rule.name, "role": matching_rule.escalate_to_role}
# Check if already assigned to this person to avoid redundant escalation
if complaint.assigned_to and complaint.assigned_to.id == escalation_target.id:
logger.info(
f"Complaint {complaint_id} already assigned to {escalation_target.get_full_name()}, "
f"skipping escalation to same person"
)
return {"status": "already_assigned", "escalated_to": escalation_target.get_full_name()}
# Perform escalation
old_assignee = complaint.assigned_to
complaint.assigned_to = escalation_target
complaint.escalated_at = timezone.now()
# Update metadata with escalation level
complaint.metadata["escalation_level"] = matching_rule.escalation_level
complaint.metadata["last_escalation_rule"] = {
"id": str(matching_rule.id),
"name": matching_rule.name,
"level": matching_rule.escalation_level,
"timestamp": timezone.now().isoformat(),
}
complaint.save(update_fields=["assigned_to", "escalated_at", "metadata"])
# Create update
ComplaintUpdate.objects.create(
complaint=complaint,
update_type="escalation",
message=(
f"Automatically escalated to {escalation_target.get_full_name()} "
f"(Level {matching_rule.escalation_level}, Rule: {matching_rule.name}). "
f"Complaint is {hours_overdue:.1f} hours overdue."
),
created_by=None, # System action
metadata={
"rule_id": str(matching_rule.id),
"rule_name": matching_rule.name,
"escalation_level": matching_rule.escalation_level,
"hours_overdue": hours_overdue,
"old_assignee_id": str(old_assignee.id) if old_assignee else None,
"new_assignee_id": str(escalation_target.id),
},
)
# Send notifications
send_complaint_notification.delay(complaint_id=str(complaint.id), event_type="escalated")
# Log audit
from apps.core.services import create_audit_log
create_audit_log(
event_type="complaint_escalated",
description=f"Complaint automatically escalated to {escalation_target.get_full_name()} (Level {matching_rule.escalation_level})",
content_object=complaint,
metadata={
"rule": matching_rule.name,
"level": matching_rule.escalation_level,
"hours_overdue": hours_overdue,
"escalated_to": escalation_target.get_full_name(),
},
)
logger.info(
f"Escalated complaint {complaint_id} to {escalation_target.get_full_name()} "
f"(Level {matching_rule.escalation_level}) using rule '{matching_rule.name}'"
)
return {
"status": "escalated",
"rule": matching_rule.name,
"level": matching_rule.escalation_level,
"escalated_to": escalation_target.get_full_name(),
"hours_overdue": round(hours_overdue, 2),
}
except Complaint.DoesNotExist:
error_msg = f"Complaint {complaint_id} not found"
logger.error(error_msg)
return {"status": "error", "reason": error_msg}
except Exception as e:
error_msg = f"Error escalating complaint: {str(e)}"
logger.error(error_msg, exc_info=True)
return {"status": "error", "reason": error_msg}
@shared_task
def escalate_after_reminder(complaint_id):
"""
Escalate complaint after reminder if no action taken.
This task is triggered by the SLA reminder task for rules with
reminder_escalation_enabled. It checks if the complaint has had any
activity since the reminder was sent, and escalates if not.
Args:
complaint_id: UUID of the Complaint
Returns:
dict: Result with escalation status
"""
from apps.complaints.models import Complaint, ComplaintUpdate, EscalationRule
try:
complaint = Complaint.objects.select_related("hospital", "department", "assigned_to", "source").get(
id=complaint_id
)
# Check if reminder was sent
if not complaint.reminder_sent_at:
logger.info(f"No reminder sent for complaint {complaint_id}, skipping escalation")
return {"status": "no_reminder_sent"}
# Get SLA config to check reminder-based escalation
sla_config = complaint.get_sla_config()
if not sla_config:
logger.info(f"No SLA config for complaint {complaint_id}, skipping reminder escalation")
return {"status": "no_sla_config"}
# Check if reminder escalation is enabled for this hospital
rules = EscalationRule.objects.filter(
hospital=complaint.hospital, is_active=True, reminder_escalation_enabled=True
).order_by("escalation_level")
# Filter by severity/priority
if complaint.severity:
rules = rules.filter(Q(severity_filter="") | Q(severity_filter=complaint.severity))
if complaint.priority:
rules = rules.filter(Q(priority_filter="") | Q(priority_filter=complaint.priority))
if not rules.exists():
logger.info(f"No reminder escalation rules for complaint {complaint_id}")
return {"status": "no_rules"}
# Get current escalation level
current_level = complaint.metadata.get("escalation_level", 0)
# Find matching rule for next level
matching_rule = None
for rule in rules:
if rule.escalation_level == current_level + 1:
# Calculate time since reminder
hours_since_reminder = (timezone.now() - complaint.reminder_sent_at).total_seconds() / 3600
# Check if enough time has passed since reminder
if hours_since_reminder >= rule.reminder_escalation_hours:
matching_rule = rule
break
if not matching_rule:
logger.info(
f"Reminder escalation not yet triggered for complaint {complaint_id} "
f"(hours since reminder: {(timezone.now() - complaint.reminder_sent_at).total_seconds() / 3600:.1f})"
)
return {
"status": "not_yet_triggered",
"hours_since_reminder": (timezone.now() - complaint.reminder_sent_at).total_seconds() / 3600,
}
# Auto-escalation disabled — manual escalation only
logger.info(
f"Reminder-based auto-escalation skipped for complaint {complaint_id} (auto-escalation disabled)"
)
return {"status": "reminder_escalation_triggered", "rule": matching_rule.name, "escalation_result": result}
except Complaint.DoesNotExist:
error_msg = f"Complaint {complaint_id} not found"
logger.error(error_msg)
return {"status": "error", "reason": error_msg}
except Exception as e:
error_msg = f"Error in reminder escalation: {str(e)}"
logger.error(error_msg, exc_info=True)
return {"status": "error", "reason": error_msg}
@shared_task
def analyze_complaint_with_ai(complaint_id):
@ -1790,33 +1497,6 @@ def get_explanation_sla_config(hospital):
return None
def _notify_max_escalation_reached(explanation):
"""Notify hospital admins and PX staff when explanation escalation has reached max level."""
from apps.complaints.services.complaint_service import ComplaintService
from apps.notifications.services import NotificationService
complaint = explanation.complaint
hospital = complaint.hospital
target_user, _ = ComplaintService.get_escalation_target(complaint, staff=explanation.staff)
if target_user and target_user.email:
try:
NotificationService.send_email(
target_user.email,
subject=f"Explanation Escalation Limit Reached - {complaint.reference_number}",
message=(
f"All escalation levels have been exhausted for explanation request "
f"on complaint {complaint.reference_number}.\n\n"
f"Staff: {explanation.staff.get_full_name() if explanation.staff else 'Unknown'}\n"
f"Hospital: {hospital.name}\n\n"
f"Please take immediate action."
),
related_object=complaint,
)
except Exception as e:
logger.error(f"Failed to send max escalation notification: {e}")
@shared_task
def send_explanation_request_email(explanation_id):
"""
@ -1915,189 +1595,21 @@ def check_overdue_explanation_requests():
Periodic task to check for overdue explanation requests.
Runs every 15 minutes (configured in config/celery.py).
When staff doesn't respond within SLA, creates an explanation request with link for manager.
Follows staff hierarchy via report_to field.
Marks overdue explanations that have passed their SLA deadline.
"""
from apps.complaints.models import ComplaintExplanation
from apps.organizations.models import Staff
now = timezone.now()
# Get explanation requests that are:
# - Not submitted (is_used=False)
# - Email sent (email_sent_at is not null)
# - Past SLA deadline
# - Not yet escalated (escalated_to_manager is null)
overdue_explanations = ComplaintExplanation.objects.filter(
is_used=False, email_sent_at__isnull=False, sla_due_at__lt=now, escalated_to_manager__isnull=True
).select_related("complaint", "staff", "staff__department")
escalated_count = 0
is_used=False, email_sent_at__isnull=False, sla_due_at__lt=now, is_overdue=False
).select_related("complaint")
for explanation in overdue_explanations:
# Mark as overdue
if not explanation.is_overdue:
explanation.is_overdue = True
explanation.save(update_fields=["is_overdue"])
explanation.is_overdue = True
explanation.save(update_fields=["is_overdue"])
# Get SLA config
sla_config = get_explanation_sla_config(explanation.complaint.hospital)
# Check if auto-escalation is enabled
if not sla_config or not sla_config.auto_escalate_enabled:
logger.info(
f"Auto-escalation disabled for explanation {explanation.id}, "
f"hospital {explanation.complaint.hospital.name}"
)
continue
# Get current escalation level
current_level = explanation.metadata.get("escalation_level", 0)
# Check max escalation level
max_level = sla_config.max_escalation_levels if sla_config else 3
if current_level >= max_level:
logger.info(f"Explanation {explanation.id} reached max escalation level {max_level}")
_notify_max_escalation_reached(explanation)
continue
# Calculate hours overdue
hours_overdue = (now - explanation.sla_due_at).total_seconds() / 3600
# Check if we should escalate now
escalation_delay = sla_config.escalation_hours_overdue if sla_config else 0
if hours_overdue < escalation_delay:
logger.info(
f"Explanation {explanation.id} overdue by {hours_overdue:.1f}h, "
f"waiting for escalation delay of {escalation_delay}h"
)
continue
# Ensure reminders have been sent before escalating
reminders_required = 2 if (sla_config and sla_config.second_reminder_enabled) else 1
if reminders_required >= 1 and not explanation.reminder_sent_at:
logger.info(
f"Explanation {explanation.id} overdue but first reminder not sent yet, "
f"skipping escalation (reminders required: {reminders_required})"
)
continue
if reminders_required >= 2 and not explanation.second_reminder_sent_at:
logger.info(
f"Explanation {explanation.id} overdue but second reminder not sent yet, "
f"skipping escalation (reminders required: {reminders_required})"
)
continue
# Determine escalation target via fallback chain
from apps.complaints.services.complaint_service import ComplaintService
target_user, fallback_path = ComplaintService.get_escalation_target(
explanation.complaint, staff=explanation.staff
)
if not target_user:
logger.warning(
f"No escalation target found for explanation {explanation.id} "
f"(staff: {explanation.staff}, fallback_path: {fallback_path})"
)
continue
# Find or create Staff record for the target user
from apps.organizations.models import Staff
manager = Staff.objects.filter(user=target_user).first()
if not manager:
logger.warning(
f"Escalation target user {target_user.id} has no Staff record, "
f"cannot create explanation request for complaint {explanation.complaint.id}"
)
continue
# Check if manager already has an active explanation request for this complaint
existing_manager_explanation = ComplaintExplanation.objects.filter(
complaint=explanation.complaint, staff=manager
).first()
if existing_manager_explanation and not existing_manager_explanation.is_used:
logger.info(
f"Manager {manager.get_full_name()} already has an active explanation "
f"request for complaint {explanation.complaint.id}, skipping escalation"
)
explanation.escalated_to_manager = existing_manager_explanation
explanation.escalated_at = now
explanation.metadata["escalation_level"] = current_level + 1
explanation.metadata["escalation_fallback_path"] = fallback_path
explanation.save(update_fields=["escalated_to_manager", "escalated_at", "metadata"])
escalated_count += 1
continue
if existing_manager_explanation and existing_manager_explanation.is_used:
logger.info(
f"Manager {manager.get_full_name()} already submitted an explanation "
f"for complaint {explanation.complaint.id}, skipping escalation"
)
explanation.escalated_to_manager = existing_manager_explanation
explanation.escalated_at = now
explanation.metadata["escalation_level"] = current_level + 1
explanation.metadata["escalation_fallback_path"] = fallback_path
explanation.save(update_fields=["escalated_to_manager", "escalated_at", "metadata"])
escalated_count += 1
continue
# Create new explanation request for manager with token/link
import secrets
manager_token = secrets.token_urlsafe(32)
# Calculate new SLA deadline for manager
sla_hours = sla_config.response_hours if sla_config else 48
new_explanation = ComplaintExplanation.objects.create(
complaint=explanation.complaint,
staff=manager,
token=manager_token,
explanation="",
requested_by=explanation.requested_by,
request_message=(
f"ESCALATED: {explanation.staff.get_full_name()} did not provide an explanation "
f"within the SLA deadline ({sla_hours} hours). "
f"As their manager, please provide your explanation about this complaint."
),
submitted_via="email_link",
sla_due_at=now + timezone.timedelta(hours=sla_hours),
email_sent_at=now,
metadata={
"escalated_from_explanation_id": str(explanation.id),
"escalation_level": current_level + 1,
"original_staff_id": str(explanation.staff.id),
"original_staff_name": explanation.staff.get_full_name(),
"is_escalation": True,
"escalation_fallback_path": fallback_path,
},
)
# Link old explanation to new one
explanation.escalated_to_manager = new_explanation
explanation.escalated_at = now
explanation.metadata["escalation_level"] = current_level + 1
explanation.metadata["escalation_fallback_path"] = fallback_path
explanation.save(update_fields=["escalated_to_manager", "escalated_at", "metadata"])
# Send email to manager with link
send_explanation_request_email.delay(str(new_explanation.id))
escalated_count += 1
logger.info(
f"Escalated explanation request {explanation.id} to {target_user.get_full_name()} "
f"(Level {current_level + 1}, path: {fallback_path})"
)
return {"overdue_count": overdue_explanations.count(), "escalated_count": escalated_count}
return {"overdue_count": overdue_explanations.count()}
@shared_task
@ -2117,13 +1629,16 @@ def send_explanation_reminders():
# First reminders: not yet reminded
explanations = ComplaintExplanation.objects.filter(
is_used=False, email_sent_at__isnull=False, reminder_sent_at__isnull=True, escalated_to_manager__isnull=True
is_used=False, email_sent_at__isnull=False, reminder_sent_at__isnull=True
).select_related("complaint", "staff")
reminder_count = 0
second_reminder_count = 0
for explanation in explanations:
if not explanation.sla_due_at:
continue
sla_config = get_explanation_sla_config(explanation.complaint.hospital)
reminder_hours_before = sla_config.reminder_hours_before if sla_config else 12
@ -2180,10 +1695,12 @@ def send_explanation_reminders():
email_sent_at__isnull=False,
reminder_sent_at__isnull=False,
second_reminder_sent_at__isnull=True,
escalated_to_manager__isnull=True,
).select_related("complaint", "staff")
for explanation in second_reminder_explanations:
if not explanation.sla_due_at:
continue
sla_config = get_explanation_sla_config(explanation.complaint.hospital)
if not sla_config or not sla_config.second_reminder_enabled:
@ -2302,32 +1819,25 @@ def send_sla_reminders():
skipped_count = 0
for complaint in active_complaints:
# Skip complaints without a deadline
if not complaint.due_at:
skipped_count += 1
continue
# Get SLA config for this complaint (source-based or severity/priority-based)
sla_config = complaint.get_sla_config()
# Calculate first reminder timing
# Calculate first reminder timing (hours before deadline)
if sla_config:
# Use config's helper method to get hours after creation
first_reminder_hours_after = sla_config.get_first_reminder_hours_after(complaint.created_at)
second_reminder_hours_after = sla_config.get_second_reminder_hours_after(complaint.created_at)
first_reminder_hours_before = sla_config.reminder_hours_before
second_reminder_hours_before = sla_config.second_reminder_hours_before
else:
# Calculate SLA hours from due_at and created_at
if complaint.due_at and complaint.created_at:
sla_hours = int((complaint.due_at - complaint.created_at).total_seconds() / 3600)
else:
sla_hours = 72 # Default 72 hours
first_reminder_hours_after = sla_hours - 24 # 24 hours before deadline
second_reminder_hours_after = sla_hours - 6 # 6 hours before deadline
first_reminder_hours_before = 24
second_reminder_hours_before = 6
# Check if we should send FIRST reminder now
if complaint.reminder_sent_at is None:
# Calculate when reminder should be sent
if first_reminder_hours_after > 0:
# Source-based: hours after creation
reminder_time = complaint.created_at + timezone.timedelta(hours=first_reminder_hours_after)
else:
# Legacy: hours before deadline
reminder_time = complaint.due_at - timezone.timedelta(hours=24)
if complaint.reminder_sent_at is None and first_reminder_hours_before > 0:
reminder_time = complaint.due_at - timezone.timedelta(hours=first_reminder_hours_before)
if now >= reminder_time:
# Determine recipient
@ -2480,22 +1990,13 @@ def send_sla_reminders():
f"({int(hours_remaining)} hours remaining)"
)
# Trigger reminder-based escalation check
escalate_after_reminder.delay(str(complaint.id))
except Exception as e:
logger.error(f"Failed to send SLA reminder for complaint {complaint.id}: {str(e)}")
skipped_count += 1
# Check if we should send SECOND reminder now
elif complaint.second_reminder_sent_at is None and second_reminder_hours_after > 0:
# Calculate when second reminder should be sent
if second_reminder_hours_after > 0:
# Source-based: hours after creation
second_reminder_time = complaint.created_at + timezone.timedelta(hours=second_reminder_hours_after)
else:
# Legacy: hours before deadline
second_reminder_time = complaint.due_at - timezone.timedelta(hours=6)
elif complaint.second_reminder_sent_at is None and second_reminder_hours_before > 0:
second_reminder_time = complaint.due_at - timezone.timedelta(hours=second_reminder_hours_before)
if now >= second_reminder_time:
# Determine recipient
@ -2649,9 +2150,6 @@ def send_sla_reminders():
f"({int(hours_remaining)} hours remaining)"
)
# Trigger reminder-based escalation check (more urgent now)
escalate_after_reminder.delay(str(complaint.id))
except Exception as e:
logger.error(f"Failed to send second SLA reminder for complaint {complaint.id}: {str(e)}")
skipped_count += 1
@ -2768,7 +2266,7 @@ def notify_admins_new_complaint(complaint_id):
"""
from .models import Complaint, OnCallAdminSchedule
from apps.notifications.services import NotificationService
from django.contrib.sites.shortcuts import get_current_site
from django.conf import settings
from django.urls import reverse
try:
@ -2798,13 +2296,8 @@ def notify_admins_new_complaint(complaint_id):
return {"status": "warning", "reason": "no_admins_found", "complaint_id": str(complaint_id)}
# Build complaint URL
try:
site = get_current_site(None)
domain = site.domain
except:
domain = "localhost:8000"
complaint_url = f"https://{domain}{reverse('complaints:complaint_detail', kwargs={'pk': complaint_id})}"
base = settings.SITE_URL.rstrip("/")
complaint_url = f"{base}{reverse('complaints:complaint_detail', kwargs={'pk': complaint_id})}"
# Get severity and priority display
severity_display = (
@ -3005,7 +2498,7 @@ def notify_staff_new_item(item_type, item_id):
Returns:
dict: Result with notification status and details
"""
from django.contrib.sites.shortcuts import get_current_site
from django.conf import settings
from django.urls import reverse
from apps.notifications.services import NotificationService
from apps.accounts.models import User
@ -3154,13 +2647,8 @@ def notify_staff_new_item(item_type, item_id):
return {"status": "warning", "reason": "no_admins_found", "item_type": item_type, "item_id": str(item_id)}
# Build URL
try:
site = get_current_site(None)
domain = site.domain
except:
domain = "localhost:8000"
item_url = f"https://{domain}{reverse(config['url_name'], kwargs={'pk': item_id})}"
base = settings.SITE_URL.rstrip("/")
item_url = f"{base}{reverse(config['url_name'], kwargs={'pk': item_id})}"
# Determine priority/high priority
is_high_priority = False
@ -3841,42 +3329,89 @@ def link_inquiry_patient(inquiry_id, phone=None):
@shared_task
def send_complaint_creation_sms_task(complaint_id):
"""Send the complaint-received SMS (backgrounded from send_complaint_creation_sms)."""
"""Send the complaint-received SMS/email (backgrounded from send_complaint_creation_sms)."""
from apps.complaints.models import Complaint, ComplaintUpdate
from apps.notifications.services import NotificationService
from apps.notifications.services import NotificationService, get_email_header_html
instance = Complaint.objects.filter(pk=complaint_id).first()
if not instance or not instance.contact_phone:
if not instance or (not instance.contact_phone and not instance.contact_email):
return
try:
tracking_url = instance.get_tracking_url()
sms_message = (
f"PX360: Your complaint #{instance.reference_number} has been received. "
f"Track: {tracking_url}"
)
notification_log = NotificationService.send_sms(
phone=instance.contact_phone,
message=sms_message,
related_object=instance,
metadata={
"notification_type": "complaint_created",
"reference_number": instance.reference_number,
"tracking_url": tracking_url,
"language": "en",
},
)
logger.info(f"Creation SMS sent to {instance.contact_phone} for complaint #{instance.id}")
sms_log = None
email_log = None
if instance.contact_phone:
sms_message = (
f"PX360: Your complaint #{instance.reference_number} has been received. "
f"Track: {tracking_url}"
)
sms_log = NotificationService.send_sms(
phone=instance.contact_phone,
message=sms_message,
related_object=instance,
metadata={
"notification_type": "complaint_created",
"reference_number": instance.reference_number,
"tracking_url": tracking_url,
"language": "en",
},
)
logger.info(f"Creation SMS sent to {instance.contact_phone} for complaint #{instance.id}")
if instance.contact_email:
email_subject = f"PX360: Your complaint #{instance.reference_number} has been received"
email_body = (
f"Dear Valued Patient,\n\n"
f"Your complaint #{instance.reference_number} has been received and is now being tracked.\n\n"
f"To view the status and updates, please visit:\n{tracking_url}\n\n"
f"Thank you for your feedback.\n\n"
f"Reference: {instance.reference_number}\n"
f"This is an automated message from PX 360."
)
email_log = NotificationService.send_email(
email=instance.contact_email,
subject=email_subject,
message=email_body,
html_message=f"""
<div style="font-family: 'Segoe UI', Tahoma, sans-serif; max-width: 600px; margin: 0 auto; border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
{get_email_header_html()}
<div style="padding: 20px;">
<h2 style="color: #005696; font-size: 18px; margin: 0 0 12px 0;">Complaint Received</h2>
<p style="margin: 0 0 12px 0;">Dear Valued Patient,</p>
<p style="margin: 0 0 12px 0;">Your complaint <strong>#{instance.reference_number}</strong> has been received and is now being tracked.</p>
<p style="margin: 0 0 12px 0;">To view the status and updates, please click the link below:</p>
<div style="text-align: center; margin: 20px 0;">
<a href="{tracking_url}" style="background: #005696; color: white; padding: 10px 24px; border-radius: 8px; text-decoration: none; font-weight: 600;">Track Your Complaint</a>
</div>
<p style="margin: 0 0 6px 0; color: #6b7280; font-size: 13px;">Reference: {instance.reference_number}</p>
</div>
</div>
""",
related_object=instance,
metadata={
"notification_type": "complaint_created_email",
"reference_number": instance.reference_number,
"tracking_url": tracking_url,
},
)
logger.info(f"Creation email sent to {instance.contact_email} for complaint #{instance.id}")
ComplaintUpdate.objects.create(
complaint=instance,
update_type="communication",
message="SMS notification sent to complainant: Your complaint has been received",
message=(
f"Notification sent to complainant: Complaint received "
f"(SMS: {bool(instance.contact_phone)}, Email: {bool(instance.contact_email)})"
),
metadata={
"notification_type": "complaint_created",
"notification_log_id": str(notification_log.id) if notification_log else None,
"sms_log_id": str(sms_log.id) if sms_log else None,
"email_log_id": str(email_log.id) if email_log else None,
},
)
except Exception as e:
logger.error(f"Failed to send creation SMS for complaint #{instance.id}: {e}")
logger.error(f"Failed to send creation notification for complaint #{instance.id}: {e}")
@shared_task
@ -3973,7 +3508,7 @@ def send_complaint_status_change_task(complaint_id, old_status, new_status):
@shared_task
def notify_champion_on_dept_assignment_task(involved_department_id):
"""Email the department champion when a complaint is sent to their department (off the signal)."""
from django.contrib.sites.models import Site
from django.conf import settings
from apps.complaints.models import ComplaintInvolvedDepartment
from apps.notifications.services import NotificationService, get_email_header_html
@ -3995,9 +3530,8 @@ def notify_champion_on_dept_assignment_task(involved_department_id):
try:
complaint = instance.complaint
department = instance.department
current_site = Site.objects.get_current()
domain = current_site.domain if current_site else "px360.tenhal.sa"
department_url = f"https://{domain}/organizations/departments/{department.pk}/"
base = settings.SITE_URL.rstrip("/")
department_url = f"{base}/organizations/departments/{department.pk}/"
NotificationService.send_email(
recipient=champion_user.email,
@ -4044,3 +3578,89 @@ PX360 Team""",
)
except Exception as e:
logger.error(f"Failed to send champion notification for ComplaintInvolvedDepartment #{instance.id}: {e}")
@shared_task
def send_department_notification_task(payload):
"""Send the champion/manager email + SMS for a complaint routed to a department.
Offloaded from `complaint_send_to` so the HTTP response returns immediately.
Best-effort: each send is wrapped in try/except and logged on failure; the
complaint's DB state (involvement, explanation tokens) is already persisted
synchronously by the view before this task is dispatched.
Args:
payload (dict): {
complaint_id, reference_number, title, department_name, note,
email_subject, email_body, host,
targets: [ {email, phone, link, label, display_name}, ... ]
}
"""
from apps.complaints.models import Complaint
from apps.notifications.services import NotificationService, get_email_header_html
complaint = Complaint.objects.filter(pk=payload.get("complaint_id")).first()
# Complaint may have been deleted; nothing to notify about.
if complaint is None:
logger.warning("send_department_notification_task: complaint not found, skipping")
return {"emailed": 0, "smsed": 0}
reference_number = payload.get("reference_number", "")
title = payload.get("title", "")
department_name = payload.get("department_name", "")
note = payload.get("note", "")
email_subject = payload.get("email_subject") or f"Complaint Sent to Department - {reference_number}"
email_body = payload.get("email_body") or (
f"Complaint #{reference_number} has been sent to your department ({department_name})."
)
emailed = 0
smsed = 0
for target in payload.get("targets", []):
email = target.get("email") or ""
phone = target.get("phone") or ""
review_link = target.get("link") or ""
label = target.get("label") or ""
if email:
try:
NotificationService.send_email(
email=email,
subject=email_subject,
message=email_body + f"\n\n{review_link}",
html_message=f"""
<div style="font-family: 'Segoe UI', Tahoma, sans-serif; max-width: 600px; margin: 0 auto; border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
{get_email_header_html()}
<div style="padding: 20px;">
<h2 style="color: #005696; font-size: 18px; margin: 0 0 12px 0;">Complaint Sent to Department</h2>
<p>Complaint <strong>#{reference_number}</strong> has been sent to your department <strong>({department_name})</strong>.</p>
<p><strong>Title:</strong> {title or 'N/A'}</p>
{f'<p><strong>Note:</strong> {note}</p>' if note else ''}
<p><strong>Role:</strong> {label}</p>
<p><a href="{review_link}">Review / Respond</a></p>
</div>
</div>
""",
related_object=complaint,
)
emailed += 1
except Exception as e:
logger.warning(f"Failed to email {email} for complaint #{reference_number}: {e}")
if phone:
try:
NotificationService.send_sms(
phone,
f"PX360: Complaint #{reference_number} sent to {department_name}. Review: {review_link}",
related_object=complaint,
)
smsed += 1
except Exception as e:
logger.warning(f"Failed to SMS {phone} for complaint #{reference_number}: {e}")
logger.info(
f"Department notification task for complaint #{reference_number}: "
f"{emailed} emailed, {smsed} smsed"
)
return {"emailed": emailed, "smsed": smsed}

238
apps/complaints/tests.py
View File

@ -194,3 +194,241 @@ class PublicComplaintViewTests(TestCase):
self.assertEqual(complaint.contact_email, "john@example.com")
self.assertEqual(complaint.staff_name, "Dr. Smith")
self.assertEqual(complaint.expected_result, "Quick resolution")
class DepartmentNotificationTaskTests(TestCase):
"""The send-to-department notifications run as a Celery task (offloaded from the view)."""
def setUp(self):
from django.contrib.auth import get_user_model
from apps.organizations.models import Staff
User = get_user_model()
self.hospital = Hospital.objects.create(name="H1", code="H1", status="active")
self.complaint = Complaint.objects.create(
hospital=self.hospital,
title="T",
description="D",
status="in_progress",
reference_number="REF-TEST-1",
)
self.staff_user = User.objects.create_user(username="champ@x", email="champ@x", password="p")
self.staff = Staff.objects.create(
hospital=self.hospital,
first_name="Champ",
last_name="X",
status="active",
staff_type="other",
job_title="C",
employee_id="EMP-1",
user=self.staff_user,
email="champ@x",
)
def _payload(self, **overrides):
payload = {
"complaint_id": str(self.complaint.id),
"reference_number": self.complaint.reference_number,
"title": self.complaint.title,
"department_name": "Emergency",
"note": "",
"email_subject": "",
"email_body": "",
"targets": [
{
"email": "champ@x",
"phone": "+966500000000",
"link": "https://example.com/explain/token/",
"label": "Champion",
"display_name": "Champ X",
}
],
}
payload.update(overrides)
return payload
def test_task_sends_email_and_sms_to_targets(self):
from unittest.mock import patch
from apps.complaints.tasks import send_department_notification_task
with patch("apps.notifications.services.NotificationService.send_email") as mock_email, \
patch("apps.notifications.services.NotificationService.send_sms") as mock_sms:
result = send_department_notification_task.apply(args=[self._payload()]).get()
self.assertEqual(result, {"emailed": 1, "smsed": 1})
mock_email.assert_called_once()
self.assertEqual(mock_email.call_args.kwargs["email"], "champ@x")
mock_sms.assert_called_once()
def test_task_skips_missing_complaint(self):
import uuid
from apps.complaints.tasks import send_department_notification_task
payload = self._payload(complaint_id=str(uuid.uuid4()))
result = send_department_notification_task.apply(args=[payload]).get()
self.assertEqual(result, {"emailed": 0, "smsed": 0})
def test_task_continues_if_one_send_fails(self):
from unittest.mock import patch
from apps.complaints.tasks import send_department_notification_task
payload = self._payload(targets=[
{"email": "a@x", "phone": "", "link": "l", "label": "Champion", "display_name": "A"},
{"email": "", "phone": "+9665", "link": "l", "label": "Manager", "display_name": "B"},
])
with patch("apps.notifications.services.NotificationService.send_email", side_effect=Exception("smtp down")), \
patch("apps.notifications.services.NotificationService.send_sms") as mock_sms:
result = send_department_notification_task.apply(args=[payload]).get()
# Email failed (best-effort), SMS still sent; task did not raise.
self.assertEqual(result, {"emailed": 0, "smsed": 1})
mock_sms.assert_called_once()
class InvestigationReviewOtpTests(TestCase):
"""The investigation-review verification code goes to the logged-in reviewer."""
def setUp(self):
from django.contrib.auth import get_user_model
from apps.organizations.models import Staff
from apps.complaints.models import ComplaintExplanation, ChampionInvestigation
User = get_user_model()
self.hospital = Hospital.objects.create(name="H1", code="H1", status="active")
self.complaint = Complaint.objects.create(
hospital=self.hospital, title="T", description="D",
status="in_progress", reference_number="REF-INV-1",
)
# Manager = investigator of record (explanation.staff / investigation.champion)
self.manager_user = User.objects.create_user(username="mgr@x", email="mgr@x", password="p")
self.manager = Staff.objects.create(
hospital=self.hospital, first_name="Mgr", last_name="X",
status="active", staff_type="other", job_title="M",
employee_id="EMP-M", user=self.manager_user, email="mgr@x",
)
# Champion = the actual reviewer (logged in)
self.champ_user = User.objects.create_user(username="champ@x", email="champ@x", password="p")
self.champion = Staff.objects.create(
hospital=self.hospital, first_name="Champ", last_name="X",
status="active", staff_type="other", job_title="C",
employee_id="EMP-C", user=self.champ_user, email="champ@x",
)
self.token = "manager-token-abc"
self.explanation = ComplaintExplanation.objects.create(
complaint=self.complaint, staff=self.manager, token=self.token,
)
self.investigation = ChampionInvestigation.objects.create(
complaint=self.complaint, explanation=self.explanation,
champion=self.manager, status="answers_received",
)
def test_otp_goes_to_logged_in_reviewer_not_investigator_of_record(self):
from unittest.mock import patch, Mock
self.client.force_login(self.champ_user)
url = reverse("complaints:champion_review_answers", args=[self.complaint.id, self.token])
with patch("apps.notifications.services.NotificationService.send_email",
return_value=Mock(status="sent")) as mock_email, \
patch("apps.notifications.services.NotificationService.send_sms",
return_value=Mock(status="sent")) as mock_sms:
self.client.post(url, {
"action": "send_code",
"final_reply": "My final reply.",
"consent": "on",
})
# The code MUST go to the logged-in champion, not the manager of record.
mock_email.assert_called_once()
self.assertEqual(mock_email.call_args.kwargs["email"], "champ@x")
# Champion has no phone on file -> SMS not used (and manager's phone not pulled in).
mock_sms.assert_not_called()
def test_send_code_persists_assessment_draft(self):
"""The assessment must be persisted at send_code so a return visit keeps it.
Regression: previously only otp_code/otp_sent_at were saved, so leaving the
page and coming back lost the final reply / findings, and verify_submit then
rejected the submission as an empty assessment.
"""
from unittest.mock import patch, Mock
self.client.force_login(self.champ_user)
url = reverse("complaints:champion_review_answers", args=[self.complaint.id, self.token])
with patch("apps.notifications.services.NotificationService.send_email",
return_value=Mock(status="sent")), \
patch("apps.notifications.services.NotificationService.send_sms",
return_value=Mock(status="sent")):
self.client.post(url, {
"action": "send_code",
"final_reply": "Persisted final reply.",
"negligence_finding": "no",
"policy_issue_finding": "yes",
"requires_improvement_project": "yes",
"improvement_project_note": "Need a project.",
"consent": "on",
})
self.investigation.refresh_from_db()
self.assertEqual(self.investigation.final_reply, "Persisted final reply.")
self.assertEqual(self.investigation.negligence_finding, "no")
self.assertEqual(self.investigation.policy_issue_finding, "yes")
self.assertEqual(self.investigation.requires_improvement_project, "yes")
self.assertEqual(self.investigation.improvement_project_note, "Need a project.")
self.assertTrue(self.investigation.otp_code)
class InquiryTimestampTests(TestCase):
"""resolved_at / closed_at are auto-stamped on status transition."""
def setUp(self):
self.hospital = Hospital.objects.create(name="H1", code="H1", status="active")
self.inquiry = Inquiry.objects.create(
hospital=self.hospital,
subject="Test",
message="M",
status="in_progress",
)
def test_resolved_at_stamped_on_resolve(self):
self.inquiry.status = "resolved"
self.inquiry.save()
self.inquiry.refresh_from_db()
self.assertIsNotNone(self.inquiry.resolved_at)
self.assertIsNone(self.inquiry.closed_at)
def test_closed_at_stamped_on_close(self):
self.inquiry.status = "closed"
self.inquiry.save()
self.inquiry.refresh_from_db()
self.assertIsNotNone(self.inquiry.closed_at)
def test_reopen_preserves_timestamps(self):
self.inquiry.status = "resolved"
self.inquiry.save()
stamped = self.inquiry.resolved_at
self.inquiry.status = "in_progress"
self.inquiry.save()
self.inquiry.refresh_from_db()
self.assertEqual(self.inquiry.resolved_at, stamped)
def test_reresolve_updates_timestamp(self):
self.inquiry.status = "resolved"
self.inquiry.save()
first = self.inquiry.resolved_at
self.inquiry.status = "in_progress"
self.inquiry.save()
self.inquiry.status = "resolved"
self.inquiry.save()
self.inquiry.refresh_from_db()
self.assertGreater(self.inquiry.resolved_at, first)
def test_resolved_by_stamped_from_acting_user(self):
from django.contrib.auth import get_user_model
User = get_user_model()
resolver = User.objects.create_user(username="resolver@x", email="resolver@x", password="p")
self.inquiry._acting_user = resolver
self.inquiry.status = "resolved"
self.inquiry.save()
self.inquiry.refresh_from_db()
self.assertEqual(self.inquiry.resolved_by, resolver)

463
apps/complaints/ui_views.py
View File

@ -633,19 +633,35 @@ def complaint_detail(request, pk):
complaint_ct = ContentType.objects.get_for_model(Complaint)
px_actions = PXAction.objects.filter(content_type=complaint_ct, object_id=complaint.id).order_by("-created_at")
assignable_users = User.objects.filter(is_active=True)
assignable_users = User.objects.filter(
is_active=True,
groups__name__in=["PX Employee", "PX Admin", "PX Management"],
)
if complaint.hospital:
assignable_users = assignable_users.filter(hospital=complaint.hospital)
assignable_users = assignable_users.distinct().order_by("first_name", "last_name")
hospital_departments = []
hospital_departments = Department.objects.none()
if complaint.hospital:
from django.db.models import Q
hospital_departments = Department.objects.filter(
hospital=complaint.hospital, status="active",
).filter(
Q(champion__isnull=False) | Q(manager__isnull=False)
).order_by("name")
hospital_departments = (
Department.objects.filter(
hospital=complaint.hospital, status="active",
)
.filter(Q(champion__isnull=False) | Q(manager__isnull=False))
.select_related("champion", "manager", "manager__staff_profile")
.order_by("name")
)
# Departments the complaint hasn't been sent to yet (drives the send-to-dept modal).
# Filter to only those the send endpoint can actually deliver to (matches
# get_champion_and_manager — closes the manager-with-no-email hole).
from apps.organizations.department_contacts import has_contact_target
available_departments = hospital_departments.exclude(
pk__in=complaint.involved_departments.values_list("department_id", flat=True)
)
available_departments = [d for d in available_departments if has_contact_target(d)]
if complaint.is_active_status and not complaint.is_overdue:
complaint.check_overdue()
@ -736,12 +752,6 @@ def complaint_detail(request, pk):
or (complaint.assigned_to == user)
),
"can_admin": user.is_px_admin() or (user.is_hospital_admin() and user.hospital == complaint.hospital),
"can_review_dept_response": (
user.is_px_admin()
or user.is_hospital_admin()
or user.is_px_management()
or user.is_px_employee()
),
"is_active_status": complaint.is_active_status,
"workflow_steps": {
"activated": complaint.activated_at is not None,
@ -791,6 +801,7 @@ def complaint_detail(request, pk):
and not complaint.involved_departments.filter(department=complaint.department).exists()
),
"hospital_departments": hospital_departments,
"available_departments": available_departments,
"involved_department_form": ComplaintInvolvedDepartmentForm(complaint=complaint, user=user),
"workflow_log": build_workflow_log(complaint),
"involved_staff_form": ComplaintInvolvedStaffForm(complaint=complaint, user=user),
@ -1108,6 +1119,7 @@ def complaint_send_to(request, pk):
email_subject = request.POST.get("email_subject", "").strip()
email_body = request.POST.get("email_body", "").strip()
notify_targets = []
try:
if recipient_type == "person":
person_id = request.POST.get("person_id")
@ -1271,39 +1283,16 @@ def complaint_send_to(request, pk):
fallback_link = f"https://{host}/complaints/{complaint.pk}/"
review_link = link or fallback_link
if email:
send_subject = email_subject or f"Complaint Sent to Department - {complaint.reference_number}"
send_body = email_body or (
f"Complaint #{complaint.reference_number} has been sent to your department ({department.name})."
)
NotificationService.send_email(
email=email,
subject=send_subject,
message=send_body + f"\n\n{review_link}",
html_message=f"""
<div style="font-family: 'Segoe UI', Tahoma, sans-serif; max-width: 600px; margin: 0 auto; border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
{get_email_header_html()}
<div style="padding: 20px;">
<h2 style="color: #005696; font-size: 18px; margin: 0 0 12px 0;">Complaint Sent to Department</h2>
<p>Complaint <strong>#{complaint.reference_number}</strong> has been sent to your department <strong>({department.name})</strong>.</p>
<p><strong>Title:</strong> {complaint.title or 'N/A'}</p>
{f'<p><strong>Note:</strong> {note}</p>' if note else ''}
<p><strong>Role:</strong> {label}</p>
<p><a href="{review_link}">Review / Respond</a></p>
</div>
</div>
""",
related_object=complaint,
)
if phone:
try:
NotificationService.send_sms(
phone,
f"PX360: Complaint #{complaint.reference_number} sent to {department.name}. Review: {review_link}",
related_object=complaint,
)
except Exception:
pass
# Collect for async notification — email + SMS are sent by a Celery task
# (send_department_notification_task) so this request stays fast.
if email or phone:
notify_targets.append({
"email": email,
"phone": phone,
"link": review_link,
"label": label,
"display_name": display_name,
})
notified.append(f"{display_name} ({label})")
@ -1348,6 +1337,27 @@ def complaint_send_to(request, pk):
"explanation_requested", "explanation_requested_at",
])
# Offload the champion/manager email + SMS to a Celery task (slow network
# round-trips) so the HTTP response returns immediately. Best-effort.
if notify_targets:
try:
from .tasks import send_department_notification_task
send_department_notification_task.delay({
"complaint_id": str(complaint.id),
"reference_number": complaint.reference_number,
"title": complaint.title,
"department_name": department.name,
"note": note,
"email_subject": email_subject,
"email_body": email_body,
"targets": notify_targets,
})
except Exception as e:
logger.error(
f"Failed to dispatch department notification task for "
f"complaint #{complaint.reference_number}: {e}"
)
return JsonResponse({
"success": True,
"message": message,
@ -2001,6 +2011,11 @@ def complaint_escalate(request, pk):
)
return redirect("complaints:complaint_detail", pk=pk)
# Complaint must be activated before it can be escalated
if not complaint.activated_at:
messages.error(request, "Activate the complaint before escalating it.")
return redirect("complaints:complaint_detail", pk=pk)
# Check permission
user = request.user
if not (
@ -2833,12 +2848,6 @@ def inquiry_detail(request, pk):
and user.department in [inquiry.department, inquiry.outgoing_department]
)
),
"can_review_dept_response": (
user.is_px_admin()
or user.is_hospital_admin()
or user.is_px_management()
or user.is_px_employee()
),
"can_send_reminder": (
user.is_px_admin()
or user.is_hospital_admin()
@ -3348,6 +3357,7 @@ def inquiry_change_status(request, pk):
messages.error(request, "Please add a response before resolving.")
return redirect("inquiries:inquiry_detail", pk=pk)
inquiry._acting_user = request.user
inquiry.save()
# Create update
@ -3479,6 +3489,7 @@ def inquiry_respond(request, pk):
inquiry.responded_at = timezone.now()
inquiry.responded_by = request.user
inquiry.status = "resolved"
inquiry._acting_user = request.user
inquiry.save()
InquiryUpdate.objects.create(
@ -4020,10 +4031,6 @@ def inquiry_department_response(request, pk):
inquiry.department_responded_at = timezone.now()
inquiry.department_responded_by = request.user
inquiry.dept_response_is_overdue = False
inquiry.dept_response_acceptance_status = "pending"
inquiry.dept_response_accepted_by = None
inquiry.dept_response_accepted_at = None
inquiry.dept_response_acceptance_notes = ""
inquiry.save()
try:
@ -4102,136 +4109,6 @@ Generate a JSON response with:
return render(request, "complaints/inquiry_department_response.html", context)
@login_required
@require_http_methods(["POST"])
def inquiry_review_dept_response(request, pk):
from .models import Inquiry, InquiryUpdate
inquiry = get_object_or_404(Inquiry, pk=pk)
user = request.user
if not (
user.is_px_admin() or user.is_hospital_admin()
or user.is_px_management() or user.is_px_employee()
):
messages.error(request, "You don't have permission to review department responses.")
return redirect("inquiries:inquiry_detail", pk=pk)
if not inquiry.department_responded_at:
messages.error(request, "No department response to review.")
return redirect("inquiries:inquiry_detail", pk=pk)
status = request.POST.get("acceptance_status")
if status not in ("acceptable", "not_acceptable"):
messages.error(request, "Invalid acceptance status.")
return redirect("inquiries:inquiry_detail", pk=pk)
notes = request.POST.get("acceptance_notes", "").strip()
if status == "not_acceptable":
inquiry.dept_response_acceptance_status = "not_acceptable"
inquiry.dept_response_accepted_by = user
inquiry.dept_response_accepted_at = timezone.now()
inquiry.dept_response_acceptance_notes = notes
inquiry.department_response_en = ""
inquiry.department_response_ar = ""
inquiry.department_response_summary_en = ""
inquiry.department_response_summary_ar = ""
inquiry.department_responded_at = None
inquiry.department_responded_by = None
inquiry.save(
update_fields=[
"dept_response_acceptance_status",
"dept_response_accepted_by",
"dept_response_accepted_at",
"dept_response_acceptance_notes",
"department_response_en",
"department_response_ar",
"department_response_summary_en",
"department_response_summary_ar",
"department_responded_at",
"department_responded_by",
]
)
dept = inquiry.outgoing_department or inquiry.transferred_to_department
if dept and dept.champion and dept.champion.user and dept.champion.user.email:
try:
from apps.notifications.services import NotificationService, get_email_header_html
NotificationService.send_email(
email=dept.champion.user.email,
subject=f"Action Required: Inquiry #{inquiry.reference_number} - Response Rejected",
message=(
f"Your department's response for inquiry #{inquiry.reference_number} has been rejected.\n\n"
f"Reason: {notes}\n\n"
f"Please revise and resubmit your response."
),
html_message=f"""
<div style="font-family: 'Segoe UI', Tahoma, sans-serif; max-width: 600px; margin: 0 auto; border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
{get_email_header_html()}
<div style="padding: 20px;">
<h2 style="color: #005696; font-size: 18px; margin: 0 0 12px 0;">Response Rejected - Inquiry #{inquiry.reference_number}</h2>
<p style="margin: 0 0 12px 0;">Your department's response for inquiry <strong>#{inquiry.reference_number}</strong> has been rejected.</p>
<div style="background: #fef2f2; padding: 12px; border-radius: 6px; margin: 0 0 12px 0;">
<p style="margin: 0;"><strong>Reason:</strong> {notes}</p>
</div>
<p style="margin: 0; color: #6b7280;">Please revise and resubmit your response.</p>
</div>
</div>
""",
related_object=inquiry,
)
except Exception:
logging.getLogger(__name__).exception("Failed to send inquiry dept response rejection email")
InquiryUpdate.objects.create(
inquiry=inquiry,
update_type="note",
message=f"Department response rejected by {user.get_full_name()}. Reason: {notes}",
created_by=user,
)
AuditService.log_event(
event_type="inquiry_dept_response_review",
description=f"Department response for inquiry {inquiry.reference_number} rejected by {user.get_full_name()}",
user=user,
content_object=inquiry,
)
messages.success(request, "Department response rejected. The department has been notified to resubmit.")
else:
inquiry.dept_response_acceptance_status = status
inquiry.dept_response_accepted_by = user
inquiry.dept_response_accepted_at = timezone.now()
inquiry.dept_response_acceptance_notes = notes
inquiry.save(
update_fields=[
"dept_response_acceptance_status",
"dept_response_accepted_by",
"dept_response_accepted_at",
"dept_response_acceptance_notes",
]
)
InquiryUpdate.objects.create(
inquiry=inquiry,
update_type="note",
message=f"Department response marked as {status} by {user.get_full_name()}. {notes}",
created_by=user,
)
AuditService.log_event(
event_type="inquiry_dept_response_review",
description=f"Department response for inquiry {inquiry.reference_number} marked as {status}",
user=user,
content_object=inquiry,
)
messages.success(request, f"Department response marked as {status}.")
return redirect("inquiries:inquiry_detail", pk=pk)
@login_required
@require_http_methods(["POST"])
@ -5229,12 +5106,10 @@ def sla_management(request):
# Group configs by type
source_based_configs = sla_configs.filter(source__isnull=False)
severity_based_configs = sla_configs.filter(source__isnull=True)
context = {
"hospital": hospital,
"source_based_configs": source_based_configs,
"severity_based_configs": severity_based_configs,
"total_configs": sla_configs.count(),
}
@ -5403,218 +5278,6 @@ def sla_management_toggle(request, pk):
return redirect("complaints:sla_management")
@login_required
def escalation_rule_list(request):
"""
Escalation Rules list view with filters.
Allows Hospital Admins and PX Admins to manage escalation rules.
"""
from .models import EscalationRule
# Check permission
user = request.user
if not (
user.is_px_admin() or user.is_hospital_admin()
or user.is_px_management() or user.is_px_employee()
):
messages.error(request, "You don't have permission to manage escalation rules.")
return redirect("accounts:settings")
# Base queryset
queryset = EscalationRule.objects.select_related("hospital", "escalate_to_user").all()
# Apply hospital filter
if not user.is_px_admin() and user.hospital:
queryset = queryset.filter(hospital=user.hospital)
# Apply filters from request
hospital_filter = request.GET.get("hospital")
if hospital_filter:
queryset = queryset.filter(hospital_id=hospital_filter)
escalation_level_filter = request.GET.get("escalation_level")
if escalation_level_filter:
queryset = queryset.filter(escalation_level=escalation_level_filter)
is_active_filter = request.GET.get("is_active")
if is_active_filter:
queryset = queryset.filter(is_active=(is_active_filter == "true"))
# Ordering
order_by = request.GET.get("order_by", "hospital__name")
queryset = queryset.order_by(order_by)
# Pagination
page_size = int(request.GET.get("page_size", 25))
paginator = Paginator(queryset, page_size)
page_number = request.GET.get("page", 1)
page_obj = paginator.get_page(page_number)
context = {
"page_obj": page_obj,
"escalation_rules": page_obj.object_list,
"filters": request.GET,
}
return render(request, "complaints/escalation_rule_list.html", context)
@login_required
@require_http_methods(["GET", "POST"])
def escalation_rule_create(request):
"""
Create new escalation rule.
"""
from .models import EscalationRule
from .forms import EscalationRuleForm
# Check permission
user = request.user
if not (
user.is_px_admin() or user.is_hospital_admin()
or user.is_px_management() or user.is_px_employee()
):
messages.error(request, "You don't have permission to create escalation rules.")
return redirect("accounts:settings")
if request.method == "POST":
form = EscalationRuleForm(request.POST, request=request)
if form.is_valid():
escalation_rule = form.save()
# Log audit
AuditService.log_event(
event_type="escalation_rule_created",
description=f"Escalation rule created: {escalation_rule}",
user=request.user,
content_object=escalation_rule,
metadata={
"hospital": str(escalation_rule.hospital),
"name": escalation_rule.name,
"escalation_level": escalation_rule.escalation_level,
},
)
messages.success(request, "Escalation rule created successfully.")
return redirect("complaints:escalation_rule_list")
else:
messages.error(request, "Please correct the errors below.")
else:
form = EscalationRuleForm(request=request)
context = {
"form": form,
"title": "Create Escalation Rule",
"action": "Create",
}
return render(request, "complaints/escalation_rule_form.html", context)
@login_required
@require_http_methods(["GET", "POST"])
def escalation_rule_edit(request, pk):
"""
Edit existing escalation rule.
"""
from .models import EscalationRule
from .forms import EscalationRuleForm
# Check permission
user = request.user
if not (
user.is_px_admin() or user.is_hospital_admin()
or user.is_px_management() or user.is_px_employee()
):
messages.error(request, "You don't have permission to edit escalation rules.")
return redirect("accounts:settings")
escalation_rule = get_object_or_404(EscalationRule, pk=pk)
# Check if user can edit this rule
if not user.is_px_admin() and escalation_rule.hospital != user.hospital:
messages.error(request, "You don't have permission to edit this escalation rule.")
return redirect("complaints:escalation_rule_list")
if request.method == "POST":
form = EscalationRuleForm(request.POST, request=request, instance=escalation_rule)
if form.is_valid():
escalation_rule = form.save()
# Log audit
AuditService.log_event(
event_type="escalation_rule_updated",
description=f"Escalation rule updated: {escalation_rule}",
user=request.user,
content_object=escalation_rule,
metadata={
"hospital": str(escalation_rule.hospital),
"name": escalation_rule.name,
"escalation_level": escalation_rule.escalation_level,
},
)
messages.success(request, "Escalation rule updated successfully.")
return redirect("complaints:escalation_rule_list")
else:
messages.error(request, "Please correct the errors below.")
else:
form = EscalationRuleForm(request=request, instance=escalation_rule)
context = {
"form": form,
"escalation_rule": escalation_rule,
"title": "Edit Escalation Rule",
"action": "Update",
}
return render(request, "complaints/escalation_rule_form.html", context)
@login_required
@require_http_methods(["POST"])
def escalation_rule_delete(request, pk):
"""
Delete escalation rule.
"""
from .models import EscalationRule
# Check permission
user = request.user
if not (
user.is_px_admin() or user.is_hospital_admin()
or user.is_px_management() or user.is_px_employee()
):
messages.error(request, "You don't have permission to delete escalation rules.")
return redirect("accounts:settings")
escalation_rule = get_object_or_404(EscalationRule, pk=pk)
# Check if user can delete this rule
if not user.is_px_admin() and escalation_rule.hospital != user.hospital:
messages.error(request, "You don't have permission to delete this escalation rule.")
return redirect("complaints:escalation_rule_list")
escalation_rule.delete()
# Log audit
AuditService.log_event(
event_type="escalation_rule_deleted",
description=f"Escalation rule deleted: {escalation_rule}",
user=request.user,
metadata={
"hospital": str(escalation_rule.hospital),
"name": escalation_rule.name,
},
)
messages.success(request, "Escalation rule deleted successfully.")
return redirect("complaints:escalation_rule_list")
@login_required
def complaint_threshold_list(request):
"""

7
apps/complaints/urls.py
View File

@ -101,11 +101,6 @@ urlpatterns = [
path("settings/sla-management/new/", ui_views.sla_management_create, name="sla_management_create"),
path("settings/sla-management/<uuid:pk>/edit/", ui_views.sla_management_edit, name="sla_management_edit"),
path("settings/sla-management/<uuid:pk>/toggle/", ui_views.sla_management_toggle, name="sla_management_toggle"),
# Escalation Rules Management
path("settings/escalation-rules/", ui_views.escalation_rule_list, name="escalation_rule_list"),
path("settings/escalation-rules/new/", ui_views.escalation_rule_create, name="escalation_rule_create"),
path("settings/escalation-rules/<uuid:pk>/edit/", ui_views.escalation_rule_edit, name="escalation_rule_edit"),
path("settings/escalation-rules/<uuid:pk>/delete/", ui_views.escalation_rule_delete, name="escalation_rule_delete"),
# Complaint Thresholds Management
path("settings/thresholds/", ui_views.complaint_threshold_list, name="complaint_threshold_list"),
path("settings/thresholds/new/", ui_views.complaint_threshold_create, name="complaint_threshold_create"),
@ -168,7 +163,7 @@ urlpatterns = [
name="complaint_resend_explanation",
),
# PDF Export
path("<uuid:pk>/pdf/", generate_complaint_pdf, name="complaint_pdf"),
path("<uuid:pk>/pdf/", generate_complaint_pdf_v2, name="complaint_pdf"),
path("<uuid:pk>/pdf-v2/", generate_complaint_pdf_v2, name="complaint_pdf_v2"),
path("inquiries/<uuid:pk>/pdf/", inquiry_pdf, name="inquiry_pdf"),
# Involved Departments Management

1
apps/complaints/urls_inquiries.py
View File

@ -19,7 +19,6 @@ urlpatterns = [
path("<uuid:pk>/respond/", ui_views.inquiry_respond, name="inquiry_respond"),
path("<uuid:pk>/transfer-to-department/", ui_views.inquiry_transfer_to_department, name="inquiry_transfer_to_department"),
path("<uuid:pk>/department-response/", ui_views.inquiry_department_response, name="inquiry_department_response"),
path("<uuid:pk>/review-dept-response/", ui_views.inquiry_review_dept_response, name="inquiry_review_dept_response"),
path("<uuid:pk>/send-dept-response-reminder/", ui_views.inquiry_send_dept_response_reminder, name="inquiry_send_dept_response_reminder"),
path("<uuid:pk>/update-contact/", ui_views.inquiry_update_contact_stage, name="inquiry_update_contact_stage"),
path("export/incoming/", ui_views.inquiry_export_incoming, name="inquiry_export_incoming"),

489
apps/complaints/views.py
View File

@ -1320,343 +1320,6 @@ This is an automated message from PX360 Complaint Management System.
status=status.HTTP_200_OK,
)
@action(detail=True, methods=["post"])
def review_explanation(self, request, pk=None):
"""
Review and mark an explanation as acceptable or not acceptable.
Allows PX Admins to review submitted explanations and mark them.
"""
complaint = self.get_object()
# Check permission
if not (request.user.is_px_admin() or request.user.is_hospital_admin()
or request.user.is_px_management() or request.user.is_px_employee()):
return Response(
{"error": "Only PX team members can review explanations"}, status=status.HTTP_403_FORBIDDEN
)
explanation_id = request.data.get("explanation_id")
acceptance_status = request.data.get("acceptance_status")
acceptance_notes = request.data.get("acceptance_notes", "")
if not explanation_id:
return Response({"error": "explanation_id is required"}, status=status.HTTP_400_BAD_REQUEST)
if not acceptance_status:
return Response(
{"error": "acceptance_status is required (acceptable or not_acceptable)"},
status=status.HTTP_400_BAD_REQUEST,
)
# Validate acceptance status
from .models import ComplaintExplanation
valid_statuses = [
ComplaintExplanation.AcceptanceStatus.ACCEPTABLE,
ComplaintExplanation.AcceptanceStatus.NOT_ACCEPTABLE,
]
if acceptance_status not in valid_statuses:
return Response(
{"error": f"Invalid acceptance_status. Must be one of: {valid_statuses}"},
status=status.HTTP_400_BAD_REQUEST,
)
# Get the explanation
try:
explanation = ComplaintExplanation.objects.get(id=explanation_id, complaint=complaint)
except ComplaintExplanation.DoesNotExist:
return Response({"error": "Explanation not found"}, status=status.HTTP_404_NOT_FOUND)
# Check if explanation has been submitted
if not explanation.is_used:
return Response(
{"error": "Cannot review explanation that has not been submitted yet"},
status=status.HTTP_400_BAD_REQUEST,
)
# Update explanation
explanation.acceptance_status = acceptance_status
explanation.accepted_by = request.user
explanation.accepted_at = timezone.now()
explanation.acceptance_notes = acceptance_notes
explanation.save()
# Create complaint update
status_display = (
"Acceptable" if acceptance_status == ComplaintExplanation.AcceptanceStatus.ACCEPTABLE else "Not Acceptable"
)
ComplaintUpdate.objects.create(
complaint=complaint,
update_type="note",
message=f"Explanation from {explanation.staff} marked as {status_display}",
created_by=request.user,
metadata={
"explanation_id": str(explanation.id),
"staff_id": str(explanation.staff.id) if explanation.staff else None,
"acceptance_status": acceptance_status,
"acceptance_notes": acceptance_notes,
},
)
# Log audit
AuditService.log_from_request(
event_type="explanation_reviewed",
description=f"Explanation marked as {status_display}",
request=request,
content_object=explanation,
metadata={
"explanation_id": str(explanation.id),
"acceptance_status": acceptance_status,
"acceptance_notes": acceptance_notes,
},
)
return Response(
{
"success": True,
"message": f"Explanation marked as {status_display}",
"explanation_id": str(explanation.id),
"acceptance_status": acceptance_status,
"accepted_at": explanation.accepted_at,
"accepted_by": request.user.get_full_name(),
}
)
@action(detail=True, methods=["post"])
def escalate_explanation(self, request, pk=None):
"""
Escalate an explanation to the staff's manager.
Marks the explanation as not acceptable and sends an explanation request
to the staff's manager (report_to).
"""
complaint = self.get_object()
# Check permission
if not (request.user.is_px_admin() or request.user.is_hospital_admin()):
return Response(
{"error": "Only PX Admins or Hospital Admins can escalate explanations"},
status=status.HTTP_403_FORBIDDEN,
)
explanation_id = request.data.get("explanation_id")
acceptance_notes = request.data.get("acceptance_notes", "")
if not explanation_id:
return Response({"error": "explanation_id is required"}, status=status.HTTP_400_BAD_REQUEST)
# Get the explanation
try:
explanation = ComplaintExplanation.objects.select_related("staff", "staff__report_to").get(
id=explanation_id, complaint=complaint
)
except ComplaintExplanation.DoesNotExist:
return Response({"error": "Explanation not found"}, status=status.HTTP_404_NOT_FOUND)
# Check if explanation has been submitted
if not explanation.is_used:
return Response(
{"error": "Cannot escalate explanation that has not been submitted yet"},
status=status.HTTP_400_BAD_REQUEST,
)
# Check if already escalated
if explanation.escalated_to_manager:
return Response({"error": "Explanation has already been escalated"}, status=status.HTTP_400_BAD_REQUEST)
# Use fallback chain to find escalation target
from apps.complaints.services.complaint_service import ComplaintService
from apps.organizations.models import Staff
target_user, fallback_path = ComplaintService.get_escalation_target(complaint, staff=explanation.staff)
if not target_user:
return Response(
{"error": f"No escalation target found (tried: {fallback_path})"},
status=status.HTTP_400_BAD_REQUEST,
)
manager = Staff.objects.filter(user=target_user).first()
if not manager:
return Response(
{"error": f"Escalation target {target_user.get_full_name()} has no Staff record"},
status=status.HTTP_400_BAD_REQUEST,
)
# Check if manager already has an explanation request for this complaint
existing_manager_explanation = ComplaintExplanation.objects.filter(complaint=complaint, staff=manager).first()
if existing_manager_explanation:
return Response(
{"error": f"Manager {manager.get_full_name()} already has an explanation request for this complaint"},
status=status.HTTP_400_BAD_REQUEST,
)
# Generate token for manager explanation
import secrets
manager_token = secrets.token_urlsafe(32)
request_message = f"Escalated from staff explanation. Staff: {explanation.staff.get_full_name() if explanation.staff else 'Unknown'}. Notes: {acceptance_notes}"
if fallback_path != "staff.report_to":
request_message += f" [Escalated via fallback: {fallback_path}]"
# Create manager explanation record
manager_explanation = ComplaintExplanation.objects.create(
complaint=complaint,
staff=manager,
token=manager_token,
is_used=False,
requested_by=request.user,
request_message=request_message,
submitted_via="email_link",
email_sent_at=timezone.now(),
metadata={
"escalation_fallback_path": fallback_path,
},
)
# Update original explanation
explanation.acceptance_status = ComplaintExplanation.AcceptanceStatus.NOT_ACCEPTABLE
explanation.accepted_by = request.user
explanation.accepted_at = timezone.now()
explanation.acceptance_notes = acceptance_notes
explanation.escalated_to_manager = manager_explanation
explanation.escalated_at = timezone.now()
explanation.save()
# Send email to manager
from django.contrib.sites.shortcuts import get_current_site
from apps.notifications.services import NotificationService, get_email_header_html
site = get_current_site(request)
explanation_link = f"https://{site.domain}/complaints/{complaint.id}/explain/{manager_token}/"
manager_email = manager.email or (manager.user.email if manager.user else None)
if manager_email:
subject = f"Escalated Explanation Request - Complaint #{complaint.reference_number}"
email_body = f"""Dear {manager.get_full_name()},
An explanation submitted by a staff member who reports to you has been marked as not acceptable and escalated to you for further review.
STAFF MEMBER:
------------
Name: {explanation.staff.get_full_name() if explanation.staff else "Unknown"}
Employee ID: {explanation.staff.employee_id if explanation.staff else "N/A"}
Department: {explanation.staff.department.name if explanation.staff and explanation.staff.department else "N/A"}
COMPLAINT DETAILS:
----------------
Reference: {complaint.reference_number}
Title: {complaint.title}
Severity: {complaint.get_severity_display()}
Priority: {complaint.get_priority_display()}
ORIGINAL EXPLANATION (Not Acceptable):
--------------------------------------
{explanation.explanation}
ESCALATION NOTES:
-----------------
{acceptance_notes if acceptance_notes else "No additional notes provided."}
PLEASE SUBMIT YOUR EXPLANATION:
------------------------------
As the manager, please submit your perspective on this matter:
{explanation_link}
Note: This link can only be used once. After submission, it will expire.
---
This is an automated message from PX360 Complaint Management System.
"""
try:
NotificationService.send_email(
email=manager_email,
subject=subject,
message=email_body,
html_message=f"""
<div style="font-family: 'Segoe UI', Tahoma, sans-serif; max-width: 600px; margin: 0 auto; border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
{get_email_header_html()}
<div style="padding: 20px;">
<h2 style="color: #005696; font-size: 18px; margin: 0 0 12px 0;">Escalated Explanation Request</h2>
<p style="margin: 0 0 12px 0;">The original explanation was not acceptable and this request has been escalated to you for review.</p>
<table style="width: 100%; border-collapse: collapse; margin: 0 0 12px 0;">
<tr><td style="padding: 4px 0; color: #6b7280; width: 140px;">Reference:</td><td style="padding: 4px 0;"><strong>{complaint.reference_number}</strong></td></tr>
<tr><td style="padding: 4px 0; color: #6b7280;">Title:</td><td style="padding: 4px 0;">{complaint.title}</td></tr>
<tr><td style="padding: 4px 0; color: #6b7280;">Severity:</td><td style="padding: 4px 0;">{complaint.get_severity_display()}</td></tr>
<tr><td style="padding: 4px 0; color: #6b7280;">Priority:</td><td style="padding: 4px 0;">{complaint.get_priority_display()}</td></tr>
</table>
<p style="margin: 0 0 6px 0; color: #6b7280; font-size: 13px;">This link can only be used once. After submission, it will expire.</p>
<div style="text-align: center; margin: 20px 0;">
<a href="{explanation_link}" style="background: #005696; color: white; padding: 10px 24px; border-radius: 8px; text-decoration: none; font-weight: 600;">Submit Your Explanation</a>
</div>
</div>
</div>
""",
related_object=complaint,
metadata={
"notification_type": "escalated_explanation_request",
"manager_id": str(manager.id),
"staff_id": str(explanation.staff.id) if explanation.staff else None,
"complaint_id": str(complaint.id),
"original_explanation_id": str(explanation.id),
},
)
email_sent = True
except Exception as e:
logger.error(f"Failed to send escalation email to manager: {e}")
email_sent = False
else:
email_sent = False
# Create complaint update
ComplaintUpdate.objects.create(
complaint=complaint,
update_type="note",
message=f"Explanation from {explanation.staff} marked as Not Acceptable and escalated to manager {manager.get_full_name()}",
created_by=request.user,
metadata={
"explanation_id": str(explanation.id),
"staff_id": str(explanation.staff.id) if explanation.staff else None,
"manager_id": str(manager.id),
"manager_explanation_id": str(manager_explanation.id),
"acceptance_status": "not_acceptable",
"acceptance_notes": acceptance_notes,
"email_sent": email_sent,
},
)
# Log audit
AuditService.log_from_request(
event_type="explanation_escalated",
description=f"Explanation escalated to manager {manager.get_full_name()}",
request=request,
content_object=explanation,
metadata={
"explanation_id": str(explanation.id),
"manager_id": str(manager.id),
"manager_explanation_id": str(manager_explanation.id),
"email_sent": email_sent,
},
)
return Response(
{
"success": True,
"message": f"Explanation escalated to manager {manager.get_full_name()}",
"explanation_id": str(explanation.id),
"manager_explanation_id": str(manager_explanation.id),
"manager_name": manager.get_full_name(),
"manager_email": manager_email,
"email_sent": email_sent,
}
)
@action(detail=True, methods=["post"])
def generate_ai_resolution(self, request, pk=None):
"""
@ -1710,7 +1373,6 @@ This is an automated message from PX360 Complaint Management System.
"employee_id": exp.staff.employee_id if exp.staff else "N/A",
"department": exp.staff.department.name if exp.staff and exp.staff.department else "N/A",
"explanation": exp.explanation,
"acceptance_status": exp.get_acceptance_status_display(),
"submitted_at": exp.responded_at.strftime("%Y-%m-%d %H:%M") if exp.responded_at else "Unknown",
}
context["explanations"].append(exp_data)
@ -1725,7 +1387,6 @@ This is an automated message from PX360 Complaint Management System.
explanations_text += f"""
Explanation {i}:
- Staff: {exp["staff_name"]} (ID: {exp["employee_id"]}, Dept: {exp["department"]})
- Status: {exp["acceptance_status"]}
- Submitted: {exp["submitted_at"]}
- Content: {exp["explanation"]}
@ -1845,19 +1506,18 @@ Always provide valid JSON output with both resolution_en and resolution_ar field
acceptable_explanation = None
explanation_source = None
# First, try to find an acceptable staff explanation
# First, try to find a submitted staff explanation
staff_explanation = complaint.explanations.filter(
staff=complaint.staff, is_used=True, acceptance_status=ComplaintExplanation.AcceptanceStatus.ACCEPTABLE
staff=complaint.staff, is_used=True
).first()
if staff_explanation:
acceptable_explanation = staff_explanation
explanation_source = "staff"
else:
# Try to find an acceptable manager explanation (escalated)
# Try to find a submitted manager explanation (escalated)
manager_explanation = complaint.explanations.filter(
is_used=True,
acceptance_status=ComplaintExplanation.AcceptanceStatus.ACCEPTABLE,
metadata__is_escalation=True,
).first()
@ -1868,7 +1528,7 @@ Always provide valid JSON output with both resolution_en and resolution_ar field
if not acceptable_explanation:
return Response(
{
"error": "No acceptable explanation found. Please review and mark an explanation as acceptable first.",
"error": "No submitted explanation found. Please request an explanation from the involved staff first.",
"suggestion": None,
},
status=status.HTTP_400_BAD_REQUEST,
@ -1980,6 +1640,7 @@ Provide 3-5 suggestions. Keep them concise and focused on how to respond to the
result = AIService.chat_completion(
prompt=prompt,
response_format="json_object",
max_tokens=1500,
)
parsed = json.loads(result)
@ -2518,7 +2179,10 @@ Generate JSON with exactly these fields:
},
)
# Send appreciation (triggers notification)
# Activate + send appreciation (triggers notification).
# activate() honors the activation gate (DRAFT -> ACTIVATED) and records
# who approved it; send() then moves ACTIVATED -> SENT.
appreciation.activate(activated_by=request.user)
appreciation.send()
# Link appreciation to complaint
@ -3311,6 +2975,7 @@ class InquiryViewSet(viewsets.ModelViewSet):
inquiry.responded_at = timezone.now()
inquiry.responded_by = request.user
inquiry.status = "resolved"
inquiry._acting_user = request.user
inquiry.save()
return Response({"message": "Response submitted successfully"})
@ -3905,23 +3570,13 @@ def complaint_explanation_form(request, complaint_id, token):
complaint = get_object_or_404(Complaint, id=complaint_id)
# Validate token with staff and department prefetch
# Also prefetch escalation relationship to show original staff explanation to manager
explanation = get_object_or_404(
ComplaintExplanation.objects.select_related("staff", "staff__department", "staff__report_to").prefetch_related(
"escalated_from_staff"
),
ComplaintExplanation.objects.select_related("staff", "staff__department", "staff__report_to"),
complaint=complaint,
token=token,
)
# Get original staff explanation if this is an escalation
original_explanation = None
if hasattr(explanation, "escalated_from_staff"):
# This explanation was created as a result of escalation
# Get the original staff explanation
original_explanation = (
ComplaintExplanation.objects.filter(escalated_to_manager=explanation).select_related("staff").first()
)
# Check if token is already used
if explanation.is_used:
@ -4023,31 +3678,43 @@ def complaint_explanation_form(request, complaint_id, token):
sent_channels = []
if phone:
try:
NotificationService.send_sms(
sms_log = NotificationService.send_sms(
phone,
f"PX360: Your verification code is {code}. Enter this to submit your response for complaint #{complaint.reference_number}.",
)
sent_channels.append("phone")
if sms_log and getattr(sms_log, "status", None) == "sent":
sent_channels.append("phone")
except Exception:
pass
if email:
try:
NotificationService.send_email(
email_log = NotificationService.send_email(
email=email,
subject=f"Verification Code - Complaint #{complaint.reference_number}",
message=f"Your verification code is: {code}\n\nEnter this code to submit your response.",
related_object=complaint,
)
sent_channels.append("email")
if email_log and getattr(email_log, "status", None) == "sent":
sent_channels.append("email")
except Exception:
pass
return render(request, "complaints/explanation_form.html", {
# Surface a real delivery failure in production. In DEBUG, always proceed so the flow is testable.
if not sent_channels and not settings.DEBUG:
return render(request, "complaints/explanation_form.html", {
**base_ctx, "consent_checked": True,
"error": _("Could not send the verification code. Please check your contact details or contact the PX team."),
})
otp_ctx = {
**base_ctx, "consent_checked": True,
"otp_sent": True,
"otp_phone": "phone" in sent_channels,
"otp_email": "email" in sent_channels,
})
}
if settings.DEBUG:
otp_ctx["dev_otp_code"] = code
return render(request, "complaints/explanation_form.html", otp_ctx)
# --- Cancel OTP: user clicked "Edit response" — re-enable the form ---
if action == "cancel_otp":
@ -4914,16 +4581,29 @@ def champion_review_answers(request, complaint_id, token):
"error": _("Please describe the required improvement project."),
})
# Get champion contact info
champion = explanation.staff
# Verification code goes to whoever is actually reviewing. Prefer the
# logged-in reviewer (champ or manager); fall back to the token owner
# (explanation.staff) for anonymous / token-only access.
phone = ""
email = ""
if champion:
phone = champion.phone or ""
email = champion.email or ""
if champion.user:
phone = phone or (champion.user.phone or "")
email = email or (champion.user.email or "")
reviewer = request.user if getattr(request.user, "is_authenticated", False) else None
if reviewer:
email = reviewer.email or ""
phone = getattr(reviewer, "phone", "") or ""
sp = getattr(reviewer, "staff_profile", None)
if sp:
email = email or sp.email or ""
phone = phone or sp.phone or ""
# Fallback to the token owner (investigator of record)
if not email and not phone:
token_owner = explanation.staff
if token_owner:
phone = token_owner.phone or ""
email = token_owner.email or ""
if token_owner.user:
phone = phone or (token_owner.user.phone or "")
email = email or (token_owner.user.email or "")
if not phone and not email:
return render(request, "complaints/investigation_review.html", {
@ -4936,36 +4616,59 @@ def champion_review_answers(request, complaint_id, token):
code = f"{random.randint(0, 999999):06d}"
investigation.otp_code = code
investigation.otp_sent_at = timezone.now()
investigation.save(update_fields=["otp_code", "otp_sent_at"])
# Persist the assessment draft so it survives a page reload / return visit
# (the OTP step locks the form; without persisting, the data is lost on GET).
investigation.final_reply = final_reply
investigation.negligence_finding = negligence_finding
investigation.policy_issue_finding = policy_issue_finding
investigation.requires_improvement_project = requires_improvement_project
investigation.improvement_project_note = improvement_project_note
investigation.save(update_fields=[
"otp_code", "otp_sent_at", "final_reply",
"negligence_finding", "policy_issue_finding",
"requires_improvement_project", "improvement_project_note",
])
sent_channels = []
if phone:
try:
NotificationService.send_sms(
sms_log = NotificationService.send_sms(
phone,
f"PX360: Your verification code is {code}. Enter this to submit your response for complaint #{complaint.reference_number}.",
)
sent_channels.append("phone")
if sms_log and getattr(sms_log, "status", None) == "sent":
sent_channels.append("phone")
except Exception:
pass
if email:
try:
NotificationService.send_email(
email_log = NotificationService.send_email(
email=email,
subject=f"Verification Code - Complaint #{complaint.reference_number}",
message=f"Your verification code is: {code}\n\nEnter this code to submit your response.",
related_object=complaint,
)
sent_channels.append("email")
if email_log and getattr(email_log, "status", None) == "sent":
sent_channels.append("email")
except Exception:
pass
return render(request, "complaints/investigation_review.html", {
# Surface a real delivery failure in production. In DEBUG, always proceed so the flow is testable.
if not sent_channels and not settings.DEBUG:
return render(request, "complaints/investigation_review.html", {
**base_ctx, "final_reply": final_reply, "consent_checked": True,
"error": _("Could not send the verification code. Please check your contact details or contact the PX team."),
})
otp_ctx = {
**base_ctx, "final_reply": final_reply, "consent_checked": True,
"otp_sent": True,
"otp_phone": "phone" in sent_channels,
"otp_email": "email" in sent_channels,
})
}
if settings.DEBUG:
otp_ctx["dev_otp_code"] = code
return render(request, "complaints/investigation_review.html", otp_ctx)
# --- Cancel OTP: user clicked "Edit response" — re-enable the form ---
if action == "cancel_otp":
@ -5112,9 +4815,18 @@ def champion_review_answers(request, complaint_id, token):
and investigation.otp_sent_at
and timezone.now() <= investigation.otp_sent_at + timedelta(minutes=10)
)
# Restore the persisted assessment draft (so a return visit keeps the data the
# reviewer already entered before requesting the code). Consent was already
# captured when the code was sent, so pre-check it while the OTP is pending.
return render(request, "complaints/investigation_review.html", {
**base_ctx,
"otp_sent": show_otp,
"final_reply": investigation.final_reply,
"negligence_finding": investigation.negligence_finding,
"policy_issue_finding": investigation.policy_issue_finding,
"requires_improvement_project": investigation.requires_improvement_project,
"improvement_project_note": investigation.improvement_project_note,
"consent_checked": show_otp,
})
@ -5294,7 +5006,7 @@ def generate_complaint_pdf_v2(request, pk):
if not stamp_path:
stamp_path = _img_to_data_uri(settings.BASE_DIR / "static" / "images" / "stamps" / "stamp.png")
explanations = complaint.explanations.all().select_related("staff", "accepted_by").prefetch_related("attachments")
explanations = complaint.explanations.all().select_related("staff", "requested_by").prefetch_related("attachments")
timeline = complaint.updates.all().select_related("created_by")[:20]
from apps.px_action_center.models import PXAction
@ -5303,6 +5015,25 @@ def generate_complaint_pdf_v2(request, pk):
complaint_ct = ContentType.objects.get_for_model(Complaint)
px_actions = PXAction.objects.filter(content_type=complaint_ct, object_id=complaint.id).order_by("-created_at")[:5]
# QR code encoding the public tracking URL for authenticity verification
qr_code_path = None
try:
import qrcode
from django.urls import reverse
tracking_url = request.build_absolute_uri(
reverse("complaints:public_complaint_track")
) + "?reference=" + complaint.reference_number
qr = qrcode.QRCode(version=1, box_size=4, border=1)
qr.add_data(tracking_url)
qr.make(fit=True)
qr_img = qr.make_image(fill_color="black", back_color="white")
qr_buf = io.BytesIO()
qr_img.save(qr_buf, format="PNG")
qr_code_path = "data:image/png;base64," + base64.b64encode(qr_buf.getvalue()).decode()
except Exception:
pass
html_string = render_to_string(
"complaints/complaint_pdf_v2.html",
{
@ -5314,6 +5045,7 @@ def generate_complaint_pdf_v2(request, pk):
"logo_path": logo_path,
"letterhead_path": letterhead_path,
"stamp_path": stamp_path,
"qr_code_path": qr_code_path,
},
)
@ -5441,7 +5173,6 @@ def inquiry_respond_with_token(request, pk, token):
inquiry.department_response_ar = response_ar
inquiry.department_responded_at = timezone.now()
inquiry.dept_response_is_overdue = False
inquiry.dept_response_acceptance_status = "pending"
inquiry.response_token_used = True
inquiry.save()

21
apps/core/ai_service.py
View File

@ -2143,22 +2143,25 @@ Respond in JSON format:
- other: Anything not covered above
Instructions:
1. Generate a short_description (2-3 sentences) summarizing the key points in BOTH English and Arabic
2. Classify the category from the list above
3. Assign a priority level based on potential impact
4. Generate 1-3 suggested_actions as concrete improvement steps, each with:
1. Generate a short_description: a concise title/headline (1 line, 5-12 words) in BOTH English and Arabic
2. Generate a description: a detailed explanation (3-6 sentences) describing what the suggestion is about and the context in BOTH English and Arabic
3. Classify the category from the list above
4. Assign a priority level based on potential impact
5. Generate 1-3 suggested_actions as concrete improvement steps, each with:
- action: Specific, actionable step the hospital can take
- priority: high|medium|low
- category: clinical_quality|patient_safety|service_quality|staff_behavior|facility|process_improvement|other
Provide all actions in BOTH English and Arabic
5. Provide reasoning for your classification in BOTH English and Arabic
6. Provide reasoning for your classification in BOTH English and Arabic
IMPORTANT: ALL TEXT FIELDS MUST BE PROVIDED IN BOTH ENGLISH AND ARABIC
Provide your analysis in JSON format:
{{
"short_description_en": "2-3 sentence summary in English of the suggestion",
"short_description_ar": "ملخص من 2-3 جمل بالعربية",
"short_description_en": "Concise title in English (1 line, 5-12 words)",
"short_description_ar": "عنوان موجز بالعربية (سطر واحد، 5-12 كلمة)",
"description_en": "Detailed explanation in English (3-6 sentences) of what the suggestion is about",
"description_ar": "شرح مفصل بالعربية (3-6 جمل) حول موضوع الاقتراح",
"category": "clinical_care|facility|staff_service|communication|technology|food_service|appointment|process_improvement|other",
"priority": "low|medium|high",
"suggested_actions": [
@ -2217,6 +2220,8 @@ Respond in JSON format:
return {
"short_description_en": message[:200] if message else "",
"short_description_ar": message[:200] if message else "",
"description_en": message[:500] if message else "",
"description_ar": message[:500] if message else "",
"category": "other",
"priority": "medium",
"suggested_actions": [],
@ -2230,6 +2235,8 @@ Respond in JSON format:
return {
"short_description_en": message[:200] if message else "",
"short_description_ar": message[:200] if message else "",
"description_en": message[:500] if message else "",
"description_ar": message[:500] if message else "",
"category": "other",
"priority": "medium",
"suggested_actions": [],

2
apps/core/management/commands/get_e2e_dept_response_state.py
View File

@ -33,7 +33,6 @@ class Command(BaseCommand):
print(f"sent_to_department={it.sent_to_department}")
print(f"department_response_en_set={bool(it.department_response_en)}")
print(f"department_responded_at={'True' if it.department_responded_at else 'False'}")
print(f"dept_response_acceptance_status={it.dept_response_acceptance_status or 'NONE'}")
print(f"response_token={it.response_token or 'NONE'}")
print(f"response_token_used={it.response_token_used}")
else:
@ -47,6 +46,5 @@ class Command(BaseCommand):
print(f"sent_to_department={it.sent_to_department}")
print(f"department_response_en_set={bool(it.department_response_en)}")
print(f"department_responded_at={'True' if it.department_responded_at else 'False'}")
print(f"dept_response_acceptance_status={it.dept_response_acceptance_status or 'NONE'}")
print(f"response_token={it.response_token or 'NONE'}")
print(f"response_token_used={it.response_token_used}")

55
apps/core/management/commands/setup_dev_environment.py
View File

@ -36,7 +36,7 @@ from apps.integrations.models import SurveyTemplateMapping
from apps.complaints.models import (
ComplaintCategory,
ComplaintSLAConfig,
EscalationRule,
ComplaintThreshold,
ExplanationSLAConfig,
)
@ -161,7 +161,7 @@ class Command(BaseCommand):
self.stdout.write("-" * 70)
self.create_complaint_categories()
self.create_complaint_sla_configs(hospitals, px_sources)
self.create_escalation_rules(hospitals)
self.create_complaint_thresholds(hospitals)
self.create_explanation_sla_configs(hospitals)
@ -1740,56 +1740,6 @@ class Command(BaseCommand):
action = "Created" if created else "Exists"
self.stdout.write(f" ✓ {action}: {source_code} ({sla_hours}h)")
def create_escalation_rules(self, hospitals):
"""Create escalation rules for each hospital"""
self.stdout.write(" Creating escalation rules...")
rules_data = [
{
"name": "Default Escalation to Department Manager",
"escalate_to_role": "department_manager",
"trigger_hours_overdue": 0,
"order": 1,
},
{
"name": "Critical Escalation to Hospital Admin",
"escalate_to_role": "hospital_admin",
"trigger_hours_overdue": 4,
"order": 2,
},
{
"name": "Final Escalation to PX Admin",
"escalate_to_role": "px_admin",
"trigger_hours_overdue": 24,
"order": 3,
},
]
for hospital in hospitals:
hospital_identifier = hospital.name if not self.dry_run else hospital.code
self.stdout.write(f" {hospital_identifier}:")
for rule_data in rules_data:
if self.dry_run:
self.stdout.write(f" ✓ Would create: {rule_data['name']}")
continue
rule, created = EscalationRule.objects.get_or_create(
hospital=hospital,
name=rule_data["name"],
defaults={
"description": rule_data["name"],
"trigger_on_overdue": True,
"trigger_hours_overdue": rule_data["trigger_hours_overdue"],
"escalate_to_role": rule_data["escalate_to_role"],
"order": rule_data["order"],
"is_active": True,
},
)
action = "Created" if created else "Exists"
self.stdout.write(f" ✓ {action}: {rule.name}")
def create_complaint_thresholds(self, hospitals):
"""Create complaint thresholds for each hospital"""
self.stdout.write(" Creating complaint thresholds...")
@ -2250,7 +2200,6 @@ class Command(BaseCommand):
if not self.skip_complaints:
self.stdout.write(f" Complaint Categories: {ComplaintCategory.objects.count()}")
self.stdout.write(f" SLA Configs: {ComplaintSLAConfig.objects.count()}")
self.stdout.write(f" Escalation Rules: {EscalationRule.objects.count()}")
if not self.skip_journeys:
self.stdout.write(f" Journey Templates: {PatientJourneyTemplate.objects.count()}")
self.stdout.write(f" Journey Stages: {PatientJourneyStageTemplate.objects.count()}")

48
apps/core/pdf_utils.py
View File

@ -1,5 +1,5 @@
"""
Shared PDF generation helper for any model using the hospital letterhead.
Shared PDF generation helper for any model using the hospital letterhead (artboard).
"""
import io
@ -10,26 +10,56 @@ from django.template.loader import render_to_string
from weasyprint import HTML
def _get_logo_data_uri():
"""Load the HH_P_ICON as a base64 data URI for embedding in PDF."""
def _img_to_data_uri(path):
"""Open an image file and return it as a base64 data URI."""
try:
from PIL import Image as PILImage
logo_img = PILImage.open(settings.BASE_DIR / "static" / "img" / "HH_P_ICON.png")
logo_img.thumbnail((600, 600), PILImage.LANCZOS)
img = PILImage.open(path)
buf = io.BytesIO()
logo_img.save(buf, format="PNG", optimize=True)
img.save(buf, format="PNG", optimize=True)
return "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
except Exception:
return None
def generate_letterhead_pdf(template_name, context, filename):
"""Render a template with the hospital letterhead and return an HttpResponse with the PDF."""
def _get_logo_data_uri():
"""Load the HH_P_ICON as a base64 data URI for embedding in PDF."""
return _img_to_data_uri(settings.BASE_DIR / "static" / "img" / "HH_P_ICON.png")
def _get_letterhead_data_uri(obj):
"""Load the hospital letterhead (artboard) for the given object's hospital.
Priority: hospital.letterhead upload → static fallback artboard image.
"""
hospital = getattr(obj, "hospital", None)
if hospital and hospital.letterhead:
uri = _img_to_data_uri(hospital.letterhead.path)
if uri:
return uri
# Static fallback
return _img_to_data_uri(settings.BASE_DIR / "static" / "images" / "artboard" / "Artboard 1@3x.png")
def generate_letterhead_pdf(template_name, context, filename, obj=None):
"""Render a template with the hospital letterhead (artboard) and return an HttpResponse with the PDF.
Args:
template_name: Django template path.
context: Dict of template context variables.
filename: Output PDF filename.
obj: The model instance (used to resolve hospital.letterhead). If None,
falls back to the static artboard image.
"""
from django.http import HttpResponse
logo_path = _get_logo_data_uri()
full_context = {**context, "logo_path": logo_path}
letterhead_path = _img_to_data_uri(settings.BASE_DIR / "static" / "images" / "artboard" / "Artboard 1@3x.png")
if obj:
letterhead_path = _get_letterhead_data_uri(obj)
full_context = {**context, "logo_path": logo_path, "letterhead_path": letterhead_path}
html_string = render_to_string(template_name, full_context)
pdf_file = HTML(string=html_string, base_url=str(settings.BASE_DIR / "static")).write_pdf()

10
apps/core/utils.py
View File

@ -17,12 +17,8 @@ def get_assignable_users(hospital):
def build_public_track_url(entity_type, reference):
try:
from django.contrib.sites.shortcuts import get_current_site
site = get_current_site(None)
domain = site.domain
except Exception:
domain = "localhost:8000"
from django.conf import settings
base = settings.SITE_URL.rstrip("/")
path = reverse("core:public_track")
return f"https://{domain}{path}?type={entity_type}&reference={reference}"
return f"{base}{path}?type={entity_type}&reference={reference}"

2
apps/dashboard/views.py
View File

@ -895,7 +895,7 @@ def get_dashboard_chart_data(user, start_date=None, selected_hospital=None):
staff_profile = getattr(user, 'staff_profile', None)
if staff_profile:
task_qs = QIProjectTask.objects.filter(assigned_to=staff_profile, status="closed", completed_date=date.date())
task_qs = QIProjectTask.objects.filter(assigned_to=staff_profile, status="completed", completed_date=date.date())
else:
task_qs = QIProjectTask.objects.none()
if selected_hospital:

6
apps/executive_summary/pdf_service.py
View File

@ -4,6 +4,7 @@ PDF generation service for executive reports.
Renders the executive PDF template without requiring an HttpRequest.
"""
from django.conf import settings
from django.template.loader import render_to_string
from django.utils import timezone
from weasyprint import HTML
@ -20,6 +21,8 @@ def generate_executive_pdf(report, user=None) -> bytes:
Returns:
PDF file contents as bytes
"""
from apps.core.pdf_utils import _get_logo_data_uri
context = {
"report": report,
"narrative": report.narrative_en,
@ -28,7 +31,8 @@ def generate_executive_pdf(report, user=None) -> bytes:
"metrics": report.metrics_snapshot,
"generated_at": timezone.now().strftime("%Y-%m-%d %H:%M"),
"user": user,
"logo_path": _get_logo_data_uri(),
}
html_string = render_to_string("executive/pdf_report.html", context)
return HTML(string=html_string).write_pdf()
return HTML(string=html_string, base_url=str(settings.BASE_DIR / "static")).write_pdf()

190
apps/executive_summary/templates/executive/pdf_report.html
View File

@ -1,114 +1,76 @@
{% extends "shared/letterhead_pdf_repeating_base.html" %}
{% load i18n %}
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>{% trans "Executive Report" %} - PX360</title>
<style>
@page {
size: A4;
margin: 2cm;
}
body {
font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
font-size: 11pt;
line-height: 1.6;
color: #1f2937;
}
.header {
border-bottom: 3px solid #4f46e5;
padding-bottom: 1rem;
margin-bottom: 1.5rem;
}
.header h1 {
font-size: 24pt;
color: #4f46e5;
margin: 0 0 0.25rem 0;
}
.meta {
font-size: 10pt;
color: #6b7280;
}
.section {
margin-bottom: 1.5rem;
}
.section h2 {
font-size: 14pt;
color: #111827;
border-left: 4px solid #4f46e5;
padding-left: 0.5rem;
margin-bottom: 0.75rem;
}
.narrative {
background: #f3f4f6;
padding: 1rem;
border-radius: 6px;
white-space: pre-line;
}
.item-list {
list-style: none;
padding: 0;
margin: 0;
}
.item-list li {
padding: 0.5rem 0;
border-bottom: 1px solid #e5e7eb;
display: flex;
align-items: flex-start;
gap: 0.5rem;
}
.item-list li:last-child {
border-bottom: none;
}
.badge {
display: inline-block;
min-width: 1.25rem;
height: 1.25rem;
line-height: 1.25rem;
text-align: center;
border-radius: 9999px;
font-size: 9pt;
font-weight: bold;
color: #fff;
flex-shrink: 0;
}
.badge-green { background: #10b981; }
.badge-red { background: #ef4444; }
.badge-amber { background: #f59e0b; }
.metrics-grid {
display: flex;
flex-wrap: wrap;
gap: 1rem;
}
.metric-box {
flex: 1 1 30%;
background: #f9fafb;
border: 1px solid #e5e7eb;
border-radius: 6px;
padding: 0.75rem;
text-align: center;
}
.metric-value {
font-size: 16pt;
font-weight: bold;
color: #111827;
}
.metric-label {
font-size: 9pt;
color: #6b7280;
}
.footer {
margin-top: 2rem;
padding-top: 1rem;
border-top: 1px solid #e5e7eb;
font-size: 9pt;
color: #9ca3af;
text-align: center;
}
</style>
</head>
<body>
<div class="header">
{% block title %}{% trans "Executive Report" %} - PX360{% endblock %}
{% block extra_css %}
<style>
body { font-size: 11pt; line-height: 1.6; color: #1f2937; }
.report-title {
border-bottom: 3px solid var(--blue);
padding-bottom: 1rem;
margin-bottom: 1.5rem;
}
.report-title h1 {
font-size: 24pt;
color: var(--blue);
margin: 0 0 0.25rem 0;
}
.meta { font-size: 10pt; color: #6b7280; }
.section { margin-bottom: 1.5rem; }
.section h2 {
font-size: 14pt;
color: #111827;
border-left: 4px solid var(--blue);
padding-left: 0.5rem;
margin-bottom: 0.75rem;
}
.narrative {
background: var(--surface);
padding: 1rem;
border-radius: 6px;
white-space: pre-line;
}
.item-list { list-style: none; padding: 0; margin: 0; }
.item-list li {
padding: 0.5rem 0;
border-bottom: 1px solid var(--border);
display: flex;
align-items: flex-start;
gap: 0.5rem;
}
.item-list li:last-child { border-bottom: none; }
.badge {
display: inline-block;
min-width: 1.25rem;
height: 1.25rem;
line-height: 1.25rem;
text-align: center;
border-radius: 9999px;
font-size: 9pt;
font-weight: bold;
color: #fff;
flex-shrink: 0;
}
.badge-green { background: #10b981; }
.badge-red { background: #ef4444; }
.badge-amber { background: #f59e0b; }
.metrics-grid { display: flex; flex-wrap: wrap; gap: 1rem; }
.metric-box {
flex: 1 1 30%;
background: #f9fafb;
border: 1px solid var(--border);
border-radius: 6px;
padding: 0.75rem;
text-align: center;
}
.metric-value { font-size: 16pt; font-weight: bold; color: #111827; }
.metric-label { font-size: 9pt; color: #6b7280; }
</style>
{% endblock %}
{% block pdf_content %}
<div class="report-title">
<h1>{% trans "Executive Summary Report" %}</h1>
<div class="meta">
<p><strong>{% trans "Report Type" %}:</strong> {{ report.get_report_type_display }}</p>
@ -165,10 +127,4 @@
</div>
</div>
{% endif %}
<div class="footer">
<p>{% trans "This report was automatically generated by the PX360 AI system." %}</p>
<p>© {% now "Y" %} PX360 - Al Hammadi Group</p>
</div>
</body>
</html>
{% endblock %}

8
apps/feedback/models.py
View File

@ -286,6 +286,14 @@ class Feedback(UUIDModel, TimeStampedModel, SoftDeleteModel):
def ai_short_description_ar(self):
return self.ai_analysis.get("short_description_ar", "")
@property
def ai_description_en(self):
return self.ai_analysis.get("description_en", "")
@property
def ai_description_ar(self):
return self.ai_analysis.get("description_ar", "")
@property
def ai_suggested_actions(self):
return self.ai_analysis.get("suggested_actions", [])

21
apps/feedback/tasks.py
View File

@ -162,6 +162,25 @@ def process_pending_sentiment_analysis():
return {"dispatched": dispatched}
@shared_task
def link_feedback_patient(feedback_id, phone=None):
"""Background patient linking for a feedback/suggestion (local DB first, then HIS).
Replaces the synchronous ``find_or_link_patient`` call that used to block the
public suggestion submit when the HIS endpoint is slow or unreachable.
Idempotent: only fills the patient if it is still empty.
"""
from apps.feedback.models import Feedback
from apps.organizations.patient_lookup import find_or_link_patient
feedback = Feedback.objects.filter(pk=feedback_id).select_related("hospital").first()
if not feedback or feedback.patient_id:
return
patient = find_or_link_patient(phone=phone, hospital=feedback.hospital)
if patient:
Feedback.objects.filter(pk=feedback_id, patient__isnull=True).update(patient=patient)
@shared_task
def analyze_suggestion_with_ai(feedback_id):
from apps.feedback.models import Feedback, FeedbackCategory, FeedbackResponse
@ -210,6 +229,8 @@ def analyze_suggestion_with_ai(feedback_id):
feedback.metadata["ai_analysis"] = {
"short_description_en": analysis.get("short_description_en", ""),
"short_description_ar": analysis.get("short_description_ar", ""),
"description_en": analysis.get("description_en", ""),
"description_ar": analysis.get("description_ar", ""),
"category": analysis.get("category", "other"),
"priority": ai_priority,
"suggested_actions": analysis.get("suggested_actions", []),

113
apps/feedback/tests_workflow_fixes.py Normal file
View File

@ -0,0 +1,113 @@
"""
Tests for the suggestion closed-loop communication fixes:
- Fix 2.1(a): public submission sends an acknowledgement SMS
- Fix 2.1(b): status change to acknowledged/closed notifies the suggester
"""
from unittest.mock import patch
from django.contrib.auth.models import Group
from django.test import TestCase
from django.urls import reverse
from apps.accounts.models import User
from apps.feedback.models import Feedback, FeedbackStatus, FeedbackType
from apps.organizations.models import Hospital
class PublicSuggestionAcknowledgementTests(TestCase):
"""Fix 2.1(a) — public suggestion submit sends an acknowledgement SMS."""
def setUp(self):
self.hospital = Hospital.objects.create(name="Ack Test Hospital", code="ACK", status="active")
@patch("apps.feedback.views.NotificationService.send_sms")
@patch("apps.feedback.tasks.analyze_suggestion_with_ai.delay")
@patch("apps.complaints.tasks.notify_staff_new_item.delay")
def test_public_suggestion_sends_acknowledgement(self, mock_notify_staff, mock_ai, mock_sms):
data = {
"contact_name": "Jane Doe",
"contact_phone": "0501234567",
"message": "Please add more seating in the waiting area.",
"hospital": str(self.hospital.id),
}
response = self.client.post(
reverse("feedback:public_suggestion_submit"),
data,
HTTP_X_REQUESTED_WITH="XMLHttpRequest",
)
self.assertEqual(response.status_code, 200)
result = response.json()
self.assertTrue(result["success"])
feedback = Feedback.objects.get()
self.assertEqual(feedback.feedback_type, FeedbackType.SUGGESTION)
# Acknowledgement SMS fired exactly once to the suggester's phone.
mock_sms.assert_called_once()
called_phone = mock_sms.call_args.args[0]
self.assertEqual(called_phone, "0501234567")
class SuggestionStatusChangeNotificationTests(TestCase):
"""Fix 2.1(b) — moving to ACKNOWLEDGED/CLOSED notifies the suggester."""
def setUp(self):
self.hospital = Hospital.objects.create(name="SC Test Hospital", code="SC", status="active")
px_group = Group.objects.create(name="PX Employee")
self.user = User.objects.create_user(email="px@example.com", password="pass12345")
self.user.groups.add(px_group)
self.client.force_login(self.user)
def _make_suggestion(self, status=FeedbackStatus.REVIEWED, phone="0509876543"):
return Feedback.objects.create(
hospital=self.hospital,
feedback_type=FeedbackType.SUGGESTION,
title="Improve signage",
message="The signage in the ER is confusing.",
status=status,
contact_name="Bob",
contact_phone=phone,
)
@patch("apps.feedback.views.NotificationService.send_sms")
def test_acknowledged_notifies_suggester(self, mock_sms):
feedback = self._make_suggestion(status=FeedbackStatus.REVIEWED, phone="0509876543")
response = self.client.post(
reverse("feedback:feedback_change_status", kwargs={"pk": feedback.pk}),
{"status": FeedbackStatus.ACKNOWLEDGED.value},
)
self.assertEqual(response.status_code, 302)
feedback.refresh_from_db()
self.assertEqual(feedback.status, FeedbackStatus.ACKNOWLEDGED.value)
mock_sms.assert_called_once()
self.assertEqual(mock_sms.call_args.args[0], "0509876543")
@patch("apps.feedback.views.NotificationService.send_sms")
def test_closed_notifies_suggester(self, mock_sms):
feedback = self._make_suggestion(status=FeedbackStatus.REVIEWED, phone="0501112233")
response = self.client.post(
reverse("feedback:feedback_change_status", kwargs={"pk": feedback.pk}),
{"status": FeedbackStatus.CLOSED.value},
)
self.assertEqual(response.status_code, 302)
feedback.refresh_from_db()
self.assertEqual(feedback.status, FeedbackStatus.CLOSED.value)
mock_sms.assert_called_once()
@patch("apps.feedback.views.NotificationService.send_sms")
def test_no_phone_skips_notification(self, mock_sms):
feedback = self._make_suggestion(status=FeedbackStatus.REVIEWED, phone="")
self.client.post(
reverse("feedback:feedback_change_status", kwargs={"pk": feedback.pk}),
{"status": FeedbackStatus.ACKNOWLEDGED.value},
)
mock_sms.assert_not_called()
@patch("apps.feedback.views.NotificationService.send_sms")
def test_reviewed_does_not_notify(self, mock_sms):
# Only acknowledged/closed notify — reviewed is an internal triage step.
feedback = self._make_suggestion(status=FeedbackStatus.SUBMITTED, phone="0509998877")
self.client.post(
reverse("feedback:feedback_change_status", kwargs={"pk": feedback.pk}),
{"status": FeedbackStatus.REVIEWED.value},
)
mock_sms.assert_not_called()

45
apps/feedback/views.py
View File

@ -16,6 +16,7 @@ from django.core.cache import cache
from apps.accounts.models import User
from apps.accounts.services import StaffActivityService
from apps.core.services import AuditService
from apps.notifications.services import NotificationService
from apps.organizations.models import Department, Hospital, Patient, Staff
from .models import (
@ -33,6 +34,10 @@ from .forms import (
FeedbackStatusChangeForm,
)
import logging
logger = logging.getLogger(__name__)
@login_required
def feedback_list(request):
@ -855,6 +860,21 @@ def feedback_change_status(request, pk):
metadata={"old_status": old_status, "new_status": new_status},
)
# Notify the suggester on acknowledge/close (closed-loop communication).
# Only for suggestions with a patient-facing contact channel; internal /
# source-user submissions have no patient to notify.
if new_status in (FeedbackStatus.ACKNOWLEDGED, FeedbackStatus.CLOSED) and feedback.contact_phone:
try:
label = "acknowledged" if new_status == FeedbackStatus.ACKNOWLEDGED else "closed"
NotificationService.send_sms(
feedback.contact_phone,
f"Your suggestion (ref {feedback.reference_number}) has been {label}. "
f"Thank you for helping us improve.",
related_object=feedback,
)
except Exception:
logger.exception("Failed to send suggestion status-change SMS")
messages.success(request, f"Suggestion status changed to {new_status}.")
return redirect("feedback:feedback_detail", pk=pk)
@ -986,13 +1006,11 @@ def public_suggestion_submit(request):
"other": FeedbackCategory.OTHER,
}
# Auto-link patient by phone (local first, then HIS). Never blocks creation.
from apps.organizations.patient_lookup import find_or_link_patient
linked_patient = find_or_link_patient(phone=contact_phone, hospital=hospital)
# Auto-link patient by phone (local first, then HIS) — moved to background task
# to avoid blocking the response when the HIS endpoint is slow.
feedback = Feedback(
patient=linked_patient,
patient=None,
hospital=hospital,
feedback_type=FeedbackType.SUGGESTION,
title=title,
@ -1009,11 +1027,24 @@ def public_suggestion_submit(request):
)
feedback.save()
# Acknowledge receipt to the suggester (closed-loop communication).
if contact_phone:
try:
NotificationService.send_sms(
contact_phone,
f"Thank you for your suggestion (ref {feedback.reference_number}). "
f"We've received it and our team will review it.",
related_object=feedback,
)
except Exception:
logger.exception("Failed to send suggestion acknowledgement SMS")
try:
from apps.feedback.tasks import analyze_suggestion_with_ai
from apps.feedback.tasks import analyze_suggestion_with_ai, link_feedback_patient
from apps.complaints.tasks import notify_staff_new_item
analyze_suggestion_with_ai.delay(str(feedback.id))
notify_staff_new_item.delay("suggestion", str(feedback.id))
link_feedback_patient.delay(str(feedback.id), phone=contact_phone)
except Exception:
pass
@ -1053,7 +1084,7 @@ def feedback_create_action(request, pk):
if not action_description:
ai = feedback.ai_analysis
action_description = ai.get("short_description_en", feedback.message[:500])
action_description = ai.get("description_en", "") or ai.get("short_description_en", feedback.message[:500])
feedback_ct = ContentType.objects.get_for_model(Feedback)

2
apps/integrations/api_serializers.py
View File

@ -22,7 +22,7 @@ class ExternalComplaintCreateSerializer(serializers.Serializer):
contact_phone = serializers.CharField(max_length=20, required=True)
contact_email = serializers.EmailField(required=False, allow_blank=True, default="")
relation_to_patient = serializers.ChoiceField(
choices=[("patient", "Patient"), ("relative", "Relative"), ("friend", "Friend"), ("other", "Other")],
choices=[("patient", "Patient"), ("relative", "Relative")],
required=False,
allow_blank=True,
default="",

3
apps/notifications/services.py
View File

@ -14,6 +14,7 @@ from django.conf import settings
from django.core.mail import send_mail
from .models import NotificationLog
from apps.surveys.services import SurveyDeliveryService
logger = logging.getLogger(__name__)
@ -682,7 +683,7 @@ class NotificationService:
NotificationLog instance
"""
patient = survey_instance.patient
survey_url = survey_instance.get_survey_url()
survey_url = SurveyDeliveryService.generate_survey_url(survey_instance)
# Determine recipient based on delivery channel
if survey_instance.delivery_channel == "sms":

1
apps/observations/admin.py
View File

@ -248,5 +248,4 @@ class ObservationSLAConfigAdmin(admin.ModelAdmin):
fieldsets = (
(None, {"fields": ("hospital", "severity", "sla_hours", "is_active")}),
("Reminders", {"fields": ("first_reminder_hours_after", "second_reminder_hours_after")}),
("Escalation", {"fields": ("escalation_hours_after",)}),
)

29
apps/observations/migrations/0020_remove_observation_dept_response_acceptance_notes_and_more.py Normal file
View File

@ -0,0 +1,29 @@
# Generated by Django 6.0.1 on 2026-07-07 10:11
from django.db import migrations
class Migration(migrations.Migration):
dependencies = [
('observations', '0019_remove_inquiry_observation_satisfaction'),
]
operations = [
migrations.RemoveField(
model_name='observation',
name='dept_response_acceptance_notes',
),
migrations.RemoveField(
model_name='observation',
name='dept_response_acceptance_status',
),
migrations.RemoveField(
model_name='observation',
name='dept_response_accepted_at',
),
migrations.RemoveField(
model_name='observation',
name='dept_response_accepted_by',
),
]

26
apps/observations/models.py
View File

@ -555,32 +555,6 @@ class Observation(UUIDModel, TimeStampedModel, SoftDeleteModel):
response_token_used = models.BooleanField(default=False)
response_token_sent_at = models.DateTimeField(null=True, blank=True)
# Department response acceptance review
dept_response_acceptance_status = models.CharField(
max_length=20,
choices=[
("pending", "Pending Review"),
("acceptable", "Acceptable"),
("not_acceptable", "Not Acceptable"),
],
default="pending",
help_text="Review status of the department response",
)
dept_response_accepted_by = models.ForeignKey(
settings.AUTH_USER_MODEL,
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name="reviewed_observation_dept_responses",
help_text="User who reviewed the department response",
)
dept_response_accepted_at = models.DateTimeField(
null=True, blank=True, help_text="When the department response was reviewed",
)
dept_response_acceptance_notes = models.TextField(
blank=True, help_text="Notes about the acceptance decision",
)
# Resolution
resolved_at = models.DateTimeField(null=True, blank=True)
resolved_by = models.ForeignKey(

66
apps/observations/tests_workflow_fixes.py Normal file
View File

@ -0,0 +1,66 @@
"""
Tests for the observation_send_to fix (Fix 1.2):
the department branch used to read observation.reference_number (which does not
exist on Observation) and crash with AttributeError. It now uses tracking_code.
"""
from unittest.mock import patch
from django.contrib.auth.models import Group
from django.test import TestCase
from django.urls import reverse
from apps.accounts.models import User
from apps.observations.models import Observation, ObservationStatus
from apps.organizations.models import Department, Hospital, LocationType
class ObservationSendToFixTests(TestCase):
"""Fix 1.2 — observation_send_to department branch must not crash."""
def setUp(self):
self.hospital = Hospital.objects.create(name="Obs Fix Hospital", code="OFX", status="active")
px_group = Group.objects.create(name="PX Admin")
self.user = User.objects.create_user(email="obs@example.com", password="pass12345")
self.user.groups.add(px_group)
self.client.force_login(self.user)
self.observation = Observation.objects.create(
hospital=self.hospital,
location_type=LocationType.OP,
description="Spilled hazard in the corridor near the lab.",
status=ObservationStatus.IN_PROGRESS.value,
severity="medium",
)
self.department = Department.objects.create(
hospital=self.hospital, name="Lab", name_en="Lab", code="ofx_lab", status="active"
)
@patch("apps.notifications.services.NotificationService.send_sms")
@patch("apps.notifications.services.NotificationService.send_email")
@patch("apps.organizations.department_contacts.get_champion_and_manager")
def test_send_to_department_returns_200_not_500(self, mock_champions, mock_email, mock_sms):
# Provide a minimal champion target so the department branch is taken
# and the notification loop (which used to reference reference_number) runs.
mock_champions.return_value = [
{
"staff": None,
"user": self.user,
"email": "champ@example.com",
"phone": "0500000000",
"label": "Champion",
}
]
response = self.client.post(
reverse("observations:observation_send_to", kwargs={"pk": self.observation.pk}),
{"recipient_type": "department", "department_id": str(self.department.id)},
HTTP_X_REQUESTED_WITH="XMLHttpRequest",
)
# Before the fix this raised AttributeError -> HTTP 500.
self.assertEqual(response.status_code, 200, response.content)
result = response.json()
self.assertTrue(result.get("success", False))
self.observation.refresh_from_db()
self.assertTrue(self.observation.sent_to_department)
self.assertEqual(self.observation.assigned_department_id, self.department.id)

2
apps/observations/urls.py
View File

@ -66,8 +66,6 @@ urlpatterns = [
path("<uuid:pk>/send-to/", views.observation_send_to, name="observation_send_to"),
# Department Response
path("<uuid:pk>/department-response/", views.observation_department_response, name="observation_department_response"),
# Review Department Response
path("<uuid:pk>/review-dept-response/", views.observation_review_dept_response, name="observation_review_dept_response"),
# Send Department Response Reminder
path("<uuid:pk>/send-dept-response-reminder/", views.observation_send_dept_response_reminder, name="observation_send_dept_response_reminder"),
# Convert to PX Action

147
apps/observations/views.py
View File

@ -598,12 +598,19 @@ def observation_detail(request, pk):
except PXAction.DoesNotExist:
pass
# Get assignable users and departments
departments = Department.objects.filter(status="active")
# Get assignable users and departments.
# Only offer departments that can actually receive a send (have a champion or an
# emailable manager) — matches the send endpoint's get_champion_and_manager() check.
from apps.organizations.department_contacts import has_contact_target
from apps.core.utils import get_assignable_users
assignable_users = get_assignable_users(user.hospital)
departments = (
Department.objects.filter(status="active")
.select_related("champion", "manager", "manager__staff_profile")
)
if user.hospital:
departments = departments.filter(hospital=user.hospital)
departments = [d for d in departments if has_contact_target(d)]
# Forms
triage_form = ObservationTriageForm(
@ -641,7 +648,6 @@ def observation_detail(request, pk):
"can_convert": user.is_px_admin() or user.is_hospital_admin() or user.is_px_management() or user.is_px_employee(),
"can_send_to_department": user.is_px_admin() or user.is_hospital_admin() or user.is_px_management() or user.is_px_employee() or user.is_department_manager() or user.is_px_management(),
"can_respond_to_department": user.is_px_admin() or user.is_hospital_admin() or user.is_px_management() or user.is_px_employee() or (user.is_champion() and observation.assigned_department == user.department),
"can_review_dept_response": user.is_px_admin() or user.is_hospital_admin() or user.is_px_management() or user.is_px_employee(),
"can_send_reminder": user.is_px_admin() or user.is_hospital_admin() or user.is_px_management() or user.is_px_employee(),
"can_delete": user.is_px_admin() or user.is_hospital_admin() or user.is_px_management() or user.is_px_employee(),
"can_admin": user.is_px_admin() or user.is_hospital_admin(),
@ -1555,8 +1561,8 @@ def observation_send_to(request, pk):
try:
NotificationService.send_email(
email=target["email"],
subject=f"Observation Sent to Department - {observation.reference_number}",
message=f"Observation #{observation.reference_number} has been sent to your department ({department.name}).\n\n{link}",
subject=f"Observation Sent to Department - {observation.tracking_code}",
message=f"Observation #{observation.tracking_code} has been sent to your department ({department.name}).\n\n{link}",
related_object=observation,
)
except Exception:
@ -1565,7 +1571,7 @@ def observation_send_to(request, pk):
try:
NotificationService.send_sms(
target["phone"],
f"PX360: Observation #{observation.reference_number} sent to {department.name}. Review: {link}",
f"PX360: Observation #{observation.tracking_code} sent to {department.name}. Review: {link}",
related_object=observation,
)
except Exception:
@ -1632,10 +1638,6 @@ def observation_department_response(request, pk):
observation.department_responded_at = timezone.now()
observation.department_responded_by = request.user
observation.dept_response_is_overdue = False
observation.dept_response_acceptance_status = "pending"
observation.dept_response_accepted_by = None
observation.dept_response_accepted_at = None
observation.dept_response_acceptance_notes = ""
observation.save()
# Generate AI summary
@ -1744,129 +1746,6 @@ Generate a JSON response with:
return render(request, "observations/observation_department_response.html", context)
@login_required
@require_http_methods(["POST"])
def observation_review_dept_response(request, pk):
observation = get_object_or_404(Observation, pk=pk)
user = request.user
if not (
user.is_px_admin() or user.is_hospital_admin()
or user.is_px_management() or user.is_px_employee()
):
messages.error(request, "You don't have permission to review department responses.")
return redirect("observations:observation_detail", pk=pk)
if not observation.department_responded_at:
messages.error(request, "No department response to review.")
return redirect("observations:observation_detail", pk=pk)
status = request.POST.get("acceptance_status")
if status not in ("acceptable", "not_acceptable"):
messages.error(request, "Invalid acceptance status.")
return redirect("observations:observation_detail", pk=pk)
notes = request.POST.get("acceptance_notes", "").strip()
if status == "not_acceptable":
observation.dept_response_acceptance_status = "not_acceptable"
observation.dept_response_accepted_by = user
observation.dept_response_accepted_at = timezone.now()
observation.dept_response_acceptance_notes = notes
observation.department_response_en = ""
observation.department_response_ar = ""
observation.department_response_summary_en = ""
observation.department_response_summary_ar = ""
observation.department_responded_at = None
observation.department_responded_by = None
observation.save(
update_fields=[
"dept_response_acceptance_status",
"dept_response_accepted_by",
"dept_response_accepted_at",
"dept_response_acceptance_notes",
"department_response_en",
"department_response_ar",
"department_response_summary_en",
"department_response_summary_ar",
"department_responded_at",
"department_responded_by",
]
)
dept = observation.assigned_department
if dept and dept.champion and dept.champion.user and dept.champion.user.email:
try:
from apps.notifications.services import NotificationService, get_email_header_html
NotificationService.send_email(
email=dept.champion.user.email,
subject=f"Action Required: Observation {observation.tracking_code} - Response Rejected",
message=(
f"Your department's response for observation {observation.tracking_code} has been rejected.\n\n"
f"Reason: {notes}\n\n"
f"Please revise and resubmit your response."
),
html_message=f"""
<div style="font-family: 'Segoe UI', Tahoma, sans-serif; max-width: 600px; margin: 0 auto; border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
{get_email_header_html()}
<div style="padding: 20px;">
<h2 style="color: #005696; font-size: 18px; margin: 0 0 12px 0;">Response Rejected - Observation {observation.tracking_code}</h2>
<p style="margin: 0 0 12px 0;">Your department's response for observation <strong>{observation.tracking_code}</strong> has been rejected.</p>
<div style="background: #fef2f2; padding: 12px; border-radius: 6px; margin: 0 0 12px 0;">
<p style="margin: 0;"><strong>Reason:</strong> {notes}</p>
</div>
<p style="margin: 0; color: #6b7280;">Please revise and resubmit your response.</p>
</div>
</div>
""",
related_object=observation,
)
except Exception:
import logging
logging.getLogger(__name__).exception("Failed to send observation dept response rejection email")
ObservationNote.objects.create(
observation=observation,
note=f"Department response rejected by {user.get_full_name()}. Reason: {notes}",
created_by=user,
is_internal=True,
)
messages.success(request, "Department response rejected. The department has been notified to resubmit.")
else:
observation.dept_response_acceptance_status = status
observation.dept_response_accepted_by = user
observation.dept_response_accepted_at = timezone.now()
observation.dept_response_acceptance_notes = notes
observation.save(
update_fields=[
"dept_response_acceptance_status",
"dept_response_accepted_by",
"dept_response_accepted_at",
"dept_response_acceptance_notes",
]
)
ObservationStatusLog.objects.create(
observation=observation,
from_status=observation.status,
to_status=observation.status,
changed_by=user,
comment=f"Department response marked as {status} by {user.get_full_name()}",
)
ObservationNote.objects.create(
observation=observation,
note=f"Department response review: {status}. {notes}",
created_by=user,
is_internal=True,
)
messages.success(request, f"Department response marked as {status}.")
return redirect("observations:observation_detail", pk=pk)
@login_required
@require_http_methods(["POST"])
@ -2137,7 +2016,6 @@ def observation_respond_with_token(request, pk, token):
observation.department_response_ar = response_ar
observation.department_responded_at = timezone.now()
observation.dept_response_is_overdue = False
observation.dept_response_acceptance_status = "pending"
observation.response_token_used = True
observation.save()
@ -2192,4 +2070,5 @@ def observation_pdf(request, pk):
'observations/observation_pdf.html',
{'object': obj},
f'observation_{obj.tracking_code}.pdf',
obj=obj,
)

66
apps/organizations/ui_views.py
View File

@ -1967,6 +1967,16 @@ def department_detail(request, pk):
department=department, feedback_type=FeedbackType.SUGGESTION
).select_related("assigned_to", "staff").order_by("-created_at")
# QI Projects linked to this department (templates excluded)
from apps.projects.models import QIProject
qi_projects = (
QIProject.objects.filter(departments=department, is_template=False)
.select_related("hospital", "project_lead")
.prefetch_related("departments", "team_members")
.order_by("-created_at")
)
appreciation_status_filter = request.GET.get("appreciation_status")
if appreciation_status_filter:
appreciations = appreciations.filter(status=appreciation_status_filter)
@ -1987,6 +1997,7 @@ def department_detail(request, pk):
"total_observations": observations.count(),
"total_appreciations": appreciations.count(),
"total_suggestions": suggestions.count(),
"total_projects": qi_projects.count(),
}
search_query = request.GET.get("search", "").strip()
@ -2225,6 +2236,7 @@ def department_detail(request, pk):
"observations": observations[:5],
"appreciations": appreciations[:50],
"suggestions": suggestions[:50],
"projects": qi_projects[:10],
"stats": stats,
"active_tab": active_tab,
"assignable_staff": assignable_staff,
@ -3184,6 +3196,60 @@ def department_record_suggestion(request, pk):
return JsonResponse(data)
@login_required
def department_record_project(request, pk):
"""AJAX endpoint returning a QI project summary for the department-detail modal."""
from django.http import JsonResponse
from apps.projects.models import QIProject
project = get_object_or_404(
QIProject.objects.select_related("hospital", "project_lead").prefetch_related(
"departments", "team_members", "tasks"
),
pk=pk,
is_template=False,
)
user = request.user
if not (
user.is_px_admin()
or user.is_hospital_admin()
or user.is_px_management()
or user.is_px_employee()
or user.is_department_manager()
or user.is_director()
or (
user.is_champion()
and project.departments.filter(champion_id=user.staff_profile.id).exists()
)
):
return JsonResponse({"error": "Access denied"}, status=403)
tasks_total = project.tasks.count()
tasks_completed = project.tasks.filter(status="completed").count()
tasks_pending = project.tasks.exclude(status__in=["completed", "cancelled"]).count()
data = {
"type": "project",
"reference": str(project.id)[:8].upper(),
"title": project.name or "",
"description": project.description or "",
"status": project.status,
"status_display": project.get_status_display(),
"lead": project.project_lead.get_full_name() if project.project_lead else "-",
"departments": [d.get_localized_name() for d in project.departments.all()],
"team_count": project.team_members.count(),
"tasks_total": tasks_total,
"tasks_completed": tasks_completed,
"tasks_pending": tasks_pending,
"start_date": project.start_date.strftime("%Y-%m-%d") if project.start_date else "-",
"target_completion_date": project.target_completion_date.strftime("%Y-%m-%d") if project.target_completion_date else "-",
"created_at": project.created_at.strftime("%Y-%m-%d %H:%M"),
"detail_url": reverse("projects:project_detail", args=[project.pk]),
}
return JsonResponse(data)
@login_required
def department_record_appreciation(request, pk):
from django.http import JsonResponse

1
apps/organizations/urls.py
View File

@ -88,6 +88,7 @@ urlpatterns = [
path("api/dept-observation/<uuid:pk>/", ui_views.department_record_observation, name="department_record_observation"),
path("api/dept-suggestion/<uuid:pk>/", ui_views.department_record_suggestion, name="department_record_suggestion"),
path("api/dept-appreciation/<uuid:pk>/", ui_views.department_record_appreciation, name="department_record_appreciation"),
path("api/dept-project/<uuid:pk>/", ui_views.department_record_project, name="department_record_project"),
path("departments/<uuid:pk>/set-role/", ui_views.set_department_role, name="set_department_role"),
path("staff/create/", ui_views.staff_create, name="staff_create"),
path("staff/import/", ui_views.staff_import, name="staff_import"),

21
apps/projects/admin.py
View File

@ -3,7 +3,7 @@ Projects admin
"""
from django.contrib import admin
from .models import QIProject, QIProjectTask
from .models import QIProject, QIProjectTask, QIProjectTaskAttachment
class QIProjectTaskInline(admin.TabularInline):
@ -89,13 +89,30 @@ class QIProjectTaskAdmin(admin.ModelAdmin):
('Status & Dates', {
'fields': ('status', 'due_date', 'completed_date')
}),
('Reminders', {
'fields': ('reminder_sent_at', 'second_reminder_sent_at')
}),
('Metadata', {
'fields': ('created_at', 'updated_at')
}),
)
readonly_fields = ['created_at', 'updated_at']
readonly_fields = ['created_at', 'updated_at', 'reminder_sent_at', 'second_reminder_sent_at']
def get_queryset(self, request):
qs = super().get_queryset(request)
return qs.select_related('project', 'assigned_to')
@admin.register(QIProjectTaskAttachment)
class QIProjectTaskAttachmentAdmin(admin.ModelAdmin):
"""QI Project task attachment admin"""
list_display = ['task', 'filename', 'file_size', 'uploaded_by', 'created_at']
list_filter = ['created_at']
search_fields = ['filename', 'description', 'task__title']
readonly_fields = ['filename', 'file_type', 'file_size', 'created_at', 'updated_at']
ordering = ['-created_at']
def get_queryset(self, request):
qs = super().get_queryset(request)
return qs.select_related('task', 'uploaded_by')

96
apps/projects/forms.py
View File

@ -10,9 +10,9 @@ from django.utils.translation import gettext_lazy as _
from apps.accounts.models import User
from apps.core.form_mixins import HospitalFieldMixin
from apps.organizations.models import Department
from apps.organizations.models import Department, Staff
from .models import FOCUSPhase, PDCAPhase, QIProject, QIProjectTask
from .models import FOCUSPhase, PDCAPhase, QIProject, QIProjectTask, QIProjectTaskAttachment
class QIProjectForm(HospitalFieldMixin, forms.ModelForm):
@ -33,6 +33,7 @@ class QIProjectForm(HospitalFieldMixin, forms.ModelForm):
"hospital",
"departments",
"project_lead",
"team_members",
"status",
"start_date",
"target_completion_date",
@ -106,7 +107,10 @@ class QIProjectForm(HospitalFieldMixin, forms.ModelForm):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
# Filter department choices based on hospital
# Project lead is required on this form (consistent with ConvertToProjectForm)
self.fields["project_lead"].required = True
# Resolve hospital id from data/initial/instance/user (same precedence as before)
hospital_id = None
if self.data.get("hospital"):
hospital_id = self.data.get("hospital")
@ -125,22 +129,62 @@ class QIProjectForm(HospitalFieldMixin, forms.ModelForm):
self.fields["departments"].queryset = Department.objects.filter(
hospital_id=hospital_id, status="active"
).order_by("name")
# Filter project lead based on hospital
from apps.organizations.models import Staff
# Broad queryset; clean_project_lead / clean_team_members enforce the
# authoritative rules (role-holder of a selected dept, or PX management/employee).
staff_qs = Staff.objects.filter(
hospital_id=hospital_id, status="active"
).order_by("first_name", "last_name")
self.fields["project_lead"].queryset = staff_qs
self.fields["team_members"].queryset = staff_qs
else:
self.fields["departments"].queryset = Department.objects.none()
self.fields["project_lead"].queryset = Department.objects.none()
self.fields["project_lead"].queryset = Staff.objects.none()
self.fields["team_members"].queryset = Staff.objects.none()
def save(self, *args, **kwargs):
instance = super().save(*args, **kwargs)
# Team membership is derived from the selected departments' champion + manager.
instance.sync_team_members_from_departments()
return instance
def _role_holder_ids_for_departments(self, departments):
"""Return the set of Staff PKs who are champion or manager (via staff_profile)
of any of the given departments."""
ids = set()
if not departments:
return ids
for dept in Department.objects.filter(pk__in=[d.pk for d in departments]):
if dept.champion_id:
ids.add(dept.champion_id)
if dept.manager_id and dept.manager is not None:
sp = getattr(dept.manager, "staff_profile", None)
if sp and sp.pk:
ids.add(sp.pk)
return ids
def clean_project_lead(self):
lead = self.cleaned_data.get("project_lead")
if not lead:
return lead
departments = self.cleaned_data.get("departments") or []
if lead.pk in self._role_holder_ids_for_departments(departments):
return lead
# PX Management / PX Employee may also lead (PX-led initiatives)
if lead.user and (lead.user.is_px_management() or lead.user.is_px_employee()):
return lead
raise forms.ValidationError(
_("Project lead must be the manager or champion of a selected department, "
"or a PX Management / PX Employee staff member.")
)
def clean_team_members(self):
members = self.cleaned_data.get("team_members") or []
departments = self.cleaned_data.get("departments") or []
if not members:
return members
valid_ids = self._role_holder_ids_for_departments(departments)
invalid = [m for m in members if m.pk not in valid_ids]
if invalid:
names = ", ".join(m.get_full_name() for m in invalid)
raise forms.ValidationError(
_("%(names)s is not the manager or champion of a selected department."),
params={"names": names},
)
return members
class QIProjectTaskForm(forms.ModelForm):
@ -243,15 +287,29 @@ class QIProjectTaskForm(forms.ModelForm):
self.fields["focus_phase"].queryset = FOCUSPhase.objects.none()
self.fields["focus_phase"].widget = forms.HiddenInput()
# Filter assigned_to choices based on project team members
# (derived from each department's champion + manager, plus the project lead).
# Filter assigned_to choices to the project's team members
# (explicitly selected managers/champions + the project lead).
if self.project and self.project.pk:
from apps.organizations.models import Staff
self.fields["assigned_to"].queryset = Staff.objects.filter(
pk__in=self.project.get_team_members_staff_ids()
).order_by("first_name", "last_name")
self.fields["assigned_to"].queryset = self.project.team_members.all().order_by("first_name", "last_name")
else:
self.fields["assigned_to"].queryset = User.objects.none()
self.fields["assigned_to"].queryset = Staff.objects.none()
class QIProjectTaskAttachmentForm(forms.ModelForm):
"""File attachment upload for a QI project task."""
class Meta:
model = QIProjectTaskAttachment
fields = ["file", "description"]
widgets = {
"description": forms.Textarea(
attrs={
"class": "w-full px-4 py-2.5 rounded-xl border border-slate-200 focus:border-navy focus:ring-2 focus:ring-navy/20 transition text-sm resize-none",
"rows": 2,
"placeholder": _("Optional description..."),
}
),
}
class QIProjectTemplateForm(HospitalFieldMixin, forms.ModelForm):

19
apps/projects/migrations/0005_alter_qiproject_departments.py Normal file
View File

@ -0,0 +1,19 @@
# Generated by Django 6.0.1 on 2026-07-07 07:32
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('organizations', '0016_patient_verbose_names'),
('projects', '0004_qi_multi_department'),
]
operations = [
migrations.AlterField(
model_name='qiproject',
name='departments',
field=models.ManyToManyField(blank=True, help_text='Departments involved in this QI project.', related_name='qi_projects', to='organizations.department'),
),
]

23
apps/projects/migrations/0006_qiprojecttask_reminder_sent_at_and_more.py Normal file
View File

@ -0,0 +1,23 @@
# Generated by Django 6.0.1 on 2026-07-07 08:02
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('projects', '0005_alter_qiproject_departments'),
]
operations = [
migrations.AddField(
model_name='qiprojecttask',
name='reminder_sent_at',
field=models.DateTimeField(blank=True, null=True),
),
migrations.AddField(
model_name='qiprojecttask',
name='second_reminder_sent_at',
field=models.DateTimeField(blank=True, null=True),
),
]

38
apps/projects/migrations/0007_qiprojecttaskattachment.py Normal file
View File

@ -0,0 +1,38 @@
# Generated by Django 6.0.1 on 2026-07-07 09:24
import django.core.validators
import django.db.models.deletion
import uuid
from django.conf import settings
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('projects', '0006_qiprojecttask_reminder_sent_at_and_more'),
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
migrations.CreateModel(
name='QIProjectTaskAttachment',
fields=[
('created_at', models.DateTimeField(auto_now_add=True, db_index=True)),
('updated_at', models.DateTimeField(auto_now=True)),
('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
('file', models.FileField(upload_to='qi_tasks/%Y/%m/%d/', validators=[django.core.validators.FileExtensionValidator(allowed_extensions=['pdf', 'doc', 'docx', 'xls', 'xlsx', 'jpg', 'jpeg', 'png', 'zip'])])),
('filename', models.CharField(blank=True, max_length=500)),
('file_type', models.CharField(blank=True, max_length=100)),
('file_size', models.IntegerField(default=0, help_text='File size in bytes')),
('description', models.TextField(blank=True)),
('task', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='attachments', to='projects.qiprojecttask')),
('uploaded_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='qi_task_attachments', to=settings.AUTH_USER_MODEL)),
],
options={
'verbose_name': 'QI Project Task Attachment',
'verbose_name_plural': 'QI Project Task Attachments',
'ordering': ['-created_at'],
},
),
]

57
apps/projects/models.py
View File

@ -11,6 +11,8 @@ This module implements QI project management:
from django.db import models
from django.utils.translation import gettext_lazy as _
from django.contrib.contenttypes.fields import GenericRelation
from django.core.validators import FileExtensionValidator
from apps.core.models import StatusChoices, TimeStampedModel, UUIDModel
@ -60,7 +62,7 @@ class QIProject(UUIDModel, TimeStampedModel):
"organizations.Department",
blank=True,
related_name="qi_projects",
help_text="Departments involved in this QI project. Team membership is derived from each department's champion and manager.",
help_text="Departments involved in this QI project.",
)
# Project lead
@ -73,7 +75,7 @@ class QIProject(UUIDModel, TimeStampedModel):
"accounts.User", on_delete=models.SET_NULL, null=True, blank=True, related_name="created_qi_projects"
)
# Team members
# Team members (explicitly selected managers/champions of linked departments)
team_members = models.ManyToManyField("organizations.Staff", blank=True, related_name="qi_project_memberships")
# Status
@ -190,9 +192,16 @@ class QIProjectTask(UUIDModel, TimeStampedModel):
due_date = models.DateField(null=True, blank=True)
completed_date = models.DateField(null=True, blank=True)
# Reminder tracking (deadline-relative email reminders sent to assignee)
reminder_sent_at = models.DateTimeField(null=True, blank=True)
second_reminder_sent_at = models.DateTimeField(null=True, blank=True)
# Order
order = models.IntegerField(default=0)
# Notes (reuses the generic core.Note model)
notes = GenericRelation("core.Note")
class Meta:
ordering = ["project", "order"]
@ -200,6 +209,50 @@ class QIProjectTask(UUIDModel, TimeStampedModel):
return f"{self.project.name} - {self.title}"
class QIProjectTaskAttachment(UUIDModel, TimeStampedModel):
"""File attachment on a QI project task (evidence, references, etc.)."""
task = models.ForeignKey(QIProjectTask, on_delete=models.CASCADE, related_name="attachments")
file = models.FileField(
upload_to="qi_tasks/%Y/%m/%d/",
validators=[
FileExtensionValidator(
allowed_extensions=["pdf", "doc", "docx", "xls", "xlsx", "jpg", "jpeg", "png", "zip"]
)
],
)
filename = models.CharField(max_length=500, blank=True)
file_type = models.CharField(max_length=100, blank=True)
file_size = models.IntegerField(default=0, help_text="File size in bytes")
uploaded_by = models.ForeignKey(
"accounts.User", on_delete=models.SET_NULL, null=True, blank=True, related_name="qi_task_attachments"
)
description = models.TextField(blank=True)
class Meta:
ordering = ["-created_at"]
verbose_name = "QI Project Task Attachment"
verbose_name_plural = "QI Project Task Attachments"
def __str__(self):
return f"{self.task.title} - {self.filename}"
def save(self, *args, **kwargs):
"""Auto-populate filename / file_size / file_type from the uploaded file."""
if self.file:
if not self.filename:
self.filename = self.file.name
if not self.file_size and hasattr(self.file, "size"):
self.file_size = self.file.size
if not self.file_type:
import mimetypes
self.file_type = mimetypes.guess_type(self.file.name)[0] or ""
super().save(*args, **kwargs)
class PDCAPhase(UUIDModel, TimeStampedModel):
"""
PDCA (Plan-Do-Check-Act) phase within a QI project.

73
apps/projects/signals.py
View File

@ -2,23 +2,23 @@
Signals for QI Projects.
- Sends a notification when a task is assigned.
- Keeps `team_members` in sync with the champion + manager of each linked
department whenever the `departments` M2M changes.
"""
import logging
from django.db.models.signals import m2m_changed, post_save
from django.db.models.signals import post_save
from django.dispatch import receiver
from apps.projects.models import QIProject
logger = logging.getLogger(__name__)
@receiver(post_save, sender="projects.QIProjectTask")
def notify_task_assignment(sender, instance, created, **kwargs):
"""Send an in-app notification when a QI task is assigned to a staff member."""
"""Notify the assignee when a QI task is assigned (email + in-app).
Fires only on new task creation with an assignee. send_email also creates
the matching in-app notification, so no separate call is needed.
"""
if not instance.assigned_to:
return
@ -27,35 +27,48 @@ def notify_task_assignment(sender, instance, created, **kwargs):
return
user = getattr(instance.assigned_to, "user", None)
if not user:
if not user or not getattr(user, "email", None):
return
try:
from apps.notifications.services import create_in_app_notification
from django.conf import settings
from apps.notifications.services import NotificationService
create_in_app_notification(
user=user,
title=f"New QI Task: {instance.title}",
message=f"You have been assigned a task in project '{instance.project.name}'.",
project_url = f"{getattr(settings, 'SITE_URL', 'http://localhost:8000').rstrip('/')}/projects/{instance.project.id}/"
due = instance.due_date.strftime("%Y-%m-%d") if instance.due_date else None
message = f"You have been assigned a task in project '{instance.project.name}'."
if due:
message += f"\nDue date: {due}"
message += f"\n\nTask: {instance.title}\nOpen: {project_url}"
html_message = f"""
<div style="font-family: 'Segoe UI', Tahoma, sans-serif; max-width: 600px; margin: 0 auto; border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
<div style="padding: 20px;">
<h2 style="color: #005696; font-size: 18px; margin: 0 0 12px 0;">New QI Task Assigned</h2>
<p style="margin: 0 0 12px 0;">You have been assigned a task in project <strong>{instance.project.name}</strong>.</p>
<p style="margin: 0 0 12px 0;"><strong>Task:</strong> {instance.title}</p>
{'<p style="margin: 0 0 12px 0;"><strong>Due date:</strong> ' + due + '</p>' if due else ''}
<div style="text-align: center; margin: 20px 0;">
<a href="{project_url}" style="background: #005696; color: white; padding: 10px 24px; border-radius: 8px; text-decoration: none; font-weight: 600;">Open Project</a>
</div>
</div>
</div>
"""
NotificationService.send_email(
email=user.email,
subject=f"New QI Task: {instance.title}",
message=message,
html_message=html_message,
related_object=instance,
metadata={
"notification_type": "qi_task_assigned",
"task_id": str(instance.id),
"project_id": str(instance.project.id),
},
notification_type="qi_task_assigned",
action_url=f"/projects/{instance.project.id}/",
user=user,
)
except Exception as e:
logger.warning(f"Failed to send QI task notification: {e}")
@receiver(m2m_changed, sender=QIProject.departments.through)
def sync_team_on_departments_change(sender, instance, action, **kwargs):
"""Rebuild the derived `team_members` set whenever the project's departments change.
Fires on `post_add` / `post_remove` / `post_clear` so that programmatic,
admin, and form-driven edits all stay consistent. The sync is idempotent.
"""
if action not in ("post_add", "post_remove", "post_clear"):
return
if not instance.pk:
return
try:
instance.sync_team_members_from_departments()
except Exception as e: # defensive: never break an M2M write on sync failure
logger.warning(f"Failed to sync QI team members for project {instance.pk}: {e}")

116
apps/projects/tasks.py Normal file
View File

@ -0,0 +1,116 @@
"""Celery tasks for the QI Projects app."""
import logging
from datetime import datetime, time as datetime_time, timedelta
from celery import shared_task
from django.conf import settings
from django.utils import timezone
logger = logging.getLogger(__name__)
FIRST_REMINDER_HOURS_BEFORE = 24
SECOND_REMINDER_HOURS_BEFORE = 6
@shared_task
def send_qi_task_reminders():
"""Send deadline-approaching reminders for assigned QI tasks.
Runs every 15 minutes via Celery Beat. Sends a first reminder 24h before the
due date and a second reminder 6h before. Each reminder fires at most once per
task (deduped via `reminder_sent_at` / `second_reminder_sent_at`). Tasks with
no email-capable assignee or whose send fails are retried on subsequent runs.
"""
from apps.notifications.services import NotificationService
from .models import QIProjectTask
now = timezone.now()
tz = timezone.get_current_timezone()
site_url = getattr(settings, "SITE_URL", "http://localhost:8000").rstrip("/")
def _deadline(task):
# Interpret due_date (a date) as end-of-day in the current tz.
return timezone.make_aware(datetime.combine(task.due_date, datetime_time(23, 59, 59)), tz)
def _send(task, hours_before, label):
project_url = f"{site_url}/projects/{task.project.id}/"
message = (
f"Reminder ({label}): The task '{task.title}' in project "
f"'{task.project.name}' is due on {task.due_date.strftime('%Y-%m-%d')} "
f"({hours_before}h remaining)."
)
NotificationService.send_email(
email=task.assigned_to.user.email,
subject=f"QI Task Reminder: {task.title}",
message=message,
related_object=task,
metadata={
"notification_type": "qi_task_reminder",
"task_id": str(task.id),
"project_id": str(task.project.id),
"reminder": label,
"hours_before": hours_before,
},
notification_type="qi_task_reminder",
user=task.assigned_to.user,
)
logger.info(
f"QI task {label} reminder sent for task {task.id} "
f"(assignee {task.assigned_to_id}, due {task.due_date})"
)
first_count = 0
second_count = 0
# First reminders: due within 24h, not yet reminded
for task in QIProjectTask.objects.filter(
assigned_to__isnull=False,
status__in=["pending", "active"],
due_date__isnull=False,
reminder_sent_at__isnull=True,
project__is_template=False,
).select_related("assigned_to__user", "project"):
deadline = _deadline(task)
if not (deadline - timedelta(hours=FIRST_REMINDER_HOURS_BEFORE) <= now < deadline):
continue
user = task.assigned_to.user
if not user or not getattr(user, "email", None):
logger.warning(f"QI task {task.id} assignee has no email; skipping first reminder.")
continue
try:
_send(task, FIRST_REMINDER_HOURS_BEFORE, "first")
task.reminder_sent_at = now
task.save(update_fields=["reminder_sent_at"])
first_count += 1
except Exception as e:
logger.warning(f"Failed to send first QI reminder for task {task.id}: {e}")
# Second reminders: due within 6h, first sent >=1h ago, not yet second-reminded
for task in QIProjectTask.objects.filter(
assigned_to__isnull=False,
status__in=["pending", "active"],
due_date__isnull=False,
second_reminder_sent_at__isnull=True,
reminder_sent_at__isnull=False,
reminder_sent_at__lt=now - timedelta(hours=1),
project__is_template=False,
).select_related("assigned_to__user", "project"):
deadline = _deadline(task)
if not (deadline - timedelta(hours=SECOND_REMINDER_HOURS_BEFORE) <= now < deadline):
continue
user = task.assigned_to.user
if not user or not getattr(user, "email", None):
logger.warning(f"QI task {task.id} assignee has no email; skipping second reminder.")
continue
try:
_send(task, SECOND_REMINDER_HOURS_BEFORE, "second")
task.second_reminder_sent_at = now
task.save(update_fields=["second_reminder_sent_at"])
second_count += 1
except Exception as e:
logger.warning(f"Failed to send second QI reminder for task {task.id}: {e}")
logger.info(f"QI task reminders: {first_count} first, {second_count} second")
return {"first_reminder_count": first_count, "second_reminder_count": second_count}

338
apps/projects/tests.py
View File

@ -1,16 +1,21 @@
"""
Tests for the QI Projects app.
Covers the multi-department + derived-team behaviour:
- Team membership is derived from each department's champion + manager (+ lead).
- Sync fires on M2M changes to `departments`.
Covers the explicit team-membership model:
- `team_members` is selected explicitly (managers/champions of linked
departments), NOT auto-derived from `departments` anymore.
- The lead must be a role-holder of a selected department or PX Management/Employee.
- ACL: only admins / project lead / team members can view & manage.
- Task `assigned_to` is limited to derived team members.
- Task `assigned_to` is limited to team members.
"""
from datetime import datetime, timedelta
from unittest.mock import patch
from django.contrib.auth import get_user_model
from django.test import TestCase
from django.urls import reverse
from django.utils import timezone
from apps.organizations.models import Department, Hospital, Staff
from apps.projects.models import QIProject, QIProjectTask
@ -36,8 +41,8 @@ def _make_staff(hospital, department=None, first="Staff", email=None):
)
class DerivedTeamTests(TestCase):
"""sync_team_members_from_departments + m2m_changed signal."""
class ExplicitTeamTests(TestCase):
"""Team membership is now explicit — `departments` changes do not rebuild it."""
def setUp(self):
self.hospital = Hospital.objects.create(name="H1", code="H1", status="active")
@ -58,48 +63,33 @@ class DerivedTeamTests(TestCase):
defaults.update(kw)
return QIProject.objects.create(**defaults)
def test_team_derived_from_department_champions(self):
def test_team_members_set_explicitly(self):
p = self._new_project()
p.departments.set([self.dept_a, self.dept_b])
# champ_a, champ_b (champions) + lead (project_lead) → 3 members
self.assertEqual(set(p.team_members.values_list("pk", flat=True)),
{self.champ_a.pk, self.champ_b.pk, self.lead.pk})
p.team_members.set([self.champ_a, self.champ_b, self.lead])
self.assertEqual(
set(p.team_members.values_list("pk", flat=True)),
{self.champ_a.pk, self.champ_b.pk, self.lead.pk},
)
def test_manager_without_staff_profile_is_skipped(self):
# Manager is a User with no staff_profile → excluded
mgr_user = User.objects.create_user(username="mgr", email="mgr@x", password="p")
self.dept_a.manager = mgr_user
self.dept_a.save()
p = self._new_project()
p.departments.set([self.dept_a])
# Only champ_a + lead; mgr_user has no staff_profile so not added
self.assertEqual(set(p.team_members.values_list("pk", flat=True)),
{self.champ_a.pk, self.lead.pk})
def test_manager_with_staff_profile_is_included(self):
mgr_staff = _make_staff(self.hospital, self.dept_a, "Mgr")
mgr_user = mgr_staff.user
self.dept_a.manager = mgr_user
self.dept_a.save()
p = self._new_project()
p.departments.set([self.dept_a])
self.assertIn(mgr_staff.pk, set(p.team_members.values_list("pk", flat=True)))
def test_removing_department_rebuilds_team(self):
def test_departments_change_does_not_rebuild_team(self):
"""The m2m_changed auto-derive signal has been removed."""
p = self._new_project()
p.team_members.set([self.champ_a])
# Linking a new department must NOT silently add its champion.
p.departments.set([self.dept_a, self.dept_b])
self.assertIn(self.champ_b.pk, set(p.team_members.values_list("pk", flat=True)))
self.assertEqual(set(p.team_members.values_list("pk", flat=True)), {self.champ_a.pk})
# And removing a department must not strip existing members.
p.departments.remove(self.dept_b)
# champ_b no longer in team; champ_a + lead remain
self.assertEqual(set(p.team_members.values_list("pk", flat=True)),
{self.champ_a.pk, self.lead.pk})
self.assertEqual(set(p.team_members.values_list("pk", flat=True)), {self.champ_a.pk})
def test_is_team_member_helper(self):
p = self._new_project()
p.departments.set([self.dept_a])
p.team_members.set([self.champ_a])
self.assertTrue(p.is_team_member(self.champ_a.user))
self.assertTrue(p.is_team_member(self.lead.user))
self.assertFalse(p.is_team_member(self.champ_b.user))
# The lead is always considered a team member (checked via project_lead_id)
self.assertTrue(p.is_team_member(self.lead.user))
class ACLTests(TestCase):
@ -117,7 +107,8 @@ class ACLTests(TestCase):
self.project = QIProject.objects.create(
name="P", description="d", hospital=self.hospital, status="pending", project_lead=self.lead
)
self.project.departments.set([self.dept]) # derives team = {champ, lead}
self.project.departments.set([self.dept])
self.project.team_members.set([self.champ, self.lead]) # explicit (views force-add the lead)
def test_team_member_can_view_detail(self):
# ACL helper level (view-level rendering is blocked by a pre-existing
@ -155,3 +146,274 @@ class ACLTests(TestCase):
# GET must be rejected (405) — CSRF-safe toggle
resp = self.client.get(url)
self.assertEqual(resp.status_code, 405)
def test_champion_of_linked_dept_can_view_even_if_not_team_member(self):
"""A champion of a linked department can view the project even when not in team_members."""
from apps.projects.ui_views import _check_project_permission
dept_b = Department.objects.create(hospital=self.hospital, name="D2", code="D2", status="active")
champ_b = _make_staff(self.hospital, dept_b, "ChampB")
dept_b.champion = champ_b
dept_b.save()
self.project.departments.add(dept_b)
# champ_b is NOT a team member
self.assertFalse(self.project.is_team_member(champ_b.user))
# ...but is champion of a linked department → may view
self.assertTrue(_check_project_permission(self.project, champ_b.user))
def test_project_modal_endpoint_allows_champion(self):
"""The department_record_project AJAX endpoint must not 403 a linked-dept champion."""
self.client.force_login(self.champ.user)
url = reverse("organizations:department_record_project", args=[self.project.pk])
resp = self.client.get(url)
self.assertEqual(resp.status_code, 200)
self.assertEqual(resp.json()["type"], "project")
class QITaskNotesAttachmentsTests(TestCase):
"""Notes (core.Note) + AJAX attachments on QI tasks."""
def setUp(self):
self.hospital = Hospital.objects.create(name="H1", code="H1", status="active")
self.dept = Department.objects.create(hospital=self.hospital, name="D", code="D", status="active")
self.champ = _make_staff(self.hospital, self.dept, "Champ")
self.lead = _make_staff(self.hospital, self.dept, "Lead")
self.project = QIProject.objects.create(
name="P", description="d", hospital=self.hospital, status="pending", project_lead=self.lead
)
self.project.departments.set([self.dept])
self.project.team_members.set([self.champ, self.lead])
self.task = QIProjectTask.objects.create(
project=self.project, title="T", assigned_to=self.champ, status="pending"
)
def _file(self, name="doc.pdf", content=b"%PDF-1.4"):
from django.core.files.uploadedfile import SimpleUploadedFile
return SimpleUploadedFile(name, content, content_type="application/pdf")
def test_note_appears_on_task(self):
from django.contrib.contenttypes.models import ContentType
from apps.core.models import Note
ct = ContentType.objects.get_for_model(QIProjectTask)
Note.objects.create(content_type=ct, object_id=self.task.id, note="hello", created_by=self.lead.user)
self.assertEqual(self.task.notes.count(), 1)
self.assertEqual(self.task.notes.first().note, "hello")
def test_contributor_can_upload_attachment(self):
self.client.force_login(self.lead.user)
url = reverse("projects:task_attachment_upload", args=[self.task.pk])
resp = self.client.post(url, {"file": self._file(), "description": "evidence"})
self.assertEqual(resp.status_code, 200)
self.assertTrue(resp.json()["success"])
self.assertEqual(self.task.attachments.count(), 1)
att = self.task.attachments.first()
self.assertEqual(att.uploaded_by, self.lead.user)
self.assertEqual(att.filename, "doc.pdf")
self.assertGreater(att.file_size, 0)
def test_non_contributor_cannot_upload(self):
# Champion-of-linked-dept who is NOT a team member → can view but not upload.
dept_b = Department.objects.create(hospital=self.hospital, name="D2", code="D2", status="active")
champ_b = _make_staff(self.hospital, dept_b, "ChampB")
dept_b.champion = champ_b
dept_b.save()
self.project.departments.add(dept_b)
self.project.team_members.remove(champ_b)
self.client.force_login(champ_b.user)
url = reverse("projects:task_attachment_upload", args=[self.task.pk])
resp = self.client.post(url, {"file": self._file()})
self.assertEqual(resp.status_code, 403)
self.assertEqual(self.task.attachments.count(), 0)
def test_oversized_file_rejected(self):
self.client.force_login(self.lead.user)
url = reverse("projects:task_attachment_upload", args=[self.task.pk])
big = self._file(content=b"x" * (10 * 1024 * 1024 + 1))
resp = self.client.post(url, {"file": big})
self.assertEqual(resp.status_code, 200)
self.assertFalse(resp.json()["success"])
self.assertEqual(self.task.attachments.count(), 0)
def test_contributor_can_delete_attachment(self):
from apps.projects.models import QIProjectTaskAttachment
att = QIProjectTaskAttachment.objects.create(task=self.task, file=self._file(), uploaded_by=self.lead.user)
self.client.force_login(self.champ.user) # champ is a team member → contributor
url = reverse("projects:task_attachment_delete", args=[self.task.pk, att.pk])
resp = self.client.post(url)
self.assertEqual(resp.status_code, 200)
self.assertTrue(resp.json()["success"])
self.assertEqual(self.task.attachments.count(), 0)
class QITaskNotificationTests(TestCase):
"""Assignment email + deadline reminders for QI tasks."""
def setUp(self):
self.hospital = Hospital.objects.create(name="H1", code="H1", status="active")
self.dept = Department.objects.create(hospital=self.hospital, name="D", code="D", status="active")
self.champ = _make_staff(self.hospital, self.dept, "Champ")
self.lead = _make_staff(self.hospital, self.dept, "Lead")
self.dept.champion = self.champ
self.dept.save()
self.project = QIProject.objects.create(
name="P", description="d", hospital=self.hospital, status="pending", project_lead=self.lead
)
self.project.departments.set([self.dept])
self.project.team_members.set([self.champ, self.lead])
def test_assignment_sends_email_to_assignee(self):
from apps.notifications.models import NotificationLog
task = QIProjectTask.objects.create(
project=self.project, title="My Task", assigned_to=self.champ, status="pending"
)
log = NotificationLog.objects.filter(
recipient=self.champ.user.email, subject__startswith="New QI Task"
).first()
self.assertIsNotNone(log, "Assignment should create an email notification log")
self.assertEqual(log.metadata.get("notification_type"), "qi_task_assigned")
def test_reassignment_does_not_notify(self):
other = _make_staff(self.hospital, self.dept, "Other")
self.project.team_members.add(other)
from apps.notifications.models import NotificationLog
task = QIProjectTask.objects.create(
project=self.project, title="T", assigned_to=self.champ, status="pending"
)
# Reassign (update, not create) — signal must stay silent
task.assigned_to = other
task.save(update_fields=["assigned_to"])
new_logs = NotificationLog.objects.filter(recipient=other.user.email, subject__startswith="New QI Task")
self.assertFalse(new_logs.exists(), "Reassignment must not trigger a new-assignment email")
def test_first_reminder_fires_and_dedups(self):
from apps.notifications.models import NotificationLog
from apps.projects.tasks import send_qi_task_reminders
frozen = timezone.make_aware(datetime(2026, 1, 15, 12, 0, 0), timezone.get_current_timezone())
task = QIProjectTask.objects.create(
project=self.project, title="Due Today", assigned_to=self.champ, status="pending",
due_date=datetime(2026, 1, 15).date(), # today → within 24h window
)
with patch("apps.projects.tasks.timezone.now", return_value=frozen):
result = send_qi_task_reminders.apply().get()
self.assertEqual(result["first_reminder_count"], 1)
task.refresh_from_db()
self.assertIsNotNone(task.reminder_sent_at)
self.assertTrue(
NotificationLog.objects.filter(
recipient=self.champ.user.email, subject__startswith="QI Task Reminder"
).exists()
)
# Second run must not re-send (deduped via reminder_sent_at)
with patch("apps.projects.tasks.timezone.now", return_value=frozen):
result2 = send_qi_task_reminders.apply().get()
self.assertEqual(result2["first_reminder_count"], 0)
def test_second_reminder_fires(self):
from apps.projects.tasks import send_qi_task_reminders
frozen = timezone.make_aware(datetime(2026, 1, 15, 18, 0, 0), timezone.get_current_timezone())
task = QIProjectTask.objects.create(
project=self.project, title="Due Today", assigned_to=self.champ, status="pending",
due_date=datetime(2026, 1, 15).date(),
reminder_sent_at=frozen - timedelta(hours=2), # first reminder already sent
)
with patch("apps.projects.tasks.timezone.now", return_value=frozen):
result = send_qi_task_reminders.apply().get()
self.assertEqual(result["second_reminder_count"], 1)
task.refresh_from_db()
self.assertIsNotNone(task.second_reminder_sent_at)
class ProjectCreationNotificationTests(TestCase):
"""Lead + team members are emailed when a project is created."""
def setUp(self):
self.hospital = Hospital.objects.create(name="H1", code="H1", status="active")
self.dept = Department.objects.create(hospital=self.hospital, name="D", code="D", status="active")
self.lead = _make_staff(self.hospital, self.dept, "Lead")
self.member = _make_staff(self.hospital, self.dept, "Member")
self.project = QIProject.objects.create(
name="P", description="d", hospital=self.hospital, status="pending", project_lead=self.lead
)
def test_lead_and_team_members_notified(self):
from apps.notifications.models import NotificationLog
from apps.projects.ui_views import _notify_project_team
self.project.team_members.set([self.lead, self.member])
_notify_project_team(self.project)
for staff in (self.lead, self.member):
exists = NotificationLog.objects.filter(
recipient=staff.user.email, subject__startswith="New QI Project"
).exists()
self.assertTrue(exists, f"Expected notification for {staff.user.email}")
def test_no_recipients_is_noop(self):
from apps.notifications.models import NotificationLog
from apps.projects.ui_views import _notify_project_team
bare = QIProject.objects.create(
name="Bare", description="d", hospital=self.hospital, status="pending"
) # no lead, no team
_notify_project_team(bare) # must not raise
self.assertEqual(
NotificationLog.objects.filter(subject__startswith="New QI Project").count(), 0
)
class ConvertActionTeamTests(TestCase):
"""Converting a PX Action to a project must NOT clobber the explicit team.
Under the explicit-team model, the converted project's team is just {lead}
(the form doesn't collect team_members). The old code called
sync_team_members_from_departments() which overwrote team_members with the
auto-derived set.
"""
def setUp(self):
from django.contrib.auth.models import Group
self.hospital = Hospital.objects.create(name="H1", code="H1", status="active")
self.dept = Department.objects.create(hospital=self.hospital, name="D", code="D", status="active")
# A department champion who would have been auto-pulled by the old sync
self.champ = _make_staff(self.hospital, self.dept, "Champ")
self.dept.champion = self.champ
self.dept.save()
self.lead = _make_staff(self.hospital, self.dept, "Lead")
# Hospital Admin user scoped to the hospital (avoids the px-admin tenant-hospital redirect)
self.admin = User.objects.create_user(
username="admin@x", email="admin@x", password="p"
)
self.admin.hospital = self.hospital
self.admin.save()
self.admin.groups.add(Group.objects.get_or_create(name="Hospital Admin")[0])
from apps.px_action_center.models import PXAction
self.action = PXAction.objects.create(
title="Action", description="d", hospital=self.hospital
)
def test_convert_sets_team_to_lead_only(self):
self.client.force_login(self.admin)
url = reverse("projects:convert_action", args=[self.action.pk])
resp = self.client.post(url, {
"project_name": "Converted Project",
"project_lead": str(self.lead.pk),
})
self.assertEqual(resp.status_code, 302)
project = QIProject.objects.get(name="Converted Project")
self.assertEqual(project.project_lead_id, self.lead.pk)
team_ids = set(project.team_members.values_list("id", flat=True))
self.assertEqual(team_ids, {self.lead.pk})
# The department champion must NOT have been auto-pulled in
self.assertNotIn(self.champ.pk, team_ids)

327
apps/projects/ui_views.py
View File

@ -5,12 +5,17 @@ Provides full CRUD functionality for Quality Improvement projects,
task management, and template handling.
"""
import json
import logging
from django.contrib import messages
from django.contrib.auth.decorators import login_required
from django.core.paginator import Paginator
from django.db.models import Q
from django.http import JsonResponse
from django.shortcuts import get_object_or_404, redirect, render
from django.urls import reverse
from django.utils import timezone
from django.utils.translation import gettext_lazy as _
from django.views.decorators.http import require_POST
@ -20,7 +25,71 @@ from apps.organizations.models import Hospital
from apps.px_action_center.models import PXAction
from .forms import ConvertToProjectForm, QIProjectForm, QIProjectTaskForm, QIProjectTemplateForm, TaskTemplateFormSet
from .models import QIProject, QIProjectTask, PDCAPhase, PDCAPhaseChoices, FOCUSPhase, FOCUSPhaseChoices
from .models import QIProject, QIProjectTask, QIProjectTaskAttachment, PDCAPhase, PDCAPhaseChoices, FOCUSPhase, FOCUSPhaseChoices
logger = logging.getLogger(__name__)
def _notify_project_team(project):
"""Email the project lead + team members that a new project was created.
Called from the create paths after `team_members` has been populated.
`NotificationService.send_email` also creates the matching in-app notification
for each recipient.
"""
from django.conf import settings
from apps.notifications.services import NotificationService
from apps.organizations.models import Staff
site_url = getattr(settings, "SITE_URL", "http://localhost:8000").rstrip("/")
project_url = f"{site_url}/projects/{project.id}/"
# Recipients: project lead + team members (deduped)
recipient_ids = set()
if project.project_lead_id:
recipient_ids.add(project.project_lead_id)
recipient_ids.update(project.team_members.values_list("id", flat=True))
if not recipient_ids:
return
recipients = Staff.objects.filter(id__in=recipient_ids, user__isnull=False).select_related("user")
subject = f"New QI Project: {project.name}"
plain = (
f"You have been added to the QI project '{project.name}'.\n"
f"Open: {project_url}"
)
html_message = f"""
<div style="font-family: 'Segoe UI', Tahoma, sans-serif; max-width: 600px; margin: 0 auto; border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
<div style="padding: 20px;">
<h2 style="color: #005696; font-size: 18px; margin: 0 0 12px 0;">New QI Project</h2>
<p style="margin: 0 0 12px 0;">You have been added to the project team for <strong>{project.name}</strong>.</p>
<div style="text-align: center; margin: 20px 0;">
<a href="{project_url}" style="background: #005696; color: white; padding: 10px 24px; border-radius: 8px; text-decoration: none; font-weight: 600;">Open Project</a>
</div>
</div>
</div>
"""
for sp in recipients:
email = getattr(sp.user, "email", None)
if not email:
continue
try:
NotificationService.send_email(
email=email,
subject=subject,
message=plain,
html_message=html_message,
related_object=project,
metadata={
"notification_type": "qi_project_created",
"project_id": str(project.id),
},
notification_type="qi_project_created",
user=sp.user,
)
except Exception as e:
logger.warning(f"Failed to notify {email} for project {project.id}: {e}")
@block_source_user
@ -481,6 +550,12 @@ def project_create(request, template_pk=None):
except Exception:
pass
# Allow explicit prefill override (e.g. improvement-project note)
if request.GET.get("description"):
initial_data["description"] = request.GET.get("description")
if request.GET.get("name"):
initial_data["name"] = request.GET.get("name")
if request.method == "POST":
form = QIProjectForm(request.POST, request=request)
@ -498,6 +573,13 @@ def project_create(request, template_pk=None):
project.save()
form.save_m2m() # Save many-to-many relationships
# Ensure the project lead is always part of the team (idempotent)
if project.project_lead_id:
project.team_members.add(project.project_lead)
# Notify the lead + team members that the project was created
_notify_project_team(project)
# If created from template, copy tasks
task_count = 0
if template:
@ -545,6 +627,7 @@ def project_create(request, template_pk=None):
"template": template,
"related_model": related_model,
"related_id": related_id,
"team_member_ids_json": "[]",
}
return render(request, "projects/project_form.html", context)
@ -571,6 +654,9 @@ def project_edit(request, pk):
form = QIProjectForm(request.POST, instance=project, request=request)
if form.is_valid():
form.save()
# Ensure the project lead is always part of the team (idempotent)
if project.project_lead_id:
project.team_members.add(project.project_lead)
messages.success(request, _("QI Project updated successfully."))
return redirect("projects:project_detail", pk=project.pk)
else:
@ -580,11 +666,101 @@ def project_edit(request, pk):
"form": form,
"project": project,
"is_create": False,
"team_member_ids_json": json.dumps(
[str(pk) for pk in project.team_members.values_list("id", flat=True)]
),
}
return render(request, "projects/project_form.html", context)
@block_source_user
@login_required
def department_team_options(request):
"""AJAX endpoint returning per-department manager/champion + lead candidates.
Powers the dynamic team-member panel and the project-lead dropdown on the
QI project create/edit form. Scoped to the user's hospital (PX admins use
their tenant_hospital).
"""
from apps.accounts.models import User
from apps.organizations.models import Department, Staff
user = request.user
if user.is_px_admin():
hospital_id = getattr(getattr(request, "tenant_hospital", None), "id", None)
else:
hospital_id = user.hospital_id
dept_ids = request.GET.get("dept_ids", "")
dept_id_list = [d for d in dept_ids.split(",") if d]
if not dept_id_list:
return JsonResponse({"departments": [], "leads": []})
depts = Department.objects.filter(pk__in=dept_id_list, status="active")
if hospital_id:
depts = depts.filter(hospital_id=hospital_id)
depts = depts.select_related("champion", "manager", "manager__staff_profile")
dept_data = []
leads = []
seen_lead_ids = set()
for dept in depts:
manager_obj = None
champion_obj = None
if dept.champion_id:
champion_obj = {
"id": str(dept.champion_id),
"name": dept.champion.get_full_name(),
}
if dept.champion_id not in seen_lead_ids:
seen_lead_ids.add(dept.champion_id)
leads.append(
{
"id": str(dept.champion_id),
"label": f"{dept.champion.get_full_name()} — Champion, {dept.get_localized_name()}",
}
)
if dept.manager_id and dept.manager is not None:
sp = getattr(dept.manager, "staff_profile", None)
if sp and sp.pk:
manager_obj = {"id": str(sp.pk), "name": sp.get_full_name()}
if sp.pk not in seen_lead_ids:
seen_lead_ids.add(sp.pk)
leads.append(
{
"id": str(sp.pk),
"label": f"{sp.get_full_name()} — Manager, {dept.get_localized_name()}",
}
)
dept_data.append(
{
"id": str(dept.id),
"name": dept.get_localized_name(),
"manager": manager_obj,
"champion": champion_obj,
}
)
# PX Management / PX Employee may also lead (PX-led initiatives)
if hospital_id:
px_user_ids = User.objects.filter(groups__name__in=["PX Management", "PX Employee"]).values_list(
"id", flat=True
)
px_staff = Staff.objects.filter(user_id__in=list(px_user_ids), hospital_id=hospital_id)
for sp in px_staff:
if sp.pk in seen_lead_ids:
continue
seen_lead_ids.add(sp.pk)
role = "PX Management" if sp.user and sp.user.is_px_management() else "PX Employee"
leads.append({"id": str(sp.pk), "label": f"{sp.get_full_name()} ({role})"})
return JsonResponse({"departments": dept_data, "leads": leads})
@block_source_user
@login_required
def project_delete(request, pk):
@ -840,6 +1016,136 @@ def task_toggle_status(request, project_pk, task_pk, phase=None):
return _task_redirect(project, task)
# =============================================================================
# Task Notes & Attachments
# =============================================================================
def _can_contribute(project, user):
"""True if the user may add content (notes/attachments) to a project's tasks.
Granted to admins of the same hospital, the project lead, and any team member.
(Viewers who are only champions-of-a-linked-department can see but not contribute.)
"""
if _get_can_edit(user, project):
return True
staff_profile = getattr(user, "staff_profile", None)
return bool(staff_profile and project.team_members.filter(id=staff_profile.id).exists())
@block_source_user
@login_required
def task_detail(request, task_pk):
"""Task detail page: shows the task, its notes, and its attachments."""
from django.contrib.contenttypes.models import ContentType
task = get_object_or_404(
QIProjectTask.objects.select_related("project", "assigned_to", "pdca_phase", "focus_phase"),
pk=task_pk,
project__is_template=False,
)
project = task.project
user = request.user
if not _check_project_permission(project, user):
messages.error(request, _("You don't have permission to view this task."))
return redirect("projects:project_detail", pk=project.pk)
ct = ContentType.objects.get_for_model(QIProjectTask)
context = {
"task": task,
"project": project,
"now": timezone.now(),
"notes": task.notes.select_related("created_by").all(),
"content_type_id": ct.id,
"object_id": task.id,
"attachments": task.attachments.select_related("uploaded_by").all(),
"can_contribute": _can_contribute(project, user),
"can_edit": _get_can_edit(user, project),
}
return render(request, "projects/task_detail.html", context)
@block_source_user
@login_required
@require_POST
def task_attachment_upload_ajax(request, task_pk):
"""Upload an attachment to a QI task via AJAX. Contributors only."""
task = get_object_or_404(QIProjectTask, pk=task_pk, project__is_template=False)
project = task.project
user = request.user
if not _check_project_permission(project, user) or not _can_contribute(project, user):
return JsonResponse({"success": False, "error": "Access denied"}, status=403)
if "file" not in request.FILES:
return JsonResponse({"success": False, "error": "No file provided"})
uploaded_file = request.FILES["file"]
# 10 MB cap
if uploaded_file.size > 10 * 1024 * 1024:
return JsonResponse({"success": False, "error": "File size must be less than 10MB"})
allowed_extensions = [".pdf", ".doc", ".docx", ".xls", ".xlsx", ".jpg", ".jpeg", ".png", ".zip"]
file_ext = "." + uploaded_file.name.split(".")[-1].lower() if "." in uploaded_file.name else ""
if file_ext not in allowed_extensions:
return JsonResponse(
{"success": False, "error": f"Invalid file type. Allowed: {', '.join(allowed_extensions)}"}
)
description = request.POST.get("description", "").strip()
try:
attachment = QIProjectTaskAttachment.objects.create(
task=task,
file=uploaded_file,
description=description,
uploaded_by=user,
)
return JsonResponse(
{
"success": True,
"attachment": {
"id": str(attachment.id),
"filename": attachment.filename,
"file_url": attachment.file.url,
"file_size": attachment.file_size,
"description": attachment.description or "",
"uploaded_by": user.get_full_name() if user else "Unknown",
"uploaded_at": attachment.created_at.strftime("%Y-%m-%d %H:%M"),
},
"attachment_count": task.attachments.count(),
}
)
except Exception as e:
logger.warning(f"Failed to upload QI task attachment for task {task.pk}: {e}")
return JsonResponse({"success": False, "error": str(e)})
@block_source_user
@login_required
@require_POST
def task_attachment_delete_ajax(request, task_pk, attachment_pk):
"""Delete a QI task attachment via AJAX. Uploader or contributors."""
task = get_object_or_404(QIProjectTask, pk=task_pk, project__is_template=False)
project = task.project
user = request.user
attachment = get_object_or_404(QIProjectTaskAttachment, pk=attachment_pk, task=task)
is_uploader = attachment.uploaded_by_id == user.id
if not (is_uploader or _can_contribute(project, user)):
return JsonResponse({"success": False, "error": "Access denied"}, status=403)
try:
attachment.file.delete(save=False)
attachment.delete()
return JsonResponse({"success": True, "attachment_count": task.attachments.count()})
except Exception as e:
logger.warning(f"Failed to delete QI task attachment {attachment_pk}: {e}")
return JsonResponse({"success": False, "error": str(e)})
# =============================================================================
# Template Management Views
# =============================================================================
@ -1061,7 +1367,6 @@ def convert_action_to_project(request, action_pk):
)
# Copy linked departments + tasks from template
project.departments.set(template.departments.all())
project.sync_team_members_from_departments()
for template_task in template.tasks.all():
QIProjectTask.objects.create(
project=project,
@ -1081,12 +1386,17 @@ def convert_action_to_project(request, action_pk):
status="pending",
created_by=user,
)
# Sync team from project lead (no departments in blank conversion)
project.sync_team_members_from_departments()
# Explicit-team model: ensure the lead is on the team (no auto-derivation)
if project.project_lead_id:
project.team_members.add(project.project_lead)
# Link to the action
project.related_actions.add(action)
# Notify the lead + team members that the project was created
_notify_project_team(project)
messages.success(request, _("PX Action converted to QI Project successfully."))
return redirect("projects:project_detail", pk=project.pk)
else:
@ -1353,7 +1663,7 @@ def _check_project_permission(project, user):
"""Check if user can access (view) a project.
Granted to: PX admins, hospital admins (same hospital), the project lead,
or any derived team member (champion/manager of a linked department).
explicit team members, or the champion/manager of any linked department.
"""
if user.is_px_admin():
return True
@ -1363,6 +1673,13 @@ def _check_project_permission(project, user):
# Cross-hospital access is always denied for regular users
if user.hospital and project.hospital and user.hospital != project.hospital:
return False
# Champions/managers of any linked department may view the project
staff_profile = getattr(user, "staff_profile", None)
dept_q = Q(manager_id=user.id)
if staff_profile:
dept_q = dept_q | Q(champion_id=staff_profile.id)
if project.departments.filter(dept_q).exists():
return True
return project.is_team_member(user)

5
apps/projects/urls.py
View File

@ -10,6 +10,7 @@ urlpatterns = [
path("my-tasks/", ui_views.my_tasks, name="my_tasks"),
path("create/", ui_views.project_create, name="project_create"),
path("create/from-template/<uuid:template_pk>/", ui_views.project_create, name="project_create_from_template"),
path("api/department-team-options/", ui_views.department_team_options, name="department_team_options"),
path("<uuid:pk>/", ui_views.project_detail, name="project_detail"),
path("<uuid:pk>/edit/", ui_views.project_edit, name="project_edit"),
path("<uuid:pk>/delete/", ui_views.project_delete, name="project_delete"),
@ -18,6 +19,10 @@ urlpatterns = [
path("<uuid:project_pk>/tasks/<uuid:task_pk>/edit/", ui_views.task_edit, name="task_edit"),
path("<uuid:project_pk>/tasks/<uuid:task_pk>/delete/", ui_views.task_delete, name="task_delete"),
path("<uuid:project_pk>/tasks/<uuid:task_pk>/toggle/", ui_views.task_toggle_status, name="task_toggle_status"),
# Task notes & attachments
path("tasks/<uuid:task_pk>/", ui_views.task_detail, name="task_detail"),
path("tasks/<uuid:task_pk>/attachments/upload/", ui_views.task_attachment_upload_ajax, name="task_attachment_upload"),
path("tasks/<uuid:task_pk>/attachments/<uuid:attachment_pk>/delete/", ui_views.task_attachment_delete_ajax, name="task_attachment_delete"),
# PDCA Phase Management
path("<uuid:pk>/pdca/<str:phase>/", ui_views.pdca_phase_detail, name="pdca_phase_detail"),
path("<uuid:pk>/pdca/<str:phase>/edit/", ui_views.pdca_phase_edit, name="pdca_phase_edit"),

11
apps/px_action_center/tasks.py
View File

@ -22,7 +22,7 @@ def check_overdue_actions():
Periodic task to check for overdue actions.
Runs every 15 minutes (configured in config/celery.py).
Updates is_overdue flag and triggers escalation if configured.
Updates is_overdue flag for actions past their SLA deadline.
"""
from apps.px_action_center.models import ActionStatus, PXAction
@ -32,7 +32,6 @@ def check_overdue_actions():
).select_related('hospital', 'assigned_to')
overdue_count = 0
escalated_count = 0
for action in active_actions:
if action.check_overdue():
@ -42,14 +41,10 @@ def check_overdue_actions():
f"(due: {action.due_at})"
)
# Trigger escalation
escalate_action.delay(str(action.id))
escalated_count += 1
if overdue_count > 0:
logger.info(f"Found {overdue_count} overdue actions, escalated {escalated_count}")
logger.info(f"Found {overdue_count} overdue actions")
return {'overdue_count': overdue_count, 'escalated_count': escalated_count}
return {'overdue_count': overdue_count}
@shared_task

6
apps/px_action_center/ui_views.py
View File

@ -207,8 +207,9 @@ def action_detail(request, pk):
messages.error(request, "You don't have permission to view this action.")
return redirect("actions:action_list")
# Get logs (timeline)
logs = action.logs.all().order_by("-created_at")
# Get logs (timeline). Notes are split into their own tab.
logs = action.logs.exclude(log_type="note").order_by("-created_at")
notes = action.logs.filter(log_type="note").order_by("-created_at")
# Get attachments
attachments = action.attachments.all().order_by("-created_at")
@ -232,6 +233,7 @@ def action_detail(request, pk):
context = {
"action": action,
"logs": logs,
"notes": notes,
"attachments": attachments,
"evidence_attachments": evidence_attachments,
"assignable_users": assignable_users,

5
apps/simulator/views.py
View File

@ -32,6 +32,7 @@ from apps.journeys.models import (
)
from apps.organizations.models import Hospital, Department, Patient
from apps.surveys.models import SurveyTemplate, SurveyInstance
from apps.surveys.services import SurveyDeliveryService
from apps.notifications.services import NotificationService
import time
@ -919,7 +920,7 @@ def send_post_discharge_survey(journey_instance, patient):
try:
sms_log = NotificationService.send_sms(
phone=patient.phone,
message=f"Your experience survey is ready: {survey_instance.get_survey_url()}",
message=f"Your experience survey is ready: {SurveyDeliveryService.generate_survey_url(survey_instance)}",
related_object=survey_instance,
metadata={"survey_id": str(survey_instance.id)},
)
@ -931,7 +932,7 @@ def send_post_discharge_survey(journey_instance, patient):
return {
"survey_sent": True,
"survey_id": str(survey_instance.id),
"survey_url": survey_instance.get_survey_url(),
"survey_url": SurveyDeliveryService.generate_survey_url(survey_instance),
"delivery_channel": "email_and_sms",
}

9
apps/standards/models.py
View File

@ -4,6 +4,7 @@ Standards Section Models - Track compliance standards (CBAHI, MOH, CHI, etc.)
from django.db import models
from django.core.validators import FileExtensionValidator
from django.utils.translation import gettext_lazy as _
from apps.core.models import TimeStampedModel, UUIDModel, StatusChoices
@ -12,7 +13,7 @@ class StandardSource(UUIDModel, TimeStampedModel):
"""Standard sources like CBAHI, MOH, CHI, JCI, etc."""
name = models.CharField(max_length=100)
name_ar = models.CharField(max_length=100, blank=True, verbose_name="Name (Arabic)")
name_ar = models.CharField(max_length=100, blank=True, verbose_name=_("Name (Arabic)"))
code = models.CharField(max_length=50, unique=True)
description = models.TextField(blank=True)
website = models.URLField(blank=True)
@ -31,7 +32,7 @@ class StandardCategory(UUIDModel, TimeStampedModel):
"""Group standards by category (Patient Safety, Quality Management, etc.)"""
name = models.CharField(max_length=100)
name_ar = models.CharField(max_length=100, blank=True, verbose_name="Name (Arabic)")
name_ar = models.CharField(max_length=100, blank=True, verbose_name=_("Name (Arabic)"))
description = models.TextField(blank=True)
order = models.PositiveIntegerField(default=0, help_text="Display order")
is_active = models.BooleanField(default=True, db_index=True)
@ -60,7 +61,7 @@ class ActivityType(UUIDModel, TimeStampedModel):
"""Activity types for standards (Clinical, Administrative, Support, etc.)"""
name = models.CharField(max_length=200)
name_ar = models.CharField(max_length=200, blank=True, verbose_name="Name (Arabic)")
name_ar = models.CharField(max_length=200, blank=True, verbose_name=_("Name (Arabic)"))
description = models.TextField(blank=True)
is_active = models.BooleanField(default=True, db_index=True)
@ -93,7 +94,7 @@ class Standard(UUIDModel, TimeStampedModel):
code = models.CharField(max_length=50, db_index=True, help_text="e.g., CBAHI-PS-01, 22.1, 1.1")
title = models.CharField(max_length=500)
title_ar = models.CharField(max_length=500, blank=True, verbose_name="Title (Arabic)")
title_ar = models.CharField(max_length=500, blank=True, verbose_name=_("Title (Arabic)"))
description = models.TextField(blank=True, help_text="Full description of the standard")
source = models.ForeignKey(StandardSource, on_delete=models.PROTECT, related_name="standards")

29
config/celery.py
View File

@ -57,60 +57,65 @@ app.conf.beat_schedule = {
"task": "apps.px_action_center.tasks.check_overdue_actions",
"schedule": crontab(minute="*/15"),
},
# Send SLA reminders every hour
# Send SLA reminders every 15 minutes
"send-sla-reminders": {
"task": "apps.complaints.tasks.send_sla_reminders",
"schedule": crontab(minute=0), # Every hour at minute 0
"schedule": crontab(minute="*/15"), # Every 15 minutes
},
# Check for overdue explanation requests every 15 minutes
"check-overdue-explanation-requests": {
"task": "apps.complaints.tasks.check_overdue_explanation_requests",
"schedule": crontab(minute="*/15"),
},
# Send explanation reminders every hour
# Send explanation reminders every 15 minutes
"send-explanation-reminders": {
"task": "apps.complaints.tasks.send_explanation_reminders",
"schedule": crontab(minute=0), # Every hour at minute 0
"schedule": crontab(minute="*/15"), # Every 15 minutes
},
# Check for overdue inquiries every 15 minutes
"check-overdue-inquiries": {
"task": "apps.complaints.tasks.check_overdue_inquiries",
"schedule": crontab(minute="*/15"),
},
# Send inquiry SLA reminders every hour
# Send inquiry SLA reminders every 15 minutes
"send-inquiry-sla-reminders": {
"task": "apps.complaints.tasks.send_inquiry_sla_reminders",
"schedule": crontab(minute=0), # Every hour at minute 0
"schedule": crontab(minute="*/15"), # Every 15 minutes
},
# Check for overdue observations every 15 minutes
"check-overdue-observations": {
"task": "apps.observations.tasks.check_overdue_observations",
"schedule": crontab(minute="*/15"),
},
# Send observation SLA reminders every hour
# Send observation SLA reminders every 15 minutes
"send-observation-sla-reminders": {
"task": "apps.observations.tasks.send_observation_sla_reminders",
"schedule": crontab(minute=0), # Every hour at minute 0
"schedule": crontab(minute="*/15"), # Every 15 minutes
},
# Check overdue inquiry dept responses every 15 minutes
"check-overdue-inquiry-dept-responses": {
"task": "apps.complaints.tasks.check_overdue_inquiry_dept_responses",
"schedule": crontab(minute="*/15"),
},
# Send inquiry dept response reminders every hour
# Send inquiry dept response reminders every 15 minutes
"send-inquiry-dept-response-reminders": {
"task": "apps.complaints.tasks.send_inquiry_dept_response_reminders",
"schedule": crontab(minute=0),
"schedule": crontab(minute="*/15"), # Every 15 minutes
},
# Check overdue observation dept responses every 15 minutes
"check-overdue-observation-dept-responses": {
"task": "apps.observations.tasks.check_overdue_observation_dept_responses",
"schedule": crontab(minute="*/15"),
},
# Send observation dept response reminders every hour
# Send observation dept response reminders every 15 minutes
"send-observation-dept-response-reminders": {
"task": "apps.observations.tasks.send_observation_dept_response_reminders",
"schedule": crontab(minute=0),
"schedule": crontab(minute="*/15"), # Every 15 minutes
},
# Send QI project task reminders every 15 minutes (24h + 6h before due date)
"send-qi-task-reminders": {
"task": "apps.projects.tasks.send_qi_task_reminders",
"schedule": crontab(minute="*/15"), # Every 15 minutes
},
# Send onboarding reminders every hour
"send-onboarding-reminders": {

2
config/settings/base.py
View File

@ -439,6 +439,8 @@ EMAIL_HOST_PASSWORD = env("EMAIL_HOST_PASSWORD", default="")
DEFAULT_FROM_EMAIL = env("DEFAULT_FROM_EMAIL", default="noreply@px360.sa")
SITE_URL = env("SITE_URL", default="http://localhost:8000")
BASE_URL = SITE_URL
SURVEY_BASE_URL = SITE_URL
EMAIL_LOGO_URL = env("EMAIL_LOGO_URL", default=f"{SITE_URL}{STATIC_URL}img/HH_P_H_Logo.png")
# HIS Integration Settings

12
deploy/compose.dev.yml
View File

@ -39,12 +39,12 @@ services:
env_file:
- .env
# celery-beat:
# image: {{ .ImageTag }}
# restart: unless-stopped
# command: celery -A config beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler
# env_file:
# - .env
celery-beat:
image: {{ .ImageTag }}
restart: unless-stopped
command: celery -A config beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler
env_file:
- .env
db:
image: postgres:15-alpine

1
deploy/env.dev.example
View File

@ -14,6 +14,7 @@ DEBUG=True
ALLOWED_HOSTS=django.ismailmosaibrahim.com,.ismailmosaibrahim.com
CSRF_TRUSTED_ORIGINS=https://django.ismailmosaibrahim.com,
ADMIN_URL=admin/
SITE_URL=https://django.ismailmosaibrahim.com
SECRET_KEY=CHANGE-ME-run: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
# --- Database (dev: bundled postgres in compose.dev.yml) ---

1
deploy/env.prod.example
View File

@ -14,6 +14,7 @@ DEBUG=False
ALLOWED_HOSTS=your-production-domain.com
CSRF_TRUSTED_ORIGINS=https://your-production-domain.com
ADMIN_URL=CHANGE-ME/
SITE_URL=https://your-production-domain.com
SECURE_SSL_REDIRECT=True
SECRET_KEY=CHANGE-ME-run: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

6
deploy/target.dev.yaml
View File

@ -2,12 +2,12 @@
# Usage: `make deploy-dev` (runs: target deploy --config deploy/target.dev.yaml)
app:
name: "hh-dev" # isolated project dir: ~/.target/hh-dev/
domain: "test.ismailmosaibrahim.com" # shared Caddy routes this domain → web_app
domain: "px360.ismailmosaibrahim.com" # shared Caddy routes this domain → web_app
port: 8888
server:
ip: "10.132.16.5"
user: "ahh-ops"
ip: "192.168.8.73"
user: "ismail"
ssh_key: "~/.ssh/id_rsa"
build:

598
docs/complaint_workflow.html Normal file
View File

@ -0,0 +1,598 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Complaint Workflow — PX360</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet">
<style>
:root {
--navy: #0a1e3f;
--blue: #007bbd;
--light: #e8f1f8;
--slate: #64748b;
--green: #16a34a;
--red: #dc2626;
--amber: #d97706;
--purple: #7c3aed;
--teal: #0d9488;
}
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: 'Inter', sans-serif;
background: linear-gradient(135deg, #f1f5f9 0%, #e2e8f0 100%);
color: #1e293b;
line-height: 1.6;
min-height: 100vh;
}
.header {
background: linear-gradient(135deg, var(--navy), var(--blue));
color: white;
padding: 3rem 2rem;
text-align: center;
}
.header h1 { font-size: 2rem; font-weight: 800; margin-bottom: 0.5rem; }
.header p { opacity: 0.85; font-size: 0.95rem; }
.container { max-width: 1100px; margin: 0 auto; padding: 2rem 1.5rem 4rem; }
.section-card {
background: white;
border-radius: 1rem;
padding: 2rem;
margin-bottom: 2rem;
box-shadow: 0 1px 3px rgba(0,0,0,0.08), 0 1px 2px rgba(0,0,0,0.04);
}
.section-card h2 {
font-size: 1.35rem;
font-weight: 700;
color: var(--navy);
margin-bottom: 0.25rem;
display: flex;
align-items: center;
gap: 0.5rem;
}
.section-card .subtitle {
color: var(--slate);
font-size: 0.875rem;
margin-bottom: 1.5rem;
}
.section-card h3 {
font-size: 1rem;
font-weight: 600;
color: var(--blue);
margin: 1.5rem 0 0.75rem;
}
.mermaid {
display: flex;
justify-content: center;
padding: 1rem 0;
}
.mermaid-wrapper {
background: #fafbfc;
border: 1px solid #e2e8f0;
border-radius: 0.75rem;
padding: 1.5rem;
overflow-x: auto;
}
table {
width: 100%;
border-collapse: collapse;
font-size: 0.875rem;
}
th {
text-align: left;
padding: 0.6rem 0.75rem;
background: var(--light);
color: var(--navy);
font-weight: 600;
border-bottom: 2px solid var(--blue);
}
td {
padding: 0.6rem 0.75rem;
border-bottom: 1px solid #e2e8f0;
vertical-align: top;
}
tr:hover td { background: #f8fafc; }
code {
background: #f1f5f9;
padding: 0.125rem 0.375rem;
border-radius: 0.25rem;
font-size: 0.8125rem;
color: var(--blue);
}
.badge {
display: inline-block;
padding: 0.125rem 0.5rem;
border-radius: 9999px;
font-size: 0.75rem;
font-weight: 600;
}
.badge-green { background: #dcfce7; color: #15803d; }
.badge-red { background: #fee2e2; color: #b91c1c; }
.badge-amber { background: #fef3c7; color: #b45309; }
.badge-blue { background: #dbeafe; color: #1e40af; }
.stepper {
display: flex;
align-items: flex-start;
justify-content: space-between;
gap: 0;
margin: 1.5rem 0;
position: relative;
}
.stepper::before {
content: '';
position: absolute;
top: 22px;
left: 5%;
right: 5%;
height: 3px;
background: #e2e8f0;
z-index: 0;
}
.step {
flex: 1;
text-align: center;
position: relative;
z-index: 1;
}
.step-circle {
width: 44px;
height: 44px;
border-radius: 50%;
background: white;
border: 3px solid var(--blue);
color: var(--blue);
display: flex;
align-items: center;
justify-content: center;
margin: 0 auto 0.5rem;
font-weight: 700;
font-size: 1rem;
}
.step-label { font-size: 0.8125rem; font-weight: 600; color: var(--navy); }
.step-flag { font-size: 0.6875rem; color: var(--slate); margin-top: 0.125rem; }
.callout {
border-left: 4px solid;
border-radius: 0.5rem;
padding: 0.75rem 1rem;
margin: 1rem 0;
font-size: 0.875rem;
}
.callout-warn { border-color: var(--amber); background: #fffbeb; color: #92400e; }
.callout-info { border-color: var(--blue); background: #eff6ff; color: #1e40af; }
.sub-workflow-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 1rem;
margin-top: 1rem;
}
.sw-card {
border: 1px solid #e2e8f0;
border-radius: 0.75rem;
padding: 1.25rem;
background: #fafbfc;
}
.sw-card h4 {
font-size: 0.9375rem;
font-weight: 700;
color: var(--navy);
margin-bottom: 0.25rem;
}
.sw-card .field { font-size: 0.75rem; color: var(--slate); margin-bottom: 0.5rem; }
.sw-states {
display: flex;
flex-wrap: wrap;
gap: 0.25rem;
}
.sw-state {
background: white;
border: 1px solid #e2e8f0;
padding: 0.1875rem 0.5rem;
border-radius: 0.375rem;
font-size: 0.6875rem;
color: #475569;
}
.sw-arrow { color: var(--slate); font-size: 0.6875rem; }
.legend {
display: flex;
gap: 1rem;
flex-wrap: wrap;
margin-top: 1rem;
font-size: 0.8125rem;
}
.legend-item { display: flex; align-items: center; gap: 0.375rem; }
.legend-dot { width: 12px; height: 12px; border-radius: 50%; }
.tab-bar {
display: flex;
gap: 0.5rem;
margin-bottom: 1.5rem;
border-bottom: 2px solid #e2e8f0;
overflow-x: auto;
}
.tab-btn {
padding: 0.75rem 1rem;
border: none;
background: none;
cursor: pointer;
font-size: 0.875rem;
font-weight: 600;
color: var(--slate);
border-bottom: 2px solid transparent;
margin-bottom: -2px;
white-space: nowrap;
transition: all 0.2s;
}
.tab-btn.active { color: var(--blue); border-bottom-color: var(--blue); }
.tab-btn:hover { color: var(--navy); }
.tab-panel { display: none; }
.tab-panel.active { display: block; }
.footer {
text-align: center;
padding: 2rem;
color: var(--slate);
font-size: 0.8125rem;
}
</style>
</head>
<body>
<div class="header">
<h1>Complaint Workflow Map</h1>
<p>Status state machine, stepper, entry points &amp; sub-workflows — auto-extracted from source</p>
</div>
<div class="container">
<div class="tab-bar">
<button class="tab-btn active" onclick="switchTab(event, 'overview')">Overview</button>
<button class="tab-btn" onclick="switchTab(event, 'stepper')">Stepper</button>
<button class="tab-btn" onclick="switchTab(event, 'entrypoints')">Entry Points</button>
<button class="tab-btn" onclick="switchTab(event, 'subworkflows')">Sub-Workflows</button>
</div>
<!-- TAB 1: OVERVIEW -->
<div id="overview" class="tab-panel active">
<div class="section-card">
<h2>1. Status State Machine</h2>
<p class="subtitle">8 statuses defined in <code>ComplaintStatus</code> (<code>models.py:25</code>). Transition map enforced at <code>complaint_service.py:284</code> — only via <code>ComplaintService.change_status</code>. PX Admins bypass.</p>
<div class="mermaid-wrapper">
<pre class="mermaid">
stateDiagram-v2
[*] --> open
open --> in_progress : activate
open --> cancelled
in_progress --> partially_resolved
in_progress --> resolved
in_progress --> cancelled
in_progress --> pending_external
in_progress --> ovr_pending : escalate
partially_resolved --> resolved
partially_resolved --> in_progress
partially_resolved --> cancelled
partially_resolved --> pending_external
resolved --> closed
resolved --> in_progress : reopen
closed --> in_progress : reopen
cancelled --> open
cancelled --> in_progress
pending_external --> resolved
pending_external --> in_progress
pending_external --> cancelled
pending_external --> closed
ovr_pending --> in_progress : approve / reject
ovr_pending --> resolved
ovr_pending --> cancelled
closed --> [*]
</pre>
</div>
<h3>Transition Table</h3>
<table>
<thead>
<tr><th>From</th><th>Allowed Next Statuses</th></tr>
</thead>
<tbody>
<tr><td><code>open</code></td><td>in_progress, cancelled</td></tr>
<tr><td><code>in_progress</code></td><td>partially_resolved, resolved, cancelled, pending_external, ovr_pending</td></tr>
<tr><td><code>partially_resolved</code></td><td>resolved, in_progress, cancelled, pending_external</td></tr>
<tr><td><code>resolved</code></td><td>closed, in_progress</td></tr>
<tr><td><code>closed</code></td><td>in_progress</td></tr>
<tr><td><code>cancelled</code></td><td>open, in_progress</td></tr>
<tr><td><code>pending_external</code></td><td>resolved, in_progress, cancelled, closed</td></tr>
<tr><td><code>ovr_pending</code></td><td>in_progress, resolved, cancelled</td></tr>
</tbody>
</table>
<h3>Active vs Inactive (<code>is_active_status</code>)</h3>
<table>
<thead>
<tr><th>Active</th><th>Inactive</th></tr>
</thead>
<tbody>
<tr>
<td>
<span class="badge badge-green">open</span>
<span class="badge badge-green">in_progress</span>
<span class="badge badge-green">partially_resolved</span>
<span class="badge badge-green">pending_external</span>
</td>
<td>
<span class="badge badge-red">resolved</span>
<span class="badge badge-red">closed</span>
<span class="badge badge-red">cancelled</span>
<span class="badge badge-amber">ovr_pending ⚠️</span>
</td>
</tr>
</tbody>
</table>
<div class="callout callout-warn">
<strong>Inconsistency:</strong> <code>ovr_pending</code> is treated as <em>inactive</em> by <code>is_active_status</code> even though it's a mid-lifecycle state. Service methods guarding on active status would reject operations on OVR-pending complaints.
</div>
</div>
</div>
<!-- TAB 2: STEPPER -->
<div id="stepper" class="tab-panel">
<div class="section-card">
<h2>2. Detail Page Stepper</h2>
<p class="subtitle">6 ordered progress flags rendered inline in <code>complaint_detail.html:147</code>. Driven by a boolean dict built at <code>ui_views.py:745</code>. Hidden when status is <code>cancelled</code>.</p>
<div class="stepper">
<div class="step">
<div class="step-circle">1</div>
<div class="step-label">Created</div>
<div class="step-flag">always ✓</div>
</div>
<div class="step">
<div class="step-circle">2</div>
<div class="step-label">Activate</div>
<div class="step-flag">activated_at set</div>
</div>
<div class="step">
<div class="step-circle">3</div>
<div class="step-label">Taxonomy</div>
<div class="step-flag">taxonomy_reviewed_at</div>
</div>
<div class="step">
<div class="step-circle">4</div>
<div class="step-label">Send to Dept</div>
<div class="step-flag">sent_to_department</div>
</div>
<div class="step">
<div class="step-circle">5</div>
<div class="step-label">Response</div>
<div class="step-flag">dept responded</div>
</div>
<div class="step">
<div class="step-circle">6</div>
<div class="step-label">Resolve</div>
<div class="step-flag">resolved / closed</div>
</div>
</div>
<h3>Step Details</h3>
<table>
<thead>
<tr><th>#</th><th>Step</th><th>Flag</th><th>Icon</th><th>Action when not done</th></tr>
</thead>
<tbody>
<tr><td>1</td><td><strong>Created</strong></td><td>always green</td><td><code>check</code></td><td>—</td></tr>
<tr><td>2</td><td><strong>Activate</strong></td><td><code>activated_at</code></td><td><code>play</code></td><td>"Activate this complaint" → <code>complaint_activate</code></td></tr>
<tr><td>3</td><td><strong>Taxonomy</strong></td><td><code>taxonomy_reviewed_at</code></td><td><code>clipboard-check</code></td><td>"Review taxonomy" → <code>confirm_taxonomy</code></td></tr>
<tr><td>4</td><td><strong>Send to Dept</strong></td><td><code>sent_to_department</code> / <code>forwarded_to_dept_at</code></td><td><code>send</code></td><td>"Send to department" modal</td></tr>
<tr><td>5</td><td><strong>Response</strong></td><td>explanation used OR dept responded</td><td><code>message-square</code></td><td>"Awaiting department response"</td></tr>
<tr><td>6</td><td><strong>Resolve</strong></td><td><code>status in (resolved, closed)</code></td><td><code>check-circle-2</code></td><td>"Generate Resolution"</td></tr>
</tbody>
</table>
<div class="callout callout-info">
The stepper is <strong>flag-driven, not status-driven</strong>. E.g. "resolved" lights up green whenever <code>status ∈ (resolved, closed)</code>, regardless of path taken.
</div>
</div>
</div>
<!-- TAB 3: ENTRY POINTS -->
<div id="entrypoints" class="tab-panel">
<div class="section-card">
<h2>3. Status-Mutating Entry Points</h2>
<p class="subtitle">Code paths that modify <code>complaint.status</code>. Only <code>ComplaintService.change_status</code> enforces the transition map — the rest set status directly.</p>
<table>
<thead>
<tr><th>Action</th><th>Location</th><th>Transition enforced?</th></tr>
</thead>
<tbody>
<tr><td><strong>Generic change status</strong></td><td><code>ui_views.py:1365</code></td><td><span class="badge badge-green">Yes</span></td></tr>
<tr><td>Activate (open→in_progress)</td><td><code>ui_views.py:2125</code></td><td><span class="badge badge-green">service guard</span></td></tr>
<tr><td>Assign / reopen-on-assign</td><td><code>ui_views.py:851</code></td><td><span class="badge badge-green">service guard</span></td></tr>
<tr><td>Reopen as new complaint</td><td><code>ui_views.py:1777</code></td><td><span class="badge badge-green">service guard</span></td></tr>
<tr><td>OVR toggle</td><td><code>ui_views.py:1549</code></td><td><span class="badge badge-red">direct</span></td></tr>
<tr><td>OVR approve</td><td><code>ui_views.py:1640</code></td><td><span class="badge badge-red">direct</span></td></tr>
<tr><td>OVR reject</td><td><code>ui_views.py:1755</code></td><td><span class="badge badge-red">direct</span></td></tr>
<tr><td>API auto-resolve</td><td><code>views.py:2040</code></td><td><span class="badge badge-red">direct</span></td></tr>
<tr><td>Convert to appreciation</td><td><code>views.py:2198</code></td><td><span class="badge badge-red">direct</span></td></tr>
<tr><td>Meeting auto-resolve</td><td><code>views.py:3279</code></td><td><span class="badge badge-red">direct</span></td></tr>
<tr><td>Bulk status change</td><td><code>utils.py:263</code></td><td><span class="badge badge-red">direct</span></td></tr>
<tr><td><code>close_stale_complaints</code> cmd</td><td><code>close_stale_complaints.py:113</code></td><td><span class="badge badge-red">direct (bulk UPDATE)</span></td></tr>
</tbody>
</table>
<div class="callout callout-warn">
<strong>7 code paths bypass the transition map.</strong> This means invalid transitions can occur via OVR views, bulk operations, API auto-resolve, convert-to-appreciation, meeting-resolve, and the stale-close command.
</div>
</div>
</div>
<!-- TAB 4: SUB-WORKFLOWS -->
<div id="subworkflows" class="tab-panel">
<div class="section-card">
<h2>4. Sub-Workflows</h2>
<p class="subtitle">Independent state machines attached to a complaint, each with its own field/model.</p>
<div class="mermaid-wrapper" style="margin-bottom: 1.5rem;">
<pre class="mermaid">
graph TD
C[COMPLAINT<br/>status: 8 states]
C --> DR["Dept Routing<br/>routing_status"]
C --> CI["Champion Investigation<br/>status"]
C --> MR["Manager Review<br/>manager_review_status"]
C --> PC["Patient Contact<br/>patient_contact_status"]
C --> SA["Satisfaction<br/>satisfaction"]
C --> AA["Adverse Action<br/>verification_status"]
DR --> |sent| DR2["accepted / rejected"]
CI --> |questions_sent| CI2["answers_received"]
CI2 --> CI3["reply_submitted / direct_reply_in_progress"]
MR --> |pending| MR2["approved / rejected"]
PC --> |not_contacted| PC2["contacted / no_response"]
SA --> SA2["satisfied / neutral / dissatisfied / no_response"]
AA --> |reported| AA2["under_investigation"]
AA2 --> AA3["verified / unfounded / resolved"]
style C fill:#0a1e3f,color:#fff,stroke:none
style DR fill:#dbeafe,stroke:#007bbd
style CI fill:#dcfce7,stroke:#16a34a
style MR fill:#fef3c7,stroke:#d97706
style PC fill:#fce7f3,stroke:#db2777
style SA fill:#ede9fe,stroke:#7c3aed
style AA fill:#fee2e2,stroke:#dc2626
</pre>
</div>
<div class="sub-workflow-grid">
<div class="sw-card">
<h4>Department Routing</h4>
<div class="field"><code>ComplaintInvolvedDepartment.routing_status</code></div>
<div class="sw-states">
<span class="sw-state">sent</span>
<span class="sw-arrow">→</span>
<span class="sw-state">accepted</span>
<span class="sw-state">rejected</span>
</div>
</div>
<div class="sw-card">
<h4>Champion Investigation</h4>
<div class="field"><code>ChampionInvestigation.status</code></div>
<div class="sw-states">
<span class="sw-state">questions_sent</span>
<span class="sw-arrow">→</span>
<span class="sw-state">answers_received</span>
<span class="sw-arrow">→</span>
<span class="sw-state">reply_submitted</span>
<span class="sw-state">direct_reply_in_progress</span>
</div>
</div>
<div class="sw-card">
<h4>Manager Review</h4>
<div class="field"><code>ComplaintInvolvedDepartment.manager_review_status</code></div>
<div class="sw-states">
<span class="sw-state">pending</span>
<span class="sw-arrow">→</span>
<span class="sw-state">approved</span>
<span class="sw-state">rejected</span>
</div>
</div>
<div class="sw-card">
<h4>Patient Contact</h4>
<div class="field"><code>Complaint.patient_contact_status</code></div>
<div class="sw-states">
<span class="sw-state">not_contacted</span>
<span class="sw-arrow">→</span>
<span class="sw-state">contacted</span>
<span class="sw-state">contacted_no_response</span>
</div>
</div>
<div class="sw-card">
<h4>Satisfaction</h4>
<div class="field"><code>Complaint.satisfaction</code></div>
<div class="sw-states">
<span class="sw-state">satisfied</span>
<span class="sw-state">neutral</span>
<span class="sw-state">dissatisfied</span>
<span class="sw-state">no_response</span>
</div>
<div class="field" style="margin-top:0.5rem;">🔒 Locked by patient submission · max 3 PX-team changes · 5-day window</div>
</div>
<div class="sw-card">
<h4>Adverse Action</h4>
<div class="field"><code>ComplaintAdverseAction.verification_status</code></div>
<div class="sw-states">
<span class="sw-state">reported</span>
<span class="sw-arrow">→</span>
<span class="sw-state">under_investigation</span>
<span class="sw-arrow">→</span>
<span class="sw-state">verified</span>
<span class="sw-state">unfounded</span>
<span class="sw-state">resolved</span>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
Generated from source · apps/complaints/ · PX360
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#e8f1f8',
primaryTextColor: '#0a1e3f',
primaryBorderColor: '#007bbd',
lineColor: '#64748b',
fontSize: '14px',
fontFamily: 'Inter, sans-serif',
},
flowchart: { curve: 'basis', padding: 20 },
stateDiagram: { backgroundColor: '#fafbfc' },
});
function switchTab(e, tabId) {
document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('active'));
document.querySelectorAll('.tab-panel').forEach(p => p.classList.remove('active'));
e.currentTarget.classList.add('active');
document.getElementById(tabId).classList.add('active');
}
</script>
</body>
</html>

1411
docs/user_guide.html Normal file
View File

File diff suppressed because it is too large Load Diff

344
docs/workflows/appreciations.md Normal file
View File

@ -0,0 +1,344 @@
# Appreciations — Workflow & Lifecycle
> Source of truth: `apps/appreciation/`. This is an **outbound recognition/recognition** module (recognition sent *to* staff/physicians), fundamentally different from inbound case-management. This document describes the **current implementation only**. Every claim is cited as `file:line`.
> **⚠ Read first — two important findings:**
> 1. `VALID_APPRECIATION_TRANSITIONS` (`models.py:28-34`) is **defined but never referenced** anywhere (dead code). The state machine is enforced **only** by runtime `ValueError` guards inside the model transition methods.
> 2. The REST API `create` and complaint→appreciation conversion call `appreciation.send()` on a freshly-created DRAFT, but `send()` requires ACTIVATED/AI_ANALYZED — **both would raise `ValueError`** (likely bugs). The **working path is the UI activation-gate flow**.
---
## 1. Purpose
**Appreciations = BOTH inbound patient feedback AND outbound staff recognition, but the dominant designed workflow is OUTBOUND recognition FROM PX/hospital staff TO staff/physicians.**
Evidence:
- `apps/appreciation/models.py:2`, `__init__.py:2`, `README.md:3`, `IMPLEMENTATION_SUMMARY.md:4`: *"Send and track appreciation to users and physicians."*
- The **outbound** character: `appreciation_create` is gated to PX/hospital staff (`ui_views.py:155`); the email subject is *"Staff Appreciation"* (`signals.py:72`); the body *"A staff member in your department has received an appreciation. Please acknowledge their good work."* (`signals.py:179`); `tasks.py:18` *"Send email + SMS to champion, manager, and appreciated staff."*
- The **inbound patient-feedback** channel: `public_appreciation_submit` (`ui_views.py:1196`) — patients/public submit a message, created as DRAFT, then PX staff triage and activate/send. Plus complaint→appreciation conversion (`complaints/views.py:2076`).
So: **a recognition engine whose originating actors can be (a) PX/hospital staff sending peer/leadership recognition, (b) public/patient submissions awaiting staff review, or (c) appreciation-type complaints being formally converted.** The terminal recipient is always a staff member or physician.
---
## 2. How a Case Starts
### 2.1 Who can create
| Channel | View/Serializer | Permission | File:line |
|---|---|---|---|
| Internal UI form | `appreciation_create` + `AppreciationForm` | `@login_required`; PX/Hosp-Admin/PX-Mgmt/PX-Employee | `forms.py:8`; `ui_views.py:153` |
| Public portal | `public_appreciation_submit` | **No auth** (`@csrf_exempt`); rate-limited (5/5min/IP) | `ui_views.py:1196` |
| External API (HIS integration) | `integrations/api_views.py` create | API-key scoped to a hospital | `integrations/api_views.py:606` |
| REST API create | `AppreciationCreateSerializer` | `IsAuthenticated` | `views.py:55`, `serializers.py:132` |
| Complaint → Appreciation conversion | `convert_to_appreciation` | Edit permission on the complaint | `complaints/views.py:2075` |
### 2.2 Creation channels in detail
**(a) Internal UI form** (`forms.py:8`): ModelForm exposing only `["hospital", "department", "message_en"]` (`forms.py:13`); `department` restricted to active departments (`forms.py:34`). On POST: `sender = request.user`, `status = DRAFT` (`ui_views.py:173`). **Category/recipient/visibility are NOT set here** — decided later during activate/send.
**(b) Public portal** (`ui_views.py:1196`): Inputs `contact_name`, `contact_phone`, `message`, `hospital`, optional `staff_name`/`department`/`section`. Required: name, phone, message, hospital (`ui_views.py:1224`). Creates with `status=DRAFT`, `visibility=PUBLIC`, `is_anonymous=False`, `category=None`, metadata `{source:"public_form", ...}` (`ui_views.py:1239`). Fires `notify_staff_new_item.delay("appreciation", ...)` (`ui_views.py:1258`). Returns `reference_number`.
**(c) External API** (`integrations/api_views.py:606`): Creates DRAFT, visibility PUBLIC, metadata `{source:"external_api", ...}`. Builds its own `APR-YYYYMMDD-<random>` (`api_views.py:602`) — informational, since `save()` also generates the canonical `reference_number`. Fires `notify_staff_new_item`.
**(d) REST API create** (`views.py:143`, serializer `serializers.py:132`):
Required: `recipient_type` (`['user','staff']`), `recipient_id` (UUID), `message_en`, `hospital_id`. Optional: `category_id`, `message_ar`, `visibility` (default PRIVATE), `is_anonymous`, `department_id`. Validation: recipient must belong to hospital; category hospital-compatible. `AppreciationViewSet.create` resolves a `User`/`Staff` via `ContentType`, creates the record (status DRAFT), then **immediately calls `appreciation.send()`** (`views.py:198`).
**(e) Complaint → Appreciation conversion** (`complaints/views.py:2076`): Guards — complaint active (`is_active_status`, `complaints/views.py:2087`), `complaint_type == "appreciation"` (`:2096`), not already converted (`:2103`). Defaults: `message_en` ← `complaint.description`; `message_ar` ← `complaint.short_description_ar`; `visibility="private"`; `is_anonymous=True` (`:2113`). Creates DRAFT (`:2171`), then `appreciation.send()` (`:2183`). Links back via `metadata.appreciation_id` (`:2186`); optionally closes complaint (`:2196`). Default category "Patient Feedback Appreciation" (code `patient_feedback`, `create_patient_feedback_category.py`).
### 2.3 What happens immediately after submission
- **Reference number** generated in `Appreciation.save()` via `generate_reference("APR", hospital)` (`models.py:243`) → `APR-YYYYMM-NNNN` (global monthly sequence). Stored on `reference_number` (`models.py:198`), comment *"internal-only, not publicly trackable"*.
- **Default status = DRAFT** (`models.py:193`).
- **`post_save` signal `handle_appreciation_sent`** (`signals.py:27`) only acts when `status == SENT and not notification_sent` — does **nothing** at creation (DRAFT).
- For public/external: **PX-admin notification task** `notify_staff_new_item("appreciation", id)` fired (`ui_views.py:1259`, `api_views.py:625`) → `emails/new_appreciation_notification.html`.
### 2.4 Why DRAFT + activation gate?
Mirrors the complaints activation gate. A DRAFT appreciation is **untriaged**: no recipient set (internal form), no AI analysis, no decision to publish at chosen visibility. **Activation** (`ui_views.py:195`) is the PX-staff gate that confirms content, triggers AI analysis, stamps `activated_at`/`activated_by`, emits audit. Only after activation may it be sent (`models.py:335`).
The draft count is surfaced to reviewers via `core/context_processors.py:74` (`draft_appreciation_count`) for PX/Hosp-Admin/PX-Mgmt.
---
## 3. Complete Lifecycle
### 3.1 The declared state machine — `VALID_APPRECIATION_TRANSITIONS` (`models.py:28-34`) — verified
```
DRAFT → {ACTIVATED}
ACTIVATED → {AI_ANALYZED, SENT}
AI_ANALYZED → {SENT}
SENT → {ACKNOWLEDGED}
ACKNOWLEDGED → set() (terminal)
```
### 3.2 Where enforced — NOWHERE via the constant
`VALID_APPRECIATION_TRANSITIONS` is **never imported or referenced** anywhere else (grep confirmed). The **model transition methods** each re-check the current status and raise `ValueError`:
- `activate()` (`models.py:309`) — requires DRAFT.
- `mark_ai_analyzed(analysis_data)` (`models.py:320`) — requires ACTIVATED.
- `send()` (`models.py:331`) — requires ACTIVATED or AI_ANALYZED.
- `acknowledge()` (`models.py:344`) — requires SENT.
### 3.3 `clean()` and DB CheckConstraints
- **No `clean()` method** on `Appreciation`.
- **No `CheckConstraint`s** in any migration. Only `unique_together` on category (`models.py:84`) and `AppreciationStats` (`models.py:517`), `unique=True` on `reference_number`/badge `code`.
**Conclusion:** status integrity enforced **only at runtime in Python methods**, not at DB layer.
---
## 4. Status Definitions
| Status | Constant | When entered | Who advances | Next | Key code |
|---|---|---|---|---|---|
| **DRAFT** | `AppreciationStatus.DRAFT` (`models.py:21`) | On creation (model default) | PX/hospital staff via `appreciation_activate` | ACTIVATED | created; ref number generated; PX admins notified (public/external only) |
| **ACTIVATED** | `ACTIVATED` (`models.py:22`) | Staff approves/triages draft; runs AI | AI step (auto) or staff `appreciation_send`/`send_to` | AI_ANALYZED, SENT | `activated_at`/`activated_by` stamped (`models.py:316`, `ui_views.py:211`) |
| **AI_ANALYZED** | `AI_ANALYZED` (`models.py:23`) | `mark_ai_analyzed()` called by activate view after a successful AI call | Staff via `send`/`send_to` | SENT | `ai_analyzed_at` + `ai_analysis` JSON (`models.py:326`, `ui_views.py:254`) |
| **SENT** | `SENT` (`models.py:24`) | `send()` invoked | The recipient (User/Staff) via `acknowledge` | ACKNOWLEDGED | `sent_at` stamped (`models.py:339`); triggers `post_save` cascade (notifications, stats, badges) |
| **ACKNOWLEDGED** | `ACKNOWLEDGED` (`models.py:25`) | Recipient acknowledges | (terminal) | none | `acknowledged_at` (`models.py:352`) |
### 4.1 The AI_ANALYZED status — what AI analysis happens
Performed **synchronously inside `appreciation_activate`** (`ui_views.py:230-258`), immediately after DRAFT→ACTIVATED. Uses `apps.core.ai_service.AIService.chat_completion` (NOT `analyze_complaint`):
- Prompt asks for JSON: `summary_en`, `summary_ar`, `themes` (list), `tone` (`warm|formal|casual`), `suggested_response_en`, `suggested_response_ar` (`ui_views.py:234-246`).
- Parsed and passed to `appreciation.mark_ai_analyzed(analysis_data)` (`ui_views.py:251`).
- On failure: logged + swallowed; appreciation stays ACTIVATED (does NOT auto-advance) — still sendable (`ui_views.py:255`).
- `AIService.chat_completion` (`ai_service.py:685`) → OpenRouter `/chat/completions`, model `google/gemini-2.5-flash-lite` default (`ai_service.py:41`).
**So AI_ANALYZED is a "content enrichment" step (summary/themes/tone/draft reply), not a sentiment/severity gate.** The appreciation can still be SENT directly from ACTIVATED without ever becoming AI_ANALYZED (`models.py:30`).
---
## 5. Workflow Actions
### 5.1 UI actions (`ui_views.py`)
| Action | Function | URL name | Status gate | Permission |
|---|---|---|---|---|
| List | `appreciation_list` `:37` | `appreciation_list` | — | `@login_required`; hospital-filtered |
| Detail | `appreciation_detail` `:92` | `appreciation_detail` | — | login; PX/Hosp-Admin or same-hospital |
| Create (internal) | `appreciation_create` `:153` | `appreciation_create` | creates DRAFT | PX/Hosp-Admin/PX-Mgmt/PX-Employee |
| **Activate** (DRAFT→ACTIVATED + AI) | `appreciation_activate` `:193` | `appreciation_activate` | must be DRAFT (`:198`) | PX/Hosp-Admin/PX-Mgmt/PX-Employee |
| Send (form) | `appreciation_send` `:264` | `appreciation_send` | ACTIVATED or AI_ANALYZED (`:269`) | PX/Hosp-Admin/PX-Mgmt/PX-Employee |
| **Send-to** (AJAX, person/department) | `appreciation_send_to` `:320` | `appreciation_send_to` | ACTIVATED or AI_ANALYZED (`:344`) | PX/Hosp-Admin/Dept-Manager/PX-Mgmt/PX-Employee |
| **Acknowledge** (SENT→ACKNOWLEDGED) | `appreciation_acknowledge` `:485` | `appreciation_acknowledge` | must be SENT (`:500`) | **recipient only** (User ContentType match, `:492`) |
| Public submit | `public_appreciation_submit` `:1196` | `public_appreciation_submit` | creates DRAFT | **none** |
| Restore deleted | `appreciation_restore` `:1036` | `admin_appreciation_restore` | — | PX/Hosp-Admin |
| PDF | `appreciation_pdf` `:1276` | `appreciation_pdf` | — | `@login_required` |
| Leaderboard | `leaderboard_view` `:515` | `leaderboard_view` | — | login |
| My Badges | `my_badges_view` `:580` | `my_badges_view` | — | login |
| Category CRUD | `:666-843` | `category_*` | — | PX/Hosp-Admin only |
| Badge CRUD | `:850-1033` | `badge_*` | — | PX/Hosp-Admin only |
| AJAX: users/staff/physicians/departments | `:1057-1147` | `ajax/*` | — | login |
Detail view exposes `can_activate` and `can_send` flags (`ui_views.py:142`).
### 5.2 REST API (`views.py`)
`AppreciationCategoryViewSet` (`:33`), `AppreciationViewSet` (`:55`, actions: `acknowledge` `:210`, `my_appreciations` `:232`, `sent_by_me` `:263`, `summary` `:277`), `AppreciationStatsViewSet` (`:363`), `AppreciationBadgeViewSet` (`:394`, PX/Hosp-Admin), `UserBadgeViewSet` (`:416`), `LeaderboardView` (`:445`).
`acknowledge` verifies the requester is the recipient via ContentType+id (`views.py:216`), else HTTP 403.
> **⚠ Note:** there is **no `activate` or `ai_analyze` REST action** — those are UI-only.
> **⚠ Gap — REST `create` vs status:** `AppreciationViewSet.create` (`views.py:143`) creates the record and immediately calls `appreciation.send()` (`views.py:198`). Because `send()` requires ACTIVATED/AI_ANALYZED (`models.py:335`), this raises `ValueError` on a DRAFT.
---
## 6. Decision Points
1. **Activation gate (DRAFT→ACTIVATED)** (`ui_views.py:195`). Mirrors the complaints activation gate.
2. **AI analysis path vs direct-send** — AI attempted at `appreciation_activate` (`ui_views.py:230`). If it succeeds → AI_ANALYZED; if it throws → stays ACTIVATED and is still sendable. From ACTIVATED the send step is allowed (`models.py:30`), so **AI is optional** to progressing.
3. **Visibility/audience decision** — `AppreciationVisibility` (`models.py:37`): PRIVATE/DEPARTMENT/HOSPITAL/PUBLIC. Default PRIVATE (`models.py:190`). Public portal forces PUBLIC (`ui_views.py:1248`); external API forces PUBLIC (`api_views.py:613`); complaint conversion defaults `"private"` (`complaints/views.py:2115`). Read-access filtered in `AppreciationViewSet.get_queryset` (`views.py:78`).
4. **Recipient/target selection** — done at send time, not creation, in `appreciation_send_to`: `recipient_type ∈ {person, department}` (`ui_views.py:350`). If department: auto-targets champion+manager via `get_champion_and_manager`. Optional `staff_id` sets recipient to a `Staff`.
5. **Badge awarding decision** — `signals.check_and_award_badges` (`signals.py:306`) runs whenever an appreciation reaches SENT.
---
## 7. Assignment Flow — RECIPIENTS
There is **no "case assignment to an agent"**. The analogous concept is the **recipient** (who the recognition is for) plus the **visibility audience**.
### 7.1 Recipient model
- Recipient is a **GenericForeignKey** (`recipient_content_type` + `recipient_object_id` + `recipient`) (`models.py:132`). Eligible concrete types: `accounts.User` and `organizations.Staff` (incl. physicians as `staff_type='physician'`, `ui_views.py:1110`).
- Sender: `models.ForeignKey("accounts.User")` (`models.py:127`).
- `AppreciationForm` (internal) does **not** set a recipient — only `hospital`, `department`, `message_en`. Recipient bound at send step (`ui_views.py:427`) for the department path, or via `recipient_type`/`recipient_id` in REST/conversion.
- The "owner" (for routing) is computed by `get_owner()` (`models.py:250`) — a cascade over section/department role-holders. **⚠ Gap:** `get_owner()` is defined but not invoked by any code in the appreciation app (verify external callers).
### 7.2 Visibility
`AppreciationVisibility` (`models.py:37`): PRIVATE, DEPARTMENT, HOSPITAL, PUBLIC. Read-side enforcement in `AppreciationViewSet.get_queryset` (`views.py:78`): a user sees their sent items, those received by their User/Staff profile, DEPARTMENT-vis in their dept, HOSPITAL-vis in their hospital, and all PUBLIC.
### 7.3 Organization context
`hospital` (required, `models.py:139`), `department` (nullable, `models.py:173`), `section` (nullable, `models.py:165`), plus three **DEPRECATED** legacy fields (`legacy_location`, `legacy_main_section`, `legacy_subsection`, `models.py:140-163`).
---
## 8. Investigation Process — N/A
Appreciations have **no investigation phase**. No investigator field, no investigation status, no evidence model. The closest analog is the **AI_ANALYZED** step, which is automated content enrichment (summary/themes/tone/suggested reply), not a human investigation. **Why N/A:** appreciations are positive recognition, not problems requiring root-cause analysis.
---
## 9. Communication Flow — notifications
### 9.1 On reaching SENT — `post_save` cascade
`signals.handle_appreciation_sent` (`signals.py:27`) fires when `status == SENT and not notification_sent`. It calls:
- **`send_appreciation_notification`** (`signals.py:49`): builds HTML email ("Staff Appreciation"); resolves recipient email/phone via `get_recipient_email`/`get_recipient_phone` (`models.py:287`); sends email + SMS; sender display "Anonymous" if `is_anonymous`; calls `_send_department_head_notification` (`signals.py:140`) emailing `department.manager` + `Staff(department=dept, is_head=True)`; calls `_send_cc_notifications` (`signals.py:203`); sets `notification_sent=True`/`notification_sent_at`.
- **`update_appreciation_stats`** (`signals.py:227`) — §12.
- **`check_and_award_badges`** (`signals.py:306`) — §Gamification.
### 9.2 The `send_appreciation_notifications` Celery task
`tasks.py:9` (`@shared_task`) — a **separate, richer** notification path used by the UI `appreciation_send_to` department branch (`ui_views.py:442`). Requires a `department`; `get_champion_and_manager(department)`; per target sends email + SMS; if `staff_id` provided, emails/SMS the Staff *"You've Been Appreciated!"*.
> **⚠ Two notification codepaths** — `signals.py` (sync, fires on every SENT) and `tasks.py` (async, fires only from UI `send_to` department branch). Both can run for the same appreciation if sent via `send_to`, potentially double-notifying.
### 9.3 On creation of a public/external DRAFT
`notify_staff_new_item("appreciation", id)` emails PX admins/on-call roster (`complaints/tasks.py:2489`), template `emails/new_appreciation_notification.html`.
### 9.4 On badge award
`signals.check_and_award_badges` emails the recipient user *"You earned a badge: <name>!"* (`signals.py:357`).
---
## 10. Escalation Flow — N/A
**No SLA timers, no escalation levels, no overdue fields** in `Appreciation` (`models.py:110-237`). No celery beat task references appreciation SLA. **Why N/A:** appreciation is non-urgent recognition; urgency/SLA semantics belong to complaints.
---
## 11. Resolution Process — "acknowledgment"
The analog of resolution is the **acknowledge** transition (SENT→ACKNOWLEDGED).
- Model method: `acknowledge()` (`models.py:344`) — sets `status=ACKNOWLEDGED`, `acknowledged_at=now()`.
- UI: `appreciation_acknowledge` (`ui_views.py:485`) — POST; **only the recipient** (matched by User ContentType + id, `ui_views.py:492`); rejects if not SENT (`ui_views.py:500`).
- REST: `AppreciationViewSet.acknowledge` (`views.py:210`) — same recipient check, HTTP 403 otherwise.
"Acknowledgment" = the recipient has confirmed/thanked — it is the **recipient's terminal action**. There is **no sender-side resolution**.
---
## 12. Closure Process
### 12.1 Terminal state & reopen
ACKNOWLEDGED is terminal: `VALID_APPRECIATION_TRANSITIONS[ACKNOWLEDGED] = set()` (`models.py:33`), and `acknowledge()` leaves no forward method. There is **no reopen** action/view anywhere. Once ACKNOWLEDGED, permanently complete.
### 12.2 Soft delete / restore
`Appreciation` extends `SoftDeleteModel` (`models.py:110`); soft-deletable + restorable via `appreciation_restore` (`ui_views.py:1036`, uses `Appreciation.all_objects` + `restore()`). Restore does not change status.
### 12.3 Statistics aggregation
`AppreciationStats` (`models.py:476`) — **monthly per recipient**. Unique key `(recipient_content_type, recipient_object_id, year, month)` (`models.py:517`). Fields: `received_count`, `sent_count`, `acknowledged_count`, `hospital_rank`, `department_rank`, `category_breakdown` (JSON). Aggregated in `signals.update_appreciation_stats` (`signals.py:227`) when an appreciation reaches SENT: `get_or_create` the month row; atomically increment counts via `F('...') + 1`; update category JSON; `recalculate_rankings` (`signals.py:269`) re-numerates ranks by `-received_count`.
### 12.4 Leaderboard
`LeaderboardView` (`views.py:445`): reads `year`/`month` (defaults current month); filters `AppreciationStats` by hospital; enumerates rank; attaches earned badges. UI equivalent `leaderboard_view` (`ui_views.py:515`).
### 12.5 Summary
`AppreciationViewSet.summary` (`views.py:277`) and `appreciation_summary_ajax` (`ui_views.py:1150`) compute total/this-month received & sent, badges earned, top category, hospital rank.
---
## 13. Exception Flows
### 13.1 Complaint → Appreciation conversion
`complaints/views.py:2076`. Guards: `is_active_status`, `complaint_type == "appreciation"`, `metadata.appreciation_id` absent. Default category "Patient Feedback Appreciation" (code `patient_feedback`).
### 13.2 ⚠ INCONSISTENCY (likely bug): conversion and REST create call `send()` on DRAFT
- Conversion: creates `status=DRAFT` (`complaints/views.py:2171`) then `appreciation.send()` (`:2183`).
- REST create: creates DRAFT then `appreciation.send()` (`views.py:198`).
- `send()` (`models.py:335`) requires ACTIVATED/AI_ANALYZED, else `ValueError`.
**Both paths would raise `ValueError` at runtime.** Neither wraps `send()` in try/except. This strongly indicates the **primary, exercised path is the UI activation-gate flow**, and these two callers are out of sync with the gate model.
### 13.3 Draft abandonment
A DRAFT has no expiry task and no cleanup. Remains queryable as DRAFT (counted in `core/context_processors.py:79`, `ui_views.py:71`). No auto-close/activation.
### 13.4 Visibility changes
`visibility` is a plain CharField (`models.py:190`) with no transition guard — editable at any status via admin or direct mutation. Public/external forced PUBLIC at creation, not otherwise change-protected.
### 13.5 Badge revocation
**No revoke/un-award path.** `UserBadge` (`models.py:432`) has only create + read. `badge_delete` (`ui_views.py:1004`) refuses to delete a badge with any `UserBadge` (`ui_views.py:1018`) — earned badges are protected. A badge, once awarded, persists.
### 13.6 Duplicate appreciation
**No deduplication** on creation. The only dedup is per-badge-award (`signals.py:326`) and per-stats-month (`unique_together` `models.py:517`, guarded by `get_or_create`).
### 13.7 Restore from soft-delete
`appreciation_restore` (`ui_views.py:1036`) — PX/Hosp-Admin only; redirects to `config:deleted_items`.
### 13.8 AI-failure handling
In `appreciation_activate`, an AI exception is logged but swallowed (`ui_views.py:255`) — appreciation stays ACTIVATED and is still sendable. At infra level, `AIService._notify_ai_failure` (`ai_service.py:172`) emails PX admins (debounced hourly) on HTTP 401/402.
---
## 14. Department-Response Sub-Flow — NOT used (confirmed)
Appreciations **do not** use the inbound send-to-department → department-responds → resolve cycle. There is no `responded`/`department_action` status, no department-side response model, no SLA on department reply. The `send_to` step (`ui_views.py:320`) is **outbound only** — it delivers the appreciation to a department's champion+manager+staff and marks the appreciation SENT; the department does not "respond back" through the system (their only return action is the recipient's `acknowledge`).
**Why:** this module is outbound recognition. The "send to department" verb here means *deliver recognition to that department*, not *open a case for the department to handle*.
---
## 15. End-to-End Example
```
Patient submits appreciation via public form (mentions Nurse A)
↓ (ui_views.py:1196) → status=DRAFT, ref APR-202607-0001,
visibility=PUBLIC, PX admins notified
PX staff reviews + activates
↓ (ui_views.py:193) → status=ACTIVATED, activated_at/by
AI analysis runs synchronously
[DECISION: AI succeeds → AI_ANALYZED, or stays ACTIVATED]
↓ (ui_views.py:230) → ai_analysis JSON stored (summary/themes/tone/suggested reply)
PX sends to Department X (target Nurse A / champion / manager)
↓ (ui_views.py:320) → recipient=Staff(Nurse A), status=SENT, sent_at
[DECISION: visibility PRIVATE/DEPARTMENT/HOSPITAL/PUBLIC]
post_save cascade fires:
- email+SMS to recipient ("Staff Appreciation")
- email department manager + dept heads
- cc notifications
- update_appreciation_stats (received/sent count, rank)
- check_and_award_badges (e.g. "First Appreciation")
→ badge email to recipient
Nurse A (the recipient) acknowledges
↓ (ui_views.py:485) → status=ACKNOWLEDGED, acknowledged_at
[TERMINAL — no reopen, no further actions]
```
---
## Appendix A — Gamification (Badges)
### A.1 `AppreciationBadge` (`models.py:360`) — definition
Fields: `hospital` (null = system-wide), `code` (unique), bilingual `name_en/ar`/`description_en/ar`, `icon`, `color`, `order`. **`criteria_type`** (`models.py:389`): `received_count`, `received_month`, `streak_weeks`, `diverse_senders`. `criteria_value` (int threshold). `is_active`.
### A.2 Seed data (`seed_appreciation_data.py`)
**Categories:** `excellent_care`, `team_player`, `innovation`, `leadership`, `mentorship`, `going_extra_mile`, `reliability`, `positive_attitude`.
**Badges** (seed file is authoritative — `README.md` differs):
| code | name_en | criteria_type | value |
|---|---|---|---|
| first_appreciation | First Appreciation | received_count | 1 |
| appreciated_5 | Rising Star | received_count | 5 |
| appreciated_10 | Shining Star | received_count | 10 |
| appreciated_25 | Super Star | received_count | 25 |
| appreciated_50 | Legendary | received_count | 50 |
| monthly_champion | Monthly Champion | received_month | 10 |
| streak_4_weeks | Consistent | streak_weeks | 4 |
| diverse_appreciation | Well-Loved | diverse_senders | 10 |
### A.3 `UserBadge` (`models.py:432`) — award record
GenericFK recipient, FK `badge`, `earned_at` (`auto_now_add`), `appreciation_count` (count-at-award), `metadata` JSON. No unique constraint — awarder dedups manually (`signals.py:326`).
### A.4 Awarding logic — `signals.check_and_award_badges` (`signals.py:306`)
Triggered from `handle_appreciation_sent` when SENT. Iterates active badges for the hospital/system-wide; skip if already earned; `check_badge_criteria` (`signals.py:383`): `received_count` (total SENT to recipient), `received_month` (this month), `streak_weeks` (`check_appreciation_streak` `signals.py:498` — Mon-start weeks; gap breaks streak), `diverse_senders` (distinct senders). If qualifies: `UserBadge.objects.create`, email recipient.
### A.5 Badge progress UI — `my_badges_view` (`ui_views.py:580`)
Computes per-badge progress % toward threshold. Template `appreciation/my_badges.html`.
---
## Appendix B — Flagged gaps / ambiguities
1. **`VALID_APPRECIATION_TRANSITIONS` is dead code** — defined but never enforced via lookup; transitions rely solely on per-method `ValueError`. Constant and methods agree today but nothing keeps them in sync.
2. **REST `create` and complaint conversion call `send()` on DRAFT** — would raise `ValueError` (`views.py:198`, `complaints/views.py:2183` vs guard `models.py:335`). Likely bug/stale code; UI activation flow is the working path.
3. **`AppreciationForm` does not capture recipient/category/visibility** — decided later (at send-time for UI path). An internally-created DRAFT has no recipient until `send_to` runs.
4. **Two notification codepaths** — `signals.py` (sync, every SENT) and `tasks.py` (async, UI `send_to` dept branch). Potential double-notification.
5. **No badge revocation, no reopen, no draft expiry** — by design.
6. **README badge list vs seed file badge list differ** — seed file is authoritative.
7. **`get_owner()` (`models.py:250`) defined but not invoked** in the appreciation app — verify external callers.

439
docs/workflows/complaints.md Normal file
View File

@ -0,0 +1,439 @@
# Complaints — Workflow & Lifecycle
> Source of truth: current code in `apps/complaints/` (+ `apps/organizations/ui_views.py` for the manager-review tier).
> This document describes the **current implementation only**. Every claim is cited as `file:line`.
> It is *not* a redesign. Where code disagrees with `docs/workflows.md`, the code wins and the gap is flagged as **⚠ Gap**.
---
## 1. Purpose
The Complaints module is the case-management engine for patient complaints. Per the model docstring (`apps/complaints/models.py:1-10`, `:197-207`) it:
- Tracks complaints with **SLA deadlines** (`models.py:501` `due_at`).
- Manages the workflow `open → in progress → resolved → closed` (plus extra states).
- Triggers a **resolution-satisfaction survey** on closure (`models.py:570-573`; task `tasks.py:386`).
- Auto-creates **PX Actions** from negative resolution satisfaction (`tasks.py:477`).
- Maintains a **complaint timeline** (`ComplaintUpdate`, `models.py:1177`) and **attachments** (`ComplaintAttachment`, `models.py:1131`).
The same `Complaint` model also handles **appreciations** via `ComplaintType.APPRECIATION` (`models.py:72-76`) and the sibling **Inquiry** model (`models.py:1528`) shares the app — both documented in their own files.
---
## 2. How a Case Starts
### 2.1 Creation channels
| Channel | Entry point | View function | Source recorded |
|---|---|---|---|
| **Public portal** (no login) | `POST /complaints/public/submit/` → `complaints:public_complaint_submit` (`urls.py:123`) | `ui_views.public_complaint_submit` (`ui_views.py:4369`) | `complaint_source_type=INTERNAL` (hardcoded `ui_views.py:4463`); `source=PXSource("Public Form")` |
| **Authenticated staff/internal form** | `GET/POST /complaints/new/` → `complaints:complaint_create` (`urls.py:39`) | `ui_views.complaint_create` (`ui_views.py:897`) | `complaint_source_type` default INTERNAL (`forms.py:374-380`); `source` from form/user, else `PXSource("staff")` (`ui_views.py:930-946`) |
| **Patient SMS portal** (token-auth session) | `POST /complaints/patient/<token>/visit/<visit_id>/` → `complaints:patient_complaint_visit_form` (`urls.py:154`) | `ui_views.patient_complaint_visit_form` (`ui_views.py:6686`) via `PatientComplaintSession` (`models.py:3449`) | `complaint_source_type="internal"`; metadata `submitted_via:"patient_link"` |
| **DRF API** (any authenticated user) | `POST /complaints/api/complaints/` → `ComplaintViewSet` (`views.py:117`) | `ComplaintViewSet.perform_create` (`views.py:229`) | via serializer |
| **Government ticket conversion (MOH/CHI/CCHI)** | `/complaints/government-tickets/<pk>/convert/` → `complaints:convert_to_complaint` (`urls.py:214`) | `ui_views.convert_to_complaint` (`ui_views.py:6887`) | `complaint_source_type=external` for MOH/CCHI (`ui_views.py:6905`); `moh_reference`/`chi_reference` (`ui_views.py:6912-6913`) |
| Call center / Survey / Social media / MOH / CHI | **No dedicated endpoint** — these are `ComplaintSource` taxonomy values (`models.py:86-97`) selected via the `source` FK (`models.py:443`) on whichever channel is used. MOH/CHI typically arrive as `GovernmentTicket`s then convert. |
### 2.2 Who can create
- Public form & patient SMS portal: **no auth**.
- Internal staff form (`complaint_create`): `@login_required` only (`ui_views.py:895`).
- Government ticket create/import/convert: `is_px_admin() or is_px_management()` (`ui_views.py:6839, 6865, 6892, 6925`).
- DRF API: `IsAuthenticated` (`views.py:127`).
### 2.3 Information required before submission
**Public form** (`PublicComplaintForm`, `forms.py:57`, `Meta.fields` `forms.py:228-247`). Required:
`complainant_name`, `relation_to_patient`, `mobile_number`, `patient_name`, `national_id`, `incident_date`, `hospital`, `location_type`, `complaint_details`. Optional: `email`, `department`, `area`, `section`, `staff_name`, `expected_result`, `attachments` (≤5 files, ≤10 MB, jpg/png/gif/pdf/doc/docx — `forms.py:319-339`).
Validators: Saudi mobile `05xxxxxxxx` (`forms.py:282-293`); national_id 10 digits (`forms.py:295-306`); no future incident date (`forms.py:308-317`).
> **⚠ Gap:** The view re-validates inline and additionally requires `department` + `location_type` + `hospital` even though the form marks `department` optional — **the view is stricter than the form** (`ui_views.py:4401-4422`, department required at `ui_views.py:4411`).
**Internal form** (`ComplaintForm`, `forms.py:351`, `Meta.fields` `forms.py:483-501`). Required: `relation_to_patient`, `patient_name`, `national_id`, `incident_date`, `hospital`, `location_type`, `department`, `description`. Optional: `complaint_type`, `complaint_source_type`, `source`, `area`, `section`, `staff`, `expected_result`.
### 2.4 What happens immediately after submission
`Complaint.save()` (`models.py:737-772`) runs on every save and:
1. Records previous status into `_status_was` for the signal (`models.py:740-745`).
2. **Generates the reference number** if absent: `generate_reference("CMP", hospital)` (`models.py:748-751`) → format `CMP-{YYYYMM}-{SEQ:04d}` (global monthly sequence, `apps/core/reference.py:32-43`).
3. **Computes the SLA deadline** `due_at` via `calculate_sla_due_date()` (`models.py:753-754, 784-830`).
4. Hashes `national_id` → `national_id_hash` (`models.py:765-768`).
5. Syncs department send/forward timestamps (`models.py:770, 774-782`).
6. Default `status = ComplaintStatus.OPEN` (`models.py:463-465`). **Cases are created OPEN, not auto-activated** — `activated_at` is null until the activation action (§6).
Then `ComplaintService.post_create_hooks` (`complaint_service.py:1049-1086`):
- Writes a `ComplaintUpdate` "Complaint created. AI analysis running in background."
- Dispatches `analyze_complaint_with_ai` (`tasks.py:668`) and `notify_admins_new_complaint` (`tasks.py:2253`).
- Logs audit event `complaint_created`.
Public form additionally dispatches `link_complaint_patient` and `notify_staff_new_item` (`ui_views.py:4482-4486`).
**Signals** (`signals.py`):
- `pre_save` `sync_department_from_staff` (`signals.py:21-39`): auto-sets `complaint.department` from `staff.department`.
- `post_save` `send_complaint_creation_sms` (`signals.py:42-56`): dispatches creation SMS **only if** `contact_phone`/`contact_email` present.
- `post_save` `send_complaint_status_change_sms` (`signals.py:59-89`): SMS when status becomes `resolved`/`closed`.
- `post_save` on `ComplaintInvolvedDepartment` `notify_champion_on_department_assignment` (`signals.py:104-126`): notifies the champion when a sent dept row is created.
---
## 3. Complete Lifecycle
### 3.1 The 8 statuses (`ComplaintStatus`, `models.py:25-35`)
`OPEN`, `IN_PROGRESS`, `PARTIALLY_RESOLVED`, `RESOLVED`, `CLOSED`, `CANCELLED`, `PENDING_EXTERNAL`, `OVR_PENDING`.
### 3.2 The transition map
`ComplaintService.VALID_STATUS_TRANSITIONS` (`complaint_service.py:292-301`):
```
open -> [in_progress, cancelled]
in_progress -> [partially_resolved, resolved, cancelled, pending_external, ovr_pending]
partially_resolved -> [resolved, in_progress, cancelled, pending_external]
resolved -> [closed, in_progress]
closed -> [in_progress]
cancelled -> [open, in_progress]
pending_external -> [resolved, in_progress, cancelled, closed]
ovr_pending -> [in_progress, resolved, cancelled]
```
### 3.3 Enforcement layers
> **⚠ Gap vs `docs/workflows.md:12`:** that doc claims invalid statuses are "rejected at the model (`clean()`) and DB (`CheckConstraint`) level." **This is not true for Complaints.** There is **no `clean()` method** on `Complaint` and **no DB `CheckConstraint`** in any migration. The only enforcement is `ComplaintService.change_status` (`complaint_service.py:386-498`), which:
> - requires `activated_at` before any change except → CLOSED (the **activation gate**, `complaint_service.py:406-407`);
> - looks up `valid_next` for `old_status`; raises `ComplaintServiceError` if `new_status` not allowed **unless the user `is_px_admin()`** (`complaint_service.py:412-417`) — PX Admin can force any transition;
> - permission: `is_px_admin() or is_hospital_admin() or is_px_management() or is_px_employee()` (`complaint_service.py:398-400`).
**⚠ Gap:** Several writers bypass `change_status` and set `status` directly: `toggle_escalated_ovr` (`ui_views.py:1560`), `approve_ovr_escalation`/`reject_ovr_escalation` (`ui_views.py:1650, 1680, 1762`), and `ComplaintService.assign` (`complaint_service.py:228-237`) which reopens resolved/closed/cancelled by flipping back to `IN_PROGRESS`.
### 3.4 All paths
```
┌─────────────────────────── cancelled ────────────┐ (reopen→open/in_progress)
│ │
[create]→ OPEN ──┼─(activate)→ IN_PROGRESS ──┬→ partially_resolved ──┬→ resolved ──┬→ closed ──(reopen)→ IN_PROGRESS
│ │ │ │
│ ├→ pending_external ────┘ └→ IN_PROGRESS (reopen)
│ ├→ ovr_pending ──(approve/reject)→ IN_PROGRESS
│ └→ cancelled
└─(cancel)→ cancelled
```
`is_active_status` property (`models.py:880-892`): active = `OPEN, IN_PROGRESS, PARTIALLY_RESOLVED, PENDING_EXTERNAL`. Note `OVR_PENDING` is **not** active.
---
## 4. Status Definitions
| Status | Purpose | When entered | Who moves it forward | Next statuses |
|---|---|---|---|---|
| **OPEN** | "Received" (public label, progress 15%, amber, `models.py:938-950`). Logged + AI-classified but not being worked; `activated_at` null. | On creation (default, `models.py:464`) | **Activation** (`ComplaintService.activate` `complaint_service.py:106`) | IN_PROGRESS, CANCELLED |
| **IN_PROGRESS** | "In Progress" (50%, blue). Owned/being worked. | From OPEN (activate), PARTIALLY_RESOLVED, RESOLVED, CLOSED, CANCELLED, OVR_PENDING, PENDING_EXTERNAL | PX/hospital/management/employee roles (`complaint_service.py:398`) — **department managers cannot change status** | PARTIALLY_RESOLVED, RESOLVED, CANCELLED, PENDING_EXTERNAL, OVR_PENDING |
| **PARTIALLY_RESOLVED** | "In Progress" (75%, blue). Some aspects resolved. Stamps `partially_resolved_at/by` (`complaint_service.py:451`). | From IN_PROGRESS | PX/hospital/management/employee | RESOLVED, IN_PROGRESS, CANCELLED, PENDING_EXTERNAL |
| **RESOLVED** | "Resolved" (100%, emerald). Solution provided. Stamps `resolved_at/by` + optional `resolution`/`resolution_category`/`resolution_outcome` (`complaint_service.py:420-434`). | From IN_PROGRESS, PARTIALLY_RESOLVED, PENDING_EXTERNAL, OVR_PENDING | Same roles | CLOSED, IN_PROGRESS (reopen) |
| **CLOSED** | "Closed" (100%, slate). Stamps `closed_at/by`; **dispatches resolution-satisfaction survey** (`complaint_service.py:436-441`). | From RESOLVED | Same roles | IN_PROGRESS (reopen) |
| **CANCELLED** | "Cancelled" (0%, rose). Withdrawn/invalid. Stamps `cancelled_at/by`. | From OPEN, IN_PROGRESS, PARTIALLY_RESOLVED, PENDING_EXTERNAL, OVR_PENDING | Same roles | OPEN, IN_PROGRESS |
| **PENDING_EXTERNAL** | (no public label). Awaiting outside party (MOH/CHI/insurance). Sets `pending_external_set_at` + `was_pending_external=True` (`complaint_service.py:443-445`). | From IN_PROGRESS, PARTIALLY_RESOLVED | Same roles | RESOLVED, IN_PROGRESS, CANCELLED, CLOSED |
| **OVR_PENDING** | "OVR Pending Approval". Escalation/oversight awaiting PX-Admin/Hospital-Admin approval. | `toggle_escalated_ovr` (`ui_views.py:1560`) | `approve_ovr_escalation`/`reject_ovr_escalation` (PX/Hospital admin only, `ui_views.py:1650, 1680`) | IN_PROGRESS, RESOLVED, CANCELLED |
> "OVR" is **never expanded** anywhere in code/docs. From fields `is_escalated_ovr`, `escalated_ovr_by` (`models.py:676-685`) it functions as an admin-approved oversight/escalation tier.
---
## 5. Workflow Actions
Decorators are consistently `@login_required` + `@require_http_methods(["POST"])` for mutations. Permissions are enforced **inside** the function (no `@permission_required` decorators). Shared helper: `can_manage_complaint` (`ui_views.py:291` → `ComplaintService.can_manage` `complaint_service.py:78-94`).
### 5.1 Lifecycle / status actions
| Action | URL name | View (file:line) | Permission / gate | Effect |
|---|---|---|---|---|
| Activate | `complaint_activate` (`urls.py:63`) | `ui_views.complaint_activate` (`ui_views.py:2141`) | `can_activate` (`complaint_service.py:96-104`) | Assigns to current user; OPEN→IN_PROGRESS; sets `activated_at`; audit `complaint_activated` |
| Change status (resolve/close/cancel) | `complaint_change_status` (`urls.py:42`) | `ui_views.complaint_change_status` (`ui_views.py:1376`) | PX/Hosp-Admin/PX-Mgmt/PX-Employee; activation gate (except→closed); transition map (PX-Admin bypasses) | §3.2 |
| Reopen | `complaint_reopen` (`urls.py:48`) | `ui_views.complaint_reopen` (`ui_views.py:1788`) | PX/Hosp-Admin/assignee/dept-manager; only from resolved/closed (view) | **Creates a NEW OPEN complaint** linked via `reopened_from`; original keeps terminal status |
| Request/cancel OVR | `toggle_escalated_ovr` (`urls.py:45`) | `ui_views.toggle_escalated_ovr` (`ui_views.py:1560`) | `can_manage_complaint` | Toggles status ↔ OVR_PENDING; emails PX admins (`ui_views.py:1591`) |
| Approve OVR | `approve_ovr_escalation` (`urls.py:46`) | `ui_views.approve_ovr_escalation` (`ui_views.py:1650`) | PX-Admin/Hosp-Admin; must be OVR_PENDING | → IN_PROGRESS + `is_escalated_ovr=True` |
| Reject OVR | `reject_ovr_escalation` (`urls.py:47`) | `ui_views.reject_ovr_escalation` (`ui_views.py:1680`) **+ duplicate at `ui_views.py:1762`** | PX-Admin/Hosp-Admin; must be OVR_PENDING | → IN_PROGRESS, not escalated |
| Escalate (to a person) | `complaint_escalate` (`urls.py:62`) | `ui_views.complaint_escalate` (`ui_views.py:2002`) | PX/Hosp-Admin/PX-Mgmt/PX-Employee; active status; **must be activated** (`ui_views.py:2015`) | Selects a `Staff` to email; sets `escalated_at`; **does NOT reassign** (`ui_views.py:2052-2054`) |
| Update patient-contact status | `update_patient_contact_status` (`urls.py:44`) | `ui_views.update_patient_contact_status` (`ui_views.py:1520`) | `can_manage_complaint` | Sets `patient_contact_status` (`not_contacted`/`contacted`/`contacted_no_response`) |
| Update satisfaction | `update_satisfaction` (`urls.py:43`) | `ui_views.update_satisfaction` (`ui_views.py:1418`) | `can_manage_complaint`; resolved/closed only; blocked if patient-locked or >5 days | Sets `satisfaction`; max 3 changes (`models.py:626-627`) |
| Update closure delay reason | `update_delay_reason_closure` (`urls.py:50`) | `ui_views.update_delay_reason_closure` (`ui_views.py:1864`) | `can_manage_complaint`; only if `is_overdue` or >72h; not on closed/resolved | Sets `delay_reason_closure` (72h rule) |
| Add note | `complaint_add_note` (`urls.py:61`) | `ui_views.complaint_add_note` (`ui_views.py:1913`) | active status only | Writes a "note" ComplaintUpdate |
| Change department | `complaint_change_department` (`urls.py:59`) | `ui_views.complaint_change_department` (`ui_views.py:1930`) | active status; PX/Hosp-Admin; same hospital | Changes `complaint.department` |
| Update location | `complaint_update_location` (`urls.py:60`) | `ui_views.complaint_update_location` (`ui_views.py:1955`) | active status | Updates `location_type`/`area`/`department`/`section`/`zone`/`floor` |
| Confirm taxonomy gate | `confirm_taxonomy` (`urls.py:64`) | `ui_views.confirm_taxonomy` (`ui_views.py:2157`) | `can_manage_complaint` | Sets `taxonomy_reviewed_at/by` to unblock Send-to-Department |
| Soft delete / restore / trash | `complaint_soft_delete`/`restore`/`trash_list` (`urls.py:94,95,93`) | `ui_views.py:7199,7213,7240` | `@login_required` | Soft-delete |
### 5.2 Assignment actions
| Action | URL name | View | Permission |
|---|---|---|---|
| Assign case manager (UI) | `complaint_assign` (`urls.py:41`) | `ui_views.complaint_assign` (`ui_views.py:862`) | assigner PX/Hosp-Admin/assignee; **target in groups PX Employee/PX Admin/PX Management** (`complaint_service.py:213-219`); reopens resolved/closed/cancelled when reassigned |
| Assign case manager (API) | `complaint-api:assign` | `ComplaintViewSet.assign` (`views.py:257`) | same |
| Assign staff (the subject) | `complaint-api:assign_staff` | `ComplaintViewSet.assign_staff` (`views.py:485`) | **PX Admin only**; active status; sets `complaint.staff`; auto-syncs `department`; clears `needs_staff_review` |
| Send to person OR dept (AJAX) | `complaint_send_to` (`urls.py:182`) | `ui_views.complaint_send_to` (`ui_views.py:1092`) | `can_manage_complaint`; **rejects `status=="open"`** | §14 |
| Confirm AI dept suggestion | `confirm_ai_department_suggestion` (`urls.py:172`) | `ui_views.confirm_ai_department_suggestion` (`ui_views.py:5500`) | `can_manage_complaint` | Creates a PRIMARY `ComplaintInvolvedDepartment` |
| Add/edit/remove involved department | `involved_department_add`/`edit`/`remove` (`urls.py:170,176,177`) | `ui_views.py:5562,5645,5701` | `can_manage_complaint` | |
| Add/edit/remove involved staff | `involved_staff_add`/`edit`/`remove` (`urls.py:186-188`) | `ui_views.py:6022,6101,6148` | `can_manage_complaint` | role ACCUSED/WITNESS/RESPONSIBLE/INVESTIGATOR/SUPPORT/PX_MANAGEMENT |
| Bulk assign/status/escalate | `complaint_bulk_*` (`urls.py:89-91`) | `ui_views.py:2498,2526,2555` | **⚠ `@require_http_methods` only (no `@login_required`)** — possible auth gap |
### 5.3 Department-response & investigation (token, no-login)
| Action | URL name | View |
|---|---|---|
| Champion/manager submits response | `involved_department_response` (`urls.py:178`) | `ui_views.involved_department_response` (`ui_views.py:5749`) |
| PX accepts/rejects response | `involved_department_review_response` (`urls.py:179`) | `ui_views.involved_department_review_response` (`ui_views.py:5853`) |
| Champion rejects routing (wrong dept) | `involved_department_reject_routing` (`urls.py:180`) | `ui_views.involved_department_reject_routing` (`ui_views.py:5955`) |
| Manager review (approve/reject) | `organizations:department_manager_review` | `apps/organizations/ui_views.py:4101` |
| Staff explanation form (token) | `complaint_explanation_form` (`urls.py:140`) | `views.complaint_explanation_form` (`views.py:3554`) |
| Champion starts investigation | `champion_start_investigation` (`urls.py:143`) | `views.champion_start_investigation` (`views.py:4009`) |
| Staff investigation response (token) | `staff_investigation_form` (`urls.py:145`) | `views.staff_investigation_form` (`views.py:4338`) |
| Champion reviews answers | `champion_review_answers` (`urls.py:146`) | `views.champion_review_answers` (`views.py:4489`) |
### 5.4 Other actions
Convert to appreciation (`ComplaintViewSet.convert_to_appreciation` `views.py:2076`); generate AI resolution (`views.py:1323`); create PX action from AI (`views.py:602`); adverse action CRUD (`adverse_action_*` `ui_views.py:6245-6622`); government ticket create/import/convert (`ui_views.py:6836,6922,6887`); PDF (`views.py:4951`); public tracking (`ui_views.public_complaint_track` `ui_views.py:4555`).
---
## 6. Decision Points
- **Activation gate** — complaint cannot be worked/sent/escalated until activated. Enforced at: `ComplaintService.activate` (`complaint_service.py:108`); `complaint_send_to` rejects `status=="open"` (`ui_views.py:1111`); `complaint_escalate` requires `activated_at` (`ui_views.py:2015`); `change_status` requires `activated_at` except →closed (`complaint_service.py:406`).
- **AI classification** — `analyze_complaint_with_ai` (`tasks.py:668`) sets severity, priority, taxonomy, emotion, `complaint_type` (complaint vs appreciation), staff matches.
- **Taxonomy review gate** — `taxonomy_reviewed_at` must be set via `confirm_taxonomy` before Send-to-Department is unblocked (`ui_views.py:2157`).
- **Manager approval tier** — `ComplaintInvolvedDepartment.manager_review_status` (`models.py:2687-2707`); set only in `apps/organizations/ui_views.py:4200/4255`.
- **PX acceptance tier** — `acceptance_status` (`models.py:2653-2662`); set in `involved_department_review_response` (`ui_views.py:5886`).
- **Resolution category** — `ResolutionCategory` (`models.py:54-61`): FULL_ACTION_TAKEN, PARTIAL_ACTION_TAKEN, NO_ACTION_NEEDED, CANNOT_RESOLVE, **PATIENT_WITHDRAWN**. Set at resolve (`complaint_service.py:429`).
- **Resolution outcome** — `ResolutionOutcome` (`models.py:64-69`): PATIENT / HOSPITAL / OTHER.
- **Delay reasons** — `DelayReasonChoices` (`models.py:46-51`): DEPARTMENT_NO_RESPONSE, ESCALATED, PATIENT_NOT_SATISFIED. Only settable if overdue or >72h (`ui_views.py:1877-1880`).
- **Duplicate detection** — `services/duplicate_detection.py` (weights: patient 0.30, date 0.20, description 0.35, category 0.15; threshold 0.75, "likely duplicate" ≥0.85; date window ±3 days). **⚠ Gap:** no call site in `apps/complaints` create views — advisory library only, not wired to block creation.
- **Patient confirmation** — satisfaction, set/locked via public tracker (`ui_views.py:4626-4638`) or PX `update_satisfaction`.
---
## 7. Assignment Flow
**On `Complaint`:**
- `assigned_to` (User, `models.py:487`) — the **case manager**. Set by `activate` (activator becomes assignee) or `assign`.
- `staff` (Staff, `models.py:270`) — the **subject of the complaint**. PX-Admin-only via `assign_staff` (`views.py:485`). Syncs `department` via `pre_save` signal (`signals.py:21-39`).
- `department` (`models.py:267`), `section` (`models.py:387`).
**`ComplaintInvolvedDepartment` (multi-department join, `models.py:2593`):** `department` FK; `role` (PRIMARY/SECONDARY/COORDINATION/INVESTIGATING, `models.py:2601-2605`); `is_primary` (only one per complaint — enforced in `save()` `models.py:2757-2764`); per-department `assigned_to` (`models.py:2629`); response, acceptance, manager-review, routing, reminder/delay fields; `unique_together=[complaint, department]` (`models.py:2744`).
**`ComplaintInvolvedStaff` (multi-staff join, `models.py:2792`):** `staff` FK; `role` (ACCUSED/WITNESS/RESPONSIBLE/INVESTIGATOR/SUPPORT/PX_MANAGEMENT); per-staff explanation tracking. Auto-created for the primary staff via `ComplaintService.ensure_involved_records` (`complaint_service.py:1020-1047`) unless `primary_staff_involved_removed`.
**Dual assignment** — `assigned_to` (case manager) and `staff` (subject) are distinct and independently assignable (`docs/COMPLAINT_DUAL_ASSIGNMENT_FEATURE.md`).
**Owner cascade** — `Complaint.get_owner()` (`models.py:711-732`): section(champion→supervisor→deputy_supervisor) → department(champion→deputy_manager→supervisor→deputy_supervisor→manager_2nd→manager_3rd).
**Reassignment / transfer** — `ComplaintService.assign` (`complaint_service.py:194`) reassigns the case manager; `change_department` (`complaint_service.py:546`) transfers; `complaint_escalate` notifies a person **without reassigning**. Final owner is `assigned_to` until resolved/closed.
---
## 8. Investigation Process
**Two parallel mechanisms:**
### 8.1 Legacy `ComplaintExplanation` direct-response
`ComplaintExplanation` (`models.py:2251`): one per (complaint, staff); token (`models.py:2273`), `is_used`, SLA tracking (`sla_due_at`, `is_overdue`), and `ExplanationAttachment` (`models.py:2359`). Token link emailed by `ComplaintService.send_to_department` (`complaint_service.py:796`) or `complaint_send_to` (`ui_views.py:1252`). Champion opens `complaint_explanation_form` (`views.py:3554`) and either submits a direct OTP-verified reply (`views.py:3620-3889`) or follows the "investigate" link.
### 8.2 `ChampionInvestigation` per-staff question flow (main investigation)
- `champion_start_investigation` (`views.py:4009`): champion selects involved staff, writes **per-staff** `InvestigationQuestion`s (`models.py:3793`); creates a `ChampionInvestigation` (`models.py:3740`, status `QUESTIONS_SENT`) + an `InvestigationResponse` per staff (`models.py:3824`) with its own token; emails/SMSes each staff a no-login link `/complaints/<id>/investigate/respond/<token>/`.
- `staff_investigation_form` (`views.py:4338`): staff answer; `InvestigationAnswer` (`models.py:3849`) + `InvestigationResponseAttachment` (`models.py:3902`).
- `champion_review_answers` (`views.py:4489`): champion reviews, writes a `final_reply`, sets assessment flags (`negligence_finding`, `policy_issue_finding`, `requires_improvement_project`), **OTP-verifies** (6-digit, 10-min expiry, `views.py:4613`), sets `InvestigationStatus.REPLY_SUBMITTED`, marks `ComplaintExplanation.is_used=True`, writes the `ComplaintInvolvedDepartment` response fields (**first-responder-wins within the same department**, `views.py:4743-4750`).
### 8.3 Other investigation models
- `ComplaintAdverseAction` (`models.py:3047`): corrective/adverse-action. `ActionType` (`models.py:3063`), `SeverityLevel` (`models.py:3077`), `VerificationStatus` (`models.py:3085`: reported→under_investigation→verified/unfounded/resolved).
- `ComplaintPRInteraction` (`models.py:2480`): PR/Patient-Relations contact log.
- `ComplaintMeeting` (`models.py:2543`): meeting record (management_intervention/pr_follow_up/department_review).
**When investigation starts:** implicitly when sent to a department. **Who investigates:** the department champion/manager (token-authenticated, no login). **Review tiers:** (1) champion composes → (2) department manager approves/rejects → (3) PX accepts/rejects.
---
## 9. Communication Flow
`ComplaintCommunication` (`models.py:3375`) with `ComplaintCommunicationType` (`models.py:3364`: PHONE_CALL/EMAIL/SMS/MEETING/LETTER/OTHER), `direction` (inbound/outbound). Exposed via DRF only.
`ComplaintUpdate` (`models.py:1177`) is the unified timeline; `update_type`: status_change/assignment/note/resolution/escalation/communication (`models.py:1187-1198`).
| Patient touchpoint | When | Where |
|---|---|---|
| **Acknowledgement/creation** | On create | `send_complaint_creation_sms_task` (`tasks.py:3331`) via signal (`signals.py:42`); `notify_admins_new_complaint` (`tasks.py:2253`) |
| **Need more info** | Manual | `update_patient_contact_status` (`ui_views.py:1520`) — records status, no auto-SMS |
| **Progress update** | Manual | notes/communications |
| **Resolution sent** | On resolve | `resolution_sent_at` set (`complaint_service.py:426`); SMS/email via `send_complaint_status_change_task` (`tasks.py:3418`, signal `signals.py:59`) |
| **Department responded** | Champion response | SMS+email to complainant (`ui_views.py:5816-5835`) |
| **Closure** | On close | resolution survey dispatched (`complaint_service.py:439` → `tasks.py:386`) |
| **Routing rejected** | Wrong dept | emails handler + PX admins (`complaint_service.py:1181-1221`) |
| **OVR requested/decided** | OVR flow | emails PX admins/managers (`ui_views.py:1591, 1704`) |
| **Champion notified** | Dept assigned | `notify_champion_on_dept_assignment_task` (`tasks.py:3509`) |
| **Satisfaction lock** | Public tracker | patient sets + locks `satisfaction` for 5 days (`ui_views.py:4626`; `models.py:894-908`) |
Delivery via `apps.notifications.services.NotificationService`, often offloaded to Celery.
---
## 10. Escalation Flow
### 10.1 SLA configuration
- `ComplaintSLAConfig` (`models.py:1224`): per (hospital, source, severity, priority) `sla_hours`; reminder timings. `unique_together=[hospital, source, severity, priority]` (`models.py:1295`).
- `ComplaintThreshold` (`models.py:1309`): threshold breaches (resolution_survey_score, response_time, resolution_time) with `action_type` (create_px_action/send_notification/escalate). `check_threshold()` at `models.py:1367`.
- Defaults (`config/settings/base.py:355-368`): low=72h, medium=48h, high=24h, critical=12h.
- `calculate_sla_due_date` (`models.py:784-830`) precedence: source-based config → severity/priority config → severity-only config → settings defaults.
### 10.2 Automatic tasks (`tasks.py`)
- `check_overdue_complaints` (`tasks.py:359`, every 15 min) → `Complaint.check_overdue()` (`models.py:867-878`). **⚠ Gap:** only checks OPEN, IN_PROGRESS, RESOLVED — not partially_resolved/pending_external/ovr_pending.
- `send_sla_reminders` (`tasks.py:1781`, hourly) — first + second reminders; emails assigned user or dept manager; uses on-call schedule.
- `send_explanation_reminders` (`tasks.py:1616`) + `check_overdue_explanation_requests` (`tasks.py:1593`) — for `ComplaintExplanation` SLA.
- `check_resolution_survey_threshold` (`tasks.py:478`) — auto-creates a `PXAction` if a closed complaint's survey breaches `ComplaintThreshold`.
### 10.3 Manual escalation
- `complaint_escalate` (`ui_views.py:2002`): pick a `Staff`; sets `escalated_at`; emails them; **does not reassign**.
- **OVR escalation** (`toggle_escalated_ovr` `ui_views.py:1560`): two-step approval flow (request → admin approve/reject). When approved, `is_escalated_ovr=True`.
### 10.4 Escalation hierarchy
`ComplaintService.get_escalation_target` (`complaint_service.py:36-76`): for a staff explanation → `staff.report_to` → `staff.department.manager` → `complaint.department.manager` → hospital admins & PX staff.
---
## 11. Resolution Process
- **Who can mark resolved:** any PX/Hosp-Admin/PX-Mgmt/PX-Employee via `change_status` (`complaint_service.py:398`).
- **Approval required?** No separate approval to *resolve* (PX Admin can force). But the **department response** must pass manager-review + PX-acceptance tiers before a complaint is typically resolved (§14).
- **Patient confirmation required?** Not to resolve; satisfaction is captured afterwards (PX sets it or patient submits/locks on the tracker).
- **Fields set on resolve** (`complaint_service.py:420-434`): `resolved_at/by`; `resolution` + `resolution_sent_at`; `resolution_category`; `resolution_outcome` + `resolution_outcome_other`. Special: if `was_pending_external`, `resolved_at` is back-dated to `pending_external_set_at` (`complaint_service.py:421-422`).
- **Patient-contact status** is tracked separately and is **not** a hard precondition.
---
## 12. Closure Process
- **Who closes:** same as resolve, via `change_status` → CLOSED.
- **What happens on close:** `closed_at/by`; dispatches `send_complaint_resolution_survey` (`tasks.py:386` → creates `SurveyInstance`).
- **72-hour closure rule:** `DelayReasonChoices` docstring "Delay reason for 72h closure" (`models.py:46-47`). `delay_reason_closure` only settable when `is_overdue` or >72h (`ui_views.py:1877-1880`); not on closed/resolved. This explains *why* a complaint wasn't closed within the target window.
- **Reopen conditions:** `complaint_reopen` (`ui_views.py:1788`) only from resolved/closed (view check `ui_views.py:1804`). `ComplaintService.reopen` (`complaint_service.py:304`) requires resolved/closed/cancelled, and **creates a brand-new OPEN complaint** linked via `reopened_from`. The original **keeps its terminal status** (its status is not changed by reopen).
- **Permanently completed:** once closed, terminal unless explicitly reopened. Patient satisfaction window expires after 5 days (`models.py:894-908`).
---
## 13. Exception Flows
- **Duplicate detection** — `ComplaintDuplicateDetector` (threshold 0.75, likely ≥0.85). **⚠ Gap:** no call site in create views — advisory only.
- **Withdrawn by patient** — `ResolutionCategory.PATIENT_WITHDRAWN` (`models.py:61`); chosen at resolve time.
- **Invalid submission / wrong department** — `involved_department_reject_routing` (`ui_views.py:5955`) + token equivalent (`views.py:3892`). `reject_department_routing` (`complaint_service.py:1093`) sets `routing_status=REJECTED`, clears `complaint.department`/`section` if it was primary, emails handler + PX admins.
- **Missing info / no patient response** — `PatientContactStatus.CONTACTED_NO_RESPONSE` (`models.py:43`) + `DelayReasonChoices.PATIENT_NOT_SATISFIED`/`DEPARTMENT_NO_RESPONSE`.
- **Complaint → Appreciation conversion** — `ComplaintViewSet.convert_to_appreciation` (`views.py:2076`); only for `complaint_type=="appreciation"`; creates an `Appreciation`, stores `metadata.appreciation_id`, optionally closes the complaint (`docs/COMPLAINT_TO_APPRECIATION_CONVERSION.md`).
- **Merged cases** — **⚠ no "merge" action exists** in `ui_views.py`/`urls.py`. Closest is duplicate-detection (advisory) and reopen-as-new.
- **Reopened cases** — creates a new complaint, doesn't mutate the original.
- **Government ticket conversion** — `convert_to_complaint` (`ui_views.py:6887`) prefills `complaint_create`; sets references and external source type.
---
## 14. Department-Response Sub-Flow
A **two-tier review** with an embedded investigation loop. State lives on `ComplaintInvolvedDepartment` (`models.py:2593`). Shared rules in `docs/workflows.md:6-18`.
### 14.1 Activation gate
A complaint cannot be sent to a department until activated. `complaint_send_to` rejects `status == "open"` (`ui_views.py:1111`). The taxonomy gate (`taxonomy_reviewed_at`, `confirm_taxonomy` `ui_views.py:2157`) must also be passed.
### 14.2 Sending to a department
- Endpoint `complaint_send_to` (`ui_views.py:1092`), URL `complaints:complaint_send_to`.
- **Primary department** (`complaint.department`): sets `complaint.sent_to_department=True`, `sent_to_department_at`, `forwarded_to_dept_at` (`ui_views.py:1197-1201`).
- **Other departments**: `get_or_create`s a `ComplaintInvolvedDepartment` with `sent=True`, `sent_at`, `forwarded_at` (`ui_views.py:1203-1213`); resets prior rejection (`ui_views.py:1219-1229`).
- Resolves recipients via `get_champion_and_manager` (`ui_views.py:1188`); creates a `ComplaintExplanation` token per recipient (`ui_views.py:1253-1265`); offloads email/SMS to `send_department_notification_task` (`ui_views.py:1342-1359`).
- A parallel implementation `ComplaintService.send_to_department` (`complaint_service.py:737`) exists (champion-only, contact-person picker). **⚠ Gap:** two overlapping "send to department" implementations.
### 14.3 Who receives it
The department **champion** (and manager) — resolved by `get_champion_and_manager` (`ui_views.py:1188`). Signal `notify_champion_on_department_assignment` (`signals.py:104`) dispatches `notify_champion_on_dept_assignment_task` (`tasks.py:3509`) when a sent dept row is created.
### 14.4 Champion's response submission
Two paths to populate `response_notes`/`response_notes_en`/`response_notes_ar`, `response_submitted=True`, `response_submitted_at` (`models.py:2641-2650`):
1. **Logged-in** — `involved_department_response` (`ui_views.py:5749`). Permission: champion OR manager OR `involved_dept.assigned_to` OR `can_manage_complaint`. Sets fields + `acceptance_status="acceptable"` + `accepted_at` immediately, notifies complainant. **⚠ Note: this path self-accepts, skipping the manager-review tier.**
2. **Token (no-login)** — direct reply (`views.py:3620-3889`) or `champion_review_answers` after investigation (`views.py:4680-4778`). **OTP-verified**; apply **first-responder-wins within the same department** (`views.py:3803-3808, 4743-4750`); email the complaint assignee.
### 14.5 Manager review tier (tier 1)
- View: `apps/organizations/ui_views.py:4101 department_manager_review` (in the **organizations** app, not complaints — easy to miss).
- Permission: PX/Hosp-Admin OR dept manager of that department.
- Preconditions: `involved_dept.response_submitted` True and not already approved.
- Shows configurable `ManagerReviewQuestion`s (`models.py:3623`); creates `DepartmentManagerReview` (`models.py:3671`) + `ManagerReviewAnswer`s (`models.py:3707`).
- **Approve** (`organizations/ui_views.py:4199`): `manager_review_status="approved"`; emails assignee.
- **Reject** (`organizations/ui_views.py:4254`): `manager_review_status="rejected"`; **clears the response** (`response_submitted=False`, `response_submitted_at=None`, `response_notes*=""`); emails champion+assignee → **reject loop back to champion**.
### 14.6 PX acceptance tier (tier 2)
- View: `involved_department_review_response` (`ui_views.py:5853`).
- Permission: PX/Hosp-Admin/PX-Mgmt/PX-Employee.
- Precondition: `manager_review_status == "approved"` (`ui_views.py:5875`) — **manager tier must run first**.
- **Accept** (`acceptance_status="acceptable"`): sets `accepted_by/at/notes`.
- **Reject** (`acceptance_status="not_acceptable"`): **clears the response** (`response_submitted=False`, `response_submitted_at=None`, `response_notes*=""`) (`ui_views.py:5891-5898`); emails champion+manager → **reject loop back to champion**.
### 14.7 Reject loops summary
Both manager-reject and PX-reject clear `response_submitted`, `response_submitted_at`, and all `response_notes*` fields, returning the involved department to the champion for a fresh response. **⚠ Gap:** PX-reject leaves `manager_review_status="approved"` (doesn't reset it), so re-approval semantics are unclear after a PX-reject.
### 14.8 Investigation sub-flow (token questions to involved staff)
The champion, instead of a direct reply, follows "investigate" → `champion_start_investigation` (`views.py:4009`): selects `ComplaintInvolvedStaff`, writes per-staff questions, each staff gets a no-login token emailed/SMSed. Staff answer via `staff_investigation_form` (`views.py:4338`). Champion reviews via `champion_review_answers` (`views.py:4489`), writes a `final_reply`, OTP-verifies — that final reply becomes the `ComplaintInvolvedDepartment` response, feeding back into the manager→PX review tiers.
### 14.9 Cross-cutting helper properties
- `Complaint.sent_to_any_department` (`models.py:1109`).
- `Complaint.all_departments_responded` (`models.py:1113`).
- `ComplaintExplanation.linked_involved_department` (`models.py:2343`).
- `ComplaintInvolvedDepartment.can_reject_routing` (`models.py:2780`): only if not responded, routing_status SENT, complaint not closed/cancelled.
- `ComplaintInvolvedDepartment.sla_remaining` (`models.py:2766`): hours left (default 48).
---
## 15. End-to-End Example
```
Patient submits via public form
↓ (ui_views.py:4369) → status=OPEN, ref CMP-202607-0001, due_at computed,
AI analysis + admin notify dispatched
Complaint auto-classified by AI (severity high, department X)
↓ (tasks.py:668)
PX staff activates + confirms taxonomy
↓ (ui_views.py:2141, 2157) → status=IN_PROGRESS, activated_at set,
assigned_to = activator, taxonomy_reviewed_at set
PX sends to Department X (primary)
↓ (ui_views.py:1092) → ComplaintInvolvedDepartment(primary, sent=True),
ComplaintExplanation token emailed to champion
[DECISION: champion investigates vs direct reply]
Champion starts investigation (token questions to involved staff)
↓ (views.py:4009) → InvestigationResponse tokens emailed to staff
Staff answer via no-login token link
↓ (views.py:4338) → InvestigationAnswer stored
Champion reviews answers, writes final_reply, OTP-verifies
↓ (views.py:4489) → ComplaintInvolvedDepartment.response_submitted=True,
first-responder-wins; assignee emailed
[DECISION POINT: Manager review tier]
Department manager approves
↓ (organizations/ui_views.py:4199) → manager_review_status="approved",
assignee emailed
[DECISION POINT: PX acceptance tier]
PX accepts the response
↓ (ui_views.py:5853) → acceptance_status="acceptable"
[DECISION POINT: resolution category]
PX resolves (category=FULL_ACTION_TAKEN, outcome=HOSPITAL)
↓ (ui_views.py:1376) → status=RESOLVED, resolved_at/by, resolution_sent_at,
patient notified (SMS/email)
↓ patient satisfaction window opens (5 days)
PX closes
↓ (ui_views.py:1376) → status=CLOSED, closed_at/by,
resolution-satisfaction survey dispatched
[PERMANENT unless reopened → creates NEW complaint]
```
---
## Appendix — Flagged gaps vs `docs/workflows.md`
1. No model-level transition enforcement (`clean()`/`CheckConstraint` absent); only `ComplaintService.VALID_STATUS_TRANSITIONS`, bypassed by PX Admin.
2. Manager review lives in `apps/organizations/ui_views.py:4101`, not `apps/complaints/`.
3. Duplicate `reject_ovr_escalation` view definitions (`ui_views.py:1680` and `1762`) registered to one URL name.
4. Public form view stricter than `PublicComplaintForm` (department required).
5. `check_overdue_complaints` ignores partially_resolved/pending_external/ovr_pending.
6. Public submissions hardcoded `complaint_source_type=INTERNAL` despite an EXTERNAL enum existing.
7. "Merge cases" action does not exist.
8. PX-reject leaves `manager_review_status="approved"`.
9. Bulk actions lack `@login_required`.
10. "OVR" acronym never expanded.
11. Duplicate-detection library not wired into create views.

44
docs/workflows/index.md Normal file
View File

@ -0,0 +1,44 @@
# 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`).

359
docs/workflows/inquiries.md Normal file
View File

@ -0,0 +1,359 @@
# Inquiries — Workflow & Lifecycle
> Source of truth: `apps/complaints/` (the `Inquiry` model lives **inside** the complaints app, not a separate one). URL namespace `inquiries`, mounted at `/inquiries/`.
> This document describes the **current implementation only**. Every claim is cited as `file:line`.
> **⚠ Read first — `docs/workflows.md` is partly out of date for Inquiries.** The most important change: the `dept_response_acceptance_status` field that backed the "PX accepts/rejects" loop was **removed** (migration `0039`), so that loop no longer exists in code. The model also has **no `clean()`/`CheckConstraint`** enforcing statuses.
---
## 1. Purpose
`Inquiry` is "for general questions/requests. Similar to complaints but for non-complaint inquiries." (`apps/complaints/models.py:1528-1533`).
Architectural differences vs. Complaint (intended, per `docs/workflows.md:31-39`):
- **Single department, flat fields** — Inquiry carries department-response data as *flat columns* on the row (`transferred_to_department`, `outgoing_department`, `department_response_en/ar`, `models.py:1824-1854`). Complaint uses a multi-department join model.
- **One-level review** — champion responds → PX accepts/rejects → resolve. **No department-manager tier** (`docs/workflows.md:34-35`). *(See §14 — the accept/reject field was removed.)*
- **Resolve requires a PX `response`** — the PX team must write `inquiry.response` before resolving (`ui_views.py:3356-3358`).
- **No investigation sub-flow** like Complaint's `InvestigationResponse`. `InquiryExplanation` is a simple token-response mechanism (§8).
- **No signals** — `apps/complaints/signals.py` wires receivers only for `Complaint`/`ComplaintUpdate`/`ComplaintInvolvedDepartment`; **zero** `Inquiry` signal receivers.
Shared vocabulary with Complaints: `open → in_progress → resolved → closed` (`models.py:1695-1705`).
---
## 2. How a Case Starts
### 2.1 Who can create
- **DRF/API:** `CanCreateInquiry` (`apps/complaints/permissions.py:39-67`) — PX Admins, Hospital Admins, Source Users with `can_create_inquiries`, everyone else (incl. patients). `InquiryViewSet` requires `IsAuthenticated` (`views.py:2895`).
- **UI form:** `@login_required` (`ui_views.py:2978`).
### 2.2 Creation channels (4 entry points)
| Channel | View | URL name | Auth |
|---|---|---|---|
| Authenticated UI form | `ui_views.inquiry_create` (`ui_views.py:2980`) | `inquiries:inquiry_create` (`urls_inquiries.py:11`) | `@login_required` |
| Public portal (complaints app) | `ui_views.public_inquiry_submit` (`ui_views.py:4707`) | `inquiries:public_inquiry_submit` (`urls_inquiries.py:27`) | **None** |
| Public portal (core app) | `apps.core.views.public_inquiry_submit` (`apps/core/views.py:170`) | `core:public_inquiry_submit` (`apps/core/urls.py:38`) | **None** |
| DRF API | `InquiryViewSet.perform_create` (`views.py:2909`) | — | `IsAuthenticated` + `CanCreateInquiry` |
**Incoming vs. Outgoing** — controlled by `is_outgoing` (`models.py:1803-1805`): `False` (default) = **incoming** (from a patient/source into the hospital); `True` = **outgoing** (hospital contacts an external/other department; paired with `outgoing_department`, `models.py:1834`). Set via hidden form field (`forms.py:676-681`), read in create view (`ui_views.py:3001-3011`). Public submissions are always incoming. Reports split on this flag (`inquiry_export_incoming`/`outgoing`, `ui_views.py:4196,4216`) — corresponding to "Reports - Incoming/Outgoing Inquiries.xlsx".
### 2.3 Information required before submission
**`InquiryForm` (`forms.py:564`)** — required: `hospital`, `location_type`, `category`, `subject`, `message`. Optional: `patient`, `area`, `department`, `contact_name/phone/email`, `section`, `priority`, `source`, `is_outgoing`, `outgoing_department`.
**Public form (`public_inquiry_submit`)** — hand-rolled validation (`ui_views.py:4725-4735`) requires: `name`, `phone`, `hospital`, `subject`, `message`.
> **⚠ Gap:** `PublicInquiryForm` (`forms.py:857`) exists and declares `name/phone/hospital/location_type` required, but `public_inquiry_submit` validates manually and does not use it — may be vestigial.
### 2.4 What happens immediately after submission
`Inquiry.save()` (`models.py:1980-2027`):
1. Loads previous status into `_status_was` (`models.py:1982`).
2. Stamps `resolved_at`/`closed_at` only on transitions into those statuses, not on creation (`models.py:1993-2000`).
3. **Generates reference number** if missing: `generate_reference("INQ", hospital)` → `INQ-YYYYMM-NNNN` (`models.py:2002-2005`).
4. **Sets SLA deadline** `due_at` = now + `sla_hours` from `InquirySLAConfig` (`models.py:2007-2012`).
5. **Auto-derives `timeline_sla`** bucket (24/48/72/>72h) from `due_at - created_at` (`models.py:2014-2025`).
6. Default `status = OPEN` (`models.py:1703`).
Background tasks after creation:
- `analyze_inquiry_with_ai.delay(...)` — AI priority/department/taxonomy/emotion (`tasks.py:2991`).
- `notify_staff_new_item.delay("inquiry", ...)` — admin notification email (`tasks.py:2490`).
- `link_inquiry_patient.delay(...)` — async patient lookup (`tasks.py:3314`).
- `InquiryUpdate` "Inquiry created." timeline entry (`ui_views.py:3046`).
> **Activation gate:** a new inquiry is `open` and **cannot be sent to a department** until activated to `in_progress`. Send endpoints reject `status == "open"` (`ui_views.py:3594, 3841`).
> **⚠ Gap — no creation acknowledgement to inquirer:** unlike Complaint (which has a `send_complaint_creation_sms` post_save signal), Inquiry has **no creation-acknowledgement signal**. The inquirer is not auto-notified on submission; only staff are notified via `notify_staff_new_item`.
---
## 3. Complete Lifecycle
### 3.1 Status "enum"
There is **no `InquiryStatus` enum class and no `VALID_INQUIRY_TRANSITIONS` map.** Status is a plain `CharField` with inline choices (`models.py:1695-1705`): `open`, `in_progress`, `resolved`, `closed`.
### 3.2 Transition enforcement — effectively NONE
- **No `clean()` method** on `Inquiry`.
- **No `constraints`/`CheckConstraint`** in `Meta` or migrations (`models.py:1971-1978`) — only indexes.
> **⚠ Gap vs `docs/workflows.md:11-13`:** that doc claims invalid statuses are "rejected at the model (clean()) and DB (CheckConstraint) level." **This is true for Complaint, but NOT for Inquiry.** `inquiry_change_status` accepts *any* string the user POSTs and saves it (the only guard is resolved-requires-response). The `choices` are not DB-enforced.
### 3.3 Where transitions actually happen
| From → To | Mechanism | File:line |
|---|---|---|
| `open → in_progress` | `inquiry_activate` (sets `status` + `activated_at` if open) | `ui_views.py:3207` |
| `open → in_progress` | `inquiry_update_contact_stage` stage `under_process` | `ui_views.py:4274` |
| resolved/closed → in_progress | `inquiry_assign` auto-reopens on reassignment | `ui_views.py:3282` |
| resolved/closed → in_progress | `inquiry_reopen` | `ui_views.py:3409` |
| `* → resolved` | `inquiry_respond` (sets `response` + status) — requires non-empty response | `ui_views.py:3486` |
| `* → resolved` | API `InquiryViewSet.respond` — requires response | `views.py:2963` |
| `* → resolved` | `inquiry_change_status` — **blocks if no `response`** | `ui_views.py:3356` |
| `* → closed` | `inquiry_change_status` with `status="closed"` (no dedicated close view) | `ui_views.py:3330` |
| `* → anything` | `inquiry_change_status` accepts arbitrary `new_status` | `ui_views.py:3345` |
`save()` stamps `resolved_at`/`resolved_by`/`closed_at`/`closed_by` on entry (`models.py:1993-2000`) using `_acting_user` (set by views).
---
## 4. Status Definitions
| Status | Purpose | When entered | Who moves forward | Next |
|---|---|---|---|---|
| **`open`** | Received; not yet owned/worked | On creation (default) | PX/Admin/Manager/Employee via `inquiry_activate` | `in_progress` |
| **`in_progress`** | Being actively worked | Activation, reassignment of resolved/closed, reopen, `under_process` stage | Assignee/PX/Champion | `resolved`, `closed` (or reopen) |
| **`resolved`** | A PX response has been written and sent | `inquiry_respond` / API `respond` / `change_status` (gated on `response`) | PX/Admin/Hosp-Admin/Manager/Employee/Assignee/Champion | `closed`; reopen → `in_progress` |
| **`closed`** | Permanently completed | `inquiry_change_status` to `closed` | PX/Admin/Hosp-Admin/Manager/Employee | reopen → `in_progress` (rare) |
`is_active_status` returns True for `open`/`in_progress` (`models.py:2132`).
> **⚠ Status-choice anomaly:** the detail view exposes `status_choices` that include `"contacted"` and `"contacted_no_response"` (`ui_views.py:2758-2765`). These are **NOT valid Inquiry statuses** (they're `contact_status` values mixed in). If selected via change-status, they persist as out-of-choices values — treat as a UI bug.
---
## 5. Workflow Actions
All UI inquiry URLs are in `urls_inquiries.py` (namespace `inquiries`); views in `ui_views.py`; API on `InquiryViewSet` (`views.py:2890`).
| Action | URL name | View (file:line) | Permission | Effect |
|---|---|---|---|---|
| Activate | `inquiry_activate` (`<pk>/activate/`) | `ui_views.py:3179` | PX/Hosp-Admin/PX-Mgmt/PX-Employee | Assigns to self; open→in_progress + `activated_at` |
| Assign | `inquiry_assign` (`<pk>/assign/`) | `ui_views.py:3252` | PX/Hosp-Admin/Dept-Manager-of-this-dept | Assign to user; **auto-reopens resolved/closed → in_progress** |
| Change status | `inquiry_change_status` (`<pk>/change-status/`) | `ui_views.py:3330` | PX/Hosp-Admin/PX-Mgmt/PX-Employee | Arbitrary status; **resolved blocked without `response`**; only way to set `closed` |
| Reopen | `inquiry_reopen` (`<pk>/reopen/`) | `ui_views.py:3388` | PX/Hosp-Admin/Dept-Manager | Only from resolved/closed; → in_progress |
| Add note | `inquiry_add_note` (`<pk>/add-note/`) | `ui_views.py:3439` | `@login_required` (no role gate) | Timeline note |
| **Respond (PX)** | `inquiry_respond` (`<pk>/respond/`) | `ui_views.py:3459` | PX/Hosp-Admin/Assignee/Champion-of-(dept/outgoing_dept) | Writes `inquiry.response`, sets `responded_at/_by`, `response_sent_at`, → `resolved`; sends SMS+email to inquirer |
| **Send to department** | `inquiry_transfer_to_department` (`<pk>/transfer-to-department/`) | `ui_views.py:3578` | PX/Hosp-Admin/Dept-Manager/PX-Mgmt/PX-Employee; **rejects open** | Full send + token (§14) |
| **Send-to (AJAX)** | `inquiry_send_to` (`<pk>/send-to/`) | `ui_views.py:3818` | PX/Hosp-Admin/Dept-Manager/PX-Mgmt/PX-Employee; **rejects open** | Unified send to person OR department (§14) |
| **Dept response (logged-in)** | `inquiry_department_response` (`<pk>/department-response/`) | `ui_views.py:4003` | PX/Hosp-Admin/Champion-of-(dept/outgoing_dept) | Champion submits `department_response_en/ar` + AI summary |
| Send dept-response reminder | `inquiry_send_dept_response_reminder` | `ui_views.py:4115` | PX/Hosp-Admin/PX-Mgmt/PX-Employee | Manual reminder email to champion |
| Send to staff (token explanation) | `inquiry_send_to_staff` (`<pk>/send-to-staff/`) | `ui_views.py:2901` | PX/Hosp-Admin/PX-Mgmt/PX-Employee | Token `InquiryExplanation` request to a staff member (§8) |
| Escalate | `inquiry_escalate` (`<pk>/escalate/`) | `ui_views.py:3728` | PX/Hosp-Admin/PX-Mgmt/PX-Employee; blocks closed/cancelled | Stamps `escalated_at`, emails target |
| Update contact stage | `inquiry_update_contact_stage` (`<pk>/update-contact/`) | `ui_views.py:4227` | PX/Hosp-Admin/Assignee | Updates 3-stage contact timeline + `timeline_sla` |
| Edit | `inquiry_edit` (`<pk>/edit/`) | `ui_views.py:3102` | PX/Hosp-Admin/PX-Mgmt/PX-Employee; blocks `closed` | Edit fields |
| Export incoming/outgoing | `inquiry_export_*` | `ui_views.py:4186,4206` | `@login_required` (RBAC inside) | Excel reports by `is_outgoing` |
| Public submit | `public_inquiry_submit` | `ui_views.py:4707` | **None** | Public creation |
| Public track | `public_inquiry_track` | `ui_views.py:4843` | None | Public status lookup by reference |
| **Token response (dept)** | `inquiry_respond_with_token` (`<pk>/respond/<token>/`) | `views.py:5141` | **None (token)** | Champion submits dept response via token (§14) |
| Token explanation (staff) | `inquiry_explanation_form` (`<id>/explain/<token>/`) | `views.py:5077` | **None (token)** | Staff submits `InquiryExplanation` |
| Restore | `inquiry_restore` | `ui_views.py:7227` | PX/Hosp-Admin/PX-Mgmt/PX-Employee | Restores soft-deleted |
**API (`InquiryViewSet`):** `respond` (`views.py:2962`), `generate_ai_response` (`views.py:2980` — bilingual AI reply draft), `reanalyze_ai` (`views.py:3103`), plus default ModelViewSet CRUD.
---
## 6. Decision Points
- **Activation gate** — every send endpoint rejects `status == "open"` (`ui_views.py:3594, 3841`). Matches `docs/workflows.md:7-9`.
- **Resolve gate** — `response` must be non-empty (`ui_views.py:3356, 3482`; API `views.py:2968`).
- **Reopen gate** — only from resolved/closed (`ui_views.py:3402`); reassignment also reopens (`ui_views.py:3282`).
- **Escalate gate** — blocked if closed/cancelled (`ui_views.py:3744`).
- **Department must have champion/manager** to be a transfer target (`ui_views.py:3610, 3916`).
- **Need-more-info** — no dedicated "request info" action; analogues are token `InquiryExplanation`, `inquiry_add_note`, and the 3-stage contact tracking (`contacted_no_response`).
- **PX acceptance of dept response** — **⚠ NO LONGER EXISTS** (`docs/workflows.md:35` is stale). See §14.
- **Patient confirmation** — does not exist. Patient can only *view* status via public track. Reopen is staff-only.
---
## 7. Assignment Flow
- **Initial owner** — none. `assigned_to`/`assigned_at` null on creation. `created_by` stamped (`models.py:1728`).
- **Self-activation** — `inquiry_activate` sets `assigned_to = current_user`, `assigned_at`, (if open) `status=in_progress` + `activated_at` (`ui_views.py:3202`).
- **Directed assignment** — `inquiry_assign` (`ui_views.py:3268`); emails assignee; notifies department.
- **Reassignment** — same path; records old assignee; reopens if needed (`ui_views.py:3275`).
- **Transfer / outgoing fields** — two parallel concepts: `transferred_to_department` (`models.py:1824`) and `outgoing_department` (`models.py:1834`), both set together by transfer/send-to (`ui_views.py:3638, 3923`). `transferred_at`/`transferred_by`/`transfer_count` track the event.
- **Owner cascade** — `Inquiry.get_owner()` (`models.py:2037`): section(champion→supervisor→deputy_supervisor) → department(champion→deputy_manager→supervisor→deputy_supervisor→manager_2nd→manager_3rd).
- **Escalation** — `inquiry_escalate`: does NOT reassign; stamps `escalated_at` + emails target.
- **Final owner** — whoever performs `inquiry_respond` (sets `responded_by`) / `change_status` to resolved/closed.
---
## 8. Investigation Process
`InquiryExplanation` (`models.py:2380`): "Staff/recipient response to an inquiry via token-based link. Mirrors ComplaintExplanation pattern." Fields: `inquiry`, `staff`, `explanation`, `token` (unique), `is_used`, `submitted_via`, SLA fields. `InquiryExplanationAttachment` (`models.py:2460`).
**No investigation sub-flow** (no Q&A loop). The mechanism is:
1. PX/Admin triggers `inquiry_send_to_staff` (`ui_views.py:2901`): creates an `InquiryExplanation` with a fresh token; emails the staff a link `/inquiries/<id>/explain/<token>/`.
2. Staff opens `inquiry_explanation_form` (`views.py:5077`), submits text + attachments; `is_used` flipped, `responded_at` stamped.
3. The explanation is stored but **not** automatically promoted into `department_response_en` — it's an *advisory* collection mechanism, distinct from the primary department-response path (§14).
> **⚠ Runtime bug:** `inquiry_send_to_staff` calls `InquirySLAConfig.get_active_config()` (`ui_views.py:2938`) and reads `sla_config.dept_response_sla_hours` (`ui_views.py:2939`). **Neither exists** — `InquirySLAConfig` has no `get_active_config` classmethod (`models.py:1432`) and the field is `dept_response_hours`, not `dept_response_sla_hours`. This code path raises `AttributeError`.
---
## 9. Communication Flow
| Event | Where |
|---|---|
| Acknowledgement/receipt | **⚠ none automatic** (no creation signal); only staff notified via `notify_staff_new_item` |
| Progress update | timeline notes (`inquiry_add_note`); contact stages (`inquiry_update_contact_stage`) |
| Need-more-info | token explanation request to staff (`inquiry_send_to_staff`); inquirer "no response" = `contacted_no_response` stage |
| Department response | `inquiry_department_response` notifies **inquirer** SMS+email (`ui_views.py:4075`); token path `inquiry_respond_with_token` (`views.py:5195`) |
| Response sent/closure | `inquiry_respond` sends SMS+email to inquirer (`ui_views.py:3512`); in-app "resolved" notice to admins. No separate closure notification. |
| Public tracking | `public_inquiry_track` (`ui_views.py:4843`) — friendly labels/progress + `department_response_en/ar` |
Notification helpers (`apps/notifications/settings_service.py`): `send_inquiry_department_assigned` (`:250`), `send_inquiry_assigned` (`:463`), `send_inquiry_resolved` (`:488`), `send_inquiry_reopened` (`:514`).
---
## 10. Escalation Flow
**Manual** — `inquiry_escalate` (`ui_views.py:3728`): PX/Hosp-Admin/PX-Mgmt/PX-Employee; blocked if closed/cancelled; requires a valid active `Staff`; stamps `escalated_at`; does NOT change status/assignee; emails target (Hospital Admin/Dept Manager/role-holders, computed in `inquiry_detail` `ui_views.py:2775`).
**Automatic (SLA breach)** — `InquirySLAConfig` (`models.py:1432`): `sla_hours`, reminder timings, dept-response SLA fields. Celery beat:
- `check-overdue-inquiries` → `check_overdue_inquiries` (`tasks.py:2886`) every 15 min: sets `is_overdue`/`breached_at`.
- `send-inquiry-sla-reminders` → `send_inquiry_sla_reminders` (`tasks.py:2915`) every 15 min: emails `assigned_to` first + second reminders.
**⚠ Department-response auto-escalation is DISABLED in code:** `check_overdue_inquiry_dept_responses` (`tasks.py:3126`) flags `dept_response_is_overdue` but the auto-escalate branch unconditionally logs "Auto-escalation skipped ... (disabled)" and `continue`s (`tasks.py:3178`), even though `dept_response_auto_escalate_enabled` defaults True (`models.py:1487`). So escalation is **manual only**.
---
## 11. Resolution Process
**VERIFIED** — `docs/workflows.md:36-38` is correct: **resolve requires a PX `response`.**
- `inquiry_change_status`: `if new_status == "resolved" and not inquiry.response: reject` (`ui_views.py:3356`).
- `inquiry_respond`: rejects empty (`ui_views.py:3482`); writes `inquiry.response` + sets `resolved` (`ui_views.py:3486`); stamps `response_sent_at` + notifies inquirer (`ui_views.py:3512`).
- API `respond`: same (`views.py:2968`).
**Who can mark resolved:** via `inquiry_respond` — PX/Hosp-Admin/assignee/Champion of `department` or `outgoing_department` (`ui_views.py:3466`); via `change_status` — PX/Hosp-Admin/PX-Mgmt/PX-Employee.
**Approval required?** No. **Patient confirmation?** Not required/captured. `save()` stamps `resolved_at`/`resolved_by` from `_acting_user`.
> **⚠ Gap:** `inquiry_respond` clears `response_en`/`response_ar` and writes only the aggregate `response` field (`ui_views.py:3487`). The bilingual columns exist but this path doesn't populate them.
---
## 12. Closure Process
- **No dedicated close view.** Closure is via `inquiry_change_status` with `status="closed"` (`ui_views.py:3330`).
- Permission: PX/Hosp-Admin/PX-Mgmt/PX-Employee.
- `save()` stamps `closed_at`/`closed_by` on entry (`models.py:1997`).
- Closed inquiries **cannot be edited** (`inquiry_edit` guard, `ui_views.py:3116`).
- **Reopen** — `inquiry_reopen` from resolved/closed → in_progress (`ui_views.py:3388`); `inquiry_assign` auto-reopens resolved/closed on reassignment (`ui_views.py:3282`).
- **Permanently completed?** No permanent lock; a closed inquiry can always be reopened. Soft-deletion is separate, restorable.
---
## 13. Exception Flows
- **Duplicate** — no duplicate-detection.
- **Withdrawn/Invalid** — no withdrawn/invalid/cancelled status (those are Complaint statuses). `cancelled` is referenced defensively (`models.py:2167`, `ui_views.py:3744`) but is never a valid Inquiry status.
- **Wrong department** — handled by re-transfer (`transfer_count` increments); no explicit bounce-back.
- **Missing info** — `inquiry_add_note` / token `InquiryExplanation`; no "pending info" status.
- **No patient response** — 3-stage contact timeline (`contacted_nr_at`, `models.py:1886`) + `contact_status="contacted_no_response"`. No auto-close.
- **Transferred** — `transfer_count` tracks; both dept fields set; `sent_to_department`/`sent_to_department_at` cross-module signal set.
- **Merged** — no merge feature.
- **Reopened** — see §12.
---
## 14. Department-Response Sub-Flow (CRITICAL)
### 14.1 Activation gate
`inquiry_transfer_to_department` (`ui_views.py:3594`) and `inquiry_send_to` (`ui_views.py:3841`) both reject `status == "open"` with *"Activate this inquiry before sending it to a department."* So `open → in_progress` (via `inquiry_activate`) is mandatory first.
### 14.2 How an inquiry is sent to a department
**(A) `inquiry_transfer_to_department` (`ui_views.py:3578`)** — the richer path:
- Validates: permission, not-open, `department_id`, department active with champion/manager, valid contact person.
- Sets: `outgoing_department`, `transferred_to_department = department`, `transferred_at`, `transferred_by`, `transfer_count += 1`, **`sent_to_department = True`**, `sent_to_department_at`.
- Computes dept-response SLA: `dept_response_sla_due_at = now + dept_response_hours`; resets overdue/reminder/escalation flags.
- Generates a one-time `response_token = secrets.token_urlsafe(32)`, sets `response_token` + `response_token_sent_at`.
- Builds token link `https://{domain}/inquiries/{pk}/respond/{token}/`; emails the contact person with deadline; calls `send_inquiry_department_assigned`.
- Writes `InquiryUpdate` type `transferred_to_department`.
**(B) `inquiry_send_to` (`ui_views.py:3818`)** — unified AJAX (person OR department):
- Department branch auto-targets champion+manager via `get_champion_and_manager`.
- Sets transfer fields + resets dept-response SLA.
- **⚠ Inconsistency:** sets `sent_to_department = True` **only if `inquiry.department_id == department.pk`** (`ui_views.py:3929`), unlike path (A) which always sets it. Sending to a *different* department via this endpoint does **not** set the cross-module "sent" signal.
- Notifies champion+manager by email+SMS; **does NOT generate a `response_token`** (no token link) — relies on in-app notification only.
### 14.3 Who receives it
The department's champion and/or manager (`get_champion_and_manager`). In path (A) the chosen `contact_person` (validated by `department.is_valid_contact_person`).
### 14.4 Champion's response submission (two ways)
**(i) Token-response path** — `/inquiries/<pk>/respond/<token>/` → `inquiry_respond_with_token` (`views.py:5141`), **no auth**:
- Validates `response_token` and not None; rejects if `response_token_used`.
- Accepts `response_en`/`response_ar` (at least one required).
- Writes `department_response_en/ar`, `department_responded_at`, clears `dept_response_is_overdue`, `response_token_used = True`.
- Generates AI summary into `department_response_summary_en/ar`.
- Notifies the **inquirer** SMS+email with public track URL.
- **⚠ Dead code:** `inquiry.dept_response_acceptance_status = "pending"` at `views.py:5173` — this field was removed (migration `0039`); silently dropped on save.
**(ii) Authenticated champion response** — `/inquiries/<pk>/department-response/` → `inquiry_department_response` (`ui_views.py:4003`):
- Permission: PX/Hosp-Admin/Champion of `department` or `outgoing_department`.
- Writes `department_response_en/ar`, `department_responded_at/_by`, clears overdue; AI summary; notifies inquirer.
- **Does NOT set any acceptance status** (field doesn't exist).
### 14.5 One-level review — accept/reject
**⚠ STALE-DOC — this loop no longer exists in the data model.** `docs/workflows.md:34-35` and the field-name table reference `dept_response_acceptance_status` (pending/acceptable/not_acceptable). Migration `0001_initial.py:440` defined it; **migration `0039` removed** `dept_response_acceptance_status`, `dept_response_acceptance_notes`, `dept_response_accepted_at`, `dept_response_accepted_by`.
Consequences:
- **No PX "accept"/"reject" view** for Inquiry dept responses (no URL/function). The only `acceptance_status` setters are for **Complaint**.
- The Inquiry model has no column to hold an accept/reject decision.
- The only surviving reference is the dead assignment at `views.py:5173`.
**So today the actual flow is:** champion submits `department_response_en/ar` → it's simply *available* to PX (shown in detail, fed into `generate_ai_response` prompt) → PX writes their own patient-facing `inquiry.response` via `inquiry_respond` → `status="resolved"`. **No explicit accept/reject decision and no reject-loop.** The champion's response is never "cleared" automatically; nothing returns a rejected response to the champion.
### 14.6 Reject loop
**⚠ Not implemented for Inquiry** (no backing field, no endpoint). `docs/workflows.md:16-17` describes the loop generally; for Inquiry it's aspirational/dead.
---
## Field-Name Reference (dept-response concept map)
| Concept | Field(s) on `Inquiry` | File:line |
|---|---|---|
| Target dept | `transferred_to_department` / `outgoing_department` | `models.py:1824, 1834` |
| Sent flag | `sent_to_department` + `sent_to_department_at` | `models.py:1810, 1813` |
| Transfer meta | `transferred_at`, `transferred_by`, `transfer_count` | `models.py:1807, 1816, 1832` |
| Response text | `department_response_en/ar` + AI `department_response_summary_en/ar` | `models.py:1843-1846` |
| Response at/by | `department_responded_at`, `department_responded_by` | `models.py:1847-1854` |
| **Acceptance** | **(REMOVED — migration `0039`)** | was `dept_response_acceptance_status` |
| Token | `response_token`, `response_token_used`, `response_token_sent_at` | `models.py:1857-1862` |
| Dept SLA | `dept_response_sla_due_at`, `dept_response_is_overdue`, `_reminder_sent_at`, `_escalated_at` | `models.py:1865-1881` |
| PX reply | `response`, `response_en/ar`, `response_sent_at`, `responded_at/_by` | `models.py:1784-1791` |
---
## 15. End-to-End Example
```
Patient submits inquiry via public form
↓ (ui_views.py:4707) → status=open, ref INQ-202607-0001, due_at set,
AI analysis + admin notify dispatched
[⚠ inquirer NOT auto-acknowledged]
PX staff activates
↓ (ui_views.py:3179) → status=in_progress, activated_at, assigned_to=self
PX transfers to Department X
↓ (ui_views.py:3578) → transferred_to_department=X, sent_to_department=True,
response_token generated, token link emailed to champion,
dept_response_sla_due_at set
[DECISION: champion responds via token or logged-in]
Champion submits dept response via token link
↓ (views.py:5141) → department_response_en set, department_responded_at,
response_token_used=True, AI summary generated,
inquirer notified SMS+email
[⚠ NO PX accept/reject — field removed]
[DECISION POINT: PX must write patient-facing response]
PX writes inquiry.response (generate_ai_response optional)
↓ (ui_views.py:3459) → response set, responded_at/by, response_sent_at,
status=resolved, inquirer notified SMS+email,
admins notified
PX closes
↓ (ui_views.py:3330) → status=closed, closed_at/by
[PERMANENT unless reopened → in_progress]
```
---
## Appendix — Flagged gaps vs `docs/workflows.md`
1. **`dept_response_acceptance_status` removed** (`0039`); the "PX accepts/rejects" loop is no longer backed by code. Dead assignment at `views.py:5173`.
2. **No `clean()`/`CheckConstraint`** on Inquiry; status enforced only ad-hoc in views; arbitrary strings persistable via change-status.
3. **Bug in `inquiry_send_to_staff`** (`ui_views.py:2938`) — calls nonexistent `InquirySLAConfig.get_active_config()` / `dept_response_sla_hours`.
4. **Auto dept-response escalation disabled** (`tasks.py:3178`).
5. **Inconsistent `sent_to_department`** between transfer (always sets) and send-to (only when target == primary dept).
6. **Invalid status choices exposed** in detail view (`contacted`/`contacted_no_response`).
7. **No creation acknowledgement to inquirer.**
8. **`inquiry_respond` clears `response_en/ar`**, fills only aggregate `response`.
9. **`is_straightforward`** field defined/serialized but never used in any decision.
10. **`cancelled`/`partially_resolved`** referenced defensively but never valid Inquiry statuses.

349
docs/workflows/observations.md Normal file
View File

@ -0,0 +1,349 @@
# Observations — Workflow & Lifecycle
> Source of truth: `apps/observations/`. An "observation" is a **staff safety/quality observation** (not a patient complaint). This document describes the **current implementation only**. Every claim is cited as `file:line`.
> **⚠ Read first — several stale-doc/latent-bug findings contradict `docs/workflows.md` and `README.md`.** Most important: the PX "accept/reject" department-response review step documented in `docs/workflows.md:44-47` **no longer exists in code** — the fields were removed (migration `0020`). Full list at the end.
---
## 1. Purpose
The Observations app is the **staff observation / safety-quality reporting module** (`apps/observations/README.md:3`). Any staff member can report issues they notice; submission may be **anonymous** (no login) with optional Staff ID + Name (`README.md:7,13`; model docstring `models.py:237-246`). PX360 staff then **triage** and route to a responsible department and/or create a PX Action.
It is explicitly **not** a complaint: no patient complainant, no multi-department join model, no manager-review tier (`docs/workflows.md:41-47`). The reporter is a *staff* observer; "patient-facing response" in code (`models.py:565`) actually means the response shown back to the staff reporter via the public track page.
Anonymous detection: `is_anonymous` returns True when neither `reporter_staff_id` nor `reporter_name` is set (`models.py:666`).
---
## 2. How a Case Starts
### 2.1 Creation channels (two entry points, both calling `ObservationService.create_observation` `services.py:43`)
| Channel | View | URL name | Auth | Form |
|---|---|---|---|---|
| Public (anonymous-allowed) | `observation_create_public` (`views.py:162`) | `observations:observation_create_public` (`urls.py:30`) → `/observations/new/` | None | `ObservationPublicForm` (`forms.py:29`) |
| Internal (staff) | `observation_create` (`views.py:301`) | `observations:observation_create` (`urls.py:41`) → `/observations/create/` | `@login_required` | `ObservationInternalForm` (`forms.py:181`) |
> **Note:** `PublicObservationForm` (`forms.py:717`) also exists but is **not wired to any URL**; only `ObservationPublicForm` is used by the view (`views.py:42`).
### 2.2 Public form — required fields (`ObservationPublicForm`, `forms.py:29`)
`Meta.fields` (`forms.py:68`): `hospital, location_type, area, title, description, location_text, incident_datetime, reporter_staff_id, reporter_name, reporter_phone, reporter_email`.
- **Required:** `description` (min length 10, `forms.py:173`); `location_type` (forced required `forms.py:147`).
- **Optional:** `area`, `title`, `location_text`, `incident_datetime` (defaulted to now `forms.py:163`), `reporter_*` (optional → enables anonymity).
- **No severity/category field on the public form** → public submissions always come in as **MEDIUM severity, no category** until triage/AI assigns them (`views.py:188`).
- Spam protection: honeypot `website` field (`forms.py:41`, validated `forms.py:166`). Attachments: `ALLOWED_EXTENSIONS`/`MAX_FILE_SIZE` 10 MB (`forms.py:25`).
### 2.3 Internal form — required fields (`ObservationInternalForm`, `forms.py:181`)
`Meta.fields` (`forms.py:196`): `hospital, location_type, area, description, section, incident_datetime, patient_file_number, assigned_department, assigned_to, px_source`.
- **Required:** `hospital`, `location_type`, `description` (min 10).
- Auto-fills reporter from logged-in user (`views.py:322`) — internal observations are never anonymous. Sets `source_legacy="staff_portal"` (vs public `"public_form"`, `views.py:204`).
- If `assigned_to` chosen at creation, the view **immediately** moves to IN_PROGRESS + writes a status log "Auto-assigned during creation" (`views.py:339`).
### 2.4 What happens immediately after submission (`ObservationService.create_observation`, `services.py:43`)
Inside one `@transaction.atomic` (`services.py:44`):
1. `Observation.objects.create(...)` with default `status=OPEN` (`models.py:375`).
2. **Tracking code** generated by the model's `save()` override (`models.py:650`): if adding and `hospital_id` set → `generate_reference("OBS", hospital)` → **`OBS-YYYYMM-NNNN`** (`apps/core/reference.py:32`); else random `OBS-XXXXXX` (`models.py:26`). Uniqueness loop retries.
3. **Initial status log:** `ObservationStatusLog(from_status="", to_status=OPEN, comment="Observation submitted")` (`services.py:113`).
4. **Attachments** created (`services.py:118`); metadata auto-extracted in `ObservationAttachment.save()` (`models.py:865`).
5. **New-observation notification** queued to `notify_staff_new_item.delay("observation", id)` (`services.py:126`) → `send_new_observation_notification` (`tasks.py:266`) → `ObservationService.notify_new_observation` (`services.py:430`) emails every user in the **"PX Admin"** group (`services.py:440`).
6. **AI analysis** queued: `analyze_observation_with_ai.delay(id)` (`services.py:134`; task `tasks.py:283`) — overwrites `severity`, matches `category`, sets `title`, stores result in `metadata["ai_analysis"]` (`tasks.py:347`); also drops a bilingual `ObservationNote` (`tasks.py:410`).
7. Public path redirects to success page showing tracking code (`views.py:207,225`).
**Signal side:** `signals.py` only `logger.info`s creation and status-log events (`signals.py:14`) — no signal-driven status change.
**Token fields** (`response_token`/`response_token_used`/`response_token_sent_at`, added `0015`) are **empty at creation** — generated only when sent to a department (`views.py:1269`).
---
## 3. Complete Lifecycle
### 3.1 The four statuses (`models.py:43-49`)
`OPEN`, `IN_PROGRESS`, `RESOLVED`, `CLOSED`.
### 3.2 `VALID_OBSERVATION_TRANSITIONS` (`models.py:52-57`) — verified
```
OPEN → {IN_PROGRESS}
IN_PROGRESS → {RESOLVED}
RESOLVED → {CLOSED, IN_PROGRESS} # IN_PROGRESS = reopen
CLOSED → {IN_PROGRESS} # reopen
```
Note the two reopen edges: RESOLVED→IN_PROGRESS and CLOSED→IN_PROGRESS.
### 3.3 Enforcement layers
- **Service:** `ObservationService.change_status` (`services.py:144`) checks `VALID_OBSERVATION_TRANSITIONS` and raises `ValueError` on illegal moves (`services.py:166`).
- **Model `clean()`:** `Observation.clean()` (`models.py:640`) raises `ValidationError` if `status` not in the four valid choices. (Validates the *value*, not the *transition*.)
- **DB `CheckConstraint`:** `observation_status_valid` restricting `status ∈ {open, in_progress, resolved, closed}` (`models.py:633`), added in `0016:30`.
- **⚠ Bypass:** `observation_respond` (`views.py:1001`) sets `status="resolved"` directly, skipping both the service transition check AND the status-log creation (Finding #7).
### 3.4 Original statuses & the simplification mapping
Original choices (`0001_initial.py:151`): `new, triaged, assigned, in_progress, resolved, closed, rejected, duplicate, contacted` (+ `contacted_no_response` on log fields).
**`0014_map_statuses.py`** (data migration):
| Old | → New `status` | `contact_status` |
|---|---|---|
| `new` | `open` | `not_contacted` |
| `triaged`/`assigned`/`contacted` | `in_progress` | `not_contacted` / `contacted` |
| `rejected`/`duplicate` | `closed` | `not_contacted` |
`0013_simplify_statuses.py` moved "contacted" out of `status` into a separate `contact_status` enum (`not_contacted / contacted / contacted_no_response`, `models.py:379-389`).
> **⚠ Stale:** `tests.py` references `ObservationStatus.NEW`/`.TRIAGED`/`.ASSIGNED` which no longer exist — would fail to import. `README.md:78` lists the old statuses; `README.md:70` the old `OBS-ABC123` format.
---
## 4. Status Definitions
| Status | Purpose | When entered | Who moves forward | Next |
|---|---|---|---|---|
| **OPEN** | Newly submitted, not picked up. Default on create. | At creation (`services.py:114`) | Anyone who activates/triages/assigns it (`observation_activate` `views.py:854`, `observation_triage` `views.py:729`, `observation_assign` `views.py:799`) — all flip OPEN→IN_PROGRESS. Send endpoints **reject OPEN** (activation gate). | IN_PROGRESS only |
| **IN_PROGRESS** | Being worked. `activated_at` stamped on first entry (`services.py:177`); `due_at` computed from SLA. | On activate/triage/assign; on reopen from RESOLVED/CLOSED; on assign from resolved/closed | PX/Hosp-Admin/PX-Mgmt/PX-Employee/Dept-Manager (varies by view) | RESOLVED only |
| **RESOLVED** | Work complete; awaiting closure. `resolved_at`/`resolved_by` stamped (`services.py:186`). Triggers `notify_resolution` (`services.py:205`). | Via `change_status` to RESOLVED; **or** via `observation_respond` which auto-resolves when a PX response is sent (`views.py:1000`) | `triage_observation` perm OR px_admin OR hospital_admin (`views.py:773`); also anyone allowed to `observation_respond` (`views.py:978`) | CLOSED, or reopen to IN_PROGRESS |
| **CLOSED** | Terminal. `closed_at`/`closed_by` stamped (`services.py:189`). | Via `change_status` to CLOSED (same gate) | Same | Reopen to IN_PROGRESS |
Helper: `is_active_status` True for open/in_progress (`models.py:771`). `check_overdue` treats resolved/closed/rejected/duplicate as inactive (`models.py:757`) — `rejected`/`duplicate` literals are harmless leftovers.
---
## 5. Workflow Actions
### Public (no login)
| Action | View (`views.py`) | URL name | Effect |
|---|---|---|---|
| Submit (public) | `observation_create_public` `:162` | `observation_create_public` | Creates OPEN; redirects to success page |
| Success page | `observation_submitted` `:225` | `observation_submitted` | Shows tracking code |
| Track by code | `observation_track` `:241` | `observation_track` | Public status + dept response view (no internal notes) |
| **Token response** (champion, no login) | `observation_respond_with_token` `:1987` | `observation_respond_with_token` | Validates token; champion submits dept response |
### Internal (login required)
| Action | View (`views.py`) | URL name | Permission gate | Effect |
|---|---|---|---|---|
| Create (internal) | `observation_create` `:301` | `observation_create` | `@login_required` | Creates OPEN; if `assigned_to` → IN_PROGRESS |
| **Triage** | `observation_triage` `:729` | `observation_triage` | `triage_observation` perm OR px_admin | `ObservationService.triage_observation` → sets dept/assignee, → IN_PROGRESS |
| **Change status** | `observation_change_status` `:765` | `observation_change_status` | `triage_observation` perm OR px_admin OR hospital_admin (`:773`) — **the gate the brief quotes** | Uses `ObservationService.change_status` → enforces transitions |
| **Assign/Reassign** | `observation_assign` `:799` | `observation_assign` | px_admin/hospital_admin/px_management/px_employee | Sets `assigned_to`; if resolved/closed → reopen to IN_PROGRESS + clear stamps; if open → IN_PROGRESS |
| **Activate (take)** | `observation_activate` `:854` | `observation_activate` | px_admin/hospital_admin/px_management/px_employee | Assigns to self; OPEN→IN_PROGRESS |
| **Reopen** | `observation_reopen` `:908` | `observation_reopen` | px_admin/hospital_admin/px_management/px_employee | Only from resolved/closed; → IN_PROGRESS; clears stamps |
| Add note | `observation_add_note` `:945` | `observation_add_note` | `@login_required` | `ObservationService.add_note` |
| **PX outward response** | `observation_respond` `:973` | `observation_respond` | px_admin/hospital_admin/px_management/px_employee OR `assigned_to` (`:978`) | Sets `response/responded_at/responded_by/response_sent_at`; auto-resolves if not already resolved/closed (`:994`). **⚠ Bypasses transition validator & status log.** |
| Generate AI response | `observation_generate_ai_response` `:1020` | `observation_generate_ai_response` | same as respond | Returns bilingual JSON draft; does not persist |
| **Send to department (legacy)** | `observation_send_to_department` `:1179` | `observation_send_to_department` | px_admin/hospital_admin/department_manager/px_management/px_employee | **Activation gate:** rejects OPEN. Sets `assigned_department`, `sent_to_department=True`, dept-response SLA, `response_token`, emails champion token link (§14) |
| **Escalate (manual)** | `observation_escalate` `:1335` | `observation_escalate` | px_admin/hospital_admin/px_management/px_employee | Refuses closed/cancelled/rejected; sets `escalated_at`, emails target |
| **Send-to (AJAX)** | `observation_send_to` `:1433` | `observation_send_to` | px_admin/hospital_admin/department_manager/px_management/px_employee | Activation gate. Branch: person (assigns User) or department (emails+SMS champion+manager). **⚠ Reads nonexistent `observation.reference_number` (`:1564`) → AttributeError.** |
| **Dept response (logged-in)** | `observation_department_response` `:1612` | `observation_department_response` | px_admin OR hospital_admin OR (is_champion AND `assigned_department==user.department`) | Stores `department_response_en/ar`, stamps `department_responded_at/_by`, AI summary, notifies reporter |
| Send dept-response reminder | `observation_send_dept_response_reminder` `:1752` | `observation_send_dept_response_reminder` | px_admin/hospital_admin/px_management/px_employee | Refuses if already responded; emails champion; stamps reminder |
| Convert to PX Action | `observation_convert_to_action` `:1113` | `observation_convert_to_action` | px_admin/hospital_admin/px_management/px_employee | One-shot guard on `action_id`; creates `PXAction` |
| Soft delete/Restore | `observation_soft_delete`/`observation_restore` `:1961/1975` | — | px_admin/hospital_admin/px_management/px_employee | |
| PDF | `observation_pdf` `:2066` | `observation_pdf` | `@login_required` | |
| Category CRUD | — | `urls.py:77-83` | `observations.manage_categories` via `@permission_required` | Delete blocked if in use |
---
## 6. Decision Points
- **Activation gate** (shared rule): OPEN observations **cannot be sent to a department** — both send endpoints reject `status == OPEN` (`views.py:1196, 1457`). Must first reach IN_PROGRESS via activate/triage/assign.
- **Triage needed?** New observations arrive OPEN with no dept/category (public) or optional dept (internal). Triage sets dept/owner/category (`services.py:215`).
- **AI classification** (`tasks.py:283`): proposes severity/category/title post-create.
- **Send to person vs department** (`observation_send_to`): `recipient_type` branch (`views.py:1463`).
- **Department has a contact target?** `has_contact_target(dept)` gates the dept list; legacy send requires champion **or** manager (`views.py:1212`).
- **Contact person valid?** `department.is_valid_contact_person(contact_person_id)` (`views.py:1221`).
- **Already responded?** Reminder short-circuits if `department_responded_at` set (`views.py:1763`).
- **Already converted?** Convert short-circuits on `action_id` (`views.py:1129`).
- **Convert-to-action vs send-to-dept** — mutually exclusive paths chosen by PX staff.
- **⚠ No formal PX accept/reject decision point exists anymore** (Finding #1). The implicit "review" is `observation_respond`.
---
## 7. Assignment Flow
- **`assigned_department`** (`models.py:445`) — the single responsible department (`SET_NULL`). This is the "outgoing department" field reused by the send flow; there is **no separate outgoing-department field**, unlike Inquiry.
- **`assigned_to`** (`models.py:453`) — individual user assignee.
- **`assigned_at`** (`models.py:461`).
- **Section** (`models.py:353`) — finer-grained.
- **Reassignment:** `observation_assign` logs old→new in the comment (`views.py:841`); `observation_activate` reassigns to self (`views.py:873`).
- **Transfer to department:** send endpoints overwrite `assigned_department` (`views.py:1240, 1538`) — effectively reassignment + send.
- **Owner cascade** `get_owner()` (`models.py:685`): section(champion→supervisor→deputy_supervisor) → department(champion→deputy_manager→supervisor→deputy_supervisor→manager_2nd→manager_3rd).
- **Escalation targets** computed in detail view from `dept.get_role_holders()` + Hospital Admin/Department Manager groups (`views.py:665`).
- **Final owner** = whoever resolves/closes (`resolved_by`/`closed_by`).
- **SLA config** per (hospital, severity): `ObservationSLAConfig` (`models.py:138`); `Observation.get_sla_config()` (`models.py:733`). `dept_response_hours` (default 48, `models.py:183`) drives dept-response SLA.
---
## 8. Investigation Process
**No separate investigation sub-flow** for observations (contrast with Complaints, `docs/workflows.md:25-28`). No Investigation/Question/Explanation models.
- **Notes** = `ObservationNote` (`models.py:879`): `note`, `created_by`, `is_internal` (default True). Plus generic `notes = GenericRelation("core.Note")` (`models.py:619`).
- **Audit trail** = `ObservationStatusLog` (`models.py:904`): every status change recorded by `change_status` (`services.py:196`). The champion-response path writes a pseudo-log with `from_status == to_status` (`views.py:1668`); the token path does **not** create a status log — small inconsistency.
- **Stage timeline** built by `_build_observation_stage_timeline` (`views.py:83`) from status logs + timestamp fields.
---
## 9. Communication Flow
All notifications via `apps.notifications.services.NotificationService`.
| Event | Trigger | Recipient | Channel | Code |
|---|---|---|---|---|
| New observation | create | "PX Admin" group | email | `services.py:430` |
| Assignment | triage/assign | `assigned_to` | email | `services.py:496` (⚠ `notify_assignment` defined but never called) |
| Sent to department | send endpoints | champion (+manager) | email (+SMS in send_to) | `views.py:1268, 1552` |
| Token link emailed | send-to-department | contact person | email w/ one-time link | `views.py:1282` |
| Department responded | dept response / token | reporter (`reporter_phone/email`) | SMS + email w/ track URL | `views.py:1684, 2039` |
| SLA reminder (resolution) | `send_observation_sla_reminders` | `assigned_to` | email | `tasks.py:53` |
| Dept-response reminders (auto) | `send_observation_dept_response_reminders` | dept champion | email | `tasks.py:511` |
| Dept-response reminder (manual) | `observation_send_dept_response_reminder` | dept champion | email | `views.py:1752` |
| Resolution/Closure | `change_status` → RESOLVED/CLOSED | `assigned_to` + dept manager | email | `services.py:559` |
| Escalation | `observation_escalate` | chosen escalate-to user | email | `views.py:1393` |
| Monthly follow-up | **(disabled)** | `assigned_to` | email | `tasks.py:211` (beat commented out, `config/celery.py:193,198`) |
| Public track page | observer enters code | observer (self-serve) | web | `views.py:241` |
**Acknowledgement/"need more info"/"no observer response"** tracked by `contact_status` (`not_contacted/contacted/contacted_no_response`, `models.py:379`), set to `contacted` on send-to-department (`views.py:1255, 1584`). **No automated "no response" flip** — no view currently writes `contacted_no_response`.
**Token-response path:** `/observations/<uuid:pk>/respond/<str:token>/` (`urls.py:36`) → `observation_respond_with_token` (`views.py:1987`). Validates token, refuses if used, one-shot.
---
## 10. Escalation Flow
### Manual
`observation_escalate` (`views.py:1335`): PX/admin/management/employee picks a `Staff` target + reason + email subject/body. Refuses closed/cancelled/rejected (`views.py:1350`). Stamps `escalated_at`, writes status log + note, emails target.
### "Automatic" — present in config but DISABLED in code
- Config fields on `ObservationSLAConfig`: `dept_response_auto_escalate_enabled` (default True, `models.py:195`), `dept_response_escalation_hours_overdue` (default 0 = immediately, `models.py:198`).
- Seed defaults (`seed_observation_dept_response_sla.py:39`): `sla_hours=72`, `dept_response_hours=48`, first reminder 12h, second 4h, auto-escalate enabled, escalation 0h.
- Task `check_overdue_observation_dept_responses` (`tasks.py:447`) flags overdue but the escalation branch is **dead code**: always logs "Auto-escalation skipped (disabled)" and `continue`s (`tasks.py:499`). **So escalation is manual only.**
- **SLA breach detection:** `Observation.check_overdue` (`models.py:757`) sets `is_overdue`/`breached_at`. Driven by `check_overdue_observations` (`tasks.py:19`) every 15 min.
- **Manager involvement:** only via manual escalation or the escalation-targets list. No manager-approval tier in the response review.
> **⚠ Celery beat contradicts task docstrings:** all four observation tasks run at `crontab(minute="*/15")` (`config/celery.py:86-114`), but `tasks.py:56` and `:517` claim "every hour". Monthly follow-up beats are **commented out** (`config/celery.py:193,198`) — never fire.
---
## 11. Resolution Process
- **Who can resolve:** the `observation_change_status` gate (`views.py:773`) = `triage_observation` perm **OR** `is_px_admin()` **OR** `is_hospital_admin()` — as `docs/workflows.md:45-46` states. Additionally `observation_respond` (`views.py:978`) lets px_admin/hospital_admin/px_management/px_employee **or the current assignee** resolve by sending a response.
- **How resolved:** `ObservationService.change_status(..., RESOLVED)` stamps `resolved_at`/`resolved_by` (`services.py:186`), writes `ObservationStatusLog`, fires `notify_resolution`. The alternate `observation_respond` sets fields inline (`views.py:997`) and additionally records `responded_at/responded_by/response_sent_at` (`models.py:570`, added `0017`).
- **Approval required:** **⚠ No separate approval step exists anymore.** The historical `dept_response_acceptance_status` (pending/acceptable/not_acceptable) was removed in `0020`. Today the champion's department response is **not formally accepted/rejected** — PX simply decides whether to write a patient-facing `response` (which resolves the case) or to reopen/re-ask via notes.
- **Observer confirmation:** **no observer satisfaction step.** `0018` added `satisfaction`/`satisfaction_set_at`, but **`0019` removed** both (`0019:13`) — so satisfaction is no longer captured for observations.
---
## 12. Closure Process
- **When closeable:** from RESOLVED only (`models.py:55`).
- **Who closes:** same `triage_observation` OR px_admin OR hospital_admin gate (`views.py:773`), via `observation_change_status`.
- **Side effects:** `closed_at`/`closed_by` (`services.py:189`); `notify_resolution` emailed.
- **Reopen:** CLOSED → IN_PROGRESS is legal (`models.py:56`). Two entry points: `observation_reopen` (`views.py:908`, clears resolved/closed stamps) and `observation_assign` (`views.py:825`, implicit reopen-on-reassign).
- **Permanently completed:** no "archived"/"locked" state — CLOSED is terminal but always reopenable. Soft-delete (`views.py:1961`) is the only "removal" path, reversible via restore.
---
## 13. Exception Flows
- **Duplicate/Invalid/Rejected:** **former statuses**, now collapsed to `closed` by `0014_map_statuses.py:19-20`. Today no dedicated "mark duplicate/invalid" action; PX closes + notes. (UI color maps for `rejected`/`duplicate` linger in `admin.py:171`, `models.py:728` but are unreachable.)
- **Wrong department:** re-send via send endpoints (overwrites `assigned_department`) or reassign.
- **Missing info:** triage note / `ObservationNote`; `contact_status` settable to `contacted` (no view sets `contacted_no_response`).
- **No observer response:** tracked conceptually via `contact_status="contacted_no_response"` but **no automated transition** writes it.
- **Converted to PX Action:** `observation_convert_to_action` (`views.py:1113`); one-shot guard on `action_id`; the observation is **not** auto-closed on conversion.
- **Withdrawn:** no dedicated status/action. Anonymous/identified reporter cannot retract; only PX can soft-delete.
- **Merged:** no merge feature.
- **Reopened:** `observation_reopen` (`views.py:908`) from resolved/closed → IN_PROGRESS.
---
## 14. Department-Response Sub-Flow
> ⚠ The documented "champion responds → PX accepts/rejects → resolve" loop (`docs/workflows.md:44`) is **only partially implemented** today. The accept/reject tier was removed (`0020`). What remains is "champion responds → PX writes outward response (resolve)". Both the intended design and the actual code are documented below.
### 14.1 Migration history of the sub-flow
- `0004_add_sent_to_department_fields.py:13` — added `sent_to_department` (bool) + `sent_to_department_at`.
- `0005_data_sent_to_department_backfill.py:5` — backfilled `sent_to_department=True` for any observation with an `assigned_department`.
- `0001_initial.py:165-175` — original dept-response fields.
- `0001_initial.py:176-178` + `0020:13-28` — `dept_response_acceptance_status` (+`_at`/`_by`/`_notes`) **added then removed**. Net effect: no acceptance fields today.
- `0015_add_response_token.py:13` — `response_token`/`response_token_used`/`response_token_sent_at`.
- `0017_observation_responded_at...py:15` — `responded_at`/`responded_by`/`response`/`response_en/ar`/`response_sent_at` (the PX outward response).
### 14.2 The activation gate (shared rule)
Both send endpoints refuse `status == OPEN`:
- `observation_send_to_department`: `views.py:1195` → "Activate this observation before sending it to a department."
- `observation_send_to`: `views.py:1456` → HTTP 400 JSON.
So an observation must first reach IN_PROGRESS (via triage/activate/assign) before forwarding.
### 14.3 Send → receive
1. **Send** (`observation_send_to_department` `views.py:1179` or `observation_send_to` `views.py:1433`):
- Sets `assigned_department = department` (`views.py:1240, 1538`).
- Sets `sent_to_department = True`, `sent_to_department_at = now`, `forwarded_to_dept_at = now` (`views.py:1241-1243, 1539-1541`) — the uniform cross-module "sent" signal.
- Computes `dept_response_sla_due_at = now + dept_response_hours`; resets overdue/reminder/escalation stamps (`views.py:1245-1252, 1543-1550`).
- Sets `contact_status="contacted"` (`views.py:1255, 1584`).
- **Legacy path** generates `response_token` (`views.py:1273`) and emails the chosen contact person a one-time link `https://{domain}/observations/{pk}/respond/{token}/` (`views.py:1282`).
- **Unified path** emails+SMSes champion **and** manager via `get_champion_and_manager` — but **⚠ crashes on `observation.reference_number`** (`views.py:1564-1574`, Finding #2 — `reference_number` doesn't exist on Observation, only `tracking_code`).
- Writes an internal `ObservationNote` (`views.py:1261, 1590`).
2. **Who receives it:** the department **champion** primarily (reminder recipient is `dept.champion.user`, `tasks.py:542`); the dept manager is a secondary recipient in the unified send path.
### 14.4 Champion's response submission (two surfaces, same fields)
- **Logged-in champion:** `observation_department_response` (`views.py:1612`), gated by `is_champion()` AND `observation.assigned_department == user.department` (`views.py:1619`). Form: `ObservationDepartmentResponseForm` (`forms.py:654`) — requires `response_en` **or** `response_ar` (`forms.py:682`).
- **Token (no login):** `observation_respond_with_token` (`views.py:1987`), validates `response_token` (`:1998`) and `response_token_used` (`:2001`).
Both store `department_response_en/ar`, stamp `department_responded_at` + `department_responded_by` (logged-in path only), clear `dept_response_is_overdue`, mark `response_token_used=True` (token path), generate AI summary into `department_response_summary_en/ar` (`views.py:1644, 2022`), write a pseudo `ObservationStatusLog` (logged-in path only, `views.py:1668`), and notify the reporter via SMS/email with the public track URL (`views.py:1684, 2039`).
### 14.5 ONE-level review — what actually exists
- **Per `docs/workflows.md:41-47` (intended):** "champion responds → PX accepts/rejects → resolve" using `dept_response_acceptance_status`.
- **In current code:** `dept_response_acceptance_status` and friends were removed (`0020`). There is **no** `px_accept`/`px_reject` URL or view. The de-facto "review" is the PX user running `observation_respond` (`views.py:973`) to write `response/response_en/ar`, `responded_at/_by`, `response_sent_at` (`models.py:565`), which also flips status to `resolved` (`views.py:1000`).
- **⚠ Reject loop / "response cleared, returns to champion":** described in `docs/workflows.md:16-17` as a shared rule, but there is **no implementation** for observations — no view clears `department_response_en/ar` or resets `department_responded_at`. If PX is unhappy, the only options today are to reopen (`observation_reopen`) and re-send, or to add a note. **Document as a gap.**
### 14.6 Token-response path (summary)
- URL: `/observations/<uuid:pk>/respond/<str:token>/` (`urls.py:36`).
- Token generated only at send-time (`views.py:1273`), stored in `response_token` (`models.py:551`), uniqueness-indexed.
- Validation: token equality + non-empty (`views.py:1998`); not already used (`views.py:2001`, field `response_token_used` `models.py:555`).
- One-shot: sets `response_token_used=True` on submit (`views.py:2019`); subsequent visits render `response_already_submitted.html`.
- No-auth requirement explicit (`views.py:1987`).
---
## 15. End-to-End Example
```
Staff member submits observation via public form (anonymous allowed)
↓ (views.py:162) → status=OPEN, tracking OBS-202607-0001,
initial status log written, AI analysis dispatched,
PX admins notified
PX triages (sets department, assignee, category, severity)
↓ (views.py:729) → status=IN_PROGRESS, activated_at, due_at computed
[DECISION: send to department or convert to action]
PX sends to Department X
↓ (views.py:1179) → assigned_department=X, sent_to_department=True,
dept_response_sla_due_at set, response_token generated,
token link emailed to champion, contact_status=contacted
[DECISION: champion responds via token or logged-in]
Champion submits dept response via token link
↓ (views.py:1987) → department_response_en set, department_responded_at,
response_token_used=True, AI summary generated,
reporter notified SMS+email
[⚠ NO PX accept/reject — field removed]
[DECISION POINT: PX must write outward response]
PX writes outward response
↓ (views.py:973) → response set, responded_at/by, response_sent_at,
status=resolved (auto), resolved_at/by
[⚠ bypasses transition validator & status log]
[DECISION POINT: close or reopen]
PX closes
↓ (views.py:765) → status=closed, closed_at/by, notify_resolution
[PERMANENT unless reopened → IN_PROGRESS]
```
---
## Appendix — Flagged gaps vs `docs/workflows.md` / `README.md`
1. **`dept_response_acceptance_status` removed** (`0020`) — PX accept/reject no longer implemented; no `px_accept`/`px_reject` view.
2. **`observation_send_to` AttributeError** (`views.py:1564-1574`) — reads nonexistent `observation.reference_number`; should be `tracking_code`.
3. **Stale test suite** — `tests.py` references `ObservationStatus.NEW`/`.TRIAGED`/`.ASSIGNED`.
4. **Celery beat contradicts task docstrings** — all run `*/15`, not "every hour"; monthly follow-up beats commented out.
5. **Auto dept-response escalation disabled** (`tasks.py:499`) despite config flag defaulting True.
6. **`README.md` outdated** — old statuses, old tracking format.
7. **`observation_respond` bypasses transition validator & status log** (`views.py:1001`) — inconsistency in audit trail.
8. **No reject loop** for observations (no view clears dept response) — gap vs `docs/workflows.md:16-17`.
9. **`satisfaction` removed** (`0019`) — no observer satisfaction step.
10. **Stale literals** — `check_overdue`/escalate reference `cancelled`/`rejected`/`duplicate` which can never occur.

310
docs/workflows/suggestions.md Normal file
View File

@ -0,0 +1,310 @@
# Suggestions — Workflow & Lifecycle
> Source of truth: `apps/feedback/`. Suggestions are implemented as `FeedbackType.SUGGESTION` on the shared `Feedback` model (`apps/feedback/models.py:24`). There is **no dedicated model, status set, or workflow of its own** — every lifecycle claim here applies to all `FeedbackType` values (COMPLIMENT, SUGGESTION, GENERAL, INQUIRY, SATISFACTION_CHECK). Suggestion-specific behavior is called out where it exists.
> This document describes the **current implementation only**. Every claim is cited as `file:line`.
---
## 1. Purpose
The Suggestions module captures ideas/recommendations from patients, staff, and external sources and routes them through a lightweight triage-and-acknowledge workflow owned centrally by the Patient Experience (PX) team.
- `FeedbackType.SUGGESTION = "suggestion"` (`models.py:24`).
- The `Feedback` model docstring (`models.py:4-9`): "Tracks patient feedback (compliments, suggestions, general feedback)" and "Manages feedback workflow (submitted → reviewed → acknowledged → closed)".
- The word "Suggestion" is a **naming convention only** throughout the UI layer — the underlying record is a generic `Feedback`. E.g. `templates/feedback/feedback_detail.html:4` ("Suggestion Detail"); every audit event is named `suggestion_*` (`suggestion_created` `views.py:377`, `suggestion_updated` `views.py:437`, `suggestion_deleted` `views.py:494`, `public_suggestion_submitted` `views.py:1020`).
---
## 2. How a Case Starts
**Four distinct creation channels**, all producing a `Feedback` row with `feedback_type=SUGGESTION`, `status=SUBMITTED`, no `assigned_to`/`department`.
### 2.1 Channel A — Public Suggestion Form (unauthenticated)
- View: `public_suggestion_submit` (`views.py:937-1029`); `@csrf_exempt` + POST-only — **deliberately NOT `@login_required`** (`views.py:937`).
- URL: `path("public/suggestion/", ..., name="public_suggestion_submit")` (`urls.py:36`).
- Form: `PublicSuggestionForm` (`forms.py:251`) — a plain `forms.Form`.
- **Rate limiting:** per-IP cap of 5 submissions / 300s → HTTP 429 (`views.py:944`).
- Accepts JSON and form-encoded (`views.py:951`).
- **Required:** `contact_name`, `contact_phone`, `message`, `hospital` (`views.py:966`). Optional: `contact_email`, `category`/Area (defaults to `OTHER`, `views.py:977`), `title` (defaults to `message[:100]`).
Post-save (`views.py:992-1024`): `patient=None` at creation; linked **asynchronously** by `link_feedback_patient.delay(id, phone)` (`views.py:1015`); `analyze_suggestion_with_ai.delay(id)` (`views.py:1013`); `notify_staff_new_item.delay("suggestion", id)` (`views.py:1014`); audit `public_suggestion_submitted` (`views.py:1019`). Returns short pseudo-reference `"SG-{uuid[:8]}"` (`views.py:1026`) — **not** the internal `SGT-...` reference; the public cannot track by reference.
### 2.2 Channel B — Internal Staff Form (authenticated)
- View: `feedback_create` (`views.py:293-405`); `@login_required`. URL `feedback_create` (`urls.py:16`).
- **Does not use `FeedbackForm`** — builds the `Feedback` directly from POST (`views.py:311`), always `feedback_type=SUGGESTION` (`views.py:343`) — i.e. this view is hard-coded to create suggestions only.
- **Required:** `contact_name`, `contact_phone`, `message`, `hospital` (`views.py:318-326`). Optional: `title`.
- Post-save: **synchronous** `find_or_link_patient` (`views.py:336`); `analyze_suggestion_with_ai.delay` (`views.py:365`); `notify_staff_new_item.delay` (`views.py:366`); internal `FeedbackResponse` "Suggestion submitted by {user}" (`views.py:368`); audit `suggestion_created` (`views.py:376`).
### 2.3 Channel C — External API (machine-to-machine)
- View: `ExternalSuggestionCreateView` (`apps/integrations/api_views.py:700`), `POST /api/v1/external/suggestions/`.
- Auth via API key; hospital must match scope. Generates its own ephemeral `SG-{YYYYMMDD}-{random6}` in `metadata` (`api_views.py:740`) — **not** the canonical `reference_number` column (which `save()` still populates). Same post-save tasks (`api_views.py:765`).
### 2.4 Channel D — PX Source-User Portal
- View: `source_user_create_suggestion` (`apps/px_sources/ui_views.py:1387`); `@login_required`; guarded by `source_user.can_create_suggestions`.
- **Uses `PublicSuggestionForm`** (`ui_views.py:1400`). Sets `source=source`, `metadata={"created_via":"source_user_portal"}`. Fires **only** `analyze_suggestion_with_ai` (notably does **NOT** call `notify_staff_new_item`).
### 2.5 What happens immediately after submission (all channels)
1. **`Feedback.save()` override** (`models.py:261`): if `reference_number` blank → `generate_reference("SGT", hospital)` → `SGT-YYYYMM-NNNN` (global monthly sequence, `apps/core/reference.py:32`). Comment on field (`models.py:168`): *"internal-only, not publicly trackable"*.
2. Default `status = SUBMITTED` (`models.py:196`).
3. **No Django signals** — there is no `apps/feedback/signals.py` and `apps.py` registers no `ready()` handler. All side-effects are triggered explicitly by views/tasks.
> **⚠ Gap:** `FeedbackForm` (`forms.py:13`) exists but is used **only by `feedback_update`** (`views.py:421`), not creation. `feedback_create` builds the object manually, bypassing the form's `clean()` validation.
### 2.6 Are `CommentImport` / `PatientComment` bulk-import channels? **No.**
`CommentImport` (`models.py:479`) and `PatientComment` (`models.py:534`) describe a **separate, parallel workflow** (monthly IT exports of raw comments; "Steps 0-5"). `PatientComment.suggestions` (`models.py:600`) is just free-text extracted from a comment — it does **not** create a `Feedback` row. No code path creates `CommentImport` records (admin-only). See §16.
---
## 3. Complete Lifecycle
### 3.1 `FeedbackStatus` enum (`models.py:30-37`)
`SUBMITTED`, `REVIEWED`, `ACKNOWLEDGED`, `CLOSED`, `REOPENED`.
### 3.2 `VALID_FEEDBACK_TRANSITIONS` (`models.py:40-46`) — verified exact
```
SUBMITTED → [REVIEWED, CLOSED]
REVIEWED → [ACKNOWLEDGED, CLOSED]
ACKNOWLEDGED → [CLOSED]
CLOSED → [REOPENED]
REOPENED → [REVIEWED, ACKNOWLEDGED, CLOSED]
```
### 3.3 Enforcement layers
- **Model:** NOT enforced — no `clean()` on `Feedback`.
- **DB:** NOT enforced — no `CheckConstraint` in `Meta` or migrations.
- **View:** enforced **only** in `feedback_change_status` (`views.py:776-859`): rejects no-op same-status (`views.py:807`); computes `allowed = VALID_FEEDBACK_TRANSITIONS.get(old_status, [])` and rejects `new_status not in allowed` (`views.py:811-817`).
- **Admin:** NOT enforced.
> **Implication:** transitions are **soft**. PX Admin editing via Django admin, or any direct ORM write, can move a suggestion to any status. Only the staff UI enforces the rules.
---
## 4. Status Definitions
| Status | Purpose | When entered | Who moves forward | Next |
|---|---|---|---|---|
| **SUBMITTED** (`models.py:33`) | Initial entry for every suggestion from every channel. UI badge: blue. | At `save()` on creation (`models.py:197`) | Any PX/hospital user with change-status perm (§5) | REVIEWED, CLOSED |
| **REVIEWED** (`models.py:34`) | PX staffer has triaged/read. Sets `reviewed_at`/`reviewed_by` (`views.py:821`). UI badge: orange. | `feedback_change_status` choosing `reviewed` | Same perm group | ACKNOWLEDGED, CLOSED |
| **ACKNOWLEDGED** (`models.py:35`) | PX formally acknowledged/accepted. Sets `acknowledged_at`/`acknowledged_by` (`views.py:824`). UI badge: green. | `feedback_change_status` choosing `acknowledged` | Same | CLOSED |
| **CLOSED** (`models.py:36`) | Terminal. Sets `closed_at`/`closed_by` (`views.py:827`). Reachable from SUBMITTED, REVIEWED, ACKNOWLEDGED, REOPENED. UI badge: slate. When closed, Quick Actions + Edit hidden (`feedback_detail.html:51,299`). | `feedback_change_status` | Same | REOPENED |
| **REOPENED** (`models.py:37`) | Closed suggestion re-opened. **Clears** `closed_at`/`closed_by` (`views.py:830`); does NOT clear `acknowledged_*`/`reviewed_*`. | `feedback_change_status` | Same | REVIEWED, ACKNOWLEDGED, CLOSED |
> **Note on ACKNOWLEDGED:** a `FeedbackResponse` with `response_type="acknowledgment"` is valid (`models.py:372`) and exposed by `FeedbackResponseForm` (`forms.py:121`), but `feedback_change_status` does **not** require a response to exist before allowing ACKNOWLEDGED. No programmatic coupling — acknowledgement is a status change; the optional acknowledgment response is an independent timeline entry.
---
## 5. Workflow Actions
### 5.1 List & Detail (read)
| Action | View | URL name | Permission |
|---|---|---|---|
| List | `feedback_list` (`views.py:37`) | `feedback_list` (`urls.py:13`) | `@login_required`; RBAC filtering (`views.py:59`): PX Admin all/hospital-filtered; Hospital Admin → own; Dept Manager → own dept; else own hospital |
| Detail | `feedback_detail` (`views.py:194`) | `feedback_detail` (`urls.py:14`) | `@login_required`; access checks (`views.py:213`) |
Detail computes a workflow stepper: Submitted → Assigned → Reviewed → Acknowledged → Closed (`views.py:278`) — advisory only, not authoritative.
### 5.2 Status change — `feedback_change_status` (`views.py:776`)
URL `feedback_change_status` (`urls.py:21`); POST-only. Permission (`views.py:783`): `is_px_admin OR is_hospital_admin OR is_px_management OR is_px_employee`. Logic: validate status value; reject no-op; enforce `VALID_FEEDBACK_TRANSITIONS`; apply side-effects (REVIEWED→`reviewed_at/by`, ACKNOWLEDGED→`acknowledged_*`, CLOSED→`closed_*`, REOPENED→clear `closed_*`); create `FeedbackResponse(response_type="status_change")`; audit. Form: `FeedbackStatusChangeForm` (`forms.py:219`) — lists all statuses without filtering (filtering in view).
### 5.3 Assign — `feedback_assign` (`views.py:721`)
URL `feedback_assign` (`urls.py:20`). Permission: PX/Hosp-Admin/PX-Mgmt/PX-Employee. Sets `assigned_to`/`assigned_at`; creates `FeedbackResponse("assignment")`; audit. Form: `FeedbackAssignForm` (`forms.py:238`). Candidate set: `get_assignable_users(hospital)` = active users in group **"PX Employee"** at the suggestion's hospital. No status restriction in the view (UI panel hidden when closed).
### 5.4 Add Response / Timeline — `feedback_add_response` (`views.py:862`)
URL `feedback_add_response` (`urls.py:24`). Permission: PX/Hosp-Admin/PX-Mgmt/Department-Manager. Creates `FeedbackResponse` with caller-supplied `response_type` (status_change/assignment/note/response/acknowledgment). No status restriction.
### 5.5 Send to Department — `feedback_send_to_department` (awareness-only)
URL `feedback_send_to_department` (`urls.py:22`). Permission: PX/Hosp-Admin/PX-Mgmt/PX-Employee. **Precondition:** `feedback.department` already set (`views.py:1104`). Emails `department.champion`/`manager`/`deputy_manager` with **"This is for your awareness. No response is required."** (`views.py:1126`). Creates `is_internal=False` note. **Does NOT change status, does NOT create a department-response workflow.** See §14.
### 5.6 Send-to (AJAX) — `feedback_send_to`
URL `feedback_send_to` (`urls.py:23`). Permission: PX/Hosp-Admin/PX-Mgmt/PX-Employee. Two modes: `recipient_type="person"` (assigns to a User + emails) or `"department"` (links `feedback.department` + emails/SMSs champion+manager via `get_champion_and_manager`; SMS says *"No response is required"*). Rejects dept with no champion/manager.
### 5.7 Toggle flags
| Action | View | Permission | Effect |
|---|---|---|---|
| Toggle featured | `feedback_toggle_featured` (`views.py:895`) | PX/Hosp-Admin | flips `is_featured` (`models.py:225`) |
| Toggle follow-up | `feedback_toggle_follow_up` (`views.py:916`) | PX/Hosp-Admin | flips `requires_follow_up` (`models.py:227`) |
### 5.8 Create PX Action — `feedback_create_action`
URL `feedback_create_action` (`urls.py:28`). Permission: PX/Hosp-Admin. Creates a `PXAction` (generic FK to Feedback), `source_type="suggestion"`, `status="open"`. **One-way spawn** — does not change Feedback status; "promote this suggestion into a tracked improvement action".
### 5.9 Attachments
`FeedbackAttachment` (`models.py:332`): no dedicated view — listed on detail (`views.py:230`) but creatable **only** via Django admin or programmatically.
### 5.10 CRUD
Create (`feedback_create` `views.py:293`); Update (`feedback_update` `views.py:408` — PX/Hosp-Admin only); Delete-soft (`feedback_delete` `views.py:476` — PX/Hosp-Admin only; `feedback.soft_delete` sets `is_deleted`/`deleted_at`/`deleted_by`).
---
## 6. Decision Points
The only **enforced** decision point is the transition gate inside `feedback_change_status` (`views.py:811`): *is `new_status` in `VALID_FEEDBACK_TRANSITIONS[old_status]`?*
Beyond that, **every other "decision" is operator judgement** — the code does not branch:
- "Needs review" — no predicate; SUBMITTED→REVIEWED or SUBMITTED→CLOSED directly.
- "Needs response before acknowledge" — **not enforced**.
- "Can be acknowledged directly" — only from REVIEWED or REOPENED; SUBMITTED→ACKNOWLEDGED forbidden.
- "Close vs reopen" — operator choice.
> **⚠ Gap — reopen unreachable via UI after closure:** the Quick Actions panel (containing the status-change form) is hidden when `status == 'closed'` (`feedback_detail.html:299`). The map allows CLOSED→REOPENED but no staff UI button offers it. Reopen is only possible via Django admin or direct ORM.
---
## 7. Assignment Flow
- Field: `Feedback.assigned_to` (`models.py:201`); `assigned_at` (`models.py:204`).
- **Initial owner:** `None` for every channel.
- **Reassignment:** `feedback_assign` overwrites each call — no history field; history preserved only via `FeedbackResponse("assignment")` entries.
- **Candidate set:** `get_assignable_users(hospital)` = active users in **"PX Employee"** group. Suggestions are assigned **to PX staff only** — never to a department manager/champion via this form.
- **Department routing:** `Feedback.department` (`models.py:148`) is **not auto-assigned** by any creation channel and is **not used for ownership/routing**. Populated only when a PX user manually sends the suggestion to a department — and even then it's for **notification only**, not ownership transfer (§14).
---
## 8. Investigation Process
**No investigation phase.** Compared to complaints/inquiries/observations there is no RCA-required state, no evidence-gathering, no explanation request, no SLA-driven investigation timer.
Closest analogues:
- **AI pre-analysis** (`analyze_suggestion_with_ai`, `tasks.py:184`): async after creation. Calls `AIService.analyze_suggestion(message, title)` (`apps/core/ai_service.py:2124`) and **overwrites** `category`/`priority`, optionally `title`, stores analysis under `metadata["ai_analysis"]` (`tasks.py:219`).
- **Optional RCA linkage:** `feedback_detail` (`views.py:236`) fetches `RootCauseAnalysis` objects; template has a (commented-out) "Initiate RCA" link. An RCA *can* be attached but is **not part of the suggestion workflow**.
### `CommentActionPlan` — a SEPARATE action-tracking sub-flow (NOT on Feedback)
`CommentActionPlan` (`models.py:660`) attaches to `PatientComment` (IT-export pipeline), **not** `Feedback`. It has its own status enum `CommentActionPlanStatus` (PENDING/ON_PROCESS/COMPLETED, `models.py:654`) and `timeframe`/`evidences`/`responsible_department` fields. Unrelated to the live suggestion lifecycle (§16).
---
## 9. Communication Flow
| Event | Channel | Where |
|---|---|---|
| Acknowledgement | none automatic — operator may add `response_type="acknowledgment"` `FeedbackResponse` | `feedback_add_response` |
| Response to patient | `FeedbackResponse("response", is_internal=False)` | `feedback_add_response` |
| Closure | no outbound message — only internal timeline note | `feedback_change_status` |
**Crucially, no email/SMS is ever sent to the suggester (the patient/contact) by the feedback app.** All notifications go **inbound to PX/department staff**:
- On creation: `notify_staff_new_item("suggestion", id)` emails/SMSs **PX Admins** (working-hours: all; after-hours: on-call) — `complaints/tasks.py:2489`; config block `complaints/tasks.py:2548`. Template `emails/new_suggestion_notification.html`.
- On send-to-department: emails champion/manager/deputy (`views.py:1113`) or champion+manager (`views.py:1255`) with explicit "No response is required".
So the suggester receives **only** the immediate `{"reference":"SG-..."}` JSON from the public endpoint (`views.py:1026`) and nothing further unless a PX operator manually contacts them outside the system. **Suggestions are inbound-only communication.**
---
## 10. Escalation Flow
**None.** Confirmed:
- `Feedback` has **no SLA fields** (no `due_date`, `sla_deadline`, `escalated_at`).
- Celery beat (`config/celery.py`) has SLA/escalation tasks for complaints, inquiries, observations — **but nothing for feedback/suggestions**.
- The only feedback-related beat entry is `analyze-feedback-sentiment` → `process_pending_sentiment_analysis` every 30 min (`config/celery.py:201`) — analytics, not escalation.
- Grep for `feedback.*sla|feedback.*escalat` returned **no matches**.
`AuditEvent.EVENT_TYPES` includes `"escalation"`/`"sla_breach"` (`apps/core/models.py:89`) but these are never emitted by the feedback app.
---
## 11. Resolution Process
Suggestions have no formal "resolution" — the resolution-equivalent statuses are **ACKNOWLEDGED** and **CLOSED**.
- **Who can move to ACKNOWLEDGED/CLOSED:** PX/Hosp-Admin/PX-Mgmt/PX-Employee (`views.py:783`).
- **Approval required:** none.
- **Patient confirmation:** not present — the suggester has no authenticated presence and is never asked to confirm.
- **Evidence:** none on `Feedback` (exists only on `CommentActionPlan.evidences`, `models.py:728`, in the separate IT-export pipeline).
"Resolution" for a suggestion is simply an operator deciding to flip status and optionally recording an internal/external `FeedbackResponse` note.
---
## 12. Closure Process
- **When closeable:** from SUBMITTED, REVIEWED, ACKNOWLEDGED, or REOPENED (`models.py:41-45`) — closable from almost every state.
- **Who closes:** PX/Hosp-Admin/PX-Mgmt/PX-Employee (`views.py:783`).
- **Side-effects:** `closed_at`/`closed_by` (`views.py:827`); `FeedbackResponse("status_change")` created; audit.
- **Reopen conditions:** CLOSED → REOPENED is the only exit; reopening clears `closed_at`/`closed_by`, leaves `acknowledged_*`/`reviewed_*` intact.
- **Permanently completed:** **no "permanent close" flag.** A suggestion can be reopened indefinitely (REOPENED → CLOSED → …).
- **Soft-delete:** independent of status — `feedback_delete` calls `soft_delete`; restorable via `SoftDeleteModel.restore()` (no UI button — admin only).
---
## 13. Exception Flows
The codebase implements **none** of the classic exception statuses as first-class concepts:
| Exception | Implemented? | Evidence |
|---|---|---|
| Duplicate | No | No `duplicate_of` FK, no detection task. Operators close+note. |
| Withdrawn | No | No `WITHDRAWN` status; suggester has no withdraw channel. |
| Invalid | No | No `INVALID`/`REJECTED`. SUBMITTED→CLOSED is closest (`models.py:41`). |
| Spam | No dedicated status | Only the public endpoint's IP rate-limit (5/300s → 429, `views.py:944`). Spam closed+noted manually. |
| Converted-to-complaint | No | No converter. Closest is `feedback_create_action` spawning a `PXAction`, not a Complaint. |
| Merged | No | No merge view, no `merged_into` FK. |
| Reopened | Yes | `models.py:37,44`; `views.py:830`. |
| Missing info | No | No "awaiting info" status. `requires_follow_up` flag (`models.py:227`, toggled `views.py:916`) is the only soft signal — a boolean, not a state. |
---
## 14. Department-Response Sub-Flow — **NOT present for Suggestions**
This is the single most important architectural difference between Suggestions and Complaints/Inquiries/Observations.
**Explicit confirmation — suggestions are NOT routed to departments for response:**
- `feedback_send_to_department` email body: *"This is for your awareness. No response is required."* (`views.py:1126`).
- `feedback_send_to` SMS body: *"PX360: Feedback '...' logged for {dept}. ... No response is required."* (`views.py:1273,1284`).
- `feedback_send_to` docstring: *"Awareness-only: no response required from the department."* (`views.py:1151`).
**What "send to department" actually does:**
1. Optionally sets `feedback.department` (`views.py:1252`; `feedback_send_to_department` requires it set, `views.py:1104`).
2. Looks up champion + manager via `get_champion_and_manager`.
3. Sends email (+ SMS in send_to) to those people.
4. Writes an `is_internal=False` `FeedbackResponse` note recording who was notified.
5. **Does not change status. Does not create any "department response" record. Has no SLA, no reminder, no overdue check.**
Contrast with complaints/inquiries/observations which have dedicated `check-overdue-*-dept-responses` and `send-*-dept-response-reminders` beat tasks — feedback/suggestions have **none**.
**Conclusion:** Suggestions are handled **centrally by PX**. Departments may be informed for awareness but are never obligated to act within the suggestion lifecycle. If PX wants a department to actually *do* something, they must escalate via `feedback_create_action` to spawn a tracked `PXAction` (separate module).
---
## 15. End-to-End Example
```
Patient submits suggestion via public form
↓ (views.py:937) → status=SUBMITTED, ref SGT-202607-0001,
AI analysis dispatched, PX admins notified
[⚠ suggester NOT auto-notified beyond immediate JSON ack]
PX staff assigns to a PX Employee
↓ (views.py:721) → assigned_to set; FeedbackResponse("assignment")
PX reviews
↓ (views.py:776) → status=REVIEWED, reviewed_at/by
[DECISION: acknowledge or close]
PX acknowledges
↓ (views.py:776) → status=ACKNOWLEDGED, acknowledged_at/by
[optional: add FeedbackResponse("acknowledgment") to timeline]
PX closes
↓ (views.py:776) → status=CLOSED, closed_at/by; Quick Actions hidden
[REOPEN only via admin/ORM — not via staff UI]
[NO department involvement; NO outbound patient comms]
```
---
## 16. Parallel Pipelines (NOT part of the Suggestion lifecycle)
These exist in the same app but are **distinct reporting/analytics workflows**, not part of the live suggestion lifecycle. Documented here for completeness.
### 16.1 `CommentActionPlan` (`models.py:660`)
Attaches to `PatientComment`, **not** `Feedback`. Status enum `CommentActionPlanStatus` (COMPLETED/ON_PROCESS/PENDING — default `models.py:715`). Fields: `problem_number`, `comment_text/_en`, `frequency`, `recommendation` (required), `responsible_department`, `timeframe` (e.g. "Q3"), `evidences` (free-text completion evidence), `month`/`year`. No transition map — free-editable via admin. Listed read-only in `action_plan_list` ("Step 5", `views.py:607`).
### 16.2 `PatientComment` (`models.py:534`)
Raw-unit model of the IT-export pipeline. Imported in monthly batches via `CommentImport` (`models.py:479`), which tracks `month`/`year`/`source_file`/`status` (pending/processing/completed/failed) and counts. Each `PatientComment` carries: `source_category` (Appointment/Inpatient/Outpatient), `comment_text`, `classification`/`sub_category`, sentiment keyword fields, **`suggestions` extracted text** (just text, not a link), `sentiment`, `is_classified`, `mentioned_doctor_name`, `frequency`, `month`/`year`. Views: read-only list (`comment_list` `views.py:538`) + Excel exports Step 1/Step 2 (`export_utils.py`). **Creation is admin-only** (no code path creates `CommentImport`).
**Bottom line:** treat Comments & Action Plans as a separate "IT-export reporting" module that happens to live in the same Django app, not part of the Suggestions lifecycle.
---
## Appendix — Flagged gaps / ambiguities
1. **Reopen unreachable via UI** after closure (Quick Actions hidden when `closed`, `feedback_detail.html:299`). CLOSED→REOPENED allowed by map but no staff UI button.
2. **`reference_number` divergence** — `save()` generates canonical `SGT-YYYYMM-NNNN`; public endpoint returns different `SG-{uuid[:8]}` (`views.py:1026`); external API generates `SG-{YYYYMMDD}-{random6}` in metadata only. Public cannot track by real reference.
3. **`FeedbackForm` unused for creation** — `feedback_create` builds manually, bypassing form `clean()`.
4. **Transitions unenforced at DB/model/admin** — only `feedback_change_status` enforces.
5. **No outbound communication to suggester** by design.
6. **`feedback_send_to_department` requires `department` set, `feedback_send_to` sets it** — overlapping confusingly.
7. **AI task overwrites operator-entered category/priority** (`tasks.py:219`) — may clobber a manual categorization made immediately after creation.

BIN
exports/_email_review_preview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 775 KiB

968
exports/communication_templates.csv Normal file
View File

@ -0,0 +1,968 @@
channel,purpose,subject,content,example
email,Appointment confirmation,—,"{patient_name} ,
{patient_name}
{appointment_id}
{appointment_date}
{appointment_time}
{department}
{doctor_name}
{location}
-
-
-
{hospital_phone}
{hospital_email}","Ahmed Al Rashid ,
Ahmed Al Rashid
APT-2026-001
Jul 8, 2026
Jul 8, 2026
Emergency Department
Dr. Khalid Al Subaie
Outpatient Clinics
-
-
-
+966 55 123 4567
patient@example.com"
email,Communication request notification,—,"{reason}
{patient_name}
{source_user_name}
{message}
{request_id}","Quality concern
Ahmed Al Rashid
Ahmed Al Rashid
Please review and respond at your earliest convenience.
REQ-2026-0042"
email,Explanation reminder,—,"{staff.first_name} {staff.last_name} ,
#{complaint.id}
{complaint.title}
{complaint.description}
{hours_remaining} ({due_date})
تذكير: طلب شرح - شكوى #{complaint.id}
هذا تذكير بأنه تم طلب منك تقديم شرح بخصوص الشكوى التالية.
موعد تقديم الشرح يتبقى {hours_remaining} ساعة (الموعد النهائي: {due_date}).
يرجى تقديم الشرح قبل الموعد النهائي لتجنب التصعيد إلى مديرك المباشر.","Sara Al Otaibi ,
#CMP-202607-0007
Long wait time in OPD
Patient waited over an hour beyond the scheduled appointment time.
24 (Jul 8, 2026)
تذكير: طلب شرح - شكوى #CMP-202607-0007
هذا تذكير بأنه تم طلب منك تقديم شرح بخصوص الشكوى التالية.
موعد تقديم الشرح يتبقى 24 ساعة (الموعد النهائي: Jul 8, 2026).
يرجى تقديم الشرح قبل الموعد النهائي لتجنب التصعيد إلى مديرك المباشر."
email,Explanation request,—,"{staff_name} ,
{custom_message}
#{complaint_id}
{complaint_title}
{patient_name}
{department_name}
{due_date}
{description}","Dr. Sara Al Otaibi ,
Kindly provide a detailed explanation.
#<value>
Long wait time in OPD
Ahmed Al Rashid
Emergency Department
Jul 8, 2026
Patient waited over an hour beyond the scheduled appointment time."
email,Explanation second reminder,—,"{staff.first_name} {staff.last_name} ,
#{complaint.id}
{complaint.title}
{complaint.description}
{hours_remaining} ({due_date})
تذكير نهائي وعاجل: طلب شرح - شكوى #{complaint.id}
هذا تذكيرك النهائي بأنه تم طلب منك تقديم شرح بخصوص الشكوى التالية.
مهم: إذا لم تقدم شرحك قبل الموعد النهائي، سيتم تصعيد هذا الأمر إلى مديرك المباشر لاتخاذ الإجراء اللازم.
يرجى تقديم الشرح فوراً لتجنب التصعيد.","Sara Al Otaibi ,
#CMP-202607-0007
Long wait time in OPD
Patient waited over an hour beyond the scheduled appointment time.
24 (Jul 8, 2026)
تذكير نهائي وعاجل: طلب شرح - شكوى #CMP-202607-0007
هذا تذكيرك النهائي بأنه تم طلب منك تقديم شرح بخصوص الشكوى التالية.
مهم: إذا لم تقدم شرحك قبل الموعد النهائي، سيتم تصعيد هذا الأمر إلى مديرك المباشر لاتخاذ الإجراء اللازم.
يرجى تقديم الشرح فوراً لتجنب التصعيد."
email,Implementation status,Email Templates - Implementation Status,"Email Templates - Implementation Status
🏥 Email Template System
Al Hammadi Hospital - Unified Brand Identity
🎨 Brand Color Palette
Primary Navy
#005696
Accent Blue
#007bbd
Light Background
#eef6fb
Slate Gray
#64748b
👥 Patient-Facing Templates
Emails sent to patients
Survey Invitation
templates/emails/survey_invitation.html
Usage: Sent after patient visits for feedback collection
Appointment Confirmation
templates/emails/appointment_confirmation.html
Usage: Sent when appointments are booked
Survey Results Notification
templates/emails/survey_results_notification.html
Usage: Department heads notified of survey results
👨‍⚕️ Staff/Admin Templates
Internal communication emails
Explanation Request INTEGRATED
templates/emails/explanation_request.html
Integration: apps/complaints/tasks.py
Function: send_explanation_request_email()
User Invitation INTEGRATED
templates/accounts/onboarding/invitation_email.html
Integration: apps/accounts/services.py
Function: EmailService.send_invitation_email()
Invitation Reminder INTEGRATED
templates/accounts/onboarding/reminder_email.html
Integration: apps/accounts/services.py
Function: EmailService.send_reminder_email()
Onboarding Completion INTEGRATED
templates/accounts/onboarding/completion_email.html
Integration: apps/accounts/services.py
Function: EmailService.send_completion_notification()
Password Reset INTEGRATED
templates/accounts/email/password_reset_email.html
Integration: Django Authentication System
🔌 Integration Points
Complaints System
apps/complaints/tasks.py
send_explanation_request_email(explanation_id)
Sends branded explanation request emails to staff when complaints are filed.
Accounts Service
apps/accounts/services.py
EmailService.send_*_email()
All onboarding emails (invitation, reminder, completion) use branded templates.
Notifications Service
apps/notifications/services.py
NotificationService.send_email()
Unified email service with HTML support and database logging.
Base Template
templates/emails/
All email templates extend the base template for consistent branding.
Al Hammadi Hospital Email Template System
Patient Experience Management Department
Created on March 12, 2026
Documentation: templates/emails/README_EMAIL_TEMPLATES.md","Email Templates - Implementation Status
🏥 Email Template System
Al Hammadi Hospital - Unified Brand Identity
🎨 Brand Color Palette
Primary Navy
#005696
Accent Blue
#007bbd
Light Background
#eef6fb
Slate Gray
#64748b
👥 Patient-Facing Templates
Emails sent to patients
Survey Invitation
templates/emails/survey_invitation.html
Usage: Sent after patient visits for feedback collection
Appointment Confirmation
templates/emails/appointment_confirmation.html
Usage: Sent when appointments are booked
Survey Results Notification
templates/emails/survey_results_notification.html
Usage: Department heads notified of survey results
👨‍⚕️ Staff/Admin Templates
Internal communication emails
Explanation Request INTEGRATED
templates/emails/explanation_request.html
Integration: apps/complaints/tasks.py
Function: send_explanation_request_email()
User Invitation INTEGRATED
templates/accounts/onboarding/invitation_email.html
Integration: apps/accounts/services.py
Function: EmailService.send_invitation_email()
Invitation Reminder INTEGRATED
templates/accounts/onboarding/reminder_email.html
Integration: apps/accounts/services.py
Function: EmailService.send_reminder_email()
Onboarding Completion INTEGRATED
templates/accounts/onboarding/completion_email.html
Integration: apps/accounts/services.py
Function: EmailService.send_completion_notification()
Password Reset INTEGRATED
templates/accounts/email/password_reset_email.html
Integration: Django Authentication System
🔌 Integration Points
Complaints System
apps/complaints/tasks.py
send_explanation_request_email(explanation_id)
Sends branded explanation request emails to staff when complaints are filed.
Accounts Service
apps/accounts/services.py
EmailService.send_*_email()
All onboarding emails (invitation, reminder, completion) use branded templates.
Notifications Service
apps/notifications/services.py
NotificationService.send_email()
Unified email service with HTML support and database logging.
Base Template
templates/emails/
All email templates extend the base template for consistent branding.
Al Hammadi Hospital Email Template System
Patient Experience Management Department
Created on March 12, 2026
Documentation: templates/emails/README_EMAIL_TEMPLATES.md"
email,Inquiry dept response escalation,—,"{recipient_name} ,
{inquiry.reference_number}
{inquiry.subject}
{department_name}
{sla_due_at}
{hours_overdue}
تصعيد - رد القسم متأخر - {inquiry.reference_number}
موعد الاستحقاق: {sla_due_at} - ساعات التأخير: {hours_overdue}","Dr. Sara Al Otaibi ,
INQ-202607-0003
Long wait time in OPD
Emergency Department
Jul 8, 2026
6
تصعيد - رد القسم متأخر - INQ-202607-0003
موعد الاستحقاق: Jul 8, 2026 - ساعات التأخير: 6"
email,Inquiry dept response reminder,—,"{recipient_name} ,
{inquiry.reference_number}
{inquiry.subject}
{department_name}
{sla_due_at}
{hours_remaining}
تذكير - مطلوب رد القسم - {inquiry.reference_number}
موعد الاستحقاق: {sla_due_at} - الوقت المتبقي: {hours_remaining} ساعة","Dr. Sara Al Otaibi ,
INQ-202607-0003
Long wait time in OPD
Emergency Department
Jul 8, 2026
24
تذكير - مطلوب رد القسم - INQ-202607-0003
موعد الاستحقاق: Jul 8, 2026 - الوقت المتبقي: 24 ساعة"
email,Inquiry explanation request,—,"{staff_name},
#{inquiry_reference}
{inquiry_subject}
{inquiry_message}
{request_message}
{explanation_url}","Dr. Sara Al Otaibi,
#CMP-202607-0007
Long wait time in OPD
Please review and respond.
Please review and respond.
https://px360.app/explain/abc123"
email,Invitation expired,—,"{user.first_name} ,","Ahmed ,"
email,New appreciation notification,—,"{recipient_name} ,
: APR-{reference}
: {sender_name}
: {hospital_name}
: {department_name}
: {category}
:
{message_en}
:
{message_ar}
{notification_type}
{current_time}","Dr. Sara Al Otaibi ,
: APR-CMP-202607-0007
: Ahmed Al Rashid
: Al Hammadi Hospital
: Emergency Department
: Wait Time
:
Please review and respond.
:
Please review and respond.
Complaint Update
Jul 8, 2026"
email,New complaint admin notification,—,"{priority_badge} complaint: {complaint_title}
{admin_name} >,
: {reference_number}
: {complaint_title}
: {priority}
: {severity}
: {patient_name}
: {hospital_name}
: {department_name}
:
{description}
{notification_type}
{current_time}","high complaint: Long wait time in OPD
Mohammed Al Harbi >,
: CMP-202607-0007
: Long wait time in OPD
: high
: medium
: Ahmed Al Rashid
: Al Hammadi Hospital
: Emergency Department
:
Patient waited over an hour beyond the scheduled appointment time.
Complaint Update
Jul 8, 2026"
email,New inquiry notification,—,"{recipient_name} ,
: {reference_number}
: {subject}
: {category}
: {priority}
: {contact_name}
: {hospital_name}
: {department_name}
:
{message}
{notification_type}
{current_time}","Dr. Sara Al Otaibi ,
: CMP-202607-0007
: Long wait time in OPD
: Wait Time
: high
: Ahmed Al Rashid
: Al Hammadi Hospital
: Emergency Department
:
Please review and respond at your earliest convenience.
Complaint Update
Jul 8, 2026"
email,New observation notification,—,"{recipient_name} ,
{observation.tracking_code}
{observation.title}
{observation.category.name_en}N/A
{observation.get_status_display}
{observation.assigned_department.name}","Dr. Sara Al Otaibi ,
OBS-202607-0012
Long wait time in OPD
Ahmed Al RashidN/A
in_progress
Ahmed Al Rashid"
email,New suggestion notification,—,"{recipient_name} ,
: SG-{reference}
: {title}
: {category}
: {priority}
: {contact_name}
: {hospital_name}
: {department_name}
:
{message}
{notification_type}
{current_time}","Dr. Sara Al Otaibi ,
: SG-CMP-202607-0007
: Long wait time in OPD
: Wait Time
: high
: Ahmed Al Rashid
: Al Hammadi Hospital
: Emergency Department
:
Please review and respond at your earliest convenience.
Complaint Update
Jul 8, 2026"
email,Observation assigned,—,"{recipient_name} ,
{observation.tracking_code}
{observation.title}
{observation.category.name_en}N/A
{observation.get_severity_display}
{observation.location_text}
{observation.hospital.name}
{observation.assigned_department.name}
{observation.due_at}
{observation.description}
-
-
-
تم تعيين ملاحظة لك - {observation.tracking_code}
تم تعيين ملاحظة لكم للمراجعة واتخاذ الإجراء اللازم. يرجى الاطلاع على التفاصيل أدناه.","Dr. Sara Al Otaibi ,
OBS-202607-0012
Long wait time in OPD
Ahmed Al RashidN/A
high
Outpatient Clinics
Ahmed Al Rashid
Ahmed Al Rashid
Jul 11, 2026
Patient waited over an hour beyond the scheduled appointment time.
-
-
-
تم تعيين ملاحظة لك - OBS-202607-0012
تم تعيين ملاحظة لكم للمراجعة واتخاذ الإجراء اللازم. يرجى الاطلاع على التفاصيل أدناه."
email,Observation dept response escalation,—,"{recipient_name} ,
{observation.tracking_code}
{observation.title}
{department_name}
{sla_due_at}
{hours_overdue}
تصعيد - رد القسم متأخر - {observation.tracking_code}
موعد الاستحقاق: {sla_due_at} - ساعات التأخير: {hours_overdue}","Dr. Sara Al Otaibi ,
OBS-202607-0012
Long wait time in OPD
Emergency Department
Jul 8, 2026
6
تصعيد - رد القسم متأخر - OBS-202607-0012
موعد الاستحقاق: Jul 8, 2026 - ساعات التأخير: 6"
email,Observation dept response reminder,—,"{recipient_name} ,
{observation.tracking_code}
{observation.title}
{department_name}
{sla_due_at}
{hours_remaining}
تذكير - مطلوب رد القسم - {observation.tracking_code}
موعد الاستحقاق: {sla_due_at} - الوقت المتبقي: {hours_remaining} ساعة","Dr. Sara Al Otaibi ,
OBS-202607-0012
Long wait time in OPD
Emergency Department
Jul 8, 2026
24
تذكير - مطلوب رد القسم - OBS-202607-0012
موعد الاستحقاق: Jul 8, 2026 - الوقت المتبقي: 24 ساعة"
email,Observation monthly followup,—,"{recipient_name} ,
{observation.tracking_code}
{observation.title}
{observation.category.name_en}N/A
{observation.get_status_display}
{observation.assigned_department.name}
{observation.resolved_at}
{observation.resolution_notes}
-
-
-
متابعة شهرية مطلوبة - {observation.tracking_code}
ملاحظة سابقة الحل تحتاج إلى مراجعة المتابعة الشهرية. يرجى التحقق من استمرار فعالية الإجراءات التصحيحية.","Dr. Sara Al Otaibi ,
OBS-202607-0012
Long wait time in OPD
Ahmed Al RashidN/A
in_progress
Ahmed Al Rashid
Jul 8, 2026
Please review and respond.
-
-
-
متابعة شهرية مطلوبة - OBS-202607-0012
ملاحظة سابقة الحل تحتاج إلى مراجعة المتابعة الشهرية. يرجى التحقق من استمرار فعالية الإجراءات التصحيحية."
email,Observation resolved,—,"{recipient_name} ,
An observation assigned to you has been {status}. Please review the resolution details below.
{observation.tracking_code}
{observation.title}
{observation.category.name_en}N/A
{observation.get_status_display}
{observation.assigned_department.name}
{observation.resolved_at}
{observation.resolution_notes}
تم {status_display_ar} الملاحظة - {observation.tracking_code}
تم تحديث حالة الملاحظة. يرجى مراجعة تفاصيل الحل.","Dr. Sara Al Otaibi ,
An observation assigned to you has been in_progress. Please review the resolution details below.
OBS-202607-0012
Long wait time in OPD
Ahmed Al RashidN/A
in_progress
Ahmed Al Rashid
Jul 8, 2026
Please review and respond.
تم in_progress الملاحظة - OBS-202607-0012
تم تحديث حالة الملاحظة. يرجى مراجعة تفاصيل الحل."
email,Observation sla reminder,—,"{recipient_name} ,
{observation.tracking_code}
{observation.title}
{observation.category.name_en}N/A
{observation.get_severity_display}
{observation.get_status_display}
{observation.location_text}
{due_date}
{hours_remaining}
-
-
-
تذكير بموعد الاستحقاق - {observation.tracking_code}
هام: هذه ملاحظة غير معينة تحتاج إلى اهتمامكم. يرجى تعيينها في أقرب وقت ممكن.
تاريخ الاستحقاق: {due_date} - الوقت المتبقي: {hours_remaining} ساعة","Dr. Sara Al Otaibi ,
OBS-202607-0012
Long wait time in OPD
Ahmed Al RashidN/A
high
in_progress
Outpatient Clinics
Jul 8, 2026
24
-
-
-
تذكير بموعد الاستحقاق - OBS-202607-0012
هام: هذه ملاحظة غير معينة تحتاج إلى اهتمامكم. يرجى تعيينها في أقرب وقت ممكن.
تاريخ الاستحقاق: Jul 8, 2026 - الوقت المتبقي: 24 ساعة"
email,Observation sla second reminder,—,"{recipient_name} ,
{observation.tracking_code}
{observation.title}
{observation.category.name_en}N/A
{observation.get_severity_display}
{observation.get_status_display}
{due_date}
{hours_remaining}
-
-
-
-
تذكير نهائي عاجل - {observation.tracking_code}
هذا هو التذكير النهائي. الملاحظة على وشك تجاوز الموعد النهائي. يرجى اتخاذ الإجراء فوراً.
تاريخ الاستحقاق: {due_date} - الوقت المتبقي: {hours_remaining} ساعة","Dr. Sara Al Otaibi ,
OBS-202607-0012
Long wait time in OPD
Ahmed Al RashidN/A
high
in_progress
Jul 8, 2026
24
-
-
-
-
تذكير نهائي عاجل - OBS-202607-0012
هذا هو التذكير النهائي. الملاحظة على وشك تجاوز الموعد النهائي. يرجى اتخاذ الإجراء فوراً.
تاريخ الاستحقاق: Jul 8, 2026 - الوقت المتبقي: 24 ساعة"
email,Public inquiry notification,—,"{reference_number}
{name}
{subject}
{message}","CMP-202607-0007
Ahmed Al Rashid
Long wait time in OPD
Please review and respond at your earliest convenience."
email,Px digest weekly,—,"PX360 {period_label} Digest
PX360 WeeklyMonthly Digest - {period_label}
PX360 WeeklyMonthly Digest
{hospital_name} - {period_label}
{period_label}
{summary.summary_en}
- {f}
Risk Level: {summary.risk_level}
{metrics.total_complaints} Complaints
{metrics.sla_compliance}% SLA Compliance
{metrics.nps_score} NPS Score
{metrics.avg_survey_score} Avg Survey
{metrics.total_actions} Actions
{metrics.avg_resolution_hours}h Avg Resolution
Department
Risk
Level
Signals
{dept.department_name}
{dept.risk_score}%
CriticalHighMediumLow
{dept.active_signals}/5
{rec.category} ({rec.complaint_count} complaints)
{rec.problem_summary_en}
- {action}
الملخص العربي
{summary.summary_ar}
- {f}
This report was automatically generated by PX360 - Patient Experience Analytics Platform","PX360 July 2026 Digest
PX360 WeeklyMonthly Digest - July 2026
PX360 WeeklyMonthly Digest
Al Hammadi Hospital - July 2026
July 2026
5 complaints, 3 resolved this period.
- <value>
Risk Level: Medium
42 Complaints
92%% SLA Compliance
4/5 NPS Score
4/5 Avg Survey
12 Actions
28h Avg Resolution
Department
Risk
Level
Signals
Emergency Department
4/5%
CriticalHighMediumLow
3/5
Wait Time (12 complaints)
OPD wait times exceeding target.
- Follow-up call scheduled
الملخص العربي
٥ شكاوى، ٣ تم حلها.
- <value>
This report was automatically generated by PX360 - Patient Experience Analytics Platform"
email,Simple email,—,"{subject}
{content_html}","Long wait time in OPD
<value>"
email,Sla reminder,—,"{recipient.get_full_name} ,
#{complaint.id}
{complaint.title}
{complaint.get_severity_display}
{complaint.get_priority_display}
{complaint.category.get_localized_name}N/A
{complaint.department.get_localized_name}N/A
{complaint.patient.get_full_name} (MRN: {complaint.patient.mrn})N/A
{due_date}
{hours_remaining}
{complaint.get_status_display}
-
-
-
تذكير اتفاقية مستوى الخدمة - شكوى #{complaint.id}
هام: هذا تذكير بشكوى غير معينة تحتاج إلى اهتمامكم. يرجى تعيينها لأحد أعضاء الفريق المناسبين في أقرب وقت ممكن.
معلومات اتفاقية مستوى الخدمة: تاريخ الاستحقاق {due_date} - الوقت المتبقي: {hours_remaining} ساعة
يرجى مراجعة هذه الشكوى واتخاذ الإجراء المناسب قبل الموعد النهائي لتجنب تجاوزها.","Ahmed Al Rashid ,
#CMP-202607-0007
Long wait time in OPD
high
high
Ahmed Al RashidN/A
Ahmed Al RashidN/A
Ahmed Al Rashid (MRN: MRN123456)N/A
Jul 8, 2026
24
in_progress
-
-
-
تذكير اتفاقية مستوى الخدمة - شكوى #CMP-202607-0007
هام: هذا تذكير بشكوى غير معينة تحتاج إلى اهتمامكم. يرجى تعيينها لأحد أعضاء الفريق المناسبين في أقرب وقت ممكن.
معلومات اتفاقية مستوى الخدمة: تاريخ الاستحقاق Jul 8, 2026 - الوقت المتبقي: 24 ساعة
يرجى مراجعة هذه الشكوى واتخاذ الإجراء المناسب قبل الموعد النهائي لتجنب تجاوزها."
email,Sla second reminder,—,"{recipient.get_full_name} ,
#{complaint.id}
{complaint.title}
{complaint.get_severity_display}
{complaint.get_priority_display}
{complaint.category.get_localized_name}N/A
{complaint.department.get_localized_name}N/A
{complaint.patient.get_full_name} (MRN: {complaint.patient.mrn})N/A
{due_date}
{hours_remaining}
{complaint.get_status_display}
-
-
-
-
-
-
عاجل - تذكير ثاني من اتفاقية مستوى الخدمة - شكوى #{complaint.id}
تنبيه هام: هذا تذكير عاجل بشكوى غير معينة تتطلب اهتماماً فورياً. هذا التذكير النهائي قبل التصعيد التلقائي.
معلومات اتفاقية مستوى الخدمة: تاريخ الاستحقاق {due_date} - الوقت المتبقي: {hours_remaining} ساعة
يرجى المراجعة واتخاذ إجراء فوري لتجنب التصعيد وعواقب تجاوز الموعد.","Ahmed Al Rashid ,
#CMP-202607-0007
Long wait time in OPD
high
high
Ahmed Al RashidN/A
Ahmed Al RashidN/A
Ahmed Al Rashid (MRN: MRN123456)N/A
Jul 8, 2026
24
in_progress
-
-
-
-
-
-
عاجل - تذكير ثاني من اتفاقية مستوى الخدمة - شكوى #CMP-202607-0007
تنبيه هام: هذا تذكير عاجل بشكوى غير معينة تتطلب اهتماماً فورياً. هذا التذكير النهائي قبل التصعيد التلقائي.
معلومات اتفاقية مستوى الخدمة: تاريخ الاستحقاق Jul 8, 2026 - الوقت المتبقي: 24 ساعة
يرجى المراجعة واتخاذ إجراء فوري لتجنب التصعيد وعواقب تجاوز الموعد."
email,Survey invitation,—,"{patient_name} >,
Thank you for choosing Al Hammadi Hospital for your healthcare needs. We hope your recent visit on {visit} met your expectations.","Ahmed Al Rashid >,
Thank you for choosing Al Hammadi Hospital for your healthcare needs. We hope your recent visit on <value> met your expectations."
email,Survey results notification,—,"{recipient_name} ,
The patient experience survey results for {dept} are now available for review.
{overall_score}
{total_responses}
{response_rate}
{strengths}
{improvements}
{survey_period}
Please review the detailed results and prepare an action plan to address identified areas for improvement by {deadline}.
{report_date}
{survey_type}
{access_level}","Dr. Sara Al Otaibi ,
The patient experience survey results for Emergency Department are now available for review.
4.2/5
156
78%
<value>
<value>
July 2026
Please review the detailed results and prepare an action plan to address identified areas for improvement by Jul 15, 2026.
Jul 8, 2026
<value>
Medium"
email,Activation error,"{% trans ""Activation Failed"" %}",{error_message},Please review and respond.
email,Bulk invite,"{% trans ""Send Bulk Invitations"" %}","-- --
{role.name}
-- --
{hospital.get_localized_name}
1
2
3","-- --
Ahmed Al Rashid
-- --
Ahmed Al Rashid
1
2
3"
email,Category list,"{% trans ""Categories"" %}","{cat.name_en}
{cat.name_ar}
{cat.code}
{cat.checklist_items.count}
{cat.description}
*
*","Ahmed Al Rashid
Ahmed Al Rashid
378752
12
Patient waited over an hour beyond the scheduled appointment time.
*
*"
email,Checklist list,—,"{item.get_localized_text}
{item.code}
{item.description_en}
{item.category.get_localized_name}
{item.content.get_localized_title}
-
{item.order}
{item.created_at}
*
{cat.name_en}
{content_item.title_en}
*
*
*","Long wait time in OPD
378752
Please review and respond.
Ahmed Al Rashid
Long wait time in OPD
-
<value>
Jul 8, 2026
*
Ahmed Al Rashid
Long wait time in OPD
*
*
*"
email,Complete,"{% trans ""Congratulations!"" %}",,
email,Completion email,—,"{user.get_full_name}
{user.email}
{role_display}
{user.department.name}
{completed_at}
-
-
-
-","Ahmed Al Rashid
patient@example.com
<value>
Ahmed Al Rashid
Jul 8, 2026
-
-
-
-"
email,Content list,"{% trans ""Onboarding Content"" %}","{item.get_localized_title}
{item.get_localized_description}
{item.code}
{item.category.get_localized_name}
{item.created_at}
*
*
{cat.name_en}
*
*","Long wait time in OPD
Please review and respond.
378752
Ahmed Al Rashid
Jul 8, 2026
*
*
Ahmed Al Rashid
*
*"
email,Dashboard,"{% trans ""Onboarding & Acknowledgements"" %}","{stats.total_invited}
{stats.completed}
{stats.in_progress}
{stats.not_started}
{activity.get_full_name}
• {activity.acknowledgement_completed_at}
{role_data.role}
{role_data.rate}%
{role_data.completed} completed
{role_data.pending} pending
{user.first_name}{user.last_name}
{user.get_full_name}
{user.email}
{user.groups.first.name}
{user.days_remaining}
-","<value>
<value>
<value>
<value>
Ahmed Al Rashid
• Jul 8, 2026
<value>
78%%
<value> completed
<value> pending
AhmedAhmed Al Rashid
Ahmed Al Rashid
patient@example.com
Ahmed Al Rashid
<value>
-"
email,Invitation email,—,"Hello {name} ,
-
-
-
-","Hello Ahmed Al Rashid ,
-
-
-
-"
email,Preview wizard,"{% trans ""Preview Onboarding Flow"" %}","{role.name}
{role.description}
{content.get_localized_title}
{content.get_localized_description}
{item.get_localized_text}
{selected_role.name}","Ahmed Al Rashid
Patient waited over an hour beyond the scheduled appointment time.
Long wait time in OPD
Please review and respond.
Long wait time in OPD
Ahmed Al Rashid"
email,Progress detail,{{ account.get_full_name|default:account.email }},"{account.first_name}
{account.get_full_name}
{account.email}
{account.email}
{account.created_at}
{progress.overall_percentage}%
{progress.checklist_completed}/{progress.checklist_total}
{progress.content_viewed}/{progress.content_total}
{progress.current_step}
1
{progress.activation_completed_at}
2
{progress.checklist_completed_at}
3
{progress.content_completed_at}
{item.name}
{item.completed_at}","Ahmed
Ahmed Al Rashid
patient@example.com
patient@example.com
Jul 8, 2026
78%%
<value>/<value>
<value>/<value>
<value>
1
Jul 8, 2026
2
Jul 8, 2026
3
Jul 8, 2026
Ahmed Al Rashid
Jul 8, 2026"
email,Provisional list,"{% trans ""Provisional Accounts"" %}","{total_count}
{completed_count}
{in_progress_count}
{account.first_name}{account.last_name}
{account.get_full_name}
{account.email}
{account.groups.first.name}
{account.created_at}
{account.invitation_expires_at}
-
*
*
*
{hospital.get_localized_name}
{department.name}
*
{role.display_name}","12
12
12
AhmedAhmed Al Rashid
Ahmed Al Rashid
patient@example.com
Ahmed Al Rashid
Jul 8, 2026
Jul 8, 2026
-
*
*
*
Ahmed Al Rashid
Emergency Department
*
Ahmed Al Rashid"
email,Reminder email,—,"Hello {name} ,
{days_remaining} .","Hello Ahmed Al Rashid ,
<value> ."
email,Step activation,"{% trans ""Create Your Account"" %}","*
*
*
*","*
*
*
*"
email,Step checklist,"{% trans ""Acknowledgement Checklist"" %}","{acknowledged_count} {total_count}
{progress_percentage}%
{category.get_localized_name}
({items})
{item.get_localized_text}
{item.code}
{item.get_localized_description}","12 12
78%%
Ahmed Al Rashid
(<value>)
Long wait time in OPD
378752
Please review and respond."
email,Step content,{{ current_content.get_localized_title }},"{current_content.get_localized_title}
{current_content.get_localized_description}
{step} {content}
{progress_percentage}%
{forloop.counter}
{forloop.counter}
{current_content.get_localized_content}","Long wait time in OPD
Please review and respond.
<value> <value>
78%%
12
12
<value>"
email,Welcome,"{% trans ""Welcome to PX360!"" %}",,
email,Password reset email,—,"{user.email} ,
{protocol}://{domain}","patient@example.com ,
<value>://<value>"
sms,send_complaint_link,,<dynamic: message>,<dynamic: message>
sms,send_post_discharge_survey,,Your experience survey is ready: {…},Your experience survey is ready: <value>
sms,notify_admins_new_complaint,,<dynamic: sms_message>,<dynamic: sms_message>
sms,notify_staff_new_item,,<dynamic: sms_message>,<dynamic: sms_message>
sms,send_complaint_creation_sms_task,,<dynamic: sms_message>,<dynamic: sms_message>
sms,send_complaint_status_change_task,,<dynamic: sms_message>,<dynamic: sms_message>
sms,send_department_notification_task,,PX360: Complaint #{reference_number} sent to {department_name}. Review: {review_link},PX360: Complaint #CMP-202607-0007 sent to Emergency Department. Review: https://px360.app/r/CMP-202607-0007
sms,complaint_explanation_form,,PX360: Your verification code is {code}. Enter this to submit your response for complaint #{complaint.reference_number}.,PX360: Your verification code is 378752. Enter this to submit your response for complaint #CMP-202607-0007.
sms,champion_start_investigation,,You have feedback to provide for complaint #{complaint.reference_number}. Please respond at: {respond_url},You have feedback to provide for complaint #CMP-202607-0007. Please respond at: https://px360.app/r/CMP-202607-0007
sms,champion_review_answers,,PX360: Your verification code is {code}. Enter this to submit your response for complaint #{complaint.reference_number}.,PX360: Your verification code is 378752. Enter this to submit your response for complaint #CMP-202607-0007.
sms,inquiry_respond_with_token,,PX360: Your inquiry {inquiry.reference_number} has been responded to. View: {track_url},PX360: Your inquiry INQ-202607-0003 has been responded to. View: https://px360.app/t/INQ-202607-0003
sms,inquiry_respond,,PX360: Your inquiry #{inquiry.reference_number} has been responded to. View details: {track_url},PX360: Your inquiry #INQ-202607-0003 has been responded to. View details: https://px360.app/t/INQ-202607-0003
sms,inquiry_send_to,,PX360: Inquiry #{inquiry.reference_number} sent to {department.name}. Review: {link},PX360: Inquiry #INQ-202607-0003 sent to Emergency Department. Review: https://px360.app/r/CMP-202607-0007
sms,inquiry_department_response,,PX360: Your inquiry {inquiry.reference_number} has been responded to. View: {track_url},PX360: Your inquiry INQ-202607-0003 has been responded to. View: https://px360.app/t/INQ-202607-0003
sms,involved_department_response,,PX360: Your complaint {complaint.reference_number} has been responded to. View: {track_url},PX360: Your complaint CMP-202607-0007 has been responded to. View: https://px360.app/t/INQ-202607-0003
sms,observation_send_to,,PX360: Observation #{observation.reference_number} sent to {department.name}. Review: {link},PX360: Observation #CMP-202607-0007 sent to Emergency Department. Review: https://px360.app/r/CMP-202607-0007
sms,observation_department_response,,PX360: Your observation {observation.tracking_code} has been responded to. View details: {track_url},PX360: Your observation OBS-202607-0012 has been responded to. View details: https://px360.app/t/INQ-202607-0003
sms,observation_respond_with_token,,PX360: Your observation {observation.tracking_code} has been responded to. View: {track_url},PX360: Your observation OBS-202607-0012 has been responded to. View: https://px360.app/t/INQ-202607-0003
sms,SurveyDeliveryService.send_survey_sms,,<dynamic: message>,<dynamic: message>
sms,feedback_send_to,,PX360: Feedback '{feedback.title or 'Untitled'}' logged for {department.name}. {link},PX360: Feedback 'Long wait time in OPD' logged for Emergency Department. https://px360.app/r/CMP-202607-0007
sms,NotificationService.send_notification,,<dynamic: sms_message>,<dynamic: sms_message>
sms,NotificationService.send_survey_invitation,,<dynamic: message>,<dynamic: message>
sms,send_sms,,<dynamic: message>,<dynamic: message>
sms,_send_deferred_sms,,<dynamic: message>,<dynamic: message>
sms,NotificationServiceWithSettings._defer_sms_if_quiet_hours,,<dynamic: message>,<dynamic: message>
sms,NotificationServiceWithSettings.send_explanation_overdue,,PX360 ESCALATION: Explanation overdue for Complaint #{complaint.id} by {staff_name},PX360 ESCALATION: Explanation overdue for Complaint #CMP-202607-0007 by Dr. Sara Al Otaibi
sms,test_notification,,PX360 Test: Your SMS notifications are configured correctly.,PX360 Test: Your SMS notifications are configured correctly.
sms,send_sms_direct,,<dynamic: message>,<dynamic: message>
sms,send_appreciation_notification,,<dynamic: message_en>,<dynamic: message_en>
sms,appreciation_send_to,,PX360: Appreciation #{appreciation.reference_number} sent to {department.name}. {link},PX360: Appreciation #CMP-202607-0007 sent to Emergency Department. https://px360.app/r/CMP-202607-0007
1 channel purpose subject content example
2 email Appointment confirmation — {patient_name} , {patient_name} {appointment_id} {appointment_date} {appointment_time} {department} {doctor_name} {location} - - - {hospital_phone} {hospital_email} Ahmed Al Rashid , Ahmed Al Rashid APT-2026-001 Jul 8, 2026 Jul 8, 2026 Emergency Department Dr. Khalid Al Subaie Outpatient Clinics - - - +966 55 123 4567 patient@example.com
3 email Communication request notification — {reason} {patient_name} {source_user_name} {message} {request_id} Quality concern Ahmed Al Rashid Ahmed Al Rashid Please review and respond at your earliest convenience. REQ-2026-0042
4 email Explanation reminder — {staff.first_name} {staff.last_name} , #{complaint.id} {complaint.title} {complaint.description} {hours_remaining} ({due_date}) تذكير: طلب شرح - شكوى #{complaint.id} هذا تذكير بأنه تم طلب منك تقديم شرح بخصوص الشكوى التالية. موعد تقديم الشرح يتبقى {hours_remaining} ساعة (الموعد النهائي: {due_date}). يرجى تقديم الشرح قبل الموعد النهائي لتجنب التصعيد إلى مديرك المباشر. Sara Al Otaibi , #CMP-202607-0007 Long wait time in OPD Patient waited over an hour beyond the scheduled appointment time. 24 (Jul 8, 2026) تذكير: طلب شرح - شكوى #CMP-202607-0007 هذا تذكير بأنه تم طلب منك تقديم شرح بخصوص الشكوى التالية. موعد تقديم الشرح يتبقى 24 ساعة (الموعد النهائي: Jul 8, 2026). يرجى تقديم الشرح قبل الموعد النهائي لتجنب التصعيد إلى مديرك المباشر.
5 email Explanation request — {staff_name} , {custom_message} #{complaint_id} {complaint_title} {patient_name} {department_name} {due_date} {description} Dr. Sara Al Otaibi , Kindly provide a detailed explanation. #<value> Long wait time in OPD Ahmed Al Rashid Emergency Department Jul 8, 2026 Patient waited over an hour beyond the scheduled appointment time.
6 email Explanation second reminder — {staff.first_name} {staff.last_name} , #{complaint.id} {complaint.title} {complaint.description} {hours_remaining} ({due_date}) تذكير نهائي وعاجل: طلب شرح - شكوى #{complaint.id} هذا تذكيرك النهائي بأنه تم طلب منك تقديم شرح بخصوص الشكوى التالية. مهم: إذا لم تقدم شرحك قبل الموعد النهائي، سيتم تصعيد هذا الأمر إلى مديرك المباشر لاتخاذ الإجراء اللازم. يرجى تقديم الشرح فوراً لتجنب التصعيد. Sara Al Otaibi , #CMP-202607-0007 Long wait time in OPD Patient waited over an hour beyond the scheduled appointment time. 24 (Jul 8, 2026) تذكير نهائي وعاجل: طلب شرح - شكوى #CMP-202607-0007 هذا تذكيرك النهائي بأنه تم طلب منك تقديم شرح بخصوص الشكوى التالية. مهم: إذا لم تقدم شرحك قبل الموعد النهائي، سيتم تصعيد هذا الأمر إلى مديرك المباشر لاتخاذ الإجراء اللازم. يرجى تقديم الشرح فوراً لتجنب التصعيد.
7 email Implementation status Email Templates - Implementation Status Email Templates - Implementation Status 🏥 Email Template System Al Hammadi Hospital - Unified Brand Identity 🎨 Brand Color Palette Primary Navy #005696 Accent Blue #007bbd Light Background #eef6fb Slate Gray #64748b 👥 Patient-Facing Templates Emails sent to patients Survey Invitation templates/emails/survey_invitation.html Usage: Sent after patient visits for feedback collection Appointment Confirmation templates/emails/appointment_confirmation.html Usage: Sent when appointments are booked Survey Results Notification templates/emails/survey_results_notification.html Usage: Department heads notified of survey results 👨‍⚕️ Staff/Admin Templates Internal communication emails Explanation Request INTEGRATED templates/emails/explanation_request.html Integration: apps/complaints/tasks.py Function: send_explanation_request_email() User Invitation INTEGRATED templates/accounts/onboarding/invitation_email.html Integration: apps/accounts/services.py Function: EmailService.send_invitation_email() Invitation Reminder INTEGRATED templates/accounts/onboarding/reminder_email.html Integration: apps/accounts/services.py Function: EmailService.send_reminder_email() Onboarding Completion INTEGRATED templates/accounts/onboarding/completion_email.html Integration: apps/accounts/services.py Function: EmailService.send_completion_notification() Password Reset INTEGRATED templates/accounts/email/password_reset_email.html Integration: Django Authentication System 🔌 Integration Points Complaints System apps/complaints/tasks.py send_explanation_request_email(explanation_id) Sends branded explanation request emails to staff when complaints are filed. Accounts Service apps/accounts/services.py EmailService.send_*_email() All onboarding emails (invitation, reminder, completion) use branded templates. Notifications Service apps/notifications/services.py NotificationService.send_email() Unified email service with HTML support and database logging. Base Template templates/emails/ All email templates extend the base template for consistent branding. Al Hammadi Hospital Email Template System Patient Experience Management Department Created on March 12, 2026 Documentation: templates/emails/README_EMAIL_TEMPLATES.md Email Templates - Implementation Status 🏥 Email Template System Al Hammadi Hospital - Unified Brand Identity 🎨 Brand Color Palette Primary Navy #005696 Accent Blue #007bbd Light Background #eef6fb Slate Gray #64748b 👥 Patient-Facing Templates Emails sent to patients Survey Invitation templates/emails/survey_invitation.html Usage: Sent after patient visits for feedback collection Appointment Confirmation templates/emails/appointment_confirmation.html Usage: Sent when appointments are booked Survey Results Notification templates/emails/survey_results_notification.html Usage: Department heads notified of survey results 👨‍⚕️ Staff/Admin Templates Internal communication emails Explanation Request INTEGRATED templates/emails/explanation_request.html Integration: apps/complaints/tasks.py Function: send_explanation_request_email() User Invitation INTEGRATED templates/accounts/onboarding/invitation_email.html Integration: apps/accounts/services.py Function: EmailService.send_invitation_email() Invitation Reminder INTEGRATED templates/accounts/onboarding/reminder_email.html Integration: apps/accounts/services.py Function: EmailService.send_reminder_email() Onboarding Completion INTEGRATED templates/accounts/onboarding/completion_email.html Integration: apps/accounts/services.py Function: EmailService.send_completion_notification() Password Reset INTEGRATED templates/accounts/email/password_reset_email.html Integration: Django Authentication System 🔌 Integration Points Complaints System apps/complaints/tasks.py send_explanation_request_email(explanation_id) Sends branded explanation request emails to staff when complaints are filed. Accounts Service apps/accounts/services.py EmailService.send_*_email() All onboarding emails (invitation, reminder, completion) use branded templates. Notifications Service apps/notifications/services.py NotificationService.send_email() Unified email service with HTML support and database logging. Base Template templates/emails/ All email templates extend the base template for consistent branding. Al Hammadi Hospital Email Template System Patient Experience Management Department Created on March 12, 2026 Documentation: templates/emails/README_EMAIL_TEMPLATES.md
8 email Inquiry dept response escalation — {recipient_name} , {inquiry.reference_number} {inquiry.subject} {department_name} {sla_due_at} {hours_overdue} تصعيد - رد القسم متأخر - {inquiry.reference_number} موعد الاستحقاق: {sla_due_at} - ساعات التأخير: {hours_overdue} Dr. Sara Al Otaibi , INQ-202607-0003 Long wait time in OPD Emergency Department Jul 8, 2026 6 تصعيد - رد القسم متأخر - INQ-202607-0003 موعد الاستحقاق: Jul 8, 2026 - ساعات التأخير: 6
9 email Inquiry dept response reminder — {recipient_name} , {inquiry.reference_number} {inquiry.subject} {department_name} {sla_due_at} {hours_remaining} تذكير - مطلوب رد القسم - {inquiry.reference_number} موعد الاستحقاق: {sla_due_at} - الوقت المتبقي: {hours_remaining} ساعة Dr. Sara Al Otaibi , INQ-202607-0003 Long wait time in OPD Emergency Department Jul 8, 2026 24 تذكير - مطلوب رد القسم - INQ-202607-0003 موعد الاستحقاق: Jul 8, 2026 - الوقت المتبقي: 24 ساعة
10 email Inquiry explanation request — {staff_name}, #{inquiry_reference} {inquiry_subject} {inquiry_message} {request_message} {explanation_url} Dr. Sara Al Otaibi, #CMP-202607-0007 Long wait time in OPD Please review and respond. Please review and respond. https://px360.app/explain/abc123
11 email Invitation expired — {user.first_name} , Ahmed ,
12 email New appreciation notification — {recipient_name} , : APR-{reference} : {sender_name} : {hospital_name} : {department_name} : {category} : {message_en} : {message_ar} {notification_type} {current_time} Dr. Sara Al Otaibi , : APR-CMP-202607-0007 : Ahmed Al Rashid : Al Hammadi Hospital : Emergency Department : Wait Time : Please review and respond. : Please review and respond. Complaint Update Jul 8, 2026
13 email New complaint admin notification — {priority_badge} complaint: {complaint_title} {admin_name} >, : {reference_number} : {complaint_title} : {priority} : {severity} : {patient_name} : {hospital_name} : {department_name} : {description} {notification_type} {current_time} high complaint: Long wait time in OPD Mohammed Al Harbi >, : CMP-202607-0007 : Long wait time in OPD : high : medium : Ahmed Al Rashid : Al Hammadi Hospital : Emergency Department : Patient waited over an hour beyond the scheduled appointment time. Complaint Update Jul 8, 2026
14 email New inquiry notification — {recipient_name} , : {reference_number} : {subject} : {category} : {priority} : {contact_name} : {hospital_name} : {department_name} : {message} {notification_type} {current_time} Dr. Sara Al Otaibi , : CMP-202607-0007 : Long wait time in OPD : Wait Time : high : Ahmed Al Rashid : Al Hammadi Hospital : Emergency Department : Please review and respond at your earliest convenience. Complaint Update Jul 8, 2026
15 email New observation notification — {recipient_name} , {observation.tracking_code} {observation.title} {observation.category.name_en}N/A {observation.get_status_display} {observation.assigned_department.name} Dr. Sara Al Otaibi , OBS-202607-0012 Long wait time in OPD Ahmed Al RashidN/A in_progress Ahmed Al Rashid
16 email New suggestion notification — {recipient_name} , : SG-{reference} : {title} : {category} : {priority} : {contact_name} : {hospital_name} : {department_name} : {message} {notification_type} {current_time} Dr. Sara Al Otaibi , : SG-CMP-202607-0007 : Long wait time in OPD : Wait Time : high : Ahmed Al Rashid : Al Hammadi Hospital : Emergency Department : Please review and respond at your earliest convenience. Complaint Update Jul 8, 2026
17 email Observation assigned — {recipient_name} , {observation.tracking_code} {observation.title} {observation.category.name_en}N/A {observation.get_severity_display} {observation.location_text} {observation.hospital.name} {observation.assigned_department.name} {observation.due_at} {observation.description} - - - تم تعيين ملاحظة لك - {observation.tracking_code} تم تعيين ملاحظة لكم للمراجعة واتخاذ الإجراء اللازم. يرجى الاطلاع على التفاصيل أدناه. Dr. Sara Al Otaibi , OBS-202607-0012 Long wait time in OPD Ahmed Al RashidN/A high Outpatient Clinics Ahmed Al Rashid Ahmed Al Rashid Jul 11, 2026 Patient waited over an hour beyond the scheduled appointment time. - - - تم تعيين ملاحظة لك - OBS-202607-0012 تم تعيين ملاحظة لكم للمراجعة واتخاذ الإجراء اللازم. يرجى الاطلاع على التفاصيل أدناه.
18 email Observation dept response escalation — {recipient_name} , {observation.tracking_code} {observation.title} {department_name} {sla_due_at} {hours_overdue} تصعيد - رد القسم متأخر - {observation.tracking_code} موعد الاستحقاق: {sla_due_at} - ساعات التأخير: {hours_overdue} Dr. Sara Al Otaibi , OBS-202607-0012 Long wait time in OPD Emergency Department Jul 8, 2026 6 تصعيد - رد القسم متأخر - OBS-202607-0012 موعد الاستحقاق: Jul 8, 2026 - ساعات التأخير: 6
19 email Observation dept response reminder — {recipient_name} , {observation.tracking_code} {observation.title} {department_name} {sla_due_at} {hours_remaining} تذكير - مطلوب رد القسم - {observation.tracking_code} موعد الاستحقاق: {sla_due_at} - الوقت المتبقي: {hours_remaining} ساعة Dr. Sara Al Otaibi , OBS-202607-0012 Long wait time in OPD Emergency Department Jul 8, 2026 24 تذكير - مطلوب رد القسم - OBS-202607-0012 موعد الاستحقاق: Jul 8, 2026 - الوقت المتبقي: 24 ساعة
20 email Observation monthly followup — {recipient_name} , {observation.tracking_code} {observation.title} {observation.category.name_en}N/A {observation.get_status_display} {observation.assigned_department.name} {observation.resolved_at} {observation.resolution_notes} - - - متابعة شهرية مطلوبة - {observation.tracking_code} ملاحظة سابقة الحل تحتاج إلى مراجعة المتابعة الشهرية. يرجى التحقق من استمرار فعالية الإجراءات التصحيحية. Dr. Sara Al Otaibi , OBS-202607-0012 Long wait time in OPD Ahmed Al RashidN/A in_progress Ahmed Al Rashid Jul 8, 2026 Please review and respond. - - - متابعة شهرية مطلوبة - OBS-202607-0012 ملاحظة سابقة الحل تحتاج إلى مراجعة المتابعة الشهرية. يرجى التحقق من استمرار فعالية الإجراءات التصحيحية.
21 email Observation resolved — {recipient_name} , An observation assigned to you has been {status}. Please review the resolution details below. {observation.tracking_code} {observation.title} {observation.category.name_en}N/A {observation.get_status_display} {observation.assigned_department.name} {observation.resolved_at} {observation.resolution_notes} تم {status_display_ar} الملاحظة - {observation.tracking_code} تم تحديث حالة الملاحظة. يرجى مراجعة تفاصيل الحل. Dr. Sara Al Otaibi , An observation assigned to you has been in_progress. Please review the resolution details below. OBS-202607-0012 Long wait time in OPD Ahmed Al RashidN/A in_progress Ahmed Al Rashid Jul 8, 2026 Please review and respond. تم in_progress الملاحظة - OBS-202607-0012 تم تحديث حالة الملاحظة. يرجى مراجعة تفاصيل الحل.
22 email Observation sla reminder — {recipient_name} , {observation.tracking_code} {observation.title} {observation.category.name_en}N/A {observation.get_severity_display} {observation.get_status_display} {observation.location_text} {due_date} {hours_remaining} - - - تذكير بموعد الاستحقاق - {observation.tracking_code} هام: هذه ملاحظة غير معينة تحتاج إلى اهتمامكم. يرجى تعيينها في أقرب وقت ممكن. تاريخ الاستحقاق: {due_date} - الوقت المتبقي: {hours_remaining} ساعة Dr. Sara Al Otaibi , OBS-202607-0012 Long wait time in OPD Ahmed Al RashidN/A high in_progress Outpatient Clinics Jul 8, 2026 24 - - - تذكير بموعد الاستحقاق - OBS-202607-0012 هام: هذه ملاحظة غير معينة تحتاج إلى اهتمامكم. يرجى تعيينها في أقرب وقت ممكن. تاريخ الاستحقاق: Jul 8, 2026 - الوقت المتبقي: 24 ساعة
23 email Observation sla second reminder — {recipient_name} , {observation.tracking_code} {observation.title} {observation.category.name_en}N/A {observation.get_severity_display} {observation.get_status_display} {due_date} {hours_remaining} - - - - تذكير نهائي عاجل - {observation.tracking_code} هذا هو التذكير النهائي. الملاحظة على وشك تجاوز الموعد النهائي. يرجى اتخاذ الإجراء فوراً. تاريخ الاستحقاق: {due_date} - الوقت المتبقي: {hours_remaining} ساعة Dr. Sara Al Otaibi , OBS-202607-0012 Long wait time in OPD Ahmed Al RashidN/A high in_progress Jul 8, 2026 24 - - - - تذكير نهائي عاجل - OBS-202607-0012 هذا هو التذكير النهائي. الملاحظة على وشك تجاوز الموعد النهائي. يرجى اتخاذ الإجراء فوراً. تاريخ الاستحقاق: Jul 8, 2026 - الوقت المتبقي: 24 ساعة
24 email Public inquiry notification — {reference_number} {name} {subject} {message} CMP-202607-0007 Ahmed Al Rashid Long wait time in OPD Please review and respond at your earliest convenience.
25 email Px digest weekly — PX360 {period_label} Digest PX360 WeeklyMonthly Digest - {period_label} PX360 WeeklyMonthly Digest {hospital_name} - {period_label} {period_label} {summary.summary_en} - {f} Risk Level: {summary.risk_level} {metrics.total_complaints} Complaints {metrics.sla_compliance}% SLA Compliance {metrics.nps_score} NPS Score {metrics.avg_survey_score} Avg Survey {metrics.total_actions} Actions {metrics.avg_resolution_hours}h Avg Resolution Department Risk Level Signals {dept.department_name} {dept.risk_score}% CriticalHighMediumLow {dept.active_signals}/5 {rec.category} ({rec.complaint_count} complaints) {rec.problem_summary_en} - {action} الملخص العربي {summary.summary_ar} - {f} This report was automatically generated by PX360 - Patient Experience Analytics Platform PX360 July 2026 Digest PX360 WeeklyMonthly Digest - July 2026 PX360 WeeklyMonthly Digest Al Hammadi Hospital - July 2026 July 2026 5 complaints, 3 resolved this period. - <value> Risk Level: Medium 42 Complaints 92%% SLA Compliance 4/5 NPS Score 4/5 Avg Survey 12 Actions 28h Avg Resolution Department Risk Level Signals Emergency Department 4/5% CriticalHighMediumLow 3/5 Wait Time (12 complaints) OPD wait times exceeding target. - Follow-up call scheduled الملخص العربي ٥ شكاوى، ٣ تم حلها. - <value> This report was automatically generated by PX360 - Patient Experience Analytics Platform
26 email Simple email — {subject} {content_html} Long wait time in OPD <value>
27 email Sla reminder — {recipient.get_full_name} , #{complaint.id} {complaint.title} {complaint.get_severity_display} {complaint.get_priority_display} {complaint.category.get_localized_name}N/A {complaint.department.get_localized_name}N/A {complaint.patient.get_full_name} (MRN: {complaint.patient.mrn})N/A {due_date} {hours_remaining} {complaint.get_status_display} - - - تذكير اتفاقية مستوى الخدمة - شكوى #{complaint.id} هام: هذا تذكير بشكوى غير معينة تحتاج إلى اهتمامكم. يرجى تعيينها لأحد أعضاء الفريق المناسبين في أقرب وقت ممكن. معلومات اتفاقية مستوى الخدمة: تاريخ الاستحقاق {due_date} - الوقت المتبقي: {hours_remaining} ساعة يرجى مراجعة هذه الشكوى واتخاذ الإجراء المناسب قبل الموعد النهائي لتجنب تجاوزها. Ahmed Al Rashid , #CMP-202607-0007 Long wait time in OPD high high Ahmed Al RashidN/A Ahmed Al RashidN/A Ahmed Al Rashid (MRN: MRN123456)N/A Jul 8, 2026 24 in_progress - - - تذكير اتفاقية مستوى الخدمة - شكوى #CMP-202607-0007 هام: هذا تذكير بشكوى غير معينة تحتاج إلى اهتمامكم. يرجى تعيينها لأحد أعضاء الفريق المناسبين في أقرب وقت ممكن. معلومات اتفاقية مستوى الخدمة: تاريخ الاستحقاق Jul 8, 2026 - الوقت المتبقي: 24 ساعة يرجى مراجعة هذه الشكوى واتخاذ الإجراء المناسب قبل الموعد النهائي لتجنب تجاوزها.
28 email Sla second reminder — {recipient.get_full_name} , #{complaint.id} {complaint.title} {complaint.get_severity_display} {complaint.get_priority_display} {complaint.category.get_localized_name}N/A {complaint.department.get_localized_name}N/A {complaint.patient.get_full_name} (MRN: {complaint.patient.mrn})N/A {due_date} {hours_remaining} {complaint.get_status_display} - - - - - - عاجل - تذكير ثاني من اتفاقية مستوى الخدمة - شكوى #{complaint.id} تنبيه هام: هذا تذكير عاجل بشكوى غير معينة تتطلب اهتماماً فورياً. هذا التذكير النهائي قبل التصعيد التلقائي. معلومات اتفاقية مستوى الخدمة: تاريخ الاستحقاق {due_date} - الوقت المتبقي: {hours_remaining} ساعة يرجى المراجعة واتخاذ إجراء فوري لتجنب التصعيد وعواقب تجاوز الموعد. Ahmed Al Rashid , #CMP-202607-0007 Long wait time in OPD high high Ahmed Al RashidN/A Ahmed Al RashidN/A Ahmed Al Rashid (MRN: MRN123456)N/A Jul 8, 2026 24 in_progress - - - - - - عاجل - تذكير ثاني من اتفاقية مستوى الخدمة - شكوى #CMP-202607-0007 تنبيه هام: هذا تذكير عاجل بشكوى غير معينة تتطلب اهتماماً فورياً. هذا التذكير النهائي قبل التصعيد التلقائي. معلومات اتفاقية مستوى الخدمة: تاريخ الاستحقاق Jul 8, 2026 - الوقت المتبقي: 24 ساعة يرجى المراجعة واتخاذ إجراء فوري لتجنب التصعيد وعواقب تجاوز الموعد.
29 email Survey invitation — {patient_name} >, Thank you for choosing Al Hammadi Hospital for your healthcare needs. We hope your recent visit on {visit} met your expectations. Ahmed Al Rashid >, Thank you for choosing Al Hammadi Hospital for your healthcare needs. We hope your recent visit on <value> met your expectations.
30 email Survey results notification — {recipient_name} , The patient experience survey results for {dept} are now available for review. {overall_score} {total_responses} {response_rate} {strengths} {improvements} {survey_period} Please review the detailed results and prepare an action plan to address identified areas for improvement by {deadline}. {report_date} {survey_type} {access_level} Dr. Sara Al Otaibi , The patient experience survey results for Emergency Department are now available for review. 4.2/5 156 78% <value> <value> July 2026 Please review the detailed results and prepare an action plan to address identified areas for improvement by Jul 15, 2026. Jul 8, 2026 <value> Medium
31 email Activation error {% trans "Activation Failed" %} {error_message} Please review and respond.
32 email Bulk invite {% trans "Send Bulk Invitations" %} -- -- {role.name} -- -- {hospital.get_localized_name} 1 2 3 -- -- Ahmed Al Rashid -- -- Ahmed Al Rashid 1 2 3
33 email Category list {% trans "Categories" %} {cat.name_en} {cat.name_ar} {cat.code} {cat.checklist_items.count} {cat.description} * * Ahmed Al Rashid Ahmed Al Rashid 378752 12 Patient waited over an hour beyond the scheduled appointment time. * *
34 email Checklist list — {item.get_localized_text} {item.code} {item.description_en} {item.category.get_localized_name} {item.content.get_localized_title} - {item.order} {item.created_at} * {cat.name_en} {content_item.title_en} * * * Long wait time in OPD 378752 Please review and respond. Ahmed Al Rashid Long wait time in OPD - <value> Jul 8, 2026 * Ahmed Al Rashid Long wait time in OPD * * *
35 email Complete {% trans "Congratulations!" %}
36 email Completion email — {user.get_full_name} {user.email} {role_display} {user.department.name} {completed_at} - - - - Ahmed Al Rashid patient@example.com <value> Ahmed Al Rashid Jul 8, 2026 - - - -
37 email Content list {% trans "Onboarding Content" %} {item.get_localized_title} {item.get_localized_description} {item.code} {item.category.get_localized_name} {item.created_at} * * {cat.name_en} * * Long wait time in OPD Please review and respond. 378752 Ahmed Al Rashid Jul 8, 2026 * * Ahmed Al Rashid * *
38 email Dashboard {% trans "Onboarding & Acknowledgements" %} {stats.total_invited} {stats.completed} {stats.in_progress} {stats.not_started} {activity.get_full_name} • {activity.acknowledgement_completed_at} {role_data.role} {role_data.rate}% {role_data.completed} completed {role_data.pending} pending {user.first_name}{user.last_name} {user.get_full_name} {user.email} {user.groups.first.name} {user.days_remaining} - <value> <value> <value> <value> Ahmed Al Rashid • Jul 8, 2026 <value> 78%% <value> completed <value> pending AhmedAhmed Al Rashid Ahmed Al Rashid patient@example.com Ahmed Al Rashid <value> -
39 email Invitation email — Hello {name} , - - - - Hello Ahmed Al Rashid , - - - -
40 email Preview wizard {% trans "Preview Onboarding Flow" %} {role.name} {role.description} {content.get_localized_title} {content.get_localized_description} {item.get_localized_text} {selected_role.name} Ahmed Al Rashid Patient waited over an hour beyond the scheduled appointment time. Long wait time in OPD Please review and respond. Long wait time in OPD Ahmed Al Rashid
41 email Progress detail {{ account.get_full_name|default:account.email }} {account.first_name} {account.get_full_name} {account.email} {account.email} {account.created_at} {progress.overall_percentage}% {progress.checklist_completed}/{progress.checklist_total} {progress.content_viewed}/{progress.content_total} {progress.current_step} 1 {progress.activation_completed_at} 2 {progress.checklist_completed_at} 3 {progress.content_completed_at} {item.name} {item.completed_at} Ahmed Ahmed Al Rashid patient@example.com patient@example.com Jul 8, 2026 78%% <value>/<value> <value>/<value> <value> 1 Jul 8, 2026 2 Jul 8, 2026 3 Jul 8, 2026 Ahmed Al Rashid Jul 8, 2026
42 email Provisional list {% trans "Provisional Accounts" %} {total_count} {completed_count} {in_progress_count} {account.first_name}{account.last_name} {account.get_full_name} {account.email} {account.groups.first.name} {account.created_at} {account.invitation_expires_at} - * * * {hospital.get_localized_name} {department.name} * {role.display_name} 12 12 12 AhmedAhmed Al Rashid Ahmed Al Rashid patient@example.com Ahmed Al Rashid Jul 8, 2026 Jul 8, 2026 - * * * Ahmed Al Rashid Emergency Department * Ahmed Al Rashid
43 email Reminder email — Hello {name} , {days_remaining} . Hello Ahmed Al Rashid , <value> .
44 email Step activation {% trans "Create Your Account" %} * * * * * * * *
45 email Step checklist {% trans "Acknowledgement Checklist" %} {acknowledged_count} {total_count} {progress_percentage}% {category.get_localized_name} ({items}) {item.get_localized_text} {item.code} {item.get_localized_description} 12 12 78%% Ahmed Al Rashid (<value>) Long wait time in OPD 378752 Please review and respond.
46 email Step content {{ current_content.get_localized_title }} {current_content.get_localized_title} {current_content.get_localized_description} {step} {content} {progress_percentage}% {forloop.counter} {forloop.counter} {current_content.get_localized_content} Long wait time in OPD Please review and respond. <value> <value> 78%% 12 12 <value>
47 email Welcome {% trans "Welcome to PX360!" %}
48 email Password reset email — {user.email} , {protocol}://{domain} patient@example.com , <value>://<value>
49 sms send_complaint_link <dynamic: message> <dynamic: message>
50 sms send_post_discharge_survey Your experience survey is ready: {…} Your experience survey is ready: <value>
51 sms notify_admins_new_complaint <dynamic: sms_message> <dynamic: sms_message>
52 sms notify_staff_new_item <dynamic: sms_message> <dynamic: sms_message>
53 sms send_complaint_creation_sms_task <dynamic: sms_message> <dynamic: sms_message>
54 sms send_complaint_status_change_task <dynamic: sms_message> <dynamic: sms_message>
55 sms send_department_notification_task PX360: Complaint #{reference_number} sent to {department_name}. Review: {review_link} PX360: Complaint #CMP-202607-0007 sent to Emergency Department. Review: https://px360.app/r/CMP-202607-0007
56 sms complaint_explanation_form PX360: Your verification code is {code}. Enter this to submit your response for complaint #{complaint.reference_number}. PX360: Your verification code is 378752. Enter this to submit your response for complaint #CMP-202607-0007.
57 sms champion_start_investigation You have feedback to provide for complaint #{complaint.reference_number}. Please respond at: {respond_url} You have feedback to provide for complaint #CMP-202607-0007. Please respond at: https://px360.app/r/CMP-202607-0007
58 sms champion_review_answers PX360: Your verification code is {code}. Enter this to submit your response for complaint #{complaint.reference_number}. PX360: Your verification code is 378752. Enter this to submit your response for complaint #CMP-202607-0007.
59 sms inquiry_respond_with_token PX360: Your inquiry {inquiry.reference_number} has been responded to. View: {track_url} PX360: Your inquiry INQ-202607-0003 has been responded to. View: https://px360.app/t/INQ-202607-0003
60 sms inquiry_respond PX360: Your inquiry #{inquiry.reference_number} has been responded to. View details: {track_url} PX360: Your inquiry #INQ-202607-0003 has been responded to. View details: https://px360.app/t/INQ-202607-0003
61 sms inquiry_send_to PX360: Inquiry #{inquiry.reference_number} sent to {department.name}. Review: {link} PX360: Inquiry #INQ-202607-0003 sent to Emergency Department. Review: https://px360.app/r/CMP-202607-0007
62 sms inquiry_department_response PX360: Your inquiry {inquiry.reference_number} has been responded to. View: {track_url} PX360: Your inquiry INQ-202607-0003 has been responded to. View: https://px360.app/t/INQ-202607-0003
63 sms involved_department_response PX360: Your complaint {complaint.reference_number} has been responded to. View: {track_url} PX360: Your complaint CMP-202607-0007 has been responded to. View: https://px360.app/t/INQ-202607-0003
64 sms observation_send_to PX360: Observation #{observation.reference_number} sent to {department.name}. Review: {link} PX360: Observation #CMP-202607-0007 sent to Emergency Department. Review: https://px360.app/r/CMP-202607-0007
65 sms observation_department_response PX360: Your observation {observation.tracking_code} has been responded to. View details: {track_url} PX360: Your observation OBS-202607-0012 has been responded to. View details: https://px360.app/t/INQ-202607-0003
66 sms observation_respond_with_token PX360: Your observation {observation.tracking_code} has been responded to. View: {track_url} PX360: Your observation OBS-202607-0012 has been responded to. View: https://px360.app/t/INQ-202607-0003
67 sms SurveyDeliveryService.send_survey_sms <dynamic: message> <dynamic: message>
68 sms feedback_send_to PX360: Feedback '{feedback.title or 'Untitled'}' logged for {department.name}. {link} PX360: Feedback 'Long wait time in OPD' logged for Emergency Department. https://px360.app/r/CMP-202607-0007
69 sms NotificationService.send_notification <dynamic: sms_message> <dynamic: sms_message>
70 sms NotificationService.send_survey_invitation <dynamic: message> <dynamic: message>
71 sms send_sms <dynamic: message> <dynamic: message>
72 sms _send_deferred_sms <dynamic: message> <dynamic: message>
73 sms NotificationServiceWithSettings._defer_sms_if_quiet_hours <dynamic: message> <dynamic: message>
74 sms NotificationServiceWithSettings.send_explanation_overdue PX360 ESCALATION: Explanation overdue for Complaint #{complaint.id} by {staff_name} PX360 ESCALATION: Explanation overdue for Complaint #CMP-202607-0007 by Dr. Sara Al Otaibi
75 sms test_notification PX360 Test: Your SMS notifications are configured correctly. PX360 Test: Your SMS notifications are configured correctly.
76 sms send_sms_direct <dynamic: message> <dynamic: message>
77 sms send_appreciation_notification <dynamic: message_en> <dynamic: message_en>
78 sms appreciation_send_to PX360: Appreciation #{appreciation.reference_number} sent to {department.name}. {link} PX360: Appreciation #CMP-202607-0007 sent to Emergency Department. https://px360.app/r/CMP-202607-0007

942
exports/templates.html Normal file
View File

File diff suppressed because one or more lines are too long

BIN
locale/ar/LC_MESSAGES/django.mo
View File

Binary file not shown.

3760
locale/ar/LC_MESSAGES/django.po
View File

File diff suppressed because it is too large Load Diff

157
requirements.txt
View File

@ -3,26 +3,49 @@ aiohttp==3.13.3
aiohttp-retry==2.9.1
aiosignal==1.4.0
amqp==5.3.1
annotated-doc==0.0.4
annotated-types==0.7.0
ansible==9.2.0
ansible-core==2.16.3
anyio==4.12.0
apache-libcloud==3.4.1
argcomplete==3.1.4
asgiref==3.11.0
attrs==25.4.0
Babel==2.10.3
beautifulsoup4==4.12.3
billiard==4.2.4
blinker==1.7.0
Brlapi==0.8.5
brotli==1.2.0
build==1.4.2
cachetools==6.2.4
ccsm==0.9.14.2
celery==5.6.2
certifi==2026.1.4
cffi==2.0.0
chardet==5.2.0
charset-normalizer==3.4.4
click==8.3.1
click-didyoumean==0.3.1
click-plugins==1.1.1.2
click-repl==0.3.0
cryptography==46.0.7
colorama==0.4.6
command-not-found==0.3
compizconfig-python==0.9.14.2
configobj==5.0.8
cron-descriptor==1.4.5
cryptography==41.0.7
cssselect2==0.8.0
cupshelpers==1.0
datastar-py==1.0.0
dbus-python==1.3.2
defer==1.0.6
deprecation==2.0.7
dill==0.3.8
distro==1.9.0
django==6.0.1
Django==6.0.1
-e git+https://github.com/ismail-mosa/django-ai-po.git@764db954b4a7f54f3d82637181c07181490c6da9#egg=django_ai_po
django-appconf==1.2.0
django-celery-beat==2.9.0
django-cryptography==1.1
@ -33,15 +56,21 @@ django-stubs==5.2.8
django-stubs-ext==5.2.8
django-timezone-field==7.2.1
djangorestframework==3.16.1
djangorestframework-simplejwt==5.5.1
djangorestframework-stubs==3.16.6
djangorestframework_simplejwt==5.5.1
dnspython==2.6.1
docutils==0.22.4
drf-spectacular==0.29.0
et-xmlfile==2.0.0
et_xmlfile==2.0.0
eyed3==0.9.7
fastuuid==0.14.0
filelock==3.20.2
filetype==1.2.0
fonttools==4.61.1
frozenlist==1.8.0
fsspec==2025.12.0
gitdb==4.0.12
GitPython==3.1.46
google-api-core==2.29.0
google-api-python-client==2.187.0
google-auth==2.41.1
@ -52,96 +81,180 @@ grpcio==1.67.1
gunicorn==23.0.0
h11==0.16.0
hf-xet==1.2.0
html2text==2024.2.26
httpcore==1.0.9
httplib2==0.31.0
httpx==0.28.1
huggingface-hub==1.2.3
huggingface_hub==1.2.3
id==1.6.1
idna==3.11
importlib-metadata==8.7.1
ifaddr==0.2.0
ImageIO==2.37.3
imageio-ffmpeg==0.6.0
IMDbPY==2021.4.18
importlib_metadata==8.7.1
inflection==0.5.1
jinja2==3.1.6
iniconfig==2.3.0
jaraco.classes==3.4.0
jaraco.context==6.1.2
jaraco.functools==4.4.0
jeepney==0.9.0
Jinja2==3.1.6
jiter==0.12.0
jmespath==1.0.1
jsonschema==4.25.1
jsonschema-specifications==2025.9.1
keyring==25.7.0
kombu==5.6.2
language-selector==0.1
launchpadlib==1.11.0
lazr.restfulclient==0.14.6
lazr.uri==1.0.6
libevdev==0.5
litellm==1.80.11
lockfile==0.12.2
louis==3.29.0
lxml==5.2.1
Mako==1.3.2.dev0
Markdown==3.5.2
markdown-it-py==4.0.0
markupsafe==3.0.3
MarkupSafe==3.0.3
mdurl==0.1.2
more-itertools==11.0.2
multidict==6.7.0
multiprocess==0.70.16
mutagen==1.46.0
netaddr==0.8.0
netifaces==0.11.0
nh3==0.3.4
ntlm-auth==1.5.0
numpy==2.4.3
oauthlib==3.3.1
onboard==1.4.1
openai==2.14.0
openpyxl==3.1.5
packaging==25.0
PAM==0.4.2
pandas==3.0.1
passlib==1.7.4
pdf2image==1.17.0
pexpect==4.9.0
pillow==12.1.0
pip==24.0
pluggy==1.6.0
polib==1.2.0
prompt-toolkit==3.0.52
prompt_toolkit==3.0.52
propcache==0.4.1
proto-plus==1.27.0
protobuf==6.33.3
psutil==5.9.8
psycopg2-binary==2.9.11
-e file:///home/ismail/projects/HH
ptyprocess==0.7.0
-e git+https://gitea.tenhal.sa/marwan/HH.git@d63ed6f95603768b73378c5925ee1301aa871d49#egg=px360
pyasn1==0.6.1
pyasn1-modules==0.4.2
pyasn1_modules==0.4.2
pycairo==1.25.1
pycparser==2.23
pycryptodomex==3.20.0
pycups==2.0.1
pycurl==7.45.3
pydantic==2.12.5
pydantic-core==2.41.5
pydantic_core==2.41.5
pydyf==0.12.1
pygments==2.19.2
pyjwt==2.10.1
pyelftools==0.30
Pygments==2.19.2
PyGObject==3.48.2
PyICU==2.12
PyJWT==2.10.1
pykerberos==1.1.14
PyNaCl==1.5.0
pyparsing==3.3.1
pyparted==3.12.0
pyphen==0.17.2
pypng==0.20231004.0
pyproject_hooks==1.2.0
pytest==9.0.3
pytest-django==4.12.0
python-apt==2.7.7+ubuntu5.2
python-crontab==3.3.0
python-dateutil==2.9.0.post0
python-debian==0.1.49+ubuntu2
python-dotenv==1.2.1
python-gnupg==0.5.2
python-xlib==0.33
pytz==2025.2
pyyaml==6.0.3
pyudev==0.24.0
pywinrm==0.4.3
pyxdg==0.28
PyYAML==6.0.3
qrcode==7.4.2
readme_renderer==44.0
redis==7.1.0
referencing==0.37.0
regex==2025.11.3
repolib==2.2.1
reportlab==4.4.7
requests==2.32.5
requests-file==1.5.1
requests-ntlm==1.1.0
requests-oauthlib==2.0.0
requests-toolbelt==1.0.0
resolvelib==1.0.1
rfc3986==2.0.0
rich==14.2.0
rpds-py==0.30.0
rsa==4.9.1
SecretStorage==3.5.0
selinux @ file:///build/libselinux-IVxPh3/libselinux-3.5/src
setproctitle==1.3.3
setuptools==82.0.1
shellingham==1.5.4
simplejson==3.19.2
six==1.17.0
smmap==5.0.3
sniffio==1.3.1
soupsieve==2.5
sqlparse==0.5.5
ssh-import-id==5.11
systemd-python==235
tiktoken==0.12.0
tinycss2==1.5.1
tinyhtml5==2.0.0
tldextract==3.1.2
tokenizers==0.22.2
tqdm==4.67.1
tweepy==4.16.0
twilio==9.10.3
twine==6.2.0
typer==0.23.1
typer-slim==0.21.0
types-pyyaml==6.0.12.20250915
types-PyYAML==6.0.12.20250915
types-requests==2.32.4.20250913
typing-extensions==4.15.0
typing-inspection==0.4.2
typing_extensions==4.15.0
tzdata==2025.3
tzlocal==5.3.1
ua-parser==1.0.1
ua-parser-builtins==202601
unidecode==1.4.0
ubuntu-drivers-common==0.0.0
ufw==0.36.2
Unidecode==1.4.0
uritemplate==4.2.0
urllib3==2.6.2
user-agents==2.2.0
vine==5.1.0
wadllib==1.3.6
watchdog==6.0.0
wcwidth==0.2.14
weasyprint==67.0
matplotlib==3.11.0
webencodings==0.5.1
websockets==10.4
wheel==0.42.0
whitenoise==6.11.0
xdg==5
xkit==0.0.0
xlrd==2.0.2
xmltodict==0.13.0
yarl==1.22.0
yt-dlp==2024.4.9
zipp==3.23.0
zopfli==0.4.0
sentry-sdk==2.20.0
django-ai-po

73
templates/actions/action_detail.html
View File

@ -105,12 +105,12 @@
{% endif %}
</div>
<!-- SLA Progress -->
<div class="mt-4 flex items-center gap-3">
{% comment %} <div class="mt-4 flex items-center gap-3">
<div class="flex-1 max-w-xs h-2 bg-slate-200 rounded-full overflow-hidden">
<div class="h-full rounded-full {% if action.is_overdue %}bg-red-500{% elif sla_progress > 80 %}bg-orange-500{% else %}bg-green-500{% endif %}" style="width: {{ sla_progress }}%"></div>
</div>
<span class="text-xs font-bold {% if action.is_overdue %}text-red-600{% else %}text-slate{% endif %}">{{ sla_progress }}%</span>
</div>
</div> {% endcomment %}
</header>
<!-- Tab Navigation -->
@ -121,9 +121,12 @@
<button class="py-4 text-sm tab-inactive" onclick="switchTab('activity')" id="tab-activity">
{% trans "Activity" %} ({{ logs.count }})
</button>
<button class="py-4 text-sm tab-inactive" onclick="switchTab('evidence')" id="tab-evidence">
{% trans "Evidence" %} ({{ evidence_attachments.count }})
<button class="py-4 text-sm tab-inactive" onclick="switchTab('notes')" id="tab-notes">
{% trans "Notes" %} ({{ notes.count }})
</button>
{% comment %} <button class="py-4 text-sm tab-inactive" onclick="switchTab('evidence')" id="tab-evidence">
{% trans "Evidence" %} ({{ evidence_attachments.count }})
</button> {% endcomment %}
<button class="py-4 text-sm tab-inactive" onclick="switchTab('attachments')" id="tab-attachments">
{% trans "Attachments" %} ({{ attachments.count }})
</button>
@ -243,6 +246,48 @@
</section>
</div>
<!-- Notes Tab -->
<div id="panel-notes" class="tab-panel hidden">
<section class="bg-white rounded-2xl p-6 shadow-sm border border-slate-100 space-y-6">
<h3 class="font-bold text-navy flex items-center gap-2">
<i data-lucide="message-square" class="w-5 h-5"></i> {% trans "Notes" %}
</h3>
<form method="post" action="{% url 'actions:action_add_note' action.id %}">
{% csrf_token %}
<textarea name="note" class="w-full px-3 py-2 border border-slate-200 rounded-xl text-sm mb-2 focus:ring-2 focus:ring-navy/20 outline-none" rows="3" placeholder="{% trans 'Enter your note...' %}" required></textarea>
<button type="submit" class="bg-navy text-white px-4 py-2 rounded-xl font-semibold hover:bg-blue transition flex items-center justify-center gap-2 text-sm">
<i data-lucide="plus-circle" class="w-4 h-4"></i> {% trans "Add Note" %}
</button>
</form>
<div>
{% if notes %}
<div class="timeline">
{% for note in notes %}
<div class="timeline-item note">
<div class="bg-slate-50 rounded-xl p-4">
<div class="flex items-center justify-between mb-2">
<span class="font-bold text-navy text-sm">{{ note.message }}</span>
<span class="text-xs text-slate-400">{{ note.created_at|date:"M d, Y H:i" }}</span>
</div>
{% if note.created_by %}
<div class="text-xs text-slate-500">
<i data-lucide="user" class="w-3 h-3 inline"></i> {{ note.created_by.get_full_name }}
</div>
{% endif %}
</div>
</div>
{% endfor %}
</div>
{% else %}
<div class="text-center py-8">
<i data-lucide="message-square" class="w-12 h-12 mx-auto text-slate-300 mb-3"></i>
<p class="text-slate text-sm">{% trans "No notes yet" %}</p>
</div>
{% endif %}
</div>
</section>
</div>
<!-- Evidence Tab -->
<div id="panel-evidence" class="tab-panel hidden">
<section class="bg-white rounded-2xl p-6 shadow-sm border border-slate-100">
@ -426,9 +471,9 @@
</form>
<!-- Escalate -->
<button type="button" onclick="document.getElementById('escalateModal').style.display='flex'" class="w-full bg-red-50 border border-red-200 text-red-600 px-4 py-2.5 rounded-xl font-semibold hover:bg-red-100 transition flex items-center justify-center gap-2 text-sm">
{% comment %} <button type="button" onclick="document.getElementById('escalateModal').style.display='flex'" class="w-full bg-red-50 border border-red-200 text-red-600 px-4 py-2.5 rounded-xl font-semibold hover:bg-red-100 transition flex items-center justify-center gap-2 text-sm">
<i data-lucide="arrow-up-circle" class="w-4 h-4"></i> {% trans "Escalate" %}
</button>
</button> {% endcomment %}
</div>
</section>
{% endif %}
@ -485,27 +530,13 @@
{% else %}
<p class="text-sm text-slate-500 mb-3">{% trans "Convert this action to a QI project for long-term tracking." %}</p>
{% endif %}
<a href="{% url 'projects:convert_action' action_pk=action.pk %}" class="w-full {% if action.qi_projects.exists %}bg-slate-200 text-slate-400 cursor-not-allowed{% else %}bg-blue-50 border border-blue-200 text-blue-700 hover:bg-blue-100{% endif %} px-4 py-2.5 rounded-xl font-semibold transition flex items-center justify-center gap-2 text-sm">
<a href="{% url 'projects:project_create' %}?action={{ action.pk }}" class="w-full {% if action.qi_projects.exists %}bg-slate-200 text-slate-400 cursor-not-allowed{% else %}bg-blue-50 border border-blue-200 text-blue-700 hover:bg-blue-100{% endif %} px-4 py-2.5 rounded-xl font-semibold transition flex items-center justify-center gap-2 text-sm">
<i data-lucide="arrow-right-circle" class="w-4 h-4"></i>
{% if action.qi_projects.exists %}{% trans "Already Converted" %}{% else %}{% trans "Convert to Project" %}{% endif %}
</a>
</section>
{% endif %}
<!-- Add Note -->
<section class="bg-white rounded-2xl p-6 shadow-sm border border-slate-100">
<h3 class="font-bold text-navy mb-4 text-sm flex items-center gap-2">
<i data-lucide="message-square" class="w-4 h-4"></i> {% trans "Add Note" %}
</h3>
<form method="post" action="{% url 'actions:action_add_note' action.id %}">
{% csrf_token %}
<textarea name="note" class="w-full px-3 py-2 border border-slate-200 rounded-xl text-sm mb-2 focus:ring-2 focus:ring-navy/20 outline-none" rows="3" placeholder="{% trans 'Enter your note...' %}" required></textarea>
<button type="submit" class="w-full bg-navy text-white px-4 py-2.5 rounded-xl font-semibold hover:bg-blue transition flex items-center justify-center gap-2 text-sm">
<i data-lucide="plus-circle" class="w-4 h-4"></i> {% trans "Add Note" %}
</button>
</form>
</section>
</div>
</main>

58
templates/analytics/kpi_report_weasyprint.html
View File

@ -1,32 +1,12 @@
{% load i18n %}<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>{{ report.kpi_id }} - {{ report.indicator_title }} - PX360</title>
<style>
@page {
size: A4 landscape;
margin: 1.5cm;
@top-center {
content: "{{ report.hospital.name }} — KPI Report {{ report.kpi_id }}";
font-size: 8pt;
color: #94a3b8;
}
@bottom-right {
content: "Page " counter(page) " of " counter(pages);
font-size: 8pt;
color: #94a3b8;
}
@bottom-left {
content: "Generated {{ generated_at }}";
font-size: 8pt;
color: #94a3b8;
}
}
@page :first {
@top-center { content: ""; }
}
{% extends "shared/letterhead_pdf_repeating_base.html" %}
{% load i18n %}
{% block title %}{{ report.kpi_id }} - {{ report.indicator_title }} - PX360{% endblock %}
{% block page_override %}@page { size: A4 landscape; margin: 28mm 15mm 20mm 15mm; }{% endblock %}
{% block extra_css %}
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
@ -336,9 +316,10 @@
.page-break { page-break-before: always; }
.no-break { page-break-inside: avoid; }
</style>
</head>
<body>
</style>
{% endblock %}
{% block pdf_content %}
<!-- Report Header -->
<div class="report-header">
@ -351,9 +332,6 @@
{% trans "Generated" %}: {{ report.generated_at|default:report.created_at|date:"M d, Y H:i" }}
</div>
</div>
{% if logo_path %}
<img src="{{ logo_path }}" alt="{{ report.hospital.name }}" class="header-logo">
{% endif %}
</div>
<!-- Executive Summary Cards -->
@ -604,14 +582,4 @@
<div class="line-label">{% trans "Name & Signature" %}</div>
</div>
</div>
<!-- Footer -->
<div class="report-footer">
PX360 — Patient Experience Management System &nbsp;|&nbsp;
{{ report.hospital.name }} &nbsp;|&nbsp;
{% trans "Report ID" %}: {{ report.id }} &nbsp;|&nbsp;
{% trans "Generated" %}: {{ generated_at }}
</div>
</body>
</html>
{% endblock %}

72
templates/appreciation/appreciation_create.html Normal file
View File

@ -0,0 +1,72 @@
{% extends "layouts/base.html" %}
{% load i18n static %}
{% block title %}{% trans "New Appreciation" %} - PX360{% endblock %}
{% block content %}
<div class="max-w-2xl mx-auto">
<header class="mb-6">
<div class="flex items-center justify-between">
<div>
<h1 class="text-2xl font-bold text-navy flex items-center gap-2">
<i data-lucide="heart" class="w-6 h-6 text-amber-500"></i>
{% trans "New Appreciation" %}
</h1>
<p class="text-sm text-slate mt-1">{% trans "Recognize a department for excellent service or care." %}</p>
</div>
<a href="{% url 'appreciation:appreciation_list' %}" class="text-slate hover:text-navy px-3 py-2 text-sm font-semibold flex items-center gap-2 border rounded-lg hover:bg-light transition">
<i data-lucide="arrow-left" class="w-4 h-4"></i> {% trans "Back" %}
</a>
</div>
</header>
<form method="post" class="bg-white rounded-2xl shadow-sm border border-slate-100 p-6 space-y-5">
{% csrf_token %}
{% if form.non_field_errors %}
<div class="bg-red-50 border border-red-200 text-red-600 text-sm rounded-xl p-3">
{{ form.non_field_errors }}
</div>
{% endif %}
<div>
<label class="block text-sm font-semibold text-navy mb-2" for="{{ form.hospital.id_for_label }}">
{{ form.hospital.label }} <span class="text-red-500">*</span>
</label>
{{ form.hospital }}
{% if form.hospital.errors %}<p class="text-xs text-red-500 mt-1">{{ form.hospital.errors }}</p>{% endif %}
</div>
<div>
<label class="block text-sm font-semibold text-navy mb-2" for="{{ form.department.id_for_label }}">
{{ form.department.label }} <span class="text-red-500">*</span>
</label>
{{ form.department }}
{% if form.department.errors %}<p class="text-xs text-red-500 mt-1">{{ form.department.errors }}</p>{% endif %}
</div>
<div>
<label class="block text-sm font-semibold text-navy mb-2" for="{{ form.message_en.id_for_label }}">
{% trans "Message" %} <span class="text-red-500">*</span>
</label>
{{ form.message_en }}
{% if form.message_en.errors %}<p class="text-xs text-red-500 mt-1">{{ form.message_en.errors }}</p>{% endif %}
</div>
<div class="flex gap-3 pt-4 border-t border-slate-100">
<button type="submit" class="flex-1 bg-navy text-white px-5 py-3 rounded-xl font-bold text-sm hover:bg-blue transition flex items-center justify-center gap-2">
<i data-lucide="check" class="w-4 h-4"></i> {% trans "Create Appreciation" %}
</button>
<a href="{% url 'appreciation:appreciation_list' %}" class="px-5 py-3 border border-slate-200 text-slate-600 rounded-xl font-semibold text-sm hover:bg-slate-50 transition">
{% trans "Cancel" %}
</a>
</div>
</form>
</div>
{% endblock %}
{% block extra_js %}
<script>
if (typeof lucide !== 'undefined') lucide.createIcons();
</script>
{% endblock %}

154
templates/appreciation/appreciation_detail.html
View File

@ -74,10 +74,10 @@
{% trans "Appreciation Detail" %}
</h1>
<div class="flex items-center gap-3">
<a href="{% url 'appreciation:appreciation_pdf' pk=appreciation.pk %}" target="_blank"
{% comment %} <a href="{% url 'appreciation:appreciation_pdf' pk=appreciation.pk %}" target="_blank"
class="inline-flex items-center gap-1.5 px-3 py-1.5 border border-slate-200 rounded-lg text-xs font-semibold text-slate hover:border-navy hover:text-navy transition">
<i data-lucide="file-text" class="w-3.5 h-3.5"></i> {% trans "PDF" %}
</a>
</a> {% endcomment %}
<span class="text-xs text-slate-400">
{{ appreciation.created_at|date:"Y-m-d H:i" }} &mdash; {{ appreciation.hospital.get_localized_name }}
</span>
@ -153,7 +153,7 @@
<section class="bg-white rounded-2xl p-6 shadow-sm border border-slate-100 mb-6">
<h3 class="font-bold text-navy mb-4 flex items-center gap-2">
<i data-lucide="user-check" class="w-5 h-5 text-blue-600"></i>
{% trans "Assigned To" %}
{% trans "Appreciation For" %}
</h3>
<div class="flex items-center gap-3">
<div class="w-10 h-10 rounded-full bg-navy/10 flex items-center justify-center">
@ -180,18 +180,18 @@
<p class="text-[10px] font-bold text-slate uppercase tracking-wider mb-1">{% trans "Sent At" %}</p>
<p class="text-sm font-semibold text-navy">{{ appreciation.sent_at|date:"Y-m-d H:i" }}</p>
</div>
<div>
{% comment %} <div>
<p class="text-[10px] font-bold text-slate uppercase tracking-wider mb-1">{% trans "To Manager" %}</p>
<p class="text-sm font-semibold {% if appreciation.send_to_manager %}text-green-600{% else %}text-slate{% endif %}">
{% if appreciation.send_to_manager %}{% trans "Yes" %}{% else %}{% trans "No" %}{% endif %}
</p>
</div>
<div>
</div> {% endcomment %}
{% comment %} <div>
<p class="text-[10px] font-bold text-slate uppercase tracking-wider mb-1">{% trans "To Department" %}</p>
<p class="text-sm font-semibold {% if appreciation.send_to_department %}text-green-600{% else %}text-slate{% endif %}">
{% if appreciation.send_to_department %}{% trans "Yes" %}{% else %}{% trans "No" %}{% endif %}
</p>
</div>
</div> {% endcomment %}
</div>
{% if appreciation.custom_message %}
<div class="mt-4 pt-4 border-t border-green-100">
@ -281,40 +281,9 @@
</h3>
<form method="post" action="{% url 'appreciation:appreciation_activate' pk=appreciation.pk %}">
{% csrf_token %}
<p class="text-slate text-xs mb-4">{% trans "Select the staff member and department, then activate to trigger AI analysis." %}</p>
<div class="space-y-3">
<div>
<label class="block text-[10px] font-bold text-slate uppercase tracking-wider mb-1">
{% trans "Staff Member" %} <span class="text-red-500">*</span>
</label>
<select name="staff" id="id_staff" data-tomselect class="w-full px-3 py-2.5 border border-slate-200 rounded-xl text-sm focus:ring-2 focus:ring-navy/20 focus:border-navy outline-none">
<option value="">{% trans "Select staff..." %}</option>
{% for s in staff_list %}
<option value="{{ s.id }}" data-department="{{ s.department.id }}">{{ s.first_name }} {{ s.last_name }}{% if s.employee_id %} ({{ s.employee_id }}){% endif %}{% if s.department %} - {{ s.department.get_localized_name }}{% endif %}</option>
{% endfor %}
</select>
</div>
<div>
<label class="block text-[10px] font-bold text-slate uppercase tracking-wider mb-1">{% trans "Department" %}</label>
<select name="department" id="id_department" data-tomselect class="w-full px-3 py-2.5 border border-slate-200 rounded-xl text-sm focus:ring-2 focus:ring-navy/20 focus:border-navy outline-none">
<option value="">{% trans "Auto from staff" %}</option>
{% for d in departments %}
<option value="{{ d.id }}">{{ d.get_localized_name }}</option>
{% endfor %}
</select>
</div>
<div>
<label class="block text-[10px] font-bold text-slate uppercase tracking-wider mb-1">{% trans "Category" %}</label>
<select name="category" class="w-full px-3 py-2.5 border border-slate-200 rounded-xl text-sm focus:ring-2 focus:ring-navy/20 focus:border-navy outline-none">
<option value="">{% trans "Select category..." %}</option>
{% for c in categories %}
<option value="{{ c.id }}" {% if appreciation.category and appreciation.category.id == c.id %}selected{% endif %}>{{ c.get_localized_name }}</option>
{% endfor %}
</select>
</div>
</div>
<button type="submit" class="w-full mt-4 px-4 py-2.5 bg-emerald-600 text-white rounded-xl font-bold hover:bg-emerald-700 transition text-sm inline-flex items-center justify-center gap-2">
<i data-lucide="zap" class="w-4 h-4"></i> {% trans "Activate & Analyze" %}
<p class="text-slate text-xs mb-4">{% trans "Activate this appreciation to make it ready for routing to a department." %}</p>
<button type="submit" class="w-full px-4 py-2.5 bg-emerald-600 text-white rounded-xl font-bold hover:bg-emerald-700 transition text-sm inline-flex items-center justify-center gap-2">
<i data-lucide="zap" class="w-4 h-4"></i> {% trans "Activate" %}
</button>
</form>
</section>
@ -326,7 +295,7 @@
<i data-lucide="send" class="w-4 h-4"></i> {% trans "Send to Department" %}
</h3>
<p class="text-slate text-xs mb-4">{% trans "Route this appreciation to a department or a specific person for acknowledgment." %}</p>
<button onclick="showSendModal('{{ appreciation.id }}', 'appreciation'{% if appreciation.department_id %}, '{{ appreciation.department_id }}'{% endif %})"
<button onclick="document.getElementById('aprSendModal').style.display='flex'"
class="w-full px-4 py-2.5 bg-navy text-white rounded-xl font-bold hover:bg-blue transition text-sm inline-flex items-center justify-center gap-2">
<i data-lucide="send" class="w-4 h-4"></i> {% trans "Send to Department" %}
</button>
@ -335,7 +304,106 @@
</div>
</main>
{% include "components/send_to_modal.html" with users=send_to_users departments=hospital_departments %}
<!-- Send to Department Modal (department + staff) -->
<div id="aprSendModal" style="display:none" class="fixed inset-0 bg-black/50 z-50 flex items-center justify-center p-4">
<div class="bg-white rounded-2xl shadow-2xl w-full max-w-md mx-4">
<div class="flex items-center justify-between p-5 border-b border-slate-100">
<h3 class="text-lg font-bold text-navy flex items-center gap-2"><i data-lucide="send" class="w-5 h-5"></i> {% trans "Send to Department" %}</h3>
<button type="button" onclick="document.getElementById('aprSendModal').style.display='none'" class="p-1.5 rounded-lg hover:bg-slate-100 text-slate-400"><i data-lucide="x" class="w-5 h-5"></i></button>
</div>
<form id="aprSendForm" onsubmit="handleAprSendSubmit(event)">
{% csrf_token %}
<div class="p-5 space-y-4">
<div id="aprSendError" class="hidden text-sm text-red-600 bg-red-50 border border-red-200 p-3 rounded-lg"></div>
<div>
<label class="block text-sm font-semibold text-slate-700 mb-1.5">{% trans "Department" %} <span class="text-red-500">*</span></label>
<select id="aprDeptSelect" name="department_id" onchange="loadAprStaff(this.value)"
class="w-full border border-slate-200 rounded-xl p-3 text-sm focus:ring-2 focus:ring-navy/20 outline-none" required>
<option value="">{% trans "Select Department" %}</option>
{% for dept in hospital_departments %}
<option value="{{ dept.id }}">{{ dept.get_localized_name }}</option>
{% endfor %}
</select>
</div>
<div>
<label class="block text-sm font-semibold text-slate-700 mb-1.5">{% trans "Staff" %} <span class="text-slate-400 font-normal">({% trans "optional" %})</span></label>
<select id="aprStaffSelect" name="staff_id"
class="w-full border border-slate-200 rounded-xl p-3 text-sm focus:ring-2 focus:ring-navy/20 outline-none">
<option value="">{% trans "Select department first" %}</option>
</select>
<p class="text-xs text-slate-400 mt-1">{% trans "The staff member, department champion and manager will be notified." %}</p>
</div>
<div>
<label class="block text-sm font-semibold text-slate-700 mb-1.5">{% trans "Note" %} <span class="text-slate-400 font-normal">({% trans "optional" %})</span></label>
<textarea name="note" rows="2" class="w-full border border-slate-200 rounded-xl p-3 text-sm focus:ring-2 focus:ring-navy/20 outline-none" placeholder="{% trans 'Add context...' %}"></textarea>
</div>
</div>
<div class="p-5 border-t border-slate-100 flex gap-3">
<button type="button" onclick="document.getElementById('aprSendModal').style.display='none'" class="flex-1 px-4 py-2.5 border border-slate-200 text-slate-600 rounded-xl font-semibold hover:bg-slate-50 transition">{% trans "Cancel" %}</button>
<button type="submit" id="aprSendBtn" class="flex-1 px-4 py-2.5 bg-navy text-white rounded-xl font-bold hover:bg-blue transition flex items-center justify-center gap-2">
<i data-lucide="send" class="w-4 h-4"></i> {% trans "Send" %}
</button>
</div>
</form>
</div>
</div>
<script>
function loadAprStaff(deptId) {
var staffSel = document.getElementById('aprStaffSelect');
if (!deptId) {
staffSel.innerHTML = '<option value="">{% trans "Select department first" %}</option>';
return;
}
staffSel.innerHTML = '<option value="">{% trans "Loading..." %}</option>';
fetch('/organizations/dropdowns/department-staff/' + encodeURIComponent(deptId) + '/')
.then(function (r) { return r.json(); })
.then(function (items) {
var html = '<option value="">{% trans "Select staff (optional)" %}</option>';
(items || []).forEach(function (it) {
var id = it.staff_id || (it.staff && it.staff.id);
var name = it.name || (it.staff && it.staff.name) || id;
if (id) html += '<option value="' + id + '">' + name + '</option>';
});
staffSel.innerHTML = html;
})
.catch(function () { staffSel.innerHTML = '<option value="">{% trans "Select staff (optional)" %}</option>'; });
}
function handleAprSendSubmit(event) {
event.preventDefault();
var deptId = document.getElementById('aprDeptSelect').value;
var err = document.getElementById('aprSendError');
var btn = document.getElementById('aprSendBtn');
if (!deptId) {
err.textContent = '{% trans "Please select a department." %}';
err.classList.remove('hidden');
return;
}
err.classList.add('hidden');
btn.disabled = true;
btn.innerHTML = '<span class="inline-block w-4 h-4 border-2 border-white/30 border-t-white rounded-full animate-spin mr-2"></span>{% trans "Sending..." %}';
fetch('{% url "appreciation:appreciation_send_to" pk=appreciation.pk %}', {
method: 'POST',
body: new FormData(event.target),
headers: { 'X-Requested-With': 'XMLHttpRequest', 'X-CSRFToken': document.querySelector('[name=csrfmiddlewaretoken]').value || '' }
})
.then(async function (r) {
var data = null;
try { data = await r.json(); } catch (e) {}
if (data && data.success === true) return data;
throw new Error((data && data.error) || (r.ok ? '{% trans "Failed to send." %}' : '{% trans "Server error" %} (' + r.status + ')'));
})
.then(function () { window.location.reload(); })
.catch(function (e) {
err.textContent = e.message;
err.classList.remove('hidden');
btn.disabled = false;
btn.innerHTML = '<i data-lucide="send" class="w-4 h-4"></i> {% trans "Send" %}';
if (window.lucide) lucide.createIcons();
});
}
</script>
<script>
function switchTab(tabName) {

5
templates/appreciation/appreciation_list.html
View File

@ -59,8 +59,11 @@
<p class="text-sm opacity-90 mt-1">{% trans "Manage and review patient appreciation submissions" %}</p>
</div>
<div class="flex items-center gap-3">
<a href="{% url 'appreciation:appreciation_create' %}" class="bg-white text-navy px-5 py-2.5 rounded-xl text-sm font-bold hover:bg-navy/10 flex items-center gap-2 transition">
<i data-lucide="plus" class="w-4 h-4"></i> {% trans "Create Internal" %}
</a>
<a href="{% url 'core:public_submit_landing' %}" target="_blank" class="bg-white/20 text-white border-2 border-white/50 px-5 py-2.5 rounded-xl text-sm font-bold hover:bg-white/30 flex items-center gap-2 transition">
<i data-lucide="plus" class="w-4 h-4"></i> {% trans "New Appreciation" %}
<i data-lucide="external-link" class="w-4 h-4"></i> {% trans "Public Form" %}
</a>
<div class="bg-white/20 rounded-xl px-5 py-3 text-center">
<p class="text-3xl font-black">{{ stats.draft }}</p>

59
templates/complaints/complaint_detail.html
View File

@ -134,7 +134,7 @@
class="text-slate hover:text-navy px-3 py-2 text-sm font-semibold flex items-center gap-2 border rounded-lg hover:bg-light transition">
<i data-lucide="printer" class="w-4 h-4"></i> {% trans "PDF View" %}
</a> {% endcomment %}
{% if can_edit and complaint.is_active_status and complaint.assigned_to == current_user %}
{% if can_edit and complaint.is_active_status and complaint.activated_at and complaint.assigned_to == current_user %}
<button onclick="showResolveModal()" class="bg-navy text-white px-4 py-2 rounded-lg text-sm font-bold shadow-md hover:bg-blue transition">
{% trans "Resolve Case" %}
</button>
@ -626,19 +626,8 @@
</div>
{% endif %}
{% if complaint.patient %}
<div class="mt-3 pt-3 border-t border-slate-100 flex items-center gap-4 text-sm">
<i data-lucide="user" class="w-4 h-4 text-slate flex-shrink-0"></i>
<span class="font-bold text-navy">{{ complaint.patient.get_full_name }}</span>
<span class="text-slate">|</span>
<span class="text-slate">{% trans "MRN:" %} <span class="font-medium text-navy">{{ complaint.patient.mrn|default:"-" }}</span></span>
{% if complaint.patient.phone %}
<span class="text-slate">|</span>
<span class="text-slate">{{ complaint.patient.phone }}</span>
{% endif %}
</div>
{% endif %}
</section>
{% include "partials/patient_card.html" with patient=complaint.patient fallback_name=complaint.patient_name fallback_mrn=complaint.file_number fallback_phone=complaint.contact_phone %}
{% if complaint.activated_at %}
{% include "complaints/partials/pdf_summary_panel.html" %}
{% else %}
@ -681,7 +670,14 @@
<div class="grid grid-cols-1 lg:grid-cols-2 gap-4">
<!-- Involved Departments (read-only) -->
<section class="bg-white rounded-2xl p-4 shadow-sm border border-slate-100">
<h4 class="text-sm font-bold text-navy uppercase tracking-wide mb-3">{% trans "Involved Departments" %}</h4>
<div class="flex items-center justify-between mb-3">
<h4 class="text-sm font-bold text-navy uppercase tracking-wide">{% trans "Involved Departments" %}</h4>
{% if can_edit and complaint.is_active_status and workflow_steps.activated and workflow_steps.taxonomy_reviewed %}
<button type="button" onclick="openSendToDeptModal()" class="px-3 py-1.5 bg-navy text-white rounded-lg font-bold text-xs hover:bg-blue transition inline-flex items-center gap-1">
<i data-lucide="send" class="w-3.5 h-3.5"></i> {% trans "Send to Department" %}
</button>
{% endif %}
</div>
{% if complaint.involved_departments.exists %}
<ul class="divide-y divide-slate-100 border border-slate-100 rounded-xl overflow-hidden">
{% for dept in complaint.involved_departments.all %}
@ -846,16 +842,17 @@
</button>
</form>
{% if complaint.activated_at %}
{% if complaint.assigned_to == current_user or can_manage_actions %}
<!-- Action buttons only shown when activated or PX-team -->
<!-- Action buttons only shown when activated -->
<button onclick="showResolveModal()" class="p-3 border rounded-xl hover:bg-light flex flex-col items-center gap-2 group transition">
<i data-lucide="check-circle-2" class="w-5 h-5 text-slate group-hover:text-green-600"></i>
<span class="text-[10px] font-bold uppercase">{% trans "Resolve" %}</span>
</button>
<button onclick="showFollowUpModal()" class="p-3 border rounded-xl hover:bg-light flex flex-col items-center gap-2 group transition">
{% comment %} <button onclick="showFollowUpModal()" class="p-3 border rounded-xl hover:bg-light flex flex-col items-center gap-2 group transition">
<i data-lucide="clock" class="w-5 h-5 text-slate group-hover:text-orange-500"></i>
<span class="text-[10px] font-bold uppercase">{% trans "Follow Up" %}</span>
</button>
</button> {% endcomment %}
{% if complaint.escalated_at %}
<button disabled class="p-3 border-red-200 bg-red-100 rounded-xl flex flex-col items-center gap-2 transition cursor-not-allowed opacity-70">
<i data-lucide="alert-triangle" class="w-5 h-5 text-red-500"></i>
@ -870,6 +867,7 @@
<form method="post" action="{% url 'complaints:toggle_escalated_ovr' pk=complaint.pk %}" class="contents">
{% csrf_token %}
<button type="submit" name="is_escalated_ovr" value="{% if not complaint.is_escalated_ovr %}on{% endif %}"
onclick="return confirm('{% if complaint.is_escalated_ovr %}{% trans "Deactivate OVR escalation for this complaint?" %}{% else %}{% trans "Are you sure you want to escalate this complaint as OVR?" %}{% endif %}')"
class="p-3 border rounded-xl hover:bg-light flex flex-col items-center gap-2 group transition
{% if complaint.is_escalated_ovr %}border-orange-300 bg-orange-100 ring-2 ring-orange-200{% endif %}">
<i data-lucide="{% if complaint.is_escalated_ovr %}shield-check{% else %}shield-alert{% endif %}" class="w-5 h-5 {% if complaint.is_escalated_ovr %}text-orange-600{% else %}text-slate group-hover:text-orange-500{% endif %}"></i>
@ -878,29 +876,20 @@
</span>
</button>
</form>
<!-- Close Button -->
<button onclick="showCloseModal()" class="p-3 border rounded-xl hover:bg-light flex flex-col items-center gap-2 group transition">
<i data-lucide="circle-check" class="w-5 h-5 text-slate-600 group-hover:text-emerald-600"></i>
<span class="text-[10px] font-bold uppercase text-slate-600">{% trans "Close" %}</span>
</button>
{% else %}
<!-- Not yet activated: show Cancel for admins -->
{% if can_manage_actions %}
<form method="post" action="{% url 'complaints:complaint_change_status' pk=complaint.pk %}" class="col-span-2 contents">
{% csrf_token %}
<input type="hidden" name="status" value="cancelled">
<button type="submit" onclick="return confirm('{% trans "Are you sure you want to cancel this complaint?" %}')"
class="p-3 border-red-200 bg-red-50 rounded-xl hover:bg-red-100 flex flex-col items-center gap-2 group transition col-span-2">
<i data-lucide="x-circle" class="w-5 h-5 text-red-500"></i>
<span class="text-[10px] font-bold text-red-600 uppercase">{% trans "Cancel Complaint" %}</span>
</button>
</form>
{% endif %}
{% else %}
<!-- Not yet activated: only Activate / Assign / Close are available -->
<div class="col-span-2 bg-yellow-50 border border-yellow-200 rounded-xl p-3 text-center">
<i data-lucide="lock" class="w-4 h-4 text-yellow-600 mx-auto mb-1"></i>
<p class="text-xs text-yellow-700">{% trans "Activate this complaint to perform actions" %}</p>
</div>
{% endif %}
<!-- Close Button - available before and after activation -->
{% if complaint.assigned_to == current_user or can_manage_actions %}
<button onclick="showCloseModal()" class="p-3 border rounded-xl hover:bg-light flex flex-col items-center gap-2 group transition">
<i data-lucide="circle-check" class="w-5 h-5 text-slate-600 group-hover:text-emerald-600"></i>
<span class="text-[10px] font-bold uppercase text-slate-600">{% trans "Close" %}</span>
</button>
{% endif %}
{% elif complaint.status == 'resolved' or complaint.status == 'closed' %}
{% if can_edit %}
@ -1234,7 +1223,7 @@
<select id="sendDeptDeptSelect" name="department_id" onchange="loadSendDeptStaff(this.value)"
class="w-full border border-slate-200 rounded-xl p-3 text-sm focus:ring-2 focus:ring-navy/20 outline-none" required>
<option value="">{% trans "Select Department" %}</option>
{% for dept in hospital_departments %}
{% for dept in available_departments %}
<option value="{{ dept.id }}">{{ dept.get_localized_name }}</option>
{% endfor %}
</select>

1
templates/complaints/complaint_detail_ds.html
View File

@ -760,6 +760,7 @@
<form method="post" action="{% url 'complaints:toggle_escalated_ovr' pk=complaint.pk %}" class="contents" data-on:submit="@post('{% url 'complaints:toggle_escalated_ovr' pk=complaint.pk %}', {contentType:'form'})">
{% csrf_token %}
<button type="submit" name="is_escalated_ovr" value="{% if not complaint.is_escalated_ovr %}on{% endif %}"
onclick="return confirm('{% if complaint.is_escalated_ovr %}{% trans "Deactivate OVR escalation for this complaint?" %}{% else %}{% trans "Are you sure you want to escalate this complaint as OVR?" %}{% endif %}')"
class="p-3 border rounded-xl hover:bg-light flex flex-col items-center gap-2 group transition
{% if complaint.is_escalated_ovr %}border-orange-200 bg-orange-50{% endif %}">
<i data-lucide="shield-alert" class="w-5 h-5 {% if complaint.is_escalated_ovr %}text-orange-600{% else %}text-slate group-hover:text-orange-500{% endif %}"></i>

13
templates/complaints/complaint_pdf_v2.html
View File

@ -48,6 +48,15 @@
z-index: 100;
}
.qr-code {
position: fixed;
bottom: 18mm;
left: 20mm;
width: 25mm;
height: auto;
z-index: 100;
}
.form-body {
padding: 38mm 20mm 35mm 20mm;
position: relative;
@ -239,5 +248,9 @@
<img class="stamp" src="{{ stamp_path }}" alt="">
{% endif %}
{% if qr_code_path %}
<img class="qr-code" src="{{ qr_code_path }}" alt="QR">
{% endif %}
</body>
</html>

2
templates/complaints/emails/explanation_reminder_en.txt
View File

@ -13,7 +13,7 @@ Your explanation is due in {{ hours_remaining }} hours (due: {{ due_date|date:"Y
To submit your explanation, click on the link below:
{{ site_url }}/complaints/explanation/{{ explanation.token }}/
Please submit your explanation before the deadline to avoid escalation to your manager.
Please submit your explanation before the deadline.
If you have any questions, please contact the person who requested this explanation.

4
templates/complaints/emails/explanation_second_reminder_en.txt
View File

@ -10,13 +10,11 @@ Description: {{ complaint.description }}
Your explanation is due in {{ hours_remaining }} hours (due: {{ due_date|date:"Y-m-d H:i" }}).
IMPORTANT: If you do not submit your explanation before the deadline, this matter will be escalated to your manager for action.
IMPORTANT: Please submit your explanation immediately before the deadline.
To submit your explanation, click on the link below:
{{ site_url }}/complaints/explanation/{{ explanation.token }}/
Please submit your explanation immediately to avoid escalation.
If you have any questions, please contact the person who requested this explanation.
Thank you for your cooperation.

469
templates/complaints/escalation_rule_form.html
View File

@ -1,469 +0,0 @@
{% extends "layouts/base.html" %}
{% load i18n %}
{% block title %}{{ title }} - {% translate "Escalation Rules" %} - PX360{% endblock %}
{% block extra_css %}
<style>
.page-header-gradient {
background: linear-gradient(135deg, #005696 0%, #0069a8 50%, #007bbd 100%);
color: white;
padding: 1.5rem 2rem;
border-radius: 1rem;
margin-bottom: 1.5rem;
box-shadow: 0 10px 15px -3px rgba(0, 86, 150, 0.2);
}
.form-section {
background: #fff;
border: 2px solid #e2e8f0;
border-radius: 1rem;
padding: 1.5rem;
margin-bottom: 1.5rem;
transition: all 0.3s ease;
}
.form-section:hover {
border-color: #005696;
box-shadow: 0 4px 12px rgba(0, 86, 150, 0.1);
}
.form-label {
display: block;
font-size: 0.875rem;
font-weight: 600;
color: #1e293b;
margin-bottom: 0.5rem;
}
.form-control, .form-select {
width: 100%;
padding: 0.75rem 1rem;
border: 2px solid #e2e8f0;
border-radius: 0.75rem;
font-size: 0.875rem;
transition: all 0.2s ease;
}
.form-control:focus, .form-select:focus {
outline: none;
border-color: #005696;
box-shadow: 0 0 0 3px rgba(0, 86, 150, 0.1);
}
.hh-btn-primary {
display: inline-flex;
align-items: center;
gap: 0.5rem;
padding: 0.75rem 1.5rem;
background: #005696;
color: white;
border-radius: 0.75rem;
font-weight: 600;
transition: all 0.2s ease;
border: none;
cursor: pointer;
}
.hh-btn-primary:hover {
background: #007bbd;
}
.hh-btn-secondary {
display: inline-flex;
align-items: center;
gap: 0.5rem;
padding: 0.75rem 1.5rem;
background: white;
color: #64748b;
border: 2px solid #e2e8f0;
border-radius: 0.75rem;
font-weight: 600;
transition: all 0.2s ease;
}
.hh-btn-secondary:hover {
background: #f1f5f9;
border-color: #005696;
}
.help-card {
background: #f8fafc;
border: 2px solid #e2e8f0;
border-radius: 1rem;
padding: 1.5rem;
}
.form-switch {
display: flex;
align-items: center;
gap: 0.75rem;
}
.form-switch-input {
width: 3rem;
height: 1.5rem;
appearance: none;
background: #cbd5e1;
border-radius: 1rem;
position: relative;
cursor: pointer;
transition: all 0.2s ease;
}
.form-switch-input:checked {
background: #005696;
}
.form-switch-input::after {
content: '';
position: absolute;
width: 1.25rem;
height: 1.25rem;
background: white;
border-radius: 50%;
top: 0.125rem;
left: 0.125rem;
transition: all 0.2s ease;
}
.form-switch-input:checked::after {
left: 1.625rem;
}
.invalid-feedback {
color: #dc2626;
font-size: 0.875rem;
margin-top: 0.25rem;
}
.form-text {
color: #64748b;
font-size: 0.875rem;
margin-top: 0.25rem;
}
.alert-info {
background: #dbeafe;
border: 1px solid #93c5fd;
border-radius: 0.75rem;
padding: 1rem;
}
.alert-info ol {
color: #1e40af;
font-size: 0.875rem;
padding-left: 1.25rem;
}
.alert-info li {
margin-bottom: 0.25rem;
}
</style>
{% endblock %}
{% block content %}
<!-- Gradient Header -->
<div class="page-header-gradient">
<div class="flex items-center justify-between">
<div class="flex items-center gap-4">
<div class="w-12 h-12 bg-white/20 rounded-xl flex items-center justify-center">
<i data-lucide="arrow-up-circle" class="w-6 h-6"></i>
</div>
<div>
<h1 class="text-2xl font-bold">{{ title }}</h1>
<p class="text-white/80">
{% if escalation_rule %}{% translate "Edit escalation rule" %}{% else %}{% translate "Create new escalation rule" %}{% endif %}
</p>
</div>
</div>
<a href="{% url 'complaints:escalation_rule_list' %}" class="hh-btn hh-btn-secondary">
<i data-lucide="arrow-left" class="w-4 h-4"></i>
{% translate "Back to List" %}
</a>
</div>
</div>
<div class="grid grid-cols-1 lg:grid-cols-3 gap-6">
<div class="lg:col-span-2">
<div class="form-section">
<form method="post" class="space-y-6">
{% csrf_token %}
{% if not form.hospital.is_hidden %}
<div>
<label for="id_hospital" class="form-label">
{% translate "Hospital" %} <span class="text-red-500">*</span>
</label>
<select name="hospital" id="id_hospital" class="form-select" required>
<option value="">{% translate "Select Hospital" %}</option>
{% for hospital in form.hospital.field.queryset %}
<option value="{{ hospital.id }}"
{% if form.hospital.value == hospital.id|stringformat:"s" %}selected{% endif %}>
{{ hospital.get_localized_name }}
</option>
{% endfor %}
</select>
{% if form.hospital.errors %}
<div class="invalid-feedback">
<i data-lucide="alert-circle" class="w-4 h-4 inline"></i>
{{ form.hospital.errors.0 }}
</div>
{% endif %}
</div>
{% endif %}
<div>
<label for="id_name" class="form-label">
{% translate "Rule Name" %} <span class="text-red-500">*</span>
</label>
<input type="text"
name="name"
id="id_name"
class="form-control"
value="{{ form.name.value|default:'' }}"
required
placeholder="{% translate 'e.g., Level 1 Escalation - High Priority' %}">
{% if form.name.errors %}
<div class="invalid-feedback">
<i data-lucide="alert-circle" class="w-4 h-4 inline"></i>
{{ form.name.errors.0 }}
</div>
{% endif %}
</div>
<div class="grid grid-cols-1 md:grid-cols-2 gap-6">
<div>
<label for="id_escalation_level" class="form-label">
{% translate "Escalation Level" %} <span class="text-red-500">*</span>
</label>
<select name="escalation_level" id="id_escalation_level" class="form-select" required>
<option value="">{% translate "Select Level" %}</option>
{% for value, label in form.escalation_level.field.choices %}
<option value="{{ value }}"
{% if form.escalation_level.value == value %}selected{% endif %}>
{{ label }}
</option>
{% endfor %}
</select>
{% if form.escalation_level.errors %}
<div class="invalid-feedback">
<i data-lucide="alert-circle" class="w-4 h-4 inline"></i>
{{ form.escalation_level.errors.0 }}
</div>
{% endif %}
</div>
<div>
<label for="id_trigger_hours" class="form-label">
{% translate "Trigger Hours" %} <span class="text-red-500">*</span>
</label>
<input type="number"
name="trigger_hours"
id="id_trigger_hours"
class="form-control"
value="{{ form.trigger_hours.value|default:'' }}"
min="1"
step="0.5"
required
placeholder="{% translate 'e.g., 24' %}">
{% if form.trigger_hours.errors %}
<div class="invalid-feedback">
<i data-lucide="alert-circle" class="w-4 h-4 inline"></i>
{{ form.trigger_hours.errors.0 }}
</div>
{% else %}
<div class="form-text">
{% translate "Hours after complaint creation to trigger escalation" %}
</div>
{% endif %}
</div>
</div>
<div class="grid grid-cols-1 md:grid-cols-2 gap-6">
<div>
<label for="id_escalate_to_role" class="form-label">
{% translate "Escalate To Role" %}
</label>
<select name="escalate_to_role" id="id_escalate_to_role" class="form-select">
<option value="">{% translate "Select Role" %}</option>
{% for value, label in form.escalate_to_role.field.choices %}
<option value="{{ value }}"
{% if form.escalate_to_role.value == value %}selected{% endif %}>
{{ label }}
</option>
{% endfor %}
</select>
{% if form.escalate_to_role.errors %}
<div class="invalid-feedback">
<i data-lucide="alert-circle" class="w-4 h-4 inline"></i>
{{ form.escalate_to_role.errors.0 }}
</div>
{% endif %}
</div>
<div>
<label for="id_escalate_to_user" class="form-label">
{% translate "Escalate To Specific User" %}
</label>
<select name="escalate_to_user" id="id_escalate_to_user" class="form-select">
<option value="">{% translate "Select User (Optional)" %}</option>
{% for user in users %}
<option value="{{ user.id }}"
{% if form.escalate_to_user.value == user.id|stringformat:"s" %}selected{% endif %}>
{{ user.get_full_name }} ({{ user.email }})
</option>
{% endfor %}
</select>
{% if form.escalate_to_user.errors %}
<div class="invalid-feedback">
<i data-lucide="alert-circle" class="w-4 h-4 inline"></i>
{{ form.escalate_to_user.errors.0 }}
</div>
{% else %}
<div class="form-text">
{% translate "Overrides role if specified" %}
</div>
{% endif %}
</div>
</div>
<div class="grid grid-cols-1 md:grid-cols-2 gap-6">
<div>
<label for="id_severity" class="form-label">
{% translate "Severity (Optional)" %}
</label>
<select name="severity" id="id_severity" class="form-select">
<option value="">{% translate "All Severities" %}</option>
{% for value, label in form.severity.field.choices %}
<option value="{{ value }}"
{% if form.severity.value == value %}selected{% endif %}>
{{ label }}
</option>
{% endfor %}
</select>
{% if form.severity.errors %}
<div class="invalid-feedback">
<i data-lucide="alert-circle" class="w-4 h-4 inline"></i>
{{ form.severity.errors.0 }}
</div>
{% else %}
<div class="form-text">
{% translate "Leave empty to apply to all severities" %}
</div>
{% endif %}
</div>
<div>
<label for="id_priority" class="form-label">
{% translate "Priority (Optional)" %}
</label>
<select name="priority" id="id_priority" class="form-select">
<option value="">{% translate "All Priorities" %}</option>
{% for value, label in form.priority.field.choices %}
<option value="{{ value }}"
{% if form.priority.value == value %}selected{% endif %}>
{{ label }}
</option>
{% endfor %}
</select>
{% if form.priority.errors %}
<div class="invalid-feedback">
<i data-lucide="alert-circle" class="w-4 h-4 inline"></i>
{{ form.priority.errors.0 }}
</div>
{% else %}
<div class="form-text">
{% translate "Leave empty to apply to all priorities" %}
</div>
{% endif %}
</div>
</div>
<div class="flex items-center gap-3 p-4 bg-gray-50 rounded-xl">
<div class="form-switch">
<input type="checkbox"
name="is_active"
id="id_is_active"
class="form-switch-input"
{% if form.is_active.value == 'on' or not form.is_active.value %}checked{% endif %}>
<label for="id_is_active" class="text-sm font-semibold text-gray-700">
{% translate "Active" %}
</label>
</div>
<div class="form-text ml-2">
{% translate "Only active rules will be triggered" %}
</div>
</div>
<div>
<label for="id_description" class="form-label">
{% translate "Description" %}
</label>
<textarea name="description"
id="id_description"
class="form-control resize-none"
rows="3"
placeholder="{% translate 'Optional notes about this escalation rule' %}">{{ form.description.value|default:'' }}</textarea>
{% if form.description.errors %}
<div class="invalid-feedback">
<i data-lucide="alert-circle" class="w-4 h-4 inline"></i>
{{ form.description.errors.0 }}
</div>
{% endif %}
</div>
<div class="flex items-center gap-3 pt-6 border-t border-gray-100">
<button type="submit" class="hh-btn hh-btn-primary">
<i data-lucide="save" class="w-4 h-4"></i>
{{ action }}
</button>
<a href="{% url 'complaints:escalation_rule_list' %}" class="hh-btn hh-btn-secondary">
<i data-lucide="x" class="w-4 h-4"></i>
{% translate "Cancel" %}
</a>
</div>
</form>
</div>
</div>
<div class="lg:col-span-1">
<div class="help-card">
<h5 class="text-lg font-bold text-gray-800 mb-4 flex items-center gap-2">
<i data-lucide="info" class="w-5 h-5 text-[#005696]"></i>
{% translate "Help" %}
</h5>
<h6 class="text-sm font-semibold text-gray-500 mb-3">
{% translate "Understanding Escalation Rules" %}
</h6>
<p class="text-sm text-gray-600 mb-4">
{% translate "Escalation rules automatically reassign complaints to higher-level staff when they exceed specified time thresholds." %}
</p>
<ul class="space-y-2 text-sm text-gray-600">
<li class="flex items-center gap-2">
<i data-lucide="check-circle" class="w-4 h-4 text-green-500"></i>
{% translate "Level 1: Escalate to department head" %}
</li>
<li class="flex items-center gap-2">
<i data-lucide="check-circle" class="w-4 h-4 text-green-500"></i>
{% translate "Level 2: Escalate to hospital admin" %}
</li>
<li class="flex items-center gap-2">
<i data-lucide="check-circle" class="w-4 h-4 text-green-500"></i>
{% translate "Level 3: Escalate to PX admin" %}
</li>
</ul>
<hr class="my-4 border-gray-200">
<h6 class="text-sm font-semibold text-gray-500 mb-3">
{% translate "Escalation Flow" %}
</h6>
<div class="alert-info">
<ol>
<li>{% translate "Complaint created" %}</li>
<li>{% translate "Trigger hours pass" %}</li>
<li>{% translate "Rule checks severity/priority" %}</li>
<li>{% translate "Complaint reassigned automatically" %}</li>
<li>{% translate "Notification sent to new assignee" %}</li>
</ol>
</div>
</div>
</div>
</div>
<script>
document.addEventListener('DOMContentLoaded', function() {
lucide.createIcons();
});
</script>
{% endblock %}

427
templates/complaints/escalation_rule_list.html
View File

@ -1,427 +0,0 @@
{% extends "layouts/base.html" %}
{% load i18n %}
{% block title %}{% translate "Escalation Rules" %} - PX360{% endblock %}
{% block extra_css %}
<style>
:root {
--hh-navy: #005696;
--hh-blue: #007bbd;
--hh-light: #eef6fb;
--hh-slate: #64748b;
}
.page-header-gradient {
background: linear-gradient(135deg, #005696 0%, #0069a8 50%, #007bbd 100%);
color: white;
padding: 1.5rem 2rem;
border-radius: 1rem;
margin-bottom: 1.5rem;
box-shadow: 0 10px 15px -3px rgba(0, 86, 150, 0.2);
}
.section-card {
background: white;
border-radius: 1rem;
border: 2px solid #e2e8f0;
box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
overflow: hidden;
transition: all 0.3s ease;
}
.section-card:hover {
border-color: #005696;
box-shadow: 0 10px 25px -5px rgba(0, 86, 150, 0.15);
}
.section-header {
padding: 1rem 1.5rem;
border-bottom: 2px solid #e2e8f0;
background: linear-gradient(to right, #f8fafc, #f1f5f9);
display: flex;
align-items: center;
gap: 0.75rem;
}
.section-icon {
width: 40px;
height: 40px;
border-radius: 0.75rem;
display: flex;
align-items: center;
justify-content: center;
}
.section-icon.primary {
background: linear-gradient(135deg, #005696, #007bbd);
color: white;
}
.section-icon.secondary {
background: linear-gradient(135deg, #f1f5f9, #e2e8f0);
color: #005696;
}
.data-table th {
background: linear-gradient(135deg, var(--hh-light), #e0f2fe);
padding: 0.875rem 1rem;
text-align: left;
font-size: 0.75rem;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 0.05em;
color: var(--hh-navy);
border-bottom: 2px solid #bae6fd;
}
.data-table td {
padding: 1rem;
border-bottom: 1px solid #f1f5f9;
color: #475569;
font-size: 0.875rem;
}
.data-table tbody tr {
transition: background-color 0.2s ease;
}
.data-table tbody tr:hover {
background-color: var(--hh-light);
}
.hh-btn-primary {
background: linear-gradient(135deg, var(--hh-navy) 0%, var(--hh-blue) 100%);
color: white;
padding: 0.625rem 1.25rem;
border-radius: 0.75rem;
font-weight: 600;
border: none;
cursor: pointer;
transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
display: inline-flex;
align-items: center;
gap: 0.5rem;
text-decoration: none;
font-size: 0.875rem;
}
.hh-btn-primary:hover {
transform: translateY(-2px);
box-shadow: 0 8px 16px rgba(0, 86, 150, 0.3);
}
.hh-btn-secondary {
background: white;
color: #475569;
padding: 0.625rem 1.25rem;
border-radius: 0.75rem;
font-weight: 600;
border: 2px solid #e2e8f0;
cursor: pointer;
transition: all 0.3s ease;
display: inline-flex;
align-items: center;
gap: 0.5rem;
text-decoration: none;
font-size: 0.875rem;
}
.hh-btn-secondary:hover {
background: #f1f5f9;
border-color: #cbd5e1;
transform: translateY(-1px);
}
.badge {
display: inline-flex;
align-items: center;
gap: 0.375rem;
padding: 0.375rem 0.75rem;
border-radius: 9999px;
font-size: 0.75rem;
font-weight: 700;
}
.badge-info {
background: linear-gradient(135deg, #dbeafe, #bfdbfe);
color: #1e40af;
}
.badge-secondary {
background: linear-gradient(135deg, #f1f5f9, #e2e8f0);
color: #475569;
}
.badge-success {
background: linear-gradient(135deg, #dcfce7, #bbf7d0);
color: #166534;
}
.severity-low {
background: linear-gradient(135deg, #dcfce7, #bbf7d0);
color: #166534;
}
.severity-medium {
background: linear-gradient(135deg, #fef3c7, #fde68a);
color: #92400e;
}
.severity-high {
background: linear-gradient(135deg, #fee2e2, #fecaca);
color: #991b1b;
}
.severity-critical {
background: linear-gradient(135deg, #7f1d1d, #991b1b);
color: white;
}
.priority-low {
background: linear-gradient(135deg, #f1f5f9, #e2e8f0);
color: #475569;
}
.priority-medium {
background: linear-gradient(135deg, #dbeafe, #bfdbfe);
color: #1e40af;
}
.priority-high {
background: linear-gradient(135deg, #fef3c7, #fde68a);
color: #92400e;
}
.priority-urgent {
background: linear-gradient(135deg, #fee2e2, #fecaca);
color: #991b1b;
}
@keyframes fadeIn {
from { opacity: 0; transform: translateY(20px); }
to { opacity: 1; transform: translateY(0); }
}
.animate-in {
animation: fadeIn 0.5s ease-out forwards;
}
</style>
{% endblock %}
{% block content %}
<div class="px-4 py-6">
<!-- Page Header -->
<div class="page-header-gradient animate-in">
<div class="flex items-center justify-between">
<div>
<h1 class="text-2xl font-bold mb-2">
<i data-lucide="arrow-up-circle" class="w-7 h-7 inline-block me-2"></i>
{% translate "Escalation Rules" %}
</h1>
<p class="text-white/90">{% translate "Configure automatic complaint escalation based on time thresholds" %}</p>
</div>
<a href="{% url 'complaints:escalation_rule_create' %}" class="hh-btn hh-btn-secondary">
<i data-lucide="plus" class="w-4 h-4"></i>
{% translate "Create Rule" %}
</a>
</div>
</div>
<!-- Filters -->
<div class="section-card mb-6 animate-in">
<div class="section-header">
<div class="section-icon secondary">
<i data-lucide="filter" class="w-5 h-5"></i>
</div>
<h2 class="text-lg font-bold text-navy m-0">{% translate "Filters" %}</h2>
</div>
<div class="p-6">
<form method="get" class="flex flex-wrap gap-4">
<div>
<label class="block text-sm font-semibold text-slate mb-1.5">{% translate "Escalation Level" %}</label>
<select name="escalation_level" class="px-4 py-2.5 border-2 border-slate-200 rounded-xl focus:outline-none focus:border-blue bg-white">
<option value="">{% translate "All Levels" %}</option>
<option value="1" {% if filters.escalation_level == "1" %}selected{% endif %}>1</option>
<option value="2" {% if filters.escalation_level == "2" %}selected{% endif %}>2</option>
<option value="3" {% if filters.escalation_level == "3" %}selected{% endif %}>3</option>
</select>
</div>
<div>
<label class="block text-sm font-semibold text-slate mb-1.5">{% translate "Status" %}</label>
<select name="is_active" class="px-4 py-2.5 border-2 border-slate-200 rounded-xl focus:outline-none focus:border-blue bg-white">
<option value="">{% translate "All" %}</option>
<option value="true" {% if filters.is_active == "true" %}selected{% endif %}>{% translate "Active" %}</option>
<option value="false" {% if filters.is_active == "false" %}selected{% endif %}>{% translate "Inactive" %}</option>
</select>
</div>
<div class="flex items-end gap-2">
<button type="submit" class="hh-btn hh-btn-primary h-[46px]">
<i data-lucide="search" class="w-4 h-4"></i>
{% translate "Apply Filters" %}
</button>
<a href="{% url 'complaints:escalation_rule_list' %}" class="hh-btn hh-btn-secondary h-[46px]">
<i data-lucide="x" class="w-4 h-4"></i>
{% translate "Clear" %}
</a>
</div>
</form>
</div>
</div>
<!-- Escalation Rules Table -->
<div class="section-card animate-in">
<div class="section-header">
<div class="section-icon primary">
<i data-lucide="arrow-up-circle" class="w-5 h-5"></i>
</div>
<h2 class="text-lg font-bold text-navy m-0">{% translate "All Escalation Rules" %}</h2>
</div>
<div class="p-0">
{% if escalation_rules %}
<div class="overflow-x-auto">
<table class="w-full data-table">
<thead>
<tr>
<th>{% translate "Hospital" %}</th>
<th>{% translate "Rule Name" %}</th>
<th>{% translate "Level" %}</th>
<th>{% translate "Trigger Hours" %}</th>
<th>{% translate "Escalate To" %}</th>
<th>{% translate "Severity" %}</th>
<th>{% translate "Priority" %}</th>
<th>{% translate "Status" %}</th>
<th class="text-right">{% translate "Actions" %}</th>
</tr>
</thead>
<tbody>
{% for rule in escalation_rules %}
<tr>
<td>
<strong>{{ rule.hospital.name }}</strong>
</td>
<td>{{ rule.name }}</td>
<td>
<span class="badge badge-info">
{% translate "Level" %} {{ rule.escalation_level }}
</span>
</td>
<td>{{ rule.trigger_hours }}h</td>
<td>
{% if rule.escalate_to_user %}
{{ rule.escalate_to_user.get_full_name }}
{% elif rule.escalate_to_role %}
<span class="badge badge-secondary">{{ rule.get_escalate_to_role_display }}</span>
{% else %}
<span class="text-slate-400">-</span>
{% endif %}
</td>
<td>
{% if rule.severity %}
<span class="badge severity-{{ rule.severity }}">
{{ rule.get_severity_display }}
</span>
{% else %}
<span class="text-slate-400">{% translate "All" %}</span>
{% endif %}
</td>
<td>
{% if rule.priority %}
<span class="badge priority-{{ rule.priority }}">
{{ rule.get_priority_display }}
</span>
{% else %}
<span class="text-slate-400">{% translate "All" %}</span>
{% endif %}
</td>
<td>
{% if rule.is_active %}
<span class="badge badge-success">
<i data-lucide="check-circle" class="w-3 h-3"></i>
{% translate "Active" %}
</span>
{% else %}
<span class="badge badge-secondary">
<i data-lucide="x-circle" class="w-3 h-3"></i>
{% translate "Inactive" %}
</span>
{% endif %}
</td>
<td class="text-right">
<div class="flex items-center justify-end gap-2">
<a href="{% url 'complaints:escalation_rule_edit' rule.id %}"
class="p-2 text-blue hover:bg-blue-50 rounded-lg transition"
title="{% translate 'Edit' %}">
<i data-lucide="edit" class="w-4 h-4"></i>
</a>
<form method="post"
action="{% url 'complaints:escalation_rule_delete' rule.id %}"
class="d-inline"
onsubmit="return confirm('{% translate "Are you sure you want to delete this escalation rule?" %}')">
{% csrf_token %}
<button type="submit"
class="p-2 text-red-500 hover:bg-red-50 rounded-lg transition"
title="{% translate 'Delete' %}">
<i data-lucide="trash-2" class="w-4 h-4"></i>
</button>
</form>
</div>
</td>
</tr>
{% endfor %}
</tbody>
</table>
</div>
<!-- Pagination -->
{% if page_obj.has_other_pages %}
<div class="p-4 border-t border-slate-200">
<div class="flex items-center justify-between">
<p class="text-sm text-slate">
{% blocktrans with start=page_obj.start_index end=page_obj.end_index total=page_obj.paginator.count %}
Showing {{ start }} to {{ end }} of {{ total }} rules
{% endblocktrans %}
</p>
<div class="flex gap-2">
{% if page_obj.has_previous %}
<a href="?page={{ page_obj.previous_page_number }}{% for key, value in filters.items %}&{{ key }}={{ value }}{% endfor %}"
class="px-4 py-2 border border-slate-200 rounded-lg hover:bg-slate-50 transition text-sm font-medium">
<i data-lucide="chevron-left" class="w-4 h-4 inline"></i>
{% translate "Previous" %}
</a>
{% endif %}
{% if page_obj.has_next %}
<a href="?page={{ page_obj.next_page_number }}{% for key, value in filters.items %}&{{ key }}={{ value }}{% endfor %}"
class="px-4 py-2 border border-slate-200 rounded-lg hover:bg-slate-50 transition text-sm font-medium">
{% translate "Next" %}
<i data-lucide="chevron-right" class="w-4 h-4 inline"></i>
</a>
{% endif %}
</div>
</div>
</div>
{% endif %}
{% else %}
<div class="text-center py-12">
<div class="w-16 h-16 bg-slate-100 rounded-full flex items-center justify-center mx-auto mb-4">
<i data-lucide="arrow-up-circle" class="w-8 h-8 text-slate-400"></i>
</div>
<p class="text-slate font-medium">{% translate "No escalation rules found" %}</p>
<p class="text-slate text-sm mt-1">{% translate "Create your first rule to get started" %}</p>
<a href="{% url 'complaints:escalation_rule_create' %}" class="hh-btn hh-btn-primary mt-4">
<i data-lucide="plus" class="w-4 h-4"></i>
{% translate "Create Escalation Rule" %}
</a>
</div>
{% endif %}
</div>
</div>
</div>
<script>
document.addEventListener('DOMContentLoaded', function() {
lucide.createIcons();
});
</script>
{% endblock %}

Some files were not shown because too many files have changed in this diff Show More