toga-ai 1.0.298 → 1.0.299

package/knowledge/clients/nycdoe/features/servicenow-integration.md

@@ -6,8 +6,8 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-06-19
-owners: [mhammontree]
+updated: 2026-07-09
+owners: [mhammontree, sking]
 files:
   - worker/crons/sync/nycdoe/import_asn.php
   - worker/crons/sync/nycdoe/import_inc.php
@@ -17,6 +17,7 @@ files:
   - worker/crons/sync/nycdoe/1_send_asn_to_netsuite.php
   - worker/crons/sync/nycdoe/2_send_serials_to_netsuite.php
   - worker/crons/sync/nycdoe/3_create_installation_ticket.php
+  - worker/crons/sync/nycdoe/test_multi_po_receipt_resolution.php
   - worker/crons/sync/nycdoe/send_ticket_updates.php
   - worker/crons/sync/nycdoe/send_request_item_updates.php
   - worker/crons/sync/nycdoe/send_nycdoe_proof_of_delivery.php
@@ -34,6 +35,7 @@ files:
   - library/app/asnprocessor/lexmark.php
   - library/app/asnprocessor/acer.php
   - library/app/edi.php
+  - library/app/netsuite.php
 related:
   - ../profile.md
   - hold-status-sync.md
@@ -131,12 +133,27 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
   `qtyOrder` is immutable** — there is no update path to a sent SO line; growth must be a
   new item row → new SO line.
 - **Stage 4:** reconciles the NetSuite **PO** (`netSuiteInternalPurchaseOrderId` — not the
-  SO id) and sends serial inventory assignments.
+  SO id) and sends serial inventory assignments. It is already multi-PO aware
+  (`listPurchaseOrdersCreatedFromSalesOrder`, groups items by PO, stamps each item's
+  `netSuiteInternalPurchaseOrderId`) **but only stamps items where the PO is NULL and never
+  re-stamps** — so an item stamped to PO-A but later *received* on PO-B is never corrected.
+  **TOGA does NOT create NetSuite POs anywhere in the DOE flow.** Stage 3 creates only the SO
+  (and, when needed, a special-order inventory Item); POs are generated inside NetSuite by
+  procurement/special-order. A single SO can therefore be fulfilled across **multiple POs**
+  (back-orders, multi-vendor, re-cut lines) — this is a legitimate NetSuite outcome, so the
+  durable fix lives downstream (resolve receipts SO-wide), not in preventing PO splits.
 - **Stage 5:** for units `WHERE togadeskRepairOrderId IS NULL`, reads serials from NetSuite
   item receipts (so TOGa Desk RO serials are **driven by NetSuite**, not the ASN unit),
   creates/reuses TOGa Desk manufacturers/models/assets/serial-numbers/MSO and creates **a
   new repair_orders row unconditionally per loop iteration** — one RO per Unit (a 50-cable
   line = 1 unit = 1 RO). Existing-serial lookup is scoped **per item row** (`$asnItemId`).
+  Item receipts are now resolved **Sales-Order-wide** via
+  `App_NetSuite::listItemReceiptsCreatedFromSalesOrder($soId)` (fans out across ALL POs from
+  `listPurchaseOrdersCreatedFromSalesOrder`, dedupes receipts by `internalId`), cached once
+  per ASN, with `getItemReceipt` cached per receipt id. The inner item query also requires
+  `netSuiteInternalSalesOrderId IS NOT NULL` so a null-SO first row cannot poison the per-ASN
+  receipt cache. Self-healing: units previously stuck under an unstamped PO clear on
+  subsequent 5-min cron runs.
 - **"#/N received" UI** (`togadesk/desk/template/pages/managedserviceorders/view.php`):
   denominator = `SUM(qtyOrder)` per part (committed + unsent); numerator = Units with
   `togadeskRepairOrderId IS NOT NULL`.
@@ -218,6 +235,36 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
 - **Stage 6 is not currently running** (`4_` paused with `active: 0`, `5_` unscheduled).
 - TRUE-77354: Stage 5 lookups changed `LIKE` → `=` to stop `_`/`%` wildcard matches in
   serials.
