0 Fork 0

Files

T

Nick SzaunigandClaude Opus 5.5 a654a1a158 docs: T7 Freihand implementation plan (6 deliveries, 25 tasks)

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

2026-10-16 09:12:04 +02:00

83 KiB

Raw Blame History

T7 „Freihand“ (Spracherfassung) Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Der Imker spricht die Durchsicht statt zu tippen: Stufe 1 diktiert per Browser-Spracherkennung in die Freitextfelder, Stufe 2 nimmt eine Sprachnotiz auch offline auf, schreibt sie im Cluster mit faster-whisper ab und lässt Claude daraus Feldvorschläge mit wörtlichem Zitat machen. Kein Feld wird ohne Klick belegt, gespeichert wird nur über „Speichern“, Ton und Text sind danach gelöscht.

Architecture: Neues Backend-Modul src/voice mit vier Schichten, die Beute Teil 4 unverändert wiederverwendet: core/ (Schlüsselbund-Zweck voice, Transkript-Hülle mit Segmenten, Text-Normalisierung und Zitatprüfung, Feld-Tabelle aus CreateInspectionDto, Fachwortliste), claims/ (Claim-, Settle- und Stale-Funktionen mit eigener Wiederholregel je Phase), extraction/ (Port StructuredModel mit Anthropic-Adapter, Prompt, Schema, reine Prüfung, Worker-Schleife voice-extractions) und captures/ (API, Übernahme in POST /inspections, Aufräumen). Abschreiben läuft als CronJob apicore-job-voice-transcribe mit drei Containern (Node fetch → Python whisper ohne Netz und ohne Schlüssel → Node ingest). Frontend: lib/voice (Spracherkennungs-Kapsel, Einwilligung, Recorder, Warteschlange pending-voice, API, Vorschlags-Mapping) und components/voice (Diktat-Knopf, Aufnahme, generisches VoiceSuggestion).

Tech Stack: NestJS 11, Prisma 7.9 (@prisma/adapter-pg), PostgreSQL (Betrieb 18.6, Test-DB 17 auf Port 5433: keine 18-only-Funktionen), Jest 30, @anthropic-ai/sdk (neu, exakt gepinnt, ≥ 14 Tage alt am Installationstag), Multer über @nestjs/platform-express (vorhanden); Next.js 16, React 19.2, TanStack Query 5, idb, Vitest 4 + RTL + fake-indexeddb (vorhanden), axe über die vorhandene Test-Hilfe; Python 3.12-slim, faster-whisper, PyAV, pytest (nur im Image apicore-whisper).

Spec: docs/superpowers/specs/2026-10-14-t7-sprache-design.md (bindend). Anschluss-Vorgaben aus docs/superpowers/specs/2026-10-16-beute-teil4-sprach-durchsicht-design.md (Teil 4 baut auf T7 auf; T7 baut Teil 4 nicht, schneidet aber die Bausteine so, dass Teil 4 sie nur erweitert). Muster und Format: docs/superpowers/plans/2026-10-14-t6-compliance.md, 2026-10-15-beute-3d.md.

Spec-Widersprüche zum Code (geprüft am 2026-10-16, HEAD `b73da4d8`) und Auflösung

Jede Zeile: Befund → Auflösung, die dieser Plan umsetzt. Punkte mit „Inhaber“ brauchen eine Bestätigung vor Task 8 bzw. Task 21; bis dahin gilt die Auflösung.

Feldgrenzen weichen ab. Spec 6.5: colonyStrength 0–30, broodFrames 0–30, feedStatus genau ausreichend|niedrig|kritisch. Code: CreateInspectionDto.colonyStrength 0–40, broodFrames nur Min(0), feedStatus ist Enum ColonyCondition mit fünf Werten (EXCELLENT GOOD AVERAGE WEAK CRITICAL, Labels in FEED_CONDITION_LABELS_DE). → FIELD_SPECS folgt dem DTO (Spec sagt selbst „gleiche Grenzen wie CreateInspectionDto“): colonyStrength 0–40, broodFrames 0–40 (serverseitige Verschärfung, weil das DTO keine Obergrenze hat; Wächter prüft „innerhalb der DTO-Grenzen“ statt „gleich“), feedStatus ∈ ColonyCondition; der Prompt nennt die Ankerwörter aus FEED_CONDITION_LABELS_DE (reichlich, ausreichend, mittel, niedrig, kritisch). Gleiche Werte wie Teil 4 §5.5 (GOOD/WEAK/CRITICAL, 0–40).
Wächter „Schema-Enum = DTO-Felder minus Wetter und Temperatur“ ist so nicht erfüllbar. Das DTO hat zusätzlich colonyId, date, broodAmount (Alt-Text), applyToColony, hiveChange und bekommt voiceCaptureId. → Feste Ausschlussliste VOICE_EXCLUDED_INSPECTION_FIELDS mit Begründung je Feld; der Wächter vergleicht DTO-Eigenschaften (class-validator-Metadaten) minus Liste mit den 17 Feldern.
recordForUserOnce gibt es nicht. NotificationsService hat record(input, tx?) mit dauerhaft eindeutigem dedupeKey. → Handler nutzen record(..., tx) mit dedupeKey voice-ready:<captureId> bzw. voice-failed:<captureId>:<code>; Kategorie SUGGESTION (die Notiz ist ein Vorschlag an den Nutzer; Telegram nur, wenn der Nutzer die Kategorie gewählt hat). Text enthält nur den Volksnamen.
outbox-claims.ts passt nicht auf VoiceCapture. Es kennt nur PENDING/PROCESSING, eine feste MAX_ATTEMPTS = 8, ein festes STALE_CLAIM_MS = 300000 und CAS auf claimedAt; T7 braucht zwei Phasen mit eigenen Status, 3 Versuchen, 30 min bzw. 5 min Stale-Frist und claimToken (der Claim wandert über zwei Prozesse). retryDelayMs ist nicht parametrierbar. → retry-policy.ts bekommt RetryPolicy und retryDelayMsFor(policy, attempts) (der bestehende retryDelayMs delegiert, Verhalten unverändert); neue src/voice/claims/voice-claims.ts mit derselben SQL-Form (SKIP LOCKED, now(), geschlossene Tabellen-Map) für VoiceCapture – Teil 4 trägt VoiceUtterance in dieselbe Map ein.
Wartezeiten beim Auswerten: „höchstens 3 Versuche“ und „30 s / 2 min / 10 min“ – bei 3 Versuchen werden nur zwei Wartezeiten gebraucht. → 3 Versuche bleiben (Entscheidung), Wartezeiten [30000, 120000]; 10 min entfällt. EXTRACT_INVALID hat laut Spec 10 „einen Wiederholungsversuch“ → zählt als normaler Versuch (passt in die 3).
Ein attempts-Zähler für zwei Phasen. → ingest setzt beim Übergang nach TRANSCRIBED attempts = 0; retry setzt ihn ebenfalls auf 0 (Spec 5).
Ton „höchstens 24 h“, aber Löschung nur im täglichen cleanup (04:00) – Ton könnte bis zu 48 h liegen. → expireVoiceContent(db) (Ton > 24 h, Inhalte nach contentExpiresAt, Inhalte deaktivierter Nutzer) läuft zusätzlich in der fetch-Phase jedes CronJob-Laufs (alle 2 min, reine SQL, kein Schlüssel nötig); cleanup ruft dieselbe Funktion und löscht Zeilen nach 90 Tagen. Teil 4 hängt dort seine 24-h-Frist für Sätze an.
VOICE_ENCRYPTION_KEY nur in api, worker, fetch/ingest (Spec 11.3) – aber startup-checks.ts verlangt in Produktion jeden Schlüssel aus ENCRYPTION_KEY_VARIABLES in jeder Rolle (API, Worker, alle Jobs), und alle Backend-Pods binden apicore-backend-secret per envFrom. → Schlüssel kommt wie MFA/WEBHOOK/BACKUP in apicore-backend-secret (ensure-secrets.sh erzeugt ihn), und zwar vor Rollout-Schritt 1 (sonst startet das neue Image nicht). Spec 14 Schritt 3.2 wird damit Voraussetzung von 4.1.
ANTHROPIC_API_KEY „in Produktion Pflicht“ und zugleich „fehlt er, startet der Worker“. → Nicht Pflicht. Eigenes Secret apicore-anthropic, nur im Worker per secretKeyRef (optional: true), Muster apicore-telegram. Startprüfung assertAnthropicKey(role, env) wie assertTelegramToken: Platzhalter oder falsches Format → Fehler-Log einmal, Auswertung aus (EXTRACT_DISABLED), kein Abbruch. API- und Job-Pods lesen den Schlüssel nie.
Gemeinsamer CronJob-Patch ist eine Falle. components/backend-roles/kustomization.yaml patcht alle CronJobs mit Label app=apicore-job mit einem Container job (Strategic Merge per Name). Der Voice-CronJob hat keinen Container job → der Patch fügt einen hinzu (Backend-Image ohne Kommando, alle Secrets). → Der Voice-CronJob trägt am CronJob-Objekt app: apicore-voice-job (vom Patch nicht getroffen) und nur im Pod-Template app: apicore-job (für NetworkPolicy apicore-jobs); Härtung, Zeitzone, Forbid stehen vollständig im eigenen Manifest; manifest-policy.test.mjs prüft, dass er genau drei Container hat.
IndexedDB „Version 4“ ist belegt (pending-phenology-reports, T4). Beute L5 plant v5 (pending-hive-changes), Teil 4 danach voice-sessions. → T7 nimmt die nächste freie Version beim Bau (v5, falls Beute L5 noch nicht gemergt ist, sonst v6); der Upgrade-Zweig prüft oldVersion < N. Task 17 schreibt die tatsächliche Nummer in db.ts und in den Bericht.
inspection-scales.ts gibt es nicht. Die Richtung der Skalen steckt im Formular (RatingDirection in lib/forms/rating.ts, je Feld in inspections/new/page.tsx). → Eine gemeinsame JSON-Quelle ApiCore-Backend/test/fixtures/voice/inspection-scales.json (Feld, gespeicherte Bedeutung von 1 und 5, Ankerwörter); Backend-Prompt liest sie zur Bauzeit über ein generiertes TS-Modul inspection-scales.ts, Frontend-Wächter vergleicht sie mit einer neuen Konstante INSPECTION_SCALE_DIRECTIONS (lib/inspections/scales.ts), die das Formular nutzt.
Rate-Limit „10/min je Nutzer“ – der Throttler zählt nach Client-IP (ClientIpThrottlerGuard). → @Throttle 10/min (IP) auf dem Upload plus Nutzergrenze in der DB (höchstens 10 neue Notizen in 60 s je ownerUserId, gleiche Abfrage wie die Tagesgrenze).
Übernahme nur bei READY (Spec 6.6) widerspricht dem Ziel „nach dem Speichern kein Inhalt mehr“: Bei TRANSCRIBED (Auswertung aus, Tageslimit), FAILED mit Text oder laufender Verarbeitung bliebe der Inhalt bis zu 7 Tage liegen, obwohl der Nutzer gespeichert hat. → Bestätigbar sind alle offenen Status (QUEUED … READY) und FAILED; CONFIRMED/DISCARDED/EXPIRED ergeben 409 VOICE_CAPTURE_GONE. Laufende Phasen schließen per CAS auf status + claimToken ab und ändern eine bestätigte Notiz nicht. Gleiches Volk bleibt Pflicht (409). Inhaber (Frage A1).
POST /voice-captures/discard-all steht in 8.4, fehlt in der API-Tabelle 5. → wird gebaut (Task 7). Kennung des Modells auf der Info-Seite (8.4) und der Schalter zum Ausblenden (14.5) brauchen Serverwissen → neuer Endpunkt GET /voice-captures/config ({ recordingEnabled, extractionEnabled, model, retention }), gesteuert über VOICE_RECORDING_ENABLED (ConfigMap, Standard false).
JobRun-Flut. run-cli.ts schreibt je Lauf eine JobRun-Zeile; zwei Phasen × 720 Läufe/Tag = 1440 Zeilen/Tag, 90 Tage Aufbewahrung. → cleanup löscht erfolgreiche voice-transcribe-Läufe ohne Arbeit (result->>'claimed' = '0' bzw. 'ingested' = '0') nach 24 h; Läufe mit Arbeit oder Fehler bleiben 90 Tage.
Netzwerk-Wächter. no-network-outside-loops.spec.ts erlaubt Netz nur in src/weather/, src/telegram/ und Altdateien. → Ausnahme genau für src/voice/extraction/anthropic-structured-model.ts und das Paket @anthropic-ai/sdk; src/jobs/** (also auch voice-transcribe.job.ts) und *.handlers.ts dürfen es nicht importieren.
Magic Bytes: matchesFileSignature gibt für unbekannte Typen true zurück und kennt kein Audio. → Neue strikte Funktion detectAudioType(buffer): VoiceAudioMime | null in src/common/file-signature.ts (EBML 1A 45 DF A3 → audio/webm, OggS → audio/ogg, ftyp an Byte 4 → audio/mp4); matchesFileSignature bleibt unverändert.
Render-Stufen. deploy/k8s/tests/render-stages.mjs kennt eine feste ROLLOUT_ORDER. → Neue Stufe voice (nach api-hpa) in render-stages.mjs und als auskommentierbare Komponente im Overlay.
Kein Playwright im Repo (Beute-Plan Global Constraints). → Browser-Prüfungen mit chrome-devtools-MCP; Teil 4 §15.3 erwähnt Playwright, das ist dort zu klären, nicht in T7.

Global Constraints

Ablauf

Arbeit auf main. Agents committen nicht; der Orchestrator committet einmal je Lieferung (L1…L6) nach den Gates und pusht gebündelt.
Backend-Gates: npm run typecheck && npx eslint "{src,test}/**/*.ts" && npm test -- --ci (nie npm run lint, das Skript hat --fix); einzelne e2e npx jest --config ./test/jest-e2e.json test/<datei>.e2e-spec.ts --runInBand; alle e2e npm run test:e2e -- --runInBand. Frontend: vor Next.js-Code node_modules/next/dist/docs/ lesen (AGENTS.md); Gates npm run lint && npm run typecheck && npx vitest run <pfade>, am Lieferungsende npm test und npm run build. Manifeste: node deploy/k8s/tests/manifest-policy.test.mjs und render-stages.mjs. Whisper: pytest im Image-Build.
Die Test-DB ist nicht leer: Tests legen eigene Nutzer/Völker an, räumen VoiceCapture* in beforeEach auf und prüfen Differenzen.
Neue Abhängigkeiten: vor der Installation supply-chain-risk-auditor; exakt pinnen (--save-exact); Ergebnis in .superpowers/sdd/2026-10-16-t7-sprache/progress.md.
ARCHITECTURE.md, TASKS.md, docs/pruefung-2026-09.md trägt nur der Orchestrator ein; Tasks liefern Doku-Text im Bericht. Neue Annahmen bekommen die nächste freie Nummer beim Eintrag (heute zuletzt 100, Beute).

Migration (eine, additiv, nach 20261018100100_hive_catalog_frame_feeder; hängt ein anderer Strang davor eine an, rückt der Stempel dahinter)

Zeitstempel	Name	Inhalt
20261019100000	`t7_voice_captures`	Enums `VoiceCaptureSource`, `VoiceCaptureStatus`; Modelle `VoiceCapture`, `VoiceCaptureAudio` exakt Spec §3; CHECKs `"audioBytes" IS NULL OR "audioBytes" BETWEEN 1 AND 2097152`, `"durationSec" IS NULL OR "durationSec" BETWEEN 1 AND 240`, `("status" = 'CONFIRMED') = ("inspectionId" IS NOT NULL)`, `"source" = 'AUDIO' OR "audioMime" IS NULL`; Recht `voice-captures:use` mit Vergabe an ADMIN, BEEKEEPER, STAFF (`ON CONFLICT DO NOTHING`)

Erzeugt mit npx prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --script, von Hand ergänzt; nie db push, nie migrate dev.

Fachwerte (exakt aus der Spec)

Aufnahme: Mono, audioBitsPerSecond: 24000, Typ audio/webm;codecs=opus, sonst audio/mp4; höchstens 180 s, Hinweis bei 150 s „Noch 30 Sekunden“; Upload ≤ 2 MB (2097152 Byte), genau ein Teil audio; Typ nur nach Magic Bytes, sonst 415 UNSUPPORTED_AUDIO, zu groß 413 TOO_LARGE.
Grenzen je Nutzer: ≤ 10 offene Notizen (QUEUED bis READY), ≤ 30 neue je UTC-Tag, ≤ 10 neue je 60 s → 429 TOO_MANY_OPEN „Zu viele offene Sprachnotizen. Erst auswerten oder verwerfen.“ Volk lebend (LIVING_COLONY_WHERE), inspectionDate höchstens 7 Tage zurück, nicht in der Zukunft (Berliner Tag). Text-Weg 20–4000 Zeichen nach NFKC und Entfernen von Steuerzeichen.
Zustände und Fristen: Abschreiben ≤ 3 Versuche, Wartezeiten 5 min / 15 min, Stale 30 min; Auswerten ≤ 3 Versuche, 30 s / 2 min, Stale 5 min. Ton ≤ 24 h (FAILED/AUDIO_EXPIRED), Inhalte ≤ 7 Tage (EXPIRED, contentExpiresAt = createdAt + 7 Tage), Zeile 90 Tage. Alle Fristen in SQL gegen now().
CronJob apicore-job-voice-transcribe: */2 * * * *, timeZone: Europe/Berlin, concurrencyPolicy: Forbid, startingDeadlineSeconds: 120, activeDeadlineSeconds: 1500; je Lauf ≤ 5 Aufnahmen und ≤ 600 s Ton; emptyDir medium: Memory, sizeLimit: 32Mi. Ressourcen: fetch/ingest 50m/500m, 192Mi/512Mi; whisper 50m/2000m, 1280Mi/1280Mi, WHISPER_CPU_THREADS=2.
Whisper: Modell small, int8, language='de', beam_size=1, vad_filter=True, condition_on_previous_text=False, initial_prompt aus voice-vocabulary.ts; NO_SPEECH bei Sprache ≠ de mit Wahrscheinlichkeit < 0,6 oder Text < 5 Zeichen; TOO_LONG bei gemessener Dauer > 240 s.
Claude: VOICE_MODEL Standard claude-sonnet-5-5 (Option für Kosten: claude-haiku-5-5, Option bei Qualitätsmangel: claude-opus-5-5), Kennungen nur in voice-config.ts; max_tokens 2000, output_config: { effort: 'low', format: { type: 'json_schema', schema } }, nicht streamend, Zeitlimit 60 s, 2 SDK-Wiederholungen, kein tool_choice, kein Prefill, keine Sampling-Parameter; fallbacks: "default" mit Beta-Header server-side-fallback-2026-07-01 nur, wenn die aktuelle Anthropic-Doku es beim Bau bestätigt (sonst weglassen, Vermerk im Bericht). SDK-Debug-Log aus. VOICE_DAILY_EXTRACTIONS Standard 60 (Betrieb gesamt, UTC-Tag).
Prüfung: Zitat ≤ 120 Zeichen, normalisiert (NFKC, Kleinbuchstaben, Nicht-Buchstaben/Ziffern → Leerzeichen, Mehrfach-Leerzeichen zusammengefasst) muss im normalisierten Transkript stehen; Freitext 1–500 Zeichen nach Entfernen von Steuerzeichen und </>, länger gekürzt und markiert; findings ≤ 20, unclear ≤ 5; pro Feld ein Vorschlag, der spätere gewinnt, der frühere als previous.
Rechte: voice-captures:use (Gruppe „Sprache“, sortOrder 4000, höchster vorhandener Wert ist 3900); jeder Endpunkt zusätzlich inspections:create; GET /voice-captures/stats nur system:manage. Fremde Ids → 404. Antworten Cache-Control: no-store.
Ereignisse: VoiceCaptureReady { captureId, colonyId }, VoiceCaptureFailed { captureId, code }, AggregateType + 'VoiceCapture'; nie Text; nie Webhooks.
Backup: VoiceCapture, VoiceCaptureAudio in MODELS_EXCLUDED_FROM_BACKUP mit Begründung „flüchtig, personenbezogen, nach Restore nicht mehr zustellbar“.
Fehlercodes (fest, VOICE_ERROR_CODES): UNSUPPORTED_AUDIO, TOO_LARGE, TOO_MANY_OPEN, NO_SPEECH, TOO_LONG, TRANSCRIBE_FAILED, AUDIO_EXPIRED, EXTRACT_DISABLED, EXTRACT_RETRY, EXTRACT_FAILED, DAILY_LIMIT, EXTRACT_INVALID, REFUSED, VOICE_CAPTURE_GONE.

Projektregeln

Sicherheit vor Bequemlichkeit. Inhalt (Ton, Text, Zitat, KI-Antwort) nie in Logs, Fehlertexten, Ereignissen, Audit, Metriken, lastErrorCode; Fehler nur über loggableError().
Datensatz, Audit, Ereignis in einer Transaktion; Handler schreiben nur über tx, ohne Netz (handler-contract.spec.ts deckt voice.handlers.ts ab).
Read-modify-write unter Zeilensperre: VoiceCapture kommt ans Ende von LOCKABLE_TABLES (nach ComplianceAcknowledgement); Durchsicht sperrt (falls nötig) Colony, dann VoiceCapture.
Worker und Jobs nutzen JobPermissionsModule; Module mit Handlern werden von AppModule und WorkerModule importiert. Der Anthropic-Adapter wird nur im Worker-Modul bereitgestellt.
UI deutsch, kurze Sätze, Zustand nie nur über Farbe, Ziele ≥ 56 px (Aufnahmetaste 72 px, Diktat-Knopf 44 px laut Spec 8.3), WCAG 2.2 AA, prefers-reduced-motion. Code, Testnamen, Log-Texte englisch.

Review Focus

Inhalt leckt: Log-Mitschnitt-Tests in Tasks 7, 11, 15 (never logs the transcript), Ereignis-Payloads nur Ids (Task 9), Whisper-Container ohne Secrets/Netz (Task 13 Policy-Test), VoiceCapture nicht in Suche/Export/Backup (Task 4).
Löschung beweisbar: confirms the voice capture and wipes its content in the same transaction (Task 8), expires audio after 24 h within one CronJob run (Task 11), Discard/Discard-all (Task 7), e2e Ende-zu-Ende (Task 23).
Erfundenes oder Fremdes kommt nie ins Formular: validateSuggestions verwirft Zitat-lose, fremde Felder, Werte außerhalb FIELD_SPECS (Task 14); Formular belegt kein Feld ohne Klick (Task 20).
Doppelarbeit/verlorene Claims: fetch claims disjoint sets under SKIP LOCKED, ingest does nothing when the claim token no longer matches, a confirmed capture is not overwritten by a late ingest or extraction (Tasks 10, 11, 15).
Offline-Warteschlange bricht nichts: DB-Upgrade behält alle Speicher (Task 17), fremde Konten senden nie, Ton im Gerät nach 2xx weg, 4xx bleibt als lastError (Task 18).

Anschluss Teil 4 (was T7 so schneidet, dass Teil 4 es nur erweitert)

T7-Baustein	Schnittstelle	Teil-4-Nutzung (Spec Teil 4)
`lib/voice/speech-support.ts`	`detectSpeechSupport()`, `createRecognition(options)` mit `continuous`, `maxAlternatives`, `processLocally`, `phrases?`	Erkennungs-Schleife §4.2/4.3 baut darauf; T7 nutzt `continuous: false`
`lib/voice/consent.ts`	Cloud-Einwilligung, Aufnahmehinweis	§4.1, §12.1
`lib/voice/recorder.ts`	`startRecording({ maxSec, warnAtSec })`	Stücke zu 180 s §10.1
`pending-voice`	Eintrag `StoredVoiceNote`, Felder additiv	`sessionId`, `chunkIndex`, `isLastChunk`, `context` §10.1
`src/voice/core/voice-crypto.ts`	`sealVoiceText/openVoiceText/sealVoiceBytes/openVoiceBytes(…, aad)`	`VoiceUtterance.textEnc`, `VoiceSession.resultEnc`
`src/voice/core/transcript.ts`	`TranscriptPayload { v: 1, text, durationSec?, segments? }`	Stücke zusammenfügen über Segmente §10.3
Whisper-Ausgabe	JSON mit `segments: [{ start, end, text }]` schon in T7	§7.4 („bekommt `segments`“ entfällt dort)
`src/voice/core/voice-text.ts`	`normalizeInputText`, `normalizeForQuote`, `quoteInText`, `sanitizeFreeText`	§8.4 Schritte 3 und 5
`src/voice/core/inspection-field-specs.ts`	`FIELD_SPECS`, `checkFieldValue`	§8.4 Schritt 1 (ergänzt `FRAME_FIELD_SPECS`)
`src/voice/core/voice-vocabulary.ts` + `test/fixtures/voice/vocabulary.json`	eine Quelle	`phrases`, Prompt, Hörfehler
`src/voice/claims/voice-claims.ts`	`VOICE_CLAIM_TABLES` (geschlossene Map), `RetryPolicy` je Phase	`VoiceUtterance` als zweite Tabelle
`src/voice/extraction/structured-model.port.ts`	`StructuredModel.extract({ model, system: SystemBlock[], userText, schema, maxTokens, timeoutMs, maxRetries })`, `SystemBlock.cache?: '5m' \| '1h'`, `TokenUsage` mit Cache-Zählern	Schleife `voice-live`, 1-h-Cache, Haiku
`src/voice/voice-config.ts`	Modell-Kennungen an einer Stelle	`VOICE_LIVE_MODEL`, `VOICE_LIVE_FALLBACK_MODEL`
`VoiceConfirmationService.confirmIn(tx, link, ctx)`	`VoiceLink = { kind: 'capture'; id }` (diskriminierte Union)	`{ kind: 'session'; id }` §9.3
`src/voice/voice-retention.ts`	`expireVoiceContent(db)`	24-h-Frist der Sätze §13
`components/voice/voice-suggestion.tsx`	generisch `{ fieldLabel, valueText, quote, chips, onTakeOver, onEdit }`	Prüfansicht §10.4
`WAKE_CHANNELS.voiceExtraction`	eigenes Muster	`voiceLive` daneben

