Skip to content

server-ticketing

@mmm/server-ticketing

Installation

Terminal window
pnpm add @mmm/ticketing-contracts @mmm/server-ticketing

Peer Dependencies müssen im Service vorhanden sein: @nestjs/common, @nestjs/core, @prisma/client, @mmm/auth-server (setzt req.user mit permissions), @mmm/auth-server-permissions (PermissionsModule.forRoot mit einem Resolver, liefert PolicyGuard und @RequireAnyPolicy), @mmm/server-db (stellt den Prisma-Client unter PRISMA_CLIENT), class-validator, class-transformer.

Die Modelle aus ../prisma/schema.fragment.prisma müssen im eigenen Prisma-Schema stehen.

Endpunkte

Alle unter /tickets (TICKETING_API_PATH):

MethodePfadSlotZweck
POST/ticketscreateTicket einreichen ({ category, payload, requesterId? }); requesterId zählt nur für Aufrufer mit manage (Mitarbeiter legt ein Ticket für einen Kunden an), sonst ist der Aufrufer der Kunde
GET/ticketsreadListe; Filter status, category, assignee (me, none, Id), requesterId, createdFrom/createdTo, q; sort/dir, page/pageSize
GET/tickets/statsreadAnzahl je Status
GET/tickets/metareadKategorien, zuweisbare Mitarbeiter (assignees) und Kunden (requesters)
POST/tickets/bulk-deletemanage{ ids } (1 bis 500); Tickets anderer Mandanten werden übergangen; Antwort { deleted }
GET/tickets/:idreadDetail mit Payload und Verlauf; closedAt wird aus dem Verlauf abgeleitet
PATCH/tickets/:idmanagestatus, assigneeId (null = Zuweisung entfernen), category, requesterId (null = Kunde entfernen); jedes Feld optional
DELETE/tickets/:idmanageTicket samt Verlauf löschen

Jede Änderung schreibt einen Eintrag in TicketEvent (CREATED, STATUS_CHANGED, ASSIGNED, UNASSIGNED, CATEGORY_CHANGED, REQUESTER_CHANGED); Bulk-Löschen schreibt nichts, die Tickets sind weg.

Schnellstart

import { TicketingModule, TicketActorDirectory, TicketTenantContext, staticTicketCategories } from '@mmm/server-ticketing';
@Module({
imports: [
TicketingModule.forRoot({
// pro Slot: der Aufrufer braucht eine dieser Permissions
policies: {
// create auch für die manage-Keys, damit Mitarbeiter Tickets für Kunden anlegen können
create: ['app.use', 'content.manage', 'user.manage'],
read: ['content.read', 'user.read'],
manage: ['content.manage', 'user.manage'],
},
tenantContext: RequestTenantContext, // extends TicketTenantContext
actorDirectory: PrismaActorDirectory, // extends TicketActorDirectory
categoryCatalog: staticTicketCategories([{ key: 'Kontakt', label: 'Kontakt' }, { key: 'WKOF', label: 'WEG Konten/Eröffnung' }]),
// eventBus: KafkaTicketEventBus, // optional, extends TicketEventBus; Default: in-process
}),
],
})
export class TicketingHostModule {}

Die Ports:

  • TicketTenantContext.requireTenantId(): in welchem Mandanten der Request arbeitet.
  • TicketActorDirectory: listAssignees(tenantId) (wem Tickets zugewiesen werden dürfen), listRequesters(tenantId) (für wen Tickets angelegt werden dürfen; Kunden-Select und -Filter), resolve(tenantId, ids) (Anzeigedaten zu Ids), search(tenantId, text) (Ids zu Name/E-Mail für den Freitextfilter).
  • TicketCategoryCatalog.list(tenantId): Labels zu den Kategorie-Schlüsseln, die die Formulare des Hosts senden. staticTicketCategories(list) für eine feste Liste; das Modul validiert Kategorien nicht gegen den Katalog.
  • TicketEventBus.publish(event): optional, ersetzt den In-Process-Bus (siehe unten).

Events

Nach jeder Änderung veröffentlicht der Service ein TicketDomainEvent (aus @mmm/ticketing-contracts) je geschriebenem Verlaufseintrag: type (CREATED, STATUS_CHANGED, ASSIGNED, UNASSIGNED, CATEGORY_CHANGED, REQUESTER_CHANGED), historyId, tenantId, ticket (Zustand nach der Änderung), payload, actor, from/to, occurredAt. Ein PATCH mit Status und Zuweisung ergibt zwei Events.

Konsumenten sind Methoden beliebiger Singleton-Provider im Host, markiert mit @OnTicketEvent(...types) (ohne Argumente: alle Events). Der Standard-Bus findet sie beim Bootstrap über DiscoveryService; Request-scoped Provider werden nicht gefunden.

import { OnTicketEvent } from '@mmm/server-ticketing';
import { isClosedStatus, isTicketStatus, type TicketDomainEvent } from '@mmm/ticketing-contracts';
@Injectable()
export class TicketMailNotifier {
constructor(private readonly mail: TemplateMailService) {}
@OnTicketEvent('CREATED')
async notifyTeam(event: TicketDomainEvent) { /* event.payload, event.ticket.requester … */ }
@OnTicketEvent('STATUS_CHANGED')
async notifyRequester(event: TicketDomainEvent) {
if (!isTicketStatus(event.to) || !isClosedStatus(event.to)) return;
// event.ticket.requester?.email
}
}

Semantik: Handler laufen nach dem Schreiben, die Antwort wartet auf sie (Promise.allSettled), ein werfender Handler wird geloggt und beeinflusst weder die anderen Handler noch den Request. Asynchrone oder entkoppelte Zustellung ist Sache eines eigenen TicketEventBus (z. B. Broker-Producer), der über forRoot({ eventBus }) eingesetzt wird; die Konsumentenseite kann denselben Decorator wiederverwenden.

Authentifizierung übernimmt der globale Guard des Hosts; die Endpunkte tragen @RequireAnyPolicy(...) mit den Keys aus policies und prüfen sie mit dem PolicyGuard aus @mmm/auth-server-permissions (Resolver aus dem globalen PermissionsModule des Hosts).

Entwicklung

Terminal window
pnpm build # prisma generate + tsc
pnpm test