朱子纯 / vibe-erp

feat(pbc): P5.5 — pbc-orders-sales + first PBC consuming TWO cross-PBC facades

The fifth real PBC and the first business workflow PBC. pbc-inventory
proved a PBC could consume ONE cross-PBC facade (CatalogApi).
pbc-orders-sales consumes TWO simultaneously (PartnersApi for the
customer, CatalogApi for every line's item) in a single transaction —
the most rigorous test of the modular monolith story so far. Neither
source PBC is on the compile classpath; the Gradle build refuses any
direct dependency. Spring DI wires the api.v1 interfaces to their
concrete adapters at runtime.

What landed
-----------
* New Gradle subproject `pbc/pbc-orders-sales` (15 modules total).
* Two JPA entities, both extending `AuditedJpaEntity`:
  - `SalesOrder` (header) — code, partner_code (varchar, NOT a UUID
    FK to partners), status enum DRAFT/CONFIRMED/CANCELLED, order_date,
    currency_code (varchar(3)), total_amount numeric(18,4),
    ext jsonb. Eager-loaded `lines` collection because every read of
    the header is followed by a read of the lines in practice.
  - `SalesOrderLine` — sales_order_id FK, line_no, item_code (varchar,
    NOT a UUID FK to catalog), quantity, unit_price, currency_code.
    Per-line currency in the schema even though v1 enforces all-lines-
    match-header (so multi-currency relaxation is later schema-free).
    No `ext` jsonb on lines: lines are facts, not master records;
    custom fields belong on the header.
* `SalesOrderService.create` performs **three independent
  cross-PBC validations** in one transaction:
  1. PartnersApi.findPartnerByCode → reject if null (covers unknown
     AND inactive partners; the facade hides them).
  2. PartnersApi result.type must be CUSTOMER or BOTH (a SUPPLIER-only
     partner cannot be the customer of a sales order).
  3. CatalogApi.findItemByCode for EVERY line → reject if null.
  Then it ALSO 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 — the caller's value
  is intentionally ignored. Never trust a financial aggregate sent
  over the wire.
* State machine enforced by `confirm()` and `cancel()`:
  - DRAFT → CONFIRMED   (confirm)
  - DRAFT → CANCELLED   (cancel from draft)
  - CONFIRMED → CANCELLED (cancel a confirmed order)
  Anything else throws with a descriptive message. CONFIRMED orders
  are immutable except for cancellation — the `update` method refuses
  to mutate a non-DRAFT order.
* `update` with line items REPLACES the existing lines wholesale
  (PUT semantics for lines, PATCH for header columns). Partial line
  edits are not modelled because the typical "edit one line" UI
  gesture renders to a full re-send anyway.
* REST: `/api/v1/orders/sales-orders` (CRUD + `/confirm` + `/cancel`).
  State transitions live on dedicated POST endpoints rather than
  PATCH-based status writes — they have side effects (lines become
  immutable, downstream PBCs will receive events in future versions),
  and sentinel-status writes hide that.
* New api.v1 facade `org.vibeerp.api.v1.ext.orders.SalesOrdersApi`
  with `findByCode`, `findById`, `SalesOrderRef`, `SalesOrderLineRef`.
  Fifth ext.* package after identity, catalog, partners, inventory.
  Sets up the next consumers: pbc-production for work orders, pbc-finance
  for invoicing, the printing-shop reference plug-in for the
  quote-to-job-card workflow.
* `SalesOrdersApiAdapter` runtime implementation. Cancelled orders ARE
  returned by the facade (unlike inactive items / partners which are
  hidden) because downstream consumers may legitimately need to react
  to a cancellation — release a production slot, void an invoice, etc.
* `orders-sales.yml` metadata declaring 2 entities, 5 permission keys,
  1 menu entry.

Build enforcement (still load-bearing)
--------------------------------------
The root `build.gradle.kts` STILL refuses any direct dependency from
`pbc-orders-sales` to either `pbc-partners` or `pbc-catalog`. Try
adding either as `implementation(project(...))` and the build fails
at configuration time with the architectural violation. The
cross-PBC interfaces live in api-v1; the concrete adapters live in
their owning PBCs; Spring DI assembles them at runtime via the
bootstrap @ComponentScan. pbc-orders-sales sees only the api.v1
interfaces.

End-to-end smoke test
---------------------
Reset Postgres, booted the app, hit:
* POST /api/v1/catalog/items × 2  → PAPER-A4, INK-CYAN
* POST /api/v1/partners/partners → CUST-ACME (CUSTOMER), SUP-ONLY (SUPPLIER)
* POST /api/v1/orders/sales-orders → 201, two lines, total 386.50
  (5000 × 0.05 + 3 × 45.50 = 250.00 + 136.50, correctly recomputed)
* POST .../sales-orders with FAKE-PARTNER → 400 with the meaningful
  message "partner code 'FAKE-PARTNER' is not in the partners
  directory (or is inactive)"
* POST .../sales-orders with SUP-ONLY → 400 "partner 'SUP-ONLY' is
  type SUPPLIER and cannot be the customer of a sales order"
* POST .../sales-orders with FAKE-ITEM line → 400 "line 1: item code
  'FAKE-ITEM' is not in the catalog (or is inactive)"
* POST /{id}/confirm → status DRAFT → CONFIRMED
* PATCH the CONFIRMED order → 400 "only DRAFT orders are mutable"
* Re-confirm a CONFIRMED order → 400 "only DRAFT can be confirmed"
* POST /{id}/cancel a CONFIRMED order → status CANCELLED (allowed)
* SELECT * FROM orders_sales__sales_order — single row, total
  386.5000, status CANCELLED
* SELECT * FROM orders_sales__sales_order_line — two rows in line_no
  order with the right items and quantities
* GET /api/v1/_meta/metadata/entities → 13 entities now (was 11)
* Regression: catalog uoms, identity users, partners, inventory
  locations, printing-shop plates with i18n (Accept-Language: zh-CN)
  all still HTTP 2xx.

Build
-----
* `./gradlew build`: 15 subprojects, 153 unit tests (was 139),
  all green. The 14 new tests cover: unknown/SUPPLIER-only/BOTH-type
  partner paths, unknown item path, empty/duplicate-lineno line
  arrays, negative-quantity early reject (verifies CatalogApi NOT
  consulted), currency mismatch reject, total recomputation, all
  three state-machine transitions and the rejected ones.

What was deferred
-----------------
* **Sales-order shipping**. Confirmed orders cannot yet ship, because
  shipping requires atomically debiting inventory — which needs the
  movement ledger that was deferred from P5.3. The pair of chunks
  (movement ledger + sales-order shipping flow) is the natural next
  combination.
* **Multi-currency lines**. The schema column is per-line but the
  service enforces all-lines-match-header in v1. Relaxing this is a
  service-only change.
* **Quotes** (DRAFT-but-customer-visible) and **deliveries** (the
  thing that triggers shipping). v1 only models the order itself.
* **Pricing engine / discounts**. v1 takes the unit price the caller
  sends. A real ERP has a price book lookup, customer-specific
  pricing, volume discounts, promotional pricing — all of which slot
  in BEFORE the line price is set, leaving the schema unchanged.
* **Tax**. v1 totals are pre-tax. Tax calculation is its own PBC
  (and a regulatory minefield) that lands later.