Adds 2 units and docs for unit 3. nfr-requirements plan

2026-06-29 22:18:37 +02:00
parent 0e01ca1e1c
commit c156107cb1
126 changed files with 15204 additions and 80199 deletions
@@ -0,0 +1,110 @@
+# NFR Requirements Plan — Unit 1: master-backend
+
+## Unit Context
+
+**Unit**: `master-backend`
+**Applicable NFRs**: NFR-MASTER-01 (fail-open), NFR-MASTER-03 (API key security), NFR-MASTER-04 (background service interval), NFR-MASTER-05 (≥80% test coverage), NFR-MASTER-06 (per-module migrations)
+
+---
+
+## NFR Questions
+
+Answer each question by filling in your choice after the `[Answer]:` tag.
+
+---
+
+### Q1 — HTTP Timeout for Slave API Calls
+
+The `SlaveApiClient` calls slave endpoints for registration, status push, and integrity checks. What HTTP timeout should be configured?
+
+A) **5 seconds** — short timeout; registration and status push are synchronous user-triggered actions; a hanging slave should not block the owner long.
+
+B) **15 seconds** — moderate timeout; balances responsiveness with tolerance for temporarily slow slaves.
+
+C) **30 seconds** — generous timeout; maximizes chance of successful contact before giving up.
+
+D) **Configurable via `MasterModuleOptions.HttpTimeoutSeconds` (default 10)** — owner can tune per-environment; sensible default.
+
+E) Other
+
+[Answer]: D
+
+---
+
+### Q2 — HTTP Retry Policy for Slave API Calls
+
+Should `SlaveApiClient` retry failed HTTP calls automatically, or fail immediately and rely on the next integrity check cycle for recovery?
+
+A) **No retry — fail immediately** — if a slave is unreachable, return `false` at once; the background integrity check handles eventual re-registration; keeps user-visible latency predictable.
+
+B) **1 retry with short delay (e.g., 2s)** — single retry on transient failures (network blip); still bounded latency; reduces false negatives on flaky connections.
+
+C) **Exponential backoff (3 attempts)** — standard resilience pattern; handles transient errors well; may add up to ~7s latency in worst case.
+
+D) Other
+
+[Answer]: C
+
+---
+
+### Q3 — ASP.NET Core Data Protection Key Storage
+
+The `ApiKey` values are encrypted with `IDataProtector`. Where should Data Protection keys be stored?
+
+A) **Default file system** (`%APPDATA%\Microsoft\UserSecrets` / platform default) — zero configuration; keys are machine-bound; acceptable for single-instance deployments.
+
+B) **SQL Server via EF Core** (`services.AddDataProtection().PersistKeysToDbContext<MasterDbContext>()`) — keys survive container restarts and work across deployable instances; requires a `DataProtectionKeys` table in `MasterDbContext`.
+
+C) **Default for now, documented as a production concern** — use the default in code; add a note in documentation that production deployments should configure persistent key storage.
+
+D) Other
+
+[Answer]: A
+
+---
+
+### Q4 — Test Coverage: Exclusions
+
+NFR-MASTER-05 requires ≥80% coverage on new backend code. Which classes should be excluded from coverage measurement for `SlpModularCms.Modules.Master`?
+
+A) **Module registration + migrations only** — exclude `MasterModule.cs` (module registration boilerplate) and EF Core migration files; cover everything else including controllers, services, and repository.
+
+B) **Module registration, migrations, and DTOs/records** — additionally exclude plain record/DTO classes (no logic to test); cover all classes with business logic.
+
+C) **No exclusions** — aim for ≥80% including all files; let natural coverage determine what's tested.
+
+D) Other
+
+[Answer]: B
+
+---
+
+### Q5 — Logging for Slave Contact Failures
+
+When a slave is unreachable during a status push or integrity check, at what log level should the failure be recorded?
+
+A) **Warning** — slave unreachability is expected during network issues; `Warning` signals the issue without triggering on-call alerts; appropriate for a fail-open system.
+
+B) **Error** — slave contact failures represent a degraded state; `Error` ensures visibility in monitoring dashboards and may trigger alerts.
+
+C) **Warning for integrity checks, Error for status push failures** — integrity checks are background maintenance; status push failures have direct owner impact.
+
+D) Other
+
+[Answer]: C
+
+---
+
+## Execution Steps
+
+After all questions above are answered, the following artifacts will be generated:
+
+- [x] **Step 1** — Analyze all answers; flag any ambiguities
+- [x] **Step 2** — Generate `nfr-requirements.md` — performance, security, reliability, testability, maintainability requirements
+- [x] **Step 3** — Generate `tech-stack-decisions.md` — HTTP client config, Data Protection, retry policy, logging
+- [x] **Step 4** — Update `aidlc-state.md`
+- [x] **Step 5** — Present completion message for user approval
+
+---
+
+*Artifact path*: `aidlc-docs/features/master-cms-module/construction/plans/master-backend-nfr-requirements-plan.md`