feat(api-v1): public plug-in contract — entities, persistence, events, security,… (f5164414) | Commits | 朱子纯 / vibe-erp

Commit f51644142c38dbc26949a8cfae54899b83011a85

Authored by vibe_erp 2026-04-07 15:28:38 +0800

feat(api-v1): public plug-in contract — entities, persistence, events, security,…

… i18n, http, plugin lifecycle

Inline Side-by-side

Showing 37 changed files with 1974 additions and 0 deletions

api/api-v1/build.gradle.kts 0 → 100644

View file @f516441

		1	+plugins {
		2	+ alias(libs.plugins.kotlin.jvm)
		3	+ `java-library`
		4	+ `maven-publish`
		5	+}
		6	+
		7	+description = "vibe_erp Public Plug-in API v1 — the only stable contract a plug-in is allowed to depend on."
		8	+
		9	+java {
		10	+ toolchain {
		11	+ languageVersion.set(JavaLanguageVersion.of(21))
		12	+ }
		13	+ withSourcesJar()
		14	+ withJavadocJar()
		15	+}
		16	+
		17	+kotlin {
		18	+ jvmToolchain(21)
		19	+}
		20	+
		21	+// api-v1 has the strictest dependency hygiene in the entire project.
		22	+// Adding ANY dependency here is effectively adding it to every plug-in
		23	+// in the ecosystem, forever, until the next major version bump. Be paranoid.
		24	+dependencies {
		25	+ api(libs.kotlin.stdlib)
		26	+ api(libs.jakarta.validation.api)
		27	+
		28	+ testImplementation(libs.junit.jupiter)
		29	+ testImplementation(libs.assertk)
		30	+}
		31	+
		32	+tasks.test {
		33	+ useJUnitPlatform()
		34	+}
		35	+
		36	+// We override the inherited project version (0.1.0-SNAPSHOT) with the
		37	+// independently-versioned API line, because plug-in authors track this.
		38	+version = providers.gradleProperty("vibeerp.api.version").get()
		39	+
		40	+publishing {
		41	+ publications {
		42	+ create<MavenPublication>("maven") {
		43	+ from(components["java"])
		44	+ groupId = "org.vibeerp"
		45	+ artifactId = "api-v1"
		46	+ version = project.version.toString()
		47	+ pom {
		48	+ name.set("vibe_erp Public Plug-in API v1")
		49	+ description.set("Stable, semver-governed plug-in API for the vibe_erp framework.")
		50	+ url.set("https://github.com/vibeerp/vibe-erp")
		51	+ licenses {
		52	+ license {
		53	+ name.set("Apache License 2.0")
		54	+ url.set("https://www.apache.org/licenses/LICENSE-2.0.txt")
		55	+ }
		56	+ }
		57	+ }
		58	+ }
		59	+ }
		60	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/core/Identifiers.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.core
		2	+
		3	+import java.util.UUID
		4	+
		5	+/**
		6	+ * Strongly-typed identifier wrapping a UUID.
		7	+ *
		8	+ * Using `Id<User>` instead of raw `UUID` everywhere prevents the classic
		9	+ * mistake of passing a tenant id where a user id was expected — the compiler
		10	+ * catches it. The wrapper is a value class so it has zero runtime overhead.
		11	+ *
		12	+ * @param T phantom type parameter that names what kind of entity this id refers to.
		13	+ */
		14	+@JvmInline
		15	+value class Id<T>(val value: UUID) {
		16	+ override fun toString(): String = value.toString()
		17	+
		18	+ companion object {
		19	+ fun <T> of(uuid: String): Id<T> = Id(UUID.fromString(uuid))
		20	+ fun <T> random(): Id<T> = Id(UUID.randomUUID())
		21	+ }
		22	+}
		23	+
		24	+/**
		25	+ * A tenant identifier.
		26	+ *
		27	+ * Self-hosted single-customer deployments use a single tenant whose id is the
		28	+ * literal string "default". Hosted multi-tenant deployments have one [TenantId]
		29	+ * per customer organization.
		30	+ */
		31	+@JvmInline
		32	+value class TenantId(val value: String) {
		33	+ init {
		34	+ require(value.isNotBlank()) { "TenantId must not be blank" }
		35	+ require(value.length <= 64) { "TenantId must be at most 64 characters" }
		36	+ require(value.all { it.isLetterOrDigit() \|\| it == '-' \|\| it == '_' }) {
		37	+ "TenantId may only contain letters, digits, '-', or '_' (got '$value')"
		38	+ }
		39	+ }
		40	+
		41	+ override fun toString(): String = value
		42	+
		43	+ companion object {
		44	+ val DEFAULT = TenantId("default")
		45	+ }
		46	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/core/Money.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.core
		2	+
		3	+import java.math.BigDecimal
		4	+import java.math.RoundingMode
		5	+
		6	+/**
		7	+ * A monetary amount in a specific ISO-4217 currency.
		8	+ *
		9	+ * vibe_erp NEVER uses raw `Double` or `BigDecimal` for money in api.v1, because
		10	+ * that strips currency context and invites silent unit conversion bugs across
		11	+ * tenants and locales. Every monetary field on every entity uses [Money].
		12	+ *
		13	+ * The framework is sold worldwide, so multi-currency is non-negotiable from
		14	+ * day one (CLAUDE.md guardrail #6 / i18n).
		15	+ */
		16	+data class Money(
		17	+ val amount: BigDecimal,
		18	+ val currency: Currency,
		19	+) : Comparable<Money> {
		20	+
		21	+ init {
		22	+ require(amount.scale() <= currency.defaultFractionDigits) {
		23	+ "Money amount scale ${amount.scale()} exceeds currency ${currency.code} fraction digits ${currency.defaultFractionDigits}"
		24	+ }
		25	+ }
		26	+
		27	+ operator fun plus(other: Money): Money {
		28	+ require(currency == other.currency) {
		29	+ "Cannot add Money in different currencies: ${currency.code} vs ${other.currency.code}"
		30	+ }
		31	+ return Money(amount + other.amount, currency)
		32	+ }
		33	+
		34	+ operator fun minus(other: Money): Money {
		35	+ require(currency == other.currency) {
		36	+ "Cannot subtract Money in different currencies: ${currency.code} vs ${other.currency.code}"
		37	+ }
		38	+ return Money(amount - other.amount, currency)
		39	+ }
		40	+
		41	+ operator fun times(multiplier: BigDecimal): Money =
		42	+ Money(amount.multiply(multiplier).setScale(currency.defaultFractionDigits, RoundingMode.HALF_EVEN), currency)
		43	+
		44	+ override fun compareTo(other: Money): Int {
		45	+ require(currency == other.currency) {
		46	+ "Cannot compare Money in different currencies: ${currency.code} vs ${other.currency.code}"
		47	+ }
		48	+ return amount.compareTo(other.amount)
		49	+ }
		50	+
		51	+ companion object {
		52	+ fun zero(currency: Currency): Money =
		53	+ Money(BigDecimal.ZERO.setScale(currency.defaultFractionDigits), currency)
		54	+ }
		55	+}
		56	+
		57	+/**
		58	+ * Minimal ISO-4217 currency descriptor.
		59	+ *
		60	+ * Kept intentionally tiny in api.v1: code + default fraction digits. The
		61	+ * full currency catalog (display names, symbols, regional formatting) lives
		62	+ * in the i18n layer and is not part of the stable plug-in contract.
		63	+ */
		64	+data class Currency(val code: String, val defaultFractionDigits: Int) {
		65	+ init {
		66	+ require(code.length == 3 && code.all { it.isUpperCase() }) {
		67	+ "Currency code must be 3 uppercase letters (got '$code')"
		68	+ }
		69	+ require(defaultFractionDigits in 0..6) {
		70	+ "defaultFractionDigits out of range: $defaultFractionDigits"
		71	+ }
		72	+ }
		73	+
		74	+ companion object {
		75	+ val USD = Currency("USD", 2)
		76	+ val EUR = Currency("EUR", 2)
		77	+ val CNY = Currency("CNY", 2)
		78	+ val JPY = Currency("JPY", 0)
		79	+ val GBP = Currency("GBP", 2)
		80	+ }
		81	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/core/Quantity.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.core
		2	+
		3	+import java.math.BigDecimal
		4	+
		5	+/**
		6	+ * A quantity in a specific unit of measure.
		7	+ *
		8	+ * Like [Money], quantities carry their unit so the compiler and the runtime
		9	+ * can refuse to add 5 kg to 5 m. The full unit catalog (with conversion
		10	+ * factors and locale-aware display) lives in pbc-catalog and is not part of
		11	+ * the stable api.v1 surface — only the [UnitOfMeasure] descriptor is.
		12	+ */
		13	+data class Quantity(
		14	+ val amount: BigDecimal,
		15	+ val unit: UnitOfMeasure,
		16	+) : Comparable<Quantity> {
		17	+
		18	+ operator fun plus(other: Quantity): Quantity {
		19	+ require(unit == other.unit) {
		20	+ "Cannot add Quantity in different units: ${unit.code} vs ${other.unit.code}. " +
		21	+ "Convert through pbc-catalog before arithmetic."
		22	+ }
		23	+ return Quantity(amount + other.amount, unit)
		24	+ }
		25	+
		26	+ operator fun minus(other: Quantity): Quantity {
		27	+ require(unit == other.unit) {
		28	+ "Cannot subtract Quantity in different units: ${unit.code} vs ${other.unit.code}"
		29	+ }
		30	+ return Quantity(amount - other.amount, unit)
		31	+ }
		32	+
		33	+ override fun compareTo(other: Quantity): Int {
		34	+ require(unit == other.unit) {
		35	+ "Cannot compare Quantity in different units: ${unit.code} vs ${other.unit.code}"
		36	+ }
		37	+ return amount.compareTo(other.amount)
		38	+ }
		39	+}
		40	+
		41	+/**
		42	+ * Unit of measure descriptor.
		43	+ *
		44	+ * `code` is a stable identifier (e.g. "kg", "m", "ea", "sheet"). Display
		45	+ * names and conversions are NOT part of api.v1 — they live in pbc-catalog.
		46	+ */
		47	+data class UnitOfMeasure(val code: String) {
		48	+ init {
		49	+ require(code.isNotBlank() && code.length <= 16) {
		50	+ "UnitOfMeasure code must be 1-16 characters (got '$code')"
		51	+ }
		52	+ }
		53	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/core/Result.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.core
		2	+
		3	+/**
		4	+ * A typed success-or-failure value used across the api.v1 surface.
		5	+ *
		6	+ * vibe_erp prefers explicit Result types in plug-in-facing APIs over thrown
		7	+ * exceptions for expected failures (validation errors, permission denials,
		8	+ * not-found, optimistic-locking conflicts). Exceptions remain appropriate for
		9	+ * unexpected, infrastructural failures (the database is down, etc.).
		10	+ *
		11	+ * Why: plug-ins are loaded into a host process and a thrown exception that
		12	+ * crosses a classloader boundary can be very hard to handle correctly. A typed
		13	+ * Result keeps the contract honest.
		14	+ */
		15	+sealed interface Result<out T, out E> {
		16	+ data class Ok<T>(val value: T) : Result<T, Nothing>
		17	+ data class Err<E>(val error: E) : Result<Nothing, E>
		18	+
		19	+ fun isOk(): Boolean = this is Ok
		20	+ fun isErr(): Boolean = this is Err
		21	+
		22	+ fun valueOrNull(): T? = (this as? Ok)?.value
		23	+ fun errorOrNull(): E? = (this as? Err)?.error
		24	+
		25	+ companion object {
		26	+ fun <T> ok(value: T): Result<T, Nothing> = Ok(value)
		27	+ fun <E> err(error: E): Result<Nothing, E> = Err(error)
		28	+ }
		29	+}
		30	+
		31	+inline fun <T, E, R> Result<T, E>.map(transform: (T) -> R): Result<R, E> = when (this) {
		32	+ is Result.Ok -> Result.Ok(transform(value))
		33	+ is Result.Err -> this
		34	+}
		35	+
		36	+inline fun <T, E, R> Result<T, E>.flatMap(transform: (T) -> Result<R, E>): Result<R, E> = when (this) {
		37	+ is Result.Ok -> transform(value)
		38	+ is Result.Err -> this
		39	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/entity/AuditedEntity.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.entity
		2	+
		3	+import org.vibeerp.api.v1.security.PrincipalId
		4	+import java.time.Instant
		5	+
		6	+/**
		7	+ * An [Entity] that carries who/when audit columns automatically maintained by
		8	+ * the platform's JPA listener.
		9	+ *
		10	+ * Why this exists as a separate interface rather than fields on [Entity]:
		11	+ * - Some entities (config rows, lookup tables, immutable event records) do
		12	+ * not need an updated-at column and forcing one on them invites lying
		13	+ * timestamps.
		14	+ * - It gives the platform a typed hook to know "this entity wants the audit
		15	+ * listener" without reflection-scanning every class.
		16	+ * - It documents in the type system that the four columns are populated by
		17	+ * the framework, not by the plug-in. Plug-ins should treat the setters
		18	+ * as read-only at the application level — the values are filled in at
		19	+ * flush time from the current [org.vibeerp.api.v1.security.Principal].
		20	+ *
		21	+ * The four columns mirror what every serious ERP records on every business
		22	+ * row and what GDPR/SOX-style audits expect to find.
		23	+ */
		24	+interface AuditedEntity : Entity {
		25	+
		26	+ /** When this row was first inserted. UTC. Set once, never updated. */
		27	+ val createdAt: Instant
		28	+
		29	+ /** Principal that performed the insert. */
		30	+ val createdBy: PrincipalId
		31	+
		32	+ /** When this row was last updated. UTC. Equal to [createdAt] until first update. */
		33	+ val updatedAt: Instant
		34	+
		35	+ /** Principal that performed the most recent update. */
		36	+ val updatedBy: PrincipalId
		37	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/entity/CustomField.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.entity
		2	+
		3	+/**
		4	+ * Declarative description of a custom field added to an existing entity.
		5	+ *
		6	+ * Custom fields are how the framework satisfies guardrail #1 ("core stays
		7	+ * domain-agnostic") in practice: a printing shop that needs a `plate_gauge`
		8	+ * column on the catalog item entity does not patch `pbc-catalog`. They add
		9	+ * a [CustomField] row through the no-code UI (Tier 1) or through a plug-in
		10	+ * manifest (Tier 2), and the JSONB `ext` column on the catalog item table
		11	+ * starts carrying the value the same instant.
		12	+ *
		13	+ * The form builder, list view designer, OpenAPI generator, AI agent function
		14	+ * catalog, and DSAR/erasure jobs all consume this descriptor. There is
		15	+ * intentionally no parallel source of truth.
		16	+ *
		17	+ * @property key Stable identifier for this field within [targetEntity]. Must be
		18	+ * stable across upgrades because it is the JSON key inside the `ext` column.
		19	+ * Convention: `snake_case`, prefixed by the owning plug-in or PBC, e.g.
		20	+ * `printingshop_plate_gauge`.
		21	+ * @property targetEntity Name of the entity this field is attached to. Must
		22	+ * be discoverable through [EntityRegistry] at registration time.
		23	+ * @property type The field's data type — see [FieldType].
		24	+ * @property required Whether the value must be present on insert/update.
		25	+ * @property pii Whether this field contains personally identifiable information.
		26	+ * Drives automatic DSAR exports and erasure jobs (architecture spec section 8,
		27	+ * "Data sovereignty"). Setting this wrong is a compliance bug, not a styling
		28	+ * choice — when in doubt, mark it `true`.
		29	+ * @property labelTranslations Locale code → human-readable label. The framework
		30	+ * refuses to render a custom field that has no label for the current locale
		31	+ * and no entry for the configured fallback locale; this prevents the
		32	+ * classic "key string leaked to the UI" failure mode.
		33	+ */
		34	+data class CustomField(
		35	+ val key: String,
		36	+ val targetEntity: String,
		37	+ val type: FieldType,
		38	+ val required: Boolean = false,
		39	+ val pii: Boolean = false,
		40	+ val labelTranslations: Map<String, String> = emptyMap(),
		41	+) {
		42	+ init {
		43	+ require(key.isNotBlank()) { "CustomField key must not be blank" }
		44	+ require(key.length <= 64) { "CustomField key must be at most 64 characters (got '$key')" }
		45	+ require(key.all { it.isLetterOrDigit() \|\| it == '_' }) {
		46	+ "CustomField key may only contain letters, digits, and '_' (got '$key')"
		47	+ }
		48	+ require(targetEntity.isNotBlank()) { "CustomField targetEntity must not be blank" }
		49	+ }
		50	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/entity/Entity.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.entity
		2	+
		3	+import org.vibeerp.api.v1.core.Id
		4	+import org.vibeerp.api.v1.core.TenantId
		5	+
		6	+/**
		7	+ * Marker interface for every domain entity that lives in the vibe_erp data model.
		8	+ *
		9	+ * Why this exists at all:
		10	+ * - It enforces, at the type level, that every entity carries a tenant id.
		11	+ * Multi-tenancy is an architectural guardrail (CLAUDE.md #5) and the cheapest
		12	+ * place to enforce it is the type system. A repository signature like
		13	+ * `Repository<T : Entity>` cannot be instantiated for a type that "forgot"
		14	+ * its tenant id.
		15	+ * - It gives the runtime a single hook for tenant filtering, JSONB `ext`
		16	+ * handling, and audit interception without each PBC reinventing it.
		17	+ * - It is intentionally minimal: no equality, no hashCode, no lifecycle
		18	+ * callbacks. Those are concerns of `platform.persistence`, not the public
		19	+ * contract. Adding them later is a breaking change; leaving them out is not.
		20	+ *
		21	+ * Plug-ins implement this on their own data classes. They never see the
		22	+ * underlying JPA `@Entity` annotation — that lives in the platform's internal
		23	+ * mapping layer.
		24	+ *
		25	+ * ```
		26	+ * data class Plate(
		27	+ * override val id: Id<Plate>,
		28	+ * override val tenantId: TenantId,
		29	+ * val gauge: Quantity,
		30	+ * ) : Entity
		31	+ * ```
		32	+ */
		33	+interface Entity {
		34	+ /**
		35	+ * The strongly-typed identifier for this entity. Using `Id<*>` here (rather
		36	+ * than `Id<Self>`) keeps the marker contravariant-friendly so polymorphic
		37	+ * collections of `Entity` can be passed across api.v1 boundaries without
		38	+ * generic gymnastics. Concrete implementations should narrow the type
		39	+ * parameter to themselves.
		40	+ */
		41	+ val id: Id<*>
		42	+
		43	+ /**
		44	+ * The tenant that owns this row. Required on every business entity, even in
		45	+ * single-tenant self-hosted deployments (where the value is
		46	+ * [TenantId.DEFAULT]) — there is intentionally one code path for both
		47	+ * deployment shapes.
		48	+ */
		49	+ val tenantId: TenantId
		50	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/entity/EntityRegistry.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.entity
		2	+
		3	+/**
		4	+ * Runtime catalog of every entity the framework knows about — core PBC
		5	+ * entities, plug-in entities, and Tier 1 user-defined entities.
		6	+ *
		7	+ * Why this is part of api.v1:
		8	+ * - Plug-ins need to introspect entities at runtime to render generic UIs,
		9	+ * drive the OpenAPI generator, and resolve [FieldType.Reference] targets,
		10	+ * without depending on the concrete PBC that owns each entity (which
		11	+ * would violate guardrail #9, "PBC boundaries are sacred").
		12	+ * - It is the seam through which Tier 1 user-defined entities and Tier 2
		13	+ * plug-in entities look identical to consumers. Neither caller cares
		14	+ * where an entity descriptor came from.
		15	+ *
		16	+ * The registry is read-only from the plug-in's perspective. Registration
		17	+ * happens during plug-in startup via [org.vibeerp.api.v1.plugin.PluginContext]
		18	+ * helpers that the platform implements internally.
		19	+ */
		20	+interface EntityRegistry {
		21	+
		22	+ /**
		23	+ * Look up an entity descriptor by its registered name.
		24	+ *
		25	+ * @return the descriptor, or `null` if no entity with that name exists.
		26	+ * Plug-ins should not throw on a miss — entities can be uninstalled
		27	+ * while a workflow that referenced them is mid-flight.
		28	+ */
		29	+ fun describe(entityName: String): EntityDescriptor?
		30	+
		31	+ /**
		32	+ * Snapshot of every currently-registered entity name. Default
		33	+ * implementation returns an empty set so adding new lookup methods later
		34	+ * (e.g. filtered by source) is non-breaking for existing host
		35	+ * implementations.
		36	+ */
		37	+ fun entityNames(): Set<String> = emptySet()
		38	+}
		39	+
		40	+/**
		41	+ * Lightweight description of an entity, returned by [EntityRegistry.describe].
		42	+ *
		43	+ * Kept intentionally small. The full mapping (table name, column types,
		44	+ * Hibernate metadata) lives in the platform internals; api.v1 exposes only
		45	+ * what plug-ins legitimately need to render generic UIs and validate input.
		46	+ *
		47	+ * @property name Stable, globally unique entity name, e.g. `catalog.item` or
		48	+ * `plugin_printingshop.plate_spec`.
		49	+ * @property pluginId The plug-in id that owns this entity, or `null` if it
		50	+ * belongs to a core PBC.
		51	+ * @property customFields Custom fields currently declared against this entity
		52	+ * for the calling tenant. Note: this list is tenant-scoped — two tenants
		53	+ * on the same host can see different custom fields on the same entity.
		54	+ * @property auditable Whether the entity implements [AuditedEntity] and
		55	+ * therefore carries the four audit columns.
		56	+ */
		57	+data class EntityDescriptor(
		58	+ val name: String,
		59	+ val pluginId: String? = null,
		60	+ val customFields: List<CustomField> = emptyList(),
		61	+ val auditable: Boolean = false,
		62	+) {
		63	+ init {
		64	+ require(name.isNotBlank()) { "EntityDescriptor name must not be blank" }
		65	+ }
		66	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/entity/FieldType.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.entity
		2	+
		3	+/**
		4	+ * The closed set of field types that vibe_erp's metadata layer can describe.
		5	+ *
		6	+ * Why this is a sealed interface and not an enum:
		7	+ * - Several types carry their own configuration (max length on STRING,
		8	+ * precision on DECIMAL, target entity on REFERENCE, allowed values on
		9	+ * ENUM). An enum cannot do that without a parallel `Map<Type, Config>`
		10	+ * table that the type system cannot keep in sync.
		11	+ * - It is closed deliberately. Adding a new field type is an api.v1 change
		12	+ * requiring a release; allowing arbitrary new field types in user metadata
		13	+ * would defeat the form designer, the OpenAPI generator, the AI function
		14	+ * catalog, and the PII/DSAR pipeline, all of which switch on this set.
		15	+ *
		16	+ * Field types are used in two places:
		17	+ * 1. [CustomField] declarations, where a key user adds a column to an
		18	+ * existing entity through the no-code UI.
		19	+ * 2. Plug-in entity descriptors registered through [EntityRegistry], so the
		20	+ * same UI machinery (form builder, list view, OpenAPI) works on plug-in
		21	+ * entities without the plug-in shipping its own React code.
		22	+ *
		23	+ * Storage shape:
		24	+ * - Custom-field values live in the JSONB `ext` column on the host entity's
		25	+ * table (architecture spec section 8). The field type drives JSON encoding,
		26	+ * GIN-index strategy, validation, and OpenAPI schema generation.
		27	+ */
		28	+sealed interface FieldType {
		29	+
		30	+ /** Free text. [maxLength] caps storage and form input length. */
		31	+ data class String(val maxLength: Int = 255) : FieldType {
		32	+ init {
		33	+ require(maxLength in 1..1_048_576) { "STRING maxLength out of range: $maxLength" }
		34	+ }
		35	+ }
		36	+
		37	+ /** 64-bit signed integer. */
		38	+ data object Integer : FieldType
		39	+
		40	+ /**
		41	+ * Fixed-point decimal stored as a JSON string to preserve scale.
		42	+ * [precision] is total digits, [scale] is digits after the decimal point.
		43	+ */
		44	+ data class Decimal(val precision: Int = 19, val scale: Int = 4) : FieldType {
		45	+ init {
		46	+ require(precision in 1..38) { "DECIMAL precision out of range: $precision" }
		47	+ require(scale in 0..precision) { "DECIMAL scale out of range: $scale" }
		48	+ }
		49	+ }
		50	+
		51	+ /** Boolean. */
		52	+ data object Boolean : FieldType
		53	+
		54	+ /** Calendar date with no time-of-day and no zone. */
		55	+ data object Date : FieldType
		56	+
		57	+ /** Instant on the timeline (stored UTC, rendered in the user's locale). */
		58	+ data object DateTime : FieldType
		59	+
		60	+ /** RFC-4122 UUID. Distinct from [Reference] — a free-floating identifier. */
		61	+ data object Uuid : FieldType
		62	+
		63	+ /**
		64	+ * A monetary value. The currency is part of the value, not the field
		65	+ * descriptor — see [org.vibeerp.api.v1.core.Money]. This means a single
		66	+ * `total_amount` field can legitimately hold mixed-currency rows.
		67	+ */
		68	+ data object Money : FieldType
		69	+
		70	+ /** A quantity with a unit of measure attached to the value. */
		71	+ data object Quantity : FieldType
		72	+
		73	+ /**
		74	+ * A foreign-key-style pointer to another entity by name.
		75	+ *
		76	+ * The reference is resolved by [EntityRegistry] at runtime, which is what
		77	+ * lets a Tier 1 user create a custom field that points at a plug-in
		78	+ * entity without anyone writing JPA mappings.
		79	+ */
		80	+ data class Reference(val targetEntity: kotlin.String) : FieldType {
		81	+ init {
		82	+ require(targetEntity.isNotBlank()) { "REFERENCE targetEntity must not be blank" }
		83	+ }
		84	+ }
		85	+
		86	+ /**
		87	+ * A closed set of allowed string values. The values themselves are stored
		88	+ * as plain strings; their human-readable labels live in the i18n bundles
		89	+ * keyed by `<entity>.<field>.<value>`.
		90	+ */
		91	+ data class Enum(val allowedValues: List<kotlin.String>) : FieldType {
		92	+ init {
		93	+ require(allowedValues.isNotEmpty()) { "ENUM must declare at least one allowed value" }
		94	+ require(allowedValues.toSet().size == allowedValues.size) { "ENUM allowedValues must be unique" }
		95	+ }
		96	+ }
		97	+
		98	+ /**
		99	+ * Arbitrary structured JSON. Use sparingly — JSON fields are opaque to
		100	+ * the form builder, the list view, and the OpenAPI schema generator.
		101	+ * Prefer a structured type when one fits.
		102	+ */
		103	+ data object Json : FieldType
		104	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/event/DomainEvent.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.event
		2	+
		3	+import org.vibeerp.api.v1.core.Id
		4	+import org.vibeerp.api.v1.core.TenantId
		5	+import java.time.Instant
		6	+
		7	+/**
		8	+ * Base contract for every domain event published on the vibe_erp event bus.
		9	+ *
		10	+ * Why a sealed-style typed contract instead of "publish any object":
		11	+ * - PBC boundaries are sacred (CLAUDE.md guardrail #9). PBCs talk to each
		12	+ * other only through events or through `api.v1.ext.<pbc>` interfaces. If
		13	+ * events were untyped, every consumer would have to know every producer's
		14	+ * class, which is exactly the coupling we are trying to avoid.
		15	+ * - The standard envelope (`eventId`, `tenantId`, `occurredAt`,
		16	+ * `aggregateType`, `aggregateId`) is what the platform's outbox table,
		17	+ * audit log, and future Kafka/NATS bridge all rely on. Plug-ins that
		18	+ * forget any of these fields cannot misroute or replay events.
		19	+ *
		20	+ * Note that this is `interface`, not `sealed interface`: plug-ins must be
		21	+ * free to extend the hierarchy with their own concrete event classes.
		22	+ * "Sealed" here means "every plug-in event must extend this sealed envelope",
		23	+ * not "the set of envelope shapes is closed". A truly closed hierarchy would
		24	+ * make plug-ins impossible.
		25	+ *
		26	+ * ```
		27	+ * data class PlateApproved(
		28	+ * override val eventId: Id<DomainEvent> = Id.random(),
		29	+ * override val tenantId: TenantId,
		30	+ * override val occurredAt: Instant = Instant.now(),
		31	+ * val plateId: Id<*>,
		32	+ * ) : DomainEvent {
		33	+ * override val aggregateType = "printingshop.plate"
		34	+ * override val aggregateId = plateId.toString()
		35	+ * }
		36	+ * ```
		37	+ */
		38	+interface DomainEvent {
		39	+
		40	+ /** Unique id for this event instance. Used for idempotent consumer logic and outbox dedup. */
		41	+ val eventId: Id<DomainEvent>
		42	+
		43	+ /** Tenant the event belongs to. Carried explicitly because background consumers run outside any HTTP request. */
		44	+ val tenantId: TenantId
		45	+
		46	+ /** When the event occurred (UTC). Set by the producer, not by the bus, so replays preserve original timing. */
		47	+ val occurredAt: Instant
		48	+
		49	+ /**
		50	+ * Logical name of the aggregate this event is about, e.g.
		51	+ * `orders_sales.order` or `plugin_printingshop.plate`. Used for routing,
		52	+ * audit views, and the future event-streaming bridge.
		53	+ */
		54	+ val aggregateType: String
		55	+
		56	+ /**
		57	+ * String form of the aggregate's id. String (not [Id]) because some
		58	+ * aggregates are keyed by composite or natural keys and the bus must
		59	+ * route them all.
		60	+ */
		61	+ val aggregateId: String
		62	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/event/EventBus.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.event
		2	+
		3	+/**
		4	+ * Publish/subscribe contract for domain events.
		5	+ *
		6	+ * The host's implementation is backed by an in-process bus plus a Postgres
		7	+ * outbox table (architecture spec section 9, "Cross-cutting concerns").
		8	+ * The outbox is what makes "modular monolith now, splittable later" real:
		9	+ * the day the framework grows a Kafka or NATS bridge, the existing
		10	+ * publish/subscribe code in every PBC and plug-in keeps working unchanged.
		11	+ *
		12	+ * Why this is the only way plug-ins emit events:
		13	+ * - The publish path goes through the platform so it can attach the current
		14	+ * tenant, principal, and request id automatically; a plug-in that bypasses
		15	+ * [EventBus] would lose all of that and break the audit trail.
		16	+ * - The subscribe path is the platform's only place to track listener
		17	+ * registrations per plug-in classloader, so unloading a plug-in cleanly
		18	+ * removes its listeners.
		19	+ *
		20	+ * Both methods are deliberately non-suspending and Java-friendly (`Class<E>`
		21	+ * over `KClass<E>`) so the contract is callable from any JVM language a
		22	+ * plug-in author chooses.
		23	+ */
		24	+interface EventBus {
		25	+
		26	+ /**
		27	+ * Publish an event. The bus is responsible for delivering it to every
		28	+ * matching listener and for persisting an outbox row inside the current
		29	+ * transaction (so a publish followed by a rollback never escapes).
		30	+ */
		31	+ fun publish(event: DomainEvent)
		32	+
		33	+ /**
		34	+ * Register a listener for events of [eventType] (and its subtypes).
		35	+ *
		36	+ * The listener stays registered until the plug-in is stopped, at which
		37	+ * point the platform tears it down automatically — plug-ins do not
		38	+ * need (and should not have) a manual `unsubscribe` method.
		39	+ */
		40	+ fun <E : DomainEvent> subscribe(eventType: Class<E>, listener: EventListener<E>)
		41	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/event/EventListener.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.event
		2	+
		3	+/**
		4	+ * Single-method listener for domain events.
		5	+ *
		6	+ * Declared as `fun interface` so plug-ins can register listeners with a Kotlin
		7	+ * lambda or a method reference, without writing an anonymous-class boilerplate
		8	+ * shell:
		9	+ *
		10	+ * ```
		11	+ * eventBus.subscribe(PlateApproved::class.java) { event ->
		12	+ * logger.info("Plate ${event.plateId} approved")
		13	+ * }
		14	+ * ```
		15	+ *
		16	+ * Listeners run on the thread the bus chooses, which may be the publisher's
		17	+ * thread (in-process synchronous), a worker thread (in-process async), or a
		18	+ * dedicated outbox-drain thread when reliability is required. Implementations
		19	+ * MUST be thread-safe and MUST NOT assume the publisher's transaction is
		20	+ * still open — if a listener needs its own transaction, it must request one
		21	+ * through [org.vibeerp.api.v1.persistence.Transaction].
		22	+ */
		23	+fun interface EventListener<E : DomainEvent> {
		24	+ fun handle(event: E)
		25	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/ext/identity/IdentityApi.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.ext.identity
		2	+
		3	+import org.vibeerp.api.v1.core.Id
		4	+import org.vibeerp.api.v1.core.TenantId
		5	+
		6	+/**
		7	+ * Cross-PBC facade for the identity bounded context.
		8	+ *
		9	+ * **This file is the proof that PBCs talk to each other through `api.v1`,
		10	+ * not directly.** Guardrail #9 ("PBC boundaries are sacred") is not just a
		11	+ * convention; it is enforced by the Gradle build, which forbids
		12	+ * `pbc-orders-sales` from declaring `pbc-identity` as a dependency. The only
		13	+ * way `pbc-orders-sales` (or any plug-in) can ask "who is the user with this
		14	+ * username?" is by injecting [IdentityApi] — an interface declared here, in
		15	+ * api.v1, and implemented by `pbc-identity` at runtime.
		16	+ *
		17	+ * If [IdentityApi] grows a method that leaks identity-internal types, the
		18	+ * abstraction has failed and the method must be reshaped. The whole point of
		19	+ * this package is to expose intent (`UserRef`) without exposing the storage
		20	+ * model (`IdentityUserEntity`, `IdentityUserRow`, etc.).
		21	+ *
		22	+ * Future PBCs will get sibling packages (`api.v1.ext.catalog`,
		23	+ * `api.v1.ext.inventory`, …) following the same pattern.
		24	+ */
		25	+interface IdentityApi {
		26	+
		27	+ /**
		28	+ * Look up a user by their unique username within the current tenant.
		29	+ * Returns `null` when no such user exists or when the calling principal
		30	+ * lacks permission to read user records.
		31	+ */
		32	+ fun findUserByUsername(username: String): UserRef?
		33	+
		34	+ /**
		35	+ * Look up a user by id. The id is `Id<*>` rather than `Id<UserRef>` so
		36	+ * callers do not have to know the exact entity type — they pass the id
		37	+ * they have, and the implementation does the matching internally.
		38	+ */
		39	+ fun findUserById(id: Id<*>): UserRef?
		40	+}
		41	+
		42	+/**
		43	+ * Minimal, safe-to-publish view of a user.
		44	+ *
		45	+ * Notably absent: password hash, MFA secrets, last login IP, anything from
		46	+ * the `identity__user_security` table. Anything that does not appear here
		47	+ * cannot be observed cross-PBC, and that is intentional — adding a field is
		48	+ * a deliberate api.v1 change and triggers a security review.
		49	+ *
		50	+ * @property id Stable user id.
		51	+ * @property username Login handle. Unique within [tenantId].
		52	+ * @property tenantId Owning tenant.
		53	+ * @property displayName Human-readable name for UI rendering. Falls back to
		54	+ * [username] when the user has not set one.
		55	+ * @property enabled Whether the account is active. A disabled user can still
		56	+ * appear as an audit-column foreign key, which is why this field exists at
		57	+ * all — callers must check it before treating the user as a current actor.
		58	+ */
		59	+data class UserRef(
		60	+ val id: Id<UserRef>,
		61	+ val username: String,
		62	+ val tenantId: TenantId,
		63	+ val displayName: String,
		64	+ val enabled: Boolean,
		65	+)

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/form/FormSchema.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.form
		2	+
		3	+/**
		4	+ * A form definition shipped by a plug-in or stored in the metadata table.
		5	+ *
		6	+ * Why two strings instead of a structured Kotlin model:
		7	+ * - The form designer in the web UI works in JSON Schema + UI Schema (the
		8	+ * same shape used by Frappe Doctype, ERPNext form layouts, and the
		9	+ * `@rjsf/core` React renderer). Re-modeling that as Kotlin classes would
		10	+ * create a parallel source of truth that drifts the moment a renderer
		11	+ * feature is added.
		12	+ * - api.v1 must not depend on a specific JSON parser (Jackson is forbidden).
		13	+ * Holding the JSON as opaque strings means the platform parses it once,
		14	+ * inside the platform layer, and plug-ins never need a JSON dependency
		15	+ * just to ship a form.
		16	+ * - The richer typed wrapper API lands in v0.2 of the api.v1 line as a
		17	+ * purely additive layer. Until then, this is the smallest contract that
		18	+ * lets a plug-in ship a working form.
		19	+ *
		20	+ * @property jsonSchema A JSON Schema (draft 2020-12) document describing
		21	+ * the data shape of the form. The host validates user input against this
		22	+ * schema before passing it to the plug-in.
		23	+ * @property uiSchema A UI Schema document (the `@rjsf/core` convention)
		24	+ * describing widget choices, ordering, and layout hints. May be empty
		25	+ * string when the default rendering is acceptable.
		26	+ * @property version Monotonically increasing schema version. The host
		27	+ * stores submitted form values tagged with the version they were captured
		28	+ * under so a plug-in upgrade does not retroactively invalidate old
		29	+ * records. Bump this when the [jsonSchema] changes shape, not when the
		30	+ * [uiSchema] is merely restyled.
		31	+ */
		32	+data class FormSchema(
		33	+ val jsonSchema: String,
		34	+ val uiSchema: String,
		35	+ val version: Int,
		36	+) {
		37	+ init {
		38	+ require(jsonSchema.isNotBlank()) { "FormSchema jsonSchema must not be blank" }
		39	+ require(version >= 1) { "FormSchema version must be >= 1 (got $version)" }
		40	+ }
		41	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/http/PluginEndpoint.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.http
		2	+
		3	+/**
		4	+ * Marks a class as a plug-in HTTP controller.
		5	+ *
		6	+ * Why this is a vibe_erp-owned annotation rather than `@RestController`:
		7	+ * - api.v1 must not leak Spring types to plug-ins (CLAUDE.md guardrail #10).
		8	+ * A plug-in that imports `org.springframework.web.bind.annotation.RestController`
		9	+ * is grade-D and rejected at install time.
		10	+ * - The host scans for `@PluginEndpoint` inside each plug-in's child Spring
		11	+ * context and mounts the controller automatically under the prefix
		12	+ * `/api/v1/plugins/<plugin-id>` + [basePath]. The plug-in author never
		13	+ * chooses the absolute URL — that prevents two plug-ins from colliding on
		14	+ * the same path and gives the OpenAPI generator one source of truth.
		15	+ * - The host applies authentication, tenant resolution, locale resolution,
		16	+ * request id propagation, structured logging, and the `RequestContext`
		17	+ * binding to every method on a `@PluginEndpoint` class, so plug-ins
		18	+ * inherit all of that without any per-controller setup.
		19	+ *
		20	+ * The actual HTTP method bindings (GET/POST/etc.), request body parsing, and
		21	+ * response serialization are still expressed using a small set of api.v1
		22	+ * annotations to be added in subsequent releases. Until then, the host
		23	+ * delegates to standard JAX-RS / Spring Web binding inside the platform
		24	+ * layer; the annotation surface visible to plug-ins is intentionally minimal
		25	+ * in v1.0 so it can grow deliberately.
		26	+ *
		27	+ * ```
		28	+ * @PluginEndpoint(basePath = "/plates")
		29	+ * class PlateController(private val ctx: RequestContext) {
		30	+ * // mounted at /api/v1/plugins/printingshop/plates
		31	+ * }
		32	+ * ```
		33	+ */
		34	+@Target(AnnotationTarget.CLASS)
		35	+@Retention(AnnotationRetention.RUNTIME)
		36	+@MustBeDocumented
		37	+annotation class PluginEndpoint(
		38	+ /**
		39	+ * Path under the plug-in's namespace, beginning with `/`. The full URL
		40	+ * is `/api/v1/plugins/<plugin-id><basePath>`.
		41	+ */
		42	+ val basePath: String,
		43	+)

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/http/RequestContext.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.http
		2	+
		3	+import org.vibeerp.api.v1.core.TenantId
		4	+import org.vibeerp.api.v1.security.Principal
		5	+import java.util.Locale
		6	+
		7	+/**
		8	+ * Per-request context, available by injection inside any class annotated with
		9	+ * [PluginEndpoint].
		10	+ *
		11	+ * Why an explicit context object instead of "scattered ThreadLocals":
		12	+ * - Plug-ins live in their own classloader, so a static `ThreadLocal` lookup
		13	+ * inside api.v1 would have to bridge classloaders to find the host's
		14	+ * state. An injected context is cleaner, testable, and forces the
		15	+ * plug-in author to declare a dependency on the values they use.
		16	+ * - It is the single answer to "who, where, when, which language, which
		17	+ * request" that every other api.v1 surface (permission check, translator,
		18	+ * repository, event bus) consults under the covers.
		19	+ *
		20	+ * The host provides one [RequestContext] per HTTP request and per workflow
		21	+ * task execution. Background jobs receive a context whose [principal] is a
		22	+ * [org.vibeerp.api.v1.security.Principal.System] and whose [requestId] is
		23	+ * the job execution id.
		24	+ */
		25	+interface RequestContext {
		26	+
		27	+ /** The authenticated caller. Never `null`; anonymous endpoints get a system principal. */
		28	+ fun principal(): Principal
		29	+
		30	+ /**
		31	+ * The tenant the request is operating in. Always equal to
		32	+ * `principal().tenantId` in normal flows, but separated for clarity in
		33	+ * "act as" / impersonation scenarios where the two could legitimately
		34	+ * differ.
		35	+ */
		36	+ fun tenantId(): TenantId
		37	+
		38	+ /** The resolved request locale. Same value [org.vibeerp.api.v1.i18n.LocaleProvider.current] would return. */
		39	+ fun locale(): Locale
		40	+
		41	+ /**
		42	+ * Correlation id for this request, propagated to logs, downstream calls,
		43	+ * and emitted events. Stable across the whole request lifecycle.
		44	+ */
		45	+ fun requestId(): String
		46	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/i18n/LocaleProvider.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.i18n
		2	+
		3	+import java.util.Locale
		4	+
		5	+/**
		6	+ * Resolves the locale of the current operation.
		7	+ *
		8	+ * Why a separate interface from [Translator]:
		9	+ * - The decision "what locale am I in right now?" is the host's
		10	+ * responsibility, not the plug-in's. The host walks a precedence chain
		11	+ * (HTTP `Accept-Language` → user preference → tenant default → system
		12	+ * default) on every request and on every background job, and a plug-in
		13	+ * must NEVER reach into HTTP headers itself — it would break for
		14	+ * non-HTTP callers (workflow tasks, scheduled jobs, MCP agents).
		15	+ * - Splitting it from [Translator] keeps the translator pure and testable
		16	+ * (you can pass any [Locale] to `translate`), while [LocaleProvider] is
		17	+ * the impure side that knows about the ambient request.
		18	+ *
		19	+ * Outside of an HTTP request (background jobs, workflow tasks, system
		20	+ * principals), the host returns the tenant's default locale, then the
		21	+ * platform default. There is always some locale; this method never throws.
		22	+ */
		23	+interface LocaleProvider {
		24	+
		25	+ /** The locale to use for the current operation. Never `null`. */
		26	+ fun current(): Locale
		27	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/i18n/MessageKey.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.i18n
		2	+
		3	+/**
		4	+ * Type-safe wrapper around an i18n message key.
		5	+ *
		6	+ * Why a value class instead of "just a String":
		7	+ * - Translator method signatures take `MessageKey`, not `String`, so the
		8	+ * compiler refuses to pass a raw user-facing English sentence into the
		9	+ * translator. That single rule eliminates the most common i18n bug:
		10	+ * "we forgot to translate this one place".
		11	+ * - Zero runtime overhead — `@JvmInline` erases to a `String` at runtime.
		12	+ *
		13	+ * Naming convention is `<plugin-or-pbc>.<area>.<message>`. Examples:
		14	+ * - `identity.user.created`
		15	+ * - `catalog.item.duplicate_sku`
		16	+ * - `printingshop.plate.approval_required`
		17	+ *
		18	+ * The convention is enforced by [init] because once a key is shipped to a
		19	+ * tenant's translation overrides table, renaming it costs everyone money.
		20	+ */
		21	+@JvmInline
		22	+value class MessageKey(val key: String) {
		23	+ init {
		24	+ require(key.isNotBlank()) { "MessageKey must not be blank" }
		25	+ require(KEY_REGEX.matches(key)) {
		26	+ "MessageKey must look like '<area>.<resource>.<message>' (got '$key')"
		27	+ }
		28	+ }
		29	+
		30	+ override fun toString(): String = key
		31	+
		32	+ companion object {
		33	+ private val KEY_REGEX = Regex("^[a-z][a-z0-9_](\\.[a-z][a-z0-9_]){2,}$")
		34	+ }
		35	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/i18n/Translator.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.i18n
		2	+
		3	+import java.util.Locale
		4	+
		5	+/**
		6	+ * Plug-in-facing translation lookup.
		7	+ *
		8	+ * Why this is a single small interface and not a fluent builder:
		9	+ * - i18n is a guardrail (CLAUDE.md #6). The interface a plug-in author sees
		10	+ * must be tiny and impossible to use wrong; otherwise plug-ins will hard-
		11	+ * code English strings "just for now" and never come back.
		12	+ * - The host implements this with ICU4J `MessageFormat` so plurals, gender,
		13	+ * number/date/currency formatting all work without the plug-in knowing.
		14	+ * - The lookup goes through the metadata translation overrides table first,
		15	+ * then the plug-in's own bundles, then the platform's bundles, then the
		16	+ * fallback locale, then the key itself. None of that is the plug-in's
		17	+ * problem.
		18	+ *
		19	+ * ```
		20	+ * translator.translate(
		21	+ * MessageKey("printingshop.plate.approved"),
		22	+ * localeProvider.current(),
		23	+ * mapOf("plateId" to plate.id, "user" to user.username),
		24	+ * )
		25	+ * ```
		26	+ */
		27	+interface Translator {
		28	+
		29	+ /**
		30	+ * Resolve a message in the given locale, substituting the named arguments.
		31	+ *
		32	+ * @param key the message key to look up.
		33	+ * @param locale the locale to render in. Use [LocaleProvider.current] to
		34	+ * pick up the request locale automatically.
		35	+ * @param args named arguments referenced from the message text using ICU
		36	+ * MessageFormat placeholders, e.g. `{user}`, `{count, plural, ...}`.
		37	+ * @return the translated string. NEVER `null` — when nothing matches, the
		38	+ * host returns the key itself so the failure is visible in the UI rather
		39	+ * than silently swallowed.
		40	+ */
		41	+ fun translate(key: MessageKey, locale: Locale, args: Map<String, Any> = emptyMap()): String
		42	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/package-info.kt 0 → 100644

View file @f516441

		1	+/**
		2	+ * vibe_erp Public Plug-in API v1.
		3	+ *
		4	+ * THE STABILITY CONTRACT
		5	+ * ----------------------
		6	+ * Everything declared under [org.vibeerp.api.v1] is the public, semver-governed
		7	+ * surface of the vibe_erp framework. Plug-in authors depend on this package and
		8	+ * only this package.
		9	+ *
		10	+ * Within the 1.x release line:
		11	+ * • Adding new types is allowed.
		12	+ * • Adding new methods to existing interfaces is allowed ONLY when a default
		13	+ * implementation is provided so existing plug-ins continue to compile and load.
		14	+ * • Renaming, removing, or changing the observable behavior of any symbol is
		15	+ * a breaking change and requires a major-version bump (api.v2).
		16	+ *
		17	+ * Across a major version, the previous major (api.v1) ships side-by-side with
		18	+ * the new major (api.v2) for at least one major release window so plug-in
		19	+ * authors have a real migration path.
		20	+ *
		21	+ * WHAT IS NOT IN HERE
		22	+ * -------------------
		23	+ * Anything not in [org.vibeerp.api.v1] — including everything in
		24	+ * `org.vibeerp.platform.` and `org.vibeerp.pbc.` — is INTERNAL. Plug-ins
		25	+ * that import internal classes are graded "D" (unsupported) and are rejected
		26	+ * by the plug-in linter at install time.
		27	+ *
		28	+ * See `docs/superpowers/specs/2026-04-07-vibe-erp-architecture-design.md`
		29	+ * sections 4 and 6 for the full extensibility model and api.v1 surface plan.
		30	+ */
		31	+package org.vibeerp.api.v1

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/persistence/Page.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.persistence
		2	+
		3	+/**
		4	+ * One page of results returned from [Repository.findAll].
		5	+ *
		6	+ * Why a dedicated type rather than `Pair<List<T>, Long>`:
		7	+ * - Named fields make the wire format and the AI-agent function catalog
		8	+ * self-describing. "What does the second element of the pair mean?" is
		9	+ * the kind of question that makes plug-in authors miserable.
		10	+ * - Adding fields later (e.g. a continuation token for keyset pagination)
		11	+ * is non-breaking. Adding a third tuple element is.
		12	+ *
		13	+ * `totalElements` is intentionally `Long` because some PBCs (audit log,
		14	+ * inventory movements) routinely cross the 32-bit row count.
		15	+ */
		16	+data class Page<T>(
		17	+ val content: List<T>,
		18	+ val pageNumber: Int,
		19	+ val pageSize: Int,
		20	+ val totalElements: Long,
		21	+) {
		22	+ init {
		23	+ require(pageNumber >= 0) { "Page pageNumber must be >= 0 (got $pageNumber)" }
		24	+ require(pageSize >= 1) { "Page pageSize must be >= 1 (got $pageSize)" }
		25	+ require(totalElements >= 0) { "Page totalElements must be >= 0 (got $totalElements)" }
		26	+ }
		27	+
		28	+ /** Number of pages, given [pageSize] and [totalElements]. */
		29	+ val totalPages: Int
		30	+ get() = if (totalElements == 0L) 0 else (((totalElements - 1) / pageSize) + 1).toInt()
		31	+
		32	+ /** Whether at least one more page exists after this one. */
		33	+ val hasNext: Boolean
		34	+ get() = (pageNumber + 1) < totalPages
		35	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/persistence/Query.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.persistence
		2	+
		3	+/**
		4	+ * Declarative query model used by [Repository.findAll].
		5	+ *
		6	+ * Why a structured query object instead of "Spring Data Specification" or a
		7	+ * raw string DSL:
		8	+ * - The whole api.v1 surface is forbidden from leaking Spring types
		9	+ * (CLAUDE.md guardrail #10). Spring Data's `Specification` is out.
		10	+ * - A typed model is what makes the OpenAPI generator and the AI agent
		11	+ * function catalog possible: every supported filter shape is enumerable.
		12	+ * - It can be serialized and shipped over the wire, which is how the
		13	+ * cross-process query path will work when the framework eventually grows
		14	+ * a remote-PBC mode.
		15	+ *
		16	+ * The model is intentionally small — equality, ordering, set membership, a
		17	+ * SQL `LIKE`, null checks, and boolean composition. Anything more exotic
		18	+ * (full-text search, geo, vector) belongs in a dedicated capability behind a
		19	+ * separate api.v1 interface, not bolted onto the generic repository.
		20	+ */
		21	+data class Query(
		22	+ val filters: List<Filter> = emptyList(),
		23	+ val sort: List<SortClause> = emptyList(),
		24	+ val pageRequest: PageRequest = PageRequest.FIRST,
		25	+)
		26	+
		27	+/**
		28	+ * The closed set of supported filter shapes.
		29	+ *
		30	+ * Sealed so the platform can pattern-match exhaustively when translating to
		31	+ * SQL, and so adding a new shape is a deliberate api.v1 change.
		32	+ */
		33	+sealed interface Filter {
		34	+
		35	+ /** Field equals value. `value` may be `null` to match SQL `IS NULL`. */
		36	+ data class Eq(val field: String, val value: Any?) : Filter
		37	+
		38	+ /** Field does not equal value. */
		39	+ data class Ne(val field: String, val value: Any?) : Filter
		40	+
		41	+ /** Field strictly less than value. */
		42	+ data class Lt(val field: String, val value: Any) : Filter
		43	+
		44	+ /** Field strictly greater than value. */
		45	+ data class Gt(val field: String, val value: Any) : Filter
		46	+
		47	+ /** Field value is one of [values]. Empty list matches nothing. */
		48	+ data class In(val field: String, val values: List<Any>) : Filter
		49	+
		50	+ /**
		51	+ * SQL `LIKE` against [pattern]. The pattern uses SQL wildcards (`%`, `_`)
		52	+ * unescaped — callers are responsible for escaping user input.
		53	+ */
		54	+ data class Like(val field: String, val pattern: String) : Filter
		55	+
		56	+ /** Field is `NULL`. */
		57	+ data class IsNull(val field: String) : Filter
		58	+
		59	+ /** Logical conjunction. Empty list is treated as "always true". */
		60	+ data class And(val operands: List<Filter>) : Filter
		61	+
		62	+ /** Logical disjunction. Empty list is treated as "always false". */
		63	+ data class Or(val operands: List<Filter>) : Filter
		64	+
		65	+ /** Logical negation. */
		66	+ data class Not(val operand: Filter) : Filter
		67	+}
		68	+
		69	+/**
		70	+ * Sort directive. Stable across pages — the platform will append a tie-break
		71	+ * on the primary key so pagination is deterministic.
		72	+ */
		73	+data class SortClause(val field: String, val direction: SortDirection = SortDirection.ASC)
		74	+
		75	+/** Sort direction. Two options, no `RANDOM` — randomness is a separate concern. */
		76	+enum class SortDirection { ASC, DESC }
		77	+
		78	+/**
		79	+ * Page coordinates. Zero-indexed for consistency with the rest of the JVM
		80	+ * ecosystem (Spring Data, Hibernate). Maximum page size is enforced by the
		81	+ * platform, not here, because the limit may differ per deployment.
		82	+ */
		83	+data class PageRequest(val page: Int, val size: Int) {
		84	+ init {
		85	+ require(page >= 0) { "PageRequest page must be >= 0 (got $page)" }
		86	+ require(size in 1..10_000) { "PageRequest size must be 1..10000 (got $size)" }
		87	+ }
		88	+
		89	+ companion object {
		90	+ val FIRST = PageRequest(page = 0, size = 50)
		91	+ }
		92	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/persistence/Repository.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.persistence
		2	+
		3	+import org.vibeerp.api.v1.core.Id
		4	+import org.vibeerp.api.v1.entity.Entity
		5	+
		6	+/**
		7	+ * Generic, tenant-scoped repository contract for any [Entity].
		8	+ *
		9	+ * Why this lives in api.v1:
		10	+ * - Plug-ins must be able to persist their own entities without depending on
		11	+ * Spring Data, JPA, or any platform internal class. The platform binds this
		12	+ * interface to a Hibernate-backed implementation per entity at startup.
		13	+ * - It is the cleanest place to enforce the tenant guarantee: **none of these
		14	+ * methods accept a `tenantId`**. The tenant is resolved from the ambient
		15	+ * [org.vibeerp.api.v1.http.RequestContext] (or, in background jobs, from the
		16	+ * job's tenant binding) by the platform. A plug-in cannot read or write
		17	+ * cross-tenant data through this contract — that is the whole point.
		18	+ * - It is generic on `T : Entity` so the type system rejects "wrong-entity"
		19	+ * mistakes at compile time.
		20	+ *
		21	+ * Methods are deliberately few. Anything more sophisticated (joins,
		22	+ * projections, native SQL) is a smell at this layer — model the use case as a
		23	+ * domain service or a query object instead. Adding methods later (with default
		24	+ * implementations) is non-breaking; removing them is not.
		25	+ */
		26	+interface Repository<T : Entity> {
		27	+
		28	+ /**
		29	+ * Find by primary key. Returns `null` when no row exists for the current
		30	+ * tenant — even if a row with that id exists for another tenant. Cross-
		31	+ * tenant reads are unobservable through this API.
		32	+ */
		33	+ fun findById(id: Id<T>): T?
		34	+
		35	+ /**
		36	+ * Run a query and return one page of results. The page descriptor is part
		37	+ * of [query], not a separate parameter, so it travels with the rest of the
		38	+ * query intact (important for paginated AI-agent function calls).
		39	+ */
		40	+ fun findAll(query: Query): Page<T>
		41	+
		42	+ /**
		43	+ * Insert or update. Returning the saved entity (rather than `Unit`) gives
		44	+ * the platform a place to populate generated columns (audit timestamps,
		45	+ * generated ids) before the plug-in sees them again.
		46	+ */
		47	+ fun save(entity: T): T
		48	+
		49	+ /**
		50	+ * Delete by id. Returns `true` if a row was deleted, `false` if no
		51	+ * matching row existed for the current tenant.
		52	+ */
		53	+ fun delete(id: Id<T>): Boolean
		54	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/persistence/Transaction.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.persistence
		2	+
		3	+/**
		4	+ * Plug-in-facing transaction boundary.
		5	+ *
		6	+ * Why this exists instead of "use Spring `@Transactional`":
		7	+ * - api.v1 is forbidden from exposing Spring types (CLAUDE.md guardrail #10).
		8	+ * A plug-in that imports `org.springframework.transaction.annotation.Transactional`
		9	+ * is grade-D and rejected at install time.
		10	+ * - The host needs a single, controlled place to enforce nested-transaction
		11	+ * rules, tenant binding, and outbox flushing across plug-in boundaries.
		12	+ * A method-level annotation cannot do those things from a child Spring
		13	+ * context cleanly.
		14	+ * - It is small enough to be implemented over JTA, Spring TX, or a future
		15	+ * Kotlin coroutines transactional context without an api.v1 change.
		16	+ *
		17	+ * Semantics:
		18	+ * - The block runs in a single platform transaction. If [block] throws, the
		19	+ * transaction rolls back and the exception propagates unchanged.
		20	+ * - Nested calls join the surrounding transaction; they do not start a new
		21	+ * one. Plug-ins that need savepoints must request them through a future
		22	+ * api.v1 extension, not by stacking calls.
		23	+ * - The current tenant and principal are propagated automatically.
		24	+ *
		25	+ * ```
		26	+ * pluginContext.transaction.inTransaction {
		27	+ * val saved = repo.save(plate)
		28	+ * eventBus.publish(PlateApproved(saved.id))
		29	+ * saved
		30	+ * }
		31	+ * ```
		32	+ */
		33	+interface Transaction {
		34	+
		35	+ /**
		36	+ * Run [block] inside a transaction and return its result.
		37	+ *
		38	+ * @param T the type returned by the block. Use `Unit` for side-effect-only
		39	+ * blocks; the host treats `Unit` no differently from any other return
		40	+ * type.
		41	+ */
		42	+ fun <T> inTransaction(block: () -> T): T
		43	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/plugin/ExtensionPoint.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.plugin
		2	+
		3	+import kotlin.reflect.KClass
		4	+
		5	+/**
		6	+ * Marks an interface or abstract class as an extension point: a seam the
		7	+ * core declares so that plug-ins (and other PBCs) can supply implementations.
		8	+ *
		9	+ * Why annotated rather than enforced by base-class inheritance:
		10	+ * - Several extension points are plain interfaces (e.g. a custom field type
		11	+ * handler, a workflow task handler, a report data provider) and forcing
		12	+ * them to extend a marker class would be noise. An annotation lets the
		13	+ * plug-in linter and the OpenAPI generator find them by metadata alone.
		14	+ * - It documents intent at the declaration site: a reader sees
		15	+ * `@ExtensionPoint` and knows "plug-ins are expected to implement this".
		16	+ * - The platform's plug-in loader scans for `@Extension` (below) and
		17	+ * cross-references it to `@ExtensionPoint`-annotated types so a typo
		18	+ * fails at install time, not at first use.
		19	+ */
		20	+@Target(AnnotationTarget.CLASS)
		21	+@Retention(AnnotationRetention.RUNTIME)
		22	+@MustBeDocumented
		23	+annotation class ExtensionPoint
		24	+
		25	+/**
		26	+ * Marks a class as a plug-in's implementation of an [ExtensionPoint].
		27	+ *
		28	+ * The plug-in loader instantiates every `@Extension`-annotated class in the
		29	+ * plug-in's child Spring context, verifies that [point] is itself
		30	+ * `@ExtensionPoint`-annotated, and registers the instance with the matching
		31	+ * platform registry.
		32	+ *
		33	+ * ```
		34	+ * @Extension(point = TaskHandler::class)
		35	+ * class ApprovePlateHandler : TaskHandler { ... }
		36	+ * ```
		37	+ */
		38	+@Target(AnnotationTarget.CLASS)
		39	+@Retention(AnnotationRetention.RUNTIME)
		40	+@MustBeDocumented
		41	+annotation class Extension(
		42	+ /** The extension-point type this class implements. Must be `@ExtensionPoint`-annotated. */
		43	+ val point: KClass<*>,
		44	+)

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/plugin/Plugin.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.plugin
		2	+
		3	+/**
		4	+ * The single entry-class contract every PF4J plug-in implements.
		5	+ *
		6	+ * Why this is in api.v1:
		7	+ * - PF4J's own `Plugin` base class is an internal implementation choice of
		8	+ * the platform-plugins module. Exposing it would tie every plug-in to a
		9	+ * specific PF4J version forever — the textbook reason api.v1 exists.
		10	+ * - The four methods are the bare minimum to manage a plug-in's lifecycle:
		11	+ * identify itself, declare its version, start, and stop. Anything richer
		12	+ * (hot reload, partial reload, health check) is added as default methods
		13	+ * in later 1.x releases without breaking existing plug-ins.
		14	+ *
		15	+ * Lifecycle (architecture spec section 7):
		16	+ * 1. The platform reads the plug-in's `plugin.yml` ([PluginManifest]).
		17	+ * 2. The classloader is created.
		18	+ * 3. The plug-in's entry class (which implements this interface) is
		19	+ * instantiated.
		20	+ * 4. [start] is called once with the [PluginContext]. The plug-in registers
		21	+ * its endpoints, listeners, workflow handlers, etc. on the context.
		22	+ * 5. When the plug-in is disabled or the host shuts down, [stop] is called
		23	+ * once. The plug-in releases any resources it holds. The platform tears
		24	+ * down the child Spring context, the listeners, and the classloader.
		25	+ *
		26	+ * Implementations must be safe to call [stop] without [start] having
		27	+ * succeeded — the platform may invoke it after a partial start failure.
		28	+ */
		29	+interface Plugin {
		30	+
		31	+ /**
		32	+ * Stable plug-in identifier matching `id` in `plugin.yml`. Used as the
		33	+ * key for tenant scoping, table prefixes (`plugin_<id>__*`), permission
		34	+ * scoping, and the URL prefix `/api/v1/plugins/<id>`. Must match the id
		35	+ * in [PluginManifest] — the platform verifies this at start time.
		36	+ */
		37	+ fun id(): String
		38	+
		39	+ /** Semver version of this plug-in build. Reported in admin UIs and audit logs. */
		40	+ fun version(): String
		41	+
		42	+ /**
		43	+ * Called once when the plug-in is being started. The [context] gives
		44	+ * access to every host service the plug-in is allowed to use.
		45	+ *
		46	+ * Throwing from [start] aborts the plug-in load. The platform calls
		47	+ * [stop] afterwards regardless.
		48	+ */
		49	+ fun start(context: PluginContext)
		50	+
		51	+ /**
		52	+ * Called once when the plug-in is being stopped. Implementations should
		53	+ * release resources owned by the plug-in itself; listeners, endpoints,
		54	+ * and Spring beans registered through [PluginContext] are torn down by
		55	+ * the platform automatically.
		56	+ */
		57	+ fun stop()
		58	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/plugin/PluginContext.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.plugin
		2	+
		3	+import org.vibeerp.api.v1.entity.EntityRegistry
		4	+import org.vibeerp.api.v1.event.EventBus
		5	+import org.vibeerp.api.v1.i18n.LocaleProvider
		6	+import org.vibeerp.api.v1.i18n.Translator
		7	+import org.vibeerp.api.v1.persistence.Transaction
		8	+import org.vibeerp.api.v1.security.PermissionCheck
		9	+
		10	+/**
		11	+ * The bag of host services a plug-in receives at [Plugin.start].
		12	+ *
		13	+ * Why a single context object instead of constructor injection of each
		14	+ * service:
		15	+ * - Plug-ins are instantiated by PF4J before any Spring wiring exists, so
		16	+ * constructor injection in the Spring sense is not yet available at
		17	+ * [Plugin.start] time. Handing a context object solves the bootstrapping
		18	+ * problem in one line.
		19	+ * - It is forward-compatible: adding a new host service is a non-breaking
		20	+ * addition to this interface (with a default implementation that throws
		21	+ * `UnsupportedOperationException` — see the per-getter doc).
		22	+ *
		23	+ * The plug-in is free to keep references to whichever services it needs and
		24	+ * pass them into its own Spring beans inside the child context. Holding onto
		25	+ * the entire context is also fine.
		26	+ */
		27	+interface PluginContext {
		28	+
		29	+ /** Publish/subscribe to domain events. Backed by the platform bus + outbox. */
		30	+ val eventBus: EventBus
		31	+
		32	+ /** Run blocks in a platform transaction without ever importing Spring. */
		33	+ val transaction: Transaction
		34	+
		35	+ /** Resolve translations using the host's ICU MessageFormat machinery. */
		36	+ val translator: Translator
		37	+
		38	+ /** Read the current request/job locale. */
		39	+ val localeProvider: LocaleProvider
		40	+
		41	+ /** Soft and hard permission checks. */
		42	+ val permissionCheck: PermissionCheck
		43	+
		44	+ /** Look up entity descriptors (core PBC, plug-in, or user-defined). */
		45	+ val entityRegistry: EntityRegistry
		46	+
		47	+ /**
		48	+ * Lifecycle-bound logger. Always prefer this over `LoggerFactory.getLogger`
		49	+ * because the platform tags every log line with the plug-in id, the
		50	+ * tenant, the request id, and the principal automatically. A plug-in that
		51	+ * brings its own SLF4J binding bypasses all of that and is hard to debug
		52	+ * in a multi-plug-in deployment.
		53	+ */
		54	+ val logger: PluginLogger
		55	+}
		56	+
		57	+/**
		58	+ * Minimal logger interface exposed to plug-ins.
		59	+ *
		60	+ * Why not just expose SLF4J:
		61	+ * - api.v1 forbids leaking external library types (CLAUDE.md guardrail #10).
		62	+ * SLF4J version skew across plug-in classloaders is a real PF4J pain that
		63	+ * a thin abstraction sidesteps entirely.
		64	+ * - The host implementation forwards to whichever logging backend is
		65	+ * configured at the platform layer (Logback today; structured JSON in the
		66	+ * cloud build), without the plug-in choosing.
		67	+ *
		68	+ * Three levels are intentional. `debug` and `trace` are deliberately omitted
		69	+ * from the contract because they encourage chatty plug-ins; if a plug-in
		70	+ * needs verbose diagnostics it should ship its own logger inside the plug-in
		71	+ * jar (which is fine — it just won't get the platform's structured tags).
		72	+ */
		73	+interface PluginLogger {
		74	+ /** Informational message about normal operation. */
		75	+ fun info(message: String)
		76	+
		77	+ /** Something looked wrong but the operation continued. */
		78	+ fun warn(message: String, error: Throwable? = null)
		79	+
		80	+ /** An operation failed. */
		81	+ fun error(message: String, error: Throwable? = null)
		82	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/plugin/PluginManifest.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.plugin
		2	+
		3	+/**
		4	+ * Strongly-typed view of a plug-in's `plugin.yml` manifest.
		5	+ *
		6	+ * Why this is in api.v1 even though plug-ins do not parse it themselves:
		7	+ * - The host parses `plugin.yml` and offers the result to the plug-in via
		8	+ * [PluginContext] (and to admin UIs, the linter, and the marketplace).
		9	+ * Putting the type in api.v1 means every consumer agrees on the schema.
		10	+ * - The schema is part of the public contract: changing a field name in
		11	+ * `plugin.yml` would break every existing plug-in's manifest. Documenting
		12	+ * it as a Kotlin data class is the cheapest way to keep that promise.
		13	+ *
		14	+ * The corresponding YAML shape:
		15	+ *
		16	+ * ```
		17	+ * id: printingshop
		18	+ * version: 1.4.2
		19	+ * requiresApi: "1.x"
		20	+ * name:
		21	+ * en-US: Printing Shop
		22	+ * zh-CN: 印刷工坊
		23	+ * dependencies:
		24	+ * - identity
		25	+ * - catalog
		26	+ * permissions:
		27	+ * - printingshop.plate.create
		28	+ * - printingshop.plate.approve
		29	+ * metadata:
		30	+ * - metadata/forms/plate.json
		31	+ * - metadata/workflows/approval.bpmn
		32	+ * ```
		33	+ *
		34	+ * @property id Stable plug-in id, used everywhere ([Plugin.id], URL prefix,
		35	+ * table prefix, metadata `source` tag).
		36	+ * @property version Plug-in build version. Semver, but the framework does
		37	+ * not enforce it parses — some customers ship date-stamped builds.
		38	+ * @property requiresApi Required api.v1 major version, expressed as a range.
		39	+ * The platform refuses to load a plug-in whose required range does not
		40	+ * include the running host's api version. Today the only supported value
		41	+ * is `"1.x"`; this field exists so the same parser handles `"2.x"` etc.
		42	+ * without an api break.
		43	+ * @property name Locale → display name. Locale codes are BCP-47.
		44	+ * @property dependencies Other plug-in ids that must be present and started
		45	+ * before this plug-in starts. The platform topologically orders startup;
		46	+ * cycles are rejected at install.
		47	+ * @property permissions Keys of the permissions this plug-in declares (see
		48	+ * [org.vibeerp.api.v1.security.Permission]). The platform refuses to start
		49	+ * a plug-in that uses a permission not in this list.
		50	+ * @property metadata JAR-relative paths the platform should load at startup
		51	+ * to seed forms, workflows, rules, list views, and translations.
		52	+ */
		53	+data class PluginManifest(
		54	+ val id: String,
		55	+ val version: String,
		56	+ val requiresApi: String,
		57	+ val name: Map<String, String> = emptyMap(),
		58	+ val dependencies: List<String> = emptyList(),
		59	+ val permissions: List<String> = emptyList(),
		60	+ val metadata: List<String> = emptyList(),
		61	+) {
		62	+ init {
		63	+ require(id.isNotBlank()) { "PluginManifest id must not be blank" }
		64	+ require(id.all { it.isLetterOrDigit() \|\| it == '-' \|\| it == '_' }) {
		65	+ "PluginManifest id may only contain letters, digits, '-', or '_' (got '$id')"
		66	+ }
		67	+ require(version.isNotBlank()) { "PluginManifest version must not be blank" }
		68	+ require(requiresApi.isNotBlank()) { "PluginManifest requiresApi must not be blank" }
		69	+ }
		70	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/security/Permission.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.security
		2	+
		3	+/**
		4	+ * A named permission a plug-in or PBC declares.
		5	+ *
		6	+ * Why permissions are first-class data, not magic strings scattered through
		7	+ * code:
		8	+ * - The role editor in the web UI lists every registered permission so an
		9	+ * administrator can grant it. There is no way to do that if permissions
		10	+ * are unenumerable.
		11	+ * - The OpenAPI generator and the AI-agent function catalog annotate every
		12	+ * operation with the permissions it requires; an LLM that calls the API
		13	+ * can therefore refuse an action up-front rather than discovering the
		14	+ * failure mid-call.
		15	+ * - Plug-ins register their permissions at startup, so uninstalling a
		16	+ * plug-in cleanly removes its permission rows from `metadata__permission`.
		17	+ *
		18	+ * Naming convention is `<plugin-or-pbc>.<resource>.<action>`. Examples:
		19	+ * - `identity.user.create`
		20	+ * - `catalog.item.update`
		21	+ * - `printingshop.plate.approve` (declared by the reference plug-in)
		22	+ *
		23	+ * The convention is enforced by [init], not by mere documentation, because
		24	+ * "we'll fix the names later" never works in a permission catalog.
		25	+ *
		26	+ * @property key The dotted permission identifier. Lower-case, three or more
		27	+ * segments separated by `.`, each segment `[a-z][a-z0-9_]*`.
		28	+ * @property description Human-readable explanation shown in the role editor.
		29	+ * This is a fallback English string; tenants override it through the i18n
		30	+ * layer.
		31	+ * @property pluginId The plug-in that owns this permission, or `null` if it
		32	+ * belongs to a core PBC. The platform uses this to scope cleanup on
		33	+ * plug-in uninstall.
		34	+ */
		35	+data class Permission(
		36	+ val key: String,
		37	+ val description: String,
		38	+ val pluginId: String? = null,
		39	+) {
		40	+ init {
		41	+ require(description.isNotBlank()) { "Permission description must not be blank" }
		42	+ require(KEY_REGEX.matches(key)) {
		43	+ "Permission key must look like '<area>.<resource>.<action>' (got '$key')"
		44	+ }
		45	+ }
		46	+
		47	+ companion object {
		48	+ private val KEY_REGEX = Regex("^[a-z][a-z0-9_](\\.[a-z][a-z0-9_]){2,}$")
		49	+ }
		50	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/security/PermissionCheck.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.security
		2	+
		3	+/**
		4	+ * Plug-in-facing permission check.
		5	+ *
		6	+ * Why this is its own interface instead of "throw whenever you feel like it":
		7	+ * - Permission checks must be enforced at the application-service layer
		8	+ * (not just the HTTP layer) so background jobs, workflow tasks, AI-agent
		9	+ * calls, and direct service-to-service calls all funnel through the same
		10	+ * code path. A plug-in that consults this interface is automatically
		11	+ * correct against every transport.
		12	+ * - The two-method shape ([has] for soft checks, [require] for hard checks)
		13	+ * is deliberate. Plug-ins frequently want to render different UI based
		14	+ * on whether the user can do a thing, and that case must not throw.
		15	+ *
		16	+ * The platform binds this to the active [Principal] from
		17	+ * [org.vibeerp.api.v1.http.RequestContext] so plug-ins almost never need to
		18	+ * pass a principal explicitly — but the explicit form exists because some
		19	+ * legitimate flows (impersonation, "act as", scheduled jobs queued by user A
		20	+ * but executed by the system) need to ask the question for a different
		21	+ * principal than the ambient one.
		22	+ */
		23	+interface PermissionCheck {
		24	+
		25	+ /**
		26	+ * Soft check: returns whether [principal] currently holds [permission].
		27	+ * Never throws on a denial.
		28	+ */
		29	+ fun has(principal: Principal, permission: Permission): Boolean
		30	+
		31	+ /**
		32	+ * Hard check: throws [PermissionDeniedException] if [principal] does not
		33	+ * hold [permission]. Returns normally otherwise. Use this at the entry
		34	+ * point of any state-changing operation a plug-in exposes.
		35	+ */
		36	+ fun require(principal: Principal, permission: Permission) {
		37	+ if (!has(principal, permission)) {
		38	+ throw PermissionDeniedException(principal, permission)
		39	+ }
		40	+ }
		41	+}
		42	+
		43	+/**
		44	+ * Thrown by [PermissionCheck.require] when a principal lacks a permission.
		45	+ *
		46	+ * The two fields ([principal], [permission]) are exposed because the platform's
		47	+ * HTTP error mapper turns this exception into a structured 403 response that
		48	+ * includes the missing permission key — important for debuggability and for
		49	+ * AI agents that need to ask the user to grant access.
		50	+ */
		51	+class PermissionDeniedException(
		52	+ val principal: Principal,
		53	+ val permission: Permission,
		54	+) : RuntimeException("Principal ${principal.id} lacks permission '${permission.key}'")

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/security/Principal.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.security
		2	+
		3	+import org.vibeerp.api.v1.core.Id
		4	+import org.vibeerp.api.v1.core.TenantId
		5	+
		6	+/**
		7	+ * Type alias for a principal identifier.
		8	+ *
		9	+ * Distinct phantom-typed alias of [Id] so signatures like `createdBy: PrincipalId`
		10	+ * are self-documenting in IDE hovers and so the compiler refuses to mix a
		11	+ * `PrincipalId` with, say, an `Id<Order>`.
		12	+ */
		13	+typealias PrincipalId = Id<Principal>
		14	+
		15	+/**
		16	+ * Who is making a request.
		17	+ *
		18	+ * vibe_erp recognizes three kinds of caller, and they all have legitimate
		19	+ * audit, permission, and event-attribution needs:
		20	+ *
		21	+ * - [User]: a human (or an AI agent acting on behalf of a human, which is
		22	+ * still a [User] in this model — the agent does not get its own principal
		23	+ * type, which would let it circumvent per-user permissions).
		24	+ * - [System]: the framework itself, e.g. background jobs, migrations, the
		25	+ * metadata seeder. Recorded in audit logs as `system:<name>` so an auditor
		26	+ * can tell automation from a human.
		27	+ * - [PluginPrincipal]: a plug-in acting under its own identity, used for
		28	+ * plug-in-to-plug-in calls and for bookkeeping rows the plug-in writes
		29	+ * without a user request (e.g. a periodic sync from an external system).
		30	+ *
		31	+ * Sealed because the framework needs to switch on the full set in audit and
		32	+ * permission code; new principal kinds are deliberate api.v1 changes.
		33	+ */
		34	+sealed interface Principal {
		35	+
		36	+ /** This principal's stable id, used as a foreign key in audit columns. */
		37	+ val id: PrincipalId
		38	+
		39	+ /**
		40	+ * The tenant the principal is acting in. A [User] always has one. A
		41	+ * [System] principal uses [TenantId.DEFAULT] for global jobs and a
		42	+ * specific tenant for per-tenant jobs. A [PluginPrincipal] uses the
		43	+ * tenant of the operation it is performing.
		44	+ */
		45	+ val tenantId: TenantId
		46	+
		47	+ /**
		48	+ * A real human user (or an AI agent acting on a human's behalf, which the
		49	+ * framework intentionally does not distinguish at the principal level).
		50	+ */
		51	+ data class User(
		52	+ override val id: PrincipalId,
		53	+ override val tenantId: TenantId,
		54	+ val username: String,
		55	+ ) : Principal {
		56	+ init {
		57	+ require(username.isNotBlank()) { "User username must not be blank" }
		58	+ }
		59	+ }
		60	+
		61	+ /**
		62	+ * The framework itself. [name] is a short identifier of which subsystem
		63	+ * is acting (e.g. `metadata-seeder`, `outbox-drain`).
		64	+ */
		65	+ data class System(
		66	+ override val id: PrincipalId,
		67	+ override val tenantId: TenantId,
		68	+ val name: String,
		69	+ ) : Principal {
		70	+ init {
		71	+ require(name.isNotBlank()) { "System name must not be blank" }
		72	+ }
		73	+ }
		74	+
		75	+ /** A plug-in acting under its own identity. */
		76	+ data class PluginPrincipal(
		77	+ override val id: PrincipalId,
		78	+ override val tenantId: TenantId,
		79	+ val pluginId: String,
		80	+ ) : Principal {
		81	+ init {
		82	+ require(pluginId.isNotBlank()) { "PluginPrincipal pluginId must not be blank" }
		83	+ }
		84	+ }
		85	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/workflow/TaskHandler.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.workflow
		2	+
		3	+/**
		4	+ * Implementation contract for a single workflow task type.
		5	+ *
		6	+ * Why this is the only workflow seam in v1.0:
		7	+ * - Workflows are data, not code (CLAUDE.md guardrail #2). The shape of a
		8	+ * workflow lives in BPMN; the only thing a plug-in legitimately needs to
		9	+ * write in code is the body of a service task. That is exactly what
		10	+ * [TaskHandler] models.
		11	+ * - It deliberately does not expose the Flowable `DelegateExecution` type,
		12	+ * because doing so would couple every plug-in to a specific Flowable
		13	+ * version forever. The platform adapts Flowable to this api.v1 shape
		14	+ * inside its workflow host module.
		15	+ *
		16	+ * Plug-ins register handlers via the `@org.vibeerp.api.v1.plugin.Extension`
		17	+ * annotation pointing at this interface, and the platform routes incoming
		18	+ * Flowable service-task executions to the handler whose [key] matches.
		19	+ *
		20	+ * ```
		21	+ * @Extension(point = TaskHandler::class)
		22	+ * class ApprovePlate : TaskHandler {
		23	+ * override fun key() = "printingshop.plate.approve"
		24	+ * override fun execute(task: WorkflowTask, ctx: TaskContext) {
		25	+ * val plateId = task.variables["plateId"] as String
		26	+ * // domain logic …
		27	+ * ctx.set("approved", true)
		28	+ * }
		29	+ * }
		30	+ * ```
		31	+ */
		32	+interface TaskHandler {
		33	+
		34	+ /**
		35	+ * The BPMN service-task key this handler claims. Convention is
		36	+ * `<plugin-id>.<aggregate>.<verb>`. Two handlers in the same running
		37	+ * deployment must not return the same key — the platform fails plug-in
		38	+ * load on conflict.
		39	+ */
		40	+ fun key(): String
		41	+
		42	+ /**
		43	+ * Execute the task. The implementation may write output variables via
		44	+ * [ctx]. Throwing aborts the workflow with a Flowable BPMN error,
		45	+ * which the surrounding process model can catch.
		46	+ */
		47	+ fun execute(task: WorkflowTask, ctx: TaskContext)
		48	+}
		49	+
		50	+/**
		51	+ * Mutable side of a task execution: the only way a [TaskHandler] writes
		52	+ * variables back into the workflow.
		53	+ *
		54	+ * Why a small interface instead of "return a Map":
		55	+ * - The host wants to know which variables a handler set (for audit) and
		56	+ * in what order (for diagnostic logging). A returned map loses both.
		57	+ * - It leaves room to grow methods like `signal(eventName)` and
		58	+ * `complete()` without changing the handler's signature.
		59	+ */
		60	+interface TaskContext {
		61	+
		62	+ /**
		63	+ * Set a process variable. The value is persisted by the workflow engine
		64	+ * under the same transaction as the surrounding task execution.
		65	+ * Passing `null` removes the variable.
		66	+ */
		67	+ fun set(name: String, value: Any?)
		68	+}

api/api-v1/src/main/kotlin/org/vibeerp/api/v1/workflow/WorkflowTask.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.workflow
		2	+
		3	+/**
		4	+ * Description of a workflow task instance the host hands to a [TaskHandler].
		5	+ *
		6	+ * Why this is in v1.0 even though the full workflow API is v0.2:
		7	+ * - The reference printing-shop plug-in is the executable acceptance test
		8	+ * (CLAUDE.md, "The reference plug-in is the executable acceptance test"),
		9	+ * and that plug-in needs to register at least one task handler against
		10	+ * the embedded Flowable engine. v1.0 ships the smallest possible
		11	+ * contract that lets the plug-in do that.
		12	+ * - The richer surface (signal/timer events, sub-processes, candidate
		13	+ * groups, business calendars) lands in v0.2 of the api.v1 line as
		14	+ * purely additive interfaces. None of it changes the shape below.
		15	+ *
		16	+ * @property taskKey The BPMN element id (`<serviceTask id="...">`) that
		17	+ * triggered this handler. A single handler may be wired to several keys
		18	+ * inside one process; matching is performed by the host based on
		19	+ * [TaskHandler.key] and the BPMN definition.
		20	+ * @property processInstanceId Flowable's process-instance id, opaque to the
		21	+ * plug-in. Useful for log correlation and for callbacks back into the
		22	+ * workflow engine.
		23	+ * @property variables The current process variables visible to this task.
		24	+ * The map is read-only — to write back, the handler uses
		25	+ * [TaskContext.set] which routes through Flowable so the variables are
		26	+ * persisted under the right transaction.
		27	+ */
		28	+data class WorkflowTask(
		29	+ val taskKey: String,
		30	+ val processInstanceId: String,
		31	+ val variables: Map<String, Any?> = emptyMap(),
		32	+) {
		33	+ init {
		34	+ require(taskKey.isNotBlank()) { "WorkflowTask taskKey must not be blank" }
		35	+ require(processInstanceId.isNotBlank()) { "WorkflowTask processInstanceId must not be blank" }
		36	+ }
		37	+}

api/api-v1/src/test/kotlin/org/vibeerp/api/v1/core/IdentifiersTest.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.core
		2	+
		3	+import assertk.assertFailure
		4	+import assertk.assertThat
		5	+import assertk.assertions.isEqualTo
		6	+import org.junit.jupiter.api.Test
		7	+
		8	+class IdentifiersTest {
		9	+
		10	+ @Test
		11	+ fun `TenantId rejects blank`() {
		12	+ assertFailure { TenantId("") }
		13	+ assertFailure { TenantId(" ") }
		14	+ }
		15	+
		16	+ @Test
		17	+ fun `TenantId rejects too-long values`() {
		18	+ val tooLong = "a".repeat(65)
		19	+ assertFailure { TenantId(tooLong) }
		20	+ }
		21	+
		22	+ @Test
		23	+ fun `TenantId rejects invalid characters`() {
		24	+ assertFailure { TenantId("acme corp") } // space
		25	+ assertFailure { TenantId("acme.corp") } // dot
		26	+ assertFailure { TenantId("acme/corp") } // slash
		27	+ assertFailure { TenantId("acme!") } // punctuation
		28	+ }
		29	+
		30	+ @Test
		31	+ fun `TenantId accepts the default tenant id`() {
		32	+ assertThat(TenantId("default").value).isEqualTo("default")
		33	+ assertThat(TenantId.DEFAULT.value).isEqualTo("default")
		34	+ }
		35	+
		36	+ @Test
		37	+ fun `TenantId accepts hyphens digits and underscores`() {
		38	+ assertThat(TenantId("tenant-1").value).isEqualTo("tenant-1")
		39	+ assertThat(TenantId("acme_2").value).isEqualTo("acme_2")
		40	+ assertThat(TenantId("ACME").value).isEqualTo("ACME")
		41	+ }
		42	+}

api/api-v1/src/test/kotlin/org/vibeerp/api/v1/core/MoneyTest.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.core
		2	+
		3	+import assertk.assertFailure
		4	+import assertk.assertThat
		5	+import assertk.assertions.isEqualTo
		6	+import assertk.assertions.messageContains
		7	+import org.junit.jupiter.api.Test
		8	+import java.math.BigDecimal
		9	+
		10	+class MoneyTest {
		11	+
		12	+ @Test
		13	+ fun `adding two USD amounts produces a USD amount`() {
		14	+ val a = Money(BigDecimal("10.00"), Currency.USD)
		15	+ val b = Money(BigDecimal("2.50"), Currency.USD)
		16	+
		17	+ val sum = a + b
		18	+
		19	+ assertThat(sum).isEqualTo(Money(BigDecimal("12.50"), Currency.USD))
		20	+ }
		21	+
		22	+ @Test
		23	+ fun `adding USD to EUR throws`() {
		24	+ val usd = Money(BigDecimal("10.00"), Currency.USD)
		25	+ val eur = Money(BigDecimal("10.00"), Currency.EUR)
		26	+
		27	+ assertFailure { usd + eur }.messageContains("different currencies")
		28	+ }
		29	+
		30	+ @Test
		31	+ fun `JPY rejects fractional amounts because its default fraction digits is zero`() {
		32	+ // JPY has 0 fraction digits — anything with a non-zero scale is wrong.
		33	+ assertFailure { Money(BigDecimal("100.50"), Currency.JPY) }
		34	+ .messageContains("scale")
		35	+
		36	+ // A whole-yen amount is fine.
		37	+ val whole = Money(BigDecimal("100"), Currency.JPY)
		38	+ assertThat(whole.amount).isEqualTo(BigDecimal("100"))
		39	+ }
		40	+}

api/api-v1/src/test/kotlin/org/vibeerp/api/v1/persistence/QueryTest.kt 0 → 100644

View file @f516441

		1	+package org.vibeerp.api.v1.persistence
		2	+
		3	+import assertk.assertThat
		4	+import assertk.assertions.isEqualTo
		5	+import assertk.assertions.isInstanceOf
		6	+import org.junit.jupiter.api.Test
		7	+
		8	+class QueryTest {
		9	+
		10	+ @Test
		11	+ fun `every Filter shape can be constructed`() {
		12	+ val filters: List<Filter> = listOf(
		13	+ Filter.Eq("name", "Acme"),
		14	+ Filter.Ne("status", "DELETED"),
		15	+ Filter.Lt("price", 100),
		16	+ Filter.Gt("price", 1),
		17	+ Filter.In("category", listOf("a", "b", "c")),
		18	+ Filter.Like("name", "Ac%"),
		19	+ Filter.IsNull("deleted_at"),
		20	+ Filter.And(listOf(Filter.Eq("a", 1), Filter.Eq("b", 2))),
		21	+ Filter.Or(listOf(Filter.Eq("a", 1), Filter.Eq("b", 2))),
		22	+ Filter.Not(Filter.Eq("flag", true)),
		23	+ )
		24	+
		25	+ assertThat(filters.size).isEqualTo(10)
		26	+ }
		27	+
		28	+ @Test
		29	+ fun `Filter hierarchy can be exhaustively pattern-matched`() {
		30	+ // The point of sealing Filter is that this `when` is exhaustive without
		31	+ // an `else` branch. If a new variant is added without updating this
		32	+ // test, the compiler fails — which is exactly the safety net we want.
		33	+ fun describe(f: Filter): String = when (f) {
		34	+ is Filter.Eq -> "eq"
		35	+ is Filter.Ne -> "ne"
		36	+ is Filter.Lt -> "lt"
		37	+ is Filter.Gt -> "gt"
		38	+ is Filter.In -> "in"
		39	+ is Filter.Like -> "like"
		40	+ is Filter.IsNull -> "isnull"
		41	+ is Filter.And -> "and"
		42	+ is Filter.Or -> "or"
		43	+ is Filter.Not -> "not"
		44	+ }
		45	+
		46	+ assertThat(describe(Filter.Eq("a", 1))).isEqualTo("eq")
		47	+ assertThat(describe(Filter.IsNull("x"))).isEqualTo("isnull")
		48	+ assertThat(describe(Filter.Not(Filter.Eq("a", 1)))).isEqualTo("not")
		49	+ }
		50	+
		51	+ @Test
		52	+ fun `Query default values are usable as-is`() {
		53	+ val q = Query()
		54	+ assertThat(q.filters).isEqualTo(emptyList<Filter>())
		55	+ assertThat(q.sort).isEqualTo(emptyList<SortClause>())
		56	+ assertThat(q.pageRequest).isEqualTo(PageRequest.FIRST)
		57	+ }
		58	+
		59	+ @Test
		60	+ fun `SortClause carries field and direction`() {
		61	+ val s = SortClause("created_at", SortDirection.DESC)
		62	+ assertThat(s.field).isEqualTo("created_at")
		63	+ assertThat(s.direction).isEqualTo(SortDirection.DESC)
		64	+ }
		65	+
		66	+ @Test
		67	+ fun `nested boolean filters compose`() {
		68	+ val nested: Filter = Filter.And(
		69	+ listOf(
		70	+ Filter.Or(listOf(Filter.Eq("status", "OPEN"), Filter.Eq("status", "PENDING"))),
		71	+ Filter.Not(Filter.IsNull("assignee")),
		72	+ )
		73	+ )
		74	+ assertThat(nested).isInstanceOf(Filter.And::class)
		75	+ }
		76	+}