Insurances List

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

This feature provides a central list of insurers used by the billing and clinical workflows. It allows authorized users to find insurers quickly, open details for updates, and export the current list view.

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

• Users with manage_insurances (commonly Admin/Owner in default role setups): Can open the Insurance menu, search insurers, open add/edit screens, and export list data.
• Superadmin users: In addition to the list actions, they can delete an insurance from the edit screen (Danger Zone).

3. Business Rules & Enforcements

• Rule 1: The list loads from GET /api/v2/insurance with server pagination and search support.
• Rule 2: Server-side search applies across insurer name, state, payer_id, and city.
• Rule 3: The UI requests per_page=100 by default and paginates using page.
• Rule 4: Each row links to the insurer edit page (/insurance/list/edit/:id) for updates.
• Rule 5: Export actions (TXT, CSV, XLSX) use the currently loaded dataset in the page context.
• Rule 6: Insurance records are global entities (not tied to a single location on the insurance table), so the same insurer master record is reused across locations.

4. UI Placement

1. Sidebar > Insurance (/insurance/list): Entry point to the insurers master list.
2. Insurance List header: Search input, add button, refresh button, and export actions.
3. Insurance table row: Click insurer name to open edit details.
4. Add action (/insurance/register): Create a new insurer from the list page.

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

Scenario A: Find and update an insurer

1. Open Insurance from the main sidebar.
2. In Search here, type part of the insurer name, city, state, or payer ID.
3. Open the target row by clicking the insurer name.
4. Update the needed fields in the edit screen and click Save.

Scenario B: Add a new insurer and export the view

1. Open Insurance > Insurance List.
2. Click the + button to open Add Insurance.
3. Complete required fields and save.
4. Return to the list and use TXT, CSV, or XLSX export depending on stakeholder needs.

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

• Q: If I switch location context, does the insurer list change?
  A: The insurer master records are global, so they are not created per location.
• Q: Can non-superadmin users delete insurers from the list?
  A: No. Deletion is exposed from the edit view only for Superadmin users.
• Q: Does export include every historical page automatically?
  A: Export uses the currently loaded page dataset. Users can navigate/filter first, then export the view they need.