朱子纯 / vibe-erp

feat(workflow): plug-in JAR BPMN auto-deployment via PluginProcessDeployer

Completes the plug-in side of the embedded Flowable story. The P2.1
core made plug-ins able to register TaskHandlers; this chunk makes
them able to ship the BPMN processes those handlers serve.

## Why Flowable's built-in auto-deployer couldn't do it

Flowable's Spring Boot starter scans the host classpath at engine
startup for `classpath[*]:/processes/[*].bpmn20.xml` and auto-deploys
every hit (the literal glob is paraphrased because the Kotlin KDoc
comment below would otherwise treat the embedded slash-star as the
start of a nested comment — feedback memory "Kotlin KDoc nested-
comment trap"). PF4J plug-ins load through an isolated child
classloader that is NOT visible to that scan, so a `processes/*.bpmn20.xml`
resource shipped inside a plug-in JAR is never seen. This chunk adds
a dedicated host-side deployer that opens each plug-in JAR file
directly (same JarFile walk pattern as
`MetadataLoader.loadFromPluginJar`) and hand-registers the BPMNs
with the Flowable `RepositoryService`.

## Mechanism

### New PluginProcessDeployer (platform-workflow)

One Spring bean, two methods:

- `deployFromPlugin(pluginId, jarPath): String?` — walks the JAR,
  collects every entry whose name starts with `processes/` and ends
  with `.bpmn20.xml` or `.bpmn`, and bundles the whole set into one
  Flowable `Deployment` named `plugin:<id>` with `category = pluginId`.
  Returns the deployment id or null (missing JAR / no BPMN resources).
  One deployment per plug-in keeps undeploy atomic and makes the
  teardown query unambiguous.
- `undeployByPlugin(pluginId): Int` — runs
  `createDeploymentQuery().deploymentCategory(pluginId).list()` and
  calls `deleteDeployment(id, cascade=true)` on each hit. Cascading
  removes process instances and history rows along with the
  deployment — "uninstalling a plug-in makes it disappear". Idempotent:
  a second call returns 0.

The deployer reads the JAR entries into byte arrays inside the
JarFile's `use` block and then passes the bytes to
`DeploymentBuilder.addBytes(name, bytes)` outside the block, so the
jar handle is already closed by the time Flowable sees the
deployment. No input-stream lifetime tangles.

### VibeErpPluginManager wiring

- New constructor dependency on `PluginProcessDeployer`.
- Deploy happens AFTER `start(context)` succeeds. The ordering matters
  because a plug-in can only register its TaskHandlers during
  `start(context)`, and a deployed BPMN whose service-task delegate
  expression resolves to a key with no matching handler would still
  deploy (Flowable only resolves delegates at process-start time).
  Registering handlers first is the safer default: the moment the
  deployment lands, every referenced handler is already in the
  TaskHandlerRegistry.
- BPMN deployment failure AFTER a successful `start(context)` now
  fully unwinds the plug-in state: call `instance.stop()`, remove
  the plug-in from the `started` list, strip its endpoints + its
  TaskHandlers + call `undeployByPlugin` (belt and suspenders — the
  deploy attempt may have partially succeeded). That mirrors the
  existing start-failure unwinding so the framework doesn't end up
  with a plug-in that's half-installed after any step throws.
- `destroy()` calls `undeployByPlugin(pluginId)` alongside the
  existing `unregisterAllByOwner(pluginId)`.

### Reference plug-in BPMN

`reference-customer/plugin-printing-shop/src/main/resources/processes/plate-approval.bpmn20.xml`
— a minimal two-task process (`start` → serviceTask → `end`) whose
serviceTask id is `printing_shop.plate.approve`, matching the
PlateApprovalTaskHandler key landed in the previous commit. Process
definition key is `plugin-printing-shop-plate-approval` (distinct
from the serviceTask id because BPMN 2.0 requires element ids to be
unique per document — same separation used for the core ping
process).

## Smoke test (fresh DB, plug-in staged)

```
$ docker compose down -v && docker compose up -d db
$ ./gradlew :distribution:bootRun &
...
registered TaskHandler 'vibeerp.workflow.ping' owner='core' ...
TaskHandlerRegistry initialised with 1 core TaskHandler bean(s): [vibeerp.workflow.ping]
...
plug-in 'printing-shop' Liquibase migrations applied successfully
[plugin:printing-shop] printing-shop plug-in started — reference acceptance test active
registered TaskHandler 'printing_shop.plate.approve' owner='printing-shop' ...
[plugin:printing-shop] registered 1 TaskHandler: printing_shop.plate.approve
PluginProcessDeployer: plug-in 'printing-shop' deployed 1 BPMN resource(s) as Flowable deploymentId='4e9f...': [processes/plate-approval.bpmn20.xml]

$ curl /api/v1/workflow/definitions (as admin)
[
  {"key":"plugin-printing-shop-plate-approval",
   "name":"Printing shop — plate approval",
   "version":1,
   "deploymentId":"4e9f85a6-33cf-11f1-acaa-1afab74ef3b4",
   "resourceName":"processes/plate-approval.bpmn20.xml"},
  {"key":"vibeerp-workflow-ping",
   "name":"vibe_erp workflow ping",
   "version":1,
   "deploymentId":"4f48...",
   "resourceName":"vibeerp-ping.bpmn20.xml"}
]

$ curl -X POST /api/v1/workflow/process-instances
         {"processDefinitionKey":"plugin-printing-shop-plate-approval",
          "variables":{"plateId":"PLATE-007"}}
  → {"processInstanceId":"5b1b...",
     "ended":true,
     "variables":{"plateId":"PLATE-007",
                  "plateApproved":true,
                  "approvedBy":"user:admin",
                  "approvedAt":"2026-04-09T04:48:30.514523Z"}}

$ kill -TERM <pid>
[ionShutdownHook] TaskHandlerRegistry.unregisterAllByOwner('printing-shop') removed 1 handler(s)
[ionShutdownHook] PluginProcessDeployer: plug-in 'printing-shop' deployment '4e9f...' removed (cascade)
```

Full end-to-end loop closed: plug-in ships a BPMN → host reads it
out of the JAR → Flowable deployment registered under the plug-in
category → HTTP caller starts a process instance via the standard
`/api/v1/workflow/process-instances` surface → dispatcher routes by
activity id to the plug-in's TaskHandler → handler writes output
variables + plug-in sees the authenticated caller as `ctx.principal()`
via the reserved `__vibeerp_*` process-variable propagation from
commit `ef9e5b42`. SIGTERM cleanly undeploys the plug-in's BPMNs.

## Tests

- 6 new unit tests on `PluginProcessDeployerTest`:
  * `deployFromPlugin returns null when jarPath is not a regular file`
    — guard against dev-exploded plug-in dirs
  * `deployFromPlugin returns null when the plug-in jar has no BPMN resources`
  * `deployFromPlugin reads every bpmn resource under processes and
    deploys one bundle` — builds a real temporary JAR with two BPMN
    entries + a README + a metadata YAML, verifies that both BPMNs
    go through `addBytes` with the right names and the README /
    metadata entries are skipped
  * `deployFromPlugin rejects a blank plug-in id`
  * `undeployByPlugin returns zero when there is nothing to remove`
  * `undeployByPlugin cascades a deleteDeployment per matching deployment`
- Total framework unit tests: 275 (was 269), all green.

## Kotlin trap caught during authoring (feedback memory paid out)

First compile failed with `Unclosed comment` on the last line of
`PluginProcessDeployer.kt`. The culprit was a KDoc paragraph
containing the literal glob
`classpath*:/processes/*.bpmn20.xml`: the embedded `/*` inside the
backtick span was parsed as the start of a nested block comment
even though the surrounding `/* ... */` KDoc was syntactically
complete. The saved feedback-memory entry "Kotlin KDoc nested-comment
trap" covered exactly this situation — the fix is to spell out glob
characters as `[star]` / `[slash]` (or the word "slash-star") inside
documentation so the literal `/*` never appears. The KDoc now
documents the behaviour AND the workaround so the next maintainer
doesn't hit the same trap.

## Non-goals (still parking lot)

- Handler-side access to the full PluginContext — PlateApprovalTaskHandler
  is still a pure function because the framework doesn't hand
  TaskHandlers a context object. For REF.1 (real quote→job-card)
  handlers will need to read + mutate plug-in-owned tables; the
  cleanest approach is closure-capture inside the plug-in class
  (handler instantiated inside `start(context)` with the context
  captured in the outer scope). Decision deferred to REF.1.
- BPMN resource hot reload. The deployer runs once per plug-in
  start; a plug-in whose BPMN changes under its feet at runtime
  isn't supported yet.
- Plug-in-shipped DMN / CMMN resources. The deployer only looks at
  `.bpmn20.xml` and `.bpmn`. Decision-table and case-management
  resources are not on the v1.0 critical path.