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).
• Rule 15: When a CPT line has a configured weekly limit on its PA Service, the popover’s Weekly Units and Weekly Hours columns reflect that configured value directly (units as configured, hours as configured / 4). Otherwise, both values are derived from remaining units divided by remaining weeks.
• Rule 16: Each CPT row that uses a configured weekly limit is marked with a red asterisk () next to its Weekly Units and Weekly Hours values. A legend ” Configured weekly limit” appears below the popover table when at least one CPT in the popover uses a configured value. See PA Service Configured Weekly Limit for how this field is set and enforced.

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. Look for the red asterisk (*) next to Weekly Units or Weekly Hours. Rows with the asterisk show the configured weekly limit instead of the derived average; rows without it show the average computed from remaining units over remaining weeks.
5. 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.

• Q: Why does one CPT row show different Weekly Units / Weekly Hours than another within the same PA Service?

• A: Rows marked with a red asterisk (*) use the value configured in the PA Service’s “Weekly Units Limit” field. Rows without the asterisk fall back to an average derived from remaining units and remaining weeks. See PA Service Configured Weekly Limit for details on how the field is set.