RenewCMS/features/localization_translation_flows.qa.md

# QA: Translation flows, revision conflicts, delete scopes, article moves and a target site for new articles

Accepted together with features/localization_translation_flows.feature. One pair, one pass: a Go backend part (POST /v1/article/ accepts `site`) comes first, then the SPA, which mocks `/v1` from the documented contract. Nothing else outside `web/` and `docs/` changes.

## Backend (Go, `task test`, package `test`)

Build `article.NewHandler(...)` over the real `CreateArticleUseCase`, `GetArticleUseCase`, `CreateTranslationUseCase`, `DescribeArticleUseCase` etc. wired to in-memory fakes (the existing `mockArticleRepo`, `mockSiteRepo` and language/localization/transaction fakes of `test/site_support_test.go` and `test/article_translation_create_http_test.go`; reuse, add no second copy). Mount it on a fresh `chi.NewRouter()` mirroring `api/router.go` for `/v1/article` (protected routes inside `authtoken.Verifier` + `authtoken.Authenticator` with a test token key and a cookie for each caller: writer, reader, anonymous), call `validator.InitValidator()`, exercise with `httptest`. No live server, no SQLite file, no SMTP. A new file `test/article_create_site_http_test.go` (unique fake type names) holds the HTTP cases; use-case cases go next to `test/article_create_language_test.go`.

Fixture: sites journal (id 1, default; en default, fr, de, ar; es disabled), atelier (id 2; en, fr, de), notes (id 3; en), archive (id 4; en), fresh (id 5; no confirmed rows). Articles: story 5 with 10 (en), 11 (de), 12 (fr), 13 (ar) in journal. A fr article with slug `couts` in journal and in atelier for the slug cases.

