feat(cabana): mail templates screen over postcard overrides

- Settings -> Mail -> Mail templates in the internal pseudo-plugin when
  postcard's Mailer is published; system.manage_mail_templates and
  system.manage_mail_layouts registered with no role grants
- MailTemplate/MailLayout models, catalog-scoped list and form, layout
  relation over file and custom layouts, no create or delete
- save stamps is_custom, base_hash and customized_at and validates the
  override through postcard.Editor inside the save transaction
- serve-start postcard.SyncIndex through lagoon.OnDatabase, retried on
  the first mail list request
- copy en/pl, README and docs; TestMailScreensSmoke/templates

Plan 35-02, task 1
This commit is contained in:
Jakub Zych
2026-11-13 11:45:13 +01:00
parent 2acf8e46c4
commit 7efb9ed7ad
13 changed files with 1046 additions and 9 deletions

View File

@@ -165,6 +165,18 @@ An override cannot stop mail from going out:
The log lines carry the component `postcard`. In a test, pass any `postcard.OverrideSource` in `postcard.Options.Overrides` to supply overrides without a database; `postcard.NewDBSource` is the one `postcard.Activate` installs.
## Editing mail in the admin
Every application with an admin gets the mail screens in Settings → Mail, with no setup in the application or its plugins. They are served by the admin itself (cabana) over postcard's tables:
- **Mail templates** lists every template the application's plugins register, one row per file, so `acme.blog::mail.welcome` and `acme.blog::mail.welcome-en` are separate rows. The list shows the code, the subject, the file's description, the locale (the suffix after the last dash when it is one of the application's locales, otherwise Default) and the layout. The form edits the subject, the Markdown message and the layout, chosen from every file layout and every layout created in the admin. The description stays the file's.
The screen needs `system.manage_mail_templates` (see [Users and permissions](../backend/users-and-permissions.md#permissions)). Templates come from files, so the list has no create and no delete.
The rows exist before anyone edits a template: when the admin starts, it writes an index row for every file template, layout and partial (`postcard.SyncIndex`), and keeps a row that is not customized equal to its file. A row whose plugin is no longer installed stays in the table but is not listed. If the tables are not there yet when the admin starts, the first open of a mail list writes the rows.
Saving a template stores your subject, message and layout in its row and marks it customized, together with the hash of the file the change was based on. From then on your version is sent instead of the file, until the template is reset to the file version. A save is checked the way a send would render it (`postcard.Editor.Validate`): a message that does not parse, does not render with the sample values or fails the safety checks is refused with a line under the field, and nothing is stored.
## Drivers
`mail.driver` selects the driver: