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

package/data/static/llms.txt

@@ -0,0 +1,1046 @@
+# @valets/schema
+
+> Canonical data model for the Valets platform.
+> Source of truth: Zod schemas in packages/schema/src/
+> All Firestore documents are scoped under companies/{companyId}/
+
+> Generated: 2026-03-09
+
+---
+
+## Enums
+
+### BookingStatus
+Booking lifecycle status. COMPLETED_MIXED = some sessions completed, others cancelled/no-show.
+Values: PENDING, CONFIRMED, COMPLETED, CANCELLED, CANCELLATION_REQUESTED, COMPLETED_MIXED
+
+### CustomerPaymentStatus
+Customer payment lifecycle status (D22). Tracks allocation progress of received payments.
+Values: PENDING, CONFIRMED, PARTIALLY_APPLIED, FULLY_APPLIED, REFUNDED, CANCELLED
+
+### CustomerPaymentTargetType
+Target document type for customer payment allocation.
+Values: BOOKING, ORDER, PURCHASE
+
+### DeliveryType
+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.
+Values: ON_SITE, PICK_UP, DELIVERY
+
+### EventStatus
+Ticketed event lifecycle (D32). Mobile-only today; Dashboard in Wave 4.
+Values: DRAFT, ACTIVE, CANCELLED, COMPLETED
+
+### FulfillmentStatus
+Delivery/fulfillment lifecycle (D34). Optional — null for in-person orders.
+Values: PREPARING, PARTIALLY_SHIPPED, SHIPPED, IN_TRANSIT, DELIVERED, PICKED_UP
+
+### LoyaltyTransactionType
+Loyalty point transaction type (D07). SCREAMING_SNAKE past tense.
+Values: EARNED, REDEEMED, ADJUSTED, EXPIRED, BONUS, REFUND
+
+### OrderStatus
+Core order lifecycle status (D03, D34). Universal across all business types. Replaces the Dashboard's legacy 20-value flat enum (MIG-11).
+Values: PENDING, CONFIRMED, PROCESSING, READY, COMPLETED, CANCELLED, EXPIRED
+
+### PaymentMethod
+Unified payment method set with African + global methods (D02).
+Values: CASH, CREDIT_CARD, ORANGE_MONEY, WAVE, MTN_MONEY, MOOV_MONEY, BANK_TRANSFER, PAYPAL, STRIPE, OTHER
+
+### PaymentProofStatus
+Payment proof review status. Used by Order and Booking payment proof workflows.
+Values: PENDING, APPROVED, REJECTED
+
+### PaymentStatus
+Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase, Booking.
+Values: PENDING, PAID, PARTIALLY_PAID, FAILED, REFUND_PROCESSING, REFUNDED, PARTIALLY_REFUNDED
+
+### ReturnStatus
+Post-sale return/exchange lifecycle (D34). Optional — null until return or exchange initiated.
+Values: RETURN_REQUESTED, RETURN_PROCESSING, RETURNED, EXCHANGE_REQUESTED, EXCHANGE_PROCESSING, EXCHANGE_COMPLETED
+
+### SessionStatus
+Per-date/per-slot booking session status (D19). Dashboard is sole writer; Mobile is read-only.
+Values: PENDING, CONFIRMED, CANCELLATION_REQUESTED, COMPLETED, NO_SHOW, CANCELLED
+
+### TicketStatus
+Event ticket status (D32). VALID = active and unused.
+Values: VALID, USED, CANCELLED
+
+---
+
+## Models
+
+### Booking
+Fields: 52 (7 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | yes | (Read-only) Firestore document ID. |
+| uid | string | yes | (Read-only) Entity UID. Often mirrors id. |
+| companyId | ['string', 'null'] | no | (Immutable) FK → Company document ID. Note: optional in current schema — should be required (see ID consistency audit). |
+| status | BookingStatus | yes | Booking lifecycle status. COMPLETED_MIXED = some sessions completed, others cancelled/no-show. |
+| totalAmount | number | yes |  |
+| bookingDates | array<object> | yes |  |
+| bookingDates[].date | string | yes |  |
+| bookingDates[].selectedTimeSlots | array<object> | yes |  |
+| bookingDates[].selectedTimeSlots[].id | number | yes |  |
+| bookingDates[].selectedTimeSlots[].name | string | yes |  |
+| bookingDates[].selectedTimeSlots[].timeRange | string | yes |  |
+| bookingDates[].selectedTimeSlots[].price | number | yes | Canonical price field (D11). Replaces legacy standardPrice/fullPrice (MIG-08). |
+| bookingDates[].selectedTimeSlots[].notMainPurposePrice | number | yes | Price when slot is not the main purpose (D11). Canonical name; replaces legacy aliases (MIG-08). |
+| bookingDates[].selectedTimeSlots[].hours | string | yes |  |
+| bookingDates[].selectedTimeSlots[].startTime | string | yes |  |
+| bookingDates[].selectedTimeSlots[].endTime | string | yes |  |
+| bookingDates[].selectedTimeSlots[].isNightSlot | boolean | no |  |
+| bookingDates[].selectedTimeSlots[].isNotMainPurpose | boolean | no |  |
+| bookingDates[].selectedTimeSlots[].isNotMainPurposeReason | string | no |  |
+| bookingDates[].selectedTimeSlots[].isNotMainPurposeOtherReason | string | no |  |
+| bookingDates[].selectedTimeSlots[]._deleted | boolean | no | Soft-delete flag. Dashboard writes; Mobile filters (IG-6). |
+| bookingDates[].selectedTimeSlots[]._deletedAt | FirestoreTimestamp | no | Firestore Timestamp serialized representation |
+| bookingDates[].selectedTimeSlots[]._deletedBy | string | no | FK → User/staff UID who soft-deleted this item. |
+| bookingDates[].selectedTimeSlots[]._lastModifiedAt | FirestoreTimestamp | no | Firestore Timestamp serialized representation |
+| bookingDates[].selectedTimeSlots[]._lastModifiedBy | string | no | FK → User/staff UID who last modified this item. |
+| bookingDates[].selectedTimeSlots[]._version | number | no | Monotonic version counter for conflict detection. |
+| bookingDates[].slotKitTypes | record<string,string> | yes | Kit type per slot (IG-11). Firebase parity gap — exists in Firestore but Firebase type lacked it. |
+| bookingDates[].slotAddOns | record<string,array<string>> | yes | Add-on IDs per slot. Numeric IDs to be normalized to descriptive names (MIG-07/D10). |
+| bookingDates[].extraHours | number | yes |  |
+| bookingDates[].status | SessionStatus | no | Per-date session status (D19). Dashboard is sole writer; Mobile is read-only. |
+| bookingDates[].statusUpdatedAt | FirestoreTimestamp | no | (Read-only) Timestamp of last status change. |
+| bookingDates[].statusUpdatedBy | string | no | FK → User/staff UID who updated this date status. |
+| bookingDates[].slotStatuses | record<string,SessionStatus> | no | Per-slot session statuses (D19). Keyed by slot ID string. |
+| bookingDates[].slotStatusUpdatedAt | record<string,FirestoreTimestamp> | no |  |
+| bookingDates[].slotStatusUpdatedBy | record<string,string> | no |  |
+| bookingDates[]._deleted | boolean | no | Soft-delete flag. Dashboard writes; Mobile filters (IG-6). |
+| bookingDates[]._deletedAt | FirestoreTimestamp | no | Firestore Timestamp serialized representation |
+| bookingDates[]._deletedBy | string | no | FK → User/staff UID who soft-deleted this item. |
+| bookingDates[]._lastModifiedAt | FirestoreTimestamp | no | Firestore Timestamp serialized representation |
+| bookingDates[]._lastModifiedBy | string | no | FK → User/staff UID who last modified this item. |
+| bookingDates[]._version | number | no | Monotonic version counter for conflict detection. |
+| customerId | ['string', 'null'] | no | FK → Customer.id (Firestore doc ID). Links booking to customer record. |
+| client | ['object', 'null'] | no | (Denormalized) Embedded client snapshot from Customer at write time. |
+| customerName | ['string', 'null'] | no | (Denormalized) From Customer.name at write time. Canonical field per D24. |
+| customerEmail | ['string', 'null'] | no | (Denormalized) From Customer.email at write time. Canonical field per D24. |
+| customerPhone | ['string', 'null'] | no | (Denormalized) From Customer.phone at write time. Canonical field per D24. |
+| clientName | ['string', 'null'] | no | (Denormalized) Legacy — use `customerName`. D24 standardized to customer* prefix. |
+| clientReference | string | yes |  |
+| clientEmail | ['string', 'null'] | no | (Denormalized) Legacy — use `customerEmail`. D24 standardized to customer* prefix. |
+| clientPhone | ['string', 'null'] | no | (Denormalized) Legacy — use `customerPhone`. D24 standardized to customer* prefix. |
+| service | ['object', 'null'] | no |  |
+| serviceId | ['string', 'null'] | no | FK → Service document ID. |
+| serviceName | ['string', 'null'] | no | (Denormalized) From Service.name at write time. |
+| timeSlot | ['string', 'null'] | no |  |
+| date | ['string', 'null'] | no |  |
+| startDate | ['string', 'null'] | no |  |
+| endDate | ['string', 'null'] | no |  |
+| startTime | ['string', 'null'] | no |  |
+| endTime | ['string', 'null'] | no |  |
+| notes | ['array', 'null'] | no |  |
+| technicalInfo | ['string', 'null'] | no |  |
+| paymentStatus | any | no | Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase, Booking. |
+| amountPaid | ['number', 'null'] | no |  |
+| amountRefunded | ['number', 'null'] | no |  |
+| amountPending | ['number', 'null'] | no |  |
+| purchaseId | ['string', 'null'] | no | FK → Sale.id. Link to associated Sale document. |
+| paymentStatusChangeReason | ['string', 'null'] | no |  |
+| paymentStatusChangedBy | ['string', 'null'] | no | FK → User/staff UID who changed payment status. |
+| paymentStatusChangedAt | any | no | Firestore Timestamp serialized representation |
+| paymentProofUrl | ['string', 'null'] | no | URL to uploaded payment proof image/document. |
+| paymentProofStatus | any | no | Payment proof review status. Used by Order and Booking payment proof workflows. |
+| paymentProofAddedAt | any | no | Firestore Timestamp serialized representation |
+| paymentProofAddedBy | ['string', 'null'] | no | FK → User/staff UID who uploaded the payment proof. |
+| paymentProofReviewedBy | ['string', 'null'] | no | FK → User/staff UID who reviewed the payment proof. |
+| paymentProofReviewedAt | any | no | Firestore Timestamp serialized representation |
+| paymentProofRejectionReason | ['string', 'null'] | no |  |
+| cancellationRequestedById | ['string', 'null'] | no | FK → User/staff UID who requested cancellation. |
+| cancellationRequestReason | ['string', 'null'] | no |  |
+| cancellationProcessedById | ['string', 'null'] | no | FK → User/staff UID who processed the cancellation. |
+| cancellationProcessedAt | any | no | Firestore Timestamp serialized representation |
+| cancelledByRole | ['string', 'null'] | no |  |
+| cancellationReason | ['string', 'null'] | no |  |
+| createdAt | FirestoreTimestamp | yes | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+| createdBy | ['string', 'null'] | no | (Immutable) FK → User/staff UID who created this booking. |
+| updatedBy | ['string', 'null'] | no | FK → User/staff UID who last updated this booking. |
+| createdFromBackend | ['boolean', 'null'] | no | When true, suppresses Firebase notification triggers (D20/IG-8). |
+
+Example:
+```json
+{
+  "id": "bk_abc123def456",
+  "uid": "user_u8x92kqm",
+  "companyId": null,
+  "status": "status",
+  "totalAmount": 45000,
+  "bookingDates": [
+    {
+      "date": "2026-02-15",
+      "selectedTimeSlots": [
+        {
+          "id": 0,
+          "name": "Morning Full Session",
+          "timeRange": "09:00 - 11:00",
+          "price": 15000,
+          "notMainPurposePrice": 10000,
+          "hours": "2h",
+          "startTime": "09:00",
+          "endTime": "11:00"
+        }
+      ],
+      "slotKitTypes": {},
+      "slotAddOns": {},
+      "extraHours": 0
+    }
+  ],
+  "customerId": null,
+  "client": null,
+  "customerName": null,
+  "customerEmail": null,
+  "customerPhone": null,
+  "clientName": null,
+  "clientReference": "CLI-2026-0017",
+  "clientEmail": null,
+  "clientPhone": null,
+  "service": null,
+  "serviceId": null,
+  "serviceName": null,
+  "timeSlot": null,
+  "date": null,
+  "startDate": null,
+  "endDate": null,
+  "startTime": null,
+  "endTime": null,
+  "notes": null,
+  "technicalInfo": null,
+  "paymentStatus": "paymentStatus",
+  "amountPaid": null,
+  "amountRefunded": null,
+  "amountPending": null,
+  "purchaseId": null,
+  "paymentStatusChangeReason": null,
+  "paymentStatusChangedBy": null,
+  "paymentStatusChangedAt": "paymentStatusChangedAt",
+  "paymentProofUrl": null,
+  "paymentProofStatus": "paymentProofStatus",
+  "paymentProofAddedAt": "paymentProofAddedAt",
+  "paymentProofAddedBy": null,
+  "paymentProofReviewedBy": null,
+  "paymentProofReviewedAt": "paymentProofReviewedAt",
+  "paymentProofRejectionReason": null,
+  "cancellationRequestedById": null,
+  "cancellationRequestReason": null,
+  "cancellationProcessedById": null,
+  "cancellationProcessedAt": "cancellationProcessedAt",
+  "cancelledByRole": null,
+  "cancellationReason": null,
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt",
+  "createdBy": null,
+  "updatedBy": null,
+  "createdFromBackend": null
+}
+```
+
+### BookingVersion
+Fields: 9 (6 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | yes | (Read-only) Firestore document ID. Server-generated version record. |
+| bookingId | string | yes | (Immutable) FK → Booking.id. Parent booking this version records. |
+| companyId | string | yes | (Immutable) FK → Company document ID. Denormalized for direct queries. |
+| changeType | enum(3) | yes | (Immutable) What caused this version record: CREATE, UPDATE, or DELETE. |
+| changedAt | FirestoreTimestamp | yes | (Read-only) Timestamp of the write that created this version. Server-set. |
+| changedBy | ['string', 'null'] | no | (Immutable) FK → User/staff UID who made the change. Null for server-originated writes. |
+| changedByRole | enum(5) | no | (Immutable) Which platform/context made the write: DASHBOARD, MOBILE, FIREBASE (trigger), CLI (migration script), or UNKNOWN. SCREAMING_SNAKE per D04. |
+| fieldsChanged | ['array', 'null'] | no | (Immutable, Read-only) List of field paths that changed in this write. Populated by the Firebase trigger diff. Null for CREATE records. |
+| snapshot | object | yes | (Immutable, Read-only) Full snapshot of the Booking document immediately after the write. Untyped to avoid circular schema dependency — cast to Booking at runtime. |
+
+Example:
+```json
+{
+  "id": "bk_abc123def456",
+  "bookingId": "boo_ref123",
+  "companyId": "comp_xyz789",
+  "changeType": "CREATE",
+  "changedAt": "changedAt",
+  "changedBy": null,
+  "changedByRole": "DASHBOARD",
+  "fieldsChanged": null,
+  "snapshot": {}
+}
+```
+
+### Customer
+Fields: 17 (4 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | yes | (Read-only) Firestore document ID. This is the canonical FK target — other models reference Customer via this field. |
+| uid | string | yes | (Read-only) Entity UID. Often mirrors id. |
+| name | string | yes |  |
+| email | ['string', 'null'] | no |  |
+| phone | ['string', 'null'] | no |  |
+| address | ['string', 'null'] | no |  |
+| notes | ['string', 'null'] | no |  |
+| tags | ['array', 'null'] | no |  |
+| communicationEntries | ['array', 'null'] | no | Embedded CRM log (D25). Stays as array, not subcollection. |
+| createdAt | FirestoreTimestamp | yes | (Read-only) Server-generated creation timestamp. |
+| lastOrderDate | any | no | (Read-only) Updated by server when orders are placed. |
+| balance | ['number', 'null'] | no | (Read-only) Outstanding balance. Dashboard-originated, server-calculated. |
+| creditLimit | ['number', 'null'] | no |  |
+| lastPaymentDate | any | no | (Read-only) Updated by server when payments are recorded. |
+| totalPaid | ['number', 'null'] | no | (Read-only) Server-calculated total paid amount. |
+| totalOwed | ['number', 'null'] | no | (Read-only) Server-calculated total owed amount. |
+| loyaltyPoints | ['number', 'null'] | no | (Read-only, Denormalized) Derived summary from loyalty/status subcollection (D08). Source of truth is LoyaltyStatus.pointsBalance. |
+
+Example:
+```json
+{
+  "id": "bk_abc123def456",
+  "uid": "user_u8x92kqm",
+  "name": "Amadou Diallo",
+  "email": null,
+  "phone": null,
+  "address": null,
+  "notes": null,
+  "tags": null,
+  "communicationEntries": null,
+  "createdAt": "createdAt",
+  "lastOrderDate": "lastOrderDate",
+  "balance": null,
+  "creditLimit": null,
+  "lastPaymentDate": "lastPaymentDate",
+  "totalPaid": null,
+  "totalOwed": null,
+  "loyaltyPoints": null
+}
+```
+
+### CustomerPayment
+Fields: 17 (12 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID. Note: optional in current schema — some legacy docs may lack this field. |
+| companyId | string | yes | (Immutable) FK → Company document ID. Scopes all queries. |
+| customerId | string | yes | (Immutable) FK → Customer.id (Firestore doc ID). Links payment to customer. Set at creation. |
+| customerName | ['string', 'null'] | no | (Denormalized) From Customer.name at write time. |
+| amount | number | yes |  |
+| currency | string | yes | Currency code. Locked to XOF (West African CFA franc) for now. |
+| paymentDate | FirestoreTimestamp | yes | Firestore Timestamp serialized representation |
+| paymentMethod | PaymentMethod | yes | Unified payment method set with African + global methods (D02). |
+| referenceNumber | string | yes | Unique payment reference (receipt number, transaction ID, etc.). |
+| allocatedAmount | number | yes | (Read-only) Total amount allocated to bookings/orders/purchases via allocations. Server-calculated. |
+| unappliedAmount | number | yes | (Read-only) Remaining unallocated amount (amount - allocatedAmount). Server-calculated. |
+| status | CustomerPaymentStatus | yes | Customer payment lifecycle status (D22). Tracks allocation progress of received payments. |
+| notes | ['string', 'null'] | no |  |
+| recordedBy | string | yes | (Immutable) FK → User/staff UID who recorded the payment. Required audit field (D22/IG-7). |
+| recordedByName | ['string', 'null'] | no | (Immutable, Denormalized) From User display name at creation time. |
+| createdAt | FirestoreTimestamp | yes | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "customerId": "cus_ref123",
+  "customerName": null,
+  "amount": 45000,
+  "currency": "XOF",
+  "paymentDate": "paymentDate",
+  "paymentMethod": "paymentMethod",
+  "referenceNumber": "PAY-2026-0099",
+  "allocatedAmount": 30000,
+  "unappliedAmount": 15000,
+  "status": "status",
+  "notes": null,
+  "recordedBy": "staff_k0f1",
+  "recordedByName": null,
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt"
+}
+```
+
+### CustomerPaymentAllocation
+Fields: 14 (8 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID. Note: optional in current schema. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| paymentId | string | yes | (Immutable) FK → CustomerPayment.id. Parent payment this allocation draws from. |
+| customerId | string | yes | (Immutable) FK → Customer.id (Firestore doc ID). |
+| targetId | string | yes | (Immutable) FK → Booking.id, Order.id, or Sale.id (polymorphic). See targetType for discriminator. |
+| targetType | CustomerPaymentTargetType | yes | (Immutable) Discriminator for targetId: BOOKING, ORDER, or PURCHASE. |
+| targetReference | ['string', 'null'] | no |  |
+| allocatedAmount | number | yes | (Immutable) Amount allocated in this allocation. Set at creation. |
+| transferredToAllocationId | ['string', 'null'] | no | FK → CustomerPaymentAllocation.id. Self-reference for transfer chains. |
+| transferredFromAllocationId | ['string', 'null'] | no | FK → CustomerPaymentAllocation.id. Self-reference for transfer chains. |
+| transferredAt | any | no | Firestore Timestamp serialized representation |
+| createdBy | string | yes | (Immutable) FK → User/staff UID who created this allocation. |
+| createdByName | ['string', 'null'] | no | (Immutable, Denormalized) From User display name at creation time. |
+| createdAt | FirestoreTimestamp | yes | (Read-only) Server-generated creation timestamp. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "paymentId": "pay_ref123",
+  "customerId": "cus_ref123",
+  "targetId": "tar_ref123",
+  "targetType": "targetType",
+  "targetReference": null,
+  "allocatedAmount": 30000,
+  "transferredToAllocationId": null,
+  "transferredFromAllocationId": null,
+  "transferredAt": "transferredAt",
+  "createdBy": "staff_k0f1",
+  "createdByName": null,
+  "createdAt": "createdAt"
+}
+```
+
+### Event
+Fields: 15 (9 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | yes | (Read-only) Firestore document ID. Note: Event does not have a uid field. |
+| companyId | string | yes | (Immutable) FK → Company document ID. Scopes all queries. |
+| name | string | yes |  |
+| description | ['string', 'null'] | no |  |
+| location | ['string', 'null'] | no |  |
+| startDate | FirestoreTimestamp | yes | Firestore Timestamp serialized representation |
+| endDate | any | no | Firestore Timestamp serialized representation |
+| status | EventStatus | yes | Event lifecycle status (D32). SCREAMING_SNAKE per D04. MIG-09 migrates legacy lowercase values. |
+| maxTickets | ['integer', 'null'] | no |  |
+| ticketsSold | integer | yes | (Read-only) Counter: total tickets sold. Updated by Firebase triggers (D28). |
+| ticketsUsed | integer | yes | (Read-only) Counter: tickets scanned/used. Updated by Firebase triggers (D28). |
+| ticketPrice | ['number', 'null'] | no |  |
+| createdAt | FirestoreTimestamp | yes | (Read-only) Server-generated creation timestamp. |
+| updatedAt | FirestoreTimestamp | yes | (Read-only) Server-generated update timestamp. |
+| createdBy | ['string', 'null'] | no | (Immutable) FK → User/staff UID who created this event. |
+
+Example:
+```json
+{
+  "id": "bk_abc123def456",
+  "companyId": "comp_xyz789",
+  "name": "Amadou Diallo",
+  "description": null,
+  "location": null,
+  "startDate": "2026-02-15",
+  "endDate": "2026-02-20",
+  "status": "status",
+  "maxTickets": null,
+  "ticketsSold": 47,
+  "ticketsUsed": 12,
+  "ticketPrice": null,
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt",
+  "createdBy": null
+}
+```
+
+### LoyaltyConfig
+Fields: 11 (2 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID. Singleton doc — typically "config". |
+| isEnabled | boolean | yes |  |
+| pointSystem | enum(3) | yes | How points are earned: SPENDING (per currency spent), PRODUCT (per product purchased), or VISIT (per visit). SCREAMING_SNAKE per D04. |
+| pointsPerCurrency | ['number', 'null'] | no | [Deprecated alias: pointsPerCurrencyUnit — renamed by MIG-06] |
+| pointsPerVisit | ['number', 'null'] | no | Points earned per visit (when pointSystem is visit). |
+| pointValue | ['number', 'null'] | no | Monetary value of one point for redemption. |
+| minimumRedeemPoints | ['integer', 'null'] | no | Minimum points balance required before redemption is allowed. |
+| welcomeBonusPoints | ['integer', 'null'] | no | One-time points bonus for new loyalty enrollees. |
+| pointsExpirationDays | any | no | [Deprecated alias: pointsExpiryMonths — renamed and converted months*30 to days by MIG-06] |
+| createdAt | any | no | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+
+Example:
+```json
+{
+  "id": null,
+  "isEnabled": true,
+  "pointSystem": "SPENDING",
+  "pointsPerCurrency": null,
+  "pointsPerVisit": null,
+  "pointValue": null,
+  "minimumRedeemPoints": null,
+  "welcomeBonusPoints": null,
+  "pointsExpirationDays": "pointsExpirationDays",
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt"
+}
+```
+
+### LoyaltyReward
+Fields: 11 (5 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | yes | (Read-only) Firestore document ID. |
+| name | string | yes |  |
+| description | ['string', 'null'] | no |  |
+| pointsRequired | integer | yes | Points cost to redeem this reward. |
+| isActive | boolean | yes | Whether this reward is currently available for redemption. |
+| imageUrl | ['string', 'null'] | no |  |
+| rewardType | ['string', 'null'] | no | Category of reward (e.g. discount, free_item, service). |
+| discountValue | ['number', 'null'] | no | Discount amount when rewardType is discount. |
+| productId | ['string', 'null'] | no | FK → Product.id. Linked product when rewardType is free_item. |
+| createdAt | FirestoreTimestamp | yes | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+
+Example:
+```json
+{
+  "id": "bk_abc123def456",
+  "name": "Free Braiding Session",
+  "description": null,
+  "pointsRequired": 200,
+  "isActive": true,
+  "imageUrl": null,
+  "rewardType": null,
+  "discountValue": null,
+  "productId": null,
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt"
+}
+```
+
+### LoyaltyStatus
+Fields: 9 (2 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| customerId | ['string', 'null'] | no | (Immutable) FK → Customer.id. Note: optional despite being in customer subcollection (path already contains custId). |
+| pointsBalance | integer | yes | (Read-only) Current available points balance. Canonical name (D08). Dashboard: pointsBalance, Mobile: currentPoints. Updated by transaction triggers. |
+| totalPointsEarned | integer | yes | (Read-only) Lifetime total points earned. Canonical name (D08). Dashboard: totalPointsEarned, Mobile: lifetimePoints. Updated by transaction triggers. |
+| redeemedPoints | ['integer', 'null'] | no | (Read-only) Total redeemed points. Updated by transaction triggers. |
+| lastActivityDate | any | no | (Read-only) Last earn/redeem activity. Canonical name (D08). Mobile alias: lastEarnedAt. |
+| lastRedeemedAt | any | no | (Read-only) Last redemption timestamp. |
+| tier | ['string', 'null'] | no |  |
+| createdAt | any | no | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+
+Example:
+```json
+{
+  "customerId": null,
+  "pointsBalance": 340,
+  "totalPointsEarned": 1200,
+  "redeemedPoints": null,
+  "lastActivityDate": "lastActivityDate",
+  "lastRedeemedAt": "lastRedeemedAt",
+  "tier": null,
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt"
+}
+```
+
+### LoyaltyTransaction
+Fields: 16 (4 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | yes | (Read-only) Firestore document ID. |
+| customerId | ['string', 'null'] | no | (Immutable) FK → Customer.id. Note: optional despite being in customer subcollection. |
+| type | LoyaltyTransactionType | yes | (Immutable) Transaction type (D07). SCREAMING_SNAKE per D04. MIG-05 migrates legacy lowercase values. |
+| pointsChange | integer | yes | (Immutable) Points delta (+/-). Canonical name (D07). Dashboard: pointsChange, Mobile: points. |
+| description | ['string', 'null'] | no |  |
+| reason | ['string', 'null'] | no |  |
+| relatedPurchaseId | ['string', 'null'] | no | (Immutable) FK → Sale.id. Linked sale that triggered this transaction. |
+| relatedOrderId | ['string', 'null'] | no | (Immutable) FK → Order.id. Linked order that triggered this transaction. |
+| relatedRewardId | ['string', 'null'] | no | (Immutable) FK → LoyaltyReward.id. Reward redeemed in this transaction. |
+| orderId | ['string', 'null'] | no | (Immutable) FK → Order.id. Note: may overlap with relatedOrderId — naming inconsistency from Mobile. |
+| sessionId | ['string', 'null'] | no | Session/booking reference. Context-dependent identifier. |
+| orderAmount | ['number', 'null'] | no |  |
+| transactionDate | FirestoreTimestamp | yes | (Immutable) When the transaction occurred. Canonical name (D07). Dashboard: transactionDate, Mobile: createdAt. |
+| pointsBalanceAfter | ['integer', 'null'] | no | (Read-only) Running balance after this transaction. Canonical name (D07). Dashboard: pointsBalanceAfter, Mobile: balanceAfter. Server-calculated. |
+| createdBy | ['string', 'null'] | no | (Immutable) FK → User/staff UID who created this transaction. |
+| createdByName | ['string', 'null'] | no | (Immutable, Denormalized) From User display name at creation time. |
+
+Example:
+```json
+{
+  "id": "bk_abc123def456",
+  "customerId": null,
+  "type": "phone",
+  "pointsChange": 50,
+  "description": null,
+  "reason": null,
+  "relatedPurchaseId": null,
+  "relatedOrderId": null,
+  "relatedRewardId": null,
+  "orderId": null,
+  "sessionId": null,
+  "orderAmount": null,
+  "transactionDate": "transactionDate",
+  "pointsBalanceAfter": null,
+  "createdBy": null,
+  "createdByName": null
+}
+```
+
+### MetricsCurrent
+Fields: 25 (25 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| todayOrdersCount | integer | yes | (Read-only) Orders created today (UTC). Resets at midnight. |
+| pendingOrdersCount | integer | yes | (Read-only) Orders currently in PENDING status (all-time cumulative). Corrected by full recalc on order updates. |
+| orderCompletionRate30d | number | yes | (Read-only) Percentage of orders completed or delivered in the last 30 days. Always full recalc. |
+| todayPurchasesCount | integer | yes | (Read-only) Purchases created today (UTC). Resets at midnight. |
+| todayPurchasesSum | number | yes | (Read-only) Total value of purchases created today (UTC). Resets at midnight. |
+| averagePurchaseAmount | number | yes | (Read-only) Average purchase value across last 200 purchases (rolling, not time-windowed). |
+| monthlyRevenue | number | yes | (Read-only) Total purchase value in the current calendar month (UTC). |
+| monthlyPurchasesCount | integer | yes | (Read-only) Number of purchases in the current calendar month (UTC). |
+| todayBookingsCount | integer | yes | (Read-only) Bookings with date == today AND status in [PENDING, CONFIRMED]. Resets at midnight. |
+| bookingsCreatedToday | integer | yes | (Read-only) Bookings with createdAt today (all statuses). Resets at midnight. |
+| todayBookingsConfirmedAmount | number | yes | (Read-only) Sum of totalAmount for bookings created today with status CONFIRMED or COMPLETED. Resets at midnight. |
+| monthlyBookingsConfirmedAmount | number | yes | (Read-only) Sum of totalAmount for bookings created this month with status CONFIRMED or COMPLETED. |
+| todayCollectedAmount | number | yes | (Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT is today. Resets at midnight. |
+| todayRevenue | number | yes | (Read-only) Sum of totalAmount for COMPLETED bookings where startDate == endDate == today (numeric YYYYMMDD). Resets at midnight. |
+| bookingsPendingPaymentVerification | integer | yes | (Read-only) Bookings with status PENDING/CANCELLATION_REQUESTED and a payment proof uploaded but not yet verified. Current state, always full recalc. |
+| bookingsPendingValidation | integer | yes | (Read-only) PENDING bookings with startDate within ±30 days of today. Rolling window, always full recalc. |
+| bookingsPendingValidation24h | integer | yes | (Read-only) PENDING bookings created in the last 24h with startDate >= tomorrow. Always full recalc. |
+| customersCount | integer | yes | (Read-only) Total customer count (all-time cumulative). |
+| newCustomersThisMonth | integer | yes | (Read-only) Customers with createdAt in the current calendar month (UTC). |
+| averageRating | number | yes | (Read-only) Average rating from the last 200 reviews (rolling). Always full recalc. |
+| lowStockItemsCount | integer | yes | (Read-only) Active stock items where currentQuantity <= minimumQuantity. Current state, always full recalc. |
+| activeRecurringPaymentsCount | integer | yes | (Read-only) Recurring payments with status ACTIVE. Current state, always full recalc. |
+| monthlyRecurringRevenue | number | yes | (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments. Always full recalc. |
+| computedForDay | string | yes | (Read-only) YYYY-MM-DD string indicating which day these metrics reflect. Used to detect day boundaries and trigger midnight resets. |
+| generatedAt | FirestoreTimestamp | yes | (Read-only) Server timestamp of the last metrics write. |
+
+Example:
+```json
+{
+  "todayOrdersCount": 2,
+  "pendingOrdersCount": 2,
+  "orderCompletionRate30d": 0,
+  "todayPurchasesCount": 2,
+  "todayPurchasesSum": 0,
+  "averagePurchaseAmount": 15000,
+  "monthlyRevenue": 0,
+  "monthlyPurchasesCount": 2,
+  "todayBookingsCount": 2,
+  "bookingsCreatedToday": 0,
+  "todayBookingsConfirmedAmount": 15000,
+  "monthlyBookingsConfirmedAmount": 15000,
+  "todayCollectedAmount": 15000,
+  "todayRevenue": 0,
+  "bookingsPendingPaymentVerification": 0,
+  "bookingsPendingValidation": 0,
+  "bookingsPendingValidation24h": 0,
+  "customersCount": 2,
+  "newCustomersThisMonth": 0,
+  "averageRating": 0,
+  "lowStockItemsCount": 2,
+  "activeRecurringPaymentsCount": 2,
+  "monthlyRecurringRevenue": 0,
+  "computedForDay": "computedForDay",
+  "generatedAt": "generatedAt"
+}
+```
+
+### MetricsDaily
+Fields: 26 (26 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| todayOrdersCount | integer | yes | (Read-only) Orders created today (UTC). Resets at midnight. |
+| pendingOrdersCount | integer | yes | (Read-only) Orders currently in PENDING status (all-time cumulative). Corrected by full recalc on order updates. |
+| orderCompletionRate30d | number | yes | (Read-only) Percentage of orders completed or delivered in the last 30 days. Always full recalc. |
+| todayPurchasesCount | integer | yes | (Read-only) Purchases created today (UTC). Resets at midnight. |
+| todayPurchasesSum | number | yes | (Read-only) Total value of purchases created today (UTC). Resets at midnight. |
+| averagePurchaseAmount | number | yes | (Read-only) Average purchase value across last 200 purchases (rolling, not time-windowed). |
+| monthlyRevenue | number | yes | (Read-only) Total purchase value in the current calendar month (UTC). |
+| monthlyPurchasesCount | integer | yes | (Read-only) Number of purchases in the current calendar month (UTC). |
+| todayBookingsCount | integer | yes | (Read-only) Bookings with date == today AND status in [PENDING, CONFIRMED]. Resets at midnight. |
+| bookingsCreatedToday | integer | yes | (Read-only) Bookings with createdAt today (all statuses). Resets at midnight. |
+| todayBookingsConfirmedAmount | number | yes | (Read-only) Sum of totalAmount for bookings created today with status CONFIRMED or COMPLETED. Resets at midnight. |
+| monthlyBookingsConfirmedAmount | number | yes | (Read-only) Sum of totalAmount for bookings created this month with status CONFIRMED or COMPLETED. |
+| todayCollectedAmount | number | yes | (Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT is today. Resets at midnight. |
+| todayRevenue | number | yes | (Read-only) Sum of totalAmount for COMPLETED bookings where startDate == endDate == today (numeric YYYYMMDD). Resets at midnight. |
+| bookingsPendingPaymentVerification | integer | yes | (Read-only) Bookings with status PENDING/CANCELLATION_REQUESTED and a payment proof uploaded but not yet verified. Current state, always full recalc. |
+| bookingsPendingValidation | integer | yes | (Read-only) PENDING bookings with startDate within ±30 days of today. Rolling window, always full recalc. |
+| bookingsPendingValidation24h | integer | yes | (Read-only) PENDING bookings created in the last 24h with startDate >= tomorrow. Always full recalc. |
+| customersCount | integer | yes | (Read-only) Total customer count (all-time cumulative). |
+| newCustomersThisMonth | integer | yes | (Read-only) Customers with createdAt in the current calendar month (UTC). |
+| averageRating | number | yes | (Read-only) Average rating from the last 200 reviews (rolling). Always full recalc. |
+| lowStockItemsCount | integer | yes | (Read-only) Active stock items where currentQuantity <= minimumQuantity. Current state, always full recalc. |
+| activeRecurringPaymentsCount | integer | yes | (Read-only) Recurring payments with status ACTIVE. Current state, always full recalc. |
+| monthlyRecurringRevenue | number | yes | (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments. Always full recalc. |
+| computedForDay | string | yes | (Read-only) YYYY-MM-DD string indicating which day these metrics reflect. Used to detect day boundaries and trigger midnight resets. |
+| generatedAt | FirestoreTimestamp | yes | (Read-only) Server timestamp of the last metrics write. |
+| date | string | yes | (Read-only) YYYY-MM-DD document ID repeated as a field. Identifies the day this snapshot covers. |
+
+Example:
+```json
+{
+  "todayOrdersCount": 2,
+  "pendingOrdersCount": 2,
+  "orderCompletionRate30d": 0,
+  "todayPurchasesCount": 2,
+  "todayPurchasesSum": 0,
+  "averagePurchaseAmount": 15000,
+  "monthlyRevenue": 0,
+  "monthlyPurchasesCount": 2,
+  "todayBookingsCount": 2,
+  "bookingsCreatedToday": 0,
+  "todayBookingsConfirmedAmount": 15000,
+  "monthlyBookingsConfirmedAmount": 15000,
+  "todayCollectedAmount": 15000,
+  "todayRevenue": 0,
+  "bookingsPendingPaymentVerification": 0,
+  "bookingsPendingValidation": 0,
+  "bookingsPendingValidation24h": 0,
+  "customersCount": 2,
+  "newCustomersThisMonth": 0,
+  "averageRating": 0,
+  "lowStockItemsCount": 2,
+  "activeRecurringPaymentsCount": 2,
+  "monthlyRecurringRevenue": 0,
+  "computedForDay": "computedForDay",
+  "generatedAt": "generatedAt",
+  "date": "2026-02-15"
+}
+```
+
+### MetricsMonthly
+Fields: 26 (26 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| todayOrdersCount | integer | yes | (Read-only) Orders created today (UTC). Resets at midnight. |
+| pendingOrdersCount | integer | yes | (Read-only) Orders currently in PENDING status (all-time cumulative). Corrected by full recalc on order updates. |
+| orderCompletionRate30d | number | yes | (Read-only) Percentage of orders completed or delivered in the last 30 days. Always full recalc. |
+| todayPurchasesCount | integer | yes | (Read-only) Purchases created today (UTC). Resets at midnight. |
+| todayPurchasesSum | number | yes | (Read-only) Total value of purchases created today (UTC). Resets at midnight. |
+| averagePurchaseAmount | number | yes | (Read-only) Average purchase value across last 200 purchases (rolling, not time-windowed). |
+| monthlyRevenue | number | yes | (Read-only) Total purchase value in the current calendar month (UTC). |
+| monthlyPurchasesCount | integer | yes | (Read-only) Number of purchases in the current calendar month (UTC). |
+| todayBookingsCount | integer | yes | (Read-only) Bookings with date == today AND status in [PENDING, CONFIRMED]. Resets at midnight. |
+| bookingsCreatedToday | integer | yes | (Read-only) Bookings with createdAt today (all statuses). Resets at midnight. |
+| todayBookingsConfirmedAmount | number | yes | (Read-only) Sum of totalAmount for bookings created today with status CONFIRMED or COMPLETED. Resets at midnight. |
+| monthlyBookingsConfirmedAmount | number | yes | (Read-only) Sum of totalAmount for bookings created this month with status CONFIRMED or COMPLETED. |
+| todayCollectedAmount | number | yes | (Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT is today. Resets at midnight. |
+| todayRevenue | number | yes | (Read-only) Sum of totalAmount for COMPLETED bookings where startDate == endDate == today (numeric YYYYMMDD). Resets at midnight. |
+| bookingsPendingPaymentVerification | integer | yes | (Read-only) Bookings with status PENDING/CANCELLATION_REQUESTED and a payment proof uploaded but not yet verified. Current state, always full recalc. |
+| bookingsPendingValidation | integer | yes | (Read-only) PENDING bookings with startDate within ±30 days of today. Rolling window, always full recalc. |
+| bookingsPendingValidation24h | integer | yes | (Read-only) PENDING bookings created in the last 24h with startDate >= tomorrow. Always full recalc. |
+| customersCount | integer | yes | (Read-only) Total customer count (all-time cumulative). |
+| newCustomersThisMonth | integer | yes | (Read-only) Customers with createdAt in the current calendar month (UTC). |
+| averageRating | number | yes | (Read-only) Average rating from the last 200 reviews (rolling). Always full recalc. |
+| lowStockItemsCount | integer | yes | (Read-only) Active stock items where currentQuantity <= minimumQuantity. Current state, always full recalc. |
+| activeRecurringPaymentsCount | integer | yes | (Read-only) Recurring payments with status ACTIVE. Current state, always full recalc. |
+| monthlyRecurringRevenue | number | yes | (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments. Always full recalc. |
+| computedForDay | string | yes | (Read-only) YYYY-MM-DD string indicating which day these metrics reflect. Used to detect day boundaries and trigger midnight resets. |
+| generatedAt | FirestoreTimestamp | yes | (Read-only) Server timestamp of the last metrics write. |
+| month | string | yes | (Read-only) YYYY-MM document ID repeated as a field. Identifies the month this rollup covers. |
+
+Example:
+```json
+{
+  "todayOrdersCount": 2,
+  "pendingOrdersCount": 2,
+  "orderCompletionRate30d": 0,
+  "todayPurchasesCount": 2,
+  "todayPurchasesSum": 0,
+  "averagePurchaseAmount": 15000,
+  "monthlyRevenue": 0,
+  "monthlyPurchasesCount": 2,
+  "todayBookingsCount": 2,
+  "bookingsCreatedToday": 0,
+  "todayBookingsConfirmedAmount": 15000,
+  "monthlyBookingsConfirmedAmount": 15000,
+  "todayCollectedAmount": 15000,
+  "todayRevenue": 0,
+  "bookingsPendingPaymentVerification": 0,
+  "bookingsPendingValidation": 0,
+  "bookingsPendingValidation24h": 0,
+  "customersCount": 2,
+  "newCustomersThisMonth": 0,
+  "averageRating": 0,
+  "lowStockItemsCount": 2,
+  "activeRecurringPaymentsCount": 2,
+  "monthlyRecurringRevenue": 0,
+  "computedForDay": "computedForDay",
+  "generatedAt": "generatedAt",
+  "month": "month"
+}
+```
+
+### Order
+Fields: 47 (8 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | yes | (Read-only) Firestore document ID. Note: some models also have uid; see ID conventions. |
+| uid | string | yes | (Read-only) Entity UID. Often mirrors id. |
+| companyId | string | yes | (Immutable) FK → Company document ID. Scopes all queries. |
+| orderNumber | string | yes | (Read-only) Server-generated order number. |
+| status | OrderStatus | yes | Core lifecycle status (D34, MIG-11). See OrderStatus enum for the legacy value migration mapping. |
+| paymentStatus | any | no | Payment lifecycle (D34). Null until payment is initiated. |
+| fulfillmentStatus | any | no | Delivery/fulfillment lifecycle (D34). |
+| returnStatus | any | no | Return/exchange lifecycle (D34). Null until a return or exchange is initiated. |
+| deliveryType | any | no | Fulfillment channel for this order (ON_SITE, PICK_UP, DELIVERY). |
+| paymentMethod | any | no | Unified payment method set with African + global methods (D02). |
+| invoiceId | ['string', 'null'] | no | FK → Invoice document ID. |
+| customerId | ['string', 'null'] | no | FK → Customer.id (Firestore doc ID). Used to resolve customer details. |
+| customerName | ['string', 'null'] | no | (Denormalized) From Customer.name at write time. |
+| customerEmail | ['string', 'null'] | no | (Denormalized) From Customer.email at write time. Canonical field per D24. |
+| customerPhone | ['string', 'null'] | no | (Denormalized) From Customer.phone at write time. Canonical field per D24. |
+| clientEmail | ['string', 'null'] | no | (Denormalized) Legacy — use `customerEmail`. D24 standardized to customer* prefix. |
+| clientPhoneNumber | ['string', 'null'] | no | (Denormalized) Legacy — use `customerPhone`. D24 standardized to customer* prefix. |
+| items | ['array', 'null'] | no |  |
+| amount | number | yes | Total order amount. Canonical field for the order total. |
+| amountPaid | ['number', 'null'] | no | Amount of `amount` paid to date. Derived from payment allocations. |
+| total | ['number', 'null'] | no | Mobile-only legacy total field. Deprecated — use `amount`. |
+| createdAt | FirestoreTimestamp | yes | (Read-only) Server-generated creation timestamp. |
+| orderDate | FirestoreTimestamp | yes | Firestore Timestamp serialized representation |
+| PROCESSING_ON | any | no | (Read-only) Timestamp when order entered PROCESSING (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase. |
+| COMPLETED_ON | any | no | (Read-only) Timestamp when order completed (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase. |
+| CANCELLED_ON | any | no | (Read-only) Timestamp when order cancelled (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase. |
+| cancellationReason | ['string', 'null'] | no |  |
+| shippingCarrier | ['string', 'null'] | no |  |
+| trackingNumber | ['string', 'null'] | no |  |
+| estimatedDeliveryDate | any | no | Firestore Timestamp serialized representation |
+| shippingCost | ['number', 'null'] | no |  |
+| paymentProofUrl | ['string', 'null'] | no | URL to uploaded payment proof image/document. |
+| paymentProofStatus | any | no | Payment proof review status. |
+| paymentProofAddedAt | any | no | (Read-only) Timestamp when proof was uploaded. |
+| paymentProofAddedBy | ['string', 'null'] | no | FK → User/staff UID who uploaded the payment proof. |
+| paymentProofReviewedAt | any | no | (Read-only) Timestamp when proof was reviewed. |
+| paymentProofReviewedBy | ['string', 'null'] | no | FK → User/staff UID who reviewed the payment proof. |
+| paymentProofRejectionReason | ['string', 'null'] | no |  |
+| paymentStatusChangeReason | ['string', 'null'] | no |  |
+| paymentStatusChangedBy | ['string', 'null'] | no | FK → User/staff UID who changed payment status. |
+| paymentStatusChangedAt | any | no | (Read-only) Timestamp of last payment status change. |
+| payments | ['array', 'null'] | no | [TBD/WIP — IG-4] Denormalized snapshots of CustomerPayments allocated to this order. Sync rules pending IG-4 resolution. |
+| totalOverridden | ['boolean', 'null'] | no | Mobile-only. When true, total was manually overridden by user (D14). |
+| notes | ['array', 'null'] | no |  |
+| additionalInfo | ['string', 'null'] | no |  |
+| appliedDiscountCode | ['string', 'null'] | no |  |
+| purchaseId | ['string', 'null'] | no | FK → Sale.id. Link to associated Sale document. |
+
+Example:
+```json
+{
+  "id": "bk_abc123def456",
+  "uid": "user_u8x92kqm",
+  "companyId": "comp_xyz789",
+  "orderNumber": "ORD-2026-0042",
+  "status": "status",
+  "paymentStatus": "paymentStatus",
+  "fulfillmentStatus": "fulfillmentStatus",
+  "returnStatus": "returnStatus",
+  "deliveryType": "deliveryType",
+  "paymentMethod": "paymentMethod",
+  "invoiceId": null,
+  "customerId": null,
+  "customerName": null,
+  "customerEmail": null,
+  "customerPhone": null,
+  "clientEmail": null,
+  "clientPhoneNumber": null,
+  "items": null,
+  "amount": 45000,
+  "amountPaid": null,
+  "total": null,
+  "createdAt": "createdAt",
+  "orderDate": "orderDate",
+  "PROCESSING_ON": "PROCESSING_ON",
+  "COMPLETED_ON": "COMPLETED_ON",
+  "CANCELLED_ON": "CANCELLED_ON",
+  "cancellationReason": null,
+  "shippingCarrier": null,
+  "trackingNumber": null,
+  "estimatedDeliveryDate": "estimatedDeliveryDate",
+  "shippingCost": null,
+  "paymentProofUrl": null,
+  "paymentProofStatus": "paymentProofStatus",
+  "paymentProofAddedAt": "paymentProofAddedAt",
+  "paymentProofAddedBy": null,
+  "paymentProofReviewedAt": "paymentProofReviewedAt",
+  "paymentProofReviewedBy": null,
+  "paymentProofRejectionReason": null,
+  "paymentStatusChangeReason": null,
+  "paymentStatusChangedBy": null,
+  "paymentStatusChangedAt": "paymentStatusChangedAt",
+  "payments": null,
+  "totalOverridden": null,
+  "notes": null,
+  "additionalInfo": null,
+  "appliedDiscountCode": null,
+  "purchaseId": null
+}
+```
+
+### OrderItem
+Fields: 12 (3 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | yes | Display name of the product or service. |
+| quantity | number | yes | Number of units ordered. |
+| price | number | yes | Unit price. Canonical name per D11. |
+| productId | ['string', 'null'] | no | FK → Product document ID. |
+| increment | ['number', 'null'] | no | Quantity step for bundle/bulk items (e.g. 5 for a 5-pack). Dashboard/Firebase only. |
+| variantId | ['string', 'null'] | no | FK → ProductVariant ID within the product. Dashboard/Firebase only. |
+| supplierId | ['string', 'null'] | no | FK → Supplier document ID. B2B orders only. |
+| supplierName | ['string', 'null'] | no | (Denormalized) From Supplier.name at write time. B2B orders only. |
+| sentAt | any | no | (Read-only) Timestamp when the item was sent to the kitchen. TBD/WIP — archived CBL flow. |
+| startedCookingAt | any | no | (Read-only) Timestamp when the kitchen started preparing this item. TBD/WIP — archived CBL flow. |
+| readyAt | any | no | (Read-only) Timestamp when the item was ready for pickup or service. TBD/WIP — archived CBL flow. |
+| servedAt | any | no | (Read-only) Timestamp when the item was served to the customer. TBD/WIP — archived CBL flow. |
+
+Example:
+```json
+{
+  "name": "Shea Butter Body Lotion",
+  "quantity": 3,
+  "price": 15000,
+  "productId": null,
+  "increment": null,
+  "variantId": null,
+  "supplierId": null,
+  "supplierName": null,
+  "sentAt": "sentAt",
+  "startedCookingAt": "startedCookingAt",
+  "readyAt": "readyAt",
+  "servedAt": "servedAt"
+}
+```
+
+### Sale
+Fields: 12 (1 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID. Note: optional in current schema — some legacy docs may lack this field. |
+| companyId | ['string', 'null'] | no | (Immutable) FK → Company document ID. Note: optional in current schema — should be required (see ID consistency audit). |
+| customerId | ['string', 'null'] | no | FK → Customer.id (Firestore doc ID). |
+| customerName | ['string', 'null'] | no | (Denormalized) From Customer.name at write time. |
+| amount | ['number', 'null'] | no |  |
+| items | ['array', 'null'] | no | Line items. Reuses Order item schema. |
+| imageUrl | ['string', 'null'] | no |  |
+| notes | ['string', 'null'] | no |  |
+| orderId | ['string', 'null'] | no | FK → Order.id. Link to associated Order document. |
+| bookingId | ['string', 'null'] | no | FK → Booking.id. Link to associated Booking document (IG-12). |
+| purchaseDate | FirestoreTimestamp | yes | Firestore Timestamp serialized representation |
+| createdAt | any | no | (Read-only) Server-generated creation timestamp. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": null,
+  "customerId": null,
+  "customerName": null,
+  "amount": null,
+  "items": null,
+  "imageUrl": null,
+  "notes": null,
+  "orderId": null,
+  "bookingId": null,
+  "purchaseDate": "purchaseDate",
+  "createdAt": "createdAt"
+}
+```
+
+### Ticket
+Fields: 16 (6 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | yes | (Read-only) Firestore document ID. Note: Ticket does not have a uid field. |
+| eventId | string | yes | (Immutable) FK → Event.id. Parent event this ticket belongs to. Set at creation. |
+| companyId | string | yes | (Immutable, Denormalized) FK → Company document ID. Denormalized from parent Event for direct queries. |
+| customerId | ['string', 'null'] | no | FK → Customer.id. Optional structured link to Customer document (D29). Added additively alongside denormalized fields. |
+| customerName | ['string', 'null'] | no | (Denormalized) From Customer.name at write time. |
+| customerEmail | ['string', 'null'] | no | (Denormalized) From Customer.email at write time. |
+| customerPhone | ['string', 'null'] | no | (Denormalized) From Customer.phone at write time. |
+| status | TicketStatus | yes | Ticket lifecycle (D32). SCREAMING_SNAKE per D04. MIG-10 migrates legacy lowercase values. |
+| usedAt | any | no | (Read-only) Timestamp when ticket was scanned/used. Set by scan operation. |
+| usedBy | ['string', 'null'] | no | (Read-only) FK → User/staff UID who scanned the ticket. |
+| usedByName | ['string', 'null'] | no | (Read-only, Denormalized) From User display name at scan time. |
+| price | ['number', 'null'] | no |  |
+| notes | ['string', 'null'] | no |  |
+| createdAt | FirestoreTimestamp | yes | (Read-only) Server-generated creation timestamp. |
+| updatedAt | FirestoreTimestamp | yes | (Read-only) Server-generated update timestamp. |
+| createdBy | ['string', 'null'] | no | (Immutable) FK → User/staff UID who created this ticket. |
+
+Example:
+```json
+{
+  "id": "bk_abc123def456",
+  "eventId": "eve_ref123",
+  "companyId": "comp_xyz789",
+  "customerId": null,
+  "customerName": null,
+  "customerEmail": null,
+  "customerPhone": null,
+  "status": "status",
+  "usedAt": "usedAt",
+  "usedBy": null,
+  "usedByName": null,
+  "price": null,
+  "notes": null,
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt",
+  "createdBy": null
+}
+```
+
+---
+
+## Proposed (Work In Progress)
+
+> These schemas are under review and not yet part of @valets/schema. Shape may change.
+
+### Proposed Models
+
+#### PaymentSummary [proposed]
+Fields: 10 (9 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | yes | (Read-only) Firestore document ID. Matches the period key (e.g. "2026-03-09" for DAILY, "2026-03" for MONTHLY). |
+| companyId | string | yes | (Immutable) FK → Company document ID. Scopes all queries. |
+| period | string | yes | Period key. Determines the document ID and the time window covered. |
+| periodType | enum(3) | yes | Granularity of this summary document. |
+| paymentsByMethod | record<string,object> | yes | Payment totals broken down by PaymentMethod. Each entry holds the total amount and transaction count for the period. |
+| grandTotal | number | yes | (Read-only) Sum of all paymentsByMethod[*].total. Server-calculated. |
+| totalCount | integer | yes | (Read-only) Sum of all paymentsByMethod[*].count. Server-calculated. |
+| currency | string | yes | Currency code. Locked to XOF (West African CFA franc). |
+| lastUpdatedAt | Timestamp | no | (Read-only) Server timestamp of the last increment write. |
+| createdAt | Timestamp | yes | (Read-only) Server-generated creation timestamp. |
+
+Example:
+```json
+{
+  "id": "bk_abc123def456",
+  "companyId": "comp_xyz789",
+  "period": "period",
+  "periodType": "DAILY",
+  "paymentsByMethod": {},
+  "grandTotal": 0,
+  "totalCount": 2,
+  "currency": "XOF",
+  "lastUpdatedAt": {
+    "_seconds": 1768478400,
+    "_nanoseconds": 0
+  },
+  "createdAt": {
+    "_seconds": 1768478400,
+    "_nanoseconds": 0
+  }
+}
+```
+