朱子纯 / vibe-erp-v0

Completes the HasExt rollout across every core entity with an ext
column. Item was the last one that carried an ext JSONB column
without any validation wired — a plug-in could declare custom fields
for Item but nothing would enforce them on save. This fixes that and
restores two printing-shop-specific Item fields to the reference
plug-in that were temporarily dropped from the previous Tier 1
customization chunk (commit 16c59310) precisely because Item wasn't
wired.

Code changes:
  - Item implements HasExt; `ext` becomes `override var ext`, a
    companion constant holds the entity name "Item".
  - ItemService injects ExtJsonValidator, calls applyTo() in both
    create() and update() (create + update symmetry like partners
    and locations). parseExt passthrough added for response mappers.
  - CreateItemCommand, UpdateItemCommand, CreateItemRequest,
    UpdateItemRequest gain a nullable ext field.
  - ItemResponse now carries the parsed ext map, same shape as
    PartnerResponse / LocationResponse / SalesOrderResponse.
  - pbc-catalog build.gradle adds
    `implementation(project(":platform:platform-metadata"))`.
  - ItemServiceTest constructor updated to pass the new validator
    dependency with no-op stubs.

Plug-in YAML (printing-shop.yml):
  - Re-added `printing_shop_color_count` (integer) and
    `printing_shop_paper_gsm` (integer) custom fields targeting Item.
    These were originally in the commit 16c59310 draft but removed
    because Item wasn't wired. Now that Item is wired, they're back
    and actually enforced.

Smoke verified end-to-end against real Postgres with the plug-in
staged:
  - GET /_meta/metadata/custom-fields/Item returns 2 plug-in fields.
  - POST /catalog/items with `{printing_shop_color_count: 4,
    printing_shop_paper_gsm: 170}` → 201, canonical form persisted.
  - GET roundtrip preserves both integer values.
  - POST with `printing_shop_color_count: "not-a-number"` → 400
    "ext.printing_shop_color_count: not a valid integer: 'not-a-number'".
  - POST with `rogue_key` → 400 "ext contains undeclared key(s)
    for 'Item': [rogue_key]".

Six of eight PBCs now participate in HasExt:
  Partner, Location, SalesOrder, PurchaseOrder, WorkOrder, Item.
The remaining two are pbc-identity (User has no ext column by
design — identity is a security concern, not a customization one)
and pbc-finance (JournalEntry is derived state from events, no
customization surface).

Five core entities carry Tier 1 custom fields as of this commit:
  Partner     (2 core + 1 plug-in)
  Item        (0 core + 2 plug-in)
  SalesOrder  (0 core + 1 plug-in)
  WorkOrder   (2 core + 1 plug-in)
  Location    (0 core + 0 plug-in — wired but no declarations yet)

246 unit tests, all green. 18 Gradle subprojects.

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.

Adds the foundation for the entire Tier 1 customization story. Core
PBCs and plug-ins now ship YAML files declaring their entities,
permissions, and menus; a `MetadataLoader` walks the host classpath
and each plug-in JAR at boot, upserts the rows tagged with their
source, and exposes them at a public REST endpoint so the future
SPA, AI-agent function catalog, OpenAPI generator, and external
introspection tooling can all see what the framework offers without
scraping code.

What landed:

* New `platform/platform-metadata/` Gradle subproject. Depends on
  api-v1 + platform-persistence + jackson-yaml + spring-jdbc.

* `MetadataYamlFile` DTOs (entities, permissions, menus). Forward-
  compatible: unknown top-level keys are ignored, so a future plug-in
  built against a newer schema (forms, workflows, rules, translations)
  loads cleanly on an older host that doesn't know those sections yet.

