Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/web/app/utils/integrations/crm/crmAudit.server.ts
T
2026-07-08 16:15:37 +02:00

108 lines
3.6 KiB
TypeScript

// R-P6 (P6 CRM core, Variante A) — audit + activity wiring for the CRM module.
//
// Audit (DoD 13): every write action records a tamper-evident AuditEvent (M001)
// via createAuditEvent with the shared db client.
//
// Activity (DoD 14): user-facing timeline entries are logged against the contact.
// A private person maps to the Activity subject "contact", an organisation to
// "company". Tag / assignment / note activities reuse the EXISTING activity types
// (tag_added, tag_removed, assignee_changed, note_added). All best-effort.
import type { JsonValue } from "@hivegrid/foundation";
import { createAuditEvent } from "@hivegrid/db/audit-events.server";
import { logActivity, type ActivityRelatedRef, type ActivitySubjectType, type ActivityType } from "@hivegrid/activity";
import type { CrmRouteContext } from "./crmAccess.server";
import type { KontaktTyp } from "./crmService.server";
export type CrmAuditTargetType = "kontakt" | "custom_field" | "custom_field_value" | "tag" | "tag_assignment";
export type CrmAuditAction =
| "kontakt.created"
| "kontakt.updated"
| "kontakt.archived"
| "kontakt.reactivated"
| "kontakt.deleted"
| "kontakt.reassigned"
| "kontakt.email_added"
| "kontakt.email_primary_set"
| "kontakt.email_removed"
| "kontakt.telefon_added"
| "kontakt.telefon_primary_set"
| "kontakt.telefon_removed"
| "kontakt.relation_added"
| "kontakt.relation_removed"
| "kontakt.bulk_archived"
| "kontakt.bulk_reassigned"
| "custom_field.created"
| "custom_field.updated"
| "custom_field.archived"
| "custom_field_value.set"
| "custom_field.demo_seeded"
| "custom_field.demo_cleared"
| "tag.created"
| "tag.updated"
| "tag.deleted"
| "tag_assignment.assigned"
| "tag_assignment.unassigned";
export async function auditCrmEvent(input: {
ctx: Pick<CrmRouteContext, "tenantId" | "userId">;
action: CrmAuditAction;
targetType: CrmAuditTargetType;
targetId: string;
metadata?: Record<string, JsonValue>;
}): Promise<void> {
try {
await createAuditEvent({
tenantId: input.ctx.tenantId,
actorId: input.ctx.userId,
actorType: "user",
action: input.action,
targetType: input.targetType,
targetId: input.targetId,
metadata: input.metadata ?? null,
});
} catch {
// Audit must never break the user action; the failure is logged upstream.
}
}
/** Map a Kontakt type to its Activity subject (DoD 14). */
function kontaktSubjectType(kontaktTyp: KontaktTyp): ActivitySubjectType {
return kontaktTyp === "organisation" ? "company" : "contact";
}
export type KontaktActivityType = Extract<
ActivityType,
"contact_created" | "contact_updated" | "contact_archived" | "assignee_changed" | "tag_added" | "tag_removed" | "note_added"
>;
/**
* Log a contact activity. The entry hangs off the contact's own timeline; its
* subject type is derived from `kontaktTyp` (private person → contact, organisation
* → company). Best-effort.
*/
export async function logKontaktActivity(input: {
ctx: Pick<CrmRouteContext, "tenantId" | "userId">;
kontaktId: string;
kontaktTyp: KontaktTyp;
activityType: KontaktActivityType;
summaryText: string;
relatedEntityRefs?: ActivityRelatedRef[];
}): Promise<void> {
try {
await logActivity({
tenantId: input.ctx.tenantId,
actorUserId: input.ctx.userId,
actorKind: "user",
activityType: input.activityType,
subjectType: kontaktSubjectType(input.kontaktTyp),
subjectId: input.kontaktId,
summaryText: input.summaryText,
relatedEntityRefs: input.relatedEntityRefs,
});
} catch {
// Activity logging is best-effort; never break the user action.
}
}