Abhängigkeiten und Wellen

Welle	Tasks (parallel, disjunkte Dateien)	wartet auf
1	1, 4	– (1 ist reines Frontend)
2	2, 5, 6, 10	2 → 1; 5, 6, 10 → 4
3	3, 7, 12	3 → 2; 7 → 5, 6; 12 → 6
4	8, 9, 11, 14	8 → 7; 9 → 7; 11 → 10, 12; 14 → 6
5	13, 15, 17	13 → 11, 12; 15 → 9, 10, 14; 17 → 1
6	16, 18, 19	16 → 11, 15; 18 → 7, 17; 19 → 18
7	20, 21, 22	20 → 8, 19; 21 → 3, 20; 22 → 7, 19
8	23, 24	alle
–	25 Abschluss und Rollout (Orchestrator)	23, 24

Geteilte Dateien (je Welle höchstens ein Task): prisma/schema.prisma, row-lock.ts, permission-catalog.ts, backup.service.ts: nur 4. key-ring.ts, startup-checks.ts: nur 5. domain-event-types.ts: nur 9. worker-runtime.service.ts, worker-wakeup.ts, worker.module.ts: nur 15. job-names.ts, jobs.module.ts: nur 11; cleanup.job.ts: nur 16. inspections.service.ts, create-inspection.dto.ts: nur 8. app.module.ts: 7 (W3), 9 (W4, nur falls das Handler-Modul neu ist – sonst 7). Frontend db.ts: nur 17; sync.ts, pending-queue-sheet.tsx, offline-band.tsx: nur 18; inspections/new/page.tsx: 20 (W7), 21 erweitert in derselben Welle nicht – 21 liefert Komponenten, 20 bindet sie ein (21 → 20 Reihenfolge innerhalb W7: 20 zuerst). nav-config.ts, quick-actions.ts: nur 19.

Lieferung L1 – Stufe 1 „Diktat“ (nur Frontend, kann vor allem anderen live)

Task 1: Spracherkennungs-Kapsel und Einwilligung

Files

Create: ApiCore-Frontend/src/lib/voice/speech-support.ts, consent.ts, vocabulary.ts (+ Specs)
Create: ApiCore-Backend/test/fixtures/voice/vocabulary.json (Fachwortliste, Spec 6.3: Königin, Stifte, Weiselzellen, Brutwaben, Futterkranz, Honigraum, Varroa, Schwarmstimmung, sanftmütig, Wabensitz, Drohnenbrut und weitere)
Test: speech-support.spec.ts, consent.spec.ts, vocabulary.spec.ts

Interfaces

export type LocalAvailability = 'available' | 'downloadable' | 'unavailable' | 'unknown';
export interface SpeechSupport { api: boolean; local: LocalAvailability; cloudAllowed: boolean; isInstalledIosPwa: boolean }
export function detectSpeechSupport(win?: Window): Promise<SpeechSupport>;
export interface RecognitionOptions { lang: 'de-DE'; continuous: boolean; interimResults: boolean; maxAlternatives: number; processLocally: boolean; phrases?: readonly string[] }
export interface RecognitionResultEvent { finalText: string; interimText: string; alternatives: string[] }
export interface RecognitionHandle { start(): void; stop(): void; abort(): void; on(event: 'result', fn: (e: RecognitionResultEvent) => void): void; on(event: 'end' | 'audiostart', fn: () => void): void; on(event: 'error', fn: (code: string) => void): void }
export function createRecognition(options: RecognitionOptions, win?: Window): RecognitionHandle | null; // null ohne API; phrases nur gesetzt, wenn die Eigenschaft existiert
// consent.ts (localStorage, jede Lese-/Schreiboperation in try/catch, Standard false)
export function getCloudRecognitionConsent(): boolean; export function setCloudRecognitionConsent(value: boolean): void;
export function hasSeenRecordingNotice(): boolean; export function markRecordingNoticeSeen(): void;
export const VOICE_VOCABULARY: readonly string[]; // aus der JSON-Fixture gespiegelt

Schritt 1: Failing Tests: returns api false without SpeechRecognition and webkitSpeechRecognition; reports local available via SpeechRecognition.available({ langs: ['de-DE'], processLocally: true }); reports unknown when available() is missing; cloudAllowed follows the stored consent and defaults to false; createRecognition sets processLocally only when requested and phrases only when supported; consent survives a throwing localStorage; VOICE_VOCABULARY equals the shared fixture (it.skipIf(!existsSync(fixture)), Muster placeholder-keys.spec.ts).
Schritt 2: npx vitest run src/lib/voice → FAIL. Schritt 3: Implementieren. Schritt 4: → PASS. Kein Commit.

Task 2: Diktat-Knopf an den Freitextfeldern

Files

Create: ApiCore-Frontend/src/components/voice/dictation-button.tsx, use-dictation.ts (+ Specs)
Modify: ApiCore-Frontend/src/app/(app)/inspections/new/page.tsx (Knopf rechts an notes, healthIssues, varroaIssues, measures)
Test: dictation.spec.tsx, inspections/new/page.spec.tsx (Erweiterung)

Interfaces

useDictation({ onFinal(text: string): void }): { state: 'idle' | 'listening' | 'unavailable' | 'needs-consent' | 'error'; interim: string; start(): void; stop(): void } – lang 'de-DE', continuous: false, interimResults: true, processLocally: true bei local = 'available', sonst nur mit Einwilligung.
<DictationButton fieldId fieldLabel onAppend(text) />: 44 px, Beschriftung „Diktieren“, während des Diktats „Hört zu …“ plus grauer Zwischentext und Stopp-Knopf; Zustand als Text (offline: „Nur auf dem Gerät“); erscheint nicht, wenn api false oder weder Gerät noch Einwilligung; installierte iOS-PWA: Hinweis „Hier lieber eine Sprachnotiz aufnehmen“ statt Knopf.
Schritt 1: Failing Tests: hides the button when the browser has no speech recognition; appends and never overwrites (Feld „Alt“ + Ergebnis „neu“ → „Alt neu“); offers cloud recognition only after consent; shows the state as text, not only colour; stops on the stop button and releases the recognizer.
Schritt 2: FAIL. Schritt 3: Implementieren. Schritt 4: PASS; Gates Frontend.

Task 3: Seite „Sprache & Datenschutz“ (Grundstock)

Files

Create: ApiCore-Frontend/src/app/(app)/settings/voice/page.tsx, voice-privacy-text.ts (+ Spec)
Modify: ApiCore-Frontend/src/app/(app)/settings/layout.tsx bzw. die Einstellungs-Navigation (Eintrag „Sprache & Datenschutz“, für alle angemeldeten Nutzer)
Test: settings/voice/page.spec.tsx

Interfaces

Abschnitte nach Spec 8.4 und 9.5: was mit Ton und Text passiert, Fristen (24 h / 7 Tage / 90 Tage), wohin (Cluster / Anthropic / bei Cloud-Erkennung Google bzw. Apple), Schalter „Browser-Cloud-Erkennung erlauben“ (Standard aus), Platzhalter für Name und Anschrift aus SiteSettings. Modellkennung und „Alle meine Sprachnotizen löschen“ folgen in Task 22 (brauchen Backend).
Schritt 1: Failing Tests: the cloud switch is off by default and stores the consent; names the retention periods in words; axe finds nothing.
Schritt 2–4: FAIL → Implementieren → PASS.
Schritt 5: Browser-Prüfung (chrome-devtools-MCP, 390 px und 1366 px, Tastatur, Fokus sichtbar, Chrome-Diktat mit echtem Mikrofon wenn verfügbar). Orchestrator committet feat: browser dictation for inspection text fields (T7 L1).

Lieferung L2 – Datenmodell, Schlüssel, API, Übernahme (Backend)

Task 4: Schema, Migration, Recht, Sperre, Backup-Ausnahme, Wächter

Files

Modify: ApiCore-Backend/prisma/schema.prisma (Spec §3 exakt; Gegenrelationen User.voiceCaptures, Colony.voiceCaptures), src/auth/permissions/permission-catalog.ts (...group('Sprache', 'voice-captures', [['use', 'Benutzen']], 4000)), src/prisma/row-lock.ts (+ Spec; VoiceCapture: lockable('VoiceCapture') am Ende), src/backup/backup.service.ts (+ Spec; Ausnahmeliste)
Create: prisma/migrations/20261019100000_t7_voice_captures/migration.sql
Test: neu test/t7-schema.e2e-spec.ts, test/voice-permissions.e2e-spec.ts; Erweiterung test/search.e2e-spec.ts bzw. Export-Spec (Wächter)

Interfaces

Prisma-Modelle VoiceCapture, VoiceCaptureAudio, Enums wie Spec §3. Keine Spalte für Teil 4 (sessionId, chunkIndex … kommen dort additiv).
Schritt 1: Failing Tests

// t7-schema.e2e-spec.ts
it('rejects audioBytes 0 and 2097153', ...);
it('rejects durationSec 241', ...);
it('rejects CONFIRMED without inspectionId and inspectionId on a non-confirmed row', ...);
it('rejects audioMime on a TEXT capture', ...);
it('deleting a capture cascades to its audio row', ...);
// voice-permissions.e2e-spec.ts
it('ADMIN, BEEKEEPER and STAFF hold voice-captures:use', ...);
it('READONLY and API_CLIENT do not', ...);
// row-lock.spec.ts
it('keeps the map in lock order with VoiceCapture last', ...);
// backup.service.spec.ts
it('excludes VoiceCapture and VoiceCaptureAudio with a reason', ...);
// Wächter
it('VoiceCapture appears in no search provider and no export', ...);

Schritt 2: FAIL. Schritt 3: Implementieren (SQL aus migrate diff, CHECKs und Rechte-INSERT von Hand). Schritt 4: PASS; Drift-Check npx prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --exit-code → 0; Test-DB migrieren (Muster T6 Global Constraints). Kein Commit.

Task 5: Schlüsselbund-Zweck `voice`, Verschlüsselungs-Hilfen, Startprüfungen

Files

Modify: src/common/crypto/key-ring.ts (+ Spec), src/runtime/startup-checks.ts (+ Spec), src/jobs/rekey.job.ts (+ Spec), deploy/k8s/base/backend/secret.example.yaml, deploy/k8s/scripts/ensure-secrets.sh
Create: src/voice/core/voice-crypto.ts (+ voice-crypto.spec.ts), src/voice/voice-config.ts (+ Spec), src/voice/anthropic-config.ts (+ Spec)

Interfaces

