Adds 2 units and docs for unit 3. nfr-requirements plan
This commit is contained in:
@@ -0,0 +1,154 @@
|
||||
# Application Design Plan — Master CMS Module
|
||||
|
||||
## Overview
|
||||
|
||||
This plan covers the high-level component identification and service layer design for the Master CMS Module.
|
||||
The feature spans four units: `master-backend`, `slave-availability-extension`, `frontend-cms-page`, and `documentation`.
|
||||
|
||||
Before generating design artifacts, a set of design questions must be answered below.
|
||||
|
||||
---
|
||||
|
||||
## Design Questions
|
||||
|
||||
Answer each question by filling in your choice after the `[Answer]:` tag.
|
||||
|
||||
---
|
||||
|
||||
### Q1 — HTTP Client for Master → Slave Communication
|
||||
|
||||
The Master CMS needs to call slave CMS REST endpoints for:
|
||||
- Auto-registration (FR-MASTER-03)
|
||||
- Status push (FR-MASTER-05)
|
||||
- Integrity verification (FR-MASTER-04)
|
||||
|
||||
How should the HTTP client be organized in `SlpModularCms.Modules.Master`?
|
||||
|
||||
A) **Typed client** — define `ISlaveApiClient` interface + `SlaveApiClient` implementation; registered via `services.AddHttpClient<ISlaveApiClient, SlaveApiClient>()`. Clean, testable, injectable.
|
||||
|
||||
B) **Named client** — register a named `HttpClient` ("slave") via `IHttpClientFactory` and inject `IHttpClientFactory` into the service that makes calls. Less abstraction, but familiar .NET pattern.
|
||||
|
||||
C) **Direct `HttpClient` injection** — inject `IHttpClientFactory` directly in `CmsInstanceService` and create a client per call. Simplest approach; no separate client abstraction.
|
||||
|
||||
D) Other
|
||||
|
||||
[Answer]: A
|
||||
|
||||
---
|
||||
|
||||
### Q2 — Two-Phase Availability Gate: Middleware Strategy
|
||||
|
||||
The slave must implement a two-phase gate: Master gate (outer) → Local gate (inner) (FR-MASTER-08).
|
||||
The existing `AvailabilityMiddleware` implements the local gate.
|
||||
|
||||
Which approach should be used to add the Master gate on the slave?
|
||||
|
||||
A) **New separate `MasterGateMiddleware`** — registered before the existing `AvailabilityMiddleware` in the pipeline. Clean separation; existing middleware is untouched; Master gate is skipped at registration if no Master URL is stored.
|
||||
|
||||
B) **Extend `AvailabilityMiddleware`** — add the Master gate logic at the top of the existing middleware class. Single file; simpler pipeline registration; slightly more coupling between Master and Availability module.
|
||||
|
||||
C) Other
|
||||
|
||||
[Answer]: B
|
||||
|
||||
---
|
||||
|
||||
### Q3 — Slave-Side Master Status Caching
|
||||
|
||||
The slave must cache the master-pulled availability status (FR-MASTER-06, FR-MASTER-07).
|
||||
The existing codebase uses a simple `static` field + timestamp in `PersistentAvailabilityService` for circuit breaker caching.
|
||||
|
||||
Which caching mechanism should be used for the master status cache on the slave?
|
||||
|
||||
A) **Static field with timestamp** (same pattern as existing circuit breaker) — a `static` field in `MasterAvailabilityService` holding the last known status and last-fetched timestamp. Zero dependencies; consistent with existing code style.
|
||||
|
||||
B) **`IMemoryCache`** — inject `IMemoryCache` and use a keyed cache entry with a sliding/absolute expiry. Standard .NET caching abstraction; easier to test via mock; slightly more infrastructure.
|
||||
|
||||
C) Other
|
||||
|
||||
[Answer]: A
|
||||
|
||||
---
|
||||
|
||||
### Q4 — `CmsInstanceService` Responsibilities
|
||||
|
||||
The master-side service needs to handle: CRUD on `CmsInstance`, status push to slave (HTTP), and auto-registration (HTTP). How should these responsibilities be organized?
|
||||
|
||||
A) **Single unified `CmsInstanceService`** — one service handles CRUD (EF Core), HTTP status push, and auto-registration. Simple; consistent with the existing single-service pattern (e.g. `PersistentAvailabilityService`).
|
||||
|
||||
B) **Split: `CmsInstanceRepository` + `CmsInstanceService`** — repository handles EF Core data access; service handles business orchestration (status push, registration). Cleaner separation; slightly more files.
|
||||
|
||||
C) **Split: `CmsInstanceService` (CRUD) + `SlaveStatusService` (HTTP calls)** — data + business logic in one service; all HTTP slave interactions in a dedicated service. Best for unit testing HTTP logic separately.
|
||||
|
||||
D) Other
|
||||
|
||||
[Answer]: B
|
||||
|
||||
---
|
||||
|
||||
### Q5 — Master-Side Controller Granularity
|
||||
|
||||
The Master module needs REST endpoints for: listing slaves, adding a slave, and setting slave status.
|
||||
|
||||
Which controller structure is preferred?
|
||||
|
||||
A) **Single `CmsInstanceController`** — all actions in one controller: `GET /api/cms-instances`, `POST /api/cms-instances`, `PUT /api/cms-instances/{id}/status`. Consistent with how `AvailabilityController` works.
|
||||
|
||||
B) **Two controllers** — `CmsInstanceController` for CRUD (`GET`, `POST`) and `CmsInstanceStatusController` for the `PUT /status` action. Clearer separation of read vs. write-with-side-effect.
|
||||
|
||||
C) Other
|
||||
|
||||
[Answer]: A
|
||||
|
||||
---
|
||||
|
||||
### Q6 — Slave-Side Internal Endpoint Placement
|
||||
|
||||
The slave needs an internal registration endpoint (`POST /api/internal/master/register`) (FR-MASTER-03).
|
||||
Where should this endpoint be defined?
|
||||
|
||||
A) **New `MasterRegistrationController`** in `SlpModularCms.Modules.Availability` — a dedicated controller for internal master endpoints. Clean; extensible if more internal endpoints are needed.
|
||||
|
||||
B) **Added to the existing `AvailabilityController`** — keeps all availability-related endpoints in one file. Simpler; no extra controller class.
|
||||
|
||||
C) Other
|
||||
|
||||
[Answer]: B
|
||||
|
||||
---
|
||||
|
||||
### Q7 — Frontend: CMS Page API Hooks Organization
|
||||
|
||||
The frontend `/cms` page needs TanStack Query hooks for: listing CMS instances, adding an instance, and updating status.
|
||||
|
||||
How should the API hooks be organized?
|
||||
|
||||
A) **Single `useCmsInstances` hook file** — one file exports all hooks: `useCmsInstances()`, `useAddCmsInstance()`, `useUpdateCmsInstanceStatus()`. Consistent and simple.
|
||||
|
||||
B) **Separate hook files per concern** — `useCmsInstances.ts`, `useAddCmsInstance.ts`, `useUpdateCmsInstanceStatus.ts`. More files, but each file is focused.
|
||||
|
||||
C) **Follow existing pattern** — check how existing hooks (e.g. availability hooks) are organized and mirror that pattern.
|
||||
|
||||
D) Other
|
||||
|
||||
[Answer]: B
|
||||
|
||||
---
|
||||
|
||||
## Execution Steps
|
||||
|
||||
After all questions above are answered, the following artifacts will be generated:
|
||||
|
||||
- [x] **Step 1** — Analyze all answers; flag any ambiguities for follow-up
|
||||
- [x] **Step 2** — Generate `components.md` with component definitions and responsibilities
|
||||
- [x] **Step 3** — Generate `component-methods.md` with method signatures and purpose
|
||||
- [x] **Step 4** — Generate `services.md` with service definitions and orchestration patterns
|
||||
- [x] **Step 5** — Generate `component-dependency.md` with dependency matrix and data flow diagrams
|
||||
- [x] **Step 6** — Generate `application-design.md` consolidating all design artifacts
|
||||
- [x] **Step 7** — Validate all content (Mermaid diagrams, no ASCII trees, color styles present)
|
||||
- [x] **Step 8** — Update `aidlc-state.md` to mark Application Design as In Progress → Complete
|
||||
- [x] **Step 9** — Present completion message for user approval
|
||||
|
||||
---
|
||||
|
||||
*Artifact path*: `aidlc-docs/features/master-cms-module/inception/plans/application-design-plan.md`
|
||||
@@ -0,0 +1,160 @@
|
||||
# Execution Plan — Master CMS Module
|
||||
|
||||
## Detailed Analysis Summary
|
||||
|
||||
### Transformation Scope
|
||||
- **Transformation Type**: Multi-component addition — new module + slave-side middleware extension + frontend page + documentation
|
||||
- **Primary Changes**: New `SlpModularCms.Modules.Master` project; extended `SlpModularCms.Modules.Availability`; updated `/cms` frontend page
|
||||
- **Related Components**: Core (new entity), Api shell (module registration), Availability module (middleware extension), Frontend (CMS page)
|
||||
|
||||
### Change Impact Assessment
|
||||
- **User-facing changes**: Yes — `/cms` page gets a full slave management UI; slave CMS users see a disable message on 503
|
||||
- **Structural changes**: Yes — new module project, per-module DbContext pattern introduced
|
||||
- **Data model changes**: Yes — new `CmsInstance` entity (master), new `MasterRegistration` entity (slave)
|
||||
- **API changes**: Yes — new Master module endpoints; new internal slave registration endpoint; extended 503 response body
|
||||
- **NFR impact**: Yes — API key security, availability caching strategy, background service, fail-open design
|
||||
|
||||
### Component Relationships
|
||||
|
||||
**Primary new component**: `SlpModularCms.Modules.Master`
|
||||
- Depends on: `SlpModularCms.Core` (shared DbContext base, IModule), `SlpModularCms.Api` (module registration)
|
||||
|
||||
**Modified component**: `SlpModularCms.Modules.Availability`
|
||||
- Extended with: master registration endpoint, two-phase availability check, `MasterAvailabilityService`, slave-side `MasterDbContext`
|
||||
- Depends on: `SlpModularCms.Core`
|
||||
|
||||
**Modified component**: `SlpModularCms.Frontend`
|
||||
- Extended with: CMS page slave management UI, new TanStack Query hooks, new API types
|
||||
|
||||
### Risk Assessment
|
||||
- **Risk Level**: Medium-High
|
||||
- **Rollback Complexity**: Moderate — new module can be unregistered from Api; slave-side changes are additive; frontend changes are isolated to one route
|
||||
- **Testing Complexity**: Complex — involves network calls between Master and Slave, background service timing, cache behavior, fallback logic
|
||||
|
||||
---
|
||||
|
||||
## Workflow Visualization
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Master CMS Module Request"])
|
||||
|
||||
subgraph INCEPTION["🔵 INCEPTION PHASE"]
|
||||
WD["Workspace Detection\nCOMPLETED"]
|
||||
RE["Reverse Engineering\nSKIPPED (artifacts exist)"]
|
||||
RA["Requirements Analysis\nCOMPLETED"]
|
||||
US["User Stories\nSKIPPED"]
|
||||
WP["Workflow Planning\nIN PROGRESS"]
|
||||
AD["Application Design\nEXECUTE"]
|
||||
UG["Units Generation\nEXECUTE"]
|
||||
end
|
||||
|
||||
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE — Per Unit"]
|
||||
FD["Functional Design\nEXECUTE"]
|
||||
NFRA["NFR Requirements\nEXECUTE"]
|
||||
NFRD["NFR Design\nEXECUTE"]
|
||||
ID["Infrastructure Design\nSKIPPED"]
|
||||
CG["Code Generation\nEXECUTE"]
|
||||
BT["Build and Test\nEXECUTE"]
|
||||
end
|
||||
|
||||
subgraph OPERATIONS["🟡 OPERATIONS PHASE"]
|
||||
OPS["Operations\nPLACEHOLDER"]
|
||||
end
|
||||
|
||||
Start --> WD --> RA --> WP --> AD --> UG
|
||||
UG --> FD --> NFRA --> NFRD --> CG
|
||||
ID -.->|skipped| CG
|
||||
CG -->|repeat per unit| FD
|
||||
CG --> BT --> OPS --> End(["Complete"])
|
||||
|
||||
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray:5 5,color:#000
|
||||
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray:5 5,color:#000
|
||||
style ID fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray:5 5,color:#000
|
||||
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray:5 5,color:#000
|
||||
style UG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray:5 5,color:#000
|
||||
style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray:5 5,color:#000
|
||||
style NFRA fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray:5 5,color:#000
|
||||
style NFRD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray:5 5,color:#000
|
||||
style OPS fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray:5 5,color:#000
|
||||
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000
|
||||
style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000
|
||||
style OPERATIONS fill:#FFF59D,stroke:#F57F17,stroke-width:3px,color:#000
|
||||
linkStyle default stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
Text alternative: Inception (WD→RA→WP→AD→UG completed/executing), Construction per-unit loop (FD→NFR Req→NFR Design→CodeGen, Infrastructure skipped), Build & Test, Operations placeholder.
|
||||
|
||||
---
|
||||
|
||||
## Phases to Execute
|
||||
|
||||
### 🔵 INCEPTION PHASE
|
||||
- [x] Workspace Detection — COMPLETED
|
||||
- [x] Reverse Engineering — SKIPPED (shared artifacts already exist in `aidlc-docs/_shared/`)
|
||||
- [x] Requirements Analysis — COMPLETED
|
||||
- [ ] User Stories — **SKIP**
|
||||
- *Rationale*: Feature is owner-operated and technical in nature. Requirements are clear and detailed. No multiple personas or acceptance criteria gaps.
|
||||
- [x] Workflow Planning — IN PROGRESS
|
||||
- [ ] Application Design — **EXECUTE**
|
||||
- *Rationale*: New module project, new services, new controller, background service, new frontend components — all need component definition and dependency mapping before code generation.
|
||||
- [ ] Units Generation — **EXECUTE**
|
||||
- *Rationale*: 4 distinct units spanning backend (master), backend (slave extension), frontend, and documentation. Sequencing and dependencies must be planned.
|
||||
|
||||
### 🟢 CONSTRUCTION PHASE (per unit)
|
||||
- [ ] Functional Design — **EXECUTE**
|
||||
- *Rationale*: Complex business logic per unit (registration handshake, two-phase middleware, background integrity check, cache + fallback)
|
||||
- [ ] NFR Requirements — **EXECUTE**
|
||||
- *Rationale*: New security concerns (API key handling), caching strategy, fail-open requirements, test coverage targets
|
||||
- [ ] NFR Design — **EXECUTE**
|
||||
- *Rationale*: Design patterns for background service, per-module DbContext, middleware extension, client-side caching
|
||||
- [ ] Infrastructure Design — **SKIP**
|
||||
- *Rationale*: No new cloud/infrastructure resources. Same deployment model (single .NET process + React SPA). Module registration is code-level, not infrastructure-level.
|
||||
- [ ] Code Generation — **EXECUTE** (always)
|
||||
- [ ] Build and Test — **EXECUTE** (always)
|
||||
|
||||
### 🟡 OPERATIONS PHASE
|
||||
- [ ] Operations — PLACEHOLDER
|
||||
|
||||
---
|
||||
|
||||
## Unit Decomposition (Proposed)
|
||||
|
||||
| # | Unit Name | Scope | Depends On |
|
||||
|---|-----------|-------|------------|
|
||||
| 1 | master-backend | New `SlpModularCms.Modules.Master` project: `CmsInstance` entity, `MasterDbContext`, migrations, `CmsInstanceService`, `MasterController`, `IntegrityCheckBackgroundService`, `MasterModule : IModule`, test project | Core |
|
||||
| 2 | slave-availability-extension | Extended `SlpModularCms.Modules.Availability`: `MasterRegistration` entity, slave `MasterDbContext`, migrations, `MasterAvailabilityService` (pull/cache/fallback), registration endpoint, two-phase `AvailabilityMiddleware` | Unit 1 (API contract) |
|
||||
| 3 | frontend-cms-page | `/cms` page: `CmsInstanceList`, `AddCmsInstanceDialog`, `SetStatusDialog`, new TanStack Query hooks, API types | Unit 1 (REST API) |
|
||||
| 4 | documentation | Update `README.md` (migrations section, module guide, prod env vars), replace `frontend/README.md` | Units 1–3 (documents final patterns) |
|
||||
|
||||
---
|
||||
|
||||
## Package Change Sequence
|
||||
|
||||
```
|
||||
SlpModularCms.Core ← no changes (CmsInstance owned by Modules.Master)
|
||||
↓
|
||||
SlpModularCms.Modules.Master [Unit 1] ← new project
|
||||
↓
|
||||
SlpModularCms.Modules.Availability [Unit 2] ← extended
|
||||
↓
|
||||
SlpModularCms.Api ← registers new Master module
|
||||
↓
|
||||
frontend/ [Unit 3] ← CMS page updated
|
||||
↓
|
||||
README.md / frontend/README.md [Unit 4] ← documentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
- **Primary Goal**: Owner on the Master CMS can register slave CMSes and toggle their availability; slaves enforce the master-controlled status with a two-phase check
|
||||
- **Key Deliverables**: `SlpModularCms.Modules.Master` project, extended Availability module, updated `/cms` frontend page, updated documentation
|
||||
- **Quality Gates**: ≥80% test coverage on new backend code; fail-open behavior verified; API key not exposed in list responses; two-phase middleware verified for all status combinations
|
||||
@@ -0,0 +1,12 @@
|
||||
# Language Preference
|
||||
|
||||
All documentation artifacts (requirements, designs, plans, code comments, etc.) will be written in **English** by default. Questions, prompts, and AI responses will be in your language.
|
||||
|
||||
Would you like to change this?
|
||||
|
||||
A) English for documentation, your language for conversation (default)
|
||||
B) English for everything (documentation and conversation)
|
||||
C) My language for everything (documentation and conversation)
|
||||
D) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A
|
||||
@@ -0,0 +1,80 @@
|
||||
# Unit of Work Plan — Master CMS Module
|
||||
|
||||
## Overview
|
||||
|
||||
The four units are pre-established from the execution plan and confirmed by the Application Design stage. This plan validates the decomposition and generates the formal unit artifacts.
|
||||
|
||||
**Pre-established units:**
|
||||
|
||||
| # | Unit | Scope | Depends On |
|
||||
|---|------|-------|------------|
|
||||
| 1 | `master-backend` | New `SlpModularCms.Modules.Master` project | Core |
|
||||
| 2 | `slave-availability-extension` | Extended `SlpModularCms.Modules.Availability` | Unit 1 (API contract + ISlaveApiClient) |
|
||||
| 3 | `frontend-cms-page` | `/cms` page in `frontend/` | Unit 1 (REST API endpoints) |
|
||||
| 4 | `documentation` | README updates | Units 1–3 (documents final patterns) |
|
||||
|
||||
---
|
||||
|
||||
## Decomposition Questions
|
||||
|
||||
Answer each question by filling in your choice after the `[Answer]:` tag.
|
||||
|
||||
---
|
||||
|
||||
### Q1 — Construction Cycle for Unit 4 (Documentation)
|
||||
|
||||
Unit 4 covers README.md updates — no new code, entities, or services. How should it be handled in the Construction phase?
|
||||
|
||||
A) **Full cycle** — run Functional Design, NFR Requirements, NFR Design, and Code Generation for Unit 4 as for the other units. Consistent process; documentation gets explicit design attention.
|
||||
|
||||
B) **Code Generation only** — skip Functional Design, NFR Requirements, and NFR Design for Unit 4; go straight to Code Generation (which in this case means drafting the README content). More efficient for a documentation-only unit.
|
||||
|
||||
C) Other
|
||||
|
||||
[Answer]: B
|
||||
|
||||
---
|
||||
|
||||
### Q2 — Test Project for Unit 1
|
||||
|
||||
Unit 1 adds `SlpModularCms.Modules.Master` — a new project. How should tests be organized?
|
||||
|
||||
A) **New `SlpModularCms.Modules.Master.Tests` project** — separate test project for the new module, parallel to the existing `SlpModularCms.Modules.Availability.Tests`. Clean isolation; follows existing pattern.
|
||||
|
||||
B) **Single shared test project** — add master module tests to an existing test project to avoid creating a new project.
|
||||
|
||||
C) Other
|
||||
|
||||
[Answer]: A
|
||||
|
||||
---
|
||||
|
||||
### Q3 — Test Project for Unit 2
|
||||
|
||||
Unit 2 extends `SlpModularCms.Modules.Availability`. How should new slave-side tests be organized?
|
||||
|
||||
A) **Extend existing `SlpModularCms.Modules.Availability.Tests`** — add new test files for `MasterAvailabilityService`, extended `AvailabilityMiddleware`, and `AvailabilityController` registration endpoint. Minimal new project overhead.
|
||||
|
||||
B) **New `SlpModularCms.Modules.Availability.Master.Tests`** — separate test project for the master-related slave-side extensions. Cleaner isolation for cross-unit changes.
|
||||
|
||||
C) Other
|
||||
|
||||
[Answer]: B
|
||||
|
||||
---
|
||||
|
||||
## 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 `unit-of-work.md` with unit definitions, responsibilities, and construction cycle per unit
|
||||
- [x] **Step 3** — Generate `unit-of-work-dependency.md` with dependency matrix and sequencing
|
||||
- [x] **Step 4** — Generate `unit-of-work-story-map.md` (requirement-to-unit mapping; no user stories in this feature)
|
||||
- [x] **Step 5** — Validate unit boundaries and completeness
|
||||
- [x] **Step 6** — Update `aidlc-state.md` to mark Units Generation as complete
|
||||
- [x] **Step 7** — Present completion message for user approval
|
||||
|
||||
---
|
||||
|
||||
*Artifact path*: `aidlc-docs/features/master-cms-module/inception/plans/unit-of-work-plan.md`
|
||||
Reference in New Issue
Block a user