docs(readme): sync features, endpoints and config with code

The readme had drifted from the code. Update sync rules, thread pools,
API tables, env vars and the CI setup.

readme.md

@@ -1,22 +1,27 @@
 # To Be Played – Core Service
 
-Business service of **To Be Played**, a Steam backlog tracker. It syncs the user's Steam library, stores the backlog
+Business service of **To Be Played**, a backlog tracker for your Steam and PlayStation libraries, plus games added
-(status, rating, notes, priority), tracks playtime per day, syncs the wishlist and adds time-to-beat data from IGDB.
+by hand or imported from GOG Galaxy, Playnite, Grouvee and HowLongToBeat files. It syncs the user's Steam library and
+the linked PlayStation account, stores the backlog (status, rating, notes, priority), tracks playtime per day, syncs
+the wishlist and adds time-to-beat data from IGDB.
 
-To Be Played is split into three repositories:
+To Be Played is split into four repositories:
 
 | Repository | Role |
 |---|---|
 | ToBePlayed-Auth | Users, login, settings, signs JWTs |
 | **ToBePlayed-Core** (this one) | Steam library, backlog, wishlist, stats; verifies JWTs |
 | ToBePlayed-Frontend | React single-page app |
+| ToBePlayed-Deployment | Docker Compose stack, env template, ROADMAP.md (history), plans |
 
 ## Features
 
 - **Steam sync**: owned games, playtime and achievements through the Steam Web API. Manual sync plus a nightly
-  sync. Resilience4j rate-limits every Steam call and tries the owned games up to three times (never again on a 4xx;
+  sync. Resilience4j rate-limits every Steam call (2 per second) and retries only where a repeat is safe: owned games,
-  the wishlist and the calls a page waits for once); Caffeine caches game counts and player summaries. A sync commits its claim (`RUNNING`, with
+  achievement schema and player achievements up to 3 times (`steamApi`, never on a 4xx); player summary and wishlist
-  `sync_started_at`), its writes and its finish apart, and calls Steam and IGDB outside any transaction: a second
+  once with an empty fallback (`steamApiOnce`); store, release and global-percentage calls not at all. Caffeine caches
+  player summaries (`steamPlayerSummary`), IGDB searches and the landing numbers, not game counts. A sync commits its
+  claim (`RUNNING`, with `sync_started_at`), its writes and its finish apart, and calls Steam and IGDB outside any transaction: a second
   sync sees `RUNNING` and skips, a failed one stores `FAILED`. A run older than `app.library.running-stale-minutes`
   can be taken over; its own finish then changes nothing.
 - **Backlog**: status (`BACKLOG`, `PLAYING`, `FINISHED`, `COMPLETED` = 100 %, `DROPPED`), rating 1–5, notes, priority,
@@ -40,6 +45,19 @@ To Be Played is split into three repositories:
   `SERIES`, `studioName` for `STUDIO`, `friendName`, `friendFinished` and `friendPlaytimeMinutes` for `FRIENDS` or `firstSeenAt` for `LONGEST`).
   Games already shown can be excluded for a reroll. Moods `STORY`, `COOP`,
   `CHILL`, `ACTION`, `SCARY` come from IGDB genres, themes and game modes; `SPEEDRUN` from speedrun.com.
+
+  ```mermaid
+  flowchart LR
+      NEXT_UP --> Rows
+      SERIES --> Rows
+      SIMILAR --> Rows
+      STUDIO --> Rows
+      FRIENDS --> Rows
+      LONGEST --> Rows
+      RANDOM --> Rows
+      Rows["up to 3 games per row (ROW_SIZE), empty rows left out"] --> Filters["budget + exclude: every row; mood: RANDOM only"]
+      Filters --> Out["games + reason"]
+  ```
 - **Follow users (#27)**: a logged-in user follows people with a public profile by display name (`/api/follows`, at most
   500, never an id in an answer) and gets one inbox note per followed user and batch (`/api/inbox`): a sync with its
   achievement run, or the hand changes of a quiet 10 minutes. A note counts new games, achievement unlocks, status
@@ -61,16 +79,6 @@ To Be Played is split into three repositories:
   sum). It keeps its status and shows `coming` / `comingOn`. Date: IGDB `first_release_date`, else Steam's store
   (`GetItems` with `include_release`), else unknown (= released). View `coming_game`, table `game_release`; a
   year-only IGDB date stays a placeholder until the real date comes (coming rows refresh daily).