// key-ring.ts
ENCRYPTION_KEY_VARIABLES.voice = 'VOICE_ENCRYPTION_KEY'; type SecretPurpose = 'mfa' | 'webhook' | 'voice';
// voice-crypto.ts  (AES-256-GCM über gcmSeal/gcmOpen, Schlüssel-Id vorn, AAD bindet an die Zeile)
export function sealVoiceText(plaintext: string, aad: string): string;           // `k…:` Format, AAD z. B. 'capture:<id>:transcript'
export function openVoiceText(stored: string, aad: string): string;
export function sealVoiceBytes(plaintext: Buffer, aad: string): Buffer;           // [1 Byte Version][8 Byte Key-Id][12 IV][16 Tag][Daten]
export function openVoiceBytes(stored: Buffer, aad: string): Buffer;
export function isVoiceSealedWithCurrentKey(stored: string | Buffer): boolean;     // für rekey
// voice-config.ts
export const VOICE_MODELS = ['claude-sonnet-5-5', 'claude-haiku-5-5', 'claude-opus-5-5'] as const;
export const DEFAULT_VOICE_MODEL = 'claude-sonnet-5-5';
export interface VoiceConfig { model: (typeof VOICE_MODELS)[number]; dailyExtractions: number; recordingEnabled: boolean; whisperModel: 'small' | 'medium' }
export function voiceConfig(env?: NodeJS.ProcessEnv): VoiceConfig; // unbekanntes Modell -> Start-Fehler mit Variablennamen; dailyExtractions 1..10000, Standard 60
// anthropic-config.ts (Muster telegram-config.ts)
export function anthropicApiKey(env?: NodeJS.ProcessEnv): string | null;  // null bei leer, Platzhalter ^change-me oder Format != /^sk-ant-[A-Za-z0-9_-]{20,}$/
export function assertAnthropicKey(role: ApicoreRole, env?: NodeJS.ProcessEnv): void; // nur worker/all; loggt einmal, wirft nie

rekey: reseal offener transcriptEnc/suggestionEnc und VoiceCaptureAudio.dataEnc (nur Status ≠ CONFIRMED/DISCARDED/EXPIRED), Zähler im JobResult.
ensure-secrets.sh: VOICE_ENCRYPTION_KEY random in apicore-backend-secret; Kommentar: vor dem T7-Backend-Image ausführen (Widerspruch 8). secret.example.yaml: Schlüssel und Hinweis auf apicore-anthropic (nur Worker, secretKeyRef, optional: true, Muster Telegram).
Schritt 1: Failing Tests: audio and transcript round-trip through the key ring; fail with the wrong key; fail when the aad names another capture; use the voice purpose key, not the JWT secret; production requires VOICE_ENCRYPTION_KEY distinct from the others (startup-checks); rejects a change-me VOICE_ENCRYPTION_KEY in production; assertAnthropicKey never throws and disables on a placeholder; api and job roles skip the Anthropic check; voiceConfig rejects an unknown model id; rekey reseals open voice content and skips confirmed rows.
Schritt 2–4: FAIL → Implementieren → PASS. Kein Commit.

Task 6: Gemeinsamer Kern (Text, Zitat, Felder, Transkript, Fachwörter, Skalen)

Files

Create: src/voice/core/voice-text.ts, inspection-field-specs.ts, transcript.ts, voice-vocabulary.ts, inspection-scales.ts, voice-errors.ts (+ Specs)
Create: ApiCore-Backend/test/fixtures/voice/inspection-scales.json
Test: voice-text.spec.ts, inspection-field-specs.spec.ts, transcript.spec.ts, voice-vocabulary.spec.ts

Interfaces

// voice-text.ts
export function normalizeInputText(text: string): string;        // NFKC, Steuerzeichen außer \n entfernt, trim
export function normalizeForQuote(text: string): string;         // NFKC, lower, [^\p{L}\p{N}] -> ' ', Leerzeichen zusammengefasst
export function quoteInText(quote: string, text: string): boolean;
export function sanitizeFreeText(text: string, max: number): { text: string; truncated: boolean } | null; // null bei leer
// inspection-field-specs.ts
export const INSPECTION_VOICE_FIELDS = ['colonyStrength','broodFrames','broodPattern','openBroodPresent','cappedBroodPresent','eggsPresent','queenSeen','queenCellsPresent','swarmMood','gentleness','combBehavior','feedStatus','honeySuperStatus','healthIssues','varroaIssues','measures','notes'] as const;
export type InspectionVoiceField = (typeof INSPECTION_VOICE_FIELDS)[number];
export type FieldSpec = { kind: 'int'; min: number; max: number } | { kind: 'bool' } | { kind: 'enum'; values: readonly string[] } | { kind: 'text'; max: 500 };
export const FIELD_SPECS: Readonly<Record<InspectionVoiceField, FieldSpec>>;
export const VOICE_EXCLUDED_INSPECTION_FIELDS: Readonly<Record<string, string>>; // colonyId, date, weather, temperature, broodAmount, applyToColony, hiveChange, voiceCaptureId -> Begründung
export function checkFieldValue(field: string, value: unknown): { ok: true; field: InspectionVoiceField; value: number | boolean | string; truncated: boolean } | { ok: false };
// transcript.ts
export interface TranscriptSegment { start: number; end: number; text: string }
export interface TranscriptPayload { v: 1; text: string; durationSec?: number; segments?: TranscriptSegment[] }
export function sealTranscript(captureId: string, payload: TranscriptPayload): string;   // aad 'capture:<id>:transcript'
export function openTranscript(captureId: string, stored: string): TranscriptPayload;   // prüft v === 1
// voice-vocabulary.ts
export const VOICE_VOCABULARY: readonly string[]; export function whisperInitialPrompt(): string; // ≤ 224 Tokens grob: ≤ 800 Zeichen
// inspection-scales.ts (generiert aus der JSON-Fixture per Import mit resolveJsonModule)
export interface ScaleSpec { field: 'broodPattern' | 'swarmMood' | 'gentleness' | 'combBehavior'; storedOne: string; storedFive: string; anchors: Record<string, 1 | 2 | 3 | 4 | 5> }
export const INSPECTION_SCALES: readonly ScaleSpec[];
// voice-errors.ts
export const VOICE_ERROR_CODES = [...] as const; export type VoiceErrorCode = (typeof VOICE_ERROR_CODES)[number];

Schritt 1: Failing Tests: matches the quote across punctuation and case; does not match a quote with a changed number; sanitizeFreeText strips control characters and angle brackets and shortens to 500; FIELD_SPECS covers exactly the DTO fields minus the excluded list (Metadaten von CreateInspectionDto über getMetadataStorage()); FIELD_SPECS bounds lie within CreateInspectionDto (Min/Max je Feld); feedStatus accepts every ColonyCondition and nothing else; rejects weather and temperature; transcript payload round-trips with segments; rejects a payload with another version; VOICE_VOCABULARY equals the shared fixture; whisperInitialPrompt stays below 800 characters.
Schritt 2–4: FAIL → Implementieren → PASS. Kein Commit.

Task 7: Sprachnotizen-API (Upload, Text, Liste, Abruf, Wiederholen, Verwerfen, Konfiguration, Zähler)

Files

Create: src/voice/voice.module.ts, src/voice/captures/voice-captures.controller.ts, voice-captures.service.ts, voice-captures-stats.service.ts, voice-capture-view.ts, dto/upload-voice-capture.dto.ts, dto/submit-voice-text.dto.ts, dto/list-voice-captures.query.ts (+ Specs)
Modify: src/common/file-signature.ts (+ Spec: detectAudioType), src/app.module.ts, src/all-in-one.module.ts (falls dort gelistet)
Test: voice-captures.service.spec.ts, file-signature.spec.ts, test/authorization-coverage.e2e-spec.ts (läuft grün)

Interfaces

export type VoiceAudioMime = 'audio/webm' | 'audio/ogg' | 'audio/mp4';
export function detectAudioType(buffer: Buffer): VoiceAudioMime | null;
export interface VoiceCaptureListItem { id; colonyId; colonyName; status: VoiceCaptureStatus; source; createdAt: string; lastErrorCode: VoiceErrorCode | null; contentExpiresAt: string }
export interface VoiceCaptureDetail extends VoiceCaptureListItem { inspectionDate: string; transcript: string | null; suggestions: VoiceSuggestionView[] | null; unclear: string[]; dropped: number }
export interface VoiceSuggestionView { field: InspectionVoiceField; value: number | boolean | string; quote: string; corrected: boolean; truncated: boolean; previous?: { value: number | boolean | string; quote: string } }
export interface VoiceClientConfig { recordingEnabled: boolean; extractionEnabled: boolean; model: string; retention: { audioHours: 24; contentDays: 7; rowDays: 90 } }
VoiceCapturesService.upload(userId: string, file: Express.Multer.File, dto: UploadVoiceCaptureDto): Promise<{ id: string; status: 'QUEUED' }>;
VoiceCapturesService.submitText(userId: string, dto: SubmitVoiceTextDto): Promise<{ id: string; status: 'TRANSCRIBED' }>; // pg_notify voice_extraction im selben tx
VoiceCapturesService.list(userId: string, status?: VoiceCaptureStatus): Promise<VoiceCaptureListItem[]>;
VoiceCapturesService.get(userId: string, id: string): Promise<VoiceCaptureDetail>;       // transcript/suggestions bei READY, TRANSCRIBED, FAILED mit Inhalt
VoiceCapturesService.retry(userId: string, id: string): Promise<VoiceCaptureListItem>;    // nur FAILED mit Ton/Text und contentExpiresAt > now()
VoiceCapturesService.discard(userId: string, id: string): Promise<void>;                 // idempotent, löscht Audio-Zeile, transcriptEnc, suggestionEnc
VoiceCapturesService.discardAll(userId: string): Promise<{ discarded: number }>;
VoiceCapturesStatsService.stats(): Promise<{ byStatus: Record<string, number>; byError: Record<string, number>; tokens: { input: number; output: number }; byModel: Record<string, number> }>; // letzte 7 Tage, ohne Nutzerbezug
// Routen (alle @RequirePermission('voice-captures:use') + inspections:create, außer stats: system:manage; Header Cache-Control: no-store)
// POST /voice-captures (multipart, FileInterceptor('audio', { storage: memoryStorage(), limits: { fileSize: 2097152, files: 1, fields: 4 } }), @Idempotent(), @Throttle 10/min)
// POST /voice-captures/text (@Idempotent()), GET /voice-captures?status=, GET /voice-captures/config, GET /voice-captures/stats,
// GET /voice-captures/:id, POST /voice-captures/:id/retry, POST /voice-captures/:id/discard, POST /voice-captures/discard-all

Upload: Volk lebend, Datum-Regel, Nutzergrenzen (offen, Tag, 60 s) in einer Transaktion unter pg_advisory_xact_lock(hashtext('voice-captures:' || userId)), Ton mit sealVoiceBytes(…, 'capture:<id>:audio') in VoiceCaptureAudio, Audit CREATE ohne Inhalt. Keine Datei auf der Platte.
Statische Pfade (config, stats, discard-all, text) vor :id registrieren.
Schritt 1: Failing Tests: rejects foreign ids with 404; limits open captures; limits per day; limits ten per minute per user; checks magic bytes not the declared type (WebM-Bytes mit Content-Type: image/png → angenommen als audio/webm; PNG-Bytes mit audio/webm → 415); rejects a file above 2 MB with 413; rejects a dead colony; rejects an inspectionDate in the future or older than 7 days; discard deletes audio, transcript and suggestion; discard-all touches only the caller's captures; retry resets attempts and only works on FAILED with content; list never contains transcript or suggestions; stats has no user ids; never logs the transcript (Logger-Spion über den Text-Weg); detectAudioType knows EBML, OggS and ftyp and nothing else.
Schritt 2–4: FAIL → Implementieren → PASS. Kein Commit.

Task 8: Übernahme in `POST /inspections`

Files

Create: src/voice/captures/voice-confirmation.service.ts (+ Spec)
Modify: src/inspections/dto/create-inspection.dto.ts (voiceCaptureId?: string, @Matches(/^[A-Za-z0-9_-]{1,40}$/)), src/inspections/inspections.service.ts (create), src/inspections/inspections.module.ts (importiert VoiceModule bzw. ein schlankes VoiceConfirmationModule ohne Netz-Provider)
Test: inspections.service.spec.ts (Erweiterung), voice-confirmation.service.spec.ts

Interfaces

export type VoiceLink = { kind: 'capture'; id: string };                 // Teil 4 ergänzt { kind: 'session'; id }
export interface VoiceConfirmContext { userId: string; colonyId: string; inspectionId: string }
VoiceConfirmationService.confirmIn(tx: Prisma.TransactionClient, link: VoiceLink, ctx: VoiceConfirmContext): Promise<void>;
// sperrt VoiceCapture FOR UPDATE; fremd oder fehlend -> 409 VOICE_CAPTURE_GONE (nicht 404: der Client wiederholt ohne Id);
// anderes Volk -> 409 { code: 'VOICE_CAPTURE_COLONY_MISMATCH' }; CONFIRMED/DISCARDED/EXPIRED -> 409 VOICE_CAPTURE_GONE;
// sonst: status CONFIRMED, inspectionId, transcriptEnc/suggestionEnc NULL, Audio-Zeile gelöscht, claimToken NULL, contentDeletedAt now(), Audit UPDATE ohne Inhalt

