Files
2026-07-08 16:15:37 +02:00

229 lines
10 KiB
TypeScript

// 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<AppointmentForAction | null> {
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<void> {
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<void> {
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<boolean> {
const to = bookerEmail(appt.intakeAnswers);
if (!to) {
return false;
}
try {
await sendEmailMailjet({ data: { to, subject, body: body.replace(/\r?\n/gu, "<br/>") } });
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<void> {
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<void> {
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<void> {
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<void> {
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<void> {
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);
}