feat(postcard): database overrides for mail templates with file fallback

- postcard owns the system_mail_* tables (postcard.Migrations), run by lagoon
  as the framework set summercms.postcard after system_files
- Send asks an OverrideSource once per message; NewDBSource reads the
  customized template row through the *gorm.DB published on the app
- a failed lookup, missing tables or an override that does not render or
  fails the safety checks sends the file version and is logged
- the caller's Message.Subject still wins; Mailer, Message, NewMailer,
  Catalog.Register and BootPlugin keep their signatures

Plan 35-01, task 2 (tracer).
This commit is contained in:
Jakub Zych
2026-11-13 10:26:10 +01:00
parent 3198bbe1aa
commit 7e5d2c74af
10 changed files with 932 additions and 30 deletions

View File

@@ -77,7 +77,7 @@ The application binary has the migration commands:
./bin/acme migrate:rollback --plugin acme.blog
```
`migrate` runs the framework's own sets first (file attachments, the admin users and roles, and the job queue), then each plugin's set in plugin activation order, so a plugin's migrations run after those of the plugins it requires. Each plugin has its own history table, `summer_migrations_<plugin id>` with dots replaced by underscores, as `lagoon.HistoryTableName` returns.
`migrate` runs the framework's own sets first (file attachments, the mail tables, the admin users and roles, and the job queue), then each plugin's set in plugin activation order, so a plugin's migrations run after those of the plugins it requires. Each plugin has its own history table, `summer_migrations_<plugin id>` with dots replaced by underscores, as `lagoon.HistoryTableName` returns.
`migrate:rollback` rolls back the last applied migration of one plugin. Without `--plugin` it picks the last activated plugin that has migrations. To fix a migration you just wrote, roll it back, edit it and run `migrate` again.

View File

@@ -70,6 +70,24 @@ Before a driver sees a message, postcard refuses a subject or address with a lin
`postcard.Mailer.Send` delivers before it returns. To keep a request fast, send from a queued job, and send after the write that triggered the mail has committed; see [Queued jobs](jobs.md) and [Transactions](../database/transactions.md).
## Overrides from the admin
A plugin's mail files are the default text. postcard also owns a set of mail tables, created by `migrate` with the framework's other tables, where an administrator's edit of a template is stored. A row of `system_mail_templates` with `is_custom` set overrides the template named in its `code`: its subject, body and layout replace the file's. The body keeps the file's format, Markdown with Go template variables.
`postcard.Mailer.Send` reads that row on every send and caches nothing, so an edit applies to the next message in every process that shares the database, a `queue:work` worker included. The subject is the first of these that is set:
1. `postcard.Message.Subject`, when the caller passes one;
2. the override's subject;
3. the file's subject.
An override cannot stop mail from going out:
- With no database, or before `migrate` has created the tables, the file version is sent. A failed lookup is logged as a warning, at most once a minute.
- An override that does not parse, fails while rendering (it uses a field of a variable the caller does not pass, for example) or fails the safety checks is logged as an error with the template name, and the file version is sent.
- An override whose layout no longer exists is rendered in the `default` layout, with a warning.
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.
## Drivers
`mail.driver` selects the driver: