docs(35-02): complete mail screens server plan
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -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*
|
||||
Reference in New Issue
Block a user