feat(form-builder): form_field_configs relational table + non-validation key split + drop validation_rules JSON columns
This commit is contained in:
@@ -176,6 +176,16 @@ WS-5b splitst `form_fields.validation_rules` en `form_field_library.validation_r
|
||||
|
||||
**Strict validator op save (commit 3).** De vier FormRequests (`StoreFormFieldRequest`, `UpdateFormFieldRequest`, `StoreFormFieldLibraryRequest`, `UpdateFormFieldLibraryRequest`) accepteren `validation_rules` nu als array-of-spec-objects (`[{rule_type, parameters, error_message_key?}, ...]`). Semantische validatie (enum-case + parameter-shape + callback-registry) loopt via `FormFieldValidationRuleService::assertSpecsValid()` in een `after()` hook, zodat bad specs 422 geven vóór enige write. Controllers schrijven niet langer `validation_rules` naar de JSON-kolom; writes gaan uitsluitend via `replaceRules()`.
|
||||
|
||||
**Configs-tabel landing (commit 5).** `form_field_configs` is de parallelle tabel voor non-validation configuratie — `tag_categories` (TAG_PICKER-opties filter) en `storage_disk` (upload disk selector). Zelfde polymorphic-morph shape, eigen `FormFieldConfigType` enum, eigen `FormFieldConfigService`, eigen `FormFieldConfigScope`. De backfill-migratie pickt deze twee keys uit de pre-WS-5b JSON bag (die commit 2 welbewust skipte) en plaatst ze in `form_field_configs` vóór de JSON-kolomdrop in `2026_04_25_120002`. De hernoemde `FormFieldChildTablesCascadeObserver` dekt nu drie child-tabellen (bindings, validation_rules, configs) op owner delete.
|
||||
|
||||
**Drie scope-siblings.** `FormFieldBindingScope` + `FormFieldValidationRuleScope` + `FormFieldConfigScope` — dezelfde UNION-over-two-owner-chains shape, drie near-duplicaten. Base-class extractie blijft uitgesteld tot WS-5d waar `form_field_options` als vierde sibling landt en het echte "wat varieert" zichtbaar zou moeten worden. Abstractie uit drie kopieën is nog steeds premature wanneer de vierde concrete implementatie aanstaande is.
|
||||
|
||||
**Breaking change frontend-contract (commit 5).** De JSON-contract wijziging landde atomair in commit 5 — geen bridging compatibility layer per de "Breaking change acceptance" clause in ARCH-FORM-BUILDER §0. Vier portal Vue-componenten gemigreerd naar de canonieke key-namen (`min_value`/`max_value`/`max_length`/`max_selected`). De `tag_categories` / `storage_disk` reads in resources bleven binnen de backend — de portal SPA had deze keys niet direct in gebruik, dus de hypothetische `field.configs.tag_categories.categories` frontend-migratie bleef beperkt tot documentatie (ARCH §17.5.5) tot een frontend consumer het aanroept.
|
||||
|
||||
**JSON-kolommen gedropt.** `form_fields.validation_rules` en `form_field_library.validation_rules` dropten in `2026_04_25_120002`. SCHEMA.md v2.4 verwerkte de drop plus de nieuwe `form_field_configs`-sectie; ARCH-FORM-BUILDER bumped naar v1.6 met een volledig nieuwe §17.5. De rollback-path "roll back WS-5b commits 1–5 together" reconstrueert beide JSON-bag bestemmingen mergen validatie-rules en configs terug naar één bag per rij — niet te verwarren met de per-migratie partial rollback die niet ondersteund is.
|
||||
|
||||
**Afronding WS-5b.** 5 commits, baseline tests 1047 → volledig groen na commit 5. WS-5b is hiermee compleet; scope-sibling extractie en WS-5c (`conditional_logic`) / WS-5d (`options`) zijn separate work packages.
|
||||
|
||||
---
|
||||
|
||||
## Q4 — Sanctum `personal_access_tokens`
|
||||
@@ -289,5 +299,6 @@ WS-1 rapport Categorie D bevindingen die geen architect-beslissing vereisten en
|
||||
- **Architect review:** akkoord per Claude Chat sessie 2026-04-24, iteratief verscherpt over drie rondes (initial → strict-enterprise op Q1/Q3 → FK-chain correctie op Q2).
|
||||
- **Product owner:** akkoord per Bert Hausmans 2026-04-24.
|
||||
- **WS-5a afronding:** 2026-04-24 — relationele `form_field_bindings` tabel, polymorphic owner, snapshot-parity, JSON-kolommen gedropt.
|
||||
- **WS-5b afronding:** 2026-04-25 — relationele `form_field_validation_rules` + parallel `form_field_configs` tabel; `validation_rules` JSON-kolommen gedropt; frontend-contract migratie naar canonieke key-namen landed in commit 5.
|
||||
|
||||
Volgende stap: prompt opstellen voor WS-2 (Purpose registry) met Q6-consolidatie als integraal onderdeel van de werkstroom.
|
||||
|
||||
@@ -1,13 +1,19 @@
|
||||
# ARCH — Universal Form Builder (v1.5)
|
||||
# ARCH — Universal Form Builder (v1.6)
|
||||
|
||||
> **Source of truth** for Crewli's universal Form Builder architecture.
|
||||
> Any discrepancy with SCHEMA.md is resolved in favour of this document
|
||||
> during the refactor. SCHEMA.md is updated at the end of the refactor.
|
||||
>
|
||||
> **Status:** Approved — WS-5a landed (relational `form_field_bindings`);
|
||||
> WS-5b validation rules landed (relational `form_field_validation_rules`).
|
||||
> **Version:** 1.5 (§17.4 restructured into relational sub-sections:
|
||||
> catalogue, relational table, callback rules, legacy JSON migration).
|
||||
> WS-5b landed in full (relational `form_field_validation_rules` and
|
||||
> parallel `form_field_configs`; pre-WS-5b `validation_rules` JSON
|
||||
> columns dropped).
|
||||
> **Version:** 1.6 (new §17.5 "Field configuration (non-validation)" for
|
||||
> the `form_field_configs` split; §17.4.4 updated with the
|
||||
> non-validation-key relocation note).
|
||||
> **Previous:**
|
||||
> 1.5 (§17.4 restructured into relational sub-sections: catalogue,
|
||||
> relational table, callback rules, legacy JSON migration).
|
||||
> **Previous versions:**
|
||||
> 1.4 (§6.3 retitled to "Binding row specification"; new §6.7 "Relational
|
||||
> binding table"; §17.3 pre-publish check in present tense per WS-5a),
|
||||
@@ -2410,13 +2416,112 @@ Those rows are immutable records and are not rewritten by the
|
||||
migration. Snapshot readers must tolerate both shapes — pre-WS-5b
|
||||
legacy keys and post-WS-5b canonical keys.
|
||||
|
||||
### 17.5 Webhooks
|
||||
### 17.5 Field configuration (non-validation)
|
||||
|
||||
#### 17.5.1 Schema
|
||||
Per-field configuration that is *not* validation (tag-picker category
|
||||
filters, upload disk selection) lives in the relational
|
||||
`form_field_configs` table — a deliberate sibling to §17.4's
|
||||
`form_field_validation_rules`, not a merger. Two tables with clear
|
||||
semantics beat one table that drifts into "bucket for everything that
|
||||
doesn't fit elsewhere".
|
||||
|
||||
#### 17.5.1 Why this is separate from `validation_rules`
|
||||
|
||||
Pre-WS-5b, `form_fields.validation_rules` was a grab-bag that held
|
||||
validation *and* non-validation keys. Keeping the non-validation keys
|
||||
in a table named `form_field_validation_rules` would have poisoned that
|
||||
table's meaning and re-introduced the drift WS-5 was cleaning up. The
|
||||
strict-enterprise resolution on the Q3 WS-5b decision gate was: split
|
||||
the non-validation keys into their own relational home with matching
|
||||
semantics ("table name = table contents"), at the cost of one extra
|
||||
table, one extra enum, one extra service, one extra scope. The
|
||||
architecture decision log is in
|
||||
`/dev-docs/ARCH-CONSOLIDATION-ADDENDUM-2026-04-24.md` §Q3 WS-5b
|
||||
Uitvoering.
|
||||
|
||||
#### 17.5.2 Table `form_field_configs` and config-type catalogue
|
||||
|
||||
**Columns** (SCHEMA.md §3.5.12):
|
||||
|
||||
| Column | Type | Notes |
|
||||
| -------------- | ----------------- | ---------------------------------------------------------- |
|
||||
| `id` | ULID | PK |
|
||||
| `owner_type` | string(40) | morph alias: `form_field` or `form_field_library` |
|
||||
| `owner_id` | ULID | parent row |
|
||||
| `config_type` | string(40) | enum case value |
|
||||
| `parameters` | JSON | per-config-type bag |
|
||||
| `created_at`, `updated_at` | timestamps | |
|
||||
|
||||
**Catalogue (`FormFieldConfigType`):**
|
||||
|
||||
| `config_type` | `parameters` shape | Consumed by |
|
||||
| ----------------- | ------------------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `tag_categories` | `{"categories": [string]}` | `FormFieldResource` + `PublicFormSchemaResource` — filters `person_tags` options for TAG_PICKER fields |
|
||||
| `storage_disk` | `{"disk": string}` | `FormValueService` (file-upload handling — WS-6) — overrides the default filesystem disk |
|
||||
|
||||
Both config types are app-enforced, not DB enum — same rationale as
|
||||
§17.4.1 (runtime extensibility via registry).
|
||||
|
||||
#### 17.5.3 Service, scope, cascade, activity log
|
||||
|
||||
Mirrors §17.4's validation-rules stack one-for-one:
|
||||
|
||||
- **Service boundary** (`FormFieldConfigService`) — `configsFor`,
|
||||
`replaceConfigs`, `copyConfigs`, `toJsonShape`, `assertSpecsValid`.
|
||||
Single writer; all controller paths go through it.
|
||||
- **Multi-tenancy** (`FormFieldConfigScope`) — third near-duplicate of
|
||||
`FormFieldBindingScope`. The three siblings' base-class extraction is
|
||||
deferred to WS-5d per addendum Q3 (abstracting from three is still
|
||||
premature when the fourth sibling is about to land and may clarify
|
||||
what truly varies).
|
||||
- **Cascade** — shared `FormFieldChildTablesCascadeObserver` (renamed
|
||||
from `FormFieldBindingsCascadeObserver` in WS-5b commit 1) covers
|
||||
all three relational tables on owner delete.
|
||||
- **Activity log** — two entries emit on config changes on a
|
||||
FormField subject: `field.updated` (reconstructed `configs` via
|
||||
`toJsonShape`) and `field.configs_replaced` (semantic event). Matches
|
||||
the §6.7 / §17.4.2 pattern. Library-level changes are silent in
|
||||
activity log; consumers that need them listen at a different layer.
|
||||
|
||||
#### 17.5.4 Snapshot embedding
|
||||
|
||||
`form_submissions.schema_snapshot.fields[*]` gains a top-level `configs`
|
||||
key alongside `validation_rules`:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "01H...",
|
||||
"slug": "vaardigheden",
|
||||
"field_type": "TAG_PICKER",
|
||||
"validation_rules": null,
|
||||
"configs": { "tag_categories": { "categories": ["Veiligheid"] } },
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Historical snapshots written before WS-5b commit 5 continue to embed
|
||||
the merged shape (`validation_rules: {"tag_categories": [...], "min":
|
||||
3}`) with no `configs` key — those rows are immutable records. Readers
|
||||
must tolerate both shapes.
|
||||
|
||||
#### 17.5.5 External API contract change
|
||||
|
||||
WS-5b commit 5 is a breaking change to the form-field JSON contract.
|
||||
Pre-WS-5b: `field.validation_rules.tag_categories`. Post-WS-5b:
|
||||
`field.configs.tag_categories.categories`. Same for `storage_disk`.
|
||||
The portal + organizer SPAs are updated in the same work package
|
||||
(WS-5b commit 5); there is no bridging compatibility layer. See the
|
||||
"Breaking change acceptance" note at the top of this document.
|
||||
|
||||
---
|
||||
|
||||
### 17.6 Webhooks
|
||||
|
||||
#### 17.6.1 Schema
|
||||
|
||||
See §4.11 `form_schema_webhooks` and §4.12 `form_webhook_deliveries`.
|
||||
|
||||
#### 17.5.2 Dispatcher
|
||||
#### 17.6.2 Dispatcher
|
||||
|
||||
`FormWebhookDispatcher` listens for FormSubmissionSubmitted / Reviewed /
|
||||
SectionSubmitted / SectionReviewed events. On trigger:
|
||||
@@ -2424,7 +2529,7 @@ SectionSubmitted / SectionReviewed events. On trigger:
|
||||
- For each: creates a form_webhook_delivery row with status=pending
|
||||
- Queues `DeliverFormWebhookJob` per delivery on dedicated `webhooks` queue
|
||||
|
||||
#### 17.5.3 Delivery job
|
||||
#### 17.6.3 Delivery job
|
||||
|
||||
`DeliverFormWebhookJob` on `webhooks` queue:
|
||||
- Idempotent (Laravel job with unique ID per delivery)
|
||||
@@ -2443,7 +2548,7 @@ SectionSubmitted / SectionReviewed events. On trigger:
|
||||
Response body first 1000 chars stored in `response_body_excerpt` for
|
||||
debugging.
|
||||
|
||||
#### 17.5.4 Security
|
||||
#### 17.6.4 Security
|
||||
|
||||
URL validation in `FormWebhookDispatcher`:
|
||||
- Parse URL; reject non-http(s)
|
||||
@@ -2455,7 +2560,7 @@ URL validation in `FormWebhookDispatcher`:
|
||||
|
||||
Admin UI shows validation status + last delivery attempt per webhook.
|
||||
|
||||
#### 17.5.5 Webhook payload format
|
||||
#### 17.6.5 Webhook payload format
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
@@ -1,10 +1,26 @@
|
||||
# Crewli — Core Database Schema
|
||||
|
||||
> Source: Design Document v1.3 — Section 3.5
|
||||
> **Version: 2.3** — Updated April 2026
|
||||
> **Version: 2.4** — Updated April 2026
|
||||
>
|
||||
> **Changelog:**
|
||||
>
|
||||
> - v2.4: WS-5b completion — `form_field_configs` relational table lands
|
||||
> alongside `form_field_validation_rules` (both from WS-5b). Holds
|
||||
> non-validation per-field configuration (`tag_categories`,
|
||||
> `storage_disk`) that would have polluted the validation-rules table
|
||||
> had it stayed there. Same polymorphic-morph pattern (owner aliases
|
||||
> `form_field` / `form_field_library`, reused from WS-5a). The
|
||||
> `validation_rules` JSON columns on `form_fields` and
|
||||
> `form_field_library` are **dropped** by this migration pair — the
|
||||
> entire pre-WS-5b bag now lives relationally across two tables.
|
||||
> Schema snapshots gain a parallel top-level `configs` key on each
|
||||
> field entry; historical snapshots pre-WS-5b remain immutable with
|
||||
> the legacy merged shape. Breaking frontend contract: portal +
|
||||
> organizer SPAs switched from reading `field.validation_rules.min`
|
||||
> etc. to the canonical post-WS-5b keys (`min_value`, `max_length`,
|
||||
> `max_selected`, etc.) per ARCH v1.6 §17.5 and addendum Q3 WS-5b
|
||||
> Uitvoering.
|
||||
> - v2.3: WS-5b (partial) — `form_field_validation_rules` relational table
|
||||
> replaces the `validation_rules` JSON on `form_fields` and
|
||||
> `form_field_library`. Typed `rule_type` column + per-rule `parameters`
|
||||
@@ -1989,7 +2005,7 @@ that aggregates the user's submitted, non-test `form_submissions`.
|
||||
| `is_active` | bool | default: true |
|
||||
| `created_at`, `updated_at` | timestamps | |
|
||||
|
||||
**Relations:** `belongsTo` organisation; `hasMany` form_fields via `library_field_id`; `morphMany` form_field_bindings as `owner`; `morphMany` form_field_validation_rules as `owner`
|
||||
**Relations:** `belongsTo` organisation; `hasMany` form_fields via `library_field_id`; `morphMany` form_field_bindings as `owner`; `morphMany` form_field_validation_rules as `owner`; `morphMany` form_field_configs as `owner`
|
||||
**Indexes:** `(organisation_id, field_type)`, `(organisation_id, is_active)`
|
||||
**Unique constraint:** `UNIQUE(organisation_id, slug)`
|
||||
**Global scope:** `OrganisationScope`
|
||||
@@ -2045,7 +2061,7 @@ that aggregates the user's submitted, non-test `form_submissions`.
|
||||
| `created_at`, `updated_at` | timestamps | |
|
||||
| `deleted_at` | timestamp nullable | Soft delete preserves history |
|
||||
|
||||
**Relations:** `belongsTo` schema, section (nullable), libraryField; `hasMany` form_values; `morphMany` form_field_bindings as `owner`; `morphMany` form_field_validation_rules as `owner`
|
||||
**Relations:** `belongsTo` schema, section (nullable), libraryField; `hasMany` form_values; `morphMany` form_field_bindings as `owner`; `morphMany` form_field_validation_rules as `owner`; `morphMany` form_field_configs as `owner`
|
||||
**Indexes:** `(form_schema_id, sort_order)`, `(form_schema_id, is_filterable)`, `(library_field_id)`, `(form_schema_id, slug)`
|
||||
**Soft delete:** yes
|
||||
|
||||
@@ -2124,6 +2140,32 @@ that aggregates the user's submitted, non-test `form_submissions`.
|
||||
|
||||
---
|
||||
|
||||
### `form_field_configs`
|
||||
|
||||
> Parallel sibling to `form_field_validation_rules` — holds
|
||||
> non-validation per-field configuration (tag-picker category filters,
|
||||
> upload disk selection). Keeps `form_field_validation_rules`
|
||||
> semantically pure (ARCH-FORM-BUILDER.md §17.5; addendum Q3 strict-
|
||||
> enterprise decision). Same polymorphic-morph pattern as the binding
|
||||
> and validation-rules tables.
|
||||
|
||||
| Column | Type | Notes |
|
||||
| -------------- | ----------------- | ---------------------------------------------------------------------- |
|
||||
| `id` | ULID | PK |
|
||||
| `owner_type` | string(40) | morph alias: `form_field` or `form_field_library` |
|
||||
| `owner_id` | ULID | parent row |
|
||||
| `config_type` | string(40) | `FormFieldConfigType` case (`tag_categories`, `storage_disk`) |
|
||||
| `parameters` | JSON | Per-config-type bag (`{"categories":[string]}`, `{"disk":string}`) |
|
||||
| `created_at`, `updated_at` | timestamps | |
|
||||
|
||||
**Relations:** `morphTo` owner (`form_field` or `form_field_library`)
|
||||
**Indexes:** `(config_type)`, `(owner_type, owner_id)`
|
||||
**Unique constraint:** `UNIQUE(owner_type, owner_id, config_type)`
|
||||
**Global scope:** `FormFieldConfigScope` — third sibling in the scope family (after `FormFieldBindingScope` and `FormFieldValidationRuleScope`), same UNION shape. Escape hatch: `withoutGlobalScope(FormFieldConfigScope::class)`.
|
||||
**Soft delete:** no — configs are current state, not audit
|
||||
|
||||
---
|
||||
|
||||
### `form_submissions`
|
||||
|
||||
> One submission per `(schema, subject)` in `single` / `draft_single`
|
||||
|
||||
Reference in New Issue
Block a user