朱子纯 / vibe-erp

2026-04-07-vibe-erp-implementation-plan.md 26.3 KB

vibe_erp — Implementation Plan (post-v0.1)

Status: Approved roadmap. v0.1 skeleton is built, tested end-to-end against a real Postgres, and pushed. This document is the source of truth for the work that turns v0.1 into v1.0. Date: 2026-04-07 Companion document: Architecture spec

2026-04-07 update — single-tenant refactor. vibe_erp is now deliberately single-tenant per instance: one running process serves exactly one company against an isolated Postgres database. All multi-tenancy work has been removed from the framework — no tenant_id columns, no Hibernate tenant filter, no Postgres Row-Level Security policies, no TenantContext. The previously-deferred P1.1 (RLS transaction hook) and H1 (per-region tenant routing) units are gone. See CLAUDE.md guardrail #5 for the rationale.

2026-04-08 update — P4.1, P5.1, P1.3, P1.7, P1.4, P1.2 all landed. Auth (Argon2id + JWT + bootstrap admin), pbc-catalog (items + UoMs), plug-in HTTP endpoints (registry + dispatcher + DefaultPluginContext), event bus + transactional outbox + audit subscriber, plug-in-owned Liquibase changelogs (the reference plug-in now has its own database tables), and the plug-in linter (ASM bytecode scan rejecting forbidden imports) are all done and smoke-tested end-to-end. The reference printing-shop plug-in has graduated from "hello world" to a real customer demonstration: it owns its own DB schema, CRUDs plates and ink recipes via REST through context.jdbc, and would be rejected at install time if it tried to import internal framework classes. The framework is now at 81 unit tests across 10 modules, all green.

What v0.1 actually delivers (verified on a running app)

Item Status
Gradle multi-project, 7 subprojects ✅ Builds end-to-end
api/api-v1 — public plug-in contract ✅ Compiles, 12 unit tests
platform/platform-bootstrap — Spring Boot main, properties, @EnableJpaRepositories, GlobalExceptionHandler ✅
platform/platform-persistence — JPA, audit listener (no tenant scaffolding) ✅
platform/platform-plugins — PF4J host, lifecycle ✅
pbc/pbc-identity — User entity end-to-end ✅ Compiles, 6 unit tests, smoke-tested via REST against real Postgres
reference-customer/plugin-printing-shop — hello-world PF4J plug-in ✅ Compiles, packs into a real PF4J JAR
distribution — Spring Boot fat jar (vibe-erp.jar) ✅ bootJar succeeds, bootRun boots cleanly in dev profile
Liquibase changelogs (platform init + identity init) ✅ Run cleanly against fresh Postgres
Dockerfile, docker-compose.yaml, Makefile ✅ Present; docker compose up -d db verified
GitHub Actions workflows ✅ Present, running in CI on every push to https://github.com/reporkey/vibe-erp
Architecture-rule enforcement in build.gradle.kts ✅ Active — fails on cross-PBC deps, on plug-ins importing internals, and on PBCs depending on platform-bootstrap
README, CONTRIBUTING, LICENSE, 8 docs guides ✅
Architecture spec + this implementation plan ✅
End-to-end smoke test against real Postgres ✅ POST/GET/PATCH/DELETE on /api/v1/identity/users; duplicate-username → 400; bogus id → 404; disable flow works

What v0.1 explicitly does NOT deliver:

  • The 9 other core PBCs (catalog, partners, inventory, warehousing, orders-sales, orders-purchase, production, quality, finance)
  • The metadata store machinery (custom-field application, form designer, list views, rules engine)
  • Embedded Flowable workflow engine
  • ICU4J Translator implementation
  • JasperReports
  • Real authentication (anonymous access; the bootstrap admin lands in P4.1)
  • React web SPA
  • Plug-in linter (rejecting reflection into platform internals at install time)
  • Plug-in Liquibase application
  • Per-plug-in Spring child context
  • MCP server
  • Mobile app (v2 anyway)

The architecture accommodates all of these — the seams are in api.v1 already — they just aren't implemented.

How to read this plan

Each work unit is sized to be a single coherent implementation pass: roughly 1–5 days of work, one developer, one PR. Units are grouped by theme, ordered roughly by dependency, but parallelizable wherever the prerequisites are satisfied.

