Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/web/app/utils/integrations/crm/crmDetailRoute.server.ts
T

480 lines
21 KiB
TypeScript

// R-P6 (P6 CRM core, Variante A) — shared loader/action for the contact detail
// (`/contacts/:id`) and the organisation detail (`/contacts/companies/:id`).
// Both render the SAME server-built KontaktDetailVM + ActivityStreamVM and share
// the inline-edit intents (DoD 3); the only per-route difference is the back
// link / breadcrumb root. Server-only (.server) — never imported by a component.
//
// Every write intent is audited (DoD 13, via crmAudit.auditCrmEvent) and, when
// contact-relevant, appends an Activity-Stream entry (DoD 14, logKontaktActivity).
import { redirect } from "react-router";
import type { JsonValue } from "@hivegrid/foundation";
import {
buildActivityStreamVM,
buildKontaktDetailVM,
datentypLabelKey,
type ActivityStreamVM,
type ClickToCallVM,
type KontaktDetailVM,
} from "@hivegrid/view-models";
import { getTranslations } from "~/locale/i18next.server";
import { loadTelephonyContext } from "~/modules/telephony/routes/telephonyAccess.server";
import { loadTelephonyClickToCallVM, startTelephonyEntityCall, TelephonyServiceError } from "~/modules/telephony/services/TelephonyService.server";
import { withTenantRLS } from "~/utils/db/.server/tenantRls.server";
import { validateCSRFToken } from "~/utils/session.server";
import { badRequestResponse, crmActionErrorResponse, loadCrmContext, notFoundResponse, requireCrmPermission, type CrmRouteContext } from "./crmAccess.server";
import {
addKontaktEmail,
addKontaktRelation,
addKontaktTelefon,
archiveKontakt,
getKontaktDetail,
getVisibleKontaktOrThrow,
hardDeleteKontakt,
listAssignableUsers,
reactivateKontakt,
reassignKontakt,
removeKontaktEmail,
removeKontaktRelation,
removeKontaktTelefon,
resolveUserLabels,
setPrimaryEmail,
setPrimaryTelefon,
updateKontakt,
type KontaktArt,
type KontaktRow,
type KontaktStatus,
type OrgMerkmal,
} from "./crmService.server";
import { getCustomFieldValues, listCustomFieldDefinitions, setCustomFieldValue } from "./customFieldService.server";
import { assignTag, listTags, listTagsForEntity, unassignTag } from "./tagService.server";
import { auditCrmEvent, logKontaktActivity } from "./crmAudit.server";
import { companiesPath, contactDetailPath, contactsPath, companyDetailPath, tagsAdminPath } from "./crmRoutePaths";
import { maskEmailActivitiesForViewer } from "~/modules/emailInbox/services/emailActivityMasking.server";
import {
canUsePortalInvitationEntrypoint,
invitePortalContactFromEntrypoint,
portalInvitationActionErrorResponse,
} from "~/services/customer-portal/portal-invitation-entrypoint.server";
const KONTAKT_CUSTOM_FIELD_ENTITY = "kontakt";
const KONTAKT_TAG_ENTITY_TYPE = "kontakt";
const ACTIVITY_LIMIT = 50;
export type KontaktDetailVariant = "contacts" | "companies";
export type CustomFieldDefOption = { id: string; key: string; label: string; datentyp: string; datentypLabelKey: string };
export type KontaktDetailLoaderData = {
title: string;
variant: KontaktDetailVariant;
backHref: string;
listLabelKey: string;
detailVM: KontaktDetailVM;
activityVM: ActivityStreamVM;
allTags: { id: string; name: string; farbe: string }[];
/** Set when the viewer may manage tags (crm.admin) — next action for the empty state. */
tagsAdminHref: string | null;
customFieldDefs: CustomFieldDefOption[];
ownerOptions: { id: string; label: string }[];
clickToCallVM: ClickToCallVM;
};
type ActivityDbRow = {
id: string;
createdAt: Date;
actorUserId: string | null;
actorKind: string;
activityType: string;
summaryText: string;
metadata?: unknown;
};
async function loadKontaktActivities(tenantId: string, subjectType: "contact" | "company", subjectId: string): Promise<ActivityDbRow[]> {
// No read helper is exported from @hivegrid/activity yet — load the per-entity
// timeline tenant-scoped (RLS GUC set by withTenantRLS), newest first.
// `metadata` is selected ONLY for the email-visibility masking (VA-P23) and
// never reaches the VM.
const rows = await withTenantRLS(tenantId, (tx) =>
tx.activity.findMany({
where: { tenantId, subjectType, subjectId },
orderBy: { createdAt: "desc" },
take: ACTIVITY_LIMIT + 1,
select: { id: true, createdAt: true, actorUserId: true, actorKind: true, activityType: true, summaryText: true, metadata: true },
})
);
return rows as ActivityDbRow[];
}
export async function loadKontaktDetailData(args: {
request: Request;
params: Record<string, string | undefined>;
variant: KontaktDetailVariant;
}): Promise<KontaktDetailLoaderData> {
const { t } = await getTranslations(args.request);
const ctx = await loadCrmContext({ request: args.request, params: args.params });
const tenantSlug = args.params.tenant ?? "";
const kontaktId = args.params.id ?? "";
if (!ctx.hasModule) {
throw notFoundResponse();
}
try {
requireCrmPermission(ctx, "crm.read_own");
} catch {
throw notFoundResponse();
}
let detail;
try {
detail = await getKontaktDetail(ctx.tenantId, kontaktId, ctx);
} catch {
throw notFoundResponse();
}
const subjectType = detail.kontakt.kontaktTyp === "organisation" ? "company" : "contact";
const portalInvitationAffordance = args.variant === "contacts" ? canUsePortalInvitationEntrypoint(ctx) : Promise.resolve(false);
const [customFields, tags, definitions, allTags, ownerOptions, activityRows, canInviteToPortal] = await Promise.all([
getCustomFieldValues({ tenantId: ctx.tenantId, entityType: KONTAKT_CUSTOM_FIELD_ENTITY, entityId: kontaktId }),
listTagsForEntity({ tenantId: ctx.tenantId, entityType: KONTAKT_TAG_ENTITY_TYPE, entityId: kontaktId }),
listCustomFieldDefinitions({ tenantId: ctx.tenantId, entityType: KONTAKT_CUSTOM_FIELD_ENTITY }),
listTags(ctx.tenantId),
listAssignableUsers(ctx.tenantId),
loadKontaktActivities(ctx.tenantId, subjectType, kontaktId),
portalInvitationAffordance,
]);
const actorIds = activityRows.map((row) => row.actorUserId).filter((id): id is string => Boolean(id));
const userLabels = await resolveUserLabels([detail.kontakt.zustaendigerUserId, ...actorIds].filter((id): id is string => Boolean(id)));
const detailVM = buildKontaktDetailVM({
detail: {
kontakt: detail.kontakt,
emails: detail.emails.map((e) => ({ id: e.id, email: e.email, primaer: e.primaer })),
telefone: detail.telefone.map((p) => ({ id: p.id, telefon: p.telefon, primaer: p.primaer })),
relationen: detail.relationen.map((r) => ({ id: r.id, vonKontaktId: r.vonKontaktId, zuKontaktId: r.zuKontaktId, rolle: r.rolle, kontext: r.kontext })),
adresse: detail.adresse
? {
strasse: detail.adresse.strasse,
hausnummer: detail.adresse.hausnummer,
plz: detail.adresse.plz,
ort: detail.adresse.ort,
land: detail.adresse.land,
}
: null,
},
customFields: customFields.map((cf) => ({
definition: {
id: cf.definition.id,
key: cf.definition.key,
label: cf.definition.label,
datentyp: cf.definition.datentyp,
optionen: cf.definition.optionen,
},
wert: cf.wert,
})),
tags: tags.map((tag) => ({ id: tag.id, name: tag.name, farbe: tag.farbe })),
userLabels,
perms: {
canWrite: ctx.permissions.includes("crm.write"),
canDelete: ctx.permissions.includes("crm.delete"),
canInviteToPortal,
},
tenantSlug,
});
const telephonyCtx = await loadTelephonyContext({ request: args.request, params: args.params, requireModule: false });
const clickToCallVM = await loadTelephonyClickToCallVM(
telephonyCtx,
detail.telefone.map((phone) => ({
id: phone.id,
label: detailVM.data?.displayName ?? phone.telefon,
e164: phone.telefon,
primary: phone.primaer,
}))
);
// VA-P23 (M09 Block H): email activities are permission-masked — without
// email.read_all only the viewer's OWN mailbox activities show details.
const maskedActivityRows = await maskEmailActivitiesForViewer({
tenantId: ctx.tenantId,
userId: ctx.userId,
permissions: ctx.permissions,
rows: activityRows,
maskedText: t("emailInbox.activity.masked"),
});
const activityVM = buildActivityStreamVM({
rows: maskedActivityRows.slice(0, ACTIVITY_LIMIT).map((row) => ({
id: row.id,
createdAt: row.createdAt,
actorUserId: row.actorUserId,
actorKind: row.actorKind as never,
activityType: row.activityType as never,
summaryText: row.summaryText,
})),
userLabels,
hasMore: activityRows.length > ACTIVITY_LIMIT,
});
const backHref = args.variant === "companies" ? companiesPath(tenantSlug) : contactsPath(tenantSlug);
return {
title: `${detailVM.data?.displayName ?? t("crm.detail.title")} | ${process.env.APP_NAME}`,
variant: args.variant,
backHref,
listLabelKey: args.variant === "companies" ? "crm.companies.title" : "crm.contacts.title",
detailVM,
activityVM,
allTags: allTags.map((tag) => ({ id: tag.id, name: tag.name, farbe: tag.farbe })),
tagsAdminHref: ctx.permissions.includes("crm.admin") ? tagsAdminPath(tenantSlug) : null,
customFieldDefs: definitions.map((def) => ({
id: def.id,
key: def.key,
label: def.label,
datentyp: def.datentyp,
datentypLabelKey: datentypLabelKey(def.datentyp),
})),
ownerOptions,
clickToCallVM,
};
}
function field(form: FormData, name: string): string {
return form.get(name)?.toString().trim() ?? "";
}
function optionalField(form: FormData, name: string): string | null {
const value = form.get(name)?.toString().trim();
return value ? value : null;
}
export async function handleKontaktDetailAction(args: {
request: Request;
params: Record<string, string | undefined>;
variant: KontaktDetailVariant;
}): Promise<Response> {
const ctx: CrmRouteContext = await loadCrmContext({ request: args.request, params: args.params, requireModule: true });
const tenantSlug = args.params.tenant ?? "";
const kontaktId = args.params.id ?? "";
const form = await args.request.formData();
const intent = form.get("intent")?.toString();
const detailHref = args.variant === "companies" ? companyDetailPath(tenantSlug, kontaktId) : contactDetailPath(tenantSlug, kontaktId);
const listHref = args.variant === "companies" ? companiesPath(tenantSlug) : contactsPath(tenantSlug);
try {
if (intent === "invitePortalContact") {
if (args.variant !== "contacts") throw notFoundResponse();
await invitePortalContactFromEntrypoint({
request: args.request,
formData: form,
context: ctx,
contactId: kontaktId,
assertTargetVisible: async () => {
await getVisibleKontaktOrThrow(ctx.tenantId, kontaktId, ctx);
},
});
return Response.json({ ok: true, messageKey: "customerPortal.invitation.sent" });
}
// Keep every detail action behind the canonical CRM object-visibility scope.
const kontakt: KontaktRow = await getVisibleKontaktOrThrow(ctx.tenantId, kontaktId, ctx);
// Type is needed by almost every remaining branch (activity subject).
const typ = kontakt.kontaktTyp;
if (intent === "startTelephonyCall") {
await validateCSRFToken(args.request, { formData: form });
const telephonyCtx = await loadTelephonyContext({ request: args.request, params: args.params, requireModule: true });
await startTelephonyEntityCall(telephonyCtx, {
entityType: "contact",
entityId: kontaktId,
numberId: field(form, "numberId"),
destination: field(form, "destination"),
});
return Response.json({ ok: true, messageKey: "crm.toast.callStarted" });
}
if (intent === "delete") {
requireCrmPermission(ctx, "crm.delete");
await hardDeleteKontakt({ tenantId: ctx.tenantId, kontaktId });
await auditCrmEvent({ ctx, action: "kontakt.deleted", targetType: "kontakt", targetId: kontaktId });
return redirect(`${listHref}?toast=${encodeURIComponent("crm.toast.contactDeleted")}`);
}
requireCrmPermission(ctx, "crm.write");
switch (intent) {
case "updateBasics": {
await updateKontakt({
tenantId: ctx.tenantId,
kontaktId,
kontaktStatus: (optionalField(form, "kontaktStatus") as KontaktStatus | null) ?? undefined,
vorname: form.has("vorname") ? optionalField(form, "vorname") : undefined,
nachname: form.has("nachname") ? optionalField(form, "nachname") : undefined,
orgName: form.has("orgName") ? optionalField(form, "orgName") : undefined,
orgMerkmal: form.has("orgMerkmal") ? (optionalField(form, "orgMerkmal") as OrgMerkmal | null) : undefined,
});
await auditCrmEvent({ ctx, action: "kontakt.updated", targetType: "kontakt", targetId: kontaktId });
await logKontaktActivity({ ctx, kontaktId, kontaktTyp: typ, activityType: "contact_updated", summaryText: "crm.activitySummary.basicsUpdated" });
// The detail screen's single "Speichern" also carries the owner change,
// but only sends `zustaendigerUserId` when it actually differs — so this
// reassign runs at most once and never logs a spurious assignee change.
if (form.has("zustaendigerUserId")) {
const owner = optionalField(form, "zustaendigerUserId");
if (owner) {
await reassignKontakt({ tenantId: ctx.tenantId, kontaktId, zustaendigerUserId: owner });
await auditCrmEvent({ ctx, action: "kontakt.reassigned", targetType: "kontakt", targetId: kontaktId, metadata: { zustaendigerUserId: owner } });
await logKontaktActivity({ ctx, kontaktId, kontaktTyp: typ, activityType: "assignee_changed", summaryText: "crm.activitySummary.assigneeChanged" });
}
}
break;
}
case "addEmail": {
await addKontaktEmail({ tenantId: ctx.tenantId, kontaktId, ctx, email: field(form, "email"), primaer: form.get("primaer") === "1" });
await auditCrmEvent({ ctx, action: "kontakt.email_added", targetType: "kontakt", targetId: kontaktId });
await logKontaktActivity({ ctx, kontaktId, kontaktTyp: typ, activityType: "contact_updated", summaryText: "crm.activitySummary.emailAdded" });
break;
}
case "setPrimaryEmail": {
await setPrimaryEmail({ tenantId: ctx.tenantId, kontaktId, ctx, emailId: field(form, "emailId") });
await auditCrmEvent({ ctx, action: "kontakt.email_primary_set", targetType: "kontakt", targetId: kontaktId });
break;
}
case "removeEmail": {
await removeKontaktEmail({ tenantId: ctx.tenantId, kontaktId, ctx, emailId: field(form, "emailId") });
await auditCrmEvent({ ctx, action: "kontakt.email_removed", targetType: "kontakt", targetId: kontaktId });
break;
}
case "addTelefon": {
await addKontaktTelefon({ tenantId: ctx.tenantId, kontaktId, ctx, telefon: field(form, "telefon"), primaer: form.get("primaer") === "1" });
await auditCrmEvent({ ctx, action: "kontakt.telefon_added", targetType: "kontakt", targetId: kontaktId });
await logKontaktActivity({ ctx, kontaktId, kontaktTyp: typ, activityType: "contact_updated", summaryText: "crm.activitySummary.phoneAdded" });
break;
}
case "setPrimaryTelefon": {
await setPrimaryTelefon({ tenantId: ctx.tenantId, kontaktId, ctx, telefonId: field(form, "telefonId") });
await auditCrmEvent({ ctx, action: "kontakt.telefon_primary_set", targetType: "kontakt", targetId: kontaktId });
break;
}
case "removeTelefon": {
await removeKontaktTelefon({ tenantId: ctx.tenantId, kontaktId, ctx, telefonId: field(form, "telefonId") });
await auditCrmEvent({ ctx, action: "kontakt.telefon_removed", targetType: "kontakt", targetId: kontaktId });
break;
}
case "addRelation": {
await addKontaktRelation({
tenantId: ctx.tenantId,
kontaktId,
ctx,
zuKontaktId: field(form, "zuKontaktId"),
rolle: (field(form, "rolle") || "hauptkontakt") as KontaktArt,
kontext: optionalField(form, "kontext"),
});
await auditCrmEvent({ ctx, action: "kontakt.relation_added", targetType: "kontakt", targetId: kontaktId });
await logKontaktActivity({ ctx, kontaktId, kontaktTyp: typ, activityType: "contact_updated", summaryText: "crm.activitySummary.relationAdded" });
break;
}
case "removeRelation": {
await removeKontaktRelation({ tenantId: ctx.tenantId, kontaktId, ctx, relationId: field(form, "relationId") });
await auditCrmEvent({ ctx, action: "kontakt.relation_removed", targetType: "kontakt", targetId: kontaktId });
break;
}
case "reassign": {
const owner = field(form, "zustaendigerUserId");
if (!owner) {
throw badRequestResponse();
}
await reassignKontakt({ tenantId: ctx.tenantId, kontaktId, zustaendigerUserId: owner });
await auditCrmEvent({ ctx, action: "kontakt.reassigned", targetType: "kontakt", targetId: kontaktId, metadata: { zustaendigerUserId: owner } });
await logKontaktActivity({ ctx, kontaktId, kontaktTyp: typ, activityType: "assignee_changed", summaryText: "crm.activitySummary.assigneeChanged" });
break;
}
case "addTag": {
const tagId = field(form, "tagId");
await assignTag({ tenantId: ctx.tenantId, tagId, entityType: KONTAKT_TAG_ENTITY_TYPE, entityId: kontaktId });
await auditCrmEvent({ ctx, action: "tag_assignment.assigned", targetType: "tag_assignment", targetId: kontaktId, metadata: { tagId } });
await logKontaktActivity({ ctx, kontaktId, kontaktTyp: typ, activityType: "tag_added", summaryText: "crm.activitySummary.tagAssigned" });
break;
}
case "removeTag": {
const tagId = field(form, "tagId");
await unassignTag({ tenantId: ctx.tenantId, tagId, entityType: KONTAKT_TAG_ENTITY_TYPE, entityId: kontaktId });
await auditCrmEvent({ ctx, action: "tag_assignment.unassigned", targetType: "tag_assignment", targetId: kontaktId, metadata: { tagId } });
await logKontaktActivity({ ctx, kontaktId, kontaktTyp: typ, activityType: "tag_removed", summaryText: "crm.activitySummary.tagRemoved" });
break;
}
case "setCustomField": {
const wert: JsonValue = field(form, "wert");
await setCustomFieldValue({
tenantId: ctx.tenantId,
definitionId: field(form, "definitionId"),
entityType: KONTAKT_CUSTOM_FIELD_ENTITY,
entityId: kontaktId,
wert,
});
await auditCrmEvent({
ctx,
action: "custom_field_value.set",
targetType: "custom_field_value",
targetId: kontaktId,
metadata: { definitionId: field(form, "definitionId") },
});
break;
}
case "addNote": {
const note = field(form, "note");
if (!note) {
throw badRequestResponse();
}
await logKontaktActivity({ ctx, kontaktId, kontaktTyp: typ, activityType: "note_added", summaryText: note });
await auditCrmEvent({ ctx, action: "kontakt.updated", targetType: "kontakt", targetId: kontaktId, metadata: { note: true } });
break;
}
case "archive": {
await archiveKontakt({ tenantId: ctx.tenantId, kontaktId });
await auditCrmEvent({ ctx, action: "kontakt.archived", targetType: "kontakt", targetId: kontaktId });
await logKontaktActivity({ ctx, kontaktId, kontaktTyp: typ, activityType: "contact_archived", summaryText: "crm.activitySummary.contactArchived" });
break;
}
case "reactivate": {
await reactivateKontakt({ tenantId: ctx.tenantId, kontaktId });
await auditCrmEvent({ ctx, action: "kontakt.reactivated", targetType: "kontakt", targetId: kontaktId });
await logKontaktActivity({ ctx, kontaktId, kontaktTyp: typ, activityType: "contact_updated", summaryText: "crm.activitySummary.contactReactivated" });
break;
}
default:
throw badRequestResponse();
}
const messageKeyByIntent: Record<string, string> = {
updateBasics: "crm.toast.contactSaved",
addEmail: "crm.toast.emailAdded",
setPrimaryEmail: "crm.toast.primaryEmailSet",
removeEmail: "crm.toast.emailRemoved",
addTelefon: "crm.toast.phoneAdded",
setPrimaryTelefon: "crm.toast.primaryPhoneSet",
removeTelefon: "crm.toast.phoneRemoved",
addRelation: "crm.toast.relationAdded",
removeRelation: "crm.toast.relationRemoved",
reassign: "crm.toast.contactReassigned",
addTag: "crm.toast.tagAssigned",
removeTag: "crm.toast.tagRemoved",
setCustomField: "crm.toast.customFieldSaved",
addNote: "crm.toast.noteAdded",
archive: "crm.toast.contactArchived",
reactivate: "crm.toast.contactReactivated",
};
return redirect(`${detailHref}?toast=${encodeURIComponent(messageKeyByIntent[intent ?? ""] ?? "crm.toast.contactSaved")}`);
} catch (error) {
if (error instanceof Response) {
throw error;
}
if (error instanceof TelephonyServiceError) {
return Response.json({ error: error.messageKey }, { status: 400 });
}
const portalInvitationError = portalInvitationActionErrorResponse(error);
if (portalInvitationError) return portalInvitationError;
return crmActionErrorResponse(error);
}
}