Caja — Pflichtenheft: Übersicht & Management-Summary#

Dieses Dokument ist die Einstiegsseite des Pflichtenhefts. Es gibt Kontext, orientiert im Gesamtsystem, verlinkt auf alle Fachkapitel und hält die verbindlichen Entscheidungen fest. Alle nachgelagerten Kapitel bauen auf diesem Fundament auf. Letzte Aktualisierung: 2026-06-26.

1. Vision & Management-Summary#

Caja (ES: Box und Kasse) ist die dedizierte All-in-One-Backend-Plattform der Dominicano Express GmbH — einem Schweizer Familienunternehmen, das seit 2026 See-Fracht zwischen der Schweiz und der Dominikanischen Republik betreibt.

Das Problem heute#

Das operative Geschäft wird über eine Kombination aus einem Excel-ERP (Erfassung_Digitar, ERP_DASHBOARD FULL.xlsx), manuellen WhatsApp-Chats, Papierformularen am Depot und verstreuten Insellösungen abgewickelt. Konsequenzen:

• Finanzbuchungen entstehen manuell, mit Zeitverzug und Fehlerrisiko
• Kundenstamm ist dezentral; Duplikate sind die Regel
• Box-Tracking und Container-Status sind nur im Kopf oder auf Papier
• Affiliate-Provisionen werden nachträglich manuell ausgerechnet
• MWST-Scharfschaltung würde heute einen Systemwechsel erzwingen

Die Lösung: Caja#

Eine App ersetzt alle Insellösungen. Der entscheidende Kerngewinn: operative Events erzeugen die Finanzbuchungen automatisch — statt Excel-Zeilen manuell nachzupflegen. Das Prinzip zieht sich durch den gesamten Fluss:

Team & Rollen#

Externe Affiliates und ein optionaler Read-only-Zugang (z. B. Treuhänder) sind in Phase 2 vorgesehen.

2. Durchgängiger Fluss#

Alle 8 Fachmodule sind durch einen einzigen, durchgängigen Datenfluss verbunden. Kein Modul ist eine Insel.

Diagramm wird geladen …

Geteilte Kern-Entitäten (modulübergreifend)#

Diese Tabellen existieren einmal und werden von allen Modulen referenziert. Änderungen an ihnen haben modulübergreifende Konsequenzen.

Kanonisches Schema (DDL, alle 48 Tabellen, Konflikt-Auflösungen K-01..K-21): Dokument 30 — Schema konsolidiert

3. Die 8 Fachmodule#

Design-System & Mobile-Patterns#

Das Design-System ist kein eigenes Fachmodul, aber ein verbindliches Querschnittskapitel, das alle anderen Module beeinflusst.

Querschnitts-Kapitel#

4. Tech-Stack ("Atlas")#

Der Stack ist fix und abgeleitet vom internen Atlas-Projekt (atlas.zvv.dev). Er ist nicht verhandelbar — alle Modulspezifikationen gehen von diesem Stack aus.

Core#

UI-Konventionen (Atlas-Muster)#

• Sidebar (Desktop/Tablet) + Command-Palette (⌘K) — globale Navigation und Schnellsuche
• KPI-Kacheln — Dashboard-Einstieg jedes Moduls
• Action-State-Forms + Toasts — Formular-Feedback ohne Page-Reload
• Empty-States + Skeletons — kein leeres Weiss, kein FOUC
• Light / Dark via Design-Tokens (CSS Custom Properties) — systemseitig oder manuell wählbar

Monorepo-Struktur (Soll-Zustand)#

