PRD: Admin Video Import (YouTube / Facebook)
Overview
Status: Done
Author: nguyenhuuca
Date: 2026-10-10
Related ADR: ADR-0019 Admin Video Import
Related Plan: plan-admin-video-import
Admin pastes one or many YouTube / Facebook video URLs; the server downloads them with yt-dlp, uploads them into the Google Drive folder that the existing sync cron reads, and the cron brings them into the app. Imports run now or at a scheduled time; progress is visible in the admin page.
Problem Statement
Adding a video today means: download it on a PC, upload it to Google Drive by hand, wait for the cron. For short clips (Reels, Shorts) this is slow and repetitive, and cannot be done from a phone.
Goals & Success Metrics
Goal
Metric
Target
Faster content intake
Admin time per video
< 30 s (paste + submit)
Reliable
Imports ending DONE (valid public URL)
≥ 95 %
Same ingest path
Imported videos visible in app after upload
≤ 15 min (next cron)
User Stories (Admin)
US-1 Paste one URL, optionally a title, press "Tải ngay" → job starts immediately.
US-2 Paste many URLs (one per line, optional URL | Tiêu đề) → one job per line (bulk, max 20).
US-3 Choose "Hẹn giờ" and a date/time (Asia/Ho_Chi_Minh) → jobs start at that time.
US-4 See each job's status, phase (đang tải / đang upload) and percent, updating automatically.
US-5 Title auto-filled from the source when possible ("Lấy tiêu đề"); I can override it.
US-6 Cancel a pending/running job; retry a failed one; run a scheduled job now.
US-7 See whether a finished job is already in the app ("Đã lên app") or waiting for sync ("Chờ đồng bộ").
Functional Requirements
ID
Requirement
Priority
FR-1
Admin tab Import Video in AdminView (admin only)
Must
FR-2
Submit 1–20 URLs; per-line optional title; invalid lines reported per line, valid ones still created
Must
FR-3
Allowed sources: YouTube (youtube.com, youtu.be, Shorts) and Facebook (facebook.com video/reel/watch, fb.watch); https only
Must
FR-4
Run now or schedule (scheduledAt in the future, ≤ 30 days)
Must
FR-5
Download max 720p mp4, max 1 GB; upload to Drive folder as {title}.mp4
Must
FR-6
Title: admin > source metadata > {platform}-{id}; sanitized, ≤ 120 chars
Must
FR-7
Progress polling every 2 s while active jobs exist; status, phase, %, size, error
Must
FR-8
Cancel / retry / run-now actions
Must
FR-9
Duplicate active URL rejected (DUPLICATE_ACTIVE)
Should
FR-10
"Đã lên app" indicator (video_sources has the Drive file id)
Should
FR-11
Jobs survive restarts; interrupted jobs retried up to 3 attempts
Must
Non-Functional
ID
Requirement
NFR-1
One import at a time (configurable); streaming must stay responsive
NFR-2
No shell execution; URL allowlist; yt-dlp --ignore-config, --use-extractors youtube,facebook, -- before URL
NFR-3
Timeouts: metadata 60 s, download 30 min; disk guard ≥ 2 GB free
NFR-4
Errors shown as codes + short Vietnamese message, never raw process output
NFR-5
All endpoints ADMIN only, @AuditLog; create endpoint rate-limited
Scope
In: YouTube + Facebook, single/bulk, now/scheduled, polling progress, cancel/retry, title auto/manual.
Out: TikTok/Instagram/other sites, recurring schedules, playlists/channels, choosing quality, editing/trimming, direct ingest without the cron (ADR-0019 D1).
Risks
Risk
Mitigation
Service Account cannot upload to personal Drive (storageQuotaExceeded)
Phase 0 PoC; OAuth refresh-token uploader fallback (ADR-0019 D2)
yt-dlp broken by site changes
Daily yt-dlp -U on host; clear EXTRACTOR_ERROR; retry
Facebook login-only videos
Optional cookies file; otherwise FAILED (LOGIN_REQUIRED)
Copyright / ToS
Owner imports only content they have rights to
Open Questions
#
Question
Proposed
OQ-1
Bulk max per submit
Decided: 20 (owner, 2026-10-10)
OQ-2
Delete local temp file after upload?
Yes (cron re-downloads; D1)
OQ-3
Keep job history how long?
Decided: forever — no purge (owner, 2026-10-10)
Approval
Role
Name
Date
Status
Product
nguyenhuuca
Pending
Engineering
nguyenhuuca
Pending (ADR-0019 proposed)
Version History
Version
Date
Change
0.1
2026-10-10
Initial draft
0.2
2026-10-10
OQ-1 = 20, OQ-3 = keep history forever