toga-ai 1.0.154 → 1.0.155

package/knowledge/clients/compass-usa/INDEX.md

@@ -5,5 +5,6 @@
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/PurchaseOrder.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql, dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16b - CleanupSA132743CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
+| [Compass MITS PO Transmission to Vendors](features/mits-po-transmission-to-vendors.md) | 2.0 | The 1.0 worker cron `2_transmit_mits_purchase_orders_to_vendors.php` transmits Compass PurchaseOrders to their vendors (Office Depot, Strategic Systems, Compass | worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, library/app/client/compass.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [Compass Order Lifecycle & Data-Integrity Invariants](workflows/order-lifecycle-and-data-integrity.md) | 2.0 | End-to-end map of how a Compass order flows through the `Client_Compass` (2.0) database and the **expected raw-data shape** at each link/ASN/IF level. |  |

package/knowledge/clients/compass-usa/features/mits-po-to-so-item-linking.md

@@ -13,6 +13,7 @@ files:
   - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
 related:
   - asn-to-item-fulfillment.md
+  - mits-po-transmission-to-vendors.md
 ---
 
 ## Summary

package/knowledge/clients/compass-usa/features/mits-po-transmission-to-vendors.md

@@ -0,0 +1,89 @@
+---
+title: Compass MITS PO Transmission to Vendors
+framework: "2.0"
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-06-22
+owners: ["rgirish"]
+files:
+  - worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php
+  - library/app/client/compass.php
+related:
+  - mits-po-to-so-item-linking.md
+  - order-lifecycle-and-data-integrity.md
+---
+
+## Summary
+The 1.0 worker cron `2_transmit_mits_purchase_orders_to_vendors.php` transmits Compass
+PurchaseOrders to their vendors (Office Depot, Strategic Systems, Compass, Presidio). Each
+vendor's `Integration` decides the channel: **CXML** (HTTP POST of a cXML OrderRequest) or
+**EMAIL** (a generated PDF emailed via `App_Email`). On success it writes "transmitted to
+Vendor" log rows and stamps `PurchaseOrders.dtSubmitted`.
+
+## Key files / entry points
+- `worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php` — the cron.
+- `library/app/client/compass.php` — `App_Client_Compass` constants:
+  `CUSTOMER_ID__COMPASS = 2`, `CUSTOMER_ID__OFFICE_DEPOT = 1`, `CUSTOMER_ID__AGILANT = 3`;
+  `VENDOR_ID__OFFICE_DEPOT = 1`, `VENDOR_ID__STRATEGIC_SYSTEMS = 25`, `VENDOR_ID__COMPASS = 26`,
+  `VENDOR_ID__PRESIDIO = 4`.
+
+## How it works
+1. **Outer query** selects POs to send: `customerId = CUSTOMER_ID__COMPASS (2)`,
+   `dtSubmitted IS NULL`, and `vendorId IN (1, 25, 26, 4)`. (So it only ever transmits
+   `customerId = 2` POs — `customerId = 1` ODP-as-customer POs are out of scope here.)
+2. **Per PO**, an inner query loads `PurchaseOrderItems` and groups them by integration
+   (`VendorItems.overridePoSubmissionIntegrationId` else the vendor's
+   `defaultPoSubmissionIntegrationId`).
+3. **Per integration group** (the `foreach`): build + send the cXML POST or the PDF email,
+   then INSERT two `Logs_Compass.Record` rows
+   (`"Purchase Order <number> transmitted to Vendor via <CXML|EMAIL>. Part numbers: ..."`,
+   recordId 17 = PO and 14 = SO).
+4. **After the integration loop**, `UPDATE PurchaseOrders SET dtSubmitted = NOW()` and `sleep(10)`.
+
+Routing note: Office Depot (vendor 1) `defaultPoSubmissionIntegrationId = 2`, which is an
+**EMAIL** integration ("Office Depot / Yes") — so ODP POs are emailed PDFs by default, not
+cXML, unless a `VendorItem` overrides it. There is also a CXML integration (id 1,
+"Office Depot / No") that is NOT the default.
+
+## Data model
+- `Client_Compass.PurchaseOrders.dtSubmitted` — set by step 4; the outer query's `IS NULL`
+  guard means a PO is only ever picked up once.
+- `Logs_Compass.Record` — `recordId` 17 (PurchaseOrder) / 14 (SalesOrder), `primaryKeyId` =
+  the PO/SO `id`. The "transmitted to Vendor" note is the success marker.
+
+## Client variations
+Compass Canada has a parallel `compasscanada/workflow/2_transmit_...` keyed on
+`CUSTOMER_ID__COMPASS_CANADA`.
+
+## Gotchas / known issues
+- **Item-less PO is silently marked submitted without being sent (the "logs show not sent
+  but dtSubmitted is set" symptom).** The `dtSubmitted = NOW()` UPDATE runs **unconditionally
+  after** the per-integration `foreach`, not inside it. If a PO has **zero
+  `PurchaseOrderItems`**, the inner items query returns nothing, `$itemsToSubmitByIntegration`
+  stays empty, the `foreach` body never runs — so **nothing is transmitted and no
+  "transmitted to Vendor" `Record` row is written** — yet `dtSubmitted` still gets stamped.
+  The PO then never re-qualifies for transmission (`dtSubmitted IS NULL` no longer matches).
+  **Diagnostic signature:** PO has `dtSubmitted` set but there is NO
+  `Logs_Compass.Record` "transmitted to Vendor" note (only "received from MITS") → the PO had
+  no line items. Confirmed on MR241298 / PO 50298575-1 (2026-06-21): `dtSubmitted` 23:20:04,
+  zero PurchaseOrderItems, no transmit log, no outbound Api log.
+- **Root cause is upstream at MITS, not this cron.** MITS created the order header-only:
+  `POST /v2/sales-orders` and `POST /v2/purchase-orders` were both received with
+  `"salesOrderItems":[]` / `"purchaseOrderItems":[]` (both 201). The V2 API accepts an order
+  with no items (no empty-items rejection), TOGA stored exactly that, and the cron then masked
+  it. To confirm what MITS actually sent, read the inbound `requestPayload` in `Logs_Compass.Api`
+  (`direction = 'IN'`, `route` `/v2/purchase-orders` or `/v2/sales-orders`, `apiId = 2`).
+- **No try/catch around the log INSERTs or the dtSubmitted UPDATE**, and they write to
+  different DBs (`Logs_Compass` vs `Client_Compass`) — a `Logs_Compass` failure can still leave
+  `dtSubmitted` stamped without a log (separate, previously-observed failure mode).
+
+## Change history
+- 2026-06-22 — Documented the cron and the unconditional-`dtSubmitted` gotcha: item-less POs
+  get marked submitted without transmitting or logging; diagnosed via MR241298 inbound MITS
+  payload showing empty item arrays. No code change made (diagnosis only). (rgirish)
+
+## Related docs
+- [Compass MITS PO → SO Item Linking](mits-po-to-so-item-linking.md)
+- [Compass Order Lifecycle & Data-Integrity Invariants](../workflows/order-lifecycle-and-data-integrity.md)

package/knowledge/clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md

@@ -13,6 +13,7 @@ related:
   - clients/compass-usa/features/asn-to-item-fulfillment.md
   - clients/compass-usa/features/mits-po-to-so-item-linking.md
   - clients/compass-usa/features/item-fulfillment-tracking-tableview.md
+  - clients/compass-usa/features/mits-po-transmission-to-vendors.md
 ---
 
 ## Summary

package/package.json

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