Prior Authorizations Report

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

This feature provides a Prior Authorizations (PAs) reporting table where users can review PA records by client, insurance, and service number with server-side filtering, sorting, and pagination. It also includes a CPT details popover per PA row, showing utilization and remaining units/hours to help teams quickly assess authorization consumption and expiration risk.

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

• Users who can access Reports and meet the PAs Report card requirements in Reports Access.
• In Reports Access, the PAs Report card is configured with both permissions: update_clients and view_all_clients.
• Users with those permissions can navigate to /reports/pas from the report card.
• Inside this component, there is no additional permission-gated UI action (read-only table interactions for search, sort, date range, pagination, and popover).

Required permissions used by this feature path:

• update_clients: required by Reports Access card visibility for PAs Report.
• view_all_clients: required by Reports Access card visibility for PAs Report.

3. Business Rules & Enforcements

• Rule 1: On first load, the component reads query params (search, from_end_date, to_end_date, sort, direction, per_page, page) and rehydrates internal state.
• Rule 2: If no from_end_date is selected, requests default to from_end_date = today (YYYY-MM-DD).
• Rule 3: Filter state is synced back to URL query params on every data load.
• Rule 4: Search text is trimmed before submit and sent lowercased as search.
• Rule 5: Search input emits with debounce (500ms) before triggering filterByName.
• Rule 6: Date validation enforces to_end_date >= from_end_date when both dates are set.
• Rule 7: Invalid date range triggers error modal and clears both date inputs.
• Rule 8: Clearing one/both dates still triggers reload with valid remaining/default filters.
• Rule 9: Sorting is tri-state per column: asc -> desc -> none.
• Rule 10: Sorting changes reset pagination to page 1 and reload data.
• Rule 11: Pagination is server-driven using page and per_page; visible paginator window is capped to 3 pages with ellipsis support.
• Rule 12: Loading state shows skeleton rows; empty state shows No data available.
• Rule 13: CPT popover only renders from PA rows that have CPT data.
• Rule 14: CPT status labeling follows: Expires soon (not expired and days_remaining <= 3), Expired (is_expired), Active (otherwise).

4. UI Placement

• Reports entry path:

1. Main app -> Reports.
2. Reports Access -> PAs Report card.
3. Navigates to primary route: /reports/pas.

• Main screen sections in this feature:

1. Back button (returns browser history).
2. Search input (by name text).
3. End date range filters (From / To).
4. Prior Authorizations table (sortable columns).
5. CPT utilization popover on PA number hover.
6. Footer controls (record range, page size, pagination).

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

Scenario A: Review PA records for current scope

1. Open Reports and enter PAs Report.
2. Optionally type client/name search text.
3. Optionally set From and To end-date filters.
4. Review matching rows with client, PA number, insurance, start date, and end date.
5. Use sorting and paginator controls to navigate result sets.

Scenario B: Inspect CPT utilization details

1. Locate a row with a PA number (non-empty CPT set).
2. Hover the PA number link.
3. Review CPT-level metrics: total units, used units, utilization %, remaining units/week, and remaining hours/week.
4. Check status label (Active / Expires soon / Expired).

Scenario C: Refine results with sorting and page size

1. Click a sortable header (Client, PA number, Insurance, Start date, End date).
2. Click same header again to switch asc/desc, and a third time to clear sorting.
3. Change Show X per page selector.
4. Move through pages with Previous/Next or direct page buttons.

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

• Q: What happens if no query params are provided?

• A: The component loads with defaults (including from_end_date = today) and then writes active params to URL.

• Q: What if the user enters a date range where To is earlier than From?

• A: An Invalid dates modal is shown and both dates are cleared.

• Q: What if user clears one or both dates?

• A: The table reloads; if From is missing, request falls back to today for from_end_date.

• Q: What if there is no data returned by API?

• A: The table displays No data available.

• Q: What if a PA row has no CPT data?

• A: The PA number cell shows -, and no CPT popover is available.

• Q: What happens on API error while loading?

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