Create Appointment

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

This feature lets users create calendar appointments for patient sessions, so schedules are visible and ready for later clinical documentation and billing workflows. It standardizes session details such as patient, provider, date, time, POS, POS 99 description when needed, and CPT before work is performed.

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

• Provider roles (for example RBT/BCBA/Analyst): Can create appointments from their own calendar view.
• Admin-style roles (for example Superadmin/Admin/Owner/Manager) or any role with manage_notes: Can create appointments in other providers’ or patients’ calendars after selecting a provider or patient context.

Permission-related behavior:

• manage_notes enables cross-calendar creation and provider selection in the form flow.
• create_note_bcba affects service options: when the selected provider does not have this permission, the CPT options are restricted to 97153.

3. Business Rules & Enforcements

• Rule 1: Required data must be present before save: patient_id, provider_id, location_id, session_date, pos, cpt_code, time_in, time_out, and status.
• Rule 2: Time validation is enforced: time_out must be after time_in.
• Rule 3: If POS 99 is selected, a POS 99 description is required and is limited server-side to 35 characters.
• Rule 4: The appointment location is tied to the selected patient and then validated server-side for location/patient access before creation. Appointment queries are also scoped to the current location context.
• Rule 5: New appointments are initialized with status = pending in the create flow.
• Rule 6: If the selected patient has no available PA/CPT services, the UI warns the user and the form cannot be submitted with a valid CPT until service availability is resolved.
• Rule 7: In shared-calendar mode (manage_notes), users must first select a provider or patient before opening the create form from the calendar grid.
• 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. In month/week/day calendar views, click an empty day cell or hour segment to open the Create Appointment form.
4. In cross-calendar mode, select a provider or patient first, then click a day/time slot to create.

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

Scenario A: Provider creates an appointment in their own calendar

1. Open Medical > Calendar.
2. Keep the default “my appointments” context (or filter by one of your assigned patients).
3. Click an empty slot on the target date/time.
4. Complete required fields: Patient, Time In, Time Out, POS, CPT Code, and POS 99 description when POS 99 is selected.
5. Click Save.
6. Confirm the success modal and return to the calendar.

Scenario B: Manager/Admin creates an appointment for another provider

1. Open Medical > Calendar.
2. Filter by a specific provider or by a specific patient.
3. Click an empty slot on the target date/time.
4. Select Patient and Provider (if applicable), then complete POS, CPT, times, and POS 99 description when POS 99 is selected.
5. Click Save.
6. Confirm success and verify the event appears in the selected calendar context.

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

• Q: What happens if I try to create an appointment without selecting a provider or patient in shared-calendar mode?
  A: The UI shows an informational message and blocks the create flow until a provider or patient is selected.

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

• Q: What happens if I select POS 99 without a description? A: The form treats the POS 99 description as required, and the backend also validates it before creating the appointment.