123 lines
5.2 KiB
Markdown
123 lines
5.2 KiB
Markdown
# Functional Design Plan — Unit 1: master-backend
|
|
|
|
## Unit Context
|
|
|
|
**Unit**: `master-backend`
|
|
**Project**: `SlpModularCms.Modules.Master` (new)
|
|
**Test Project**: `SlpModularCms.Modules.Master.Tests` (new)
|
|
**Requirements**: FR-MASTER-01 t/m FR-MASTER-05, FR-MASTER-10, FR-MASTER-12/13/14; NFR-MASTER-03/04/05/06
|
|
|
|
---
|
|
|
|
## Functional Design Questions
|
|
|
|
Answer each question by filling in your choice after the `[Answer]:` tag.
|
|
|
|
---
|
|
|
|
### Q1 — Auto-Registration Failure Behavior
|
|
|
|
When the Master calls `RegisterMasterAsync` on a new slave during `AddAsync`, and the slave is unreachable or returns an error, what should happen?
|
|
|
|
A) **Persist anyway, LastContactedAt = null** — save the `CmsInstance` record regardless; `LastContactedAt` stays null to signal no successful contact; the owner can see the slave is uncontacted and resolve manually.
|
|
|
|
B) **Rollback — do not persist** — if registration fails, the entire `AddAsync` operation fails; return an error to the owner; no partial record is created.
|
|
|
|
C) **Persist with Status = Inactive** — save the record but set status to `Inactive` automatically; the owner must manually reactivate once the slave is reachable.
|
|
|
|
D) Other
|
|
|
|
[Answer]: A
|
|
|
|
---
|
|
|
|
### Q2 — Status Push When Setting to Inactive
|
|
|
|
When the owner sets a slave's status to `Inactive`, should the Master attempt to push this status change to the slave via HTTP?
|
|
|
|
A) **No push for Inactive** — `Inactive` means the Master stops contacting the slave entirely; no status push is sent; the slave keeps its last received state until the owner reactivates it.
|
|
|
|
B) **Push Inactive status** — send a final status update to the slave before going silent, so the slave is aware it has been deactivated.
|
|
|
|
C) Other
|
|
|
|
[Answer]: A
|
|
|
|
---
|
|
|
|
### Q3 — Integrity Check: Unreachable Slave
|
|
|
|
During `VerifyIntegrityAsync`, if a slave is unreachable (HTTP timeout or error), what should happen?
|
|
|
|
A) **Log and skip** — log the failure at Warning level, skip this slave, continue with the remaining slaves in the batch; retry on the next scheduled cycle.
|
|
|
|
B) **Mark as needs-check** — update a `LastIntegrityCheckFailedAt` timestamp on the entity; retry more aggressively on next cycle for flagged slaves.
|
|
|
|
C) Other
|
|
|
|
[Answer]: B
|
|
|
|
---
|
|
|
|
### Q4 — Master URL Discovery
|
|
|
|
When the Master calls `RegisterMasterAsync`, it needs to send its own public base URL to the slave. How should the Master know its own URL?
|
|
|
|
A) **Configured in `appsettings.json`** — owner sets `MasterModule:MasterUrl` (e.g., `https://master.myapp.com`). Explicit, reliable in all environments; simple to implement; follows existing `appsettings` pattern.
|
|
|
|
B) **Derived from `HttpContext`** — inject `IHttpContextAccessor` and derive the base URL from the current request in the controller; pass it down to the service. No config needed; but only works when called from an HTTP request (not from background service integrity checks).
|
|
|
|
C) **Two-value approach** — use `IHttpContextAccessor` when available (in controller context), fall back to `MasterModule:MasterUrl` config (for background service context).
|
|
|
|
D) Other
|
|
|
|
[Answer]: C
|
|
|
|
---
|
|
|
|
### Q5 — ApiKey Storage
|
|
|
|
The `ApiKey` in `CmsInstance` is the secret the Master sends to the slave in `X-Master-Api-Key`. How should it be stored in the `MasterDbContext`?
|
|
|
|
A) **Plaintext** — stored as-is in the database. The master must read the actual value to send in HTTP calls, so it must be stored in recoverable form. Access to the database is already protected by the deployment environment.
|
|
|
|
B) **Encrypted via ASP.NET Core Data Protection** — encrypt at write, decrypt at read using `IDataProtector`. More secure at rest; adds complexity; requires Data Protection key management.
|
|
|
|
C) Other
|
|
|
|
[Answer]: B
|
|
|
|
---
|
|
|
|
### Q6 — CmsInstanceController: Return 503 or 200 on Failed Slave Push
|
|
|
|
When `UpdateStatusAsync` successfully persists the new status but the subsequent HTTP push to the slave fails, what should the controller return to the frontend?
|
|
|
|
A) **200 OK with a warning field** — the status change is persisted (source of truth is the master DB); return 200 with an additional `slaveContactSuccess: false` field so the UI can display a warning.
|
|
|
|
B) **200 OK, no warning** — the master DB is the authority; whether the slave received the push is an implementation detail; the background integrity check ensures eventual consistency.
|
|
|
|
C) **207 Multi-Status** — partial success response indicating the DB write succeeded but the slave push failed.
|
|
|
|
D) Other
|
|
|
|
[Answer]: A
|
|
|
|
---
|
|
|
|
## 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 `domain-entities.md` — `CmsInstance` entity, `MasterModuleOptions`, enums, DTO shapes
|
|
- [x] **Step 3** — Generate `business-logic-model.md` — process flows: AddAsync, UpdateStatusAsync, VerifyIntegrityAsync
|
|
- [x] **Step 4** — Generate `business-rules.md` — validation rules, constraints, decision logic
|
|
- [x] **Step 5** — Validate all Mermaid diagrams (no hyphens in IDs, classDef colors, text alternatives)
|
|
- [x] **Step 6** — Update `aidlc-state.md`
|
|
- [x] **Step 7** — Present completion message for user approval
|
|
|
|
---
|
|
|
|
*Artifact path*: `aidlc-docs/features/master-cms-module/construction/plans/master-backend-functional-design-plan.md`
|