Each unit names:

  • the Gradle modules it touches (or creates)
  • the api.v1 surface it consumes (and never modifies, unless explicitly noted)
  • the acceptance test that proves it landed correctly
  • any upstream dependencies that must complete first

The 11 architecture guardrails in CLAUDE.md and the 14-section design in 2026-04-07-vibe-erp-architecture-design.md apply to every unit. This document does not restate them.

Phase 1 — Platform completion (the foundation everything else needs)

These units finish the platform layer so PBCs can be implemented without inventing scaffolding.

✅ P1.2 — Plug-in linter (DONE 2026-04-08)

Module: platform-plugins What landed: ASM-based bytecode scanner that walks every .class entry in a plug-in JAR, checks every type/method/field reference for forbidden internal package prefixes (org/vibeerp/platform/, org/vibeerp/pbc/), and rejects the plug-in at install time with a per-class violation report. Wired into VibeErpPluginManager.afterPropertiesSet() between PF4J's loadPlugins() and startPlugins(). 5 unit tests with synthesized in-memory JARs cover clean plug-ins, forbidden platform refs, forbidden pbc refs, allowed api.v1 refs, and multiple violations being reported together.

✅ P1.3 — Plug-in lifecycle: HTTP endpoints (DONE 2026-04-07, v0.5)

