Worked Hours By Providers Report

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

This feature provides a Worked Hours reporting table that compares hours worked vs remaining authorization units for each client by provider (should be interpreted as employees.) The screen supports server-side sorting and pagination, date-based reload, and includes a daily summary table with total worked hours and total remaining units.

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

• Users who can access Reports and meet the Worked Hours By Providers Report card requirements in Reports Access.
• In Reports Access, the Worked Hours By Providers Report card is configured with both permissions: view_employees and view_all_clients.
• Users with those permissions can navigate to /reports/hours from the report card.
• In this feature context, provider data maps to employee data (provider = employee).
• This component is read-only (no create/update actions inside the report UI).

Required permissions used by this feature path:

• view_employees: required by Reports Access card visibility and employee/provider context.
• view_all_clients: required by Reports Access card visibility and client context.

3. Business Rules & Enforcements

• Rule 1: When the page opens, the report automatically uses yesterday’s date and loads data.
• Rule 2: Every request includes fixed report settings required by the backend.
• Rule 3: A date is always required to load results.
• Rule 4: Sorting is done by the server. Clicking a column cycles through ascending, descending, and no sort.
• Rule 5: When sorting changes, results return to page 1.
• Rule 6: Pagination is handled by the server using current page and rows per page.
• Rule 7: Changing rows per page resets results to page 1 and reloads data.
• Rule 8: Pagination stays compact around the current page, with first/last navigation when needed.
• Rule 9: While loading, the table shows skeleton rows.
• Rule 10: If no records are found, show: No data available.
• Rule 11: A CPT row shows no active PA service only when Remaining Units is missing (not when it is 0).
• Rule 12: Summary totals are based on the currently loaded rows:
  • Total Hours Worked is calculated from CPT units and shown in hours/minutes.
  • Total Remaining Units is the sum of remaining units.
• Rule 13: If loading fails, stop loading, clear visible rows, and log the error in console.
• Rule 14: Location scope is handled by backend context, not by sending location_id from this screen.

4. UI Placement

• Reports entry path:

1. Main app -> Reports.
2. Reports Access -> Worked Hours By Providers Report card.
3. Navigates to primary route: /reports/hours.

• Main screen sections in this feature:

1. Back button (returns browser history).
2. Search Date input (date picker).
3. Worked hours table (sortable columns).
4. Row-level metrics by client and provider (employee) with CPT values.
5. Footer controls (record range, page size selector, pagination).
6. Bottom summary table (selected date, total worked hours, total remaining units).

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

Scenario A: Review worked hours for a specific date

1. Open Reports and enter Worked Hours By Providers Report.
2. Select the desired Search Date.
3. Review rows by Client and Provider (employee).
4. Compare Hours, Average Hours, and Remaining Units.
5. Use pagination to inspect additional rows.

Scenario B: Sort performance values

1. Click a sortable column header (Client, Provider, CPT, Hours, Average Hours, Remaining Units).
2. Click same header again to switch asc/desc.
3. Click same header a third time to clear sorting.
4. Confirm results reload from page 1 after sorting changes.

Scenario C: Inspect daily totals

1. Set a date in Search Date.
2. Confirm table data loads.
3. Check summary table at the bottom:
4. Date Selected.
5. Total Hours Worked.
6. Total Remaining Units.

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

• Q: What happens on first load without user input?

• A: The component sets Search Date to yesterday and loads data automatically.

• Q: What if no records are returned for the selected date?

• A: The table displays No data available and summary totals remain zeroed.

• Q: What if the API fails during data load?

• A: Loading stops, visible list is cleared, and the error is logged in console.

• Q: What if a CPT has no remaining_units value?

• A: The row shows no active PA service.

• Q: What if remaining_units is exactly 0?

• A: It is treated as a valid value and rendered as 0 (not as no active PA service).

• Q: Are providers different from employees in this report?

• A: No. In this report context, providers are treated as employees.

• Q: Do totals represent all backend data or only current page rows?

• A: Totals are calculated from the currently loaded page rows in the component.