toga-ai 1.0.76 → 1.0.77

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

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [TOGa Desk Architecture](architecture.md) | TOGa Desk is the staff-facing support desk **and field-service platform** (analysts work at `/desk/`). | desk/index.php, desk/includes/loader.php, desk/config.php, desk/includes/controllers/actions.php, desk/includes/controllers/data.php, desk/includes/controllers/modals.php, desk/includes/classes/class.app.php, desk/includes/classes/class.ticket.php, desk/api/index.php, desk/api/resources/tickets.php, crons/tickets.php |
 | [Email-to-Ticket Intake (crons/tickets.php)](features/email-to-ticket-intake.md) | TOGa Desk ingests support email into tickets through a cron-driven IMAP poller (`crons/tickets.php`) plus a postfix pipe variant (`crons/pipe.php`). | crons/tickets.php, crons/tickets_prod.php, crons/pipe.php, desk/includes/classes/class.ticket.php |
-| [Field-Service Dispatch (central / repair orders)](features/field-service-dispatch.md) | The **central** subsystem is TOGa Desk's field-service dispatch domain: repair-order lifecycle, technician scheduling, onsite vs depot service, parts, and shipm | desk/includes/controllers/actions/central/, desk/includes/classes/class.repair.php, desk/includes/classes/class.repairhistory.php, desk/_/browser/datatable/central.php, desk/template/pages/central.php, desk/template/pages/central/view.php |
+| [Field-Service Dispatch (central / repair orders)](features/field-service-dispatch.md) | The **central** subsystem is TOGa Desk's field-service dispatch domain: repair-order lifecycle, technician scheduling, onsite vs depot service, parts, and shipm | desk/includes/controllers/actions/central/, desk/includes/classes/class.repair.php, desk/includes/classes/class.repairhistory.php, desk/_/browser/datatable/central.php, desk/template/pages/central.php, desk/template/pages/central/view.php, desk/template/modals/central/addTracking.php, library/app/model/togadesk/repairordertracking.php, library/app/api/carrier/ups.php |
 | [REST API (RPC-over-POST) & API-Key Auth](features/rest-api.md) | TOGa Desk exposes a programmatic API at `desk/api/`. | desk/api/index.php, desk/api/resources/tickets.php, desk/api/resources/assets.php, desk/api/resources/authenticate.php, desk/includes/classes/class.apikey.php, desk/includes/functions.php |
 | [SMB Contract Editing & the clientMspId Corruption Trap](features/smb-contract-editing.md) | The SMB contracts page (`/desk/?route=toga/smbcontracts&togaClientId=<id>`) edits `TOGA_*.SMBContracts` rows via a modal. | desk/template/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/edit.php |
 | [Ticket Lifecycle (class.ticket.php)](features/ticket-lifecycle.md) | All TOGa Desk ticket creation and reply handling funnels through `Ticket` in `desk/includes/classes/class.ticket.php`. | desk/includes/classes/class.ticket.php, desk/includes/controllers/actions.php, desk/api/resources/tickets.php, crons/tickets.php, desk/includes/controllers/actions/tickets/merge.php |

package/knowledge/1.0/apps/togadesk/features/field-service-dispatch.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-06-15
-owners: ["jcardinal"]
+owners: ["jcardinal", "mhammontree"]
 files:
   - desk/includes/controllers/actions/central/
   - desk/includes/classes/class.repair.php
@@ -15,6 +15,9 @@ files:
   - desk/_/browser/datatable/central.php
   - desk/template/pages/central.php
   - desk/template/pages/central/view.php
+  - desk/template/modals/central/addTracking.php
+  - library/app/model/togadesk/repairordertracking.php
+  - library/app/api/carrier/ups.php
 related:
   - 1.0/apps/togadesk/architecture.md
   - 1.0/apps/togadesk/features/ticket-lifecycle.md
@@ -53,6 +56,25 @@ the originating page. Status changes are audited through `RepairHistory` (`repai
 onsite/install started → review → closed; depot repairs add parts/tracking steps. Bulk actions
 exist for closing installs and editing onsite tickets.
 
+## UPS shipment / carrier-account billing (Prepare Shipment flow)
+The "PREPARE SHIPMENT" button opens modal `desk/template/modals/central/addTracking.php`,
+whose carrier/account dropdown is built from the constant
+`App_Model_TogaDesk_RepairOrderTracking::CARRIER_ACCOUNTS`
+(`library/app/model/togadesk/repairordertracking.php`) — a display⇒value list of multiple
+carrier accounts (Agilant `8696XA`, ODP Veyer `H4Y167`, Compass `33951W`, Advance Auto
+`2V1Y10`, Vision Precision `87161X`, plus FedEx accounts). Submit calls
+`Repair::addTracking($_POST)` (~L600 in `class.repair.php`), which builds an
+`App_Api_Carrier_ShipmentRequest` and calls `App_Api_Carrier_UPS::submitShipmentRequest()`.
+
+**The displayed account and the billed account come from different places.** The dropdown is
+just `CARRIER_ACCOUNTS`; the account that actually ships/bills is the hardcoded
+`const SHIPPER_NUMBER` in `library/app/api/carrier/ups.php`, injected into the UPS payload as
+*both* `Shipment.Shipper.ShipperNumber` and `BillShipper.AccountNumber`. `SHIPPER_NUMBER` is
+shared **library core** consumed by every 1.0 app (togadesk, togaview, worker); a separate
+synced copy lives in `_underscore` for 2.0 apps, plus a hardcoded `<ShipAccount>` in
+`library/app/api/essls.php`. Full account-location map:
+`C:\WWW\shipping_carrier_ups_account_location.md`.
+
 ## Data model
 `repair_orders`, `repair_order_customers`, `repair_order_addresses`, `repair_order_technicians`,
 `repair_history` (in `db_togadesk`), joined to TOGA `ServiceRequests` for managed-service-order
@@ -70,7 +92,21 @@ always confirm the client arm before changing shared central logic.
   an order in an inconsistent state.
 - Cross-database context: some central data controllers switch the DB link to a client database
   (`App_Model_Client::changeDbLinkToClientDatabase()`).
+- **UPS carrier-account dropdown is NOT honored by the shipment API call.** In
+  `Repair::addTracking()` the selected `carrierAccount` is only saved onto the tracking record
+  (`$track->carrierAccount = $data['carrierAccount']`, ~L932/949/966); it is never passed into
+  the `ShipmentRequest`. `submitShipmentRequest()` therefore always bills the hardcoded
+  `SHIPPER_NUMBER` (Agilant), so picking ODP Veyer / Compass / etc. has no billing effect. True
+  third-party billing would require passing the chosen account into the request via a UPS
+  `BillThirdParty` / `BillReceiver` payment block instead of `BillShipper`.
+- The Agilant UPS account is **hardcoded in core, not config/DB** — changing it means editing
+  `SHIPPER_NUMBER` in both framework cores (`library` and `_underscore`), the ESSLS
+  `<ShipAccount>` XML, the `CARRIER_ACCOUNTS` Agilant entry, and test fallbacks. See the
+  account-location map noted under *UPS shipment / carrier-account billing*.
 
 ## Change history
+- 2026-06-15 — documented UPS Prepare Shipment flow: CARRIER_ACCOUNTS dropdown vs hardcoded
+  SHIPPER_NUMBER, and the gotcha that the dropdown selection is never forwarded to the UPS API
+  (always bills Agilant). Agilant account migrated 135FV5 → 8696XA. (mhammontree)
 - 2026-06-15 — documented from a source read of `controllers/actions/central/` and
   `class.repair.php` (jcardinal)

package/package.json

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