-
-  ```mermaid
-  flowchart LR
-      A["anchor: random of top 5 played"] --> S[similar]
-      S --> M["PickMix: rotate 4 sources, dedupe, random fallback"]
-      L[longest waiting] --> M
-      R[random] --> M
-      N["next up: random of top 5 in order"] --> M
-      M --> O["games + reason"]
-  ```
 - **Speedrun games**: a backlog game counts as a speedrun game when speedrun.com has a game with the same name (case,
   punctuation, ™ and roman numerals ignored) and a release year at most one year off, when IGDB knows it, with at
   least one verified run. An edition that finds nothing tries its IGDB parent game with the parent's year, else its
@@ -178,8 +186,8 @@ flowchart LR
   header picture (`IStoreBrowseService/GetItems` with assets) goes to `steam_game.image_url`. When a few achievement
   icons do not load, the schema comes fresh from Steam; an empty answer keeps the stored one. A report that cannot be repaired is tried again on the next report, at most 3 times,
   then after 30 days.
-- **Time to beat**: story, extras and completionist hours from the IGDB API. Optional: without credentials the
+- **Time to beat**: IGDB's `hastily`, `normally` and `completely` minutes (`game_time_to_beat`, V6). The Frontend labels
-  feature is off and the rest works.
+  them story / extras / 100 %. Optional: without credentials the feature is off and the rest works.
 - **PlayStation link** (optional, unofficial API): the user pastes an NPSSO once, Core keeps only the encrypted refresh
   token (about 10 days). Every library sync then adds the played PS4/PS5 titles that match IGDB exactly, keeps the unsure
   ones for the import review, and updates playtime and last played date. The same sync reads the PS4/PS5 **trophy
