朱子纯 / vibe-erp

feat(workflow): REF.1 — plug-in BPMN publishes WorkOrderRequestedEvent → pbc-pro…

…duction auto-creates WorkOrder

First end-to-end cross-PBC workflow driven entirely from a customer
plug-in through api.v1 surfaces. A printing-shop BPMN kicks off a
TaskHandler that publishes a generic api.v1 event; pbc-production
reacts by creating a DRAFT WorkOrder. The plug-in has zero
compile-time coupling to pbc-production, and pbc-production has zero
knowledge the plug-in exists.

## Why an event, not a facade

Two options were on the table for "how does a plug-in ask
pbc-production to create a WorkOrder":

  (a) add a new cross-PBC facade `api.v1.ext.production.ProductionApi`
      with a `createWorkOrder(command)` method
  (b) add a generic `WorkOrderRequestedEvent` in `api.v1.event.production`
      that anyone can publish — this commit

Facade pattern (a) is what InventoryApi.recordMovement and
CatalogApi.findItemByCode use: synchronous, in-transaction,
caller-blocks-on-completion. Event pattern (b) is what
SalesOrderConfirmedEvent → SalesOrderConfirmedSubscriber uses:
asynchronous over the bus, still in-transaction (the bus uses
`Propagation.MANDATORY` with synchronous delivery so a failure
rolls everything back), but the caller doesn't need a typed result.

Option (b) wins for plug-in → pbc-production:

- Plug-in compile-time surface stays identical: plug-ins already
  import `api.v1.event.*` to publish. No new api.v1.ext package.
  Zero new plug-in dependency.
- The outbox gets the row for free — a crash between publish and
  delivery replays cleanly from `platform__event_outbox`.
- A second customer plug-in shipping a different flow that ALSO
  wants to auto-spawn work orders doesn't need a second facade, just
  publishes the same event. pbc-scheduling (future) can subscribe
  to the same channel without duplicating code.

The synchronous facade pattern stays the right tool for cross-PBC
operations the caller needs to observe (read-throughs, inventory
debits that must block the current transaction). Creating a DRAFT
work order is a fire-and-trust operation — the event shape fits.

## What landed

### api.v1 — WorkOrderRequestedEvent

New event class `org.vibeerp.api.v1.event.production.WorkOrderRequestedEvent`
with four required fields:
  - `code`: desired work-order code (must be unique globally;
    convention is to bake the source reference into it so duplicate
    detection is trivial, e.g. `WO-FROM-PRINTINGSHOP-Q-007`)
  - `outputItemCode` + `outputQuantity`: what to produce
  - `sourceReference`: opaque free-form pointer used in logs and
    the outbox audit trail. Example values:
    `plugin:printing-shop:quote:Q-007`,
    `pbc-orders-sales:SO-2026-001:L2`

The class is a `DomainEvent` (not a `WorkOrderEvent` subclass — the
existing `WorkOrderEvent` sealed interface is for LIFECYCLE events
published BY pbc-production, not for inbound requests). `init`
validators reject blank strings and non-positive quantities so a
malformed event fails fast at publish time rather than at the
subscriber.

### pbc-production — WorkOrderRequestedSubscriber

New `@Component` in `pbc/pbc-production/.../event/WorkOrderRequestedSubscriber.kt`.
Subscribes in `@PostConstruct` via the typed-class `EventBus.subscribe`
overload (same pattern as `SalesOrderConfirmedSubscriber` + the six
pbc-finance order subscribers). The subscriber:

  1. Looks up `workOrders.findByCode(event.code)` as the idempotent
     short-circuit. If a WorkOrder with that code already exists
     (outbox replay, future async bus retry, developer re-running the
     same BPMN process), the subscriber logs at DEBUG and returns.
     **Second execution of the same BPMN produces the same outbox row
     which the subscriber then skips — the database ends up with
     exactly ONE WorkOrder regardless of how many times the process
     runs.**
  2. Calls `WorkOrderService.create(CreateWorkOrderCommand(...))` with
     the event's fields. `sourceSalesOrderCode` is null because this
     is the generic path, not the SO-driven one.

