Skip to main content

Scheduling Service — User Stories

Service: scheduling-service Story prefix: SCHED-US Last updated: 2026-04-17

Stories​

SCHED-US-001 — Appointment booking, rescheduling, and conflict prevention​

FieldValue
Issue typeStory
SummaryBook, reschedule, and cancel appointments with conflict prevention
Epic linkSCHED-EPIC-01
StatusIn Progress
PriorityMust
Story points8
Labelsservice:scheduling, type:backend, type:api, slice:S0
Componentsappointments, slots
FR referencesFR-SCHED-003, FR-SCHED-004, FR-SCHED-007
Legacy FR refsFR-SCHED-003, FR-SCHED-004, FR-SCHED-007
DependenciesREG-US-001

User story: As a scheduler, when managing appointments, I want booking, rescheduling, and cancellation enforced with conflict rules so that schedule integrity is preserved.

Acceptance criteria (Gherkin):

  • Given a free slot, when POST /v1/appointments is called, then appointment is created with status: booked and slot becomes busy.
  • Given a busy slot, when booking is attempted, then 409 SLOT_NOT_AVAILABLE is returned.
  • Given an overlapping resource booking and no override permission, when booking is attempted, then 409 DOUBLE_BOOKING_DETECTED.
  • Given a booked appointment, when cancelled with reason + version, then status transitions to cancelled, slot released to free, and appointment.cancelled event emitted.

Technical notes:

  • POST /api/v1/appointments, PUT /api/v1/appointments/:id/cancel, PUT /api/v1/appointments/:id/reschedule
  • Atomic slot status via DB transaction + unique index

Definition of Done:

  • Unit + integration tests; coverage ≥ 80%.
  • Tenant isolation integration test passing.
  • Contract test for appointment.created schema.

SCHED-US-002 — Schedule and slot governance with exceptions​

FieldValue
Issue typeStory
SummaryConfigure resource schedules with slots and blocked-time exceptions
Epic linkSCHED-EPIC-02
StatusIn Progress
PriorityMust
Story points5
Labelsservice:scheduling, type:backend, slice:S0
Componentsschedules, slots, exceptions
FR referencesFR-SCHED-001, FR-SCHED-002, FR-SCHED-009, FR-SCHED-010
Legacy FR refsFR-SCHED-001..010
DependenciesSCHED-US-001

User story: As an operations scheduler, when configuring resource availability, I want facility-aware schedules, slots, and exceptions so that invalid booking windows are prevented.

Acceptance criteria (Gherkin):

  • Given a configured schedule exception for a public holiday, when availability is queried for that date, then no free slots are returned.
  • Given a schedule with timezone: Asia/Kabul, when slots are queried, then UTC timestamps render correctly at +04:30.
  • Given providerId and locationId filters on GET /v1/slots/availability, then only matching free slots are returned.

Technical notes:

  • POST /api/v1/schedules, POST /api/v1/schedules/:id/exceptions, GET /api/v1/slots/availability
  • IANA timezone validation at schedule creation

Definition of Done:

  • Unit tests for exception blocking logic; integration test for availability endpoint.
  • Timezone rendering test with Asia/Kabul (+04:30).

SCHED-US-003 — Waitlist auto-fill and reminder dispatch​

FieldValue
Issue typeStory
SummaryWaitlist auto-fill from cancellations and reminder dispatch
Epic linkSCHED-EPIC-03
StatusIn Progress
PriorityMust
Story points5
Labelsservice:scheduling, type:backend, slice:S1
Componentswaitlist, reminders
FR referencesFR-SCHED-005, FR-SCHED-006
Legacy FR refsFR-SCHED-005, FR-SCHED-006
DependenciesSCHED-US-001

User story: As a care access coordinator, when cancellations occur, I want waitlist candidates evaluated by priority and patients reminded so that access and communication are reliable.

Acceptance criteria (Gherkin):

  • Given a waiting patient in the waitlist, when an appointment is cancelled freeing a matching slot, then SCHEDULING.waitlist.slot-available is emitted with waitlistEntryId.
  • Given an appointment 24 hours away, when reminder cron runs, then appointment.reminder.sent event is emitted with correct channel.
  • Given patient communication consent granted: false for SMS, when reminder dispatch runs, then SMS channel is skipped.

Technical notes:

  • POST /api/v1/waitlist, waitlist auto-fill on CancelAppointmentUseCase
  • Reminder dispatch async (DispatchReminderUseCase); configurable lead time

Definition of Done:

  • Integration test for waitlist auto-fill on cancellation.
  • Unit test for reminder channel routing with consent check.

SCHED-US-004 — Localized and RTL-safe appointment reminders​

