优化支持0.5集

Cursor/hide viewer admin UI

$null

@@ -0,0 +1,2 @@
+'Get-Content' is not recognized as an internal or external command,
+operable program or batch file.

.github/workflows/Auto-docker-publish.yml

@@ -115,7 +115,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version-file: '.nvmrc'
           cache: 'npm'
           cache-dependency-path: web/package-lock.json
       - name: Install
@@ -196,8 +196,12 @@ jobs:
           path: web/dist
       - name: Build binary
         run: |
+          LDFLAGS="-s -w -X main.version=${{ needs.build-image.outputs.release_tag }}"
+          if [ "${{ matrix.goos }}" = "windows" ]; then
+            LDFLAGS="$LDFLAGS -H=windowsgui"
+          fi
           CGO_ENABLED=0 GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} \
-            go build -trimpath -ldflags="-s -w -X main.version=${{ needs.build-image.outputs.release_tag }}" \
+            go build -trimpath -ldflags="$LDFLAGS" \
             -o "dist/mebox-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.ext }}" ./cmd/server
       - name: Package
         run: |

.github/workflows/beta-build.yml

@@ -48,7 +48,7 @@ jobs:
       # before the Go toolchain touches the web package.
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version-file: '.nvmrc'
           cache: 'npm'
           cache-dependency-path: web/package-lock.json
       - name: Build SPA
@@ -77,7 +77,7 @@ jobs:
       - name: Build linux/arm64
         run: CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -ldflags="-s -w -X main.version=${{ steps.version.outputs.full_version }}" -o dist/mebox-beta-linux-arm64 ./cmd/server
       - name: Build windows/amd64
-        run: CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -trimpath -ldflags="-s -w -X main.version=${{ steps.version.outputs.full_version }}" -o dist/mebox-beta-windows-amd64.exe ./cmd/server
+        run: CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -trimpath -ldflags="-s -w -H=windowsgui -X main.version=${{ steps.version.outputs.full_version }}" -o dist/mebox-beta-windows-amd64.exe ./cmd/server
 
       - name: Upload artifacts
         uses: actions/upload-artifact@v4

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
       # before the Go toolchain touches the `web` package.
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version-file: '.nvmrc'
           cache: 'npm'
           cache-dependency-path: web/package-lock.json
       - name: Build SPA
@@ -51,7 +51,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version-file: '.nvmrc'
           cache: 'npm'
           cache-dependency-path: web/package-lock.json
 

.nvmrc

@@ -0,0 +1 @@
+20.19.0

Dockerfile

@@ -2,7 +2,7 @@
 # =============================================================================
 # Multi-architecture build for MeBox.
 #
-# Stage 1 (frontend) :  Node 20  -> static SPA bundle
+# Stage 1 (frontend) :  Node 20.19+ -> static SPA bundle
 # Stage 2 (backend)  :  Go 1.25  -> single static binary (CGO_ENABLED=0)
 # Stage 3 (runtime)  :  Alpine 3.23 -> ffmpeg + tzdata + non-root user
 #
@@ -15,7 +15,7 @@
 # =============================================================================
 
 # ---- Stage 1: frontend (always build on the host architecture) -------------
-FROM --platform=$BUILDPLATFORM node:20-alpine AS frontend
+FROM --platform=$BUILDPLATFORM node:20.19-alpine AS frontend
 ARG NPM_CONFIG_REGISTRY=https://registry.npmjs.org/
 WORKDIR /app/web
 COPY web/package*.json ./

README.md

@@ -199,6 +199,11 @@ environment:
 **硬链接失败（cross-device link）？**  
 硬链接要求源与目标在同一文件系统/子卷；跨盘、跨 btrfs 子卷或网盘挂载时请改用复制或软链接。
 
+**日志保留时间太短？**
+
+默认应用日志为 `20MB x 5`，容器 stdout 日志为 `20m x 3`。排障时可在 compose 中调大
+`MEBOX_LOGGING_MAX_SIZE_MB`、`MEBOX_LOGGING_MAX_BACKUPS` 与服务的 `logging.options.max-size/max-file`。
+
 **第三方播放器连不上？**  
 确认地址为 `http://IP:18080`，使用 MeBox 用户账号；反代部署需正确配置外部 URL 与 HTTPS 头。
 
@@ -207,6 +212,7 @@ environment:
 ## 开发构建
 
 后端通过 `go:embed` 嵌入 `web/dist`，**编译前必须先构建前端**。
+前端构建要求 Node.js `20.19+` 或 `22.12+`。
 
 ```bash
 npm --prefix web ci
@@ -219,6 +225,14 @@ npm --prefix web run dev     # http://127.0.0.1:3000
 
 CI 会在 Release 中提供 Windows / Linux / macOS 的 amd64、arm64 单文件可执行程序。
 
+Windows 本地打包：
+
+```powershell
+.\scripts\build-windows.ps1 -Version dev
+```
+
+Windows 可执行程序使用项目 Logo，不显示控制台窗口；启动后会常驻系统托盘。托盘菜单可打开 MeBox、切换开机自启、查看日志、重启或退出。
+
 ---
 
 ## 鸣谢

README_EN.md

@@ -199,6 +199,14 @@ npm --prefix web run dev
 
 Release builds ship single-file binaries for Windows, Linux, and macOS on amd64 and arm64.
 
+Build the Windows executable locally:
+
+```powershell
+.\scripts\build-windows.ps1 -Version dev
+```
+
+The Windows executable uses the project logo and runs without a console window. It stays in the notification area, with menu actions for opening MeBox, toggling auto-start, viewing logs, restarting, and exiting.
+
 ---
 
 ## Acknowledgements

cmd/server/application.go

@@ -0,0 +1,197 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"sync"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/database"
+	"github.com/truewhile/MeBox/internal/helper"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// application owns the long-running MeBox server and all resources created
+// during startup. Platform entry points decide how the application is
+// controlled: a console signal loop or a Windows notification-area icon.
+type application struct {
+	cfg              *config.Config
+	logger           *zap.Logger
+	embyCompatLogger *zap.Logger
+	serverManager    *serverManager
+	services         *service.Container
+
+	closeMu     sync.Mutex
+	closeFuncs  []func()
+	shutdown    sync.Once
+	shutdownErr error
+}
+
+func newApplication() (*application, error) {
+	cfg, err := config.Load()
+	if err != nil {
+		return nil, fmt.Errorf("config load failed: %w", err)
+	}
+
+	logger, closeLogger, err := newLoggerWithCloser(cfg)
+	if err != nil {
+		return nil, fmt.Errorf("logger init failed: %w", err)
+	}
+
+	app := &application{
+		cfg:        cfg,
+		logger:     logger,
+		closeFuncs: []func(){closeLogger},
+	}
+	if err := app.start(); err != nil {
+		app.closeLoggers()
+		return nil, err
+	}
+	return app, nil
+}
+
+func (a *application) start() error {
+	embyCompatLogger, closeEmbyCompatLogger, err := newEmbyCompatLogger(a.cfg)
+	if err != nil {
+		a.logger.Error("Emby compatibility logger init failed", zap.Error(err))
+		return fmt.Errorf("Emby compatibility logger init failed: %w", err)
+	}
+	a.embyCompatLogger = embyCompatLogger
+	a.addCloser(closeEmbyCompatLogger)
+
+	appVersion := effectiveVersion(version)
+	a.logger.Info("starting MeBox",
+		zap.String("version", appVersion),
+		zap.Int("port", a.cfg.App.Port),
+		zap.String("data_dir", a.cfg.App.DataDir),
+		zap.String("emby_compat_log", embyCompatLogPath(a.cfg)),
+	)
+
+	for _, dir := range []string{a.cfg.App.DataDir, a.cfg.Cache.CacheDir} {
+		if err := os.MkdirAll(dir, 0o750); err != nil {
+			a.logger.Error("create dir failed", zap.String("dir", dir), zap.Error(err))
+			return fmt.Errorf("create dir %s failed: %w", dir, err)
+		}
+	}
+
+	db, err := database.Open(a.cfg, a.logger)
+	if err != nil {
+		a.logger.Error("database open failed", zap.Error(err))
+		return fmt.Errorf("database open failed: %w", err)
+	}
+	if err := waitForDatabase(db, a.logger); err != nil {
+		a.logger.Error("database not ready", zap.Error(err))
+		return fmt.Errorf("database not ready: %w", err)
+	}
+	if err := database.AutoMigrate(db); err != nil {
+		a.logger.Error("auto-migrate failed", zap.Error(err))
+		return fmt.Errorf("auto-migrate failed: %w", err)
+	}
+	if err := database.MigrateSQLiteToCurrentIfNeeded(a.cfg, db, a.logger); err != nil {
+		a.logger.Error("sqlite to postgres migration failed", zap.Error(err))
+		return fmt.Errorf("sqlite to postgres migration failed: %w", err)
+	}
+
+	repos := repository.New(db)
+	service.ApplyRuntimeSettings(context.Background(), a.cfg, repos, a.logger)
+	applyCPUThreadLimit(a.cfg, a.logger)
+	a.services = service.NewWithVersion(a.cfg, a.logger, repos, appVersion)
+
+	// 一次性清洗历史脏数据: 老版本把单集 episode id / 单集名写进整剧字段, 导致
+	// 同一部剧被拆成多张单集卡。清空被污染的字段并重置为 pending(借后续重刮修正)。
+	if cleaned, err := a.services.NormalizePollutedEpisodeMetadata(context.Background()); err != nil {
+		a.logger.Warn("polluted episode metadata cleanup failed", zap.Error(err))
+	} else if cleaned > 0 {
+		a.logger.Info("polluted episode metadata cleanup completed", zap.Int("media_count", cleaned))
+	}
+
+	if err := a.services.Auth.SeedAdmin(context.Background()); err != nil {
+		a.logger.Warn("seed admin failed", zap.Error(err))
+	}
+
+	router := buildRouter(a.cfg, a.logger, a.embyCompatLogger, a.services)
+	a.serverManager = newServerManager(a.cfg, a.logger, router)
+	a.services.ReloadHTTPServer = a.serverManager.Reload
+	if err := a.serverManager.Start(); err != nil {
+		a.logger.Error("listen failed", zap.Error(err))
+		return fmt.Errorf("listen failed: %w", err)
+	}
+
+	go func() {
+		scheme := "http"
+		if a.cfg.App.HTTPSEnabled {
+			scheme = "https"
+		}
+		if publicIP := getPublicIP(3 * time.Second); publicIP != "" {
+			a.logger.Info("server public endpoint",
+				zap.String("public", fmt.Sprintf("%s://%s:%d", scheme, publicIP, a.cfg.App.Port)),
+			)
+		}
+	}()
+	helper.Go(a.logger, "services.boot", a.services.Boot)
+	return nil
+}
+
+// Shutdown is idempotent and safe to call from both the tray handler and the
+// systray exit callback.
+func (a *application) Shutdown() error {
+	a.shutdown.Do(func() {
+		a.logger.Info("shutdown requested")
+
+		ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+		if a.serverManager != nil {
+			if err := a.serverManager.Shutdown(ctx); err != nil {
+				a.shutdownErr = err
+				a.logger.Error("graceful shutdown failed", zap.Error(err))
+			}
+		}
+		cancel()
+
+		if a.services != nil {
+			a.services.Close()
+		}
+		a.logger.Info("MeBox stopped")
+		_ = a.logger.Sync()
+		if a.embyCompatLogger != nil {
+			_ = a.embyCompatLogger.Sync()
+		}
+		a.closeLoggers()
+	})
+	return a.shutdownErr
+}
+
+func (a *application) addCloser(fn func()) {
+	if fn == nil {
+		return
+	}
+	a.closeMu.Lock()
+	a.closeFuncs = append(a.closeFuncs, fn)
+	a.closeMu.Unlock()
+}
+
+func (a *application) closeLoggers() {
+	a.closeMu.Lock()
+	closers := append([]func(){}, a.closeFuncs...)
+	a.closeFuncs = nil
+	a.closeMu.Unlock()
+
+	for i := len(closers) - 1; i >= 0; i-- {
+		closers[i]()
+	}
+}
+
+func (a *application) localURL() string {
+	config.RuntimeMu.RLock()
+	scheme := "http"
+	if a.cfg.App.HTTPSEnabled {
+		scheme = "https"
+	}
+	port := a.cfg.App.Port
+	config.RuntimeMu.RUnlock()
+	return fmt.Sprintf("%s://127.0.0.1:%d", scheme, port)
+}

cmd/server/main.go

@@ -11,21 +11,8 @@
 package main
 
 import (
-	"context"
-	"fmt"
 	"os"
-	"os/signal"
 	"strings"
-	"syscall"
-	"time"
-
-	"go.uber.org/zap"
-
-	"github.com/truewhile/MeBox/internal/config"
-	"github.com/truewhile/MeBox/internal/database"
-	"github.com/truewhile/MeBox/internal/helper"
-	"github.com/truewhile/MeBox/internal/repository"
-	"github.com/truewhile/MeBox/internal/service"
 )
 
 // version is overwritten at build time via -ldflags="-X main.version=...".
@@ -46,105 +33,5 @@ func effectiveVersion(buildVersion string) string {
 }
 
 func main() {
-	cfg, err := config.Load()
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "config load failed: %v\n", err)
-		os.Exit(1)
-	}
-
-	logger, err := newLogger(cfg)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "logger init failed: %v\n", err)
-		os.Exit(1)
-	}
-	defer func() { _ = logger.Sync() }()
-
-	embyCompatLogger, closeEmbyCompatLogger, err := newEmbyCompatLogger(cfg)
-	if err != nil {
-		logger.Fatal("Emby compatibility logger init failed", zap.Error(err))
-	}
-	defer func() {
-		_ = embyCompatLogger.Sync()
-		closeEmbyCompatLogger()
-	}()
-
-	appVersion := effectiveVersion(version)
-	logger.Info("starting MeBox",
-		zap.String("version", appVersion),
-		zap.Int("port", cfg.App.Port),
-		zap.String("data_dir", cfg.App.DataDir),
-		zap.String("emby_compat_log", embyCompatLogPath(cfg)),
-	)
-
-	// Ensure data / cache / web dirs exist.
-	for _, d := range []string{cfg.App.DataDir, cfg.Cache.CacheDir} {
-		if err := os.MkdirAll(d, 0o750); err != nil {
-			logger.Fatal("create dir failed", zap.String("dir", d), zap.Error(err))
-		}
-	}
-
-	db, err := database.Open(cfg, logger)
-	if err != nil {
-		logger.Fatal("database open failed", zap.Error(err))
-	}
-	if err := waitForDatabase(db, logger); err != nil {
-		logger.Fatal("database not ready", zap.Error(err))
-	}
-	if err := database.AutoMigrate(db); err != nil {
-		logger.Fatal("auto-migrate failed", zap.Error(err))
-	}
-	if err := database.MigrateSQLiteToCurrentIfNeeded(cfg, db, logger); err != nil {
-		logger.Fatal("sqlite to postgres migration failed", zap.Error(err))
-	}
-
-	repos := repository.New(db)
-	service.ApplyRuntimeSettings(context.Background(), cfg, repos, logger)
-	applyCPUThreadLimit(cfg, logger)
-	services := service.NewWithVersion(cfg, logger, repos, appVersion)
-
-	// 一次性清洗历史脏数据: 老版本把单集 episode id / 单集名写进整剧字段, 导致
-	// 同一部剧被拆成多张单集卡。清空被污染的字段并重置为 pending(借后续重刮修正)。
-	if cleaned, err := services.NormalizePollutedEpisodeMetadata(context.Background()); err != nil {
-		logger.Warn("polluted episode metadata cleanup failed", zap.Error(err))
-	} else if cleaned > 0 {
-		logger.Info("polluted episode metadata cleanup completed", zap.Int("media_count", cleaned))
-	}
-
-	if err := services.Auth.SeedAdmin(context.Background()); err != nil {
-		logger.Warn("seed admin failed", zap.Error(err))
-	}
-
-	router := buildRouter(cfg, logger, embyCompatLogger, services)
-
-	serverMgr := newServerManager(cfg, logger, router)
-	services.ReloadHTTPServer = serverMgr.Reload
-	if err := serverMgr.Start(); err != nil {
-		logger.Fatal("listen failed", zap.Error(err))
-	}
-	go func() {
-		scheme := "http"
-		if cfg.App.HTTPSEnabled {
-			scheme = "https"
-		}
-		if publicIP := getPublicIP(3 * time.Second); publicIP != "" {
-			logger.Info("server public endpoint",
-				zap.String("public", fmt.Sprintf("%s://%s:%d", scheme, publicIP, cfg.App.Port)),
-			)
-		}
-	}()
-	helper.Go(logger, "services.boot", services.Boot)
-
-	// Graceful shutdown.
-	stop := make(chan os.Signal, 1)
-	signal.Notify(stop, syscall.SIGINT, syscall.SIGTERM)
-	<-stop
-	logger.Info("shutdown requested")
-
-	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
-	defer cancel()
-	if err := serverMgr.Shutdown(ctx); err != nil {
-		logger.Error("graceful shutdown failed", zap.Error(err))
-	}
-	services.Close()
-	logger.Info("MeBox stopped")
+	runProgram()
 }

cmd/server/program_other.go

@@ -0,0 +1,33 @@
+//go:build !windows
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+)
+
+func runProgram() {
+	app, err := newApplication()
+	if err != nil {
+		reportError("MeBox 启动失败", err)
+		os.Exit(1)
+	}
+
+	stop := make(chan os.Signal, 1)
+	signal.Notify(stop, syscall.SIGINT, syscall.SIGTERM)
+	<-stop
+
+	if err := app.Shutdown(); err != nil {
+		reportError("MeBox 退出失败", err)
+	}
+}
+
+func reportError(title string, err error) {
+	if err == nil {
+		return
+	}
+	fmt.Fprintf(os.Stderr, "%s: %v\n", title, err)
+}

cmd/server/program_windows.go

@@ -0,0 +1,330 @@
+//go:build windows
+
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"syscall"
+
+	"fyne.io/systray"
+	"golang.org/x/sys/windows"
+	"golang.org/x/sys/windows/registry"
+
+	"github.com/truewhile/MeBox/internal/brand"
+)
+
+const (
+	runRegistryKey     = `Software\Microsoft\Windows\CurrentVersion\Run`
+	runRegistryValue   = "MeBox"
+	singleInstanceName = `Local\MeBox-Server`
+)
+
+var errAlreadyRunning = errors.New("MeBox is already running")
+
+func runProgram() {
+	if err := prepareWorkingDirectory(); err != nil {
+		reportError("MeBox 启动失败", fmt.Errorf("切换工作目录失败: %w", err))
+		return
+	}
+
+	instance, err := acquireSingleInstance()
+	if errors.Is(err, errAlreadyRunning) {
+		reportError("MeBox", errors.New("MeBox 已在运行，请查看右下角托盘图标"))
+		return
+	}
+	if err != nil {
+		reportError("MeBox 启动失败", fmt.Errorf("创建单实例锁失败: %w", err))
+		return
+	}
+
+	app, err := newApplication()
+	if err != nil {
+		_ = instance.Close()
+		reportError("MeBox 启动失败", err)
+		return
+	}
+
+	controller := &trayController{app: app}
+	systray.Run(controller.onReady, controller.onExit)
+
+	// Release the mutex before starting the replacement process. The new
+	// process must be able to acquire it immediately after the old one exits.
+	_ = instance.Close()
+
+	if !controller.readyClosed.Load() {
+		_ = app.Shutdown()
+		reportError("MeBox 启动失败", errors.New("系统托盘初始化失败"))
+		return
+	}
+	if controller.restartRequested.Load() {
+		if err := launchSelf(); err != nil {
+			reportError("MeBox 重启失败", err)
+		}
+	}
+}
+
+type trayController struct {
+	app *application
+
+	readyClosed      atomic.Bool
+	restartRequested atomic.Bool
+	shutdownStarted  atomic.Bool
+}
+
+func (c *trayController) onReady() {
+	defer func() {
+		c.readyClosed.Store(true)
+	}()
+
+	systray.SetIcon(brand.Icon)
+	systray.SetTooltip("MeBox")
+
+	mOpen := systray.AddMenuItem("打开 MeBox", "在浏览器中打开 MeBox")
+	mAutoStart := systray.AddMenuItemCheckbox("开机自启", "登录 Windows 后自动启动 MeBox", autoStartEnabled())
+	mLogs := systray.AddMenuItem("查看日志", "打开 MeBox 应用日志")
+	systray.AddSeparator()
+	mRestart := systray.AddMenuItem("重启 MeBox", "重启 MeBox 服务")
+	mQuit := systray.AddMenuItem("退出 MeBox", "停止服务并退出")
+
+	initialAutoStart := mAutoStart.Checked()
+	go func() {
+		for {
+			select {
+			case <-mOpen.ClickedCh:
+				if err := openURL(c.app.localURL()); err != nil {
+					reportError("MeBox", fmt.Errorf("打开 MeBox 失败: %w", err))
+				}
+			case <-mAutoStart.ClickedCh:
+				enable := !mAutoStart.Checked()
+				if err := setAutoStart(enable); err != nil {
+					if initialAutoStart {
+						mAutoStart.Check()
+					} else {
+						mAutoStart.Uncheck()
+					}
+					reportError("MeBox", fmt.Errorf("更新开机自启设置失败: %w", err))
+					continue
+				}
+				if enable {
+					mAutoStart.Check()
+				} else {
+					mAutoStart.Uncheck()
+				}
+				initialAutoStart = enable
+			case <-mLogs.ClickedCh:
+				if err := c.app.openLog(); err != nil {
+					reportError("MeBox", fmt.Errorf("打开日志失败: %w", err))
+				}
+			case <-mRestart.ClickedCh:
+				c.restart()
+			case <-mQuit.ClickedCh:
+				c.quit()
+			}
+		}
+	}()
+}
+
+func (c *trayController) onExit() {
+	_ = c.app.Shutdown()
+}
+
+func (c *trayController) quit() {
+	if !c.shutdownStarted.CompareAndSwap(false, true) {
+		return
+	}
+	go func() {
+		_ = c.app.Shutdown()
+		systray.Quit()
+	}()
+}
+
+func (c *trayController) restart() {
+	if !c.shutdownStarted.CompareAndSwap(false, true) {
+		return
+	}
+	c.restartRequested.Store(true)
+	go func() {
+		_ = c.app.Shutdown()
+		systray.Quit()
+	}()
+}
+
+func (a *application) openLog() error {
+	appLog, _, _ := logFilePaths(a.cfg)
+	if appLog != "" {
+		if _, err := os.Stat(appLog); err == nil {
+			return openPath(appLog)
+		}
+		_ = os.MkdirAll(filepath.Dir(appLog), 0o750)
+		return openPath(filepath.Dir(appLog))
+	}
+
+	logDir := filepath.Join(a.cfg.App.DataDir, "logs")
+	if err := os.MkdirAll(logDir, 0o750); err != nil {
+		return err
+	}
+	return openPath(logDir)
+}
+
+func prepareWorkingDirectory() error {
+	exe, err := os.Executable()
+	if err != nil {
+		return err
+	}
+	exeDir := filepath.Dir(exe)
+	cwd, err := os.Getwd()
+	if err != nil {
+		return err
+	}
+	if samePath(exeDir, cwd) || looksLikeProjectDirectory(cwd) {
+		return nil
+	}
+	return os.Chdir(exeDir)
+}
+
+func looksLikeProjectDirectory(dir string) bool {
+	for _, name := range []string{"go.mod", "config.yaml", "data", filepath.Join("web", "dist")} {
+		if _, err := os.Stat(filepath.Join(dir, name)); err == nil {
+			return true
+		}
+	}
+	return false
+}
+
+func samePath(left, right string) bool {
+	return strings.EqualFold(filepath.Clean(left), filepath.Clean(right))
+}
+
+type singleInstance struct {
+	handle windows.Handle
+}
+
+func acquireSingleInstance() (*singleInstance, error) {
+	name, err := windows.UTF16PtrFromString(singleInstanceName)
+	if err != nil {
+		return nil, err
+	}
+	handle, err := windows.CreateMutex(nil, false, name)
+	if errors.Is(err, windows.ERROR_ALREADY_EXISTS) {
+		if handle != 0 {
+			_ = windows.CloseHandle(handle)
+		}
+		return nil, errAlreadyRunning
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &singleInstance{handle: handle}, nil
+}
+
+func (s *singleInstance) Close() error {
+	if s == nil || s.handle == 0 {
+		return nil
+	}
+	err := windows.CloseHandle(s.handle)
+	s.handle = 0
+	return err
+}
+
+func launchSelf() error {
+	exe, err := os.Executable()
+	if err != nil {
+		return err
+	}
+	cwd, err := os.Getwd()
+	if err != nil {
+		return err
+	}
+
+	cmd := exec.Command(exe, os.Args[1:]...)
+	cmd.Dir = cwd
+	cmd.Env = os.Environ()
+	cmd.SysProcAttr = &syscall.SysProcAttr{
+		HideWindow:    true,
+		CreationFlags: windows.CREATE_NEW_PROCESS_GROUP | windows.DETACHED_PROCESS,
+	}
+	if err := cmd.Start(); err != nil {
+		return err
+	}
+	return cmd.Process.Release()
+}
+
+func autoStartEnabled() bool {
+	key, err := registry.OpenKey(registry.CURRENT_USER, runRegistryKey, registry.QUERY_VALUE)
+	if err != nil {
+		return false
+	}
+	defer key.Close()
+
+	value, _, err := key.GetStringValue(runRegistryValue)
+	if err != nil {
+		return false
+	}
+	exe, err := os.Executable()
+	if err != nil {
+		return false
+	}
+	return strings.EqualFold(strings.TrimSpace(strings.Trim(value, `"`)), filepath.Clean(exe))
+}
+
+func setAutoStart(enabled bool) error {
+	key, _, err := registry.CreateKey(registry.CURRENT_USER, runRegistryKey, registry.SET_VALUE)
+	if err != nil {
+		return err
+	}
+	defer key.Close()
+
+	if !enabled {
+		if err := key.DeleteValue(runRegistryValue); err != nil && !errors.Is(err, registry.ErrNotExist) {
+			return err
+		}
+		return nil
+	}
+
+	exe, err := os.Executable()
+	if err != nil {
+		return err
+	}
+	return key.SetStringValue(runRegistryValue, syscall.EscapeArg(filepath.Clean(exe)))
+}
+
+func openURL(url string) error {
+	return shellOpen(url)
+}
+
+func openPath(path string) error {
+	return shellOpen(path)
+}
+
+func shellOpen(target string) error {
+	targetPtr, err := windows.UTF16PtrFromString(target)
+	if err != nil {
+		return err
+	}
+	verbPtr, err := windows.UTF16PtrFromString("open")
+	if err != nil {
+		return err
+	}
+	return windows.ShellExecute(0, verbPtr, targetPtr, nil, nil, 1)
+}
+
+func reportError(title string, err error) {
+	if err == nil {
+		return
+	}
+	text, textErr := windows.UTF16PtrFromString(title + "\r\n\r\n" + err.Error())
+	if textErr != nil {
+		return
+	}
+	caption, captionErr := windows.UTF16PtrFromString("MeBox")
+	if captionErr != nil {
+		return
+	}
+	_, _ = windows.MessageBox(0, text, caption, windows.MB_OK|windows.MB_ICONERROR|windows.MB_SETFOREGROUND)
+}

cmd/server/resources_windows.go

@@ -0,0 +1,11 @@
+//go:build windows
+
+package main
+
+// Regenerate the linked Windows resources after changing the project logo or
+// manifest:
+//
+//	go generate ./cmd/server
+//
+//go:generate go run github.com/akavel/rsrc@v0.10.2 -arch amd64 -ico ../../internal/brand/logo.ico -manifest winres/mebox.manifest -o rsrc_windows_amd64.syso
+//go:generate go run github.com/akavel/rsrc@v0.10.2 -arch arm64 -ico ../../internal/brand/logo.ico -manifest winres/mebox.manifest -o rsrc_windows_arm64.syso

cmd/server/winres/mebox.manifest

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
+  <assemblyIdentity
+    version="1.0.0.0"
+    processorArchitecture="*"
+    name="MeBox"
+    type="win32"
+  />
+  <description>MeBox media server</description>
+  <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
+    <security>
+      <requestedPrivileges>
+        <requestedExecutionLevel level="asInvoker" uiAccess="false" />
+      </requestedPrivileges>
+    </security>
+  </trustInfo>
+  <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
+    <application>
+      <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
+    </application>
+  </compatibility>
+  <application xmlns="urn:schemas-microsoft-com:asm.v3">
+    <windowsSettings>
+      <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true/pm</dpiAware>
+      <longPathAware xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">true</longPathAware>
+    </windowsSettings>
+  </application>
+</assembly>

docker-compose.metatube.yml

