toga-ai 1.0.112 → 1.0.113

package/knowledge/2.0/apps/worker2/INDEX.md

@@ -8,4 +8,5 @@
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Notification/Email.php, dbchanges2/Core/2026-05-21 - Monitors.sql |
 | [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
+| [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | `_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for Teams meeting transcripts produced by a set of organizers, classifies ea | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini |

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -22,6 +22,7 @@ files:
   - test/@dave/clickup/probe_opportunity_fields.php
   - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
 related:
+  - ./netsuite-salesorder-open-orders-sync.md
   - ../architecture.md
 ---
 

package/knowledge/2.0/apps/worker2/features/netsuite-salesorder-open-orders-sync.md

@@ -0,0 +1,120 @@
+---
+title: NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-17
+owners: ["dfranks"]
+files:
+  - worker2/Worker/Netsuite/SalesOrder.php
+  - worker2/Worker/Netsuite.php
+  - test/@dave/probe_salesorder_rest_shape.php
+  - worker/crons/toga2/forecast2/import_open_orders.php
+  - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
+related:
+  - ./netsuite-opportunity-sync.md
+  - ../architecture.md
+---
+
+## Summary
+
+Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). A NetSuite
+`salesOrder` create/edit/delete arrives at `webhook.togahub.com/netsuite`, the
+`_Worker_NetSuite::Webhook` router dispatches `Netsuite/SalesOrder/{POST,PUT,DELETE}`, and the
+handler syncs the order's currently-**open** line items into `Forecast.OpenOrderItems`. It is the
+real-time equivalent of the batch cron `worker/crons/toga2/forecast2/import_open_orders.php` (whose
+per-record logic lives in `common_import_sales_from_netsuite.php`, OPEN ORDERS section). Mirrors the
+[opportunity sync](./netsuite-opportunity-sync.md) — same shape, different table and gating.
+
+`OpenOrderItems` holds the **unbilled remainder** of approved-but-not-fully-billed sales orders;
+realized revenue (invoices/cash sales/credit memos/cash refunds) lives in `Forecast.Sales` and is a
+separate build (see *Related work*).
+
+## Key files / entry points
+
+- `Worker/Netsuite/SalesOrder.php` — `_Worker_Netsuite_SalesOrder`. **One class, two directions:**
+  the new INBOUND import (`POST`/`PUT`/`DELETE`, REST → Forecast) was *merged into* the pre-existing
+  OUTBOUND push (`Create`/`Update`/`Sync`, Toga → NetSuite via SOAP). The action router forces the
+  import entry points to live here (`salesOrder` → `_Worker_Netsuite_SalesOrder`), so they coexist.
+- `Worker/Netsuite.php` — the shared router (unchanged; no per-recordType edits needed).
+- NetSuite access is **REST only**, via the `_underscore` client `_Component_Api_Netsuite`
+  (`RECORD_SALES_ORDER` + `?expandSubResources=true`) — never the SOAP `NetSuiteService`.
+
+## How it works
+
+1. `POST`/`PUT` → `importOpenOrder($internalId)`; `DELETE` → `removeAll($internalId)`.
+2. `importOpenOrder` GETs the sales order via REST, then gates on **open status** (`status->refName`
+   ∈ `OPEN_STATUSES`: `Pending Fulfillment`, `Partially Fulfilled`, `Pending Billing/Partially
+   Fulfilled`, `Pending Billing`). A non-open **or missing** status → `removeAll` (the order carries
+   no open rows).
+3. Per open line: skip lines with no NS item id, item-group items (`netsuiteTransactionType ==
+   'itemGroup'`), and excluded EWR items (`DO_NOT_IMPORT_OPEN_ORDER_ITEM_IDS`). Throw if the NS item
+   isn't in `Forecast.Items` (surfaces an item-sync gap rather than dropping revenue).
+4. Open economics: `qtyOpen = quantity − quantityBilled`; `revenue = qtyOpen × rate`;
+   `profit = revenue − qtyOpen × unitCost` where `unitCost = costEstimate / quantity`
+   (divide-by-zero-safe). A line with `revenue == 0 && profit == 0` is dropped.
+5. Lookups → local ids: `Customers`/`Employees` by `netsuiteInternalId` (miss → null);
+   `Classifications` create-on-miss, name = last ` : `-segment of `class->refName` (e.g.
+   "True Solutions : SaaS Reseller : CSP" → "CSP").
+6. `syncOpenLines` upserts each open line keyed on `(netsuiteSalesOrderInternalId, lineNumber)`, then
+   deletes any row NetSuite no longer returns as open (orphans + now-closed lines). Commits
+   `DB_FORECAST` (lazy-transaction discipline).
+
+## Data model
+
+`Forecast.OpenOrderItems` — flat, denormalized **leaf** table (no header table, no FK children).
+Unique key `(netsuiteSalesOrderInternalId, lineNumber)`. Columns written: `netsuiteSalesOrderInternalId`,
+`dateOrder` (tranDate +12h), `orderNumber` (tranId), `customerId`, `salesRepEmployeeId`,
+`classificationId`, `itemId` (nullable), `lineNumber`, `revenue`, `profit`. The `accountId` FK column
+exists but is **never populated** (the legacy writer never set it — parity).
+
+## Client variations
+
+None — uniform (platform-wide Forecast2 sync).
+
+## Gotchas / known issues
+
+- **REST shape ≠ SOAP shape.** The cron reads the SOAP-shim shape; this handler reads the REST record
+  (`status->refName`, line `quantityBilled`, `class->refName`, `entity->id`, `salesRep->id`,
+  `shippingCost`). Verified against live orders via `test/@dave/probe_salesorder_rest_shape.php`.
+- **Three deliberate departures from the legacy cron (all intentional):**
+  1. **No date-window gate.** The cron flips `isOrderOpen=false` for tranDate outside −365d/+90d
+     (`common_import_…:1753`) to bound its windowed scan. Irrelevant to a single-id webhook — dropped.
+     (Consequence: a future-dated open SO the cron excludes *would* sync via webhook.)
+  2. **No shipping line.** The cron appends a synthetic `SHIPPING` line for `OpenOrderItems` with a
+     **null** item id, which its own item-id guard then drops — so shipping has **never** persisted to
+     `OpenOrderItems` (confirmed: 0 line-0 rows in prod). We omit it, preserving that behavior. (NB:
+     the cron's *Sales* section is different — it uses real item id **13500**, so shipping *does*
+     persist in `Forecast.Sales`.)
+  3. **Zero-open cascade bug fixed.** The cron's `$isOrderOpen` is order-scoped and never reset
+     per-line, so the first zero-open line (`common_import_…:1848`) poisons every later line on the
+     order — under-reporting open revenue on partially-billed multi-line orders, order-dependent. The
+     webhook skips only the zero line and keeps the order's other open lines (correct per-line
+     semantic). `trueup_open_orders.php` has been masking this in prod data.
+- **No `initialize()`.** It was removed: it only constructed the SOAP `NetSuiteService` (which *throws*
+  without `NS_HOST`/`NS_ENDPOINT` and builds a `SoapClient`), and the framework runs `initialize()`
+  before *every* action — keeping it would couple the REST import to SOAP config. The push methods
+  (`Create`/`Update`/`Sync`) self-construct `NetSuiteService`, so push is unaffected and the Forecast
+  DB is registered globally in `_.php`.
+
+## Related work
+
+`Forecast.Sales` (realized revenue) is fed by four other NS record types — `invoice`, `cashSale`,
+`creditMemo`, `cashRefund` — each routing to its own worker (`_Worker_Netsuite_Invoice`, etc.) over a
+planned shared `_Component_Forecast_SaleImport` engine (apply `$factor = −1` for credit memos / cash
+refunds). The low-level Forecast SQL/lookup helpers (`sqlLiteral`, `buildInsert`, `buildAssignments`,
+`lookupId`, `toSqlDate`, `fetchRecord`) are currently duplicated in `Opportunity.php` + `SalesOrder.php`
+and are a candidate to extract into a shared `_Component_Forecast_Db` before the Sales build.
+
+## Change history
+
+- 2026-06-17 — Initial open-orders importer merged into `_Worker_Netsuite_SalesOrder` (TRUE-79142):
+  REST-only, no date-window gate, no shipping line, cascade bug fixed. (dfranks)
+
+## Related docs
+
+- [NetSuite → TOGA Opportunity Sync](./netsuite-opportunity-sync.md) — the sibling pattern this mirrors.
+- [Worker (worker2) Architecture](../architecture.md)

package/knowledge/INDEX.md

@@ -15,7 +15,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 7 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 7 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 8 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 3 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 2 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/package.json

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