@ingenx-io/valets-schema-mcp-server 0.1.1 → 0.1.3

package/data/static/openapi.yaml

@@ -0,0 +1,3090 @@
+openapi: 3.1.0
+info:
+  title: '@valets/schema'
+  description: 'Canonical data model for the Valets platform (Firestore document schemas).
+
+
+    Each model appears in up to three variants:
+
+    - **{Model}** — read model (full Firestore document, includes server-set fields)
+
+    - **{Model}Create** — write model for document creation; uses allOf composition
+    referencing {Model}. `readOnly` fields must not be sent.
+
+    - **{Model}Update** — write model for partial updates / PATCH; uses allOf composition.
+    All fields optional; `readOnly` and `x-immutable` fields must not be sent.
+
+
+    Server-owned models (e.g. BookingVersion, LoyaltyStatus) only have the read variant.'
+  version: 0.1.0
+paths: {}
+components:
+  schemas:
+    BookingStatus:
+      type: string
+      enum:
+      - PENDING
+      - CONFIRMED
+      - COMPLETED
+      - CANCELLED
+      - CANCELLATION_REQUESTED
+      - COMPLETED_MIXED
+      description: Booking lifecycle status. COMPLETED_MIXED = some sessions completed,
+        others cancelled/no-show.
+    CustomerPaymentStatus:
+      type: string
+      enum:
+      - PENDING
+      - CONFIRMED
+      - PARTIALLY_APPLIED
+      - FULLY_APPLIED
+      - REFUNDED
+      - CANCELLED
+      description: Customer payment lifecycle status (D22). Tracks allocation progress
+        of received payments.
+    CustomerPaymentTargetType:
+      type: string
+      enum:
+      - BOOKING
+      - ORDER
+      - PURCHASE
+      description: Target document type for customer payment allocation.
+    DeliveryType:
+      type: string
+      enum:
+      - ON_SITE
+      - PICK_UP
+      - DELIVERY
+      description: Fulfillment channel for an order. Determines whether the customer
+        comes to the business (ON_SITE), collects their order themselves (PICK_UP),
+        or receives a physical delivery (DELIVERY). Drives whether fulfillmentStatus
+        is relevant.
+    EventStatus:
+      type: string
+      enum:
+      - DRAFT
+      - ACTIVE
+      - CANCELLED
+      - COMPLETED
+      description: Ticketed event lifecycle (D32). Mobile-only today; Dashboard in
+        Wave 4.
+    FulfillmentStatus:
+      type: string
+      enum:
+      - PREPARING
+      - PARTIALLY_SHIPPED
+      - SHIPPED
+      - IN_TRANSIT
+      - DELIVERED
+      - PICKED_UP
+      description: Delivery/fulfillment lifecycle (D34). Optional — null for in-person
+        orders.
+    LoyaltyTransactionType:
+      type: string
+      enum:
+      - EARNED
+      - REDEEMED
+      - ADJUSTED
+      - EXPIRED
+      - BONUS
+      - REFUND
+      description: Loyalty point transaction type (D07). SCREAMING_SNAKE past tense.
+    OrderStatus:
+      type: string
+      enum:
+      - PENDING
+      - CONFIRMED
+      - PROCESSING
+      - READY
+      - COMPLETED
+      - CANCELLED
+      - EXPIRED
+      description: Core order lifecycle status (D03, D34). Universal across all business
+        types. Replaces the Dashboard's legacy 20-value flat enum (MIG-11).
+    PaymentMethod:
+      type: string
+      enum:
+      - CASH
+      - CREDIT_CARD
+      - ORANGE_MONEY
+      - WAVE
+      - MTN_MONEY
+      - MOOV_MONEY
+      - BANK_TRANSFER
+      - PAYPAL
+      - STRIPE
+      - OTHER
+      description: Unified payment method set with African + global methods (D02).
+    PaymentProofStatus:
+      type: string
+      enum:
+      - PENDING
+      - APPROVED
+      - REJECTED
+      description: Payment proof review status. Used by Order and Booking payment
+        proof workflows.
+    PaymentStatus:
+      type: string
+      enum:
+      - PENDING
+      - PAID
+      - PARTIALLY_PAID
+      - FAILED
+      - REFUND_PROCESSING
+      - REFUNDED
+      - PARTIALLY_REFUNDED
+      description: Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase,
+        Booking.
+    ReturnStatus:
+      type: string
+      enum:
+      - RETURN_REQUESTED
+      - RETURN_PROCESSING
+      - RETURNED
+      - EXCHANGE_REQUESTED
+      - EXCHANGE_PROCESSING
+      - EXCHANGE_COMPLETED
+      description: Post-sale return/exchange lifecycle (D34). Optional — null until
+        return or exchange initiated.
+    SessionStatus:
+      type: string
+      enum:
+      - PENDING
+      - CONFIRMED
+      - CANCELLATION_REQUESTED
+      - COMPLETED
+      - NO_SHOW
+      - CANCELLED
+      description: Per-date/per-slot booking session status (D19). Dashboard is sole
+        writer; Mobile is read-only.
+    TicketStatus:
+      type: string
+      enum:
+      - VALID
+      - USED
+      - CANCELLED
+      description: Event ticket status (D32). VALID = active and unused.
+    FirestoreTimestamp:
+      type: object
+      properties:
+        _seconds:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        _nanoseconds:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+      required:
+      - _seconds
+      - _nanoseconds
+      additionalProperties: false
+      description: Firestore Timestamp serialized representation
+    Booking:
+      type: object
+      properties:
+        id:
+          type: string
+          readOnly: true
+          description: (Read-only) Firestore document ID.
+        uid:
+          type: string
+          readOnly: true
+          description: (Read-only) Entity UID. Often mirrors id.
+        companyId:
+          x-immutable: true
+          description: '(Immutable) FK → Company document ID. Note: optional in current
+            schema — should be required (see ID consistency audit).'
+          type:
+          - string
+          - 'null'
+        status:
+          $ref: '#/components/schemas/BookingStatus'
+          description: Booking lifecycle status. COMPLETED_MIXED = some sessions completed,
+            others cancelled/no-show.
+        totalAmount:
+          type: number
+          x-note: Booking uses `totalAmount`; Order uses `amount` for the equivalent
+            field (D05 locked `amount` as canonical for orders). Pending cross-model
+            alignment.
+          x-see:
+            decisions:
+            - D05
+        bookingDates:
+          type: array
+          items:
+            type: object
+            properties:
+              date:
+                type: string
+              selectedTimeSlots:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: number
+                    name:
+                      type: string
+                    timeRange:
+                      type: string
+                    price:
+                      type: number
+                      description: Canonical price field (D11). Replaces legacy standardPrice/fullPrice
+                        (MIG-08).
+                    notMainPurposePrice:
+                      type: number
+                      description: Price when slot is not the main purpose (D11).
+                        Canonical name; replaces legacy aliases (MIG-08).
+                    hours:
+                      type: string
+                    startTime:
+                      type: string
+                    endTime:
+                      type: string
+                    isNightSlot:
+                      type: boolean
+                    isNotMainPurpose:
+                      type: boolean
+                    isNotMainPurposeReason:
+                      type: string
+                    isNotMainPurposeOtherReason:
+                      type: string
+                    _deleted:
+                      description: Soft-delete flag. Dashboard writes; Mobile filters
+                        (IG-6).
+                      type: boolean
+                    _deletedAt:
+                      $ref: '#/components/schemas/FirestoreTimestamp'
+                      description: Firestore Timestamp serialized representation
+                    _deletedBy:
+                      description: FK → User/staff UID who soft-deleted this item.
+                      type: string
+                    _lastModifiedAt:
+                      $ref: '#/components/schemas/FirestoreTimestamp'
+                      description: Firestore Timestamp serialized representation
+                    _lastModifiedBy:
+                      description: FK → User/staff UID who last modified this item.
+                      type: string
+                    _version:
+                      description: Monotonic version counter for conflict detection.
+                      type: number
+                  required:
+                  - id
+                  - name
+                  - timeRange
+                  - price
+                  - notMainPurposePrice
+                  - hours
+                  - startTime
+                  - endTime
+                  additionalProperties: false
+                  description: Selected time slot within a BookingDate. Carries CRDT
+                    metadata for conflict-free editing.
+              slotKitTypes:
+                type: object
+                propertyNames:
+                  type: string
+                additionalProperties:
+                  type: string
+                description: Kit type per slot (IG-11). Firebase parity gap — exists
+                  in Firestore but Firebase type lacked it.
+              slotAddOns:
+                type: object
+                propertyNames:
+                  type: string
+                additionalProperties:
+                  type: array
+                  items:
+                    type: string
+                description: Add-on IDs per slot. Numeric IDs to be normalized to
+                  descriptive names (MIG-07/D10).
+              extraHours:
+                type: number
+              status:
+                $ref: '#/components/schemas/SessionStatus'
+                description: Per-date session status (D19). Dashboard is sole writer;
+                  Mobile is read-only.
+              statusUpdatedAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                readOnly: true
+                description: (Read-only) Timestamp of last status change.
+              statusUpdatedBy:
+                description: FK → User/staff UID who updated this date status.
+                type: string
+              slotStatuses:
+                description: Per-slot session statuses (D19). Keyed by slot ID string.
+                type: object
+                propertyNames:
+                  type: string
+                additionalProperties:
+                  $ref: '#/components/schemas/SessionStatus'
+                  description: Per-date/per-slot booking session status (D19). Dashboard
+                    is sole writer; Mobile is read-only.
+              slotStatusUpdatedAt:
+                type: object
+                propertyNames:
+                  type: string
+                additionalProperties:
+                  $ref: '#/components/schemas/FirestoreTimestamp'
+                  description: Firestore Timestamp serialized representation
+              slotStatusUpdatedBy:
+                type: object
+                propertyNames:
+                  type: string
+                additionalProperties:
+                  type: string
+              _deleted:
+                description: Soft-delete flag. Dashboard writes; Mobile filters (IG-6).
+                type: boolean
+              _deletedAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: Firestore Timestamp serialized representation
+              _deletedBy:
+                description: FK → User/staff UID who soft-deleted this item.
+                type: string
+              _lastModifiedAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: Firestore Timestamp serialized representation
+              _lastModifiedBy:
+                description: FK → User/staff UID who last modified this item.
+                type: string
+              _version:
+                description: Monotonic version counter for conflict detection.
+                type: number
+            required:
+            - date
+            - selectedTimeSlots
+            - slotKitTypes
+            - slotAddOns
+            - extraHours
+            additionalProperties: false
+            description: Single date entry within a Booking. Contains time slots,
+              session statuses (D19), and CRDT metadata.
+        customerId:
+          description: FK → Customer.id (Firestore doc ID). Links booking to customer
+            record.
+          type:
+          - string
+          - 'null'
+        client:
+          denormalized: true
+          description: (Denormalized) Embedded client snapshot from Customer at write
+            time.
+          type:
+          - object
+          - 'null'
+          properties:
+            firstName:
+              type: string
+            lastName:
+              type: string
+            email:
+              type: string
+            phone:
+              type: string
+          additionalProperties: false
+        customerName:
+          denormalized: true
+          description: (Denormalized) From Customer.name at write time. Canonical
+            field per D24.
+          type:
+          - string
+          - 'null'
+        customerEmail:
+          denormalized: true
+          description: (Denormalized) From Customer.email at write time. Canonical
+            field per D24.
+          type:
+          - string
+          - 'null'
+        customerPhone:
+          denormalized: true
+          description: (Denormalized) From Customer.phone at write time. Canonical
+            field per D24.
+          type:
+          - string
+          - 'null'
+        clientName:
+          denormalized: true
+          deprecated: true
+          x-replaced-by: customerName
+          description: (Denormalized) Legacy — use `customerName`. D24 standardized
+            to customer* prefix.
+          type:
+          - string
+          - 'null'
+        clientReference:
+          type: string
+        clientEmail:
+          denormalized: true
+          deprecated: true
+          x-replaced-by: customerEmail
+          description: (Denormalized) Legacy — use `customerEmail`. D24 standardized
+            to customer* prefix.
+          type:
+          - string
+          - 'null'
+        clientPhone:
+          denormalized: true
+          deprecated: true
+          x-replaced-by: customerPhone
+          description: (Denormalized) Legacy — use `customerPhone`. D24 standardized
+            to customer* prefix.
+          type:
+          - string
+          - 'null'
+        service:
+          type:
+          - object
+          - 'null'
+          properties:
+            name:
+              type: string
+          additionalProperties: false
+        serviceId:
+          description: FK → Service document ID.
+          type:
+          - string
+          - 'null'
+        serviceName:
+          denormalized: true
+          description: (Denormalized) From Service.name at write time.
+          type:
+          - string
+          - 'null'
+        timeSlot:
+          type:
+          - string
+          - 'null'
+        date:
+          type:
+          - string
+          - 'null'
+        startDate:
+          type:
+          - string
+          - 'null'
+        endDate:
+          type:
+          - string
+          - 'null'
+        startTime:
+          type:
+          - string
+          - 'null'
+        endTime:
+          type:
+          - string
+          - 'null'
+        notes:
+          type:
+          - array
+          - 'null'
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+                readOnly: true
+                description: (Read-only) Note ID.
+              text:
+                type: string
+              createdAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: (Read-only) Firestore Timestamp serialized representation.
+                readOnly: true
+              createdBy:
+                x-immutable: true
+                description: (Immutable) FK → User/staff UID who created this note.
+                type: string
+              createdByName:
+                denormalized: true
+                description: (Denormalized) From User display name at write time.
+                type: string
+              _deleted:
+                description: Soft-delete flag. Dashboard writes; Mobile filters (IG-6).
+                type: boolean
+              _deletedAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: Firestore Timestamp serialized representation
+              _deletedBy:
+                description: FK → User/staff UID who soft-deleted this item.
+                type: string
+              _lastModifiedAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: Firestore Timestamp serialized representation
+              _lastModifiedBy:
+                description: FK → User/staff UID who last modified this item.
+                type: string
+              _version:
+                description: Monotonic version counter for conflict detection.
+                type: number
+            required:
+            - id
+            - text
+            - createdAt
+            additionalProperties: false
+            description: Timestamped note attached to a Booking. Carries CRDT metadata.
+        technicalInfo:
+          type:
+          - string
+          - 'null'
+        paymentStatus:
+          anyOf:
+          - $ref: '#/components/schemas/PaymentStatus'
+          - type: 'null'
+          description: Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase,
+            Booking.
+        amountPaid:
+          type:
+          - number
+          - 'null'
+        amountRefunded:
+          type:
+          - number
+          - 'null'
+        amountPending:
+          type:
+          - number
+          - 'null'
+        purchaseId:
+          description: FK → Sale.id. Link to associated Sale document.
+          type:
+          - string
+          - 'null'
+        paymentStatusChangeReason:
+          type:
+          - string
+          - 'null'
+        paymentStatusChangedBy:
+          description: FK → User/staff UID who changed payment status.
+          type:
+          - string
+          - 'null'
+        paymentStatusChangedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: Firestore Timestamp serialized representation
+        paymentProofUrl:
+          description: URL to uploaded payment proof image/document.
+          type:
+          - string
+          - 'null'
+        paymentProofStatus:
+          anyOf:
+          - $ref: '#/components/schemas/PaymentProofStatus'
+          - type: 'null'
+          description: Payment proof review status. Used by Order and Booking payment
+            proof workflows.
+        paymentProofAddedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: Firestore Timestamp serialized representation
+        paymentProofAddedBy:
+          description: FK → User/staff UID who uploaded the payment proof.
+          type:
+          - string
+          - 'null'
+        paymentProofReviewedBy:
+          description: FK → User/staff UID who reviewed the payment proof.
+          type:
+          - string
+          - 'null'
+        paymentProofReviewedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: Firestore Timestamp serialized representation
+        paymentProofRejectionReason:
+          type:
+          - string
+          - 'null'
+        cancellationRequestedById:
+          description: FK → User/staff UID who requested cancellation.
+          type:
+          - string
+          - 'null'
+        cancellationRequestReason:
+          type:
+          - string
+          - 'null'
+        cancellationProcessedById:
+          description: FK → User/staff UID who processed the cancellation.
+          type:
+          - string
+          - 'null'
+        cancellationProcessedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: Firestore Timestamp serialized representation
+        cancelledByRole:
+          type:
+          - string
+          - 'null'
+        cancellationReason:
+          type:
+          - string
+          - 'null'
+        createdAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server-generated creation timestamp.
+          readOnly: true
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+        createdBy:
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who created this booking.
+          type:
+          - string
+          - 'null'
+        updatedBy:
+          description: FK → User/staff UID who last updated this booking.
+          type:
+          - string
+          - 'null'
+        createdFromBackend:
+          description: When true, suppresses Firebase notification triggers (D20/IG-8).
+          type:
+          - boolean
+          - 'null'
+      required:
+      - id
+      - uid
+      - status
+      - totalAmount
+      - bookingDates
+      - clientReference
+      - createdAt
+      additionalProperties: false
+      description: 'Booking model. Collection: companies/{companyId}/bookings/{bookingId}.
+        All platforms. Uses BookingStatus (6 values) and SessionStatus (D19) for per-date/slot
+        tracking.'
+    BookingCreate:
+      allOf:
+      - $ref: '#/components/schemas/Booking'
+      description: Write payload for creating a new Booking document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - status
+      - totalAmount
+      - bookingDates
+      - clientReference
+    BookingUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Booking'
+      description: Write payload for partial update (PATCH) of a Booking document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    BookingVersion:
+      type: object
+      properties:
+        id:
+          type: string
+          readOnly: true
+          description: (Read-only) Firestore document ID. Server-generated version
+            record.
+        bookingId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Booking.id. Parent booking this version records.
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Denormalized for direct
+            queries.
+        changeType:
+          type: string
+          enum:
+          - CREATE
+          - UPDATE
+          - DELETE
+          x-immutable: true
+          x-note: DELETE versions are written when a booking is soft-deleted (CRDT
+            _deleted flag). Hard deletes bypass this trail.
+          description: '(Immutable) What caused this version record: CREATE, UPDATE,
+            or DELETE.'
+        changedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Timestamp of the write that created this version.
+            Server-set.
+          readOnly: true
+        changedBy:
+          x-immutable: true
+          x-note: Null when the write originated from a Firebase trigger, CLI script,
+            or unknown source.
+          description: (Immutable) FK → User/staff UID who made the change. Null for
+            server-originated writes.
+          type:
+          - string
+          - 'null'
+        changedByRole:
+          x-immutable: true
+          x-note: Populated by the Firebase trigger from the write context. Helps
+            distinguish client vs. server writes.
+          description: '(Immutable) Which platform/context made the write: DASHBOARD,
+            MOBILE, FIREBASE (trigger), CLI (migration script), or UNKNOWN. SCREAMING_SNAKE
+            per D04.'
+          type:
+          - string
+          - 'null'
+          enum:
+          - DASHBOARD
+          - MOBILE
+          - FIREBASE
+          - CLI
+          - UNKNOWN
+        fieldsChanged:
+          x-immutable: true
+          readOnly: true
+          x-note: Dot-notation paths for nested fields (e.g. "bookingDates.0.status").
+            Populated by diff in Firebase trigger. Null for CREATE versions.
+          description: (Immutable, Read-only) List of field paths that changed in
+            this write. Populated by the Firebase trigger diff. Null for CREATE records.
+          type:
+          - array
+          - 'null'
+          items:
+            type: string
+        snapshot:
+          type: object
+          propertyNames:
+            type: string
+          additionalProperties: {}
+          x-immutable: true
+          readOnly: true
+          x-note: Full Booking document at the time of write. Typed as a string-keyed
+            record to avoid circular schema reference. Consumers cast to Booking at
+            runtime.
+          x-see:
+            decisions:
+            - D18
+          description: (Immutable, Read-only) Full snapshot of the Booking document
+            immediately after the write. Untyped to avoid circular schema dependency
+            — cast to Booking at runtime.
+      required:
+      - id
+      - bookingId
+      - companyId
+      - changeType
+      - changedAt
+      - snapshot
+      additionalProperties: false
+      description: 'BookingVersion model (D18). Collection: companies/{companyId}/bookings/{bookingId}/versions/{versionId}.
+        Server-owned audit trail written by Firebase trigger on every Booking mutation.
+        Captures writes from all clients.'
+    Customer:
+      type: object
+      properties:
+        id:
+          type: string
+          readOnly: true
+          description: (Read-only) Firestore document ID. This is the canonical FK
+            target — other models reference Customer via this field.
+        uid:
+          type: string
+          readOnly: true
+          description: (Read-only) Entity UID. Often mirrors id.
+        name:
+          type: string
+        email:
+          type:
+          - string
+          - 'null'
+        phone:
+          type:
+          - string
+          - 'null'
+        address:
+          type:
+          - string
+          - 'null'
+        notes:
+          type:
+          - string
+          - 'null'
+        tags:
+          type:
+          - array
+          - 'null'
+          items:
+            type: string
+        communicationEntries:
+          description: Embedded CRM log (D25). Stays as array, not subcollection.
+          type:
+          - array
+          - 'null'
+          items:
+            type: object
+            properties:
+              timestamp:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: Firestore Timestamp serialized representation
+              type:
+                type: string
+                description: Communication channel (e.g. phone, email, meeting).
+              summary:
+                type: string
+              staffMember:
+                description: Staff member name involved in this communication.
+                type: string
+            required:
+            - timestamp
+            - type
+            - summary
+            additionalProperties: false
+            description: CRM communication log entry (D25). Embedded array on Customer
+              document.
+        createdAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server-generated creation timestamp.
+          readOnly: true
+        lastOrderDate:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Updated by server when orders are placed.
+        balance:
+          readOnly: true
+          description: (Read-only) Outstanding balance. Dashboard-originated, server-calculated.
+          type:
+          - number
+          - 'null'
+        creditLimit:
+          type:
+          - number
+          - 'null'
+        lastPaymentDate:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Updated by server when payments are recorded.
+        totalPaid:
+          readOnly: true
+          description: (Read-only) Server-calculated total paid amount.
+          type:
+          - number
+          - 'null'
+        totalOwed:
+          readOnly: true
+          description: (Read-only) Server-calculated total owed amount.
+          type:
+          - number
+          - 'null'
+        loyaltyPoints:
+          denormalized: true
+          readOnly: true
+          description: (Read-only, Denormalized) Derived summary from loyalty/status
+            subcollection (D08). Source of truth is LoyaltyStatus.pointsBalance.
+          type:
+          - number
+          - 'null'
+      required:
+      - id
+      - uid
+      - name
+      - createdAt
+      additionalProperties: false
+      description: 'Customer model. Collection: companies/{companyId}/customers/{customerId}.
+        Canonical across all platforms.'
+    CustomerCreate:
+      allOf:
+      - $ref: '#/components/schemas/Customer'
+      description: Write payload for creating a new Customer document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - name
+    CustomerUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Customer'
+      description: Write payload for partial update (PATCH) of a Customer document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    CustomerPayment:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: '(Read-only) Firestore document ID. Note: optional in current
+            schema — some legacy docs may lack this field.'
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Scopes all queries.
+        customerId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Customer.id (Firestore doc ID). Links payment
+            to customer. Set at creation.
+        customerName:
+          denormalized: true
+          description: (Denormalized) From Customer.name at write time.
+          type:
+          - string
+          - 'null'
+        amount:
+          type: number
+        currency:
+          type: string
+          const: XOF
+          description: Currency code. Locked to XOF (West African CFA franc) for now.
+        paymentDate:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: Firestore Timestamp serialized representation
+        paymentMethod:
+          $ref: '#/components/schemas/PaymentMethod'
+          description: Unified payment method set with African + global methods (D02).
+        referenceNumber:
+          type: string
+          description: Unique payment reference (receipt number, transaction ID, etc.).
+        allocatedAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Total amount allocated to bookings/orders/purchases
+            via allocations. Server-calculated.
+        unappliedAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Remaining unallocated amount (amount - allocatedAmount).
+            Server-calculated.
+        status:
+          $ref: '#/components/schemas/CustomerPaymentStatus'
+          description: Customer payment lifecycle status (D22). Tracks allocation
+            progress of received payments.
+        notes:
+          type:
+          - string
+          - 'null'
+        recordedBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who recorded the payment. Required
+            audit field (D22/IG-7).
+        recordedByName:
+          x-immutable: true
+          denormalized: true
+          description: (Immutable, Denormalized) From User display name at creation
+            time.
+          type:
+          - string
+          - 'null'
+        createdAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server-generated creation timestamp.
+          readOnly: true
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+      required:
+      - companyId
+      - customerId
+      - amount
+      - currency
+      - paymentDate
+      - paymentMethod
+      - referenceNumber
+      - allocatedAmount
+      - unappliedAmount
+      - status
+      - recordedBy
+      - createdAt
+      additionalProperties: false
+      description: 'CustomerPayment model (D22). Collection: companies/{companyId}/customerPayments/{paymentId}.
+        Dashboard-only today; Mobile read in Wave 2, write in Wave 4 (trusted-party
+        workflow).'
+    CustomerPaymentCreate:
+      allOf:
+      - $ref: '#/components/schemas/CustomerPayment'
+      description: Write payload for creating a new CustomerPayment document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - customerId
+      - amount
+      - currency
+      - paymentDate
+      - paymentMethod
+      - referenceNumber
+      - status
+      - recordedBy
+    CustomerPaymentUpdate:
+      allOf:
+      - $ref: '#/components/schemas/CustomerPayment'
+      description: Write payload for partial update (PATCH) of a CustomerPayment document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    CustomerPaymentAllocation:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: '(Read-only) Firestore document ID. Note: optional in current
+            schema.'
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        paymentId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → CustomerPayment.id. Parent payment this allocation
+            draws from.
+        customerId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Customer.id (Firestore doc ID).
+        targetId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Booking.id, Order.id, or Sale.id (polymorphic).
+            See targetType for discriminator.
+        targetType:
+          $ref: '#/components/schemas/CustomerPaymentTargetType'
+          description: '(Immutable) Discriminator for targetId: BOOKING, ORDER, or
+            PURCHASE.'
+          x-immutable: true
+        targetReference:
+          type:
+          - string
+          - 'null'
+        allocatedAmount:
+          type: number
+          x-immutable: true
+          description: (Immutable) Amount allocated in this allocation. Set at creation.
+        transferredToAllocationId:
+          description: FK → CustomerPaymentAllocation.id. Self-reference for transfer
+            chains.
+          type:
+          - string
+          - 'null'
+        transferredFromAllocationId:
+          description: FK → CustomerPaymentAllocation.id. Self-reference for transfer
+            chains.
+          type:
+          - string
+          - 'null'
+        transferredAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: Firestore Timestamp serialized representation
+        createdBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who created this allocation.
+        createdByName:
+          x-immutable: true
+          denormalized: true
+          description: (Immutable, Denormalized) From User display name at creation
+            time.
+          type:
+          - string
+          - 'null'
+        createdAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server-generated creation timestamp.
+          readOnly: true
+      required:
+      - companyId
+      - paymentId
+      - customerId
+      - targetId
+      - targetType
+      - allocatedAmount
+      - createdBy
+      - createdAt
+      additionalProperties: false
+      description: 'CustomerPaymentAllocation model. Collection: companies/{companyId}/customerPaymentAllocations/{allocId}.
+        Links customer payments to bookings, orders, or purchases.'
+    CustomerPaymentAllocationCreate:
+      allOf:
+      - $ref: '#/components/schemas/CustomerPaymentAllocation'
+      description: Write payload for creating a new CustomerPaymentAllocation document.
+        Fields marked `readOnly` are server-set and must not be included. Fields marked
+        `x-immutable` may be set once at creation.
+      required:
+      - companyId
+      - paymentId
+      - customerId
+      - targetId
+      - targetType
+      - allocatedAmount
+      - createdBy
+    CustomerPaymentAllocationUpdate:
+      allOf:
+      - $ref: '#/components/schemas/CustomerPaymentAllocation'
+      description: Write payload for partial update (PATCH) of a CustomerPaymentAllocation
+        document. All fields optional. Fields marked `readOnly` or `x-immutable` must
+        not be sent.
+    Event:
+      type: object
+      properties:
+        id:
+          type: string
+          readOnly: true
+          description: '(Read-only) Firestore document ID. Note: Event does not have
+            a uid field.'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Scopes all queries.
+        name:
+          type: string
+        description:
+          type:
+          - string
+          - 'null'
+        location:
+          type:
+          - string
+          - 'null'
+        startDate:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: Firestore Timestamp serialized representation
+        endDate:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: Firestore Timestamp serialized representation
+        status:
+          $ref: '#/components/schemas/EventStatus'
+          description: Event lifecycle status (D32). SCREAMING_SNAKE per D04. MIG-09
+            migrates legacy lowercase values.
+        maxTickets:
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        ticketsSold:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: '(Read-only) Counter: total tickets sold. Updated by Firebase
+            triggers (D28).'
+        ticketsUsed:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: '(Read-only) Counter: tickets scanned/used. Updated by Firebase
+            triggers (D28).'
+        ticketPrice:
+          type:
+          - number
+          - 'null'
+        createdAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server-generated creation timestamp.
+          readOnly: true
+        updatedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server-generated update timestamp.
+          readOnly: true
+        createdBy:
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who created this event.
+          type:
+          - string
+          - 'null'
+      required:
+      - id
+      - companyId
+      - name
+      - startDate
+      - status
+      - ticketsSold
+      - ticketsUsed
+      - createdAt
+      - updatedAt
+      additionalProperties: false
+      description: 'Event model (D26, D32). Collection: companies/{companyId}/events/{eventId}.
+        Mobile-only today; Dashboard in Wave 4.'
+    EventCreate:
+      allOf:
+      - $ref: '#/components/schemas/Event'
+      description: Write payload for creating a new Event document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - name
+      - startDate
+      - status
+    EventUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Event'
+      description: Write payload for partial update (PATCH) of a Event document. All
+        fields optional. Fields marked `readOnly` or `x-immutable` must not be sent.
+    LoyaltyConfig:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID. Singleton doc — typically
+            "config".
+          type:
+          - string
+          - 'null'
+        isEnabled:
+          type: boolean
+        pointSystem:
+          type: string
+          enum:
+          - SPENDING
+          - PRODUCT
+          - VISIT
+          description: 'How points are earned: SPENDING (per currency spent), PRODUCT
+            (per product purchased), or VISIT (per visit). SCREAMING_SNAKE per D04.'
+        pointsPerCurrency:
+          description: '[Deprecated alias: pointsPerCurrencyUnit — renamed by MIG-06]'
+          deprecated: true
+          type:
+          - number
+          - 'null'
+        pointsPerVisit:
+          description: Points earned per visit (when pointSystem is visit).
+          type:
+          - number
+          - 'null'
+        pointValue:
+          description: Monetary value of one point for redemption.
+          type:
+          - number
+          - 'null'
+        minimumRedeemPoints:
+          description: Minimum points balance required before redemption is allowed.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        welcomeBonusPoints:
+          description: One-time points bonus for new loyalty enrollees.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        pointsExpirationDays:
+          description: '[Deprecated alias: pointsExpiryMonths — renamed and converted
+            months*30 to days by MIG-06]'
+          deprecated: true
+          anyOf:
+          - type: integer
+            minimum: -9007199254740991
+            maximum: 9007199254740991
+          - type: 'null'
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated creation timestamp.
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+      required:
+      - isEnabled
+      - pointSystem
+      additionalProperties: false
+      description: 'LoyaltyConfig model (D21). Collection: companies/{companyId}/loyaltySettings/config.
+        1 doc per company. Uses canonical field names per D21 (MIG-06 renames legacy
+        aliases).'
+    LoyaltyConfigCreate:
+      allOf:
+      - $ref: '#/components/schemas/LoyaltyConfig'
+      description: Write payload for creating a new LoyaltyConfig document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - isEnabled
+      - pointSystem
+    LoyaltyConfigUpdate:
+      allOf:
+      - $ref: '#/components/schemas/LoyaltyConfig'
+      description: Write payload for partial update (PATCH) of a LoyaltyConfig document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    LoyaltyReward:
+      type: object
+      properties:
+        id:
+          type: string
+          readOnly: true
+          description: (Read-only) Firestore document ID.
+        name:
+          type: string
+        description:
+          type:
+          - string
+          - 'null'
+        pointsRequired:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Points cost to redeem this reward.
+        isActive:
+          type: boolean
+          description: Whether this reward is currently available for redemption.
+        imageUrl:
+          type:
+          - string
+          - 'null'
+        rewardType:
+          description: Category of reward (e.g. discount, free_item, service).
+          type:
+          - string
+          - 'null'
+        discountValue:
+          description: Discount amount when rewardType is discount.
+          type:
+          - number
+          - 'null'
+        productId:
+          description: FK → Product.id. Linked product when rewardType is free_item.
+          type:
+          - string
+          - 'null'
+        createdAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server-generated creation timestamp.
+          readOnly: true
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+      required:
+      - id
+      - name
+      - pointsRequired
+      - isActive
+      - createdAt
+      additionalProperties: false
+      description: 'LoyaltyReward model. Collection: companies/{companyId}/loyaltyRewards/{rewardId}.
+        Reward catalog for point redemption (IG-10).'
+    LoyaltyRewardCreate:
+      allOf:
+      - $ref: '#/components/schemas/LoyaltyReward'
+      description: Write payload for creating a new LoyaltyReward document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - name
+      - pointsRequired
+      - isActive
+    LoyaltyRewardUpdate:
+      allOf:
+      - $ref: '#/components/schemas/LoyaltyReward'
+      description: Write payload for partial update (PATCH) of a LoyaltyReward document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    LoyaltyStatus:
+      type: object
+      properties:
+        customerId:
+          x-immutable: true
+          description: '(Immutable) FK → Customer.id. Note: optional despite being
+            in customer subcollection (path already contains custId).'
+          type:
+          - string
+          - 'null'
+        pointsBalance:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: '(Read-only) Current available points balance. Canonical name
+            (D08). Dashboard: pointsBalance, Mobile: currentPoints. Updated by transaction
+            triggers.'
+        totalPointsEarned:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: '(Read-only) Lifetime total points earned. Canonical name (D08).
+            Dashboard: totalPointsEarned, Mobile: lifetimePoints. Updated by transaction
+            triggers.'
+        redeemedPoints:
+          readOnly: true
+          description: (Read-only) Total redeemed points. Updated by transaction triggers.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        lastActivityDate:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: '(Read-only) Last earn/redeem activity. Canonical name (D08).
+            Mobile alias: lastEarnedAt.'
+        lastRedeemedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Last redemption timestamp.
+        tier:
+          type:
+          - string
+          - 'null'
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated creation timestamp.
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+      required:
+      - pointsBalance
+      - totalPointsEarned
+      additionalProperties: false
+      description: 'LoyaltyStatus model (D08). Collection: companies/{companyId}/customers/{custId}/loyalty/status.
+        Source of truth for customer points. Customer doc loyaltyPoints is a derived
+        summary only.'
+    LoyaltyTransaction:
+      type: object
+      properties:
+        id:
+          type: string
+          readOnly: true
+          description: (Read-only) Firestore document ID.
+        customerId:
+          x-immutable: true
+          description: '(Immutable) FK → Customer.id. Note: optional despite being
+            in customer subcollection.'
+          type:
+          - string
+          - 'null'
+        type:
+          $ref: '#/components/schemas/LoyaltyTransactionType'
+          description: (Immutable) Transaction type (D07). SCREAMING_SNAKE per D04.
+            MIG-05 migrates legacy lowercase values.
+          x-immutable: true
+        pointsChange:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          x-immutable: true
+          description: '(Immutable) Points delta (+/-). Canonical name (D07). Dashboard:
+            pointsChange, Mobile: points.'
+        description:
+          type:
+          - string
+          - 'null'
+        reason:
+          type:
+          - string
+          - 'null'
+        relatedPurchaseId:
+          x-immutable: true
+          description: (Immutable) FK → Sale.id. Linked sale that triggered this transaction.
+          type:
+          - string
+          - 'null'
+        relatedOrderId:
+          x-immutable: true
+          description: (Immutable) FK → Order.id. Linked order that triggered this
+            transaction.
+          type:
+          - string
+          - 'null'
+        relatedRewardId:
+          x-immutable: true
+          description: (Immutable) FK → LoyaltyReward.id. Reward redeemed in this
+            transaction.
+          type:
+          - string
+          - 'null'
+        orderId:
+          x-immutable: true
+          description: '(Immutable) FK → Order.id. Note: may overlap with relatedOrderId
+            — naming inconsistency from Mobile.'
+          type:
+          - string
+          - 'null'
+        sessionId:
+          description: Session/booking reference. Context-dependent identifier.
+          type:
+          - string
+          - 'null'
+        orderAmount:
+          type:
+          - number
+          - 'null'
+        transactionDate:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: '(Immutable) When the transaction occurred. Canonical name
+            (D07). Dashboard: transactionDate, Mobile: createdAt.'
+          x-immutable: true
+        pointsBalanceAfter:
+          readOnly: true
+          description: '(Read-only) Running balance after this transaction. Canonical
+            name (D07). Dashboard: pointsBalanceAfter, Mobile: balanceAfter. Server-calculated.'
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        createdBy:
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who created this transaction.
+          type:
+          - string
+          - 'null'
+        createdByName:
+          x-immutable: true
+          denormalized: true
+          description: (Immutable, Denormalized) From User display name at creation
+            time.
+          type:
+          - string
+          - 'null'
+      required:
+      - id
+      - type
+      - pointsChange
+      - transactionDate
+      additionalProperties: false
+      description: 'LoyaltyTransaction model (D07). Collection: companies/{companyId}/customers/{custId}/loyaltyTransactions/{txId}.
+        Type values use SCREAMING_SNAKE per D04 (MIG-05 migrates lowercase).'
+    LoyaltyTransactionCreate:
+      allOf:
+      - $ref: '#/components/schemas/LoyaltyTransaction'
+      description: Write payload for creating a new LoyaltyTransaction document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - type
+      - pointsChange
+      - transactionDate
+    LoyaltyTransactionUpdate:
+      allOf:
+      - $ref: '#/components/schemas/LoyaltyTransaction'
+      description: Write payload for partial update (PATCH) of a LoyaltyTransaction
+        document. All fields optional. Fields marked `readOnly` or `x-immutable` must
+        not be sent.
+    MetricsCurrent:
+      type: object
+      properties:
+        todayOrdersCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Orders created today (UTC). Resets at midnight.
+        pendingOrdersCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Orders currently in PENDING status (all-time cumulative).
+            Corrected by full recalc on order updates.
+        orderCompletionRate30d:
+          type: number
+          readOnly: true
+          description: (Read-only) Percentage of orders completed or delivered in
+            the last 30 days. Always full recalc.
+        todayPurchasesCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Purchases created today (UTC). Resets at midnight.
+        todayPurchasesSum:
+          type: number
+          readOnly: true
+          description: (Read-only) Total value of purchases created today (UTC). Resets
+            at midnight.
+        averagePurchaseAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Average purchase value across last 200 purchases
+            (rolling, not time-windowed).
+        monthlyRevenue:
+          type: number
+          readOnly: true
+          description: (Read-only) Total purchase value in the current calendar month
+            (UTC).
+        monthlyPurchasesCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Number of purchases in the current calendar month
+            (UTC).
+        todayBookingsCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Bookings with date == today AND status in [PENDING,
+            CONFIRMED]. Resets at midnight.
+        bookingsCreatedToday:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Bookings with createdAt today (all statuses). Resets
+            at midnight.
+        todayBookingsConfirmedAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for bookings created today with
+            status CONFIRMED or COMPLETED. Resets at midnight.
+        monthlyBookingsConfirmedAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for bookings created this month
+            with status CONFIRMED or COMPLETED.
+        todayCollectedAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT
+            is today. Resets at midnight.
+        todayRevenue:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for COMPLETED bookings where
+            startDate == endDate == today (numeric YYYYMMDD). Resets at midnight.
+        bookingsPendingPaymentVerification:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Bookings with status PENDING/CANCELLATION_REQUESTED
+            and a payment proof uploaded but not yet verified. Current state, always
+            full recalc.
+        bookingsPendingValidation:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) PENDING bookings with startDate within ±30 days
+            of today. Rolling window, always full recalc.
+        bookingsPendingValidation24h:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) PENDING bookings created in the last 24h with startDate
+            >= tomorrow. Always full recalc.
+        customersCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Total customer count (all-time cumulative).
+        newCustomersThisMonth:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Customers with createdAt in the current calendar
+            month (UTC).
+        averageRating:
+          type: number
+          readOnly: true
+          description: (Read-only) Average rating from the last 200 reviews (rolling).
+            Always full recalc.
+        lowStockItemsCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Active stock items where currentQuantity <= minimumQuantity.
+            Current state, always full recalc.
+        activeRecurringPaymentsCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Recurring payments with status ACTIVE. Current
+            state, always full recalc.
+        monthlyRecurringRevenue:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments.
+            Always full recalc.
+        computedForDay:
+          type: string
+          readOnly: true
+          description: (Read-only) YYYY-MM-DD string indicating which day these metrics
+            reflect. Used to detect day boundaries and trigger midnight resets.
+        generatedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server timestamp of the last metrics write.
+          readOnly: true
+      required:
+      - todayOrdersCount
+      - pendingOrdersCount
+      - orderCompletionRate30d
+      - todayPurchasesCount
+      - todayPurchasesSum
+      - averagePurchaseAmount
+      - monthlyRevenue
+      - monthlyPurchasesCount
+      - todayBookingsCount
+      - bookingsCreatedToday
+      - todayBookingsConfirmedAmount
+      - monthlyBookingsConfirmedAmount
+      - todayCollectedAmount
+      - todayRevenue
+      - bookingsPendingPaymentVerification
+      - bookingsPendingValidation
+      - bookingsPendingValidation24h
+      - customersCount
+      - newCustomersThisMonth
+      - averageRating
+      - lowStockItemsCount
+      - activeRecurringPaymentsCount
+      - monthlyRecurringRevenue
+      - computedForDay
+      - generatedAt
+      additionalProperties: false
+      description: 'Server-computed company metrics. Collection: companies/{companyId}/metrics/current
+        (singleton). All fields are server-set — clients must never write to this
+        collection. See also MetricsDaily and MetricsMonthly for historical snapshots.'
+    MetricsCurrentCreate:
+      allOf:
+      - $ref: '#/components/schemas/MetricsCurrent'
+      description: Write payload for creating a new MetricsCurrent document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+    MetricsCurrentUpdate:
+      allOf:
+      - $ref: '#/components/schemas/MetricsCurrent'
+      description: Write payload for partial update (PATCH) of a MetricsCurrent document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    MetricsDaily:
+      type: object
+      properties:
+        todayOrdersCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Orders created today (UTC). Resets at midnight.
+        pendingOrdersCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Orders currently in PENDING status (all-time cumulative).
+            Corrected by full recalc on order updates.
+        orderCompletionRate30d:
+          type: number
+          readOnly: true
+          description: (Read-only) Percentage of orders completed or delivered in
+            the last 30 days. Always full recalc.
+        todayPurchasesCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Purchases created today (UTC). Resets at midnight.
+        todayPurchasesSum:
+          type: number
+          readOnly: true
+          description: (Read-only) Total value of purchases created today (UTC). Resets
+            at midnight.
+        averagePurchaseAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Average purchase value across last 200 purchases
+            (rolling, not time-windowed).
+        monthlyRevenue:
+          type: number
+          readOnly: true
+          description: (Read-only) Total purchase value in the current calendar month
+            (UTC).
+        monthlyPurchasesCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Number of purchases in the current calendar month
+            (UTC).
+        todayBookingsCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Bookings with date == today AND status in [PENDING,
+            CONFIRMED]. Resets at midnight.
+        bookingsCreatedToday:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Bookings with createdAt today (all statuses). Resets
+            at midnight.
+        todayBookingsConfirmedAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for bookings created today with
+            status CONFIRMED or COMPLETED. Resets at midnight.
+        monthlyBookingsConfirmedAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for bookings created this month
+            with status CONFIRMED or COMPLETED.
+        todayCollectedAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT
+            is today. Resets at midnight.
+        todayRevenue:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for COMPLETED bookings where
+            startDate == endDate == today (numeric YYYYMMDD). Resets at midnight.
+        bookingsPendingPaymentVerification:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Bookings with status PENDING/CANCELLATION_REQUESTED
+            and a payment proof uploaded but not yet verified. Current state, always
+            full recalc.
+        bookingsPendingValidation:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) PENDING bookings with startDate within ±30 days
+            of today. Rolling window, always full recalc.
+        bookingsPendingValidation24h:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) PENDING bookings created in the last 24h with startDate
+            >= tomorrow. Always full recalc.
+        customersCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Total customer count (all-time cumulative).
+        newCustomersThisMonth:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Customers with createdAt in the current calendar
+            month (UTC).
+        averageRating:
+          type: number
+          readOnly: true
+          description: (Read-only) Average rating from the last 200 reviews (rolling).
+            Always full recalc.
+        lowStockItemsCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Active stock items where currentQuantity <= minimumQuantity.
+            Current state, always full recalc.
+        activeRecurringPaymentsCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Recurring payments with status ACTIVE. Current
+            state, always full recalc.
+        monthlyRecurringRevenue:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments.
+            Always full recalc.
+        computedForDay:
+          type: string
+          readOnly: true
+          description: (Read-only) YYYY-MM-DD string indicating which day these metrics
+            reflect. Used to detect day boundaries and trigger midnight resets.
+        generatedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server timestamp of the last metrics write.
+          readOnly: true
+        date:
+          type: string
+          readOnly: true
+          description: (Read-only) YYYY-MM-DD document ID repeated as a field. Identifies
+            the day this snapshot covers.
+      required:
+      - todayOrdersCount
+      - pendingOrdersCount
+      - orderCompletionRate30d
+      - todayPurchasesCount
+      - todayPurchasesSum
+      - averagePurchaseAmount
+      - monthlyRevenue
+      - monthlyPurchasesCount
+      - todayBookingsCount
+      - bookingsCreatedToday
+      - todayBookingsConfirmedAmount
+      - monthlyBookingsConfirmedAmount
+      - todayCollectedAmount
+      - todayRevenue
+      - bookingsPendingPaymentVerification
+      - bookingsPendingValidation
+      - bookingsPendingValidation24h
+      - customersCount
+      - newCustomersThisMonth
+      - averageRating
+      - lowStockItemsCount
+      - activeRecurringPaymentsCount
+      - monthlyRecurringRevenue
+      - computedForDay
+      - generatedAt
+      - date
+      additionalProperties: false
+      description: 'Daily metrics snapshot. Collection: companies/{companyId}/metrics_daily/{YYYY-MM-DD}.
+        Same fields as MetricsCurrent plus `date`. Written by computeDailyCompanyMetrics
+        cron (02:00 UTC) and inline after full recalcs.'
+    MetricsDailyCreate:
+      allOf:
+      - $ref: '#/components/schemas/MetricsDaily'
+      description: Write payload for creating a new MetricsDaily document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+    MetricsDailyUpdate:
+      allOf:
+      - $ref: '#/components/schemas/MetricsDaily'
+      description: Write payload for partial update (PATCH) of a MetricsDaily document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    MetricsMonthly:
+      type: object
+      properties:
+        todayOrdersCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Orders created today (UTC). Resets at midnight.
+        pendingOrdersCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Orders currently in PENDING status (all-time cumulative).
+            Corrected by full recalc on order updates.
+        orderCompletionRate30d:
+          type: number
+          readOnly: true
+          description: (Read-only) Percentage of orders completed or delivered in
+            the last 30 days. Always full recalc.
+        todayPurchasesCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Purchases created today (UTC). Resets at midnight.
+        todayPurchasesSum:
+          type: number
+          readOnly: true
+          description: (Read-only) Total value of purchases created today (UTC). Resets
+            at midnight.
+        averagePurchaseAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Average purchase value across last 200 purchases
+            (rolling, not time-windowed).
+        monthlyRevenue:
+          type: number
+          readOnly: true
+          description: (Read-only) Total purchase value in the current calendar month
+            (UTC).
+        monthlyPurchasesCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Number of purchases in the current calendar month
+            (UTC).
+        todayBookingsCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Bookings with date == today AND status in [PENDING,
+            CONFIRMED]. Resets at midnight.
+        bookingsCreatedToday:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Bookings with createdAt today (all statuses). Resets
+            at midnight.
+        todayBookingsConfirmedAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for bookings created today with
+            status CONFIRMED or COMPLETED. Resets at midnight.
+        monthlyBookingsConfirmedAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for bookings created this month
+            with status CONFIRMED or COMPLETED.
+        todayCollectedAmount:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT
+            is today. Resets at midnight.
+        todayRevenue:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of totalAmount for COMPLETED bookings where
+            startDate == endDate == today (numeric YYYYMMDD). Resets at midnight.
+        bookingsPendingPaymentVerification:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Bookings with status PENDING/CANCELLATION_REQUESTED
+            and a payment proof uploaded but not yet verified. Current state, always
+            full recalc.
+        bookingsPendingValidation:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) PENDING bookings with startDate within ±30 days
+            of today. Rolling window, always full recalc.
+        bookingsPendingValidation24h:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) PENDING bookings created in the last 24h with startDate
+            >= tomorrow. Always full recalc.
+        customersCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Total customer count (all-time cumulative).
+        newCustomersThisMonth:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Customers with createdAt in the current calendar
+            month (UTC).
+        averageRating:
+          type: number
+          readOnly: true
+          description: (Read-only) Average rating from the last 200 reviews (rolling).
+            Always full recalc.
+        lowStockItemsCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Active stock items where currentQuantity <= minimumQuantity.
+            Current state, always full recalc.
+        activeRecurringPaymentsCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Recurring payments with status ACTIVE. Current
+            state, always full recalc.
+        monthlyRecurringRevenue:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments.
+            Always full recalc.
+        computedForDay:
+          type: string
+          readOnly: true
+          description: (Read-only) YYYY-MM-DD string indicating which day these metrics
+            reflect. Used to detect day boundaries and trigger midnight resets.
+        generatedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server timestamp of the last metrics write.
+          readOnly: true
+        month:
+          type: string
+          readOnly: true
+          description: (Read-only) YYYY-MM document ID repeated as a field. Identifies
+            the month this rollup covers.
+      required:
+      - todayOrdersCount
+      - pendingOrdersCount
+      - orderCompletionRate30d
+      - todayPurchasesCount
+      - todayPurchasesSum
+      - averagePurchaseAmount
+      - monthlyRevenue
+      - monthlyPurchasesCount
+      - todayBookingsCount
+      - bookingsCreatedToday
+      - todayBookingsConfirmedAmount
+      - monthlyBookingsConfirmedAmount
+      - todayCollectedAmount
+      - todayRevenue
+      - bookingsPendingPaymentVerification
+      - bookingsPendingValidation
+      - bookingsPendingValidation24h
+      - customersCount
+      - newCustomersThisMonth
+      - averageRating
+      - lowStockItemsCount
+      - activeRecurringPaymentsCount
+      - monthlyRecurringRevenue
+      - computedForDay
+      - generatedAt
+      - month
+      additionalProperties: false
+      description: 'Monthly metrics rollup. Collection: companies/{companyId}/metrics_monthly/{YYYY-MM}.
+        Same fields as MetricsCurrent plus `month`. Written alongside daily snapshots;
+        reflects state at last full recalc within the month.'
+    MetricsMonthlyCreate:
+      allOf:
+      - $ref: '#/components/schemas/MetricsMonthly'
+      description: Write payload for creating a new MetricsMonthly document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+    MetricsMonthlyUpdate:
+      allOf:
+      - $ref: '#/components/schemas/MetricsMonthly'
+      description: Write payload for partial update (PATCH) of a MetricsMonthly document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    Order:
+      type: object
+      properties:
+        id:
+          type: string
+          readOnly: true
+          description: '(Read-only) Firestore document ID. Note: some models also
+            have uid; see ID conventions.'
+        uid:
+          type: string
+          readOnly: true
+          description: (Read-only) Entity UID. Often mirrors id.
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Scopes all queries.
+        orderNumber:
+          type: string
+          readOnly: true
+          description: (Read-only) Server-generated order number.
+        status:
+          $ref: '#/components/schemas/OrderStatus'
+          description: Core lifecycle status (D34, MIG-11). See OrderStatus enum for
+            the legacy value migration mapping.
+          x-migration:
+            source: Dashboard flat 20-value OrderStatus
+            migration: MIG-11
+            note: REFUND_PROCESSING and REFUNDED map to paymentStatus, not returnStatus
+              — an order can be refunded without a physical return.
+            mapping:
+            - old: PENDING
+              status: PENDING
+            - old: CONFIRMED
+              status: CONFIRMED
+            - old: PROCESSING
+              status: PROCESSING
+            - old: READY
+              status: READY
+            - old: COMPLETED
+              status: COMPLETED
+            - old: CANCELLED
+              status: CANCELLED
+            - old: EXPIRED
+              status: EXPIRED
+            - old: AWAITING_PAYMENT
+              status: PENDING
+              paymentStatus: PENDING
+            - old: SHIPPED
+              status: PROCESSING
+              fulfillmentStatus: SHIPPED
+            - old: PARTIALLY_SHIPPED
+              status: PROCESSING
+              fulfillmentStatus: PARTIALLY_SHIPPED
+            - old: ON_THE_WAY
+              status: PROCESSING
+              fulfillmentStatus: IN_TRANSIT
+            - old: DELIVERED
+              status: COMPLETED
+              fulfillmentStatus: DELIVERED
+            - old: PICKED_UP
+              status: COMPLETED
+              fulfillmentStatus: PICKED_UP
+            - old: RETURN_REQUESTED
+              status: COMPLETED
+              returnStatus: RETURN_REQUESTED
+            - old: RETURN_PROCESSING
+              status: COMPLETED
+              returnStatus: RETURN_PROCESSING
+            - old: RETURNED
+              status: COMPLETED
+              returnStatus: RETURNED
+            - old: EXCHANGE_REQUESTED
+              status: COMPLETED
+              returnStatus: EXCHANGE_REQUESTED
+            - old: EXCHANGE_PROCESSING
+              status: COMPLETED
+              returnStatus: EXCHANGE_PROCESSING
+            - old: EXCHANGE_COMPLETED
+              status: COMPLETED
+              returnStatus: EXCHANGE_COMPLETED
+            - old: REFUND_PROCESSING
+              status: COMPLETED
+              paymentStatus: REFUND_PROCESSING
+            - old: REFUNDED
+              status: COMPLETED
+              paymentStatus: REFUNDED
+        paymentStatus:
+          anyOf:
+          - $ref: '#/components/schemas/PaymentStatus'
+          - type: 'null'
+          description: Payment lifecycle (D34). Null until payment is initiated.
+        fulfillmentStatus:
+          anyOf:
+          - $ref: '#/components/schemas/FulfillmentStatus'
+          - type: 'null'
+          x-when: Null for ON_SITE and PICK_UP orders. Set when deliveryType is DELIVERY
+            and a physical shipment or pickup is involved.
+          x-see:
+            decisions:
+            - D34
+          description: Delivery/fulfillment lifecycle (D34).
+        returnStatus:
+          anyOf:
+          - $ref: '#/components/schemas/ReturnStatus'
+          - type: 'null'
+          description: Return/exchange lifecycle (D34). Null until a return or exchange
+            is initiated.
+        deliveryType:
+          anyOf:
+          - $ref: '#/components/schemas/DeliveryType'
+          - type: 'null'
+          x-note: Drives whether fulfillmentStatus is relevant. ON_SITE and PICK_UP
+            orders typically have no fulfillmentStatus.
+          description: Fulfillment channel for this order (ON_SITE, PICK_UP, DELIVERY).
+        paymentMethod:
+          anyOf:
+          - $ref: '#/components/schemas/PaymentMethod'
+          - type: 'null'
+          description: Unified payment method set with African + global methods (D02).
+        invoiceId:
+          description: FK → Invoice document ID.
+          type:
+          - string
+          - 'null'
+        customerId:
+          description: FK → Customer.id (Firestore doc ID). Used to resolve customer
+            details.
+          type:
+          - string
+          - 'null'
+        customerName:
+          denormalized: true
+          description: (Denormalized) From Customer.name at write time.
+          type:
+          - string
+          - 'null'
+        customerEmail:
+          denormalized: true
+          description: (Denormalized) From Customer.email at write time. Canonical
+            field per D24.
+          type:
+          - string
+          - 'null'
+        customerPhone:
+          denormalized: true
+          description: (Denormalized) From Customer.phone at write time. Canonical
+            field per D24.
+          type:
+          - string
+          - 'null'
+        clientEmail:
+          denormalized: true
+          deprecated: true
+          x-replaced-by: customerEmail
+          description: (Denormalized) Legacy — use `customerEmail`. D24 standardized
+            to customer* prefix.
+          type:
+          - string
+          - 'null'
+        clientPhoneNumber:
+          denormalized: true
+          deprecated: true
+          x-replaced-by: customerPhone
+          description: (Denormalized) Legacy — use `customerPhone`. D24 standardized
+            to customer* prefix.
+          type:
+          - string
+          - 'null'
+        items:
+          type:
+          - array
+          - 'null'
+          items:
+            $ref: '#/components/schemas/OrderItem'
+            description: 'Line item within an Order or Sale/Purchase. Canonical fields:
+              name, quantity, price, productId. Optional commerce fields (increment,
+              variantId, supplierId, supplierName) and kitchen tracking fields (sentAt,
+              startedCookingAt, readyAt, servedAt) are TBD/WIP pending cross-platform
+              alignment.'
+        amount:
+          type: number
+          description: Total order amount. Canonical field for the order total.
+        amountPaid:
+          description: Amount of `amount` paid to date. Derived from payment allocations.
+          type:
+          - number
+          - 'null'
+        total:
+          deprecated: true
+          x-replaced-by: amount
+          x-note: Sent by Mobile only. Mirrors `amount`. Use `amount` for all new
+            writes. Pending deduplication cleanup.
+          description: Mobile-only legacy total field. Deprecated — use `amount`.
+          type:
+          - number
+          - 'null'
+        createdAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server-generated creation timestamp.
+          readOnly: true
+        orderDate:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: Firestore Timestamp serialized representation
+        PROCESSING_ON:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          x-note: Never write this field directly. The server sets it automatically
+            on status transition to PROCESSING.
+          x-see:
+            decisions:
+            - D04
+            migrations:
+            - MIG-01
+          description: (Read-only) Timestamp when order entered PROCESSING (D04 SCREAMING_SNAKE).
+            MIG-01 renames from camelCase.
+        COMPLETED_ON:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Timestamp when order completed (D04 SCREAMING_SNAKE).
+            MIG-01 renames from camelCase.
+        CANCELLED_ON:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Timestamp when order cancelled (D04 SCREAMING_SNAKE).
+            MIG-01 renames from camelCase.
+        cancellationReason:
+          type:
+          - string
+          - 'null'
+        shippingCarrier:
+          type:
+          - string
+          - 'null'
+        trackingNumber:
+          type:
+          - string
+          - 'null'
+        estimatedDeliveryDate:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: Firestore Timestamp serialized representation
+        shippingCost:
+          type:
+          - number
+          - 'null'
+        paymentProofUrl:
+          description: URL to uploaded payment proof image/document.
+          type:
+          - string
+          - 'null'
+        paymentProofStatus:
+          anyOf:
+          - $ref: '#/components/schemas/PaymentProofStatus'
+          - type: 'null'
+          description: Payment proof review status.
+        paymentProofAddedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Timestamp when proof was uploaded.
+        paymentProofAddedBy:
+          description: FK → User/staff UID who uploaded the payment proof.
+          type:
+          - string
+          - 'null'
+        paymentProofReviewedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Timestamp when proof was reviewed.
+        paymentProofReviewedBy:
+          description: FK → User/staff UID who reviewed the payment proof.
+          type:
+          - string
+          - 'null'
+        paymentProofRejectionReason:
+          type:
+          - string
+          - 'null'
+        paymentStatusChangeReason:
+          type:
+          - string
+          - 'null'
+        paymentStatusChangedBy:
+          description: FK → User/staff UID who changed payment status.
+          type:
+          - string
+          - 'null'
+        paymentStatusChangedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Timestamp of last payment status change.
+        payments:
+          x-note: Shape and sync rules are TBD pending IG-4 resolution. Do not build
+            production logic against this field until IG-4 is closed.
+          x-see:
+            issues:
+            - IG-4
+          description: '[TBD/WIP — IG-4] Denormalized snapshots of CustomerPayments
+            allocated to this order. Sync rules pending IG-4 resolution.'
+          type:
+          - array
+          - 'null'
+          items:
+            type: object
+            properties:
+              paymentId:
+                type: string
+                x-immutable: true
+                description: (Immutable) FK → CustomerPayment.id. Source document
+                  for this snapshot.
+              amount:
+                type: number
+                description: Total payment amount.
+              currency:
+                type: string
+                const: XOF
+                description: Currency code. Locked to XOF.
+              paymentMethod:
+                $ref: '#/components/schemas/PaymentMethod'
+                description: Payment method used (D02).
+              paymentDate:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: Firestore Timestamp serialized representation
+              referenceNumber:
+                description: Payment reference (receipt number, transaction ID, etc.).
+                type: string
+              status:
+                $ref: '#/components/schemas/CustomerPaymentStatus'
+                description: Payment status at time of snapshot. May lag CustomerPayment.status
+                  until re-synced.
+            required:
+            - paymentId
+            - amount
+            - currency
+            - paymentMethod
+            - paymentDate
+            - status
+            additionalProperties: false
+            description: '[TBD/WIP — IG-4] Denormalized payment snapshot. Subset of
+              CustomerPayment (D22), written when a payment is allocated to this order.
+              Sync rules pending IG-4 resolution.'
+        totalOverridden:
+          x-when: Set only by the mobile app when the user manually edits the order
+            total. Dashboard and Cloud Functions should treat this field as read-only.
+          x-see:
+            decisions:
+            - D14
+          description: Mobile-only. When true, total was manually overridden by user
+            (D14).
+          type:
+          - boolean
+          - 'null'
+        notes:
+          type:
+          - array
+          - 'null'
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+                readOnly: true
+                description: (Read-only) Note ID. Server-generated.
+              text:
+                type: string
+              createdAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: (Read-only) Firestore Timestamp serialized representation.
+                readOnly: true
+              createdBy:
+                x-immutable: true
+                description: (Immutable) FK → User/staff UID who created this note.
+                type: string
+              createdByName:
+                denormalized: true
+                description: (Denormalized) From User display name at write time.
+                type: string
+            required:
+            - id
+            - text
+            - createdAt
+            additionalProperties: false
+            description: Timestamped note attached to an Order.
+        additionalInfo:
+          type:
+          - string
+          - 'null'
+        appliedDiscountCode:
+          type:
+          - string
+          - 'null'
+        purchaseId:
+          description: FK → Sale.id. Link to associated Sale document.
+          type:
+          - string
+          - 'null'
+      required:
+      - id
+      - uid
+      - companyId
+      - orderNumber
+      - status
+      - amount
+      - createdAt
+      - orderDate
+      additionalProperties: false
+      description: 'Order model (D34). Collection: companies/{companyId}/orders/{orderId}.
+        Status decomposed into 4 orthogonal fields per D34: status (OrderStatus),
+        paymentStatus, fulfillmentStatus, returnStatus. deliveryType determines the
+        fulfillment channel. MIG-11 migrates the old flat 20-value enum.'
+    OrderCreate:
+      allOf:
+      - $ref: '#/components/schemas/Order'
+      description: Write payload for creating a new Order document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - status
+      - amount
+      - orderDate
+    OrderUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Order'
+      description: Write payload for partial update (PATCH) of a Order document. All
+        fields optional. Fields marked `readOnly` or `x-immutable` must not be sent.
+    OrderItem:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Display name of the product or service.
+        quantity:
+          type: number
+          description: Number of units ordered.
+        price:
+          type: number
+          description: Unit price. Canonical name per D11.
+        productId:
+          description: FK → Product document ID.
+          type:
+          - string
+          - 'null'
+        increment:
+          x-note: TBD/WIP — Dashboard/Firebase only. Canonical status pending cross-platform
+            alignment.
+          description: Quantity step for bundle/bulk items (e.g. 5 for a 5-pack).
+            Dashboard/Firebase only.
+          type:
+          - number
+          - 'null'
+        variantId:
+          x-note: TBD/WIP — Dashboard/Firebase only. Canonical status pending cross-platform
+            alignment.
+          description: FK → ProductVariant ID within the product. Dashboard/Firebase
+            only.
+          type:
+          - string
+          - 'null'
+        supplierId:
+          x-note: TBD/WIP — B2B orders only. Canonical status pending cross-platform
+            alignment.
+          description: FK → Supplier document ID. B2B orders only.
+          type:
+          - string
+          - 'null'
+        supplierName:
+          denormalized: true
+          x-note: TBD/WIP — B2B orders only. Canonical status pending cross-platform
+            alignment.
+          description: (Denormalized) From Supplier.name at write time. B2B orders
+            only.
+          type:
+          - string
+          - 'null'
+        sentAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          x-note: TBD/WIP — Originally from the archived Couchbase Lite (CBL) restaurant
+            flow. Canonical inclusion in Firestore model is pending review.
+          description: (Read-only) Timestamp when the item was sent to the kitchen.
+            TBD/WIP — archived CBL flow.
+        startedCookingAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          x-note: TBD/WIP — Originally from the archived Couchbase Lite (CBL) restaurant
+            flow. Canonical inclusion in Firestore model is pending review.
+          description: (Read-only) Timestamp when the kitchen started preparing this
+            item. TBD/WIP — archived CBL flow.
+        readyAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          x-note: TBD/WIP — Originally from the archived Couchbase Lite (CBL) restaurant
+            flow. Canonical inclusion in Firestore model is pending review.
+          description: (Read-only) Timestamp when the item was ready for pickup or
+            service. TBD/WIP — archived CBL flow.
+        servedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          x-note: TBD/WIP — Originally from the archived Couchbase Lite (CBL) restaurant
+            flow. Canonical inclusion in Firestore model is pending review.
+          description: (Read-only) Timestamp when the item was served to the customer.
+            TBD/WIP — archived CBL flow.
+      required:
+      - name
+      - quantity
+      - price
+      additionalProperties: false
+      description: 'Line item within an Order or Sale/Purchase. Canonical fields:
+        name, quantity, price, productId. Optional commerce fields (increment, variantId,
+        supplierId, supplierName) and kitchen tracking fields (sentAt, startedCookingAt,
+        readyAt, servedAt) are TBD/WIP pending cross-platform alignment.'
+    OrderItemCreate:
+      allOf:
+      - $ref: '#/components/schemas/OrderItem'
+      description: Write payload for creating a new OrderItem document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - name
+      - quantity
+      - price
+    OrderItemUpdate:
+      allOf:
+      - $ref: '#/components/schemas/OrderItem'
+      description: Write payload for partial update (PATCH) of a OrderItem document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    Sale:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: '(Read-only) Firestore document ID. Note: optional in current
+            schema — some legacy docs may lack this field.'
+          type:
+          - string
+          - 'null'
+        companyId:
+          x-immutable: true
+          description: '(Immutable) FK → Company document ID. Note: optional in current
+            schema — should be required (see ID consistency audit).'
+          type:
+          - string
+          - 'null'
+        customerId:
+          description: FK → Customer.id (Firestore doc ID).
+          type:
+          - string
+          - 'null'
+        customerName:
+          denormalized: true
+          description: (Denormalized) From Customer.name at write time.
+          type:
+          - string
+          - 'null'
+        amount:
+          type:
+          - number
+          - 'null'
+        items:
+          description: Line items. Reuses Order item schema.
+          type:
+          - array
+          - 'null'
+          items:
+            $ref: '#/components/schemas/OrderItem'
+            description: 'Line item within an Order or Sale/Purchase. Canonical fields:
+              name, quantity, price, productId. Optional commerce fields (increment,
+              variantId, supplierId, supplierName) and kitchen tracking fields (sentAt,
+              startedCookingAt, readyAt, servedAt) are TBD/WIP pending cross-platform
+              alignment.'
+        imageUrl:
+          type:
+          - string
+          - 'null'
+        notes:
+          type:
+          - string
+          - 'null'
+        orderId:
+          description: FK → Order.id. Link to associated Order document.
+          type:
+          - string
+          - 'null'
+        bookingId:
+          description: FK → Booking.id. Link to associated Booking document (IG-12).
+          type:
+          - string
+          - 'null'
+        purchaseDate:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: Firestore Timestamp serialized representation
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated creation timestamp.
+      required:
+      - purchaseDate
+      additionalProperties: false
+      description: 'Sale/Purchase model (D06). Collection: companies/{companyId}/purchases/{purchaseId}.
+        Code alias: SalesService. [Deprecated path: customers/{custId}/purchases/{purchaseId}
+        — migrate to company-wide path per MIG-04/IG-5]'
+    SaleCreate:
+      allOf:
+      - $ref: '#/components/schemas/Sale'
+      description: Write payload for creating a new Sale document. Fields marked `readOnly`
+        are server-set and must not be included. Fields marked `x-immutable` may be
+        set once at creation.
+      required:
+      - purchaseDate
+    SaleUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Sale'
+      description: Write payload for partial update (PATCH) of a Sale document. All
+        fields optional. Fields marked `readOnly` or `x-immutable` must not be sent.
+    Ticket:
+      type: object
+      properties:
+        id:
+          type: string
+          readOnly: true
+          description: '(Read-only) Firestore document ID. Note: Ticket does not have
+            a uid field.'
+        eventId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Event.id. Parent event this ticket belongs
+            to. Set at creation.
+        companyId:
+          type: string
+          x-immutable: true
+          denormalized: true
+          description: (Immutable, Denormalized) FK → Company document ID. Denormalized
+            from parent Event for direct queries.
+        customerId:
+          x-see:
+            decisions:
+            - D29
+          x-note: Added additively per D29. Denormalized customerName/email/phone
+            are kept for backwards compatibility. Null on tickets created before D29
+            was applied.
+          description: FK → Customer.id. Optional structured link to Customer document
+            (D29). Added additively alongside denormalized fields.
+          type:
+          - string
+          - 'null'
+        customerName:
+          denormalized: true
+          description: (Denormalized) From Customer.name at write time.
+          type:
+          - string
+          - 'null'
+        customerEmail:
+          denormalized: true
+          description: (Denormalized) From Customer.email at write time.
+          type:
+          - string
+          - 'null'
+        customerPhone:
+          denormalized: true
+          description: (Denormalized) From Customer.phone at write time.
+          type:
+          - string
+          - 'null'
+        status:
+          $ref: '#/components/schemas/TicketStatus'
+          description: Ticket lifecycle (D32). SCREAMING_SNAKE per D04. MIG-10 migrates
+            legacy lowercase values.
+        usedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Timestamp when ticket was scanned/used. Set by
+            scan operation.
+        usedBy:
+          readOnly: true
+          description: (Read-only) FK → User/staff UID who scanned the ticket.
+          type:
+          - string
+          - 'null'
+        usedByName:
+          readOnly: true
+          denormalized: true
+          description: (Read-only, Denormalized) From User display name at scan time.
+          type:
+          - string
+          - 'null'
+        price:
+          type:
+          - number
+          - 'null'
+        notes:
+          type:
+          - string
+          - 'null'
+        createdAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server-generated creation timestamp.
+          readOnly: true
+        updatedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Server-generated update timestamp.
+          readOnly: true
+        createdBy:
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who created this ticket.
+          type:
+          - string
+          - 'null'
+      required:
+      - id
+      - eventId
+      - companyId
+      - status
+      - createdAt
+      - updatedAt
+      additionalProperties: false
+      description: 'Ticket model (D32). Collection: companies/{companyId}/events/{eventId}/tickets/{ticketId}.
+        Mobile-only today; Dashboard in Wave 4.'
+    TicketCreate:
+      allOf:
+      - $ref: '#/components/schemas/Ticket'
+      description: Write payload for creating a new Ticket document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - eventId
+      - companyId
+      - status
+    TicketUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Ticket'
+      description: Write payload for partial update (PATCH) of a Ticket document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    PaymentSummary:
+      type: object
+      properties:
+        id:
+          type: string
+          readOnly: true
+          description: (Read-only) Firestore document ID. Matches the period key (e.g.
+            "2026-03-09" for DAILY, "2026-03" for MONTHLY).
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Scopes all queries.
+        period:
+          type: string
+          x-note: 'Document ID matches this value. Format: YYYY-MM-DD (DAILY), YYYY-Www
+            (WEEKLY), YYYY-MM (MONTHLY).'
+          description: Period key. Determines the document ID and the time window
+            covered.
+        periodType:
+          type: string
+          enum:
+          - DAILY
+          - WEEKLY
+          - MONTHLY
+          description: Granularity of this summary document.
+        paymentsByMethod:
+          type: object
+          propertyNames:
+            type: string
+            enum:
+            - CASH
+            - CREDIT_CARD
+            - ORANGE_MONEY
+            - WAVE
+            - MTN_MONEY
+            - MOOV_MONEY
+            - BANK_TRANSFER
+            - PAYPAL
+            - STRIPE
+            - OTHER
+          additionalProperties:
+            type: object
+            properties:
+              total:
+                type: number
+                description: Sum of payment amounts for this method in the period.
+                  Updated via FieldValue.increment().
+              count:
+                type: integer
+                minimum: -9007199254740991
+                maximum: 9007199254740991
+                description: Number of individual payments for this method in the
+                  period. Updated via FieldValue.increment().
+            required:
+            - total
+            - count
+            additionalProperties: false
+          required:
+          - CASH
+          - CREDIT_CARD
+          - ORANGE_MONEY
+          - WAVE
+          - MTN_MONEY
+          - MOOV_MONEY
+          - BANK_TRANSFER
+          - PAYPAL
+          - STRIPE
+          - OTHER
+          x-note: Keys are PaymentMethod enum values (CASH, WAVE, ORANGE_MONEY, etc.).
+            Missing keys imply zero for that method. Updated incrementally via FieldValue.increment().
+          x-see:
+            decisions:
+            - D02
+            - D12
+          description: Payment totals broken down by PaymentMethod. Each entry holds
+            the total amount and transaction count for the period.
+        grandTotal:
+          type: number
+          readOnly: true
+          description: (Read-only) Sum of all paymentsByMethod[*].total. Server-calculated.
+        totalCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          description: (Read-only) Sum of all paymentsByMethod[*].count. Server-calculated.
+        currency:
+          type: string
+          const: XOF
+          description: Currency code. Locked to XOF (West African CFA franc).
+        lastUpdatedAt:
+          readOnly: true
+          description: (Read-only) Server timestamp of the last increment write.
+          type: object
+          properties:
+            _seconds:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+            _nanoseconds:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+          required:
+          - _seconds
+          - _nanoseconds
+          additionalProperties: false
+        createdAt:
+          type: object
+          properties:
+            _seconds:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+            _nanoseconds:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+          required:
+          - _seconds
+          - _nanoseconds
+          additionalProperties: false
+          description: (Read-only) Server-generated creation timestamp.
+          readOnly: true
+      required:
+      - id
+      - companyId
+      - period
+      - periodType
+      - paymentsByMethod
+      - grandTotal
+      - totalCount
+      - currency
+      - createdAt
+      additionalProperties: false
+      description: '[PROPOSED] Aggregated payment totals by method for a given period.
+        Collection: companies/{companyId}/paymentSummaries/{period}. Server-owned
+        — all fields are set by Cloud Function triggers on Order.payments[] and CustomerPayment
+        writes. Clients must never write to this collection.'
+      x-status: proposed