@ingenx-io/valets-schema-mcp-server 0.1.4 → 0.1.6

package/data/docs/models/stocktake-item.md

@@ -0,0 +1,500 @@
+---
+title: "StocktakeItem"
+sidebar_label: "StocktakeItem"
+sidebar_position: 26
+---
+
+# StocktakeItem
+
+<details>
+<summary>Example JSON</summary>
+
+```json
+{
+  "stockItemId": "sto_ref123",
+  "stockItemName": "stockItemName",
+  "theoreticalQuantity": 2,
+  "actualQuantity": "actualQuantity",
+  "delta": 0,
+  "unit": "unit",
+  "costPerUnit": 15000,
+  "totalValue": 0,
+  "status": "status",
+  "notes": "VIP customer, handle with care",
+  "countedBy": "countedBy",
+  "countedByName": "countedByName",
+  "countedAt": "countedAt",
+  "verifiedBy": "verifiedBy",
+  "verifiedByName": "verifiedByName",
+  "verifiedAt": "verifiedAt"
+}
+```
+
+</details>
+
+
+- [1. Property `stockItemId`](#stockItemId)
+- [2. Property `stockItemName`](#stockItemName)
+- [3. Property `theoreticalQuantity`](#theoreticalQuantity)
+- [4. Property `actualQuantity`](#actualQuantity)
+  - [4.1. Property `item 0`](#actualQuantity_anyOf_i0)
+  - [4.2. Property `item 1`](#actualQuantity_anyOf_i1)
+- [5. Property `delta`](#delta)
+- [6. Property `unit`](#unit)
+- [7. Property `costPerUnit`](#costPerUnit)
+- [8. Property `totalValue`](#totalValue)
+- [9. Property `status`](#status)
+- [10. Property `notes`](#notes)
+  - [10.1. Property `item 0`](#notes_anyOf_i0)
+  - [10.2. Property `item 1`](#notes_anyOf_i1)
+- [11. Property `countedBy`](#countedBy)
+  - [11.1. Property `item 0`](#countedBy_anyOf_i0)
+  - [11.2. Property `item 1`](#countedBy_anyOf_i1)
+- [12. Property `countedByName`](#countedByName)
+  - [12.1. Property `item 0`](#countedByName_anyOf_i0)
+  - [12.2. Property `item 1`](#countedByName_anyOf_i1)
+- [13. Property `countedAt`](#countedAt)
+  - [13.1. Property `firestore-timestamp`](#countedAt_anyOf_i0)
+    - [13.1.1. Property `_seconds`](#countedAt_anyOf_i0__seconds)
+    - [13.1.2. Property `_nanoseconds`](#countedAt_anyOf_i0__nanoseconds)
+  - [13.2. Property `item 1`](#countedAt_anyOf_i1)
+- [14. Property `verifiedBy`](#verifiedBy)
+  - [14.1. Property `item 0`](#verifiedBy_anyOf_i0)
+  - [14.2. Property `item 1`](#verifiedBy_anyOf_i1)
+- [15. Property `verifiedByName`](#verifiedByName)
+  - [15.1. Property `item 0`](#verifiedByName_anyOf_i0)
+  - [15.2. Property `item 1`](#verifiedByName_anyOf_i1)
+- [16. Property `verifiedAt`](#verifiedAt)
+  - [16.1. Property `firestore-timestamp`](#verifiedAt_anyOf_i0)
+  - [16.2. Property `item 1`](#verifiedAt_anyOf_i1)
+
+|                           |                              |
+| ------------------------- | ---------------------------- |
+| **Type**                  | `object`                     |
+| **Required**              | No                           |
+| **Additional properties** | Not allowed                  |
+| **Defined in**            | #/definitions/stocktake-item |
+
+**Description:** StocktakeItem (GH#29 §4). Sub-collection path: companies/\{companyId\}/stocktakes/\{stocktakeId\}/items/\{stockItemId\}. Replaces the embedded `InventoryItem[]` array on the dashboard model. Server emits one StockMovement(type=INVENTORY) per non-zero delta when the parent Stocktake transitions to COMPLETED.
+
+| Property                                       | Pattern | Type             | Deprecated | Definition                             | Title/Description                                                                                                                    |
+| ---------------------------------------------- | ------- | ---------------- | ---------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| + [stockItemId](#stockItemId )                 | No      | string           | No         | -                                      | FK → StockItem document ID. Doubles as the item document ID.                                                                         |
+| + [stockItemName](#stockItemName )             | No      | string           | No         | -                                      | (Denormalized) Snapshot of StockItem.name at session time.                                                                           |
+| + [theoreticalQuantity](#theoreticalQuantity ) | No      | number           | No         | -                                      | (Immutable) System belief at session start, snapshotted when this item row was created.                                              |
+| - [actualQuantity](#actualQuantity )           | No      | Combination      | No         | -                                      | Physical count entered by the counter. Null until counted; set when the line moves to status COUNTED.                                |
+| + [delta](#delta )                             | No      | number           | No         | -                                      | (Read-only) Signed difference between actual and theoretical. Drives the StockMovement(type=INVENTORY) emitted on session COMPLETED. |
+| + [unit](#unit )                               | No      | string           | No         | -                                      | (Immutable) Snapshot of StockItem.unit at session start. Locks the unit against later catalog changes.                               |
+| + [costPerUnit](#costPerUnit )                 | No      | number           | No         | -                                      | (Immutable) Snapshot of StockItem.costPerUnit at session start, in XOF integer minor units.                                          |
+| + [totalValue](#totalValue )                   | No      | number           | No         | -                                      | (Read-only) Per-line valuation in XOF integer minor units.                                                                           |
+| + [status](#status )                           | No      | enum (of string) | No         | In #/definitions/stocktake-item-status | Per-line workflow status. Server transitions ADJUSTED on parent COMPLETED.                                                           |
+| - [notes](#notes )                             | No      | Combination      | No         | -                                      | Optional per-line note from the counter (e.g. "damaged carton, 3 unsellable").                                                       |
+| - [countedBy](#countedBy )                     | No      | Combination      | No         | -                                      | UID of the staff member who entered actualQuantity.                                                                                  |
+| - [countedByName](#countedByName )             | No      | Combination      | No         | -                                      | (Denormalized) Snapshot of the counter's display name at count time.                                                                 |
+| - [countedAt](#countedAt )                     | No      | Combination      | No         | -                                      | When the line was counted.                                                                                                           |
+| - [verifiedBy](#verifiedBy )                   | No      | Combination      | No         | -                                      | UID of a second staff member who verified the count. Nullable per GH#29 Q21.                                                         |
+| - [verifiedByName](#verifiedByName )           | No      | Combination      | No         | -                                      | (Denormalized) Snapshot of the verifier's display name.                                                                              |
+| - [verifiedAt](#verifiedAt )                   | No      | Combination      | No         | -                                      | When the line was verified, if a second-eye flow was used.                                                                           |
+
+## <a name="stockItemId"></a>1. Property `stockItemId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** FK → StockItem document ID. Doubles as the item document ID.
+
+## <a name="stockItemName"></a>2. Property `stockItemName`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Denormalized) Snapshot of StockItem.name at session time.
+
+:::note
+Read-time hint snapshot of StockItem.name. Authoritative value lives at the StockItem record; do not refresh on rename — the historical name at session time is what the auditor wrote (GH#29 §3 / Q10).
+:::
+
+## <a name="theoreticalQuantity"></a>3. Property `theoreticalQuantity`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) System belief at session start, snapshotted when this item row was created.
+
+:::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="actualQuantity"></a>4. Property `actualQuantity`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** Physical count entered by the counter. Null until counted; set when the line moves to status COUNTED.
+
+| Any of(Option)                     |
+| ---------------------------------- |
+| [item 0](#actualQuantity_anyOf_i0) |
+| [item 1](#actualQuantity_anyOf_i1) |
+
+### <a name="actualQuantity_anyOf_i0"></a>4.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | No       |
+
+### <a name="actualQuantity_anyOf_i1"></a>4.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+## <a name="delta"></a>5. Property `delta`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** (Read-only) Signed difference between actual and theoretical. Drives the StockMovement(type=INVENTORY) emitted on session COMPLETED.
+
+:::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.
+:::
+
+:::note
+Server-derived = actualQuantity − theoreticalQuantity. Recomputed on every actualQuantity write; null/zero before counting.
+:::
+
+## <a name="unit"></a>6. Property `unit`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) Snapshot of StockItem.unit at session start. Locks the unit against later catalog changes.
+
+:::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="costPerUnit"></a>7. Property `costPerUnit`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) Snapshot of StockItem.costPerUnit at session start, in XOF integer minor units.
+
+:::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.
+:::
+
+:::note
+Snapshot at session time — locks valuation against future cost changes. Lock to XOF integer minor units per D18 (GH#29 Q16).
+:::
+
+## <a name="totalValue"></a>8. Property `totalValue`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** (Read-only) Per-line valuation in XOF integer minor units.
+
+:::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.
+:::
+
+:::note
+Server-derived = actualQuantity × costPerUnit. Recomputed when actualQuantity is written.
+:::
+
+## <a name="status"></a>9. Property `status`
+
+|                |                                     |
+| -------------- | ----------------------------------- |
+| **Type**       | `enum (of string)`                  |
+| **Required**   | Yes                                 |
+| **Defined in** | #/definitions/stocktake-item-status |
+
+**Description:** Per-line workflow status. Server transitions ADJUSTED on parent COMPLETED.
+
+Must be one of:
+* "PENDING"
+* "COUNTED"
+* "VERIFIED"
+* "ADJUSTED"
+
+:::note
+PENDING = line not yet counted. COUNTED = a counter recorded actualQuantity. VERIFIED = a second pair of eyes signed off (verifiedBy fields populated; Q21 — kept nullable until tenants opt into stricter QA via policy). ADJUSTED = the resulting StockMovement was emitted (server-set on Stocktake.status → COMPLETED).
+:::
+
+:::info See also
+**Issues:** `gh#29`
+:::
+
+## <a name="notes"></a>10. Property `notes`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** Optional per-line note from the counter (e.g. "damaged carton, 3 unsellable").
+
+| Any of(Option)            |
+| ------------------------- |
+| [item 0](#notes_anyOf_i0) |
+| [item 1](#notes_anyOf_i1) |
+
+### <a name="notes_anyOf_i0"></a>10.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+### <a name="notes_anyOf_i1"></a>10.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+## <a name="countedBy"></a>11. Property `countedBy`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** UID of the staff member who entered actualQuantity.
+
+| Any of(Option)                |
+| ----------------------------- |
+| [item 0](#countedBy_anyOf_i0) |
+| [item 1](#countedBy_anyOf_i1) |
+
+### <a name="countedBy_anyOf_i0"></a>11.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+### <a name="countedBy_anyOf_i1"></a>11.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+## <a name="countedByName"></a>12. Property `countedByName`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Denormalized) Snapshot of the counter's display name at count time.
+
+| Any of(Option)                    |
+| --------------------------------- |
+| [item 0](#countedByName_anyOf_i0) |
+| [item 1](#countedByName_anyOf_i1) |
+
+### <a name="countedByName_anyOf_i0"></a>12.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+### <a name="countedByName_anyOf_i1"></a>12.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+:::note
+Read-time hint snapshot of the counter's display name (GH#29 §3 / Q10).
+:::
+
+## <a name="countedAt"></a>13. Property `countedAt`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** When the line was counted.
+
+| Any of(Option)                             |
+| ------------------------------------------ |
+| [firestore-timestamp](#countedAt_anyOf_i0) |
+| [item 1](#countedAt_anyOf_i1)              |
+
+### <a name="countedAt_anyOf_i0"></a>13.1. Property `firestore-timestamp`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | No                                |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** Firestore Timestamp serialized representation
+
+| Property                                            | Pattern | Type    | Deprecated | Definition | Title/Description |
+| --------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#countedAt_anyOf_i0__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#countedAt_anyOf_i0__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+#### <a name="countedAt_anyOf_i0__seconds"></a>13.1.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+#### <a name="countedAt_anyOf_i0__nanoseconds"></a>13.1.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="countedAt_anyOf_i1"></a>13.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+## <a name="verifiedBy"></a>14. Property `verifiedBy`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** UID of a second staff member who verified the count. Nullable per GH#29 Q21.
+
+| Any of(Option)                 |
+| ------------------------------ |
+| [item 0](#verifiedBy_anyOf_i0) |
+| [item 1](#verifiedBy_anyOf_i1) |
+
+### <a name="verifiedBy_anyOf_i0"></a>14.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+### <a name="verifiedBy_anyOf_i1"></a>14.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+## <a name="verifiedByName"></a>15. Property `verifiedByName`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Denormalized) Snapshot of the verifier's display name.
+
+| Any of(Option)                     |
+| ---------------------------------- |
+| [item 0](#verifiedByName_anyOf_i0) |
+| [item 1](#verifiedByName_anyOf_i1) |
+
+### <a name="verifiedByName_anyOf_i0"></a>15.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+### <a name="verifiedByName_anyOf_i1"></a>15.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+:::note
+Read-time hint snapshot of the verifier's display name (GH#29 §3 / Q10).
+:::
+
+## <a name="verifiedAt"></a>16. Property `verifiedAt`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** When the line was verified, if a second-eye flow was used.
+
+| Any of(Option)                              |
+| ------------------------------------------- |
+| [firestore-timestamp](#verifiedAt_anyOf_i0) |
+| [item 1](#verifiedAt_anyOf_i1)              |
+
+### <a name="verifiedAt_anyOf_i0"></a>16.1. Property `firestore-timestamp`
+
+|                           |                                           |
+| ------------------------- | ----------------------------------------- |
+| **Type**                  | `object`                                  |
+| **Required**              | No                                        |
+| **Additional properties** | Not allowed                               |
+| **Same definition as**    | [countedAt_anyOf_i0](#countedAt_anyOf_i0) |
+
+**Description:** Firestore Timestamp serialized representation
+
+### <a name="verifiedAt_anyOf_i1"></a>16.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-05 at 12:09:28 +0000