157 lines
7.8 KiB
Markdown
157 lines
7.8 KiB
Markdown
# Requirements Document — SlpModularCms.Api
|
|
|
|
## Intent Analyse
|
|
|
|
- **Gebruikersverzoek**: Een modulaire CMS API bouwen als raamwerk voor klantprojecten, met authenticatie, autorisatie en gebruikersbeheer als MVP, uitbreidbaar via modules.
|
|
- **Request Type**: Nieuw project (Greenfield)
|
|
- **Scope Schatting**: Systeem-breed — meerdere componenten (raamwerk + modules architectuur)
|
|
- **Complexiteit Schatting**: Complex — meerdere lagen, modulaire architectuur, beschikbaarheidscontrole mechanisme
|
|
|
|
---
|
|
|
|
## Functionele Requirements
|
|
|
|
### FR-01: Authenticatie
|
|
- Het systeem MOET JWT Bearer token authenticatie ondersteunen
|
|
- Tokens MOETEN een configureerbare vervaltijd hebben
|
|
- Het systeem MOET refresh tokens ondersteunen voor het vernieuwen van sessies
|
|
- Tokens MOETEN gebruikersidentiteit en rollen bevatten als claims
|
|
|
|
### FR-02: Autorisatie
|
|
- Het systeem MOET role-based access control (RBAC) ondersteunen
|
|
- Standaard rollen (hiërarchie hoog → laag): **Eigenaar (Owner)**, **Beheerder (Administrator)**, **Gebruiker (User)**
|
|
- Endpoints MOETEN beveiligd kunnen worden op basis van rollen
|
|
- **Eigenaar**:
|
|
- Heeft alle rechten zonder uitzondering
|
|
- Kan NIET worden verwijderd door andere rollen
|
|
- Kan een andere gebruiker als Eigenaar instellen (eigenaarschap overdragen)
|
|
- Kan rollen van alle gebruikers wijzigen inclusief Beheerders
|
|
- **Beheerder**:
|
|
- Heeft dezelfde rechten als Eigenaar, behalve:
|
|
- Kan de Eigenaar GEEN andere rol geven
|
|
- Kan GEEN nieuwe Eigenaar instellen
|
|
- Kan Gebruikers en andere Beheerders (lager in hiërarchie) beheren
|
|
- Kan content beheren
|
|
- **Gebruiker**:
|
|
- Heeft beperkte rechten die per klant/tenant configureerbaar zijn
|
|
- Specifieke rechten worden ingesteld door een Beheerder of Eigenaar
|
|
- Een gebruiker kan nooit een hogere rol aan zichzelf of anderen toekennen dan zijn eigen rol
|
|
|
|
### FR-03: Gebruikersbeheer
|
|
- Het systeem MOET CRUD-operaties bieden voor gebruikers (aanmaken, lezen, bijwerken, verwijderen)
|
|
- Gebruikers MOETEN een e-mailadres, wachtwoord en rol hebben
|
|
- Wachtwoorden MOETEN veilig worden opgeslagen (gehasht)
|
|
- **GEEN zelfregistratie**: Gebruikers kunnen zich NIET zelf registreren via een publiek endpoint
|
|
- Alleen een **Beheerder** of **Eigenaar** mag nieuwe gebruikers aanmaken
|
|
- Het systeem MOET een login endpoint bieden (`POST /api/auth/login`)
|
|
- Beheerders en Eigenaars MOETEN gebruikersrollen kunnen wijzigen (binnen hun hiërarchische bevoegdheid)
|
|
- Bij aanmaken van een gebruiker stelt de Beheerder/Eigenaar het initiële wachtwoord in of wordt een uitnodigingsflow gebruikt
|
|
|
|
### FR-04: Module Architectuur
|
|
- Modules MOETEN worden geïmplementeerd als aparte class libraries (.csproj)
|
|
- Het raamwerk MOET een mechanisme bieden om modules te registreren en te laden
|
|
- Modules MOETEN onafhankelijk van elkaar kunnen worden toegevoegd of verwijderd
|
|
- Het raamwerk MOET een standaard interface/contract definiëren waaraan modules moeten voldoen
|
|
|
|
### FR-05: Beschikbaarheidscontrole (Master-API — MVP Placeholder)
|
|
- Het raamwerk MOET een placeholder/stub bevatten voor de toekomstige master-API beschikbaarheidscontrole
|
|
- De stub MOET een interface definiëren (`IAvailabilityService` of vergelijkbaar) zodat de echte implementatie later eenvoudig kan worden ingeplugd
|
|
- De stub MOET standaard altijd "beschikbaar" retourneren in de MVP
|
|
- De architectuur MOET het mogelijk maken om modules op afstand uit te zetten (via de interface, implementatie later)
|
|
|
|
### FR-06: API Endpoints
|
|
- De API MOET RESTful endpoints bieden (standaard HTTP verbs: GET, POST, PUT, DELETE)
|
|
- De API MOET Swagger/OpenAPI documentatie bieden
|
|
- Alle beveiligde endpoints MOETEN een geldig JWT token vereisen
|
|
|
|
---
|
|
|
|
## Niet-Functionele Requirements
|
|
|
|
### NFR-01: Technologie Stack
|
|
- **Runtime**: .NET 10 (ASP.NET Core)
|
|
- **Database**: SQL Server
|
|
- **ORM**: Entity Framework Core (code-first met migrations)
|
|
- **Authenticatie**: ASP.NET Core Identity + JWT Bearer
|
|
- **API Stijl**: REST (Controllers)
|
|
- **Documentatie**: Swagger / OpenAPI (Swashbuckle)
|
|
|
|
### NFR-02: Architectuur
|
|
- **Patroon**: Single-tenant (één instantie per klant)
|
|
- **Module systeem**: Aparte class libraries (.csproj) per module
|
|
- **Deployment**: On-premises / eigen server
|
|
- **Structuur**: Clean Architecture of gelaagde architectuur (API → Application → Domain → Infrastructure)
|
|
|
|
### NFR-03: Beveiliging (Security Baseline — INGESCHAKELD)
|
|
- Wachtwoorden MOETEN worden gehasht met een veilig algoritme (bcrypt of ASP.NET Core Identity standaard)
|
|
- JWT tokens MOETEN worden ondertekend met een sterke sleutel (minimaal 256-bit)
|
|
- De API MOET HTTPS afdwingen
|
|
- Gevoelige configuratie (connection strings, JWT secrets) MOETEN via environment variables of secrets management worden beheerd
|
|
- Input validatie MOET worden toegepast op alle endpoints
|
|
- SQL injection MOET worden voorkomen (via EF Core parameterisatie)
|
|
- CORS MOET expliciet worden geconfigureerd
|
|
|
|
### NFR-04: Onderhoudbaarheid
|
|
- Code MOET goed gestructureerd en leesbaar zijn
|
|
- Modules MOETEN een duidelijk contract/interface volgen
|
|
- Het project MOET unit tests bevatten voor business logic
|
|
- Migrations MOETEN worden bijgehouden in versiebeheer
|
|
|
|
### NFR-05: Schaalbaarheid
|
|
- De architectuur MOET het eenvoudig maken om nieuwe modules toe te voegen zonder het raamwerk te wijzigen
|
|
- De beschikbaarheidscontrole interface MOET later kunnen worden vervangen door een echte implementatie zonder grote refactoring
|
|
|
|
### NFR-06: Property-Based Testing (GEDEELTELIJK INGESCHAKELD)
|
|
- Property-based testing MOET worden toegepast voor pure functies en serialisatie round-trips
|
|
- Specifiek: token generatie/validatie logica en data mapping functies
|
|
|
|
---
|
|
|
|
## Gebruikersscenario's
|
|
|
|
### Scenario 1: Beheerder voegt gebruiker toe
|
|
Een Beheerder of Eigenaar maakt een nieuwe gebruiker aan via `POST /api/users` met e-mail, wachtwoord en rol. Het systeem maakt het account aan en retourneert een bevestiging. Zelfregistratie is niet mogelijk.
|
|
|
|
### Scenario 2: Gebruiker logt in
|
|
Een gebruiker logt in via `POST /api/auth/login` met e-mail en wachtwoord. Het systeem valideert de credentials en retourneert een JWT access token en refresh token.
|
|
|
|
### Scenario 3: Beheerder/Eigenaar beheert gebruikers
|
|
Een Beheerder of Eigenaar raadpleegt alle gebruikers via `GET /api/users`, wijzigt een rol via `PUT /api/users/{id}/role` (binnen hiërarchische bevoegdheid), of verwijdert een gebruiker via `DELETE /api/users/{id}`. Een Eigenaar kan niet worden verwijderd door een Beheerder.
|
|
|
|
### Scenario 4: Beveiligd endpoint benaderen
|
|
Een client stuurt een request naar een beveiligd endpoint met een JWT token in de Authorization header. Het systeem valideert het token en verleent of weigert toegang op basis van de rol.
|
|
|
|
### Scenario 5: Module wordt geladen
|
|
Bij het opstarten van de API worden alle geregistreerde modules automatisch geladen en hun endpoints/services geregistreerd in de DI container.
|
|
|
|
---
|
|
|
|
## Technische Context
|
|
|
|
- **Workspace Root**: `K:\Development\Projects\SlpModularCms`
|
|
- **Hoofdproject**: `SlpModularCms.Api` (ASP.NET Core Web API)
|
|
- **Solution**: `SlpModularCms.sln`
|
|
- **Toekomstige uitbreiding**: Master-API module voor beschikbaarheidscontrole (buiten MVP scope)
|
|
|
|
---
|
|
|
|
## Extension Configuratie
|
|
|
|
| Extension | Ingeschakeld | Beslist bij |
|
|
|---|---|---|
|
|
| Security Baseline | Ja | Requirements Analysis |
|
|
| Property-Based Testing | Gedeeltelijk | Requirements Analysis |
|
|
|
|
---
|
|
|
|
## Succescriteria MVP
|
|
|
|
- [ ] Gebruikers kunnen inloggen via JWT (geen zelfregistratie)
|
|
- [ ] Rollen (Eigenaar, Beheerder, Gebruiker) zijn geïmplementeerd met hiërarchische bevoegdheden
|
|
- [ ] CRUD voor gebruikers is beschikbaar voor Beheerders en Eigenaars
|
|
- [ ] Eigenaar kan niet worden verwijderd en kan eigenaarschap overdragen
|
|
- [ ] Module architectuur is opgezet met minimaal één voorbeeldmodule
|
|
- [ ] Beschikbaarheidscontrole placeholder/stub is aanwezig
|
|
- [ ] Swagger documentatie is beschikbaar
|
|
- [ ] Alle beveiligingsvereisten zijn geïmplementeerd
|