@happychef/algorithm 1.0.3 → 1.1.0

package/RESERVERINGEN_GIDS.md

@@ -0,0 +1,986 @@
+# Handleiding Reserveringssysteem HappyChef
+
+## Inhoudsopgave
+
+1. [Overzicht van het Systeem](#overzicht-van-het-systeem)
+2. [Hoe Beschikbaarheid Wordt Berekend](#hoe-beschikbaarheid-wordt-berekend)
+3. [Datamodellen en Configuratie](#datamodellen-en-configuratie)
+4. [Boekingsfilters en Validatie](#boekingsfilters-en-validatie)
+5. [Tafeltoewijzing](#tafeltoewijzing)
+6. [Volledige Reserveringsflow](#volledige-reserveringsflow)
+7. [Belangrijke Validatieregels](#belangrijke-validatieregels)
+
+---
+
+## Overzicht van het Systeem
+
+Het HappyChef reserveringssysteem is een gelaagd algoritme voor het berekenen van restaurantbeschikbaarheid en het toewijzen van tafels aan reserveringen. Het systeem bestaat uit de volgende kerncomponenten:
+
+### Bestandsstructuur
+
+```
+├── Core Beschikbaarheidslogica
+│   ├── isDateAvailable.js          - Controleert of een datum beschikbaar is
+│   ├── isTimeAvailable.js          - Controleert of een tijdstip beschikbaar is
+│   └── getAvailableTimeblocks.js   - Haalt beschikbare tijdsblokken op
+│
+├── Processing Engines (processing/)
+│   ├── timeblocksAvailable.js      - Kernmotor voor beschikbaarheid
+│   ├── dailyGuestCounts.js         - Berekent dagelijkse gastentellingen
+│   └── mealTypeCount.js            - Berekent gasten per maaltijdtype
+│
+├── Datamodellen (restaurant_data/)
+│   ├── openinghours.js             - Openingstijden configuratie
+│   ├── exceptions.js               - Uitzonderingen en sluitingen
+│   └── counter.js                  - Gastentelling functies
+│
+├── Boekingsfilters (filters/)
+│   ├── timeFilter.js               - Tijdsfilter
+│   ├── maxArrivalsFilter.js        - Maximum aankomsten filter
+│   └── maxGroupsFilter.js          - Maximum groepen filter
+│
+└── Tafelbeheer
+    ├── assignTables.js             - Tafeltoewijzing logica
+    ├── grouping.js                 - Tafelgroepering
+    └── tableHelpers.js             - Hulpfuncties voor tafels
+```
+
+---
+
+## Hoe Beschikbaarheid Wordt Berekend
+
+De beschikbaarheidberekening gebeurt in meerdere lagen, van datum tot specifiek tijdstip.
+
+### 1. Beschikbaarheid op Datumniveau (`isDateAvailable.js`)
+
+```
+isDateAvailable(data, dateStr, reservations, guests)
+  ↓
+Stap 1: Controleer of datum binnen toegestane toekomstbereik ligt (dagenInToekomst: standaard 90 dagen)
+Stap 2: Roep getAvailableTimeblocks() aan om beschikbare tijdsslots te vinden
+Stap 3: Geef TRUE terug als er minstens ÉÉN tijdsblok beschikbaar is
+```
+
+**Belangrijke Instellingen:**
+- `dagenInToekomst`: Maximum aantal dagen in de toekomst (standaard: 90)
+- `uurOpVoorhand`: Aantal uren van tevoren vereist om te boeken (standaard: 4)
+- Tijdzone: Europe/Amsterdam
+
+### 2. Tijdsblok Beschikbaarheid (`getAvailableTimeblocks.js`)
+
+```
+getAvailableTimeblocks(data, dateStr, reservations, guests)
+  ↓
+Stap 1: Valideer dat datum binnen dagenInToekomst bereik ligt
+Stap 2: Voor VANDAAG: Verwijder slots binnen uurOpVoorhand venster
+Stap 3: Roep timeblocksAvailable() aan voor alle potentiële slots
+Stap 4: Geef gefilterd tijdsblok object terug met tijden en beschikbaarheid
+```
+
+**Voorbeeld output:**
+```javascript
+{
+  "12:00": true,   // Beschikbaar
+  "12:15": true,
+  "12:30": false,  // Niet beschikbaar
+  "12:45": true
+}
+```
+
+### 3. Kern Beschikbaarheidsmotor (`processing/timeblocksAvailable.js`)
+
+Dit is het hart van het systeem en werkt in twee modi:
+
+#### **A. SHIFTS MODUS** (indien ingeschakeld)
+
+```
+timeblocksAvailable(data, dateStr, reservations, guests)
+  ↓
+Stap 1: Controleer maaltijdtypes met shifts ingeschakeld
+Stap 2: Voor elke shift tijd:
+        - Tel beschikbare stoelen (maxCapacity - huidigeGasten)
+Stap 3: Geef beschikbare shifts terug waar: beschikbareStoelen >= gasten
+```
+
+**Voorbeeld:**
+```javascript
+// Shift configuratie
+shifts: [
+  { name: "Eerste dienst", time: "12:00" },
+  { name: "Tweede dienst", time: "14:00" }
+]
+
+// Berekening voor 4 gasten
+Shift "12:00": maxCapacity (30) - bezet (25) = 5 beschikbaar → ✓ BESCHIKBAAR
+Shift "14:00": maxCapacity (30) - bezet (28) = 2 beschikbaar → ✗ NIET BESCHIKBAAR
+```
+
+#### **B. TIJDSINTERVAL MODUS** (standaard)
+
+```
+timeblocksAvailable(data, dateStr, reservations, guests)
+  ↓
+Stap 1: Genereer alle tijdslots binnen maaltijdperiodes met regelmatige intervallen
+        (intervalReservatie: standaard 15 minuten)
+
+Stap 2: Voor elk interval:
+        - Tel beschikbare stoelen met getDailyGuestCounts()
+        - Controleer of er voldoende opeenvolgende slots bestaan voor volledige reserveringsduur
+          (duurReservatie: standaard 120 minuten)
+
+Stap 3: Valideer dat starttijd + duur binnen maaltijdtijdvenster past
+
+Stap 4: Geef beschikbare tijdsblok objecten terug
+```
+
+**Voorbeeld berekening voor 4 gasten om 12:00:**
+```
+Reserveringsduur: 120 minuten
+Vereiste slots: 12:00, 12:15, 12:30, 12:45, 13:00, 13:15, 13:30, 13:45
+
+Check per slot:
+  12:00 → beschikbaar: 6 stoelen ✓
+  12:15 → beschikbaar: 5 stoelen ✓
+  12:30 → beschikbaar: 3 stoelen ✗ (te weinig!)
+
+Resultaat: 12:00 NIET BESCHIKBAAR (niet alle slots hebben voldoende capaciteit)
+```
+
+### 4. Dagelijkse Gastentelling (`processing/dailyGuestCounts.js`)
+
+Deze functie berekent hoeveel gasten er op elk moment van de dag aanwezig zijn.
+
+```
+getDailyGuestCounts(data, dateStr, reservations)
+  ↓
+Stap 1: Verwerk drie maaltijdtypes: ontbijt, lunch, diner
+
+Stap 2: Voor elke maaltijd:
+        - Haal gastentellingen op per interval via getGuestCountsForMeal()
+
+Stap 3: Merge resultaten op basis van maaltijdprioriteit:
+        DINER (hoogste) > LUNCH > ONTBIJT (laagste)
+        - Als tijden overlappen tussen maaltijden, wordt capaciteit van
+          maaltijd met hoogste prioriteit gebruikt
+
+Stap 4: Geef terug:
+        - guestCounts: { "12:00": 5, "12:15": 3, ... } (beschikbare stoelen)
+        - shiftsInfo: [{ mealType, shiftName, time, availableSeats }, ...]
+```
+
+**Voorbeeld overlapping:**
+```javascript
+// Lunch eindigt om 15:00, Diner start om 14:00
+
+14:00 → Lunch capaciteit: 25, Diner capaciteit: 30
+        Systeem kiest: 30 (diner heeft hogere prioriteit)
+
+14:30 → Lunch capaciteit: 25, Diner capaciteit: 30
+        Systeem kiest: 30 (diner heeft hogere prioriteit)
+```
+
+### 5. Gastentelling per Maaltijdtype (`processing/mealTypeCount.js`)
+
+Voor elk maaltijdtype (ontbijt/lunch/diner):
+
+```
+getGuestCountsForMeal(data, dateStr, mealType, reservations)
+  ↓
+ALS shifts ingeschakeld:
+  Voor elke gedefinieerde shift tijd:
+    - Tel bezette gasten op dat moment via getGuestCountAtHour()
+    - beschikbareStoelen = maxCapacity - bezetteGasten
+
+ANDERS (normale intervallen):
+  Genereer tijdslots: startTime tot endTime met intervalReservatie intervallen
+  Voor elk tijdslot:
+    - Tel bezette gasten via getGuestCountAtHour()
+    - beschikbareStoelen = maxCapacity - bezetteGasten
+```
+
+### 6. Gastentelling op Specifiek Uur (`reservation_data/counter.js`)
+
+```
+getGuestCountAtHour(data, reservations, hour, dateStr)
+  ↓
+Som gasten van alle reserveringen waar:
+  - datum === dateStr
+  - startTime <= hour < (startTime + duurReservatie)
+```
+
+**Voorbeeld:**
+```javascript
+// Bestaande reserveringen op 2025-01-15:
+Reservering A: 12:00, 4 gasten, duur 120 min (12:00 - 14:00)
+Reservering B: 12:30, 2 gasten, duur 120 min (12:30 - 14:30)
+Reservering C: 14:00, 6 gasten, duur 120 min (14:00 - 16:00)
+
+// Gastentelling per tijdslot:
+12:00 → 4 gasten (alleen A)
+12:15 → 4 gasten (alleen A)
+12:30 → 6 gasten (A + B)
+12:45 → 6 gasten (A + B)
+13:00 → 6 gasten (A + B)
+13:30 → 6 gasten (A + B)
+14:00 → 8 gasten (B + C, A is beëindigd)
+14:30 → 8 gasten (B + C)
+15:00 → 6 gasten (alleen C, B is beëindigd)
+```
+
+---
+
+## Datamodellen en Configuratie
+
+### 1. Algemene Instellingen (`general-settings`)
+
+```javascript
+{
+  zitplaatsen: 30,              // Totaal aantal stoelen in restaurant
+  uurOpVoorhand: 4,             // Aantal uren van tevoren vereist voor reservering
+  dagenInToekomst: 90,          // Maximaal aantal dagen vooruit boeken
+  maxGasten: 8,                 // Maximum aantal gasten per reservering
+  intervalReservatie: 15,       // Tijdslot interval in minuten
+  duurReservatie: 120,          // Duur van reservering in minuten
+  minutenTotEinde: 135,         // Minuten tot einde van dienst
+  ontbijtStop: "10:00",         // Stoptijd voor ontbijt (dynamische stop)
+  lunchStop: "14:00",           // Stoptijd voor lunch
+  dinerStop: "20:00"            // Stoptijd voor diner
+}
+```
+
+**Uitleg per instelling:**
+
+- **zitplaatsen**: Het totaal aantal beschikbare stoelen in het hele restaurant
+- **uurOpVoorhand**: Voorkomt last-minute reserveringen; gasten moeten X uren van tevoren boeken
+- **dagenInToekomst**: Beperkt hoe ver vooruit klanten kunnen reserveren
+- **maxGasten**: Maximum groepsgrootte voor online reserveringen
+- **intervalReservatie**: Hoe vaak nieuwe tijdslots beginnen (bv. 15 min = 12:00, 12:15, 12:30...)
+- **duurReservatie**: Standaard duur van elke reservering
+- **minutenTotEinde**: Buffer tijd aan het einde van dienst (voorkomt te late reserveringen)
+- **ontbijtStop/lunchStop/dinerStop**: Voor reserveringen op VANDAAG - stopt nieuwe boekingen na deze tijd
+
+### 2. Maaltijdconfiguratie (`openinghours-breakfast/lunch/dinner`)
+
+```javascript
+{
+  schemeSettings: {
+    Monday: {
+      enabled: true,              // Is deze maaltijd beschikbaar op maandag?
+      startTime: "07:00",         // Starttijd van maaltijd
+      endTime: "11:00",           // Eindtijd van maaltijd
+      maxCapacity: 30,            // Maximum capaciteit voor deze maaltijd
+      shiftsEnabled: false,       // Gebruik shifts modus?
+      shifts: [],                 // Shift configuraties
+      giftcardsEnabled: false,    // Cadeaubonnen beschikbaar?
+      giftcards: []              // Cadeaubon configuraties
+    },
+    Tuesday: { /* ... */ },
+    Wednesday: { /* ... */ },
+    Thursday: { /* ... */ },
+    Friday: { /* ... */ },
+    Saturday: { /* ... */ },
+    Sunday: { /* ... */ }
+  }
+}
+```
+
+**Voorbeeld met shifts:**
+```javascript
+{
+  Monday: {
+    enabled: true,
+    startTime: "18:00",
+    endTime: "22:00",
+    maxCapacity: 40,
+    shiftsEnabled: true,
+    shifts: [
+      { name: "Vroege dienst", time: "18:00" },
+      { name: "Late dienst", time: "20:00" }
+    ]
+  }
+}
+```
+
+### 3. Uitzonderingen (`exceptions`)
+
+Uitzonderingen overschrijven de normale openingstijden.
+
+```javascript
+{
+  type: "Sluiting",             // Type: "Sluiting", "Opening", "Uitzondering"
+  startDate: "2024-12-25",      // Startdatum van uitzondering
+  endDate: "2024-12-25",        // Einddatum van uitzondering
+  daysOfWeek: ["maandag"],      // Dagen van de week (optioneel)
+  timeframe: "Volledige Dag",   // "Volledige Dag" of specifiek maaltijdtype
+  startHour: "12:00",           // Starttijd (voor gedeeltelijke sluitingen)
+  endHour: "15:00",             // Eindtijd (voor gedeeltelijke sluitingen)
+  maxSeats: 20                  // Aangepaste capaciteit (voor "Uitzondering")
+}
+```
+
+**Prioriteitsvolgorde van uitzonderingen:**
+1. **Opening** (hoogste prioriteit) - Opent het restaurant op normaal gesloten dag
+2. **Sluiting** - Sluit het restaurant (geheel of gedeeltelijk)
+3. **Uitzondering** (laagste prioriteit) - Past capaciteit aan zonder te sluiten
+
+**Voorbeelden:**
+
+```javascript
+// Voorbeeld 1: Volledige sluiting op Kerstmis
+{
+  type: "Sluiting",
+  startDate: "2024-12-25",
+  endDate: "2024-12-25",
+  timeframe: "Volledige Dag"
+}
+
+// Voorbeeld 2: Speciale opening op zondag
+{
+  type: "Opening",
+  startDate: "2024-12-01",
+  endDate: "2024-12-01",
+  daysOfWeek: ["zondag"],
+  timeframe: "Lunch",
+  startHour: "12:00",
+  endHour: "16:00",
+  maxSeats: 25
+}
+
+// Voorbeeld 3: Verminderde capaciteit voor privé evenement
+{
+  type: "Uitzondering",
+  startDate: "2024-11-20",
+  endDate: "2024-11-20",
+  timeframe: "Diner",
+  maxSeats: 15  // In plaats van normale 30
+}
+```
+
+---
+
+## Boekingsfilters en Validatie
+
+Na de basis beschikbaarheidsberekening worden extra filters toegepast om de beschikbare tijdslots verder te verfijnen.
+
+### 1. Tijdsfilter (`filters/timeFilter.js`)
+
+Verwijdert tijdslots op basis van stoptijden voor boekingen op dezelfde dag.
+
+```
+Functionaliteit:
+- Verwijdert tijdslots na ontbijtStop/lunchStop/dinerStop
+- Geldt ALLEEN voor reserveringen op VANDAAG
+- Gebruikt Europe/Brussels tijdzone
+
+Voorbeeld:
+Huidige tijd: 09:30
+ontbijtStop: "10:00"
+dateStr: vandaag
+
+Tijdslots voor ontbijt:
+  09:00 ✗ (verleden)
+  09:15 ✗ (verleden)
+  09:30 ✗ (binnen uurOpVoorhand venster)
+  09:45 ✗ (binnen uurOpVoorhand venster)
+  10:00 ✗ (na ontbijtStop)
+  10:15 ✗ (na ontbijtStop)
+```
+
+### 2. Maximum Aankomsten Filter (`filters/maxArrivalsFilter.js`)
+
+Beperkt het aantal gasten dat op exact hetzelfde tijdstip mag aankomen.
+
+```
+filterTimeblocksByMaxArrivals(restaurantData, date, timeblocks, reservations, guests)
+  ↓
+Voor elk tijdsblok:
+  Stap 1: Bepaal maaltijdtype op basis van tijd
+  Stap 2: Haal maxArrivalsConfig[maaltijdtype][tijd] instelling op
+  Stap 3: Tel huidige aankomsten op exact deze tijd op deze datum
+  Stap 4: Sta alleen toe als: huidigeAankomsten + nieuweGasten <= maxAankomsten
+```
+
+**Data structuur:**
+```javascript
+{
+  "max-arrivals-breakfast": {
+    "08:00": 5,   // Max 5 gasten mogen om 08:00 aankomen
+    "08:15": 5,
+    "08:30": 8,
+    "08:45": 8
+  },
+  "max-arrivals-lunch": {
+    "12:00": 10,  // Max 10 gasten mogen om 12:00 aankomen
+    "12:15": 10,
+    "12:30": 12,
+    "12:45": 12
+  },
+  "max-arrivals-dinner": {
+    "18:00": 15,  // Max 15 gasten mogen om 18:00 aankomen
+    "18:30": 15,
+    "19:00": 12,
+    "19:30": 12
+  }
+}
+```
+
+**Voorbeeld scenario:**
+```javascript
+// Bestaande reserveringen op 2025-01-15 om 12:00:
+Reservering A: 12:00, 4 gasten
+Reservering B: 12:00, 3 gasten
+Totaal: 7 gasten
+
+// Nieuwe aanvraag: 4 gasten om 12:00
+maxArrivals voor 12:00 lunch: 10
+
+Berekening: 7 (bestaand) + 4 (nieuw) = 11 > 10
+Resultaat: ✗ GEWEIGERD (te veel aankomsten op dit tijdstip)
+
+// Maar 12:15 is nog beschikbaar:
+Aankomsten om 12:15: 0 gasten
+Berekening: 0 + 4 = 4 ≤ 10
+Resultaat: ✓ TOEGESTAAN
+```
+
+### 3. Maximum Groepen Filter (`filters/maxGroupsFilter.js`)
+
+Beperkt het aantal grote groepen tijdens een maaltijdperiode.
+
+```
+filterTimeblocksByMaxGroups(restaurantData, date, timeblocks, reservations, guests)
+  ↓
+Voor elk tijdsblok:
+  Stap 1: Bepaal maaltijdtype
+  Stap 2: Haal max-groups-{maaltijdtype} instellingen op
+  Stap 3: Instellingenstructuur: { "6": maxAantal, "7": maxAantal, ... }
+          - Definieert: max groepen van grootte >= 6, >= 7, etc.
+  Stap 4: Tel bestaande groepen >= gastGrootte in die maaltijd
+  Stap 5: Sta alleen toe als: bestaandeGroepen + 1 <= maxToegstaneGroepen
+```
+
+**Data structuur:**
+```javascript
+{
+  "max-groups-breakfast": {
+    "6": 2,  // Maximaal 2 groepen van 6+ personen
+    "7": 1,  // Maximaal 1 groep van 7+ personen
+    "8": 0   // Geen groepen van 8+ personen toegestaan
+  },
+  "max-groups-lunch": {
+    "6": 3,  // Maximaal 3 groepen van 6+ personen
+    "7": 2,  // Maximaal 2 groepen van 7+ personen
+    "8": 1   // Maximaal 1 groep van 8+ personen
+  },
+  "max-groups-dinner": {
+    "5": 5,  // Maximaal 5 groepen van 5+ personen
+    "6": 3,  // Maximaal 3 groepen van 6+ personen
+    "7": 2   // Maximaal 2 groepen van 7+ personen
+  }
+}
+```
+
+**Voorbeeld scenario:**
+```javascript
+// Bestaande reserveringen tijdens lunch:
+Reservering A: 6 gasten
+Reservering B: 7 gasten
+Reservering C: 4 gasten (telt niet mee voor "6+" filter)
+
+// Nieuwe aanvraag: 6 gasten voor lunch
+max-groups-lunch configuratie: { "6": 3, "7": 2 }
+
+Berekening voor grootte "6+":
+  Bestaande groepen >= 6: 2 (Reservering A en B)
+  Nieuwe groep: 1
+  Totaal: 2 + 1 = 3 ≤ 3 (max)
+  Resultaat: ✓ TOEGESTAAN
+
+// Maar als er een 7e gast bijkomt:
+Nieuwe aanvraag: 7 gasten voor lunch
+
+Berekening voor grootte "7+":
+  Bestaande groepen >= 7: 1 (Reservering B)
+  Nieuwe groep: 1
+  Totaal: 1 + 1 = 2 ≤ 2 (max)
+  Resultaat: ✓ TOEGESTAAN
+```
+
+**Hoe de drempel werkt:**
+```javascript
+// Voor een groep van 6 personen:
+Controleert: max-groups["6"] → controleert limiet voor groepen van 6+ personen
+
+// Voor een groep van 8 personen:
+Controleert: max-groups["8"], max-groups["7"], max-groups["6"]
+Moet voldoen aan ALLE limieten:
+  - Voldoende ruimte binnen limiet voor 8+ groepen
+  - Voldoende ruimte binnen limiet voor 7+ groepen
+  - Voldoende ruimte binnen limiet voor 6+ groepen
+```
+
+---
+
+## Tafeltoewijzing
+
+Het systeem kan optioneel automatisch tafels toewijzen aan reserveringen.
+
+### 1. Tafel Data Structuur
+
+```javascript
+{
+  tableNumber: 5,              // Uniek tafelnummer
+  tableId: "id123",            // Unieke tafel ID
+  minCapacity: 2,              // Minimum gasten om tafel te vullen
+  maxCapacity: 4,              // Maximum capaciteit
+  priority: 1,                 // Lagere waarde = hogere prioriteit
+  x: 100,                      // X-coördinaat op plattegrond
+  y: 150,                      // Y-coördinaat op plattegrond
+  isTemporary: false,          // Is dit een tijdelijke tafel?
+  startDate: "2024-12-01",     // Startdatum (voor tijdelijke tafels)
+  endDate: "2024-12-31",       // Einddatum (voor tijdelijke tafels)
+  application: "dinner"        // Maaltijdtype restrictie (breakfast/lunch/dinner)
+}
+```
+
+### 2. Enkele Tafel Toewijzing
+
+```
+assignTablesIfPossible({db, reservation, enforceTableAvailability})
+  ↓
+Stap 1: Bereken vereiste slots op basis van startTime + duurReservatie
+        (bv. 12:00 + 120 min = slots: 12:00, 12:15, 12:30, ..., 13:45)
+
+Stap 2: Haal alle tafels op van restaurant.floors
+
+Stap 3: Valideer tijdelijke tafels:
+        - Controleer datum binnen startDate/endDate bereik
+        - Controleer maaltijdtype restrictie (application veld)
+
+Stap 4: Bouw tableOccupiedSlots: { tableNumber: Set([slot1, slot2, ...]) }
+        → Welke tijdslots zijn al bezet per tafel
+
+Stap 5: Probeer eerst vastgepinde groepen (via tryGroupTables)
+
+Stap 6: Als geen groep match:
+        - Vind tafels waar: minCapacity <= gasten <= maxCapacity
+        - Controleer dat tafel vrij is voor ALLE vereiste slots
+        - Selecteer op basis van:
+            1. Kleinste capaciteit die past (minimaliseert verspilling)
+            2. Dan priority (lagere waarde eerst)
+            3. Dan minCapacity (kleinere tafels eerst)
+```
+
+**Voorbeeld tafeltoewijzing:**
+```javascript
+// Beschikbare tafels:
+Tafel 1: min 2, max 4, priority 1
+Tafel 2: min 2, max 4, priority 2
+Tafel 3: min 4, max 6, priority 1
+Tafel 4: min 6, max 8, priority 1
+
+// Nieuwe reservering: 4 gasten om 12:00
+
+Stap 1: Filter tafels waar 4 gasten passen
+  → Tafel 1 ✓ (2-4)
+  → Tafel 2 ✓ (2-4)
+  → Tafel 3 ✓ (4-6)
+  → Tafel 4 ✗ (6-8, te groot - minCapacity > 4)
+
+Stap 2: Sorteer op capaciteit, dan priority, dan minCapacity
+  1. Tafel 1: maxCap 4, priority 1, minCap 2
+  2. Tafel 2: maxCap 4, priority 2, minCap 2
+  3. Tafel 3: maxCap 6, priority 1, minCap 4
+
+Stap 3: Controleer beschikbaarheid in volgorde
+  Tafel 1: Vrij voor alle slots? → JA
+
+Resultaat: Tafel 1 toegewezen ✓
+```
+
+### 3. Vastgepinde Groepen Toewijzing (`grouping.js`)
+
+Voor grote groepen kunnen meerdere tafels worden gecombineerd.
+
+```
+tryGroupTables({restaurantSettings, allTables, guests, ...})
+  ↓
+Stap 1: Controleer of groepering ingeschakeld is in grouping-settings
+
+Stap 2: Valideer dat vastgepinde groepen bestaan en subtables hebben
+
+Stap 3: Voor elke vastgepinde groep:
+        a) Haal alle subtables op
+        b) Controleer: totalMin <= gasten <= totalMax
+        c) Alloceer gasten:
+           - Vul eerst minCapacity van elke subtable
+           - Distribueer resterende gasten
+        d) Verifieer dat alle subtables vrij zijn voor alle vereiste slots
+
+Stap 4: Geef gematchte groep terug met tableNumbers en viaGroup identifier
+```
+
+**Data structuur vastgepinde groepen:**
+```javascript
+{
+  "grouping-settings": {
+    groupingEnabled: true,
+    pinnedGroups: [
+      {
+        groupId: "group1",
+        groupName: "Grote Groep Zone A",
+        subtables: [
+          { tableNumber: 5, minCapacity: 2, maxCapacity: 4 },
+          { tableNumber: 6, minCapacity: 2, maxCapacity: 4 },
+          { tableNumber: 7, minCapacity: 2, maxCapacity: 4 }
+        ]
+      }
+    ]
+  }
+}
+
+// Totale capaciteit: min 6 (2+2+2), max 12 (4+4+4)
+```
+
+**Voorbeeld groepstoewijzing:**
+```javascript
+// Vastgepinde groep: Tafels 5, 6, 7
+Tafel 5: min 2, max 4
+Tafel 6: min 2, max 4
+Tafel 7: min 2, max 4
+Totaal: min 6, max 12
+
+// Nieuwe reservering: 10 gasten
+
+Stap 1: Check capaciteit
+  10 >= 6 (min) ✓
+  10 <= 12 (max) ✓
+
+Stap 2: Alloceer gasten
+  Eerst minCapacity vullen:
+    Tafel 5: 2 gasten (min)
+    Tafel 6: 2 gasten (min)
+    Tafel 7: 2 gasten (min)
+    Totaal: 6 gasten, resterend: 4 gasten
+
+  Dan resterende gasten verdelen:
+    Tafel 5: +2 gasten → 4 gasten (max bereikt)
+    Tafel 6: +2 gasten → 4 gasten (max bereikt)
+    Tafel 7: +0 gasten → 2 gasten
+    Totaal: 10 gasten ✓
+
+Stap 3: Controleer beschikbaarheid
+  Tafel 5 vrij? ✓
+  Tafel 6 vrij? ✓
+  Tafel 7 vrij? ✓
+
+Resultaat: Tafels 5, 6, 7 toegewezen als groep ✓
+```
+
+---
+
+## Volledige Reserveringsflow
+
+Hier is de complete flow van een reservering van begin tot eind:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Gebruiker vraagt beschikbaarheid voor X gasten op datum D  │
+└────────────────────────┬────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STAP 1: isDateAvailableWithTableCheck()                     │
+│                                                              │
+│ a) isDateAvailable() → Basis beschikbaarheidscheck          │
+│    - Controleer dagenInToekomst bereik                      │
+│    - Haal beschikbare timeblocks op                         │
+│                                                              │
+│ b) ALS tafeltoewijzing ingeschakeld:                        │
+│    Voor elk beschikbaar timeblock:                          │
+│      - Check timeHasGiftcard() als cadeaubon geselecteerd   │
+│      - Check isTimeAvailableSync() → kunnen tafels worden   │
+│        toegewezen?                                           │
+│    Return TRUE als ER EEN timeblock beschikbare tafel heeft │
+│                                                              │
+│ c) Return beschikbaarheidsflag                              │
+└────────────────────────┬────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────┐
+│ Gebruiker selecteert tijd T op datum D                      │
+└────────────────────────┬────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STAP 2: assignTablesIfPossible()                            │
+│                                                              │
+│ Probeer vastgepinde groep →                                 │
+│ Probeer enkele tafel →                                      │
+│ Wijs toe                                                     │
+└────────────────────────┬────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STAP 3: Maak reservering met toegewezen tafel(s)           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Gedetailleerde Stappen
+
+#### **Stap 1a: Basis Beschikbaarheidscheck**
+
+```javascript
+// Voorbeeld aanroep
+isDateAvailable(restaurantData, "2025-01-15", bestaandeReserveringen, 4)
+
+// Interne flow:
+1. Check: "2025-01-15" binnen 90 dagen? ✓
+2. Roep getAvailableTimeblocks() aan
+   → Krijg: { "12:00": true, "12:15": true, "12:30": false, ... }
+3. Filter lege resultaten
+4. Return: true (er zijn beschikbare tijden)
+```
+
+#### **Stap 1b: Tafelbeschikbaarheidscheck** (optioneel)
+
+```javascript
+// Voor elk beschikbaar tijdsblok
+Voor tijd "12:00":
+  1. Check: Heeft deze tijd cadeaubon als vereist? ✓
+  2. Roep isTimeAvailableSync("2025-01-15", "12:00", 4) aan
+     → Probeer tafel toe te wijzen (zonder op te slaan)
+     → Return: true als tafel beschikbaar
+  3. Als true: behoud "12:00" in beschikbare lijst
+  4. Als false: verwijder "12:00" uit beschikbare lijst
+
+Uiteindelijk resultaat: Alleen tijden waar zowel capaciteit ALS tafels beschikbaar zijn
+```
+
+#### **Stap 2: Tafel Toewijzing**
+
+```javascript
+// Wanneer gebruiker tijd selecteert
+assignTablesIfPossible({
+  db: database,
+  reservation: {
+    date: "2025-01-15",
+    startTime: "12:00",
+    guests: 4,
+    durationMinutes: 120
+  },
+  enforceTableAvailability: true
+})
+
+// Interne flow:
+1. Bereken slots: ["12:00", "12:15", "12:30", ..., "13:45"]
+2. Haal alle tafels op en filter tijdelijke/applicatie restricties
+3. Bouw occupied slots map voor elke tafel
+4. Probeer groepstoewijzing (als 4 >= min groepsgrootte)
+   → Geen match gevonden
+5. Probeer enkele tafel:
+   → Tafel 3 past (min 2, max 4)
+   → Tafel 3 is vrij voor alle slots ✓
+   → Wijs Tafel 3 toe
+6. Return: { success: true, assignedTables: [3] }
+```
+
+#### **Stap 3: Reservering Opslaan**
+
+```javascript
+// Reservering object
+{
+  id: "res123",
+  date: "2025-01-15",
+  startTime: "12:00",
+  guests: 4,
+  assignedTables: [3],
+  customerName: "Jan Janssen",
+  email: "jan@example.com",
+  phone: "+31612345678"
+}
+
+// Opgeslagen in database
+// Toekomstige beschikbaarheidschecks zullen deze reservering meenemen
+```
+
+---
+
+## Belangrijke Validatieregels
+
+Bij elke reserveringsaanvraag worden de volgende regels gecontroleerd:
+
+### 1. **Datumvalidatie**
+```
+Regel: Datum moet binnen dagenInToekomst bereik liggen
+Check: dateStr >= vandaag EN dateStr <= vandaag + dagenInToekomst
+
+Voorbeeld:
+  Vandaag: 2025-01-15
+  dagenInToekomst: 90
+  Toegestaan bereik: 2025-01-15 tot 2025-04-15
+
+  Aanvraag: 2025-02-01 ✓ (binnen bereik)
+  Aanvraag: 2025-05-01 ✗ (buiten bereik)
+```
+
+### 2. **Tijdvalidatie**
+```
+Regel: Tijd moet binnen maaltijd operationele uren vallen (met uitzonderingen)
+Check: startTime >= mealStartTime EN startTime < mealEndTime
+
+Voorbeeld:
+  Lunch: 12:00 - 15:00
+
+  Aanvraag: 12:00 ✓ (binnen maaltijd)
+  Aanvraag: 14:30 ✓ (binnen maaltijd)
+  Aanvraag: 15:00 ✗ (na eindtijd)
+```
+
+### 3. **Duurvalidatie**
+```
+Regel: Starttijd + duurReservatie moet binnen maaltijd eindtijd passen
+Check: startTime + duurReservatie <= mealEndTime
+
+Voorbeeld:
+  Lunch eindigt: 15:00
+  Duur reservering: 120 minuten
+
+  Aanvraag: 12:00 → eindigt 14:00 ✓ (past binnen lunch)
+  Aanvraag: 13:30 → eindigt 15:30 ✗ (loopt over eindtijd heen)
+
+  Let op: minutenTotEinde (135 min) wordt ook gecontroleerd
+  Laatste toegestane start: 15:00 - 135 min = 12:45
+```
+
+### 4. **Capaciteitsvalidatie**
+```
+Regel: Beschikbare stoelen >= aantal gasten voor ALLE opeenvolgende slots
+Check: Voor elke vereiste slot, availableSeats >= requestedGuests
+
+Voorbeeld:
+  Reservering: 4 gasten om 12:00, duur 120 min
+  Vereiste slots: 12:00, 12:15, 12:30, 12:45, 13:00, 13:15, 13:30, 13:45
+
+  Beschikbare stoelen per slot:
+    12:00 → 6 stoelen ✓
+    12:15 → 5 stoelen ✓
+    12:30 → 3 stoelen ✗ (TE WEINIG!)
+
+  Resultaat: ✗ AFGEWEZEN (niet alle slots hebben voldoende capaciteit)
+```
+
+### 5. **Vooraf Boekingsvalidatie**
+```
+Regel: Voor reserveringen VANDAAG, moet starttijd >= uurOpVoorhand uren van nu
+Check: startDateTime >= huidigeDateTime + uurOpVoorhand
+
+Voorbeeld:
+  Huidige tijd: 10:00
+  uurOpVoorhand: 4 uren
+  Minimum starttijd: 14:00
+
+  Aanvraag: 12:00 ✗ (binnen 4 uur venster)
+  Aanvraag: 14:00 ✓ (exact 4 uur vooruit)
+  Aanvraag: 15:00 ✓ (meer dan 4 uur vooruit)
+```
+
+### 6. **Stoptijdvalidatie**
+```
+Regel: Kan niet boeken na ontbijtStop/lunchStop/dinerStop als datum = vandaag
+Check: Als dateStr === vandaag, filter tijden > stopTijd voor die maaltijd
+
+Voorbeeld:
+  Huidige tijd: 09:30
+  ontbijtStop: "10:00"
+  Datum: vandaag
+
+  Beschikbare ontbijttijden:
+    09:00 ✗ (in het verleden)
+    09:15 ✗ (in het verleden)
+    09:30 ✗ (binnen uurOpVoorhand)
+    09:45 ✗ (binnen uurOpVoorhand)
+    10:00 ✗ (na stopTijd)
+    10:15 ✗ (na stopTijd)
+```
+
+### 7. **Tafelvalidatie** (indien tafeltoewijzing ingeschakeld)
+```
+Regel: Tafel moet vrije slots hebben + capaciteit matchen + aan restricties voldoen
+Check:
+  a) minCapacity <= gasten <= maxCapacity
+  b) Alle vereiste tijdslots zijn vrij
+  c) Als tijdelijk: datum binnen startDate/endDate
+  d) Als application beperkt: maaltijdtype matcht
+
+Voorbeeld:
+  Tafel 5: min 2, max 4, application: "dinner", tijdelijk: 01-12 tot 31-12
+
+  Aanvraag: 4 gasten, lunch, 15 december
+    Capaciteit: 2 <= 4 <= 4 ✓
+    Datum: 15-12 binnen 01-12 tot 31-12 ✓
+    Maaltijdtype: lunch ≠ dinner ✗
+
+  Resultaat: ✗ AFGEWEZEN (maaltijdtype restrictie)
+```
+
+### 8. **Maximum Aankomsten Validatie**
+```
+Regel: Totale aankomsten op exact tijdstip <= maxArrivals voor die tijd
+Check: bestaandeAankomsten[tijd] + nieuweGasten <= maxArrivals[tijd]
+
+Voorbeeld:
+  maxArrivals lunch 12:00: 10 gasten
+  Bestaande aankomsten om 12:00: 7 gasten
+
+  Aanvraag: 4 gasten om 12:00
+    7 + 4 = 11 > 10 ✗
+
+  Resultaat: ✗ AFGEWEZEN (te veel gelijktijdige aankomsten)
+```
+
+### 9. **Maximum Groepen Validatie**
+```
+Regel: Aantal groepen van grootte X in maaltijd <= maxGroups voor die grootte
+Check: bestaandeGroepen[grootte] + 1 <= maxGroups[grootte]
+
+Voorbeeld:
+  maxGroups lunch: { "6": 3, "7": 2 }
+  Bestaande lunch reserveringen:
+    - 6 gasten (groep 1)
+    - 7 gasten (groep 2)
+    - 4 gasten (telt niet mee)
+
+  Aanvraag: 6 gasten voor lunch
+    Voor grootte "6+": 2 bestaande + 1 nieuwe = 3 <= 3 ✓
+
+  Resultaat: ✓ TOEGESTAAN (precies aan limiet)
+
+  Volgende aanvraag: nog 6 gasten
+    Voor grootte "6+": 3 bestaande + 1 nieuwe = 4 > 3 ✗
+
+  Resultaat: ✗ AFGEWEZEN (te veel grote groepen)
+```
+
+---
+
+## Samenvatting
+
+Het HappyChef reserveringssysteem is een geavanceerd, meerlagig algoritme dat:
+
+1. **Beschikbaarheid berekent** op basis van capaciteit, openingstijden, en bestaande reserveringen
+2. **Meerdere maaltijdtypes ondersteunt** met verschillende configuraties en prioriteiten
+3. **Uitzonderingen afhandelt** zoals feestdagen, sluitingen, en speciale evenementen
+4. **Filters toepast** om ongewenste scenario's te voorkomen (te veel aankomsten, te grote groepen)
+5. **Automatisch tafels toewijst** met ondersteuning voor enkele tafels en gecombineerde groepen
+6. **Intelligent valideert** met 9 verschillende validatieregels
+
+Het systeem is gebouwd om flexibel, schaalbaar en betrouwbaar te zijn voor moderne restaurantoperaties.
+
+---
+
+## Bestandslocaties
+
+Alle belangrijke bestanden bevinden zich in `/home/user/15-happy-algorithm/`:
+
+- **Hoofdingang**: `index.js`
+- **Restaurant data**: `restaurant_data/openinghours.js`, `restaurant_data/exceptions.js`
+- **Processing engines**: `processing/timeblocksAvailable.js`, `processing/dailyGuestCounts.js`
+- **Filters**: `filters/timeFilter.js`, `filters/maxArrivalsFilter.js`, `filters/maxGroupsFilter.js`
+- **Tafelbeheer**: `assignTables.js`, `grouping.js`, `tableHelpers.js`