3.9 KiB
3.9 KiB
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
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.