朱子纯 / vibe-erp

…c-warehousing StockTransfer

First cross-PBC reaction originating from pbc-quality. Records a
REJECTED inspection with explicit source + quarantine location
codes, publishes an api.v1 event inside the same transaction as
the row insert, and pbc-warehousing's new subscriber atomically
creates + confirms a StockTransfer that moves the rejected
quantity to the quarantine bin. The whole chain — inspection
insert + event publish + transfer create + confirm + two ledger
rows — runs in a single transaction under the synchronous
in-process bus with Propagation.MANDATORY.

## Why the auto-quarantine is opt-in per-inspection

Not every inspection wants physical movement. A REJECTED batch
that's already separated from good stock on the shop floor doesn't
need the framework to move anything; the operator just wants the
record. Forcing every rejection to create a ledger pair would
collide with real-world QC workflows.

The contract is simple: the `InspectionRecord` now carries two
OPTIONAL columns (`source_location_code`, `quarantine_location_code`).
When BOTH are set AND the decision is REJECTED AND the rejected
quantity is positive, the subscriber reacts. Otherwise it logs at
DEBUG and does nothing. The event is published either way, so
audit/KPI subscribers see every inspection regardless.

## api.v1 additions

New event class `org.vibeerp.api.v1.event.quality.InspectionRecordedEvent`
with nine fields:

  inspectionCode, itemCode, sourceReference, decision,
  inspectedQuantity, rejectedQuantity,
  sourceLocationCode?, quarantineLocationCode?, inspector

All required fields validated in `init { }` — blank strings,
non-positive inspected quantity, negative rejected quantity, or
an unknown decision string all throw at publish time so a
malformed event never hits the outbox.

`aggregateType = "quality.InspectionRecord"` matches the
`<pbc>.<aggregate>` convention.

`decision` is carried as a String (not the pbc-quality
`InspectionDecision` enum) to keep guardrail #10 honest — api.v1
events MUST NOT leak internal PBC types. Consumers compare
against the literal `"APPROVED"` / `"REJECTED"` strings.

## pbc-quality changes

- `InspectionRecord` entity gains two nullable columns:
  `source_location_code` + `quarantine_location_code`.
- Liquibase migration `002-quality-quarantine-locations.xml` adds
  the columns to `quality__inspection_record`.
- `InspectionRecordService` now injects `EventBus` and publishes
  `InspectionRecordedEvent` inside the `@Transactional record()`
  method. The publish carries all nine fields including the
  optional locations.
- `RecordInspectionCommand` + `RecordInspectionRequest` gain the
  two optional location fields; unchanged default-null means
  every existing caller keeps working unchanged.
- `InspectionRecordResponse` exposes both new columns on the HTTP
  wire.

## pbc-warehousing changes

- New `QualityRejectionQuarantineSubscriber` @Component.
- Subscribes in `@PostConstruct` via the typed-class
  `EventBus.subscribe(InspectionRecordedEvent::class.java, ...)`
  overload — same pattern every other PBC subscriber uses
  (SalesOrderConfirmedSubscriber, WorkOrderRequestedSubscriber,
  the pbc-finance order subscribers).
- `handle(event)` is `internal` so the unit test can drive it
  directly without going through the bus.
- Activation contract (all must be true): decision=REJECTED,
  rejectedQuantity>0, sourceLocationCode non-blank,
  quarantineLocationCode non-blank. Any missing condition → no-op.
- Idempotency: derived transfer code is `TR-QC-<inspectionCode>`.
  Before creating, the subscriber checks
  `stockTransfers.findByCode(derivedCode)` — if anything exists
  (DRAFT, CONFIRMED, or CANCELLED), the subscriber skips. A
  replay of the same event under at-least-once delivery is safe.
- On success: creates a DRAFT StockTransfer with one line moving
  `rejectedQuantity` of `itemCode` from source to quarantine,
  then calls `confirm(id)` which writes the atomic TRANSFER_OUT
  + TRANSFER_IN ledger pair.

## Smoke test (fresh DB)

