server-ticketing
@mmm/server-ticketing
Installation
pnpm add @mmm/ticketing-contracts @mmm/server-ticketingPeer 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):
| Methode | Pfad | Slot | Zweck |
|---|---|---|---|
POST | /tickets | create | Ticket 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 | /tickets | read | Liste; Filter status, category, assignee (me, none, Id), requesterId, createdFrom/createdTo, q; sort/dir, page/pageSize |
GET | /tickets/stats | read | Anzahl je Status |
GET | /tickets/meta | read | Kategorien, zuweisbare Mitarbeiter (assignees) und Kunden (requesters) |
POST | /tickets/bulk-delete | manage | { ids } (1 bis 500); Tickets anderer Mandanten werden übergangen; Antwort { deleted } |
GET | /tickets/:id | read | Detail mit Payload und Verlauf; closedAt wird aus dem Verlauf abgeleitet |
PATCH | /tickets/:id | manage | status, assigneeId (null = Zuweisung entfernen), category, requesterId (null = Kunde entfernen); jedes Feld optional |
DELETE | /tickets/:id | manage | Ticket 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
pnpm build # prisma generate + tscpnpm test