Copy Appointment

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

This feature lets users duplicate an existing appointment from the calendar modal instead of creating each recurring session manually. It reduces repetitive data entry while preserving the original appointment structure for patient, provider, schedule block, POS and POS 99 details, CPT, and status.

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

• Provider roles (for example RBT/BCBA/Analyst): Can copy appointments they can open in their own calendar context.
• Admin-style roles (for example Superadmin/Admin/Owner/Manager) or any role with manage_notes: Can open shared calendars (after selecting provider/patient context) and copy appointments from that context.

Permission-related behavior:

• There is no separate copy-specific permission gate in the modal; availability depends on being able to open the appointment details modal.
• manage_notes controls shared-calendar access, which indirectly controls which appointments a user can copy.
• Appointment lookup is scoped to the current location context.

3. Business Rules & Enforcements

• Rule 1: Copy starts from View Appointment modal by clicking the Copy appointment icon.
• Rule 2: In manual mode, at least one date must be selected before Duplicate is enabled.
• Rule 3: Manual date selection excludes the original appointment date and blocks past dates in the date picker.
• Rule 4: Non-manual duplication requires a duplication pattern and month limit (1 to 6 months in the UI).
• Rule 5: The backend creates new appointments using the base appointment values (patient_id, location_id, provider_id, session time, POS, POS 99 description, CPT, and status).
• Rule 6: Duplicated appointments clear supervisor_id and description, even when those values existed on the original appointment.
• Rule 7: If duplication fails (validation or API error), the system shows an error modal and no success refresh is triggered.

4. UI Placement

1. Medical > Calendar.
2. Route: /calendar/view.
3. Click an existing appointment event to open View Appointment (ModalCalendarV2Component).
4. In the top-right action bar, click the copy icon (Copy appointment).
5. The modal switches to the duplicate form (app-duplicate-appointment) with duplication options and submit/cancel actions.

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

Scenario A: Duplicate to specific dates (manual mode)

1. Open Medical > Calendar.
2. Click the target appointment, then click Copy appointment.
3. Set Duplication type to Select specific dates.
4. Click one or more valid dates in the calendar.
5. Click Duplicate.
6. Confirm the success message and verify new events appear in the calendar view after refresh.

Scenario B: Duplicate as recurring pattern

1. Open an appointment and click Copy appointment.
2. Choose Duplicate Monday to Friday, Duplicate Monday to Sunday, or Duplicate same weekday (every week).
3. Select a Duplication limit (1 to 6 months).
4. Click Duplicate.
5. Confirm success and validate that generated appointments follow the selected pattern.

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

• Q: What happens if I choose manual mode but do not select dates?
  A: The Duplicate action stays disabled until at least one date is selected.

• Q: Can I duplicate into the same original date or into past dates from the UI?
  A: No. The date picker blocks the original appointment date and past dates.

• Q: What if the duplication request fails in the backend?
  A: The app shows an error modal (Error duplicating appointments) and does not show the success confirmation. Duplicated records preserve core session details, but supervisor and description are reset.