@@ -237,9 +245,10 @@ ArchUnit role rules (`RoleAnnotationRules`) and `src/test/resources/contract/aut
 | `GET` | `/api/rewards/wallet` (balance, catalog, owned, equipped, last 50 ledger rows with the game name, unlock `progress` per track, `earlySince` for the rules text) | JWT |
 | `GET` | `/api/rewards/expected?appids=` (`{appid: points}`, the full finish value, 0 when paid; read-only, no settle; `400 TOO_MANY` over 200 appids) | JWT |
 | `POST` | `/api/rewards/purchases` (`{item}`; `200` wallet, `409 ALREADY_OWNED` / `NOT_ENOUGH_POINTS` / `NOT_FOR_SALE`) | JWT |
+| `GET` | `/api/rewards/games/{appid}` (settles, then the paid rows of the game and its set, `bookedNow`, one reason per missing kind; `404 GAME_NOT_FOUND`) | JWT |
 | `GET` | `/api/rewards/progress/{track}/games?page=`, `/api/rewards/history/{kind}/{ref}/games?page=` (the games behind a track or a `MONTH` / `STREAK` bonus; `400 NOT_A_GAME_LIST`) | JWT |
 | `PUT` | `/api/rewards/equipped/{slot}` (`{item}`, null = take off; `200` wallet, `409 NOT_OWNED`, `400 WRONG_SLOT`) | JWT |
-| `GET` | `/api/library/games` (one row per set, the counted edition, with `platforms[]` of all its editions: Steam, PlayStation, then manual, and `totalPlaytimeMinutes` (all platforms; `playtimeMinutes` stays the counted edition's own); `name` matches any edition; `source=STEAM,PSN` keeps rows with a platform of that source, a PlayStation title on a Steam row counts as `PSN`; ignored with `hidden=true`, which lists every hidden row; `400` on an unknown source; an old `hideDuplicates` param is ignored), `/api/library/games/{appid}` | JWT |
+| `GET` | `/api/library/games` (one row per set, the counted edition, with `platforms[]` of all its editions: Steam, PlayStation, then manual, and `totalPlaytimeMinutes` (all platforms; `playtimeMinutes` stays the counted edition's own); `name` matches any edition; `source=STEAM,PSN` keeps rows with a platform of that source, a PlayStation title on a Steam row counts as `PSN`; ignored with `hidden=true`, which lists every hidden row; `400` on an unknown source; an old `hideDuplicates` param is ignored) | JWT |
 | `GET` | `/api/library/dashboard-games?top=10&playing=8` (`{top, playing}`: the Dashboard tiles in one call, listed entries by set playtime, most first; `playing` only status PLAYING; same rows and order as `/games` with `sort=playtimeMinutes,desc` / `status=PLAYING`, no count query; limits clamped to 1..20; calls `syncIfStale` like `/games`) | JWT |
 | `PATCH` | `/api/library/games/{appid}/backlog` (only the sent fields; `null` clears one) | JWT |
 | `PUT`, `DELETE` | `/api/library/games/{appid}/corrections/{field}` (`{value}`; `name`, `image`, `speedrun`, `moods`, `endless`, `genres`, `time_to_beat` = `{normallyMinutes, completelyMinutes}`; `204`, `400 INVALID_CORRECTION`) | JWT, AUDITOR |
@@ -259,6 +268,12 @@ ArchUnit role rules (`RoleAnnotationRules`) and `src/test/resources/contract/aut
 | `PUT` | `/api/library/games/{appid}/finished-hint` (`{dismissed: ENDING\|PLAYTIME}`, "Not yet"; `204`) | JWT |
 | `GET` | `/api/library/removed-games` (`{results: [{appid, name, imageUrl, source, platform, removedAt}]}`: the caller's removed `MANUAL` and `PSN` games, newest first) | JWT |
 | `POST` | `/api/library/games/{appid}/restore` (a removed game comes back with its old data; `204`, also when it is already back; `404 GAME_NOT_FOUND`, `409 STEAM_GAME`) | JWT |
+| `GET` | `/api/library/game-search?q=` (IGDB search for "add a game", `q` 2-100 characters; `{available, results: [{appid, inLibrary, ...}]}`; `502 IGDB_FAILED`) | JWT |
+| `POST` | `/api/library/games` (`{igdbId, platform, status, playtimeMinutes?}`; `201 {appid}`, `400 UNKNOWN_GAME`, `409 ALREADY_IN_LIBRARY`, `503 IGDB_OFF`) | JWT |
+| `PUT` | `/api/library/games/{appid}/manual` (`{platform, playtimeMinutes}`, MANUAL and PSN rows, a PSN row keeps its playtime; `204`, `404 GAME_NOT_FOUND`, `409 STEAM_GAME`) | JWT |
+| `DELETE` | `/api/library/games/{appid}` (soft remove, same answers) | JWT |
+| `GET` | `/api/library/sync-changes` (`{syncedAt, startedBy, seen, importedGames, changes[]}` of the last sync; `204` when none) | JWT |
+| `PUT` | `/api/library/sync-changes/seen` (`{syncedAt}`; idempotent; `204`) | JWT |
 | `PUT` | `/api/library/games/{appid}/hidden` (`{hidden}`; Steam and manual games) | JWT |
 | `POST` | `/api/library/imports` (`{source: TEXT\|CSV\|SEARCH\|GALAXY\|GROUVEE\|HLTB\|PLAYNITE\|BOOKMARKLET, rows: [{title, platform, playtimeMinutes, status, igdbId}]}`, 1–1000 rows; `202 {id}` in `QUEUED`, `409 IMPORT_RUNNING`, `503 IGDB_OFF`) | JWT |
 | `GET` | `/api/library/imports` (`{imports}`, the last 20), `/api/library/imports/{id}` (status, progress counts, `ahead` while it waits in a queue, `attempts`; the rows with their candidates while `READY`) | JWT |
@@ -268,7 +283,7 @@ ArchUnit role rules (`RoleAnnotationRules`) and `src/test/resources/contract/aut
 | `GET`, `DELETE` | `/api/library/psn-account` (`{enabled, linked, linkedAt, expiresAt, reviewImportId}`: the PSN import waiting for review, else null), unlink (`204`, deletes the stored token) | JWT |
 | `GET`, `DELETE` | `/api/library/imports/{id}/undo-check` (`{games, changed}`), `/api/library/imports/{id}/games` (undo; `204`, `409 IMPORT_NOT_SAVED`) | JWT |
 | `POST` | `/api/library/sync` | JWT |
-| `GET` | `/api/library/games/{appid}` (detail; `refresh=false` answers from stored data and sets `achievementsStale` when a due Steam refresh was skipped (default `refresh=true` refreshes, as before); slice 3: `achievements[]` also hold trophies with `kind` `STEAM`\|`PSN`, `setId`, `trophyType`, `group`, `rarity`; new `achievementSets[]` = `{id, kind, platform, name, total, unlocked, perfect, visible, listed}`, Steam first, then PS5 before PS4; `hasAchievements` = any set; the top-level counts stay Steam only; `platforms[]` = `{source, platform, appid, playtimeMinutes, lastPlayedAt, achievementsUnlocked, achievementsTotal, perfect}` one line per platform of the entry, Steam, PS5, PS4, manual, each with its own progress, `appid` = the edition whose detail lists them; `totalPlaytimeMinutes` = their sum) | JWT |
+| `GET` | `/api/library/games/{appid}` (detail; `refresh=false` answers from stored data and sets `achievementsStale` when a due Steam refresh was skipped; `achievements[]` also hold trophies with `kind` `STEAM`\|`PSN`, `setId`, `trophyType`, `group`, `rarity`; new `achievementSets[]` = `{id, kind, platform, name, total, unlocked, perfect, visible, listed}`, Steam first, then PS5 before PS4; `hasAchievements` = any set; the top-level counts stay Steam only; `platforms[]` = `{source, platform, appid, playtimeMinutes, lastPlayedAt, achievementsUnlocked, achievementsTotal, perfect}` one line per platform of the entry, Steam, PS5, PS4, manual, each with its own progress, `appid` = the edition whose detail lists them; `totalPlaytimeMinutes` = their sum) | JWT |
 | `POST` | `/api/library/broken-images` (`{appid, kind}`, kind `COVER` or `ACHIEVEMENT_ICONS`; `204`) | JWT |
 | `GET` | `/api/library/backlog?limit=&released=` (`{games}` in the user's order; `limit` 1-20, none = all) | JWT |
 | `PUT` | `/api/library/backlog` (`{appids}` = the whole order; `204`) | JWT |
@@ -300,9 +315,9 @@ ArchUnit role rules (`RoleAnnotationRules`) and `src/test/resources/contract/aut
 - PostgreSQL 17, Flyway migrations
 - Resilience4j: retry and rate limiter for Steam, rate limiters for IGDB and speedrun.com
 - JJWT with Ed25519 public key
-- Spring Boot Actuator + Micrometer (Prometheus)
+- Spring Boot Actuator (`/actuator/health` only)
 - Tests: JUnit 5, Testcontainers (PostgreSQL), ArchUnit
-- CI: Forgejo Actions, multi-stage Docker image
+- CI: Gitea Actions (`.gitea/workflows/publish-core.yml`), multi-stage Docker image
 
 ## Architecture
 
@@ -398,8 +413,10 @@ Inside a module: `api` (controllers, DTOs), `service` (business logic), `domain`
 ### Sync flow
 
 1. `GET /api/library/games`, `/dashboard-games`, `/games-count` and `/picker` call `LibrarySyncService.syncIfStale`. It starts a sync
-   when the last one is older than 24 hours, older than 15 minutes after a failure, or was for another Steam ID.
+   when the last success is older than 20 hours (`app.library.sync-ttl-hours`) and the last try older than 60 minutes
-   `POST /api/library/sync` starts one at once, but at most every 60 seconds (else `429` with `Retry-After`).
+   (`login-retry-minutes`, also after a failure), or when it was for another Steam ID.
+   `POST /api/library/sync` starts one at once, but at most every 60 seconds (`force-sync-cooldown-seconds`),
+   else `429` with `Retry-After`.
 2. A nightly job (23:55, Europe/Berlin) syncs every account used in the last 14 days, one after the other. A
    request without a `steamId` claim (the user unlinked the Steam account in Auth) takes the user out of it.
    Afterwards it writes every user's pile size of the day to `backlog_snapshot`, also for users without Steam, and
@@ -463,18 +480,20 @@ At 01:30 `ImageRepairService` repairs the pictures reported through `POST /api/l
 
 ### Background work
 
-Background work runs on two pools (`AsyncConfig`; every `@Async` names one, ArchUnit checks it):
+Background work runs on three pools (`AsyncConfig`; every `@Async` names one, ArchUnit checks it):
 
 - The default pool (4 threads, queue 100) runs the syncs and the time-to-beat and mood refreshes a page view
   starts. A page view queues only games without a fresh row. When the queue is full, the task is dropped with
   a warning, and the next view or sync asks again. Known limit: a dropped sync still answers `202`; the user
   starts it again.
-- The follow-up pool (2 threads, no limit on the queue) runs the achievement runs after a sync and every speedrun
+- The follow-up pool (2 threads, no limit on the queue) runs the achievement runs after a sync and the speedrun
-  refresh. They hold a thread for minutes because of the Steam and speedrun.com pace, so they do not take the page
+  refreshes (`@Async`). They hold a thread for minutes because of the Steam and speedrun.com pace, so they do not take
-  views' threads. A task is small (a user or a few appids), and none is dropped.
+  the page views' threads. A task is small (a user or a few appids), and none is dropped.
+- The speedrun drainer (`speedrunExecutor`, 1 thread) works the speedrun.com queue (`SpeedrunService`).
 
-Imports have their own two threads, and `game_import` is their queue. Scheduled jobs (nightly sync, image repair,
+Imports run in two lanes, `game-import-match` and `game-import-save`, 1 thread each, queue 1; `game_import` is their
-import watchdog) run on the scheduler.
+queue. Scheduled jobs run on the scheduler: nightly sync 23:55, image repair 01:30, rewards settle 02:30, inbox purge
+03:15, merge-undo purge 03:45, import watchdog every minute, credit backfill every 30 s, follow digest every 10 min.
 
 ```mermaid
 flowchart LR
@@ -482,10 +501,12 @@ flowchart LR
     Sync["sync request"] --> Pool
     Synced["sync, after commit"] --> FollowUp["follow-up pool<br/>2 threads"]
     View -->|"speedrun"| FollowUp
+    FollowUp --> Drainer["speedrunExecutor<br/>1 thread"]
     Pool --> Apis["Steam, IGDB, speedrun.com"]
     FollowUp --> Apis
+    Drainer --> Apis
     Import["POST /imports"] --> Lanes["GameImportWorker<br/>2 own threads"]
-    Cron["scheduler"] --> Jobs["nightly sync, image repair, import watchdog"]
+    Cron["scheduler"] --> Jobs["nightly sync, image repair, rewards settle, inbox purge, merge-undo purge, import watchdog, credit backfill, follow digest"]
 ```
 
 Core runs as one instance. The pools, the speedrun queue, the per-user achievement runs and the achievement locks
@@ -812,7 +833,7 @@ other, then start them in this order (Core also starts without Auth and finds it
 3. **Frontend**: in `ToBePlayed-Frontend`, `npm install`, then `npm run dev`, and open `http://localhost:5173`
    (`localhost`, not `127.0.0.1`, so the browser sends the login cookies to every local port). The development
    values must be `VITE_API_URL=http://localhost:8080` and `VITE_CORE_API_URL=http://localhost:8090`.
-4. **Log in** with `dev@localhost` / `password123`. On the dashboard, start a Steam sync: the library fills with 8
+4. **Log in** with `dev@localhost` / `password123`. On the dashboard, start a Steam sync: the library fills with 30
    games, achievements, time to beat, moods, a wishlist and one speedrun game from recorded answers.
 
 What the `local` profile does:
@@ -853,10 +874,11 @@ Needs Java 25, Docker and your own keys.
 ```
 
 Spring Boot's Docker Compose support starts PostgreSQL from `compose.yaml`, Flyway applies the migrations, and the
-service listens on `http://localhost:8090`. Health: `/actuator/health`, metrics: `/actuator/prometheus`.
+service listens on `http://localhost:8090`. Health: `/actuator/health` (the only open actuator endpoint).
 
 In the `dev` profile a request without an `Authorization` header gets a dummy user, so the API is usable without a
-running Auth service.
+running Auth service. There is no `application-dev.yml`: `dev` only swaps the JWT filter
+(`DevJwtAuthenticationFilter`, `@Profile("dev")`); everything else is `application.yml`.
 
 Configuration comes from environment variables:
 
@@ -867,7 +889,9 @@ Configuration comes from environment variables:
 | `STEAM_API_KEY` | Steam Web API key |
 | `IGDB_CLIENT_ID`, `IGDB_CLIENT_SECRET` | Twitch app for IGDB (optional) |
 | `APP_PSN_TOKEN_KEY` | Key for the stored PlayStation tokens, `openssl rand -base64 32` (optional; empty = PlayStation link off) |
-| `DB_PASSWORD` | Local PostgreSQL password |
+| `APP_FRONTEND_URL` | CORS origin, default the production host |
+| `APP_ACCOUNT_CLEANUP_DRY_RUN` | Default `true`: the purge and prune only count |
+| `APP_BUILD_COMMIT`, `APP_BUILD_TIME` | Feed `GET /api/version`; defaults `dev` and empty. CI passes `GIT_SHA` and `BUILD_TIME` as Docker build args |
 
 ### Request timing log