feat: prefer short videos by watched tags

Recommend shorts from the least-populated tag after a user watches a video long enough, while preserving random fallback behavior.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,135 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Common Commands
+
+### Full Local Development
+
+```bash
+npm install
+./start.sh
+```
+
+`./start.sh` starts the Go backend on `127.0.0.1:9192` and the frontend on `0.0.0.0:9191`. By default it builds the frontend and runs Vite preview mode. Use hot reload with:
+
+```bash
+FRONTEND_MODE=dev ./start.sh --restart
+```
+
+Useful variants:
+
+```bash
+./start.sh --status
+./start.sh --restart
+./start.sh --stop
+```
+
+### Frontend
+
+Run from the repository root:
+
+```bash
+npm run dev        # Vite dev server; default port comes from Vite unless overridden
+npm run dev:raw    # Vite dev server on 127.0.0.1:5173
+npm run build      # tsc -b && vite build
+npm run preview    # Vite preview; vite.config.ts uses port 9191
+npm run lint       # TypeScript no-emit check
+npm test           # node --import tsx --test tests/*.test.ts
+```
+
+Run one frontend test:
+
+```bash
+node --import tsx --test tests/previewIntent.test.ts
+```
+
+### Backend
+
+Run from `backend/` unless noted:
+
+```bash
+go run ./cmd/server
+go test ./... -count=1
+go build -o video-server ./cmd/server
+```
+
+Run one backend package or test:
+
+```bash
+go test ./internal/scanner -count=1
+go test ./internal/scanner -run TestParse -count=1
+```
+
+The backend requires Go 1.23+ and uses vendored dependencies in `backend/vendor/`, so keep `go mod vendor` in sync after dependency changes.
+
+### Release and Deployment
+
+```bash
+scripts/build-release.sh   # builds Linux amd64/arm64 release tarballs into release/
+sudo bash install.sh       # prebuilt installer flow used by README
+sudo bash deploy.sh        # build from current checkout and install systemd services
+```
+
+Docker uses the root `Dockerfile` and `docker-compose.yml`. The runtime image exposes port `9191` and stores persistent data under `/opt/video-site-91/data`.
+
+## Architecture Overview
+
+This is a private video aggregation site with a React/Vite frontend and a Go backend.
+
+### Frontend
+
+The frontend is a React 18 SPA under `src/`. `src/main.tsx` mounts `BrowserRouter`, `ToastProvider`, and `AuthProvider`, then renders `src/App.tsx`. `App.tsx` defines the public app routes (`/`, `/list`, `/shorts`, `/upload`, `/video/:id`) and admin routes under `/admin`; both main-site and admin pages are wrapped in `RequireAuth`, while `/login` is public.
+
+Frontend API calls are split by surface:
+
+- `src/data/videos.ts` calls the main authenticated API under `/api` and upload/proxy-related endpoints.
+- `src/admin/api.ts` is the admin API client for `/admin/api`, always sending cookies and raising `UnauthorizedError` on `401`.
+
+`vite.config.ts` proxies `/api`, `/p`, and `/admin/api` to `http://127.0.0.1:9192`, with frontend dev/preview served on port `9191` by default. The alias `@` maps to `src`.
+
+Styling is plain CSS loaded from `src/main.tsx` in token/base/layout/navigation/search/video/admin layers. Shared UI lives in `src/components`, page-level screens in `src/pages`, and admin screens in `src/admin`.
+
+### Backend
+
+The backend entrypoint is `backend/cmd/server/main.go`. It loads `config.yaml` or `VIDEO_CONFIG`, creates the SQLite catalog and preview directories, builds the app state, registers API routes, starts the nightly runner, and then asynchronously attaches configured external drives so slow upstream login checks do not block port binding.
+
+Important backend packages:
+
+- `internal/config`: YAML config loading and first-run admin credential setup.
+- `internal/catalog`: SQLite catalog, schema migration, video metadata, settings, tags, drive records, generation status, and deduplication state. It opens SQLite with WAL and a busy timeout.
+- `internal/drives`: provider abstraction. Implementations include `quark`, `p115`, `pikpak`, `wopan`, `onedrive`, `localstorage`, `localupload`, and `spider91`.
+- `internal/scanner`: recursively lists drive directories, parses filenames/tags, upserts catalog videos, applies skip-directory rules, and enqueues newly discovered videos.
+- `internal/preview`: ffprobe/ffmpeg thumbnail and teaser generation workers. Generated assets are local files under the configured preview directory.
+- `internal/fingerprint`: asynchronous sampled SHA-256 worker used for cross-drive duplicate detection.
+- `internal/proxy`: `/p/*` media serving. Some providers redirect with `302` to signed CDN URLs, while providers requiring backend-held headers are reverse-proxied with Range support.
+- `internal/api`: main API and admin API route handlers.
+- `internal/nightly`: daily pipeline for drive scans, spider91 crawl, migration, queue drain, and duplicate asset cleanup.
+- `internal/spider91migrate`: migration from spider91 downloads to a configured cloud drive.
+
+### Runtime Flow
+
+1. Admin adds or edits drives through `/admin/drives`, which persists drive config in the catalog.
+2. The server attaches the drive implementation into the proxy registry and can trigger scans.
+3. Scans convert provider files into catalog video rows, parse titles/authors/tags from filenames, and queue preview/fingerprint work.
+4. The frontend lists videos through `/api/home`, `/api/list`, `/api/video/:id`, and streams media through `/p/*` endpoints.
+5. The nightly runner performs the scheduled end-to-end maintenance pipeline; admins can trigger it manually through `/admin/api/jobs/nightly/run`.
+
+### Configuration and Data
+
+Backend defaults come from `backend/config.example.yaml`. On first backend start, `config.yaml` is created automatically if missing. Default local development paths are:
+
+- Backend listen address: `127.0.0.1:9192`
+- SQLite DB: `backend/data/video-site.db`
+- Generated previews/thumbs: `backend/data/previews`
+
+Docker and installer deployments rewrite config paths so data lives under `/opt/video-site-91/data` or the mounted `./data` directory.
+
+`VIDEO_FRONTEND_DIR` controls where the Go server looks for built frontend assets. If unset, it serves `./dist` when present. Backend routes (`/api`, `/admin/api`, `/p`) are excluded from the SPA fallback.
+
+## Notes for Changes
+
+- Main-site API routes and proxy routes require authentication; only login/setup and `/api/settings/theme` are intentionally public.
+- When adding a new drive provider, implement `internal/drives.Drive`, persist any needed config through catalog/admin APIs, attach it in `cmd/server`, and decide whether `/p/stream` should redirect or reverse-proxy in `internal/proxy`.
+- Generated thumbnails and teasers are local runtime assets; do not treat them as source files.
+- Frontend tests use Node's built-in test runner with `tsx`; TypeScript linting only checks `src` through the root `tsconfig.json`.

