168 lines
10 KiB
Markdown
168 lines
10 KiB
Markdown
# Task P.7.2 Implementation Report
|
|
|
|
## Scope
|
|
|
|
This round implements the first working slice of the SMTP / Email Configuration Platform for ALLA OS.
|
|
|
|
Delivered scope:
|
|
|
|
- organization-scoped email configuration persistence
|
|
- encrypted SMTP password storage
|
|
- CRUD APIs for email configurations
|
|
- SMTP connection test
|
|
- send test email action
|
|
- setup readiness / verification integration
|
|
- setup wizard optional email status card
|
|
- dashboard-native email administration page
|
|
- notification runtime integration so email sending uses the stored organization configuration
|
|
|
|
## Review Summary
|
|
|
|
Reviewed before implementation:
|
|
|
|
- [AGENTS.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/AGENTS.md)
|
|
- [docs/standards/project-foundations.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/project-foundations.md)
|
|
- [docs/standards/architecture-rules.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/architecture-rules.md)
|
|
- [docs/standards/ui-ux-rules.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/ui-ux-rules.md)
|
|
- [docs/standards/task-review-checklist.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/task-review-checklist.md)
|
|
- [docs/setup/verification-matrix.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/setup/verification-matrix.md)
|
|
- [docs/setup/setup-wizard-blueprint.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/setup/setup-wizard-blueprint.md)
|
|
- [docs/setup/installation-profiles.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/setup/installation-profiles.md)
|
|
- [docs/implementation/task-d72-setup-readiness-verification-apis.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-d72-setup-readiness-verification-apis.md)
|
|
- [docs/implementation/task-d76-dashboard-setup-wizard-ui.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-d76-dashboard-setup-wizard-ui.md)
|
|
- [docs/implementation/task-f4-notification-framework-foundation.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-f4-notification-framework-foundation.md)
|
|
- [docs/implementation/task-p.7.1-implementation.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-p.7.1-implementation.md)
|
|
|
|
## Architecture Notes
|
|
|
|
The implementation intentionally extends the existing notification foundation instead of creating a second outbound-email stack.
|
|
|
|
Key decisions:
|
|
|
|
- persisted email configuration is organization-scoped in a new `email_configurations` table
|
|
- secret encryption is isolated in a reusable helper at [src/features/foundation/secrets/server/crypto.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/secrets/server/crypto.ts)
|
|
- the notification runtime keeps using the existing provider factory, but the email provider now resolves organization SMTP config from the new foundation
|
|
- setup readiness and setup verification both read from the same persisted source of truth instead of environment-only `SMTP_*` variables
|
|
- the setup wizard keeps email as an optional operator step, matching the task requirement that email must not block first-run setup by default
|
|
|
|
## Main Changes
|
|
|
|
### 1. Data Model And Secret Handling
|
|
|
|
Added:
|
|
|
|
- [src/db/schema.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/schema.ts)
|
|
- [drizzle/0001_yellow_wasp.sql](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/drizzle/0001_yellow_wasp.sql)
|
|
- [src/features/foundation/secrets/server/crypto.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/secrets/server/crypto.ts)
|
|
|
|
Behavior:
|
|
|
|
- SMTP passwords are stored only as encrypted ciphertext
|
|
- API responses never return decrypted or raw password values
|
|
- UI only receives `hasPassword`
|
|
- missing or weak `EMAIL_CONFIG_ENCRYPTION_KEY` blocks encryption-dependent save paths
|
|
|
|
### 2. Email Foundation Services
|
|
|
|
Added:
|
|
|
|
- [src/features/foundation/email/server/email-provider.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/email/server/email-provider.ts)
|
|
- [src/features/foundation/email/server/smtp-provider.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/email/server/smtp-provider.ts)
|
|
- [src/features/foundation/email/server/email-config.service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/email/server/email-config.service.ts)
|
|
- [src/features/foundation/email/server/email-test.service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/email/server/email-test.service.ts)
|
|
|
|
Behavior:
|
|
|
|
- create, update, list, fetch, and delete email configs
|
|
- track default / active config
|
|
- test connection and test send update `last_test_status`, `last_tested_at`, and safe `last_test_error`
|
|
- audit events are written for create, update, delete, and test outcomes
|
|
|
|
### 3. Notification Runtime Integration
|
|
|
|
Updated:
|
|
|
|
- [src/features/foundation/notifications/server/email-provider.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/notifications/server/email-provider.ts)
|
|
- [src/features/foundation/notifications/server/provider-factory.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/notifications/server/provider-factory.ts)
|
|
- [src/features/foundation/notifications/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/notifications/server/service.ts)
|
|
|
|
Behavior:
|
|
|
|
- email dispatches now resolve SMTP settings from the active organization configuration
|
|
- the provider factory now receives `organizationId`
|
|
- existing notification send / resend flows continue using the established foundation contract
|
|
|
|
### 4. Setup Integration
|
|
|
|
Updated:
|
|
|
|
- [src/features/setup/server/readiness.service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/setup/server/readiness.service.ts)
|
|
- [src/features/setup/server/verification.service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/setup/server/verification.service.ts)
|
|
- [src/features/setup/components/setup-wizard.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/setup/components/setup-wizard.tsx)
|
|
- [src/features/foundation/email/components/setup-email-card.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/email/components/setup-email-card.tsx)
|
|
|
|
Behavior:
|
|
|
|
- readiness and verification now check persisted organization email config
|
|
- no configuration returns `WARNING`, not `FAIL`, so setup remains non-blocking by default
|
|
- a lightweight email status card is shown inside the setup wizard and links to the email admin page
|
|
|
|
### 5. Admin APIs And UI
|
|
|
|
Added APIs:
|
|
|
|
- [src/app/api/notifications/email-configurations/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/notifications/email-configurations/route.ts)
|
|
- [src/app/api/notifications/email-configurations/[id]/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/notifications/email-configurations/[id]/route.ts)
|
|
- [src/app/api/notifications/email-configurations/[id]/test/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/notifications/email-configurations/[id]/test/route.ts)
|
|
- [src/app/api/notifications/email-configurations/[id]/send-test/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/notifications/email-configurations/[id]/send-test/route.ts)
|
|
|
|
Added client layer:
|
|
|
|
- [src/features/foundation/email/api/types.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/email/api/types.ts)
|
|
- [src/features/foundation/email/api/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/email/api/service.ts)
|
|
- [src/features/foundation/email/api/queries.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/email/api/queries.ts)
|
|
- [src/features/foundation/email/api/mutations.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/email/api/mutations.ts)
|
|
|
|
Added page:
|
|
|
|
- [src/app/dashboard/administration/email/page.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/dashboard/administration/email/page.tsx)
|
|
- [src/features/foundation/email/components/email-configuration-page.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/email/components/email-configuration-page.tsx)
|
|
- [src/config/nav-config.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/config/nav-config.ts)
|
|
|
|
UI notes:
|
|
|
|
- layout follows dashboard-native card rhythm rather than a separate visual system
|
|
- top summary area keeps status scannable
|
|
- quick verification panel gives one stable place for test-recipient entry
|
|
- config cards separate transport, sender identity, secret state, and test state clearly
|
|
- operator notes are intentionally calm and low-noise per task request
|
|
|
|
## Validation
|
|
|
|
Executed:
|
|
|
|
- `npm run typecheck -- --pretty false`
|
|
- `npm run db:generate`
|
|
- `npm run test:setup`
|
|
- `npx oxlint src/features/foundation/email src/features/foundation/secrets src/features/foundation/notifications/server/email-provider.ts src/features/foundation/notifications/server/provider-factory.ts src/features/setup/server/readiness.service.ts src/features/setup/server/verification.service.ts src/features/setup/components/setup-wizard.tsx src/app/api/notifications/email-configurations src/app/dashboard/administration/email/page.tsx src/config/nav-config.ts`
|
|
|
|
Results:
|
|
|
|
- TypeScript passed
|
|
- Drizzle migration generated successfully
|
|
- setup test suite passed
|
|
- targeted lint passed
|
|
|
|
## Known Gaps After This Round
|
|
|
|
- no dedicated profile-level rule yet to force email as a blocking setup requirement for selected installation profiles
|
|
- no password reset or invitation flow integration yet; this round only builds the platform and runtime foundation
|
|
- no seeded email templates or notification-template management UI specific to outbound email yet
|
|
- no per-configuration preview panel for rendered notification payloads yet
|
|
- no explicit soft-delete or archived state; delete currently removes the configuration row
|
|
|
|
## Notes
|
|
|
|
- This implementation assumes `EMAIL_CONFIG_ENCRYPTION_KEY` will be added to runtime environments before operators save SMTP passwords.
|
|
- Existing unrelated dirty files in the worktree were left untouched.
|