You need to sign in before continuing.
-
Removes the ext-handling copy/paste that had grown across four PBCs (partners, inventory, orders-sales, orders-purchase). Every service that wrote the JSONB `ext` column was manually doing the same four-step sequence: validate, null-check, serialize with a local ObjectMapper, assign to the entity. And every response mapper was doing the inverse: check-if-blank, parse, cast, swallow errors. Net: ~15 lines saved per PBC, one place to change the ext contract later (e.g. PII redaction, audit tagging, field-level events), and a stable plug-in opt-in mechanism — any plug-in entity that implements `HasExt` automatically participates. New api.v1 surface: interface HasExt { val extEntityName: String // key into metadata__custom_field var ext: String // the serialized JSONB column } Lives in `org.vibeerp.api.v1.entity` so plug-ins can opt their own entities into the same validation path. Zero Spring/Jackson dependencies — api.v1 stays clean. Extended `ExtJsonValidator` (platform-metadata) with two helpers: fun applyTo(entity: HasExt, ext: Map<String, Any?>?) — null-safe; validates; writes canonical JSON to entity.ext. Replaces the validate + writeValueAsString + assign triplet in every service's create() and update(). fun parseExt(entity: HasExt): Map<String, Any?> — returns empty map on blank/corrupt column; response mappers never 500 on bad data. Replaces the four identical parseExt local functions. ExtJsonValidator now takes an ObjectMapper via constructor injection (Spring Boot's auto-configured bean). Entities that now implement HasExt (override val extEntityName; override var ext; companion object const val ENTITY_NAME): - Partner (`partners.Partner` → "Partner") - Location (`inventory.Location` → "Location") - SalesOrder (`orders_sales.SalesOrder` → "SalesOrder") - PurchaseOrder (`orders_purchase.PurchaseOrder` → "PurchaseOrder") Deliberately NOT converted this chunk: - WorkOrder (pbc-production) — its ext column has no declared fields yet; a follow-up that adds declarations AND the HasExt implementation is cleaner than splitting the two. - JournalEntry (pbc-finance) — derived state, no ext column. Services lose: - The `jsonMapper: ObjectMapper = ObjectMapper().registerKotlinModule()` field (four copies eliminated) - The `parseExt(entity): Map` helper function (four copies) - The `companion object { const val ENTITY_NAME = ... }` constant (moved onto the entity where it belongs) - The `val canonicalExt = extValidator.validate(...)` + `.also { it.ext = jsonMapper.writeValueAsString(canonicalExt) }` create pattern (replaced with one applyTo call) - The `if (command.ext != null) { ... }` update pattern (applyTo is null-safe) Unit tests: 6 new cases on ExtJsonValidatorTest cover applyTo and parseExt (null-safe path, happy path, failure path, blank column, round-trip, malformed JSON). Existing service tests just swap the mock setup from stubbing `validate` to stubbing `applyTo` and `parseExt` with no-ops. Smoke verified end-to-end against real Postgres: - POST /partners with valid ext (partners_credit_limit, partners_industry) → 201, canonical form persisted. - GET /partners/by-code/X → 200, ext round-trips. - POST with invalid enum value → 400 "value 'x' is not in allowed set [printing, publishing, packaging, other]". - POST with undeclared key → 400 "ext contains undeclared key(s) for 'Partner': [rogue_field]". - PATCH with new ext → 200, ext updated. - PATCH WITHOUT ext field → 200, prior ext preserved (null-safe applyTo). - POST /orders/sales-orders with no ext → 201, the create path via the shared helper still works. 246 unit tests (+6 over 240), 18 Gradle subprojects.
-
The keystone of the framework's "key user adds fields without code" promise. A YAML declaration is now enough to add a typed custom field to an existing entity, validate it on every save, and surface it to the SPA / OpenAPI / AI agent. This is the bit that makes vibe_erp a *framework* instead of a fork-per-customer app. What landed ----------- * Extended `MetadataYamlFile` with a top-level `customFields:` section and `CustomFieldYaml` + `CustomFieldTypeYaml` wire-format DTOs. The YAML uses a flat `kind: decimal / scale: 2` discriminator instead of Jackson polymorphic deserialization so plug-in authors don't have to nest type configs and api.v1's `FieldType` stays free of Jackson imports. * `MetadataLoader.doLoad` now upserts `metadata__custom_field` rows alongside entities/permissions/menus, with the same delete-by-source idempotency. `LoadResult` carries the count for the boot log. * `CustomFieldRegistry` reads every `metadata__custom_field` row from the database and builds an in-memory `Map<entityName, List<CustomField>>` for the validator's hot path. `refresh()` is called by `VibeErpPluginManager` after the initial core load AND after every plug-in load, so a freshly-installed plug-in's custom fields are immediately enforceable. ConcurrentHashMap under the hood; reads are lock-free. * `ExtJsonValidator` is the on-save half: takes (entityName, ext map), walks the declared fields, coerces each value to its native type, and returns the canonicalised map (or throws IllegalArgumentException with ALL violations joined for a single 400). Per-FieldType rules: - String: maxLength enforced. - Integer: accepts Number and numeric String, rejects garbage. - Decimal: precision/scale enforced; preserved as plain string in canonical form so JSON encoding doesn't lose trailing zeros. - Boolean: accepts true/false (case-insensitive). - Date / DateTime: ISO-8601 parse via java.time. - Uuid: java.util.UUID parse. - Enum: must be in declared `allowedValues`. - Money / Quantity / Json / Reference: pass-through (Reference target existence check pending the cross-PBC EntityRegistry seam). Unknown ext keys are rejected with the entity's name and the keys themselves listed. ALL violations are returned in one response, not failing on the first, so a form submitter fixes everything in one round-trip. * `Partner` is the first PBC entity to wire ext through the validator: `CreatePartnerRequest` and `UpdatePartnerRequest` accept an `ext: Map<String, Any?>?`; `PartnerService.create/update` calls `extValidator.validate("Partner", ext)` and persists the canonical JSON to the existing `partners__partner.ext` JSONB column; `PartnerResponse` parses it back so callers see what they wrote. * `partners.yml` now declares two custom fields on Partner — `partners_credit_limit` (Decimal precision=14, scale=2) and `partners_industry` (Enum of printing/publishing/packaging/other) — with English and Chinese labels. Tagged `source=core` so the framework has something to demo from a fresh boot. * New public `GET /api/v1/_meta/metadata/custom-fields/{entityName}` endpoint serves the api.v1 runtime view of declarations from the in-memory registry (so it reflects every refresh) for the SPA's form builder, the OpenAPI generator, and the AI agent function catalog. The existing `GET /api/v1/_meta/metadata` endpoint also gained a `customFields` list. End-to-end smoke test --------------------- Reset Postgres, booted the app, verified: * Boot log: `CustomFieldRegistry: refreshed 2 custom fields across 1 entities (0 malformed rows skipped)` — twice (after core load and after plug-in load). * `GET /api/v1/_meta/metadata/custom-fields/Partner` → both declarations with their labels. * `POST /api/v1/partners/partners` with `ext = {credit_limit: "50000.00", industry: "printing"}` → 201; the response echoes the canonical map. * `POST` with `ext = {credit_limit: "1.234", industry: "unicycles", rogue: "x"}` → 400 with all THREE violations in one body: "ext contains undeclared key(s) for 'Partner': [rogue]; ext.partners_credit_limit: decimal scale 3 exceeds declared scale 2; ext.partners_industry: value 'unicycles' is not in allowed set [printing, publishing, packaging, other]". * `SELECT ext FROM partners__partner WHERE code = 'CUST-EXT-OK'` → `{"partners_industry": "printing", "partners_credit_limit": "50000.00"}` — the canonical JSON is in the JSONB column verbatim. * Regression: catalog uoms, identity users, partners list, and the printing-shop plug-in's POST /plates (with i18n via Accept-Language: zh-CN) all still HTTP 2xx. Build ----- * `./gradlew build`: 13 subprojects, 129 unit tests (was 118), all green. The 11 new tests cover each FieldType variant, multi-violation reporting, required missing rejection, unknown key rejection, and the null-value-dropped case. What was deferred ----------------- * JPA listener auto-validation. Right now PartnerService explicitly calls extValidator.validate(...) before save; Item, Uom, User and the plug-in tables don't yet. Promoting the validator to a JPA PrePersist/PreUpdate listener attached to a marker interface HasExt is the right next step but is its own focused chunk. * Reference target existence check. FieldType.Reference passes through unchanged because the cross-PBC EntityRegistry that would let the validator look up "does an instance with this id exist?" is a separate seam landing later. * The customization UI (Tier 1 self-service add a field via the SPA) is P3.3 — the runtime enforcement is done, the editor is not. * Custom-field-aware permissions. The `pii: true` flag is in the metadata but not yet read by anything; the DSAR/erasure pipeline that will consume it is post-v1.0. -
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.
