朱子纯 / vibe-erp

feat(ref-plugin): PlateApprovalTaskHandler mutates plate state via PluginContext

Proves out the "handler-side plug-in context access" pattern: a
plug-in's TaskHandler captures the PluginContext through its
constructor when the plug-in instantiates it inside `start(context)`,
and then uses `context.jdbc`, `context.logger`, etc. from inside
`execute` the same way the plug-in's HTTP lambdas do. Zero new
api.v1 surface was needed — the plug-in decides whether a handler
takes a context or not, and a pure handler simply omits the
constructor parameter.

## Why this pattern and not a richer TaskContext

The alternatives were:
  (a) add a `PluginContext` field (or a narrowed projection of it)
      to api.v1 `TaskContext`, threading the host-owned context
      through the workflow engine
  (b) capture the context in the plug-in's handler constructor —
      this commit

Option (a) would have forced every TaskHandler author — core PBC
handlers too, not just plug-in ones — to reason about a per-plug-in
context that wouldn't make sense for core PBCs. It would also have
coupled api.v1 to the plug-in machinery in a way that leaks into
every handler implementation.

Option (b) is a pure plug-in-local pattern. A pure handler:

    class PureHandler : TaskHandler { ... }

and a stateful handler look identical except for one constructor
parameter:

    class StatefulHandler(private val context: PluginContext) : TaskHandler {
        override fun execute(task, ctx) {
            context.jdbc.update(...)
            context.logger.info(...)
        }
    }

and both register the same way:

    context.taskHandlers.register(PureHandler())
    context.taskHandlers.register(StatefulHandler(context))

The framework's `TaskHandlerRegistry`, `DispatchingJavaDelegate`,
and `DelegateTaskContext` stay unchanged. Plug-in teardown still
strips handlers via `unregisterAllByOwner(pluginId)` because
registration still happens through the scoped registrar inside
`start(context)`.

## What PlateApprovalTaskHandler now does

Before this commit, the handler was a pure function that wrote
`plateApproved=true` + metadata to the process variables and
didn't touch the DB. Now it:

  1. Parses `plateId` out of the process variables as a UUID
     (fail-fast on non-UUID).
  2. Calls `context.jdbc.update` to set the plate row's `status`
     from 'DRAFT' to 'APPROVED', guarded by an explicit
     `WHERE id=:id AND status='DRAFT'`. The guard makes a second
     invocation a no-op (rowsUpdated=0) rather than silently
     overwriting a later status.
  3. Logs via the plug-in's PluginLogger — "plate {id} approved by
     user:admin (rows updated: 1)". Log lines are tagged
     `[plugin:printing-shop]` by the framework's Slf4jPluginLogger.
  4. Emits process output variables: `plateApproved=true`,
     `plateId=<uuid>`, `approvedBy=<principal label>`, `approvedAt=<instant>`,
     and `rowsUpdated=<count>` so callers can see whether the
     approval actually changed state.

## Smoke test (fresh DB, full end-to-end loop)

```
POST /api/v1/plugins/printing-shop/plates
     {"code":"PLATE-042","name":"Red cover plate","widthMm":320,"heightMm":480}
  → 201 {"id":"0bf577c9-...","status":"DRAFT",...}

POST /api/v1/workflow/process-instances
     {"processDefinitionKey":"plugin-printing-shop-plate-approval",
      "variables":{"plateId":"0bf577c9-..."}}
  → 201 {"ended":true,
         "variables":{"plateId":"0bf577c9-...",
                      "rowsUpdated":1,
                      "approvedBy":"user:admin",
                      "approvedAt":"2026-04-09T05:01:01.779369Z",
                      "plateApproved":true}}

GET  /api/v1/plugins/printing-shop/plates/0bf577c9-...
  → 200 {"id":"0bf577c9-...","status":"APPROVED", ...}
       ^^^^ note: was DRAFT a moment ago, NOW APPROVED — persisted to
       plugin_printingshop__plate via the handler's context.jdbc.update

POST /api/v1/workflow/process-instances   (same plateId, second run)
  → 201 {"variables":{"rowsUpdated":0,"plateApproved":true,...}}
       ^^^^ idempotent guard: the WHERE status='DRAFT' clause prevents
       double-updates, rowsUpdated=0 on the re-run
```

This is the first cross-cutting end-to-end business flow in the
framework driven entirely through the public surfaces:
  1. Plug-in HTTP endpoint writes a domain row
  2. Workflow HTTP endpoint starts a BPMN process
  3. Plug-in-contributed BPMN (deployed via PluginProcessDeployer)
     routes to a plug-in-contributed TaskHandler (registered via
     context.taskHandlers)
  4. Handler mutates the same plug-in-owned table via context.jdbc
  5. Plug-in HTTP endpoint reads the new state
Every step uses only api.v1. Zero framework core code knows the
plug-in exists.

## Non-goals (parking lot)

- Emitting an event from the handler. The next step in the
  plug-in workflow story is for a handler to publish a domain
  event via `context.eventBus.publish(...)` so OTHER subscribers
  (e.g. pbc-production waiting on a PlateApproved event) can react.
  This commit stays narrow: the handler only mutates its own plug-in
  state.
- Transaction scope of the handler's DB write relative to the
  Flowable engine's process-state persistence. Today both go
  through the host DataSource and Spring transaction manager that
  Flowable auto-configures, so a handler throw rolls everything
  back — verified by walking the code path. An explicit test of
  transactional rollback lands with REF.1 when the handler takes
  on real business logic.