Adds SlpModularCms.Api.SlpSoftware and extracts shared CmsHost composition

Unit 1 of the slpsoftware-api feature (FR-1/FR-2/FR-3): a new Client project in the Clients solution folder, intended to eventually become the deployed API for test.slpsoftware.nl/slpsoftware.nl, hosting the same four modules as SlpModularCms.Api plus a future Offerings module. - Extracts SlpModularCms.Api/Program.cs's hosting-pipeline composition into SlpModularCms.Core.Hosting.CmsHost (ConfigureServices/ConfigurePipeline), shared by both Client projects so they cannot drift apart - Moves StaticContentExtensions.cs + WebsitePlaceholder.html from Api into Core, since CmsHost cannot live in Api but Core cannot depend on Api - Adds SlpModularCms.Api.SlpSoftware with its own isolated local dev database and dev ports (5286/7223, distinct from Api's and Api.Slave's) - Adds SlpModularCms.Api.Tests with WebApplicationFactory-based pipeline regression tests (security headers, health check, SPA fallback, rate limiting), scoped to Api per NFR Design - Adds a frontend dev:slpsoftware pnpm script mirroring dev:slave - Fixes GlobalExceptionHandler logging routine 401s (e.g. an expired/missing refresh token) as unhandled errors -- pre-existing, unrelated to this feature's own scope, found while testing the new instance Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWyStNL2ZsjrS7FLd7xvvN
2026-08-02 01:28:39 +02:00
parent dcc82cdf62
commit fa389e42ee
51 changed files with 3119 additions and 127 deletions
@@ -0,0 +1,86 @@
+# Code Generation Plan — Unit: SlpSoftware Client Setup
+
+## Unit Context
+
+**Stories implemented**: None directly (unit-of-work-story-map.md — this unit is a purely technical enabling unit).
+**Functional requirements implemented**: FR-1, FR-2, FR-3.
+**Dependencies**: None on other units (this unit is the dependency Unit 2 "Offerings" needs).
+**Expected interfaces produced**: `SlpModularCms.Core.Hosting.CmsHost` (`ConfigureServices`/`ConfigurePipeline`), consumed by both Client projects' `Program.cs`.
+**Database entities owned**: None.
+**Workspace root**: `K:\Development\Projects\SlpModularCms` (brownfield — modify/move existing files where noted, never duplicate).
+
+## Investigation Finding That Shapes This Plan
+
+Reading `SlpModularCms.Api/Program.cs` and `SlpModularCms.Api/Extensions/StaticContentExtensions.cs` directly (not assumed) revealed that `UseCmsStaticContent()`/`MapCmsSpaFallbacks()` — needed by `CmsHost.ConfigurePipeline` — currently live in the **`Api` project itself**, not in `Core`. Since `Core` cannot depend on `Api` (wrong dependency direction — `Api` depends on `Core`, never the reverse), this file (and its embedded `WebsitePlaceholder.html` resource) must move into `Core` **before** `CmsHost` can call it. This is Step 1 below, not an afterthought.
+
+---
+
+## Steps
+
+### Step 1 — Move Static Content Hosting into Core (prerequisite for CmsHost)
+- [x] Move `src/SlpModularCms.Api/Extensions/StaticContentExtensions.cs` → `src/SlpModularCms.Core/Hosting/StaticContentExtensions.cs`; change namespace `SlpModularCms.Api.Extensions` → `SlpModularCms.Core.Hosting`; update `PlaceholderResourceName` from `"SlpModularCms.Api.Extensions.WebsitePlaceholder.html"` to `"SlpModularCms.Core.Hosting.WebsitePlaceholder.html"`
+- [x] Move `src/SlpModularCms.Api/Extensions/WebsitePlaceholder.html` → `src/SlpModularCms.Core/Hosting/WebsitePlaceholder.html`
+- [x] `SlpModularCms.Core.csproj`: add `<EmbeddedResource Include="Hosting\WebsitePlaceholder.html" />`
+- [x] `SlpModularCms.Api.csproj`: remove the now-obsolete `<EmbeddedResource Include="Extensions\WebsitePlaceholder.html" />` item group and its explanatory comment (the file no longer lives there)
+- [x] Delete the now-empty `src/SlpModularCms.Api/Extensions/` directory if nothing else remains in it
+
+### Step 2 — `CmsHostOptions` (Business Logic Generation — Core)
+- [x] Create `src/SlpModularCms.Core/Hosting/CmsHostOptions.cs`: an intentionally empty class (NFR Design Pattern 2 / Q2 = B) — a pure extension point, no properties yet
+
+### Step 3 — `CmsHost` (Business Logic Generation — Core)
+- [x] Create `src/SlpModularCms.Core/Hosting/CmsHost.cs` with:
+  - `public static ModuleOrchestrator ConfigureServices(WebApplicationBuilder builder, CmsHostOptions options)` — reproduces `Api/Program.cs` lines for: `appsettings.local.json` loading stays in each project's own `Program.cs` (NOT moved here — application-design.md component-methods.md is explicit that bootstrap lines stay per-project); logging (`AddCmsLogging`), Sentry (`UseCmsSentry`), `ModuleOrchestrator` construction + `DiscoverModules()`, `AddCoreInfrastructure`, `AddCmsCors`, `AddCmsRateLimiting`, `AddCmsHealthChecks`, `AddCmsSecurityHeaders`, `AddCmsObservability`, `AddCmsDataProtection` (before module services — order preserved exactly), `RegisterModuleServices`, `AddSingleton(orchestrator)`, `AddControllers` with `ApiPrefixConvention("api/v1")` + `JsonStringEnumConverter`. Returns the orchestrator.
+  - `public static void ConfigurePipeline(WebApplication app, ModuleOrchestrator orchestrator, CmsHostOptions options)` — reproduces: `MigrateCoreDatabase`, `UseExceptionHandler`, `UseCmsSecurityHeaders`, `UseRateLimiter`, Development-only `MapOpenApi`/`MapScalarApiReference`, `UseHttpsRedirection`, `UseCmsStaticContent`, `UseCors`, `orchestrator.UseModules(app)`, `UseAuthentication`/`UseAuthorization`, `MapControllers`, `MapCmsHealthChecks`, `MapSentryTunnel`, `MapCmsSpaFallbacks` — same order as today's `Program.cs`, since that order encodes real constraints documented in its comments
+- [x] Both methods accept `CmsHostOptions` per NFR-CS-02, even though it currently has no properties to read
+
+### Step 4 — Repoint `SlpModularCms.Api/Program.cs` (Modify In-Place)
+- [x] Rewrite `src/SlpModularCms.Api/Program.cs` to the thin form: create builder, load `appsettings.local.json`, `var orchestrator = CmsHost.ConfigureServices(builder, new CmsHostOptions());`, `var app = builder.Build();`, `CmsHost.ConfigurePipeline(app, orchestrator, new CmsHostOptions());`, `app.Run();`
+- [x] No behavior change — verified by Step 7's regression tests
+
+### Step 5 — New Client Project: `SlpModularCms.Api.SlpSoftware` (Project Structure Setup)
+- [x] Create `src/SlpModularCms.Api.SlpSoftware/SlpModularCms.Api.SlpSoftware.csproj` — mirrors `SlpModularCms.Api.csproj` (SDK, `TargetFramework`, `Nullable`, `ImplicitUsings`, same package references: `Asp.Versioning.Mvc`, `Microsoft.AspNetCore.Authentication.JwtBearer`, `Microsoft.AspNetCore.OpenApi`, `Microsoft.EntityFrameworkCore.Design`, `Scalar.AspNetCore`), **without** the `WebsitePlaceholder.html` embedded resource (that now lives in `Core`, shared) and **without** a `Modules.Offerings` reference (added later by Unit 2, per unit-of-work.md)
+  - `ProjectReference`: `SlpModularCms.Core`, `SlpModularCms.Modules.Availability`, `SlpModularCms.Modules.Identity`, `SlpModularCms.Modules.Master` (FR-2)
+- [x] Create `src/SlpModularCms.Api.SlpSoftware/Program.cs` — same thin shape as Step 4's rewritten `Api/Program.cs`
+- [x] Create `src/SlpModularCms.Api.SlpSoftware/appsettings.json` — mirrors `Api`'s structure/keys (connection string placeholder, JWT settings, Availability, MasterModule, MasterPolling, Cors, RateLimiting, SecurityHeaders, Observability sections)
+- [x] Create `src/SlpModularCms.Api.SlpSoftware/appsettings.Development.json` — mirrors `Api`'s Development file, but with its **own isolated local dev database name** (Infrastructure Design Q1 = B), e.g. `Database=SlpModularCmsSlpSoftwareDev`
+- [x] **Not creating** `appsettings.local.json` — it's git-ignored (verified: listed in `.gitignore`, not tracked in git) and personal per-developer; the developer creates their own copy locally if needed, same as for `Api`
+- [x] **Not creating** `Program.Coverage.cs` for this project in this unit — Infrastructure/NFR Design (Q1 = C) scoped the new pipeline regression tests to `Api` only, so there is no test target requiring `Program` to be a public partial class here yet; add it in a future unit/feature if `Api.SlpSoftware`-specific pipeline tests are ever introduced
+
+### Step 6 — Solution File Updates (`SlpModularCms.sln`)
+- [x] Add `SlpModularCms.Api.SlpSoftware` project entry, nested under the existing (currently empty) `Clients` solution folder (`{D72703E6-B021-4360-B1EE-0E99999B5899}`)
+- [x] Add `SlpModularCms.Api.Tests` project entry (Step 7), nested directly under `Tests` (`{2F43D186-C7D5-4AB1-B821-4D595CA2ECB3}`) — mirroring how `SlpModularCms.Core.Tests` is nested directly under `Tests`, not under `Tests/Modules`
+- [x] Add both new projects' GUIDs to `ProjectConfigurationPlatforms` (Debug/Release × Any CPU/x64/x86, matching the existing pattern for every other project)
+- [x] Add both new projects' GUIDs to `NestedProjects`
+
+### Step 7 — Pipeline Regression Tests (Business Logic Unit Testing, NFR-CS-01)
+- [x] Create `src/SlpModularCms.Api.Tests/SlpModularCms.Api.Tests.csproj` — same SDK-style shape as `SlpModularCms.Core.Tests.csproj` (xunit, FluentAssertions, `Microsoft.NET.Test.Sdk`, `coverlet.collector`), plus `Microsoft.AspNetCore.Mvc.Testing` (provides `WebApplicationFactory<TEntryPoint>`); `ProjectReference` to `SlpModularCms.Api.csproj` (its `Program.Coverage.cs` already makes `Program` a public partial class, so no further change needed there)
+- [x] Create `src/SlpModularCms.Api.Tests/PipelineTests.cs` using `WebApplicationFactory<Program>`, asserting (NFR-CS-01 / NFR Design Pattern 1):
+  - Required security headers (CSP, HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy) present on a representative response
+  - `/health` returns a successful response
+  - A non-file `/admin/{path}` route resolves to the admin SPA's `index.html` fallback (or, absent a built SPA in the test environment, at minimum does not 404 as a missing-file/static-asset request would)
+  - A burst of requests against a rate-limited route eventually receives `429 Too Many Requests`
+
+### Step 8 — Business Logic Summary
+- [x] Create `aidlc-docs/features/slpsoftware-api/construction/slpsoftware-client-setup/code/summary.md` (markdown only) summarizing: files moved (Step 1), `CmsHost`/`CmsHostOptions` added, `Api/Program.cs` rewritten, `Api.SlpSoftware` created, solution file changes, tests added
+
+### Step 9 — API Layer / Repository Layer Generation
+- [x] **N/A** — this unit introduces no new HTTP endpoints or persisted entities (FR-1/FR-2/FR-3 are pure composition/project-scaffolding); these categories apply to Unit 2 "Offerings" instead
+
+### Step 10 — Database Migration Scripts
+- [x] **N/A** — no new data model in this unit
+
+### Step 11 — Documentation Generation
+- [x] Update root `README.md`: add `SlpModularCms.Api.SlpSoftware` to the project-structure description alongside `SlpModularCms.Api`/`SlpModularCms.Api.Slave`, and add a short note under the existing architecture/hosting section explaining `CmsHost` as the shared composition point both Client projects call, plus a one-line note that `Api.SlpSoftware` uses its own local dev database (Infrastructure Design Q1 = B)
+
+### Step 12 — Deployment Artifacts Generation
+- [x] **N/A for this Construction stage** — per Infrastructure Design, no `.gitea/workflows/*.yaml` or Gitea Actions variable changes happen here; the CI/CD retarget is explicitly Operations-phase work (D-7/D-15)
+
+### Step 13 — Build and Test Verification (automatic, Step 13.5 of the workflow)
+- [x] Build the full solution (or at minimum `Api`, `Api.SlpSoftware`, `Core`, `Api.Tests`) and confirm it compiles
+- [x] Run `SlpModularCms.Api.Tests` (new) and confirm all pipeline regression tests pass against `Api`
+- [x] Run `SlpModularCms.Core.Tests` (existing) and confirm nothing regressed from the Step 1 file move
+- [x] Fix and retry on any failure; only surface to the user if a fix requires a decision only they can make
+
+---
+
+**Scope reminder**: this plan implements Unit 1 only. Unit 2 "Offerings" (all 12 user stories) is a separate Code Generation pass, after this unit is approved and its own Build and Test step is green.
@@ -0,0 +1,30 @@
+# Infrastructure Design Plan — Unit: SlpSoftware Client Setup
+
+Voordat ik vragen stelde, heb ik `aidlc-docs/features/gitea-deployment-workflow/operations/deployment/deployment-instructions.md` (de bestaande, gedetailleerde deploy-documentatie van de feature die de huidige pipeline bezit) volledig gelezen. Dat geeft keihard bewijs voor bijna elke categorie hieronder — vandaar dat er maar één echte vraag overblijft.
+
+## Al opgelost via bestaand bewijs (geen vraag nodig)
+
+- **Deployment Environment / Compute**: één Raspberry Pi ("pi-main"), test en productie gescheiden per directory/systemd-unit/poort (5100/5101). Een aparte proxy-Pi regelt TLS-terminatie. Dit verandert niet door deze feature — D-15 is een **cutover**, geen nieuwe, aparte deploy-slot. Zodra de Operations-fase de pipeline omzet, draait `Api.SlpSoftware` **op precies dezelfde plek** als `Api` nu draait: zelfde Pi, zelfde systemd-unitnamen (`slpsoftware-test.service`/`slpsoftware-production.service`), zelfde poorten, zelfde domeinen. Het enige wat verandert is de ExecStart-regel (`SlpModularCms.Api.dll` → `SlpModularCms.Api.SlpSoftware.dll`) en het CI-publish-artefact — en dat is expliciet Operations-werk (D-7), niet iets wat deze Construction-stage of deze unit's Code Generation al hoeft aan te passen.
+- **Networking**: geen nginx-wijziging nodig (al vastgelegd als D-6/NFR-1) — de bestaande proxy-Pi-configuratie blijft ongewijzigd, hij proxied gewoon naar dezelfde poort, ongeacht welke `.dll` daar luistert.
+- **Storage (productie/test)**: zelfde MariaDB-instantie op pi-main, zelfde databasenamen (`SlpSoftwareTest`/`SlpSoftwareProduction`) — logisch gevolg van "cutover, geen nieuwe aparte app".
+- **Monitoring**: zelfde Sentry-project/DSN, onderscheiden via de bestaande `Observability__Environment`-tag — geen wijziging nodig.
+- **Shared Infrastructure/multi-tenancy**: N/A — single-tenant deployment, geen wijziging.
+- **Geen wijzigingen aan `.gitea/workflows/*.yaml` of Gitea Actions-variabelen in deze stage** — dat is expliciet Operations-fase-werk (D-7/D-15). Deze stage documenteert alleen de doelvorm, zodat Code Generation niets bouwt wat daar niet in past.
+
+## Uitvoeringschecklist
+
+- [x] Stap A — `infrastructure-design.md`: bovenstaande bevindingen + antwoord op Vraag 1 vastleggen
+- [x] Stap B — `deployment-architecture.md`: doelarchitectuur voor `Api.SlpSoftware` na de toekomstige cutover (referentie, geen wijziging nu)
+
+---
+
+## Vragen
+
+### Vraag 1 — Lokale ontwikkeldatabase voor `Api.SlpSoftware`
+Voor productie/test is de databasekeuze al duidelijk (hierboven). Voor **lokale ontwikkeling** (jouw eigen machine) is dat nog niet vastgelegd: moet `Api.SlpSoftware` lokaal dezelfde database gebruiken als `Api` vandaag, of een eigen, aparte lokale database?
+
+A) Dezelfde lokale database als `Api` — handig als je makkelijk wilt wisselen tussen beide projecten met dezelfde testdata; risico op onderlinge beïnvloeding tijdens ontwikkeling van de Offerings-module (Unit 2)
+B) Eigen, aparte lokale database voor `Api.SlpSoftware` — geïsoleerde ontwikkelomgeving, geen kans dat het testen van de Offerings-module `Api`'s lokale data raakt; wel een aparte lokale database aanmaken
+X) Anders (beschrijf hieronder na de [Answer]:-tag)
+
+[Answer]:B
@@ -0,0 +1,34 @@
+# NFR Design Plan — Unit: SlpSoftware Client Setup
+
+**Categorieën die niet van toepassing zijn (met onderbouwing, niet zomaar overgeslagen)**:
+- **Scalability Patterns**: N/A — deze unit voegt geen belasting toe, ze hercomponeert bestaande middleware. Geen nieuwe schaal-grenzen.
+- **Performance Patterns**: N/A — zelfde reden; geen nieuwe latency/throughput-doelen, alleen reproductie van bestaand gedrag.
+- **Security Patterns**: al besloten in NFR Requirements (NFR-CS-03) — "identiek gedrag, geverifieerd door de nieuwe regressietests" is het patroon; er is geen los ontwerp nodig bovenop wat NFR-CS-01 al vastlegt.
+
+## Uitvoeringschecklist
+
+- [x] Stap A — `nfr-design-patterns.md`: testpatroon en observability-patroon vastleggen
+- [x] Stap B — `logical-components.md`: de nieuwe testproject-structuur en `CmsHostOptions` als logische componenten beschrijven
+
+---
+
+## Vragen
+
+### Vraag 1 — Tegen welk(e) project(en) draaien de nieuwe pipeline-tests?
+NFR-CS-01 vereist nieuwe `WebApplicationFactory`-gebaseerde tests die het pipeline-gedrag verifiëren. Ze kunnen tegen `Api`, tegen `Api.SlpSoftware`, of tegen beide draaien.
+
+A) Tegen beide Client-projecten — één gedeelde/geparametriseerde testsuite die tegen zowel `Api` als `Api.SlpSoftware` draait; sterkste garantie dat `CmsHost` zich op beide identiek gedraagt, iets meer testtijd
+B) Alleen tegen `Api.SlpSoftware` — het project waar het écht om gaat (toekomstige productie-host); `Api` blijft ongetest op pipeline-niveau maar heeft z'n bestaande (unit-niveau) testsuite nog
+C) Alleen tegen `Api` — bestaat al, sneller op te zetten; `Api.SlpSoftware` erft het vertrouwen via de gedeelde `CmsHost`-code
+X) Anders (beschrijf hieronder na de [Answer]:-tag)
+
+[Answer]: C
+
+### Vraag 2 — Inhoud van `CmsHostOptions`
+Tech-stack-decisions.md liet de exacte vorm van `CmsHostOptions` open. Voor het NFR-ontwerp: moet de klasse nu al één concreet, direct nuttig veld krijgen, of blijft het een lege plaatshouder?
+
+A) Eén concreet veld nu: bijv. `HostLabel`/`ApplicationName` (string) — gebruikt voor observability-tagging (logs/Sentry), zodat je straks in gedeelde logging kunt onderscheiden of een entry van `Api` of `Api.SlpSoftware` komt. Direct nuttig, geen giswerk over toekomstige velden.
+B) Volledig lege plaatshouderklasse — puur een uitbreidingspunt zonder velden, tot er een concrete behoefte is
+X) Anders (beschrijf hieronder na de [Answer]:-tag)
+
+[Answer]: B
@@ -0,0 +1,37 @@
+# NFR Requirements Plan — Unit: SlpSoftware Client Setup
+
+**Waarom Functional Design is overgeslagen voor deze unit**: geen nieuw datamodel, geen nieuwe business rules — dit is een pure hosting-compositie-extractie (FR-1/FR-2/FR-3), zonder domeinlogica om te ontwerpen. Rechtstreeks door naar NFR Requirements.
+
+**Al vastgelegd, hier niet opnieuw bevraagd**:
+- **Security**: deze unit introduceert geen nieuw aanvalsoppervlak (geen nieuwe module, geen nieuwe business logic) — het enige vereiste is dat de bestaande Security Baseline-regels (SECURITY-03/04/09/10/14/15) na de extractie **exact** hetzelfde gedrag opleveren als vandaag. Zie Vraag 1 hieronder voor hoe dat geverifieerd wordt.
+- **Database-scheiding**: `Api` en `Api.SlpSoftware` gebruiken elk hun eigen `appsettings.json`/`appsettings.local.json` (bestaand `dotnet-appsettings`-patroon, ook al toegepast tussen `Api` en `Api.Slave`) — dus per omgeving een eigen connection string. Geen wijziging t.o.v. vandaag, geen vraag nodig.
+
+## Uitvoeringschecklist
+
+- [x] Stap A — `nfr-requirements.md`: NFR's voor deze unit vastleggen (reliability/testability, maintainability)
+- [x] Stap B — `tech-stack-decisions.md`: bevestigen dat geen nieuwe technologie nodig is; vastleggen of `CmsHost` parameterloos blijft
+
+---
+
+## Vragen
+
+### Vraag 1 — Regressietest-strengheid voor de `CmsHost`-extractie
+`Api/Program.cs` bevat vandaag gedrag dat niet mag veranderen: security headers, rate limiting, health checks, static content + SPA-fallback, Sentry-tunnel. Hoe streng moet geverifieerd worden dat `CmsHost` dat gedrag exact reproduceert?
+
+A) Vertrouwen op `Api`'s bestaande testsuite die ongewijzigd groen blijft — voldoende signaal, geen nieuwe tests specifiek voor deze extractie
+B) Nieuwe integratietests toevoegen die specifiek het pipeline-gedrag assert (headerwaarden aanwezig, health-endpoint bereikbaar, SPA-fallback lost op) — blijvende regressiebewaking voor beide Client-projecten, ook na deze feature
+C) Alleen handmatige smoke-test (beide apps lokaal draaien, responses vergelijken), geen nieuwe geautomatiseerde tests
+X) Anders (beschrijf hieronder na de [Answer]:-tag)
+
+[Answer]: A, als dit voldoende dekking geeft, anders B
+
+### Vraag 2 — Uitbreidbaarheid van `CmsHost`
+`CmsHost.ConfigureServices`/`ConfigurePipeline` (application-design/component-methods.md) hebben vandaag geen parameters buiten `WebApplicationBuilder`/`WebApplication` — beide Client-projecten roepen ze identiek aan.
+
+Moet er nu al ruimte komen voor toekomstige verschillen tussen projecten (bijv. een `CmsHostOptions`-object), of pas toevoegen zodra er een echte reden voor is?
+
+A) Parameterloos houden voor nu (YAGNI) — pas een parameter toevoegen zodra `Api` en `Api.SlpSoftware` daadwerkelijk moeten verschillen
+B) Nu al een klein `CmsHostOptions`-object toevoegen, ook al geven beide aanroepen vandaag identieke waarden door
+X) Anders (beschrijf hieronder na de [Answer]:-tag)
+
+[Answer]: B