Why this is a SECOND subscriber rather than extending
`SalesOrderConfirmedSubscriber`: the two events serve different
producers. `SalesOrderConfirmedEvent` is pbc-orders-sales-specific
and requires a round-trip through `SalesOrdersApi.findByCode` to
fetch the lines; `WorkOrderRequestedEvent` carries everything the
subscriber needs inline. Collapsing them would mean the generic
path inherits the SO-flow's SO-specific lookup and short-circuit
logic that doesn't apply to it.

### reference printing-shop plug-in — CreateWorkOrderFromQuoteTaskHandler

New plug-in TaskHandler in
`reference-customer/plugin-printing-shop/.../workflow/CreateWorkOrderFromQuoteTaskHandler.kt`.
Captures the `PluginContext` via constructor — same pattern as
`PlateApprovalTaskHandler` landed in `7b2ab34d` — and from inside
`execute`:

  1. Reads `quoteCode`, `itemCode`, `quantity` off the process variables
     (`quantity` accepts Number or String since Flowable's variable
     coercion is flexible).
  2. Derives `workOrderCode = "WO-FROM-PRINTINGSHOP-$quoteCode"` and
     `sourceReference = "plugin:printing-shop:quote:$quoteCode"`.
  3. Logs via `context.logger.info(...)` — the line is tagged
     `[plugin:printing-shop]` by the framework's `Slf4jPluginLogger`.
  4. Publishes `WorkOrderRequestedEvent` via `context.eventBus.publish(...)`.
     This is the first time a plug-in TaskHandler publishes a cross-PBC
     event from inside a workflow — proves the event-bus leg of the
     handler-context pattern works end-to-end.
  5. Writes `workOrderCode` + `workOrderRequested=true` back to the
     process variables so a downstream BPMN step or the HTTP caller
     can see the derived code.

The handler is registered in `PrintingShopPlugin.start(context)`
alongside `PlateApprovalTaskHandler`:

    context.taskHandlers.register(PlateApprovalTaskHandler(context))
    context.taskHandlers.register(CreateWorkOrderFromQuoteTaskHandler(context))

Teardown via `unregisterAllByOwner("printing-shop")` still works
unchanged — the scoped registrar tracks both handlers.

### reference printing-shop plug-in — quote-to-work-order.bpmn20.xml

New BPMN file `processes/quote-to-work-order.bpmn20.xml` in the
plug-in JAR. Single synchronous service task, process definition
key `plugin-printing-shop-quote-to-work-order`, service task id
`printing_shop.quote.create_work_order` (matches the handler key).
Auto-deployed by the host's `PluginProcessDeployer` at plug-in
start — the printing-shop plug-in now ships two BPMNs bundled into
one Flowable deployment, both under category `printing-shop`.

## Smoke test (fresh DB)

