朱子纯 / vibe-erp

feat(pbc): P5.6 — pbc-orders-purchase + receive-driven inventory increase

The buying-side mirror of pbc-orders-sales. Adds the 6th real PBC
and closes the loop: the framework now does both directions of the
inventory flow through the same `InventoryApi.recordMovement` facade.
Buy stock with a PO that hits RECEIVED, ship stock with a SO that
hits SHIPPED, both feed the same `inventory__stock_movement` ledger.

What landed
-----------
* New Gradle subproject `pbc/pbc-orders-purchase` (16 modules total
  now). Same dependency set as pbc-orders-sales, same architectural
  enforcement — no direct dependency on any other PBC; cross-PBC
  references go through `api.v1.ext.<pbc>` facades at runtime.
* Two JPA entities mirroring SalesOrder / SalesOrderLine:
  - `PurchaseOrder` (header) — code, partner_code (varchar, NOT a
    UUID FK), status enum DRAFT/CONFIRMED/RECEIVED/CANCELLED,
    order_date, expected_date (nullable, the supplier's promised
    delivery date), currency_code, total_amount, ext jsonb.
  - `PurchaseOrderLine` — purchase_order_id FK, line_no, item_code,
    quantity, unit_price, currency_code. Same shape as the sales
    order line; the api.v1 facade reuses `SalesOrderLineRef` rather
    than declaring a duplicate type.
* `PurchaseOrderService.create` performs three cross-PBC validations
  in one transaction:
  1. PartnersApi.findPartnerByCode → reject if null.
  2. The partner's `type` must be SUPPLIER or BOTH (a CUSTOMER-only
     partner cannot be the supplier of a purchase order — the
     mirror of the sales-order rule that rejects SUPPLIER-only
     partners as customers).
  3. CatalogApi.findItemByCode for EVERY line.
  Then validates: at least one line, no duplicate line numbers,
  positive quantity, non-negative price, currency matches header.
  The header total is RECOMPUTED from the lines (caller's value
  ignored — never trust a financial aggregate sent over the wire).
* State machine enforced by `confirm()`, `cancel()`, and `receive()`:
  - DRAFT → CONFIRMED   (confirm)
  - DRAFT → CANCELLED   (cancel)
  - CONFIRMED → CANCELLED (cancel before receipt)
  - CONFIRMED → RECEIVED  (receive — increments inventory)
  - RECEIVED → ×          (terminal; cancellation requires a
                            return-to-supplier flow)
* `receive(id, receivingLocationCode)` walks every line and calls
  `inventoryApi.recordMovement(... +line.quantity reason="PURCHASE_RECEIPT"
  reference="PO:<order_code>")`. The whole operation runs in ONE
  transaction so a failure on any line rolls back EVERY line's
  already-written movement AND the order status change. The
  customer cannot end up with "5 of 7 lines received, status
  still CONFIRMED, ledger half-written".
* New `POST /api/v1/orders/purchase-orders/{id}/receive` endpoint
  with body `{"receivingLocationCode": "WH-MAIN"}`, gated by
  `orders.purchase.receive`. The single-arg DTO has the same
  Jackson `@JsonCreator(mode = PROPERTIES)` workaround as
  `ShipSalesOrderRequest` (the trap is documented in the class
  KDoc with a back-reference to ShipSalesOrderRequest).
* Confirm/cancel/receive endpoints carry `@RequirePermission`
  annotations (`orders.purchase.confirm`, `orders.purchase.cancel`,
  `orders.purchase.receive`). All three keys declared in the new
  `orders-purchase.yml` metadata.
* New api.v1 facade `org.vibeerp.api.v1.ext.orders.PurchaseOrdersApi`
  + `PurchaseOrderRef`. Reuses the existing `SalesOrderLineRef`
  type for the line shape — buying and selling lines carry the
  same fields, so duplicating the ref type would be busywork.
* `PurchaseOrdersApiAdapter` — sixth `*ApiAdapter` after Identity,
  Catalog, Partners, Inventory, SalesOrders.
* `orders-purchase.yml` metadata declaring 2 entities, 6 permission
  keys, 1 menu entry under "Purchasing".

End-to-end smoke test (the full demo loop)
------------------------------------------
Reset Postgres, booted the app, ran:
* Login as admin
* POST /catalog/items → PAPER-A4
* POST /partners → SUP-PAPER (SUPPLIER)
* POST /inventory/locations → WH-MAIN
* GET /inventory/balances?itemCode=PAPER-A4 → [] (no stock)
* POST /orders/purchase-orders → PO-2026-0001 for 5000 sheets
  @ $0.04 = total $200.00 (recomputed from the line)
* POST /purchase-orders/{id}/confirm → status CONFIRMED
* POST /purchase-orders/{id}/receive body={"receivingLocationCode":"WH-MAIN"}
  → status RECEIVED
* GET /inventory/balances?itemCode=PAPER-A4 → quantity=5000
* GET /inventory/movements?itemCode=PAPER-A4 →
  PURCHASE_RECEIPT delta=5000 ref=PO:PO-2026-0001

Then the FULL loop with the sales side from the previous chunk:
* POST /partners → CUST-ACME (CUSTOMER)
* POST /orders/sales-orders → SO-2026-0001 for 50 sheets
* confirm + ship from WH-MAIN
* GET /inventory/balances?itemCode=PAPER-A4 → quantity=4950 (5000-50)
* GET /inventory/movements?itemCode=PAPER-A4 →
  PURCHASE_RECEIPT delta=5000  ref=PO:PO-2026-0001
  SALES_SHIPMENT   delta=-50   ref=SO:SO-2026-0001

The framework's `InventoryApi.recordMovement` facade now has TWO
callers — pbc-orders-sales (negative deltas, SALES_SHIPMENT) and
pbc-orders-purchase (positive deltas, PURCHASE_RECEIPT) — feeding
the same ledger from both sides.

Failure paths verified:
* Re-receive a RECEIVED PO → 400 "only CONFIRMED orders can be received"
* Cancel a RECEIVED PO → 400 "issue a return-to-supplier flow instead"
* Create a PO from a CUSTOMER-only partner → 400 "partner 'CUST-ONLY'
  is type CUSTOMER and cannot be the supplier of a purchase order"

Regression: catalog uoms, identity users, partners, inventory,
sales orders, purchase orders, printing-shop plates with i18n,
metadata entities (15 now, was 13) — all still HTTP 2xx.

Build
-----
* `./gradlew build`: 16 subprojects, 186 unit tests (was 175),
  all green. The 11 new tests cover the same shapes as the
  sales-order tests but inverted: unknown supplier, CUSTOMER-only
  rejection, BOTH-type acceptance, unknown item, empty lines,
  total recomputation, confirm/cancel state machine,
  receive-rejects-non-CONFIRMED, receive-walks-lines-with-positive-
  delta, cancel-rejects-RECEIVED, cancel-CONFIRMED-allowed.

What was deferred
-----------------
* **RFQs** (request for quotation) and **supplier price catalogs**
  — both lay alongside POs but neither is in v1.
* **Partial receipts**. v1's RECEIVED is "all-or-nothing"; the
  supplier delivering 4500 of 5000 sheets is not yet modelled.
* **Supplier returns / refunds**. The cancel-RECEIVED rejection
  message says "issue a return-to-supplier flow" — that flow
  doesn't exist yet.
* **Three-way matching** (PO + receipt + invoice). Lands with
  pbc-finance.
* **Multi-leg transfers**. TRANSFER_IN/TRANSFER_OUT exist in the
  movement enum but no service operation yet writes both legs
  in one transaction.