Billable Hours Report

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

This feature shows aggregated billable activity by location and CPT code for a selected date range. It helps billing and operations teams quickly review total units, hours, and notes, with an optional weekly breakdown and PDF export.

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

• Superadmin: Can access the report across locations according to global access rules.
• Users with manage_notes in the current location context (for example, Admin/Owner/Manager depending role setup): Can open and use the report in that location.

Required permission: manage_notes (unless the user is SUPERADMIN).

3. Business Rules & Enforcements

• Rule 1: date_start and date_end are required to run the report.
• Rule 2: date_end must be the same as or later than date_start.
• Rule 3: The date range cannot exceed 62 days.
• Rule 4: The request requires current location context (X-Location-ID). If location_id is sent, it must match X-Location-ID.
• Rule 5: Access is restricted to users with manage_notes in the current location (or SUPERADMIN), and results are scoped to the active location context.
• Rule 6: Only notes with a CPT code are aggregated; soft-deleted notes are excluded.
• Rule 7: Units are calculated from note session times using 15-minute units with an 8-minute rounding threshold.
• Rule 8: Weekly breakdown is generated in Sunday-to-Saturday ranges, adjusted to the selected start/end dates.
• Rule 9: PDF export is available only when report data is present.

4. UI Placement

1. Reports > Human Resources > Billable Hours Report (card entry point).
2. Route: /reports/location-cpt.
3. Search section: Date range, note type, insurance, CPT code, status, billed, paid, patient, provider, and supervisor filters.
4. Billable Hours Summary section: Total units, total notes, total hours, location/CPT breakdown, and weekly breakdown details.
5. Export action: Export PDF button at the top-right of the summary section when data exists.

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

Scenario A: Review billable hours for the last completed week

1. Open Reports > Human Resources > Billable Hours Report.
2. Confirm the default range (last Sunday to last Saturday) or click Last Week.
3. Adjust filters as needed (for example, insurance, provider, CPT code, billed/paid).
4. Click Search (or use filter auto-refresh on field changes).
5. Review totals (units, notes, hours) and expand weekly breakdown rows per location/CPT code.

Scenario B: Generate a PDF version of the report

1. Run a report that returns data.
2. Click Export PDF.
3. Select sections to include (Units, Hours, Notes).
4. Choose table format (Single table for entire period or Separate table for each week).
5. Click Generate PDF and wait for the file download.

Scenario C: Correct a blocked query due to date range

1. Set a date range longer than 62 days.
2. Review the warning message indicating the report limit.
3. Reduce the range to 62 days or less.
4. Run the search again to load results.

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

• Q: What happens if a user without manage_notes opens the report route?
  • A: The backend blocks access with an insufficient-permissions response.
• Q: What happens if no location context is provided?
  • A: The request is rejected because X-Location-ID is required.
• Q: Why can the report show no rows even with a valid date range?
  • A: The report only aggregates notes that have CPT codes and match the selected filters within the active location scope.