FieldValue
Issue typeStory
SummaryGenerate localized and RTL-safe reminders in patient preferred language
Epic linkSCHED-EPIC-03
StatusIn Progress
PriorityMust
Story points3
Labelsservice:scheduling, type:backend, slice:S1
Componentsreminders, localization
FR referencesFR-SCHED-008, FR-SCHED-011
Legacy FR refsFR-SCHED-008, FR-SCHED-011
DependenciesSCHED-US-003

User story: As a patient communications operator, when sending appointment reminders, I want localized and RTL-safe templates so that reminders are understandable in Dari, Pashto, and Arabic.

Acceptance criteria (Gherkin):

  • Given patient preferredLang: fa-af, when reminder is dispatched, then locale fa-af is included in appointment.reminder.sent data.
  • Given no patient language preference, when reminder dispatches, then facility default locale is used.
  • Given RTL locale, when reminder payload includes date/time, then formatting follows locale rules (right-to-left date format).

Technical notes:

  • appointment.reminder.sent payload includes locale field
  • Template rendering is downstream concern (communication-service)

Definition of Done:

  • Unit tests for locale fallback chain.
  • Contract test for appointment.reminder.sent schema with locale.

SCHED-US-005 — FHIR and HL7 SIU interoperability​

FieldValue
Issue typeStory
SummaryFHIR Appointment/Slot read+search and HL7 SIU inbound/outbound
Epic linkSCHED-EPIC-04
StatusTo Do
PriorityShould
Story points8
Labelsservice:scheduling, type:backend, type:api, slice:S2
ComponentsFHIR, HL7-SIU
FR referencesFR-SCHED-012, FR-SCHED-014, FR-SCHED-015
Legacy FR refs—
DependenciesSCHED-US-001, INTEROP-US-001

User story: As an interoperability engineer, when exchanging scheduling data with partner systems, I want complete FHIR and HL7 paths so that partner systems stay synchronized.

Acceptance criteria (Gherkin):

  • Given a booked appointment, when GET /fhir/R4/Appointment/:id is called, then FHIR R4 Appointment resource is returned with correct status.
  • Given an inbound SIU S12 message, when posted to /v1/integration/hl7/siu, then appointment is created in booked state.
  • Given an appointment lifecycle event, when outbound SIU is generated by interop-service, then message includes correct ORC and AIL segments.

Technical notes:

  • FHIR base path /fhir/R4
  • HL7 SIU parsed by interop-service adapter; scheduling-service receives canonical command

Definition of Done:

  • FHIR Appointment read test.
  • HL7 SIU inbound integration test.
  • Contract test for FHIR Appointment schema.

SCHED-US-006 — Scheduling reliability and quality controls​

FieldValue
Issue typeStory
SummaryMeet latency, resilience, and coverage targets for production
Epic linkSCHED-EPIC-05
StatusIn Progress
PriorityMust
Story points5
Labelsservice:scheduling, type:backend, slice:S0
Componentstesting, observability
FR referencesNFR-SCHED-001, NFR-SCHED-002
Legacy FR refsNFR-SCHED-001, NFR-SCHED-002
DependenciesSCHED-US-001

User story: As a reliability owner, when validating release readiness, I want measurable latency, resilience, and coverage evidence so that scheduling risks are controlled.

Acceptance criteria (Gherkin):

  • Given availability benchmark, when measured, then p95 search latency < 1 000 ms.
  • Given reminder pipeline transient failure, when retry occurs, then recovery behavior is logged and observable.
  • Given CI coverage run, when executed on main, then ≥ 80% line coverage.

Technical notes:

  • Outbox integration test required
  • SLO alerts configured in Grafana

Definition of Done:

  • All mandatory integration tests passing.
  • SLO dashboards and alerts configured.
  • Coverage ≥ 80%.

SCHED-ENH-US-001 — Recurring series and group session capacity​

FieldValue
Issue typeStory
SummarySupport recurring appointment series and group capacity limits
Epic linkSCHED-ENH-EPIC-01
StatusTo Do
PriorityCould
Story points13
Labelsservice:scheduling, type:backend, slice:S3
Componentsrecurring, group
FR referencesFR-SCHED-ENH-001, FR-SCHED-ENH-002
Legacy FR refsFR-SCHED-ENH-001..002
DependenciesSCHED-US-001, SCHED-US-002

User story: As an operations lead, when managing chronic-disease follow-up programmes, I want recurring appointment series and group capacity limits so that clinic planning is automated.

Acceptance criteria (Gherkin):

  • Given a recurring series pattern, when created, then individual appointment instances are generated per schedule.
  • Given a group session at capacity, when a new booking is attempted, then 409 GROUP_CAPACITY_EXCEEDED is returned.

Definition of Done:

  • Unit tests for series generation and exception handling.
  • Group capacity guard integration test.