InspectionsService.create: voiceCaptureId aus data herauslösen (wird nicht an Inspection gespeichert), nach dem Insert in derselben Transaktion confirmIn. Nicht bestätigbare Notiz → ganze Transaktion bricht ab, keine Durchsicht (Spec 6.6).
Schritt 1: Failing Tests: confirms the voice capture and wipes its content in the same transaction; 409 VOICE_CAPTURE_GONE for an expired, discarded or foreign capture and no inspection row; 409 when the capture belongs to another colony; rolls back the confirmation when the inspection fails; confirms a TRANSCRIBED capture too (Widerspruch 14); voiceCaptureId is never written to the inspection; without voiceCaptureId the existing specs stay green.
Schritt 2–4: FAIL → Implementieren → PASS; npx jest src/inspections src/voice. Kein Commit.

Task 9: Ereignisse, Handler, Meldungen

Files

Modify: src/domain-events/domain-event-types.ts (Payloads, CATALOG, AggregateType), src/domain-events/domain-events.service.spec.ts (Typliste), src/webhooks/webhook.handlers.spec.ts (nicht weitergeleitet)
Create: src/voice/voice.handlers.ts (+ Spec), Eintrag in voice.module.ts; WorkerModule importiert ein Modul mit den Handlern (Task 15 trägt es ein, hier nur VoiceHandlersModule bereitstellen)
Test: voice.handlers.spec.ts, handler-contract.spec.ts (läuft grün)

Interfaces

@OnDomainEvent(['VoiceCaptureReady'], 'voice.notify-ready'): notifications.record({ userId: owner, priority: 'HINWEIS', category: 'SUGGESTION', message: 'Sprachnotiz für {Volk} ist fertig', relatedType: 'VoiceCapture', relatedId: captureId, link: '/inspections/new?colonyId=…&voice=…', requiredPermissions: ['voice-captures:use'], dedupeKey: 'voice-ready:<captureId>' }, tx).
@OnDomainEvent(['VoiceCaptureFailed'], 'voice.notify-failed'): WARNUNG, „Sprachnotiz für {Volk} konnte nicht ausgewertet werden.“ plus je Code ein Satz aus VOICE_ERROR_TEXTS_DE (z. B. NO_SPEECH „Es war nichts zu verstehen. Bitte noch einmal aufnehmen.“), Link /voice, dedupeKey: 'voice-failed:<captureId>:<code>'.
Fehlschlag der Abschrift/Auswertung wegen EXTRACT_DISABLED meldet zusätzlich an system:manage (recordForPermissionOnce, ohne Nutzerbezug im Text).
Schritt 1: Failing Tests: writes one HINWEIS for the owner only once per capture; the failure text names the next step per code; payloads carry only ids and the code; neither event is forwarded to webhooks; the handler reads the colony name from the database, not from the payload.
Schritt 2–4: FAIL → Implementieren → PASS. Orchestrator prüft L2-Gates und committet feat: voice capture data model, API and inspection confirmation (T7 L2).

Lieferung L3 – Abschreiben im Cluster

Task 10: Wiederholregel und Voice-Claims

Files

Modify: src/common/retry-policy.ts (+ Spec)
Create: src/voice/claims/voice-claims.ts, voice-phases.ts (+ Specs)
Test: retry-policy.spec.ts, voice-claims.spec.ts, neu test/voice-claims.e2e-spec.ts

Interfaces

// retry-policy.ts
export interface RetryPolicy { delaysMs: readonly number[]; maxAttempts: number; staleClaimMs: number }
export const DEFAULT_RETRY_POLICY: RetryPolicy; // = bisherige Konstanten
export function retryDelayMsFor(policy: RetryPolicy, attempts: number): number; // retryDelayMs(a) === retryDelayMsFor(DEFAULT_RETRY_POLICY, a)
// voice-phases.ts
export const VOICE_PHASES = {
  transcribe: { from: 'QUEUED', working: 'TRANSCRIBING', policy: { delaysMs: [300_000, 900_000], maxAttempts: 3, staleClaimMs: 1_800_000 } },
  extract:    { from: 'TRANSCRIBED', working: 'EXTRACTING', policy: { delaysMs: [30_000, 120_000], maxAttempts: 3, staleClaimMs: 300_000 } },
} as const;
export type VoicePhase = keyof typeof VOICE_PHASES;
// voice-claims.ts (geschlossene Map VOICE_CLAIM_TABLES = { VoiceCapture: {...} }; Teil 4 ergänzt VoiceUtterance)
export interface VoiceClaim { id: string; claimToken: string; attempts: number; ownerUserId: string; colonyId: string; audioMime: string | null; durationSec: number | null }
export function claimVoiceCaptures(db: PrismaService, phase: VoicePhase, opts: { limit: number; maxTotalSec?: number }): Promise<VoiceClaim[]>; // UPDATE … FOR UPDATE SKIP LOCKED, claimToken = gen_random_uuid(), ordered createdAt; maxTotalSec über laufende Summe (Fenster-Funktion)
export function settleVoiceSuccess(tx: DbClient, phase: VoicePhase, claim: Pick<VoiceClaim, 'id' | 'claimToken'>, set: Prisma.Sql): Promise<boolean>; // CAS status = working AND claimToken
export function settleVoiceFailure(db: DbClient, phase: VoicePhase, claim: VoiceClaim, code: VoiceErrorCode): Promise<'retry' | 'failed'>;
export function deferVoiceClaim(db: DbClient, phase: VoicePhase, claim: VoiceClaim, delayMs: number): Promise<boolean>; // ohne Versuch (Tageslimit, Schlüssel fehlt)
export function releaseStaleVoiceClaims(db: PrismaService, phase: VoicePhase): Promise<{ id: string; status: string }[]>;

Schritt 1: Failing Tests: retryDelayMs keeps its old values; retryDelayMsFor uses the policy's delays; e2e fetch claims disjoint sets under SKIP LOCKED (zwei parallele Claims); respects the total seconds of audio per run; stale TRANSCRIBING claims are released with attempts + 1; the third failure ends FAILED with the code; settle does nothing when the claim token no longer matches; settle does nothing on a capture confirmed meanwhile.
Schritt 2–4: FAIL → Implementieren → PASS (npx jest src/common src/voice und die e2e-Datei). Kein Commit.

Task 11: Job `voice-transcribe` (Phasen `fetch` und `ingest`) und Aufbewahrung im Takt

Files

Create: src/jobs/voice-transcribe.job.ts (+ Spec), src/voice/transcribe/work-dir.ts (+ Spec), src/voice/voice-retention.ts (+ Spec)
Modify: src/jobs/job-names.ts (+ Spec: 'voice-transcribe', Label „Sprachnotizen abschreiben“, JOB_FAILURE_PERMISSION: 'system:manage', JOB_ALLOWED_ARGS: ['--phase=fetch', '--phase=ingest']), src/jobs/jobs.module.ts, src/common/worker-wakeup.ts (voiceExtraction: 'voice_extraction' – nur die Konstante; die Schleife folgt in Task 15)
Test: voice-transcribe.job.spec.ts, work-dir.spec.ts, voice-retention.spec.ts, Erweiterung test/jobs.e2e-spec.ts

Interfaces

// work-dir.ts (Pfad aus VOICE_WORK_DIR, Standard /work; Dateinamen nur aus cuids)
export interface WorkManifest { v: 1; items: { captureId: string; claimToken: string; file: string; mime: VoiceAudioMime; reportedSec: number | null }[] }
export interface WhisperResult { v: 1; captureId: string; text: string; durationSec: number; language: string; languageProbability: number; segments: TranscriptSegment[]; error?: 'NO_SPEECH' | 'TOO_LONG' | 'DECODE_FAILED' }
export function writeInputs(dir: string, items: { claim: VoiceClaim; audio: Buffer }[]): Promise<WorkManifest>; // 0600, Größe ≤ 32Mi geprüft vor dem Schreiben
export function readResults(dir: string, manifest: WorkManifest): Promise<Map<string, WhisperResult | null>>; // null = keine/kaputte Datei; Schema streng geprüft
// voice-retention.ts
export interface VoiceRetentionCounts { audioExpired: number; contentExpired: number; inactiveOwnersWiped: number }
export function expireVoiceContent(db: PrismaService): Promise<VoiceRetentionCounts>; // Ton > 24 h -> FAILED/AUDIO_EXPIRED (+ VoiceCaptureFailed); contentExpiresAt < now() -> EXPIRED; Inhalte deaktivierter Nutzer löschen
export function deleteOldVoiceRows(db: PrismaService): Promise<number>;                 // createdAt < now() - 90 Tage
// voice-transcribe.job.ts
run(['--phase=fetch']): expireVoiceContent; releaseStaleVoiceClaims('transcribe'); claim ≤ 5 / ≤ 600 s; Ton entschlüsseln; writeInputs; JobResult { claimed, audioExpired, contentExpired }
run(['--phase=ingest']): Manifest lesen (fehlt -> { ingested: 0 }); je Ergebnis: Erfolg -> sealTranscript, Audio-Zeile löschen, status TRANSCRIBED, attempts 0, durationSec gemessen, pg_notify('voice_extraction') in einer Transaktion (CAS);
  NO_SPEECH/TOO_LONG -> FAILED mit Code, Ton löschen, VoiceCaptureFailed; fehlend/DECODE_FAILED -> settleVoiceFailure(TRANSCRIBE_FAILED); Arbeitsdateien danach löschen; JobResult { ingested, failed }

Ohne offene Arbeit: fetch macht eine Abfrage (SELECT 1 … LIMIT 1) und endet; Gesamtlauf < 5 s (Spec 4.2).
Schritt 1: Failing Tests: fetch writes one file per claimed capture and a manifest; fetch ends quickly without work and writes no manifest; ingest stores TRANSCRIBED, deletes the audio and wakes the worker in one transaction; ingest does nothing when the claim token no longer matches; a confirmed capture is not overwritten by a late ingest; NO_SPEECH and TOO_LONG end FAILED and delete the audio; a missing result counts as a failed attempt; expires audio after 24 h within one CronJob run; wipes content after 7 days and marks EXPIRED; wipes content of deactivated users; job names accept only --phase=fetch and --phase=ingest; ingest never logs the transcript.
Schritt 2–4: FAIL → Implementieren → PASS. Kein Commit.

Task 12: Fachwortliste für Whisper exportieren (Brücke Node → Python)

Files

Create: ApiCore-Backend/scripts/export-voice-vocabulary.ts (schreibt ApiCore-Whisper/vocabulary.txt aus voice-vocabulary.ts), Wächter src/voice/core/voice-vocabulary-export.spec.ts

Interfaces

ApiCore-Whisper/vocabulary.txt ist eingecheckt; der Wächter vergleicht ihn mit whisperInitialPrompt() (eine Quelle, Spec 6.3).
Schritt 1: Failing Test the whisper vocabulary file equals whisperInitialPrompt(). Schritt 2–4: FAIL → Skript, Datei → PASS. Kein Commit.

Task 13: Image `apicore-whisper`, CronJob-Komponente `voice`, Policy-Tests

Files

Create: ApiCore-Whisper/transcribe.py, ApiCore-Whisper/requirements.txt (mit --hash), ApiCore-Whisper/Dockerfile, ApiCore-Whisper/tests/test_transcribe.py, ApiCore-Whisper/vocabulary.txt (aus Task 12), .gitea/workflows/whisper-image.yml
Create: deploy/k8s/components/voice/kustomization.yaml, cronjob-voice-transcribe.yaml, patch-worker-voice.yaml
Modify: deploy/k8s/overlays/encry/kustomization.yaml (Komponente voice als letzte, Image git.encry.de/nick.rosenloecher/apicore-whisper mit Platzhalter-Digest), deploy/k8s/overlays/encry/configmap-backend.yaml (VOICE_RECORDING_ENABLED: "false", VOICE_MODEL: claude-sonnet-5-5, VOICE_DAILY_EXTRACTIONS: "60"), deploy/k8s/tests/manifest-policy.test.mjs, deploy/k8s/tests/render-stages.mjs (Stufe voice)

Interfaces