dominicanoexpress.com/          ← Privates Familien-GmbH-Repo
├── apps/
│   ├── web/                    ← LIVE: statische Website (nicht anfassen)
│   ├── cajaspec/               ← DIESE Spec-Site (cajaspec.dominicanoexpress.com)
│   └── caja/                   ← NEU: die App (Next.js App Router, caja.dominicanoexpress)
├── packages/
│   ├── db/                     ← @caja/db: Supabase-Clients, Typen, Query-Helfer, RLS
│   ├── ui/                     ← @caja/ui: geteilte shadcn-Komponenten
│   ├── i18n/                   ← @caja/i18n: Locale-Loading, Type-safe Keys
│   └── config/                 ← @caja/config: ESLint, TSConfig, Tailwind-Preset
└── dokumente/                  ← gitignored (sensibel → SharePoint)

Details: Dokument 20 — Technische Architektur

5. Mobile/Tablet-First — Harte Kern-Pflicht#

Mobile/Tablet-First ist keine Responsive-Nachbesserung, sondern eine strukturelle Entscheidung, die jede Layout-, Navigations- und Datenbankdesign-Entscheidung beeinflusst.

Warum#

Das Feldteam (Arkys am Depot, Markus am Container-Terminal) arbeitet ausschliesslich auf Handy oder Tablet. Mariela arbeitet im Büro vorwiegend auf Tablet. Marcel hat als einziger einen regulären Desktop-Kontext.

Verbindliche Regeln#

Details: Dokument 18 — Design-System & Mobile-Patterns

6. Dreisprachigkeit DE / ES / EN#

Caja ist vollständig dreisprachig. Die Sprache ist nie in der Logik verdrahtet — interne Fachcodes (IDs, source_type, Rollen-Codes, Status-Werte) sind die Wahrheit; DE/ES/EN sind Anzeige-Schichten.

7. Fixe Entscheidungen#

Diese Entscheidungen sind abgeschlossen und werden in den Modul-Specs als gegeben behandelt. Sie werden hier nicht mehr zur Diskussion gestellt.

8. Roadmap-Phasen (Übersicht)#

Umsetzung als 4-Wochen-Plan bis Go-Live 25.07.2026 (parallelisiert, KI-gestützt aus der Spec — s. 40-roadmap.md mit Mermaid-Timeline). Die sequentielle Schätzung (~18–22 Wochen) bleibt die fachliche Aufschlüsselung der Phasen.

Details: Dokument 40 — Roadmap

9. Compliance-Rahmen (Kurzübersicht)#

Vollständige Matrix: Dokument 45 — Compliance & Sicherheit

10. 🔲 Zu bestätigen — Index#

Alle offenen Geschäftsentscheide und Klärungspunkte, die die Implementierung blockieren könnten. Technische Lücken/Widersprüche sind in Dokument 99 — Offene Punkte separat geführt.

11. Lesereihenfolge#

Empfohlene Reihenfolge für Erstleser:

1. Dieses Dokument (00-overview.md) — Gesamtüberblick, Fluss, Entscheidungen
2. 05-legacy-ist.md — IST-Kontext: was das Alt-ERP fachlich kann (Anforderungsbasis)
3. 20-architektur.md — wie alles technisch verdrahtet ist (Monorepo, RLS, i18n, Auto-Posting)
4. 30-schema-konsolidiert.md — die einzige Wahrheitsquelle des Datenmodells
5. 10-crm.md → 11-whatsapp-ocr.md — Einstiegspunkte des Flusses
6. 12-produkte-preise.md → 13-offerten.md — kommerzieller Zyklus
7. 14-logistik-tracking.md — operativer Kernfluss
8. 15-finanzen.md — Ledger + Auto-Posting
9. 16-affiliate.md — Provisions-Layer
10. 17-plattform.md — Auth, RLS, i18n, Audit, Notifications
11. 18-design-mobile.md — Design-System, Mobile-Patterns
12. 40-roadmap.md — Phasen und Prioritäten
13. 45-compliance.md — rechtliche Anforderungen
14. 50-us-logistik.md ff. — User Stories (Connextra + Gherkin) je Epic
15. 99-offene-punkte.md — technische Lücken (vor Implementierung lesen!)