Constraints & Non-obvious Semantics

This page flags fields that have non-obvious semantics, non-standard storage formats, or constraints that are easy to get wrong.

Critical: pricing field semantics

QuoteLine.unitPrice and QuoteLine.totalPrice are always HT

QuoteLine.unitPrice and QuoteLine.totalPrice are HT (hors taxes / excl. VAT) values — never TTC.

Do not display unitPrice to end-users as the final price without adding VAT. Use totalTtc for customer-facing displays.

QuoteLine.vatRate — decimal percent, not a ratio

vatRate is stored as a decimal percentage. 10.00 means 10 %, not 0.10.

Correct:   totalTtc = totalPrice × (1 + vatRate / 100)
Incorrect: totalTtc = totalPrice × (1 + vatRate)   ← off by 100x

Default value: 10.00 (the French transport VAT rate). This default comes from OrganizationPricingSettings.defaultVatRate.

The same convention applies to InvoiceLine.vatRate, ZoneRoute.vatRate, ExcursionPackage.vatRate, DispoPackage.vatRate, and PartnerContractZoneRoute.vatRate.

Grid prices — HT or TTC depends on priceMode

ZoneRoute.fixedPrice, ExcursionPackage.price, and DispoPackage.basePrice may be stored as either HT or TTC. Check the priceMode field (HT / TTC) before using the value.

if (priceMode === 'TTC') {
  htPrice = fixedPrice / (1 + vatRate / 100)
} else {
  htPrice = fixedPrice
}

PartnerContractZoneRoute.overridePrice is always HT (no priceMode on override).

TripType enum

Quote.tripType has exactly four values:

dropoffAddress is nullable for DISPO and OFF_GRID. vehicleCategoryId is nullable for OFF_GRID.

Mission.quoteId — nullable by design

Mission.quoteId is nullable. Internal tasks (operator-created missions not tied to a commercial quote) leave this field null. These missions have isInternal = true and are excluded from invoice generation.

Never assume quoteId is present in a Mission query. Always use a left-join or optional include:

// Prisma — safe
const mission = await prisma.mission.findUnique({
  where: { id },
  include: { quote: true }  // quote may be null
})

// Guard before accessing quote fields
if (mission.quote) {
  // use mission.quote.finalPrice, etc.
}

Quote.tripAnalysis JSON shape

Quote.tripAnalysis stores the shadow calculation output from the pricing engine. Typical shape:

{
  "segments": [
    {
      "type": "APPROACH" | "SERVICE" | "RETURN",
      "distanceKm": 12.5,
      "durationSeconds": 1800,
      "costEur": 18.75
    }
  ],
  "totalDistanceKm": 37.2,
  "totalDurationSeconds": 5400,
  "costBreakdown": {
    "fuel": 12.50,
    "tolls": 4.20,
    "driverCost": 18.00,
    "wear": 3.72
  },
  "staffingPlan": {
    "mode": "SIMPLE" | "DOUBLE_EQUIPAGE" | "RELAIS",
    "additionalCost": 0
  },
  "alternativeCalculation": {
    "mode": "DISPO",
    "estimatedPrice": 220.00
  }
}

This field is read-only from the frontend — it is produced by packages/api/src/services/pricing-engine.ts and must not be hand-crafted.

Key database indexes

Performance-critical indexes defined in the schema:

Unique constraints

Document counters and references

Sequential document references (QT-2026-001, ORD-2026-001, INV-2026-001) are generated using the DocumentCounter model:

DocumentCounter (organizationId, type, year) → lastNumber (atomic increment)

Types: DEV (devis/quote), RES (reservation/order), MIS (mission), INV (invoice). The upsert+increment pattern guarantees uniqueness without race conditions.

Language field conventions

Language fields across all models store an ISO 639-1 two-letter code (fr, en). Forward-compatible values (es, pt, de, it) are planned. A CHECK constraint is enforced at the DB level via migration on Contact.preferredLanguage and EndCustomer.preferredLanguage.

Resolution order for PDF and email language:

1. EndCustomer.preferredLanguage (if passenger is specified)
2. Contact.preferredLanguage (billing contact)
3. Operator fallback (fr)

Soft-delete conventions

No model uses hard-delete by default. Soft-delete patterns:

The onDelete cascades defined in the schema handle hard-deletes of parent records (e.g., deleting an Organization cascades to all its child records).