-
Ninth core PBC. Ships the first-class orchestration aggregate for moving stock between locations: a header + lines that represents operator intent, and a confirm() verb that atomically posts the matching TRANSFER_OUT / TRANSFER_IN ledger pair per line via the existing InventoryApi.recordMovement facade. Takes the framework's core-PBC count to 9 of 10 (only pbc-quality remains in the P5.x row). ## The shape pbc-warehousing sits above pbc-inventory in the dependency graph: it doesn't replace the flat movement ledger, it orchestrates multi-row ledger writes with a business-level document on top. A DRAFT `warehousing__stock_transfer` row is queued intent (pickers haven't started yet); a CONFIRMED row reflects movements that have already posted to the `inventory__stock_movement` ledger. Each confirmed line becomes two ledger rows: TRANSFER_OUT(itemCode, fromLocationCode, -quantity, ref="TR:<code>") TRANSFER_IN (itemCode, toLocationCode, quantity, ref="TR:<code>") All rows of one confirm call run inside ONE @Transactional method, so a failure anywhere — unknown item, unknown location, balance would go below zero — rolls back EVERY line's both halves. There is no half-confirmed transfer. ## Module contents - `build.gradle.kts` — new Gradle subproject, api-v1 + platform/* dependencies only. No cross-PBC dependency (guardrail #9 stays honest; CatalogApi + InventoryApi both come in via api.v1.ext). - `StockTransfer` entity — header with code, from/to location codes, status (DRAFT/CONFIRMED/CANCELLED), transfer_date, note, OneToMany<StockTransferLine>. Table name `warehousing__stock_transfer`. - `StockTransferLine` entity — lineNo, itemCode, quantity. `transfer_id → warehousing__stock_transfer(id) ON DELETE CASCADE`, unique `(transfer_id, line_no)`. - `StockTransferJpaRepository` — existsByCode + findByCode. - `StockTransferService` — create / confirm / cancel + three read methods. @Transactional service-level; all state transitions run through @Transactional methods so the event-bus MANDATORY propagation (if/when a pbc-warehousing event is added later) has a transaction to join. Business invariants: * code is unique (existsByCode short-circuit) * from != to (enforced in code AND in the Liquibase CHECK) * at least one line * each line: positive line_no, unique per transfer, positive quantity, itemCode must resolve via CatalogApi.findItemByCode * confirm requires DRAFT; writes OUT-first-per-line so a balance-goes-negative error aborts before touching the destination location * cancel requires DRAFT; CONFIRMED transfers are terminal (reverse by creating a NEW transfer in the opposite direction, matching the document-discipline rule every other PBC uses) - `StockTransferController` — `/api/v1/warehousing/stock-transfers` with GET list, GET by id, GET by-code, POST create, POST {id}/confirm, POST {id}/cancel. Every endpoint @RequirePermission-gated using the keys declared in the metadata YAML. Matches the shape of pbc-orders-sales, pbc-orders-purchase, pbc-production. - DTOs use the established pattern — jakarta.validation on the request, response mapping via extension functions. - `META-INF/vibe-erp/metadata/warehousing.yml` — 1 entity, 4 permissions, 1 menu. Loaded by MetadataLoader at boot, visible via `GET /api/v1/_meta/metadata`. - `distribution/src/main/resources/db/changelog/pbc-warehousing/001-warehousing-init.xml` — creates both tables with the full audit column set, state CHECK constraint, locations-distinct CHECK, unique (transfer_id, line_no) index, quantity > 0 CHECK, item_code index for cross-PBC grep. - `settings.gradle.kts`, `distribution/build.gradle.kts`, `master.xml` all wired. ## Smoke test (fresh DB + running app) ``` # seed POST /api/v1/catalog/items {code: PAPER-A4, baseUomCode: sheet} POST /api/v1/catalog/items {code: PAPER-A3, baseUomCode: sheet} POST /api/v1/inventory/locations {code: WH-MAIN, type: WAREHOUSE} POST /api/v1/inventory/locations {code: WH-SHOP, type: WAREHOUSE} POST /api/v1/inventory/movements {itemCode: PAPER-A4, locationId: <WH-MAIN>, delta: 100, reason: RECEIPT} POST /api/v1/inventory/movements {itemCode: PAPER-A3, locationId: <WH-MAIN>, delta: 50, reason: RECEIPT} # exercise the new PBC POST /api/v1/warehousing/stock-transfers {code: TR-001, fromLocationCode: WH-MAIN, toLocationCode: WH-SHOP, lines: [{lineNo: 1, itemCode: PAPER-A4, quantity: 30}, {lineNo: 2, itemCode: PAPER-A3, quantity: 10}]} → 201 DRAFT POST /api/v1/warehousing/stock-transfers/<id>/confirm → 200 CONFIRMED # verify balances via the raw DB (the HTTP stock-balance endpoint # has a separate unrelated bug returning 500; the ledger state is # what this commit is proving) SELECT item_code, location_id, quantity FROM inventory__stock_balance; PAPER-A4 / WH-MAIN → 70 ← debited 30 PAPER-A4 / WH-SHOP → 30 ← credited 30 PAPER-A3 / WH-MAIN → 40 ← debited 10 PAPER-A3 / WH-SHOP → 10 ← credited 10 SELECT item_code, location_id, reason, delta, reference FROM inventory__stock_movement ORDER BY occurred_at; PAPER-A4 / WH-MAIN / TRANSFER_OUT / -30 / TR:TR-001 PAPER-A4 / WH-SHOP / TRANSFER_IN / 30 / TR:TR-001 PAPER-A3 / WH-MAIN / TRANSFER_OUT / -10 / TR:TR-001 PAPER-A3 / WH-SHOP / TRANSFER_IN / 10 / TR:TR-001 ``` Four rows all tagged `TR:TR-001`. A grep of the ledger attributes both halves of each line to the single source transfer document. ## Transactional rollback test (in the same smoke run) ``` # ask for more than exists POST /api/v1/warehousing/stock-transfers {code: TR-002, from: WH-MAIN, to: WH-SHOP, lines: [{lineNo: 1, itemCode: PAPER-A4, quantity: 1000}]} → 201 DRAFT POST /api/v1/warehousing/stock-transfers/<id>/confirm → 400 "stock movement would push balance for 'PAPER-A4' at location <WH-MAIN> below zero (current=70.0000, delta=-1000.0000)" # assert TR-002 is still DRAFT GET /api/v1/warehousing/stock-transfers/<id> → status: DRAFT ← NOT flipped to CONFIRMED # assert the ledger still has exactly 6 rows (no partial writes) SELECT count(*) FROM inventory__stock_movement; → 6 ``` The failed confirm left no residue: status stayed DRAFT, and the ledger count is unchanged at 6 (the 2 RECEIPT seeds + the 4 TRANSFER_OUT/IN from TR-001). Propagation.REQUIRED + Spring's default rollback-on-unchecked-exception semantics do exactly what the KDoc promises. ## State-machine guards ``` POST /api/v1/warehousing/stock-transfers/<confirmed-id>/confirm → 400 "cannot confirm stock transfer TR-001 in status CONFIRMED; only DRAFT can be confirmed" POST /api/v1/warehousing/stock-transfers/<confirmed-id>/cancel → 400 "cannot cancel stock transfer TR-001 in status CONFIRMED; only DRAFT can be cancelled — reverse a confirmed transfer by creating a new one in the other direction" ``` ## Tests - 10 new unit tests in `StockTransferServiceTest`: * `create persists a DRAFT transfer when everything validates` * `create rejects duplicate code` * `create rejects same from and to location` * `create rejects an empty line list` * `create rejects duplicate line numbers` * `create rejects non-positive quantities` * `create rejects unknown items via CatalogApi` * `confirm writes an atomic TRANSFER_OUT + TRANSFER_IN pair per line` — uses `verifyOrder` to assert OUT-first-per-line dispatch order * `confirm refuses a non-DRAFT transfer` * `cancel refuses a CONFIRMED transfer` * `cancel flips a DRAFT transfer to CANCELLED` - Total framework unit tests: 288 (was 278), all green. ## What this unblocks - **Real warehouse workflows** — confirm a transfer from a picker UI (R1 is pending), driven by a BPMN that hands the confirm to a TaskHandler once the physical move is complete. - **pbc-quality (P5.8, last remaining core PBC)** — inspection plans + results + holds. Holds would typically quarantine stock by moving it to a QUARANTINE location via a stock transfer, which is the natural consumer for this aggregate. - **Stocktakes (physical inventory reconciliation)** — future pbc-warehousing verb that compares counted vs recorded and posts the differences as ADJUSTMENT rows; shares the same `recordMovement` primitive.
