toga-ai 1.0.119 → 1.0.120

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -57,6 +57,9 @@ the window's upper bound after each successful section.
 
 ### Adding a new client (the full recipe)
 
+A wrapper + schedule alone is **not enough** — the client must also be provisioned in three
+places or the sync runs but imports nothing (or 403s). All five steps are required:
+
 1. **Wrapper** — copy `sync_togasupply_canon.php` to `sync_togasupply_<client>.php`; set
    `CLIENT_CONFIGURATION` (literal UUIDs, or `App_Api_Toga2::*` consts if defined). Keep the
    rest identical.
@@ -64,8 +67,35 @@ the window's upper bound after each successful section.
    `"cron": "toga2/netsuite/sync_togasupply_<client>.php"`). Deploys regenerate the crontab.
 3. **Seed Parameters** — add `dbchanges2/Client_<Id>/<date> - NetsuiteSyncParameters.sql`
    inserting the 12 keys. **Without this the sync 404s on the first `/parameters` GET and the
-   run aborts.** `Client_<Id>` directory selects the DB — no `USE` statement (dbchanges2 rule).
+   run aborts.** Seed start date = the canonical **`2026-03-04`** (from
+   `_modules/netsuite/2026-04-01 - Parameters.sql`) unless backfilling earlier history for that
+   client. `Client_<Id>` directory selects the DB — no `USE` statement (dbchanges2 rule).
    `lint`: `C:\xampp7\php\php.exe -l` (prod worker is PHP 7.2).
+4. **Client→NetSuite customer link** (`Core.Clients.netsuiteCustomerInternalId`) — **MUST be
+   set** to the client's NetSuite customer internal id. The lookup phase calls
+   `listChildCustomers((int)$client->netsuiteCustomerInternalId)`; if it's `NULL` the walk
+   seeds off `0`, the customer→client map is empty, and **no order ever matches → silent
+   zero-import** (the sync "runs" and even advances windows, but writes nothing). Find the id
+   with a SuiteQL `customer` lookup (`test/@dave/find_aig_netsuite_customer.php` is a template);
+   set it via a `dbchanges2/Core/` migration. Verify the client *has* supply transactions on
+   that customer before bothering (see the AIG gotcha).
+5. **Per-client custom fields on the synced records** — the shared engine hardcodes a fixed set
+   of `c_netsuite*` field names it reads/writes (see *Custom field contract* below). Each must
+   exist on the client's records as **column + `CustomRecordFields` row + `AclCustomFieldPermissions`
+   grant** (custom fields are per-client — see the 2.0 `_underscore` per-client-database doc). A
+   missing one → **403 EZ-2** ("not authorized to read the specified fields") aborting the run.
+   The most commonly-missing one is `c_netsuiteInternalCustomerId` on the **Customers** record
+   (`recordId 113`, `isIdentifier=1`).
+
+### Custom field contract (hardcoded in `common_sync_togasupply.php`)
+
+The engine requests these `c_` fields by literal name per route — every synced client must have
+them provisioned: `/customers`→`c_netsuiteInternalCustomerId`; `/countries`→`c_netsuiteCountry`;
+`/locations`→`c_netsuiteInternalCustomerId` + `c_netsuiteInternalLocationId` + the
+`c_dtNetsuiteLast*Integration` timestamps; `/subsidiaries`→`c_netsuiteInternalSubsidiaryId`;
+`/vendors`→`c_netsuiteInternalVendorId`; `/payment-terms`→`c_netsuiteInternalTermsId`;
+`/shipping-methods`→`c_netsuiteInternalShipMethodId`. The names are a **convention**, not
+discovered per-client.
 
 ## Data model
 
@@ -74,7 +104,8 @@ Per-client `Parameters` table (2.0 client DB, e.g. `Client_Canon.Parameters`; co
 `/parameters`:
 
 - `NETSUITE_LAST_SYNC_DATETIME_{SALES_ORDERS,PURCHASE_ORDERS,INVOICES,ITEM_RECEIPTS,ITEM_FULFILLMENTS,INVENTORY_ADJUSTMENTS}`
-  — seed `'2025-01-01 00:00:00'` (or chosen backfill start).
+  — seed `'2026-03-04 00:00:00'` (the canonical start; use an earlier date only to backfill a
+  client whose history predates it — e.g. AIG seeded `2023-01-01` to reach its 2023/2025 records).
 - `NETSUITE_EXECUTION_MODE_{...same six...}` — seed `'864000-IDLE'`.
 
 Parameters are stored **per client DB** but accessed **through the TOGa2 API**, not direct SQL.
@@ -102,13 +133,28 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   `Client_<Id>.Parameters`: a healthy client advances to ~now every 5 min. As of 2026-06-17,
   Quad was seeded but frozen at 2025-04/05 (not advancing) while the other 12 deployed clients
   were current.
+- **Silent zero-import = missing `netsuiteCustomerInternalId`.** If a client "runs" (sections
+  flip RUNNING→IDLE, windows advance) but imports nothing, check
+  `Core.Clients.netsuiteCustomerInternalId` — a NULL there empties the customer map so no order
+  matches. Distinct from the EZ-2 *abort* caused by a missing `c_netsuite*` field.
+- **"Listed ≠ functioning" — the AIG case (2026-06-17).** AIG was in the original combined
+  array but had **never** imported anything in prod (0 SalesOrders/POs/Invoices/Locations/Customers)
+  and *couldn't* have: its `netsuiteCustomerInternalId` was NULL and its Customers record lacked
+  `c_netsuiteInternalCustomerId`. After provisioning all three (custom field, Parameters, customer
+  link → NetSuite customer **34902**), it still imports ~nothing because AIG's entire NetSuite
+  supply footprint is **1 sales order (2025-09-11) + 15 opportunities** — it's an
+  opportunity/entitlement account, not a procurement/supply customer. Lesson: before onboarding a
+  client, confirm it actually transacts supply orders in NetSuite (SuiteQL the `customer`'s
+  transaction history) — being in the array doesn't mean it belongs on this engine.
 
 ## Change history
 
-- 2026-06-17 — Added AIG + Growrk thin wrappers (the two clients from the original array that
-  never got one), registered both in `cron.worker.sync.json`, and added their dbchanges2
-  Parameters seeds (`Client_Aig`, `Client_Growrk`). Verified the other 13 clients' Parameters
-  against prod. (dfranks)
+- 2026-06-17 — Documented the full onboarding prerequisites (client→NetSuite customer link +
+  per-client `c_netsuite*` custom fields) after AIG ran but imported nothing. Added AIG + Growrk
+  thin wrappers, schedule entries, and dbchanges2 Parameters seeds; built AIG's
+  `c_netsuiteInternalCustomerId` field migration + `Core.Clients` customer-link migration (id
+  34902). Confirmed AIG is not a real supply client; Growrk ships, AIG held. Canonical seed start
+  is `2026-03-04` (not `2025-01-01`). (dfranks)
 
 ## Related docs
 

package/package.json

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