docs(35-02): complete mail screens server plan

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-11-13 13:05:25 +01:00
parent 0c73c8d4f1
commit 399ba5fb60

View File

@@ -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:<adminID> 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:<adminID>; 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*