1. **Site decides placement, Examples-driven**: omitted `site`, `"site":null`, `"site":"journal"`, `"site":"atelier"` with and without `lang`; assert status 201, `site_id`, `lang` (starting language of the chosen site, never journal's), `is_online` false, new story, `created_by`, and that the response key set equals the pre-change key set (no new field).
2. **Refusals, Examples-driven over the table**: `missing` 404 `site_not_found` (plain text body, no JSON), `Bad Key!` and `""` 400 `invalid_site_key` (a short title keeps the validator text), `es` on atelier 422 `language_not_enabled`, `fr` on notes 422, `es` on journal 409 `language_unavailable`, `pt`, `xx`, `english`, short title, reader 403 `missing_permission`, anonymous 401 `Unauthorized`. Each: nothing stored in the fake. Refusals reaching the use case (404, 409, 422, short title) record one failed `article.create` event with a plain reason; refusals before it (400 validation of `site`, the site with story_id/source_article_id/copy 400, 401, 403) record no event, as before.
3. **Setup required**: site `fresh` with `lang` `fr` gives 409 `setup_required`; nothing stored.
4. **Language rules follow the site**: the same `{"lang":"fr"}` body is 201 on atelier and 409 `language_unavailable` on journal.
5. **Slug per (site, lang)**: clash in the same site and language gives the suffixed slug; the same slug in another site or another language leaves the plain slug.
6. **Site with a translation is refused**: the four bodies of the Examples table give 400 `apperr.BodyErrorMessage`, nothing stored, and the translation use case is not reached (assert with the fake). `POST /v1/article/10/translations` still creates in site 1 and ignores a `site` field.
7. **Visibility and activity**: the new offline article is 404 for an anonymous GET, absent from the public lists of both sites, listed by `GET /v1/article/?site=atelier` for a writer; the event params hold the site key.
8. **Dependency rule**: the handler test imports no persistence, models or gorm; a grep-style check is not added here (architect covers it). The handler change is the `Site *string` field with `validate:"omitempty,sitekey"` and the pass-through in `CreateArticleCommand`; no domain, repository, mapper or migration change.

Real-database runs: `task test:mysql` and `task test:postgres` are not required, because no query, model or repository changes (existing `GetByKey`, `LockSite`, `Rows`, `SlugTaken` and `Create` are already covered per site by `test/article_localization_storage_persistence_test.go` and `test/site_persistence_test.go`). If the implementation adds any query, add a persistence case there and run both.

Existing Go specs to amend (and nothing else): `test/article_create_language_test.go` (command carries the site key), `test/article_translation_create_http_test.go` (rows of the "unchanged when it is not a translation" table, the `site` plus `story_id` refusal), `test/article_title_rules_test.go` and `test/use_case_baseline_test.go` only where they build `CreateArticleCommand` or `PostArticle` (compile and default-site behaviour must be unchanged), `test/api_catalogue_drift_test.go` stays green because the route list does not change (check it still passes; if the catalogue documents request fields, update it with the docs). `test/seo_data_cleaner_test.go` fails `GetDefault` on purpose and must keep passing for the omitted-site path.

Docs (the HTTP contract the SPA mocks): update `docs/api/article-localization.md` (the `POST /v1/article/` without `story_id` section and its status table with the `site` rows above) and `docs/api/articles.md` (the `POST /v1/article/` request body), and add the `site` field to the create recipe in `docs/llm/recipe-articles.md`. The SPA mocks are written from these pages, so they land with the Go change, before the SPA work.

## Automated SPA (Vitest + Vue Test Utils, `task test:web`)

Mock `useApi`'s `request` per case (no backend), from the documented contract above. Mount EditorView in DashboardShell with a resolved verified session (user id 7, username "marta") and a test router with `/article/:id/edit` and `/article`; mount NewArticleModal from ArticleView and HomeView. Use fake timers for any delay. Specs live in `web/src/views/__tests__/`, `web/src/components/__tests__/`, `web/src/composables/__tests__/` and `web/src/lib/__tests__/`, reusing `editorKit.ts` and `localizationKit.ts`.

Fixture: the 5a fixture (journal, story 5; article 10 en online "Renovation costs"; 12 fr offline "Couts de renovation"; 13 ar online "Takalif" read-only; 11 de readable by the owner) with `revision` added (12: 3). `GET /v1/site/` mocked with journal (default), atelier, notes, archive. `GET /v1/site/{key}/languages` mocked for journal (en default, fr, de, ar, es disabled), atelier (en, fr, de), notes (en), archive (en). Error mocks reject with `ApiError` carrying the plain-text body, `code` and the headers X-Existing-Article-Id, X-Current-Revision, X-Missing-Languages, X-Conflicting-Articles (the useApi change is tested first, item 1).

Client plumbing
1. **useApi exposes the four response headers** on `ApiError` for non-ok answers, leaves `missing_permission` toasting by default and honours `onMissingPermission: 'passthrough'`; headers absent give `undefined`.
2. **Article type and draft**: `revision` read from GET and PATCH answers; the stored draft carries the base revision; a draft with no revision uses the revision loaded now (update `storedDraft`, `useArticleDraft` specs).

Add translation
3. **Entry points, Examples-driven**: language menu row, URL with and without `lang`, `lang` of an existing or disabled language, no `create_translation` (parameters removed, no dialog), list row menu navigation (`dialog=add-translation`, `&lang=` only when one language is missing); Back closes (loc.l4.form).
4. **Offered languages**: enabled minus translations[]; an unreadable existing version is offered; order follows the site.
5. **Form copy, source default and Start empty**: description, help text, radios, footer order, default source rule (default language readable, else first readable), the source option labels, the empty state hiding the source (loc.l4.form, loc.l4.empty).
6. **Title validation, Examples-driven** (nothing, "ab", 201 chars, 200 emoji): no request when invalid.
7. **Request bodies**: copy with a chosen source, start empty (no `source_article_id`); path id is the open version.
8. **Creating**: fields disabled, "Creating…" busy, Escape and backdrop inert (loc.l4.saving).
9. **Success**: dialog closes, route `/article/14/edit`, announcement "German draft created"; with unsaved edits the "Leave without saving?" dialog opens with the German labels and "Keep editing" stays.
10. **Failures, Examples-driven over the table**: 409 language_exists (Open German version navigates through the version switch, loc.dup.readable), 409 language_unavailable with the languages refetched (still enabled gives loc.dup.hidden with no Open action, no title and no id; disabled gives loc.l4.langOff), 422 language_not_enabled, 404 source_unavailable (loc.l4.unreadable), 500 and network (loc.l4.fail, entries kept, "Try again"), 403 with no toast, 400, 404 Article not found (Version unavailable). Assert the three neutral answers render the same DOM.
11. **Recovery from blocking states** (source, start empty, language) re-enables the primary.
12. **Keyboard and focus**: trap, first field, Escape (not while creating), focus returns to the opener.
13. **Long content notes**: authors and images notes from the fetched source for the thresholds in the table; no note for one author and no image (loc.l4.long).

New article modal
14. **Form by site, Examples-driven**: Archive (Title and Site only), Journal (Title, Site, Language, choice), languages request failing (Title and Site only, POST has `site` and no `lang`) (loc.l3.single, loc.l3.multi).
15. **Site field**: options in the order of `GET /v1/site/`, the `is_default` site chosen at open, one-site install still shows the field, sites request failing or empty hides it and POSTs `{title}` only.
16. **Site change** (loc.l3.sitechange): French on Journal then Notes gives English and the help "Notes only offers English, so the language was reset from French."; title kept; the help clears on the next change; Atelier keeps French with no message; languages request failing for the chosen site hides Language and the choice and POSTs `{title, site}`.
17. **Copy**: new description and "Create article"; the old sentence is gone; existing validation, counter, submitting, 400 and Error states of features/new_article_modal.feature unchanged.
18. **Create request**: body `{title, lang, site}` for Atelier and French, `{title, lang:"en", site:"journal"}` on the default site; failures: 409 `language_unavailable` and 422 `language_not_enabled` refetch the chosen site's languages and show the Error alert; 404 `site_not_found` refetches `GET /v1/site/`, resets to the default site and shows the Error alert; 409 `setup_required` and 403 `missing_permission` give the Error state with no global toast.
19. **Translation of an existing article**: `GET /v1/article/?tab=missing&lang=fr&q=...` mocked; no Site field in this mode; picker contents, help text, POST body with `story_id`, `source_article_id` (default-language version), `copy: true` and no `site`; failures reuse the Add translation alerts (loc.l3.translation). Switching the choice back and forth keeps the title and the site.

Revisions and conflicts
20. **if_revision on every save path, Examples-driven**: Save, Save and publish (save step only), Save and open English, Try saving again, title Try again; publish and unpublish carry no body; base revision updates from each 200.
21. **Restored draft**: written against revision 3 while the server is at 5; Save sends 3 and the conflict dialog shows the Restored notice (loc.l11.conflictRestored).
22. **Conflict dialog**: PATCH 409 plus X-Current-Revision then GET; copy, option order, only "Keep my changes" filled, focus, Escape equals Keep, edits and unsaved state untouched (loc.conflict). Mobile sheet at 390 shows all four options.
23. **Chained actions stop**: Save and publish (no `/publish`), Save and open English (no GET 10).
24. **Conflict reload fails**: GET 500 or network shows Save failed, no dialog.
25. **Keep my changes**; **Download my version** (Blob content: title, blank line, body text; toast and announcement "Download started"; dialog stays; no request; loc.l11.download); **Reload theirs** two-step (loc.l11.reloadConfirm), discard clears dirty state, stored draft and sets the base revision; Keep from the confirm step.
26. **Save over theirs**: PATCH with the shown revision, no refetch before it, 200 closes the dialog and updates the base revision, no request for other articles.
27. **Second conflict** (loc.l11.conflict2): GET repeated, newer time 14:41, alert copy, revision updated; **other failures** (500, network, 401 mirror and redirect, 403, 404).

Deletes
28. **Menu by scope, Examples-driven** over the three rows: enabled and disabled items, reasons, single version.
29. **Delete French version dialog and request** (loc.l8.delete): copy, danger button, busy state, DELETE 12 only, navigation to /article, toast; 404 closes quietly.
30. **Delete the only version** (loc.l8.deleteLast) and **delete the whole article** (loc.l8.deleteStoryOk): names in site language order, no hidden version, sequential DELETE (assert each call starts after the previous resolved) once per readable version with the open one last, navigation after the last 204.
31. **Refused whole delete** (loc.l8.deleteStory): first DELETE 403 gives the blocked dialog, no toast, "Delete French version" switches to the confirmation. **Stops half way**: the second DELETE answering 500, 403 or network error means the remaining versions are not requested, the toast "Couldn't delete the whole article" with "Some versions were deleted. Open the language menu to see what is left." shows, and the editor refetches or shows Version unavailable. A first-call failure other than 403 stops the same way.
32. **Single-language wording** unchanged.

Move
33. **Panel and note**: opens from the Site field and from "Move article"; listbox "Site", current site marked, note rows with Published/Draft/Read only, "Move article…" disabled until another site; choosing a site does not enable Save or send site_id (loc.l11b.moveSelect). No sentence about unreadable versions and no footnote.
34. **Confirm, busy and done** (loc.l11b.moveConfirm, moveBusy, moveDone): request body `{site:"atelier"}` to `/v1/story/5/move`, locked dialog, toast and announcement "Moved to Atelier", silent refetch keeps unsaved edits, next Save uses the new revision.
35. **Refusals, Examples-driven over the table** (loc.l11b.move, moveSlug, movePerm): X-Missing-Languages names, the destination's languages from GET site languages, slug from GET article of each id in X-Conflicting-Articles (two ids give two sentences, no Edit slug button), 403 passes through without a global toast, 500/network, site_not_found, 404.
36. **Keyboard and focus** of the panel and its dialogs.

Existing specs to amend (and nothing else)
37. Re-run and update `EditorView.spec.ts`, `EditorHeaderActions.spec.ts` (overflow items no longer "Not available yet." except Edit slug), `EditorLanguageMenu.spec.ts` (Add translation rows act), `EditorRecovery.spec.ts` (draft carries the revision), `EditorPublishing.spec.ts` (PATCH carries if_revision), `NewArticleModal.spec.ts` (title-only form becomes Title, Site, Language), the specs of `MetaSection` / sites_authors_integration (the Site field opens the move panel, the old choose-then-Save path is removed), `ArticleView` row menu (Add translation URL), `useArticleDraft*.spec.ts`.

## Visual (`task visual:check`)

Reference: docs/design/screens/localization-new-article.md, localization-editor.md and localization-conflicts-moves.md, boards in docs/design/source/. Register the screen `localization-new-article` in `web/visual/states.ts` (a new states file next to `editorLocalizationStates.ts`; it is not registered today), and replace the `pending` placeholders of the in-scope states below in `web/visual/editorLocalizationStates.ts`. Reuse the board's Journal, Archive, Atelier and Notes fixtures from `locale-fixtures.js` (article titles, the board's French title, Marta Alves, "Spring newsletter" for loc.l3.sitechange, the times 14:18, 14:32 and 14:41, the ten-author and eight-image source of loc.l4.long). Every capture must be within 10 %, light and dark, at the listed sizes. No exception or threshold change without the user's approval.

