Plan: Video Suggestions (the "+" button)¶
Overview¶
Status: Approved (2026-10-15). Defaults are accepted: 5 per day, approval starts the download immediately, and the suggester is shown as a masked email. Author: nguyenhuuca Date: 2026-10-15 Related PRD: PRD-video-suggestions Builds on: ADR-0019 (import), ADR-0017 (notifications), ADR-0020 (i18n)
No new ADR is needed: the change is additive (a new table, new notification types, one post-save event) and easy to reverse.
Technical Approach¶
Data: one migration, 202610150002-create-video-suggestions.sql¶
CREATE TABLE video_suggestions (
id BIGSERIAL PRIMARY KEY,
user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
source_url TEXT NOT NULL,
normalized_url TEXT NOT NULL,
platform VARCHAR(16) NOT NULL, -- YOUTUBE | FACEBOOK (same enum as import)
title VARCHAR(200),
note VARCHAR(300),
status VARCHAR(16) NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING','APPROVED','REJECTED')),
reject_reason VARCHAR(32),
reject_note VARCHAR(300),
reviewed_by BIGINT REFERENCES users(id) ON DELETE SET NULL,
reviewed_at TIMESTAMPTZ,
import_job_id BIGINT REFERENCES video_import_jobs(id) ON DELETE SET NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE UNIQUE INDEX uq_video_suggestions_pending_url ON video_suggestions(normalized_url) WHERE status = 'PENDING';
CREATE INDEX idx_video_suggestions_status ON video_suggestions(status, created_at DESC);
CREATE INDEX idx_video_suggestions_user ON video_suggestions(user_id, created_at DESC);
CREATE INDEX idx_video_suggestions_job ON video_suggestions(import_job_id) WHERE import_job_id IS NOT NULL;
Backend¶
- Model:
entity/VideoSuggestion,enums/SuggestionStatusandenums/SuggestionRejectReason(DUPLICATE, INAPPROPRIATE, LOW_QUALITY, COPYRIGHT, OTHER), plusrepo/VideoSuggestionRepository. -
service/VideoSuggestionServiceand its impl.User-facing:
submit(url, title, note)- Parse the URL with
ImportUrlValidator.parse(shared allowlist and normalization). - Enforce the daily limit:
countByUserIdAndCreatedAtAfter(now − 24h) ≥ app.video-suggestion.daily-limit(default 5) gives 429error.suggestion.dailyLimit. - Reject duplicates with 409
error.suggestion.duplicatewhen either:- a suggestion for the same
normalizedUrlis pending, or - an import job for that URL exists with status in ACTIVE ∪ {DONE}.
- a suggestion for the same
- Save. The partial unique index is authoritative:
DataIntegrityViolationExceptionalso maps to 409.
- Parse the URL with
mine(status, page, size)returns the user's own suggestions, newest first, with an optional status filter and a size clamped to 50. Each hasliveVideoIdwhen its job'sdrive_file_idexists invideo_sources. The modal uses page 0 with size 5, and History uses pages of 20.
Admin:
list(status, page)lists suggestions, pending first.approve(id, titleOverride)- Require import to be enabled, otherwise 503
error.import.disabled. - Lock the suggestion row and require PENDING, otherwise 409.
- Call
VideoImportService.create(single item, scheduledAt = now, adminId). If that line result is an error (for example a duplicate active job), return 409 with the import's code. - Set APPROVED,
import_job_id,reviewed_*. - Publish
SuggestionReviewedEvent.
- Require import to be enabled, otherwise 503
reject(id, reason, note)requires a note when the reason is OTHER, sets REJECTED, and publishesSuggestionReviewedEvent.- Controllers:
VideoSuggestionController/suggestions, authenticated:POSTwith@RateLimited(permit=10)and@AuditLog.GET /mine?status&page&sizewith@RateLimited(60).
AdminVideoSuggestionController/admin/video-suggestions, with@HasPermission(ADMIN)like the import controller:GET ?status&pagePOST /{id}/approvePOST /{id}/rejectGET /pending-countfor the tab badge.
- "Live" hook:
VideoStorageServiceImpl.saveInfo, after save, publishesVideoIngestedEvent(driveFileId, videoSourceId, videoId).SuggestionLiveListener(AFTER_COMMIT+@Async, like the notification listeners) does the following:- Finds the import job by
drive_file_id. - Finds the suggestion by
import_job_id. - Notifies
SUGGESTION_LIVEwithvideoId.
- Finds the import job by
- A new video is PUBLISHED and visible by default, so "live" is accurate.
- Notifications:
NotificationTypegainsSUGGESTION_APPROVED,SUGGESTION_REJECTEDandSUGGESTION_LIVE. The type column is VARCHAR(30) with no CHECK, so no migration is needed.- The group key is
suggestion:<id>:<type>, so they never collapse with each other. - The payload holds
{ title, reason }. - The digest gets new
mail.digest.item.suggestion*keys in both properties files. - i18n: new
error.suggestion.*keys in both properties files; the parity test keeps them in sync. - Config:
app.video-suggestion.daily-limit: ${VIDEO_SUGGESTION_DAILY_LIMIT:5}.
Frontend¶
api/suggestions.jsandhooks/useSuggestions.js:useSubmitSuggestionanduseMySuggestions.- Admin:
useAdminSuggestions(status, page),useApproveSuggestion,useRejectSuggestionanduseSuggestionPendingCount.
components/suggestions/SuggestVideoModal.jsx(namespacesuggestions):- Fields: URL, title, note. Client-side check that the URL is HTTPS YouTube or Facebook.
- Errors map from
err.code. - A "Đề xuất gần đây" list shows the latest 5 with status chips. A live item has a "Xem" button that opens
?v=. A "Xem tất cả" link opens History. - Uses
aria-busyon submit.
- AppShell:
- The FAB and the mobile FAB open
SuggestVideoModalfor users. For admins they navigate to Admin withinitialTab='IMPORT_VIDEO'. - Remove the header upload icon and
ShareModal. - Rename
shareAVideotosuggestVideo.
- The FAB and the mobile FAB open
- Admin:
- New
SUGGESTIONStab inAdminView, with a pending-count badge. AdminSuggestionTable.jsx: link (opens in a new tab), title, note, suggester, time, status. Approve uses a title override and a ConfirmModal. Reject uses a reason select and a note, reusing the pattern of the commentRemoveModal.
- New
- History page:
components/history/HistoryView.jsxreplaces theComingSoonplaceholder for thehistorynav item. It is built so watch history (plan-watch-history-opus) can become another section later.- Section "Đề xuất của tôi" / "My suggestions" (
MySuggestionsSection.jsx, namespacehistory) shows the full list with status filter tabs (Tất cả / Chờ duyệt / Đã duyệt / Bị từ chối / Đã lên app) and paging with "Xem thêm". - Each row shows the link, title, note, date, status chip and reject reason. A live row has a "Xem" button.
- Logged out, it shows a sign-in hint.
- Section "Đề xuất của tôi" / "My suggestions" (
- Notifications:
notificationText.jsadds the three types. ClickingSUGGESTION_LIVEplays the video (?v=); the other two open History → My suggestions. - Clean up:
- Delete
components/modals/ShareModal.jsxandvideosApi.share/delete. - Remove the share keys from
shell.json. - Update
webapp/CLAUDE.md.
- Delete
Tasks¶
| ID | Task | Est. | Depends on | Acceptance criteria |
|---|---|---|---|---|
| BE-1 | Migration, entity, enums, repository, VideoSuggestionService (submit, mine, list, approve, reject) and config |
1.5d | — | Unit tests cover: • invalid URL 400 • duplicate pending 409 • duplicate import 409 • 6th suggestion in 24 h 429 • approve creates exactly one import job and links it • double approve 409 • approve with import disabled 503 • reject OTHER without a note 400 • mine shows liveVideoId once ingested |
| BE-2 | Controllers (user and admin), permissions, rate limits and WebMvc tests | 0.5d | BE-1 | Guests get 401. A non-admin calling an admin endpoint gets 403. vi and en messages carry code. Coverage ≥ 90%. |
| BE-3 | Notifications: three types, SuggestionReviewedEvent, VideoIngestedEvent from saveInfo, SuggestionLiveListener, and digest text in vi and en |
1d | BE-1 | Approve and reject each create one notification for the suggester. Ingesting the Drive file of an approved suggestion's job creates SUGGESTION_LIVE with videoId. An ingest with no matching suggestion does nothing. The digest renders the three types in both languages. |
| FE-1 | SuggestVideoModal, API and hooks, AppShell FAB rewiring (users get the modal, admins get Admin → Import), removal of ShareModal, videosApi.share/delete and the header upload icon |
1d | BE-2 contract | Submitting shows the item as "Chờ duyệt" in the recent list. Duplicate and limit errors are translated. An admin's FAB opens the Import tab. There are no ShareModal references left. Tests run in vi with en render tests. |
| FE-2 | Admin SUGGESTIONS tab: table, filter, approve (title override), reject (reason and note), pending badge |
1d | BE-2 contract | Approve moves the row to "Đã duyệt" and a job appears in the Import tab. Reject requires a reason, and a note for OTHER. The badge count updates. Tests pass. |
| FE-3 | Notification rendering for the three types and their click behaviour | 0.5d | FE-1, BE-3, FE-4 | Titles are translated in vi and en. LIVE opens the video. APPROVED and REJECTED open History → My suggestions, where REJECTED shows the reason. |
| FE-4 | History page (HistoryView) replaces ComingSoon, with a "My suggestions" section: status filter, paging, live "Xem", reject reason, logged-out hint |
0.5d | BE-2 contract | The History nav shows the user's suggestions with working filters and paging. A live item plays its video. A guest sees the sign-in hint. Tests run in vi with an en render test. |
| QA-1 | Local end-to-end and prod smoke | 0.5d | all | A user suggests a link and an admin approves it. The job runs, the cron ingests the video, the user gets three notifications (approved, live, plus the digest email), and the video plays from the LIVE notification. A 6th suggestion in a day is blocked. A reject shows its reason. |
The total is about 6.5 days, which makes this a Medium feature (PRD and plan).
Dependency Graph¶
Once BE-2 has fixed the API contract, FE-1, FE-2 and FE-4 run in parallel, alongside BE-3.
Beads¶
bd is not installed in this repo, so tasks are tracked in this table and in docs/tracking.md. When bd is available:
bd create --title="Video suggestions (+ button)" --type=feature --priority=2
bd create --title="[BE-1] video_suggestions table + service" --type=task
bd create --title="[BE-2] Suggestion controllers + permissions" --type=task
bd create --title="[BE-3] Suggestion notifications + ingest hook" --type=task
bd create --title="[FE-1] SuggestVideoModal + FAB rewiring, remove ShareModal" --type=task
bd create --title="[FE-2] Admin suggestions tab" --type=task
bd create --title="[FE-3] Suggestion notifications UI" --type=task
bd create --title="[FE-4] History page + My suggestions" --type=task
bd create --title="[QA-1] E2E + prod smoke" --type=task
# deps: BE-2←BE-1, BE-3←BE-1, FE-1←BE-2, FE-2←BE-2, FE-4←BE-2, FE-3←FE-1+FE-4+BE-3, QA-1←all
Risks¶
| Risk | Mitigation |
|---|---|
VIDEO_IMPORT_ENABLED is false on prod, so approvals fail |
Approve returns a clear 503, and submissions still queue. Enabling import is an owner decision, and its default stays false. |
| Spam, or links to inappropriate content | Login is required, the daily limit is 5, admins approve every suggestion, and the reject reasons are logged with @AuditLog. |
| The "live" event is missed (async after commit, JVM restart) | mine() also computes liveVideoId from the DB, so the status stays correct even if a notification is lost. |
| Concurrent approve of the same suggestion | Row lock plus a PENDING check. The import's partial unique index blocks duplicate active jobs. |
| The extra event changes the cron ingest | It is publish-only. The listener runs after commit and asynchronously, so ingest latency and failure modes stay the same. |
Rollback¶
- FE: revert. The FAB falls back to the previous behaviour, and the deleted ShareModal comes back with the revert.
- BE: the endpoints and the event are additive. The table can stay, or be dropped with
DROP TABLE video_suggestions. The notification types are only enum values.
Progress Log¶
| Date | Note |
|---|---|
| 2026-10-15 | Owner asked for a "My suggestions" section in History, so FE-4 was added. The history nav item becomes a real page instead of the ComingSoon placeholder. |
| 2026-10-15 | Plan created from a parallel exploration of the import pipeline, the notifications system and the FE "+" and admin UI. |
| 2026-10-15 | BE-1..3 and FE-1..4 were implemented with 3 parallel workers. BE: 1220 tests, coverage 96.49%. FE: 345 tests. The listener is named SuggestionNotificationListener, and the ingest event uses fallbackExecution because saveInfo has no outer transaction. videosApi.delete is kept because DeleteConfirmModal still uses it (legacy share_link); remove it together with share_link. The queries were parsed by Hibernate but have not run on a real Postgres, so QA-1 on prod is the first DB check. |