toga-ai 1.0.766 → 1.0.767

package/knowledge/1.0/apps/worker/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config, worker/crons/infrastructure/execute_dbchanges.php, worker/.ebextensions/030_dbchanges.config |
+| [Canon received-PO → NetSuite sales order sync](features/canon-received-po-netsuite-order-sync.md) | A 1.0 `worker` cron that reads Canon customer purchase orders out of the **Vision** databases and creates the matching **sales order in NetSuite**. | worker/crons/sync/sync_received_po.php, library/netsuitetoolkit/NSPHPClient.php |
 | [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php, worker/schedules/cron.worker.sync.json |
 | [Compass Manager Approval Reminder Emails (1.0 worker crons)](features/compass-manager-approval-reminder-emails.md) | Two 1.0 worker crons nag approvers about sales orders still waiting on a decision — one per Compass tenant. | worker/crons/toga2/compass/compass_email_reminders.php, worker/crons/toga2/compasscanada/compass_email_reminders.php, worker/schedules/cron.worker.sync.json, worker1.5/crons/toga2/compass/compass_email_reminders.php, worker1.5/schedules/cron.worker.json |
 | [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compass/send_delivered_email.php, worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php, worker/crons/toga2/compasscanada/send_delivered_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php, library/app/client/compasscanada.php |

package/knowledge/1.0/apps/worker/features/canon-received-po-netsuite-order-sync.md

@@ -0,0 +1,112 @@
+---
+title: Canon received-PO → NetSuite sales order sync
+framework: "1.0"
+repo: worker
+project: Worker
+client: canon
+type: feature
+status: active
+updated: 2026-09-03
+owners: ["mhammontree"]
+files:
+  - worker/crons/sync/sync_received_po.php
+  - library/netsuitetoolkit/NSPHPClient.php
+related:
+  - ./netsuite-togasupply-per-client-sync.md
+  - ../../../clients/canon/profile.md
+---
+
+## Summary
+A 1.0 `worker` cron that reads Canon customer purchase orders out of the **Vision** databases and
+creates the matching **sales order in NetSuite**. Before it can create the order it must turn every
+Vision part number into a real NetSuite item — bundles are exploded into components and prefixes are
+stripped. If any line cannot be matched, no order is created and operations gets a "not every part
+number could be located" email.
+
+**Critical rule:** the prefix strip list (`ASI-`, `/4YR`, `TOGA-`) appears **twice** in the file —
+line ~54 and line ~233. A new SKU prefix must be added to **both** or the sync silently searches
+NetSuite for the bundle name itself and fails.
+
+## Key files / entry points
+- `worker/crons/sync/sync_received_po.php` — the whole sync (selection, bundle explode, NetSuite
+  item lookup, order create, all three emails).
+- `library/netsuitetoolkit/NSPHPClient.php` line 200 — sets `SOAP_SINGLE_ELEMENT_ARRAYS`.
+
+## How it works
+1. **Selection.** Picks up rows from `Vision.CustomerPurchaseOrders` joined to
+   `CustomerPurchaseOrderItems` on `customerPurchaseOrderId`, where
+   `companyId = 13785 AND amiExportEnabled = 1 AND exportedToAmi = 0 AND IFNULL(netsuiteOrderNumber,'') LIKE ''`.
+2. **Bundle explode.** Custom-catalog bundles are expanded into their component part numbers
+   **before** any NetSuite search, using `Vision_Catalog.CustomProducts` joined through
+   `CustomCatalogCache` → `Products` for Canon companies **13785 / 18610**.
+3. **Prefix normalization.** Both the explode map (line ~54) and the per-line lookup (line ~233) run
+   `trim(str_replace(['ASI-', '/4YR', 'TOGA-'], '', $partNumber))`.
+4. **NetSuite item lookup** (~line 250) walks the search results and deliberately **skips
+   `ItemGroup` records**: `if (get_class($record) != 'ItemGroup') { $internalId = $record->internalId; break; }`.
+   If nothing is left, `$allItemsLocated` goes false and the failure email fires.
+5. **Quantity.** `billTo` selects the NetSuite customer and whether `$enforceQuantityOne` is set:
+   - `HPFS-LEASES` → 2839 — `enforceQuantityOne = true`
+   - `ACH-ASILEASE` → 28537 — `enforceQuantityOne = true`
+   - `ACH-HP-ACCESSOR` → 21908 if the order number starts with `9`, else 21055 — `false`
+   With `enforceQuantityOne = true` an exploded **bundle** line is written at quantity 1.
+6. **Price.** The exploded bundle's main line is priced from
+   `IFNULL(CustomProducts.listPrice, PriceProfilePartRules.rate)` — the Vision catalog price is
+   taken as-is; the sync does **not** compute cost + margin.
+7. **Email.** Three distinct bodies: SUCCESSFUL, a generic FAILED, and the "not every part number
+   could be located" FAILED that lists `$partNumbersCouldNotFind`. **Only the third names part
+   numbers** — that is the tell for a lookup miss vs. a NetSuite write failure. Recipients are
+   hardcoded near the top (`$emailOrdersTo` mfrye, cmullen; CC jblevins, sking).
+
+## Data model
+- `Vision.CustomerPurchaseOrders`, `Vision.CustomerPurchaseOrderItems` (schema `Vision`,
+  environment `legacy`).
+- `Vision_Catalog.CustomProducts`, `CustomCatalogCache`, `Products`, `PriceProfilePartRules`.
+- Canon's catalog is 21 parts: 19 plain, 1 `ASI-` prefixed, and exactly one `TOGA-` prefixed
+  (`TOGA-MGEE4LL/A`) — the only entry with both `assetTagging` and `biosTagging` set.
+
+## Client variations
+Canon-only cron (`companyId 13785`, catalog companies 13785 / 18610). No other client runs it.
+
+## Gotchas / known issues
+- **A missing prefix makes the bundle name look like a part number.** `TOGA-MGEE4LL/A` was searched
+  literally; in NetSuite that name is an **Item Group** (internal id 1609121) whose components are
+  `MGEE4LL/A`, `SVC-TS-BIOSTAG`, `SVC-TS-ASSETTAG`. Because the lookup skips `ItemGroup`, the search
+  "found" the item and still returned nothing usable. The real item is `MGEE4LL/A`
+  (Serialized Inventory Item, internal id 1607214). Add any new prefix to **both** `str_replace`
+  arrays.
+- **Quantity 12 on a lease PO means 12 monthly payments for ONE machine, not 12 machines.** Verified
+  against the manually keyed records for PO 9318575 (PO 169288 TD Synnex, SO 285071) — both show
+  `MGEE4LL/A` qty 1. Do **not** "fix" `$enforceQuantityOne` to pass the PO quantity through.
+  **Non-bundle** parts are not exploded and therefore DO keep the PO quantity (e.g. older
+  `ASI-MW1H3LL/A` orders imported at qty 12).
+- **Catalog price can be stale, and that is accepted.** `TOGA-MGEE4LL/A` `listPrice` is $5,118.45;
+  the manually keyed SO 285071 used $5,106.45 (TD Synnex cost $4,749.00 + 7% margin = $357.45 GP).
+  Decision 2026-09-03: ship as-is — the sync should not compute margin; a reviewer adjusts the
+  auto-created order.
+- **⚠ OPEN LATENT BUG (not fixed, needs its own ticket).** In the per-line NetSuite lookup, if
+  `$response->searchResult->status->isSuccess` is FALSE the code does **nothing** — the line is
+  silently skipped, `$allItemsLocated` stays TRUE, and the sales order is created in NetSuite
+  **missing that line**, with no email and no error. A NetSuite search outage or throttled call
+  produces a silently short order. This violates the fail-loud rule in `1.0/standards/backend-php.md`
+  via an implicit no-op rather than an explicit catch.
+- **A fixed PO does not re-run.** Rows are flagged `exportedToAmi = 1` even when the export failed,
+  so deploying a fix does **not** replay them. POs 9318538, 9318575 and 9318670 (all
+  `TOGA-MGEE4LL/A`, qty 12, `netsuiteOrderNumber` NULL) were already flagged and need manual entry
+  or a flag reset. 9318575 is in NetSuite as SO 285071, keyed manually.
+- **Ruled out — do not re-investigate.** (a) The single-result SOAP array trap does not apply: the
+  lookup is guarded by `is_array($response->searchResult->recordList->record)`, and
+  `library/netsuitetoolkit/NSPHPClient.php` line 200 sets `SOAP_SINGLE_ELEMENT_ARRAYS`, so a
+  one-record search is still an array. (b) Commit `a3e33776c` (TRUE-75559, 2026-03-17) did not
+  introduce the skip-ItemGroup behavior — it only deleted a commented-out block; the older
+  commented version actually *preferred* the ItemGroup, so the flip happened years earlier under a
+  different file path.
+
+## Change history
+- 2026-09-03 — Added `TOGA-` to the prefix strip list at both line 54 and line 233 so Canon's new
+  bundle SKU `TOGA-MGEE4LL/A` resolves to `MGEE4LL/A` instead of the NetSuite Item Group; documented
+  the qty-1 lease rule, the accept-catalog-price decision, and the silent `isSuccess=false` skip
+  (TRUE-80811, mhammontree).
+
+## Related docs
+- [NetSuite → TOGa Supply per-client sync](./netsuite-togasupply-per-client-sync.md)
+- [Canon profile](../../../clients/canon/profile.md)

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 24 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 32 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 33 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 13 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)

package/knowledge/clients/canon/profile.md

@@ -8,11 +8,12 @@ project: Worker
 client: canon
 type: profile
 status: active
-updated: 2026-08-29
-owners: ["jcardinal"]
+updated: 2026-09-03
+owners: ["jcardinal", "mhammontree"]
 files: []
 related:
   - ../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../1.0/apps/worker/features/canon-received-po-netsuite-order-sync.md
 ---
 
 ## Summary
@@ -32,3 +33,7 @@ full mechanics and the diagnosis playbook live in
 ## Integration touchpoints
 
 - **`worker` / `library` (1.0)** — the shared togasupply sync engine + `App_Api_Toga2` bridge.
+- **`worker` (1.0) — received-PO → NetSuite sales orders.** `crons/sync/sync_received_po.php` reads
+  Canon POs from the **Vision** databases (`companyId 13785`, catalog companies 13785 / 18610),
+  explodes custom-catalog bundles into components, and creates the NetSuite sales order. See
+  [Canon received-PO → NetSuite sales order sync](../../1.0/apps/worker/features/canon-received-po-netsuite-order-sync.md).

package/package.json

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