UI styling improvements: dashboard headers and navigation
- Restore blue PageHeader on Dashboard (/app-components) - Update homepage (/) with subtle header design without blue bar - Add uniform PageHeader styling to application edit page - Fix Rapporten link on homepage to point to /reports overview - Improve header descriptions spacing for better readability
This commit is contained in:
211
docs/DATABASE-DRIVEN-SCHEMA-IMPLEMENTATION-PLAN.md
Normal file
211
docs/DATABASE-DRIVEN-SCHEMA-IMPLEMENTATION-PLAN.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# Database-Driven Schema Implementation Plan
|
||||
|
||||
## Overzicht
|
||||
|
||||
Dit plan beschrijft de migratie van statische schema files naar een volledig database-driven aanpak waarbij:
|
||||
1. Schema wordt dynamisch opgehaald van Jira Assets API
|
||||
2. Schema wordt opgeslagen in PostgreSQL database
|
||||
3. Datamodel en datavalidatie pagina's worden opgebouwd vanuit database
|
||||
4. TypeScript types worden gegenereerd vanuit database (handmatig)
|
||||
|
||||
## Architectuur
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Jira Assets API │ (Authoritative Source)
|
||||
└────────┬────────┘
|
||||
│
|
||||
│ Schema Discovery
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Schema Discovery│ (Jira API → Database)
|
||||
│ Service │
|
||||
└────────┬────────┘
|
||||
│
|
||||
│ Store in DB
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ PostgreSQL DB │ (Cached Schema)
|
||||
│ - object_types │
|
||||
│ - attributes │
|
||||
└────────┬────────┘
|
||||
│
|
||||
│ Serve to Frontend
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ API Endpoints │ (/api/schema)
|
||||
└────────┬────────┘
|
||||
│
|
||||
│ Code Generation
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ TypeScript Types │ (Handmatig gegenereerd)
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## Database Schema
|
||||
|
||||
De database heeft al de benodigde tabellen in `normalized-schema.ts`:
|
||||
- `object_types` - Object type definities
|
||||
- `attributes` - Attribute definities per object type
|
||||
|
||||
**Geen extra tabellen nodig!** We gebruiken de bestaande structuur.
|
||||
|
||||
## Implementatie Stappen
|
||||
|
||||
### Stap 1: Schema Discovery Service Aanpassen ✅
|
||||
|
||||
**Huidige situatie:**
|
||||
- `schemaDiscoveryService` haalt data uit statische `OBJECT_TYPES` file
|
||||
|
||||
**Nieuwe situatie:**
|
||||
- `schemaDiscoveryService` haalt schema direct van Jira Assets API
|
||||
- Gebruikt `JiraSchemaFetcher` logica (uit `generate-schema.ts`)
|
||||
- Slaat schema op in database tabellen
|
||||
|
||||
**Bestanden:**
|
||||
- `backend/src/services/schemaDiscoveryService.ts` - Aanpassen om API calls te maken
|
||||
|
||||
### Stap 2: Schema Cache Service ✅
|
||||
|
||||
**Nieuwe service:**
|
||||
- In-memory cache met 5 minuten TTL
|
||||
- Cache invalidation bij schema updates
|
||||
- Snelle response voor `/api/schema` endpoint
|
||||
|
||||
**Bestanden:**
|
||||
- `backend/src/services/schemaCacheService.ts` - Nieuw bestand
|
||||
|
||||
### Stap 3: Schema API Endpoint Migreren ✅
|
||||
|
||||
**Huidige situatie:**
|
||||
- `/api/schema` endpoint leest van statische `OBJECT_TYPES` file
|
||||
|
||||
**Nieuwe situatie:**
|
||||
- `/api/schema` endpoint leest van database (via cache)
|
||||
- Gebruikt `schemaCacheService` voor performance
|
||||
|
||||
**Bestanden:**
|
||||
- `backend/src/routes/schema.ts` - Aanpassen om database te gebruiken
|
||||
|
||||
### Stap 4: Code Generation Script ✅
|
||||
|
||||
**Nieuwe functionaliteit:**
|
||||
- Script dat database schema → TypeScript types genereert
|
||||
- Handmatig uitvoerbaar via CLI command
|
||||
- Genereert: `jira-schema.ts`, `jira-types.ts`
|
||||
|
||||
**Bestanden:**
|
||||
- `backend/scripts/generate-types-from-db.ts` - Nieuw bestand
|
||||
- `package.json` - NPM script toevoegen
|
||||
|
||||
### Stap 5: Datavalidatie Pagina Migreren ✅
|
||||
|
||||
**Huidige situatie:**
|
||||
- Gebruikt mogelijk statische schema files
|
||||
|
||||
**Nieuwe situatie:**
|
||||
- Volledig database-driven
|
||||
- Gebruikt `schemaDiscoveryService` voor schema data
|
||||
|
||||
**Bestanden:**
|
||||
- `backend/src/routes/dataValidation.ts` - Controleren en aanpassen indien nodig
|
||||
|
||||
### Stap 6: Database Indexes ✅
|
||||
|
||||
**Toevoegen:**
|
||||
- Indexes voor snelle schema queries
|
||||
- Performance optimalisatie
|
||||
|
||||
**Bestanden:**
|
||||
- `backend/src/services/database/normalized-schema.ts` - Indexes toevoegen
|
||||
|
||||
### Stap 7: CLI Command voor Schema Discovery ✅
|
||||
|
||||
**Nieuwe functionaliteit:**
|
||||
- Handmatige trigger voor schema discovery
|
||||
- Bijvoorbeeld: `npm run discover-schema`
|
||||
|
||||
**Bestanden:**
|
||||
- `backend/scripts/discover-schema.ts` - Nieuw bestand
|
||||
- `package.json` - NPM script toevoegen
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### GET /api/schema
|
||||
**Huidig:** Leest van statische files
|
||||
**Nieuw:** Leest van database (via cache)
|
||||
|
||||
**Response format:** Ongewijzigd (backward compatible)
|
||||
|
||||
### POST /api/schema/discover (Nieuw)
|
||||
**Functionaliteit:** Handmatige trigger voor schema discovery
|
||||
**Gebruik:** Admin endpoint voor handmatige schema refresh
|
||||
|
||||
## Code Generation
|
||||
|
||||
### Script: `generate-types-from-db.ts`
|
||||
**Input:** Database schema (object_types, attributes)
|
||||
**Output:**
|
||||
- `backend/src/generated/jira-schema.ts`
|
||||
- `backend/src/generated/jira-types.ts`
|
||||
|
||||
**Uitvoering:** Handmatig via `npm run generate-types`
|
||||
|
||||
## Migratie Strategie
|
||||
|
||||
1. **Parallelle implementatie:** Nieuwe code naast oude code
|
||||
2. **Feature flag:** Optioneel om tussen oude/nieuwe aanpak te switchen
|
||||
3. **Testing:** Uitgebreide tests voor schema discovery
|
||||
4. **Handmatige migratie:** Breaking changes worden handmatig opgelost
|
||||
|
||||
## Performance Overwegingen
|
||||
|
||||
- **In-memory cache:** 5 minuten TTL voor schema endpoints
|
||||
- **Database indexes:** Voor snelle queries op object_types en attributes
|
||||
- **Lazy loading:** Schema wordt alleen geladen wanneer nodig
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
- **Geen fallback:** Als database schema niet beschikbaar is, werkt niets
|
||||
- **TypeScript errors:** Bij schema wijzigingen ontstaan compile errors
|
||||
- **Handmatige fix:** Developers lossen errors handmatig op
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] Schema discovery van Jira API werkt
|
||||
- [ ] Schema wordt correct opgeslagen in database
|
||||
- [ ] `/api/schema` endpoint retourneert database data
|
||||
- [ ] Cache werkt correct (TTL, invalidation)
|
||||
- [ ] Code generation script werkt
|
||||
- [ ] Datamodel pagina toont database data
|
||||
- [ ] Datavalidatie pagina toont database data
|
||||
- [ ] Handmatige schema discovery trigger werkt
|
||||
|
||||
## Rollout Plan
|
||||
|
||||
1. **Fase 1:** Schema discovery service aanpassen (API calls)
|
||||
2. **Fase 2:** Schema cache service implementeren
|
||||
3. **Fase 3:** API endpoints migreren
|
||||
4. **Fase 4:** Code generation script maken
|
||||
5. **Fase 5:** Testing en validatie
|
||||
6. **Fase 6:** Oude statische files verwijderen (na handmatige migratie)
|
||||
|
||||
## Risico's en Mitigatie
|
||||
|
||||
| Risico | Impact | Mitigatie |
|
||||
|--------|--------|-----------|
|
||||
| Jira API niet beschikbaar | Hoog | Geen fallback - downtime acceptabel |
|
||||
| Schema wijzigingen | Medium | TypeScript errors - handmatig oplossen |
|
||||
| Performance issues | Laag | Cache + indexes |
|
||||
| Data migratie fouten | Medium | Uitgebreide tests |
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ Schema wordt dynamisch opgehaald van Jira API
|
||||
✅ Schema wordt opgeslagen in database
|
||||
✅ Datamodel pagina toont database data
|
||||
✅ Datavalidatie pagina toont database data
|
||||
✅ Code generation script werkt
|
||||
✅ Handmatige schema discovery werkt
|
||||
✅ Performance is acceptabel (< 1s voor schema endpoint)
|
||||
Reference in New Issue
Block a user