Insurance Services Add/Edit Workflow

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

This workflow lets users create and update insurance service records that drive billing behavior (CPT, provider types, modifiers, pricing, and optional automation criteria). It standardizes how each insurance+location service rule is captured before notes and claims are processed.

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

• Users with manage_insurances: Can open the modal, submit create/update requests, and maintain service records.
• Users without manage_insurances: Cannot use add/edit actions from the Insurance Services UI.
• Billing/clinical operations users: Indirect consumers of these settings through downstream note and claim behavior.

3. Business Rules & Enforcements

• Rule 1: Required fields for create are insurance_id, location_id, cpt_code, provider_types, description, and unit_price.
• Rule 2: unit_price must be numeric and between 0 and 999999.99.
• Rule 3: Provider types are selected as checkboxes and persisted as a comma-separated value.
• Rule 4: Modifiers are optional and persisted as a dash-separated value.
• Rule 5: On CPT selection, the form can auto-fill description with the CPT default text when description is empty.
• Rule 6: Backend blocks duplicate service overlaps for the same insurance + location + cpt + modifiers when provider types overlap.
• Rule 7: Edit uses the same modal with prefilled values; save calls update (PUT /api/v2/insurance-services/{id}), while add calls create (POST /api/v2/insurance-services).
• Rule 8: Validation errors returned by backend are surfaced inline per field.

4. UI Placement

1. Sidebar > Insurance (/insurance/list).
2. Open insurance edit (/insurance/list/edit/:id).
3. Go to Insurance Services tab.
4. Use Add Service (new) or row Edit action (update).

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

Scenario A: Add a new insurance service

1. Open the insurance in edit mode and go to Insurance Services.
2. Click Add Service.
3. Select Location and CPT Code.
4. Confirm/adjust Description.
5. Select at least one Provider Type.
6. Enter Unit Price.
7. Optionally select Modifiers and Automation settings.
8. Click Add Service.

Scenario B: Edit an existing service

1. In the list, click the row Edit icon.
2. Update any needed fields (for example provider types, modifiers, price, or automation).
3. Click Update Service.
4. Confirm the updated row appears in the list reload.

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

• Q: What happens if I submit without provider types selected?
  A: Submission is blocked and the form shows a provider-types validation error.
• Q: What happens if unit price is negative or not numeric?
  A: Backend and frontend validation reject the submission.
• Q: What happens if another service already covers the same insurance/location/CPT/modifier with overlapping provider types?
  A: Backend returns a conflict-style validation error for provider_types.
• Q: Can I edit only one field without retyping all values?
  A: Yes. The edit modal is prefilled and you can update only the necessary fields.