Commerce & Finance Domain (schema: commerce)

The conversion and accounting engine, focused on B2C/B2B sales, capacity holds, cross-border manifest data, and generalized taxation logic based on actuals.

→ Hub: See domain-model.md for the bounded context map and cross-boundary integration surface.

---

Entity Relationship Diagram

100%

Cross-context references (soft FKs, not shown above):

• TOUR_OFFERING ← created from Backoffice TOUR_DEPARTURE via TourDeparturePublished event
• TOUR_OFFERING pricing ← synced from Backoffice PRICE_MATRIX via PriceMatrixPublished event
• SEAT_RESERVATION → references Operations SERVICE_LEG for capacity tracking
• PASSENGER → references Backoffice PERSON_PROFILE via soft FK
• BOOKING → references Backoffice PERSON_PROFILE via booker_profile_id soft FK [planned — Phase 1]
• PASSENGER → references Backoffice BOARDING_POINT via soft FK
• RESELLER (Backoffice) → brokers BOOKING
• TICKET → read by Operations BOARDING_EVENT for QR validation

---

Entity Dictionary

• TourOffering: The sellable, Commerce-owned projection of a published TourDeparture. Created/updated when Backoffice publishes a TourDeparture via the TourDeparturePublished event. References the source TourDeparture and TourTemplate via soft FKs. Carries denormalized display data. Pricing comes from TourOfferingPrice — a read-model projection of the Backoffice PriceMatrix, synced asynchronously via PriceMatrixPublished events. Lifecycle status: SCHEDULED, SOLD_OUT, COMPLETED, CANCELLED (Note: DRAFT and READY states belong natively to TourDeparture in Backoffice and are not projected to Commerce until published).
• TourOfferingPrice (Read-Model): A flattened Commerce-side projection of the Backoffice PriceMatrix. Stores price_matrix_version_id (soft FK to backoffice.price_matrices), channel, and variants (JSONB). Synced via PriceMatrixPublished events. Checkout validates the cart's price against the authoritative price_matrix_version_id — mismatches trigger a hard reject and cart refresh.
• CheckoutSession: A short-lived entity tracking a user's purchase intent before the system confirms a Booking. Captures the selected TourOffering, passenger count, seat holds, and chosen boarding point. Status lifecycle: ACTIVE → EXPIRED (TTL elapsed) or CONVERTED (successful payment). Converts to a Booking upon successful payment. Enables abandoned cart recovery: session expires after TTL (default 30 minutes) → Hasura Scheduled Trigger sets status = 'EXPIRED' → emits CheckoutAbandoned event → Communications context executes re-engagement workflow (Email at +1h, WhatsApp at +24h). See PRODUCT_mollie-integration.md §4 for the full checkout pipeline.
• Booking: The primary transactional container bundling requested products and managing checkout states. The system defines the booking lifecycle through a strict state machine: DRAFT → PENDING_PAYMENT → DEPOSIT_PAID → FULLY_PAID → COMPLETED → CANCELLED / REFUNDED / NO_SHOW. [planned — Phase 1] References booker_profile_id (soft FK to Backoffice PersonProfile) — the person with billing authority who initiates and pays. The booker may or may not also appear as a Passenger (traveler). Phase 1 B2C: the form submitter is assumed to also be the primary contact passenger; submitCheckout resolves booker_profile_id from that passenger's PersonProfile. Non-traveler booker capture (the grandmother case) deferred to Phase 1.x. In dispatcher-created bookings, the dispatcher sets the booker directly. See ADR-037.
• Passenger: The individual traveler on a booking. Carries cross-border documentation fields (name, DOB, document number, nationality) required for cross-border tours; these fields are nullable for domestic tours where no border manifest is needed. The is_primary_contact flag identifies the on-trip communication recipient and driver's on-site contact — the person who receives operational messages (pre-departure reminders, boarding details). Note: the person who pays is the booker (on the parent Booking), not necessarily the primary contact passenger. References a boarding_point_id (soft FK to Backoffice) for the chosen pickup location and a person_profile_id (soft FK to Backoffice PersonProfile) for CRM linkage. Border document authority: document_number and nationality exist only on Passenger — they are point-in-time travel credentials, not identity attributes. PersonProfile deliberately omits these fields because passport numbers expire and renew between bookings; the border manifest requires the document the traveler carries on this departure. For returning travelers, the checkout and dispatcher UIs pre-fill border document fields from the traveler's most recent Passenger row as a read-only suggestion (passengers WHERE person_profile_id = :id ORDER BY created_at DESC LIMIT 1). The traveler confirms or updates before submission. Pre-fill requires a linked person_profile_id — children and other passengers without contact identifiers may lack a stable profile link and require manual data entry. DOB sync direction: date_of_birth exists on both PersonProfile (CRM, demographic pricing) and Passenger (border manifests). The Passenger row captures the value entered at booking time. On BookingConfirmed, the PersonProfile updater writes back the Passenger's DOB to PersonProfile.date_of_birth — the most recent booking input wins. If a Passenger row omits DOB (domestic tour), the system does not overwrite an existing PersonProfile DOB. Border manifest delivery: The Operations context generates the driver-facing manifest via a denormalized read model joining Passenger data with Departure, Seats, and BoardingPoints ([v0.2] — see PRODUCT_demo-loop.md §S5).
• Payment: Granular tracking via Mollie Marketplaces, where the system handles split transactions like deposit (Anzahlung) and final payment (Restzahlung). Uses Mollie's delayed capture and marketplace routing for multi-party payouts to operators. Supports SEPA, PayPal, Apple/Google Pay, Klarna (BNPL), iDEAL, and credit cards. Records the actual payment_method used (populated from Mollie webhook). See PRODUCT_mollie-integration.md for the complete integration spec including webhook-to-state mapping.
• Ancillary: Upsells added to a booking. The type field defines the behavioral category (INSURANCE, SEAT_UPGRADE, LUGGAGE, EXCURSION, MEAL, BOARDING_SURCHARGE, OTHER) which governs system behavior (refund rules, reporting, fulfillment hints). BOARDING_SURCHARGE is auto-created by Commerce when a passenger selects a boarding point with a surcharge. The label field is operator-defined (the passenger-facing name). Each ancillary has an independent lifecycle (ACTIVE, CANCELLED, REFUNDED) to support partial cancellation. Carries an optional catalog_item_id (soft FK to backoffice.ancillary_catalog_items) for traceability to the operator's catalog; null for system-generated items like boarding surcharges.
• SeatReservation: Time-locked capacity holds mapped against the operational ServiceLeg. Carries seat_identifier (matching a key in the vehicle's seat_map_layout JSONB), hold_expires_at (aligned with checkout session TTL, default 30 minutes — see ADR-013), and status enum (HELD, CONFIRMED, RELEASED). A Hasura Scheduled Trigger (seat_hold_cleanup) runs every 60s to release expired holds. When a vehicle swap occurs, reservations are re-mapped to equivalent seat positions on the new layout.
• Ticket (Fulfillment Artifact): The digital fulfillment and boarding pass. Owned by Commerce (it is a commercial fulfillment artifact of a confirmed booking). Operations reads the ticket via a cross-schema soft reference or denormalized read model to track check_in_status via qr_hash validation in the driver's offline app.
• FinancialLedger (Nachkalkulation): The per-departure profitability ledger. The system auto-creates one FinancialLedger per TourOffering when the first booking reaches DEPOSIT_PAID. It aggregates actual booking revenues (realized_revenue = sum of Payment.amount with status = COMPLETED) and actual operational expenses (realized_expense = sum from ExpenseSubmitted and OnboardSaleRecorded domain events consumed from Operations). These scalar totals are management/profitability accumulators, not the semantic authority for tax classification: payments prove that money moved, while booking, cancellation, ancillary, invoice, and onboard-sale commands classify what the money means. Snapshots two Soll baselines at creation: planned_cost from CostingSheet.total_net_cost and planned_revenue from the active PriceMatrix (Σ variant prices × expected pax at CapacityRule.max_capacity; version tracked via planned_price_matrix_version_id). Computes three delta columns: cost_delta = realized_expense − planned_cost, revenue_delta = realized_revenue − planned_revenue, margin_delta = (realized_revenue − realized_expense) − (planned_revenue − planned_cost). Carries costing_sheet_id (soft FK) for Soll/Ist baseline and currency (ISO 4217). Status lifecycle: OPEN (accepting mutations from booking/expense events) → CLOSED (period-locked, the system finalizes all actuals via the closed_at timestamp). See ADR-002.
• TaxLedgerEntry: A generalized entity utilizing a TaxStrategyType to calculate the correct tax burden based on ledger actuals. Relationship is 1:N — a single FinancialLedger can produce multiple TaxLedgerEntries when a departure mixes tax strategies (e.g., one MARGIN_SCHEME_25 entry for the tour margin and one STANDARD_VAT entry for onboard sales). TaxLedgerEntry generation must fold classified economic facts, not only FinancialLedger.realized_revenue / realized_expense; otherwise cancellation-derived retained amounts can be folded as ordinary travel-service revenue while the final ledger rows still look arithmetically consistent. Persists the four mandatory § 25 Abs. 5 UStG recording fields as immutable columns. See ADR-012 and tax-engine-protocol.md.
• Invoice: Consolidates billing information and integrates e-invoicing standards. The system generates invoices as PDFs directly from aggregated TaxLedgerEntry and Booking data without a persistent invoice_line_items table.
• LedgerPeriodLock: Prevents mutation of financial records (FinancialLedger, Invoice, TaxLedgerEntry) after the user closes a reporting period or the system exports it to DATEV. Lock types: EXPORT (irreversible, auto-created on DATEV export) and MANUAL (operator-triggered month-end close, admin-unlockable with audit trail). See Invoice Service Protocol § Period Lock.
• InvoiceCancellation (Storno): GoBD-compliant cancellation record linking a voided invoice to its counter-document (Stornorechnung) and optional replacement invoice. The system never modifies the original invoice — it creates a new counter-invoice with negative amounts. See Invoice Service Protocol § Storno Workflow.
• Infrastructure Entities: The physical schema includes lower-level tables (ReconciliationUpload, ReconciliationEntry) supporting DATEV BWA/SuSa import and Soll/Ist comparison at the account-code level. These are import/comparison utilities without domain lifecycle.

---

Aggregates

Each aggregate defines a transactional consistency boundary. Cross-aggregate references follow ADR-036.

TourOffering

Role	Entity
Root	TourOffering
Child	TourOfferingPrice (read-model projection)

Invariants: Status: SCHEDULED → SOLD_OUT / COMPLETED / CANCELLED. Price version must match active Backoffice PriceMatrix version. Domain Services: Exposes a read-model endpoint to auto-generate the standard "Anlage 11" Formblatt PDF dynamically using the offering's template data and the operator's insolvency insurance details.

Booking

Role	Entity
Root	Booking
Child	Passenger
Child	Payment
Child	Ancillary
Child	Ticket

Invariants: Status state machine: DRAFT → PENDING_PAYMENT → DEPOSIT_PAID → FULLY_PAID → COMPLETED → CANCELLED / REFUNDED / NO_SHOW. Must have a booker_profile_id before transitioning past DRAFT (exception: B2B bookings with reseller_id may omit — see ADR-037). At least one Passenger (traveler). Deposit/final payment split. Each Passenger and Ancillary carries an independent lifecycle for partial cancellation. Events: BookingConfirmed, BookingFullyPaid, BookingCancelled, BookingRefunded, BookingCompleted, BookingNoShow, PassengerCancelled, AncillaryCancelled, PaymentReceived. Cross-aggregate refs: tour_offering_id is a hard FK (stable — offering never deleted).

Contention note: Mollie webhooks can arrive concurrently for the same booking (deposit + final payment race). Use optimistic concurrency on the Booking root (version column / updated_at check).

State vs. event decoupling: DEPOSIT_PAID is a booking state (a position in the lifecycle); BookingConfirmed is a domain event (an integration contract). Today they fire 1:1 — the Hasura Event Trigger on commerce.bookings.status → DEPOSIT_PAID emits BookingConfirmed — but they are conceptually independent and the downstream consequences fan out to separate concerns: CostingSheet cost-lock (Backoffice, ADR-009, defended by § 651a BGB), FinancialLedger auto-creation (Commerce internal), Ticket issuance (ADR-014), confirmation PDF + Formblatt + Sicherungsschein delivery (Communications), and PersonProfile DOB write-back (Backoffice, ADR-037 §7). Each consequence is modeled as an independent consumer so the firing condition can be re-bound without touching the others — relevant if legal review of Widerrufsrecht (§ 312g BGB) or § 651t (Reisepreisabsicherung) forces a "confirmed but withdrawable" sub-state. See ADR-009 § Scope & Legal Contingency and PRODUCT_payments-and-billing.md §4.

CheckoutSession

Single-entity aggregate. Short-lived purchase intent tracker.

Invariants: Status: ACTIVE → EXPIRED / CONVERTED. TTL-based lifecycle (default 30 minutes). A CheckoutSession cannot transition to CONVERTED unless legal_consent.agb_accepted and privacy_accepted are both true. If the associated TourOffering has is_pauschalreise = true, formblatt_acknowledged must also be true. Events: CheckoutAbandoned, OnboardPaymentExpired. Cross-aggregate refs: tour_offering_id (hard FK — stable), booking_id (soft FK — independent TTL lifecycle, set only on conversion).

SeatReservation

Single-entity aggregate. Time-locked capacity hold against an operational ServiceLeg.

Invariants: Partial unique: (service_leg_id, seat_identifier) WHERE status IN ('HELD', 'CONFIRMED') — no double-booking. Status: HELD → CONFIRMED / RELEASED. Events: SeatHoldExpired (emitted by the seat_hold_cleanup Scheduled Trigger when hold_expires_at elapses). Cross-aggregate refs: service_leg_id (soft FK to Operations ServiceLeg), passenger_id (hard FK to Booking.Passenger — set when status transitions to CONFIRMED).

FinancialLedger

Role	Entity
Root	FinancialLedger
Child	TaxLedgerEntry

Invariants: One per TourOffering. Status: OPEN → CLOSED. § 25 Abs. 5 UStG immutable tax recording fields. Events emitted: FinancialLedgerClosed. Events consumed: PaymentReceived (increments realized_revenue), classified booking/cancellation facts (preserve sale vs. cancellation-fee semantics for tax close), ExpenseSubmitted and OnboardSaleRecorded (increment realized_expense — consumed from Operations context). Cross-aggregate refs: tour_offering_id (hard FK — stable, UNIQUE).

Invoice

Role	Entity
Root	Invoice
Child	InvoiceCancellation

Invariants: Status: DRAFT → ISSUED → PAID → VOIDED. Gap-free, tenant-scoped sequential numbering (GoBD). Original invoices never modified — the system creates counter-invoices. JSONB snapshots freeze supplier, recipient, and line-item data at generation. Events: InvoiceIssued. Cross-aggregate refs: financial_ledger_id and booking_id are soft FKs (Invoice has own lifecycle + JSONB snapshot independence).

LedgerPeriodLock

Single-entity aggregate. Immutable lock record.

Invariants: Prevents mutation of financial data after period close or DATEV export. Types: EXPORT (irreversible) and MANUAL (admin-unlockable with audit trail).

Infrastructure Entities (not aggregates)

change_events, tenant_invoice_sequences, reconciliation_uploads + reconciliation_entries.