+- **Multi-PO-per-SO silently drops install tickets (FIXED 2026-07-09).** Stage 5 used to
+  fetch item receipts only for the single stamped `netSuiteInternalPurchaseOrderId`. When a
+  NetSuite SO is fulfilled across more than one PO, units received under a PO *other* than the
+  stamped one never got a TogaDesk repair order, and the every-5-min cron silently re-queried
+  the wrong PO forever. No error was raised — the symptom was serials never syncing. Fixed by
+  resolving receipts SO-wide (see Stage 5). Before, no `App_NetSuite` method listed receipts
+  by SO — only by PO (`listItemReceiptsCreateFromPurchaseOrder`) or location
+  (`listAllItemReceiptsForLocation`); the new `listItemReceiptsCreatedFromSalesOrder`
+  (`library/app/netsuite.php`, after `listItemReceiptsCreateFromPurchaseOrder`) fills that gap.
+  Concrete case: customer PO `S202643596` (ASN 26339, SO internalId 6971858) split across PO
+  164785 (internalId 6971859 → `38S0500` synced, 15 ROs) and PO 165751 (`50M7280` + `A3L980`
+  NOT synced). PRs: library#831 (merge first) then worker#1670.
+
+## Debugging & DB topology (DOE 1.0 sync)
+
+Reference for future DOE investigations — the 1.0 worker cannot run on a dev/Windows box;
+use the toga DB MCP + `Logs.API` instead of running prod code locally.
+
+- **`db_core` alias → legacy (V1) environment, schema `Core`** — holds the FLAT tables
+  `AdvanceShippingNotices` / `AdvanceShippingNoticeItems` / `AdvanceShippingNoticeUnits`
+  (columns incl. `togadeskRepairOrderId`, `serialNumber`, `netSuiteInternalSalesOrderId`,
+  `netSuiteInternalPurchaseOrderId`, `customerPurchaseOrder`). The 1.0 cron reads **legacy/Core**.
+- **Do NOT confuse with prod (V2) `Client_Nycdoe`** — a DIFFERENT, normalized schema
+  (`AdvanceShippingNoticeItemUnits` with a `unitId` FK). The 1.0 cron does not read V2.
+- **NetSuite SOAP request/response payloads** are logged in legacy `Logs.API` — filter
+  `sourceJob LIKE '%3_create_installation_ticket%'`; `requestPayload` contains the PO
+  internalId. (The multi-PO case above was verified this way: the receipt search for PO
+  6971859 returned `totalRecords=1`, only `38S0500`.)
+- **`Bridge_NetSuite`** (legacy) has `SalesOrders` / `SalesOrderItems` / `SerialNumbers` but
+  **no `PurchaseOrders` table** — POs are pulled live from the NetSuite API.
 
 ## Operating rules when changing this integration
 
@@ -231,6 +278,14 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
    of the consumer query; `php -l` every touched file.
 
 ## Change history
+- 2026-07-09 — Fixed silent install-ticket drop when a NetSuite SO is fulfilled across
+  multiple POs: Stage 5 now resolves item receipts Sales-Order-wide via new helper
+  `App_NetSuite::listItemReceiptsCreatedFromSalesOrder` (fans across all POs from the SO,
+  dedupes by internalId, cached per ASN), and its item query requires
+  `netSuiteInternalSalesOrderId IS NOT NULL`. Root cause: TOGA doesn't create DOE POs, so
+  multi-PO-per-SO is legitimate and units received on an unstamped PO were never ticketed.
+  Added multi-PO notes to Stage 4/5, a gotcha, and a DB-topology/debugging section.
+  PRs library#831 + worker#1670. (sking)
 - 2026-06-29 — Outbound status sync now keeps DOE holds authoritative (TRUE-79922). Hold
   detection moved to the SNOW native `state` field (not `u_status_task`); Assigned-force
   blocks guarded against local `HOLD_*` to stop the `state:3`↔`state:2` self-clobber; RITM

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.298",
+  "version": "1.0.299",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",