Files

52 lines
3.9 KiB
Markdown

# Execution Plan - identity-email-notifications
## Detailed analysis
- **Request type**: New feature across shared Core, Identity and the admin frontend.
- **Risk**: Medium-high. It handles SMTP credentials, links that grant account access, an anonymous endpoint, and three additive database changes that run on every host (SlpSoftware included).
- **Depth**: Comprehensive. **Extensions**: Security Baseline (enforced), PBT partial (PBT-02, 03, 07, 08, 09). **Operations**: yes.
- **Lane**: Feature.
## Stages
| Stage | Run? | Reason |
|---|---|---|
| Workspace Detection | done | |
| Reverse Engineering | skip | shared artifacts reused |
| Requirements Analysis | done (approval pending) | |
| User Stories | skip | one user type (administrators, plus the person who resets a password); acceptance criteria are in requirements.md |
| Workflow Planning | this document | |
| Application Design | run | new components (sender, templates, settings store, reset flow) |
| Units Generation | run | three units with clear dependencies |
| Functional Design | per unit, where noted below | mail rules, reset rules, language fallback |
| NFR Requirements / NFR Design | per unit, light | security-driven (tokens, anonymity, timeouts) |
| Infrastructure Design | U1 only | config keys, env secrets on the Pi, smtp4dev, SPF/DKIM alignment |
| Code Generation | each unit | per-unit build and test |
| Build and Test | once at the end | |
| Operations | yes | deployment config, monitoring, production-readiness incl. SPF alignment |
## Units and order
```mermaid
flowchart LR
U1["U1 mail-foundation<br/>sender, options, templates,<br/>SiteSettings + Mail card"] --> U2["U2 identity-mail-flows<br/>language per user, invitation,<br/>new link, resend, notices"]
U2 --> U3["U3 password-reset<br/>forgot/reset, cooldown,<br/>session revocation on completion"]
classDef u fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
class U1,U2,U3 u;
```
Text alternative: U1 (foundation) is built first, then U2 (flows that use it and the language column), then U3 (password reset, which needs both).
| Unit | Scope | Migration |
|---|---|---|
| U1 mail-foundation | `IEmailSender` + `SmtpEmailSender`, `EmailOptions` + start-up validation, template renderer + resources (nl, en), `SiteSettings` store + service + API + Mail card, `emailEnabled` and `defaultLanguage` in system capabilities, fake sender, smtp4dev docs | new table `SiteSettings` |
| U2 identity-mail-flows | `PreferredLanguage` on users, `Language` on invitations, profile language select, invite dialog language and mail result, invitation / new-link / resend mails, deactivation, reactivation and role-change notices, resend action in the users list | columns `Users.PreferredLanguage`, `Invitations.Language` (nullable) |
| U3 password-reset | `forgot-password` / `reset-password`, Identity token provider, cooldown, revocation of refresh tokens on completion only, access-token stamp check (decision D2), login link and two pages | none (token provider is stateless) |
All three migrations are additive, nullable (or new tables), with a working `Down`, and safe to run on SlpSoftware's database.
## Approval and delivery gates
- Requirements and this design go to Bryan through "CMS & API" before any code (his rule for this feature).
- Each unit is built and tested (per-unit build and test), hand-back after each unit.
- Branch `feature/identity-email-notifications`; push and deploy to ASF test only with the relayed permission pattern used so far (branch push, `deploy_asf_test`; no merge, no SLP Software, no production).
- A real test mail to an address of Bryan from the test host is part of acceptance (Operations).
## Success criteria
Mail disabled = behaviour unchanged (all existing tests green). Mail enabled = every mail kind sent correctly with a fake sender; failures never fail an action; reset request never touches password or sessions; completed reset revokes them; sender address only from the allowlist; no secrets in logs or messages.