Run state by state while iterating (`task visual:check -- localization-new-article loc.l4.form`, ...), the three screens whole once at the end.

In scope (29), 1440 and 390:
- localization-new-article (13): loc.l3.single, loc.l3.multi, loc.l3.translation, loc.l3.sitechange, loc.l4.form, empty, saving, loc.dup.readable, loc.dup.hidden, loc.l4.fail, loc.l4.unreadable, loc.l4.langOff, loc.l4.long.
- localization-editor (4): loc.l8.delete, loc.l8.deleteLast, loc.l8.deleteStoryOk, loc.l8.deleteStory.
- localization-conflicts-moves (12): loc.conflict, loc.l11.conflictRestored, loc.l11.reloadConfirm, loc.l11.conflict2, loc.l11.download, loc.l11b.moveSelect, moveConfirm, moveBusy, moveDone, loc.l11b.move, moveSlug, movePerm.

Skipped (4), each `skip: 'pending'` in the setups (the existing checker reason; they print SKIP and are not investigated): loc.l4.gone, loc.l8.deleteSource, loc.l11b.moveSelectHidden, loc.l11.session. Causes are in Known gaps.

Clock-sensitive: none expected. The conflict times (14:32, 14:41, 14:18) come from mocked `updated_at` values and the stored mirror time, not from `now`. If a setup depends on the real clock, list it as `skip: 'clock-sensitive'`.

