fix: technical debts left by the Sites, Authors and SEO slices, plus backend support for the new Sites and Authors pagination

docs/api.md

@@ -22,11 +22,11 @@ for example `https://cms.example/v1/article/`.
   under `/v1/site`) and the author writes (`POST`, `PATCH` and `DELETE` under `/v1/author`, `POST /v1/author/me` included) are session only too.
 - Each key can make 120 requests per minute. Beyond that: 429 with a `Retry-After` header.
 
-## Routes a key can call (29)
+## Routes a key can call (30)
 | Group | Routes |
 | --- | --- |
 | Articles | GET /v1/article/, GET /v1/article/{id}, GET /v1/article/{id}/seo, POST /v1/article/{id}/seo/check, POST /v1/article/, PATCH /v1/article/{id}, PATCH /v1/article/{id}/publish, PATCH /v1/article/{id}/unpublish, DELETE /v1/article/{id} |
-| Media | GET /v1/media/, POST /v1/media/, PATCH /v1/media/{id}, DELETE /v1/media/{id}, POST /v1/media/merge, GET /v1/media/{id}/usage, GET /v1/media/purge-settings (owner or admin), PATCH /v1/media/purge-settings (owner or admin), GET /v1/media/purge-preview (owner or admin), POST /v1/media/purge (owner or admin), GET /v1/media/{id}/variants (owner or admin, session only), POST /v1/media/{id}/variants (owner or admin, session only), POST /v1/media/{id}/variants/{name} (owner or admin, session only), DELETE /v1/media/{id}/variants/{name} (owner or admin, session only) |
+| Media | GET /v1/media/, GET /v1/media/{id}, POST /v1/media/, PATCH /v1/media/{id}, DELETE /v1/media/{id}, POST /v1/media/merge, GET /v1/media/{id}/usage, GET /v1/media/purge-settings (owner or admin), PATCH /v1/media/purge-settings (owner or admin), GET /v1/media/purge-preview (owner or admin), POST /v1/media/purge (owner or admin), GET /v1/media/{id}/variants (owner or admin, session only), POST /v1/media/{id}/variants (owner or admin, session only), POST /v1/media/{id}/variants/{name} (owner or admin, session only), DELETE /v1/media/{id}/variants/{name} (owner or admin, session only) |
 | Users and invites | GET /v1/user/, PATCH /v1/user/me, POST /v1/user/invite (owner only), DELETE /v1/user/invite/{id} (owner only), POST /v1/user/invite/{id}/renew (owner only), GET /v1/auth/me (with the linked `author`) |
 | Settings | GET /v1/settings |
 | Sites | GET /v1/site/, GET /v1/site/{key}/sitemap |