backend/internal/api/api.go

@@ -443,8 +443,9 @@ func (s *Server) handleTags(w http.ResponseWriter, r *http.Request) {
 // shortsNextReq 客户端把当前轮已看过的 video id 列表传上来，
 // 服务器从未在列表中的视频里随机抽 count 个返回。
 type shortsNextReq struct {
-	SeenIDs []string `json:"seenIds"`
-	Count   int      `json:"count"`
+	SeenIDs              []string `json:"seenIds"`
+	Count                int      `json:"count"`
+	PreferredFromVideoID string   `json:"preferredFromVideoId"`
 }
 
 // ShortsItemDTO 是短视频流单条的精简结构。比 VideoDTO 多 videoSrc / poster，
@@ -490,7 +491,12 @@ func (s *Server) handleShortsNext(w http.ResponseWriter, r *http.Request) {
 		exclude = nil
 	}
 
-	items, err := s.Catalog.RandomVideosExcluding(r.Context(), exclude, count)
+	var items []*catalog.Video
+	if strings.TrimSpace(body.PreferredFromVideoID) != "" {
+		items, err = s.Catalog.RandomVideosForPreferredVideoExcluding(r.Context(), body.PreferredFromVideoID, exclude, count)
+	} else {
+		items, err = s.Catalog.RandomVideosExcluding(r.Context(), exclude, count)
+	}
 	if err != nil {
 		writeErr(w, http.StatusInternalServerError, err)
 		return

backend/internal/api/api_test.go

@@ -523,6 +523,66 @@ func TestHandleTagsReturnsUnifiedTagPool(t *testing.T) {
 	}
 }
 
+func TestHandleShortsNextUsesPreferredVideoLeastPopulatedTag(t *testing.T) {
+	ctx := context.Background()
+	cat, err := catalog.Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cat.Close(); err != nil {
+			t.Fatalf("close catalog: %v", err)
+		}
+	})
+
+	now := time.Now()
+	for _, v := range []*catalog.Video{
+		{ID: "current", DriveID: "drive", FileID: "f-current", Title: "current", Tags: []string{"common", "rare"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "common-1", DriveID: "drive", FileID: "f-common-1", Title: "common 1", Tags: []string{"common"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "common-2", DriveID: "drive", FileID: "f-common-2", Title: "common 2", Tags: []string{"common"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "rare-1", DriveID: "drive", FileID: "f-rare-1", Title: "rare 1", Tags: []string{"rare"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+	} {
+		if err := cat.UpsertVideo(ctx, v); err != nil {
+			t.Fatalf("seed %s: %v", v.ID, err)
+		}
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/shorts/next", strings.NewReader(`{"seenIds":["current"],"count":3,"preferredFromVideoId":"current"}`))
+	rr := httptest.NewRecorder()
+	(&Server{Catalog: cat}).handleShortsNext(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rr.Code, rr.Body.String())
+	}
+	var got struct {
+		Items         []ShortsItemDTO `json:"items"`
+		Total         int             `json:"total"`
+		RoundComplete bool            `json:"roundComplete"`
+	}
+	if err := json.NewDecoder(rr.Body).Decode(&got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	ids := make([]string, 0, len(got.Items))
+	for _, item := range got.Items {
+		ids = append(ids, item.ID)
+	}
+	if got.Total != 4 {
+		t.Fatalf("total = %d, want 4", got.Total)
+	}
+	if got.RoundComplete {
+		t.Fatalf("roundComplete = true, want false with fallback-filled batch")
+	}
+	if !containsString(ids, "rare-1") {
+		t.Fatalf("ids = %#v, want rare-1 from least populated tag", ids)
+	}
+	if containsString(ids, "current") {
+		t.Fatalf("ids = %#v, should exclude current", ids)
+	}
+	if len(ids) != 3 {
+		t.Fatalf("ids = %#v, want 3 items", ids)
+	}
+}
+
 func TestHandleUpdateVideoTagsRejectsUnknownTags(t *testing.T) {
 	ctx := context.Background()
 	cat, err := catalog.Open(t.TempDir() + "/catalog.db")

backend/internal/catalog/catalog.go

@@ -869,21 +869,7 @@ func (c *Catalog) RandomVideosExcluding(ctx context.Context, excludeIDs []string
 		return nil, nil
 	}
 
-	// 去重 excludeIDs，过滤空串
-	seen := make(map[string]struct{}, len(excludeIDs))
-	cleaned := make([]string, 0, len(excludeIDs))
-	for _, id := range excludeIDs {
-		id = strings.TrimSpace(id)
-		if id == "" {
-			continue
-		}
-		if _, ok := seen[id]; ok {
-			continue
-		}
-		seen[id] = struct{}{}
-		cleaned = append(cleaned, id)
-	}
-
+	cleaned := cleanVideoIDs(excludeIDs)
 	args := make([]any, 0, len(cleaned)+1)
 	whereSQL := `WHERE COALESCE(hidden, 0) = 0
 		           AND ` + uniqueVideoWhereSQL
@@ -921,6 +907,175 @@ func (c *Catalog) RandomVideosExcluding(ctx context.Context, excludeIDs []string
 	return out, nil
 }
 
+func cleanVideoIDs(ids []string) []string {
+	seen := make(map[string]struct{}, len(ids))
+	cleaned := make([]string, 0, len(ids))
+	for _, id := range ids {
+		id = strings.TrimSpace(id)
+		if id == "" {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		cleaned = append(cleaned, id)
+	}
+	return cleaned
+}
+
+func cleanTagLabels(labels []string) []string {
+	seen := make(map[string]struct{}, len(labels))
+	cleaned := make([]string, 0, len(labels))
+	for _, label := range labels {
+		label = strings.TrimSpace(label)
+		if label == "" {
+			continue
+		}
+		key := strings.ToLower(label)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		cleaned = append(cleaned, label)
+	}
+	return cleaned
+}
+
+func (c *Catalog) LeastPopulatedVisibleUniqueTag(ctx context.Context, labels []string) (string, error) {
+	cleaned := cleanTagLabels(labels)
+	bestLabel := ""
+	bestCount := 0
+	for _, label := range cleaned {
+		var count int
+		if err := c.db.QueryRowContext(ctx,
+			`SELECT COUNT(*)
+			   FROM videos
+			  WHERE COALESCE(hidden, 0) = 0
+			    AND `+uniqueVideoWhereSQL+`
+			    AND EXISTS (
+			      SELECT 1
+			        FROM video_tags vt
+			        JOIN tags t ON t.id = vt.tag_id
+			       WHERE vt.video_id = videos.id
+			         AND t.label = ? COLLATE NOCASE
+			    )`,
+			label,
+		).Scan(&count); err != nil {
+			return "", err
+		}
+		if count == 0 {
+			continue
+		}
+		if bestLabel == "" || count < bestCount {
+			bestLabel = label
+			bestCount = count
+		}
+	}
+	return bestLabel, nil
+}
+
+func (c *Catalog) RandomVideosByTagExcluding(ctx context.Context, tag string, excludeIDs []string, limit int) ([]*Video, error) {
+	if limit <= 0 {
+		return nil, nil
+	}
+	tag = strings.TrimSpace(tag)
+	if tag == "" {
+		return nil, nil
+	}
+
+	cleaned := cleanVideoIDs(excludeIDs)
+	args := make([]any, 0, len(cleaned)+2)
+	args = append(args, tag)
+	whereSQL := `WHERE COALESCE(hidden, 0) = 0
+		           AND ` + uniqueVideoWhereSQL + `
+		           AND EXISTS (
+		             SELECT 1
+		               FROM video_tags vt
+		               JOIN tags t ON t.id = vt.tag_id
+		              WHERE vt.video_id = videos.id
+		                AND t.label = ? COLLATE NOCASE
+		           )`
+	if len(cleaned) > 0 {
+		placeholders := strings.Repeat("?,", len(cleaned))
+		placeholders = placeholders[:len(placeholders)-1]
+		whereSQL += " AND id NOT IN (" + placeholders + ")"
+		for _, id := range cleaned {
+			args = append(args, id)
+		}
+	}
+	args = append(args, limit)
+
+	rows, err := c.db.QueryContext(ctx,
+		`SELECT `+allVideoCols+` FROM videos `+whereSQL+`
+		 ORDER BY RANDOM() LIMIT ?`,
+		args...,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var out []*Video
+	for rows.Next() {
+		v, err := scanVideo(rows)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, v)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *Catalog) RandomVideosForPreferredVideoExcluding(ctx context.Context, preferredVideoID string, excludeIDs []string, limit int) ([]*Video, error) {
+	if limit <= 0 {
+		return nil, nil
+	}
+	preferredVideoID = strings.TrimSpace(preferredVideoID)
+	if preferredVideoID == "" {
+		return c.RandomVideosExcluding(ctx, excludeIDs, limit)
+	}
+
+	preferredExclude := append([]string{}, excludeIDs...)
+	preferredExclude = append(preferredExclude, preferredVideoID)
+
+	preferred, err := c.GetVideo(ctx, preferredVideoID)
+	if err != nil || preferred == nil || preferred.Hidden || len(preferred.Tags) == 0 {
+		return c.RandomVideosExcluding(ctx, preferredExclude, limit)
+	}
+	tag, err := c.LeastPopulatedVisibleUniqueTag(ctx, preferred.Tags)
+	if err != nil {
+		return nil, err
+	}
+	if tag == "" {
+		return c.RandomVideosExcluding(ctx, preferredExclude, limit)
+	}
+
+	items, err := c.RandomVideosByTagExcluding(ctx, tag, preferredExclude, limit)
+	if err != nil {
+		return nil, err
+	}
+	if len(items) >= limit {
+		return items, nil
+	}
+
+	mergedExclude := make([]string, 0, len(preferredExclude)+len(items))
+	mergedExclude = append(mergedExclude, preferredExclude...)
+	for _, item := range items {
+		if item != nil {
+			mergedExclude = append(mergedExclude, item.ID)
+		}
+	}
+	fallback, err := c.RandomVideosExcluding(ctx, mergedExclude, limit-len(items))
+	if err != nil {
+		return nil, err
+	}
+	return append(items, fallback...), nil
+}
+
 type DriveTeaserCounts struct {
 	Ready   int
 	Pending int

backend/internal/catalog/shorts_test.go

@@ -109,3 +109,171 @@ func TestRandomVideosExcluding(t *testing.T) {
 		t.Fatalf("limit 0 should return nil, got %v", got4)
 	}
 }
+
+func TestRandomVideosForPreferredVideoChoosesLeastPopulatedTag(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() { _ = cat.Close() })
+
+	now := time.Now()
+	for _, v := range []*Video{
+		{ID: "current", DriveID: "drive", FileID: "f-current", Title: "current", Tags: []string{"common", "rare"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "common-1", DriveID: "drive", FileID: "f-common-1", Title: "common 1", Tags: []string{"common"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "common-2", DriveID: "drive", FileID: "f-common-2", Title: "common 2", Tags: []string{"common"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "rare-1", DriveID: "drive", FileID: "f-rare-1", Title: "rare 1", Tags: []string{"rare"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+	} {
+		if err := cat.UpsertVideo(ctx, v); err != nil {
+			t.Fatalf("seed %s: %v", v.ID, err)
+		}
+	}
+
+	tag, err := cat.LeastPopulatedVisibleUniqueTag(ctx, []string{"common", "rare"})
+	if err != nil {
+		t.Fatalf("least populated tag: %v", err)
+	}
+	if tag != "rare" {
+		t.Fatalf("least populated tag = %q, want rare", tag)
+	}
+
+	got, err := cat.RandomVideosForPreferredVideoExcluding(ctx, "current", []string{"current"}, 1)
+	if err != nil {
+		t.Fatalf("random preferred: %v", err)
+	}
+	if len(got) != 1 || got[0].ID != "rare-1" {
+		t.Fatalf("preferred result = %#v, want rare-1", videoIDs(got))
+	}
+
+	got, err = cat.RandomVideosForPreferredVideoExcluding(ctx, "current", nil, 1)
+	if err != nil {
+		t.Fatalf("random preferred without explicit exclude: %v", err)
+	}
+	if len(got) != 1 || got[0].ID == "current" {
+		t.Fatalf("preferred result without explicit exclude = %#v, should not return current", videoIDs(got))
+	}
+}
+
+func TestRandomVideosForPreferredVideoFallsBackToFillBatch(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() { _ = cat.Close() })
+
+	now := time.Now()
+	for _, v := range []*Video{
+		{ID: "current", DriveID: "drive", FileID: "f-current", Title: "current", Tags: []string{"common", "rare"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "common-1", DriveID: "drive", FileID: "f-common-1", Title: "common 1", Tags: []string{"common"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "common-2", DriveID: "drive", FileID: "f-common-2", Title: "common 2", Tags: []string{"common"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "rare-1", DriveID: "drive", FileID: "f-rare-1", Title: "rare 1", Tags: []string{"rare"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "hidden-rare", DriveID: "drive", FileID: "f-hidden-rare", Title: "hidden rare", Tags: []string{"rare"}, PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+	} {
+		if err := cat.UpsertVideo(ctx, v); err != nil {
+			t.Fatalf("seed %s: %v", v.ID, err)
+		}
+	}
+	if err := cat.HideVideo(ctx, "hidden-rare"); err != nil {
+		t.Fatalf("hide hidden-rare: %v", err)
+	}
+
+	got, err := cat.RandomVideosForPreferredVideoExcluding(ctx, "current", []string{"current"}, 3)
+	if err != nil {
+		t.Fatalf("random preferred: %v", err)
+	}
+	ids := videoIDs(got)
+	if len(ids) != 3 {
+		t.Fatalf("result ids = %#v, want 3 items", ids)
+	}
+	for _, excluded := range []string{"current", "hidden-rare"} {
+		if hasVideoID(ids, excluded) {
+			t.Fatalf("result ids = %#v, should not include %s", ids, excluded)
+		}
+	}
+	if !hasVideoID(ids, "rare-1") {
+		t.Fatalf("result ids = %#v, want rare-1 from least populated tag", ids)
+	}
+	if len(uniqueVideoIDs(ids)) != len(ids) {
+		t.Fatalf("result ids = %#v, want no duplicates", ids)
+	}
+}
+
+func TestRandomVideosForPreferredVideoFallbacksWhenPreferenceUnavailable(t *testing.T) {
+	ctx := context.Background()
+	cat, err := Open(t.TempDir() + "/catalog.db")
+	if err != nil {
+		t.Fatalf("open catalog: %v", err)
+	}
+	t.Cleanup(func() { _ = cat.Close() })
+
+	now := time.Now()
+	for _, v := range []*Video{
+		{ID: "untagged", DriveID: "drive", FileID: "f-untagged", Title: "untagged", PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "visible-1", DriveID: "drive", FileID: "f-visible-1", Title: "visible 1", PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+		{ID: "visible-2", DriveID: "drive", FileID: "f-visible-2", Title: "visible 2", PublishedAt: now, CreatedAt: now, UpdatedAt: now},
+	} {
+		if err := cat.UpsertVideo(ctx, v); err != nil {
+			t.Fatalf("seed %s: %v", v.ID, err)
+		}
+	}
+
+	got, err := cat.RandomVideosForPreferredVideoExcluding(ctx, "missing", []string{"untagged"}, 2)
+	if err != nil {
+		t.Fatalf("random missing preferred: %v", err)
+	}
+	if !sameVideoIDSet(videoIDs(got), []string{"visible-1", "visible-2"}) {
+		t.Fatalf("missing preferred ids = %#v, want visible fallback videos", videoIDs(got))
+	}
+
+	got, err = cat.RandomVideosForPreferredVideoExcluding(ctx, "untagged", []string{"untagged"}, 2)
+	if err != nil {
+		t.Fatalf("random untagged preferred: %v", err)
+	}
+	if !sameVideoIDSet(videoIDs(got), []string{"visible-1", "visible-2"}) {
+		t.Fatalf("untagged preferred ids = %#v, want visible fallback videos", videoIDs(got))
+	}
+}
+
+func videoIDs(videos []*Video) []string {
+	ids := make([]string, 0, len(videos))
+	for _, v := range videos {
+		ids = append(ids, v.ID)
+	}
+	return ids
+}
+
+func hasVideoID(ids []string, want string) bool {
+	for _, id := range ids {
+		if id == want {
+			return true
+		}
+	}
+	return false
+}
+
+func uniqueVideoIDs(ids []string) map[string]struct{} {
+	seen := make(map[string]struct{}, len(ids))
+	for _, id := range ids {
+		seen[id] = struct{}{}
+	}
+	return seen
+}
+
+func sameVideoIDSet(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	seen := make(map[string]int, len(a))
+	for _, value := range a {
+		seen[value]++
+	}
+	for _, value := range b {
+		if seen[value] == 0 {
+			return false
+		}
+		seen[value]--
+	}
+	return true
+}

src/data/videos.ts

@@ -99,11 +99,12 @@ export type ShortsNextResponse = {
  */
 export function fetchShortsNext(
   seenIds: string[],
-  count: number
+  count: number,
+  preferredFromVideoId?: string
 ): Promise<ShortsNextResponse> {
   return apiJSON<ShortsNextResponse>("/api/shorts/next", {
     method: "POST",
-    body: JSON.stringify({ seenIds, count }),
+    body: JSON.stringify({ seenIds, count, preferredFromVideoId }),
   }).catch(() => ({ items: [], total: 0, roundComplete: false }));
 }
 

src/pages/ShortsPage.tsx

@@ -120,6 +120,8 @@ export default function ShortsPage() {
 
   // seenIds 用 ref 维护，方便在异步 callback 里读到最新值
   const seenIdsRef = useRef<string[]>(loadSeenIds());
+  const preferredFromVideoIdRef = useRef<string | null>(null);
+  const reportedPreferenceIdsRef = useRef<Set<string>>(new Set());
 
   const containerRef = useRef<HTMLDivElement | null>(null);
   // 整个页面根元素，用于 requestFullscreen
@@ -183,6 +185,12 @@ export default function ShortsPage() {
     []
   );
 
+  const handlePreferenceReady = useCallback((item: ShortsItem) => {
+    if (reportedPreferenceIdsRef.current.has(item.id)) return;
+    reportedPreferenceIdsRef.current.add(item.id);
+    preferredFromVideoIdRef.current = item.id;
+  }, []);
+
   /**
    * 向后端请求下一批不重复的短视频，追加到 items 末尾。
    */
@@ -191,7 +199,11 @@ export default function ShortsPage() {
     setLoading(true);
     try {
       const seen = seenIdsRef.current;
-      const resp = await fetchShortsNext(seen, BATCH_SIZE);
+      const resp = await fetchShortsNext(
+        seen,
+        BATCH_SIZE,
+        preferredFromVideoIdRef.current ?? undefined
+      );
       if (resp.items.length === 0) {
         setEmpty((prev) => prev || true /* 维持 true 即可 */);
         setRoundComplete(true);
@@ -622,6 +634,7 @@ export default function ShortsPage() {
             onLikeToggle={handleLikeToggle}
             hasLiked={hasLiked}
             onHideSuccess={handleHideSuccess}
+            onPreferenceReady={handlePreferenceReady}
             showHud={showHud}
           />
         ))}
@@ -655,6 +668,7 @@ type SlideProps = {
   /** 父组件查询某 id 是否已经在本次会话内点过赞 */
   hasLiked: (videoId: string) => boolean;
   onHideSuccess: (index: number) => void;
+  onPreferenceReady: (item: ShortsItem) => void;
   showHud: (text: string, icon?: React.ReactNode) => void;
 };
 
@@ -678,6 +692,7 @@ function ShortsSlide({
   onLikeToggle,
   hasLiked,
   onHideSuccess,
+  onPreferenceReady,
   showHud,
 }: SlideProps) {
   const localRef = useRef<HTMLVideoElement | null>(null);
@@ -698,6 +713,8 @@ function ShortsSlide({
   // 拖动开始时是否在播：用于拖完后判断要不要 resume
   const wasPlayingRef = useRef(true);
 
+  const preferenceFiredRef = useRef(false);
+
   // 点赞数和"是否已点过赞"状态。
   // 初始 likes 取自后端返回的列表项；isLiked 仅控制视觉态，
   // 真正的防重在父组件 likedIdsRef 里，这里只信任父返回的回执。
@@ -722,6 +739,10 @@ function ShortsSlide({
     setIsLiked(hasLiked(item.id));
   }, [item.id, item.likes, hasLiked]);
 
+  useEffect(() => {
+    preferenceFiredRef.current = false;
+  }, [item.id]);
+
   const setRef = useCallback(
     (el: HTMLVideoElement | null) => {
       localRef.current = el;
@@ -770,6 +791,16 @@ function ShortsSlide({
     const handleTime = () => {
       // 拖动期间不要被 timeupdate 覆盖 UI
       if (!scrubbing) setCurrentTime(video.currentTime);
+      if (
+        isActive &&
+        shouldMount &&
+        !isMarkedHidden &&
+        !preferenceFiredRef.current &&
+        video.currentTime >= 3
+      ) {
+        preferenceFiredRef.current = true;
+        onPreferenceReady(item);
+      }
     };
     const handleWaiting = () => {
       setIsBuffering(true);
@@ -811,7 +842,7 @@ function ShortsSlide({
       video.removeEventListener("canplay", handlePlayingOrCanPlay);
       video.removeEventListener("volumechange", handleVolumeChange);
     };
-  }, [shouldMount, scrubbing, muted, volume, setMuted, setVolume]);
+  }, [shouldMount, scrubbing, muted, volume, setMuted, setVolume, isActive, isMarkedHidden, item, onPreferenceReady]);
 
   // 长按 2 倍速：直接绑原生事件
   useEffect(() => {