```
# seed
POST /api/v1/catalog/items       {code: WIDGET-1, baseUomCode: ea}
POST /api/v1/inventory/locations {code: WH-MAIN, type: WAREHOUSE}
POST /api/v1/inventory/locations {code: WH-QUARANTINE, type: WAREHOUSE}
POST /api/v1/inventory/movements {itemCode: WIDGET-1, locationId: <WH-MAIN>, delta: 100, reason: RECEIPT}

# the cross-PBC reaction
POST /api/v1/quality/inspections
     {code: QC-R-001,
      itemCode: WIDGET-1,
      sourceReference: "WO:WO-001",
      decision: REJECTED,
      inspectedQuantity: 50,
      rejectedQuantity: 7,
      reason: "surface scratches",
      sourceLocationCode: "WH-MAIN",
      quarantineLocationCode: "WH-QUARANTINE"}
  → 201 {..., sourceLocationCode: "WH-MAIN", quarantineLocationCode: "WH-QUARANTINE"}

# automatically created + confirmed
GET /api/v1/warehousing/stock-transfers/by-code/TR-QC-QC-R-001
  → 200 {
      "code": "TR-QC-QC-R-001",
      "fromLocationCode": "WH-MAIN",
      "toLocationCode": "WH-QUARANTINE",
      "status": "CONFIRMED",
      "note": "auto-quarantine from rejected inspection QC-R-001",
      "lines": [{"itemCode": "WIDGET-1", "quantity": 7.0}]
    }

# ledger state (raw SQL)
SELECT l.code, b.item_code, b.quantity
  FROM inventory__stock_balance b
  JOIN inventory__location l ON l.id = b.location_id
  WHERE b.item_code = 'WIDGET-1';
  WH-MAIN       | WIDGET-1 | 93.0000   ← was 100, now 93
  WH-QUARANTINE | WIDGET-1 |  7.0000   ← 7 rejected units here

SELECT item_code, location, reason, delta, reference
  FROM inventory__stock_movement m JOIN inventory__location l ON l.id=m.location_id
  WHERE m.reference = 'TR:TR-QC-QC-R-001';
  WIDGET-1 | WH-MAIN       | TRANSFER_OUT | -7 | TR:TR-QC-QC-R-001
  WIDGET-1 | WH-QUARANTINE | TRANSFER_IN  |  7 | TR:TR-QC-QC-R-001

# negatives
POST /api/v1/quality/inspections {decision: APPROVED, ...+locations}
  → 201, but GET /TR-QC-QC-A-001 → 404 (no transfer, correct opt-out)

POST /api/v1/quality/inspections {decision: REJECTED, rejected: 2, no locations}
  → 201, but GET /TR-QC-QC-R-002 → 404 (opt-in honored)

# handler log
[warehousing] auto-quarantining 7 units of 'WIDGET-1'
from 'WH-MAIN' to 'WH-QUARANTINE'
(inspection=QC-R-001, transfer=TR-QC-QC-R-001)
```

Everything happens in ONE transaction because EventBusImpl uses
Propagation.MANDATORY with synchronous delivery: the inspection
insert, the event publish, the StockTransfer create, the
confirm, and the two ledger rows all commit or roll back
together.

## Tests

- Updated `InspectionRecordServiceTest`: the service now takes an
  `EventBus` constructor argument. Every existing test got a
  relaxed `EventBus` mock; the one new test
  `record publishes InspectionRecordedEvent on success` captures
  the published event and asserts every field including the
  location codes.
- 6 new unit tests in `QualityRejectionQuarantineSubscriberTest`:
  * subscribe registers one listener for InspectionRecordedEvent
  * handle creates and confirms a quarantine transfer on a
    fully-populated REJECTED event (asserts derived code,
    locations, item code, quantity)
  * handle is a no-op when decision is APPROVED
  * handle is a no-op when sourceLocationCode is missing
  * handle is a no-op when quarantineLocationCode is missing
  * handle skips when a transfer with the derived code already
    exists (idempotent replay)
- Total framework unit tests: 334 (was 327), all green.

## What this unblocks

- **Quality KPI dashboards** — any PBC can now subscribe to
  `InspectionRecordedEvent` without coupling to pbc-quality.
- **pbc-finance quality-cost tracking** — when GL growth lands, a
  finance subscriber can debit a "quality variance" account on
  every REJECTED inspection.
- **REF.2 / customer plug-in workflows** — the printing-shop
  plug-in can emit an `InspectionRecordedEvent` of its own from
  a BPMN service task (via `context.eventBus.publish`) and drive
  the same quarantine chain without touching pbc-quality's HTTP
  surface.

## Non-goals (parking lot)

- Partial-batch quarantine decisions (moving some units to
  quarantine, some back to general stock, some to scrap). v1
  collapses the decision into a single "reject N units" action
  and assumes the operator splits batches manually before
  inspecting. A richer ResolutionPlan aggregate is a future
  chunk if real workflows need it.
- Quality metrics storage. The event is audited by the existing
  wildcard event subscriber but no PBC rolls it up into a KPI
  table. Belongs to a future reporting feature.
- Auto-approval chains. An APPROVED inspection could trigger a
  "release-from-hold" transfer (opposite direction) in a
  future-expanded subscriber, but v1 keeps the reaction
  REJECTED-only to match the "quarantine on fail" use case.