Insurance Services List

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

This feature shows all service configurations tied to a selected insurance and lets authorized users filter, review, and maintain those records by location, CPT, and provider type. It also includes controlled copy workflows to replicate services from another location or another insurance.

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

• Users with manage_insurances (commonly Admin/Owner in default setups): Can add, edit, delete, and run copy operations from this list.
• Users with access_all_locations: Can load all locations in filters and are not restricted to assigned-location subsets in copy flows.
• Users without manage_insurances: Can still see list data if they reach the screen, but action buttons are hidden.

3. Business Rules & Enforcements

• Rule 1: The list loads from GET /api/v2/insurance-services with insurance_id fixed to the insurance currently open in edit mode.
• Rule 2: Backend applies location-based access filtering on the query; users only see records from locations they are allowed to access unless they have global access.
• Rule 3: Supported list filters are location_id, cpt_code, and provider_type; results are paginated (per_page defaults to 15 in the UI).
• Rule 4: Delete action removes services via soft delete (DELETE /api/v2/insurance-services/{id}).
• Rule 5: Copy Services from Another Location always previews totals first, then replaces destination services (delete + copy) for either: current insurance only, or all insurances.
• Rule 6: Copy Services from Another Insurance previews per location, then replaces destination insurance services across the locations the user can access.
• Rule 7: Copy execution is blocked when source has no services to copy.

4. UI Placement

1. Sidebar > Insurance (/insurance/list).
2. Open an insurance record in Edit Insurance (/insurance/list/edit/:id).
3. Select tab Insurance Services.
4. Use header actions (Add Service, copy actions), filters, table rows, and pagination controls.

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

Scenario A: Review and filter current insurance services

1. Open Insurance from the sidebar and enter the insurance edit screen.
2. Go to the Insurance Services tab.
3. Use Location, CPT Code, and Provider Type filters.
4. Review the resulting rows and page through results as needed.

Scenario B: Copy services from another insurance

1. In Insurance Services, click Copy Services from Another Insurance.
2. Select the source insurance and click Preview.
3. Review totals (to copy and to delete) by location.
4. Confirm copy to replace destination insurance services with source configuration.

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

• Q: What happens if there are no services for this insurance/filter set?
  A: The list shows an empty state with guidance to clear filters or add the first service.
• Q: What happens if source and destination are the same location/insurance during copy?
  A: The request is rejected by validation (different rule).
• Q: What happens if I can only access a subset of locations?
  A: Copy and list behavior is limited to your accessible locations.
• Q: Are copy operations additive?
  A: No. Destination data is replaced (existing destination services are deleted, then source services are inserted).