Setup & Deployment

Vereisten

Component	Versie	Doel
WordPress	5.9+	CMS platform
PHP	7.4+	IntlDateFormatter, type hints
MySQL	5.7+ / MariaDB 10.3+	Database
WPForms Pro	Latest	Formulieren (forms 2, 40, 3493, 3500)
ACF Pro	Latest	Custom fields en veldgroepen
Node.js	16+	Dependencies (jQuery, Flatpickr, Select2)
CodeKit 3	Optioneel	SCSS compilatie, JS bundeling

Installatie

1. Clone of kopieer het thema naar wp-content/themes/werkbon
2. Installeer Node dependencies:

   cd wp-content/themes/werkbon
   npm install

3. Activeer het thema in WordPress admin
4. Automatische acties bij activatie:
   • werkbon_addresses_create_table() — maakt wp_werkbon_addresses tabel aan
   • Postmeta indexes aanmaken (6 composite indexes via db-optimize.php)
   • Rollen hernoemen: administrator → Beheerder, subscriber → Monteur
   • Editor, author en contributor rollen worden permanent verwijderd

Vereiste Plugins

WPForms Pro

Form IDs moeten exact matchen — deze zijn hardcoded op meerdere plekken:

Form ID	Naam	Doel
40	Werkbon invullen	Hoofdformulier — werkbon aanmaken
3493	Melding aanmaken/bewerken	Melding create + edit
3500	Melding aanmaken	Alternatief melding formulier
2	Werkbon aanmaken	Alternatief werkbon formulier

Benodigde WPForms addons:

• Smart Phone Field (telefoon velden)
• File Upload (handtekening)
• Signatures (handtekening capture)

Let op: Als formulieren opnieuw worden aangemaakt, krijgen ze nieuwe IDs. Alle referenties in PHP en JavaScript moeten dan worden bijgewerkt.

ACF Pro

• 4 veldgroepen worden automatisch geïmporteerd vanuit /acf-json/
• De /acf-json/ directory moet schrijfbaar zijn voor JSON sync
• ACF Options Page wordt geactiveerd in admin.php
• Veldgroepen: Werkbonnen, Meldingen, Contact, Gebruiker (zie Datamodel)

Build Process

Met CodeKit 3

1. Open config.codekit3 in CodeKit
2. SCSS wordt automatisch gecompileerd naar style.css
3. JavaScript wordt gebundeld naar main-min.js via @codekit-prepend directives

Zonder CodeKit (handmatig)

# SCSS compilatie (vereist sass CLI)
npx sass assets/scss/style.scss:style.css

# JS bundeling: bestanden samenvoegen in deze volgorde:
cat assets/js/nav.js \
    assets/js/modules/prefill-manager.js \
    assets/js/modules/wpforms-werkbon.js \
    assets/js/modules/melding-modal.js \
    assets/js/modules/form-field-locks.js \
    assets/js/modules/file-overview-sync.js \
    assets/js/modules/form-prefill-helpers.js \
    assets/js/modules/submit-validation.js \
    > main-min.js

Let op: main-min.js is NIET daadwerkelijk geminificeerd ondanks de naam.

CSV Adresdata

1. Plaats CSV bestanden in /assets/csv/addresses/
2. Ga naar Admin > Tools > Adressen Database
3. Klik “Importeren” om de data in wp_werkbon_addresses te laden
4. Maasdelta-adressen worden gemarkeerd met is_maasdelta = 1
5. Bestaande duplicaten worden overgeslagen (INSERT IGNORE)

Zie Adressysteem voor details over het CSV formaat en de import functie.

Environment Configuratie

Productie vs Development

Gedrag	Productie	Development
Make.com webhooks	Actief	Overgeslagen
Contact sync → Moneybird	Actief	Overgeslagen
File webhook → factuur	Actief	Overgeslagen

Detectie via wp_get_environment_type(). Stel in via wp-config.php:

// Development (webhooks uitgeschakeld)
define('WP_ENVIRONMENT_TYPE', 'local');

// Productie (webhooks actief)
define('WP_ENVIRONMENT_TYPE', 'production');

Webhook URLs

WAARSCHUWING: Webhook URLs staan hardcoded in de broncode en zijn gecommit naar Git.

Constante	Bestand	Doel
ACS_MAKE_WEBHOOK_URL	api-contact.php:10	Contact sync naar Make.com
ACS_MAKE_FILE_WEBHOOK_URL	api-file.php:13	Werkbon/factuur naar Make.com

Aanbeveling — verplaats naar wp-config.php:

define('ACS_MAKE_WEBHOOK_URL', 'https://hook.eu2.make.com/...');
define('ACS_MAKE_FILE_WEBHOOK_URL', 'https://hook.eu2.make.com/...');

