U7 — tells a website builder what they need to know

WEBSITE_WORKSPACE.md, plus the parts of the README that were still describing the old layout or a manual step the code doesn't need anymore (the key-ring paragraph, mainly - that one was actively wrong now, not just stale).
2026-07-28 16:30:19 +02:00
parent 9f4ae475e7
commit 88770c5bd0
6 changed files with 258 additions and 6 deletions
@@ -0,0 +1,63 @@
+# Code Generation Plan — U7 Repository Documentation
+
+## Unit Context
+
+- **Unit**: U7 Repository Documentation (Documentation-only — no components, no code)
+- **Requirements**: FR-09
+- **Depends on**: U6 (settled host layout — `unit-of-work-dependency.md`: "U6 before U7 —
+  documentation cannot precede the layout it documents")
+- **No Functional/NFR/Infrastructure Design, no test project**: per the execution plan, this unit
+  goes straight to Code Generation
+- **Scope split** (Q8 of Requirements = A): repository documentation here; operational documents
+  (host setup, rollback, FTPS switch) belong to the Operations phase, not this unit
+
+## Steps
+
+- [x] Step 1: Create `WEBSITE_WORKSPACE.md` at the repository root — the website workspace contract
+  (FR-09): target path `wwwroot/web/` and required structure (must include `index.html`), forbidden
+  paths (`wwwroot/admin/`, the application root), reserved paths (`/admin`, `/api/v1`, `/health`),
+  SPA-fallback behaviour (non-file paths fall back to the website's own `index.html`; paths with a
+  file extension 404 if missing), calling `/api/v1` same-origin with relative URLs (no CORS needed),
+  which CSP policy applies to the public website (`Relaxed`, the default policy — `/admin`,
+  `/api/v1` and `/health` get `Strict`) and what that permits, and how to include the Umami
+  tracking script
+
+- [x] Step 2: Update `README.md`
+  - New `wwwroot` layout: `/` → `wwwroot/web/` (customer website, deployed separately, persists
+    across releases), `/admin` → `wwwroot/admin/` (this repo's admin SPA), link to
+    `WEBSITE_WORKSPACE.md` for the full contract
+  - `/health` endpoint: what it proves (process liveness only) and what it explicitly does not mean
+    (not the same as `Availability/status` or `System/capabilities`)
+  - Production setup section rewritten for what U1–U6 actually built: CI/CD via Gitea Actions
+    (`continuous_integration.yaml` → `deploy-scp.yaml`), atomic release switching, and the Data
+    Protection key ring being automatic now (removing the old manual "you must configure a
+    persistent key ring" instruction, since U2 already wires `PersistKeysToDbContext` by default)
+  - New runtime configuration environment variables introduced by U3/U4: `SecurityHeaders__*`,
+    `Observability__SentryDsn`, plus the frontend's `VITE_SENTRY_DSN` / `VITE_UMAMI_SCRIPT_URL` /
+    `VITE_UMAMI_WEBSITE_ID`
+
+- [x] Step 3: Update `frontend/.env.example`
+  - Document the same-origin default: an absent or empty `VITE_API_BASE_URL` now means same-origin
+    (the production default, since the SPA and API are served by one process); explicit absolute
+    URLs still work unchanged for local development
+  - Add the new observability variables: `VITE_SENTRY_DSN`, `VITE_APP_ENV`, `VITE_UMAMI_SCRIPT_URL`,
+    `VITE_UMAMI_WEBSITE_ID`, each documented as optional/absent-is-supported
+
+- [x] Step 4: Verify documentation accuracy against the code as built (Definition of Done)
+  - Cross-checked every path, config key and behaviour claim against the actual U1–U6 source:
+    `Program.cs` fallback/placeholder wiring, `SlpModularCms.Api.csproj`'s `BuildAndCopyAdminFrontend`
+    and embedded `WebsitePlaceholder.html`, `AvailabilityMiddleware._bypassPrefixes`, U2's
+    `MigrateCoreDatabase()` fail-fast and `PersistKeysToDbContext` discriminator, U3's
+    `PathPolicies` fail-at-startup and `Relaxed`/`Strict` split in `appsettings.json`, U4's
+    Sentry/Umami absent-is-supported behaviour, U6's `linux-arm64` framework-dependent publish and
+    atomic release switch. No discrepancies found between the design record and what was actually
+    built — all documentation claims verified directly against source
+
+## Story / Requirement Traceability
+
+| Step | Covers |
+|---|---|
+| 1 | FR-09 |
+| 2 | FR-07, FR-08, FR-10 (documented, not re-implemented), FR-12 (key ring note) |
+| 3 | FR-13, FR-14, FR-15, FR-16 (documented, not re-implemented) |
+| 4 | Definition of Done: "documentation is accurate against the code as built in U1–U6" |