transcribe.py: liest /work/in/manifest.json; ohne Manifest Exit 0 sofort; lädt WhisperModel('/models/small', device='cpu', compute_type='int8', cpu_threads=int(os.environ['WHISPER_CPU_THREADS'])) einmal; je Datei nacheinander, eine kaputte Datei bricht den Lauf nicht ab; schreibt /work/out/<captureId>.json nach WhisperResult; Dauer vor dem Abschreiben per PyAV messen (TOO_LONG > 240 s ohne Dekodieren des Rests); vor dem Modell-Laden socket.socket gesperrt (Belt-and-braces zur NetworkPolicy). Ausgabe auf stdout nur Zähler.
Dockerfile: python:3.12-slim@sha256:…, Nutzer 1000, pip install --require-hashes -r requirements.txt, Modelldateien small int8 nach /models/small mit SHA-256-Prüfung im Build, kein Netz zur Laufzeit, pytest als Build-Stufe. CI: nur bei Änderungen unter ApiCore-Whisper/, Tag sha-<commit>, trivy wenn im Runner vorhanden.
CronJob (vollständig, Widerspruch 10): Objekt-Label app: apicore-voice-job, Pod-Labels app: apicore-job, apicore.io/job: voice-transcribe, db-client: "true"; Werte aus Global Constraints; restartPolicy: Never, backoffLimit: 0, ttlSecondsAfterFinished: 86400, automountServiceAccountToken: false, Pod-securityContext wie die anderen Jobs; Volumes work (emptyDir: { medium: Memory, sizeLimit: 32Mi }) und tmp; initContainers: [fetch, whisper], containers: [ingest]; fetch/ingest: Backend-Image, node dist/cli.js voice-transcribe --phase=…, APICORE_ROLE=job, envFrom ConfigMap + apicore-backend-secret; whisper: Image apicore-whisper, kein env/envFrom außer WHISPER_CPU_THREADS, nur Volume work (ganzer Mount auf /work, Schreibrecht nötig für /work/out), readOnlyRootFilesystem, runAsNonRoot uid 1000, capabilities.drop: [ALL], seccompProfile: RuntimeDefault.
patch-worker-voice.yaml: Worker bekommt ANTHROPIC_API_KEY per secretKeyRef (apicore-anthropic, optional: true); kein anderer Pod.
manifest-policy.test.mjs neu: whisper container has no env from secrets, no secretKeyRef and no service account token; the voice pod matches the jobs network policy (egress only postgres and dns); work volume is a memory emptyDir of at most 32Mi; resources match spec 11.1; the voice CronJob is not matched by the shared job patch and has exactly fetch, whisper, ingest; ANTHROPIC_API_KEY appears only in the worker; apicore-whisper is pinned by digest in the overlay.
Schritt 1: Failing Tests: pytest writes an empty result for silence (NO_SPEECH), rejects audio longer than 240 seconds, rejects a corrupt file without crashing the batch, processes files one after the other and writes one result each, does not read the network (Socket-Sperre), writes segments with start, end and text; die Policy-Tests oben.
Schritt 2: FAIL. Schritt 3: Implementieren. Schritt 4: docker build lokal (falls Docker fehlt: CI-Lauf im Bericht vermerken), Policy-Tests und render-stages.mjs grün. Orchestrator committet feat: in-cluster voice transcription job and whisper image (T7 L3).

Lieferung L4 – Auswertung mit Claude

Task 14: Port, Anthropic-Adapter, Prompt, Schema, Prüfung

Files

Modify: ApiCore-Backend/package.json (@anthropic-ai/sdk exakt; vorher supply-chain-risk-auditor), src/common/no-network-outside-loops.spec.ts (Ausnahme Widerspruch 17)
Create: src/voice/extraction/structured-model.port.ts, anthropic-structured-model.ts, voice-prompt.ts, voice-schema.ts, validate-suggestions.ts, fake-structured-model.ts (Test-Hilfe) (+ Specs)
Test: voice-suggestions.spec.ts, voice-schema.spec.ts, voice-prompt.spec.ts, anthropic-structured-model.spec.ts (SDK gemockt)

Interfaces

export const STRUCTURED_MODEL = Symbol('STRUCTURED_MODEL');
export interface SystemBlock { text: string; cache?: '5m' | '1h' }
export interface TokenUsage { input: number; output: number; cacheRead: number; cacheWrite: number }
export interface StructuredRequest { model: string; system: readonly SystemBlock[]; userText: string; schema: object; maxTokens: number; timeoutMs: number; maxRetries: number; effort: 'low' }
export type StructuredOutcome =
  | { kind: 'ok'; data: unknown; usage: TokenUsage; model: string }
  | { kind: 'refused' | 'truncated'; usage: TokenUsage; model: string }
  | { kind: 'error'; code: 'AUTH' | 'RETRYABLE' | 'BAD_REQUEST' };
export interface StructuredModel { readonly configured: boolean; extract(request: StructuredRequest, signal?: AbortSignal): Promise<StructuredOutcome> }
// anthropic-structured-model.ts: client.messages.create({ model, max_tokens, system: blocks.map(b => ({ type: 'text', text: b.text, ...(b.cache ? { cache_control: { type: 'ephemeral', ttl: b.cache } } : {}) })),
//   messages: [{ role: 'user', content: userText }], output_config: { effort, format: { type: 'json_schema', schema } } }, { timeout, maxRetries, signal });
//   stop_reason 'refusal' -> refused, 'max_tokens' -> truncated, JSON-Parse-Fehler -> ok mit data = undefined (Prüfung verwirft); 401/403 -> AUTH; 429/5xx/Timeout/Netz -> RETRYABLE; 400 -> BAD_REQUEST.
//   baseURL nur aus der Umgebung (Standard des SDK), nie aus Daten; Logger des SDK aus.
// voice-prompt.ts
export const VOICE_PROMPT_VERSION = 1;
export function buildSystemBlocks(): SystemBlock[];     // Regeln 1–9 aus Spec 6.4, Fachwortliste, Skalen aus INSPECTION_SCALES, feedStatus-Anker aus FEED_CONDITION_LABELS_DE; fest, ohne Datum/Volk/Nutzer
export function buildUserText(transcript: string): string; // '<transkript>' + Text + '</transkript>', Text mit '<'/'>' entschärft
// voice-schema.ts
export const SUGGESTION_SCHEMA: object;                 // Spec 6.5, field-enum = INSPECTION_VOICE_FIELDS, kein minimum/maximum
// validate-suggestions.ts
export interface ValidatedSuggestions { suggestions: VoiceSuggestionView[]; unclear: string[]; dropped: number; truncated: number }
export function validateSuggestions(raw: unknown, transcript: string): ValidatedSuggestions | null; // null = Form passt nicht (EXTRACT_INVALID)

Schritt 1: Failing Tests: drops a finding whose quote is not in the transcript; drops a value outside the field's range; drops an unknown field; keeps one suggestion per field and notes the earlier value; matches the quote across punctuation and case; shortens long free text and marks it; never returns weather or temperature; returns null for a response that is not the schema shape; caps unclear at five and findings at twenty; schema field enum equals INSPECTION_VOICE_FIELDS; the system prompt contains no date, colony or user (Snapshot mit festen Platzhaltern); buildUserText neutralises angle brackets in the transcript; Adapter: sends output_config with effort low and the json schema, sends no tool_choice and no sampling parameters, maps refusal, max_tokens, 401 and 529, marks a system block for cache only when asked; Netzwerk-Wächter: @anthropic-ai/sdk is imported only by anthropic-structured-model.ts.
Schritt 2–4: FAIL → Implementieren → PASS. Bau-Notiz: aktuelle Anthropic-Doku zu output_config, Modellkennungen und fallbacks gegenlesen (claude-api-Skill); Abweichungen im Bericht, Code passt sich an, Spec bleibt Quelle der Absicht. Kein Commit.

Task 15: Worker-Schleife `voice-extractions`

Files

Create: src/voice/extraction/voice-extraction.service.ts (+ Spec), src/voice/voice-worker.module.ts (stellt STRUCTURED_MODEL → Anthropic-Adapter, Handler-Modul, Service bereit)
Modify: src/worker/worker-runtime.service.ts (+ Spec: Schleife), src/worker/worker.module.ts (importiert VoiceWorkerModule), src/runtime/startup-checks.ts (ruft assertAnthropicKey) – Hinweis: startup-checks.ts gehört in W2 Task 5; hier nur die eine Zeile, Welle 5 ist frei
Test: voice-extraction.service.spec.ts, worker-runtime.service.spec.ts, Erweiterung test/domain-event-registry-Spec (Handler im Worker registriert)

Interfaces

Schleife: { name: 'voice-extractions', intervalMs: 15_000, channel: WAKE_CHANNELS.voiceExtraction, tick: () => this.voiceExtraction.runOnce(this.stopping.signal) }.
VoiceExtractionService.runOnce(signal): Promise<void> = releaseStaleVoiceClaims('extract') + drain(signal); drain claimt je Runde 1, nacheinander, bis nichts mehr da oder signal abgebrochen.
Je Notiz: Schlüssel fehlt (configured === false) → beim Start einmal „voice extraction disabled“, Notizen bleiben TRANSCRIBED (deferVoiceClaim 1 h), lastErrorCode EXTRACT_DISABLED, Meldung an system:manage einmal; Tageslimit (count(*) heutiger UTC-Tag mit model IS NOT NULL) ≥ dailyExtractions → deferVoiceClaim bis Mitternacht UTC, DAILY_LIMIT; sonst openTranscript → extract (Modell aus voiceConfig, max_tokens 2000, 60 s, 2 Wiederholungen) → ok + validateSuggestions ≠ null → in einer Transaktion suggestionEnc = sealVoiceText(JSON, 'capture:<id>:suggestion'), model, Tokens, READY, readyAt, Ereignis VoiceCaptureReady (CAS); refused → FAILED/REFUSED + VoiceCaptureFailed; truncated/null → settleVoiceFailure(EXTRACT_INVALID); RETRYABLE → settleVoiceFailure(EXTRACT_RETRY), beim 3. Mal EXTRACT_FAILED; AUTH → wie Schlüssel fehlt.
Schritt 1: Failing Tests: stores READY and writes VoiceCaptureReady in one transaction; keeps TRANSCRIBED on 401 and notifies system:manage once; retries with the backoff and ends FAILED after three; handles refusal; respects the daily limit; a confirmed capture is not overwritten by a late extraction; never logs the transcript (Logger-Spion, auch im Fehlerpfad mit SDK-Fehler, der den Text in der Message hätte); the worker registers voice-extractions with the voice_extraction channel; voice handlers are registered in the worker.
Schritt 2–4: FAIL → Implementieren → PASS. Kein Commit.

Task 16: Aufräumen erweitert, Gold-Menge, Kostenanzeige

Files

