Plan: Watch History (v2)¶
Overview¶
Status: Done (2026-10-18, QA-1 verified on prod). Approved 2026-10-15. Defaults are accepted: 30 s progress heartbeat, accent-sensitive search, and the feed only shows a badge.
Author: nguyenhuuca
Date: 2026-10-15
Related PRD: PRD-watch-history-v2
ADR: ADR-0021. It supersedes ADR-0013 and ADR-0014.
Supersedes: plan-watch-history.md and plan-watch-history-opus.md (never implemented).
Builds on:
- the view counter (
POST /videos/{id}/view,VideoViewServiceImpl) user_settings.incognito_enabled- the History page (
HistoryView,hist-*CSS) - ADR-0020 (i18n)
Estimate: about 6.5 dev-days. BE about 2.5d, FE about 3.5d, QA 0.5d.
Technical Approach¶
Data: one migration, 202610160001-create-watch-history.sql¶
CREATE TABLE watch_history (
user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
video_id BIGINT NOT NULL REFERENCES video_sources(id) ON DELETE CASCADE,
watched_at TIMESTAMPTZ NOT NULL DEFAULT now(),
position_sec INT NOT NULL DEFAULT 0 CHECK (position_sec >= 0),
duration_sec INT CHECK (duration_sec > 0),
PRIMARY KEY (user_id, video_id)
);
CREATE INDEX idx_watch_history_user_recent ON watch_history (user_id, watched_at DESC);
Other migrations already reference users(id), so the foreign key works as written.
Backend¶
WatchHistoryRepository uses native SQL, like VideoReactionRepository:
-
It returns the number of rows. 0 means the video is unknown or hidden.upsertWatched(userId, videoId): -
trimToCap(userId, cap): -
updateProgress(userId, videoId, pos, dur)runsUPDATE … WHERE user_id = :u AND video_id = :vid. It never inserts. - Page query: a constructor-expression or projection that joins
video_sources. It takes an optionallower(v.title) LIKE lower(:q)filter, with%and_escaped. It returns videoId, title, fileId, viewCount, watchedAt, positionSec, durationSec. One query plus one count. findSummary(userId)returns(video_id, position_sec, duration_sec), limit 500.deleteOne(userId, videoId),deleteAll(userId).
WatchHistoryService / WatchHistoryServiceImpl:
recordWatch(userId, videoId):- If
settingsReposays incognito, it returns without writing. - Otherwise
@Transactionalupsert, then trim toapp.watch-history.max-entries(default 500).
- If
saveProgress(userId, videoId, pos, dur):- It is a no-op in incognito.
- It clamps
durto 1..21600 andposto 0..dur, and ignores non-finite or negative values.
list(userId, q, page, size):sizeis clamped to 1..50.qis trimmed, at most 100 characters, and a blankqmeans no filter.- The DTO includes
completed = pos >= 0.9·dur || dur − pos <= 10.
summary(userId),remove(userId, videoId),clear(userId).
Hook into the view path.
- In
VideoViewController.record, whenAppUtils.getCurrentUser()is non-null, callwatchHistoryService.recordWatch(user.getId(), videoId)in addition torecordView. It is not gated by the 30-minute dedupe, so a re-watch still bumpswatched_at. - Wrap it in try/catch and log at warn level. A history failure must never fail the view call (still 204).
WatchHistoryController, base /watch-history, authenticated. These paths are not in the public AppConstant list.
| Method | Path | Body / params | Response | Rate |
|---|---|---|---|---|
| GET | /watch-history |
q?, page=0, size=20 |
{data: Page<WatchHistoryItemDto>} |
60 |
| GET | /watch-history/summary |
— | {data: [{videoId, positionSec, durationSec, completed}]} |
30 |
| PUT | /watch-history/{videoId}/progress |
{positionSec, durationSec} |
204 | 120 |
| DELETE | /watch-history/{videoId} |
— | 204 | 20 |
| DELETE | /watch-history |
— | 204 | 20 |
- CORS needs no change:
filter/WebSecurityConfigalready allowsPUTandDELETE. - Account deletion:
UserSettingsServiceImpl.deleteAccountcallswatchHistoryRepository.deleteAll(userId). - Config: add
app.watch-history.max-entries: ${WATCH_HISTORY_MAX_ENTRIES:500}.
Frontend¶
api/watchHistory.js:list(q, page, size),summary(),progress(videoId, pos, dur),remove(id),clear().progressusesfetchwithkeepalive: true. Add akeepaliveoption toclient.jsrequest().- It is a no-op for guests.
hooks/useWatchHistory.js:useWatchHistoryInfinite(q)under query key['watchHistory', 'list', q].useWatchHistorySummary(), enabled only when logged in, withstaleTimeof 60 s. It returns aMap<videoId, {positionSec, durationSec, completed}>.- Mutations
useRemoveWatchEntryanduseClearWatchHistory, which invalidate['watchHistory']. - The view call invalidates the summary and list after it succeeds.
VideoPlayer.jsx:- After the view is sent, if the user is logged in, report progress: on
pause, onactive→ false, onvisibilitychangehidden, every 30 s while playing, and on unmount. Throttle to at most one call per 10 s, except on pause or unmount. - New prop
startAt(seconds). Onloadedmetadata, seek to it once when it is > 5 and < duration − 10.
- After the view is sent, if the user is logged in, report progress: on
- Resume entry:
AppShell.playVideo(id, { startAt })storesdeepLinkStartAtnext todeepLinkId.PublicFeedpasses it to theVideoPlayerof the deep-linked video only, once.- History cards call
onPlayVideo(id, { startAt: completed ? 0 : positionSec }).
- Badges:
WatchedBadgeshows "Đã xem" when completed, otherwise a 3 px progress line.- It appears in the
VideoPlayermeta overlay (feed and Library player) and onExploreViewcards. It reads from the summary map, with no request per card.
- History page (
HistoryView), per the Stitch design:- Top tab pills: "Lịch sử xem (N)" | "Đề xuất của tôi (N)". "Lịch sử xem" is the default tab. The tab is remembered in
localStorage, wrapped in try/catch. WatchHistorySectioncontains:- a search input (debounced 300 ms);
- a controls row with the "Tạm dừng lịch sử" switch and a "Xoá toàn bộ" button. The switch PATCHes
incognitoEnabledthrough the existing settings hook and invalidates settings. The clear button asks for confirmation through anapp-modal. - When paused, a banner reads "Lịch sử đang tạm dừng".
- Day groups Today / Yesterday / Earlier, computed in local time.
WatchHistoryCard:- thumbnail via
thumbnailUrl(fileId), with a duration or "Đã xem hết" chip - title, view count (
compactNumber) - "Đã xem {relativeTime}"
- a progress bar
- a "⋮" menu with "Xoá khỏi lịch sử"
- thumbnail via
- "Xem thêm" paging.
- Reuse the
hist-*styles and addhist-watch-*classes, with light theme and ≤ 768 px rules.
- Top tab pills: "Lịch sử xem (N)" | "Đề xuất của tôi (N)". "Lịch sử xem" is the default tab. The tab is remembered in
- i18n: add keys under the
historynamespace (vi and en) for the tab, groups, controls, confirm dialog, empty, paused and badge. The Settings incognito description is unchanged.
Tasks¶
Beads is not installed (no .beads/), so this table is the task list.
| ID | Task | Est. | Depends on | Acceptance criteria |
|---|---|---|---|---|
| BE-1 | Migration, WatchHistoryRepository (native upsert, trim, progress, page, summary, deletes), WatchHistoryService and config |
1d | — | Unit tests cover: first watch inserts; re-watch updates watched_at and keeps one row; hidden or unknown video writes 0 rows; incognito writes nothing; the 501st entry evicts the oldest; progress does not insert; progress clamping; completed flag; q escaping of % and _. |
| BE-2 | WatchHistoryController (5 endpoints, rate limits, auth required) and the hook in VideoViewController.record |
0.75d | BE-1 | Controller tests: 401 for guests; owner isolation (user A cannot delete user B's entry, and B's entries never appear for A); size clamp. A view call by a logged-in user records history even when the view is deduped. A history exception still returns 204 for the view. Guests get no history. |
| BE-3 | Account deletion clears history. Update ADR-0021 if anything changes, and the API contract note. | 0.25d | BE-1 | deleteAccount test asserts deleteAll(userId). mvn verify is green and coverage stays ≥ 90 %. |
| FE-1 | api/watchHistory.js, keepalive in client.js, hooks/useWatchHistory.js |
0.5d | BE-2 contract | Hook tests: list paging, q in the key, summary map, remove and clear invalidate. Guests make no calls. |
| FE-2 | VideoPlayer progress reporting and startAt seek; AppShell.playVideo(id, {startAt}) → PublicFeed deep link |
1d | FE-1 | Tests with fake timers: no progress before the view is sent; pause sends progress; switching or unmounting sends it; at most one call per 10 s while playing; guests and incognito send none; startAt seeks once only when > 5 s and not near the end. |
| FE-3 | History page tabs and WatchHistorySection (search, pause switch, clear-all confirm, day groups, cards, remove, paging, empty and paused states), CSS for dark, light and mobile |
1.5d | FE-1, FE-2 | Tests (vi, plus one en render): groups by local day; card shows progress or "Đã xem hết"; clicking a card calls onPlayVideo(id, {startAt}); remove and clear call the API; the pause switch PATCHes incognitoEnabled; search is debounced. Preview checked at 1440 px and 390 px in both themes. |
| FE-4 | WatchedBadge on the feed player overlay and Explore cards |
0.5d | FE-1 | Badge renders from the summary map and makes no request per card. Hidden for guests. |
| QA-1 | Prod smoke after deploy, logged in | 0.5d | all | Watch a video for ≥ 3 s and it appears under Today. Pause mid-video, reopen from History and it resumes. Incognito on records nothing. Remove and clear work. Badge shows in the feed. Endpoints return 401 for guests. |
Dependency Graph¶
BE-1 ──► BE-2 ──► FE-1 ──► FE-2 ──► FE-3 ──► QA-1
│ │ └────► FE-4 ─────────────┘
└──► BE-3 ────────────────────────────────┘
BE-3 and FE-4 can run in parallel with the main chain. FE-1 can start from the contract above before BE-2 is merged.
Risks¶
| Risk | Mitigation |
|---|---|
| Extra write on every logged-in view on a 1 vCPU VM | One upsert plus one bounded delete on an indexed key, in the same transaction. Measure the p95 of the view call in QA-1 (PRD target ≤ +10 ms). |
| Progress heartbeats while many users watch | 30 s interval, a 10 s client throttle, a 120/min server limit, and an UPDATE by primary key only. |
keepalive fetch is dropped on tab close |
Best effort by design. Pause and switch events already save most positions. |
| Resume deep link races with feed loading | startAt is applied on loadedmetadata of the deep-linked player only, once. Covered by FE-2 tests. |
| Incognito toggled while a video plays | The server checks the flag on every write, so the client state does not matter. |
| Search on Vietnamese titles without accents | Documented as OQ-2. Follow-up: unaccent. |
Rollback¶
- Remove the
recordWatchcall fromVideoViewController. The view counting is unchanged. - Hide the History tab.
- Drop the
watch_historytable in a follow-up migration. Nothing else depends on it.
Progress Log¶
| Date | Update |
|---|---|
| 2026-10-15 | Plan created (/swarm-plan history). Scope chosen by the owner: list with day groups, progress and resume, clear-all and pause, search and badges. Recording piggybacks on the view call. New docs supersede the June drafts. |
| 2026-10-15 | /swarm-execute: BE-1..3 and FE-1..4 implemented. mvn verify: 1305 tests, LINE coverage 96.63 %. Vitest: 401 tests; eslint 0 errors; build OK. Previewed at desktop and 390 px in dark and light themes (fixed mobile top padding under the floating header). Native SQL not yet run against a real Postgres (no local DB); covered by QA-1. |
| 2026-10-16 | Pushed and deployed (0a2a365 BE, 4c46791 FE). Liquibase changeset 202610160001-create-watch-history ran on prod; endpoints return 401 for guests. |
| 2026-10-18 | QA-1 passed on prod, logged in (owner): recording, resume, pause history, remove/clear, badges. |