## Manual

- Focus order and focus return: dialogs and sheets return focus to their opener, the conflict dialog to the title, the Add translation dialog to the language-menu control.
- Screen reader: "German draft created", "Download started", "Moved to Atelier", dialogs announced as modal, Escape equals Keep my changes.
- Real round trip against `task dev`: create an article on a second site in another language and see it in the list of that site, add a translation (copy and empty) and open it, a real revision conflict from two browser sessions with all four choices, delete a version and the whole article, move a story to a second site with a missing language and with a slug clash, mobile sheets at 390 px.
- A real browser download of the conflict text file (Vitest checks the Blob only).
- Hover, pressed and motion states of the new dialogs; reduced motion.

## Known gaps and scope decisions

- "Save over theirs" has no destructive cue: it is drawn as an equal-weight secondary button next to "Reload theirs", as designed. Design gap to report to Claude Design; no cue is invented.
- Copy not in the design and proposed in the feature, to be confirmed by Claude Design: the toast "French version deleted", "Couldn't delete the whole article" with "Some versions were deleted. Open the language menu to see what is left.", "Couldn't move the article", "Couldn't replace theirs" for a non-conflict failure, and the Language help "Default for Atelier." pattern for any site.
- Skipped states and their cause: loc.l4.gone (a deleted source and an unreadable source give the same neutral 404, so loc.l4.unreadable covers both); loc.l8.deleteSource (siblings that track a version are unknown to the client; deferred); loc.l11b.moveSelectHidden (the client cannot tell a hidden version from a missing language; no footnote); loc.l11.session (the redirect to /login stays, the "Your session expired" dialog is not implemented). loc.l3.sitechange is now reachable through the backend `site` field and is checked.
- The Site field now also appears in the single-language form, as drawn (loc.l3.single shows Archive). Board copy kept verbatim, including the title help "0 / 200" difference with the existing "3 to 200 characters." text, recorded as a gap.
- The client cannot tell an unreadable sibling from a language with no version (the `missing_langs` follow-up on GET /v1/article/{id}), so Add translation is offered for every enabled language without a readable version and the neutral 409 answers the rest.
- "Delete the only version?" is shown when one version is readable, even if an unreadable one remains; the story then stays on the server.
- Deleting the whole article is one DELETE per readable version, sequential and stopping at the first failure other than 404 (a version already gone is skipped), not atomic. The stop-half-way toast is the only handling.
- content.create is not scoped to a site, so there is no "site the caller cannot create in" answer. A site deleted between the lookup and the insert surfaces as the existing 500 "Failed to create article".
- The copy text of the board mentions "Needs review" and "No source"; the freshness badge is release 2, so the words describe a state not yet visible.
- Edit slug: the "Edit slug" action of loc.l11b.moveSlug and the More actions item stay out until the Search and sharing slice.
- Article list row dialogs (Delete, Publish) are not changed in this slice.
- Amended in the same pair commit: features/article_translation_create.feature and .qa.md (the "unchanged when it is not a translation" table and wording, the `site` plus `story_id` refusal), features/localization_editor_navigation.feature and .qa.md (Background line on if_revision, overflow and Add translation scenarios, QA item 20, Known gaps), features/new_article_modal.feature and .qa.md (copy, Site, Language, translation path), features/sites_authors_integration.feature and .qa.md ("Changing the site is an edit"), features/articles_list.feature and .qa.md (Add translation destination), features/editor_core.feature and .qa.md (PATCH body carries if_revision; delete dialog). The Go specs listed under Backend are amended in the same commit.

- Architect fix round: a refetch after a move or a partial delete is retried once; a second failure other than 404 announces "This page may be out of date. Reload it to see the latest." politely and keeps the edits. In the New article modal a 404 "Article not found" source shows the unreadable-source alert (neutral copy, no claim of deletion); Add translation keeps closing with Version unavailable. A bad `site` key answers 400 `invalid_site_key`.