archivdms/internal/storage/migrations

Migrations-Konvention

archivdms verwendet, wie archivmail, kein externes Migrationstool. Das tatsächliche Schema wird idempotent zur Laufzeit von initSchema()-Funktionen in den jeweiligen Store-Paketen angelegt/erweitert (CREATE TABLE IF NOT EXISTS, ALTER TABLE ... ADD COLUMN IF NOT EXISTS, CREATE INDEX IF NOT EXISTS). Das ist sicher gegen mehrfaches Ausführen und gegen bereits existierende Produktiv-Datenbanken.

Dieses Verzeichnis dokumentiert trotzdem jede Schemaänderung als nummerierte NNN_name.sql-Datei — rein informativ/Doku, nicht ausführbar über ein Migrationstool. Sie dient als:

• lesbare Historie, welche Änderung wann und warum kam
• Referenz für DBAs, die das Schema manuell nachvollziehen wollen
• Grundlage für Code-Review von Schemaänderungen (PR zeigt sowohl den Go-Diff in initSchema() als auch die dazugehörige NNN_name.sql-Doku)

Regeln

1. Jede neue Migration bekommt eine fortlaufende Nummer (001, 002, ...).
2. Der Dateiname beschreibt die Änderung kurz (002_add_reminders.sql).
3. Der SQL-Inhalt muss exakt dem entsprechen, was initSchema() (oder das jeweilige Store-Paket) zur Laufzeit ausführt.
4. Migrationen werden nie verändert oder gelöscht, nur ergänzt.
5. Zu jeder neuen Migration gehört eine Down-Datei NNN_name.down.sql (siehe Abschnitt „Rollback-Pfad").

Rollback-Pfad (NNN_name.down.sql)

initSchema() ist ausschließlich vorwärtsgerichtet — es gibt bewusst keinen automatischen Rollback-Runner (kein Migrationstool, kein Zustandstabellen- Tracking). Für den Ernstfall (fehlerhaftes Release, Rückbau eines Features) braucht es trotzdem ein reviewtes Rückbau-SQL. Deshalb gilt ab FDN-02:

Jede neue NNN_name.sql bekommt eine gleichnamige NNN_name.down.sql mit dem exakten Rückbau der Vorwärts-Migration. Separate Datei statt -- DOWN-Abschnitt in derselben Datei, weil Regel 4 („Migrationen werden nie verändert") sonst verletzt würde und weil sich eine Down-Datei fehlerfrei per psql -f einspielen lässt, ohne vorher Abschnitte herauszuschneiden.

Anforderungen an eine Down-Datei:

1. Header-Kommentar mit Bezug auf die Vorwärts-Migration und der zugehörigen PROJ-/Ticket-Nummer.
2. Precondition benennen: welche Go-Stelle (initSchema, Store-Datei, aufrufende Queries) vorher entfernt bzw. deployt sein muss. Sonst legt der nächste Prozessstart das Objekt sofort wieder an.
3. Datenverlust explizit benennen — was ist danach unwiederbringlich weg, was ist regenerierbar (z.B. abgeleitete Indizes wie ocr_words).
4. WORM/GoBD-Hinweis: klarstellen, dass kein archiviertes File unter store/ und kein retain_until berührt wird. Down-SQL darf niemals Dokument-Nutzdaten oder Aufbewahrungssperren löschen.
5. Idempotent formulieren (DROP ... IF EXISTS) und in BEGIN; ... COMMIT; klammern.

Ausführung ist immer manuell und bewusst (psql -f internal/storage/migrations/NNN_name.down.sql), nie automatisch beim Start.

Beispiele (rückwirkend ergänzt, dienen als Vorlage): 024_ocr_words.down.sql, 025_document_date_score.down.sql, 026_accounting_api_keys.down.sql. Ältere Migrationen (001–023) haben keine Down-Datei — sie beschreiben das etablierte Kernschema, dessen Rückbau kein realistisches Szenario ist.

Vorhandene Migrationen

• 001_initial.sql — tenants, users, token_blacklist, documents, audit_log
• 002_reminders.sql — reminders (Wiedervorlage)
• 003_documents_unique_hash.sql — UNIQUE INDEX (tenant_id, content_hash) auf documents (DB-seitiger Duplikatschutz für die Upload-Pipeline)
• 004_sftp_credentials.sql — sftp_credentials (per-Mandant SFTP-Zugangsdaten für den eingebetteten SFTP-Server, internal/sftpserver)
• 005_taxonomy.sql — tags/document_types/correspondents/document_tags (strukturierte Entitäten mit Matching-Algorithmus + Barcode-Wert) plus documents.doc_type_id/correspondent_id/barcode_values-ALTER
• 006_custom_fields.sql — custom_field_defs/document_type_fields/document_field_values (benutzerdefinierte Felder pro Mandant/Dokumenttyp/Dokument)
• 007_trash.sql — Papierkorb + gestaffeltes Löschkonzept: documents.deleted_at/deleted_by-ALTER (Soft-Delete) plus document_delete_requests (Vier-Augen-Workflow für finales WORM-Löschen, Retention-Prüfung, Tombstone)
• 011_classification_templates.sql — classification_templates/classification_template_tags/classification_template_field_defaults (Klassifizierungsvorlagen: benannte Bündel aus Dokumenttyp/Tags/Custom-Field-Defaults/Aufbewahrungsdauer, anwendbar per Preview+Commit; keine persistente Kopplung an documents, Retention nur verlängerbar)
• 021_title_template.sql — classification_templates.title_template-ALTER + tenants.default_title_template-ALTER (Titel-Vorlage pro Klassifizierungsvorlage mit tenant-weitem Default-Fallback; Go-text/template-Rendering in classification_templates_title.go, angewendet in ApplyTemplate für manuellen Endpoint UND Workflow-Trigger; setzt Titel nur wenn title_manually_set=false und lässt das Flag false)
• 022_retention_rules.sql — retention_rules (GoBD-Aufbewahrungsregeln / "Disposition Schedules" pro Dokumenttyp bzw. tenant-weiter Default mit doc_type_id IS NULL): trigger_type (document_date/upload_date/fixed_date/event) + retention_years/days berechnen documents.retain_until über den Batch-Job archivdms retention apply (initRetentionRulesSchema/ApplyRetentionRules). Setzt nur retain_until (WORM-Sperre), löscht nie und verkürzt nie; die Vernichtung läuft weiter über 007_trash.sql. event-Regeln werden nicht auto-berechnet (künftiger Erweiterungspunkt)
• 024_ocr_words.sql — ocr_words (word-level OCR bounding boxes per Dokument, Phase 2 des Text-Highlight/Overlay-Features, internal/storage/ocr_words.go/initOCRWordsSchema): document_id FK ON DELETE CASCADE, kein tenant_id (immer über document_id mediiert), ReplaceOCRWords löscht+re-inserted atomar bei jedem (Re-)OCR-Lauf (Upload-Job, /reprocess-Endpoint, documents reprocess-all CLI), damit kein Duplikat-Anhäufen entsteht
• 025_document_date_score.sql — documents.document_date_score (NUMERIC, nullable, kein Backfill): persistiert die Konfidenz (0.4-0.9 automatische Keyword-Proximity-Heuristik, 1.0 = manuell bestätigt/überschrieben via PUT /api/documents/{id}/document-date) der bereits vorhandenen document_date-Erkennung, vorbereitend für die geplante Buchhaltungs-Pull-API (Score >= 0.75 als Pull-Filter)
• 020_ml_classifier.sql — ml_classifier_tokens/ml_classifier_classes/ml_classifier_runs (Naive-Bayes-Retraining-Klassifizierung Phase 1, ergänzt die Regel-Engine) plus document_tags.assigned_via/documents.doc_type_assigned_via/documents.correspondent_assigned_via-ALTER (Provenienz: manual/rule/ml_accepted, Default manual zum Schutz bestehender Trainingsdaten)