* `MetadataLoader` with two entry points:

    loadCore() — uses Spring's PathMatchingResourcePatternResolver
      against the host classloader. Finds every classpath*:META-INF/
      vibe-erp/metadata/*.yml across all jars contributing to the
      application. Tagged source='core'.

    loadFromPluginJar(pluginId, jarPath) — opens ONE specific
      plug-in JAR via java.util.jar.JarFile and walks its entries
      directly. This is critical: a plug-in's PluginClassLoader is
      parent-first, so a classpath*: scan against it would ALSO
      pick up the host's metadata files via parent classpath. We
      saw this in the first smoke run — the plug-in source ended
      up with 6 entities (the plug-in's 2 + the host's 4) before
      the fix. Walking the JAR file directly guarantees only the
      plug-in's own files load. Tagged source='plugin:<id>'.

  Both entry points use the same delete-then-insert idempotent core
  (doLoad). Loading the same source twice produces the same final
  state. User-edited metadata (source='user') is NEVER touched by
  either path — it survives boot, plug-in install, and plug-in
  upgrade. This is what lets a future SPA "Customize" UI add custom
  fields without fearing they'll be wiped on the next deploy.

* `VibeErpPluginManager.afterPropertiesSet()` now calls
  metadataLoader.loadCore() at the very start, then walks plug-ins
  and calls loadFromPluginJar(...) for each one between Liquibase
  migration and start(context). Order is guaranteed: core → linter
  → migrate → metadata → start. The CommandLineRunner I originally
  put `loadCore()` in turned out to be wrong because Spring runs
  CommandLineRunners AFTER InitializingBean.afterPropertiesSet(),
  so the plug-in metadata was loading BEFORE core — the wrong way
  around. Calling loadCore() inline in the plug-in manager fixes
  the ordering without any @Order(...) gymnastics.

* `MetadataController` exposes:
    GET /api/v1/_meta/metadata           — all three sections
    GET /api/v1/_meta/metadata/entities  — entities only
    GET /api/v1/_meta/metadata/permissions
    GET /api/v1/_meta/metadata/menus
  Public allowlist (covered by the existing /api/v1/_meta/** rule
  in SecurityConfiguration). The metadata is intentionally non-
  sensitive — entity names, permission keys, menu paths. Nothing
  in here is PII or secret; the SPA needs to read it before the
  user has logged in.

* YAML files shipped:
  - pbc-identity/META-INF/vibe-erp/metadata/identity.yml
    (User + Role entities, 6 permissions, Users + Roles menus)
  - pbc-catalog/META-INF/vibe-erp/metadata/catalog.yml
    (Item + Uom entities, 7 permissions, Items + UoMs menus)
  - reference plug-in/META-INF/vibe-erp/metadata/printing-shop.yml
    (Plate + InkRecipe entities, 5 permissions, Plates + Inks menus
    in a "Printing shop" section)

Tests: 4 MetadataLoaderTest cases (loadFromPluginJar happy paths,
mixed sections, blank pluginId rejection, missing-file no-op wipe)
+ 7 MetadataYamlParseTest cases (DTO mapping, optional fields,
section defaults, forward-compat unknown keys). Total now
**92 unit tests** across 11 modules, all green.

End-to-end smoke test against fresh Postgres + plug-in loaded:

  Boot logs:
    MetadataLoader: source='core' loaded 4 entities, 13 permissions,
      4 menus from 2 file(s)
    MetadataLoader: source='plugin:printing-shop' loaded 2 entities,
      5 permissions, 2 menus from 1 file(s)

  HTTP smoke (everything green):
    GET /api/v1/_meta/metadata (no auth)              → 200
      6 entities, 18 permissions, 6 menus
      entity names: User, Role, Item, Uom, Plate, InkRecipe
      menu sections: Catalog, Printing shop, System
    GET /api/v1/_meta/metadata/entities                → 200
    GET /api/v1/_meta/metadata/menus                   → 200

  Direct DB verification:
    metadata__entity:    core=4, plugin:printing-shop=2
    metadata__permission: core=13, plugin:printing-shop=5
    metadata__menu:      core=4, plugin:printing-shop=2

  Idempotency: restart the app, identical row counts.

  Existing endpoints regression:
    GET /api/v1/identity/users (Bearer)               → 1 user
    GET /api/v1/catalog/uoms (Bearer)                  → 15 UoMs
    GET /api/v1/plugins/printing-shop/ping (Bearer)    → 200

Bugs caught and fixed during the smoke test:

  • The first attempt loaded core metadata via a CommandLineRunner
    annotated @Order(HIGHEST_PRECEDENCE) and per-plug-in metadata
    inline in VibeErpPluginManager.afterPropertiesSet(). Spring
    runs all InitializingBeans BEFORE any CommandLineRunner, so
    the plug-in metadata loaded first and the core load came
    second — wrong order. Fix: drop CoreMetadataInitializer
    entirely; have the plug-in manager call metadataLoader.loadCore()
    directly at the start of afterPropertiesSet().

  • The first attempt's plug-in load used
    metadataLoader.load(pluginClassLoader, ...) which used Spring's
    PathMatchingResourcePatternResolver against the plug-in's
    classloader. PluginClassLoader is parent-first, so the resolver
    enumerated BOTH the plug-in's own JAR AND the host classpath's
    metadata files, tagging core entities as source='plugin:<id>'
    and corrupting the seed counts. Fix: refactor MetadataLoader
    to expose loadFromPluginJar(pluginId, jarPath) which opens
    the plug-in JAR directly via java.util.jar.JarFile and walks
    its entries — never asking the classloader at all. The
    api-v1 surface didn't change.

  • Two KDoc comments contained the literal string `*.yml` after
    a `/` character (`/metadata/*.yml`), forming the `/*` pattern
    that Kotlin's lexer treats as a nested-comment opener. The
    file failed to compile with "Unclosed comment". This is the
    third time I've hit this trap; rewriting both KDocs to avoid
    the literal `/*` sequence.

  • The MetadataLoaderTest's hand-rolled JAR builder didn't include
    explicit directory entries for parent paths. Real Gradle JARs
    do include them, and Spring's PathMatchingResourcePatternResolver
    needs them to enumerate via classpath*:. Fixed the test helper
    to write directory entries for every parent of each file.

Implementation plan refreshed: P1.5 marked DONE. Next priority
candidates: P5.2 (pbc-partners — third PBC clone) and P3.4 (custom
field application via the ext jsonb column, which would unlock the
full Tier 1 customization story).

Framework state: 17→18 commits, 10→11 modules, 81→92 unit tests,
metadata seeded for 6 entities + 18 permissions + 6 menus.