// AK-P16b · appointment lifecycle (M06 Block D / M129 VOLL): held / no-show / cancel // / reschedule / re-assign. Transitions are validated by the pure state machine; the // local CalendarEvent mirror is kept in sync (archived on cancel, moved on re-assign, // superseded on reschedule). Customer-facing changes (cancel/reschedule/re-assign) // send an auto-mail (best-effort, M06 I.3) and record an Activity (M06 J.4); an in-app // notification goes to the provider via notify() (M011). External calendar push lands // with the AK-P16a write-path (here only the local mirror is updated). import { formatInTimeZone } from "date-fns-tz"; import { logActivity, type ActivityType } from "@hivegrid/activity"; import { notify, type NotificationClient } from "@hivegrid/foundation"; import { db } from "~/utils/db.server"; import { sendEmailMailjet } from "~/modules/emails/services/MailjetEmailService"; import { assertTransition, statusAfter, notifiesCustomer, type LifecycleAction } from "./bookingTransitions"; const MINUTE_MS = 60_000; interface AppointmentForAction { id: string; status: "scheduled" | "held" | "cancelled" | "no_show" | "rescheduled"; providerUserId: string; bookingPageId: string; kontaktId: string | null; startAt: Date; endAt: Date; timezone: string; internalCalendarEventId: string | null; intakeAnswers: unknown; pageTitle: string; durationMinutes: number; tenantName: string; } async function loadAppointmentForAction(tenantId: string, appointmentId: string): Promise { const row = await db.appointment.findFirst({ where: { id: appointmentId, tenantId }, select: { id: true, status: true, providerUserId: true, bookingPageId: true, kontaktId: true, startAt: true, endAt: true, timezone: true, internalCalendarEventId: true, intakeAnswers: true, bookingPage: { select: { title: true, durationMinutes: true } }, }, }); if (!row) { return null; } const tenant = await db.tenant.findUnique({ where: { id: tenantId }, select: { name: true } }); return { id: row.id, status: row.status, providerUserId: row.providerUserId, bookingPageId: row.bookingPageId, kontaktId: row.kontaktId, startAt: row.startAt, endAt: row.endAt, timezone: row.timezone, internalCalendarEventId: row.internalCalendarEventId, intakeAnswers: row.intakeAnswers, pageTitle: row.bookingPage.title, durationMinutes: row.bookingPage.durationMinutes, tenantName: tenant?.name ?? "", }; } function bookerEmail(intakeAnswers: unknown): string | null { if (intakeAnswers && typeof intakeAnswers === "object" && "email" in intakeAnswers) { const email = (intakeAnswers as { email?: unknown }).email; return typeof email === "string" && email.trim() ? email.trim() : null; } return null; } async function recordActivity(tenantId: string, appt: AppointmentForAction, activityType: ActivityType, summaryText: string, actorUserId: string | null): Promise { if (!appt.kontaktId) { return; } await logActivity({ tenantId, actorUserId, actorKind: actorUserId ? "user" : "system", activityType, subjectType: "contact", subjectId: appt.kontaktId, summaryText, metadata: { appointmentId: appt.id }, }).catch(() => undefined); } async function notifyProvider(tenantId: string, providerUserId: string, messageKey: string, appointmentId: string): Promise { await notify( { tenantId, userId: providerUserId, channel: "IN_APP", category: "bookings", messageKey, sourceKey: `${messageKey}:${appointmentId}`, payloadMetadata: { appointmentId } }, db as unknown as NotificationClient ).catch(() => undefined); } async function sendLifecycleMail(appt: AppointmentForAction, subject: string, body: string): Promise { const to = bookerEmail(appt.intakeAnswers); if (!to) { return false; } try { await sendEmailMailjet({ data: { to, subject, body: body.replace(/\r?\n/gu, "
") } }); return true; } catch { return false; } } function whenLabel(appt: AppointmentForAction): string { return formatInTimeZone(appt.startAt, appt.timezone, "dd.MM.yyyy HH:mm"); } /** Mark a past appointment as held (M06 D). */ export async function markAppointmentHeld(tenantId: string, appointmentId: string, actorUserId: string): Promise { await applyStatusOnly(tenantId, appointmentId, "mark_held", actorUserId, "appointment_held", "als stattgefunden markiert"); } /** Mark an appointment as no-show (M06 D). */ export async function markAppointmentNoShow(tenantId: string, appointmentId: string, actorUserId: string): Promise { await applyStatusOnly(tenantId, appointmentId, "mark_no_show", actorUserId, "appointment_no_show", "als nicht erschienen markiert"); } async function applyStatusOnly(tenantId: string, appointmentId: string, action: LifecycleAction, actorUserId: string, activityType: ActivityType, summaryVerb: string): Promise { const appt = await loadAppointmentForAction(tenantId, appointmentId); if (!appt) { return; } assertTransition(appt.status, action); const next = statusAfter(action); if (next) { await db.appointment.update({ where: { id: appt.id }, data: { status: next } }); } await recordActivity(tenantId, appt, activityType, `Termin ${appt.pageTitle} (${whenLabel(appt)}) ${summaryVerb}`, actorUserId); } /** Cancel an appointment with a reason + auto-mail (M06 D / I). */ export async function cancelAppointment(input: { tenantId: string; appointmentId: string; reason: string; byKind: "customer" | "provider" | "system"; actorUserId: string | null }): Promise { const appt = await loadAppointmentForAction(input.tenantId, input.appointmentId); if (!appt) { return; } assertTransition(appt.status, "cancel"); await db.$transaction(async (tx) => { await tx.appointment.update({ where: { id: appt.id }, data: { status: "cancelled", cancelledAt: new Date(), cancelledByKind: input.byKind, cancellationReason: input.reason }, }); if (appt.internalCalendarEventId) { // Free the slot: archive the local mirror so it stops blocking availability. await tx.calendarEvent.update({ where: { id: appt.internalCalendarEventId }, data: { archivedAt: new Date(), isBusyForAvailability: false } }); } }); await sendLifecycleMail(appt, `Termin storniert: ${appt.pageTitle}`, `Dein Termin am ${whenLabel(appt)} wurde storniert.\nGrund: ${input.reason}`); await recordActivity(input.tenantId, appt, "appointment_cancelled", `Termin ${appt.pageTitle} (${whenLabel(appt)}) storniert: ${input.reason}`, input.actorUserId); if (notifiesCustomer("cancel")) { await notifyProvider(input.tenantId, appt.providerUserId, "bookings.status.cancelled", appt.id); } } /** Reschedule to a new start time: supersede the old appointment with a successor (M06 D). */ export async function rescheduleAppointment(input: { tenantId: string; appointmentId: string; newStartAt: Date; actorUserId: string }): Promise<{ newAppointmentId: string }> { const appt = await loadAppointmentForAction(input.tenantId, input.appointmentId); if (!appt) { throw new Error("appointment_not_found"); } assertTransition(appt.status, "reschedule"); const newEndAt = new Date(input.newStartAt.getTime() + appt.durationMinutes * MINUTE_MS); const newAppointmentId = await db.$transaction(async (tx) => { await tx.appointment.update({ where: { id: appt.id }, data: { status: "rescheduled" } }); if (appt.internalCalendarEventId) { await tx.calendarEvent.update({ where: { id: appt.internalCalendarEventId }, data: { archivedAt: new Date(), isBusyForAvailability: false } }); } const successor = await tx.appointment.create({ data: { tenantId: input.tenantId, bookingPageId: appt.bookingPageId, providerUserId: appt.providerUserId, startAt: input.newStartAt, endAt: newEndAt, timezone: appt.timezone, status: "scheduled", kontaktId: appt.kontaktId, intakeAnswers: appt.intakeAnswers as object, rescheduledFromId: appt.id, }, select: { id: true }, }); const calendarEvent = await tx.calendarEvent.create({ data: { tenantId: input.tenantId, userId: appt.providerUserId, source: "hivegrid_internal", title: appt.pageTitle, startsAt: input.newStartAt, endsAt: newEndAt, isBusyForAvailability: true, internalEntityLink: { type: "booking_appointment", id: successor.id } }, select: { id: true }, }); await tx.appointment.update({ where: { id: successor.id }, data: { internalCalendarEventId: calendarEvent.id } }); return successor.id; }); const newWhen = formatInTimeZone(input.newStartAt, appt.timezone, "dd.MM.yyyy HH:mm"); await sendLifecycleMail(appt, `Termin verschoben: ${appt.pageTitle}`, `Dein Termin wurde von ${whenLabel(appt)} auf ${newWhen} verschoben.`); await recordActivity(input.tenantId, appt, "appointment_rescheduled", `Termin ${appt.pageTitle} verschoben von ${whenLabel(appt)} auf ${newWhen}`, input.actorUserId); await notifyProvider(input.tenantId, appt.providerUserId, "bookings.status.rescheduled", newAppointmentId); return { newAppointmentId }; } /** Re-assign the appointment to a different provider (M06 D, bookings.admin). */ export async function reassignAppointment(input: { tenantId: string; appointmentId: string; newProviderUserId: string; actorUserId: string }): Promise { const appt = await loadAppointmentForAction(input.tenantId, input.appointmentId); if (!appt) { return; } assertTransition(appt.status, "reassign"); await db.$transaction(async (tx) => { await tx.appointment.update({ where: { id: appt.id }, data: { providerUserId: input.newProviderUserId } }); if (appt.internalCalendarEventId) { // Move the local mirror to the new provider so availability follows. await tx.calendarEvent.update({ where: { id: appt.internalCalendarEventId }, data: { userId: input.newProviderUserId } }); } }); await sendLifecycleMail(appt, `Termin: neuer Ansprechpartner — ${appt.pageTitle}`, `Dein Termin am ${whenLabel(appt)} wird von einem anderen Mitarbeiter betreut.`); await recordActivity(input.tenantId, appt, "appointment_rescheduled", `Termin ${appt.pageTitle} (${whenLabel(appt)}) neu zugewiesen`, input.actorUserId); await notifyProvider(input.tenantId, input.newProviderUserId, "bookings.status.scheduled", appt.id); }