From 399ba5fb60c907dd0e3f48a111145ac698385d92 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 13:05:25 +0100 Subject: [PATCH] docs(35-02): complete mail screens server plan Co-authored-by: Cursor --- .../35-02-SUMMARY.md | 244 ++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100644 .planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md new file mode 100644 index 00000000..cfd0f0a8 --- /dev/null +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md @@ -0,0 +1,244 @@ +--- +phase: 35-mail-templates-and-layouts-editor +plan: 02 +subsystem: mail +tags: [cabana, postcard, mail, admin-api, codeeditor, colorpicker, mailimage, mailpreview, cooler, openapi] + +# Dependency graph +requires: + - phase: 35-mail-templates-and-layouts-editor + provides: postcard.Editor Validate/Preview/SendDraft, SyncIndex, ResetOverride, Brand, AbsolutePublicURL, RowStateCustomized/Outdated +provides: + - "Settings → Mail screens (templates, layouts, partials, branding, images) via cabana pseudo-plugin when postcard.EditorFrom succeeds" + - "system.manage_mail_templates and system.manage_mail_layouts with no default role grants" + - "override save/reset, custom layouts with in-use delete refusal, drift row states and File version LCS diff" + - "built-in field types codeeditor, colorpicker, mailimage, mailpreview on the server" + - "GET/POST /mail/images and GET /mail/images/{id} with absolute public URLs" + - "POST /mail/preview and POST /mail/test-send (own-address, interactive-only, 5/10min via cooler.Attempter)" + - "admin OpenAPI + schema.d.ts for the new routes; en/pl mail copy" +affects: [35-03, 35-04, admin-spa, boardwalk] + +# Actuals (#2632) +actuals: + tokens: 67849 + tasks: 4 + commits: 5 +plan_head_before: 7efb9ed7ad36478bd9d810f13895893dd9d50020 +plan_head_after: 0c73c8d4f13395e6d96721df98d8b8422a547ba3 + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Mail screens register only when postcard.EditorFrom succeeds; tests without a Mailer see no mail controllers" + - "Draft preview/test-send map form values to postcard.Draft; DraftError → 422 details field/rule/message" + - "Test-send limit key mail_test: via cooler.Attempter (surf publishes Redis store) with in-process fixed-window fallback" + +key-files: + created: + - modules/cabana/mail_admin.go + - modules/cabana/mail_diff.go + - modules/cabana/mail_routes.go + - modules/cabana/field_mail.go + - modules/cabana/mail_screens_smoke_test.go + - modules/cabana/backendscreens/controllers/mailtemplates/ + - modules/cabana/backendscreens/controllers/maillayouts/ + - modules/cabana/backendscreens/controllers/mailpartials/ + - modules/cabana/backendscreens/controllers/mailimages/ + - modules/cabana/backendscreens/models/mailtemplate/ + - modules/cabana/backendscreens/models/maillayout/ + - modules/cabana/backendscreens/models/mailpartial/ + - modules/cabana/backendscreens/models/mailbrandsetting/ + - modules/cabana/backendscreens/models/mailimagelibrary/ + modified: + - modules/cabana/backend_screens.go + - modules/cabana/http.go + - modules/cabana/form_schema.go + - modules/cabana/crud.go + - modules/cabana/settings.go + - modules/cabana/query.go + - modules/cabana/messages.go + - modules/cabana/relation_field.go + - modules/cabana/admin_openapi.go + - modules/cabana/README.md + - modules/surf/serve.go + - modules/surf/README.md + - modules/phrasebook/backend/lang/en/lang.yaml + - modules/phrasebook/backend/lang/pl/lang.yaml + - admin/openapi/admin.json + - admin/src/api/schema.d.ts + - docs/backend/forms.md + - docs/backend/settings.md + - docs/backend/users-and-permissions.md + - docs/backend/lists-and-filters.md + - docs/services/mail.md + - docs/services/rate-limiting.md + +key-decisions: + - "35-02: image list/pick allows either mail permission; upload and Mail images singleton need system.manage_mail_layouts" + - "35-02: test-send is interactive-only, recipient always the BackendUser email of principal.ID, unknown body keys refused by decodeStrictBody" + - "35-02: test-send limit 5 per 10 minutes keyed mail_test:; surf publishes cooler.Attempter next to Store when Redis rate-limit is on" + - "35-02: layout create form defaults injected from postcard default layout at Activate (YAML carries no copy)" + - "35-02: GET /mail/images answers AdminMailImagesResponse (custom meta canUpload/total/page/perPage), not Envelope with SuccessMeta" + +patterns-established: + - "cabana mail routes gate with Allows + tokenRouteGate; test-send adds interactiveOnly" + - "New mail field types register in formFieldTypes/formFieldKeys; mailpreview is valueless and skipped from Writable" + - "Route inventories (phase10 coverage, OpenAPI conformance, security, token classes) updated in the same commit as new admin routes" + +requirements-completed: [D-01, D-02, D-03, D-04, D-05, D-06, D-07, D-08, D-09, D-10, D-13, D-16, D-17, D-18, D-19, D-23, D-25] + +coverage: + - id: D1 + description: "Mail templates screen lists catalog templates, saves overrides used by real sends, refuses unsafe body and wrong permission" + requirement: "D-04" + verification: + - kind: integration + ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/templates" + status: pass + human_judgment: false + - id: D2 + description: "Layouts/partials reset, custom-layout create/delete-in-use, drift states and File version diff" + requirement: "D-07" + verification: + - kind: integration + ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/layouts|reset|delete|drift|diff" + status: pass + human_judgment: false + - id: D3 + description: "codeeditor/colorpicker/mailimage fields, Branding settings, image library absolute URLs and permission split" + requirement: "D-09" + verification: + - kind: integration + ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/fields|branding|images|images_permissions" + status: pass + human_judgment: false + - id: D4 + description: "Preview and test-send through postcard.Editor; own-address only; per-admin rate limit; interactive-only" + requirement: "D-16" + verification: + - kind: integration + ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/preview|preview_permissions|test_send|test_send_recipient|test_send_limit" + status: pass + human_judgment: false + +duration: 77min +completed: 2026-11-13 +status: complete +--- + +# Phase 35 Plan 02: Mail screens server Summary + +**Cabana Settings → Mail screens over postcard: templates/layouts/partials with reset and drift, Branding and image library, codeeditor/colorpicker/mailimage/mailpreview, plus preview and own-address test-send with a per-admin limit** + +## Performance + +- **Duration:** 77 min +- **Started:** 2026-11-13T11:45:13+01:00 +- **Completed:** 2026-11-13T13:02:49+01:00 +- **Tasks:** 4 +- **Files modified:** 66 (modules/, docs/, admin/) + +## Accomplishments + +- Five Settings → Mail entries behind `system.manage_mail_templates` / `system.manage_mail_layouts` (no default grants), registered only when `postcard.EditorFrom` succeeds. +- Templates, layouts and partials: catalog-scoped lists, override save with Editor.Validate, reset record action, custom layouts with in-use delete refusal, customized/outdated row states and File version LCS diff. +- Server field types `codeeditor`, `colorpicker`, `mailimage`, `mailpreview`; Branding settings form; image library routes with absolute URLs. +- `POST /mail/preview` and interactive-only `POST /mail/test-send` (own email, 5/10 min via `cooler.Attempter` or in-process fallback); OpenAPI regenerated. + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Mail templates screen** - `7efb9ed7` (feat) +2. **Task 2: Layouts/partials, reset, drift, custom layouts** - `83f76cc3` (feat) +3. **Task 3: Field types, branding, image library** - `4fd2ed07` (feat) +4. **Task 4: Preview and test send** - `0c73c8d4` (feat) + +**Plan metadata:** (this SUMMARY commit) + +## Shipped contracts (for 35-03) + +### Permissions and controller IDs + +- `cabana.PermissionManageMailTemplates` = `system.manage_mail_templates` +- `cabana.PermissionManageMailLayouts` = `system.manage_mail_layouts` +- Controllers: `summercms.cabana.mailtemplates` | `maillayouts` | `mailpartials` | `mailimages` +- Settings codes: `mail_templates`, `mail_layouts`, `mail_partials`, `mail_brand`, `mail_images` (category `backend::lang.settings.category_mail`) + +### Routes (admin API prefix) + +| Method | Path | Notes | +|--------|------|-------| +| GET | `/mail/images` | `AdminMailImagesResponse` (`data[]`, meta `canUpload`/`total`/`page`/`perPage`) | +| GET | `/mail/images/{id}` | `Envelope[AdminMailImage]` | +| POST | `/mail/images` | multipart `file`; layouts permission; 201 | +| POST | `/mail/preview` | `AdminMailPreviewRequest` → `AdminMailPreviewResult` | +| POST | `/mail/test-send` | interactive-only; same request; `AdminMailTestSendResult{email}` | + +### Request/response types + +- `AdminMailPreviewRequest`: `mode` (`template`\|`layout`\|`partial`\|`branding`), `id` (uint64), `values` (map). No `to`/`email`/`recipient`. +- `AdminMailPreviewResult`: `subject`, `html`, `text` +- `AdminMailTestSendResult`: `email` +- `AdminMailImage`: `id`, `fileName`, `title`, `url`, `thumbUrl` +- `RecordMeta.Deletable` (`*bool`, omitempty) on mail controllers + +### Field schema keys + +- Types: `codeeditor` (`language`: html\|css\|text; optional `size`, `mailImages`), `colorpicker`, `mailimage`, `mailpreview` (`mode`: template\|layout\|partial\|branding) +- Keys: `language`, `mailImages` (plus existing `mode`/`size`) +- List messages: `rowStateCustomized`, `rowStateOutdated` + +### Record action + +- `reset` on templates, layouts, partials config_form.yaml (file-backed customized rows) + +## Decisions Made + +- Image picker: list for either mail code; upload only for layouts (planner call). +- Test-send limit through `cooler.Attempter` when surf publishes Redis store; otherwise cabana's in-process fixed window. +- Layout create defaults injected from the catalog default layout at Activate. +- List endpoint documents `AdminMailImagesResponse` so conformance accepts `canUpload` meta. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Conformance/CSRF/schema tests lagged new field types and routes** +- **Found during:** Task 3 close-out +- **Issue:** CSRF unsafe-route count, repeater nested refusal order for codeeditor/mailpreview, datepicker/phase121 mode error text, OpenAPI inventory missing image show/upload and SuccessMeta mismatch for list meta +- **Fix:** Updated expectation strings/counts; added typeKeys for nested refusal; documented `AdminMailImagesResponse`; granted mail perms + `app.url` + library migrate in conform env +- **Files modified:** phase10_csrf_test.go, repeater_test.go, datepicker_*_test.go, phase121_*_test.go, openapi_conformance_test.go, mail_routes.go, admin_openapi.go +- **Verification:** `go test -short ./...` and `TestPhase10OpenAPIConformance` pass +- **Committed in:** `4fd2ed07` (Task 3) + +**2. [Rule 2 - Missing Critical] Conform env upload_bytes too small once Mailer published for preview cases** +- **Found during:** Task 4 OpenAPI conformance +- **Issue:** Publishing postcard Mailer activates mailimages; 5 MiB maxFilesize failed boot against 1 MiB upload_bytes +- **Fix:** Raised conform `http.body_limits.upload_bytes` to 8 MiB (same as mail smoke env) +- **Files modified:** openapi_conformance_test.go +- **Verification:** OpenAPI conformance green +- **Committed in:** `0c73c8d4` (Task 4) + +--- + +**Total deviations:** 2 auto-fixed (1 bug, 1 blocking/boot) +**Impact on plan:** Necessary for green inventories and boot; no scope creep. + +## Issues Encountered + +None beyond the auto-fixes above. Substantial uncommitted Task 3 work was inventoried and reused rather than discarded. + +## User Setup Required + +None - no external service configuration required. Test-send uses the application's existing mail driver; Redis Attempter is optional (`http.rate_limit.store: redis`). + +## Next Phase Readiness + +- Server contracts are stable for 35-03 (SPA field controls + mailpreview UX). +- 35-03 can bind to the routes, types and YAML field modes listed above without further server changes for the screens. + +--- +*Phase: 35-mail-templates-and-layouts-editor* +*Completed: 2026-11-13*