Module: platform-plugins + api.v1 What landed (v0.5 cut): Real Plugin.start(context) lifecycle. DefaultPluginContext provides a real PluginLogger (SLF4J + per-plugin tag), a real EventBus (P1.7), real PluginEndpointRegistrar, and real PluginJdbc (P1.4). Single Spring @RestController PluginEndpointDispatcher at /api/v1/plugins/{pluginId}/** dispatches via PluginEndpointRegistry (Spring AntPathMatcher for {var} extraction). Reference plug-in registers 7 endpoints. Deferred: per-plug-in Spring child contexts — v0.6 instantiates the plug-in via PF4J's classloader without its own Spring context. Auto-scoping subscriptions on plug-in stop is also deferred.

✅ P1.4 — Plug-in Liquibase application (DONE 2026-04-08)

Module: platform-plugins + api.v1 (added PluginJdbc/PluginRow) What landed: PluginLiquibaseRunner looks for META-INF/vibe-erp/db/changelog.xml inside the plug-in JAR via the PF4J classloader, applies it via Liquibase against the host's shared DataSource. Convention: tables use plugin_<id>__* prefix (linter will enforce in a future version). The reference printing-shop plug-in now has two real tables (plugin_printingshop__plate, plugin_printingshop__ink_recipe) and CRUDs them via REST through the new context.jdbc typed-SQL surface in api.v1. Plug-ins never see Spring's JdbcTemplate. Deferred: per-plug-in datasource isolation, table-prefix linter, rollback on uninstall.

P1.5 — Metadata store seeding

Module: new platform-metadata module (or expand platform-persistence) Depends on: — What: A MetadataLoader Spring component that, on boot and on plug-in start, upserts rows into metadata__entity, metadata__form, metadata__workflow, etc. from YAML files in the classpath / plug-in JAR. Each row carries source = 'core' | 'plugin:<id>' | 'user'. Idempotent; safe to run on every boot. Acceptance: integration test confirms that booting twice doesn't duplicate rows; uninstalling a plug-in removes its source = 'plugin:<id>' rows; user-edited rows (source = 'user') are never touched.

P1.6 — Translator implementation backed by ICU4J

Module: new platform-i18n module Depends on: P1.5 (so plug-in message bundles can be loaded as part of metadata) What: Implement org.vibeerp.api.v1.i18n.Translator using ICU4J MessageFormat with locale fallback. Resolve message bundles in this order: metadata__translation (operator overrides) → plug-in i18n/messages_<locale>.properties → core i18n/messages_<locale>.properties → fallback locale. Acceptance: unit tests covering plurals, gender, number formatting in en-US, zh-CN, de-DE, ja-JP, es-ES; a test that an operator override beats a plug-in default beats a core default.

✅ P1.7 — Event bus + outbox (DONE 2026-04-08)

Module: new platform-events module What landed: Real EventBus implementation with the transactional outbox pattern. publish() writes the event row to platform__event_outbox AND synchronously delivers to in-process subscribers in the SAME database transaction (Propagation.MANDATORY so the bus refuses to publish outside a transaction). OutboxPoller (@Scheduled every 5s, pessimistic SELECT FOR UPDATE) drains PENDING / FAILED rows and marks them DISPATCHED. ListenerRegistry indexes by both class and topic string, supports a ** wildcard. EventAuditLogSubscriber logs every event as the v0.6 demo subscriber. pbc-identity publishes UserCreatedEvent after UserService.create(). 13 unit tests + verified end-to-end against Postgres: created users produce outbox rows that flip from PENDING to DISPATCHED inside one poller cycle. Deferred: external dispatcher (Kafka/NATS bridge), exponential backoff, dead-letter queue, async publish.

P1.8 — JasperReports integration

Module: new platform-reporting module Depends on: P1.5 What: Wrap JasperReports compilation/rendering behind a ReportRenderer Spring component. Reports live in metadata__report (path or content). API exposes /api/v1/_meta/reports/{id}.pdf?param=... for synchronous rendering, with a job-based async path for big reports. Acceptance: ship one core report (a User list) and confirm it renders to PDF with the correct locale-aware date and number formatting.

P1.9 — File store (local + S3)

Module: new platform-files module Depends on: — What: A FileStore interface with LocalFileStore and S3FileStore implementations, configured via vibeerp.files.backend. Files are stored under a flat key namespace — there is exactly one company per instance, so no per-tenant prefixing is needed. Acceptance: unit tests for both backends; integration test with MinIO Testcontainer for S3.

P1.10 — Job scheduler

Module: new platform-jobs module Depends on: — What: Quartz integration with the JDBCJobStore against the same Postgres. PBCs and plug-ins register jobs through a typed JobScheduler API in api.v1 (already has the seam, may need a tiny addition). Each job runs inside a PrincipalContext.runAs(systemPrincipal) block so audit columns get a sensible value instead of inheriting whatever the trigger thread had. Acceptance: a recurring core job that prunes the audit log; integration test confirms the job runs with the expected system principal in audit columns.

Phase 2 — Embedded workflow engine

P2.1 — Embedded Flowable

Module: new platform-workflow module Depends on: P1.5 (metadata), P1.6 (i18n for task names), P1.7 (events) What: Pull in flowable-spring-boot-starter. Configure Flowable to use the same Postgres datasource (so its tables live alongside ours, prefixed flowable_*). Wire org.vibeerp.api.v1.workflow.TaskHandler implementations registered by plug-ins as Flowable JavaDelegates. Workflows are deployed from metadata__workflow rows (BPMN XML payload) on boot and on plug-in load. Acceptance: the reference printing-shop plug-in registers a "quote-to-job-card" TaskHandler; a BPMN process that calls it can be started via REST and returns the expected output.

P2.2 — BPMN designer integration (web)

Module: the future React SPA Depends on: P2.1, R1 (web bootstrap) What: Embed bpmn-js (Camunda's BPMN modeler) in a "Workflow Designer" page. Save as a metadata__workflow row; deploy through the Tier 1 path. Acceptance: end-to-end test where a Tier 1 user creates a workflow in the browser and starts an instance of it.

P2.3 — User task / form rendering

Module: platform-workflow + future React SPA Depends on: P2.1, P3.3 (form designer), R1 What: When a Flowable user task fires, look up the form id from the task definition, render it via the form renderer (P3.x), capture the user's input, and complete the task. Acceptance: end-to-end test of an approval workflow where a human clicks a button.

Phase 3 — Metadata store: forms and rules (the Tier 1 user journeys)

P3.1 — JSON Schema form renderer (server)

Module: new platform-forms module Depends on: P1.5 What: A FormRenderer that, given an entity instance and a FormSchema, returns a server-side JSON describing what to render. The actual rendering happens in the SPA (P3.2). The server-side piece is needed for non-browser clients (CLI, integration tests, AI agents). Acceptance: snapshot tests of the rendered JSON for a User form with an added custom field.

P3.2 — Form renderer (web)

Module: future React SPA Depends on: P3.1, R1 What: A React component that consumes JSON Schema + UI Schema and renders an interactive form. Use react-jsonschema-form as the base, customize the widget set for vibe_erp's design language. Acceptance: Storybook for every widget type; e2e test that filling and submitting a form persists the data.

P3.3 — Form designer (web)

Module: future React SPA Depends on: P3.2 What: A drag-and-drop designer that produces JSON Schema + UI Schema and saves into metadata__form. This is the Tier 1 entry point for "add a field, change a layout". Acceptance: e2e test where a Tier 1 user adds a "Customer PO Reference" field to the Sales Order form without writing code.

P3.4 — Custom field application

Module: platform-metadata Depends on: P1.5 What: A Hibernate interceptor (or JPA listener) that reads the entity's metadata__custom_field rows on save and validates the JSON in the ext column against them — required, type, max length, etc. Validation errors come back as 422 with a per-field map. Acceptance: integration test that a User with a missing required custom field cannot be saved; one with a valid one round-trips.

P3.5 — Rules engine (simple "if X then Y")

Module: new platform-rules module Depends on: P1.7 (events) What: Listen to DomainEvents, evaluate metadata__rule rows scoped to that event type, run the configured action (send email, set field, call workflow, publish another event). Use a simple expression language (Spring SpEL — already on the classpath). Acceptance: integration test where a rule "on UserCreated, set ext.greeting = 'Welcome'" actually fires.

P3.6 — List view designer (web)

Module: future React SPA Depends on: R1 What: A grid component backed by metadata__list_view rows. Operators pick columns, filters, sort, save as a named list view. Acceptance: e2e test where a user creates a "Active customers in Germany" list view and re-opens it later.

Phase 4 — Authentication and authorization (PROMOTED to next priority)

Promoted from "after the platform layer" to "do this next." With the single-tenant refactor, there is no second wall protecting data. Auth is the only security. Until P4.1 lands, vibe_erp is only safe to run on localhost.

✅ P4.1 — Built-in JWT auth (DONE 2026-04-07)

Module: pbc-identity (extended) + new platform-security module What landed: Username/password login backed by identity__user_credential (separate table). Argon2id via Spring Security's Argon2PasswordEncoder. HMAC-SHA256 JWTs with sub/username/iss/iat/exp/type. JwtIssuer mints, JwtVerifier decodes back to a typed DecodedToken. PrincipalContext (ThreadLocal) bridges Spring Security → audit listener so created_by/updated_by carry real user UUIDs. BootstrapAdminInitializer creates admin with a random 16-char password printed to logs on first boot of an empty identity__user. Spring Security filter chain in platform-security makes everything except /actuator/health, /api/v1/_meta/**, /api/v1/auth/login, /api/v1/auth/refresh require a valid Bearer token. GlobalExceptionHandler maps AuthenticationFailedException → 401 RFC 7807. 38 unit tests + 10 end-to-end smoke assertions all green.

P4.2 — OIDC integration

Module: pbc-identity Depends on: P4.1 What: Plug Spring Security's OIDC client into the same Principal resolution. Configurable per instance (not per tenant — vibe_erp is single-tenant): which provider, which client id, which claim is the username. Keycloak is the smoke-test target. Acceptance: Keycloak Testcontainer + integration test of a full OIDC code flow; the same UserController endpoints work without changes.

P4.3 — Permission checking (real)

Module: platform-security Depends on: P4.1 What: Implement org.vibeerp.api.v1.security.PermissionCheck. Resolve permissions from metadata__role_permission rows for the current Principal's roles. Plug-ins register their own permissions via @Extension(point = PermissionRegistrar::class) (api.v1 may need a tiny addition here — deliberate, with a minor version bump). Acceptance: integration test that a user without identity.user.create gets 403 from POST /api/v1/identity/users; with the role, 201.

Phase 5 — Core PBCs (the meat of the framework)

Each PBC follows the same 7-step recipe:

  1. Create the Gradle subproject under pbc/
  2. Domain entities (extending AuditedJpaEntity, with ext jsonb)
  3. Spring Data JPA repositories
  4. Application services
  5. REST controllers under /api/v1/<pbc>/<resource>
  6. Liquibase changelog (db/changelog/<pbc>/) with rollback blocks
  7. Cross-PBC facade in api.v1.ext.<pbc> + adapter in the PBC

No tenant_id columns. No RLS policies. vibe_erp is single-tenant per instance — everything in the database belongs to the one company that owns the instance.

✅ P5.1 — pbc-catalog — items, units of measure (DONE 2026-04-08)

Uom and Item entities + JpaRepositories + Services (with cross-PBC validation: ItemService rejects unknown UoM codes) + REST controllers under /api/v1/catalog/uoms and /api/v1/catalog/items + CatalogApi facade in api.v1.ext + CatalogApiAdapter (filters inactive items at the boundary). Liquibase seeds 15 canonical UoMs at first boot (kg/g/t, m/cm/mm/km, m2, l/ml, ea/sheet/pack, h/min). 11 unit tests + end-to-end smoke. Pricing and configurable products are deferred to P5.10.

P5.2 — pbc-partners — customers, suppliers, contacts

Companies, addresses, contacts, contact channels. PII-tagged from day one (CLAUDE.md guardrail #6 / DSAR).

P5.3 — pbc-inventory — stock items, lots, locations, movements

Movements as immutable events; on-hand quantity is a projection. Locations are hierarchical.

P5.4 — pbc-warehousing — receipts, picks, transfers, counts

Built on top of inventory via api.v1.ext.inventory. The first PBC that proves the cross-PBC dependency rule under load.

P5.5 — pbc-orders-sales — quotes, sales orders, deliveries

Workflow-heavy. The reference printing-shop plug-in's quote-to-job-card flow exercises this.

P5.6 — pbc-orders-purchase — RFQs, POs, receipts

Mirror image of sales. Shares the document/approval pattern.

P5.7 — pbc-production (basic) — work orders, routings, operations

Generic discrete-manufacturing primitives. NOT printing-specific.

P5.8 — pbc-quality (basic) — inspection plans, results, holds

Generic; the printing-specific QC steps live in the plug-in.

P5.9 — pbc-finance (basic) — GL, journal entries, AR/AP minimal

Basic double-entry. Tax engines, multi-currency revaluation, consolidation are v1.2+.

P5.10 — pbc-catalog — pricing, configurable products

Defer until P5.5 (orders-sales) is real, since pricing only matters when orders exist.

Phase 6 — Web SPA

R1 — React + TypeScript bootstrap

Module: new web/ directory (Vite + React + TS) Depends on: P4.1 (need a way to log in) What: Vite scaffold, design system (likely Mantine or Radix), routing (React Router), data fetching (TanStack Query), generated TypeScript client from the backend's OpenAPI spec. Acceptance: can log in, see a list of users, log out.

R2 — Identity screens

Depends on: R1 What: User list, user detail, role list, role detail, permission editor.

R3 — Customize / metadata UIs

Depends on: R1, P3.3, P3.6 What: The Tier 1 entry point. Form designer, list view designer, custom field designer, workflow designer.

R4 — One screen per core PBC

Depends on: R1, the matching PBC from Phase 5 What: Per-PBC list / detail / create / edit screens. Generated from metadata wherever possible; hand-built where the metadata-driven approach falls short (and those gaps become future enhancements to the metadata store).

Phase 7 — Reference plug-in (the executable acceptance test)

REF.1 — Real workflow handler

Module: reference-customer/plugin-printing-shop Depends on: P2.1 (Flowable) What: Replace the v0.1 hello-world with a real TaskHandler that converts a Quote into a JobCard, registered as acme.printingshop.quoteToJobCard. A BPMN file in the plug-in JAR drives a workflow that calls this handler. Acceptance: integration test starts the workflow with a real Quote and asserts the JobCard appears.

REF.2 — Plate / ink / press domain

Module: same plug-in Depends on: P1.4 (plug-in Liquibase application) What: The plug-in defines its own entities (plugin_printingshop__plate, plugin_printingshop__ink_recipe, plugin_printingshop__press) via its own Liquibase changelog. It registers REST endpoints for them via @PluginEndpoint. It registers permissions like printingshop.plate.approve. Acceptance: integration test that a printing-shop user can CRUD plates against /api/v1/plugins/printing-shop/plates.

REF.3 — Real reference forms and metadata

Module: same plug-in Depends on: P3.3, P3.4 What: The plug-in ships YAML metadata for: a custom field on Sales Order ("printing job type"), a custom form for plate approval, an automation rule "on plate approved, dispatch to press". All loaded at plug-in start, all tagged source = 'plugin:printing-shop'. Acceptance: end-to-end smoke test that loads the plug-in into a fresh instance and exercises the full quote-to-job-card-to-press flow without any code changes outside the plug-in.

Phase 8 — Hosted operations, AI agents, mobile (post-v1.0)

H1 — Instance provisioning console (hosted)

What: A separate operator console that, given a "create customer" request, provisions a fresh vibe_erp instance: spin up a dedicated Postgres database, deploy a vibe_erp container pointed at it, register DNS, hand the customer their bootstrap admin credentials. The vibe_erp framework itself is not changed for this — provisioning is a layer on top of the framework. Each customer gets their own process, their own database, their own backups, their own upgrade cadence. Acceptance: can provision and tear down a customer instance via a single CLI command.

A1 — MCP server

Module: new platform-mcp Depends on: every PBC, every endpoint having a typed OpenAPI definition What: Expose every REST endpoint as an MCP function. Permission-checked, locale-aware. A Tier 2 plug-in can register additional MCP functions via a new @McpFunction annotation in api.v1 (an additive change, minor version bump). Acceptance: an LLM-driven agent can call vibe_erp.identity.users.create and the result is identical to a REST call.

M1 — React Native skeleton

Shared TypeScript types with the web SPA; first screens cover shop-floor scanning and approvals.

Tracking and ordering

A coarse dependency view (after the single-tenant refactor):

P4.1 — auth (PROMOTED) ─────────┐
P1.5 — metadata seed ──┐ ──┐    │
P1.6 — translator ──── (depends on P1.5)
P1.7 — events ─────────┘   │
P1.2 — linter ──┐
P1.3 — child ctx ┘
P1.4 — plug-in liquibase ── depends on P1.3
P1.8 — reports ── depends on P1.5
P1.9 — files
P1.10 — jobs
P2.1 — Flowable ── depends on P1.5, P1.6, P1.7
P3.x — metadata Tier 1 ── depends on P1.5
P5.x — core PBCs ── depend on P1.x complete + P4.x for permission checks
R1   — web bootstrap ── depends on P4.1
REF.x — reference plug-in ── depends on P1.4 + P2.1 + P3.3

Sensible ordering for one developer (single-tenant world): P4.1 ✅ → P5.1 ✅ → P1.3 ✅ → P1.7 ✅ → P1.4 ✅ → P1.2 ✅ → P1.5 → P1.6 → P5.2 → P2.1 → P5.3 → P3.4 → R1 → ...

Next up after this commit: P1.5 (metadata seeder) and P5.2 (pbc-partners) are the strongest candidates. Metadata seeder unblocks the entire Tier 1 customization story; pbc-partners adds another business surface (customers / suppliers) that sales orders will reference. Either is a clean ~half-day chunk.

Sensible parallel ordering for a team of three:

  • Dev A: P4.1, P1.5, P1.7, P1.6, P2.1
  • Dev B: P1.4, P1.3, P1.2, P3.4, P3.1
  • Dev C: P5.1 (catalog), P5.2 (partners), P4.3

Then converge on R1 (web) and the rest of Phase 5 in parallel.

Definition of "v1.0 ready"

v1.0 ships when, on a fresh Postgres, an operator can:

  1. docker run the image with a connection string and a company name
  2. Read the bootstrap admin password from the logs
  3. Log in to the web SPA
  4. Drop the printing-shop plug-in JAR into ./plugins/
  5. Restart the container
  6. See the printing-shop's screens, custom fields, workflows, and permissions in the SPA
  7. Walk a quote through the printing shop's full workflow without writing any code
  8. Generate a PDF report for that quote in zh-CN
  9. Export a DSAR for one of their customers

…and the same image, against a fresh empty Postgres pointed at a different company, also serves a customer who has loaded a completely different plug-in expressing a completely different business — without any change to the core image. (Hosting both customers in one process is explicitly NOT a goal — they are two independent instances.)

That's the bar. Until that bar is met, the framework has not delivered on its premise.