docs(forms): SCHEMA crosswalk, foundation concept page, getting-started + migration playbook, copy catalogue init
SCHEMA.md - New §3.5.12 "Form Builder" with the legacy-tables-retained note placed prominently directly under the section header (per S1 wrap-up Path 3 decision: Phase 8 deferred to S2). - Crosswalk: every legacy volunteer_profiles column → its new home (user_profiles columns vs form_fields vs person_tags). - Summary table for the 13 new tables with one-line purpose + ARCH § pointer each. - Activity log strategy and multi-tenancy discipline noted. - §3.5.4 marked SUPERSEDED with a pointer to the new section. /dev-docs/form-builder-migration-playbook.md (new) - Operator runbook for forms:migrate-legacy-data on real legacy data. - Pre-flight audit, dry-run, migrate, verify, spot-check, rollback paths spelled out. Same legacy-tables-retained note prominently. /dev-docs/form-builder-getting-started.md (new) - Developer onboarding. Mental model, code samples for creating a schema/field/submission/value, adding a new subject type, registering a custom field type, suppressing activity log via App\Support\ActivityLog::suppressed. /dev-docs/COPY_CATALOGUE.md (new) - Seeded verbatim from ARCH §30 (naming conventions, tooltip catalogue, warning catalogue) with a header explaining purpose, growth strategy, and the per-PR update workflow. /docs/organizer/forms/concepts/wat-is-een-formulier.md (new VitePress) - Dutch, informal je/jij. Follows /docs/.templates/concept-page.md. - Three example use-cases: vrijwilligersregistratie, artist advance, incidentrapportage. Light foundation; depth arrives in S2-S5. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
120
dev-docs/COPY_CATALOGUE.md
Normal file
120
dev-docs/COPY_CATALOGUE.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# Crewli — In-app copy catalogue
|
||||
|
||||
> Single source of truth for user-facing Dutch copy. Seeded from
|
||||
> `/dev-docs/ARCH-FORM-BUILDER.md` §30.
|
||||
|
||||
## Purpose
|
||||
|
||||
Centralises terminology and warnings so every screen, tooltip, and
|
||||
error message stays consistent. Without this, "Dienst" / "Shift" /
|
||||
"Taak" drift across pages and confuse organisers; "Privacy-gevoelig"
|
||||
and "Bevat persoonsgegevens" appear side-by-side for the same flag.
|
||||
|
||||
This catalogue is the canonical reference for both backend validation
|
||||
messages (Form Requests) and frontend rendering (Vue components).
|
||||
Whenever you write Dutch copy that a user will read, look here first.
|
||||
|
||||
## Growth strategy
|
||||
|
||||
Living document. Each session that adds user-facing UI:
|
||||
|
||||
1. **Check first.** Search for the concept (in Dutch and English) before
|
||||
coining a new term. If it's here, use the existing wording verbatim.
|
||||
2. **Propose new terms in PR.** Add to the relevant section. Brief
|
||||
rationale in the commit message.
|
||||
3. **Reviewer (Bert) signs off** on terminology before merge. Once a
|
||||
term is in the catalogue, it's binding for future sessions.
|
||||
|
||||
The catalogue stays in `/dev-docs/` (developer-facing) rather than
|
||||
`/docs/` (end-user-facing). End-user docs are written *using* this
|
||||
catalogue, not *about* it.
|
||||
|
||||
## Update workflow
|
||||
|
||||
- Adding a tooltip → update §30.2 here.
|
||||
- Adding a warning → update §30.3 here.
|
||||
- Renaming a concept → update §30.1 here AND grep for all current
|
||||
Dutch occurrences (frontend, validation messages, end-user docs)
|
||||
and update them in the same PR.
|
||||
- Wholesale restructure → discuss in design-document.md first; then
|
||||
rewrite this catalogue in one commit.
|
||||
|
||||
## Naming conventions
|
||||
|
||||
| Concept | Canonical Dutch term | Never use |
|
||||
| -------------------- | ---------------------------- | ---------------------------------- |
|
||||
| `form_schema` | Formulier | Schema, template |
|
||||
| `form_field` | Veld | Vraag, item |
|
||||
| `form_template` | Formulier-sjabloon | Template (alleen in dev-docs) |
|
||||
| `form_field_library` | Veldenbibliotheek | Library, bibliotheek alleen |
|
||||
| `form_submission` | Inzending | Submission, antwoord |
|
||||
| `is_filterable` | Filterbaar | Queryable, zoekbaar |
|
||||
| `is_pii` | Bevat persoonsgegevens | Privacy-gevoelig |
|
||||
| `freeze_on_submit` | Bevriezen na inzending | Vergrendelen |
|
||||
| `consent_version` | Toestemmingsversie | Consent-versie |
|
||||
|
||||
## Tooltip catalogue (selection)
|
||||
|
||||
```
|
||||
is_filterable:
|
||||
"Filterbaar — dit veld wordt extra geïndexeerd voor snelle filtering
|
||||
in overzichten. Alleen aanvinken voor velden die je daadwerkelijk als
|
||||
filter gebruikt (bijvoorbeeld: shirtmaat wel, motivatie niet)."
|
||||
|
||||
is_pii:
|
||||
"Bevat persoonsgegevens — bij retentie-verwerking worden deze waardes
|
||||
geanonimiseerd volgens je privacy-instellingen. Vink aan voor velden
|
||||
zoals telefoon, e-mail, noodcontact, medische info."
|
||||
|
||||
is_unique:
|
||||
"Uniek per formulier — waardes van dit veld moeten uniek zijn over alle
|
||||
inzendingen heen. Geschikt voor bijvoorbeeld BSN of werknemersnummer.
|
||||
Dubbele waardes worden afgewezen."
|
||||
|
||||
freeze_on_submit:
|
||||
"Bevriezen na eerste inzending — zodra iemand het formulier indient
|
||||
kunnen de velden niet meer gewijzigd worden. Gebruik dit voor
|
||||
contracten, signatures, of formulieren waar de structuur vast moet
|
||||
staan voor audit-doeleinden."
|
||||
|
||||
snapshot_mode:
|
||||
never: "Geen snapshot — wijzigingen worden alleen in het activity log
|
||||
bijgehouden."
|
||||
on_submit: "Snapshot bij inzending — bij elke indiening wordt het
|
||||
complete formulier gesnapshot voor audit-doeleinden."
|
||||
always: "Altijd snapshot — elke wijziging (ook drafts) wordt
|
||||
gesnapshot. Gebruikt meer opslag maar biedt het volledige
|
||||
audit-spoor."
|
||||
|
||||
retention_days:
|
||||
"Bewaartermijn — na deze periode (vanaf inzendingsdatum) worden
|
||||
PII-velden automatisch geanonimiseerd. Typische waardes: 1095 dagen
|
||||
(3 jaar) voor vrijwilligers, 2555 dagen (7 jaar) voor contracten,
|
||||
null voor onbeperkt bewaren."
|
||||
```
|
||||
|
||||
## Warning catalogue (selection)
|
||||
|
||||
```
|
||||
binding_change_with_submissions:
|
||||
"Je staat op het punt de koppeling van dit veld te wijzigen terwijl er
|
||||
al {count} ingediende inzendingen zijn. De historische waardes blijven
|
||||
bestaan, maar zijn niet meer de bron-van-waarheid. Dit kan niet
|
||||
ongedaan worden gemaakt."
|
||||
|
||||
delete_schema_with_submissions:
|
||||
"Dit formulier heeft {count} inzendingen. Als je het verwijdert, blijven
|
||||
de inzendingen bewaard als archief maar zijn niet meer nieuw in te
|
||||
dienen. Type de naam van het formulier om te bevestigen:"
|
||||
|
||||
field_type_change:
|
||||
"Je wijzigt het veldtype van {old} naar {new}. Bestaande waardes worden
|
||||
mogelijk niet correct omgezet — sommige kunnen onleesbaar worden.
|
||||
Aanbevolen: maak een nieuw veld aan in plaats van dit veld te
|
||||
wijzigen."
|
||||
|
||||
public_token_rotation:
|
||||
"Je roteert de publieke link voor dit formulier. Bestaande gebruikers
|
||||
kunnen nog 7 dagen inzenden met de oude link; daarna krijgen ze een
|
||||
410 Gone foutmelding."
|
||||
```
|
||||
Reference in New Issue
Block a user