Edit Appointment

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

This feature allows authorized users to update an existing calendar appointment when schedule or session details change. It keeps appointment data accurate for clinical follow-up, note creation, and downstream billing workflows, including POS 99 details when the session requires them.

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

• Provider roles (for example RBT/BCBA/Analyst): Can edit appointments visible in their own calendar context.
• Admin-style roles (for example Superadmin/Admin/Owner/Manager) or any role with manage_notes: Can access shared calendars and edit appointments after selecting a provider or patient context.

Permission-related behavior:

• manage_notes enables shared-calendar access (provider/patient context switching) and cross-calendar editing workflows.
• create_note_bcba affects CPT availability in the edit form when provider context changes; if the selected provider does not have this permission, CPT options are restricted to 97153.

3. Business Rules & Enforcements

• Rule 1: The edit action is only available from the appointment detail modal when the appointment does not already have a related note.
• Rule 2: Required data must be valid on update: patient_id, provider_id, location_id, session_date, pos, cpt_code, time_in, time_out, and status.
• Rule 3: Time validation is enforced: time_out must be after time_in.
• Rule 4: If POS 99 is selected, a POS 99 description is required and is limited server-side to 35 characters.
• Rule 5: The backend enforces location and patient authorization before updating, and re-checks authorization if location or patient values are changed during edit. Appointment access remains scoped to the current location context.
• Rule 6: The selected patient must have valid available PA/CPT services; when none are available, the UI warns the user and valid submission is blocked until a valid CPT can be selected.
• Rule 7: In the time UI, Time Out remains disabled until Time In is selected, and the minimum allowed Time Out is tied to the selected Time In.
• Rule 8: The success message reminds users that billing or payment only occurs once the related note is fully completed.

4. UI Placement

1. Medical > Calendar.
2. Route: /calendar/view.
3. Open an existing appointment from month/week/day calendar views.
4. In the appointment modal, click the pencil icon (Edit appointment) when available.
5. The same Appointment form opens in edit mode with existing values prefilled.

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

Scenario A: Provider edits an appointment in own calendar

1. Open Medical > Calendar.
2. Click an existing appointment event.
3. In the modal, click the Edit appointment icon.
4. Update one or more fields (for example Time In/Time Out, POS, POS 99 description, CPT, or description).
5. Click Save.
6. Confirm the success message and verify the updated event in the calendar.

Scenario B: Manager/Admin edits an appointment in shared-calendar mode

1. Open Medical > Calendar.
2. Select a provider or patient from filters.
3. Click the target appointment event.
4. Click Edit appointment in the modal.
5. Adjust needed fields and click Save.
6. Confirm success and verify the event updates in the selected calendar context.

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

• Q: What happens if an appointment already has a related note?
  A: The edit icon is not shown in the appointment modal, so the appointment cannot be edited from this flow.

• Q: What if Time Out is earlier than Time In when saving edits?
  A: The update fails validation because time_out must be after time_in.

• Q: What happens if I change the appointment to POS 99? A: The POS 99 description becomes required before the edited appointment can be saved.