HH/org_hir_plan.md

PX360 Organization Hierarchy Refactor Plan

Objective

Simplify the current Department Hierarchy implementation and establish a single source of truth for complaint routing, reporting, escalation, and ownership.

The current implementation successfully migrated data but carries excessive legacy concepts into the active business model.

The goal is to:

• Use the new organizational structure as the only operational hierarchy.
• Preserve legacy complaint information only for audit/reference purposes.
• Eliminate dependency on legacy hierarchy fields for reporting.
• Simplify routing and ownership logic.
• Align the system with how the hospital currently operates.

---

Business Understanding

Legacy Structure

Old complaints were created using:

Location
 └── Main Section
       └── Sub Section

Example:

Outpatient
 └── Medical
       └── Radiology

In practice:

Legacy SubSection

was the actual operational unit receiving complaints.

---

New Structure

The new organization file defines:

Location
 └── Area
       └── Department
              └── Section

Example:

Outpatient
 └── Medical
       └── Pharmacy
              ├── ER Pharmacy
              ├── OPD Pharmacy
              └── Pediatric Pharmacy

---

Complaint Ownership Rules

A complaint may be owned by:

• A Department
• A Section

Departments always have a Champion.

Sections may optionally have a Champion.

Routing rules:

Section Champion
      ↓
Department Champion

If a Section has no Champion, responsibility falls back to the Department Champion.

---

Target Data Model

Area

class Area(models.Model):
    hospital
    name
    name_en
    name_ar
    code
    status

Represents:

Medical
Non-Medical
Nursing
Support Services

---

Department

class Department(models.Model):
    area = ForeignKey(Area)

    name
    code

    champion
    manager
    manager_1st
    manager_2nd
    manager_3rd

    deputy_manager
    supervisor
    deputy_supervisor

Examples:

Pharmacy
Radiology
Laboratory
Emergency Department

---

Section

Rename:

OrgSubSection

to:

Section

Model:

class Section(models.Model):
    department = ForeignKey(Department)

    name
    code

    champion = FK(Staff, null=True)

    status

Examples:

ER Pharmacy
OPD Pharmacy
Pediatric Pharmacy

---

Remove Sub-Section Layer

Current:

OrgSubSubSection

Business review determined:

• Mostly empty
• Not used for reporting
• Not used for routing
• Not used for ownership

Action:

Deprecate and remove

after data validation.

---

Complaint Model

Target Structure

class Complaint(models.Model):

    department = FK(Department)

    section = FK(
        Section,
        null=True,
        blank=True
    )

    legacy_mapping = FK(
        LegacyHierarchyMapping,
        null=True,
        blank=True
    )

---

Ownership Resolution

Implement:

Complaint.get_owner()

Logic:

if complaint.section and complaint.section.champion:
    return complaint.section.champion

return complaint.department.champion

This becomes the single ownership rule used everywhere.

---

Legacy Data Strategy

Important Rule

Legacy hierarchy is no longer part of the operational model.

Legacy hierarchy exists only to explain historical complaints.

---

Keep Mapping Table

Retain:

LegacyHierarchyMapping

Refactor to:

class LegacyHierarchyMapping(models.Model):

    old_location
    old_main_section
    old_subsection

    department
    section

Purpose:

Legacy Complaint
          ↓
Legacy Mapping
          ↓
Department / Section

---

Remove Operational Usage Of

legacy_location
legacy_main_section
legacy_subsection

from:

• Reporting
• Routing
• Dashboards
• KPIs
• Escalation
• Filters

They may remain temporarily for audit/reference only.

---

Reporting Refactor

New Reporting Rule

All reports must use:

complaint.department
complaint.section

only.

Never use:

legacy_location
legacy_main_section
legacy_subsection

for any new report.

---

Report Grouping

Department-level:

values("department__name")

Section-level:

values("section__name")

Area-level:

values("department__area__name")

---

Dashboard Refactor

Replace:

location__name_en
main_section
legacy_main_section

with:

department
department__area
section

---

Routing Refactor

Send To Department

Current behavior should become:

owner = complaint.get_owner()

No custom routing logic should duplicate ownership checks.

---

Escalation

Escalation should work against:

Department
Section

only.

Legacy hierarchy must never influence escalation.

---

Forms Refactor

Replace all remaining legacy hierarchy forms.

Current:

Location
Main Section
Sub Section

New:

Area
Department
Section

Fields:

area
department
section

Section optional.

---

Naming Cleanup

Rename:

OrgSubSection

→

Section

Rename related:

org_subsections

→

sections

Update:

• serializers
• views
• APIs
• templates
• services

---

Migration Steps

Phase 1

Create:

Area

model.

Populate from Department records.

---

Phase 2

Rename:

OrgSubSection

to:

Section

Update all references.

---

Phase 3

Backfill:

complaint.department
complaint.section

for all historical complaints.

Target:

100%

coverage.

---

Phase 4

Update:

• dashboards
• exports
• KPI services
• analytics

to use new hierarchy only.

---

Phase 5

Update:

• complaint forms
• inquiry forms
• observation forms
• government ticket forms

to use:

Area → Department → Section

---

Phase 6

Mark legacy hierarchy fields as deprecated.

No new writes allowed.

---

Success Criteria

The implementation is complete when:

✓ All complaints have Department assigned.

✓ Reporting uses only Department/Section hierarchy.

✓ Routing uses only Department/Section ownership.

✓ Dashboards use only Department/Section hierarchy.

✓ Legacy hierarchy is retained only for historical reference.

✓ OrgSubSubSection is removed.

✓ OrgSubSection is renamed to Section.

✓ Area is a first-class model.

✓ There is only one source of truth for complaint ownership.