WordPress Pagina’s

De volgende pagina’s moeten bestaan met de juiste page template:

Pagina	Template	Slug	Doel
Dashboard	Dashboard	/ (front page)	Startpagina met snelkoppelingen
Login	Login	/login/	Inlogscherm
Meldingen	Jobs	/meldingen/	Meldingen lijst + filters
Melding aanmaken	Jobs form	/melding-aanmaken/	Form 3493
Werkbon invullen	Jobs form	/werkbon-invullen/	Form 40
Rapporten	Reports	/rapporten/	Werkbonnen rapportage

ACF JSON Sync

• Veldgroepen worden opgeslagen als JSON in /acf-json/
• Bij wijziging in admin → JSON wordt automatisch bijgewerkt
• Bij installatie op nieuwe omgeving → JSON wordt automatisch geïmporteerd
• Vereist: directory schrijfrechten voor de webserver

Bekende Valkuilen

1. Glob include — Elk .php bestand in /functions/ wordt automatisch geladen. Test- of tijdelijke bestanden worden ook uitgevoerd.

2. jQuery in header — jQuery wordt in de header geladen (render-blocking) vanwege WPForms compatibiliteit. Dit kan niet naar de footer verplaatst worden zonder WPForms te breken.

3. main-min.js niet minified — De bestandsnaam is misleidend. Het bestand is een concatenatie zonder minificatie.

4. Form IDs hardcoded — WPForms form IDs (2, 40, 3493, 3500) staan op 10+ plekken in PHP en JavaScript. Bij opnieuw aanmaken van formulieren moeten alle referenties worden bijgewerkt.

5. REST API open — Alle REST endpoints zijn publiek toegankelijk zonder authenticatie. Zie Security Audit.

6. Rollen onomkeerbaar — Bij theme activatie worden editor, author en contributor rollen permanent verwijderd. Dit is niet omkeerbaar via de admin — alleen via code of database.

7. Adres tabel vereist import — De wp_werkbon_addresses tabel wordt leeg aangemaakt. Zonder CSV import werkt het adressysteem niet.

Troubleshooting

Formulier werkt niet / velden missen

• Oorzaak: WPForms form IDs matchen niet
• Check: Ga naar WPForms → All Forms, controleer of forms 2, 40, 3493 en 3500 bestaan
• Fix: Als forms opnieuw aangemaakt zijn, update alle hardcoded IDs in PHP en JS

Adres zoeken werkt niet

• Oorzaak 1: wp_werkbon_addresses tabel is leeg

• Check: Admin > Tools > Adressen Database → statistieken

• Fix: CSV importeren

• Oorzaak 2: AJAX nonce is verlopen

• Check: Browser console → netwerk tab → 403 op admin-ajax.php

• Fix: Pagina herladen (nonce wordt opnieuw gegenereerd)

Webhooks komen niet aan bij Make.com

• Oorzaak 1: Niet op productie

• Check: wp_get_environment_type() moet 'production' retourneren

• Fix: define('WP_ENVIRONMENT_TYPE', 'production'); in wp-config.php

• Oorzaak 2: Contact type is maasdelta

• Check: Contact bewerken → type veld controleren

• Verwacht: Maasdelta contacten worden nooit gesynceerd

• Oorzaak 3: Debounce actief

• Check: Wacht 3 seconden, sla opnieuw op

• Fix: Post meta _acs_make_last_fired_ts verwijderen

Contacten worden dubbel aangemaakt

• Oorzaak: Email verschilt (hoofdletter/spatie)
• Check: Contact zoeken op email → vergelijk normalisatie
• Preventie: Email wordt genormaliseerd naar lowercase+trim, maar bestaande data kan inconsistent zijn

Monteur kan meldingen niet verwijderen

• Oorzaak: ACF admin veld niet op true gezet
• Check: Gebruiker bewerken → admin veld controleren
• Fix: admin op true zetten (los van WP administrator rol)

Lokale Ontwikkeling

1. Gebruik Local by Flywheel, MAMP, DDEV of vergelijkbare setup
2. Stel environment type in:

   define('WP_ENVIRONMENT_TYPE', 'local');

3. Webhooks worden automatisch overgeslagen
4. Installeer en activeer WPForms Pro + ACF Pro
5. ACF veldgroepen worden automatisch geïmporteerd vanuit /acf-json/
6. WPForms formulieren moeten handmatig worden geëxporteerd/geïmporteerd vanuit productie
7. Importeer CSV adresdata via Admin > Tools > Adressen Database
8. Maak de vereiste pagina’s aan met de juiste templates (zie tabel hierboven)