G2-CM: Backend APIs — SLA, drafts, verification, escalation, analytics, and role-based access

[ManbirS07]

Proposed changes

Brief description of what is fixed or changed

• Introduces role-based access control for user (student/faculty), caretaker, supervisor, and admin.
• Adds role/profile models and migrations, serializers, permission classes, and middleware/decorators to enforce role-specific behavior.
• Implements REST endpoints for role assignment and management, request creation and workflows, and admin operations.
• Adds unit tests covering key permission flows and request lifecycle.

Main API Endpoints

• GET /complaint/api/studentcomplain — Lists complaints visible to the current user (own complaints, plus caretaker area and supervisor type/area scope).
• POST /complaint/api/newcomplain — Creates a submitted complaint or a draft; applies SLA and auto-assignment when not a draft.
• GET /complaint/api/user/detail/{id} — Returns one complaint with complainer info, serialized complaint including events, and worker/assigned-worker details.
• PUT /complaint/api/updatecomplain/{id} — Updates a complaint with validated status transitions (status changes restricted to caretaker/supervisor; closed via verify only).
• POST /complaint/api/caretaker-action/{id} — Assigned caretaker (or matching supervisor on escalated) sets status to in-progress or resolved with required remarks (optional ETA/attachment).
• POST /complaint/api/verify/{id} — Complainant or supervisor verifies a resolved complaint: approve closes it; reject sends it back to reopened with notes.
• POST /complaint/api/escalate/{id} — Caretaker escalates with escalation_reason when the lifecycle allows it.

Key Highlights

• Assignment: Complaints pick up workers using a layered policy — explicit category-and-location rules first, then location-wide defaults, then a global fallback. Worker lookup follows a chain: prefer area and category, then category only, then any worker if still unassigned.
• Assignment traceability: Whenever a complaint is created, a draft is submitted, or a reopen path reassigns work, assignment details (policy source, strategy, team, etc.) are stored on the complaint’s lifecycle audit events.
• SLA: Urgent complaints get roughly 24 hours to resolution target, Standard 72 hours, Low Week (168 hours). Drafts do not get SLA until they are formally submitted.
• Lifecycle: Status changes obey a fixed allowed transition map — invalid jumps are rejected. Complaints cannot be jumped to closed via a generic status update; they must reach resolved first and then be verified through the verification flow before closure.
• Auditing: Every meaningful step logs a structured audit record (who did what, from/to status, notes, structured metadata).
• Notifications: Stakeholders are notified on complaint creation, status/progress updates, verification outcomes, reopen requests/approval, and bulk reassignment (where applicable).

Testing

• Auth & listing: Unauthenticated list rejected, student sees only own complaints, caretaker filtered by area and supervisor by category and optional area.
• Lifecycle: invalid transitions are rejected, remarks required for progress statuses, closure blocked on generic PUT unless using verify and detail access denial for unrelated student.
• Verify / feedback / reopen: Verify only when resolved, complainant approve closes, supervisor reject reopens, feedback only after close and only by complainant and reopen reasons and time window enforced.
• Escalation & tasks: Manual escalate logs and notifies (mock), supervisor can resolve via caretaker-action and escalate_overdue_complaints and send_sla_deadline_reminders covered with mocks/de-duplication.

Checklist

Put an x in the boxes that apply

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have created new branch for this pull request
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• My changes does not break the current system and it passes all the current test cases.

[FusionIIIT-Bot]

Congratulations for making your first Pull Request at Fusion!! 🎉 Someone from our team will review it soon.