@@ -115,6 +115,11 @@ with `items: []` and the real `total`. Any invalid `page`, `size`, `filter`, `so
 `hash` is 400 "The media query is invalid.". Every item carries `variant_count` and `variant_size`
 (the index rows of the image and their bytes, 0 when none).
 
+`GET /v1/media/{id}` reads one image with the same auth as the list (a verified session or an API key; 403 for an
+unverified account, 401 without credentials) and writes nothing, so it records no activity event. It answers 200 with
+the object of one `items` element of the list, a missing image is 404 "Image not found" and a malformed id is 400 with
+the id-format message.
+
 Breaking change: `next_cursor` is gone and no `X-Total-Count` header is sent. `cursor` and `limit`
 are no longer parameters; they are ignored, never an error, and have no effect on paging.
 
@@ -132,7 +137,7 @@ session." with a key). The role is checked before the body.
 
 | Route | Purpose |
 | --- | --- |
-| `GET /v1/site/` | The sites, default first and then by name, each with `article_count`. |
+| `GET /v1/site/` | The sites, default first and then by name, each with `article_count`. Query `q` (up to 200 characters, matched in `name`, `key` or `base_url`, ignoring case and accents, `%` and `_` literal), `page` (a whole number from 1) and `size` (5, 25, 50 or 100). Without `page` and `size` every matching site is returned; with only `page`, `size` is 25; with only `size`, `page` is 1. The body stays a JSON array (`[]` when nothing matches, never `null`) and `X-Total-Count` holds the number of matching sites before paging. A page past the end is `200 []` with the total. An invalid `page`, `size` or `q` is 400 with the body-mismatch message and no `X-Total-Count`. |
 | `POST /v1/site/` | Create. 201 with the site. `is_default: true` makes it the default. `site_name`, `title_template` and `default_description` are optional and validated like on `PATCH`. |
 | `PATCH /v1/site/{id}` | Edit `name`, `base_url`, `default_robots`, `locale`, `default_social_image_id`, `site_name`, `title_template`, `default_description`. Absent fields are untouched. `key` may only be repeated unchanged; `is_default` is refused. |
 | `PATCH /v1/site/{id}/default` | Make the site the default, atomically. Setting the current default is a no-op. |
@@ -238,7 +243,7 @@ article is allowed and never blocks publishing.
 
 | Route | Who | Purpose |
 | --- | --- | --- |
-| `GET /v1/author/` | verified session or API key | The authors newest first. Query `q` (name or slug, accent and case insensitive), `page` (default 1), `size` (5, 25, 50 or 100, default 25). Body `{ items, total, page, size }`; a bad query is 400 with the body-mismatch message. |
+| `GET /v1/author/` | verified session or API key | The authors newest first. Query `q` (name or slug, accent and case insensitive), `page` (default 1), `size` (5, 25, 50 or 100, default 25). Body `{ items, total, page, size }`, with `total` repeated in the `X-Total-Count` header on every 200; a bad query is 400 with the body-mismatch message and no header. |
 | `POST /v1/author/` | owner or admin, session only | Create. 201 with the author. `user_id` links an account that has no author. |
 | `POST /v1/author/me` | any verified session | Create the caller's own author from the display name (or the username). A taken slug gets `-2`, `-3`... silently. 201 with the author plus `slug_adjusted`: `true` when the stored slug differs from the plain slug of the name (a collision suffix was added), `false` otherwise. No other author response carries this field. |
 | `PATCH /v1/author/{id}` | owner or admin on any author; any verified session on the author linked to it; session only | Edit `name`, `slug`, `bio`, `avatar_id`, `website`, `social_links`, `user_id`. Absent fields are untouched, `avatar_id`, `website` and `user_id` accept `null`, `social_links` is replaced as a whole. `user_id` links or unlinks the account and is owner or admin only. |

docs/api/articles.md

@@ -25,7 +25,7 @@ Visibility is unchanged: anonymous and unverified callers only see online articl
   "total": 30,
   "page": 1,
   "size": 25,
-  "counts": { "all": 30, "online": 30, "draft": 0 }
+  "counts": { "all": 30, "online": 30, "draft": 0, "suggestions": 4 }
 }
 ```
 
@@ -42,7 +42,7 @@ Visibility is unchanged: anonymous and unverified callers only see online articl
 - `items` is `[]` when empty, never `null`. Each item is the article object below.
 - Items follow `sort` (default `updated_at:desc`) across the whole list before paging. `title` ignores case, `status` orders on online state (`status:asc` puts drafts first), and every ordering ends with `id` descending so pages never overlap.
 - `total` is the number of visible articles matching `q` and `status`, before paging. `page` and `size` echo the values applied.
