Start feature identity-email-notifications: requirements-vragen

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-08 17:08:04 +01:00
co-authored by Claude Sonnet 5.5
parent e9feb37961
commit 02827c590f
4 changed files with 248 additions and 0 deletions
+1
View File
@@ -12,3 +12,4 @@
| Feature | Andrea's site hosting (andreaslop-site-hosting) | 🟡 Operations (wacht op CI-proef en eerste test-deploy) | feature/andreaslop-site-hosting | Core (CmsHost, CSP, static content), Clients (new Api.AndreaSlopFotografie), Frontend (theme), CI/CD | 2026-11-06 |
| Bug | [cms-admin-nine-points](bugs/cms-admin-nine-points/bug-fix.md) | ✅ Complete (wacht op goedkeuring ASF test) | feature/andreaslop-site-hosting | Core (auth, invitations), Identity, Availability, Frontend | 2026-11-08 |
| Bug | [invitation-delete-and-lifetime](bugs/invitation-delete-and-lifetime/bug-fix.md) | ✅ Complete (wacht op goedkeuring ASF test) | feature/andreaslop-site-hosting | Core (invitations), Identity, Frontend | 2026-11-08 |
| Feature | Identity e-mail notifications (identity-email-notifications) | 🔵 Inception (wacht op antwoorden) | feature/identity-email-notifications | Core (IEmailSender), Identity, Frontend | 2026-11-08 |
@@ -0,0 +1,47 @@
# AI-DLC State Tracking
## Project Information
- **Feature Name**: E-mail notifications for identity (invitation, new activation link, password reset)
- **Feature Slug**: identity-email-notifications
- **Project Type**: Brownfield
- **Start Date**: 2026-11-08
- **Current Stage**: INCEPTION - Requirements Analysis (questions issued, waiting for Bryan's answers via session "CMS & API")
- **Branch**: feature/identity-email-notifications (branched from feature/andreaslop-site-hosting at e9feb37; own branch, not merged anywhere)
- **Request Type**: Feature (Bryan chose real e-mail over a workaround button; relayed by session "CMS & API")
## Workspace State
- **Existing Code**: Yes
- **Reverse Engineering Needed**: No - reuse aidlc-docs/_shared/reverse-engineering/
- **Workspace Root**: K:\Development\Projects\SlpModularCms
## Code Location Rules
- **Application Code**: Workspace root (NEVER in aidlc-docs/)
- **Feature Documentation**: aidlc-docs/features/identity-email-notifications/ only
## Language Configuration
- **Documentation Language**: English
- **Conversation Language**: User Language (Dutch)
- **Note**: Inherited from the other features in this workspace.
## External Requester (hand-off)
- **Session**: "CMS & API", relays Bryan's decisions. Questions for Bryan go through that session. No implementation before the answers are in.
- **Reference implementation (read-only)**: K:\Development\Projects\SimpleDeckApp (MailKit/MimeKit `SmtpEmailSender`, `IEmailSender.SendAsync(to, subject, htmlBody, ct)`, `EmailOptions` section "Email").
## Extension Configuration
| Extension | Enabled | Decided At |
|---|---|---|
| Security Baseline | Pending (question in questions file) | Requirements Analysis |
| Property-Based Testing | Pending (question in questions file) | Requirements Analysis |
## Operations Configuration
- **Include Operations Phase**: Undecided (question in questions file)
- **Decided At**: Pending - asked at Requirements Analysis
## Stage Progress
### INCEPTION
- [x] Workspace Detection - Complete
- [ ] Requirements Analysis - questions issued
- [ ] User Stories
- [ ] Workflow Planning
- [ ] Application Design
- [ ] Units Generation
@@ -0,0 +1,35 @@
# Audit Log - identity-email-notifications
## Workspace Detection
**Timestamp**: 2026-11-08T16:15:00Z
**User Input**: "(Relayed by session 'CMS & API', Bryan's decisions in his own chat) Knop/mail: Bryan kiest ECHTE E-MAIL. Dat is een aparte feature (niet in deze branch bouwen). Start die als nieuwe AIDLC-feature (bv. 'identity-email-notifications') in een eigen branch/worktree vanaf de huidige branch na de deploy van punt 1. Begin met requirements-analyse; zet vragen aan Bryan aan mij door (ik stel ze in zijn chat): provider/SMTP-keuze (eigen SMTP via hostingpartner vs transactionele dienst), afzenderadres/domein + SPF/DKIM/DMARC, welke mails (uitnodiging, nieuwe activatiecode, wachtwoord-reset?), per-site configuratie van afzendernaam/logo, secrets-beheer op de Pi, rate limiting, sjabloon NL, fallback als mail faalt (kopieerbare link blijft bestaan), testen zonder echte verzending (fake sender). Geen implementatie voor die vragen beantwoord zijn."
**AI Response**: "Classified as Feature (new capability). Created branch feature/identity-email-notifications from e9feb37 after the ASF test deploy of run 615, created the feature directory, reused the shared reverse-engineering artifacts, wrote requirement-verification-questions.md (17 questions). Findings used: no mail code or config anywhere in this repo."
**Context**: Workspace Detection, Feature lane, brownfield, no RE rerun. Request relayed by a peer session; approvals must come from Bryan.
---
## Requirements Analysis - reference implementation read
**Timestamp**: 2026-11-08T16:20:00Z
**User Input**: "(Relayed by 'CMS & API') Aanvulling voor de e-mailfeature: SimpleDeckApp (K:\Development\Projects\SimpleDeckApp, alleen lezen) heeft al mail. Kijk daar eerst naar en volg het patroon tenzij je een goede reden hebt ... Zoek ook uit welke SMTP-server/provider productie daar gebruikt en of afzenderdomein + SPF/DKIM daar al ingericht zijn ... Eventueel een gedeelde Core-abstractie (IEmailSender in Core) i.p.v. kopieer."
**AI Response**: "Read SimpleDeckApp read-only: SmtpEmailSender (MailKit/MimeKit, StartTls when EnableSsl, auth only when Username set), EmailOptions (section Email: FromAddress, FromName, Smtp{Host,Port=587,EnableSsl,Username,Password}), committed appsettings sender no-reply@slpsoftware.nl / name 'Decks', secrets via Email__Smtp__* env vars, local catcher on localhost:25. The production SMTP host/provider and the SPF/DKIM state are NOT in that repo (config lives outside it); asked as Questions 1 to 3."
**Context**: Requirements Analysis, inputs for the question file.
---
## Requirements Analysis - questions issued
**Timestamp**: 2026-11-08T16:25:00Z
**AI Response**: "Question file inception/requirements/requirement-verification-questions.md (17 questions incl. both extension opt-ins and the Operations question) forwarded to Bryan through session 'CMS & API'. Waiting for answers; no implementation."
**Context**: Requirements Analysis gate: await answers.
---
@@ -0,0 +1,165 @@
# Requirements Clarification Questions - identity-email-notifications
Context: the CMS has no mail at all today. Invitations work through a link that an administrator copies and passes on. Bryan chose real e-mail. SimpleDeckApp already sends mail (MailKit, `IEmailSender`, options section `Email`, sender `no-reply@slpsoftware.nl`); the plan is to follow that pattern, preferably as a shared abstraction in Core. Nothing is built until these are answered. Answers are relayed by session "CMS & API".
## Question 1: SMTP server / provider
Which mail server should the CMS send through (test and, later, production)?
- A) The same SMTP server SimpleDeckApp uses in production (reuse host, account type and domain pattern)
- B) The SMTP server of the hosting partner (own account/mailbox)
- C) A transactional mail service (for example Brevo, Mailgun, Postmark, Amazon SES) with its own account
- D) Own mail server on the Pi (Postfix and similar)
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 2: Sender address and domain
From which address should the mails come?
- A) One shared sender for all sites (for example no-reply@slpsoftware.nl), per-site name only in the display name
- B) A sender per site on that site's own domain (for example no-reply@andreaslop.nl for Andrea's site)
- C) A shared address for the test environment and a per-site address for production
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 3: Sender authentication (SPF / DKIM / DMARC)
Is the chosen sender domain already set up so that mail is not marked as spam?
- A) Yes, SPF, DKIM and DMARC are already set up for the sender domain (reuse the SimpleDeckApp setup)
- B) Not sure; please check (read-only) what is published and report
- C) No; it still has to be set up before production (test may go out without it)
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 4: Which mails
Which mails should the CMS send in the first version? (Select the lowest letter that covers what you want; each option includes the previous ones.)
- A) Only the invitation mail (link to complete the account), plus a "new invitation link" mail when an administrator regenerates one
- B) A, plus password reset ("forgot password") with a mail link
- C) B, plus a notification when the account is deactivated or the role changes
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 5: Per-site mail content
How much should the mail look like each site?
- A) Per site: sender name and mail text in Dutch, plain and without a logo
- B) Per site: sender name, Dutch text, and the site's logo and brand colour in a shared template
- C) Fully custom template per site (separate HTML per site)
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 6: Languages
In which language(s) should the mails be written?
- A) Dutch only (the admin of these sites is Dutch)
- B) Dutch and English, following the recipient's or the site's default language
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 7: When sending fails
What should happen when the mail cannot be sent (server down, wrong credentials)?
- A) The invitation is still created and the administrator sees a clear message plus the copyable link (the current link stays available as fallback)
- B) The invitation is not created and the administrator sees an error
- C) The mail is retried in the background a few times; the administrator sees the status ("sent", "failed") and the copyable link
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 8: Where the mail is sent from (sending model)
How should the sending be done technically?
- A) Directly during the request (simple; the request waits for the mail server)
- B) In the background (queue in the database or in memory), the request returns immediately
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 9: Secrets on the host
How do the SMTP credentials get onto the Pi?
- A) As environment variables in the host's `shared/env` (mode 600), same as other secrets (Email__Smtp__Username, Email__Smtp__Password)
- B) Via another secrets mechanism (please describe)
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 10: Abuse and cost protection
How should the CMS prevent being used to spam or run up costs?
- A) A rate limit per administrator and per recipient address (for example a few mails per address per hour) plus the existing login rate limits
- B) Only the existing role checks (only Owner/Administrator can trigger mails), no extra limit
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 11: Link in the mail
The link in the mail points to the admin on the site's own address. Where does the CMS get that address from?
- A) A configured setting per site (for example `App:PublicBaseUrl`), validated at start-up
- B) From the incoming request (Host header, behind the proxy)
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 12: Shared code
How should the mail code be shared between SlpModularCms and SimpleDeckApp?
- A) A new `IEmailSender` in SlpModularCms.Core, following the SimpleDeckApp pattern (same interface and options names); no code shared across the two repos
- B) A small shared NuGet package used by both repos
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 13: Testing without real sending
How do we test?
- A) A fake sender in unit and integration tests (always), plus a local catcher (smtp4dev/Papercut) for manual runs; one manual test mail to a real address on the test host before approval
- B) Fake sender only, no real test mail
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 14: Scope across sites
For which sites should this be switched on?
- A) All sites on the shared code, switched on per site by configuration (no mail configured = the current copy-link flow keeps working unchanged)
- B) First only ASF test; SlpSoftware later
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 15: Security Extensions
Should security extension rules be enforced for this feature?
- A) Yes - enforce all SECURITY rules as blocking constraints (recommended; this feature handles credentials, links that grant account access, and personal data)
- B) No - skip all SECURITY rules
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 16: Property-Based Testing Extension
Should property-based testing (PBT) rules be enforced for this feature?
- A) Yes - enforce all PBT rules as blocking constraints
- B) Partial - only for pure functions and serialization round-trips (for example building links and templates)
- C) No - skip all PBT rules
- X) Other (please describe after [Answer]: tag below)
[Answer]:
## Question 17: Operations Phase
Should this feature go through the Operations phase after Construction (setting up deployment and monitoring)?
- A) Yes - run the Operations phase after Construction (deployment + monitoring setup)
- B) No - stop after Build and Test (deployment/monitoring are out of scope for this feature)
- C) Not sure yet - ask me again after the Construction phase
- X) Other (please describe after [Answer]: tag below)
[Answer]: