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

package/data/docs/models/payment-summary.md

@@ -0,0 +1,123 @@
+---
+title: "PaymentSummary"
+sidebar_label: "PaymentSummary"
+sidebar_position: 99
+---
+
+# PaymentSummary
+
+**Collection:** `companies/{companyId}/paymentSummaries/{period}`
+
+Aggregated payment totals broken down by payment method for a given period. This is a **server-owned, read-only** model — clients never write to it directly. It is maintained by Cloud Function triggers that fire on `Order.payments[]` and `CustomerPayment` changes.
+
+## Schema
+
+<details>
+<summary>Example JSON</summary>
+
+```json
+{
+  "id": "2026-03-09",
+  "companyId": "comp_xyz789",
+  "period": "2026-03-09",
+  "periodType": "DAILY",
+  "paymentsByMethod": {
+    "CASH": { "total": 245000, "count": 12 },
+    "WAVE": { "total": 180000, "count": 8 },
+    "ORANGE_MONEY": { "total": 95000, "count": 5 }
+  },
+  "grandTotal": 520000,
+  "totalCount": 25,
+  "currency": "XOF",
+  "lastUpdatedAt": { "_seconds": 1741478400, "_nanoseconds": 0 },
+  "createdAt": { "_seconds": 1741435200, "_nanoseconds": 0 }
+}
+```
+
+</details>
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | — | (Read-only) Document ID. Matches the period key. |
+| `companyId` | `string` | + | (Immutable) FK → Company document ID. |
+| `period` | `string` | + | Period key: `YYYY-MM-DD` (daily), `YYYY-Www` (weekly), `YYYY-MM` (monthly). |
+| `periodType` | `enum` | + | `DAILY`, `WEEKLY`, or `MONTHLY`. |
+| `paymentsByMethod` | `map` | + | Keyed by PaymentMethod enum value. Each value has `total` (number) and `count` (integer). |
+| `grandTotal` | `number` | + | (Read-only) Sum of all `paymentsByMethod[*].total`. |
+| `totalCount` | `integer` | + | (Read-only) Sum of all `paymentsByMethod[*].count`. |
+| `currency` | `string` | + | Locked to `XOF`. |
+| `lastUpdatedAt` | `Timestamp` | — | (Read-only) Last increment timestamp. |
+| `createdAt` | `Timestamp` | + | (Read-only) Server-generated creation timestamp. |
+
+:::info PaymentMethod keys
+The `paymentsByMethod` map uses [PaymentMethod](/enums/payment-method) enum values as keys: `CASH`, `WAVE`, `ORANGE_MONEY`, `CREDIT_CARD`, etc. Missing keys imply zero for that method.
+:::
+
+:::warning Server-owned
+This document is entirely server-set. All fields are computed by Cloud Function triggers. Clients should treat it as read-only.
+:::
+
+## Trigger design
+
+### Source events
+
+The summary is updated by **two independent triggers**:
+
+1. **`onOrderPaymentChange`** — fires when `Order.payments[]` array changes (new payment added or existing payment updated). Computes the delta and applies `FieldValue.increment()` to the matching `paymentsByMethod.{method}.total` and `.count`, plus `grandTotal` and `totalCount`.
+
+2. **`onCustomerPaymentWrite`** — fires on `CustomerPayment` create/update. Same increment logic for standalone customer payments not tied to an order.
+
+### Increment pattern
+
+```typescript
+// Pseudo-code for the trigger
+const summaryRef = db.doc(
+  `companies/${companyId}/paymentSummaries/${todayKey}`
+);
+
+await summaryRef.set({
+  companyId,
+  period: todayKey,
+  periodType: 'DAILY',
+  currency: 'XOF',
+  [`paymentsByMethod.${method}.total`]: FieldValue.increment(amount),
+  [`paymentsByMethod.${method}.count`]: FieldValue.increment(1),
+  grandTotal: FieldValue.increment(amount),
+  totalCount: FieldValue.increment(1),
+  lastUpdatedAt: FieldValue.serverTimestamp(),
+  createdAt: FieldValue.serverTimestamp(), // only sets on first write (merge)
+}, { merge: true });
+```
+
+### Idempotency
+
+To avoid double-counting on trigger retries, the trigger should check if the payment has already been counted (e.g., via a `_summarized` flag on the payment or by comparing `before`/`after` snapshots in the `onUpdate` trigger).
+
+### Rollups
+
+A scheduled Cloud Function (daily at midnight WAT) can roll up daily summaries into weekly and monthly documents. This is optional — daily granularity alone may be sufficient for the dashboard.
+
+## Querying
+
+```typescript
+// Get today's summary
+const today = '2026-03-09';
+const snap = await db.doc(`companies/${companyId}/paymentSummaries/${today}`).get();
+const summary = snap.data(); // PaymentSummary
+
+// Get summaries for a date range
+const snaps = await db.collection(`companies/${companyId}/paymentSummaries`)
+  .where('periodType', '==', 'DAILY')
+  .where('period', '>=', '2026-03-01')
+  .where('period', '<=', '2026-03-09')
+  .get();
+```
+
+## Related
+
+- [PaymentMethod](/enums/payment-method) — enum used as map keys
+- [CustomerPayment](/models/customer-payment) — source event for trigger
+- [Order](/models/order) — `payments[]` array is the other source event
+- Decision D02 — Unified PaymentMethod enum

