diff --git a/docs/api-router-procedure-support-pattern.md b/docs/api-router-procedure-support-pattern.md new file mode 100644 index 0000000..8291ff1 --- /dev/null +++ b/docs/api-router-procedure-support-pattern.md @@ -0,0 +1,42 @@ +# API Router Procedure-Support Pattern + +Ziel: Top-Level-Router bleiben dünne tRPC-Kompositionsschichten. Orchestrierung, Audit-Logik und +zusammengehörige Input-Schemas wandern in ein benachbartes `*-procedure-support.ts` Modul. + +## Struktur + +- `router/.ts` + Enthält nur Procedure-Wiring, Rollen-Gates und die Delegation an benannte Support-Funktionen. +- `router/-procedure-support.ts` + Enthält: + - zusammengehörige `zod`-Input-Schemas für Router-Procedures + - DB-Orchestrierung und Guard-Checks + - Audit-Aufrufe + - kleine private Hilfsfunktionen wie `withAuditUser(...)` +- `router/-support.ts` + Bleibt für pure Builder-, Resolver- und Transform-Helfer reserviert. + +## Teststrategie + +- `__tests__/-support.test.ts` + Deckt reine Helper-Funktionen ab. +- `__tests__/-procedure-support.test.ts` + Deckt Orchestrierung, Audit-Snapshots und Guard-Verhalten ab. +- `__tests__/-router.test.ts` + Deckt echte `createCaller`-Pfade ab und hält den Router als dünne Integrationsschicht ehrlich. + +## Guardrails + +- Öffentliche Router-Contracts bleiben stabil. +- Keine Logik zurück in den Top-Level-Router ziehen. +- Vorhandene pure Support-Module weiterverwenden statt duplizieren. +- Slice-Tests gezielt fahren; globales `tsc --noEmit` nur dort nutzen, wo kein fremder Blocker aktiv ist. + +## Referenz-Slices + +- `rate-card` +- `effort-rule` +- `experience-multiplier` +- `management-level` +- `blueprint` +- `client`