docs(spec): metadata-driven forms & list views design (P3.2/P3.3/P3.6/R3) (39827f04) | Commits | 朱子纯 / vibe-erp-v0

Commit 39827f040f15aa63a087a59071c170565c6881a9

Authored by zichun 2026-04-10 12:31:42 +0800

docs(spec): metadata-driven forms & list views design (P3.2/P3.3/P3.6/R3)

Sub-project A of remaining v1.0 work. Key decisions:
- Hybrid: core forms stay handcrafted, renderer for user-task forms
- @rjsf/core with custom ERP widget registry
- Structured property editor (not drag-and-drop) for form designer
- Custom entities deferred to v1.1

Inline Side-by-side

Showing 1 changed file with 391 additions and 0 deletions

docs/superpowers/specs/2026-04-10-metadata-forms-listviews-design.md 0 → 100644

View file @39827f0

	1	+# Metadata-Driven Forms & List Views — Design Spec
	2	+
	3	+> Sub-project A of the v1.0 remaining work. Covers P3.2 (form renderer),
	4	+> P3.3 (form designer), P3.6 (list view designer), and R3 (metadata admin UIs).
	5	+
	6	+## 1. Context & Motivation
	7	+
	8	+vibe_erp's Tier 1 extensibility promise is that business analysts can customize
	9	+the system through the web UI — no code, no build, no restart. The foundation
	10	+is live: custom fields on core entities (P3.1 + P3.4), metadata YAML loader,
	11	+`metadata__*` tables, and the `DynamicExtFields` SPA component.
	12	+
	13	+What's missing is the designer and renderer layer — the UIs that let key
	14	+users create form layouts, configure list views, and manage all metadata
	15	+through the browser. Without these, Tier 1 customization requires editing
	16	+YAML files and restarting the server.
	17	+
	18	+## 2. Scope Decisions (Agreed)
	19	+
	20	+\| Decision \| Choice \| Rationale \|
	21	+\|---\|---\|---\|
	22	+\| Form renderer scope \| Hybrid — core entity forms stay handcrafted; renderer handles user-task forms, custom fields, and future custom entities \| Core forms have complex interactions (line items, state transitions) that don't map well to JSON Schema \|
	23	+\| Custom entity creation \| Deferred to v1.1 — no dynamic DDL or runtime endpoint registration in v1.0 \| Large, risky feature; custom fields already give key users meaningful extensibility \|
	24	+\| Form renderer library \| @rjsf/core with custom widget registry — React JSON Schema Form with ERP-specific widgets \| FormSchema.kt already stores JSON Schema + UI Schema; @rjsf is the standard renderer \|
	25	+\| Form designer UX \| Structured property editor — table/accordion UI with live preview tab \| 90% of the value of drag-and-drop at 30% of the cost; upgradeable later \|
	26	+
	27	+## 3. Architecture
	28	+
	29	+```
	30	+metadata__form / metadata__list_view (Postgres JSONB rows)
	31	+ │
	32	+ │ source = 'core' \| 'plugin:<id>' \| 'user'
	33	+ │
	34	+ MetadataController (REST API)
	35	+ │
	36	+ ├── GET /api/v1/_meta/metadata/forms
	37	+ ├── GET /api/v1/_meta/metadata/forms/{slug}
	38	+ ├── PUT /api/v1/_meta/metadata/forms/{slug} ← designer writes
	39	+ ├── DELETE /api/v1/_meta/metadata/forms/{slug} ← user-created only
	40	+ ├── GET /api/v1/_meta/metadata/list-views
	41	+ ├── GET /api/v1/_meta/metadata/list-views/{slug}
	42	+ ├── PUT /api/v1/_meta/metadata/list-views/{slug}
	43	+ └── DELETE /api/v1/_meta/metadata/list-views/{slug}
	44	+ │
	45	+ SPA (React + TypeScript)
	46	+ │
	47	+ ├── MetadataFormRenderer (P3.2) — @rjsf/core, renders form from definition
	48	+ ├── FormDesigner (P3.3) — structured editor, writes definitions back
	49	+ ├── ListViewDesigner (P3.6) — column/filter/sort editor
	50	+ └── MetadataAdmin (R3) — tabs: entities, permissions, menus,
	51	+ custom fields, forms, list views
	52	+```
	53	+
	54	+### Source tagging
	55	+
	56	+All form and list-view definitions follow the existing `source` convention:
	57	+- `core` — shipped in metadata YAML, loaded by MetadataLoader at boot
	58	+- `plugin:<id>` — from plug-in JAR, loaded at plug-in start
	59	+- `user` — created through the designer UI, never touched by the loader
	60	+
	61	+The `PUT` and `DELETE` endpoints only accept `source='user'` rows. Core and
	62	+plugin definitions are read-only in the UI (shown grayed out with a lock icon).
	63	+
	64	+## 4. P3.2 — Form Renderer (`MetadataFormRenderer`)
	65	+
	66	+### Component
	67	+
	68	+```tsx
	69	+<MetadataFormRenderer
	70	+ slug="plate-approval-task" // looks up from metadata__form
	71	+ initialValues={{ ... }} // pre-fill for edit mode
	72	+ onSubmit={(values) => { ... }} // called on valid submit
	73	+ readOnly={false} // true for view / completed tasks
	74	+/>
	75	+```
	76	+
	77	+### Form definition schema (stored in `metadata__form.payload`)
	78	+
	79	+```typescript
	80	+interface FormDefinition {
	81	+ entityName: string // "WorkOrder", "printing-shop.Plate"
	82	+ slug: string // unique key: "plate-approval-task"
	83	+ title: string // display title
	84	+ purpose: 'create' \| 'edit' \| 'user-task' \| 'view'
	85	+ jsonSchema: object // JSON Schema draft 2020-12
	86	+ uiSchema: object // @rjsf UI Schema (widget, order, sections)
	87	+ version: number // monotonically increasing
	88	+}
	89	+```
	90	+
	91	+### @rjsf integration
	92	+
	93	+- Library: `@rjsf/core` + `@rjsf/validator-ajv8`
	94	+- Theme: Custom `VibeErpTheme` wrapping existing Tailwind CSS classes
	95	+ (slate-700 labels, rounded-md inputs, btn-primary buttons) so rendered
	96	+ forms look identical to handcrafted pages.
	97	+- Custom widget registry:
	98	+
	99	+\| Widget ID \| Purpose \| Data source \|
	100	+\|---\|---\|---\|
	101	+\| `partner-picker` \| Searchable partner dropdown \| `GET /api/v1/partners` \|
	102	+\| `item-picker` \| Searchable item dropdown \| `GET /api/v1/catalog/items` \|
	103	+\| `uom-selector` \| UoM dropdown \| `GET /api/v1/catalog/uoms` \|
	104	+\| `location-picker` \| Location dropdown \| `GET /api/v1/inventory/locations` \|
	105	+\| `money-input` \| Number + currency display \| FieldType.Money \|
	106	+\| `quantity-input` \| Number + UoM display \| FieldType.Quantity \|
	107	+
	108	+Widgets are registered in a `vibeWidgets` map and passed to `@rjsf/core`'s
	109	+`widgets` prop. Each widget is a standard React component that receives
	110	+`WidgetProps` from @rjsf.
	111	+
	112	+### User-task form bridge (P2.3)
	113	+
	114	+Flowable user-tasks carry a `formKey` in BPMN XML (e.g. `formKey="vibe:plate-approval-task"`).
	115	+When the SPA renders a pending user-task:
	116	+
	117	+1. Strip the `vibe:` prefix → slug `plate-approval-task`
	118	+2. Fetch form definition: `GET /api/v1/_meta/metadata/forms/plate-approval-task`
	119	+3. Fetch task variables: `GET /api/v1/workflow/tasks/{taskId}`
	120	+4. Render: `<MetadataFormRenderer slug="..." initialValues={taskVars} />`
	121	+5. On submit: `POST /api/v1/workflow/tasks/{taskId}/complete` with form values
	122	+
	123	+### Relationship with DynamicExtFields (P3.1)
	124	+
	125	+DynamicExtFields stays as-is for custom fields on core entity create/edit pages.
	126	+MetadataFormRenderer is a separate, more powerful component for full-form rendering.
	127	+They share the same Tailwind styling but are independent components — no refactor
	128	+of existing create/edit pages needed.
	129	+
	130	+## 5. P3.3 — Form Designer
	131	+
	132	+### UX: Structured property editor
	133	+
	134	+The form designer is a full-page editor with two panels:
	135	+
	136	+Left panel — Field list (accordion/table):
	137	+- One row per field in the form
	138	+- Each row shows: field key, label, type, required checkbox, width (1/2/3 cols)
	139	+- Rows are reorderable via up/down buttons
	140	+- "Add field" button at the bottom with a type picker
	141	+- "Add section divider" to group fields under headings
	142	+- Click a row to expand its property panel inline:
	143	+ - Label (per locale, with translation inputs)
	144	+ - Placeholder text
	145	+ - Help text / description
	146	+ - Validation rules (min, max, pattern, required)
	147	+ - Visibility condition (simple: "show when field X equals Y")
	148	+ - Widget override (dropdown of available widgets)
	149	+
	150	+Right panel — Live preview:
	151	+- Renders the current form definition using `<MetadataFormRenderer />`
	152	+- Updates in real-time as the user edits fields in the left panel
	153	+- "Preview" / "Edit" toggle
	154	+
	155	+Top bar:
	156	+- Form title (editable)
	157	+- Entity selector (which entity this form is for)
	158	+- Purpose selector (create / edit / user-task / view)
	159	+- Save button → `PUT /api/v1/_meta/metadata/forms/{slug}`
	160	+- Discard button
	161	+
	162	+### Visibility conditions
	163	+
	164	+Simple "show when" rules stored in the UI Schema:
	165	+
	166	+```json
	167	+{
	168	+ "ui:field:press_id": {
	169	+ "ui:visible": { "field": "item_type", "equals": "GOOD" }
	170	+ }
	171	+}
	172	+```
	173	+
	174	+The MetadataFormRenderer evaluates these at render time — no server round-trip.
	175	+Only single-field equality conditions in v1.0; complex expressions deferred.
	176	+
	177	+### Form definition generation
	178	+
	179	+The designer generates a JSON Schema + UI Schema pair from the field list.
	180	+It never exposes raw JSON to the user — the structured editor is the only
	181	+interface. Power users who want raw JSON can use the R3 metadata admin UI's
	182	+"Raw JSON" tab.
	183	+
	184	+## 6. P3.6 — List View Designer
	185	+
	186	+### Definition schema (stored in `metadata__list_view.payload`)
	187	+
	188	+```typescript
	189	+interface ListViewDefinition {
	190	+ entityName: string
	191	+ slug: string // "sales-orders-default"
	192	+ title: string
	193	+ columns: Array<{
	194	+ field: string // entity field key or custom field key
	195	+ label: string // display header
	196	+ width?: string // CSS width hint ("200px", "auto")
	197	+ sortable: boolean
	198	+ format?: 'date' \| 'money' \| 'status-badge' \| 'link'
	199	+ }>
	200	+ defaultSort?: { field: string; direction: 'asc' \| 'desc' }
	201	+ filters?: Array<{
	202	+ field: string
	203	+ operator: 'eq' \| 'contains' \| 'gt' \| 'lt' \| 'in'
	204	+ label: string
	205	+ }>
	206	+ pageSize: number // default 25
	207	+ version: number
	208	+}
	209	+```
	210	+
	211	+### Designer UX
	212	+
	213	+Simple two-section editor:
	214	+
	215	+Columns section:
	216	+- Table of columns with checkboxes (show/hide), drag-to-reorder, label editing
	217	+- Available fields populated from entity's JSON Schema + custom fields
	218	+- Format selector per column (plain text, date, money, status badge, link)
	219	+
	220	+Filters & sorting section:
	221	+- Add filterable fields (creates a filter bar above the list)
	222	+- Set default sort column and direction
	223	+- Page size selector
	224	+
	225	+Preview: Shows a mock table with sample data using the current config.
	226	+
	227	+### Integration with existing list pages
	228	+
	229	+v1.0 list pages (ItemsPage, PartnersPage, etc.) continue to use the existing
	230	+`<DataTable>` component with hardcoded columns. The `ListViewDesigner` creates
	231	+definitions for future use (custom entities in v1.1, and opt-in override of
	232	+core list views). A `<MetadataListView entityName="..." />` component renders
	233	+a list from a `ListViewDefinition`, reusing `DataTable` internally.
	234	+
	235	+## 7. R3 — Metadata Admin UIs
	236	+
	237	+### Route: `/admin/metadata`
	238	+
	239	+A tabbed admin page with sections:
	240	+
	241	+\| Tab \| Content \| Editable? \|
	242	+\|---\|---\|---\|
	243	+\| Entities \| List of all registered entities (core + plugin + user) \| Read-only (v1.0 has no custom entities) \|
	244	+\| Custom Fields \| List/create/edit custom fields for any entity \| Full CRUD for `source='user'` fields \|
	245	+\| Permissions \| List of all permissions \| Read-only (permissions come from YAML) \|
	246	+\| Menus \| List of all menu entries with section/order \| Read-only for core/plugin; editable for user \|
	247	+\| Forms \| List of form definitions; click to open FormDesigner \| Full CRUD for `source='user'` forms \|
	248	+\| List Views \| List of list-view definitions; click to open ListViewDesigner \| Full CRUD for `source='user'` views \|
	249	+
	250	+Each tab shows a `source` badge (core / plugin:name / user) and a lock icon
	251	+for non-editable rows.
	252	+
	253	+### Custom field editor (inline in the admin)
	254	+
	255	+The custom field tab lets key users:
	256	+- Add a new custom field to any entity (creates a `source='user'` row)
	257	+- Choose: target entity, field key, type (from FieldType sealed set), required, PII flag
	258	+- Add label translations (en, zh-CN, etc.)
	259	+- Delete user-created custom fields (with confirmation)
	260	+
	261	+This replaces the need to edit YAML for Tier 1 custom fields — the full
	262	+key-user story is now possible through the browser.
	263	+
	264	+### Permissions
	265	+
	266	+- `admin.metadata.read` — view all metadata tabs
	267	+- `admin.metadata.write` — create/edit/delete user metadata (custom fields, forms, list views, menus)
	268	+
	269	+These are added to the core `identity.yml` metadata.
	270	+
	271	+## 8. Backend Changes
	272	+
	273	+### New REST endpoints (MetadataController)
	274	+
	275	+```
	276	+# Forms
	277	+GET /api/v1/_meta/metadata/forms → List<FormDefinition>
	278	+GET /api/v1/_meta/metadata/forms/{slug} → FormDefinition
	279	+PUT /api/v1/_meta/metadata/forms/{slug} → FormDefinition (upsert, source='user')
	280	+DELETE /api/v1/_meta/metadata/forms/{slug} → 204 (source='user' only)
	281	+
	282	+# List views
	283	+GET /api/v1/_meta/metadata/list-views → List<ListViewDefinition>
	284	+GET /api/v1/_meta/metadata/list-views/{slug} → ListViewDefinition
	285	+PUT /api/v1/_meta/metadata/list-views/{slug} → ListViewDefinition (upsert, source='user')
	286	+DELETE /api/v1/_meta/metadata/list-views/{slug} → 204 (source='user' only)
	287	+
	288	+# Custom fields (new write endpoints)
	289	+POST /api/v1/_meta/metadata/custom-fields → CustomField (source='user')
	290	+PUT /api/v1/_meta/metadata/custom-fields/{key} → CustomField (source='user')
	291	+DELETE /api/v1/_meta/metadata/custom-fields/{key} → 204 (source='user' only)
	292	+```
	293	+
	294	+The existing `GET` endpoints remain unchanged. Write endpoints require
	295	+`admin.metadata.write` permission.
	296	+
	297	+### Database
	298	+
	299	+The `metadata__form` and `metadata__list_view` tables already exist in
	300	+`000-platform-init.xml`. No new migrations needed — just new code that
	301	+reads/writes these tables.
	302	+
	303	+### MetadataLoader changes
	304	+
	305	+Add `forms:` and `listViews:` sections to the MetadataYaml schema so core
	306	+PBCs and plug-ins can ship default form and list-view definitions in their
	307	+metadata YAML. The loader processes them with the same delete-by-source
	308	+idempotency as entities, permissions, menus, and custom fields.
	309	+
	310	+### CustomFieldRegistry refresh
	311	+
	312	+After a custom field is created/updated/deleted through the REST API, the
	313	+registry must refresh. Add a `refresh()` call in the write endpoint handler
	314	+(same pattern as MetadataLoader already uses).
	315	+
	316	+## 9. SPA Dependencies
	317	+
	318	+New npm packages:
	319	+- `@rjsf/core` — React JSON Schema Form renderer
	320	+- `@rjsf/utils` — shared utilities
	321	+- `@rjsf/validator-ajv8` — JSON Schema validation via Ajv
	322	+
	323	+Estimated bundle impact: ~60KB gzipped (acceptable for an ERP SPA).
	324	+
	325	+## 10. File Inventory (New & Modified)
	326	+
	327	+### New files
	328	+
	329	+Backend (Kotlin):
	330	+- `platform/platform-metadata/src/.../web/FormDefinitionController.kt` — CRUD for form defs
	331	+- `platform/platform-metadata/src/.../web/ListViewDefinitionController.kt` — CRUD for list-view defs
	332	+- `platform/platform-metadata/src/.../web/CustomFieldWriteController.kt` — write endpoints for custom fields
	333	+- `platform/platform-metadata/src/.../yaml/FormYaml.kt` — YAML deserialization for forms
	334	+- `platform/platform-metadata/src/.../yaml/ListViewYaml.kt` — YAML deserialization for list views
	335	+
	336	+Frontend (TypeScript/React):
	337	+- `web/src/components/MetadataFormRenderer.tsx` — @rjsf wrapper with VibeErp theme
	338	+- `web/src/components/form-widgets/PartnerPicker.tsx` — partner search widget
	339	+- `web/src/components/form-widgets/ItemPicker.tsx` — item search widget
	340	+- `web/src/components/form-widgets/UomSelector.tsx` — UoM dropdown widget
	341	+- `web/src/components/form-widgets/LocationPicker.tsx` — location dropdown widget
	342	+- `web/src/components/form-widgets/MoneyInput.tsx` — money input widget
	343	+- `web/src/components/form-widgets/QuantityInput.tsx` — quantity input widget
	344	+- `web/src/components/form-widgets/index.ts` — widget registry
	345	+- `web/src/pages/FormDesignerPage.tsx` — structured property editor
	346	+- `web/src/pages/ListViewDesignerPage.tsx` — column/filter/sort editor
	347	+- `web/src/pages/MetadataAdminPage.tsx` — tabbed admin with sub-sections
	348	+
	349	+Metadata YAML (reference):
	350	+- Core PBCs ship default form definitions for user-task forms (if any)
	351	+- Printing-shop plug-in ships a `plate-approval-task` form definition
	352	+
	353	+### Modified files
	354	+
	355	+- `platform/platform-metadata/src/.../yaml/MetadataYaml.kt` — add `forms` + `listViews` sections
	356	+- `platform/platform-metadata/src/.../MetadataLoader.kt` — process forms + list views
	357	+- `platform/platform-metadata/src/.../web/MetadataController.kt` — add form/list-view GET endpoints
	358	+- `web/src/App.tsx` — add routes for designer + admin pages
	359	+- `web/src/api/client.ts` — add API functions for form/list-view/custom-field CRUD
	360	+- `web/src/i18n/messages.ts` — add message keys for new pages
	361	+- `web/src/types/api.ts` — add FormDefinition + ListViewDefinition types
	362	+- `web/package.json` — add @rjsf dependencies
	363	+
	364	+## 11. Testing Strategy
	365	+
	366	+Backend unit tests:
	367	+- FormDefinition CRUD (create, read, update, delete with source enforcement)
	368	+- ListViewDefinition CRUD (same)
	369	+- CustomField write endpoints (create, update, delete, registry refresh)
	370	+- MetadataLoader with forms + list views sections
	371	+- Source-tag enforcement (reject writes to core/plugin rows)
	372	+
	373	+Frontend:
	374	+- Manual smoke test: open form designer, create a form, preview it, save it
	375	+- Manual smoke test: open list view designer, configure columns, save
	376	+- Manual smoke test: open metadata admin, browse all tabs
	377	+
	378	+Integration:
	379	+- Printing-shop plug-in ships a `plate-approval-task` form definition
	380	+- Boot the framework, start the plate-approval BPMN process, verify the
	381	+ user-task renders the form from metadata, complete it, verify values flow
	382	+ through to the workflow
	383	+
	384	+## 12. Out of Scope (Deferred)
	385	+
	386	+- Custom entities / dynamic DDL — v1.1
	387	+- Drag-and-drop form designer — future upgrade of the structured editor
	388	+- Complex visibility conditions — v1.0 supports "show when X equals Y" only
	389	+- Form versioning / migration — v1.1 (for now, bumping version is manual)
	390	+- List view as override for core pages — v1.1 (core pages keep hardcoded columns)
	391	+- Import/export of form/list-view definitions — v1.1
...	...