package/data/docs/models/sale.md

@@ -0,0 +1,540 @@
+---
+title: "Sale"
+sidebar_label: "Sale"
+sidebar_position: 16
+---
+
+# Sale
+
+<details>
+<summary>Example JSON</summary>
+
+```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"
+}
+```
+
+</details>
+
+
+- [1. Property `id`](#id)
+- [2. Property `companyId`](#companyId)
+- [3. Property `customerId`](#customerId)
+- [4. Property `customerName`](#customerName)
+- [5. Property `amount`](#amount)
+- [6. Property `items`](#items)
+  - [6.1. order-item](#items_items)
+    - [6.1.1. Property `name`](#items_items_name)
+    - [6.1.2. Property `quantity`](#items_items_quantity)
+    - [6.1.3. Property `price`](#items_items_price)
+    - [6.1.4. Property `productId`](#items_items_productId)
+    - [6.1.5. Property `increment`](#items_items_increment)
+    - [6.1.6. Property `variantId`](#items_items_variantId)
+    - [6.1.7. Property `supplierId`](#items_items_supplierId)
+    - [6.1.8. Property `supplierName`](#items_items_supplierName)
+    - [6.1.9. Property `sentAt`](#items_items_sentAt)
+      - [6.1.9.1. Property `_seconds`](#items_items_sentAt__seconds)
+      - [6.1.9.2. Property `_nanoseconds`](#items_items_sentAt__nanoseconds)
+    - [6.1.10. Property `startedCookingAt`](#items_items_startedCookingAt)
+      - [6.1.10.1. Property `_seconds`](#items_items_startedCookingAt__seconds)
+      - [6.1.10.2. Property `_nanoseconds`](#items_items_startedCookingAt__nanoseconds)
+    - [6.1.11. Property `readyAt`](#items_items_readyAt)
+      - [6.1.11.1. Property `_seconds`](#items_items_readyAt__seconds)
+      - [6.1.11.2. Property `_nanoseconds`](#items_items_readyAt__nanoseconds)
+    - [6.1.12. Property `servedAt`](#items_items_servedAt)
+      - [6.1.12.1. Property `_seconds`](#items_items_servedAt__seconds)
+      - [6.1.12.2. Property `_nanoseconds`](#items_items_servedAt__nanoseconds)
+- [7. Property `imageUrl`](#imageUrl)
+- [8. Property `notes`](#notes)
+- [9. Property `orderId`](#orderId)
+- [10. Property `bookingId`](#bookingId)
+- [11. Property `purchaseDate`](#purchaseDate)
+  - [11.1. Property `_seconds`](#purchaseDate__seconds)
+  - [11.2. Property `_nanoseconds`](#purchaseDate__nanoseconds)
+- [12. Property `createdAt`](#createdAt)
+  - [12.1. Property `firestore-timestamp`](#createdAt_anyOf_i0)
+  - [12.2. Property `item 1`](#createdAt_anyOf_i1)
+
+|                           |                    |
+| ------------------------- | ------------------ |
+| **Type**                  | `object`           |
+| **Required**              | No                 |
+| **Deprecated**            |
+| **Additional properties** | Not allowed        |
+| **Defined in**            | #/definitions/sale |
+
+**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]
+
+| Property                         | Pattern | Type           | Deprecated | Definition                           | Title/Description                                                                                                       |
+| -------------------------------- | ------- | -------------- | ---------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| - [id](#id )                     | No      | string or null | No         | -                                    | (Read-only) Firestore document ID. Note: optional in current schema — some legacy docs may lack this field.             |
+| - [companyId](#companyId )       | No      | string or null | No         | -                                    | (Immutable) FK → Company document ID. Note: optional in current schema — should be required (see ID consistency audit). |
+| - [customerId](#customerId )     | No      | string or null | No         | -                                    | FK → Customer.id (Firestore doc ID).                                                                                    |
+| - [customerName](#customerName ) | No      | string or null | No         | -                                    | (Denormalized) From Customer.name at write time.                                                                        |
+| - [amount](#amount )             | No      | number or null | No         | -                                    | -                                                                                                                       |
+| - [items](#items )               | No      | array or null  | No         | -                                    | Line items. Reuses Order item schema.                                                                                   |
+| - [imageUrl](#imageUrl )         | No      | string or null | No         | -                                    | -                                                                                                                       |
+| - [notes](#notes )               | No      | string or null | No         | -                                    | -                                                                                                                       |
+| - [orderId](#orderId )           | No      | string or null | No         | -                                    | FK → Order.id. Link to associated Order document.                                                                       |
+| - [bookingId](#bookingId )       | No      | string or null | No         | -                                    | FK → Booking.id. Link to associated Booking document (IG-12).                                                           |
+| + [purchaseDate](#purchaseDate ) | No      | object         | No         | In #/definitions/firestore-timestamp | Firestore Timestamp serialized representation                                                                           |
+| - [createdAt](#createdAt )       | No      | Combination    | No         | -                                    | (Read-only) Server-generated creation timestamp.                                                                        |
+
+## <a name="id"></a>1. Property `id`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Read-only) Firestore document ID. Note: optional in current schema — some legacy docs may lack this field.
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="companyId"></a>2. Property `companyId`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Immutable) FK → Company document ID. Note: optional in current schema — should be required (see ID consistency audit).
+
+:::info Immutable
+Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
+:::
+
+## <a name="customerId"></a>3. Property `customerId`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** FK → Customer.id (Firestore doc ID).
+
+## <a name="customerName"></a>4. Property `customerName`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Denormalized) From Customer.name at write time.
+
+## <a name="amount"></a>5. Property `amount`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `number or null` |
+| **Required** | No               |
+
+## <a name="items"></a>6. Property `items`
+
+|              |                 |
+| ------------ | --------------- |
+| **Type**     | `array or null` |
+| **Required** | No              |
+
+**Description:** Line items. Reuses Order item schema.
+
+|                      | Array restrictions |
+| -------------------- | ------------------ |
+| **Min items**        | N/A                |
+| **Max items**        | N/A                |
+| **Items unicity**    | False              |
+| **Additional items** | False              |
+| **Tuple validation** | See below          |
+
+| Each item of this array must be | Description                                                                                                                                                                                                                                                                                       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [order-item](#items_items)      | 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. |
+
+### <a name="items_items"></a>6.1. order-item
+
+|                           |                          |
+| ------------------------- | ------------------------ |
+| **Type**                  | `object`                 |
+| **Required**              | No                       |
+| **Additional properties** | Not allowed              |
+| **Defined in**            | #/definitions/order-item |
+
+**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.
+
+| Property                                             | Pattern | Type   | Deprecated | Definition | Title/Description                                                                                 |
+| ---------------------------------------------------- | ------- | ------ | ---------- | ---------- | ------------------------------------------------------------------------------------------------- |
+| + [name](#items_items_name )                         | No      | string | No         | -          | Display name of the product or service.                                                           |
+| + [quantity](#items_items_quantity )                 | No      | number | No         | -          | Number of units ordered.                                                                          |
+| + [price](#items_items_price )                       | No      | number | No         | -          | Unit price. Canonical name per D11.                                                               |
+| - [productId](#items_items_productId )               | No      | string | No         | -          | FK → Product document ID.                                                                         |
+| - [increment](#items_items_increment )               | No      | number | No         | -          | Quantity step for bundle/bulk items (e.g. 5 for a 5-pack). Dashboard/Firebase only.               |
+| - [variantId](#items_items_variantId )               | No      | string | No         | -          | FK → ProductVariant ID within the product. Dashboard/Firebase only.                               |
+| - [supplierId](#items_items_supplierId )             | No      | string | No         | -          | FK → Supplier document ID. B2B orders only.                                                       |
+| - [supplierName](#items_items_supplierName )         | No      | string | No         | -          | (Denormalized) From Supplier.name at write time. B2B orders only.                                 |
+| - [sentAt](#items_items_sentAt )                     | No      | object | No         | -          | (Read-only) Timestamp when the item was sent to the kitchen. TBD/WIP — archived CBL flow.         |
+| - [startedCookingAt](#items_items_startedCookingAt ) | No      | object | No         | -          | (Read-only) Timestamp when the kitchen started preparing this item. TBD/WIP — archived CBL flow.  |
+| - [readyAt](#items_items_readyAt )                   | No      | object | No         | -          | (Read-only) Timestamp when the item was ready for pickup or service. TBD/WIP — archived CBL flow. |
+| - [servedAt](#items_items_servedAt )                 | No      | object | No         | -          | (Read-only) Timestamp when the item was served to the customer. TBD/WIP — archived CBL flow.      |
+
+#### <a name="items_items_name"></a>6.1.1. Property `name`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Display name of the product or service.
+
+#### <a name="items_items_quantity"></a>6.1.2. Property `quantity`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** Number of units ordered.
+
+#### <a name="items_items_price"></a>6.1.3. Property `price`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** Unit price. Canonical name per D11.
+
+#### <a name="items_items_productId"></a>6.1.4. Property `productId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** FK → Product document ID.
+
+#### <a name="items_items_increment"></a>6.1.5. Property `increment`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | No       |
+
+**Description:** Quantity step for bundle/bulk items (e.g. 5 for a 5-pack). Dashboard/Firebase only.
+
+#### <a name="items_items_variantId"></a>6.1.6. Property `variantId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** FK → ProductVariant ID within the product. Dashboard/Firebase only.
+
+#### <a name="items_items_supplierId"></a>6.1.7. Property `supplierId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** FK → Supplier document ID. B2B orders only.
+
+#### <a name="items_items_supplierName"></a>6.1.8. Property `supplierName`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** (Denormalized) From Supplier.name at write time. B2B orders only.
+
+#### <a name="items_items_sentAt"></a>6.1.9. Property `sentAt`
+
+|                           |             |
+| ------------------------- | ----------- |
+| **Type**                  | `object`    |
+| **Required**              | No          |
+| **Additional properties** | Not allowed |
+
+**Description:** (Read-only) Timestamp when the item was sent to the kitchen. TBD/WIP — archived CBL flow.
+
+| Property                                            | Pattern | Type    | Deprecated | Definition | Title/Description |
+| --------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#items_items_sentAt__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#items_items_sentAt__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+##### <a name="items_items_sentAt__seconds"></a>6.1.9.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+##### <a name="items_items_sentAt__nanoseconds"></a>6.1.9.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+#### <a name="items_items_startedCookingAt"></a>6.1.10. Property `startedCookingAt`
+
+|                           |             |
+| ------------------------- | ----------- |
+| **Type**                  | `object`    |
+| **Required**              | No          |
+| **Additional properties** | Not allowed |
+
+**Description:** (Read-only) Timestamp when the kitchen started preparing this item. TBD/WIP — archived CBL flow.
+
+| Property                                                      | Pattern | Type    | Deprecated | Definition | Title/Description |
+| ------------------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#items_items_startedCookingAt__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#items_items_startedCookingAt__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+##### <a name="items_items_startedCookingAt__seconds"></a>6.1.10.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+##### <a name="items_items_startedCookingAt__nanoseconds"></a>6.1.10.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+#### <a name="items_items_readyAt"></a>6.1.11. Property `readyAt`
+
+|                           |             |
+| ------------------------- | ----------- |
+| **Type**                  | `object`    |
+| **Required**              | No          |
+| **Additional properties** | Not allowed |
+
+**Description:** (Read-only) Timestamp when the item was ready for pickup or service. TBD/WIP — archived CBL flow.
+
+| Property                                             | Pattern | Type    | Deprecated | Definition | Title/Description |
+| ---------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#items_items_readyAt__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#items_items_readyAt__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+##### <a name="items_items_readyAt__seconds"></a>6.1.11.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+##### <a name="items_items_readyAt__nanoseconds"></a>6.1.11.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+#### <a name="items_items_servedAt"></a>6.1.12. Property `servedAt`
+
+|                           |             |
+| ------------------------- | ----------- |
+| **Type**                  | `object`    |
+| **Required**              | No          |
+| **Additional properties** | Not allowed |
+
+**Description:** (Read-only) Timestamp when the item was served to the customer. TBD/WIP — archived CBL flow.
+
+| Property                                              | Pattern | Type    | Deprecated | Definition | Title/Description |
+| ----------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#items_items_servedAt__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#items_items_servedAt__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+##### <a name="items_items_servedAt__seconds"></a>6.1.12.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+##### <a name="items_items_servedAt__nanoseconds"></a>6.1.12.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+## <a name="imageUrl"></a>7. Property `imageUrl`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+## <a name="notes"></a>8. Property `notes`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+## <a name="orderId"></a>9. Property `orderId`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** FK → Order.id. Link to associated Order document.
+
+## <a name="bookingId"></a>10. Property `bookingId`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** FK → Booking.id. Link to associated Booking document (IG-12).
+
+## <a name="purchaseDate"></a>11. Property `purchaseDate`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | Yes                               |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** Firestore Timestamp serialized representation
+
+| Property                                      | Pattern | Type    | Deprecated | Definition | Title/Description |
+| --------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#purchaseDate__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#purchaseDate__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+### <a name="purchaseDate__seconds"></a>11.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="purchaseDate__nanoseconds"></a>11.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+## <a name="createdAt"></a>12. Property `createdAt`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Read-only) Server-generated creation timestamp.
+
+| Any of(Option)                             |
+| ------------------------------------------ |
+| [firestore-timestamp](#createdAt_anyOf_i0) |
+| [item 1](#createdAt_anyOf_i1)              |
+
+### <a name="createdAt_anyOf_i0"></a>12.1. Property `firestore-timestamp`
+
+|                           |                               |
+| ------------------------- | ----------------------------- |
+| **Type**                  | `object`                      |
+| **Required**              | No                            |
+| **Additional properties** | Not allowed                   |
+| **Same definition as**    | [purchaseDate](#purchaseDate) |
+
+**Description:** Firestore Timestamp serialized representation
+
+### <a name="createdAt_anyOf_i1"></a>12.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## Related Decisions
+
+| Decision | Title |
+|---|---|
+| **D05** | Canonical purchase amount field |
+| **D06** | Canonical sales collection path |
+| **D12** | Payments canonical location model |
+| **D15** | Should SaleMargin be server-side |