Weekly Reports Generation

1. What does this feature do? (High-Level Overview)

Weekly Reports Generation allows administrators to manually trigger weekly report generation for all patients when a scheduled process did not run as expected. It provides an operational recovery path to keep BIP chart data complete.

2. Who is this for? (Roles & Permissions)

• Superadmin: Can access and run this tool from Admin View.
• Admin: Can access and run this tool from Admin View.
• Custom administrative roles with use_admin_tools: Can access and run this tool when the permission is granted.

Required Permission: use_admin_tools

3. Business Rules & Enforcements

• Rule 1: The generation endpoint is protected by the permission use_admin_tools.
• Rule 2: The admin page accepts only Saturdays from fully completed past weeks.
• Rule 3: Current week dates are blocked to avoid incomplete-week generation.
• Rule 4: The request is executed in all-patients mode from this screen.
• Rule 5: From this admin page, generation runs with force_update = false, so existing weekly reports are kept and only missing records are created.
• Rule 6: A 45-second cooldown is enforced in the UI after each submission to reduce repeated triggers.
• Rule 7: On backend processing, week boundaries are normalized to Sunday-Saturday for report generation.

4. UI Placement

1. Admin View > Settings > Weekly Reports Generation (/settings/weekly-reports-generation) — Tool to trigger generation for all patients.
2. Form controls on this page:
   • Week selector (Saturday only, past weeks only)
   • Generate action button

5. How-To Guide (Step-by-Step)

Scenario A: Recover weekly reports after a failed scheduled run

1. Log in with an account that has use_admin_tools.
2. Open Settings in Admin View.
3. Click Weekly Reports Generation.
4. Select the Saturday of the week you need to regenerate.
5. Confirm the highlighted week range shown by the tool.
6. Click Generate weekly reports.
7. Wait for the success confirmation and allow the cooldown window to finish.

Scenario B: Re-run for a different week

1. After cooldown, choose another past Saturday.
2. Confirm the selected week range.
3. Click Generate weekly reports again.
4. Monitor BIP charts/reports to confirm the missing data has been recovered.

6. What happens if…? (Edge Cases / FAQ)

• Q: Can I choose between force recalculation and only-missing from this admin page?

  • A: Not currently. This page triggers generation without force overwrite, which preserves existing weekly reports and fills missing ones.

• Q: What happens if I select a non-Saturday date?

  • A: The UI blocks it and asks for a Saturday from a completed week.

• Q: What if I need to overwrite existing weekly reports?

  • A: Use a flow that sends force = true (for example, patient-level admin tool/API), because this specific admin page does not expose force overwrite.