Sluijsens
8072025e0b
Finishes the master-cms-module feature (Units 1-4): runs Build and Test across master-backend, slave-availability-extension and frontend-cms-page, fixes a missing Availability EF migration for MasterRegistration and a TanStack Query v5 mutation-callback type break, adds the missing MasterModule appsettings section, and documents the module in README.md. Also seeds a tech-debt-backlog feature to track dead config and pre-existing/introduced frontend lint findings for later cleanup.
42 lines
5.5 KiB
Markdown
42 lines
5.5 KiB
Markdown
# Code Generation Plan — Unit 4: documentation
|
|
|
|
## Unit Context
|
|
- **Scope**: Update `README.md` (root) with a Master CMS Module section covering the new module, migrations, and production env vars; replace the default Vite template `frontend/README.md` was never actually replaced by Unit 3 and still contains boilerplate — bring it in line with the rest of the documented feature set.
|
|
- **Depends on**: Units 1-3 (master-backend, slave-availability-extension, frontend-cms-page) — documents their final, built-and-tested patterns.
|
|
- **No new code**: Documentation only; no business logic, no NFRs, no tests. Functional Design / NFR Requirements / NFR Design were correctly skipped for this unit.
|
|
|
|
## Steps
|
|
|
|
- [x] **Step 1 — Root README: Add "Master CMS Module" section**
|
|
Add a new `## Master CMS Module` section to `README.md` after the existing "Nieuwe Module Toevoegen" section, covering:
|
|
- What the module does (Owner registers/manages slave CMS instances; slaves enforce master-controlled availability)
|
|
- Architecture summary: `SlpModularCms.Modules.Master` (per-module `MasterDbContext`), extended `SlpModularCms.Modules.Availability` (slave-side `MasterRegistration` + two-phase `AvailabilityMiddleware`)
|
|
- Registration flow: Owner adds a slave URL via `/cms` → Master generates an API key → Master pushes registration to the slave's `/api/v1/master/register` (`X-Master-Api-Key` header)
|
|
- Status flow: Owner toggles status on Master → Master pushes to slave synchronously → fail-open on push failure (DB change not rolled back) → `IntegrityCheckBackgroundService` retries/reconciles on `IntegrityCheckIntervalMinutes` (default 60)
|
|
- Fail-open behavior: slave defaults `_masterIsAvailable = true` at startup; no TTL on cached status
|
|
|
|
- [x] **Step 2 — Root README: Extend "Database Migraties" section**
|
|
Add a subsection noting that `SlpModularCms.Modules.Master` and `SlpModularCms.Modules.Availability` are per-module `DbContext`s with their own migrations, applied automatically at startup via `Database.Migrate()`. Document the exact commands:
|
|
```powershell
|
|
dotnet ef migrations add <Naam> --project src\SlpModularCms.Modules.Master --startup-project src\SlpModularCms.Api
|
|
dotnet ef migrations add <Naam> --project src\SlpModularCms.Modules.Availability --startup-project src\SlpModularCms.Api --context AvailabilityDbContext
|
|
```
|
|
Note the `--context` requirement for the Availability project (it now hosts two logical concerns sharing one `AvailabilityDbContext`, but `dotnet ef` needs disambiguation because the API composes multiple `DbContext` types across modules).
|
|
|
|
- [x] **Step 3 — Root README: Extend "Productie Setup" section**
|
|
Add the new production-relevant configuration:
|
|
- `MasterModule` options actually consumed by the code (bound from config section `MasterModule`): `IntegrityCheckIntervalMinutes` (default 60), `HttpTimeoutSeconds` (default 10), `MasterUrl`. **Revised during execution**: `CacheMinutes` and `ApiKey` are declared on `MasterModuleOptions` but never read anywhere in the codebase (verified via `dotnet-appsettings` skill pass) — they were superseded by Unit 2's actual design (per-instance encrypted keys, no-TTL cache). Left undocumented here per user decision; tracked as TD-001 in the new `tech-debt-backlog` feature instead of documenting dead config as if live.
|
|
- **Data Protection key ring warning** (per NFR tech-stack-decisions.md): the API key encryption uses ASP.NET Core Data Protection with the default file-system key store. For containerized/multi-instance deployments, configure a persistent key ring (`PersistKeysToDbContext`, `PersistKeysToAzureBlobStorage`, etc.) — otherwise a container restart makes all stored `ApiKey` values undecryptable, breaking master↔slave communication until instances are re-added.
|
|
- **Added during execution**: actual `MasterModule` config section added to `appsettings.json` and `appsettings.Development.json` (was completely missing before this unit, discovered via the `dotnet-appsettings` skill pass).
|
|
|
|
- [x] **Step 4 — Replace `frontend/README.md`**
|
|
Replace the default Vite/React template content with a short pointer document: describe the frontend briefly and redirect to the root `README.md`'s "Frontend Development (CMS Admin UI)" section, which already documents setup, scripts, and configuration in full. Avoids duplicating content that already exists and stays in sync.
|
|
|
|
- [x] **Step 5 — Update feature state**
|
|
Mark Unit 4 (documentation) Code Generation complete in `aidlc-docs/features/master-cms-module/aidlc-state.md`; update `aidlc-docs/active-features.md` status.
|
|
|
|
## Deviations From Plan (logged during execution)
|
|
- **Missing EF migration found & fixed**: `SlpModularCms.Modules.Availability` had no migration for `MasterRegistration` (Unit 2 gap). Generated during Build & Test, before this unit started — see `aidlc-docs/features/master-cms-module/construction/build-and-test/build-and-test-summary.md`.
|
|
- **Lint baseline correction**: the "all pre-existing" claim for frontend lint findings in the Build & Test summary was based on a contaminated comparison; corrected via a clean `git worktree` checkout. 2 of the 6 lint findings are new (Unit 3); all 6 moved to `tech-debt-backlog` (TD-002/TD-003) rather than fixed in-flight, per user decision.
|
|
- **appsettings gap found & fixed**: `MasterModule` config section was entirely absent from `appsettings.json`/`appsettings.Development.json` despite `MasterModuleOptions.BindConfiguration("MasterModule")` in code. Added both files during this unit's execution (see Step 3).
|