docs(35-05): complete mail template locale groups plan

This commit is contained in:
Jakub Zych
2026-11-13 20:43:18 +01:00
parent 1173a5c5a2
commit 7a209dee9a
2 changed files with 255 additions and 0 deletions

View File

@@ -0,0 +1,246 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 05
subsystem: mail
tags: [postcard, cabana, admin-spa, mail-templates, locales, gormigrate, vue]
requires:
- phase: 35-mail-templates-and-layouts-editor
provides: "35-01 postcard index rows/editor, 35-02 cabana mail screens, 35-03 admin SPA mail UI, 35-04 check-phase35.sh"
provides:
- "postcard: migration 202611130001_mail_template_base_code (base_code column + system_mail_templates_base_code_index)"
- "postcard.TemplateBase, postcard.Catalog.TemplateFor, postcard.EnsureLocaleRows"
- "postcard send resolution of <template>-<locale> without a file: own customization, else base customization, else base file"
- "postcard.ResetOverride accepts a fallback-locale template code"
- "cabana.RecordMeta.LocaleVariants + cabana.RecordLocaleVariant (show and update responses of the mail templates screen)"
- "cabana.MailTemplate.BaseCode and CustomizedLocales (unstored list column)"
- "Mail templates list: one row per template, Customized locales column, grouped badges and status filter, no locale filter"
- "admin LocaleVariantSwitcher (data-locale-variant) in the FormView header"
- "decision note .planning/notes/2026-11-13-mail-template-locale-groups.md superseding D-05; 35-UI-SPEC C16"
affects: [35-06, 35-07, sm-user-plugin follow-up, sm-demo-app UAT re-run]
actuals:
tokens: 36600
tasks: 3
commits: 4
plan_head_before: 9afe95ccef37455e7b9c9923a91ad469a5e2212c
plan_head_after: 1173a5c5a230f174afdb2be9d5f0bafa50188ad4
tech-stack:
added: []
patterns:
- "Controller-decided record meta through unexported cabana interfaces (recordLocaleVariants, recordShowAdjuster), next to recordDeletable"
- "Send-time locale fallback in postcard with no locale list: <base>-<tag> resolves to the registered base"
key-files:
created:
- admin/src/components/form/LocaleVariantSwitcher.vue
- admin/tests/form/LocaleVariantSwitcher.test.ts
- .planning/notes/2026-11-13-mail-template-locale-groups.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-05-task2-red-evidence.json
modified:
- modules/postcard/store.go
- modules/postcard/templates.go
- modules/postcard/mailer.go
- modules/postcard/editor.go
- modules/postcard/override_smoke_test.go
- modules/postcard/README.md
- modules/cabana/mail_admin.go
- modules/cabana/mail_routes.go
- modules/cabana/crud.go
- modules/cabana/relation_field.go
- modules/cabana/mail_screens_smoke_test.go
- modules/cabana/mail_lifecycle_postgres_test.go
- modules/cabana/mail_unit_test.go
- modules/cabana/README.md
- modules/cabana/backendscreens/models/mailtemplate/columns.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/_info.htm
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- admin/openapi/admin.json
- admin/src/api/schema.d.ts
- admin/src/views/FormView.vue
- admin/tests/form/FormViewMail.test.ts
- modules/boardwalk/dist
- docs/services/mail.md
- docs/backend/forms.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
key-decisions:
- "D-05 superseded (G-35-1): a mail template is one admin record; locale versions are rows grouped by base_code and opened through a locale switcher"
- "Mail locales = translator Locales(\"\") plus TranslationWriter.EnabledLocales when published; default = writer DefaultLocale, else translator Locale(); a changed locale set re-syncs the index"
- "postcard resolves <template>-<tag> (two-letter language, optional -/_ 2-8 char subtag, longest registered base) to the base file with own customization > base customization > file; names with files unchanged"
- "EnsureLocaleRows only creates a row for a code the send rule resolves to that base, so admin rows and sends cannot disagree"
- "meta.localeVariants is also sent on the update response so the switcher's state words are fresh after a save"
- "Locale filter removed; status filter and badges aggregate over the template's versions"
patterns-established:
- "recordShowAdjuster: a controller may change the loaded record before projection on show only (no write)"
requirements-completed: [G-35-1, D-05, D-06, D-07, D-13, D-16]
coverage:
- id: D1
description: "Send of <template>-<locale> uses that locale's customization, else the default-locale customization, else the default file; file-backed names unchanged; unknown names keep the error"
requirement: G-35-1
verification:
- kind: integration
ref: "modules/postcard/override_smoke_test.go#TestMailOverrideSmoke/locale_fallback"
status: pass
- kind: integration
ref: "bash scripts/check-phase35.sh --consumers --additive"
status: pass
human_judgment: false
- id: D2
description: "Template form locale switcher from meta.localeVariants; saving a locale without a file creates its own version that the next send uses; preview of that version works; out-of-catalog ids are 404"
requirement: G-35-1
verification:
- kind: integration
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/locales"
status: pass
- kind: unit
ref: "admin/tests/form/LocaleVariantSwitcher.test.ts"
status: pass
- kind: unit
ref: "admin/tests/form/FormViewMail.test.ts#shows the locale switcher from meta.localeVariants when there are two or more"
status: pass
human_judgment: false
- id: D3
description: "Templates list has one row per template with Customized locales, grouped badges and status filter; no locale filter; per-locale show, info, file version, drift and reset"
requirement: D-07
verification:
- kind: integration
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/locales_list"
status: pass
- kind: integration
ref: "modules/cabana/mail_lifecycle_postgres_test.go#TestMailDrift"
status: pass
- kind: unit
ref: "modules/cabana/mail_unit_test.go#TestMailTemplateFilterScopes"
status: pass
human_judgment: false
- id: D4
description: "The switcher and the grouped list read well in the real admin (placement under the title, option text, a site with many locales)"
verification: []
human_judgment: true
rationale: "Visual placement and readability of the switcher and the Customized locales column in the embedded admin are judged in UAT (re-run of 35-UAT test 1 on sm-demo-app)"
duration: 28min
completed: 2026-11-13
status: complete
---
# Phase 35 Plan 05: Mail template locale groups (G-35-1) Summary
**Mail templates are one admin record each: postcard groups rows by `base_code`, creates rows for locales without a file and resolves `<template>-<locale>` at send time to the default-locale version, cabana lists one row per template with customized locales and serves `meta.localeVariants`, and the admin form switches versions through a Language select.**
## Performance
- **Duration:** 28 min
- **Started:** 2026-11-13T19:14:28Z
- **Completed:** 2026-11-13T19:42:30Z
- **Tasks:** 3
- **Files modified:** 29 (plus the rebuilt `modules/boardwalk/dist`)
## Accomplishments
- postcard: migration `202611130001_mail_template_base_code`; `postcard.TemplateBase`, `postcard.Catalog.TemplateFor`, `postcard.EnsureLocaleRows`; one unexported resolver (`resolveTemplate`) for send, preview and validation; the mailer asks the override source for the locale name first and then the base; `postcard.ResetOverride` accepts a fallback-locale code.
- cabana: mail locales from the translator plus a published `TranslationWriter` (re-sync when the set changes); record lookups admit fallback rows; base-code record title; `RecordMeta.LocaleVariants` / `RecordLocaleVariant`; one list row per template with `customized_locales`, grouped row states and status filter; the locale filter is gone; a not-customized locale without a file shows the base row's current version; info lines `mail.info_locale_default` / `mail.info_locale_fallback`.
- admin: `LocaleVariantSwitcher.vue` (native select, `data-locale-variant`, unsaved-changes confirm, selection restored on refusal); embedded admin rebuilt.
- Decision note superseding D-05 and UI-SPEC section C16 (superseded rows marked).
## Task Commits
1. **Task 1: tracer, one admin record per template with a locale switcher** - `52c9c7eb` (feat)
2. **Task 2: grouped list, per-locale status, dist rebuild** - `67f71643` (feat), `e114492b` (build)
3. **Task 3: decision note and UI-SPEC C16** - `1173a5c5` (docs)
## Exported names, IDs and copy keys (for 35-06 / 35-07)
- postcard: `TemplateBase(name, locales)`, `(*Catalog).TemplateFor(name) (TemplateFile, bool)`, `EnsureLocaleRows(ctx, db, cat, defaultLocale, locales, bases...)`; migration ID `202611130001_mail_template_base_code`; index `system_mail_templates_base_code_index`.
- cabana: `RecordMeta.LocaleVariants []RecordLocaleVariant` (json `localeVariants,omitempty`), `RecordLocaleVariant{ID, Locale, Label, States, Current}`; `MailTemplate.BaseCode`, `MailTemplate.CustomizedLocales` (`gorm:"-:all;column:customized_locales"`).
- Copy (en/pl): `form.locale_variant` (Language / Język), `mail.template.customized_locales` (Customized locales / Dostosowane języki), `mail.info_locale_default`, `mail.info_locale_fallback` (`:locale`).
- Tests: `TestMailOverrideSmoke/locale_fallback`, `TestMailOverrideSmoke/migrations_roll_back` (rolls back every migration), `TestMailScreensSmoke/locales`, `TestMailScreensSmoke/locales_list`, `TestMailDrift` (grouped row), `TestMailTemplateFilterScopes`, `admin/tests/form/LocaleVariantSwitcher.test.ts`, FormViewMail switcher case.
## Decisions Made
- `EnsureLocaleRows` skips a locale whose `<base>-<locale>` code the send rule would not resolve to that base (for example a three-letter language code), so a row in the admin always matches what a send uses.
- `meta.localeVariants` is filled on the update response as well as the show response, so the switcher's state words (Customized) are current after a save without a reload.
- The variant states array is always present (`[]` when none), which keeps the SPA free of null checks.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 1 - Bug] copy key placed under the wrong YAML section**
- **Found during:** Task 1 verification (`go test -short ./...`, TestPhase10SPAKeysResolve)
- **Issue:** `form.locale_variant` was first inserted under `messages.form`, so `backend::lang.form.locale_variant` did not resolve.
- **Fix:** moved it to the top-level `form:` section in en and pl.
- **Files modified:** modules/phrasebook/backend/lang/{en,pl}/lang.yaml
- **Committed in:** 52c9c7eb
**2. [Rule 2 - Missing functionality] switcher states after a save**
- **Found during:** Task 1 (FormView wiring)
- **Issue:** the plan fills `meta.localeVariants` on show only; the save response replaces the record meta, so the switcher would keep pre-save states (a saved locale would not show Customized).
- **Fix:** `CRUDService.save` fills `LocaleVariants` on update for controllers implementing `recordLocaleVariants`; FormView keeps the previous list when a response carries none. Documented in `RecordMeta.LocaleVariants`, the cabana README and docs/backend/forms.md.
- **Files modified:** modules/cabana/crud.go, modules/cabana/relation_field.go, admin/src/views/FormView.vue
- **Committed in:** 52c9c7eb
**3. [Rule 3 - Blocking] TestMailDrift asserted the per-row list**
- **Found during:** Task 2 GREEN run
- **Issue:** `mail_lifecycle_postgres_test.go` (not in the plan's file list) expected the drifted `welcome-en` row in the outdated filter and its own row states.
- **Fix:** it now checks the welcome row (Customized locales `en`, states on the base row id).
- **Files modified:** modules/cabana/mail_lifecycle_postgres_test.go
- **Committed in:** 67f71643
**4. [Rule 2 - Missing test] FormView wiring test and filter-scope unit test**
- **Found during:** Tasks 1 and 2
- **Fix:** added a FormViewMail case (switcher rendered from `meta.localeVariants` with two variants, absent otherwise) and `TestMailTemplateFilterScopes`.
- **Committed in:** 52c9c7eb, 67f71643
**5. [gofmt] mail_admin.go reformatted**
- `gofmt -w` also realigned the pre-existing `MailBrandSetting` struct tags (whitespace only). Committed in 67f71643.
---
**Total deviations:** 5 (1 bug, 2 missing functionality/tests, 1 blocking, 1 formatting)
**Impact on plan:** no scope change; all API changes stay additive (check-phase35.sh additive passed).
## TDD Gate Compliance
Task 2 (`tdd="true"`): the RED tests (`TestMailScreensSmoke/locales_list`, the updated `templates` and `drift` subtests, `TestMailTemplateFilterScopes`) were written first and failed on their target assertions (`templates list filters = filterLocalelocale,filterStatusstatus`, `MailTemplate filter scopes = filterLocale,filterStatus`). Two gaps against the MSD TDD gate:
- **No separate `test(35-05)` RED commit.** The project rule "keep `go vet` and `go test ./...` green at every commit" (CLAUDE.md) takes precedence, so the tests landed with the implementation in `67f71643`.
- **The RED evidence checker returned INVALID_RED (`zero_tests_discovered`).** `msd-tools check tdd-red-evidence` parses only TAP and Surefire XML, and the record in `35-05-task2-red-evidence.json` holds the raw `go test -v` output of the real failing run. The record was kept as captured, not reformatted. The failure itself is genuine and reproducible by reverting `67f71643`'s non-test files.
## Issues Encountered
- Prettier reports style differences in `FormView.vue` and `FormViewMail.test.ts`; they were present before this plan and the admin has no prettier config or lint gate, so nothing was changed.
- `modules/postcard/store_postgres_test.go`, `modules/cabana/mail_routes.go` have pre-existing gofmt differences unrelated to this plan; left untouched.
## Known Stubs
None.
## Threat Flags
None beyond the plan's threat model (T-35-29..33: fallback ids go through the same permission and FormExtendQuery scope, an orphan row id is a 404 in `TestMailScreensSmoke/locales`; fallback saves are validated by `postcard.Editor.Validate`; the send rule only resolves a locale tag on a registered base in the same plugin namespace; the show hook ensures only its own group under a savepoint).
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- 35-06 / 35-07 can build on the exported names above.
- Before re-running UAT test 1 on sm-demo-app: rebuild the app on this framework commit; the index re-syncs on start and creates the locale rows. sm-user-plugin passes only `-en` today, so per-locale admin versions apply to its mail once the plugin passes `<template>-<locale>` for every locale (plugin follow-up, outside this phase).
- Nothing was pushed or tagged; no sibling repository was changed.
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-13*
## Self-Check: PASSED
All created files exist; commits 52c9c7eb, 67f71643, e114492b and 1173a5c5 are in the history; Task 1-3 acceptance criteria re-run green; plan verification: go vet, go test -short ./..., go test ./modules/postcard ./modules/cabana, check-admin-openapi.sh --check, check-admin-dist.sh, admin test (114 files) and typecheck, docs:build --check, check-phase35.sh --consumers --additive all pass.

View File

@@ -0,0 +1,9 @@
{
"command": "go test ./modules/cabana -run 'TestMailScreensSmoke/locales_list' -count=1 -v",
"exitCode": 1,
"output": " mail_screens_smoke_test.go:432: templates list filters = filterLocalelocale,filterStatusstatus\n--- FAIL: TestMailScreensSmoke (4.52s)\n --- FAIL: TestMailScreensSmoke/locales_list (0.05s)\nFAIL\nFAIL\tgit.golem15.com/golem15/summercms/modules/cabana\t4.605s\nFAIL\n",
"targetTest": "TestMailScreensSmoke/locales_list",
"targetFile": "modules/cabana/mail_screens_smoke_test.go",
"expected": "the templates list schema has no locale filter (only the status filter), one list row per template with customized_locales and grouped row states",
"actual": "templates list filters = filterLocalelocale,filterStatusstatus (the locale filter scope is still declared)"
}