@@ -0,0 +1,216 @@
+# MeBox + MetaTube 一体部署 Docker Compose 部署文件
+#
+# 组件：
+#   MeBox + PostgreSQL + Redis + MetaTube
+#
+# 与 docker-compose.standard.yml 的区别：
+#   额外内置一个 MetaTube 后端（番号元数据刮削 / 封面人脸裁剪），
+#   并与 MeBox 共用同一个 PostgreSQL 实例，不需要再单独起一套数据库。
+#
+# 使用方式二选一：
+#   1. 保存为 docker-compose.yml 后执行：
+#        docker compose up -d
+#   2. 保留本文件名时执行：
+#        docker compose -f docker-compose.metatube.yml up -d
+#
+# 首次启动后需要做一次配置（只有这一处是手动的）：
+#   登录 MeBox → 设置 → 番号刮削：
+#     - 番号刮削引擎：MetaTube 后端服务，或 智能混合
+#     - MetaTube 服务端地址：http://metatube:8080
+#     - 访问 Token：留空（仅内部网络，未启用认证；如需认证两边填同一个值）
+#
+# 说明：
+#   - MetaTube 使用独立数据库 metatube，由 metatube-db-init 一次性容器自动创建；
+#     和 MeBox 的 mebox 库共用同一个 PostgreSQL 实例，只是分成两个库。
+#   - MetaTube 不向宿主机映射端口，只在本 Compose 内部网络提供服务。
+#   - MeBox 故意不依赖 MetaTube：MetaTube 未就绪或挂掉时，智能混合模式会自动回退到内置刮削源。
+#   - 更新全部组件：
+#       docker compose -f docker-compose.metatube.yml pull
+#       docker compose -f docker-compose.metatube.yml up -d
+#     保留本文件名时，管理面板「系统更新」需要把「Compose 安装目录」指向本文件所在目录，
+#     或把更新命令改成带 -f docker-compose.metatube.yml 的形式。
+#
+# 默认账号：
+#   admin / admin123
+
+services:
+  mebox:
+    image: ghcr.io/truewhile/mebox:latest
+
+    restart: unless-stopped
+    init: true
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+
+    ports:
+      - "18080:8080"
+
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+    volumes:
+      # 程序运行数据：JWT 密钥、运行配置、旧 SQLite 迁移源。
+      - ./data:/data
+
+      # 缓存目录：海报缓存、临时文件等。通常不用备份。
+      - ./cache:/cache
+
+      # 媒体库目录。自动整理/重命名/入库需要读写权限。
+      # NAS 示例：source: /vol1/1000/Media
+      # Windows Docker Desktop 示例：source: D:/Media
+      # create_host_path=false 可以避免路径写错时 Docker 自动创建空文件夹。
+      - ./media: /media
+
+    environment:
+      TZ: Asia/Shanghai
+
+      PUID: "0"
+      PGID: "0"
+
+      MEBOX_APP_HOST: 0.0.0.0
+      MEBOX_APP_PORT: 8080
+      MEBOX_APP_WEB_DIR: /app/web/dist
+      MEBOX_APP_DATA_DIR: /data
+      MEBOX_LOGGING_LEVEL: info
+      MEBOX_LOGGING_FORMAT: console
+      MEBOX_LOGGING_OUTPUT_PATH: /data/logs
+      MEBOX_LOGGING_MAX_SIZE_MB: "20"
+      MEBOX_LOGGING_MAX_BACKUPS: "5"
+      MEBOX_LOGGING_MAX_AGE_DAYS: "30"
+
+      MEBOX_DATABASE_TYPE: postgres
+      MEBOX_DATABASE_DSN: postgres://mebox:mebox@postgres:5432/mebox?sslmode=disable
+      MEBOX_DATABASE_DB_PATH: /data/mebox.db
+
+      # Redis 只做热缓存，源数据仍在 PostgreSQL；Redis 丢失可自动重建。
+      MEBOX_CACHE_REDIS_URL: redis://redis:6379/0
+      MEBOX_CACHE_CACHE_DIR: /cache
+
+      MEBOX_UPDATE_IMAGE: ghcr.io/truewhile/mebox:latest
+
+      # 路径换算配置。左边宿主机真实路径要和 volumes 左边保持一致。
+      MEBOX_MEDIA_DIR: /media
+      MEBOX_MEDIA_CONTAINER_DIR: /media
+      MEBOX_DOWNLOAD_DIR: /downloads
+      MEBOX_DOWNLOAD_CONTAINER_DIR: /downloads
+
+      MEBOX_TRANSCODER_ENABLED: "true"
+      MEBOX_TRANSCODER_HARDWARE_ACCEL: "false"
+      MEBOX_TRANSCODER_REALTIME: "true"
+      MEBOX_TRANSCODER_THREADS: "2"
+      MEBOX_TRANSCODER_MAX_CONCURRENT: "1"
+      MEBOX_TRANSCODER_IDLE_TIMEOUT_SECONDS: "120"
+
+    healthcheck:
+      test: ["CMD-SHELL", "busybox wget -qO- http://127.0.0.1:8080/api/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 30s
+
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "3"
+
+  postgres:
+    image: postgres:16-alpine
+    # 首次部署允许拉取；日常更新请只 pull mebox。
+    # MetaTube 与 MeBox 共用本实例（不同数据库），无需第二套 PostgreSQL。
+    pull_policy: missing
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: mebox
+      POSTGRES_USER: mebox
+      POSTGRES_PASSWORD: mebox
+      TZ: Asia/Shanghai
+    volumes:
+      # 同时存放 mebox 与 metatube 两个数据库，备份这一个目录即可。
+      - ./postgres:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U mebox -d mebox"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "3"
+
+  # 一次性容器：确保 metatube 库存在。
+  # MetaTube 自己的 -db-auto-migrate 只建表不建库，所以必须先建库。
+  # 数据库已存在时它会直接退出，重复执行无副作用。
+  metatube-db-init:
+    image: postgres:16-alpine
+    pull_policy: missing
+    restart: "no"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      PGPASSWORD: mebox
+    entrypoint: ["/bin/sh", "-c"]
+    command:
+      - |
+        psql -h postgres -U mebox -d mebox -tAc "SELECT 1 FROM pg_database WHERE datname='metatube'" | grep -q 1 || psql -h postgres -U mebox -d mebox -c "CREATE DATABASE metatube OWNER mebox"
+    logging:
+      driver: json-file
+      options:
+        max-size: "5m"
+        max-file: "1"
+
+  metatube:
+    image: ghcr.io/metatube-community/metatube-server:latest
+    restart: unless-stopped
+    depends_on:
+      metatube-db-init:
+        condition: service_completed_successfully
+    environment:
+      TZ: Asia/Shanghai
+      # 需要走代理时在这里填写，例如 http://192.168.1.2:7890
+      HTTP_PROXY: ""
+      HTTPS_PROXY: ""
+    # 不需要 ports：MeBox 通过内部网络访问 http://metatube:8080。
+    # 只有想让局域网内其他工具直连时才映射，且建议只映射到 127.0.0.1。
+    command:
+      - -dsn
+      - postgres://mebox:mebox@postgres:5432/metatube?sslmode=disable
+      - -port
+      - "8080"
+      - -db-auto-migrate
+      - -db-prepared-stmt
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "3"
+
+  redis:
+    image: redis:7-alpine
+    pull_policy: missing
+    restart: unless-stopped
+    command:
+      - redis-server
+      - --appendonly
+      - "yes"
+      - --maxmemory
+      - 256mb
+      - --maxmemory-policy
+      - allkeys-lru
+    volumes:
+      - ./redis:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "3"

docker-compose.search.yml

@@ -81,8 +81,8 @@ services:
       MEBOX_LOGGING_LEVEL: info
       MEBOX_LOGGING_FORMAT: console
       MEBOX_LOGGING_OUTPUT_PATH: /data/logs
-      MEBOX_LOGGING_MAX_SIZE_MB: "50"
-      MEBOX_LOGGING_MAX_BACKUPS: "20"
+      MEBOX_LOGGING_MAX_SIZE_MB: "20"
+      MEBOX_LOGGING_MAX_BACKUPS: "5"
       MEBOX_LOGGING_MAX_AGE_DAYS: "30"
 
       MEBOX_DATABASE_TYPE: postgres
@@ -124,8 +124,8 @@ services:
     logging:
       driver: json-file
       options:
-        max-size: "50m"
-        max-file: "10"
+        max-size: "20m"
+        max-file: "3"
 
   postgres:
     image: postgres:16-alpine
@@ -147,8 +147,8 @@ services:
     logging:
       driver: json-file
       options:
-        max-size: "50m"
-        max-file: "10"
+        max-size: "20m"
+        max-file: "3"
 
   redis:
     image: redis:7-alpine
@@ -172,8 +172,8 @@ services:
     logging:
       driver: json-file
       options:
-        max-size: "50m"
-        max-file: "10"
+        max-size: "20m"
+        max-file: "3"
 
   opensearch:
     image: opensearchproject/opensearch:2
@@ -196,5 +196,5 @@ services:
     logging:
       driver: json-file
       options:
-        max-size: "50m"
-        max-file: "10"
+        max-size: "20m"
+        max-file: "3"

docker-compose.simple.yml

@@ -64,8 +64,8 @@ services:
       MEBOX_LOGGING_LEVEL: info
       MEBOX_LOGGING_FORMAT: console
       MEBOX_LOGGING_OUTPUT_PATH: /data/logs
-      MEBOX_LOGGING_MAX_SIZE_MB: "50"
-      MEBOX_LOGGING_MAX_BACKUPS: "20"
+      MEBOX_LOGGING_MAX_SIZE_MB: "20"
+      MEBOX_LOGGING_MAX_BACKUPS: "5"
       MEBOX_LOGGING_MAX_AGE_DAYS: "30"
 
     extra_hosts:
@@ -82,5 +82,5 @@ services:
     logging:
       driver: json-file
       options:
-        max-size: "50m"
-        max-file: "10"
+        max-size: "20m"
+        max-file: "3"

docker-compose.standard.yml

@@ -44,30 +44,13 @@ services:
       # NAS 示例：source: /vol1/1000/Media
       # Windows Docker Desktop 示例：source: D:/Media
       # create_host_path=false 可以避免路径写错时 Docker 自动创建空文件夹。
-      - type: bind
-        source: ./media
-        target: /media
-        bind:
-          create_host_path: false
-
-      # 下载目录。需要和下载器保存路径保持一致。
-      # NAS 示例：source: /vol1/1000/Downloads
-      # Windows Docker Desktop 示例：source: D:/Downloads
-      - type: bind
-        source: ./downloads
-        target: /downloads
-        bind:
-          create_host_path: false
-
-      # 管理面板「系统更新」需要访问 Docker 引擎。
-      # 需要一键更新 Docker 镜像时取消下一行注释。
-      # - /var/run/docker.sock:/var/run/docker.sock
+      - ./media: /media
 
     environment:
       TZ: Asia/Shanghai
 
-      PUID: "1000"
-      PGID: "1000"
+      PUID: "0"
+      PGID: "0"
 
       MEBOX_APP_HOST: 0.0.0.0
       MEBOX_APP_PORT: 8080
@@ -76,8 +59,8 @@ services:
       MEBOX_LOGGING_LEVEL: info
       MEBOX_LOGGING_FORMAT: console
       MEBOX_LOGGING_OUTPUT_PATH: /data/logs
-      MEBOX_LOGGING_MAX_SIZE_MB: "50"
-      MEBOX_LOGGING_MAX_BACKUPS: "20"
+      MEBOX_LOGGING_MAX_SIZE_MB: "20"
+      MEBOX_LOGGING_MAX_BACKUPS: "5"
       MEBOX_LOGGING_MAX_AGE_DAYS: "30"
 
       MEBOX_DATABASE_TYPE: postgres
@@ -113,8 +96,8 @@ services:
     logging:
       driver: json-file
       options:
-        max-size: "50m"
-        max-file: "10"
+        max-size: "20m"
+        max-file: "3"
 
   postgres:
     image: postgres:16-alpine
@@ -136,8 +119,8 @@ services:
     logging:
       driver: json-file
       options:
-        max-size: "50m"
-        max-file: "10"
+        max-size: "20m"
+        max-file: "3"
 
   redis:
     image: redis:7-alpine
@@ -161,5 +144,5 @@ services:
     logging:
       driver: json-file
       options:
-        max-size: "50m"
-        max-file: "10"
+        max-size: "20m"
+        max-file: "3"

docker-compose.yml

@@ -92,8 +92,8 @@ services:
       MEBOX_LOGGING_LEVEL: info
       MEBOX_LOGGING_FORMAT: console
       MEBOX_LOGGING_OUTPUT_PATH: /data/logs
-      MEBOX_LOGGING_MAX_SIZE_MB: "50"
-      MEBOX_LOGGING_MAX_BACKUPS: "20"
+      MEBOX_LOGGING_MAX_SIZE_MB: "20"
+      MEBOX_LOGGING_MAX_BACKUPS: "5"
       MEBOX_LOGGING_MAX_AGE_DAYS: "30"
 
       # 轻量模式默认只使用 PostgreSQL，适合大多数 NAS。
@@ -141,8 +141,8 @@ services:
     logging:
       driver: json-file
       options:
-        max-size: "50m"
-        max-file: "10"
+        max-size: "20m"
+        max-file: "3"
 
   postgres:
     image: postgres:16-alpine
@@ -166,5 +166,5 @@ services:
     logging:
       driver: json-file
       options:
-        max-size: "50m"
-        max-file: "10"
+        max-size: "20m"
+        max-file: "3"

docs/forum-post.md

@@ -1,190 +0,0 @@
-# 【开源推荐】MeBox：把 NAS / 网盘 / 远程 Emby 统一家里的观影入口，Docker 一键部署
-
-> 配图已托管在 GitHub 仓库（`raw.githubusercontent.com` 直链），发帖时可直接引用，或下载 `docs/tutorial-screenshots/` 后作为附件上传。
-
----
-
-## 写在前面
-
-给论坛的朋友们推荐一个我维护的开源项目 —— **MeBox**，一个面向 NAS 与家庭影音场景的**自托管私人媒体中心**（GPL-3.0，Go + React）。
-
-GitHub：https://github.com/truewhile/MeBox
-
-一句话介绍：**部署一个服务，同时获得媒体库后台、网盘 STRM 整理、Emby 客户端协议网关三件套。** 内置完整 Emby/Jellyfin 服务端协议实现——手机、电视、平板上的 Infuse、SenPlayer、Fileball、Emby/Jellyfin 官方客户端直接「添加 Emby 服务器」就能连，一套账号体系全搞定，Emby 老用户零学习成本。
-
-项目 fork 自 MediaStationGo 并持续二开，围绕网盘播放、任务队列、远程挂载和权限体系做了大量增强。
-
----
-
-## 它能解决什么问题？
-
-家里看电影电视的痛点，MeBox 基本一把梭：
-
-| 痛点 | MeBox 的解法 |
-| --- | --- |
-| 硬盘散落各处，海报墙乱七八糟 | 多根目录媒体库 + TMDb/Bangumi/Douban 自动刮削，海报墙、继续观看、多季剧集一应俱全 |
-| 网盘资源看一部下一部太麻烦 | OpenList / CloudDrive2 / 115 / WebDAV 接入，STRM 同步 + 直链/302 播放，不占本地空间 |
-| 已经有一台 Emby，出门还得开 App | **远程 Emby 挂载**：把远程 Emby 的媒体库直接挂进 MeBox 界面统一浏览 |
-| 家人乱动设置、小孩看不该看的 | 多用户 + 有效期 + 成人内容开关 + 播放配置 PIN，细粒度权限 |
-| 每个设备装一套专属 App 太折腾 | **完整兼容 Emby/Jellyfin 客户端**：Infuse、SenPlayer、Fileball、官方客户端按「添加 Emby 服务器」填地址 + MeBox 账号即可，海报墙、观看进度、多用户直接同步 |
-
----
-
-## 特点一览
-
-**1. 现代化 Web UI，海报墙开箱即用**
-
-![登录页](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/01-login.png)
-
-深色系登录页，默认账号 `admin / admin123`（首次登录请立即改密）。
-
-![首页](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/02-home.png)
-
-首页自带焦点推荐轮播 + 媒体库入口卡片，继续观看、最近添加直接呈现。
-
-**2. 媒体库与刮削**
-
-![媒体库总览](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/03-libraries.png)
-
-20 个媒体库、1600+ 条目一眼尽收：每库自带封面拼贴、条目数统计，支持「全库修复+重刮」「刮削队列」批量处理。
-
-![海报墙](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/04-library-posters.png)
-
-库内海报墙带评分、集数角标，支持按最后集添加日期排序，点开即看。
-
-**3. 详情页与多季管理**
-
-![详情页](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/05-media-detail.png)
-
-剧情简介、类型标签、多季分集（特别篇/第 1-N 季）、每集缩略图与时长；一键立即播放、调用外部播放器、加入收藏。
-
-**4. Emby/Jellyfin 客户端无缝兼容**
-
-这是我最想强调的一点：**MeBox 内置了完整的 Emby 服务端协议实现**。手机、电视、平板上的 Infuse、SenPlayer、Fileball，甚至 Emby/Jellyfin 官方客户端，都不需要任何插件或改造——按「添加 Emby 服务器」填入 `http://服务器IP:18080`，用 MeBox 账号登录，海报墙、观看进度、收藏、多用户权限全部无缝衔接。已经习惯 Emby 生态的朋友可以零成本迁移，家人只用电视端 App 也完全无感。
-
-**5. 网页播放器 + 弹幕自动匹配**
-
-![播放器与弹幕](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/06-player-danmu.png)
-
-内置网页播放器支持 HLS 转码、字幕、播放配置档；**弹幕按剧名自动匹配全季分集**（截图中自动匹配到《一拳超人》39 集），屏幕占比/透明度/字号随意调，追新番体验直接拉满。
-
-**6. 网盘 STRM：网盘当本地盘用**
-
-![STRM 管理](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/07-strm-cloud.png)
-
-添加网盘账号（**115 支持二维码扫码登录**）→ 添加同步目录 → 系统把网盘/本地目录里的视频生成 `.strm` 文件，元数据经下载/上传队列双向同步，播放走直链/302 不落盘。
-
-**7. 远程 Emby 挂载（特色功能）**
-
-![Emby 挂载](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/08-emby-mount.png)
-
-已有远程 Emby 服务器？填一次账号，按需勾选要挂载的媒体库（支持同服务器多线路自动切换、直连开关、排序），远程库直接出现在 MeBox 首页，不必再开 Emby 客户端。
-
-**8. 任务队列统一管理**
-
-![任务队列](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/09-task-queue.png)
-
-刮削 / 下载 / 上传三类任务统一看板，排队中、进行中、已匹配、失败分类计数，支持搜索与批量清理。
-
-**9. 下载与自动整理**
-
-![文件管理](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/11-file-manager.png)
-
-配合任意下载器（qBittorrent、Transmission 等下载到本地目录即可），MeBox 定时自动整理入媒体库：智能分类子库、自动注册目的地媒体库、复制/移动/硬链/软链多种整理方式，命名规则可配。
-
-**10. 多用户与权限**
-
-![用户管理](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/12-user-admin.png)
-
-管理员/普通用户分级、单实例用户数上限、账号有效期、成人内容开关、播放配置 PIN——给家人开号放心给。
-
-**11. 运维省心**
-
-![系统设置](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/10-settings.png)
-
-FFmpeg/FFprobe 一键下载安装、转码与硬件加速开关、TMDb 语言、识别词、弹幕、Adult/NSFW 开关全在设置页分组管理；另有 DLNA 投屏、存储统计、海报墙聚合视图：
-
-![海报墙聚合](https://raw.githubusercontent.com/truewhile/MeBox/main/docs/tutorial-screenshots/13-poster-wall.png)
-
----
-
-## 使用教程：从零到海报墙只要 5 步
-
-### 第 1 步：Docker 一键部署
-
-推荐 Docker Compose（仓库提供 4 份互相独立的完整模板，无需 `.env`）：
-
-```bash
-mkdir -p MeBox && cd MeBox
-
-# 最省心：单镜像 + 内置 SQLite
-curl -fsSL https://raw.githubusercontent.com/truewhile/MeBox/main/docker-compose.simple.yml -o docker-compose.yml
-
-# 多用户/大数据量可选 PostgreSQL 档、Redis 档、OpenSearch 档，见仓库 README「部署档位」
-
-docker compose up -d
-```
-
-浏览器访问 `http://服务器IP:18080`，镜像：`ghcr.io/truewhile/mebox:latest`（amd64 / arm64 都有，也提供 Windows/Linux/macOS 单文件可执行程序，不想装 Docker 直接下载跑）。
-
-### 第 2 步：登录并修改密码
-
-默认账号 `admin / admin123`，登录后右上角头像 → 个人资料修改密码。
-
-### 第 3 步：创建媒体库 + 扫库
-
-后台 → 媒体库 → 管理媒体库，添加本地路径（Docker 部署记得填**容器内**路径，如 `/media/电影`，`volumes` 左侧挂宿主机真实目录）→ 执行扫库。
-
-### 第 4 步：配置元数据刮削
-
-系统设置 → 外部 API，填入 TMDb / Bangumi / Douban 等 API Key；媒体库页可对单个库「全库修复+重刮」，刮削进度在任务队列实时可见。
-
-### 第 5 步（可选但强烈推荐）：
-
-- **网盘用户**：STRM 管理 → 添加网盘账号（115 可扫码）→ 添加同步目录 → 生成 STRM 后直链播放；
-- **已有 Emby**：Emby 挂载 → 添加 Emby 账号 → 勾选要挂载的媒体库；
-- **第三方播放器（Emby 客户端全兼容）**：Infuse / SenPlayer / Fileball / Emby、Jellyfin 官方客户端，按「添加 Emby 服务器」填 `http://服务器IP:18080`，用 MeBox 账号登录即可，原有使用习惯完全不变；
-- **下载党**：qBittorrent 等任意下载器把视频下到下载目录，在文件管理里把它设为整理源，下完自动分类入库。
-
-### 路径映射小抄（Docker 最常见坑）
-
-```yaml
-volumes:
-  - /vol1/1000/Media:/media        # 左：宿主机真实路径；右：容器内路径（网页里填这个）
-environment:
-  MEBOX_MEDIA_DIR: /vol1/1000/Media
-  MEBOX_MEDIA_CONTAINER_DIR: /media
-```
-
-硬链接要求同一文件系统/子卷，跨盘请改复制或软链。
-
----
-
-## 部署档位怎么选？
-
-| 档位 | 文件 | 组件 | 适合 |
-| --- | --- | --- | --- |
-| 极简 | `docker-compose.simple.yml` | 单镜像 + SQLite | 个人使用、低配设备 |
-| 标准 | `docker-compose.yml` | + PostgreSQL | 多用户家庭共享 |
-| 增强 | `docker-compose.standard.yml` | + Redis | 大媒体库高频访问 |
-| 搜索 | `docker-compose.search.yml` | + OpenSearch | 超大库全文搜索 |
-
----
-
-## 技术栈与致谢
-
-- 后端：Go · Gin · GORM · SQLite/PostgreSQL · 可选 Redis / OpenSearch
-- 前端：React 18 · Vite · TypeScript · Tailwind CSS · Zustand
-- 部署：Docker Compose 多档模板，amd64/arm64 镜像 + 单文件可执行
-
-感谢上游 [MediaStationGo](https://github.com/ShukeBta/MediaStationGo) 的奠基，网盘同步/STRM/整理部分参考了 [qmediasync](https://github.com/qicfan/qmediasync) 的思路。
-
----
-
-## 链接
-
-- GitHub：https://github.com/truewhile/MeBox
-- Issue / PR：欢迎提 bug（附部署方式+复现步骤+日志）与功能建议
-- License：GPL-3.0
-
-觉得有用的话求个 Star ⭐，也欢迎论坛里的朋友反馈使用体验，我长期维护。

docs/superpowers/plans/2026-09-24-segment-coverage.md

@@ -0,0 +1,36 @@
+# Segment Coverage Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** IntroDB prewarm + same-season intro propagation + shorter miss TTL + playback-only duration probe (option C).
+
+**Architecture:** Extend `MediaSegmentService` for merge/propagate/prewarm; add scheduler job `segment_prewarm`; repository queries for candidates and season siblings.
+
+**Tech Stack:** Go, GORM/SQLite, existing SchedulerService + IntroDB client.
+
+---
+
+### Task 1: Negative cache TTL + ledgerFresh tests
+
+**Files:** `internal/service/media_segment.go`, `internal/service/media_segment_test.go`
+
+- Change `segmentMissingTTL` to 24h; update tests for fresh/stale miss.
+
+### Task 2: Playback merge + propagation
+
+**Files:** `media_segment.go`, `media_segment_repository.go`, `media_repository.go`, tests
+
+- Constant `PropagatedSource = "propagated"`.
+- `ListForPlayback` merges sources with priority manual > theintrodb > propagated.
+- After successful IntroDB refresh with intro, propagate to same-season siblings (shared `tm_db_id` or `series_id`).
+
+### Task 3: Prewarm API + scheduler job
+
+**Files:** `media_segment.go`, `media_segment_repository.go`, `scheduler.go`, `scheduler_segment_jobs.go`, `service_builder.go`, tests
+
+- `Prewarm(ctx, limit)` rate-limited refreshes.
+- Job `segment_prewarm` every 6h.
+
+### Task 4: Verify
+
+- `go test` for affected packages.

docs/superpowers/specs/2026-09-24-segment-coverage-design.md

@@ -0,0 +1,52 @@
+# Segment Coverage Improvements (1–4, option C)
+
+## Goal
+
+Raise intro/outro skip availability without Chromaprint or full-library STRM probing.
+
+## Scope (approved)
+
+1. **IntroDB prewarm** — background job for all queryable media (TMDb + season/episode).
+2. **Duration** — playback-path only (no full STRM scan); keep `ListForPlayback` → `EnsureAsync`.
+3. **Same-season intro propagation** — copy intro to sibling episodes after a hit.
+4. **Negative cache** — miss TTL 24h; 403/429/timeout must not write miss ledger.
+
+## Non-goals
+
+Chromaprint, manual segment UI, library-name filters, batch STRM duration scan.
+
+## Behavior
+
+### Prewarm (`segment_prewarm`)
+
+- Scheduler job, interval 6h, initial delay 6h (avoid restart spike).
+- **Opt-in via `segment.prewarm_enabled` (default off)** — system settings toggle「后台预热 IntroDB 片头片段」.
+- Candidates: `tm_db_id > 0`, season/episode or movie, ledger missing or stale.
+- Order: recently played first, then others.
+- Rate: ~1 req/s, stop on context cancel; respect IntroDB 429 retry already in client.
+- Reuse `MediaSegmentService` refresh + propagation.
+- Manual `RunNow` can bypass the toggle (same pattern as organize).
+
+### Propagation
+
+- After TheIntroDB refresh finds at least one `intro` span, write the same intro window to same-season siblings that lack a `theintrodb` intro.
+- Source tag: `propagated`.
+- Do not propagate credits/preview/recap.
+- Playback merge priority per kind: `manual` > `theintrodb` > `propagated`.
+
+### Negative cache
+
+- `segmentMissingTTL`: 24h (was 7d).
+- `segmentFoundTTL`: 30d (unchanged).
+- Provider errors (non-404) continue to skip ledger writes.
+
+### Duration (C)
+
+- No new batch probe job.
+- Existing `defer ensureMediaProbe` on playback remains the only STRM duration path.
+
+## Success criteria
+
+- Prewarm increases `media_segment_fetches` over time without blocking play.
+- One IntroDB intro hit can surface skip on sibling episodes via `propagated`.
+- Misses are retried within ~24h (sooner if recently played and prewarm runs).

go.mod

@@ -3,6 +3,7 @@ module github.com/truewhile/MeBox
 go 1.25.0
 
 require (
+	fyne.io/systray v1.12.2
 	github.com/aliyun/alibabacloud-oss-go-sdk-v2 v1.5.2
 	github.com/fsnotify/fsnotify v1.7.0
 	github.com/gin-contrib/gzip v1.2.6
@@ -12,16 +13,16 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/metatube-community/metatube-sdk-go v1.4.0
-	github.com/redis/go-redis/v9 v9.7.0
+	github.com/redis/go-redis/v9 v9.7.3
 	github.com/shirou/gopsutil/v3 v3.24.5
 	github.com/spf13/viper v1.18.2
 	github.com/stretchr/testify v1.11.1
-	github.com/ulikunitz/xz v0.5.12
+	github.com/ulikunitz/xz v0.5.15
 	go.uber.org/zap v1.27.0
 	golang.org/x/crypto v0.49.0
-	golang.org/x/image v0.37.0
-	golang.org/x/sync v0.20.0
-	golang.org/x/sys v0.42.0
+	golang.org/x/image v0.45.0
+	golang.org/x/sync v0.22.0
+	golang.org/x/sys v0.47.0
 	golang.org/x/time v0.15.0
 	gopkg.in/yaml.v3 v3.0.1
 	gorm.io/driver/postgres v1.6.0
@@ -48,10 +49,11 @@ require (
 	github.com/go-playground/validator/v10 v10.30.1 // indirect
 	github.com/goccy/go-json v0.10.6 // indirect
 	github.com/goccy/go-yaml v1.19.2 // indirect
+	github.com/godbus/dbus/v5 v5.1.0 // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
-	github.com/jackc/pgx/v5 v5.8.0 // indirect
+	github.com/jackc/pgx/v5 v5.9.2 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
@@ -69,7 +71,7 @@ require (
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
 	github.com/quic-go/qpack v0.6.0 // indirect
-	github.com/quic-go/quic-go v0.59.0 // indirect
+	github.com/quic-go/quic-go v0.59.1 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/sagikazarmark/locafero v0.4.0 // indirect
 	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
@@ -89,7 +91,7 @@ require (
 	golang.org/x/arch v0.25.0 // indirect
 	golang.org/x/exp v0.0.0-20251023183803-a4bb9ffd2546 // indirect
 	golang.org/x/net v0.52.0 // indirect
-	golang.org/x/text v0.35.0 // indirect
+	golang.org/x/text v0.41.0 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	modernc.org/libc v1.70.0 // indirect

go.sum

@@ -1,3 +1,5 @@
+fyne.io/systray v1.12.2 h1:Y8DZxgLHsVQt6rY9Zrkkg+j67S7vv/1F2viOWKPpVeA=
+fyne.io/systray v1.12.2/go.mod h1:RVwqP9nYMo7h5zViCBHri2FgjXF7H2cub7MAq4NSoLs=
 github.com/aliyun/alibabacloud-oss-go-sdk-v2 v1.5.2 h1:40yUSXwdkWN851BHCq6uiDhleh7A4+0yIBS+IUAqZVY=
 github.com/aliyun/alibabacloud-oss-go-sdk-v2 v1.5.2/go.mod h1:FTzydeQVmR24FI0D6XWUOMKckjXehM/jgMn1xC+DA9M=
 github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
@@ -56,6 +58,8 @@ github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU=
 github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
 github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
+github.com/godbus/dbus/v5 v5.1.0 h1:4KLkAxT3aOY8Li4FRJe/KvhoNFFxo0m6fNuFUO8QJUk=
+github.com/godbus/dbus/v5 v5.1.0/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
 github.com/golang-jwt/jwt/v5 v5.2.2 h1:Rl4B7itRWVtYIHFrSNd7vhTiz9UpLdi6gZhZ3wEeDy8=
 github.com/golang-jwt/jwt/v5 v5.2.2/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
 github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
@@ -77,8 +81,8 @@ github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsI
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
-github.com/jackc/pgx/v5 v5.8.0 h1:TYPDoleBBme0xGSAX3/+NujXXtpZn9HBONkQC7IEZSo=
-github.com/jackc/pgx/v5 v5.8.0/go.mod h1:QVeDInX2m9VyzvNeiCJVjCkNFqzsNb43204HshNSZKw=
+github.com/jackc/pgx/v5 v5.9.2 h1:3ZhOzMWnR4yJ+RW1XImIPsD1aNSz4T4fyP7zlQb56hw=
+github.com/jackc/pgx/v5 v5.9.2/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
@@ -121,10 +125,10 @@ github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c h1:ncq/mPwQF
 github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
 github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII=
-github.com/quic-go/quic-go v0.59.0 h1:OLJkp1Mlm/aS7dpKgTc6cnpynnD2Xg7C1pwL6vy/SAw=
-github.com/quic-go/quic-go v0.59.0/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
-github.com/redis/go-redis/v9 v9.7.0 h1:HhLSs+B6O021gwzl+locl0zEDnyNkxMtf/Z3NNBMa9E=
-github.com/redis/go-redis/v9 v9.7.0/go.mod h1:f6zhXITC7JUJIlPEiBOTXxJgPLdZcA93GewI7inzyWw=
+github.com/quic-go/quic-go v0.59.1 h1:0Gmua0HW1Tv7ANR7hUYwRyD0MG5OJfgvYSZasGZzBic=
+github.com/quic-go/quic-go v0.59.1/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
+github.com/redis/go-redis/v9 v9.7.3 h1:YpPyAayJV+XErNsatSElgRZZVCwXX9QzkKYNvO7x0wM=
+github.com/redis/go-redis/v9 v9.7.3/go.mod h1:bGUrSggJ9X9GUmZpZNEOQKaANxSGgOEBRltRTZHSvrA=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
 github.com/rogpeppe/go-internal v1.11.0 h1:cWPaGQEPrBb5/AsnsZesgZZ9yb1OQ+GOISoDNXVBh4M=
@@ -171,8 +175,8 @@ github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
 github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
-github.com/ulikunitz/xz v0.5.12 h1:37Nm15o69RwBkXM0J6A5OlE67RZTfzUxTj8fB3dfcsc=
-github.com/ulikunitz/xz v0.5.12/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oWt/14=
+github.com/ulikunitz/xz v0.5.15 h1:9DNdB5s+SgV3bQ2ApL10xRc35ck0DuIX/isZvIk+ubY=
+github.com/ulikunitz/xz v0.5.15/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oWt/14=
 github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
 github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
 go.mongodb.org/mongo-driver/v2 v2.5.0 h1:yXUhImUjjAInNcpTcAlPHiT7bIXhshCTL3jVBkF3xaE=
@@ -192,28 +196,28 @@ golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtC
 golang.org/x/exp v0.0.0-20251023183803-a4bb9ffd2546 h1:mgKeJMpvi0yx/sU5GsxQ7p6s2wtOnGAHZWCHUM4KGzY=
 golang.org/x/exp v0.0.0-20251023183803-a4bb9ffd2546/go.mod h1:j/pmGrbnkbPtQfxEe5D0VQhZC6qKbfKifgD0oM7sR70=
 golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8/go.mod h1:FeLwcggjj3mMvU+oOTbSwawSJRM1uh48EjtB4UJZlP0=
-golang.org/x/image v0.37.0 h1:ZiRjArKI8GwxZOoEtUfhrBtaCN+4b/7709dlT6SSnQA=
-golang.org/x/image v0.37.0/go.mod h1:/3f6vaXC+6CEanU4KJxbcUZyEePbyKbaLoDOe4ehFYY=
-golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
-golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
+golang.org/x/image v0.45.0 h1:FMb1nTbH5H9vF55SriQHgFw5GnNL9Jg6L25BwXKzhB0=
+golang.org/x/image v0.45.0/go.mod h1:n62x/7RqlwXDvGsSU4u6IUTUf6KghUZ9Bt7cG/T9Fx4=
+golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
+golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
 golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
 golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.11.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
-golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
-golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
-golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
+golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
+golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
-golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
-golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
+golang.org/x/tools v0.48.0 h1:3+hClM1aLL5mjMKm5ovokw9epgRXPuu2tILgismM6RE=
+golang.org/x/tools v0.48.0/go.mod h1:08xX0orndb/F7jJxGDicx061tyd5pcMto75YMAXr6lk=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=

internal/brand/brand.go

@@ -0,0 +1,10 @@
+// Package brand contains the embedded MeBox application artwork.
+package brand
+
+import _ "embed"
+
+// Icon is the Windows ICO used by both the executable resource and the
+// notification-area icon.
+//
+//go:embed logo.ico
+var Icon []byte

internal/config/defaults.go

@@ -44,9 +44,10 @@ func setDefaults(v *viper.Viper) {
 	v.SetDefault("logging.max_backups", 10)
 
 	v.SetDefault("cache.cache_dir", "./cache")
-	v.SetDefault("cache.images_max_size_mb", 500)
+	v.SetDefault("cache.images_max_size_mb", 2000)
+	v.SetDefault("cache.images_originals_max_size_mb", 256)
+	v.SetDefault("cache.images_originals_ttl_hours", 168)
 	v.SetDefault("cache.memory_max_size_mb", DefaultCacheMemoryMaxSizeMB)
-	v.SetDefault("cache.cleanup_interval_min", 60)
 	v.SetDefault("cache.redis_url", "")
 	v.SetDefault("cache.redis_prefix", "mebox")
 	v.SetDefault("cache.media_ttl_seconds", 90)

internal/config/normalize.go

@@ -47,6 +47,12 @@ func (c *Config) normalize() error {
 	if c.Cache.ImagesMaxSizeMB < 0 {
 		c.Cache.ImagesMaxSizeMB = 0
 	}
+	if c.Cache.ImagesOriginalsMaxSizeMB < 0 {
+		c.Cache.ImagesOriginalsMaxSizeMB = 0
+	}
+	if c.Cache.ImagesOriginalsTTLHours < 0 {
+		c.Cache.ImagesOriginalsTTLHours = 0
+	}
 	if c.Cache.MemoryMaxSizeMB <= 0 {
 		c.Cache.MemoryMaxSizeMB = DefaultCacheMemoryMaxSizeMB
 	}

internal/config/types.go

@@ -117,12 +117,14 @@ type LoggingConfig struct {
 type CacheConfig struct {
 	CacheDir        string `mapstructure:"cache_dir"`
 	ImagesMaxSizeMB int    `mapstructure:"images_max_size_mb"`
+	// ImagesOriginalsMaxSizeMB 限制 cache/images 下原图子配额（MB）。原图只是
+	// 生成缩略图的原料，丢了可以重新回源；0 表示不单独限制（只受总量约束）。
+	ImagesOriginalsMaxSizeMB int `mapstructure:"images_originals_max_size_mb"`
+	// ImagesOriginalsTTLHours 是原图的保留时长（小时），超过即删除；0 表示
+	// 不按时间淘汰。缩短它能让原图缓存保持在一个滚动窗口内。
+	ImagesOriginalsTTLHours int `mapstructure:"images_originals_ttl_hours"`
 	// MemoryMaxSizeMB 限制进程内 L1 缓存总字节数，JSON/对象缓存共用该预算。
 	MemoryMaxSizeMB int    `mapstructure:"memory_max_size_mb"`
-	MaxDiskUsageMB     int    `mapstructure:"max_disk_usage_mb"`
-	TTLHours           int    `mapstructure:"ttl_hours"`
-	AutoCleanup        bool   `mapstructure:"auto_cleanup"`
-	CleanupIntervalMin int    `mapstructure:"cleanup_interval_min"`
 	RedisURL        string `mapstructure:"redis_url"`
 	RedisPrefix     string `mapstructure:"redis_prefix"`
 	MediaTTLSeconds int    `mapstructure:"media_ttl_seconds"`

internal/database/database.go

@@ -127,5 +127,10 @@ func (z zapStdLogger) Printf(format string, args ...interface{}) {
 	if z.log == nil {
 		return
 	}
-	z.log.Sugar().Infof(format, args...)
+	message := fmt.Sprintf(format, args...)
+	if strings.Contains(strings.ToLower(message), "context canceled") {
+		z.log.Debug(message)
+		return
+	}
+	z.log.Info(message)
 }

internal/database/schema_migration.go

@@ -99,6 +99,11 @@ func ensurePerformanceIndexes(db *gorm.DB) error {
 		`CREATE INDEX IF NOT EXISTS idx_media_library_episode_active ON media(library_id, season_num, episode_num, created_at DESC) WHERE deleted_at IS NULL`,
 		`CREATE INDEX IF NOT EXISTS idx_media_library_root_active ON media(library_id, library_root_id) WHERE deleted_at IS NULL`,
 		`CREATE INDEX IF NOT EXISTS idx_media_series_active ON media(series_id, season_num, episode_num) WHERE deleted_at IS NULL`,
+		`CREATE INDEX IF NOT EXISTS idx_media_library_series_active ON media(library_id, series_id, season_num, episode_num) WHERE deleted_at IS NULL`,
+		`CREATE INDEX IF NOT EXISTS idx_media_library_tmdb_active ON media(library_id, tm_db_id) WHERE deleted_at IS NULL`,
+		`CREATE INDEX IF NOT EXISTS idx_media_library_bangumi_active ON media(library_id, bangumi_id) WHERE deleted_at IS NULL`,
+		`CREATE INDEX IF NOT EXISTS idx_media_library_douban_active ON media(library_id, douban_id) WHERE deleted_at IS NULL`,
+		`CREATE INDEX IF NOT EXISTS idx_media_library_thetvdb_active ON media(library_id, thetvdb_id) WHERE deleted_at IS NULL`,
 		`CREATE INDEX IF NOT EXISTS idx_favorites_user_media_active ON favorites(user_id, media_id) WHERE deleted_at IS NULL`,
 		`CREATE INDEX IF NOT EXISTS idx_playback_histories_user_media_active ON playback_histories(user_id, media_id, watched_at DESC) WHERE deleted_at IS NULL`,
 		`CREATE INDEX IF NOT EXISTS idx_playback_histories_resume_active ON playback_histories(user_id, completed, watched_at DESC) WHERE deleted_at IS NULL`,

internal/handler/admin_settings.go

@@ -20,6 +20,12 @@ type settingReq struct {
 	Value string `json:"value"`
 }
 
+// maskedSettingKeys 里的设置值绝不能被完整下发：它们是可用于对外操作的凭据。
+// 下发脱敏值，保存时再靠 isMaskedSettingValue 还原为「保持原值」。
+var maskedSettingKeys = map[string]bool{
+	service.SettingTelegramBotToken: true,
+}
+
 func listSettingsHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		settings, err := svc.Repo.Setting.All(c.Request.Context())
@@ -27,10 +33,21 @@ func listSettingsHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
 		}
+		for i := range settings {
+			if maskedSettingKeys[settings[i].Key] {
+				settings[i].Value = service.MaskSecret(settings[i].Value)
+			}
+		}
 		c.JSON(http.StatusOK, settings)
 	}
 }
 
+// isMaskedSettingValue 识别「前端把脱敏值原样提交回来」的情况。此时必须保留
+// 已存的真实值，否则一次保存就会把凭据覆盖成 ***。
+func isMaskedSettingValue(value string) bool {
+	return strings.Contains(value, "***")
+}
+
 func updateSettingHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		var req settingReq
@@ -38,6 +55,11 @@ func updateSettingHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
+		// 脱敏值回传 == 用户没改这个凭据，保留库里已存的真实值。
+		if maskedSettingKeys[req.Key] && isMaskedSettingValue(req.Value) {
+			c.Status(http.StatusNoContent)
+			return
+		}
 		oldValue := ""
 		if req.Key == service.AdultLibraryIDsSettingKey {
 			oldValue, _ = svc.Repo.Setting.Get(c.Request.Context(), req.Key)
@@ -65,9 +87,11 @@ func updateSettingHandler(svc *service.Container) gin.HandlerFunc {
 		if req.Key == "transcode.hw_enabled" || req.Key == "transcode.hw_accel" || req.Key == "transcoder.hardware_accel" || req.Key == "transcoder.encoder" {
 			svc.Transcoder.StopAll()
 		}
-		if req.Key == "cache.images_max_size_mb" && svc.Scheduler != nil {
+		if req.Key == "cache.images_max_size_mb" || req.Key == "cache.images_originals_max_size_mb" || req.Key == "cache.images_originals_ttl_hours" {
+			if svc.Scheduler != nil {
 				_ = svc.Scheduler.RunNowAsync(c.Request.Context(), "image_cache_cleanup")
 			}
+		}
 		if req.Key == "cache.memory_max_size_mb" && svc.Cache != nil {
 			svc.Cache.SetMaxSizeMB(svc.Cfg.Cache.MemoryMaxSizeMB)
 		}

internal/handler/cloud115_playback.go

@@ -0,0 +1,148 @@
+package handler
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+func mediaPlaybackInfoHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc == nil || svc.Cloud115 == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "cloud115 playback unavailable"})
+			return
+		}
+		m, err := svc.Media.GetMedia(c.Request.Context(), c.Param("id"))
+		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
+			c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+			return
+		}
+		if !enforceScopedPlaybackToken(c, m.ID) {
+			return
+		}
+		quality, _ := strconv.Atoi(c.Query("quality"))
+		info, err := svc.Cloud115.PlaybackInfo(c.Request.Context(), m.ID, quality)
+		if err != nil {
+			if errors.Is(err, service.ErrMediaNotFound) {
+				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+				return
+			}
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, info)
+	}
+}
+
+func mediaTranscodeHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc == nil || svc.Cloud115 == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "cloud115 playback unavailable"})
+			return
+		}
+		m, err := svc.Media.GetMedia(c.Request.Context(), c.Param("id"))
+		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
+			c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+			return
+		}
+		if !enforceScopedPlaybackToken(c, m.ID) {
+			return
+		}
+		var req struct {
+			Definition int `json:"definition"`
+		}
+		_ = c.ShouldBindJSON(&req)
+		info, err := svc.Cloud115.StartTranscode(c.Request.Context(), m.ID, req.Definition)
+		if err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, info)
+	}
+}
+
+func cloud115HLSMasterHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc == nil || svc.Cloud115 == nil || svc.Cloud115.HLSProxy() == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "cloud115 playback unavailable"})
+			return
+		}
+		m, err := svc.Media.GetMedia(c.Request.Context(), c.Param("id"))
+		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
+			c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+			return
+		}
+		if !enforceScopedPlaybackToken(c, m.ID) {
+			return
+		}
+		definition, _ := strconv.Atoi(c.Query("definition"))
+		err = svc.Cloud115.HLSProxy().ServeMaster(c.Request.Context(), c.Writer, c.Request, m.ID, definition)
+		if err == nil {
+			return
+		}
+		if c.Writer.Written() {
+			return
+		}
+		if errors.Is(err, service.ErrCloud115TranscodePending) {
+			retryAfter := 5
+			message := "115 正在转码，请稍候"
+			var info *service.PlaybackInfo
+			if latest, infoErr := svc.Cloud115.PlaybackInfo(c.Request.Context(), m.ID, definition); infoErr == nil && latest != nil {
+				info = latest
+				if latest.Transcode.Message != "" {
+					message = latest.Transcode.Message
+				}
+				if latest.Transcode.RetryAfterSec > 0 {
+					retryAfter = latest.Transcode.RetryAfterSec
+				}
+			}
+			c.JSON(http.StatusConflict, gin.H{
+				"code":            "transcode_pending",
+				"message":         message,
+				"retry_after_sec": retryAfter,
+				"playback":        info,
+			})
+			return
+		}
+		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+	}
+}
+
+func cloud115HLSSessionHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc == nil || svc.Cloud115 == nil || svc.Cloud115.HLSProxy() == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "cloud115 playback unavailable"})
+			return
+		}
+		mediaID := c.Query("media_id")
+		if mediaID == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "missing media_id"})
+			return
+		}
+		if !enforceScopedPlaybackToken(c, mediaID) {
+			return
+		}
+		err := svc.Cloud115.HLSProxy().ServeChild(
+			c.Request.Context(),
+			c.Writer,
+			c.Request,
+			c.Param("session"),
+			c.Param("key"),
+		)
+		if err == nil || c.Writer.Written() {
+			return
+		}
+		switch {
+		case errors.Is(err, service.ErrCloud115HLSSessionNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": "hls session not found"})
+		case errors.Is(err, service.ErrCloud115HLSUpstreamExpired):
+			c.JSON(http.StatusGone, gin.H{"error": "hls upstream expired"})
+		default:
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+		}
+	}
+}

