feat(cabana): mail templates list grouped by template with per-locale status

Gap G-35-1 (supersedes D-05; D-06 reset and D-07 drift per locale):
- the templates list keeps one row per template (the base row, or the
  lowest variant when only variants ship) with a Customized locales
  column (Default, then locale codes, at most three then +N);
- row states and the status filter aggregate over the template's
  locale versions; the locale filter is removed;
- a not-customized locale without a file shows the base row's current
  subject, body and layout; its info partial says so, its file version
  compares with the base file, and Reset returns it to the base file
  (postcard.ResetOverride accepts a fallback-locale code);
- copy: mail.template.customized_locales, mail.info_locale_default,
  mail.info_locale_fallback (en/pl);
- tests: TestMailScreensSmoke/locales_list, templates and drift updated,
  TestMailDrift on the grouped row, TestMailTemplateFilterScopes.
This commit is contained in:
Jakub Zych
2026-11-13 20:39:45 +01:00
parent 52c9c7eb18
commit 67f7164302
14 changed files with 460 additions and 118 deletions

View File

@@ -354,27 +354,41 @@ type MailTemplate struct {
CreatedAt time.Time `gorm:"column:created_at"`
UpdatedAt time.Time `gorm:"column:updated_at"`
Layout MailLayout `gorm:"foreignKey:LayoutID"`
// CustomizedLocales is the list's Customized locales column: the labels
// of the template's customized versions (Default, then locale codes),
// filled by the list; it is not stored.
CustomizedLocales string `gorm:"-:all;column:customized_locales"`
}
func (MailTemplate) TableName() string { return postcard.TemplatesTable }
// FilterScopes lists the scopes of the templates list filters.
func (MailTemplate) FilterScopes() []string { return []string{mailFilterLocale, mailFilterStatus} }
// FilterScopes lists the scopes of the templates list filters: the status.
func (MailTemplate) FilterScopes() []string { return []string{mailFilterStatus} }
// FilterScope narrows the templates list: filterLocale keeps one locale
// (default: no locale suffix), filterStatus one status.
// FilterScope narrows the templates list to one status of the whole
// template: customized when any of its locale versions is, not customized
// when none is, outdated when a customized version's file changed since.
func (MailTemplate) FilterScope(name string, db *gorm.DB, value any) *gorm.DB {
if db == nil {
return db
}
text := strings.TrimSpace(fmt.Sprint(value))
if name == mailFilterLocale {
if text == mailLocaleDefault {
return db.Where(postcard.TemplatesTable + ".locale IS NULL")
}
return db.Where(postcard.TemplatesTable+".locale = ?", text)
if name != mailFilterStatus {
return db.Where("1 = 0")
}
return mailStatusScope(db, name, postcard.TemplatesTable, text)
table := postcard.TemplatesTable
group := "COALESCE(" + table + ".base_code, " + table + ".code)"
groups := func(cond string) string {
return "SELECT g.base_code FROM " + table + " g WHERE g.base_code IS NOT NULL AND " + cond
}
switch strings.TrimSpace(fmt.Sprint(value)) {
case mailStatusCustomized:
return db.Where(group + " IN (" + groups("g.is_custom") + ")")
case mailStatusNotCustomized:
return db.Where(group + " NOT IN (" + groups("g.is_custom") + ")")
case mailStatusOutdated:
return db.Where(group + " IN (" + groups("g.is_custom AND g.base_hash IS DISTINCT FROM g.file_hash") + ")")
}
return db
}
// Fillable lists the override columns a form writes: subject and body. The
@@ -435,6 +449,7 @@ var (
_ pact.AdminPartialData = mailTemplatesAdmin{}
_ recordDeletable = mailTemplatesAdmin{}
_ recordLocaleVariants = mailTemplatesAdmin{}
_ recordShowAdjuster = mailTemplatesAdmin{}
_ formFooterActions = mailTemplatesAdmin{}
)
@@ -506,10 +521,41 @@ func (c mailTemplatesAdmin) scopeTemplates(db *gorm.DB) *gorm.DB {
}
// ListExtendQuery retries the index sync until it succeeded in this process
// and lists the catalog's templates.
// and lists one row per template of the catalog (templateRepresentatives).
func (c mailTemplatesAdmin) ListExtendQuery(ctx context.Context, db *gorm.DB) *gorm.DB {
c.mail.ensureSynced(ctx)
return c.scopeTemplates(db)
if db == nil {
return db
}
_, locales := c.mail.mailLocales(ctx, c.mail.db())
return db.Where(postcard.TemplatesTable+".code IN ?", nonEmpty(c.mail.templateRepresentatives(locales)))
}
// templateRepresentatives are the codes of the rows the templates list
// shows, one per template: the base template's own row when the base ships
// a file, otherwise the lowest code of its locale variants.
func (m *mailScreens) templateRepresentatives(locales []string) []string {
byBase := map[string]string{}
for _, f := range m.catalog().Templates() {
base := postcard.TemplateBase(f.Name, locales)
if current, ok := byBase[base]; !ok || f.Name == base || (current != base && f.Name < current) {
byBase[base] = f.Name
}
}
out := make([]string, 0, len(byBase))
for _, code := range byBase {
out = append(out, code)
}
sort.Strings(out)
return out
}
// templateGroup is the base code a template row's locale versions share.
func templateGroup(t *MailTemplate, locales []string) string {
if t.BaseCode != nil && *t.BaseCode != "" {
return *t.BaseCode
}
return postcard.TemplateBase(t.Code, locales)
}
// FormExtendQuery scopes every record lookup to the catalog's templates and
@@ -529,19 +575,63 @@ func (m *mailScreens) scopeTemplateVersions(db *gorm.DB) *gorm.DB {
return db.Where("("+postcard.TemplatesTable+".code IN ? OR "+postcard.TemplatesTable+".base_code IN ?)", codes, codes)
}
// ListExtendRecords shows a template without a locale suffix as Default in
// the locale column; sorting still reads the stored column.
func (c mailTemplatesAdmin) ListExtendRecords(ctx context.Context, _ *gorm.DB, records []any) error {
label := c.mail.message(ctx, mailLang+"template.locale_default", nil)
// mailCustomizedLocalesShown is how many customized locales the list names
// before it adds " +N".
const mailCustomizedLocalesShown = 3
// ListExtendRecords fills the Customized locales column from one query over
// the page's templates: the labels of their customized versions, Default
// first, then the locale codes.
func (c mailTemplatesAdmin) ListExtendRecords(ctx context.Context, db *gorm.DB, records []any) error {
_, locales := c.mail.mailLocales(ctx, c.mail.db())
groups := make([]string, 0, len(records))
for _, record := range records {
t, err := asMailTemplate(record)
if err != nil {
return err
}
if t.Locale == nil || *t.Locale == "" {
value := label
t.Locale = &value
groups = append(groups, templateGroup(t, locales))
}
if len(groups) == 0 || db == nil {
return nil
}
var rows []struct {
BaseCode string
Code string
Locale *string
}
q := db.Session(&gorm.Session{NewDB: true}).Table(postcard.TemplatesTable).
Select("base_code, code, locale").
Where(postcard.TemplatesTable+".base_code IN ? AND "+postcard.TemplatesTable+".is_custom", groups)
if err := c.mail.scopeTemplateVersions(q).Scan(&rows).Error; err != nil {
return err
}
byGroup := map[string][]string{}
defaults := map[string]bool{}
for _, r := range rows {
if r.Code == r.BaseCode {
defaults[r.BaseCode] = true
continue
}
label := r.Code
if r.Locale != nil && *r.Locale != "" {
label = *r.Locale
}
byGroup[r.BaseCode] = append(byGroup[r.BaseCode], label)
}
defaultLabel := c.mail.message(ctx, mailLang+"template.locale_default", nil)
for i, record := range records {
t, _ := asMailTemplate(record)
labels := byGroup[groups[i]]
sort.Strings(labels)
if defaults[groups[i]] {
labels = append([]string{defaultLabel}, labels...)
}
text := strings.Join(labels, ", ")
if extra := len(labels) - mailCustomizedLocalesShown; extra > 0 {
text = strings.Join(labels[:mailCustomizedLocalesShown], ", ") + " +" + strconv.Itoa(extra)
}
t.CustomizedLocales = text
}
return nil
}
@@ -561,37 +651,54 @@ func (mailTemplatesAdmin) recordDeletable(any) bool { return false }
func (mailTemplatesAdmin) formFooterActions() {}
// ListRowStates marks a customized template, and one whose file changed
// since, outdated (D-07).
func (mailTemplatesAdmin) ListRowStates(_ context.Context, _ *gorm.DB, records []any) ([][]pact.RowState, error) {
// ListRowStates marks a template customized when any of its locale
// versions is, and outdated as well when a customized version's file
// changed since (D-07), from one grouped query over the page.
func (c mailTemplatesAdmin) ListRowStates(ctx context.Context, db *gorm.DB, records []any) ([][]pact.RowState, error) {
out := make([][]pact.RowState, len(records))
for i, record := range records {
_, locales := c.mail.mailLocales(ctx, c.mail.db())
groups := make([]string, 0, len(records))
for _, record := range records {
t, err := asMailTemplate(record)
if err != nil {
return nil, err
}
out[i] = mailRowStates(true, t.IsCustom, t.BaseHash, t.FileHash)
groups = append(groups, templateGroup(t, locales))
}
if len(groups) == 0 || db == nil {
return out, nil
}
var rows []struct {
BaseCode string
Custom bool
Outdated bool
}
table := postcard.TemplatesTable
q := db.Session(&gorm.Session{NewDB: true}).Table(table).
Select("base_code, BOOL_OR(is_custom) AS custom, BOOL_OR(is_custom AND base_hash IS DISTINCT FROM file_hash) AS outdated").
Where(table+".base_code IN ?", groups)
if err := c.mail.scopeTemplateVersions(q).Group("base_code").Scan(&rows).Error; err != nil {
return nil, err
}
states := map[string][]pact.RowState{}
for _, r := range rows {
switch {
case r.Outdated:
states[r.BaseCode] = []pact.RowState{pact.RowStateCustomized, pact.RowStateOutdated}
case r.Custom:
states[r.BaseCode] = []pact.RowState{pact.RowStateCustomized}
}
}
for i, group := range groups {
out[i] = states[group]
}
return out, nil
}
// FilterOptions serves the locale filter (Default plus every locale a
// catalog template carries) and the status filter.
func (c mailTemplatesAdmin) FilterOptions(scope string) []pact.Option {
switch scope {
case mailFilterStatus:
// FilterOptions serves the status filter.
func (mailTemplatesAdmin) FilterOptions(scope string) []pact.Option {
if scope == mailFilterStatus {
return mailStatusOptions()
case mailFilterLocale:
out := []pact.Option{{Value: mailLocaleDefault, Label: mailLang + "template.locale_default"}}
seen := map[string]bool{}
_, locales := c.mail.mailLocales(context.Background(), c.mail.db())
for _, f := range c.mail.catalog().Templates() {
if locale := postcard.TemplateLocale(f.Name, locales); locale != "" && !seen[locale] {
seen[locale] = true
out = append(out, pact.Option{Value: locale, Label: locale})
}
}
return out
}
return nil
}
@@ -614,19 +721,23 @@ func (c mailTemplatesAdmin) PartialData(ctx context.Context, name string, record
if t == nil || t.ID == 0 {
return mailEmptyView(name)
}
file, ok := c.mail.catalog().Template(t.Code)
// A locale that ships no file is based on the base template's file.
file, ok := c.mail.catalog().TemplateFor(t.Code)
switch name {
case mailPartialInfo:
view := mailInfoView{Template: true, Customized: t.IsCustom, Outdated: mailOutdated(t.IsCustom, t.BaseHash, t.FileHash)}
view.Status = mailStatusKey(t.IsCustom)
if ok {
view.Description = c.mail.message(ctx, mailLang+"info_description", map[string]string{"text": file.Description})
view.File = c.mail.fileLine(ctx, t.Code, file.PluginID)
view.File = c.mail.fileLine(ctx, file.Name, file.PluginID)
for key := range file.Samples {
view.Variables = append(view.Variables, key)
}
sort.Strings(view.Variables)
}
if err := c.localeInfo(ctx, t, &view); err != nil {
return nil, err
}
return view, nil
case mailPartialFileVersion:
if !ok {
@@ -643,6 +754,68 @@ func (c mailTemplatesAdmin) PartialData(ctx context.Context, name string, record
return nil, fmt.Errorf("cabana: mail templates: unknown partial %q", name)
}
// localeInfo sets the info partial's locale line of a template with two or
// more locale versions: the default line on the Default version, the
// fallback line (:locale) on a locale that ships no file.
func (c mailTemplatesAdmin) localeInfo(ctx context.Context, t *MailTemplate, view *mailInfoView) error {
db := c.mail.requestDB(ctx)
if db == nil {
return nil
}
def, locales := c.mail.mailLocales(ctx, db)
base := templateGroup(t, locales)
variants, err := c.mail.localeVariants(ctx, db, t, base, def, locales)
if err != nil || len(variants) < 2 {
return err
}
if t.Code == base {
view.LocaleDefault = true
return nil
}
if _, own := c.mail.catalog().Template(t.Code); !own {
locale := t.Code
if t.Locale != nil && *t.Locale != "" {
locale = *t.Locale
}
view.LocaleFallback = c.mail.message(ctx, mailLang+"info_locale_fallback", map[string]string{"locale": locale})
}
return nil
}
// adjustShownRecord shows a locale that ships no file and is not customized
// with what that locale sends now: the base template's current subject, body
// and layout (its customization when there is one). Only the shown record
// changes; nothing is written.
func (c mailTemplatesAdmin) adjustShownRecord(_ context.Context, tx *gorm.DB, record any) error {
t, err := asMailTemplate(record)
if err != nil || t.IsCustom {
return err
}
cat := c.mail.catalog()
if _, own := cat.Template(t.Code); own {
return nil
}
file, ok := cat.TemplateFor(t.Code)
if !ok {
return nil
}
var rows []struct {
Subject string
Body string
LayoutID *uint
}
if err := tx.Session(&gorm.Session{NewDB: true}).Table(postcard.TemplatesTable).
Select("subject, body, layout_id").Where("code = ?", file.Name).Scan(&rows).Error; err != nil {
return err
}
if len(rows) == 0 {
return nil
}
t.Subject, t.Body, t.LayoutID = rows[0].Subject, rows[0].Body, rows[0].LayoutID
t.Layout = MailLayout{}
return nil
}
// FormBeforeUpdate marks the row customized and stamps it with the hash of
// the file it is based on, which is what later shows a changed file (D-07).
func (c mailTemplatesAdmin) FormBeforeUpdate(_ context.Context, model any) error {
@@ -729,6 +902,15 @@ type recordLocaleVariants interface {
recordLocaleVariants(ctx context.Context, tx *gorm.DB, record any) ([]RecordLocaleVariant, error)
}
// recordShowAdjuster is implemented by the mail templates controller: the
// show response of a locale version that is not customized and ships no
// file shows the default version instead of its stored copy. It runs in the
// show's transaction after the record is loaded and only changes the loaded
// value. Unexported: no other controller's payload changes.
type recordShowAdjuster interface {
adjustShownRecord(ctx context.Context, tx *gorm.DB, record any) error
}
// formFooterActions marks a controller whose config_form.yaml declares
// recordActions without a preview block: the admin offers them in the
// update form's footer instead. Only the mail controllers implement it.
@@ -736,11 +918,9 @@ type formFooterActions interface {
formFooterActions()
}
// The mail list filter scopes and values.
// The mail list filter scope and values.
const (
mailFilterLocale = "filterLocale"
mailFilterStatus = "filterStatus"
mailLocaleDefault = "default"
mailFilterStatus = "filterStatus"
mailStatusCustomized = "customized"
mailStatusNotCustomized = "not_customized"
@@ -1385,15 +1565,20 @@ const (
// custom layout's code), the status, the template's sample variables, a
// partial's call, and the drift callout.
type mailInfoView struct {
Template bool
Description string
File []mailTextPart
CustomCode string
Customized bool
Status string
Variables []string
Usage string
Outdated bool
Template bool
// LocaleDefault marks the Default version of a template with locale
// versions; LocaleFallback is the translated line of a locale that
// ships no file.
LocaleDefault bool
LocaleFallback string
Description string
File []mailTextPart
CustomCode string
Customized bool
Status string
Variables []string
Usage string
Outdated bool
}
// mailTextPart is a piece of a translated line; Code pieces are shown as
@@ -1558,23 +1743,23 @@ func partialUsage(code, sections string) string {
// MailBrandSetting is the settings form over postcard's branding row (id 1).
// Saving it switches mail from mail.brandCss to the compiled colours.
type MailBrandSetting struct {
ID uint `gorm:"column:id;primaryKey"`
LogoFileID *uint `gorm:"column:logo_file_id"`
BodyBg string `gorm:"column:body_bg"`
ContentBg string `gorm:"column:content_bg"`
HeaderColor string `gorm:"column:header_color"`
FooterColor string `gorm:"column:footer_color"`
HeadingColor string `gorm:"column:heading_color"`
TextColor string `gorm:"column:text_color"`
LinkColor string `gorm:"column:link_color"`
ButtonTextColor string `gorm:"column:button_text_color"`
ButtonPrimaryBg string `gorm:"column:button_primary_bg"`
ButtonPositiveBg string `gorm:"column:button_positive_bg"`
ButtonNegativeBg string `gorm:"column:button_negative_bg"`
PanelBg string `gorm:"column:panel_bg"`
TableBorderColor string `gorm:"column:table_border_color"`
CreatedAt time.Time `gorm:"column:created_at"`
UpdatedAt time.Time `gorm:"column:updated_at"`
ID uint `gorm:"column:id;primaryKey"`
LogoFileID *uint `gorm:"column:logo_file_id"`
BodyBg string `gorm:"column:body_bg"`
ContentBg string `gorm:"column:content_bg"`
HeaderColor string `gorm:"column:header_color"`
FooterColor string `gorm:"column:footer_color"`
HeadingColor string `gorm:"column:heading_color"`
TextColor string `gorm:"column:text_color"`
LinkColor string `gorm:"column:link_color"`
ButtonTextColor string `gorm:"column:button_text_color"`
ButtonPrimaryBg string `gorm:"column:button_primary_bg"`
ButtonPositiveBg string `gorm:"column:button_positive_bg"`
ButtonNegativeBg string `gorm:"column:button_negative_bg"`
PanelBg string `gorm:"column:panel_bg"`
TableBorderColor string `gorm:"column:table_border_color"`
CreatedAt time.Time `gorm:"column:created_at"`
UpdatedAt time.Time `gorm:"column:updated_at"`
}
func (MailBrandSetting) TableName() string { return postcard.BrandTable }
@@ -1764,20 +1949,14 @@ type templateVersion struct {
// recordLocaleVariants lists the locale versions of the record's template
// for the switcher. It first gives the template's missing locales their rows
// (postcard.EnsureLocaleRows, idempotent), so a locale enabled since the last
// sync can be opened without a restart. The order is Default (the base
// file), then by locale code every locale with its own file, every other
// mail locale except the default, and any customized version of a locale
// that is no longer enabled.
// sync can be opened without a restart.
func (c mailTemplatesAdmin) recordLocaleVariants(ctx context.Context, tx *gorm.DB, record any) ([]RecordLocaleVariant, error) {
t, err := asMailTemplate(record)
if err != nil {
return nil, err
}
def, locales := c.mail.mailLocales(ctx, tx)
base := postcard.TemplateBase(t.Code, locales)
if t.BaseCode != nil && *t.BaseCode != "" {
base = *t.BaseCode
}
base := templateGroup(t, locales)
cat := c.mail.catalog()
if _, ok := cat.Template(base); ok {
// Under a savepoint: a failure leaves the show working.
@@ -1787,13 +1966,22 @@ func (c mailTemplatesAdmin) recordLocaleVariants(ctx context.Context, tx *gorm.D
moduleLog.WarnContext(ctx, "cabana: mail locale rows", "template", base, "error", err)
}
}
return c.mail.localeVariants(ctx, tx, t, base, def, locales)
}
// localeVariants are the locale versions of template base, t being the one
// shown, in switcher order: Default (the base file), then by locale code
// every locale with its own file, every other mail locale except the
// default, and any customized version of a locale that is no longer enabled.
func (m *mailScreens) localeVariants(ctx context.Context, db *gorm.DB, t *MailTemplate, base, def string, locales []string) ([]RecordLocaleVariant, error) {
var rows []templateVersion
q := tx.Session(&gorm.Session{NewDB: true}).Table(postcard.TemplatesTable).
q := db.Session(&gorm.Session{NewDB: true}).Table(postcard.TemplatesTable).
Select("id, code, locale, is_custom, base_hash, file_hash").
Where(postcard.TemplatesTable+".base_code = ? OR "+postcard.TemplatesTable+".code = ?", base, base)
if err := c.mail.scopeTemplateVersions(q).Order("code").Scan(&rows).Error; err != nil {
if err := m.scopeTemplateVersions(q).Order("code").Scan(&rows).Error; err != nil {
return nil, err
}
cat := m.catalog()
enabled := map[string]bool{}
for _, l := range locales {
enabled[strings.ToLower(l)] = true
@@ -1804,13 +1992,13 @@ func (c mailTemplatesAdmin) recordLocaleVariants(ctx context.Context, tx *gorm.D
_, fileBacked := cat.Template(r.Code)
v := RecordLocaleVariant{ID: r.ID, States: []string{}, Current: r.ID == t.ID}
if r.IsCustom {
v.States = append(v.States, c.mail.message(ctx, mailLang+"state_customized", nil))
v.States = append(v.States, m.message(ctx, mailLang+"state_customized", nil))
if mailOutdated(true, r.BaseHash, r.FileHash) {
v.States = append(v.States, c.mail.message(ctx, mailLang+"state_outdated", nil))
v.States = append(v.States, m.message(ctx, mailLang+"state_outdated", nil))
}
}
if r.Code == base {
v.Label = c.mail.message(ctx, mailLang+"template.locale_default", nil)
v.Label = m.message(ctx, mailLang+"template.locale_default", nil)
head = &v
continue
}