feat(follow): add user follows with activity inbox digest

readme.md

@@ -29,6 +29,12 @@ To Be Played is split into three repositories:
   Every game carries a `reason` (`source`, plus the anchor game for `SIMILAR` 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.
+- **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
+  changes and Steam wishlist adds, and leaves out what the followed user's profile hides (`public_user.sections`).
+  Follows end for good, with a note, when the followed user goes private, and without a note when the user is blocked or
+  deleted. The nightly job at 03:15 deletes notes older than 90 days (`app.inbox.keep-days`); the list shows the newest 50.
 - **Backlog order**: every listed `BACKLOG` game (not removed, not hidden) has a row in `backlog_order (user_id,
   appid, position)`, kept by a database trigger on `user_game` like the status history: a game entering the backlog
   goes to the bottom, a game leaving it loses its row. V34 seeded the first order (priority HIGH, MEDIUM, rest, then
@@ -207,8 +213,13 @@ ArchUnit role rules (`RoleAnnotationRules`) and `src/test/resources/contract/aut
 | `GET` | `/api/stats/public` (+ games per platform, top genres, finished per year) | public |
 | `GET` | `/api/stats/owners?appid=&key=&arg=&page=` (who owns a game in the set behind a community number, `key` default `OWNED`: `listed` display names only, `listedTotal`, `privateCount`, `includesYou`, not cached, `400 BAD_ARG`) | login |
 | `GET` | `/api/stats/public/games?key=&arg=&page=` (the games behind a landing number, per game `libraries` and `minutes`; `400 BAD_ARG`) | public |
+| `GET` | `/api/follows` (`{following: [{id, displayName}], followers: [{id, displayName}]}`, `id` is the follow row; a follower with a private profile has `displayName` null) | login |
+| `PUT`, `DELETE` | `/api/follows/by-name/{displayName}` (follow, unfollow; `204`; PUT: `404 PROFILE_NOT_FOUND` for an unknown, private, blocked or deleted name, `400 FOLLOW_SELF`, `400 FOLLOW_LIMIT`) | login |
+| `DELETE` | `/api/follows/{id}` (unfollow, or remove a follower; only rows of the caller change; `204`) | login |
+| `GET` | `/api/inbox` (`{results: [{id, kind, displayName, newGames, achievements, statusChanges, wishlistAdds, createdAt, read}], unread}`, newest 50, `kind` `DIGEST` or `VISIBILITY`) | login |
+| `PUT` | `/api/inbox/read` (marks all read; `204`) | login |
 | `POST`, `PUT` | `/internal/accounts/deleted` (`{userIds}`; POST adds, PUT replaces the whole set; `204`) | service token |
-| `POST`, `PUT` | `/internal/accounts/states` (`{accounts: [{userId, steamId, displayName, blocked, roleChangedAt, listed}]}`, `displayName`, `roleChangedAt` and `listed` optional (`listed`: Auth lists the user by name, kept in `listed_user`, `null` keeps it), `displayName` at most 100 characters, kept in `account_name` for the audit log, `roleChangedAt` kept in `account_role_change`; POST updates, PUT replaces the whole set; `204`) | service token |
+| `POST`, `PUT` | `/internal/accounts/states` (`{accounts: [{userId, steamId, displayName, blocked, roleChangedAt, listed, publicProfile, profileSections}]}`, `displayName`, `roleChangedAt`, `listed` and `publicProfile` optional (`listed`: Auth lists the user by name, kept in `listed_user`, `null` keeps it; `publicProfile`: the profile is public, kept as a row in `public_user` with `profileSections`, `null` keeps row and sections, `false` ends the follows of the user with one `VISIBILITY` note each; `profileSections` `null` = all shown), `displayName` at most 100 characters, kept in `account_name` for the audit log, `roleChangedAt` kept in `account_role_change`; POST updates, PUT replaces the whole set; `204`) | service token |
 | `POST` | `/internal/accounts/purge` (`{userIds}`), `/internal/accounts/prune` (`{knownUserIds}`, not empty) | service token |
 | `GET` | `/api/version` (`{commit, builtAt}` of the running image, from the CI build; `dev` locally) | public |
 
@@ -238,6 +249,8 @@ flowchart LR
         Stats["stats"]
         Version["version"]
         Account["account"]
+        Follow["follow"]
+        Inbox["inbox"]
         Rewards["rewards"]
         Steam["steam_adapter"]
         Igdb["igdb_adapter"]
@@ -256,8 +269,10 @@ flowchart LR
     Speedrun --> SpeedrunApi["speedrun.com API"]
     LibRepo --> Db[("PostgreSQL tbp_core")]
     Stats -->|"listed_user_game, counted_user_game, game_mood, coming_game, user_game_status_change, deleted_user, blocked_user, listed_user, account_name, game_alias"| Db
+    Follow -->|"follow, follow_digest, inbox_note, public_user, sync_change, user_game_status_change, account_name"| Db
+    Inbox --> Db
     Auth -->|"service token<br/>/internal/accounts"| Account
-    Account -->|"per-user rows, deleted_user, blocked_user, listed_user, account_name, user_seen_at"| Db
+    Account -->|"per-user rows, deleted_user, blocked_user, listed_user, public_user, follow, account_name, user_seen_at"| Db
 ```
 
 | Module | Content |
@@ -265,11 +280,16 @@ flowchart LR
 | `library` | Sync, backlog, manual games, imports, playtime history, wishlist, achievements, public profile data |
 | `stats` | Public numbers for the landing page |
 | `version` | `GET /api/version`: commit and build time of the running image |
-| `account` | Driven by Auth: tombstones in `deleted_user`, purge and orphan prune of the per-user rows; blocks in `blocked_user`, listing in `listed_user` (users Auth shows by name in owner lists, #26), role changes in `account_role_change`, display names in `account_name`, Steam ID changes stop the nightly sync |
+| `follow` | Follows (`follow`), the digest cursor per followed user (`follow_digest`) and `FollowDigestService`: one note per follower and batch, from `sync_change` and the hand rows of `user_game_status_change` |
+| `inbox` | `inbox_note`: the notes of a user, `GET /api/inbox`, the 90-day purge |
+| `account` | Driven by Auth: tombstones in `deleted_user`, purge and orphan prune of the per-user rows; blocks in `blocked_user`, listing in `listed_user` (users Auth shows by name in owner lists, #26), public profiles and their sections in `public_user` (#27), role changes in `account_role_change`, display names in `account_name`, Steam ID changes stop the nightly sync |
 | `steam_adapter` | Steam Web API client, availability check of Steam CDN pictures |
 | `igdb_adapter` | IGDB client (Twitch OAuth): time to beat, game tags for moods, release years, game search |
 | `speedrun_adapter` | speedrun.com client: game search by name, verified runs |
 
+`follow` and `inbox` read `account_name`, `public_user`, `blocked_user`, `deleted_user`, `sync_result`, `sync_change`,
+`user_game` and `user_game_status_change` in SQL; the sync tells `follow` through `shared.event.LibraryActivityEvent`.
+
 **One shared schema.** All modules use one database `tbp_core`, and some read or write another module's tables in
 SQL, which ArchUnit cannot see: `stats` reads `listed_user`, `account_name`, `game_alias`, `listed_user_game`, `counted_user_game`, `steam_game`, `game_mood`, `coming_game`, `user_game_status_change`, `deleted_user` and `blocked_user`; `account`
 deletes the per-user rows of the library tables (`AccountCleanupRepository`; a new library table with `user_id` goes
@@ -321,6 +341,27 @@ Inside a module: `api` (controllers, DTOs), `service` (business logic), `domain`
 
 The frontend polls `GET /api/library/sync-status` until the run ends.
 
+Followers (#27): when the achievement run ends, `AchievementSyncService` publishes `LibraryActivityEvent`, and
+`FollowDigestService` writes one inbox note per follower from the new sync result (`ADDED`, `ACHIEVEMENTS`, `STATUS`
+and `WISHLIST` rows of `sync_change`) and the hand changes since the cursor. Kinds that the profile hides (`public_user.sections`)
+are left out, and the cursor moves anyway. A job every 10 minutes reports the hand changes alone once a user was quiet for 10
+minutes; it never takes a sync result, which may still wait for its achievements.
+
+```mermaid
+sequenceDiagram
+    participant W as LibrarySyncWorker
+    participant A as AchievementSyncService
+    participant F as FollowDigestService
+    participant D as Db
+    W->>D: sync_result, sync_change (ADDED, STATUS, WISHLIST)
+    W-->>A: LibrarySyncedEvent
+    A->>D: sync_change (ACHIEVEMENTS)
+    A-->>F: LibraryActivityEvent
+    F->>D: lock follow_digest, count sync + hand changes
+    F->>D: inbox_note per follower (public, not blocked, not deleted)
+    F->>D: move cursor
+```
+
 At 01:30 `ImageRepairService` repairs the pictures reported through `POST /api/library/broken-images` (table
 `broken_image`, one row per game and kind). Reports only count for Steam games the user owns.
 
@@ -449,12 +490,14 @@ gets no more syncs and leaves the landing stats and the pile snapshots at once.
 flagged set (`PUT`), then `purge` for users flagged 30 days ago (only tombstoned ones), then `prune` with all its
 user ids, which removes the rows of users Auth does not know (refused for more than
 `app.account-cleanup.max-orphans`, default 5). `app.account-cleanup.dry-run` (default `true`) only counts the rows.
+The tombstone also ends the user's follows in both directions without a note and removes the user's `public_user` and
+`follow_digest` rows; the purge removes the user's inbox notes and the notes about the user.
 The purge also removes the user's `account_name` and `listed_user` rows and link requests (`game_link_request`).
 
 ### Blocked users and Steam ID changes
 
 Auth sends a user's state (`POST /internal/accounts/states`) after a Steam link, an unlink, a Steam ID another account
-took by a verified link, a display name change, a block, an unblock and a change of the owner-list opt-in (`listed`, #26); its nightly job sends every user (`PUT`). A blocked user is in
+took by a verified link, a display name change, a block, an unblock and a change of the owner-list opt-in (`listed`, #26), of the public profile or of the profile tiles (`publicProfile`, `profileSections`, #27); its nightly job sends every user (`PUT`). A blocked user is in
 `blocked_user`: no nightly sync, no new sync run, not in the landing stats. `JwtAuthenticationFilter` refuses a blocked
 user's token and a token issued before the user's last role change (`account_role_change`, sent as `roleChangedAt`),
 through the cache `loginStates` (30 s, evicted by every state call). An Auth that does not send `roleChangedAt` changes