Add GUI Reporting Option – Overvoted Result Forms Report

[JohnMwashuma]

Context

The system currently generates a CSV file listing overvoted result forms—forms where the number of ballots inside (recorded via the reconciliation form) exceeds the number of registrants at the station (from the station model). This CSV generation is handled by a management command, which relies on complex ORM queries and subqueries to match reconciliation data with station data. However, the HNEC team have expressed the need for a real-time, GUI-based report that allows them to quickly view and assess these overvoted forms without manually running commands and inspecting CSV files.

Current Issues Identified:

• Manual Process:
  Administrators must run a management command to generate a CSV report, which is less efficient than an on-demand GUI report.
• Lack of Visibility:
  There is no immediate, web-based report to review overvoted result forms, making it harder to monitor and react to overvote conditions.
• Inconsistent Workflow Integration:
  The CSV report does not integrate with other reporting tools or dashboards in the system, causing extra steps for the end-users.
• Operational Overhead:
  Reliance on manual CSV generation increases the operational overhead and potential delays in identifying problematic forms.

To improve operational efficiency and provide real-time insights, a new GUI reporting option must be added that displays the list of overvoted result forms directly within the application.

---

Proposed Changes

• Develop a report that identifies result forms where the number of ballots inside exceeds the number of registered voters for a station.
• Display these forms in a table with relevant details such as center, station, number of votes, and number of registrants.
• Implement sorting and filtering options to prioritize forms with the highest discrepancies.
• Provide options to export the report and notify relevant personnel for further investigation.

---

Proposed Implementation plan

1️⃣ Create a New Backend Report View for Overvoted Result Forms

✅ Develop a new class-based view (e.g., OvervotedResultFormsReportView):

• Reuse the logic from the existing CSV generation task to filter ReconciliationForm records where number_ballots_inside_box is greater than the station registrants (retrieved via the Station model).
• Annotate the queryset with relevant fields such as barcode, center code, station number, ballots inside, station registrants, sub-race name, and sub-race code.
• Ensure that only result forms with FormState.ARCHIVED and EntryVersion.FINAL are considered, and that the reconciliation form is active.

2️⃣ Implement a New Template for the Overvoted Report

✅ Design a new template (e.g., reports/overvoted_forms.html) that:

• Displays the list of overvoted result forms in a table format.
• Includes columns for Barcode, Center Code, Station Number, Ballots Inside, Station Registrants, Sub Race Name, and Sub Race Code.
• Optionally offers filtering or sorting options to help administrators quickly locate specific records.

3️⃣ Update URL Configuration

✅ Add new URL patterns to expose the GUI report:

• Define a URL (e.g., /reports/overvoted-forms/) that maps to the new report view.
• Ensure the URL is accessible via the main navigation or reporting dashboard.

4️⃣ Navigation and Frontend Integration

✅ Integrate the new report into the existing system:

• Add a link to the “Overvoted Result Forms Report” in the navigation menus or reporting dashboard.
• Ensure proper access control so that only authorized users can view this report.

---

Acceptance Criteria

✅ A new report view is implemented that aggregates and filters result forms to display only those where the number of ballots inside exceeds the station registrants.
✅ The aggregation logic correctly mirrors the existing CSV generation logic, using reconciliation data linked to result forms and station information.
✅ A new template renders a table with the following columns: Barcode, Center Code, Station Number, Ballots Inside, Station Registrants, Sub Race Name, and Sub Race Code.
✅ A dedicated URL endpoint (e.g., /reports/overvoted-forms/) is available and integrated into the system’s navigation.
✅ Unit tests are added to verify the correctness of the filtering and aggregation logic.
✅ The new report is reviewed in QA/UAT to ensure it meets design standards and user expectations.

---

Estimated Level of Effort (LOE)

Task	Complexity	Estimated Time
1. Develop the Report View with Overvote Filtering Logic	🟡 Medium	4-6 hours
2. Create the Report Template	🟡 Medium	3-5 hours
3. Update URL Configuration & Navigation Integration	🟢 Low	2-3 hours
4. Write Unit Tests & Update Existing Tests	🟡 Medium	3-5 hours
5. QA & UAT (User Testing & Validation)	🟠 High	4-6 hours
6. Deployment & Documentation Updates	🟢 Low	2-3 hours

Total Estimated LOE: ~18-28 hours (~2-4 working days)

🚀 Effort Level: 🟡 Medium Complexity