朱子纯 / vibe-erp

feat(inventory+orders): movement ledger + sales-order shipping (end-to-end demo)

The killer demo finally works: place a sales order, ship it, watch
inventory drop. This chunk lands the two pieces that close the loop:
the inventory movement ledger (the audit-grade history of every
stock change) and the sales-order /ship endpoint that calls
InventoryApi.recordMovement to atomically debit stock for every line.

This is the framework's FIRST cross-PBC WRITE flow. Every earlier
cross-PBC call was a read (CatalogApi.findItemByCode,
PartnersApi.findPartnerByCode, InventoryApi.findStockBalance).
Shipping inverts that: pbc-orders-sales synchronously writes to
inventory's tables (via the api.v1 facade) as a side effect of
changing its own state, all in ONE Spring transaction.

What landed
-----------
* New `inventory__stock_movement` table — append-only ledger
  (id, item_code, location_id FK, signed delta, reason enum,
  reference, occurred_at, audit cols). CHECK constraint
  `delta <> 0` rejects no-op rows. Indexes on item_code,
  location_id, the (item, location) composite, reference, and
  occurred_at. Migration is in its own changelog file
  (002-inventory-movement-ledger.xml) per the project convention
  that each new schema cut is a new file.
* New `StockMovement` JPA entity + repository + `MovementReason`
  enum (RECEIPT, ISSUE, ADJUSTMENT, SALES_SHIPMENT, PURCHASE_RECEIPT,
  TRANSFER_OUT, TRANSFER_IN). Each value carries a documented sign
  convention; the service rejects mismatches (a SALES_SHIPMENT
  with positive delta is a caller bug, not silently coerced).
* New `StockMovementService.record(...)` — the ONE entry point for
  changing inventory. Cross-PBC item validation via CatalogApi,
  local location validation, sign-vs-reason enforcement, and
  negative-balance rejection all happen BEFORE the write. The
  ledger row insert AND the balance row update happen in the
  SAME database transaction so the two cannot drift.
* `StockBalanceService.adjust` refactored to delegate: it computes
  delta = newQty - oldQty and calls record(... ADJUSTMENT). The
  REST endpoint keeps its absolute-quantity semantics — operators
  type "the shelf has 47" not "decrease by 3" — but every
  adjustment now writes a ledger row too. A no-op adjustment
  (re-saving the same value) does NOT write a row, so the audit
  log doesn't fill with noise from operator clicks that didn't
  change anything.
* New `StockMovementController` at `/api/v1/inventory/movements`:
  GET filters by itemCode, locationId, or reference (for "all
  movements caused by SO-2026-0001"); POST records a manual
  movement. Both protected by `inventory.stock.adjust`.
* `InventoryApi` facade extended with `recordMovement(itemCode,
  locationCode, delta, reason: String, reference)`. The reason is
  a String in the api.v1 surface (not the local enum) so plug-ins
  don't import inventory's internal types — the closed set is
  documented on the interface. The adapter parses the string with
  a meaningful error on unknown values.
* New `SHIPPED` status on `SalesOrderStatus`. Transitions:
  DRAFT → CONFIRMED → SHIPPED (terminal). Cancelling a SHIPPED
  order is rejected with "issue a return / refund flow instead".
* New `SalesOrderService.ship(id, shippingLocationCode)`: walks
  every line, calls `inventoryApi.recordMovement(... -line.quantity
  reason="SALES_SHIPMENT" reference="SO:{order_code}")`, flips
  status to SHIPPED. The whole operation runs in ONE transaction
  so a failure on any line — bad item, bad location, would push
  balance negative — rolls back the order status change AND every
  other line's already-written movement. The customer never ends
  up with "5 of 7 lines shipped, status still CONFIRMED, ledger
  half-written".
* New `POST /api/v1/orders/sales-orders/{id}/ship` endpoint with
  body `{"shippingLocationCode": "WH-MAIN"}`, gated by the new
  `orders.sales.ship` permission key.
* `ShipSalesOrderRequest` is a single-arg Kotlin data class — same
  Jackson deserialization trap as `RefreshRequest`. Fixed with
  `@JsonCreator(mode = PROPERTIES) + @param:JsonProperty`. The
  trap is documented in the class KDoc.

End-to-end smoke test (the killer demo)
---------------------------------------
Reset Postgres, booted the app, ran:
* Login as admin
* POST /catalog/items → PAPER-A4
* POST /partners → CUST-ACME
* POST /inventory/locations → WH-MAIN
* POST /inventory/balances/adjust → quantity=1000
  (now writes a ledger row via the new path)
* GET /inventory/movements?itemCode=PAPER-A4 →
  ADJUSTMENT delta=1000 ref=null
* POST /orders/sales-orders → SO-2026-0001 (50 units of PAPER-A4)
* POST /sales-orders/{id}/confirm → status CONFIRMED
* POST /sales-orders/{id}/ship body={"shippingLocationCode":"WH-MAIN"}
  → status SHIPPED
* GET /inventory/balances?itemCode=PAPER-A4 → quantity=950
  (1000 - 50)
* GET /inventory/movements?itemCode=PAPER-A4 →
  ADJUSTMENT     delta=1000   ref=null
  SALES_SHIPMENT delta=-50    ref=SO:SO-2026-0001

Failure paths verified:
* Re-ship a SHIPPED order → 400 "only CONFIRMED orders can be shipped"
* Cancel a SHIPPED order → 400 "issue a return / refund flow instead"
* Place a 10000-unit order, confirm, try to ship from a 950-stock
  warehouse → 400 "stock movement would push balance for 'PAPER-A4'
  at location ... below zero (current=950.0000, delta=-10000.0000)";
  balance unchanged after the rollback (transaction integrity
  verified)

Regression: catalog uoms, identity users, inventory locations,
printing-shop plates with i18n, metadata entities — all still
HTTP 2xx.

Build
-----
* `./gradlew build`: 15 subprojects, 175 unit tests (was 163),
  all green. The 12 new tests cover:
  - StockMovementServiceTest (8): zero-delta rejection, positive
    SALES_SHIPMENT rejection, negative RECEIPT rejection, both
    signs allowed on ADJUSTMENT, unknown item via CatalogApi seam,
    unknown location, would-push-balance-negative rejection,
    new-row + existing-row balance update.
  - StockBalanceServiceTest, rewritten (5): negative-quantity
    early reject, delegation with computed positive delta,
    delegation with computed negative delta, no-op adjustment
    short-circuit (NO ledger row written), no-op on missing row
    creates an empty row at zero.
  - SalesOrderServiceTest, additions (3): ship rejects non-CONFIRMED,
    ship walks lines and calls recordMovement with negated quantity
    + correct reference, cancel rejects SHIPPED.

What was deferred
-----------------
* **Event publication.** A `StockMovementRecorded` event would
  let pbc-finance and pbc-production react to ledger writes
  without polling. The event bus has been wired since P1.7 but
  no real cross-PBC flow uses it yet — that's the natural next
  chunk and the chunk after this commit.
* **Multi-leg transfers.** TRANSFER_OUT and TRANSFER_IN are in
  the enum but no service operation atomically writes both legs
  yet (both legs in one transaction is required to keep total
  on-hand invariant).
* **Reservation / pick lists.** "Reserve 50 of PAPER-A4 for an
  unconfirmed order" is its own concept that lands later.
* **Shipped-order returns / refunds.** The cancel-SHIPPED rule
  points the user at "use a return flow" — that flow doesn't
  exist yet. v1 says shipments are terminal.