Client Providers Assignment

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

This feature allows assigning and unassigning clinical professionals to a client from the Providers tab inside the client profile edit flow. It centralizes selection of RBT, RBT 2, BCBA Supervisor, BCBA 2, Clinical Director, and Case Manager using a shared modal with search and backend-driven availability filters.

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

• Users with update_clients can enter edit mode in the Providers section (guarded by appEditWrapper in client profile).
• Users without update_clients can view assigned providers but cannot open edit mode.
• For selector filtering, each provider slot applies backend permission filters when opening the modal:
• BCBA Supervisor / BCBA 2: request includes permission=create_note_bcba.
• Clinical Director / Case Manager: request includes permission=manage_notes.
• RBT / RBT 2: no explicit permission filter is passed from this component.

Required permissions used by this feature path:

• update_clients: enables provider assignment edit mode and save/cancel actions.
• create_note_bcba: used as provider query filter for BCBA slots.
• manage_notes: used as provider query filter for Clinical Director and Case Manager slots.

3. Business Rules & Enforcements

• Rule 1: Edit form initializes from client-assigned ids first; if missing, it falls back to doctor inputs from parent state.
• Rule 2: On input changes (client/doctors), editable provider state is rehydrated to remain in sync.
• Rule 3: Modal doctor query always scopes by client location_id and requests up to 1000 records.
• Rule 4: Modal search text is trimmed, lowercased, and sent as search with 500ms debounce from UI input.
• Rule 5: Provider query always applies status filter:
• RBT/RBT2/BCBA/BCBA2 fields use status=active,incoming.
• Clinical Director/Case Manager fields use status=active.
• Rule 6: Optional provider-permission filter is attached only for fields that define it (BCBA or manage_notes slots).
• Rule 7: Optional type filter is applied client-side after API response (RBT slots require type === RBT).
• Rule 8: A doctor cannot be assigned to two different provider fields in the same edit session.
• Rule 9: Already-used doctors are visually disabled in the modal list and cannot be clicked.
• Rule 10: Clearing a provider sets the field to undefined in child state and marks it as explicitly cleared for name resolution.
• Rule 11: Name resolution priority in edit inputs is: selected id from allDoctors -> matching fallback doctor input -> embedded client name/surname.
• Rule 12: Save emits a merged client payload from child; parent maps it to staff payload and calls updatePatientStaff.
• Rule 13: Parent staff payload currently includes only non-null and non-undefined ids.
• Rule 14: On successful save, parent reloads client profile and shows success feedback.
• Rule 15: On save error, parent restores previous doctors snapshot and shows error feedback.

4. UI Placement

• Main route context:

1. Medical > Patients.
2. Open client profile.
3. Providers tab.
4. Enter edit mode (requires update_clients).

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

Scenario A: Assign a provider to an empty slot

1. Open client profile and go to Providers tab.
2. Enter edit mode.
3. Click the target field (for example RBT or BCBA Supervisor).
4. In modal, search or pick an available provider.
5. Click Save Changes.
6. System updates staff endpoint and reloads profile assignments.

Scenario B: Replace an existing provider

1. In edit mode, click the field that already has an assigned provider.
2. Select a different provider from modal list.
3. Save changes.
4. Updated assignment is persisted and reflected after profile reload.

Scenario C: Remove an assignment

1. In edit mode, click the X button on a provider field (or double click in RBT field where enabled).
2. Field becomes empty in the edit form.
3. Save changes.
4. Parent sends staff update payload and refreshes the profile view.

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

• Q: What if the same doctor is selected for multiple fields?

• A: Selection is blocked in the modal; already-selected doctors are disabled and direct duplicate click also shows an alert.

• Q: What if there are no providers available for current filters?

• A: Modal table shows Data not available.

• Q: What if the provider query fails?

• A: Modal list is cleared and loading state ends.

• Q: What if save fails in parent component?

• A: Parent restores previous doctor state and shows error alert.

• Q: Are incoming staff selectable for all roles?

• A: No. Incoming is enabled only for RBT/RBT2/BCBA/BCBA2; Clinical Director and Case Manager are active-only.

• Q: Does clear always guarantee backend unassignment?

• A: Not fully guaranteed with current parent payload logic, because null/undefined fields are omitted from buildStaffPayload. Effective unassignment depends on backend handling and current payload strategy.