朱子纯 / vibe-erp

feat(ref-plugin): printing-shop plug-in Tier 1 customization of core entities

The reference printing-shop plug-in now demonstrates the framework's
most important promise — that a customer plug-in can EXTEND core
business entities (Partner, SalesOrder, WorkOrder) with customer-
specific fields WITHOUT touching any core code.

Added to `printing-shop.yml` customFields section:

  Partner:
    printing_shop_customer_segment (enum: agency, in_house, end_client, reseller)

  SalesOrder:
    printing_shop_quote_number (string, maxLength 32)

  WorkOrder:
    printing_shop_press_id (string, maxLength 32)

Mechanism (no code changes, all metadata-driven):
  1. Plug-in YAML carries a `customFields:` section alongside its
     entities / permissions / menus.
  2. MetadataLoader.loadFromPluginJar reads the section and inserts
     rows into `metadata__custom_field` tagged
     `source='plugin:printing-shop'`.
  3. CustomFieldRegistry.refresh re-reads ALL rows (both `source='core'`
     and `source='plugin:*'`) and merges them by `targetEntity`.
  4. ExtJsonValidator.applyTo now validates incoming ext against the
     MERGED set, so a POST to /api/v1/partners/partners can include
     both core-declared (partners_industry) and plug-in-declared
     (printing_shop_customer_segment) fields in the same request,
     and both are enforced.
  5. Uninstalling the plug-in removes the plugin:printing-shop rows
     and the fields disappear from validation AND from the UI's
     custom-field catalog — no migration, no restart of anything
     other than the plug-in lifecycle itself.

Convention established: plug-in-contributed custom field keys are
prefixed with the plug-in id (e.g. `printing_shop_*`) so two
independent plug-ins can't collide on the same entity. Documented
inline in the YAML.

Smoke verified end-to-end against real Postgres with the plug-in
staged:
  - CustomFieldRegistry logs "refreshed 4 custom fields" after core
    load, then "refreshed 7 custom fields across 3 entities" after
    plug-in load — 4 core + 3 plug-in fields, merged.
  - GET /_meta/metadata/custom-fields/Partner returns 3 fields
    (2 core + 1 plug-in).
  - GET /_meta/metadata/custom-fields/SalesOrder returns 1 field
    (plug-in only).
  - GET /_meta/metadata/custom-fields/WorkOrder returns 3 fields
    (2 core + 1 plug-in).
  - POST /partners/partners with BOTH a core field AND a plug-in
    field → 201, canonical form persisted.
  - POST with an invalid plug-in enum value → 400 "ext.printing_shop_customer_segment:
    value 'ghost' is not in allowed set [agency, in_house, end_client, reseller]".
  - POST /orders/sales-orders with printing_shop_quote_number → 201,
    quote number round-trips.
  - POST /production/work-orders with mixed production_priority +
    printing_shop_press_id → 201, both fields persisted.

This is the first executable demonstration of Clean Core
extensibility (CLAUDE.md guardrail #7) — the plug-in extends
core-owned data through a stable public contract (api.v1 HasExt +
metadata__custom_field) without reaching into any core or platform
internal class. This is the "A" grade on the A/B/C/D extensibility
safety scale.

No code changes. No test changes. 246 unit tests, still green.