internal/handler/danmaku_settings_test.go

@@ -170,6 +170,72 @@ func TestUpdateDanmakuSettingsPersistsAllPlayerPreferences(t *testing.T) {
 	}
 }
 
+func TestUpdateDanmakuSettingsPersistsVr360GuideSeen(t *testing.T) {
+	svc := newDanmakuSettingsService(t)
+
+	// 默认未看过：配置接口必须先如实告知前端，否则首次操作说明会被跳过。
+	initial := svc.Danmaku.ConfigForUser(t.Context(), "user-1")
+	if initial.Vr360GuideSeen {
+		t.Fatal("vr360 guide should be unread for a fresh user")
+	}
+
+	c, w := newDanmakuSettingsContext(t, svc, http.MethodPut, "/danmaku/settings",
+		`{"vr360_guide_seen":true}`, "user-1")
+	updateDanmakuSettingsHandler(svc)(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (body=%s)", w.Code, w.Body.String())
+	}
+	var cfg service.DanmakuRenderConfig
+	if err := json.Unmarshal(w.Body.Bytes(), &cfg); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if !cfg.Vr360GuideSeen {
+		t.Fatalf("config should reflect the persisted guide flag: %+v", cfg)
+	}
+
+	user, err := svc.Repo.User.FindByID(t.Context(), "user-1")
+	if err != nil || user == nil {
+		t.Fatalf("read persisted user: %v", err)
+	}
+	if !user.PlayerVr360GuideSeen {
+		t.Fatalf("guide flag not persisted on the user: %+v", user)
+	}
+}
+
+// 播放倍速只作用于当前视频：接口既不下发也不保存它。老客户端仍可能带上
+// playback_rate，服务端应当忽略而不是报错。
+func TestDanmakuSettingsIgnorePlaybackRate(t *testing.T) {
+	svc := newDanmakuSettingsService(t)
+
+	c, w := newDanmakuSettingsContext(t, svc, http.MethodGet, "/danmaku/config", "", "user-1")
+	getDanmakuConfigHandler(svc)(c)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (body=%s)", w.Code, w.Body.String())
+	}
+	if bytes.Contains(w.Body.Bytes(), []byte("playback_rate")) {
+		t.Fatalf("config must not expose playback rate: %s", w.Body.String())
+	}
+
+	c2, w2 := newDanmakuSettingsContext(t, svc, http.MethodPut, "/danmaku/settings",
+		`{"volume":0.5,"playback_rate":1.5}`, "user-1")
+	updateDanmakuSettingsHandler(svc)(c2)
+
+	if w2.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (body=%s)", w2.Code, w2.Body.String())
+	}
+	if bytes.Contains(w2.Body.Bytes(), []byte("playback_rate")) {
+		t.Fatalf("settings response must not expose playback rate: %s", w2.Body.String())
+	}
+	user, err := svc.Repo.User.FindByID(t.Context(), "user-1")
+	if err != nil || user == nil {
+		t.Fatalf("read user: %v", err)
+	}
+	if user.PlayerVolume != 0.5 {
+		t.Fatalf("volume not persisted: %v", user.PlayerVolume)
+	}
+}
+
 func TestUpdateDanmakuSettingsRejectsInvalidSource(t *testing.T) {
 	svc := newDanmakuSettingsService(t)
 

internal/handler/devices.go

@@ -0,0 +1,173 @@
+package handler
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/truewhile/MeBox/internal/middleware"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// 设备管理接口。
+//
+// 普通用户只能操作自己的设备（路由挂在 /me 下，用户 ID 始终取自会话）；
+// 管理员通过 /admin/users/:id/devices 代管任意用户。两组接口共用同一份
+// DeviceService，因此「谁上线过、谁被踢掉」只有一处事实来源。
+
+// deviceListPayload 是设备列表的下发形状。Fingerprint 不外发：它是防共享
+// 判定用的内部标识，暴露出去只会方便伪造。
+type deviceListPayload struct {
+	Devices []devicePayload `json:"devices"`
+}
+
+type devicePayload struct {
+	ID         string `json:"id"`
+	DeviceID   string `json:"device_id"`
+	DeviceName string `json:"device_name,omitempty"`
+	Client     string `json:"client,omitempty"`
+	LastIP     string `json:"last_ip,omitempty"`
+	LastSeenAt string `json:"last_seen_at,omitempty"`
+	LastPlayAt string `json:"last_play_at,omitempty"`
+	Kicked     bool   `json:"kicked"`
+	Online     bool   `json:"online"`
+	Playing    bool   `json:"playing"`
+	Warnings   int    `json:"warnings"`
+}
+
+func toDevicePayload(d model.UserDevice) devicePayload {
+	out := devicePayload{
+		ID:         d.ID,
+		DeviceID:   d.DeviceID,
+		DeviceName: d.DeviceName,
+		Client:     d.Client,
+		LastIP:     d.LastIP,
+		Kicked:     d.Kicked,
+		Online:     d.Online,
+		Playing:    d.Playing,
+		Warnings:   d.Warnings,
+	}
+	if !d.LastSeenAt.IsZero() {
+		out.LastSeenAt = d.LastSeenAt.Format("2006-01-02T15:04:05Z07:00")
+	}
+	if d.LastPlayAt != nil && !d.LastPlayAt.IsZero() {
+		out.LastPlayAt = d.LastPlayAt.Format("2006-01-02T15:04:05Z07:00")
+	}
+	return out
+}
+
+func deviceListResponse(devices []model.UserDevice) deviceListPayload {
+	items := make([]devicePayload, 0, len(devices))
+	for _, d := range devices {
+		items = append(items, toDevicePayload(d))
+	}
+	return deviceListPayload{Devices: items}
+}
+
+// myDevicesHandler 返回当前会话用户的设备列表。
+func myDevicesHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		userID := sessionUserID(c)
+		devices, err := svc.Device.ListDevices(c.Request.Context(), userID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, deviceListResponse(devices))
+	}
+}
+
+// myKickDeviceHandler 踢掉当前用户的一台设备。
+func myKickDeviceHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		userID := sessionUserID(c)
+		deviceID := strings.TrimSpace(c.Param("deviceID"))
+		if deviceID == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "device id required"})
+			return
+		}
+		if err := svc.Device.KickDevice(c.Request.Context(), userID, deviceID); err != nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+			return
+		}
+		c.Status(http.StatusNoContent)
+	}
+}
+
+// myKickAllDevicesHandler 踢掉当前用户的全部设备。
+func myKickAllDevicesHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		userID := sessionUserID(c)
+		if err := svc.Device.KickAllDevices(c.Request.Context(), userID); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.Status(http.StatusNoContent)
+	}
+}
+
+// adminUserDevicesHandler 返回指定用户的设备列表。
+func adminUserDevicesHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		userID := strings.TrimSpace(c.Param("id"))
+		// FindByID 对「不存在」返回 (nil, nil)，必须判空而不是判 error，
+		// 否则「用户不存在」会伪装成「该用户没有设备」的空列表。
+		user, err := svc.Repo.User.FindByID(c.Request.Context(), userID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if user == nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
+			return
+		}
+		devices, err := svc.Device.ListDevices(c.Request.Context(), userID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, deviceListResponse(devices))
+	}
+}
+
+// adminKickUserDeviceHandler 由管理员踢掉指定用户的一台设备。
+func adminKickUserDeviceHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		userID := strings.TrimSpace(c.Param("id"))
+		deviceID := strings.TrimSpace(c.Param("deviceID"))
+		if deviceID == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "device id required"})
+			return
+		}
+		if err := svc.Device.KickDevice(c.Request.Context(), userID, deviceID); err != nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+			return
+		}
+		c.Status(http.StatusNoContent)
+	}
+}
+
+// adminKickAllUserDevicesHandler 由管理员踢掉指定用户的全部设备。
+func adminKickAllUserDevicesHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		userID := strings.TrimSpace(c.Param("id"))
+		if err := svc.Device.KickAllDevices(c.Request.Context(), userID); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.Status(http.StatusNoContent)
+	}
+}
+
+// sessionUserID 读取会话用户 ID。调用方路由都挂在鉴权中间件之后，因此这里
+// 只做类型断言兜底，不做权限判断。
+func sessionUserID(c *gin.Context) string {
+	if v, ok := c.Get(middleware.CtxUserID); ok {
+		if s, ok := v.(string); ok {
+			return s
+		}
+	}
+	return ""
+}

internal/handler/devices_test.go

@@ -0,0 +1,232 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/middleware"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// newDeviceTestEnv 搭一个只挂设备/Telegram 路由的最小环境，并预置两个用户，
+// 用于验证「只能操作自己的设备」这条边界。
+func newDeviceTestEnv(t *testing.T) (*gin.Engine, *service.Container) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(&model.User{}, &model.UserDevice{}, &model.Setting{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	repos := repository.New(db)
+	svc := &service.Container{Repo: repos, Log: zap.NewNop()}
+	svc.Device = service.NewDeviceService(zap.NewNop(), repos)
+	svc.Device.SetSessionTracker(service.NewSessionTrackerService(zap.NewNop()))
+	svc.Telegram = service.NewTelegramService(zap.NewNop(), repos)
+
+	const secret = "test-secret"
+	router := gin.New()
+	authed := router.Group("/api", func(c *gin.Context) {
+		// 测试里直接注入会话身份，绕开真实 JWT 解析。
+		if uid := c.GetHeader("X-Test-User"); uid != "" {
+			c.Set(middleware.CtxUserID, uid)
+			c.Set(middleware.CtxUserRole, c.GetHeader("X-Test-Role"))
+		}
+		c.Next()
+	})
+	authed.GET("/me/devices", myDevicesHandler(svc))
+	authed.POST("/me/devices/kick-all", myKickAllDevicesHandler(svc))
+	authed.POST("/me/devices/:deviceID/kick", myKickDeviceHandler(svc))
+	authed.GET("/me/telegram", getTelegramStatusHandler(svc))
+	authed.POST("/me/telegram/bind-code", startTelegramBindHandler(svc))
+	authed.DELETE("/me/telegram", unbindTelegramHandler(svc))
+	authed.GET("/admin/users/:id/devices", adminUserDevicesHandler(svc))
+	authed.POST("/admin/users/:id/devices/:deviceID/kick", adminKickUserDeviceHandler(svc))
+	_ = secret
+	return router, svc
+}
+
+func seedDeviceUsers(t *testing.T, svc *service.Container) {
+	t.Helper()
+	ctx := context.Background()
+	for _, id := range []string{"user-a", "user-b"} {
+		if err := svc.Repo.User.Create(ctx, &model.User{
+			Base: model.Base{ID: id}, Username: id, PasswordHash: "x", Role: "user", IsActive: true,
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func doJSON(t *testing.T, router *gin.Engine, method, path, userID, role string) *httptest.ResponseRecorder {
+	t.Helper()
+	req := httptest.NewRequest(method, path, nil)
+	req.Header.Set("X-Test-User", userID)
+	if role != "" {
+		req.Header.Set("X-Test-Role", role)
+	}
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	return w
+}
+
+// /me/devices 只能返回调用者自己的设备。
+func TestMyDevicesScopedToCaller(t *testing.T) {
+	router, svc := newDeviceTestEnv(t)
+	seedDeviceUsers(t, svc)
+	ctx := context.Background()
+
+	svc.Device.RecordLogin(ctx, "user-a", "dev-a", "A-Phone", "Infuse", "1.1.1.1")
+	svc.Device.RecordLogin(ctx, "user-b", "dev-b", "B-Phone", "Infuse", "2.2.2.2")
+
+	w := doJSON(t, router, http.MethodGet, "/api/me/devices", "user-a", "user")
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	var payload struct {
+		Devices []struct {
+			DeviceID string `json:"device_id"`
+		} `json:"devices"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if len(payload.Devices) != 1 || payload.Devices[0].DeviceID != "dev-a" {
+		t.Fatalf("devices = %+v, want only dev-a", payload.Devices)
+	}
+	// 设备指纹属于内部判定标识，不能下发。
+	if strings.Contains(w.Body.String(), "fingerprint") {
+		t.Fatalf("response must not expose fingerprint: %s", w.Body.String())
+	}
+}
+
+// 踢别人的设备必须失败：/me 路由用会话身份，deviceID 属于他人时查不到。
+func TestKickForeignDeviceFails(t *testing.T) {
+	router, svc := newDeviceTestEnv(t)
+	seedDeviceUsers(t, svc)
+	svc.Device.RecordLogin(context.Background(), "user-b", "dev-b", "B-Phone", "Infuse", "2.2.2.2")
+
+	w := doJSON(t, router, http.MethodPost, "/api/me/devices/dev-b/kick", "user-a", "user")
+	if w.Code == http.StatusNoContent {
+		t.Fatal("user-a must not be able to kick user-b's device")
+	}
+}
+
+func TestMyKickOwnDeviceSucceeds(t *testing.T) {
+	router, svc := newDeviceTestEnv(t)
+	seedDeviceUsers(t, svc)
+	svc.Device.RecordLogin(context.Background(), "user-a", "dev-a", "A-Phone", "Infuse", "1.1.1.1")
+
+	w := doJSON(t, router, http.MethodPost, "/api/me/devices/dev-a/kick", "user-a", "user")
+	if w.Code != http.StatusNoContent {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+}
+
+// 管理员接口对不存在的用户返回 404，避免把「用户不存在」和「用户没有设备」
+// 混成同一个空列表。
+func TestAdminDevicesUnknownUserReturns404(t *testing.T) {
+	router, svc := newDeviceTestEnv(t)
+	seedDeviceUsers(t, svc)
+
+	w := doJSON(t, router, http.MethodGet, "/api/admin/users/nope/devices", "admin-1", "admin")
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want 404", w.Code)
+	}
+}
+
+func TestTelegramStatusAndBindCode(t *testing.T) {
+	router, svc := newDeviceTestEnv(t)
+	seedDeviceUsers(t, svc)
+
+	w := doJSON(t, router, http.MethodGet, "/api/me/telegram", "user-a", "user")
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d", w.Code)
+	}
+	if !strings.Contains(w.Body.String(), `"bound":false`) {
+		t.Fatalf("body = %s, want bound=false", w.Body.String())
+	}
+
+	w = doJSON(t, router, http.MethodPost, "/api/me/telegram/bind-code", "user-a", "user")
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	var code struct {
+		Code      string `json:"code"`
+		ExpiresIn int    `json:"expires_in_seconds"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &code); err != nil {
+		t.Fatal(err)
+	}
+	if len(code.Code) != 6 {
+		t.Fatalf("code = %q, want 6 chars", code.Code)
+	}
+	if code.ExpiresIn <= 0 {
+		t.Fatalf("expires_in_seconds = %d, want > 0", code.ExpiresIn)
+	}
+}
+
+func TestAdminSettingsMasksBotToken(t *testing.T) {
+	router, svc := newDeviceTestEnv(t)
+	ctx := context.Background()
+	if err := svc.Repo.Setting.Set(ctx, service.SettingTelegramBotToken, "123456:AAHsecretTOKEN"); err != nil {
+		t.Fatal(err)
+	}
+	router.GET("/api/admin/settings", listSettingsHandler(svc))
+	router.PUT("/api/admin/settings", updateSettingHandler(svc))
+
+	w := doJSON(t, router, http.MethodGet, "/api/admin/settings", "admin-1", "admin")
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d", w.Code)
+	}
+	if strings.Contains(w.Body.String(), "AAHsecretTOKEN") {
+		t.Fatalf("bot token leaked: %s", w.Body.String())
+	}
+	if !strings.Contains(w.Body.String(), "***") {
+		t.Fatalf("bot token should be masked: %s", w.Body.String())
+	}
+}
+
+// 把脱敏值原样提交回来时，必须保留库里真实 Token —— 否则一次保存就把凭据毁掉。
+func TestSavingMaskedTokenKeepsRealValue(t *testing.T) {
+	router, svc := newDeviceTestEnv(t)
+	ctx := context.Background()
+	const real = "123456:AAHsecretTOKEN"
+	if err := svc.Repo.Setting.Set(ctx, service.SettingTelegramBotToken, real); err != nil {
+		t.Fatal(err)
+	}
+	router.PUT("/api/admin/settings", updateSettingHandler(svc))
+
+	body := `{"key":"telegram.bot_token","value":"12***EN"}`
+	req := httptest.NewRequest(http.MethodPut, "/api/admin/settings", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-Test-User", "admin-1")
+	req.Header.Set("X-Test-Role", "admin")
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusNoContent {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	got, err := svc.Repo.Setting.Get(ctx, service.SettingTelegramBotToken)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != real {
+		t.Fatalf("stored token = %q, want the original value preserved", got)
+	}
+}

internal/handler/emby_auth.go

@@ -26,6 +26,13 @@ func embyUserID(c *gin.Context) string {
 	return ""
 }
 
+// embyEffectiveUserID 返回当前鉴权用户。收藏、续播、播放进度等用户态数据必须
+// 绑定到登录身份；路径/Query 里的 UserId 只是 Emby URL 形态兼容，不能覆盖鉴权结果，
+// 否则多用户会串到同一个 UserId 上。
+func embyEffectiveUserID(c *gin.Context) string {
+	return embyUserID(c)
+}
+
 const embyCompatSessionTTL = 30 * time.Minute
 
 type embyCompatSession struct {

internal/handler/emby_discovery.go

@@ -0,0 +1,122 @@
+package handler
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// Emby 发现类接口的 handler：NextUp / Similar / Genres。
+//
+// 这三个接口此前返回空列表，导致第三方客户端首页「接下来播放」、详情页
+// 「相似推荐」、按类型浏览全部为空白。它们必须始终返回 200 + 合法信封，
+// 因为客户端在首页刷新时会并发请求，任何 4xx/5xx 都会被判定为服务端异常。
+
+func embyNextUpHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		userID := embyScopedUserID(c)
+		if userID == "" {
+			c.JSON(http.StatusOK, embyEmptyItemsPayload())
+			return
+		}
+		limit, _ := strconv.Atoi(embyFirstNonEmptyString(firstQueryValue(c, "Limit", "limit"), ""))
+		// YamBy / Emby 进剧集详情会带 SeriesId 请求「本剧下一集」。
+		// 忽略该参数会把全站 NextUp 第一条塞进详情页「继续播放」。
+		// 注意：不要把普通 ParentId（媒体库）当成 SeriesId，否则首页 NextUp 会被滤空。
+		seriesID := firstQueryValue(c, "SeriesId", "seriesId", "seriesid")
+		if seriesID == "" {
+			if parentID := firstQueryValue(c, "ParentId", "parentId", "parentid"); parentID != "" {
+				if strings.HasPrefix(parentID, "msgo-series-") || service.IsEmbyRemoteID(parentID) {
+					seriesID = parentID
+				}
+			}
+		}
+		out, err := svc.Emby.NextUp(c.Request.Context(), userID, seriesID, limit)
+		if err != nil {
+			c.JSON(http.StatusOK, embyEmptyItemsPayload())
+			return
+		}
+		embyAttachRequestTokenToMediaSources(c, out)
+		c.JSON(http.StatusOK, out)
+	}
+}
+
+// embyShowNextUpHandler 处理 /Shows/{id}/NextUp：把路径上的剧集 ID 当作 SeriesId。
+func embyShowNextUpHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		userID := embyScopedUserID(c)
+		if userID == "" {
+			c.JSON(http.StatusOK, embyEmptyItemsPayload())
+			return
+		}
+		seriesID := strings.TrimSpace(c.Param("id"))
+		if seriesID == "" || strings.EqualFold(seriesID, "NextUp") {
+			c.JSON(http.StatusOK, embyEmptyItemsPayload())
+			return
+		}
+		limit, _ := strconv.Atoi(embyFirstNonEmptyString(firstQueryValue(c, "Limit", "limit"), ""))
+		out, err := svc.Emby.NextUp(c.Request.Context(), userID, seriesID, limit)
+		if err != nil {
+			c.JSON(http.StatusOK, embyEmptyItemsPayload())
+			return
+		}
+		embyAttachRequestTokenToMediaSources(c, out)
+		c.JSON(http.StatusOK, out)
+	}
+}
+
+func embySimilarHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		mediaID := strings.TrimSpace(c.Param("id"))
+		if mediaID == "" {
+			c.JSON(http.StatusOK, embyEmptyItemsPayload())
+			return
+		}
+		limit, _ := strconv.Atoi(embyFirstNonEmptyString(firstQueryValue(c, "Limit", "limit"), ""))
+		out, err := svc.Emby.SimilarItems(c.Request.Context(), mediaID, embyEffectiveUserID(c), limit)
+		if err != nil {
+			c.JSON(http.StatusOK, embyEmptyItemsPayload())
+			return
+		}
+		embyAttachRequestTokenToMediaSources(c, out)
+		c.JSON(http.StatusOK, out)
+	}
+}
+
+func embyGenresHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		parentID := firstQueryValue(c, "ParentId", "parentId", "parentid")
+		out, err := svc.Emby.Genres(c.Request.Context(), embyEffectiveUserID(c), parentID)
+		if err != nil {
+			c.JSON(http.StatusOK, embyEmptyItemsPayload())
+			return
+		}
+		c.JSON(http.StatusOK, out)
+	}
+}
+
+// embyScopedUserID 解析「按用户请求」的 Emby 接口的生效用户。
+//
+// 路由上带 :userId 时（/Users/{uid}/Shows/NextUp），只允许查询自己：客户端
+// 偶尔会带着别人的 id 请求，直接采信等于开放他人观看历史的读取。管理员同样
+// 按自己处理，避免出现一条无人使用的越权路径。
+func embyScopedUserID(c *gin.Context) string {
+	caller := embyEffectiveUserID(c)
+	requested := strings.TrimSpace(c.Param("userId"))
+	if requested == "" {
+		return caller
+	}
+	if requested == caller {
+		return caller
+	}
+	return ""
+}
+
+// embyEmptyItemsPayload 与 embyEmptyItemsHandler 保持同一形状。
+func embyEmptyItemsPayload() gin.H {
+	return gin.H{"Items": []any{}, "TotalRecordCount": 0}
+}

internal/handler/emby_discovery_test.go