Modify: src/jobs/cleanup.job.ts (+ Spec): ruft expireVoiceContent, deleteOldVoiceRows, löscht leere voice-transcribe-JobRuns > 24 h (Widerspruch 16), Zähler im JobResult (voiceAudioExpired, voiceContentExpired, voiceRowsDeleted, voiceIdleJobRuns)
Create: ApiCore-Backend/scripts/eval-voice.ts, test/fixtures/voice/gold/*.json (30 erfundene, anonyme Fälle: Transkript + erwartete Vorschläge), package.json Skript eval:voice
Test: voice-cleanup.spec.ts

Interfaces

eval:voice ruft den echten Adapter nur mit ANTHROPIC_API_KEY und --yes, misst je Modell: Genauigkeit Wahrheitswerte (Ziel ≥ 98 %), Trefferquote (≥ 85 %), Anzahl nicht gesagter Übernahmen (Ziel 0), Tokens und Kosten; nie in der CI (Wächter: kein Workflow ruft eval:voice).
Schritt 1: Failing Tests: deletes audio after 24 h; wipes content after 7 days and marks EXPIRED; deletes rows after 90 days; leaves open captures; deletes idle voice-transcribe job runs after a day and keeps runs with work or errors; no workflow runs eval:voice.
Schritt 2–4: FAIL → Implementieren → PASS. Orchestrator prüft L3+L4-Gates und committet feat: voice extraction with Claude structured output (T7 L4).

Lieferung L5 – Aufnahme, Warteschlange, Prüfen (Frontend)

Task 17: Recorder und Speicher `pending-voice`

Files

Create: ApiCore-Frontend/src/lib/voice/recorder.ts, pending-voice.ts (+ Specs)
Modify: ApiCore-Frontend/src/lib/offline/db.ts (+ db.spec.ts; Version = nächste freie, Widerspruch 11; Store pending-voice mit Index ownerUserId)

Interfaces

export interface Recording { blob: Blob; mime: string; durationSec: number }
export interface RecordingHandle { stop(): Promise<Recording>; cancel(): void }
export function pickMimeType(win?: Window): string | null;   // 'audio/webm;codecs=opus' | 'audio/mp4' | null
export function startRecording(opts: { maxSec: number; warnAtSec: number; onTick(sec: number): void; onWarn(): void; onAutoStop(r: Recording): void }): Promise<RecordingHandle>;
// getUserMedia({ audio: { channelCount: 1 } }) erst hier (Tipp), audioBitsPerSecond 24000, wakeLock wo vorhanden, visibilitychange -> stop und speichern, track.stop() bei stop/cancel
export interface StoredVoiceNote { id: string; ownerUserId: string; blob: Blob; mime: string; durationSec: number; colonyId: string; inspectionDate: string; createdAt: string; uploadIdempotencyKey: string; state: 'recorded' | 'uploading'; lastError?: QueueError }
export function queueVoiceNote(input: Omit<StoredVoiceNote, 'id' | 'createdAt' | 'uploadIdempotencyKey' | 'state'>): Promise<StoredVoiceNote>; // fragt beim ersten Mal navigator.storage.persist(); QuotaExceeded -> wirft VoiceStorageFullError
export function listPendingVoice(currentUserId: string): Promise<StoredVoiceNote[]>;
export function countForeignVoice(currentUserId: string): Promise<number>;
export function discardPendingVoice(id: string): Promise<void>;
export function discardAllPendingVoice(ownerUserId: string): Promise<number>;

Schritt 1: Failing Tests: upgrading to the new version keeps queued inspections, photos and phenology reports; stops at 180 seconds and keeps the recording; warns at 150 seconds; requests the microphone only on start and releases it on stop; saves what was recorded when the page goes to the background; rejects a new note when storage is full and keeps the stored ones; never lists another user's notes.
Schritt 2–4: FAIL → Implementieren → PASS. Kein Commit.

Task 18: Hochladen in der Synchronisierung, Warteschlangen-Sheet, Abmelden

Files

Create: ApiCore-Frontend/src/lib/voice/api.ts, upload-pending-voice.ts (+ Specs)
Modify: src/lib/offline/sync.ts (+ sync.spec.ts: Schritt „Sprachnotizen“ nach den Datensätzen und Fotos, innerhalb des Laufs, isCancelled beachtet), src/lib/offline/queue-texts.ts (+ Spec), src/components/offline/pending-queue-sheet.tsx (+ Spec: Abschnitt „Sprachnotizen“ mit „Erneut aufnehmen“ und „Verwerfen“, fremde nur als Anzahl), src/components/offline/offline-band.tsx (+ Spec: zählt Sprachnotizen mit), die Abmelde-Rückfrage (T3 Task 16, gleicher Weg) um wartende Aufnahmen

Interfaces

export const voiceKeys = { all: ['voice-captures'] as const, detail: (id: string) => ['voice-captures', id] as const, config: ['voice-captures', 'config'] as const };
export function uploadVoiceCapture(note: StoredVoiceNote): Promise<{ id: string; status: 'QUEUED' }>; // FormData audio + colonyId + inspectionDate + durationSec, Header Idempotency-Key = uploadIdempotencyKey
export function submitVoiceText(input: { colonyId: string; inspectionDate: string; text: string }, idempotencyKey: string): Promise<{ id: string }>;
export function fetchVoiceCaptures(status?: string): Promise<VoiceCaptureListItem[]>; export function fetchVoiceCapture(id: string): Promise<VoiceCaptureDetail>;
export function fetchVoiceConfig(): Promise<VoiceClientConfig>; export function retryVoiceCapture(id: string): Promise<void>;
export function discardVoiceCapture(id: string): Promise<void>; export function discardAllVoiceCaptures(): Promise<{ discarded: number }>;
export function uploadPendingVoice(userId: string, isCancelled: () => boolean): Promise<SyncResult>; // 2xx -> Eintrag sofort löschen; 4xx außer 401/408/409/429 -> lastError; Netz/5xx -> stoppen

Schritt 1: Failing Tests: uploads recorded voice notes after records; deletes the local audio after a 2xx; keeps 4xx rejections as lastError; stops on a network error and keeps the rest; never sends another user's recordings; a cancelled run sends no voice note; Sheet: shows a voice note with Erneut aufnehmen and Verwerfen, shows only the count of another account's notes; Band: counts voice notes in the waiting entries; Abmelden: asks to discard waiting recordings.
Schritt 2–4: FAIL → Implementieren → PASS. Kein Commit.

Task 19: Aufnahmeseite, Einstiege, Liste `/voice`

Files

Create: ApiCore-Frontend/src/app/(app)/voice/page.tsx, src/app/(app)/voice/new/page.tsx, src/components/voice/voice-recorder.tsx, recording-notice-dialog.tsx, voice-capture-card.tsx, src/lib/voice/status-texts.ts (+ Specs)
Modify: src/app/(app)/quick-actions.ts + quick-add-sheet.tsx (Eintrag „Sprachnotiz“, Mikrofon-Symbol, nur mit voice-captures:use und recordingEnabled), src/components/rounds/round-next-panel.tsx bzw. Standrunde (Knopf „Sprachnotiz aufnehmen“ neben „Durchsicht erfassen“), Volksseite (colonies/[id]/page.tsx, Knopf neben „Durchsicht“), src/app/(app)/nav-config.ts (+ Spec: „Sprachnotizen“ unter „Mehr“)
Test: voice-recorder.spec.tsx, voice/page.spec.tsx, voice/new/page.spec.tsx, quick-add-sheet.spec.tsx, nav-config.spec.ts

Interfaces

/voice/new?colonyId=&date=&apiaryId=: Kopf „B3 · 14.10.“ (änderbar über ColonySelectField/Datum), Satz „Sprich in ganzen Sätzen, nur du.“, Gedächtnisstütze (Königin · Stifte · Brut · Waben · Sanftmut · Futter · Honigraum · Varroa · Maßnahmen), Aufnahmetaste 72 px mit Text „Aufnahme starten“ → „Aufnahme beenden“ am selben Ort; während der Aufnahme rote Markierung und „Aufnahme läuft“ plus Zeit; Ansage nur alle 30 s und beim Stopp (aria-live="polite"); kein Pulsieren bei prefers-reduced-motion; nach Stopp native Wiedergabe, Hauptaktion „Senden“ (offline „Speichern“), „Neu aufnehmen“, „Verwerfen“; Erfolgstexte exakt Spec 8.1; „Weiter mit B4“ in der Standrunde; Mikrofon verweigert: Schritt-für-Schritt je Browser und „Stattdessen tippen“; erster Start: RecordingNoticeDialog mit Spec-9.5-Text.
/voice: Karten (Volk, Zeit, Status mit Symbol und Wort aus VOICE_STATUS_TEXTS_DE: „Wartet auf Netz“, „Wird abgeschrieben“, „Wird ausgewertet“, „Fertig – prüfen“, „Fehlgeschlagen“), Hauptaktion „Prüfen“ → /inspections/new?colonyId=…&date=…&voice=<id>, unter „Mehr“ „Verwerfen“ (Rückfrage), „Nochmal versuchen“ bei FAILED mit Inhalt; wartende Geräte-Einträge oben; Leerzustand „Noch keine Sprachnotizen.“
Schritt 1: Failing Tests: shows words and not just color while recording; announces the time only every 30 seconds; shows the denied-state with a way to type instead; offline the main action reads Speichern and the note lands in the queue; shows the notice once before the first recording; the list shows status words and Prüfen only when ready; the quick-add entry is hidden without permission or when recording is disabled; axe finds nothing (Aufnahme und Liste).
Schritt 2–4: FAIL → Implementieren → PASS. Kein Commit.

Task 20: Vorschläge in der Durchsicht, Übernehmen, Speichern mit `voiceCaptureId`

Files

Create: ApiCore-Frontend/src/components/voice/voice-suggestion.tsx, voice-capture-box.tsx, src/lib/voice/suggestions.ts, src/lib/inspections/scales.ts (+ Specs)
Modify: src/app/(app)/inspections/new/page.tsx (+ page.spec.tsx), inspection-form-values.ts (+ Spec: Markierung „aus Sprache“ je Feld, voiceCaptureId im Input, nicht im Entwurf), src/lib/inspections/types.ts (CreateInspectionInput.voiceCaptureId?: string), src/lib/offline/sync.ts nicht (409-Weg siehe unten über useCaptureMutation)
Test: voice-suggestion.spec.tsx, voice-capture-box.spec.tsx, suggestions.spec.ts, scales.spec.ts, page.spec.tsx

Interfaces

// suggestions.ts
export function suggestionPatch(s: VoiceSuggestionView): Partial<InspectionFormValues>; // feedStatus -> ColonyCondition, Skalen gespeichert, Freitext angehängt an leere/vorhandene Felder nach Formular-Regel
export function describeSuggestionValue(s: VoiceSuggestionView): string; // „Königin gesehen: Ja“, „Futter: Niedrig“, „Sanftmut: 4 von 5“
export function openSuggestions(all: VoiceSuggestionView[], values: InspectionFormValues, taken: ReadonlySet<string>): VoiceSuggestionView[];
// scales.ts
export const INSPECTION_SCALE_DIRECTIONS: Record<'broodPattern' | 'swarmMood' | 'gentleness' | 'combBehavior', RatingDirection>; // Formular nutzt sie; Wächter gegen test/fixtures/voice/inspection-scales.json

<VoiceSuggestion fieldLabel valueText quote chips onTakeOver onEdit /> (generisch, Teil 4): Wert in Worten, Zitat in Anführungszeichen, „Übernehmen“, „Ändern“, Chips „Korrigiert“/„Zuvor genannt: …“; Enter auf „Übernehmen“ setzt den Wert, meldet „Übernommen“ in einem role="status"-Bereich, Fokus bleibt; „Ändern“ setzt und fokussiert das Feld.
<VoiceCaptureBox capture onTakeOverAll onDiscard />: „Sprachnotiz vom 14.10., 12 Vorschläge“, „Alle übernehmen“ mit Rückfrage „12 Felder aus der Sprachnotiz übernehmen?“, „Sprachnotiz verwerfen“ (Rückfrage), aufklappbar „Gesagt wurde:“ mit vollem Text (kopierbar), unclear als „Das konnte ich nicht zuordnen“ ohne Knopf, dropped > 0 und leer: „Nichts Eindeutiges erkannt. Der Text steht oben.“; Status ≠ READY: passende Zeile („Wird noch ausgewertet“, „Auswertung gerade nicht möglich“ + Text).
Seite: ?voice=<id> lädt fetchVoiceCapture, setzt Volk und Datum der Notiz, kein Feld belegt; Hinweise unter jedem Feld mit Vorschlag, unter dem „Letztes Mal“-Hinweis mit klarer Beschriftung; übernommene Felder bleiben „aus Sprache“, bis bearbeitet oder gespeichert; Speichern schickt voiceCaptureId; offline gespeichert geht die Id mit in die Warteschlange; Antwort 409 VOICE_CAPTURE_GONE (online oder beim Sync) → genau ein erneuter Versuch ohne voiceCaptureId mit denselben Eingaben und neuem Idempotency-Key, Hinweis „Sprachnotiz war abgelaufen, Durchsicht ohne sie gespeichert“; 409 VOICE_CAPTURE_COLONY_MISMATCH → Fehlertext, nichts gespeichert, Angebot „Ohne Sprachnotiz speichern“. Nach Erfolg voiceKeys.all invalidieren.
Sync-Seite des 409-Wegs: drain für pending-inspections bekommt einen Hook retryWithout(entry, error) (kleine Erweiterung in sync.ts) – Dateikonflikt mit Task 18: läuft in W7 nach W6, also zulässig; Test a queued inspection with an expired voice capture is saved without it.
Schritt 1: Failing Tests: leaves the field empty until Übernehmen; Übernehmen sets the value and moves no focus; Ändern focuses the field; Alle übernehmen asks first and names the count; works with the keyboard only; axe finds nothing; saves with voiceCaptureId and shows no suggestion afterwards; a 409 VOICE_CAPTURE_GONE retries without the id; a queued inspection with an expired voice capture is saved without it; both hints stand one below the other and neither fills the field; scale directions equal the shared fixture; suggestion text is rendered as text, never as HTML.
Schritt 2–4: FAIL → Implementieren → PASS. Kein Commit.

Task 21: Text-Weg „Ganze Durchsicht auswerten“

Files

Create: ApiCore-Frontend/src/components/voice/evaluate-dictation-button.tsx (+ Spec)
Modify: src/app/(app)/inspections/new/page.tsx (unter den Freitextfeldern; Zustand „mindestens ein Diktat“ aus useDictation gemeldet), nach Task 20 in derselben Welle

Interfaces

Sichtbar nur online und wenn mindestens ein Diktat vorliegt; schickt die diktierten Texte zusammen (≥ 20, ≤ 4000 Zeichen, sonst Hinweis) an submitVoiceText, zeigt danach den Zustand der Notiz in VoiceCaptureBox (Abfrage alle 5 s bis READY/FAILED, höchstens 2 min, dann Hinweis auf die Meldung) und Vorschläge nur für leere Felder (Spec 8.3).
Schritt 1: Failing Tests: is hidden offline and without dictation; sends the dictated text once with an idempotency key; offers suggestions only for empty fields; stops polling after two minutes and points to the notification.
Schritt 2–4: FAIL → Implementieren → PASS. Kein Commit.

Task 22: Info-Seite vervollständigen, System-Zähler

Files

Modify: ApiCore-Frontend/src/app/(app)/settings/voice/page.tsx (+ Spec: Modellkennung aus fetchVoiceConfig, „Alle meine Sprachnotizen löschen“ → discardAllVoiceCaptures + discardAllPendingVoice, Rückfrage mit Anzahl), src/app/(app)/settings/system/… (+ Spec: Karte „Sprachnotizen“ mit Zählern je Status/Fehlercode und Monatskosten aus Tokens × Preis aus einer Tabelle VOICE_MODEL_PRICES_USD in lib/voice/prices.ts, nur mit system:manage), src/lib/system/labels.ts (+ Spec: DOMAIN_EVENT_LABELS für VoiceCaptureReady „Sprachnotiz fertig“, VoiceCaptureFailed „Sprachnotiz fehlgeschlagen“; Job-Label), public/sw-routes.js + public/sw.js (SW_ROUTES_VERSION) + src/lib/offline/sw-routes.spec.ts (/api/v1/voice-captures nie gecacht)
Schritt 1: Failing Tests: shows the model id from the server; delete all asks with the count and empties server and device; the system card shows counts without user names; voice-captures paths are never cached by the service worker; labels exist for both voice events.
Schritt 2–4: FAIL → Implementieren → PASS.
Schritt 5: Browser-Prüfung (chrome-devtools-MCP, lokales Backend mit FakeStructuredModel über VOICE_FAKE_MODEL=1 nur außerhalb Produktion, Ersatz-Whisper per Testdatei): 390 px und 1366 px, Flugmodus-Aufnahme → Netz an → Meldung → Prüfen → Speichern; Tastatur und Screenreader-Namen der Prüfansicht; prefers-reduced-motion; Leer- und Fehlerzustände. Orchestrator committet feat: voice notes recording, queue and suggestion review (T7 L5).

Lieferung L6 – Ende-zu-Ende, Messung, Doku

Task 23: e2e gegen die Test-DB

Files

Create: ApiCore-Backend/test/voice-captures.e2e-spec.ts
Modify: test/authorization-coverage.e2e-spec.ts (läuft grün mit den neuen Routen)
Schritt 1: e2e schreiben (Spec 12): Upload → QUEUED; fetch-Phase direkt aufgerufen → Datei im Arbeitsverzeichnis (Temp-Verzeichnis); Ersatz-Whisper schreibt WhisperResult → ingest → TRANSCRIBED, Audio-Zeile weg; Schleife mit FakeStructuredModel → READY und genau eine Meldung nach drainDomainEvents; POST /inspections mit voiceCaptureId → CONFIRMED, transcriptEnc und suggestionEnc null, Audio weg; fremder Nutzer 404; READONLY und API_CLIENT 403; zwei parallele fetch-Läufe → jede Aufnahme genau einmal; Text-Weg → TRANSCRIBED → READY; Log-Mitschnitt über den ganzen Lauf enthält den Text nicht.
Schritt 2: npx jest --config ./test/jest-e2e.json test/voice-captures.e2e-spec.ts --runInBand → PASS (Code reparieren, nicht Tests). Danach alle e2e mit --runInBand.

Task 24: Messung vor der Freigabe (mit Freigabe des Inhabers)

Schritt 1: Spec 11.4 Punkt 1–2 auf dem Zielknoten: 10 Aufnahmen des Inhabers (30–180 s, Standumgebung), Laufzeit, Spitzen-RAM, CPU-Drosselung, Fachwort-Trefferquote (Ziel ≥ 90 %); Ergebnis in progress.md. Darunter: Fachwortliste erweitern oder medium (Request 2Gi) nur nach Freigabe.
Schritt 2: npm run eval:voice -- --yes (kostet Geld, nur nach Freigabe) mit claude-sonnet-5-5; nur wenn Kosten Thema werden zusätzlich claude-haiku-5-5; verfehlt Sonnet die Ziele → VOICE_MODEL=claude-opus-5-5 vorschlagen. Ergebnis in progress.md.

Task 25: Abschluss und Rollout (Orchestrator)

Schritt 1: Alle Gates Backend, Frontend, Manifeste, Whisper-CI; code-simplifier auf den geänderten Code; Gesamt-Diff-Review (Sicherheitsblick: Logs, Rechte, Netz).
Schritt 2: Doku im selben Commit: ARCHITECTURE nächste freie Annahmen „Sprachnotizen und Datenschutz“, „Abschreiben im Cluster“, „Auswertung mit Claude (Schema und Prüfung)“; §1 Modul voice; §7 Komponente voice, Pod-Aufbau, Secret apicore-anthropic; §10 Schleife voice-extractions, Wake-Kanal, Ereignisse; docs/pruefung-2026-09.md „Sprachdaten“; TASKS.md: „Sprache, KI und Sensoren nicht umsetzbar“ für Sprache und KI korrigiert, Sensoren „nicht geplant, kein Gerät“.
Schritt 3: Rollout (jeder Schritt mit Freigabe, kubectl diff -k vorher): 0. Inhaber: Anthropic-Schlüssel, Ausgabenlimit (Vorschlag 10 $/Monat), DPA, Datenschutzerklärung; ensure-secrets.sh ergänzt VOICE_ENCRYPTION_KEY (vor Schritt 1, Widerspruch 8); Inhaber legt apicore-anthropic an. 1. Backend-Image mit Migration (VOICE_RECORDING_ENABLED=false, Auswertung ohne Schlüssel aus). 2. apicore-whisper bauen, Digest ins Overlay. 3. Komponente voice einschalten; erster Lauf kubectl create job --from=cronjob/apicore-job-voice-transcribe; Logs auf Inhalte prüfen (keine). 4. Messung Task 24. 5. VOICE_RECORDING_ENABLED=true, Frontend freigeben.
Schritt 4: Rückweg dokumentiert: VOICE_RECORDING_ENABLED=false, Komponente voice aus; offene Notizen laufen über expireVoiceContent ab.

Abdeckung der Spec

Spec-Abschnitt	Tasks
1 Messkriterien 1–5	1: 7, 11, 15, 18, 23 · 2: 14, 20 · 3: 8, 23 · 4: 7, 11, 13, 15 · 5: 6, 14
1 Entscheidungen	5 (Schlüssel), 10–13 (CronJob), 14–15 (Claude, Schema, Zitat), 20 (nie still), 7 (nur Aufnehmender), 11/16 (Fristen), 4 (Backup), 1–2 (Browser-Erkennung)
2.1 Bausteine	Stufe 1: 1–3 · Aufnahme/Warteschlange: 17–19 · Abschreiben: 10–13 · Auswerten: 14–15 · Text-Weg: 7, 21 · Prüf-UI: 20 · Liste: 19 · Datenschutz: 3, 5, 16, 22
3 Datenmodell, Schlüssel, Rechte, Ereignisse, Backup	4, 5, 8, 9
4 Zustände, Jobs, Schleifen	10, 11, 13, 15, 16
5 API, Eingaben	7, 8 (+ `config`, `discard-all`)
6.1–6.2 Gerät, Diktat	1, 2, 17, 18
6.3 Abschreiben	11, 12, 13
6.4–6.5 Claude, Schema, Prüfung	14, 15
6.6 Übernehmen und Speichern	8, 20
7 Modell, Kosten, Protokoll ohne Inhalt	5, 15, 16, 22, 24
8 Oberfläche	2, 3, 19, 20, 21, 22
9 Sicherheit und Datenschutz	Global Constraints; 4, 5, 7, 13, 14, 15, 16, 22
10 Fehlerfälle	Codes in 6; Verhalten in 7, 8, 11, 15, 18, 19, 20
11 Betrieb und Ressourcen	13, 15, 24
12 Tests	in den Tasks benannt; e2e 23
14 Rollout	25

Offene Fragen an den Inhaber (zusätzlich zu Spec 15)

A1 Widerspruch 14: Soll das Speichern einer Durchsicht eine Sprachnotiz in jedem offenen Zustand (nicht nur „Fertig“) bestätigen und ihren Inhalt löschen? Empfehlung: ja.
A2 Widerspruch 1: colonyStrength und broodFrames bis 40 (wie das Formular) statt 30, Futter in fünf Stufen statt drei? Empfehlung: ja, das Formular ist die Quelle.
A3 Meldungskategorie der Sprachnotiz SUGGESTION (Telegram nur, wenn gewählt) – oder lieber SYSTEM? Empfehlung: SUGGESTION.
Spec-Fragen 1–3 (Modell, Browser-Cloud, Drittland) bleiben offen; der Bau ändert sich nur bei Frage 3 (ohne Anthropic entfallen Tasks 14–16 und 21).

83 KiB Raw Blame History Unescape Escape

T7 „Freihand“ (Spracherfassung) Implementation Plan

Spec-Widersprüche zum Code (geprüft am 2026-10-16, HEAD b73da4d8) und Auflösung

Global Constraints

Review Focus

Anschluss Teil 4 (was T7 so schneidet, dass Teil 4 es nur erweitert)

Abhängigkeiten und Wellen

Lieferung L1 – Stufe 1 „Diktat“ (nur Frontend, kann vor allem anderen live)

Task 1: Spracherkennungs-Kapsel und Einwilligung

Task 2: Diktat-Knopf an den Freitextfeldern

Task 3: Seite „Sprache & Datenschutz“ (Grundstock)

Lieferung L2 – Datenmodell, Schlüssel, API, Übernahme (Backend)

Task 4: Schema, Migration, Recht, Sperre, Backup-Ausnahme, Wächter

Task 5: Schlüsselbund-Zweck voice, Verschlüsselungs-Hilfen, Startprüfungen

Task 6: Gemeinsamer Kern (Text, Zitat, Felder, Transkript, Fachwörter, Skalen)

Task 7: Sprachnotizen-API (Upload, Text, Liste, Abruf, Wiederholen, Verwerfen, Konfiguration, Zähler)

Task 8: Übernahme in POST /inspections

Task 9: Ereignisse, Handler, Meldungen

Lieferung L3 – Abschreiben im Cluster

Task 10: Wiederholregel und Voice-Claims

Task 11: Job voice-transcribe (Phasen fetch und ingest) und Aufbewahrung im Takt

Task 12: Fachwortliste für Whisper exportieren (Brücke Node → Python)

Task 13: Image apicore-whisper, CronJob-Komponente voice, Policy-Tests

Lieferung L4 – Auswertung mit Claude

Task 14: Port, Anthropic-Adapter, Prompt, Schema, Prüfung

Task 15: Worker-Schleife voice-extractions

Task 16: Aufräumen erweitert, Gold-Menge, Kostenanzeige

Lieferung L5 – Aufnahme, Warteschlange, Prüfen (Frontend)

Task 17: Recorder und Speicher pending-voice

Task 18: Hochladen in der Synchronisierung, Warteschlangen-Sheet, Abmelden

Task 19: Aufnahmeseite, Einstiege, Liste /voice

Task 20: Vorschläge in der Durchsicht, Übernehmen, Speichern mit voiceCaptureId

Task 21: Text-Weg „Ganze Durchsicht auswerten“

Task 22: Info-Seite vervollständigen, System-Zähler

Lieferung L6 – Ende-zu-Ende, Messung, Doku

Task 23: e2e gegen die Test-DB

Task 24: Messung vor der Freigabe (mit Freigabe des Inhabers)

Task 25: Abschluss und Rollout (Orchestrator)

Abdeckung der Spec

Offene Fragen an den Inhaber (zusätzlich zu Spec 15)

83 KiB

Raw Blame History

Spec-Widersprüche zum Code (geprüft am 2026-10-16, HEAD `b73da4d8`) und Auflösung

Task 5: Schlüsselbund-Zweck `voice`, Verschlüsselungs-Hilfen, Startprüfungen

Task 8: Übernahme in `POST /inspections`

Task 11: Job `voice-transcribe` (Phasen `fetch` und `ingest`) und Aufbewahrung im Takt

Task 13: Image `apicore-whisper`, CronJob-Komponente `voice`, Policy-Tests

Task 15: Worker-Schleife `voice-extractions`

Task 17: Recorder und Speicher `pending-voice`

Task 19: Aufnahmeseite, Einstiege, Liste `/voice`

Task 20: Vorschläge in der Durchsicht, Übernehmen, Speichern mit `voiceCaptureId`