docs(35-05): complete mail template locale groups plan
This commit is contained in:
@@ -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.
|
||||
@@ -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)"
|
||||
}
|
||||
Reference in New Issue
Block a user