@@ -0,0 +1,372 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// newEmbyDiscoveryEnv 搭一个跑在内存库上的 Emby 路由环境。
+func newEmbyDiscoveryEnv(t *testing.T) (*gin.Engine, *service.Container, string) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(
+		&model.User{}, &model.Library{}, &model.Media{}, &model.PlaybackHistory{},
+		&model.Setting{}, &model.Favorite{}, &model.UserDevice{},
+	); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	repos := repository.New(db)
+	cfg := &config.Config{}
+	cfg.Secrets.JWTSecret = "test-secret"
+
+	svc := &service.Container{Repo: repos, Log: zap.NewNop()}
+	svc.Emby = service.NewEmbyService(cfg, zap.NewNop(), repos).
+		SetDiscovery(service.NewMediaDiscoveryService(zap.NewNop(), repos))
+
+	const userID = "user-1"
+	if err := repos.User.Create(context.Background(), &model.User{
+		Base: model.Base{ID: userID}, Username: "tester", PasswordHash: "x",
+		Role: "user", IsActive: true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	router := gin.New()
+	registerEmbyRoutes(router, cfg.Secrets.JWTSecret, svc)
+	return router, svc, userID
+}
+
+func seedEmbyLibrary(t *testing.T, svc *service.Container, typ string) string {
+	t.Helper()
+	lib := &model.Library{Name: "库-" + typ, Path: "/media/" + typ, Type: typ, Enabled: true}
+	if err := svc.Repo.Library.Create(context.Background(), lib); err != nil {
+		t.Fatal(err)
+	}
+	return lib.ID
+}
+
+func embyGet(t *testing.T, router *gin.Engine, path, token string) *httptest.ResponseRecorder {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	if token != "" {
+		req.Header.Set("X-Emby-Token", token)
+	}
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	return w
+}
+
+func decodeItemsEnvelope(t *testing.T, body []byte) []map[string]any {
+	t.Helper()
+	var payload struct {
+		Items            []map[string]any `json:"Items"`
+		TotalRecordCount int64            `json:"TotalRecordCount"`
+	}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		t.Fatalf("decode %s: %v", string(body), err)
+	}
+	return payload.Items
+}
+
+// NextUp 必须真的返回下一集，而不是空数组。
+func TestEmbyNextUpReturnsNextEpisode(t *testing.T) {
+	router, svc, userID := newEmbyDiscoveryEnv(t)
+	libID := seedEmbyLibrary(t, svc, "tv")
+	watchedAt := time.Now().Add(-time.Hour)
+
+	for episode, watched := range map[int]bool{1: true, 2: false, 3: false} {
+		m := &model.Media{
+			LibraryID: libID, SeriesID: "series-1", Title: "剧一",
+			SeasonNum: 1, EpisodeNum: episode,
+			Path: "/media/tv/S1E" + string(rune('0'+episode)) + ".mkv",
+		}
+		if err := svc.Repo.DB.Create(m).Error; err != nil {
+			t.Fatal(err)
+		}
+		if watched {
+			h := &model.PlaybackHistory{
+				UserID: userID, MediaID: m.ID, PositionMs: 2000, DurationMs: 2000,
+				WatchedAt: watchedAt, Completed: true, // 第 1 集已看完
+			}
+			if err := svc.Repo.DB.Create(h).Error; err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+
+	w := embyGet(t, router, "/emby/Shows/NextUp", signedTestToken(t, "test-secret"))
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	items := decodeItemsEnvelope(t, w.Body.Bytes())
+	if len(items) != 1 {
+		t.Fatalf("items = %d, want 1 (body=%s)", len(items), w.Body.String())
+	}
+	if index, ok := items[0]["IndexNumber"].(float64); !ok || int(index) != 2 {
+		t.Fatalf("IndexNumber = %v, want 2 (body=%s)", items[0]["IndexNumber"], w.Body.String())
+	}
+}
+
+// 回归：用户在剧集详情页点播放、只看了几秒就退出（历史行 completed=false）后，
+// Yamby 再次进入详情页带的 NextUp 仍要指向那一集本身，否则「继续播放」会跳到下一集。
+func TestEmbyNextUpKeepsPartiallyWatchedEpisode(t *testing.T) {
+	router, svc, userID := newEmbyDiscoveryEnv(t)
+	libID := seedEmbyLibrary(t, svc, "tv")
+
+	episodeIDs := map[int]string{}
+	for ep := 1; ep <= 3; ep++ {
+		m := &model.Media{
+			LibraryID: libID, SeriesID: "series-1", Title: "剧一",
+			SeasonNum: 1, EpisodeNum: ep,
+			Path: "/media/tv/S1E" + strconv.Itoa(ep) + ".mkv",
+		}
+		if err := svc.Repo.DB.Create(m).Error; err != nil {
+			t.Fatal(err)
+		}
+		episodeIDs[ep] = m.ID
+	}
+
+	// 第 2 集播放了 3 秒后退出：有进度、未标记看完。
+	if err := svc.Repo.DB.Create(&model.PlaybackHistory{
+		UserID: userID, MediaID: episodeIDs[2], PositionMs: 3582, DurationMs: 1440064,
+		WatchedAt: time.Now(), Completed: false,
+	}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	w := embyGet(t, router, "/emby/Shows/NextUp?SeriesId=series-1&Limit=1", signedTestToken(t, "test-secret"))
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	items := decodeItemsEnvelope(t, w.Body.Bytes())
+	if len(items) != 1 {
+		t.Fatalf("items = %d, want 1 (body=%s)", len(items), w.Body.String())
+	}
+	if id, _ := items[0]["Id"].(string); id != episodeIDs[2] {
+		t.Fatalf("Id = %q, want the partially watched episode %q (body=%s)", id, episodeIDs[2], w.Body.String())
+	}
+	if index, ok := items[0]["IndexNumber"].(float64); !ok || int(index) != 2 {
+		t.Fatalf("IndexNumber = %v, want 2 (body=%s)", items[0]["IndexNumber"], w.Body.String())
+	}
+}
+
+// 没有历史时必须返回合法空信封，不能 404/500。
+func TestEmbyNextUpEmptyWithoutHistory(t *testing.T) {
+	router, _, _ := newEmbyDiscoveryEnv(t)
+
+	w := embyGet(t, router, "/emby/Shows/NextUp", signedTestToken(t, "test-secret"))
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	if items := decodeItemsEnvelope(t, w.Body.Bytes()); len(items) != 0 {
+		t.Fatalf("items = %d, want 0", len(items))
+	}
+}
+
+// 小写别名路由同样要走到真实实现（客户端路径大小写并不统一）。
+func TestEmbyNextUpLowercaseAlias(t *testing.T) {
+	router, svc, _ := newEmbyDiscoveryEnv(t)
+	_ = seedEmbyLibrary(t, svc, "tv")
+
+	w := embyGet(t, router, "/emby/shows/nextup", signedTestToken(t, "test-secret"))
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+}
+
+// Similar 对不存在的条目返回空列表（客户端详情页会无条件请求）。
+func TestEmbySimilarUnknownItemReturnsEmpty(t *testing.T) {
+	router, _, _ := newEmbyDiscoveryEnv(t)
+
+	w := embyGet(t, router, "/emby/Items/does-not-exist/Similar", signedTestToken(t, "test-secret"))
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	if items := decodeItemsEnvelope(t, w.Body.Bytes()); len(items) != 0 {
+		t.Fatalf("items = %d, want 0", len(items))
+	}
+}
+
+func TestEmbySimilarReturnsCandidates(t *testing.T) {
+	router, svc, _ := newEmbyDiscoveryEnv(t)
+	libID := seedEmbyLibrary(t, svc, "movie")
+
+	source := &model.Media{
+		LibraryID: libID, Title: "源片", Genres: "Action", Year: 2010, Rating: 8,
+		Path: "/media/movie/source.mkv",
+	}
+	if err := svc.Repo.DB.Create(source).Error; err != nil {
+		t.Fatal(err)
+	}
+	other := &model.Media{
+		LibraryID: libID, Title: "同类片", Genres: "Action", Year: 2011, Rating: 8,
+		Path: "/media/movie/other.mkv",
+	}
+	if err := svc.Repo.DB.Create(other).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	w := embyGet(t, router, "/emby/Items/"+source.ID+"/Similar", signedTestToken(t, "test-secret"))
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	items := decodeItemsEnvelope(t, w.Body.Bytes())
+	if len(items) != 1 {
+		t.Fatalf("items = %d, want 1 (body=%s)", len(items), w.Body.String())
+	}
+	if name, _ := items[0]["Name"].(string); name != "同类片" {
+		t.Fatalf("Name = %q, want 同类片", name)
+	}
+}
+
+// Genres 必须返回真实类型与计数。
+func TestEmbyGenresReturnsCounts(t *testing.T) {
+	router, svc, _ := newEmbyDiscoveryEnv(t)
+	libID := seedEmbyLibrary(t, svc, "movie")
+
+	for i, genres := range []string{"Action,Drama", "Action"} {
+		m := &model.Media{
+			LibraryID: libID, Title: "片" + string(rune('A'+i)), Genres: genres,
+			Path: "/media/movie/m" + string(rune('0'+i)) + ".mkv",
+		}
+		if err := svc.Repo.DB.Create(m).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	w := embyGet(t, router, "/emby/Genres", signedTestToken(t, "test-secret"))
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	items := decodeItemsEnvelope(t, w.Body.Bytes())
+	if len(items) != 2 {
+		t.Fatalf("items = %d, want 2 (body=%s)", len(items), w.Body.String())
+	}
+	// 排序按计数降序：Action(2) 在前。
+	if name, _ := items[0]["Name"].(string); name != "Action" {
+		t.Fatalf("first Name = %q, want Action", name)
+	}
+	if count, ok := items[0]["ItemCount"].(float64); !ok || int(count) != 2 {
+		t.Fatalf("ItemCount = %v, want 2", items[0]["ItemCount"])
+	}
+	if id, _ := items[0]["Id"].(string); len(id) == 0 {
+		t.Fatal("genre item must carry a stable Id")
+	}
+}
+
+// 按别人的 userId 请求 NextUp 不允许泄露他人历史。
+func TestEmbyNextUpRejectsForeignUserID(t *testing.T) {
+	router, _, _ := newEmbyDiscoveryEnv(t)
+
+	w := embyGet(t, router, "/emby/Users/someone-else/Shows/NextUp", signedTestToken(t, "test-secret"))
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	if items := decodeItemsEnvelope(t, w.Body.Bytes()); len(items) != 0 {
+		t.Fatalf("items = %d, want 0", len(items))
+	}
+}
+
+// YamBy 等客户端进入剧集详情会带 SeriesId 调 NextUp；必须只返回该剧的下一集，
+// 不能回落成全站「继续观看」第一条，否则详情页播放会串到别的片子。
+func TestEmbyNextUpFiltersBySeriesID(t *testing.T) {
+	router, svc, userID := newEmbyDiscoveryEnv(t)
+	libID := seedEmbyLibrary(t, svc, "tv")
+	recent := time.Now().Add(-time.Minute)
+	older := time.Now().Add(-2 * time.Hour)
+
+	seedSeries := func(seriesID, title string, watchedAt time.Time) (watchedID, nextID string) {
+		t.Helper()
+		for ep := 1; ep <= 3; ep++ {
+			m := &model.Media{
+				LibraryID: libID, SeriesID: seriesID, Title: title,
+				SeasonNum: 1, EpisodeNum: ep,
+				Path: "/media/tv/" + seriesID + "/S1E" + strconv.Itoa(ep) + ".mkv",
+			}
+			if err := svc.Repo.DB.Create(m).Error; err != nil {
+				t.Fatal(err)
+			}
+			switch ep {
+			case 1:
+				watchedID = m.ID
+				h := &model.PlaybackHistory{
+					UserID: userID, MediaID: m.ID, PositionMs: 2000, DurationMs: 2000,
+					WatchedAt: watchedAt, Completed: true, // 第 1 集已看完，下一集是 S1E2
+				}
+				if err := svc.Repo.DB.Create(h).Error; err != nil {
+					t.Fatal(err)
+				}
+			case 2:
+				nextID = m.ID
+			}
+		}
+		return watchedID, nextID
+	}
+
+	_, _ = seedSeries("series-hot", "热门剧", recent)
+	_, wantNext := seedSeries("series-cold", "目标剧", older)
+
+	token := signedTestToken(t, "test-secret")
+	global := embyGet(t, router, "/emby/Shows/NextUp?Limit=10", token)
+	if global.Code != http.StatusOK {
+		t.Fatalf("global status = %d body=%s", global.Code, global.Body.String())
+	}
+	if items := decodeItemsEnvelope(t, global.Body.Bytes()); len(items) < 2 {
+		t.Fatalf("global items = %d, want >= 2 (body=%s)", len(items), global.Body.String())
+	}
+
+	scoped := embyGet(t, router, "/emby/Shows/NextUp?SeriesId=series-cold&Limit=10", token)
+	if scoped.Code != http.StatusOK {
+		t.Fatalf("scoped status = %d body=%s", scoped.Code, scoped.Body.String())
+	}
+	items := decodeItemsEnvelope(t, scoped.Body.Bytes())
+	if len(items) != 1 {
+		t.Fatalf("scoped items = %d, want 1 (body=%s)", len(items), scoped.Body.String())
+	}
+	if id, _ := items[0]["Id"].(string); id != wantNext {
+		t.Fatalf("scoped Id = %q, want %q (body=%s)", id, wantNext, scoped.Body.String())
+	}
+	if seriesID, _ := items[0]["SeriesId"].(string); seriesID != "series-cold" {
+		t.Fatalf("scoped SeriesId = %q, want series-cold", seriesID)
+	}
+
+	empty := embyGet(t, router, "/emby/Shows/NextUp?SeriesId=series-never-watched", token)
+	if empty.Code != http.StatusOK {
+		t.Fatalf("empty status = %d body=%s", empty.Code, empty.Body.String())
+	}
+	if items := decodeItemsEnvelope(t, empty.Body.Bytes()); len(items) != 0 {
+		t.Fatalf("never-watched items = %d, want 0 (body=%s)", len(items), empty.Body.String())
+	}
+
+	pathScoped := embyGet(t, router, "/emby/Shows/series-cold/NextUp?Limit=10", token)
+	if pathScoped.Code != http.StatusOK {
+		t.Fatalf("path scoped status = %d body=%s", pathScoped.Code, pathScoped.Body.String())
+	}
+	pathItems := decodeItemsEnvelope(t, pathScoped.Body.Bytes())
+	if len(pathItems) != 1 {
+		t.Fatalf("path scoped items = %d, want 1 (body=%s)", len(pathItems), pathScoped.Body.String())
+	}
+	if id, _ := pathItems[0]["Id"].(string); id != wantNext {
+		t.Fatalf("path scoped Id = %q, want %q", id, wantNext)
+	}
+}

internal/handler/emby_items_handlers.go

@@ -13,13 +13,7 @@ import (
 func parseEmbyItemsParams(c *gin.Context) service.ItemsParams {
 	limit, _ := strconv.Atoi(embyFirstNonEmptyString(firstQueryValue(c, "Limit", "limit"), "50"))
 	offset, _ := strconv.Atoi(embyFirstNonEmptyString(firstQueryValue(c, "StartIndex", "startIndex", "startindex"), "0"))
-	uid := c.Param("userId")
-	if uid == "" {
-		uid = firstQueryValue(c, "UserId", "userId", "userid")
-	}
-	if uid == "" {
-		uid = embyUserID(c)
-	}
+	uid := embyEffectiveUserID(c)
 	splitOpt := func(s string) []string {
 		if s == "" {
 			return nil
@@ -46,9 +40,28 @@ func parseEmbyItemsParams(c *gin.Context) service.ItemsParams {
 		SortOrder:        firstQueryValue(c, "SortOrder", "sortOrder", "sortorder"),
 		Limit:            limit,
 		StartIndex:       offset,
+		SeasonIndex:      parseEmbySeasonIndexQuery(c),
 	}
 }
 
+// parseEmbySeasonIndexQuery 读取客户端请求的季序号。
+//
+// Emby 客户端有两种表达方式：SeasonId（虚拟季 ID）与 Season / SeasonIndex
+// （季序号，特别篇为 0）。两者都是合法入参，SeasonId 更精确。这里只解析季序号，
+// 返回 nil 表示客户端没有按季过滤（区别于 Season=0 的特别篇）。
+func parseEmbySeasonIndexQuery(c *gin.Context) *int {
+	raw := firstQueryValue(c, "Season", "season", "SeasonIndex", "seasonIndex", "seasonindex")
+	if raw == "" {
+		return nil
+	}
+	value, err := strconv.Atoi(raw)
+	if err != nil {
+		// 客户端偶尔传入季名称之类的非数字值；按「未过滤」处理，避免整季空结果。
+		return nil
+	}
+	return &value
+}
+
 func embyFirstNonEmptyString(values ...string) string {
 	for _, value := range values {
 		if strings.TrimSpace(value) != "" {
@@ -73,10 +86,7 @@ func embyItemsHandler(svc *service.Container) gin.HandlerFunc {
 func embyItemByIDHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		id := c.Param("id")
-		uid := c.Param("userId")
-		if uid == "" {
-			uid = embyUserID(c)
-		}
+		uid := embyEffectiveUserID(c)
 		out, err := svc.Emby.Item(c.Request.Context(), id, uid)
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
@@ -106,13 +116,7 @@ func embyUserItemByIDHandler(svc *service.Container) gin.HandlerFunc {
 
 func embyLatestItemsHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		uid := c.Param("userId")
-		if uid == "" {
-			uid = firstQueryValue(c, "UserId", "userId", "userid")
-		}
-		if uid == "" {
-			uid = embyUserID(c)
-		}
+		uid := embyEffectiveUserID(c)
 		limit, _ := strconv.Atoi(embyFirstNonEmptyString(firstQueryValue(c, "Limit", "limit"), "20"))
 		out, err := svc.Emby.LatestItems(c.Request.Context(), uid, firstQueryValue(c, "ParentId", "parentId", "parentid"), limit)
 		if err != nil {
@@ -126,15 +130,12 @@ func embyLatestItemsHandler(svc *service.Container) gin.HandlerFunc {
 
 func embyResumeItemsHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		uid := c.Param("userId")
-		if uid == "" {
-			uid = firstQueryValue(c, "UserId", "userId", "userid")
-		}
-		if uid == "" {
-			uid = embyUserID(c)
-		}
+		uid := embyEffectiveUserID(c)
 		limit, _ := strconv.Atoi(embyFirstNonEmptyString(firstQueryValue(c, "Limit", "limit"), "20"))
-		out, err := svc.Emby.ResumeItems(c.Request.Context(), uid, limit)
+		startIndex, _ := strconv.Atoi(embyFirstNonEmptyString(firstQueryValue(c, "StartIndex", "startIndex", "startindex"), "0"))
+		// ParentId / SeriesId 收窄到当前库或当前剧，避免详情页继续播放串到全站历史。
+		parentID := firstQueryValue(c, "ParentId", "parentId", "parentid", "SeriesId", "seriesId", "seriesid")
+		out, err := svc.Emby.ResumeItems(c.Request.Context(), uid, parentID, limit, startIndex)
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
@@ -147,13 +148,7 @@ func embyResumeItemsHandler(svc *service.Container) gin.HandlerFunc {
 func embyItemsCountsHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		if svc != nil && svc.Emby != nil {
-			uid := firstQueryValue(c, "UserId", "userId")
-			if uid == "" {
-				uid = c.Param("userId")
-			}
-			if uid == "" {
-				uid = embyUserID(c)
-			}
+			uid := embyEffectiveUserID(c)
 			out, err := svc.Emby.ItemCounts(c.Request.Context(), uid)
 			if err != nil {
 				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
@@ -209,7 +204,7 @@ func embySaveDisplayPreferencesHandler(_ *service.Container) gin.HandlerFunc {
 func embyShowSeasonsHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		params := service.ItemsParams{
-			UserID:   firstQueryValue(c, "UserId", "userId"),
+			UserID:   embyEffectiveUserID(c),
 			ParentID: c.Param("id"),
 			Limit:    500,
 		}
@@ -226,15 +221,35 @@ func embyShowSeasonsHandler(svc *service.Container) gin.HandlerFunc {
 func embyShowEpisodesHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		parentID := firstQueryValue(c, "SeasonId", "seasonId")
+		// 客户端常用季序号而不是虚拟季 ID 请求剧集。缺了这层过滤，
+		// /Shows/{id}/Episodes?Season=2 会把整部剧的所有季都返回。
+		seasonIndex := parseEmbySeasonIndexQuery(c)
 		if parentID == "" {
 			parentID = c.Param("id")
+		} else {
+			// SeasonId 已经限定了具体季，忽略同时传来的季序号，避免两者
+			// 不一致时把结果过滤成空集。
+			seasonIndex = nil
+		}
+		// Emby 客户端按 StartIndex/Limit 分页拉取分集，并在已收条目数小于
+		// TotalRecordCount 时继续请求下一页。忽略这两个参数会让客户端永远
+		// 停在第一页、反复重发同一请求（现象是分集列表一直加载不出来）。
+		limit, _ := strconv.Atoi(embyFirstNonEmptyString(firstQueryValue(c, "Limit", "limit"), "500"))
+		if limit <= 0 {
+			limit = 500
+		}
+		startIndex, _ := strconv.Atoi(embyFirstNonEmptyString(firstQueryValue(c, "StartIndex", "startIndex", "startindex"), "0"))
+		if startIndex < 0 {
+			startIndex = 0
 		}
 		params := service.ItemsParams{
-			UserID:           firstQueryValue(c, "UserId", "userId"),
+			UserID:           embyEffectiveUserID(c),
 			ParentID:         parentID,
 			IncludeItemTypes: []string{"Episode"},
 			Recursive:        true,
-			Limit:            500,
+			Limit:            limit,
+			StartIndex:       startIndex,
+			SeasonIndex:      seasonIndex,
 		}
 		out, err := svc.Emby.Items(c.Request.Context(), params)
 		if err != nil {

internal/handler/emby_media_segments.go

@@ -0,0 +1,151 @@
+// Package handler — Emby / Jellyfin 媒体分段（片头、片尾）兼容接口。
+//
+//	GET /MediaSegments/{itemId}
+//	GET /Items/{itemId}/MediaSegments
+//	GET /Users/{userId}/Items/{itemId}/MediaSegments
+//
+// 契约对齐 Jellyfin 10.10 引入的 Media Segments API（Emby 采用同一形状），
+// 也是 TheIntroDB 官方 Jellyfin 插件走的同一条路：
+//
+//	QueryResult<MediaSegmentDto> = {"Items": [...], "TotalRecordCount": N}
+//	MediaSegmentDto = {"Id", "ItemId", "Type", "StartTicks", "EndTicks"}
+//
+// 时间是 .NET ticks（1 tick = 100ns，即每秒 10,000,000、每毫秒 10,000）；
+// Type 是枚举名字符串 Intro / Outro / Recap / Preview / Commercial。
+package handler
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// 第三方客户端会在起播前后同步请求分段，不能被一次外网抓取无限拖住。超时后
+// 退回已有缓存（可能为空），请求本身永远不失败。
+const embyMediaSegmentsFetchBudget = 5 * time.Second
+
+// 1 秒 = 10,000,000 ticks => 1 毫秒 = 10,000 ticks。
+const embyTicksPerMillisecond int64 = 10_000
+
+func embyMediaSegmentsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 未知条目、虚拟剧集/季、远程 Emby 挂载、以及当前不可见的内容一律返回
+		// 空结果而不是 404：客户端会把 404 判成「条目损坏」（同 emby_routes.go
+		// 里 AdditionalParts 的说明），而「没有可跳过的片段」本来就是个合法状态。
+		empty := gin.H{"Items": []any{}, "TotalRecordCount": 0}
+		if svc == nil || svc.Repo == nil || svc.Segments == nil {
+			c.JSON(http.StatusOK, empty)
+			return
+		}
+		id := c.Param("id")
+		// 远程 Emby 挂载的条目是上游库的投影，本地没有可查询的外部 ID 关联。
+		if service.IsEmbyRemoteID(id) {
+			c.JSON(http.StatusOK, empty)
+			return
+		}
+		m, err := svc.Repo.Media.FindByID(c.Request.Context(), id)
+		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
+			c.JSON(http.StatusOK, empty)
+			return
+		}
+
+		ctx, cancel := context.WithTimeout(c.Request.Context(), embyMediaSegmentsFetchBudget)
+		defer cancel()
+		rows, listErr := svc.Segments.ListForPlayback(ctx, m)
+		if listErr != nil && svc.Log != nil {
+			svc.Log.Debug("emby media segments lookup failed",
+				zap.String("media_id", m.ID), zap.Error(listErr))
+		}
+
+		items := embySegmentItems(m, rows, embyRequestedSegmentTypes(c))
+		c.JSON(http.StatusOK, gin.H{"Items": items, "TotalRecordCount": len(items)})
+	}
+}
+
+// embySegmentItems 把库内片段转换成 MediaSegmentDto 列表。
+func embySegmentItems(m *model.Media, rows []model.MediaSegment, want map[string]bool) []gin.H {
+	// 末段在库内用 end_ms = 0 表示「一直到片尾」（TheIntroDB 对片尾返回 end_ms: null），
+	// 这里必须换算成真实结束时间；拿不到时长就丢弃该分段，否则会给出一个零长度区间，
+	// 客户端要么忽略要么画出一个错误的跳转点。
+	durationMs := int64(m.DurationSec) * 1000
+	items := make([]gin.H, 0, len(rows))
+	for _, row := range rows {
+		typeName := embySegmentTypeName(row.Kind)
+		if typeName == "" {
+			continue
+		}
+		if len(want) > 0 && !want[typeName] {
+			continue
+		}
+		endMs := row.EndMs
+		if endMs <= 0 {
+			if durationMs <= 0 {
+				continue
+			}
+			endMs = durationMs
+		}
+		if endMs <= row.StartMs {
+			continue
+		}
+		items = append(items, gin.H{
+			"Id":         row.ID,
+			"ItemId":     m.ID,
+			"Type":       typeName,
+			"StartTicks": row.StartMs * embyTicksPerMillisecond,
+			"EndTicks":   endMs * embyTicksPerMillisecond,
+		})
+	}
+	return items
+}
+
+// embySegmentTypeName 把库内 kind 映射成 Emby/Jellyfin 的 MediaSegmentType 名字。
+// 库内的 credits 取自 TheIntroDB 的字段名，在 Emby 一侧对应 Outro。
+func embySegmentTypeName(kind string) string {
+	switch kind {
+	case model.SegmentKindIntro:
+		return "Intro"
+	case model.SegmentKindRecap:
+		return "Recap"
+	case model.SegmentKindCredits:
+		return "Outro"
+	case model.SegmentKindPreview:
+		return "Preview"
+	default:
+		return ""
+	}
+}
+
+// embyRequestedSegmentTypes 解析 includeSegmentTypes（Jellyfin 的过滤参数）。
+// 支持重复参数与逗号分隔两种写法；返回空集合表示不过滤。
+//
+// 只认枚举名字符串。数字枚举虽然 ASP.NET 模型绑定也接受，但各家定义的顺序并
+// 不一致，猜错会把过滤结果算错；认不出来时按「不过滤」处理，返回的是超集，
+// 客户端自己仍会再过滤一次。
+func embyRequestedSegmentTypes(c *gin.Context) map[string]bool {
+	raw := make([]string, 0, 4)
+	for _, key := range []string{"includeSegmentTypes", "IncludeSegmentTypes", "includesegmenttypes"} {
+		raw = append(raw, c.QueryArray(key)...)
+	}
+	want := make(map[string]bool, len(raw))
+	for _, value := range raw {
+		for _, part := range strings.Split(value, ",") {
+			part = strings.TrimSpace(part)
+			if part == "" {
+				continue
+			}
+			for _, name := range []string{"Intro", "Outro", "Recap", "Preview", "Commercial"} {
+				if strings.EqualFold(part, name) {
+					want[name] = true
+				}
+			}
+		}
+	}
+	return want
+}

internal/handler/emby_media_segments_test.go

@@ -0,0 +1,217 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+type embySegmentsPayload struct {
+	Items []struct {
+		ID         string `json:"Id"`
+		ItemID     string `json:"ItemId"`
+		Type       string `json:"Type"`
+		StartTicks int64  `json:"StartTicks"`
+		EndTicks   int64  `json:"EndTicks"`
+	} `json:"Items"`
+	TotalRecordCount int `json:"TotalRecordCount"`
+}
+
+// 电影：intro 有明确结束点；credits 的 end_ms 为 null（库内落成 0），
+// 必须用媒体时长补齐 —— 这是最容易写错的一处。
+const embySegmentsProviderBody = `{"tmdb_id":27205,"type":"movie","intro":[{"start_ms":null,"end_ms":38000}],"credits":[{"start_ms":6480000,"end_ms":null}]}`
+
+const (
+	embySegmentsMovieDurationSec = 8880
+	embySegmentsTicksPerSecond   = 10_000_000
+)
+
+func newEmbySegmentsTestRouter(t *testing.T, durationSec int) (*gin.Engine, string, *int32) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.AutoMigrate(model.AllModels()...); err != nil {
+		t.Fatal(err)
+	}
+	repos := repository.New(db)
+	if err := repos.User.Create(t.Context(), &model.User{
+		Base:         model.Base{ID: "user-1"},
+		Username:     "tester",
+		PasswordHash: "x",
+		Role:         "admin",
+		Tier:         "plus",
+		IsActive:     true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	lib := model.Library{Base: model.Base{ID: "lib-movies"}, Name: "电影", Path: "D:\\media\\movies", Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&model.Media{
+		Base:        model.Base{ID: "movie-1"},
+		LibraryID:   lib.ID,
+		Title:       "Inception",
+		Path:        "D:\\media\\movies\\Inception.mkv",
+		DurationSec: durationSec,
+		TMDbID:      27205,
+	}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	var calls int32
+	provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(embySegmentsProviderBody))
+	}))
+	t.Cleanup(provider.Close)
+
+	segments := service.NewMediaSegmentService(zap.NewNop(), repos).
+		SetIntroDB(service.NewIntroDBService(zap.NewNop()).SetBaseURL(provider.URL))
+
+	const secret = "test-secret"
+	router := gin.New()
+	registerEmbyRoutes(router, secret, &service.Container{
+		Repo:     repos,
+		Emby:     service.NewEmbyService(&config.Config{}, zap.NewNop(), repos),
+		Segments: segments,
+		Log:      zap.NewNop(),
+	})
+	return router, secret, &calls
+}
+
+func embySegmentsRequest(t *testing.T, router *gin.Engine, secret, path string) embySegmentsPayload {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	req.Header.Set("X-Emby-Token", signedTestToken(t, secret))
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("%s status = %d body=%s", path, w.Code, w.Body.String())
+	}
+	var payload embySegmentsPayload
+	if err := json.Unmarshal(w.Body.Bytes(), &payload); err != nil {
+		t.Fatalf("%s decode: %v", path, err)
+	}
+	return payload
+}
+
+func TestEmbyMediaSegmentsReturnsTicksAndMapsCreditsToOutro(t *testing.T) {
+	router, secret, _ := newEmbySegmentsTestRouter(t, embySegmentsMovieDurationSec)
+
+	payload := embySegmentsRequest(t, router, secret, "/MediaSegments/movie-1")
+	if payload.TotalRecordCount != 2 || len(payload.Items) != 2 {
+		t.Fatalf("segments = %#v (total %d), want 2", payload.Items, payload.TotalRecordCount)
+	}
+
+	intro := payload.Items[0]
+	if intro.Type != "Intro" || intro.ItemID != "movie-1" || intro.ID == "" {
+		t.Fatalf("intro segment = %#v", intro)
+	}
+	// start_ms null 表示从片头开始。
+	if intro.StartTicks != 0 || intro.EndTicks != 38*embySegmentsTicksPerSecond {
+		t.Fatalf("intro ticks = %d..%d, want 0..%d",
+			intro.StartTicks, intro.EndTicks, 38*embySegmentsTicksPerSecond)
+	}
+
+	// 库内 credits 在 Emby 一侧是 Outro；end_ms = 0 必须按媒体时长补齐，
+	// 否则客户端会拿到一个零长度区间。
+	outro := payload.Items[1]
+	if outro.Type != "Outro" {
+		t.Fatalf("credits should map to Outro, got %q", outro.Type)
+	}
+	if outro.StartTicks != 6480*embySegmentsTicksPerSecond {
+		t.Fatalf("outro StartTicks = %d, want %d", outro.StartTicks, 6480*embySegmentsTicksPerSecond)
+	}
+	if outro.EndTicks != embySegmentsMovieDurationSec*embySegmentsTicksPerSecond {
+		t.Fatalf("outro EndTicks = %d, want the media duration %d",
+			outro.EndTicks, embySegmentsMovieDurationSec*embySegmentsTicksPerSecond)
+	}
+}
+
+func TestEmbyMediaSegmentsIsServedFromTheSameCacheAsTheWebPlayer(t *testing.T) {
+	router, secret, calls := newEmbySegmentsTestRouter(t, embySegmentsMovieDurationSec)
+
+	// 多条路径 + 大小写变体都应命中同一份缓存，而不是各自再打一次外网。
+	for _, path := range []string{
+		"/MediaSegments/movie-1",
+		"/mediasegments/movie-1",
+		"/Items/movie-1/MediaSegments",
+		"/items/movie-1/mediasegments",
+		"/Users/user-1/Items/movie-1/MediaSegments",
+	} {
+		payload := embySegmentsRequest(t, router, secret, path)
+		if len(payload.Items) != 2 {
+			t.Fatalf("%s returned %#v, want 2 segments", path, payload.Items)
+		}
+	}
+	if got := atomic.LoadInt32(calls); got != 1 {
+		t.Fatalf("provider calls = %d, want 1 (all routes share the cached rows)", got)
+	}
+}
+
+func TestEmbyMediaSegmentsHonoursIncludeSegmentTypes(t *testing.T) {
+	router, secret, _ := newEmbySegmentsTestRouter(t, embySegmentsMovieDurationSec)
+
+	payload := embySegmentsRequest(t, router, secret, "/MediaSegments/movie-1?includeSegmentTypes=Intro")
+	if payload.TotalRecordCount != 1 || len(payload.Items) != 1 {
+		t.Fatalf("filtered segments = %#v (total %d), want only Intro", payload.Items, payload.TotalRecordCount)
+	}
+	if payload.Items[0].Type != "Intro" {
+		t.Fatalf("filtered type = %q, want Intro", payload.Items[0].Type)
+	}
+
+	// 认不出的枚举名按「不过滤」处理：返回超集比返回空集安全。
+	payload = embySegmentsRequest(t, router, secret, "/MediaSegments/movie-1?includeSegmentTypes=NotAType")
+	if payload.TotalRecordCount != 2 {
+		t.Fatalf("unknown filter returned %d segments, want the unfiltered set", payload.TotalRecordCount)
+	}
+}
+
+func TestEmbyMediaSegmentsDropsOpenEndedRangeWhenDurationUnknown(t *testing.T) {
+	// 时长未知（STRM/云盘媒体探测前）时，credits 无法换算成真实结束点，
+	// 只能丢弃；有明确结束点的 intro 必须保留。
+	router, secret, _ := newEmbySegmentsTestRouter(t, 0)
+
+	payload := embySegmentsRequest(t, router, secret, "/MediaSegments/movie-1")
+	if payload.TotalRecordCount != 1 || len(payload.Items) != 1 {
+		t.Fatalf("segments = %#v (total %d), want only the intro", payload.Items, payload.TotalRecordCount)
+	}
+	if payload.Items[0].Type != "Intro" {
+		t.Fatalf("kept segment = %#v, want Intro", payload.Items[0])
+	}
+}
+
+func TestEmbyMediaSegmentsReturnsEmptyInsteadOfNotFound(t *testing.T) {
+	router, secret, calls := newEmbySegmentsTestRouter(t, embySegmentsMovieDurationSec)
+
+	// 未知条目必须 200 + 空数组：客户端会把 404 判成「条目损坏」。
+	payload := embySegmentsRequest(t, router, secret, "/MediaSegments/does-not-exist")
+	if payload.Items == nil || len(payload.Items) != 0 || payload.TotalRecordCount != 0 {
+		t.Fatalf("unknown item payload = %#v", payload)
+	}
+	// 远程 Emby 条目同理（本地没有可查询的外部 ID 关联）。
+	payload = embySegmentsRequest(t, router, secret, "/MediaSegments/embyremote~acct1~item1")
+	if len(payload.Items) != 0 {
+		t.Fatalf("remote emby item payload = %#v, want empty", payload.Items)
+	}
+	if got := atomic.LoadInt32(calls); got != 0 {
+		t.Fatalf("provider calls = %d, want 0 for unresolvable items", got)
+	}
+}

internal/handler/emby_playback.go

@@ -1,10 +1,13 @@
 package handler
 
 import (
+	"context"
 	"errors"
 	"net/http"
 	"net/url"
 	"strings"
+	"sync"
+	"time"
 
 	"github.com/gin-gonic/gin"
 
@@ -13,10 +16,7 @@ import (
 
 func embyPlaybackInfoHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		uid := c.Param("userId")
-		if uid == "" {
-			uid = embyUserID(c)
-		}
+		uid := embyEffectiveUserID(c)
 		out, err := svc.Emby.PlaybackInfo(c.Request.Context(), c.Param("id"), uid)
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
@@ -27,10 +27,98 @@ func embyPlaybackInfoHandler(svc *service.Container) gin.HandlerFunc {
 			return
 		}
 		embyAttachRequestTokenToMediaSources(c, out)
+		// 在后台把本次条目的云盘直链换好：播放器拿到 PlaybackInfo 后通常还要
+		// 1–2 秒才请求 /Videos/{id}/stream，把换链开销落在这段等待里。
+		embyPrewarmPlaybackTargets(svc, c, out)
 		c.JSON(http.StatusOK, out)
 	}
 }
 
+// embyPrewarmTimeout 是单次预热的等待上限。115 开放平台在跨太平洋线路上单次
+// 换链实测 0.4–1.1s，这里给足余量；超时只是没预热成功，不影响后续播放。
+const embyPrewarmTimeout = 10 * time.Second
+
+// embyPrewarmInFlight 去重同一个条目的并发预热（首页刷新会并发请求多个接口，
+// 同一条目可能在短时间内被多次请求）。
+var embyPrewarmInFlight sync.Map
+
+// embyPrewarmSlots 限制同时进行的预热数量。客户端可能批量预取 PlaybackInfo
+// （逐个剧集的预取请求），预热只是优化，不能反过来把 115 换链接口打出突发。
+// 名额满时直接跳过：排队等待的预热往往等真正播放时已经没意义了。
+var embyPrewarmSlots = make(chan struct{}, 4)
+
+// embyPrewarmPlaybackTargets 在后台预热本次 PlaybackInfo 涉及条目的云盘直链。
+//
+// 起播链路里最贵的一步是「服务端拿 pickcode 去 115 开放平台换直链」：服务器在
+// 洛杉矶、115 接口在国内，冷启动实测 0.4–1.1s；之后 45 分钟内命中进程内缓存。
+// 播放器在 PlaybackInfo 与真正拉流之间有几秒间隔，这里把换链放到那段间隔里，
+// 起播时就只剩纯网络耗时。
+//
+// 只处理云盘/strm 条目，且失败一律静默忽略：预热是尽力而为的优化，不能影响
+// PlaybackInfo 的正常返回。
+func embyPrewarmPlaybackTargets(svc *service.Container, c *gin.Context, out map[string]any) {
+	if svc == nil || svc.Strm == nil || svc.Repo == nil || svc.Repo.Media == nil || out == nil {
+		return
+	}
+	ids := embyPrewarmMediaIDs(out)
+	if len(ids) == 0 {
+		return
+	}
+	userAgent := c.GetHeader("User-Agent")
+	// 预热是给「后续请求」用的：即便本次 PlaybackInfo 的连接断开，
+	// 也要把换链跑完。
+	base := context.WithoutCancel(c.Request.Context())
+	for _, mediaID := range ids {
+		if _, loaded := embyPrewarmInFlight.LoadOrStore(mediaID, struct{}{}); loaded {
+			continue
+		}
+		go func(id string) {
+			defer embyPrewarmInFlight.Delete(id)
+			select {
+			case embyPrewarmSlots <- struct{}{}:
+				defer func() { <-embyPrewarmSlots }()
+			default:
+				return
+			}
+			ctx, cancel := context.WithTimeout(base, embyPrewarmTimeout)
+			defer cancel()
+			m, err := svc.Repo.Media.FindByID(ctx, id)
+			if err != nil || m == nil {
+				return
+			}
+			raw := strings.TrimSpace(m.STRMURL)
+			if raw == "" || !service.IsStrmMediaRow(m) {
+				return
+			}
+			// 解析结果由 strm 层按 pickcode+UA 缓存；已缓存时这里是空转。
+			_, _ = svc.Strm.ResolvePlayTargetWithUA(ctx, raw, userAgent)
+		}(mediaID)
+	}
+}
+
+// embyPrewarmMediaIDs 取出 PlaybackInfo 载荷里 MediaSources 的条目 ID。
+func embyPrewarmMediaIDs(out map[string]any) []string {
+	sources, ok := out["MediaSources"].([]map[string]any)
+	if !ok || len(sources) == 0 {
+		return nil
+	}
+	ids := make([]string, 0, len(sources))
+	seen := make(map[string]struct{}, len(sources))
+	for _, src := range sources {
+		id, _ := src["Id"].(string)
+		id = strings.TrimSpace(id)
+		if id == "" {
+			continue
+		}
+		if _, dup := seen[id]; dup {
+			continue
+		}
+		seen[id] = struct{}{}
+		ids = append(ids, id)
+	}
+	return ids
+}
+
 // embySubtitleStreamHandler serves an external subtitle track advertised in a
 // MediaSource's MediaStreams via its Emby index
 // (/Videos/:id/Subtitles/:index/Stream). The index maps to a discovered
@@ -47,10 +135,7 @@ func embySubtitleStreamHandler(svc *service.Container) gin.HandlerFunc {
 			}
 			return
 		}
-		uid := c.Param("userId")
-		if uid == "" {
-			uid = embyUserID(c)
-		}
+		uid := embyEffectiveUserID(c)
 		ctx := c.Request.Context()
 		// The official-format route carries a :format suffix (Stream.ass /
 		// Stream.vtt); prefer it for the Content-Type when present, otherwise

internal/handler/emby_playback_prewarm_test.go

@@ -0,0 +1,159 @@
+package handler
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+func newPrewarmTestContainer(t *testing.T) *service.Container {
+	t.Helper()
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(&model.Media{}, &model.Setting{}, &model.StrmAccount{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	if sqlDB, err := db.DB(); err == nil {
+		// 内存库 + 后台预热协程：限制单连接，避免新连接拿到空白的 :memory:。
+		sqlDB.SetMaxOpenConns(1)
+	}
+	repos := repository.New(db)
+	return &service.Container{
+		Log:  zap.NewNop(),
+		Repo: repos,
+		Strm: service.NewStrmService(&config.Config{}, zap.NewNop(), repos, nil),
+	}
+}
+
+func newPrewarmTestContext() *gin.Context {
+	gin.SetMode(gin.TestMode)
+	c, _ := gin.CreateTestContext(httptest.NewRecorder())
+	c.Request = httptest.NewRequest(http.MethodPost, "/emby/Items/media-1/PlaybackInfo", nil)
+	c.Request.Header.Set("User-Agent", "RodelPlayer/2.2607.7.0")
+	return c
+}
+
+func TestEmbyPrewarmMediaIDsExtractsDeduplicates(t *testing.T) {
+	out := map[string]any{
+		"MediaSources": []map[string]any{
+			{"Id": "src-1"},
+			{"Id": " src-1 "},
+			{"Id": "src-2"},
+			{"Id": ""},
+			{"Name": "no id"},
+		},
+	}
+	got := embyPrewarmMediaIDs(out)
+	if len(got) != 2 || got[0] != "src-1" || got[1] != "src-2" {
+		t.Fatalf("ids = %v, want [src-1 src-2]", got)
+	}
+	if got := embyPrewarmMediaIDs(map[string]any{}); len(got) != 0 {
+		t.Fatalf("missing MediaSources should yield no ids, got %v", got)
+	}
+	if got := embyPrewarmMediaIDs(map[string]any{"MediaSources": []any{}}); len(got) != 0 {
+		t.Fatalf("foreign payload shape should yield no ids, got %v", got)
+	}
+}
+
+// 预热是异步的：调用必须立即返回，并且协程结束后不能残留去重标记。
+func TestEmbyPrewarmPlaybackTargetsRunsAsyncAndCleansUp(t *testing.T) {
+	svc := newPrewarmTestContainer(t)
+	if err := svc.Repo.DB.Create(&model.Media{
+		Base:      model.Base{ID: "media-1"},
+		Title:     "Cloud",
+		Path:      "cloud://cloud115/Movie.mkv",
+		Container: "strm",
+		STRMURL:   "/api/strm/play/cloud115/video.mkv?acct=missing&pickcode=pc1",
+	}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	embyPrewarmInFlight.Delete("media-1")
+	out := map[string]any{"MediaSources": []map[string]any{{"Id": "media-1"}}}
+
+	done := make(chan struct{})
+	go func() {
+		embyPrewarmPlaybackTargets(svc, newPrewarmTestContext(), out)
+		close(done)
+	}()
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("embyPrewarmPlaybackTargets blocked the caller")
+	}
+
+	// 后台协程应很快跑完并释放去重标记，否则同一条目后续再也预热不了。
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		if _, busy := embyPrewarmInFlight.Load("media-1"); !busy {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatal("prewarm in-flight marker leaked")
+}
+
+// 各种缺数据的情况都不允许 panic 或阻塞：预热只是尽力而为的优化。
+func TestEmbyPrewarmPlaybackTargetsIsNilSafe(t *testing.T) {
+	svc := newPrewarmTestContainer(t)
+	c := newPrewarmTestContext()
+	out := map[string]any{"MediaSources": []map[string]any{{"Id": "media-1"}}}
+
+	cases := []struct {
+		name string
+		svc  *service.Container
+		out  map[string]any
+	}{
+		{name: "空容器", svc: &service.Container{}, out: out},
+		{name: "无 Strm", svc: &service.Container{Repo: svc.Repo}, out: out},
+		{name: "无 Repo", svc: &service.Container{Strm: svc.Strm}, out: out},
+		{name: "nil 载荷", svc: svc, out: nil},
+		{name: "无 MediaSources", svc: svc, out: map[string]any{}},
+		{name: "条目不存在", svc: svc, out: out},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			embyPrewarmPlaybackTargets(tc.svc, c, tc.out)
+		})
+	}
+}
+
+// 本地文件条目不该触发换链预热（没有云盘直链可预热）。
+func TestEmbyPrewarmSkipsLocalMedia(t *testing.T) {
+	svc := newPrewarmTestContainer(t)
+	if err := svc.Repo.DB.Create(&model.Media{
+		Base:      model.Base{ID: "local-1"},
+		Title:     "Local",
+		Path:      "/media/movies/Local.mkv",
+		LibraryID: "lib-1",
+	}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	embyPrewarmInFlight.Delete("local-1")
+	embyPrewarmPlaybackTargets(svc, newPrewarmTestContext(),
+		map[string]any{"MediaSources": []map[string]any{{"Id": "local-1"}}})
+
+	// 协程要么已经跑完（标记被清掉），要么根本没起；两种都不该留下标记。
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if _, busy := embyPrewarmInFlight.Load("local-1"); !busy {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatal("local media must not leave a prewarm marker")
+}

internal/handler/emby_playstate_handlers.go

@@ -92,10 +92,7 @@ func embyPlayingProgressHandler(svc *service.Container) gin.HandlerFunc {
 
 func embyFavoriteHandler(svc *service.Container, fav bool) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		uid := c.Param("userId")
-		if uid == "" {
-			uid = embyUserID(c)
-		}
+		uid := embyEffectiveUserID(c)
 		mid := c.Param("itemId")
 		if uid == "" || mid == "" {
 			c.Status(http.StatusBadRequest)
@@ -116,10 +113,7 @@ func embyFavoriteHandler(svc *service.Container, fav bool) gin.HandlerFunc {
 
 func embyMarkPlayedHandler(svc *service.Container, played bool) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		uid := c.Param("userId")
-		if uid == "" {
-			uid = embyUserID(c)
-		}
+		uid := embyEffectiveUserID(c)
 		mid := c.Param("itemId")
 		if uid == "" || mid == "" {
 			c.Status(http.StatusBadRequest)

internal/handler/emby_routes.go

@@ -196,15 +196,20 @@ func registerEmbyAuthenticatedItemRoutes(auth *gin.RouterGroup, svc *service.Con
 	auth.GET("/Shows/:id/Episodes", embyShowEpisodesHandler(svc))
 	auth.GET("/Users/:userId/Shows/:id/Seasons", embyShowSeasonsHandler(svc))
 	auth.GET("/Users/:userId/Shows/:id/Episodes", embyShowEpisodesHandler(svc))
-	auth.GET("/Shows/NextUp", embyEmptyItemsHandler(svc))
-	auth.GET("/Users/:userId/Shows/NextUp", embyEmptyItemsHandler(svc))
-	auth.GET("/MediaSegments/:id", embyEmptyItemsHandler(svc))
+	auth.GET("/Shows/NextUp", embyNextUpHandler(svc))
+	auth.GET("/Users/:userId/Shows/NextUp", embyNextUpHandler(svc))
+	// 部分客户端用路径形式 /Shows/{seriesId}/NextUp，而不是 query SeriesId。
+	auth.GET("/Shows/:id/NextUp", embyShowNextUpHandler(svc))
+	auth.GET("/Users/:userId/Shows/:id/NextUp", embyShowNextUpHandler(svc))
+	auth.GET("/MediaSegments/:id", embyMediaSegmentsHandler(svc))
+	auth.GET("/Items/:id/MediaSegments", embyMediaSegmentsHandler(svc))
+	auth.GET("/Users/:userId/Items/:id/MediaSegments", embyMediaSegmentsHandler(svc))
 	auth.GET("/Artists", embyEmptyItemsHandler(svc))
 	auth.GET("/Persons", embyEmptyItemsHandler(svc))
-	auth.GET("/Genres", embyEmptyItemsHandler(svc))
+	auth.GET("/Genres", embyGenresHandler(svc))
 	auth.GET("/Shows/Upcoming", embyEmptyItemsHandler(svc))
 	auth.GET("/Users/:userId/Shows/Upcoming", embyEmptyItemsHandler(svc))
-	auth.GET("/Items/:id/Similar", embyEmptyItemsHandler(svc))
+	auth.GET("/Items/:id/Similar", embySimilarHandler(svc))
 	auth.GET("/Items/:id/ThumbnailSet", embyEmptyItemsHandler(svc))
 	auth.GET("/Items/:id/ThemeMedia", embyThemeMediaHandler(svc))
 	auth.GET("/Users/:userId/Items/:id/SpecialFeatures", embyEmptyItemsHandler(svc))

internal/handler/emby_routes_lowercase.go

@@ -40,15 +40,19 @@ func registerLowercaseEmbyItemRoutes(auth *gin.RouterGroup, svc *service.Contain
 	auth.GET("/shows/:id/episodes", embyShowEpisodesHandler(svc))
 	auth.GET("/users/:userId/shows/:id/seasons", embyShowSeasonsHandler(svc))
 	auth.GET("/users/:userId/shows/:id/episodes", embyShowEpisodesHandler(svc))
-	auth.GET("/shows/nextup", embyEmptyItemsHandler(svc))
-	auth.GET("/users/:userId/shows/nextup", embyEmptyItemsHandler(svc))
-	auth.GET("/mediasegments/:id", embyEmptyItemsHandler(svc))
+	auth.GET("/shows/nextup", embyNextUpHandler(svc))
+	auth.GET("/users/:userId/shows/nextup", embyNextUpHandler(svc))
+	auth.GET("/shows/:id/nextup", embyShowNextUpHandler(svc))
+	auth.GET("/users/:userId/shows/:id/nextup", embyShowNextUpHandler(svc))
+	auth.GET("/mediasegments/:id", embyMediaSegmentsHandler(svc))
+	auth.GET("/items/:id/mediasegments", embyMediaSegmentsHandler(svc))
+	auth.GET("/users/:userId/items/:id/mediasegments", embyMediaSegmentsHandler(svc))
 	auth.GET("/artists", embyEmptyItemsHandler(svc))
 	auth.GET("/persons", embyEmptyItemsHandler(svc))
-	auth.GET("/genres", embyEmptyItemsHandler(svc))
+	auth.GET("/genres", embyGenresHandler(svc))
 	auth.GET("/shows/upcoming", embyEmptyItemsHandler(svc))
 	auth.GET("/users/:userId/shows/upcoming", embyEmptyItemsHandler(svc))
-	auth.GET("/items/:id/similar", embyEmptyItemsHandler(svc))
+	auth.GET("/items/:id/similar", embySimilarHandler(svc))
 	auth.GET("/items/:id/thumbnailset", embyEmptyItemsHandler(svc))
 	auth.GET("/items/:id/thememedia", embyThemeMediaHandler(svc))
 	auth.GET("/users/:userId/items/:id/specialfeatures", embyEmptyItemsHandler(svc))

internal/handler/emby_show_episodes_season_test.go

@@ -0,0 +1,372 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// embySeasonEpisodesRouter builds an Emby-compatible router over one series with
+// two seasons, so /Shows/{id}/Episodes can be exercised with the query forms
+// real clients send.
+func embySeasonEpisodesRouter(t *testing.T) (*gin.Engine, string, string) {
+	t.Helper()
+	return embySeriesRouter(t, []model.Media{
+		{
+			Base:       model.Base{ID: "s1e1"},
+			Title:      "Test Show",
+			Path:       "D:\\media\\tv\\Test Show\\Season 01\\Test Show - S01E01.mkv",
+			SeasonNum:  1,
+			EpisodeNum: 1,
+			Container:  "mkv",
+		},
+		{
+			Base:       model.Base{ID: "s2e1"},
+			Title:      "Test Show",
+			Path:       "D:\\media\\tv\\Test Show\\Season 02\\Test Show - S02E01.mkv",
+			SeasonNum:  2,
+			EpisodeNum: 1,
+			Container:  "mkv",
+		},
+	})
+}
+
+// embySeriesRouter builds an Emby-compatible router with a single tv library and
+// one series made of the given episode rows. Callers omit LibraryID: it is filled
+// in here once the library exists.
+func embySeriesRouter(t *testing.T, rows []model.Media) (*gin.Engine, string, string) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(&model.User{}, &model.Library{}, &model.Series{}, &model.Media{}, &model.Favorite{}, &model.PlaybackHistory{}, &model.Setting{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	if sqlDB, err := db.DB(); err == nil {
+		sqlDB.SetMaxOpenConns(1)
+	}
+	repos := repository.New(db)
+	if err := repos.User.Create(t.Context(), &model.User{
+		Base:         model.Base{ID: "user-1"},
+		Username:     "tester",
+		PasswordHash: "x",
+		Role:         "admin",
+		Tier:         "plus",
+		IsActive:     true,
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	lib := model.Library{Name: "剧集", Path: "D:\\media\\tv", Type: "tv", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatalf("create library: %v", err)
+	}
+	for i := range rows {
+		rows[i].LibraryID = lib.ID
+		if err := db.Create(&rows[i]).Error; err != nil {
+			t.Fatalf("create media: %v", err)
+		}
+	}
+
+	const secret = "test-secret"
+	router := gin.New()
+	registerEmbyRoutes(router, secret, &service.Container{
+		Repo: repos,
+		Emby: service.NewEmbyService(&config.Config{}, zap.NewNop(), repos),
+	})
+
+	// Resolve the virtual series id the way a client would.
+	seriesReq := httptest.NewRequest(http.MethodGet, "/Items?ParentId="+lib.ID+"&IncludeItemTypes=Series", nil)
+	seriesReq.Header.Set("X-Emby-Token", signedTestToken(t, secret))
+	seriesRec := httptest.NewRecorder()
+	router.ServeHTTP(seriesRec, seriesReq)
+	if seriesRec.Code != http.StatusOK {
+		t.Fatalf("series lookup status=%d body=%s", seriesRec.Code, seriesRec.Body.String())
+	}
+	var seriesPayload struct {
+		Items []map[string]any `json:"Items"`
+	}
+	if err := json.Unmarshal(seriesRec.Body.Bytes(), &seriesPayload); err != nil {
+		t.Fatalf("decode series: %v", err)
+	}
+	if len(seriesPayload.Items) != 1 {
+		t.Fatalf("want one series, got %#v", seriesPayload.Items)
+	}
+	seriesID, _ := seriesPayload.Items[0]["Id"].(string)
+	if seriesID == "" {
+		t.Fatalf("series payload has no Id: %#v", seriesPayload.Items[0])
+	}
+	return router, secret, seriesID
+}
+
+func fetchSeasonID(t *testing.T, router *gin.Engine, secret, seriesID string, index int) string {
+	t.Helper()
+	path := "/Shows/" + seriesID + "/Seasons"
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	req.Header.Set("X-Emby-Token", signedTestToken(t, secret))
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("seasons status=%d body=%s", rec.Code, rec.Body.String())
+	}
+	var seasons struct {
+		Items []map[string]any `json:"Items"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &seasons); err != nil {
+		t.Fatalf("decode seasons: %v", err)
+	}
+	for _, s := range seasons.Items {
+		if got, ok := s["IndexNumber"].(float64); ok && int(got) == index {
+			if id, _ := s["Id"].(string); id != "" {
+				return id
+			}
+		}
+	}
+	t.Fatalf("season %d not found in %#v", index, seasons.Items)
+	return ""
+}
+
+func fetchEpisodeItems(t *testing.T, router *gin.Engine, secret, path string) ([]map[string]any, int) {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	req.Header.Set("X-Emby-Token", signedTestToken(t, secret))
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("%s status=%d body=%s", path, rec.Code, rec.Body.String())
+	}
+	var payload struct {
+		Items            []map[string]any `json:"Items"`
+		TotalRecordCount float64          `json:"TotalRecordCount"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &payload); err != nil {
+		t.Fatalf("decode %s: %v", path, err)
+	}
+	return payload.Items, int(payload.TotalRecordCount)
+}
+
+func fetchEpisodeIDs(t *testing.T, router *gin.Engine, secret, path string) ([]string, int) {
+	t.Helper()
+	items, total := fetchEpisodeItems(t, router, secret, path)
+	ids := make([]string, 0, len(items))
+	for _, item := range items {
+		id, _ := item["Id"].(string)
+		ids = append(ids, id)
+	}
+	return ids, total
+}
+
+// TestEmbyShowEpisodesHonoursSeasonQueryParam is the client-facing regression
+// test: Emby clients scope episodes with ?Season=<index> (not only SeasonId), and
+// the endpoint used to ignore it and return every season of the series.
+func TestEmbyShowEpisodesHonoursSeasonQueryParam(t *testing.T) {
+	router, secret, seriesID := embySeasonEpisodesRouter(t)
+
+	cases := []struct {
+		name    string
+		query   string
+		wantIDs []string
+	}{
+		{name: "season 1", query: "Season=1", wantIDs: []string{"s1e1"}},
+		{name: "season 2", query: "Season=2", wantIDs: []string{"s2e1"}},
+		{name: "season index alias", query: "SeasonIndex=2", wantIDs: []string{"s2e1"}},
+		{name: "no season returns all", query: "", wantIDs: []string{"s1e1", "s2e1"}},
+		{name: "unknown season is empty", query: "Season=9", wantIDs: []string{}},
+		{name: "non numeric season falls back to all", query: "Season=Specials", wantIDs: []string{"s1e1", "s2e1"}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			path := "/Shows/" + seriesID + "/Episodes"
+			if tc.query != "" {
+				path += "?" + tc.query
+			}
+			ids, total := fetchEpisodeIDs(t, router, secret, path)
+			if len(ids) != len(tc.wantIDs) {
+				t.Fatalf("episode ids = %#v (total=%d), want %#v", ids, total, tc.wantIDs)
+			}
+			for i := range tc.wantIDs {
+				if ids[i] != tc.wantIDs[i] {
+					t.Fatalf("episode ids = %#v, want %#v", ids, tc.wantIDs)
+				}
+			}
+			if total != len(tc.wantIDs) {
+				t.Fatalf("TotalRecordCount = %d, want %d", total, len(tc.wantIDs))
+			}
+		})
+	}
+}
+
+// TestEmbyShowEpisodesSeasonIdStillWins pins that the virtual SeasonId form keeps
+// working, and that a conflicting Season query cannot empty it out.
+func TestEmbyShowEpisodesSeasonIdStillWins(t *testing.T) {
+	router, secret, seriesID := embySeasonEpisodesRouter(t)
+
+	season1ID := fetchSeasonID(t, router, secret, seriesID, 1)
+
+	ids, _ := fetchEpisodeIDs(t, router, secret, "/Shows/"+seriesID+"/Episodes?SeasonId="+season1ID)
+	if len(ids) != 1 || ids[0] != "s1e1" {
+		t.Fatalf("SeasonId episodes = %#v, want [s1e1]", ids)
+	}
+
+	// A stale/conflicting season number must not override the explicit season id.
+	ids, _ = fetchEpisodeIDs(t, router, secret, "/Shows/"+seriesID+"/Episodes?SeasonId="+season1ID+"&Season=2")
+	if len(ids) != 1 || ids[0] != "s1e1" {
+		t.Fatalf("SeasonId+Season episodes = %#v, want [s1e1]", ids)
+	}
+}
+
+// foldedDuplicateSeriesRows models a season where two files resolve to the same
+// episode number — 3月的狮子 S01E11 together with S01E11.5, which the episode
+// parser reads as S01E11 and stores as a second row for season 1 episode 2 here.
+func foldedDuplicateSeriesRows() []model.Media {
+	return []model.Media{
+		{
+			Base:       model.Base{ID: "e1"},
+			Title:      "三月的狮子",
+			Path:       "D:\\media\\tv\\三月的狮子\\三月的狮子 - S01E01.mkv",
+			SeasonNum:  1,
+			EpisodeNum: 1,
+			Container:  "mkv",
+		},
+		{
+			Base:       model.Base{ID: "e2"},
+			Title:      "三月的狮子",
+			Path:       "D:\\media\\tv\\三月的狮子\\三月的狮子 - S01E02.mkv",
+			SeasonNum:  1,
+			EpisodeNum: 2,
+			Container:  "mkv",
+		},
+		{
+			Base:       model.Base{ID: "e2half"},
+			Title:      "三月的狮子",
+			Path:       "D:\\media\\tv\\三月的狮子\\三月的狮子 - S01E02.5.mkv",
+			SeasonNum:  1,
+			EpisodeNum: 2,
+			Container:  "mkv",
+		},
+	}
+}
+
+// TestEmbyShowEpisodesFoldedDuplicateKeepsTotalsConsistent is the regression test
+// for the "第一季分集加载不出来" lock-up: two rows sharing one season/episode are
+// folded into a single Emby item with two MediaSources. TotalRecordCount used to
+// be computed before that fold, so clients that page until they have
+// TotalRecordCount items kept re-requesting the same page and never rendered the
+// season.
+func TestEmbyShowEpisodesFoldedDuplicateKeepsTotalsConsistent(t *testing.T) {
+	router, secret, seriesID := embySeriesRouter(t, foldedDuplicateSeriesRows())
+	seasonID := fetchSeasonID(t, router, secret, seriesID, 1)
+
+	items, total := fetchEpisodeItems(t, router, secret, "/Shows/"+seriesID+"/Episodes?SeasonId="+seasonID)
+	if total != len(items) {
+		t.Fatalf("TotalRecordCount = %d but %d items returned, want them equal", total, len(items))
+	}
+	if total != 2 {
+		t.Fatalf("TotalRecordCount = %d, want 2 distinct episodes", total)
+	}
+	// The folded episode must still carry both files so clients can switch version.
+	versioned := 0
+	for _, item := range items {
+		if sources, ok := item["MediaSources"].([]any); ok && len(sources) > 1 {
+			versioned++
+		}
+	}
+	if versioned != 1 {
+		t.Fatalf("items with multiple MediaSources = %d, want 1 (%#v)", versioned, items)
+	}
+}
+
+// TestEmbyShowEpisodesPagingAdvances pins that the client's StartIndex/Limit reach
+// the episode list. Ignoring them made every page identical, so a client paging
+// until it has TotalRecordCount items could never finish loading the season.
+func TestEmbyShowEpisodesPagingAdvances(t *testing.T) {
+	router, secret, seriesID := embySeriesRouter(t, foldedDuplicateSeriesRows())
+	base := "/Shows/" + seriesID + "/Episodes?Season=1"
+
+	first, total := fetchEpisodeIDs(t, router, secret, base+"&StartIndex=0&Limit=1")
+	if total != 2 || len(first) != 1 {
+		t.Fatalf("page 1 = %#v (total=%d), want one item of two", first, total)
+	}
+	second, _ := fetchEpisodeIDs(t, router, secret, base+"&StartIndex=1&Limit=1")
+	if len(second) != 1 || second[0] == first[0] {
+		t.Fatalf("page 2 = %#v, want the remaining episode (page 1 = %#v)", second, first)
+	}
+	third, _ := fetchEpisodeIDs(t, router, secret, base+"&StartIndex=2&Limit=1")
+	if len(third) != 0 {
+		t.Fatalf("page 3 = %#v, want an empty page so clients stop paging", third)
+	}
+}
+
+// 半集（S01E11.5）在 Emby 侧必须和第 11 集并列返回：一旦被折成一个条目，
+// TotalRecordCount 就会比 Items 多一条，按总数翻页的客户端会一直重发同一页
+// （这就是「第一季分集加载不出来」的根因）。Emby 的 IndexNumber 只能是整数，
+// 所以集号仍占 11，小数通过条目名体现。
+func TestEmbyShowEpisodesKeepsHalfEpisodeVisible(t *testing.T) {
+	router, secret, seriesID := embySeriesRouter(t, []model.Media{
+		{
+			Base:       model.Base{ID: "e11"},
+			Title:      "三月的狮子",
+			Path:       "D:\\media\\tv\\三月的狮子\\三月的狮子 - S01E11.mkv",
+			SeasonNum:  1,
+			EpisodeNum: 11,
+			Container:  "mkv",
+		},
+		{
+			Base:            model.Base{ID: "e11half"},
+			Title:           "三月的狮子",
+			Path:            "D:\\media\\tv\\三月的狮子\\三月的狮子 - S01E11.5.mkv",
+			SeasonNum:       1,
+			EpisodeNum:      11,
+			EpisodeFraction: 0.5,
+			Container:       "mkv",
+		},
+		{
+			Base:       model.Base{ID: "e12"},
+			Title:      "三月的狮子",
+			Path:       "D:\\media\\tv\\三月的狮子\\三月的狮子 - S01E12.mkv",
+			SeasonNum:  1,
+			EpisodeNum: 12,
+			Container:  "mkv",
+		},
+	})
+
+	items, total := fetchEpisodeItems(t, router, secret, "/Shows/"+seriesID+"/Episodes?Season=1")
+	if total != 3 || len(items) != 3 {
+		t.Fatalf("TotalRecordCount = %d, items = %d, want 3/3", total, len(items))
+	}
+	wantOrder := []string{"e11", "e11half", "e12"}
+	for i, want := range wantOrder {
+		id, _ := items[i]["Id"].(string)
+		if id != want {
+			t.Fatalf("items[%d] = %q, want %q (order %#v)", i, id, want, items)
+		}
+	}
+	for _, item := range items {
+		sources, _ := item["MediaSources"].([]any)
+		if len(sources) != 1 {
+			t.Fatalf("item %v folded %d sources, want 1", item["Id"], len(sources))
+		}
+	}
+
+	halfName, _ := items[1]["Name"].(string)
+	if !strings.HasPrefix(halfName, "第 11.5 集") {
+		t.Fatalf("half episode name = %q, want prefix 第 11.5 集", halfName)
+	}
+	if idx, _ := items[1]["IndexNumber"].(float64); int(idx) != 11 {
+		t.Fatalf("half episode IndexNumber = %v, want 11 (Emby only supports integers)", items[1]["IndexNumber"])
+	}
+}

internal/handler/emby_views_handlers.go

@@ -10,10 +10,7 @@ import (
 
 func embyViewsHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		uid := c.Param("userId")
-		if uid == "" {
-			uid = embyUserID(c)
-		}
+		uid := embyEffectiveUserID(c)
 		out, err := svc.Emby.Views(c.Request.Context(), uid)
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})

internal/handler/handler.go

@@ -19,6 +19,7 @@ func Register(r *gin.Engine, cfg *config.Config, log *zap.Logger, svc *service.C
 	api.Use(middleware.GzipAPI())
 	{
 		api.GET("/health", healthCheck)
+		api.HEAD("/health", healthCheck)
 		api.GET("/version", versionInfo)
 		api.GET("/public/ui-config", publicUIConfigHandler(svc))
 

internal/handler/library_discovery.go

@@ -0,0 +1,55 @@
+package handler
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// 媒体库筛选面板接口：facets 提供可选项，random 提供「随便看看」。
+//
+// 两者都走与列表完全相同的可见性判定（mediaVisibilityForRequest）与筛选解析
+// （parseLibraryFilters），因此不会出现「列表里有、facets 里没有」或「随机跳
+// 到了筛选条件之外的条目」这类不一致。
+
+func libraryFacetsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		libraryID := c.Param("id")
+		facets, err := svc.Media.LibraryFacets(
+			c.Request.Context(),
+			libraryID,
+			mediaVisibilityForRequest(c, svc),
+			svc.Discovery,
+		)
+		if err != nil {
+			writeInternalOrCanceled(c, err)
+			return
+		}
+		c.JSON(http.StatusOK, facets)
+	}
+}
+
+func libraryRandomHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		libraryID := c.Param("id")
+		filters := parseLibraryFilters(c)
+		// 随机只取一条，因此不带分页参数；未观看筛选仍需要会话用户。
+		media, err := svc.Media.RandomMedia(
+			c.Request.Context(),
+			libraryID,
+			mediaVisibilityForRequest(c, svc),
+			filters,
+		)
+		if err != nil {
+			writeInternalOrCanceled(c, err)
+			return
+		}
+		if media == nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "no media matches the current filters"})
+			return
+		}
+		c.JSON(http.StatusOK, media)
+	}
+}

internal/handler/library_filters_test.go

@@ -0,0 +1,283 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/middleware"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+func newLibraryFilterEnv(t *testing.T) (*gin.Engine, *service.Container, string, string) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(
+		&model.User{}, &model.Library{}, &model.Media{}, &model.PlaybackHistory{}, &model.Setting{},
+	); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	repos := repository.New(db)
+	svc := &service.Container{Repo: repos, Log: zap.NewNop()}
+	svc.Media = service.NewMediaService(nil, zap.NewNop(), repos)
+	svc.Discovery = service.NewMediaDiscoveryService(zap.NewNop(), repos)
+
+	const userID = "user-1"
+	if err := repos.User.Create(context.Background(), &model.User{
+		Base: model.Base{ID: userID}, Username: "tester", PasswordHash: "x", Role: "user", IsActive: true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	lib := &model.Library{Name: "电影", Path: "/media/movies", Type: "movie", Enabled: true}
+	if err := repos.Library.Create(context.Background(), lib); err != nil {
+		t.Fatal(err)
+	}
+
+	router := gin.New()
+	authed := router.Group("/api", func(c *gin.Context) {
+		c.Set(middleware.CtxUserID, userID)
+		c.Set(middleware.CtxUserRole, "user")
+		c.Next()
+	})
+	authed.GET("/libraries/:id/media", listMediaHandler(svc))
+	authed.GET("/libraries/:id/facets", libraryFacetsHandler(svc))
+	authed.GET("/libraries/:id/random", libraryRandomHandler(svc))
+	return router, svc, userID, lib.ID
+}
+
+func seedLibraryMedia(t *testing.T, svc *service.Container, rows ...*model.Media) {
+	t.Helper()
+	for _, row := range rows {
+		if err := svc.Repo.DB.Create(row).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func getJSON(t *testing.T, router *gin.Engine, path string) (int, []byte) {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	return w.Code, w.Body.Bytes()
+}
+
+func TestLibraryFacetsReturnGenresAndYears(t *testing.T) {
+	router, svc, _, libID := newLibraryFilterEnv(t)
+	seedLibraryMedia(t, svc,
+		&model.Media{LibraryID: libID, Title: "A", Genres: "Action,Drama", Year: 1999, Path: "/a.mkv"},
+		&model.Media{LibraryID: libID, Title: "B", Genres: "Action", Year: 2021, Path: "/b.mkv"},
+	)
+
+	code, body := getJSON(t, router, "/api/libraries/"+libID+"/facets")
+	if code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", code, body)
+	}
+	var facets struct {
+		Genres []struct {
+			Name  string `json:"name"`
+			Count int    `json:"count"`
+		} `json:"genres"`
+		YearMin int `json:"year_min"`
+		YearMax int `json:"year_max"`
+	}
+	if err := json.Unmarshal(body, &facets); err != nil {
+		t.Fatalf("decode %s: %v", body, err)
+	}
+	if facets.YearMin != 1999 || facets.YearMax != 2021 {
+		t.Fatalf("year range = %d..%d, want 1999..2021", facets.YearMin, facets.YearMax)
+	}
+	if len(facets.Genres) != 2 {
+		t.Fatalf("genres = %+v, want 2 entries", facets.Genres)
+	}
+	if facets.Genres[0].Name != "Action" || facets.Genres[0].Count != 2 {
+		t.Fatalf("first genre = %+v, want Action:2", facets.Genres[0])
+	}
+}
+
+// 空库时 facets 必须返回空数组而不是 null，前端无需额外判空。
+func TestLibraryFacetsEmptyLibrary(t *testing.T) {
+	router, _, _, libID := newLibraryFilterEnv(t)
+
+	code, body := getJSON(t, router, "/api/libraries/"+libID+"/facets")
+	if code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", code, body)
+	}
+	if !containsSubstring(string(body), `"genres":[]`) {
+		t.Fatalf("body = %s, want genres:[]", body)
+	}
+}
+
+// 列表筛选：按类型过滤后只返回命中的条目。
+func TestListMediaAppliesGenreFilter(t *testing.T) {
+	router, svc, _, libID := newLibraryFilterEnv(t)
+	seedLibraryMedia(t, svc,
+		&model.Media{LibraryID: libID, Title: "动作", Genres: "Action", Path: "/a.mkv"},
+		&model.Media{LibraryID: libID, Title: "喜剧", Genres: "Comedy", Path: "/b.mkv"},
+	)
+
+	code, body := getJSON(t, router, "/api/libraries/"+libID+"/media?group_versions=0&genre=Action")
+	if code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", code, body)
+	}
+	var payload struct {
+		Items []model.Media `json:"items"`
+		Total int64         `json:"total"`
+	}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		t.Fatalf("decode %s: %v", body, err)
+	}
+	if payload.Total != 1 || len(payload.Items) != 1 || payload.Items[0].Title != "动作" {
+		t.Fatalf("payload = %+v, want only 动作", payload)
+	}
+}
+
+// 筛选条件必须进入缓存键：先请求未筛选列表、再筛选时不能命中旧缓存。
+func TestListMediaFilterBypassesUnfilteredCache(t *testing.T) {
+	router, svc, _, libID := newLibraryFilterEnv(t)
+	seedLibraryMedia(t, svc,
+		&model.Media{LibraryID: libID, Title: "动作", Genres: "Action", Path: "/a.mkv"},
+		&model.Media{LibraryID: libID, Title: "喜剧", Genres: "Comedy", Path: "/b.mkv"},
+	)
+
+	// 先拉全量（可能写缓存），再拉筛选结果。
+	if code, body := getJSON(t, router, "/api/libraries/"+libID+"/media?group_versions=0"); code != http.StatusOK {
+		t.Fatalf("unfiltered status = %d body=%s", code, body)
+	}
+	code, body := getJSON(t, router, "/api/libraries/"+libID+"/media?group_versions=0&genre=Comedy")
+	if code != http.StatusOK {
+		t.Fatalf("filtered status = %d body=%s", code, body)
+	}
+	var payload struct {
+		Total int64 `json:"total"`
+	}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload.Total != 1 {
+		t.Fatalf("total = %d, want 1 (filtered response must not be served from the unfiltered cache)", payload.Total)
+	}
+}
+
+// 未观看筛选：已看完的不出现，看了一半的仍出现。
+func TestListMediaUnwatchedFilter(t *testing.T) {
+	router, svc, userID, libID := newLibraryFilterEnv(t)
+	seedLibraryMedia(t, svc,
+		&model.Media{Base: model.Base{ID: "m-done"}, LibraryID: libID, Title: "看完", Path: "/a.mkv"},
+		&model.Media{Base: model.Base{ID: "m-half"}, LibraryID: libID, Title: "看一半", Path: "/b.mkv"},
+	)
+	for _, h := range []*model.PlaybackHistory{
+		{UserID: userID, MediaID: "m-done", Completed: true},
+		{UserID: userID, MediaID: "m-half", Completed: false},
+	} {
+		if err := svc.Repo.DB.Create(h).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	code, body := getJSON(t, router, "/api/libraries/"+libID+"/media?group_versions=0&unwatched=1")
+	if code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", code, body)
+	}
+	var payload struct {
+		Items []model.Media `json:"items"`
+	}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		t.Fatal(err)
+	}
+	if len(payload.Items) != 1 || payload.Items[0].Title != "看一半" {
+		t.Fatalf("items = %+v, want only 看一半", payload.Items)
+	}
+}
+
+func TestLibraryRandomReturnsMedia(t *testing.T) {
+	router, svc, _, libID := newLibraryFilterEnv(t)
+	seedLibraryMedia(t, svc,
+		&model.Media{LibraryID: libID, Title: "唯一", Genres: "Action", Path: "/a.mkv"},
+	)
+
+	code, body := getJSON(t, router, "/api/libraries/"+libID+"/random")
+	if code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", code, body)
+	}
+	var media model.Media
+	if err := json.Unmarshal(body, &media); err != nil {
+		t.Fatalf("decode %s: %v", body, err)
+	}
+	if media.Title != "唯一" {
+		t.Fatalf("title = %q, want 唯一", media.Title)
+	}
+}
+
+// 筛选后没有命中时返回 404，前端据此提示「没有符合条件的媒体」。
+func TestLibraryRandomEmptyResultIs404(t *testing.T) {
+	router, svc, _, libID := newLibraryFilterEnv(t)
+	seedLibraryMedia(t, svc,
+		&model.Media{LibraryID: libID, Title: "动作", Genres: "Action", Path: "/a.mkv"},
+	)
+
+	code, body := getJSON(t, router, "/api/libraries/"+libID+"/random?genre=Nonexistent")
+	if code != http.StatusNotFound {
+		t.Fatalf("status = %d body=%s, want 404", code, body)
+	}
+}
+
+// axios 默认把数组序列化为 genre[]=Action 格式；后端必须把它当作 genre=Action 处理。
+func TestListMediaAcceptsBracketGenreParam(t *testing.T) {
+	router, svc, _, libID := newLibraryFilterEnv(t)
+	seedLibraryMedia(t, svc,
+		&model.Media{LibraryID: libID, Title: "动作", Genres: "Action", Path: "/a.mkv"},
+		&model.Media{LibraryID: libID, Title: "喜剧", Genres: "Comedy", Path: "/b.mkv"},
+	)
+
+	// genre[]=Action — axios bracket format without custom paramsSerializer
+	code, body := getJSON(t, router, "/api/libraries/"+libID+"/media?group_versions=0&genre[]=Action")
+	if code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", code, body)
+	}
+	var payload struct {
+		Items []model.Media `json:"items"`
+		Total int64         `json:"total"`
+	}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		t.Fatalf("decode %s: %v", body, err)
+	}
+	if payload.Total != 1 || len(payload.Items) != 1 || payload.Items[0].Title != "动作" {
+		t.Fatalf("payload = %+v, want only 动作 for genre[]=Action", payload)
+	}
+}
+
+// 随机也遵守筛选：只命中 Action 时，带 Comedy 筛选必须 404。
+func TestLibraryRandomHonoursFilters(t *testing.T) {
+	router, svc, _, libID := newLibraryFilterEnv(t)
+	seedLibraryMedia(t, svc,
+		&model.Media{LibraryID: libID, Title: "A", Genres: "Action", Year: 2001, Path: "/a.mkv"},
+		&model.Media{LibraryID: libID, Title: "B", Genres: "Comedy", Year: 2002, Path: "/b.mkv"},
+	)
+
+	code, body := getJSON(t, router, "/api/libraries/"+libID+"/random?genre=Comedy&year_min=2002")
+	if code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", code, body)
+	}
+	var media model.Media
+	if err := json.Unmarshal(body, &media); err != nil {
+		t.Fatal(err)
+	}
+	if media.Title != "B" {
+		t.Fatalf("title = %q, want B", media.Title)
+	}
+}

internal/handler/media.go

@@ -4,6 +4,7 @@ package handler
 import (
 	"context"
 	"errors"
+	"math"
 	"net/http"
 	"strconv"
 	"strings"
@@ -36,7 +37,7 @@ type webLibraryPayload struct {
 	IsRemoteEmby bool                     `json:"is_remote_emby,omitempty"`
 	RemoteSource string                   `json:"remote_source,omitempty"`
 	Total        int64                    `json:"total,omitempty"`
-	Cards        []service.SeriesCard `json:"cards,omitempty"`
+	Cards        []service.SeriesCardView `json:"cards,omitempty"`
 }
 
 // remoteLibraryItemTypes 远程库内容拉取时按 CollectionType 过滤直属条目，
@@ -115,7 +116,11 @@ func listLibrariesHandler(svc *service.Container) gin.HandlerFunc {
 				return
 			}
 			for _, p := range previews {
-				out = append(out, webLibraryPayload{Library: p.Library, Total: p.Total, Cards: p.Cards})
+				out = append(out, webLibraryPayload{
+					Library: p.Library,
+					Total:   p.Total,
+					Cards:   service.NewSeriesCardViews(p.Cards),
+				})
 			}
 		} else {
 			visibility := mediaVisibilityForRequest(c, svc)
@@ -202,7 +207,7 @@ func listLibrariesHandler(svc *service.Container) gin.HandlerFunc {
 									remotePayloads[i].Total = total
 								}
 								if cards, err := svc.EmbyRemote.RemoteLatestCards(ctx, tmpMount, acct, v.RemoteID, limit); err == nil {
-									remotePayloads[i].Cards = cards
+									remotePayloads[i].Cards = service.NewSeriesCardViews(cards)
 								}
 							})
 						}()
@@ -403,6 +408,92 @@ func deleteLibraryHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }
 
+// parseLibraryFilters 解析媒体库列表的筛选查询参数。
+//
+// 全部参数都是可选的：缺省时返回零值，`MediaListFilters.empty()` 为真，列表
+// 行为与此前完全一致（不引入任何默认筛选）。
+//
+// 参数约定：
+//   - genre=Action&genre=Comedy  类型多选（或关系，整词匹配）
+//   - year_min / year_max        年份区间，0 或非法值表示不限
+//   - rating_min                 评分下限（浮点）
+//   - unwatched=1                仅显示未看完；用户 ID 取自会话
+func parseLibraryFilters(c *gin.Context) service.MediaListFilters {
+	filters := service.MediaListFilters{
+		Genres:    parseRepeatedQueryValues(c, "genre"),
+		YearMin:   parseNonNegativeInt(firstQueryValue(c, "year_min", "yearMin")),
+		YearMax:   parseNonNegativeInt(firstQueryValue(c, "year_max", "yearMax")),
+		RatingMin: parseNonNegativeFloat(firstQueryValue(c, "rating_min", "ratingMin")),
+	}
+	if isTruthyQuery(firstQueryValue(c, "unwatched", "unwatched_only", "unwatchedOnly")) {
+		filters.Unwatched = true
+		filters.UserID = toString(mustSessionUserID(c))
+	}
+	return filters
+}
+
+// parseRepeatedQueryValues 读取可重复出现的查询参数，去重并丢弃空值。
+// 同时接受 key[] 括号格式（axios 1.x 默认序列化方式）作为向后兼容回退，
+// 在前端 paramsSerializer 未正确配置时不会静默返回空结果。
+func parseRepeatedQueryValues(c *gin.Context, key string) []string {
+	raw := c.QueryArray(key)
+	if len(raw) == 0 {
+		// fallback: axios bracket format (e.g. genre[]=Action&genre[]=Comedy)
+		raw = c.QueryArray(key + "[]")
+	}
+	if len(raw) == 0 {
+		return nil
+	}
+	seen := make(map[string]struct{}, len(raw))
+	out := make([]string, 0, len(raw))
+	for _, value := range raw {
+		// 客户端可能把多值拼成一次逗号分隔，两种形式都要接受。
+		for _, part := range strings.Split(value, ",") {
+			trimmed := strings.TrimSpace(part)
+			if trimmed == "" {
+				continue
+			}
+			if _, ok := seen[trimmed]; ok {
+				continue
+			}
+			seen[trimmed] = struct{}{}
+			out = append(out, trimmed)
+		}
+	}
+	return out
+}
+
+func parseNonNegativeInt(raw string) int {
+	value, err := strconv.Atoi(strings.TrimSpace(raw))
+	if err != nil || value < 0 {
+		return 0
+	}
+	return value
+}
+
+func parseNonNegativeFloat(raw string) float64 {
+	value, err := strconv.ParseFloat(strings.TrimSpace(raw), 64)
+	if err != nil || value < 0 || math.IsNaN(value) {
+		return 0
+	}
+	return value
+}
+
+func isTruthyQuery(raw string) bool {
+	switch strings.ToLower(strings.TrimSpace(raw)) {
+	case "1", "true", "yes", "on":
+		return true
+	default:
+		return false
+	}
+}
+
+// mustSessionUserID 取会话用户 ID，缺失时返回空串（筛选逻辑会忽略它）。
+func mustSessionUserID(c *gin.Context) any {
+	uid, _ := c.Get(middleware.CtxUserID)
+	return uid
+}
+
 func listMediaHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		id := c.Param("id")
@@ -446,9 +537,10 @@ func listMediaHandler(svc *service.Container) gin.HandlerFunc {
 		if sortSpec.Field == "last_played" {
 			history = mediaHistoryMap(c, svc)
 		}
+		filters := parseLibraryFilters(c)
 		groupVersions := c.DefaultQuery("group_versions", "1") != "0"
 		if !groupVersions {
-			items, total, err := svc.Media.ListMediaVisible(ctx, id, page, size, mediaVisibilityForRequest(c, svc))
+			items, total, err := svc.Media.ListMediaVisibleFiltered(ctx, id, page, size, mediaVisibilityForRequest(c, svc), filters)
 			if err != nil {
 				writeInternalOrCanceled(c, err)
 				return
@@ -464,7 +556,7 @@ func listMediaHandler(svc *service.Container) gin.HandlerFunc {
 			})
 			return
 		}
-		grouped, err := svc.Media.GroupedMediaVisible(ctx, id, mediaVisibilityForRequest(c, svc))
+		grouped, err := svc.Media.GroupedMediaVisibleFiltered(ctx, id, mediaVisibilityForRequest(c, svc), filters)
 		if err != nil {
 			writeInternalOrCanceled(c, err)
 			return
@@ -718,7 +810,9 @@ func streamHandler(svc *service.Container) gin.HandlerFunc {
 				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 				return
 			}
-			if mount.ProxyPlay {
+			// 远程 Emby 条目的同源转发：VR 全景需要浏览器读帧（见 stream_proxy.go），
+			// 与挂载账号的 proxy_play 开关等价。
+			if mount.ProxyPlay || wantSameOriginProxy(c) {
 				if err := svc.Emby.ProxyRemoteVideoStream(ctx, c.Writer, c.Request, mountID, remoteID); err != nil {
 					if !c.Writer.Written() {
 						c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
@@ -754,6 +848,15 @@ func streamHandler(svc *service.Container) gin.HandlerFunc {
 		if !enforceScopedPlaybackToken(c, m.ID) {
 			return
 		}
+		// ?proxy=1：把网盘/STRM 直链改为服务端同源转发（网页端读帧、VR 全景用），
+		// 画质与原文件一致，不触发转码。
+		if wantSameOriginProxy(c) {
+			handled, proxyErr := proxySTRMStream(c, svc, m)
+			if handled {
+				writeProxyError(c, proxyErr)
+				return
+			}
+		}
 		err = svc.Stream.ServeFile(c.Writer, c.Request, c.Param("id"))
 		if errors.Is(err, service.ErrMediaNotFound) {
 			c.JSON(http.StatusNotFound, gin.H{"error": "not found"})

internal/handler/pinned_libraries.go

@@ -6,6 +6,7 @@ import (
 	"github.com/gin-gonic/gin"
 
 	"github.com/truewhile/MeBox/internal/middleware"
+	"github.com/truewhile/MeBox/internal/model"
 	"github.com/truewhile/MeBox/internal/service"
 )
 
@@ -13,6 +14,45 @@ type pinnedLibrariesReq struct {
 	LibraryIDs []string `json:"library_ids"`
 }
 
+type libraryTagsReq struct {
+	Tags []model.LibraryTagSet `json:"tags"`
+}
+
+func getLibraryTagsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		uid, _ := c.Get(middleware.CtxUserID)
+		tags, err := svc.Profile.GetLibraryTags(c.Request.Context(), uid.(string))
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		if tags == nil {
+			tags = []model.LibraryTagSet{}
+		}
+		c.JSON(http.StatusOK, gin.H{"tags": tags})
+	}
+}
+
+func setLibraryTagsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var req libraryTagsReq
+		if err := c.ShouldBindJSON(&req); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		uid, _ := c.Get(middleware.CtxUserID)
+		tags, err := svc.Profile.SetLibraryTags(c.Request.Context(), uid.(string), req.Tags)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		if tags == nil {
+			tags = []model.LibraryTagSet{}
+		}
+		c.JSON(http.StatusOK, gin.H{"tags": tags})
+	}
+}
+
 func getPinnedLibrariesHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		uid, _ := c.Get(middleware.CtxUserID)

internal/handler/playback_extra_test.go

@@ -346,6 +346,9 @@ func newPlaybackScopeTestRouter(t *testing.T) (*gin.Engine, *service.Container,
 		&model.Library{},
 		&model.Media{},
 		&model.PlayProfile{},
+		&model.Series{},
+		&model.MediaSegment{},
+		&model.MediaSegmentFetch{},
 	); err != nil {
 		t.Fatal(err)
 	}
@@ -408,6 +411,7 @@ func newPlaybackScopeTestRouter(t *testing.T) (*gin.Engine, *service.Container,
 	api := router.Group("/api")
 	api.Use(middleware.AuthRequired(cfg.Secrets.JWTSecret))
 	api.GET("/playback/:id/info", playbackInfoHandler(svc))
+	api.GET("/playback/:id/segments", playbackSegmentsHandler(svc))
 	api.GET("/playback/:id/external-url", externalURLHandler(svc))
 	api.GET("/playback/:id/external-players", externalPlayersHandler(svc))
 	api.GET("/stream/:id", streamHandler(svc))

internal/handler/playback_segments.go

@@ -0,0 +1,55 @@
+// Package handler — 片头/片尾片段接口。
+//
+//	GET /playback/:id/segments
+//
+// 单独开一个接口而不是塞进 /media/:id/playback，有两个原因：一是抓取外部数据
+// 可能要几秒，不能拖慢决定能否起播的那个请求；二是片段与播放来源（本地 / 云盘 /
+// 远程 Emby）无关，独立出来对所有媒体一致。
+package handler
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// playbackSegmentsHandler returns the skippable ranges for one media item.
+// The client calls it after playback has already started, so the provider
+// lookup never delays a play.
+func playbackSegmentsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		autoSkip := resolveAutoSkipFlag(c, svc)
+		segments := []service.SegmentView{}
+
+		m, err := findMediaForPlaybackEndpoint(c, svc, c.Param("id"))
+		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
+			c.JSON(http.StatusNotFound, gin.H{"error": "media not found"})
+			return
+		}
+		// 远程 Emby 挂载的条目是上游库的投影，本地没有可查询的外部 ID 关联。
+		if svc.Segments != nil && !service.IsEmbyRemoteID(m.ID) {
+			rows, listErr := svc.Segments.ListForPlayback(c.Request.Context(), m)
+			if listErr != nil && svc.Log != nil {
+				svc.Log.Debug("list media segments failed",
+					zap.String("media_id", m.ID), zap.Error(listErr))
+			}
+			segments = service.ToSegmentViews(rows)
+		}
+		c.JSON(http.StatusOK, gin.H{"segments": segments, "auto_skip": autoSkip})
+	}
+}
+
+// resolveAutoSkipFlag reads the「自动跳过片头」switch off whichever profile is
+// currently in effect. It reuses selectedPlayProfile so the server agrees with
+// the UI about which profile is active (explicit header first, then the user's
+// default profile), and a PIN-locked profile never silently skips for the user.
+func resolveAutoSkipFlag(c *gin.Context, svc *service.Container) bool {
+	profile, locked := selectedPlayProfile(c, svc)
+	if locked || profile == nil {
+		return false
+	}
+	return profile.SkipIntro
+}

internal/handler/playback_segments_test.go

@@ -0,0 +1,134 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+type segmentPayload struct {
+	Segments []struct {
+		Kind    string `json:"kind"`
+		StartMs int64  `json:"start_ms"`
+		EndMs   int64  `json:"end_ms"`
+	} `json:"segments"`
+	AutoSkip bool `json:"auto_skip"`
+}
+
+const segmentsProviderBody = `{"tmdb_id":27205,"type":"movie","intro":[{"start_ms":null,"end_ms":38000}],"credits":[{"start_ms":6480000,"end_ms":null}]}`
+
+func TestPlaybackSegmentsReturnsProviderDataAndAutoSkip(t *testing.T) {
+	router, svc, secret := newPlaybackScopeTestRouter(t)
+	// 片段数据与播放来源无关，云盘媒体同样适用，只要它能解析出外部 ID。
+	// 注意列名是 tm_db_id（GORM 对 TMDbID 的默认命名）。
+	if err := svc.Repo.DB.Model(&model.Media{}).
+		Where("id = ?", "media-1").Update("tm_db_id", 27205).Error; err != nil {
+		t.Fatal(err)
+	}
+	var calls int32
+	provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(segmentsProviderBody))
+	}))
+	defer provider.Close()
+	svc.Segments = service.NewMediaSegmentService(zap.NewNop(), svc.Repo).
+		SetIntroDB(service.NewIntroDBService(zap.NewNop()).SetBaseURL(provider.URL))
+
+	// 默认档案打开「自动跳过片头」，接口应把开关原样带出来。
+	if err := svc.Repo.DB.Create(&model.PlayProfile{
+		Base:      model.Base{ID: "profile-1"},
+		UserID:    "user-1",
+		Name:      "主档案",
+		IsDefault: true,
+		SkipIntro: true,
+	}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	loginToken := signedTestToken(t, secret)
+	fetch := func() segmentPayload {
+		t.Helper()
+		req := httptest.NewRequest(http.MethodGet, "http://nas.local/api/playback/media-1/segments", nil)
+		req.Header.Set("Authorization", "Bearer "+loginToken)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+		if w.Code != http.StatusOK {
+			t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+		}
+		var payload segmentPayload
+		if err := json.Unmarshal(w.Body.Bytes(), &payload); err != nil {
+			t.Fatalf("decode: %v", err)
+		}
+		return payload
+	}
+
+	first := fetch()
+	if !first.AutoSkip {
+		t.Fatal("auto_skip should reflect the active profile's skip_intro switch")
+	}
+	if len(first.Segments) != 2 {
+		t.Fatalf("segments = %#v, want 2", first.Segments)
+	}
+	// start_ms: null -> 0；end_ms: null -> 0（延续到片尾，由客户端按时长补齐）。
+	if first.Segments[0].Kind != "intro" || first.Segments[0].StartMs != 0 || first.Segments[0].EndMs != 38_000 {
+		t.Fatalf("intro segment = %#v", first.Segments[0])
+	}
+	if first.Segments[1].Kind != "credits" || first.Segments[1].StartMs != 6_480_000 || first.Segments[1].EndMs != 0 {
+		t.Fatalf("credits segment = %#v", first.Segments[1])
+	}
+
+	// 第二次播放必须走本地缓存，不再打外网。
+	if second := fetch(); len(second.Segments) != 2 {
+		t.Fatalf("second fetch segments = %#v", second.Segments)
+	}
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("provider calls = %d, want 1", got)
+	}
+}
+
+func TestPlaybackSegmentsAutoSkipIsFalseWithoutProfile(t *testing.T) {
+	router, svc, secret := newPlaybackScopeTestRouter(t)
+	svc.Segments = service.NewMediaSegmentService(zap.NewNop(), svc.Repo)
+
+	req := httptest.NewRequest(http.MethodGet, "http://nas.local/api/playback/media-1/segments", nil)
+	req.Header.Set("Authorization", "Bearer "+signedTestToken(t, secret))
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	var payload segmentPayload
+	if err := json.Unmarshal(w.Body.Bytes(), &payload); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if payload.AutoSkip {
+		t.Fatal("auto_skip must default to false")
+	}
+	// 即使一条片段都没有，也必须返回空数组而不是 null，前端才能无条件遍历。
+	if payload.Segments == nil {
+		t.Fatal("segments must serialise as an empty array, not null")
+	}
+}
+
+func TestPlaybackSegmentsForUnknownMediaReturnsNotFound(t *testing.T) {
+	router, svc, secret := newPlaybackScopeTestRouter(t)
+	svc.Segments = service.NewMediaSegmentService(zap.NewNop(), svc.Repo)
+
+	req := httptest.NewRequest(http.MethodGet, "http://nas.local/api/playback/does-not-exist/segments", nil)
+	req.Header.Set("Authorization", "Bearer "+signedTestToken(t, secret))
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("status = %d body=%s, want 404", w.Code, w.Body.String())
+	}
+}

internal/handler/routes_admin.go

@@ -116,8 +116,13 @@ func registerAdminUserRoutes(admin *gin.RouterGroup, svc *service.Container) {
 	admin.PATCH("/users/:id/role", adminUpdateRoleHandler(svc))
 	admin.PATCH("/users/:id/libraries", updateUserLibrariesHandler(svc))
 	admin.DELETE("/users/:id", deleteUserHandler(svc))
+	// 设备代管：管理员可查看并踢掉任意用户的设备。
+	admin.GET("/users/:id/devices", adminUserDevicesHandler(svc))
+	admin.POST("/users/:id/devices/kick-all", adminKickAllUserDevicesHandler(svc))
+	admin.POST("/users/:id/devices/:deviceID/kick", adminKickUserDeviceHandler(svc))
 	admin.GET("/settings", listSettingsHandler(svc))
 	admin.PUT("/settings", updateSettingHandler(svc))
+	admin.POST("/telegram/test", testTelegramHandler(svc))
 	admin.POST("/adult/test-scraper", testAdultScraperHandler(svc))
 	admin.GET("/logs", recentLogsHandler(svc))
 }

internal/handler/routes_authenticated_core.go

@@ -12,11 +12,23 @@ func registerAuthedUserAndLicenseRoutes(authed *gin.RouterGroup, svc *service.Co
 	authed.PATCH("/me", updateProfileHandler(svc))
 	authed.GET("/me/pinned-libraries", getPinnedLibrariesHandler(svc))
 	authed.PUT("/me/pinned-libraries", setPinnedLibrariesHandler(svc))
+	authed.GET("/me/library-tags", getLibraryTagsHandler(svc))
+	authed.PUT("/me/library-tags", setLibraryTagsHandler(svc))
 	authed.POST("/me/password", changePasswordHandler(svc))
 	authed.POST("/me/logout", logoutHandler(svc))
 	authed.GET("/me/temporary-password", temporaryPasswordHandler(svc))
 	authed.POST("/me/temporary-password", temporaryPasswordHandler(svc))
 
+	// 设备管理：路由挂在 /me 下，用户 ID 一律取自会话，天然只能管自己的设备。
+	authed.GET("/me/devices", myDevicesHandler(svc))
+	authed.POST("/me/devices/kick-all", myKickAllDevicesHandler(svc))
+	authed.POST("/me/devices/:deviceID/kick", myKickDeviceHandler(svc))
+
+	// Telegram 通知绑定：一次性码 + Bot /bind <code>。
+	authed.GET("/me/telegram", getTelegramStatusHandler(svc))
+	authed.POST("/me/telegram/bind-code", startTelegramBindHandler(svc))
+	authed.DELETE("/me/telegram", unbindTelegramHandler(svc))
+
 	authed.GET("/auth/permissions", getMyPermissionsHandler(svc))
 }
 
@@ -36,6 +48,8 @@ func registerAuthedLibraryRoutes(authed *gin.RouterGroup, svc *service.Container
 	authed.POST("/libraries/:id/scrape", middleware.AdminRequired(), scrapeLibraryHandler(svc))
 
 	authed.GET("/libraries/:id/media", listMediaHandler(svc))
+	authed.GET("/libraries/:id/facets", libraryFacetsHandler(svc))
+	authed.GET("/libraries/:id/random", libraryRandomHandler(svc))
 	authed.GET("/libraries/:id/series", listLibrarySeriesHandler(svc))
 	authed.GET("/libraries/:id/series/episodes", listLibrarySeriesEpisodesHandler(svc))
 	authed.GET("/libraries/:id/seasons", listSeasonsHandler(svc))
@@ -44,6 +58,8 @@ func registerAuthedLibraryRoutes(authed *gin.RouterGroup, svc *service.Container
 func registerAuthedMediaRoutes(authed *gin.RouterGroup, svc *service.Container) {
 	authed.GET("/media/:id", getMediaHandler(svc))
 	authed.GET("/media/:id/episodes", listMediaEpisodesHandler(svc))
+	authed.GET("/media/:id/playback", mediaPlaybackInfoHandler(svc))
+	authed.POST("/media/:id/transcode", mediaTranscodeHandler(svc))
 	authed.GET("/media", searchMediaHandler(svc))
 	authed.PATCH("/media/:id/metadata", middleware.AdminRequired(), updateMediaMetadataHandler(svc))
 	authed.POST("/media/:id/scrape", middleware.AdminRequired(), scrapeOneHandler(svc))
@@ -65,6 +81,10 @@ func registerAuthedPlaybackAndProxyRoutes(authed *gin.RouterGroup, svc *service.
 	authed.GET("/hls/:id/index.m3u8", hlsPlaylistHandler(svc))
 	authed.GET("/hls/:id/:seg", hlsSegmentHandler(svc))
 	authed.DELETE("/hls/:id", stopTranscodeHandler(svc))
+	authed.GET("/cloud115/media/:id/master.m3u8", cloud115HLSMasterHandler(svc))
+	authed.HEAD("/cloud115/media/:id/master.m3u8", cloud115HLSMasterHandler(svc))
+	authed.GET("/cloud115/hls/:session/:key", cloud115HLSSessionHandler(svc))
+	authed.HEAD("/cloud115/hls/:session/:key", cloud115HLSSessionHandler(svc))
 
 	authed.GET("/img", imageProxyHandler(svc))
 }

internal/handler/routes_authenticated_extras.go

@@ -15,7 +15,7 @@ func registerAuthedUISurfaceRoutes(authed *gin.RouterGroup, svc *service.Contain
 	authed.PUT("/danmaku/settings", updateDanmakuSettingsHandler(svc))
 
 	authed.GET("/watch-history", historyListHandler(svc))
-	authed.GET("/watch-history/stats", historyStatsHandler(svc))
+	authed.GET("/watch-history/stats", requirePermission(svc, "can_view_history"), historyStatsHandler(svc))
 	authed.GET("/watch-history/continue", historyContinueHandler(svc))
 	authed.DELETE("/watch-history", historyDeleteHandler(svc))
 	authed.DELETE("/watch-history/:id", historyDeleteOneHandler(svc))
@@ -73,6 +73,7 @@ func registerAuthedFavoriteAndMediaActionRoutes(authed *gin.RouterGroup, svc *se
 func registerAuthedPlaybackExtraRoutes(authed *gin.RouterGroup, svc *service.Container) {
 	authed.GET("/playback/:id/info", playbackInfoHandler(svc))
 	authed.GET("/playback/:id/resume", playbackResumeHandler(svc))
+	authed.GET("/playback/:id/segments", playbackSegmentsHandler(svc))
 	authed.POST("/playback/:id/progress", playbackProgressHandler(svc))
 	authed.GET("/playback/:id/external-players", externalPlayersHandler(svc))
 	authed.GET("/playback/:id/external-url", externalURLHandler(svc))

internal/handler/routes_authenticated_test.go

@@ -27,6 +27,8 @@ func TestAuthenticatedRouteSurfacesAreRegistered(t *testing.T) {
 		"GET /api/me",
 		"GET /api/me/pinned-libraries",
 		"PUT /api/me/pinned-libraries",
+		"GET /api/me/library-tags",
+		"PUT /api/me/library-tags",
 		"GET /api/auth/permissions",
 		"GET /api/libraries",
 		"GET /api/media",
@@ -34,6 +36,7 @@ func TestAuthenticatedRouteSurfacesAreRegistered(t *testing.T) {
 		"GET /api/storage",
 		"GET /api/watch-history",
 		"GET /api/playback/:id/info",
+		"GET /api/playback/:id/segments",
 	} {
 		if !routes[want] {
 			t.Fatalf("%s route is not registered", want)

internal/handler/series.go

@@ -89,7 +89,7 @@ func listLibrarySeriesHandler(svc *service.Container) gin.HandlerFunc {
 				writeInternalOrCanceled(c, err)
 				return
 			}
-			cards = service.SortSeriesCards(cards, sortSpec.Field, sortSpec.Order, history)
+			cards = sortRemoteSeriesCards(cards, sortSpec, history)
 			page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
 			size, _ := strconv.Atoi(c.DefaultQuery("page_size", "500"))
 			if page < 1 {
@@ -124,7 +124,9 @@ func listLibrarySeriesHandler(svc *service.Container) gin.HandlerFunc {
 				return
 			}
 		}
-		items, total, err := svc.Media.ListLibrarySeriesCards(c.Request.Context(), libID, mediaVisibilityForRequest(c, svc))
+		items, total, err := svc.Media.ListLibrarySeriesCardsFiltered(
+			c.Request.Context(), libID, mediaVisibilityForRequest(c, svc), parseLibraryFilters(c),
+		)
 		if err != nil {
 			writeInternalOrCanceled(c, err)
 			return

internal/handler/series_sort.go

@@ -0,0 +1,23 @@
+package handler
+
+import (
+	"slices"
+	"time"
+
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// sortRemoteSeriesCards keeps the DateLastContentAdded order returned by the
+// remote Emby server when LastAddedAt is not exposed in the Series DTO.
+func sortRemoteSeriesCards(cards []service.SeriesCard, spec service.MediaSortSpec, history map[string]time.Time) []service.SeriesCard {
+	if spec.Field != "updated_at" {
+		return service.SortSeriesCards(cards, spec.Field, spec.Order, history)
+	}
+
+	out := append([]service.SeriesCard(nil), cards...)
+	// RemoteSeriesCards always fetches DateLastContentAdded in descending order.
+	if spec.Order == "asc" {
+		slices.Reverse(out)
+	}
+	return service.SortSeriesCards(out, spec.Field, spec.Order, history)
+}

internal/handler/series_sort_test.go

@@ -0,0 +1,21 @@
+package handler
+
+import (
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+func TestSortRemoteSeriesCardsUpdatedAtUsesRemoteOrder(t *testing.T) {
+	cards := []service.SeriesCard{{Key: "newest"}, {Key: "middle"}, {Key: "oldest"}}
+
+	desc := sortRemoteSeriesCards(cards, service.MediaSortSpec{Field: "updated_at", Order: "desc"}, nil)
+	if desc[0].Key != "newest" || desc[1].Key != "middle" || desc[2].Key != "oldest" {
+		t.Fatalf("descending order = %q, %q, %q", desc[0].Key, desc[1].Key, desc[2].Key)
+	}
+
+	asc := sortRemoteSeriesCards(cards, service.MediaSortSpec{Field: "updated_at", Order: "asc"}, nil)
+	if asc[0].Key != "oldest" || asc[1].Key != "middle" || asc[2].Key != "newest" {
+		t.Fatalf("ascending order = %q, %q, %q", asc[0].Key, asc[1].Key, asc[2].Key)
+	}
+}

internal/handler/stream_proxy.go

@@ -0,0 +1,56 @@
+// 直连流的同源转发：网页端需要读取视频帧的场景（VR 全景渲染走 WebGL 纹理）
+// 不能使用会跳到网盘 CDN 的跨域直链，这里把直链改为服务端转发。
+//
+// 只在客户端显式带上 ?proxy=1 时生效，普通播放仍走原来的 302 直连，
+// 避免把网盘流量无谓地压到服务器上。
+package handler
+
+import (
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// wantSameOriginProxy 客户端是否要求把直连流改为服务端同源转发。
+func wantSameOriginProxy(c *gin.Context) bool {
+	if c == nil {
+		return false
+	}
+	switch strings.ToLower(strings.TrimSpace(c.Query("proxy"))) {
+	case "1", "true", "yes":
+		return true
+	default:
+		return false
+	}
+}
+
+// proxySTRMStream 处理 STRM/网盘媒体的同源转发请求。返回 handled=false 表示
+// 该媒体不需要（或无法）代理，调用方继续按原有逻辑处理。
+func proxySTRMStream(c *gin.Context, svc *service.Container, m *model.Media) (bool, error) {
+	if c == nil || svc == nil || svc.Strm == nil || m == nil {
+		return false, nil
+	}
+	if !service.IsStrmMediaRow(m) {
+		return false, nil
+	}
+	if err := svc.Strm.ProxyMediaDirect(c.Request.Context(), c.Writer, c.Request, m); err != nil {
+		if errors.Is(err, service.ErrStrmProxyNotApplicable) {
+			return false, nil
+		}
+		return true, err
+	}
+	return true, nil
+}
+
+// writeProxyError 在尚未写入任何响应内容时回一个明确的网关错误。
+func writeProxyError(c *gin.Context, err error) {
+	if c == nil || err == nil || c.Writer.Written() {
+		return
+	}
+	c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+}

internal/handler/strm.go

@@ -138,26 +138,36 @@ func testStrmAccountHandler(svc *service.Container) gin.HandlerFunc {
 			return
 		}
 		now := time.Now()
-		acct.LastTestAt = &now
 		if acct.Provider == model.StrmProviderEmbyRemote && svc.EmbyRemote != nil {
+			result := ""
+			ok := false
 			if err := svc.EmbyRemote.TestConnection(c.Request.Context(), acct); err != nil {
-				acct.LastTestResult = err.Error()
-				acct.LastTestOK = false
+				result = err.Error()
 			} else {
-				acct.LastTestResult = "ok"
-				acct.LastTestOK = true
+				result = "ok"
+				ok = true
+			}
+			acct.LastTestAt = &now
+			acct.LastTestResult = result
+			acct.LastTestOK = ok
+			if err := svc.Repo.StrmAccount.UpdateTestResult(c.Request.Context(), acct.ID, now, result, ok); err != nil {
+				// 写库失败时仍返回本地测试结果；不要回退到整行 Update，
+				// 那会覆盖 TestConnection 期间可能刷新的账号配置。
+				c.JSON(http.StatusOK, strmAccountViews(svc, []model.StrmAccount{*acct})[0])
+				return
+			}
+			if fresh, err := svc.Repo.StrmAccount.FindByID(c.Request.Context(), acct.ID); err == nil && fresh != nil {
+				acct = fresh
+			}
+			c.JSON(http.StatusOK, strmAccountViews(svc, []model.StrmAccount{*acct})[0])
+			return
 		}
-		} else {
 		acct = svc.Strm.TestStrmAccount(c.Request.Context(), id)
 		if acct == nil {
 			c.JSON(http.StatusNotFound, gin.H{"error": "网盘账号不存在"})
 			return
 		}
 		c.JSON(http.StatusOK, strmAccountViews(svc, []model.StrmAccount{*acct})[0])
-			return
-		}
-		_ = svc.Repo.StrmAccount.Update(c.Request.Context(), acct)
-		c.JSON(http.StatusOK, strmAccountViews(svc, []model.StrmAccount{*acct})[0])
 	}
 }
 

internal/handler/telegram_me.go

@@ -0,0 +1,89 @@
+package handler
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// Telegram 绑定与测试接口。
+//
+// 绑定刻意做成「网页生成一次性码 → 用户在 Bot 里发 /bind <码>」：服务端不需要
+// 用户手工填写 chat id，也不需要站点暴露 Bot 命令以外任何能力。
+
+type telegramBindCodePayload struct {
+	Code      string `json:"code"`
+	ExpiresIn int    `json:"expires_in_seconds"`
+}
+
+// startTelegramBindHandler 生成一次性绑定码。同一用户重复调用时旧码作废。
+func startTelegramBindHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc.Telegram == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "telegram service unavailable"})
+			return
+		}
+		userID := sessionUserID(c)
+		code, err := svc.Telegram.StartBind(c.Request.Context(), userID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, telegramBindCodePayload{Code: code, ExpiresIn: 300})
+	}
+}
+
+// getTelegramStatusHandler 返回绑定状态与脱敏会话 ID。
+func getTelegramStatusHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc.Telegram == nil {
+			c.JSON(http.StatusOK, gin.H{"bound": false})
+			return
+		}
+		bound, masked := svc.Telegram.Status(c.Request.Context(), sessionUserID(c))
+		payload := gin.H{"bound": bound}
+		if bound {
+			payload["chat_id_masked"] = masked
+		}
+		c.JSON(http.StatusOK, payload)
+	}
+}
+
+// unbindTelegramHandler 解除当前用户的 Telegram 绑定。
+func unbindTelegramHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc.Telegram == nil {
+			c.Status(http.StatusNoContent)
+			return
+		}
+		if err := svc.Telegram.Unbind(c.Request.Context(), sessionUserID(c)); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.Status(http.StatusNoContent)
+	}
+}
+
+// testTelegramHandler 向管理员会话发送一条测试消息，用于验证 Token/会话 ID。
+func testTelegramHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc.Telegram == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "telegram service unavailable"})
+			return
+		}
+		if !svc.Telegram.Configured(c.Request.Context()) {
+			c.JSON(http.StatusBadRequest, gin.H{
+				"success": false,
+				"error":   "请先启用 Telegram 通知并填写 Bot Token 与管理员 Chat ID",
+			})
+			return
+		}
+		if err := svc.Telegram.SendToAdminChecked(c.Request.Context(), "✅ MeBox 测试消息：通知通道工作正常。"); err != nil {
+			c.JSON(http.StatusOK, gin.H{"success": false, "error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"success": true})
+	}
+}

internal/handler/watch_history.go

@@ -11,8 +11,11 @@
 package handler
 
 import (
+	"context"
 	"net/http"
+	"sort"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/gin-gonic/gin"
@@ -48,11 +51,16 @@ func historyListHandler(svc *service.Container) gin.HandlerFunc {
 }
 
 // historyStatsHandler returns aggregate watch time + completion counts
-// for the caller. Used by the WatchHistoryPage hero card.
+// for the caller. Used by the WatchHistoryPage hero card and the dedicated
+// personal statistics page.
+//
+// 统计口径全部来自 PlaybackHistory 本身，不新增统计表：position_ms 是「已看
+// 时长」的近似值，足以支撑趋势图；精确到秒的播放时长另有会话统计负责。
 func historyStatsHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		uid, _ := c.Get(middleware.CtxUserID)
 		userID := toString(uid)
+		ctx := c.Request.Context()
 
 		var total int64
 		_ = svc.Repo.DB.Model(&model.PlaybackHistory{}).
@@ -77,28 +85,209 @@ func historyStatsHandler(svc *service.Container) gin.HandlerFunc {
 			last = &lastT
 		}
 
+		visibility := mediaVisibilityForRequest(c, svc)
+		daily, byType, recent := historyStatsBreakdowns(ctx, svc, userID, visibility)
+
+		inProgress := total - completed
+		if inProgress < 0 {
+			inProgress = 0
+		}
+
 		c.JSON(http.StatusOK, gin.H{
 			"total":           total,
 			"completed":       completed,
+			"in_progress":     inProgress,
 			"watched_ms":      watchedMs,
 			"watched_hours":   float64(watchedMs) / 1000.0 / 3600.0,
 			"last_watched":    last,
+			"daily":           daily,
+			"by_library_type": byType,
+			"recent":          recent,
 		})
 	}
 }
 
+// historyStatsDailyDays 是趋势图回看的天数。
+const historyStatsDailyDays = 30
+
+// historyStatsRecentLimit 是「最近看过」返回的条数。
+const historyStatsRecentLimit = 8
+
+type historyDailyStat struct {
+	Day     string `json:"day"`
+	WatchMs int64  `json:"watch_ms"`
+	Plays   int64  `json:"plays"`
+}
+
+type historyTypeStat struct {
+	Type    string `json:"type"`
+	WatchMs int64  `json:"watch_ms"`
+	Count   int64  `json:"count"`
+}
+
+// historyStatsBreakdowns 产出每日趋势、按媒体库类型分布与最近记录。
+//
+// 分桶在 Go 里做而不是用 SQL 的日期函数：SQLite 的 strftime 与 PostgreSQL 的
+// to_char 语法不同，写两份 SQL 会在方言差异上长期出错，而历史行数受用户规模
+// 约束（每人一行一部媒体），一次全量读取是可以接受的。
+//
+// visibility 控制哪些媒体对调用者可见（播放档案、成人锁等）。
+func historyStatsBreakdowns(ctx context.Context, svc *service.Container, userID string, visibility service.MediaVisibility) ([]historyDailyStat, []historyTypeStat, []map[string]any) {
+	daily := make([]historyDailyStat, 0, historyStatsDailyDays)
+	byType := make([]historyTypeStat, 0)
+	recent := make([]map[string]any, 0, historyStatsRecentLimit)
+
+	var rows []model.PlaybackHistory
+	if err := svc.Repo.DB.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Order("watched_at desc").
+		Find(&rows).Error; err != nil || len(rows) == 0 {
+		return daily, byType, recent
+	}
+
+	// 每日趋势：只回看最近 N 天，且按「本地日」分桶，避免跨时区偏移。
+	now := time.Now()
+	cutoff := now.AddDate(0, 0, -(historyStatsDailyDays - 1))
+	startOfDay := func(t time.Time) time.Time {
+		local := t.In(time.Local)
+		return time.Date(local.Year(), local.Month(), local.Day(), 0, 0, 0, 0, time.Local)
+	}
+	buckets := make(map[string]*historyDailyStat, historyStatsDailyDays)
+	for i := 0; i < historyStatsDailyDays; i++ {
+		day := startOfDay(cutoff).AddDate(0, 0, i).Format("2006-01-02")
+		buckets[day] = &historyDailyStat{Day: day}
+	}
+	for _, r := range rows {
+		watched := r.WatchedAt.In(time.Local)
+		if watched.Before(startOfDay(cutoff)) {
+			continue
+		}
+		if bucket, ok := buckets[watched.Format("2006-01-02")]; ok {
+			bucket.WatchMs += r.PositionMs
+			bucket.Plays++
+		}
+	}
+	for i := 0; i < historyStatsDailyDays; i++ {
+		day := startOfDay(cutoff).AddDate(0, 0, i).Format("2006-01-02")
+		if bucket, ok := buckets[day]; ok && bucket.Plays > 0 {
+			daily = append(daily, *bucket)
+		}
+	}
+
+	mediaIDs := make([]string, 0, len(rows))
+	for _, r := range rows {
+		mediaIDs = append(mediaIDs, r.MediaID)
+	}
+	var medias []model.Media
+	_ = svc.Repo.DB.WithContext(ctx).Where("id IN ?", mediaIDs).Find(&medias).Error
+	mediaByID := make(map[string]*model.Media, len(medias))
+	for i := range medias {
+		mediaByID[medias[i].ID] = &medias[i]
+	}
+
+	libraryTypes := make(map[string]string)
+	var libraries []model.Library
+	if svc.Repo.Library != nil {
+		if libs, err := svc.Repo.Library.List(ctx); err == nil {
+			libraries = libs
+		}
+	}
+	for _, lib := range libraries {
+		libraryTypes[lib.ID] = lib.Type
+	}
+
+	typeAcc := make(map[string]*historyTypeStat)
+	order := make([]string, 0, 4)
+	for _, r := range rows {
+		media := mediaByID[r.MediaID]
+		var key string
+		if media == nil {
+			// 媒体记录已删除（含 Emby 远程缓存失效）：计入 "other" 桶而非丢弃，
+			// 这样类型分布总数才能与播放历史总数吻合。
+			key = "other"
+		} else {
+			// 如果调用者的可见性策略排除了该媒体，则跳过统计（visibility leak fix）。
+			if !visibility.Allows(media) {
+				continue
+			}
+			key = strings.TrimSpace(libraryTypes[media.LibraryID])
+			if key == "" {
+				key = "other"
+			}
+		}
+		acc, ok := typeAcc[key]
+		if !ok {
+			acc = &historyTypeStat{Type: key}
+			typeAcc[key] = acc
+			order = append(order, key)
+		}
+		acc.WatchMs += r.PositionMs
+		acc.Count++
+	}
+	// 顺序按观看时长降序，让「我主要在看什么」一眼可见。
+	for _, key := range order {
+		byType = append(byType, *typeAcc[key])
+	}
+	sort.SliceStable(byType, func(i, j int) bool {
+		if byType[i].WatchMs != byType[j].WatchMs {
+			return byType[i].WatchMs > byType[j].WatchMs
+		}
+		return byType[i].Type < byType[j].Type
+	})
+
+	for _, r := range rows {
+		if len(recent) >= historyStatsRecentLimit {
+			break
+		}
+		entry := map[string]any{"history": r}
+		if media := mediaByID[r.MediaID]; media != nil {
+			// 可见性检查：隐藏库或受档案限制的媒体不进入最近记录（visibility leak fix）。
+			if !visibility.Allows(media) {
+				continue
+			}
+			entry["media"] = media
+		} else if svc.EmbyRemote != nil && service.IsEmbyRemoteID(r.MediaID) {
+			// 尝试从 Emby 远端补全媒体详情，与 historyContinueHandler 保持相同策略。
+			mountID, remoteID, _ := service.DecodeEmbyRemoteID(r.MediaID)
+			mount, acct, resolveErr := svc.EmbyRemote.ResolveMount(ctx, mountID)
+			if resolveErr == nil && mount != nil && acct != nil {
+				remoteMedia, detailErr := svc.EmbyRemote.RemoteMediaDetail(ctx, mount, acct, remoteID)
+				if detailErr == nil && remoteMedia != nil {
+					if !visibility.Allows(remoteMedia) {
+						continue
+					}
+					entry["media"] = *remoteMedia
+				} else {
+					// 无法获取 Emby 媒体详情，跳过此条记录。
+					continue
+				}
+			} else {
+				// 挂载不可用，跳过。
+				continue
+			}
+		} else {
+			// 媒体记录不存在且无法 Emby 补全，跳过。
+			continue
+		}
+		recent = append(recent, entry)
+	}
+
+	return daily, byType, recent
+}
+
 // historyContinueHandler returns "Continue Watching" rows: incomplete
 // items, most recent first.
 func historyContinueHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		uid, _ := c.Get(middleware.CtxUserID)
+		userID := toString(uid)
 		limit, _ := strconv.Atoi(c.DefaultQuery("limit", "10"))
 		if limit <= 0 || limit > 50 {
 			limit = 10
 		}
 		var rows []model.PlaybackHistory
 		if err := svc.Repo.DB.
-			Where("user_id = ? AND completed = ?", toString(uid), false).
+			Where("user_id = ? AND completed = ?", userID, false).
 			Order("watched_at desc").
 			Limit(limit).
 			Find(&rows).Error; err != nil {
@@ -116,58 +305,49 @@ func historyContinueHandler(svc *service.Container) gin.HandlerFunc {
 		}
 		mIdx := make(map[string]model.Media, len(media))
 		for _, m := range media {
-			if !mediaVisibleForRequest(c, svc, &m) {
-				continue
-			}
 			mIdx[m.ID] = m
 		}
 		out := make([]gin.H, 0, len(rows))
+		staleIDs := make([]string, 0)
 		for _, r := range rows {
 			m, ok := mIdx[r.MediaID]
-			if !ok {
-				if svc.EmbyRemote != nil && service.IsEmbyRemoteID(r.MediaID) {
-					mountID, remoteID, _ := service.DecodeEmbyRemoteID(r.MediaID)
-					if mount, acct, _ := svc.EmbyRemote.ResolveMount(c.Request.Context(), mountID); mount != nil && acct != nil {
-						if rm, err := svc.EmbyRemote.RemoteMediaDetail(c.Request.Context(), mount, acct, remoteID); err == nil && rm != nil {
-							if mediaVisibleForRequest(c, svc, rm) {
-								out = append(out, gin.H{
-									"history": r,
-									"media":   *rm,
-								})
-							}
-							continue
-						}
-					}
-				}
-				fallback := fallbackHistoryMedia(r.MediaID)
-				if fallback != nil {
-					out = append(out, gin.H{
-						"history": r,
-						"media":   *fallback,
-					})
-				}
-				continue
-			}
+			if ok {
+				if mediaVisibleForRequest(c, svc, &m) {
 					out = append(out, gin.H{
 						"history": r,
 						"media":   m,
 					})
 				}
-		c.JSON(http.StatusOK, out)
+				continue
 			}
-}
 
-func fallbackHistoryMedia(mediaID string) *model.Media {
-	if mediaID == "" {
-		return nil
+			if svc.EmbyRemote != nil && service.IsEmbyRemoteID(r.MediaID) {
+				mountID, remoteID, _ := service.DecodeEmbyRemoteID(r.MediaID)
+				mount, acct, resolveErr := svc.EmbyRemote.ResolveMount(c.Request.Context(), mountID)
+				if resolveErr == nil && mount != nil && acct != nil {
+					remoteMedia, detailErr := svc.EmbyRemote.RemoteMediaDetail(c.Request.Context(), mount, acct, remoteID)
+					if detailErr == nil && remoteMedia != nil {
+						if mediaVisibleForRequest(c, svc, remoteMedia) {
+							out = append(out, gin.H{
+								"history": r,
+								"media":   *remoteMedia,
+							})
 						}
-	title := "媒体"
-	if service.IsEmbyRemoteID(mediaID) {
-		title = "远程媒体"
+						continue
 					}
-	return &model.Media{
-		Base:  model.Base{ID: mediaID},
-		Title: title,
+				}
+			}
+
+			// 媒体记录已不存在。继续返回占位卡只会让用户点击后遇到 404，
+			// 因此清理这条失效播放记录，不再占用继续观看列表。
+			staleIDs = append(staleIDs, r.MediaID)
+		}
+		if len(staleIDs) > 0 {
+			_ = svc.Repo.DB.WithContext(c.Request.Context()).Unscoped().
+				Where("user_id = ? AND media_id IN ?", userID, staleIDs).
+				Delete(&model.PlaybackHistory{}).Error
+		}
+		c.JSON(http.StatusOK, out)
 	}
 }
 

internal/handler/watch_history_stats_test.go

@@ -0,0 +1,349 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/middleware"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+func newHistoryStatsEnv(t *testing.T) (*gin.Engine, *service.Container, string) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(&model.User{}, &model.Library{}, &model.Media{}, &model.PlaybackHistory{}, &model.UserPermission{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	repos := repository.New(db)
+	svc := &service.Container{Repo: repos, Log: zap.NewNop()}
+	svc.Permissions = service.NewPermissionService(zap.NewNop(), repos)
+
+	const userID = "user-1"
+	if err := repos.User.Create(context.Background(), &model.User{
+		Base: model.Base{ID: userID}, Username: "tester", PasswordHash: "x", Role: "user", IsActive: true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	router := gin.New()
+	authed := router.Group("/api", func(c *gin.Context) {
+		c.Set(middleware.CtxUserID, userID)
+		c.Next()
+	})
+	authed.GET("/watch-history/stats", historyStatsHandler(svc))
+	return router, svc, userID
+}
+
+type historyStatsPayload struct {
+	Total         int64 `json:"total"`
+	Completed     int64 `json:"completed"`
+	InProgress    int64 `json:"in_progress"`
+	WatchedMs     int64 `json:"watched_ms"`
+	WatchedHours  float64 `json:"watched_hours"`
+	Daily         []struct {
+		Day     string `json:"day"`
+		WatchMs int64  `json:"watch_ms"`
+		Plays   int64  `json:"plays"`
+	} `json:"daily"`
+	ByLibraryType []struct {
+		Type    string `json:"type"`
+		WatchMs int64  `json:"watch_ms"`
+		Count   int64  `json:"count"`
+	} `json:"by_library_type"`
+	Recent []struct {
+		Media *model.Media `json:"media"`
+	} `json:"recent"`
+}
+
+func fetchHistoryStats(t *testing.T, router *gin.Engine) historyStatsPayload {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, "/api/watch-history/stats", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	var payload historyStatsPayload
+	if err := json.Unmarshal(w.Body.Bytes(), &payload); err != nil {
+		t.Fatalf("decode %s: %v", w.Body.String(), err)
+	}
+	return payload
+}
+
+// 新字段必须提供每日聚合、库类型分布与在看数量，供个人统计页绘图。
+func TestHistoryStatsIncludesDailyAndTypes(t *testing.T) {
+	router, svc, userID := newHistoryStatsEnv(t)
+	ctx := context.Background()
+
+	movieLib := &model.Library{Name: "电影", Path: "/media/movies", Type: "movie", Enabled: true}
+	if err := svc.Repo.Library.Create(ctx, movieLib); err != nil {
+		t.Fatal(err)
+	}
+	tvLib := &model.Library{Name: "剧集", Path: "/media/tv", Type: "tv", Enabled: true}
+	if err := svc.Repo.Library.Create(ctx, tvLib); err != nil {
+		t.Fatal(err)
+	}
+
+	yesterday := time.Now().Add(-24 * time.Hour)
+	today := time.Now().Add(-time.Hour)
+
+	rows := []struct {
+		media     *model.Media
+		watchedAt time.Time
+		position  int64
+		completed bool
+	}{
+		{
+			media:     &model.Media{LibraryID: movieLib.ID, Title: "电影A", Path: "/media/movies/a.mkv"},
+			watchedAt: yesterday, position: 60000, completed: true,
+		},
+		{
+			media:     &model.Media{LibraryID: tvLib.ID, Title: "剧B", Path: "/media/tv/b.mkv"},
+			watchedAt: today, position: 30000, completed: false,
+		},
+	}
+	for _, row := range rows {
+		if err := svc.Repo.DB.Create(row.media).Error; err != nil {
+			t.Fatal(err)
+		}
+		h := &model.PlaybackHistory{
+			UserID: userID, MediaID: row.media.ID, PositionMs: row.position,
+			DurationMs: 120000, WatchedAt: row.watchedAt, Completed: row.completed,
+		}
+		if err := svc.Repo.DB.Create(h).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	payload := fetchHistoryStats(t, router)
+
+	if payload.Total != 2 {
+		t.Fatalf("total = %d, want 2", payload.Total)
+	}
+	if payload.Completed != 1 {
+		t.Fatalf("completed = %d, want 1", payload.Completed)
+	}
+	if payload.InProgress != 1 {
+		t.Fatalf("in_progress = %d, want 1", payload.InProgress)
+	}
+	if payload.WatchedMs != 90000 {
+		t.Fatalf("watched_ms = %d, want 90000", payload.WatchedMs)
+	}
+	if len(payload.Daily) != 2 {
+		t.Fatalf("daily = %+v, want 2 days", payload.Daily)
+	}
+	if len(payload.ByLibraryType) != 2 {
+		t.Fatalf("by_library_type = %+v, want 2 entries", payload.ByLibraryType)
+	}
+	if len(payload.Recent) != 2 {
+		t.Fatalf("recent = %d entries, want 2", len(payload.Recent))
+	}
+	if payload.Recent[0].Media == nil || payload.Recent[0].Media.Title != "剧B" {
+		t.Fatalf("recent[0] = %+v, want the most recent entry (剧B)", payload.Recent[0])
+	}
+}
+
+// 没有任何播放记录时，新字段要返回空数组而不是 null，前端无需额外判空。
+func TestHistoryStatsEmptyProvidesEmptyArrays(t *testing.T) {
+	router, _, _ := newHistoryStatsEnv(t)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/watch-history/stats", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	body := w.Body.String()
+	for _, field := range []string{`"daily":[]`, `"by_library_type":[]`, `"recent":[]`} {
+		if !containsSubstring(body, field) {
+			t.Fatalf("body = %s, want %s", body, field)
+		}
+	}
+}
+
+func containsSubstring(haystack, needle string) bool {
+	for i := 0; i+len(needle) <= len(haystack); i++ {
+		if haystack[i:i+len(needle)] == needle {
+			return true
+		}
+	}
+	return false
+}
+
+// TestHistoryStatsBreakdownsVisibilityFilter validates that historyStatsBreakdowns
+// respects the caller's MediaVisibility: media in a hidden library must be absent
+// from both the recent list and the by_library_type buckets.
+func TestHistoryStatsBreakdownsVisibilityFilter(t *testing.T) {
+	_, svc, userID := newHistoryStatsEnv(t)
+	ctx := context.Background()
+
+	allowedLib := &model.Library{Name: "允许库", Path: "/media/allowed", Type: "movie", Enabled: true}
+	hiddenLib := &model.Library{Name: "隐藏库", Path: "/media/hidden", Type: "tv", Enabled: true}
+	if err := svc.Repo.Library.Create(ctx, allowedLib); err != nil {
+		t.Fatal(err)
+	}
+	if err := svc.Repo.Library.Create(ctx, hiddenLib); err != nil {
+		t.Fatal(err)
+	}
+
+	allowedMedia := &model.Media{LibraryID: allowedLib.ID, Title: "允许媒体", Path: "/media/allowed/a.mkv"}
+	hiddenMedia := &model.Media{LibraryID: hiddenLib.ID, Title: "隐藏媒体", Path: "/media/hidden/b.mkv"}
+	if err := svc.Repo.DB.Create(allowedMedia).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := svc.Repo.DB.Create(hiddenMedia).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	now := time.Now()
+	for _, mid := range []string{allowedMedia.ID, hiddenMedia.ID} {
+		h := &model.PlaybackHistory{
+			UserID: userID, MediaID: mid, PositionMs: 10000,
+			DurationMs: 100000, WatchedAt: now, Completed: false,
+		}
+		if err := svc.Repo.DB.Create(h).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	// visibility that hides hiddenLib
+	vis := service.MediaVisibility{
+		HiddenLibraryIDs: []string{hiddenLib.ID},
+	}
+
+	_, byType, recent := historyStatsBreakdowns(ctx, svc, userID, vis)
+
+	// recent must contain only the allowed media
+	for _, entry := range recent {
+		m, ok := entry["media"]
+		if !ok {
+			t.Fatal("recent entry missing media field")
+		}
+		switch med := m.(type) {
+		case *model.Media:
+			if med.LibraryID == hiddenLib.ID {
+				t.Fatalf("hidden media appeared in recent: %s", med.Title)
+			}
+		case model.Media:
+			if med.LibraryID == hiddenLib.ID {
+				t.Fatalf("hidden media appeared in recent: %s", med.Title)
+			}
+		}
+	}
+	if len(recent) != 1 {
+		t.Fatalf("recent length = %d, want 1 (hidden entry must be excluded)", len(recent))
+	}
+
+	// by_library_type must not contain the hidden library's type ("tv")
+	for _, bt := range byType {
+		if bt.Type == "tv" {
+			t.Fatalf("hidden library type 'tv' appeared in by_library_type (count=%d)", bt.Count)
+		}
+	}
+}
+
+// TestHistoryStatsBreakdownsNilMediaCountsAsOther confirms that a history row
+// whose media has been deleted (nil lookup) is counted under the "other" type
+// bucket rather than silently dropped.
+func TestHistoryStatsBreakdownsNilMediaCountsAsOther(t *testing.T) {
+	_, svc, userID := newHistoryStatsEnv(t)
+	ctx := context.Background()
+
+	// Insert a history row whose media_id does not correspond to any Media row.
+	ghost := &model.PlaybackHistory{
+		UserID:     userID,
+		MediaID:    "ghost-media-id",
+		PositionMs: 5000,
+		DurationMs: 50000,
+		WatchedAt:  time.Now(),
+		Completed:  false,
+	}
+	if err := svc.Repo.DB.Create(ghost).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	vis := service.MediaVisibility{} // unrestricted
+	_, byType, _ := historyStatsBreakdowns(ctx, svc, userID, vis)
+
+	var otherEntry *historyTypeStat
+	for i := range byType {
+		if byType[i].Type == "other" {
+			otherEntry = &byType[i]
+			break
+		}
+	}
+	if otherEntry == nil {
+		t.Fatalf("expected 'other' bucket for nil-media history row, got %+v", byType)
+	}
+	if otherEntry.Count != 1 {
+		t.Fatalf("other.Count = %d, want 1", otherEntry.Count)
+	}
+}
+
+// TestHistoryStatsPermissionDeny checks that a user without can_view_history
+// receives HTTP 403 from the gated route.
+func TestHistoryStatsPermissionDeny(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(
+		&model.User{}, &model.Library{}, &model.Media{},
+		&model.PlaybackHistory{}, &model.UserPermission{},
+	); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	repos := repository.New(db)
+	svc := &service.Container{Repo: repos, Log: zap.NewNop()}
+	svc.Permissions = service.NewPermissionService(zap.NewNop(), repos)
+
+	const userID = "user-noperm"
+	if err := repos.User.Create(context.Background(), &model.User{
+		Base: model.Base{ID: userID}, Username: "noperm", PasswordHash: "x", Role: "user", IsActive: true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	// Explicitly deny can_view_history for this user.
+	// First seed defaults (Effective will create the row with defaults), then
+	// update to deny via Save which uses an explicit map update path in the repo.
+	if _, err := svc.Permissions.Effective(context.Background(), userID); err != nil {
+		t.Fatalf("seed permissions: %v", err)
+	}
+	denyPerm := &model.UserPermission{UserID: userID, CanViewHistory: false}
+	if err := svc.Permissions.Save(context.Background(), userID, denyPerm); err != nil {
+		t.Fatalf("save permission: %v", err)
+	}
+
+	router := gin.New()
+	authed := router.Group("/api", func(c *gin.Context) {
+		c.Set(middleware.CtxUserID, userID)
+		c.Set(middleware.CtxUserRole, "user")
+		c.Next()
+	})
+	authed.GET("/watch-history/stats", requirePermission(svc, "can_view_history"), historyStatsHandler(svc))
+
+	req := httptest.NewRequest(http.MethodGet, "/api/watch-history/stats", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want 403 for user without can_view_history", w.Code)
+	}
+}

internal/handler/watch_history_test.go

@@ -0,0 +1,105 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/middleware"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+func TestHistoryContinueRemovesMissingMedia(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.AutoMigrate(&model.PlaybackHistory{}, &model.Media{}); err != nil {
+		t.Fatal(err)
+	}
+
+	valid := model.Media{
+		Base:  model.Base{ID: "media-valid"},
+		Title: "有效影片",
+		Path:  "/media/valid.mkv",
+	}
+	if err := db.Create(&valid).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	now := time.Now()
+	if err := db.Create(&model.PlaybackHistory{
+		Base:       model.Base{ID: "history-valid"},
+		UserID:     "user-1",
+		MediaID:    valid.ID,
+		PositionMs: 30_000,
+		DurationMs: 120_000,
+		WatchedAt:  now.Add(-time.Minute),
+	}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&model.PlaybackHistory{
+		Base:       model.Base{ID: "history-stale"},
+		UserID:     "user-1",
+		MediaID:    "media-deleted",
+		PositionMs: 60_000,
+		DurationMs: 120_000,
+		WatchedAt:  now,
+	}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	repos := repository.New(db)
+	svc := &service.Container{
+		Log:      zap.NewNop(),
+		Repo:     repos,
+		Playback: service.NewPlaybackService(zap.NewNop(), repos),
+	}
+	router := gin.New()
+	router.Use(func(c *gin.Context) {
+		c.Set(middleware.CtxUserID, "user-1")
+		c.Next()
+	})
+	router.GET("/watch-history/continue", historyContinueHandler(svc))
+
+	req := httptest.NewRequest(http.MethodGet, "/watch-history/continue?limit=10", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rec.Code, rec.Body.String())
+	}
+
+	var body []struct {
+		History model.PlaybackHistory `json:"history"`
+		Media   model.Media           `json:"media"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatal(err)
+	}
+	if len(body) != 1 {
+		t.Fatalf("continue watching rows = %d, want 1: %s", len(body), rec.Body.String())
+	}
+	if body[0].Media.ID != valid.ID || body[0].History.ID != "history-valid" {
+		t.Fatalf("unexpected row: %#v", body[0])
+	}
+
+	var staleCount int64
+	if err := db.Unscoped().Model(&model.PlaybackHistory{}).
+		Where("user_id = ? AND media_id = ?", "user-1", "media-deleted").
+		Count(&staleCount).Error; err != nil {
+		t.Fatal(err)
+	}
+	if staleCount != 0 {
+		t.Fatalf("stale history rows remaining = %d, want 0", staleCount)
+	}
+}

internal/middleware/auth.go

@@ -125,6 +125,8 @@ func externalPlaybackTokenAllowedPath(c *gin.Context, mediaID string) bool {
 			return len(segments) >= 3 &&
 				strings.EqualFold(segments[2], "play") &&
 				strings.TrimSpace(c.Query("media_id")) == mediaID
+		case "cloud115":
+			return strings.TrimSpace(c.Query("media_id")) == mediaID
 		}
 	}
 	return false

internal/model/library_media.go

@@ -49,6 +49,7 @@ type Media struct {
 	ReleaseDate     string  `gorm:"size:10;index:idx_media_library_release,priority:2" json:"release_date,omitempty"`
 	SeasonNum       int     `json:"season_num"`
 	EpisodeNum      int     `json:"episode_num"`
+	EpisodeFraction float64 `gorm:"default:0" json:"episode_fraction,omitempty"` // 集号小数部分（S01E11.5 → 0.5）；Emby 的 IndexNumber 只能是整数，小数单独存放
 	ScrapeStatus    string  `gorm:"size:16;default:pending" json:"scrape_status"`
 	TMDbID          int     `json:"tmdb_id"`
 	BangumiID       int     `json:"bangumi_id"`

internal/model/library_tag.go

@@ -0,0 +1,118 @@
+package model
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// MaxLibraryTags 是单个用户可创建的标签数量上限，避免恶意写入过大的 JSON。
+const MaxLibraryTags = 50
+
+// MaxLibraryTagNameLen 是单个标签名的最大字符长度（按 rune 计数）。
+const MaxLibraryTagNameLen = 24
+
+// LibraryTagSet 是用户自定义的媒体库标签分组。
+// LibraryIDs 保存该标签下媒体库的 ID（含远程 Emby 挂载库的 embyremote~ 形式），
+// 顺序即媒体库在该标签内的展示顺序。
+type LibraryTagSet struct {
+	Name       string   `json:"name"`
+	LibraryIDs []string `json:"library_ids"`
+}
+
+// DecodeLibraryTags 解析 LibraryTags 字段，忽略损坏的数据。
+func (u *User) DecodeLibraryTags() []LibraryTagSet {
+	if u == nil || strings.TrimSpace(u.LibraryTags) == "" {
+		return nil
+	}
+	var tags []LibraryTagSet
+	if err := json.Unmarshal([]byte(u.LibraryTags), &tags); err != nil {
+		return nil
+	}
+	out := make([]LibraryTagSet, 0, len(tags))
+	for _, tag := range NormalizeLibraryTags(tags) {
+		out = append(out, tag)
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+// EncodeLibraryTags 把标签集合序列化为可写入 LibraryTags 字段的 JSON 字符串。
+// 空集合序列化为空字符串，便于用零值表达"没有标签"。
+func EncodeLibraryTags(tags []LibraryTagSet) (string, error) {
+	if len(tags) == 0 {
+		return "", nil
+	}
+	raw, err := json.Marshal(tags)
+	if err != nil {
+		return "", err
+	}
+	return string(raw), nil
+}
+
+// NormalizeLibraryTags 清洗标签集合：去空白、丢弃空名标签、去掉标签名与
+// 标签内媒体库 ID 的重复项，并把标签名重复的项合并。保持传入顺序。
+func NormalizeLibraryTags(tags []LibraryTagSet) []LibraryTagSet {
+	if len(tags) == 0 {
+		return nil
+	}
+	out := make([]LibraryTagSet, 0, len(tags))
+	indexByName := make(map[string]int, len(tags))
+	for _, tag := range tags {
+		name := TruncateLibraryTagName(tag.Name)
+		if name == "" {
+			continue
+		}
+		if len(out) >= MaxLibraryTags {
+			break
+		}
+		key := strings.ToLower(name)
+		pos, exists := indexByName[key]
+		if !exists {
+			if len(out) >= MaxLibraryTags {
+				break
+			}
+			out = append(out, LibraryTagSet{Name: name, LibraryIDs: []string{}})
+			pos = len(out) - 1
+			indexByName[key] = pos
+		}
+		seen := make(map[string]struct{}, len(out[pos].LibraryIDs))
+		for _, id := range out[pos].LibraryIDs {
+			seen[id] = struct{}{}
+		}
+		for _, id := range tag.LibraryIDs {
+			trimmed := strings.TrimSpace(id)
+			if trimmed == "" {
+				continue
+			}
+			if _, ok := seen[trimmed]; ok {
+				continue
+			}
+			seen[trimmed] = struct{}{}
+			out[pos].LibraryIDs = append(out[pos].LibraryIDs, trimmed)
+		}
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	for i := range out {
+		if out[i].LibraryIDs == nil {
+			out[i].LibraryIDs = []string{}
+		}
+	}
+	return out
+}
+
+// TruncateLibraryTagName 去掉首尾空白并按 rune 截断到长度上限。
+func TruncateLibraryTagName(name string) string {
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return ""
+	}
+	runes := []rune(name)
+	if len(runes) > MaxLibraryTagNameLen {
+		runes = runes[:MaxLibraryTagNameLen]
+	}
+	return strings.TrimSpace(string(runes))
+}

internal/model/library_tag_test.go

@@ -0,0 +1,79 @@
+package model
+
+import "testing"
+
+func TestNormalizeLibraryTagsMergesDuplicatesAndTrims(t *testing.T) {
+	tags := []LibraryTagSet{
+		{Name: "  动画  ", LibraryIDs: []string{" a ", "", "b", "a"}},
+		{Name: "动画", LibraryIDs: []string{"c", "b"}},
+		{Name: "   ", LibraryIDs: []string{"x"}},
+		{Name: "电影", LibraryIDs: nil},
+	}
+	got := NormalizeLibraryTags(tags)
+	if len(got) != 2 {
+		t.Fatalf("NormalizeLibraryTags len = %d, want 2 (%#v)", len(got), got)
+	}
+	if got[0].Name != "动画" {
+		t.Fatalf("first tag name = %q, want 动画", got[0].Name)
+	}
+	want := []string{"a", "b", "c"}
+	if len(got[0].LibraryIDs) != len(want) {
+		t.Fatalf("first tag ids = %v, want %v", got[0].LibraryIDs, want)
+	}
+	for i := range want {
+		if got[0].LibraryIDs[i] != want[i] {
+			t.Fatalf("first tag ids = %v, want %v", got[0].LibraryIDs, want)
+		}
+	}
+	if got[1].Name != "电影" || got[1].LibraryIDs == nil {
+		t.Fatalf("empty tag should survive with an empty non-nil id list: %#v", got[1])
+	}
+}
+
+func TestNormalizeLibraryTagsCapsCountAndNameLength(t *testing.T) {
+	long := make([]rune, MaxLibraryTagNameLen+10)
+	for i := range long {
+		long[i] = 'x'
+	}
+	got := NormalizeLibraryTags([]LibraryTagSet{{Name: string(long)}})
+	if len(got) != 1 {
+		t.Fatalf("len = %d, want 1", len(got))
+	}
+	if runes := []rune(got[0].Name); len(runes) != MaxLibraryTagNameLen {
+		t.Fatalf("name length = %d, want %d", len(runes), MaxLibraryTagNameLen)
+	}
+
+	many := make([]LibraryTagSet, 0, MaxLibraryTags+5)
+	for i := 0; i < MaxLibraryTags+5; i++ {
+		many = append(many, LibraryTagSet{Name: string(rune('a' + i%26)) + "-" + string(rune('a'+i/26))})
+	}
+	if capped := NormalizeLibraryTags(many); len(capped) > MaxLibraryTags {
+		t.Fatalf("capped len = %d, want <= %d", len(capped), MaxLibraryTags)
+	}
+}
+
+func TestEncodeDecodeLibraryTagsRoundTrip(t *testing.T) {
+	user := &User{}
+	if encoded, err := EncodeLibraryTags(nil); err != nil || encoded != "" {
+		t.Fatalf("EncodeLibraryTags(nil) = %q, %v; want \"\", nil", encoded, err)
+	}
+	raw, err := EncodeLibraryTags([]LibraryTagSet{{Name: "动画", LibraryIDs: []string{"lib-1"}}})
+	if err != nil {
+		t.Fatalf("EncodeLibraryTags: %v", err)
+	}
+	user.LibraryTags = raw
+	decoded := user.DecodeLibraryTags()
+	if len(decoded) != 1 || decoded[0].Name != "动画" || len(decoded[0].LibraryIDs) != 1 || decoded[0].LibraryIDs[0] != "lib-1" {
+		t.Fatalf("DecodeLibraryTags = %#v", decoded)
+	}
+
+	user.LibraryTags = "{not json"
+	if decoded := user.DecodeLibraryTags(); decoded != nil {
+		t.Fatalf("corrupt payload should decode to nil, got %#v", decoded)
+	}
+
+	user.PopulateComputedFields()
+	if user.LibraryTagList != nil {
+		t.Fatalf("PopulateComputedFields should mirror DecodeLibraryTags, got %#v", user.LibraryTagList)
+	}
+}

internal/model/media_probe.go

@@ -0,0 +1,42 @@
+package model
+
+import "time"
+
+// MediaProbe 是一次 ffprobe 全量探测（容器 / 轨道 / 内嵌章节）的结果缓存。
+//
+// 它存在的理由：探测一次要 3～4 秒——远端直链更慢，因为要跨洋跑三次 HTTP
+// 事务。播放链路绝不能等它，所以第一次播放只起后台任务，结果落库后由后续请求
+// 与「跳过片头」的章节数据直接读库。
+//
+// Payload 刻意只保存裁剪后的字段：ffprobe 原始输出里的 format.filename 是解析
+// 后的播放直链（带网盘签名与 pickcode），原样落库等于把可直接下载的链接留在
+// 数据库里，所以只保留与技术信息有关的字段。
+type MediaProbe struct {
+	Base
+	MediaID string `gorm:"uniqueIndex;size:128;not null" json:"media_id"`
+	// Signature 是「探的是哪个文件」的指纹（哈希）：本地文件取路径 + 大小 +
+	// 修改时间，STRM / 云盘取固化的播放目标。文件换了就说明缓存不再对应当前
+	// 内容，需要重探。
+	Signature string `gorm:"size:64" json:"signature,omitempty"`
+	// Source 记录输入形态：local | strm。
+	Source string `gorm:"size:16" json:"source,omitempty"`
+
+	Container       string `gorm:"size:64" json:"container,omitempty"`
+	DurationSec     int    `json:"duration_sec"`
+	BitRate         int64  `json:"bit_rate,omitempty"`
+	Width           int    `json:"width,omitempty"`
+	Height          int    `json:"height,omitempty"`
+	VideoCodec      string `gorm:"size:64" json:"video_codec,omitempty"`
+	AudioCodec      string `gorm:"size:64" json:"audio_codec,omitempty"`
+	VideoStreams    int    `json:"video_streams"`
+	AudioStreams    int    `json:"audio_streams"`
+	SubtitleStreams int    `json:"subtitle_streams"`
+	ChapterCount    int    `json:"chapter_count"`
+
+	// Payload 是供详情页展示的裁剪后 JSON（容器 + 每路轨道 + 章节）。
+	Payload string `gorm:"type:text" json:"payload,omitempty"`
+	// ProbedAt 是最近一次探测的时刻。LastError 非空表示这次探测失败；失败只更新
+	// 这两个字段，不会覆盖此前成功的 Payload 与已经落库的章节片段。
+	ProbedAt  time.Time `json:"probed_at"`
+	LastError string    `gorm:"size:512" json:"last_error,omitempty"`
+}

internal/model/media_segment.go

@@ -0,0 +1,39 @@
+package model
+
+import "time"
+
+// 片段类型与 TheIntroDB 的返回字段一一对应。客户端按 kind 决定按钮文案
+// （片头 / 回顾 / 片尾 / 预告），不依赖具体来源。
+const (
+	SegmentKindIntro   = "intro"
+	SegmentKindRecap   = "recap"
+	SegmentKindCredits = "credits"
+	SegmentKindPreview = "preview"
+)
+
+// MediaSegment 是媒体源时间轴上一个可被跳过的区间（片头 / 回顾 / 片尾 / 预告）。
+// 提供方（当前为 TheIntroDB）填充，播放器消费后向用户提供「跳过片头」。
+type MediaSegment struct {
+	Base
+	MediaID  string `gorm:"index;size:128;not null;uniqueIndex:uniq_media_segment" json:"media_id"`
+	SeriesID string `gorm:"index;size:128" json:"series_id,omitempty"`
+	Kind     string `gorm:"size:16;not null;uniqueIndex:uniq_media_segment" json:"kind"`
+	// StartMs/EndMs 是媒体源时间轴上的毫秒绝对值。EndMs 为 0 表示区间一直延续到
+	// 片尾（TheIntroDB 对末段返回 end_ms: null），由客户端结合媒体总时长补齐。
+	StartMs int64 `gorm:"not null;default:0;uniqueIndex:uniq_media_segment" json:"start_ms"`
+	EndMs   int64 `gorm:"not null;default:0" json:"end_ms"`
+	// Source 记录数据来源，让同一媒体上多来源共存、以及将来的人工覆盖成为可能。
+	// 它必须参与唯一索引：否则「外部数据」与「人工修正」给出同一区间时会撞索引。
+	Source string `gorm:"size:32;not null;default:'';uniqueIndex:uniq_media_segment" json:"source,omitempty"`
+}
+
+// MediaSegmentFetch 记录「某媒体的片段是否已向某来源查询过」。
+// 单独建表是为了能缓存「查不到」这个结果：没有负缓存的话，每次播放一部社区库里
+// 还没有数据的影片都会重新打一次外网。
+type MediaSegmentFetch struct {
+	Base
+	MediaID   string    `gorm:"index;size:128;not null;uniqueIndex:uniq_media_segment_fetch" json:"media_id"`
+	Source    string    `gorm:"size:32;not null;uniqueIndex:uniq_media_segment_fetch" json:"source"`
+	FetchedAt time.Time `json:"fetched_at"`
+	Found     bool      `json:"found"`
+}

internal/model/model.go

@@ -38,6 +38,9 @@ func AllModels() []interface{} {
 		&Series{},
 		&Media{},
 		&PlaybackHistory{},
+		&MediaSegment{},
+		&MediaSegmentFetch{},
+		&MediaProbe{},
 		&Favorite{},
 		&Playlist{},
 		&PlaylistItem{},

internal/model/user.go

@@ -28,11 +28,20 @@ type User struct {
 	// PinnedLibraryIDs 存储用户置顶的媒体库 ID 列表（JSON 字符串），顺序即置顶优先级。
 	PinnedLibraryIDs  string   `gorm:"type:text" json:"-"`
 	PinnedLibraryList []string `gorm:"-" json:"pinned_library_ids,omitempty"`
+	// LibraryTags 存储用户自定义的媒体库标签分组（JSON 字符串），
+	// 形如 [{"name":"动画","library_ids":["lib-1","lib-2"]}]。标签属于用户本人，
+	// 用于在媒体库页把同一标签下的媒体库聚合到一起。
+	LibraryTags    string          `gorm:"type:text" json:"-"`
+	LibraryTagList []LibraryTagSet `gorm:"-" json:"library_tags,omitempty"`
 	// SubtitleChineseMode 是网页播放器外挂字幕的简繁转换偏好：
 	// original / simplified / traditional。
 	SubtitleChineseMode string `gorm:"size:16;not null;default:original" json:"subtitle_chinese_mode"`
 	// 网页播放器偏好按用户存储，切换媒体对象后继续沿用。
+	// 播放倍速不在此列：它只作用于当前视频，不进数据库。
 	PlayerVolume float64 `gorm:"not null;default:1" json:"player_volume"`
+	// PlayerVr360GuideSeen 记录用户是否已经看过 VR 全景播放的首次操作说明，
+	// 按用户保存：看过一次之后不再弹出。
+	PlayerVr360GuideSeen bool    `gorm:"not null;default:false" json:"player_vr360_guide_seen"`
 	DanmakuEnabled       bool    `gorm:"not null;default:true" json:"danmaku_enabled"`
 	DanmakuOpacity       float64 `gorm:"not null;default:1" json:"danmaku_opacity"`
 	DanmakuFontSize      int     `gorm:"not null;default:24" json:"danmaku_font_size"`
@@ -46,6 +55,9 @@ type User struct {
 	// expires. When set and in the past, the account is treated as expired
 	// (login blocked) until an admin or a redemption code renews it.
 	ExpiredAt *time.Time `json:"expired_at,omitempty"`
+	// TelegramChatID 是用户绑定的 Telegram 会话 ID，用于接收账号与设备通知。
+	// 为空表示未绑定；绑定走个人资料页生成的一次性码 + Bot /bind 命令。
+	TelegramChatID string `gorm:"size:64" json:"telegram_chat_id,omitempty"`
 	// ShareWarnings counts anti-account-sharing warnings, mainly device
 	// fingerprint mismatches. Once it exceeds the configured threshold a
 	// re-offence disables the account until an admin re-enables it.
@@ -102,4 +114,5 @@ func (u *User) PopulateComputedFields() {
 	}
 	u.AllowedLibraryList = u.DecodeAllowedLibraryIDs()
 	u.PinnedLibraryList = u.DecodePinnedLibraryIDs()
+	u.LibraryTagList = u.DecodeLibraryTags()
 }

internal/model/user_telegram_test.go

@@ -0,0 +1,24 @@
+package model
+
+import (
+	"sync"
+	"testing"
+
+	"gorm.io/gorm/schema"
+)
+
+// TelegramChatID 是 Telegram 通知的绑定目标：Size 必须容得下真实 chat id
+// （群/频道 id 为负数且位数更长），因此下限设为 64。
+func TestUserTelegramChatIDFieldSize(t *testing.T) {
+	parsed, err := schema.Parse(&User{}, &sync.Map{}, schema.NamingStrategy{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	field := parsed.LookUpField("TelegramChatID")
+	if field == nil {
+		t.Fatal("TelegramChatID field not found")
+	}
+	if field.Size < 64 {
+		t.Fatalf("TelegramChatID size = %d, want at least 64", field.Size)
+	}
+}

internal/repository/media_filter_test.go

@@ -0,0 +1,174 @@
+package repository
+
+import (
+	"context"
+	"testing"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+func newMediaFilterTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.AutoMigrate(&model.Media{}, &model.PlaybackHistory{}); err != nil {
+		t.Fatal(err)
+	}
+	return db
+}
+
+func seedFilterMedia(t *testing.T, db *gorm.DB, rows ...*model.Media) {
+	t.Helper()
+	for _, row := range rows {
+		if err := db.WithContext(context.Background()).Create(row).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func listFiltered(t *testing.T, db *gorm.DB, filter MediaQueryFilter) []string {
+	t.Helper()
+	var rows []model.Media
+	q := db.WithContext(context.Background()).Model(&model.Media{})
+	q = applyMediaQueryFilter(q, filter)
+	if err := q.Order("title asc").Find(&rows).Error; err != nil {
+		t.Fatal(err)
+	}
+	out := make([]string, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, row.Title)
+	}
+	return out
+}
+
+func hasTitle(items []string, want string) bool {
+	for _, item := range items {
+		if item == want {
+			return true
+		}
+	}
+	return false
+}
+
+// 多个类型之间是「或」：勾选 Action 与 Comedy 应同时命中两类。
+func TestFilterByGenreOR(t *testing.T) {
+	db := newMediaFilterTestDB(t)
+	seedFilterMedia(t, db,
+		&model.Media{Title: "动作", Genres: "Action", Path: "/a.mkv", LibraryID: "lib-1"},
+		&model.Media{Title: "喜剧", Genres: "Comedy", Path: "/b.mkv", LibraryID: "lib-1"},
+		&model.Media{Title: "剧情", Genres: "Drama", Path: "/c.mkv", LibraryID: "lib-1"},
+	)
+
+	got := listFiltered(t, db, MediaQueryFilter{IncludeNSFW: true, Genres: []string{"Action", "Comedy"}})
+	if !hasTitle(got, "动作") || !hasTitle(got, "喜剧") {
+		t.Fatalf("result = %v, want both 动作 and 喜剧", got)
+	}
+	if hasTitle(got, "剧情") {
+		t.Fatalf("result = %v, must not contain 剧情", got)
+	}
+}
+
+// 类型匹配必须是整词匹配：搜 "Action" 不能命中 "ActionComedy" 这类拼接值。
+func TestFilterByGenreDoesNotMatchSubstring(t *testing.T) {
+	db := newMediaFilterTestDB(t)
+	seedFilterMedia(t, db,
+		&model.Media{Title: "精确", Genres: "Action,Drama", Path: "/a.mkv", LibraryID: "lib-1"},
+		&model.Media{Title: "拼接", Genres: "ActionComedy", Path: "/b.mkv", LibraryID: "lib-1"},
+	)
+
+	got := listFiltered(t, db, MediaQueryFilter{IncludeNSFW: true, Genres: []string{"Action"}})
+	if !hasTitle(got, "精确") {
+		t.Fatalf("result = %v, want 精确", got)
+	}
+	if hasTitle(got, "拼接") {
+		t.Fatalf("result = %v, must not match ActionComedy for Action", got)
+	}
+}
+
+func TestFilterYearAndRating(t *testing.T) {
+	db := newMediaFilterTestDB(t)
+	seedFilterMedia(t, db,
+		&model.Media{Title: "老片", Year: 1995, Rating: 9, Path: "/a.mkv", LibraryID: "lib-1"},
+		&model.Media{Title: "中年", Year: 2010, Rating: 5, Path: "/b.mkv", LibraryID: "lib-1"},
+		&model.Media{Title: "新片", Year: 2023, Rating: 8, Path: "/c.mkv", LibraryID: "lib-1"},
+	)
+
+	got := listFiltered(t, db, MediaQueryFilter{IncludeNSFW: true, YearMin: 2000, YearMax: 2020})
+	if len(got) != 1 || got[0] != "中年" {
+		t.Fatalf("year filter result = %v, want [中年]", got)
+	}
+
+	got = listFiltered(t, db, MediaQueryFilter{IncludeNSFW: true, RatingMin: 8})
+	if len(got) != 2 {
+		t.Fatalf("rating filter result = %v, want 2 entries", got)
+	}
+}
+
+// 「未观看」的语义是「没有标记看完的记录」：看了一半的仍应出现。
+func TestFilterUnwatchedExcludesCompleted(t *testing.T) {
+	db := newMediaFilterTestDB(t)
+	seedFilterMedia(t, db,
+		&model.Media{Base: model.Base{ID: "m-done"}, Title: "看完", Path: "/a.mkv", LibraryID: "lib-1"},
+		&model.Media{Base: model.Base{ID: "m-half"}, Title: "看一半", Path: "/b.mkv", LibraryID: "lib-1"},
+		&model.Media{Base: model.Base{ID: "m-new"}, Title: "没看过", Path: "/c.mkv", LibraryID: "lib-1"},
+	)
+
+	ctx := context.Background()
+	for _, h := range []*model.PlaybackHistory{
+		{UserID: "u1", MediaID: "m-done", Completed: true},
+		{UserID: "u1", MediaID: "m-half", Completed: false},
+		// 别人的完播记录不应影响本人筛选。
+		{UserID: "u2", MediaID: "m-new", Completed: true},
+	} {
+		if err := db.WithContext(ctx).Create(h).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	got := listFiltered(t, db, MediaQueryFilter{
+		IncludeNSFW: true, UnwatchedOnly: true, UnwatchedUserID: "u1",
+	})
+	if hasTitle(got, "看完") {
+		t.Fatalf("result = %v, must exclude completed media", got)
+	}
+	if !hasTitle(got, "看一半") || !hasTitle(got, "没看过") {
+		t.Fatalf("result = %v, want both 看一半 and 没看过", got)
+	}
+}
+
+// 多词类型（如 "Science Fiction"）：列侧 SQL 会 REPLACE 掉空格，参数侧也必须同步
+// 去掉空格，两侧对称才能命中。
+func TestFilterByGenreMultiWordStripsSpaces(t *testing.T) {
+	db := newMediaFilterTestDB(t)
+	seedFilterMedia(t, db,
+		&model.Media{Title: "科幻", Genres: "Science Fiction,Drama", Path: "/a.mkv", LibraryID: "lib-1"},
+		&model.Media{Title: "动作", Genres: "Action", Path: "/b.mkv", LibraryID: "lib-1"},
+	)
+
+	got := listFiltered(t, db, MediaQueryFilter{IncludeNSFW: true, Genres: []string{"Science Fiction"}})
+	if !hasTitle(got, "科幻") {
+		t.Fatalf("result = %v, want 科幻 (multi-word genre must match after space stripping)", got)
+	}
+	if hasTitle(got, "动作") {
+		t.Fatalf("result = %v, must not contain 动作", got)
+	}
+}
+
+// UnwatchedOnly 缺省 userID 时必须忽略该条件，而不是返回空结果。
+func TestFilterUnwatchedWithoutUserIsIgnored(t *testing.T) {
+	db := newMediaFilterTestDB(t)
+	seedFilterMedia(t, db, &model.Media{Title: "片", Path: "/a.mkv", LibraryID: "lib-1"})
+
+	got := listFiltered(t, db, MediaQueryFilter{IncludeNSFW: true, UnwatchedOnly: true})
+	if len(got) != 1 {
+		t.Fatalf("result = %v, want the row to be returned", got)
+	}
+}

internal/repository/media_probe_repository.go

@@ -0,0 +1,61 @@
+package repository
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// MediaProbeRepository 持久化 ffprobe 全量探测的结果缓存。
+type MediaProbeRepository struct{ db *gorm.DB }
+
+// Get 返回某媒体的探测缓存，未探测过时返回 (nil, nil)。
+func (r *MediaProbeRepository) Get(ctx context.Context, mediaID string) (*model.MediaProbe, error) {
+	var row model.MediaProbe
+	err := r.db.WithContext(ctx).
+		Where("media_id = ?", mediaID).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &row, nil
+}
+
+// Upsert 写入一次成功的探测结果（含裁剪后的媒体信息）。
+func (r *MediaProbeRepository) Upsert(ctx context.Context, row *model.MediaProbe) error {
+	onConflict := clause.OnConflict{
+		Columns: []clause.Column{{Name: "media_id"}},
+		DoUpdates: clause.AssignmentColumns([]string{
+			"signature", "source",
+			"container", "duration_sec", "bit_rate",
+			"width", "height", "video_codec", "audio_codec",
+			"video_streams", "audio_streams", "subtitle_streams", "chapter_count",
+			"payload", "probed_at", "last_error",
+			"deleted_at",
+		}),
+	}
+	return r.db.WithContext(ctx).Clauses(onConflict).Create(row).Error
+}
+
+// MarkFailure 记录一次失败的探测。它只更新「时间 + 错误信息」，刻意不碰
+// payload 与其它字段：一次失败的重探不该把上一次成功拿到的媒体信息抹掉。
+func (r *MediaProbeRepository) MarkFailure(ctx context.Context, mediaID, message string, probedAt time.Time) error {
+	row := model.MediaProbe{MediaID: mediaID, ProbedAt: probedAt, LastError: message}
+	onConflict := clause.OnConflict{
+		Columns: []clause.Column{{Name: "media_id"}},
+		DoUpdates: clause.Assignments(map[string]any{
+			"probed_at":  probedAt,
+			"last_error": message,
+			"deleted_at": nil,
+		}),
+	}
+	return r.db.WithContext(ctx).Clauses(onConflict).Create(&row).Error
+}

internal/repository/media_probe_repository_test.go

@@ -0,0 +1,105 @@
+package repository
+
+import (
+	"testing"
+	"time"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+func TestMediaProbeUpsertReplacesAndGetReturnsLatest(t *testing.T) {
+	repos := newSegmentTestRepos(t)
+	ctx := t.Context()
+
+	first := &model.MediaProbe{
+		MediaID: "m-1", Signature: "sig-1", Source: "local",
+		Container: "matroska,webm", DurationSec: 1451, ChapterCount: 2,
+		Payload: `{"container":"matroska,webm"}`, ProbedAt: time.Now(),
+	}
+	if err := repos.MediaProbe.Upsert(ctx, first); err != nil {
+		t.Fatalf("upsert #1: %v", err)
+	}
+	second := &model.MediaProbe{
+		MediaID: "m-1", Signature: "sig-2", Source: "strm",
+		Container: "mp4", DurationSec: 900, ChapterCount: 0,
+		Payload: `{"container":"mp4"}`, ProbedAt: time.Now(),
+	}
+	if err := repos.MediaProbe.Upsert(ctx, second); err != nil {
+		t.Fatalf("upsert #2: %v", err)
+	}
+
+	got, err := repos.MediaProbe.Get(ctx, "m-1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got == nil {
+		t.Fatal("probe row missing")
+	}
+	if got.Container != "mp4" || got.DurationSec != 900 || got.Signature != "sig-2" || got.Payload != `{"container":"mp4"}` {
+		t.Fatalf("probe = %#v, want the second upsert to win", got)
+	}
+	// 重复探测不能累积重复行：media_id 是唯一索引。
+	var count int64
+	if err := repos.DB.Model(&model.MediaProbe{}).Where("media_id = ?", "m-1").Count(&count).Error; err != nil {
+		t.Fatal(err)
+	}
+	if count != 1 {
+		t.Fatalf("rows = %d, want 1", count)
+	}
+}
+
+func TestMediaProbeGetReturnsNilWhenMissing(t *testing.T) {
+	repos := newSegmentTestRepos(t)
+	got, err := repos.MediaProbe.Get(t.Context(), "nope")
+	if err != nil {
+		t.Fatalf("Get: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("probe = %#v, want nil", got)
+	}
+}
+
+func TestMediaProbeMarkFailureKeepsPreviousPayload(t *testing.T) {
+	repos := newSegmentTestRepos(t)
+	ctx := t.Context()
+
+	if err := repos.MediaProbe.Upsert(ctx, &model.MediaProbe{
+		MediaID: "m-1", Container: "matroska,webm", DurationSec: 1451,
+		ChapterCount: 2, Payload: `{"container":"matroska,webm"}`, ProbedAt: time.Now(),
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := repos.MediaProbe.MarkFailure(ctx, "m-1", "ffprobe full: exit status 1", time.Now()); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := repos.MediaProbe.Get(ctx, "m-1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got == nil || got.LastError != "ffprobe full: exit status 1" {
+		t.Fatalf("probe = %#v, want the recorded failure", got)
+	}
+	// 一次失败的重探不该把上一次成功拿到的媒体信息抹掉。
+	if got.Container != "matroska,webm" || got.DurationSec != 1451 || got.Payload == "" || got.ChapterCount != 2 {
+		t.Fatalf("a failed re-probe wiped the previous summary: %#v", got)
+	}
+}
+
+func TestMediaProbeMarkFailureInsertsRowWhenAbsent(t *testing.T) {
+	repos := newSegmentTestRepos(t)
+	ctx := t.Context()
+
+	// 没有历史成功记录时，失败也必须落一行：否则冷却期没有时间戳，
+	// 每次播放都会重跑一次注定失败的探测。
+	if err := repos.MediaProbe.MarkFailure(ctx, "m-2", "boom", time.Now()); err != nil {
+		t.Fatal(err)
+	}
+	got, err := repos.MediaProbe.Get(ctx, "m-2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got == nil || got.LastError != "boom" || got.ProbedAt.IsZero() {
+		t.Fatalf("probe = %#v, want a failure row with a timestamp", got)
+	}
+}

internal/repository/media_repository.go

@@ -43,6 +43,22 @@ type MediaQueryFilter struct {
 	IncludeNSFW       bool
 	AllowedLibraryIDs []string
 	HiddenLibraryIDs  []string
+	SeriesID          string
+	// LibraryID 是精确匹配的单个库过滤，用于库内场景（例如媒体库页筛选）。
+	// 它与 AllowedLibraryIDs 是「与」关系：可见性仍由后者兜底，避免越权。
+	LibraryID string
+	// Genres 是类型多选，之间为「或」。按整词匹配（见 genreMatchClause）。
+	Genres []string
+	// YearMin / YearMax 为 0 表示该端不限。
+	YearMin int
+	YearMax int
+	// RatingMin 为 0 表示不限。
+	RatingMin float64
+	// UnwatchedOnly 排除 UnwatchedUserID 已标记看完的条目。
+	// 「未观看」定义为「没有 completed=true 的记录」：看到一半的仍会出现，
+	// 与「继续观看」互补而不是重复。
+	UnwatchedOnly   bool
+	UnwatchedUserID string
 }
 
 func applyMediaQueryFilter(q *gorm.DB, filter MediaQueryFilter) *gorm.DB {
@@ -55,9 +71,113 @@ func applyMediaQueryFilter(q *gorm.DB, filter MediaQueryFilter) *gorm.DB {
 	if len(filter.AllowedLibraryIDs) > 0 {
 		q = q.Where("library_id IN ?", filter.AllowedLibraryIDs)
 	}
+	if libraryID := strings.TrimSpace(filter.LibraryID); libraryID != "" {
+		q = q.Where("library_id = ?", libraryID)
+	}
+	if seriesID := strings.TrimSpace(filter.SeriesID); seriesID != "" {
+		q = q.Where("series_id = ?", seriesID)
+	}
+	if len(filter.Genres) > 0 {
+		q = q.Where(genreMatchClause(filter.Genres), genreMatchArgs(filter.Genres)...)
+	}
+	if filter.YearMin > 0 {
+		q = q.Where("year >= ?", filter.YearMin)
+	}
+	if filter.YearMax > 0 {
+		q = q.Where("year <= ?", filter.YearMax)
+	}
+	if filter.RatingMin > 0 {
+		q = q.Where("rating >= ?", filter.RatingMin)
+	}
+	if filter.UnwatchedOnly {
+		userID := strings.TrimSpace(filter.UnwatchedUserID)
+		// 没有用户上下文时忽略该条件：否则会把整个库筛成空，看起来像「坏了」。
+		if userID != "" {
+			q = q.Where(
+				"id NOT IN (SELECT media_id FROM playback_histories WHERE user_id = ? AND completed = ?)",
+				userID, true,
+			)
+		}
+	}
 	return q
 }
 
+// genreMatchClause 生成类型整词匹配条件。
+//
+// genres 列是逗号分隔字符串，直接 LIKE '%Action%' 会把 "ActionComedy" 也命中。
+// 这里统一补上首尾逗号（并用空格容错）后再按 "%,Action,%" 匹配，实现整词语义；
+// 该写法在 SQLite 与 PostgreSQL 上行为一致，因此不需要方言分支。
+//
+// 注意写法：参数本身带上首尾逗号，SQL 里只做一次 REPLACE 来保证列值两端也有
+// 分隔符，避免 OR 链里重复拼接列表达式。
+func genreMatchClause(genres []string) string {
+	clauses := make([]string, 0, len(genres))
+	for range genres {
+		clauses = append(clauses, "',' || REPLACE(REPLACE(TRIM(genres), ' ', ''), '，', ',') || ',' LIKE ?")
+	}
+	return "(" + strings.Join(clauses, " OR ") + ")"
+}
+
+// genreMatchArgs 生成与 genreMatchClause 对应的参数，形如 "%,Action,%"。
+//
+// 必须与 genreMatchClause 的列端处理完全对称：
+//   - TRIM                   → TrimSpace
+//   - REPLACE(…, ' ', '')    → ReplaceAll(…, " ", "")   ← 多词类型（如 "Science Fiction"）
+//   - REPLACE(…, '，', ',')  → ReplaceAll(…, "，", ",")
+func genreMatchArgs(genres []string) []any {
+	args := make([]any, 0, len(genres))
+	for _, genre := range genres {
+		name := strings.ReplaceAll(strings.TrimSpace(genre), "，", ",")
+		name = strings.ReplaceAll(name, " ", "") // mirror REPLACE(…,' ','') in genreMatchClause
+		if name == "" {
+			name = "\x00" // 空类型不会命中任何行
+		}
+		args = append(args, "%,"+name+",%")
+	}
+	return args
+}
+
+// ListGenreValues 返回符合过滤条件的 media.genres 原始值（逗号分隔字符串）。
+//
+// 只取单列：类型聚合不需要整行 media，而一台大库的整行扫描会把海报 URL、
+// 简介等大字段一起读进内存。切分与去重交给调用方，SQL 层保持方言无关。
+func (r *MediaRepository) ListGenreValues(ctx context.Context, filter MediaQueryFilter) ([]string, error) {
+	var values []string
+	q := r.db.WithContext(ctx).
+		Model(&model.Media{}).
+		Where("genres IS NOT NULL AND genres <> ''")
+	q = applyMediaQueryFilter(q, filter)
+	if err := q.Pluck("genres", &values).Error; err != nil {
+		return nil, err
+	}
+	return values, nil
+}
+
+// YearRange 返回符合过滤条件的年份区间（两端都为 0 表示没有可用年份）。
+// 供媒体库筛选面板生成年份上下限，避免前端硬编码或先取全量再自己算。
+func (r *MediaRepository) YearRange(ctx context.Context, filter MediaQueryFilter) (int, int, error) {
+	var bounds struct {
+		MinYear *int
+		MaxYear *int
+	}
+	q := r.db.WithContext(ctx).
+		Model(&model.Media{}).
+		Where("year > 0").
+		Select("MIN(year) AS min_year, MAX(year) AS max_year")
+	q = applyMediaQueryFilter(q, filter)
+	if err := q.Scan(&bounds).Error; err != nil {
+		return 0, 0, err
+	}
+	min, max := 0, 0
+	if bounds.MinYear != nil {
+		min = *bounds.MinYear
+	}
+	if bounds.MaxYear != nil {
+		max = *bounds.MaxYear
+	}
+	return min, max, nil
+}
+
 func (r *MediaRepository) indexMediaBestEffort(ctx context.Context, media model.Media) {
 	backend, ok := r.searchBackend.(MediaSearchSyncBackend)
 	if !ok {
@@ -79,6 +199,64 @@ func (r *MediaRepository) FindByID(ctx context.Context, id string) (*model.Media
 	return &m, nil
 }
 
+// ExistsSiblingWithTMDbID reports whether another row of the same show carries
+// the same tm_db_id as m.
+//
+// 它的用途是把「剧集级 id」和「单集自己的 id」区分开：一部剧的多集共用一个
+// 剧集级 id，而单集各自的 id 不会重复。调用方据此决定能否把 Media.TMDbID
+// 当作 Series.TMDbID 的替代品（见 MediaSegmentService.queryIDs）。
+//
+// 同一部剧的判定优先用 series_id；没有 series_id 的行（部分刮削路径不写它）
+// 退回到「同一个库 + 同一个标题」。查询失败按「不共用」处理：宁可不查，
+// 也不能拿一个可能是单集的 id 去查错片。
+func (r *MediaRepository) ExistsSiblingWithTMDbID(ctx context.Context, m *model.Media) bool {
+	if r == nil || m == nil || m.TMDbID <= 0 || m.ID == "" {
+		return false
+	}
+	query := r.db.WithContext(ctx).Model(&model.Media{}).
+		Where("tm_db_id = ? AND id <> ?", m.TMDbID, m.ID)
+	if seriesID := strings.TrimSpace(m.SeriesID); seriesID != "" {
+		query = query.Where("series_id = ?", seriesID)
+	} else {
+		libraryID := strings.TrimSpace(m.LibraryID)
+		title := strings.TrimSpace(m.Title)
+		if libraryID == "" || title == "" {
+			return false
+		}
+		query = query.Where("library_id = ? AND title = ?", libraryID, title)
+	}
+	var count int64
+	if err := query.Limit(1).Count(&count).Error; err != nil {
+		return false
+	}
+	return count > 0
+}
+
+// ListSeasonSiblings returns other episodes in the same season as m.
+// Prefers series_id; falls back to shared library+title+tm_db_id (anime scrape path).
+func (r *MediaRepository) ListSeasonSiblings(ctx context.Context, m *model.Media) ([]model.Media, error) {
+	if r == nil || m == nil || m.SeasonNum <= 0 || m.ID == "" {
+		return nil, nil
+	}
+	query := r.db.WithContext(ctx).Model(&model.Media{}).
+		Where("season_num = ? AND id <> ?", m.SeasonNum, m.ID)
+	if seriesID := strings.TrimSpace(m.SeriesID); seriesID != "" {
+		query = query.Where("series_id = ?", seriesID)
+	} else {
+		libraryID := strings.TrimSpace(m.LibraryID)
+		title := strings.TrimSpace(m.Title)
+		if libraryID == "" || title == "" || m.TMDbID <= 0 {
+			return nil, nil
+		}
+		query = query.Where("library_id = ? AND title = ? AND tm_db_id = ?", libraryID, title, m.TMDbID)
+	}
+	var rows []model.Media
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
 // ListByLibrary returns paginated media items for a library.
 func (r *MediaRepository) ListByLibrary(ctx context.Context, libraryID string, offset, limit int) ([]model.Media, int64, error) {
 	return r.ListByLibraryFiltered(ctx, libraryID, offset, limit, MediaQueryFilter{IncludeNSFW: true})
@@ -120,6 +298,47 @@ func (r *MediaRepository) ListAllByLibrariesFilteredNoCount(ctx context.Context,
 	return items, err
 }
 
+// ListVersionCandidates loads a bounded candidate set for version grouping
+// using the strongest identity stored on the row. Returning ok=false keeps the
+// caller's full-library fallback for rows without external IDs or SeriesID.
+func (r *MediaRepository) ListVersionCandidates(ctx context.Context, libraryIDs []string, media model.Media, limit int) ([]model.Media, bool, error) {
+	items := make([]model.Media, 0)
+	if len(libraryIDs) == 0 {
+		return items, false, nil
+	}
+	if limit <= 0 {
+		limit = 5000
+	}
+	q := r.db.WithContext(ctx).Model(&model.Media{})
+	if len(libraryIDs) == 1 {
+		q = q.Where("library_id = ?", libraryIDs[0])
+	} else {
+		q = q.Where("library_id IN ?", libraryIDs)
+	}
+	found := true
+	switch {
+	case strings.TrimSpace(media.SeriesID) != "":
+		q = q.Where("series_id = ?", strings.TrimSpace(media.SeriesID))
+	case media.TMDbID > 0:
+		q = q.Where("tm_db_id = ?", media.TMDbID)
+	case media.BangumiID > 0:
+		q = q.Where("bangumi_id = ?", media.BangumiID)
+	case strings.TrimSpace(media.DoubanID) != "":
+		q = q.Where("douban_id = ?", strings.TrimSpace(media.DoubanID))
+	case strings.TrimSpace(media.TheTVDBID) != "":
+		q = q.Where("thetvdb_id = ?", strings.TrimSpace(media.TheTVDBID))
+	default:
+		found = false
+	}
+	if !found {
+		return items, false, nil
+	}
+	err := q.Order("release_date DESC, year DESC, updated_at DESC, created_at DESC, id DESC").
+		Limit(limit).
+		Find(&items).Error
+	return items, true, err
+}
+
 func (r *MediaRepository) listByLibrariesFiltered(ctx context.Context, libraryIDs []string, offset, limit int, filter MediaQueryFilter, withCount bool) ([]model.Media, int64, error) {
 	var items []model.Media
 	var total int64
@@ -216,6 +435,10 @@ func mediaQueryFilterSQL(filter MediaQueryFilter) (string, []interface{}) {
 		parts = append(parts, "library_id IN ?")
 		args = append(args, filter.AllowedLibraryIDs)
 	}
+	if seriesID := strings.TrimSpace(filter.SeriesID); seriesID != "" {
+		parts = append(parts, "series_id = ?")
+		args = append(args, seriesID)
+	}
 	return strings.Join(parts, " AND "), args
 }
 

internal/repository/media_repository_upsert.go

@@ -332,6 +332,11 @@ func addMediaPlacementUpdates(updates map[string]any, existing, incoming model.M
 	if episodeChanged {
 		updates["episode_num"] = incoming.EpisodeNum
 	}
+	// 半集的小数部分独立于整数集号比较：S01E11.5 重命名/新增/删除时都要落库，
+	// 否则「11」与「11.5」会被当成同一集折叠。
+	if existing.EpisodeFraction != incoming.EpisodeFraction {
+		updates["episode_fraction"] = incoming.EpisodeFraction
+	}
 	if strings.TrimSpace(existing.ScrapeStatus) == "no_match" && incoming.ScrapeStatus != "matched" && (seasonChanged || episodeChanged) {
 		updates["scrape_status"] = "pending"
 	}

internal/repository/media_search_repository.go

@@ -146,6 +146,9 @@ func applyQualifiedMediaQueryFilter(q *gorm.DB, filter MediaQueryFilter) *gorm.D
 	if len(filter.AllowedLibraryIDs) > 0 {
 		q = q.Where("media.library_id IN ?", filter.AllowedLibraryIDs)
 	}
+	if seriesID := strings.TrimSpace(filter.SeriesID); seriesID != "" {
+		q = q.Where("media.series_id = ?", seriesID)
+	}
 	return q
 }