Formtest Entwicklerdoku

Appearance

API-Schicht ​

Komponenten sollen Serverzugriffe nicht direkt ausführen. Produktiver App-Code verwendet die gemeinsamen Fetch- und API-Composables.

$ivmFetch ​

app/plugins/00.ivm.ts registriert nuxtApp.$ivmFetch.

Eigenschaften:

  • verwendet runtimeConfig.public.devServer als Basis-URL
  • sendet Requests mit Credentials
  • behandelt 401 über ein Login-Popup
  • wiederholt den fehlgeschlagenen Request nach erfolgreichem Login
  • triggert app:login und aktualisiert Nuxt-Async-Data

Alle appinternen API-Helfer bauen darauf auf.

useIVMFetch(...) ​

app/composables/api/useIVMFetch.ts ist der useFetch-Wrapper für IVM-Requests.

Das Composable setzt nur $fetch: useNuxtApp().$ivmFetch und behält dadurch das normale Nuxt-Async-Data-Verhalten bei.

Typische Nutzung:

ts
await useIVMFetch<ApiResponse<Data>>('/some/path', {
  immediate: true,
  watch: [someRef],
})

Einsatzbereiche im Code sind unter anderem /create, ProtocolSelection.vue und die Historie.

useIVMApi() ​

app/composables/api/useIVMApi.ts ist der imperative API-Helfer für JSON, Blob, Raw, HEAD und DELETE.

Der Helper normalisiert URLs:

  • blob: bleibt ein Blob-Zugriff über fetch
  • absolute URLs auf denselben devServer werden zu IVM-Pfaden normalisiert
  • fremde absolute HTTP(S)-URLs laufen über $fetch
  • relative Pfade laufen über $ivmFetch

Das ist wichtig für PDF-Vorschauen, fertige PDF-Dateien und Bild-/Dateioperationen, weil dort lokale Blob-URLs, Backend-Pfade und absolute URLs zusammen vorkommen.

Fachliche API-Composables ​

Fachliche Mutationen liegen in kleineren Composables.

app/composables/api/useAcceptanceApi.ts:

  • createAcceptance(contractId, type) -> POST /acceptance/
  • archiveAcceptance(acceptanceId) -> POST /acceptance/{id}/archive
  • markPendingUpload(acceptanceId) -> POST /acceptance/{id}/pending-upload
  • unlockAcceptance(acceptanceId) -> POST /acceptance/{id}/unlock

app/composables/api/useSetupApi.ts:

  • globale Setup-Editoren
  • Raumtypen, Raumklassen, Komponenten und Materialien
  • Verantwortlichkeiten und Scope-Einstellungen
  • Dienstleister, globale Vorlagen, Mieterbestätigungen
  • allgemeine Einstellungen, PDF-Einstellungen und Sektionskonfiguration

app/composables/api/useBillingProvidersApi.ts:

  • getFlatAssignments() -> GET /billing-providers/flat-assignments

Binärdaten ​

Für Uploads mit Fortschritt nutzt die App nicht $fetch, sondern XHR-Helfer.

Beispiele:

  • app/utils/upload.ts für Bild-Uploads
  • app/composables/protocol/finalizeUpload.ts für Finalisierungsdokumente

Dadurch können Upload-Fortschritt, Retry-Zähler und Abbruchfehler präzise im UI angezeigt werden.

Regel ​

Neue produktive API-Zugriffe sollten in einem passenden Store oder Composable landen.

Direkte API-Aufrufe aus präsentationalen Komponenten sind zu vermeiden. Wiederverwendbare fachliche Endpunkte gehören in app/composables/api/**, workflownahe Orchestrierung in app/composables/protocol/** oder einen Store.