-- `counts` ignores `q` and `status`, so tab counts do not move while searching. For anonymous and unverified callers `all` equals `online` and `draft` is `0`, and `status=draft` answers `items: []` and `total: 0`.
+- `counts` ignores `q`, `status`, `site`, `seo`, `sort`, `page` and `size`, so tab counts do not move while searching. `suggestions` is the number of visible articles whose `seo_status` is `suggestions` (hidden and ready articles and dismissed codes are not counted); it equals the `total` of `?seo=suggestions` sent with no other filter by the same caller. For anonymous and unverified callers `all` equals `online` and `draft` is `0`, and `status=draft` answers `items: []` and `total: 0`.
 - Each item also carries `seo_status` and `seo_suggestions` (see [SEO status and suggestions](#seo-status-and-suggestions)). `seo` filters on the status before paging, so `total` follows it while `counts` do not.
 - A page beyond the last answers `200` with `items: []` and the real `total`.
 - An invalid `page`, `size`, `status`, `sort` or an over-long `q` answers `400` with the plain-text message `The request cannot be processed due to a mismatch in the format of the body.` An invalid `format` is reported first.

docs/development.md

@@ -72,6 +72,11 @@ task clean           # remove bin/, tmp/ and the built SPA
 - All Go tests live in [`test/`](../test) (package `test`, black-box). They use in-memory fakes of the domain `Repository` interfaces, so they need no database, SMTP server or network.
 - HTTP-level tests use `net/http/httptest` against a chi router. Call `validator.InitValidator()` before invoking a handler.
 - SPA component tests use Vitest + Vue Test Utils (`task test:web`). `task lint:web` runs eslint and a type check.
+- A few tests open a real SQLite file in a temporary directory (the chunked id lookups, the slug backfill and the `?seo=` measurement). They never touch the real database.
+- The tests that need a real MySQL, MariaDB or PostgreSQL server skip themselves when `RENEWCMS_TEST_MYSQL_DSN` or `RENEWCMS_TEST_POSTGRES_DSN` is unset. No CI exists, so run them by hand before a release that touches the repositories:
+  - `task test:mysql` runs `mysql:8.4` then `mariadb:11` in Docker, and `task test:postgres` runs `postgres:16` then `postgres:17`. Docker is required; the tasks start and remove the containers. Extra arguments go after `--`, for example `task test:postgres -- -run Postgres.*Chunked -v`.
+  - To use your own server on a scratch database: `RENEWCMS_TEST_MYSQL_DSN='user:pass@tcp(host:3306)/db' go test -tags nofrontend ./test/... -run MySQL -count=1`, or `RENEWCMS_TEST_POSTGRES_DSN='postgres://user:pass@host:5432/db?sslmode=disable' go test -tags nofrontend ./test/... -run Postgres -count=1`.
+  - `TestMySQLChunkedLookups` and `TestPostgresChunkedLookups` check that the batched `IN` lookups of the article repository (500 ids per batch) return the same rows as SQLite.
 
 ## Visual check against the design
 

docs/performance.md

@@ -0,0 +1,21 @@
+# Performance notes
+
+## The `?seo=` article filter
+
+`GET /v1/article/` assesses the SEO status of articles in memory, because the status depends on the body, the site template and the authors. Every request assesses every visible article once, to fill `counts.suggestions`, and `?seo=` reuses that assessment to filter before paging. The cost therefore grows with the number of articles, not with the page size.
+
+Measured by `TestSeoFilterPerformance` in `test/seo_filter_performance_test.go` (skipped with `-short`): 5,000 articles of about 5 KB each in one site, on a SQLite file in a temporary directory, every article with suggestions, `?seo=suggestions&size=25`, slowest of 3 runs:
+
+| Version | Time |
+| --- | --- |
+| `counts.suggestions` added, assessment done twice | about 430 ms |
+| assessment shared between the counts and the filter | about 270 ms |
+
+The target is 300 ms for 5,000 articles. The test also measures the default list (`GET /v1/article/` with no `?seo=`), which pays the same assessment for `counts.suggestions`. Latest run on the development machine, slowest of 3 runs:
+
+| Request | Time |
+| --- | --- |
+| `?seo=suggestions&size=25` | 315 to 338 ms |
+| default page, no `?seo=` | 307 to 329 ms |
+
+Both are slightly above the 300 ms target on this machine (they were about 270 ms in the earlier measurement), so the target is logged by the test but not enforced; no cache or index was added. Re-run the test with `go test -tags nofrontend ./test/... -run TestSeoFilterPerformance -v -count=1` after a change to the assessment rules or the article repository. The time depends on the machine; the test only fails above 500 ms.

docs/release-notes.md

@@ -41,11 +41,16 @@ Articles and sites now store the data a website needs for search and sharing, an
 - `POST /v1/article/{id}/seo/check` evaluates an article without saving, with optional overrides, and reports the suggestions, the status and whether the slug is free.
 - `GET /v1/article/` items carry `seo_status` and `seo_suggestions`, and the new `seo` parameter filters on the status.
 - `GET /v1/site/{key}/sitemap` lists the published URLs of a site, paged, with the total in `X-Total-Count`, which is now exposed to browsers through CORS.
+- `GET /v1/article/` counts gain `suggestions`, the number of visible articles that still have SEO suggestions.
+- `GET /v1/site/` takes `q`, `page` and `size` and sends the number of matching sites in `X-Total-Count`; without `page` and `size` every site is still returned, as a JSON array.
+- `GET /v1/author/` also sends its total in `X-Total-Count`.
+- `GET /v1/media/{id}` reads one image, with the fields of a media list item; a missing image answers `404` and a malformed id `400`.
 
 ### Upgrading
 
 - The first start after the upgrade adds the new columns, gives every existing article a slug generated from its title (in id order within each site, with `-2`, `-3` on conflicts) and creates the unique `(site_id, slug)` index. Nothing else changes, and a second start changes nothing.
 - A deleted article now frees its slug.
+- The slug backfill writes in batches of 500 rows, so a large database is migrated without one long transaction, and a start that was interrupted resumes where it stopped.
 
 ## Published releases