```
$ docker compose down -v && docker compose up -d db
$ ./gradlew :distribution:bootRun &
...
registered TaskHandler 'printing_shop.plate.approve' owner='printing-shop' ...
registered TaskHandler 'printing_shop.quote.create_work_order' owner='printing-shop' ...
[plugin:printing-shop] registered 2 TaskHandlers: printing_shop.plate.approve, printing_shop.quote.create_work_order
PluginProcessDeployer: plug-in 'printing-shop' deployed 2 BPMN resource(s) as Flowable deploymentId='1e5c...':
  [processes/quote-to-work-order.bpmn20.xml, processes/plate-approval.bpmn20.xml]
pbc-production subscribed to WorkOrderRequestedEvent via EventBus.subscribe (typed-class overload)

# 1) seed a catalog item
$ curl -X POST /api/v1/catalog/items
       {"code":"BOOK-HARDCOVER","name":"Hardcover book","itemType":"GOOD","baseUomCode":"ea"}
  → 201 BOOK-HARDCOVER

# 2) start the plug-in's quote-to-work-order BPMN
$ curl -X POST /api/v1/workflow/process-instances
       {"processDefinitionKey":"plugin-printing-shop-quote-to-work-order",
        "variables":{"quoteCode":"Q-007","itemCode":"BOOK-HARDCOVER","quantity":500}}
  → 201 {"ended":true,
         "variables":{"quoteCode":"Q-007",
                      "itemCode":"BOOK-HARDCOVER",
                      "quantity":500,
                      "workOrderCode":"WO-FROM-PRINTINGSHOP-Q-007",
                      "workOrderRequested":true}}

Log lines observed:
  [plugin:printing-shop] quote Q-007: publishing WorkOrderRequestedEvent
     (code=WO-FROM-PRINTINGSHOP-Q-007, item=BOOK-HARDCOVER, qty=500)
  [production] WorkOrderRequestedEvent creating work order 'WO-FROM-PRINTINGSHOP-Q-007'
     for item 'BOOK-HARDCOVER' x 500 (source='plugin:printing-shop:quote:Q-007')

# 3) verify the WorkOrder now exists in pbc-production
$ curl /api/v1/production/work-orders
  → [{"id":"029c2482-...",
      "code":"WO-FROM-PRINTINGSHOP-Q-007",
      "outputItemCode":"BOOK-HARDCOVER",
      "outputQuantity":500.0,
      "status":"DRAFT",
      "sourceSalesOrderCode":null,
      "inputs":[], "ext":{}}]

# 4) run the SAME BPMN a second time — verify idempotent
$ curl -X POST /api/v1/workflow/process-instances
       {same body as above}
  → 201  (process ends, workOrderRequested=true, new event published + delivered)
$ curl /api/v1/production/work-orders
  → count=1, still only WO-FROM-PRINTINGSHOP-Q-007
```

Every single step runs through an api.v1 public surface. No framework
core code knows the printing-shop plug-in exists; no plug-in code knows
pbc-production exists. They meet on the event bus, and the outbox
guarantees the delivery.

## Tests

- 3 new tests in `pbc-production/.../WorkOrderRequestedSubscriberTest`:
  * `subscribe registers one listener for WorkOrderRequestedEvent`
  * `handle creates a work order from the event fields` — captures the
    `CreateWorkOrderCommand` and asserts every field
  * `handle short-circuits when a work order with that code already exists`
    — proves the idempotent branch
- Total framework unit tests: 278 (was 275), all green.

## What this unblocks

- **Richer multi-step BPMNs** in the plug-in that chain plate
  approval + quote → work order + production start + completion.
- **Plug-in-owned Quote entity** — the printing-shop plug-in can now
  introduce a `plugin_printingshop__quote` table via its own Liquibase
  changelog and have its HTTP endpoint create quotes that kick off the
  quote-to-work-order workflow automatically (or on operator confirm).
- **pbc-production routings/operations (v3)** — each operation becomes
  a BPMN step, potentially driven by plug-ins contributing custom
  steps via the same TaskHandler + event seam.
- **Second reference plug-in** — any new customer plug-in can publish
  `WorkOrderRequestedEvent` from its own workflows without any
  framework change.

## Non-goals (parking lot)

- The handler publishes but does not also read pbc-production state
  back. A future "wait for WO completion" BPMN step could subscribe
  to `WorkOrderCompletedEvent` inside a user-task + signal flow, but
  the engine's signal/correlation machinery isn't wired to
  plug-ins yet.
- Quote entity + HTTP + real business logic. REF.1 proves the
  cross-PBC event seam; the richer quote lifecycle is a separate
  chunk that can layer on top of this.
- Transactional rollback integration test. The synchronous bus +
  `Propagation.MANDATORY` guarantees it, but an explicit test that
  a subscriber throw rolls back both the ledger-adjacent writes and
  the Flowable process state would be worth adding with a real
  test container run.