Tickets & Bug Reporting

ScannerSky provides an integrated, role-isolated Ticketing, Bug Reporting, and Feature Request System accessible via Django Unfold Admin.

---

1. Overview & Architecture

The ticketing subsystem enables staff and instructors to submit bug reports, feature requests, improvements, and general support inquiries. Superadmins and designated ticket managers triage, assign, update progress statuses, and resolve issues with automated notification workflows.

flowchart LR
    Submitter([Staff / User]) -->|1. Submit Ticket + Screenshot| TicketSystem[Ticket System]
    TicketSystem -->|2. Automated Notification| Superadmins([Superadmins / Managers])
    Superadmins -->|3. Update Status & Assign| TicketSystem
    TicketSystem -->|4. Automated Notification + Notes| Submitter

---

2. Data Model Specification

Ticket (core.models.Ticket)

Field	Type	Description
title	CharField(255)	Short summary of the bug or feature request.
ticket_type	CharField(32)	Choices: bug, feature, improvement, support.
priority	CharField(32)	Choices: low, medium, high, urgent.
description	TextField	Markdown-supported issue description and replication steps.
image	ImageField	Optional screenshot/attachment saved to tickets/images/%Y/%m/ (enforced max 5 MB size limit).
submitted_by	ForeignKey(User)	The user who created the ticket.
assigned_to	ForeignKey(User)	The developer or administrator assigned to resolve the ticket.
status	CharField(32)	new, in_progress, resolved, canceled.
status_message	TextField	Triage notes and resolution comments provided by administrators.
created_at	DateTimeField	Auto-generated submission timestamp.
updated_at	DateTimeField	Auto-updated modification timestamp.
resolved_at	DateTimeField	Auto-recorded timestamp when status transitions to resolved or canceled.

---

3. Permissions & Role Isolation

Permission Codename	Label	Permitted Actions & UI Behavior
core.can_submit_ticket	Can submit new ticket	Enables the dedicated "Submit New Ticket" header action and submission page. Automatically hides the standard generic + Add Ticket admin button so the custom submission workflow is the sole entry point for regular users.
core.add_ticket	Can add ticket	Reveals the default Django changeform + Add Ticket button (reserved for administrators).
core.can_manage_tickets	Can manage ticket status and assignment	View all tickets across all users, assign developers, change statuses, and post resolution notes.
Superusers (is_superuser)	Global Administrator	Full view, triage, assignment, status update, and deletion permissions.

---

4. Admin Workflows & Custom Actions

Submitting a Ticket

1. Navigate to Tickets & Support in the Unfold admin sidebar.
2. Click the header action "Submit New Ticket".
3. Fill in the title, category, priority, Markdown description, and optional screenshot.
4. Upon submission, the ticket is assigned status new, and superadmins receive an immediate notification.

Updating Status & Assigning

1. Open any ticket row or detail view as a superadmin or ticket manager.
2. Click "Update Status".
3. Select the target status (In Progress, Resolved, Canceled), assign a developer, and provide resolution notes.
4. Saving automatically sets timestamps and delivers a formatted notification to the ticket submitter with the admin notes.

---

5. Realtime Capability & Notification Integration

ScannerSky integrates Tickets with the universal Server-Sent Events (SSE) stream (/admin/events/sse/):

• Universal Model Change Events: Ticket is registered in REALTIME_MODELS (core.signals), dispatching model_change events on create, update, and delete actions.
• Dynamic Changelist Swapping: When viewing the Tickets admin list (/admin/core/ticket/), incoming ticket creations or status changes dynamically swap the table and stat cards (Total Tickets, New, In Progress, Resolved) and pulse-highlight affected rows without requiring a manual page refresh.
• Sidebar Badge Synchronization: The active ticket counter in the navigation sidebar (core.utils.ticket_badge_callback) dynamically synchronizes in real time via the /admin/core/ticket/active-count/ endpoint.
• New Ticket Alert: Automated notifications sent to superadmins (NotificationType.ALERT for High/Urgent, NotificationType.INFO otherwise) with submitter metadata and quick triage links.
• Status Change Alert: Automated notifications delivered directly to ticket.submitted_by (recipient_user) via SSE realtime channel and in-app Notification center.