toga-ai 1.0.487 → 1.0.488
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: session
|
|
3
|
+
slug: true-80494-fulfill-ship-hotfix
|
|
4
|
+
title: TRUE-80494 Fulfill & Ship submit-blocker hotfix + Reference 1/2 carrier pass-through + beta metadata repairs
|
|
5
|
+
author: mhammontree
|
|
6
|
+
repos: [toga2-supply, _underscore, dbchanges2, api2]
|
|
7
|
+
framework: "2.0"
|
|
8
|
+
client: growrk
|
|
9
|
+
status: active
|
|
10
|
+
created: 2026-07-31
|
|
11
|
+
updated: 2026-07-31
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Session: true-80494-fulfill-ship-hotfix
|
|
15
|
+
**Date:** 2026-07-31
|
|
16
|
+
**Project/Repo:** toga2-supply (2.0) + _underscore / dbchanges2 / api2
|
|
17
|
+
**Task:** Root-cause why Fulfill & Ship stopped working in production for GroWrk after the TRUE-79191 deploy (2026-07-29), ship the TRUE-80494 hotfix, wire the Reference 1/2 fields through to the carrier so they print on shipping labels, and repair the beta/dev-sandbox metadata gaps blocking an end-to-end test.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## What WORKED
|
|
22
|
+
|
|
23
|
+
- **ROOT CAUSE of the prod outage — proven, not inferred.** Clicking Fulfill & Ship fired **no network request at all** (empty Network tab). Cause: `DUMMYUPDATESHIPMENTFIELDS.json:189-201` has a **display-only** section header (id 31, "Address") with `valueKey: ""` + `isRequired: true`. `validateFormOnSubmit.ts:37-44` does `getValues(field.valueKey)`; react-hook-form's `get` short-circuits on a falsy path so `getValues("")` is **always** `undefined` → `hasErrors = true` on **every** submit. Field 31 is **pre-existing** (confirmed via `git show b6cb3b426^`) and was harmless because the caller filtered blank keys. CodeRabbit batch 2 (`ba611989a`) broke it:
|
|
24
|
+
```diff
|
|
25
|
+
- let hasErrors = actualErrors.length > 0; // "" filtered out → harmless
|
|
26
|
+
+ let hasErrors = validationHasErrors || actualErrors.length > 0; // raw boolean → always true
|
|
27
|
+
```
|
|
28
|
+
The early `return` is silent: the error is keyed on `""` and that field renders through `BaseInput`'s `case "none"` branch (a bare `<p>`, no error slot), so nothing displays. **Blast radius: all clients, and all three actions** (Fulfill & Ship, Save, Save & Create New Shipment) — `onFormSubmit` gates all of them. Why local testing passed on 07-27: tracking number 9676 was saved **before** `ba611989a` existed.
|
|
29
|
+
- **The fix works — confirmed by the developer in prod-branch local.** Reverted only the caller in `EditShipmentForm.tsx:592` back to `actualErrors.length > 0` and dropped the now-unused `const validationHasErrors =`. Buttons work again and validation correctly blocks on an empty weight field. `npx tsc --noEmit` clean.
|
|
30
|
+
- **`dbchanges2` RecordFields id corrections — committed `5447f68`.** `2434 → 2480` (returnAddressId) and `2435 → 2481` (signatureType), matching what production actually holds.
|
|
31
|
+
- **`api2` `label_format = "PNG"` added to `Config/production.ini` — committed `851c227`.** Without it prod UPS defaults to ZPL while the return-label path expects a raster PNG for FPDF. `beta.ini` already had it, which is exactly why beta worked and prod didn't.
|
|
32
|
+
- **Reference 1/2 → carrier pass-through implemented** (uncommitted). Verified the transport mechanism first: these are **RecordScripts** (`Core.RecordScripts`), dispatched at `api2/Component/Api/V2/V2.php:4202` via `parse_str($_SERVER['QUERY_STRING'], $args)` then `$model::$method(...$args)` — PHP **named-argument unpacking**, so query-string keys bind to parameter names. `Core.RecordScripts` stores only `(recordId, method, route, phpMethod)` — no parameter signature — so **no migration is needed** to add params.
|
|
33
|
+
- **UPS label fix identified and implemented.** `Ups.php` was putting the reference into `Request.TransactionReference.CustomerContext`, which is UPS's request/response **correlation echo** — it never prints on a label. Replaced with real **package-level** `ReferenceNumber` entries via a new `buildPackageReferenceNumbers()` helper, wired into **both** payload builders (OAuth + legacy), following the existing `DCISType` conditional pattern. FedEx was already correct (`customerReferences`), just needed a second entry.
|
|
34
|
+
- **Carrier codes verified against docs** (web lookup): UPS `PO` = Purchase Order Number, `TN` = Transaction Reference Number, plus AJ/AT/BM/9V/ON/DP/3Q/IK/MK/MJ/PM/PC/RQ/RZ/SA/SE/ST/EI/TJ/SY. **UPS max 2 reference numbers, 35 chars each.** UPS prints the code's *meaning* next to the value. FedEx `customerReferenceType` accepts CUSTOMER_REFERENCE / P_O_NUMBER / INVOICE_NUMBER / DEPARTMENT_NUMBER / BILL_OF_LADING / RMA_ASSOCIATION / STORE_NUMBER / ELECTRONIC_PRODUCT_CODE / SHIPMENT_INTEGRITY / INTRACOUNTRY_REGULATORY_REFERENCE, **max 3 per package**, and rejects two entries of the same type.
|
|
35
|
+
- **All `php -l` clean; `tsc --noEmit` clean; JSON valid.**
|
|
36
|
+
- **BETA (= dev-sandbox cluster) METADATA REPAIRS — all applied and verified this session:**
|
|
37
|
+
1. **Empty unit dropdowns fixed.** `Client_Growrk` (dev-sandbox) had `lengthMeasureId` (2476) and `weightMeasureId` (2477) granted to **role 3 only**, and `measureType` (2478) with **zero** grant rows. Ungranted = the V2 engine omits the field from `GET /v2/measures` (200, no error), so the frontend's `measureType === "LENGTH"` split returned empty arrays. Final verified state: 2476 → roles 1,3; 2477 → roles 1,3; 2478 → role 1. Dropdowns now show `in`/`lb`.
|
|
38
|
+
2. **Save fixed (`EV-10`, "Column 'itemFulfillmentStageId' cannot be null").** `_Model_Client_ItemFulfillment::prePost()` defaults the stage to *shipped*, but it is **not called directly** — the V2 engine dispatches it from an `ApiPayloadInterceptors` registration, deriving the method as `strtolower('PRE') . ucfirst(strtolower('POST'))` → `prePost`. dev-sandbox `Core` was missing the `PRE`/`POST` row for recordId 28. Applied `Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql`; verified present and active. **Full-table drift check: that was the ONLY interceptor missing** — the other 8 match prod exactly. Stages themselves were already seeded (picked/packed/shipped).
|
|
39
|
+
3. **Tracking-number save fixed (`EV-8`, field `signatureType` does not exist).** dev-sandbox had neither the Core RecordField nor the column. Registered the field **omitting `id`** so auto_increment assigned it → landed at **2764**; added the `VARCHAR(255) utf8mb4` column `AFTER requiresSignature`; granted by mirroring `containsBattery` (field **962**). Verified: 2764 → roles 1 and 3.
|
|
40
|
+
- **Identified that "beta" reads dev-sandbox.** `toga2-supply/.env` → `VITE_API=https://api.beta.togahub.com/v2`; `api2/Config/beta.ini` `[database] hostname = dev.sandbox.database.togahub.com`. `Core` and `Client_Growrk` are on the **same cluster** in dev-sandbox, so `Core.`-qualified references in `Client/` migrations resolve there (in prod they are split across `prod-core`/`prod-client`).
|
|
41
|
+
|
|
42
|
+
## What did NOT work — DO NOT RETRY THESE
|
|
43
|
+
|
|
44
|
+
- **The ACL/missing-migration theory for the PROD outage — FALSIFIED.** Every UoM grant, column, and seed row is present in prod `Client_Growrk` (2476/2477/2478 all role 1, `Measures.measureType` + `conversionFactorToBase`, Inch/Pound seeded, `TrackingNumbers` FK columns), and bridge records 317-322 each have their `AclLogicGroups` + `AclLogicGroupExpressions`. Do not re-investigate prod ACL for this bug.
|
|
45
|
+
- **Assuming the frontend/backend wasn't deployed — WRONG.** All four CodeRabbit commits (`e91f7029d`, `d1eba64af`, `ba611989a`, `e0942cb4f`) are on `toga2-supply` `_production` via PR #585, and `77fae34c` is on `_underscore` `_production` via PR #691. **The deployed code was precisely the problem.**
|
|
46
|
+
- **Shipping `dbchanges2` `3bc5e5b` as written — WRONG.** It asserts `signatureType = 2482`, but prod 2482 is already `entitlements.serviceAddressId` (TRUE-79533). Prod actually holds returnAddressId=2480 and signatureType=**2481**. Corrected to 2481 in `5447f68`.
|
|
47
|
+
- **Crediting `_underscore/Route.php` with the query-param → argument binding — WRONG.** `Route.php:46` builds `$routeVars` from `explode('/', urldecode($route))` — **path segments, not the query string**. The real dispatcher is the RecordScripts path in `api2/Component/Api/V2/V2.php:4202`.
|
|
48
|
+
- **Running `Client/2026-07-22c` in chunks / as a partial selection — SILENTLY HALF-APPLIES.** Its `@measuresSlugFieldId` / `@measureTypeFieldId` are `SET` *after* the first two INSERTs, so a chunked execution skips the measureType block, and `WHERE sibling.recordFieldId = NULL` matches nothing → **0 rows, no error**. This has now cost two debugging rounds (prod originally, dev-sandbox today). Fix by running the whole file in one batch, or use the inlined-subselect form.
|
|
49
|
+
- **Running the shipped `Core/2026-07-10a` / `Core/2026-07-16a` on dev-sandbox — WILL FAIL.** They hardcode ids 2480/2481, which in dev-sandbox belong to `vocabularies.id` / `vocabularies.uuid` (dev-sandbox `MAX(RecordFields.id)` was 2763; `isFulfillable` is 2615 there vs 2434 in prod). Ids genuinely diverge per environment. Omit `id` and let auto_increment assign instead.
|
|
50
|
+
- **Testing `_underscore` changes from local against beta — IMPOSSIBLE as configured.** The local Vite server supplies only the frontend; every API call goes to the **deployed** beta api2 + `_underscore`. Local `_underscore` edits are not in the request path. The developer pushed TRUE-80494 `_underscore` to beta to work around this.
|
|
51
|
+
- **Mirroring `needsReturnLabel` for grants** — its grants don't exist in every client (Client_True had none) → ungranted fields → EV-9. Mirror `shippingMethodId` (338) / `slug` (723) / `containsBattery` (962) / `shipToAddressId` (991) instead.
|
|
52
|
+
- **Re-running `Client/2026-07-22b`** — one-time backfill; a re-run coerces later NULL rows to Inch/Pound.
|
|
53
|
+
- **Initially mapping Reference 1 = PO / Reference 2 = SO — REVERSED.** The field-config placeholders are Reference 1 → `"e.g. NetSuite Sales Order #"` and Reference 2 → `"e.g. NetSuite Purchase Order #"`. Code now follows the UI.
|
|
54
|
+
- **`Measures.customerPurchaseOrder` as a PO source** — in GroWrk that column holds **people's names** ("Butch Dority", "Robin Rigg") on old rows only (id ≤ 7524) and is NULL on all recent orders. It is not a PO field. (It was the hardcoded source in `ItemFulfillment.php` for the carrier reference — now replaced.)
|
|
55
|
+
- **A `toga_query` containing the word "grant" in a string literal** is rejected by the MCP tool's keyword guard ("Forbidden keyword 'GRANT'"). Rename the label.
|
|
56
|
+
|
|
57
|
+
## Not tried yet (candidates for next session)
|
|
58
|
+
|
|
59
|
+
- **THE ACTUAL END-TO-END BETA TEST — interrupted mid-run.** The developer had a disposable SO ready and was retrying the tracking-number save right after the `signatureType` repair landed. Not yet done: fulfill, inspect the label, confirm NetSuite.
|
|
60
|
+
- **`returnAddressId` Core registration + grant on dev-sandbox.** SQL fully prepared and dependency-checked (mirror `shipToAddressId` field **991**, `childPolicy = 'CREATE'`, `type = NULL`, uuid `c3a1f2d4-5e6b-4c7a-9d8e-0f1a2b3c4d5e`, omit `id` → expect 2765). Only needed if testing return labels. The **column already exists** in dev-sandbox; only the Core row + grant are missing.
|
|
61
|
+
- **Hardening `Client/2026-07-22c`** (and `2026-07-16b`) to inline subselects instead of session variables so a partial execution fails loudly instead of silently.
|
|
62
|
+
- **Deciding whether the references belong on the RETURN label.** `ItemFulfillment.php:1468` (`generateReturnLabel`) still uses `$salesOrder->customerPurchaseOrder`. Deliberately left unchanged — it's the return leg to the warehouse, a product decision, not mechanical.
|
|
63
|
+
- **Confirming the Reference 1/2 semantic order with Eric/Skyler.** If Eric actually types the PO into Reference 1, the labels print the wrong descriptors — a two-line constant swap in `Ups.php` and `Fedex.php`.
|
|
64
|
+
- **Committing `toga2-supply` + `_underscore`** — both working trees are dirty on TRUE-80494.
|
|
65
|
+
- **Latent second silent-abort path:** `checkDimensions.ts:6` dereferences `formValues.dimensions.length` unguarded, and `handleFulfillAndShip` (`EditShipmentForm.tsx:770-772`) calls `onFormSubmit` without `await`/`.catch()` — a `TypeError` becomes an unhandled rejection with the same "nothing happens" symptom. Deserves its own ticket.
|
|
66
|
+
- **Dynamic weight symbol** on Pending Shipments cards is still a static `"lbs."`.
|
|
67
|
+
|
|
68
|
+
## Current file state
|
|
69
|
+
|
|
70
|
+
| File | Status | Notes |
|
|
71
|
+
|------|--------|-------|
|
|
72
|
+
| `toga2-supply` `src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx` | modified, **uncommitted** | Submit-guard revert (the outage fix) + `reference1`/`reference2` in `defaultValues` + passed into `fulfillShipment()` |
|
|
73
|
+
| `toga2-supply` `src/pages/EditShipment/api/UpdateShipmentApi.ts` | modified, **uncommitted** | `fulfillShipment()` takes both references, URL-encodes them onto the query string |
|
|
74
|
+
| `toga2-supply` `src/pages/EditShipment/types.ts` | modified, **uncommitted** | `reference1?`/`reference2?` on `ShipmentData` |
|
|
75
|
+
| `toga2-supply` `.../FIELDS/DUMMYUPDATESHIPMENTFIELDS.json` | modified, **uncommitted** | `"characterLimit": 35` on both reference fields (UPS cap) |
|
|
76
|
+
| `_underscore` `Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php` | modified, **uncommitted** | Added `$referenceString2` |
|
|
77
|
+
| `_underscore` `Component/Library/Carriers/Ups/Ups.php` | modified, **uncommitted** | New `buildPackageReferenceNumbers()`; package-level `ReferenceNumber` in **both** payload builders; code constants TN/PO |
|
|
78
|
+
| `_underscore` `Component/Library/Carriers/Fedex/Fedex.php` | modified, **uncommitted** | Two `customerReferences` entries; PRIMARY=CUSTOMER_REFERENCE, SECONDARY=P_O_NUMBER; `MAX_CUSTOMER_REFERENCES = 3` |
|
|
79
|
+
| `_underscore` `Model/Client/ItemFulfillment.php` | modified, **uncommitted** | Optional `$reference1`/`$reference2` on `fedexShipmentApi` + `upsShipmentApi`; the **two outbound** sites (763-764, 1251-1252) now use them. Return-label site (1468) intentionally untouched |
|
|
80
|
+
| `dbchanges2` `Core/2026-07-10a - ItemFulfillmentReturnAddressIdRecordField.sql` | **committed `5447f68`** | id 2434 → 2480 |
|
|
81
|
+
| `dbchanges2` `Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql` | **committed `5447f68`** | id 2435 → 2481 (NOT 2482 — that's `entitlements.serviceAddressId`) |
|
|
82
|
+
| `api2` `Config/production.ini` | **committed `851c227`** | `label_format = "PNG"` under `[ups]` |
|
|
83
|
+
| dev-sandbox `Core` | **DB changed** | `ApiPayloadInterceptors` PRE/POST for recordId 28; `RecordFields` signatureType @ **2764** |
|
|
84
|
+
| dev-sandbox `Client_Growrk` | **DB changed** | measure grants completed (2476/2477 role 1, 2478 role 1); `TrackingNumbers.signatureType` column; signatureType grants (roles 1,3) |
|
|
85
|
+
| `_underscore` beta deploy | pushed by developer | TRUE-80494 pushed to beta so the carrier changes are in the request path |
|
|
86
|
+
|
|
87
|
+
## Decisions made
|
|
88
|
+
|
|
89
|
+
- **Revert only the caller, not the validation helpers.** `validateFormOnSubmit` and `checkDimensions` keep returning booleans, because reverting them would destroy CodeRabbit **batch 3** (`e0942cb4f`), a genuinely correct `clearErrors` fix. Rejected: full revert of `ba611989a`.
|
|
90
|
+
- **Chose the revert over hardening the validator.** Developer's explicit call. Noted risk: it restores the first-submit-slips-through behaviour CodeRabbit flagged, and CodeRabbit will likely re-flag it. The alternative (skip fields with `!field.valueKey || inputType === "none"` inside the validator, keeping both fixes) is written into the plan file but **not applied**.
|
|
91
|
+
- **No `dbchanges2` work for the reference feature.** Skyler confirmed the values are user-entered, not stored and not prefilled from NetSuite — so no columns, no `Core.RecordFields`, no `AclFieldPermissions`. Rejected: the earlier full-stack persist-and-recall design.
|
|
92
|
+
- **UPS references at PACKAGE level, not shipment level.** UPS rejects `Shipment.ReferenceNumber` on US/PR→US/PR domestic shipments, which is most GroWrk volume.
|
|
93
|
+
- **Reference 1 = sales order → UPS `TN` / FedEx `CUSTOMER_REFERENCE`; Reference 2 = purchase order → UPS `PO` / FedEx `P_O_NUMBER`.** Driven by the form placeholders (the UI is what Eric follows), and kept consistent across carriers so a label reads the same either way. `TN` chosen over `ON` (Dealer Order Number) because UPS prints the code's meaning and `ON` would be misleading — UPS has no sales-order code.
|
|
94
|
+
- **Enforce the 35-char UPS cap on the form** via the existing `characterLimit` mechanism (visible RHF message) rather than truncating server-side. Silent truncation would print wrong data on a label; a visible form error is recoverable.
|
|
95
|
+
- **On dev-sandbox, omit `id` on `RecordFields` inserts** and let auto_increment assign, instead of adapting the hardcoded prod ids. Removes the whole class of collision.
|
|
96
|
+
- **Reuse prod uuids for the dev-sandbox metadata rows** so environments stay comparable (verified free before inserting).
|
|
97
|
+
- **Left `generateReturnLabel` unchanged** — return-leg references are a product decision, and the plan listed line 1468 before we knew it was the return path.
|
|
98
|
+
|
|
99
|
+
## Blockers
|
|
100
|
+
|
|
101
|
+
None technical. The developer was pulled to a more urgent task mid-test; the beta end-to-end run is incomplete. All known metadata gaps blocking the *save* path are fixed; `returnAddressId` remains unregistered on dev-sandbox and will surface as `EV-8` **only** if the return-label flow is exercised.
|
|
102
|
+
|
|
103
|
+
## Exact next step
|
|
104
|
+
|
|
105
|
+
> On beta (`growrk.togasupply:5173/edit-shipment?internalId=7221433`, or the disposable SO), retry the tracking-number save — it should now succeed with `signatureType` registered at 2764. Then fill both Reference fields, weight, and all three dimensions, click Fulfill & Ship, and **inspect the returned label image** for both reference values and which descriptor sits next to which ("Purchase Order" must be beside the Reference 2 value). A successful API response proves nothing here — UPS previously accepted the reference into `CustomerContext` and printed nothing. Be aware `beta.ini` and `production.ini` point at the **same NetSuite account (1095849)**, so the fulfillment writes to production NetSuite.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
_Saved by /session-save on 2026-07-31_
|
package/package.json
CHANGED