朱子纯 / vibe-erp

feat(inventory+warehousing): InventoryApi.findLocationByCode — pbc-warehousing v…

…alidates locations at create

Follow-up to the pbc-warehousing chunk. Plugs a real gap noticed in
the smoke test: an unknown fromLocationCode or toLocationCode on a
StockTransfer was silently accepted at create() and only surfaced
as a confirm()-time rollback, which is a confusing UX — the operator
types TR-001 wrong, hits "create", then hits "confirm" minutes later
and sees "location GHOST-SRC is not in the inventory directory".

## api.v1 growth

New cross-PBC method on `InventoryApi`:

    fun findLocationByCode(locationCode: String): LocationRef?

Parallel shape to `CatalogApi.findItemByCode` — a lookup-by-code
returning a lightweight ref or null, safe for any cross-PBC consumer
to inject. The returned `LocationRef` data class carries id, code,
name, type (as a String, not the inventory-internal LocationType
enum — rationale in the KDoc), and active flag. Fields that are
NOT part of the cross-PBC contract (audit columns, ext JSONB, the
raw JPA entity) stay inside pbc-inventory.

api.v1 additive change within the v1 line — no breaking rename, no
signature churn on existing methods. The interface adds a new
abstract method, which IS technically a source-breaking change for
any in-tree implementation, but the only impl is
pbc-inventory/InventoryApiAdapter which is updated in the same
commit. No external plug-in implements InventoryApi (by design;
plug-ins inject it, they don't provide it).

## Adapter implementation

`InventoryApiAdapter.findLocationByCode` resolves the location via
the existing `LocationJpaRepository.findByCode`, which is exactly
what `recordMovement` already uses. A new private extension
`Location.toRef()` builds the api.v1 DTO. Zero new SQL; zero new
repository methods.

## pbc-warehousing wiring

`StockTransferService.create` now calls the facade twice — once for
the source location, once for the destination — BEFORE validating
lines. The four-step ordering is: code uniqueness → from != to →
non-empty lines → both locations exist and are active → per-line
validation. Unknown locations produce a 400 with a clear message;
deactivated locations produce a 400 distinguishing "doesn't exist"
from "exists but can't be used":

    "from location code 'GHOST-SRC' is not in the inventory directory"
    "from location 'WH-CLOSED' is deactivated and cannot be transfer source"

The confirm() path is unchanged. Locations may still vanish between
create and confirm (though the likelihood is low for a normal
workflow), and `recordMovement` will still raise its own error in
that case — belt and suspenders.

## Smoke test

```
POST /api/v1/inventory/locations {code: WH-GOOD, type: WAREHOUSE}
POST /api/v1/catalog/items       {code: ITEM-1, baseUomCode: ea}

POST /api/v1/warehousing/stock-transfers
     {code: TR-bad, fromLocationCode: GHOST-SRC, toLocationCode: WH-GOOD,
      lines: [{lineNo: 1, itemCode: ITEM-1, quantity: 1}]}
  → 400 "from location code 'GHOST-SRC' is not in the inventory directory"
     (before this commit: 201 DRAFT, then 400 at confirm)

POST /api/v1/warehousing/stock-transfers
     {code: TR-bad2, fromLocationCode: WH-GOOD, toLocationCode: GHOST-DST,
      lines: [{lineNo: 1, itemCode: ITEM-1, quantity: 1}]}
  → 400 "to location code 'GHOST-DST' is not in the inventory directory"

POST /api/v1/warehousing/stock-transfers
     {code: TR-ok, fromLocationCode: WH-GOOD, toLocationCode: WH-OTHER,
      lines: [{lineNo: 1, itemCode: ITEM-1, quantity: 1}]}
  → 201 DRAFT   ← happy path still works
```

## Tests

- Updated the 3 existing `StockTransferServiceTest` tests that
  created real transfers to stub `inventory.findLocationByCode` for
  both WH-A and WH-B via a new `stubLocation()` helper.
- 3 new tests:
  * `create rejects unknown from location via InventoryApi`
  * `create rejects unknown to location via InventoryApi`
  * `create rejects a deactivated from location`
- Total framework unit tests: 300 (was 297), all green.

## Why this isn't a breaking api.v1 change

InventoryApi is an interface consumed by other PBCs and by plug-ins,
implemented ONLY by pbc-inventory. Adding a new method to an
interface IS a source-breaking change for any implementer — but
the framework's dependency rules mean no external code implements
this interface. Plug-ins and other PBCs CONSUME it via dependency
injection; the only production impl is InventoryApiAdapter, updated
in the same commit. Binary compatibility for consumers is
preserved: existing call sites compile and run unchanged because
only the interface grew, not its existing methods.

If/when a third party implements InventoryApi (e.g. a test double
outside the framework, or a custom backend plug-in), this would be
a semver-major-worthy addition. For the in-tree framework, it's
additive-within-a-major.