添加新功能，完善项目

internal/service/device_listing.go

@@ -21,14 +21,24 @@ func (s *DeviceService) KickDevice(ctx context.Context, userID, deviceID string)
 		return fmt.Errorf("device not found")
 	}
 	if fp := strings.TrimSpace(d.Fingerprint); fp != "" {
-		return s.repo.UserDevice.SetKickedByFingerprint(ctx, userID, fp, true)
+		err = s.repo.UserDevice.SetKickedByFingerprint(ctx, userID, fp, true)
+	} else {
+		err = s.repo.UserDevice.SetKicked(ctx, d.ID, true)
 	}
-	return s.repo.UserDevice.SetKicked(ctx, d.ID, true)
+	if err != nil {
+		return err
+	}
+	s.notify(ctx, userID, fmt.Sprintf("🔌 设备已下线：<b>%s</b>\n该终端需要重新登录后才能继续使用。", deviceLabel(d.DeviceName, d.Client)))
+	return nil
 }
 
 // KickAllDevices marks all devices for a user as kicked.
 func (s *DeviceService) KickAllDevices(ctx context.Context, userID string) error {
-	return s.repo.UserDevice.SetKickedByUser(ctx, userID, true)
+	if err := s.repo.UserDevice.SetKickedByUser(ctx, userID, true); err != nil {
+		return err
+	}
+	s.notify(ctx, userID, "🔌 你名下的全部设备已下线，需要重新登录后才能继续使用。")
+	return nil
 }
 
 // ListDevices returns the device sessions for a user.

internal/service/device_notify_test.go

@@ -0,0 +1,155 @@
+package service
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+func newDeviceServiceForTest(t *testing.T) (*DeviceService, *repository.Container, string) {
+	t.Helper()
+	repos := repository.New(newServiceTestDB(t))
+	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)
+	}
+	svc := NewDeviceService(zap.NewNop(), repos)
+	svc.SetSessionTracker(NewSessionTrackerService(zap.NewNop()))
+	return svc, repos, userID
+}
+
+// 新终端首次登录必须通知用户，否则「谁在用我的账号」永远无从察觉。
+func TestRecordLoginNotifiesOnNewDevice(t *testing.T) {
+	svc, _, userID := newDeviceServiceForTest(t)
+
+	type call struct{ userID, text string }
+	var calls []call
+	svc.SetNotifier(func(_ context.Context, uid, text string) {
+		calls = append(calls, call{uid, text})
+	})
+
+	svc.RecordLogin(context.Background(), userID, "dev-1", "Phone", "Infuse", "1.2.3.4")
+
+	if len(calls) != 1 {
+		t.Fatalf("notifier calls = %d, want 1", len(calls))
+	}
+	if calls[0].userID != userID {
+		t.Fatalf("notifier user = %q, want %q", calls[0].userID, userID)
+	}
+	if !strings.Contains(calls[0].text, "新设备") {
+		t.Fatalf("notifier text = %q, want it to mention 新设备", calls[0].text)
+	}
+}
+
+// 已知终端重复登录不应刷屏：只在首次建档时通知。
+func TestRecordLoginDoesNotNotifyOnKnownDevice(t *testing.T) {
+	svc, _, userID := newDeviceServiceForTest(t)
+
+	var count int
+	svc.SetNotifier(func(context.Context, string, string) { count++ })
+
+	svc.RecordLogin(context.Background(), userID, "dev-1", "Phone", "Infuse", "1.2.3.4")
+	svc.RecordLogin(context.Background(), userID, "dev-1", "Phone", "Infuse", "1.2.3.4")
+
+	if count != 1 {
+		t.Fatalf("notifier calls = %d, want exactly 1", count)
+	}
+}
+
+// 一键踢下线后必须告知用户，否则只会表现为「播放莫名失败」。
+func TestKickDeviceNotifiesUser(t *testing.T) {
+	svc, _, userID := newDeviceServiceForTest(t)
+	svc.RecordLogin(context.Background(), userID, "dev-1", "Phone", "Infuse", "1.2.3.4")
+
+	var kickText string
+	svc.SetNotifier(func(_ context.Context, _, text string) { kickText = text })
+
+	if err := svc.KickAllDevices(context.Background(), userID); err != nil {
+		t.Fatal(err)
+	}
+	if kickText == "" {
+		t.Fatal("expected a notification after kicking devices")
+	}
+	if !strings.Contains(kickText, "已下线") && !strings.Contains(kickText, "踢") {
+		t.Fatalf("kick notification text = %q, want it to describe the kick", kickText)
+	}
+}
+
+// 未接线 notifier 时（例如测试环境或 Bot 未配置），所有路径必须保持可用。
+func TestDeviceServiceWorksWithoutNotifier(t *testing.T) {
+	svc, _, userID := newDeviceServiceForTest(t)
+	svc.RecordLogin(context.Background(), userID, "dev-1", "Phone", "Infuse", "1.2.3.4")
+	if err := svc.KickAllDevices(context.Background(), userID); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// 设备指纹警告除通知用户外，管理员也必须同步收到告警。
+func TestFingerprintWarnNotifiesAdmin(t *testing.T) {
+	svc, repos, userID := newDeviceServiceForTest(t)
+
+	// 启用防共享策略
+	if err := repos.Setting.Set(context.Background(), SettingAntiShareEnabled, "true"); err != nil {
+		t.Fatal(err)
+	}
+
+	type call struct{ text string }
+	var adminCalls []call
+	svc.SetAdminNotifier(func(_ context.Context, text string) {
+		adminCalls = append(adminCalls, call{text})
+	})
+	svc.SetNotifier(func(context.Context, string, string) {}) // 用户通知静默接收
+
+	// 第一次登录注册设备
+	svc.RecordLogin(context.Background(), userID, "dev-1", "Phone-A", "Infuse", "1.2.3.4")
+	// 同设备 ID 换设备名 → 触发指纹变更警告
+	svc.RecordLogin(context.Background(), userID, "dev-1", "Phone-B", "Infuse", "1.2.3.4")
+
+	if len(adminCalls) == 0 {
+		t.Fatal("admin must be notified on fingerprint warn")
+	}
+}
+
+// 账号因设备策略被禁用时，管理员也必须收到告警。
+func TestPolicyDisableNotifiesAdmin(t *testing.T) {
+	svc, repos, userID := newDeviceServiceForTest(t)
+
+	// 启用防共享策略，设置最大并发客户端为 1
+	for _, kv := range [][2]string{
+		{SettingAntiShareEnabled, "true"},
+		{SettingMaxLoggedClients, "1"},
+		{SettingClientActiveDays, "30"},
+	} {
+		if err := repos.Setting.Set(context.Background(), kv[0], kv[1]); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	var adminCalls []string
+	svc.SetAdminNotifier(func(_ context.Context, text string) {
+		adminCalls = append(adminCalls, text)
+	})
+	svc.SetNotifier(func(context.Context, string, string) {})
+
+	// 两台不同设备登录，超出上限 → 触发禁用
+	svc.RecordLogin(context.Background(), userID, "dev-1", "Phone", "Infuse", "1.2.3.4")
+	svc.RecordLogin(context.Background(), userID, "dev-2", "TV", "Emby", "1.2.3.5")
+
+	if len(adminCalls) == 0 {
+		t.Fatal("admin must be notified when account is disabled by policy")
+	}
+	if !strings.Contains(adminCalls[0], "禁用") {
+		t.Fatalf("admin notification = %q, want it to mention 禁用", adminCalls[0])
+	}
+}

internal/service/device_service.go

@@ -5,6 +5,7 @@ import (
 	"crypto/sha256"
 	"encoding/hex"
 	"fmt"
+	"html"
 	"strings"
 	"time"
 
@@ -34,6 +35,10 @@ type DeviceService struct {
 	// notifyUser sends a Telegram message to the local user (resolved to their
 	// Telegram binding). Wired by the bot service; nil disables notifications.
 	notifyUser func(ctx context.Context, userID, text string)
+
+	// notifyAdmin sends a Telegram message to all admin accounts.
+	// Wired by the bot service; nil disables notifications.
+	notifyAdmin func(ctx context.Context, text string)
 }
 
 // NewDeviceService constructs a DeviceService.
@@ -46,6 +51,11 @@ func (s *DeviceService) SetNotifier(fn func(ctx context.Context, userID, text st
 	s.notifyUser = fn
 }
 
+// SetAdminNotifier wires the admin-broadcast Telegram notification callback.
+func (s *DeviceService) SetAdminNotifier(fn func(ctx context.Context, text string)) {
+	s.notifyAdmin = fn
+}
+
 func (s *DeviceService) SetSessionTracker(tracker *SessionTrackerService) {
 	s.sessions = tracker
 }
@@ -102,6 +112,8 @@ func (s *DeviceService) RecordLogin(ctx context.Context, userID, deviceID, devic
 			FirstSeenAt: now,
 			LastSeenAt:  now,
 		})
+		// 新终端首次登录才通知：已知设备重复登录不刷屏。
+		s.notify(ctx, userID, fmt.Sprintf("🔔 新设备登录：<b>%s</b>\n如果这不是你本人，请到「个人资料 → 我的设备」踢下线并修改密码。", deviceLabel(deviceName, client)))
 	} else {
 		if existing.Fingerprint != "" && existing.Fingerprint != fp {
 			mismatch = true
@@ -236,7 +248,10 @@ func (s *DeviceService) registerFingerprintWarning(ctx context.Context, userID,
 		"last_share_warn_at": &now,
 	})
 	left := cfg.WarnThreshold + 1 - warnings
-	s.notify(ctx, userID, fmt.Sprintf("⚠️ 账号 <b>%s</b> 触发设备指纹警告：%s\n这是第 <b>%d</b> 次警告，再异常 <b>%d</b> 次将禁用账号。请使用 Bot 的「我的设备」踢下线异常设备。", u.Username, reason, warnings, left))
+	warnText := fmt.Sprintf("⚠️ 账号 <b>%s</b> 触发设备指纹警告：%s\n这是第 <b>%d</b> 次警告，再异常 <b>%d</b> 次将禁用账号。请到「个人资料 → 我的设备」踢下线异常设备。",
+		html.EscapeString(u.Username), html.EscapeString(reason), warnings, left)
+	s.notify(ctx, userID, warnText)
+	s.notifyAdminMsg(ctx, warnText)
 	s.log.Info("anti-share: warning issued", zap.String("user", u.Username), zap.Int("warnings", warnings), zap.String("reason", reason))
 }
 
@@ -255,7 +270,10 @@ func (s *DeviceService) disableForPolicy(ctx context.Context, userID, reason str
 		"last_share_warn_at": &now,
 	})
 	_ = s.repo.UserDevice.SetKickedByUser(ctx, userID, true)
-	s.notify(ctx, userID, fmt.Sprintf("⛔️ 账号 <b>%s</b> 因触发设备规则已被禁用：%s\n请联系管理员解除禁用，或通过「我的设备」踢下线多余设备后再申请恢复。", u.Username, reason))
+	disableText := fmt.Sprintf("⛔️ 账号 <b>%s</b> 因触发设备规则已被禁用：%s\n请联系管理员解除禁用，或通过「个人资料 → 我的设备」踢下线多余设备后再申请恢复。",
+		html.EscapeString(u.Username), html.EscapeString(reason))
+	s.notify(ctx, userID, disableText)
+	s.notifyAdminMsg(ctx, disableText)
 	s.log.Warn("device policy: disabled account", zap.String("user", u.Username), zap.String("reason", reason))
 }
 
@@ -276,6 +294,12 @@ func (s *DeviceService) notify(ctx context.Context, userID, text string) {
 	}
 }
 
+func (s *DeviceService) notifyAdminMsg(ctx context.Context, text string) {
+	if s.notifyAdmin != nil {
+		s.notifyAdmin(ctx, text)
+	}
+}
+
 func deviceLabel(name, client string) string {
 	name = strings.TrimSpace(name)
 	client = strings.TrimSpace(client)

internal/service/emby_compat.go

@@ -76,6 +76,10 @@ type EmbyService struct {
 	adult         *AdultProvider
 	personImageMu sync.RWMutex
 	personImages  map[string]string
+
+	// discovery 提供 NextUp / Similar / Genres 的候选集。它只选候选，
+	// DTO 形状仍由本服务统一产出，避免同一部剧在不同接口上长得不一样。
+	discovery *MediaDiscoveryService
 }
 
 // NewEmbyService is the constructor.
@@ -91,6 +95,26 @@ func (e *EmbyService) SetEmbyRemote(remote *EmbyRemoteService) *EmbyService {
 	return e
 }
 
+// SetDiscovery 注入发现类查询服务（NextUp / Similar / Genres）。
+func (e *EmbyService) SetDiscovery(discovery *MediaDiscoveryService) *EmbyService {
+	if e != nil {
+		e.discovery = discovery
+	}
+	return e
+}
+
+// discoveryService 返回发现服务；未注入时按需构造，保证 Emby 接口在任何
+// 组装顺序下都不会因为缺少注入而返回空结果。
+func (e *EmbyService) discoveryService() *MediaDiscoveryService {
+	if e == nil {
+		return nil
+	}
+	if e.discovery == nil {
+		e.discovery = NewMediaDiscoveryService(e.log, e.repo)
+	}
+	return e.discovery
+}
+
 // SetTMDbProvider wires the TMDb client used for detail-time cast/crew lookup.
 func (e *EmbyService) SetTMDbProvider(tmdb *TMDbProvider) *EmbyService {
 	if e != nil {

internal/service/emby_compat_test.go

@@ -1,6 +1,8 @@
 package service
 
 import (
+	"context"
+	"strings"
 	"testing"
 	"time"
 
@@ -65,3 +67,133 @@ func TestEmbyLatestItemsOrderByReleaseDate(t *testing.T) {
 		t.Fatalf("latest item should expose PremiereDate for Emby clients: %#v", items[0])
 	}
 }
+
+// SimilarItems with a real series_id (not a media table row ID) must return
+// results instead of an empty list.  Before bug-2 fix, Media.FindByID returned
+// nil for any ID that wasn't a primary-key match in the media table (including
+// series_id values and virtual msgo-series-* IDs), so SimilarItems always
+// returned empty for series detail pages.
+func TestEmbyServiceSimilarItemsSeriesID(t *testing.T) {
+	svc := newTestEmbyService(t)
+	svc.SetDiscovery(NewMediaDiscoveryService(zap.NewNop(), svc.repo))
+
+	lib := model.Library{Name: "TV", Path: "/media/tv", Type: "tv", Enabled: true}
+	if err := svc.repo.Library.Create(context.Background(), &lib); err != nil {
+		t.Fatal(err)
+	}
+
+	// Two series with the same genre so they score > 0 for similarity.
+	ep1 := model.Media{
+		LibraryID:  lib.ID,
+		SeriesID:   "real-series-1",
+		Title:      "剧一",
+		Genres:     "Action",
+		SeasonNum:  1,
+		EpisodeNum: 1,
+		Path:       "/media/tv/s1e1.mkv",
+	}
+	ep2 := model.Media{
+		LibraryID:  lib.ID,
+		SeriesID:   "real-series-2",
+		Title:      "剧二",
+		Genres:     "Action",
+		SeasonNum:  1,
+		EpisodeNum: 1,
+		Path:       "/media/tv/s2e1.mkv",
+	}
+	for _, m := range []*model.Media{&ep1, &ep2} {
+		if err := svc.repo.DB.Create(m).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	// "real-series-1" is the series_id stored in the media row but is NOT a
+	// primary key in the media table, so Media.FindByID("real-series-1") returns
+	// nil.  SimilarItems must fall back to findSeriesGroup and still return
+	// results.
+	result, err := svc.SimilarItems(context.Background(), "real-series-1", "", 12)
+	if err != nil {
+		t.Fatalf("SimilarItems with series_id: %v", err)
+	}
+	similar, _ := result["Items"].([]map[string]any)
+	if similar == nil {
+		t.Fatal("SimilarItems returned nil items for a series_id that resolves via findSeriesGroup")
+	}
+	// Should contain 剧二 (the only other episodic content with the same genre).
+	found := false
+	for _, item := range similar {
+		if name, _ := item["Name"].(string); strings.Contains(name, "剧二") || strings.Contains(name, "第 1 集") {
+			found = true
+			break
+		}
+	}
+	if !found && len(similar) == 0 {
+		t.Fatalf("SimilarItems returned no results; want at least 剧二 for series real-series-1")
+	}
+}
+
+// SimilarItems with a virtual series ID (msgo-series-*) must also work.
+// Virtual IDs are generated for episodes that have no series_id set.
+func TestEmbyServiceSimilarItemsVirtualSeriesID(t *testing.T) {
+	svc := newTestEmbyService(t)
+	svc.SetDiscovery(NewMediaDiscoveryService(zap.NewNop(), svc.repo))
+
+	lib := model.Library{Name: "TV2", Path: "/media/tv2", Type: "tv", Enabled: true}
+	if err := svc.repo.Library.Create(context.Background(), &lib); err != nil {
+		t.Fatal(err)
+	}
+
+	// Episodes WITHOUT SeriesID → series group gets a virtual msgo-series-* ID.
+	ep1 := model.Media{
+		LibraryID:  lib.ID,
+		Title:      "虚拟剧一",
+		Genres:     "Drama",
+		SeasonNum:  1,
+		EpisodeNum: 1,
+		Path:       "/media/tv2/virtual1/S01E01.mkv",
+	}
+	ep2 := model.Media{
+		LibraryID:  lib.ID,
+		Title:      "虚拟剧二",
+		Genres:     "Drama",
+		SeasonNum:  1,
+		EpisodeNum: 1,
+		Path:       "/media/tv2/virtual2/S01E01.mkv",
+	}
+	for _, m := range []*model.Media{&ep1, &ep2} {
+		if err := svc.repo.DB.Create(m).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	// Fetch series items to get the virtual ID for ep1's series.
+	seriesItems, err := svc.Items(context.Background(), ItemsParams{
+		IncludeItemTypes: []string{"Series"},
+		Recursive:        true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	items, _ := seriesItems["Items"].([]map[string]any)
+	var virtualID string
+	for _, item := range items {
+		id, _ := item["Id"].(string)
+		name, _ := item["Name"].(string)
+		if strings.Contains(name, "虚拟剧一") && strings.HasPrefix(id, embyVirtualSeriesPrefix) {
+			virtualID = id
+			break
+		}
+	}
+	if virtualID == "" {
+		t.Skip("virtual series ID not generated for episodes without series_id in this build")
+	}
+
+	result, err := svc.SimilarItems(context.Background(), virtualID, "", 12)
+	if err != nil {
+		t.Fatalf("SimilarItems with virtual series ID: %v", err)
+	}
+	similar, _ := result["Items"].([]map[string]any)
+	if similar == nil {
+		t.Fatalf("SimilarItems returned nil items for virtual series ID %q", virtualID)
+	}
+}

internal/service/emby_discovery.go

@@ -0,0 +1,178 @@
+package service
+
+import (
+	"context"
+	"crypto/sha1"
+	"encoding/hex"
+	"strings"
+)
+
+// Emby 发现类接口：NextUp / Similar / Genres。
+//
+// 候选集的选取交给 MediaDiscoveryService（纯查询、无 DTO 概念），本文件只做
+// 「候选 → Emby DTO」的映射，复用 itemPayload 以保证与 /Items 的形状一致。
+
+const (
+	embyNextUpDefaultLimit  = 20
+	embySimilarDefaultLimit = 12
+	embyNextUpMaxLimit      = 100
+	embySimilarMaxLimit     = 50
+)
+
+// NextUp 返回「每部在看的剧的下一集」，即 Emby 客户端首页「接下来播放」的数据源。
+func (e *EmbyService) NextUp(ctx context.Context, userID string, limit int) (map[string]any, error) {
+	if limit <= 0 {
+		limit = embyNextUpDefaultLimit
+	}
+	if limit > embyNextUpMaxLimit {
+		limit = embyNextUpMaxLimit
+	}
+	if strings.TrimSpace(userID) == "" {
+		return emptyItemsEnvelope(0), nil
+	}
+	discovery := e.discoveryService()
+	if discovery == nil {
+		return emptyItemsEnvelope(0), nil
+	}
+
+	rows, err := discovery.NextUpCandidates(ctx, userID, limit, e.mediaVisibility(ctx, userID))
+	if err != nil {
+		return nil, err
+	}
+	// Bug 3 fix: use payloadsForMedia which attaches the request-scoped payload
+	// cache (withPayloadCache + prefetchPayloadCache) to avoid N+1 DB queries.
+	items, err := e.payloadsForMedia(ctx, rows, userID)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{
+		"Items":            items,
+		"TotalRecordCount": int64(len(items)),
+	}, nil
+}
+
+// SimilarItems 返回与指定条目相似的本地媒体。
+//
+// 找不到条目（或该条目对当前用户不可见）时返回空列表而不是错误：客户端会在
+// 详情页无条件请求它，404/500 会让客户端把条目判定为不完整。
+func (e *EmbyService) SimilarItems(ctx context.Context, mediaID, userID string, limit int) (map[string]any, error) {
+	if limit <= 0 {
+		limit = embySimilarDefaultLimit
+	}
+	if limit > embySimilarMaxLimit {
+		limit = embySimilarMaxLimit
+	}
+	discovery := e.discoveryService()
+	if discovery == nil || strings.TrimSpace(mediaID) == "" {
+		return emptyItemsEnvelope(0), nil
+	}
+
+	// Bug 2 fix: resolve virtual series IDs (msgo-series-*) and real series
+	// table IDs to a representative episode so SimilarCandidates (which calls
+	// Media.FindByID) can seed similarity from concrete media metadata.
+	resolvedID := mediaID
+	if strings.HasPrefix(mediaID, embyVirtualSeriesPrefix) {
+		series, ok, err := e.findSeriesGroup(ctx, mediaID, userID)
+		if err != nil {
+			return nil, err
+		}
+		if !ok || len(series.Episodes) == 0 {
+			return emptyItemsEnvelope(0), nil
+		}
+		resolvedID = series.Episodes[0].ID
+	} else if e.repo != nil && e.repo.Media != nil {
+		// For non-virtual IDs that are series-level (not in media table), also
+		// resolve via findSeriesGroup so the seed row can be found.
+		m, err := e.repo.Media.FindByID(ctx, mediaID)
+		if err != nil {
+			return nil, err
+		}
+		if m == nil {
+			series, ok, err := e.findSeriesGroup(ctx, mediaID, userID)
+			if err != nil {
+				return nil, err
+			}
+			if !ok || len(series.Episodes) == 0 {
+				return emptyItemsEnvelope(0), nil
+			}
+			resolvedID = series.Episodes[0].ID
+		}
+	}
+
+	rows, err := discovery.SimilarCandidates(ctx, resolvedID, limit, e.mediaVisibility(ctx, userID))
+	if err != nil {
+		return nil, err
+	}
+	// Bug 3 fix: use payloadsForMedia which attaches the request-scoped payload
+	// cache (withPayloadCache + prefetchPayloadCache) to avoid N+1 DB queries.
+	items, err := e.payloadsForMedia(ctx, rows, userID)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{
+		"Items":            items,
+		"TotalRecordCount": int64(len(items)),
+	}, nil
+}
+
+// Genres 返回类型清单。parentID 非空时（客户端按媒体库浏览类型）只统计该库。
+func (e *EmbyService) Genres(ctx context.Context, userID, parentID string) (map[string]any, error) {
+	discovery := e.discoveryService()
+	if discovery == nil {
+		return emptyItemsEnvelope(0), nil
+	}
+
+	libraryID := ""
+	if trimmed := strings.TrimSpace(parentID); trimmed != "" {
+		// 只有本地的真实库 ID 才能用于收窄；虚拟视图 ID（Emby 客户端自己的
+		// 视图标识）收窄后会得到空结果，因此识别不出来时按全库统计。
+		if e.libraryExists(ctx, trimmed) {
+			libraryID = trimmed
+		}
+	}
+
+	genres, err := discovery.AggregateGenres(ctx, e.mediaVisibility(ctx, userID), libraryID)
+	if err != nil {
+		return nil, err
+	}
+	items := make([]map[string]any, 0, len(genres))
+	for _, genre := range genres {
+		items = append(items, map[string]any{
+			"Id":                embyGenreID(genre.Name),
+			"Name":              genre.Name,
+			"ItemCount":         genre.Count,
+			"Type":              "Genre",
+			"ServerId":          embyServerID,
+			"IsFolder":          false,
+			"CanDelete":         false,
+			"CanDownload":       false,
+			"ImageTags":         map[string]any{},
+			"BackdropImageTags": []any{},
+		})
+	}
+	return map[string]any{
+		"Items":            items,
+		"TotalRecordCount": int64(len(items)),
+	}, nil
+}
+
+// libraryExists 判断 ID 是否对应本地媒体库。
+func (e *EmbyService) libraryExists(ctx context.Context, id string) bool {
+	if e == nil || e.repo == nil || e.repo.Library == nil {
+		return false
+	}
+	lib, err := e.repo.Library.FindByID(ctx, id)
+	if err != nil {
+		return false
+	}
+	return lib != nil
+}
+
+// embyGenreID 为类型生成稳定的虚拟 ID。
+//
+// 客户端会把 Id 当作条目去请求图片/详情，直接用类型名会带上空格与非 ASCII
+// 字符，因此用固定前缀 + 名称哈希；同一个名称永远得到同一个 ID。
+func embyGenreID(name string) string {
+	sum := sha1.Sum([]byte(strings.ToLower(strings.TrimSpace(name))))
+	return "msgo-genre-" + hex.EncodeToString(sum[:])[:16]
+}

internal/service/media_cache.go

@@ -32,10 +32,26 @@ func (s *MediaService) mediaListCacheKey(libraryID string, libraryIDs []string,
 		strings.Join(allowed, ","),
 		strings.Join(hidden, ","),
 		filter.SeriesID,
+		filterFingerprint(filter),
 	}, "|")))
 	return "media:list:" + hex.EncodeToString(sum[:])
 }
 
+// filterFingerprint 把影响结果的筛选维度序列化成稳定字符串。
+//
+// 缓存键必须覆盖所有会改变结果的过滤条件：漏一个就会出现「先打开未筛选列表，
+// 再筛选时命中旧缓存」这类脏读（返回不带筛选的数据）。新增过滤字段时只改这里。
+func filterFingerprint(filter repository.MediaQueryFilter) string {
+	genres := append([]string(nil), filter.Genres...)
+	sort.Strings(genres)
+	return strings.Join([]string{
+		"genres=" + strings.Join(genres, ","),
+		fmt.Sprintf("year=%d-%d", filter.YearMin, filter.YearMax),
+		fmt.Sprintf("rating=%.2f", filter.RatingMin),
+		fmt.Sprintf("unwatched=%t:%s", filter.UnwatchedOnly, filter.UnwatchedUserID),
+	}, "&")
+}
+
 func (s *MediaService) libraryPreviewCacheKey(libraries []model.Library, cardLimit int, filter repository.MediaQueryFilter, includeCounts bool) string {
 	libIDs := make([]string, len(libraries))
 	for i, lib := range libraries {
@@ -138,6 +154,7 @@ func (s *MediaService) groupedItemsCacheKey(libraryID string, libraryIDs []strin
 		strings.Join(allowed, ","),
 		strings.Join(hidden, ","),
 		filter.SeriesID,
+		filterFingerprint(filter),
 	})
 }
 

internal/service/media_discovery.go

@@ -0,0 +1,570 @@
+package service
+
+import (
+	"context"
+	"sort"
+	"strings"
+
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// MediaDiscoveryService 提供「发现类」查询：类型聚合、下一集、相似内容。
+//
+// 它只负责候选集的选取，不产出 Emby DTO —— DTO 形状必须由 EmbyService 统一
+// 提供，否则同一部剧在 /Items 与 /Shows/NextUp 上会长得不一样。同理，这里
+// 只接受调用方传入的 MediaVisibility，不自己解析用户权限。
+type MediaDiscoveryService struct {
+	log  *zap.Logger
+	repo *repository.Container
+}
+
+// GenreCount 是类型聚合结果。Name 保留首次出现时的写法（大小写与全半角
+// 均按原样展示），计数则不区分大小写。
+type GenreCount struct {
+	Name  string `json:"name"`
+	Count int    `json:"count"`
+}
+
+// NewMediaDiscoveryService 构建发现服务。
+func NewMediaDiscoveryService(log *zap.Logger, repo *repository.Container) *MediaDiscoveryService {
+	return &MediaDiscoveryService{log: log, repo: repo}
+}
+
+// mediaFilterFromVisibility 把可见性翻译成仓储过滤条件。所有发现类查询都必须
+// 经过这里，避免某一处忘记过滤 NSFW 或受限媒体库。
+func mediaFilterFromVisibility(visibility MediaVisibility) repository.MediaQueryFilter {
+	return repository.MediaQueryFilter{
+		IncludeNSFW:       visibility.IncludeNSFW,
+		AllowedLibraryIDs: visibility.AllowedLibraryIDs,
+		HiddenLibraryIDs:  visibility.HiddenLibraryIDs,
+	}
+}
+
+// AggregateGenres 统计可见媒体的类型分布。libraryID 非空时只统计该库，
+// 供媒体库页的筛选项与 Emby /Genres 共用。
+func (s *MediaDiscoveryService) AggregateGenres(ctx context.Context, visibility MediaVisibility, libraryID string) ([]GenreCount, error) {
+	if s == nil || s.repo == nil || s.repo.Media == nil {
+		return nil, nil
+	}
+	filter := mediaFilterFromVisibility(visibility)
+	filter.LibraryID = strings.TrimSpace(libraryID)
+
+	raw, err := s.repo.Media.ListGenreValues(ctx, filter)
+	if err != nil {
+		return nil, err
+	}
+	return countGenres(raw), nil
+}
+
+// countGenres 切分并计数。大小写不同的同名类型合并计数，展示名取首次出现的
+// 写法；结果按 count 降序、同数按名称升序，保证输出稳定可测。
+func countGenres(values []string) []GenreCount {
+	counts := make(map[string]int)
+	display := make(map[string]string)
+	for _, value := range values {
+		for _, name := range SplitGenreList(value) {
+			key := strings.ToLower(name)
+			if _, seen := display[key]; !seen {
+				display[key] = name
+			}
+			counts[key]++
+		}
+	}
+	out := make([]GenreCount, 0, len(counts))
+	for key, count := range counts {
+		out = append(out, GenreCount{Name: display[key], Count: count})
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].Count != out[j].Count {
+			return out[i].Count > out[j].Count
+		}
+		return out[i].Name < out[j].Name
+	})
+	return out
+}
+
+// SplitGenreList 切分逗号分隔的类型字段。
+//
+// 刮削来源既有英文逗号也有中文全角逗号，且常见首尾空格，因此三种分隔符都要
+// 处理，并丢弃空段。
+func SplitGenreList(value string) []string {
+	if strings.TrimSpace(value) == "" {
+		return nil
+	}
+	parts := strings.FieldsFunc(value, func(r rune) bool {
+		return r == ',' || r == '，' || r == '、' || r == ';' || r == '；'
+	})
+	out := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if trimmed := strings.TrimSpace(part); trimmed != "" {
+			out = append(out, trimmed)
+		}
+	}
+	return out
+}
+
+// genreSet 把类型字段转成小写集合，用于相似度计算。
+func genreSet(value string) map[string]struct{} {
+	names := SplitGenreList(value)
+	if len(names) == 0 {
+		return nil
+	}
+	out := make(map[string]struct{}, len(names))
+	for _, name := range names {
+		out[strings.ToLower(name)] = struct{}{}
+	}
+	return out
+}
+
+// genreOverlap 返回两个类型集合的交集大小。
+func genreOverlap(a, b map[string]struct{}) int {
+	if len(a) == 0 || len(b) == 0 {
+		return 0
+	}
+	// 遍历较小的集合，减少比较次数。
+	if len(b) < len(a) {
+		a, b = b, a
+	}
+	count := 0
+	for name := range a {
+		if _, ok := b[name]; ok {
+			count++
+		}
+	}
+	return count
+}
+
+// mediaIsEpisode 判断一行 media 是否属于「剧集」维度。
+//
+// 与 Emby 的判定保持一致（季号或集号大于 0），但不依赖 library type：同一个
+// 库既可能放电影也可能放剧集，用编号判断更贴近实际数据。
+func mediaIsEpisode(m *model.Media) bool {
+	return m != nil && (m.SeasonNum > 0 || m.EpisodeNum > 0)
+}
+
+// seriesGroupKey 是「同一部剧」的归并键。SeriesID 优先；缺省时退回
+// (库, 标题)，这样未刮削的剧集也能归到一组而不是每条历史各算一部剧。
+func seriesGroupKey(m *model.Media) string {
+	if m == nil {
+		return ""
+	}
+	if key := strings.TrimSpace(m.SeriesID); key != "" {
+		return "sid:" + key
+	}
+	if !mediaIsEpisode(m) {
+		return ""
+	}
+	return "lib:" + m.LibraryID + "|title:" + strings.ToLower(strings.TrimSpace(m.Title))
+}
+
+// nextUpHistoryScanLimit 是扫描播放历史的上限。历史按最近观看倒序取，
+// 因此截断只会丢掉「很久没看且排在很后面」的剧，不会影响首页前排。
+const nextUpHistoryScanLimit = 100
+
+// NextUpCandidates 返回「每部在看的剧的下一个待看集」，按最近观看时间排序。
+//
+// 语义要点：
+//   - 只处理剧集，电影由 Resume 接口负责，避免两个接口内容重复。
+//   - 同一部剧最多一条：取最近看过的集合之后、编号最小的那集。
+//   - 已标记看完的集跳过；追到最后一集则该剧不出现在结果里。
+func (s *MediaDiscoveryService) NextUpCandidates(ctx context.Context, userID string, limit int, visibility MediaVisibility) ([]model.Media, error) {
+	if s == nil || s.repo == nil || s.repo.Media == nil {
+		return nil, nil
+	}
+	if strings.TrimSpace(userID) == "" {
+		return nil, nil
+	}
+	if limit <= 0 {
+		limit = 20
+	}
+
+	// Bug 1 fix: include completed histories as anchors so a finished episode
+	// still anchors its series and the next unwatched episode is picked.
+	var histories []model.PlaybackHistory
+	if err := s.repo.DB.WithContext(ctx).
+		Where("user_id = ? AND position_ms > 0", userID).
+		Order("watched_at desc").
+		Limit(nextUpHistoryScanLimit).
+		Find(&histories).Error; err != nil {
+		return nil, err
+	}
+	if len(histories) == 0 {
+		return nil, nil
+	}
+
+	mediaIDs := make([]string, 0, len(histories))
+	for _, h := range histories {
+		mediaIDs = append(mediaIDs, h.MediaID)
+	}
+	filter := mediaFilterFromVisibility(visibility)
+	var watchedRows []model.Media
+	q := s.repo.DB.WithContext(ctx).Where("id IN ?", mediaIDs)
+	q = applyDiscoveryVisibility(q, filter)
+	if err := q.Find(&watchedRows).Error; err != nil {
+		return nil, err
+	}
+	byID := make(map[string]*model.Media, len(watchedRows))
+	for i := range watchedRows {
+		byID[watchedRows[i].ID] = &watchedRows[i]
+	}
+
+	// 按最近观看顺序归并到「剧」维度，同时记住该剧最近的已看集。
+	type seriesState struct {
+		key     string
+		current *model.Media
+	}
+	states := make([]seriesState, 0, len(histories))
+	seen := make(map[string]bool, len(histories))
+	for _, h := range histories {
+		m := byID[h.MediaID]
+		if m == nil || !mediaIsEpisode(m) {
+			continue
+		}
+		key := seriesGroupKey(m)
+		if key == "" || seen[key] {
+			continue
+		}
+		seen[key] = true
+		states = append(states, seriesState{key: key, current: m})
+	}
+	if len(states) == 0 {
+		return nil, nil
+	}
+
+	// 一次性把涉及的剧集全部取回，避免按剧逐条查询。
+	//
+	// Bug 4 fix: group by library_id when fetching by series_id so episodes
+	// from a different library with the same series_id don't bleed in.
+	// Bug 5 fix: batch unscraped (library_id, title) lookups per library
+	// instead of one query per series.
+	byLibSeries := make(map[string][]string) // libID -> []seriesID
+	var fallback []seriesState
+	for _, st := range states {
+		if id := strings.TrimSpace(st.current.SeriesID); id != "" {
+			byLibSeries[st.current.LibraryID] = append(byLibSeries[st.current.LibraryID], id)
+		} else {
+			fallback = append(fallback, st)
+		}
+	}
+
+	episodes := make([]model.Media, 0, len(states)*8)
+	// 按库批量加载刮削剧集，避免跨库混入同名 series_id 的剧集。
+	for libID, sids := range byLibSeries {
+		var rows []model.Media
+		eq := s.repo.DB.WithContext(ctx).Where("series_id IN ? AND library_id = ?", sids, libID)
+		eq = applyDiscoveryVisibility(eq, filter)
+		if err := eq.Find(&rows).Error; err != nil {
+			return nil, err
+		}
+		episodes = append(episodes, rows...)
+	}
+	// 未刮削剧集按 (库, 标题) 批量兜底查询，每库一条 SQL 避免 N+1。
+	byLibTitles := make(map[string][]string) // libID -> []title
+	for _, st := range fallback {
+		byLibTitles[st.current.LibraryID] = append(byLibTitles[st.current.LibraryID], st.current.Title)
+	}
+	for libID, titles := range byLibTitles {
+		var rows []model.Media
+		fq := s.repo.DB.WithContext(ctx).Where("library_id = ? AND title IN ?", libID, titles)
+		fq = applyDiscoveryVisibility(fq, filter)
+		if err := fq.Find(&rows).Error; err != nil {
+			return nil, err
+		}
+		episodes = append(episodes, rows...)
+	}
+
+	// 按剧归并候选集，便于 O(1) 查找下一集。
+	bySeries := make(map[string][]model.Media, len(states))
+	for _, row := range episodes {
+		key := seriesGroupKey(&row)
+		if key == "" {
+			continue
+		}
+		bySeries[key] = append(bySeries[key], row)
+	}
+	completed := s.completedMediaIDs(ctx, userID, episodes)
+
+	out := make([]model.Media, 0, limit)
+	for _, st := range states {
+		if len(out) >= limit {
+			break
+		}
+		next, ok := pickNextEpisode(bySeries[st.key], st.current, completed)
+		if !ok {
+			continue
+		}
+		out = append(out, next)
+	}
+	return out, nil
+}
+
+// applyDiscoveryVisibility 把可见性过滤应用到查询上。
+func applyDiscoveryVisibility(q *gorm.DB, filter repository.MediaQueryFilter) *gorm.DB {
+	if !filter.IncludeNSFW {
+		q = q.Where("nsfw = ?", false)
+	}
+	if len(filter.HiddenLibraryIDs) > 0 {
+		q = q.Where("library_id NOT IN ?", filter.HiddenLibraryIDs)
+	}
+	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)
+	}
+	return q
+}
+
+// completedMediaIDs 找出这些候选里该用户已标记看完的集。
+func (s *MediaDiscoveryService) completedMediaIDs(ctx context.Context, userID string, rows []model.Media) map[string]bool {
+	out := make(map[string]bool)
+	if len(rows) == 0 {
+		return out
+	}
+	ids := make([]string, 0, len(rows))
+	for _, row := range rows {
+		ids = append(ids, row.ID)
+	}
+	var done []model.PlaybackHistory
+	if err := s.repo.DB.WithContext(ctx).
+		Where("user_id = ? AND completed = ? AND media_id IN ?", userID, true, ids).
+		Find(&done).Error; err != nil {
+		return out
+	}
+	for _, h := range done {
+		out[h.MediaID] = true
+	}
+	return out
+}
+
+// pickNextEpisode 在候选集中选出严格晚于 current 的、编号最小的一集。
+// 比较顺序为 (季, 集)，因此跨季时自然落到下一季第一集。
+func pickNextEpisode(candidates []model.Media, current *model.Media, completed map[string]bool) (model.Media, bool) {
+	var best model.Media
+	found := false
+	for _, candidate := range candidates {
+		if candidate.ID == current.ID || completed[candidate.ID] {
+			continue
+		}
+		if !episodeAfter(candidate, *current) {
+			continue
+		}
+		if !found || episodeBefore(candidate, best) {
+			best = candidate
+			found = true
+		}
+	}
+	return best, found
+}
+
+// episodeAfter 报告 a 是否严格晚于 b。
+func episodeAfter(a, b model.Media) bool {
+	if a.SeasonNum != b.SeasonNum {
+		return a.SeasonNum > b.SeasonNum
+	}
+	return a.EpisodeNum > b.EpisodeNum
+}
+
+// episodeBefore 报告 a 是否严格早于 b。
+func episodeBefore(a, b model.Media) bool {
+	if a.SeasonNum != b.SeasonNum {
+		return a.SeasonNum < b.SeasonNum
+	}
+	return a.EpisodeNum < b.EpisodeNum
+}
+
+// similarCandidateLimit 是每个来源池（同库 / 同类型其他库）的候选上限。
+//
+// 相似度需要在内存里按类型/年份/评分算分，因此不能把整库拉出来；按评分倒序
+// 取前 N 条是「好的片子更可能被推荐」与「查询有界」之间的折中。
+const similarCandidateLimit = 400
+
+// SimilarCandidates 返回与源条目相似的本地媒体。
+//
+// 打分口径（不依赖任何外部 API，离线可用）：
+//   - 类型重合数 × 10：最强信号，同类内容通常才谈得上相似；
+//   - 年份接近度：相差 5 年内给分，差得越远越低；
+//   - 评分接近度：同为高分片算加分，避免「8 分片旁边推 3 分片」。
+//
+// 同库优先；不足时才从同类型的其它可见库里补齐。同剧其它集与自身一律排除。
+func (s *MediaDiscoveryService) SimilarCandidates(ctx context.Context, mediaID string, limit int, visibility MediaVisibility) ([]model.Media, error) {
+	if s == nil || s.repo == nil || s.repo.Media == nil {
+		return nil, nil
+	}
+	if limit <= 0 {
+		limit = 12
+	}
+	source, err := s.repo.Media.FindByID(ctx, mediaID)
+	if err != nil {
+		return nil, err
+	}
+	if source == nil || !visibility.Allows(source) {
+		return nil, nil
+	}
+
+	filter := mediaFilterFromVisibility(visibility)
+
+	pool, err := s.similarPool(ctx, filter, source, false)
+	if err != nil {
+		return nil, err
+	}
+	if len(pool) < limit {
+		// 同库不够时再扩到同类型库，保持「电影配电影、剧集配剧集」的直觉。
+		more, err := s.similarPool(ctx, filter, source, true)
+		if err != nil {
+			return nil, err
+		}
+		pool = append(pool, more...)
+	}
+
+	return rankSimilar(source, pool, limit), nil
+}
+
+// similarPool 取一批候选。expand=true 时排除源所在的库（用于补齐阶段），
+// 否则只取源所在的库（首选阶段）。
+func (s *MediaDiscoveryService) similarPool(ctx context.Context, filter repository.MediaQueryFilter, source *model.Media, expand bool) ([]model.Media, error) {
+	q := s.repo.DB.WithContext(ctx).Model(&model.Media{})
+	q = applyDiscoveryVisibility(q, filter)
+	q = q.Where("id <> ?", source.ID)
+
+	libraryIDs := []string{source.LibraryID}
+	if expand {
+		ids, err := s.compatibleLibraryIDs(ctx, source)
+		if err != nil {
+			return nil, err
+		}
+		filtered := make([]string, 0, len(ids))
+		for _, id := range ids {
+			if id != source.LibraryID {
+				filtered = append(filtered, id)
+			}
+		}
+		if len(filtered) == 0 {
+			return nil, nil
+		}
+		libraryIDs = filtered
+	}
+	q = q.Where("library_id IN ?", libraryIDs)
+
+	// 电影与剧集不互相推荐：用集号判定，和 NextUp 保持同一套口径。
+	if mediaIsEpisode(source) {
+		q = q.Where("(season_num > 0 OR episode_num > 0)")
+	} else {
+		q = q.Where("season_num = 0 AND episode_num = 0")
+	}
+
+	var rows []model.Media
+	if err := q.Order("rating desc, updated_at desc").Limit(similarCandidateLimit).Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+// compatibleLibraryIDs 返回与源条目同类型的库 ID（可能包含源库自身）。
+// 查不到类型时退回源库，保证补齐阶段不会跨类型乱推。
+func (s *MediaDiscoveryService) compatibleLibraryIDs(ctx context.Context, source *model.Media) ([]string, error) {
+	if s.repo.Library == nil {
+		return []string{source.LibraryID}, nil
+	}
+	libs, err := s.repo.Library.List(ctx)
+	if err != nil {
+		return nil, err
+	}
+	sourceType := ""
+	for _, lib := range libs {
+		if lib.ID == source.LibraryID {
+			sourceType = strings.ToLower(strings.TrimSpace(lib.Type))
+			break
+		}
+	}
+	if sourceType == "" {
+		return []string{source.LibraryID}, nil
+	}
+	out := make([]string, 0, len(libs))
+	for _, lib := range libs {
+		if strings.ToLower(strings.TrimSpace(lib.Type)) == sourceType {
+			out = append(out, lib.ID)
+		}
+	}
+	return out, nil
+}
+
+// rankSimilar 按相似度排序并截断。
+func rankSimilar(source *model.Media, pool []model.Media, limit int) []model.Media {
+	if len(pool) == 0 {
+		return nil
+	}
+	sourceGenres := genreSet(source.Genres)
+	sourceKey := seriesGroupKey(source)
+
+	type scored struct {
+		media model.Media
+		score float64
+	}
+	scoredRows := make([]scored, 0, len(pool))
+	seen := make(map[string]bool, len(pool))
+	for _, candidate := range pool {
+		if candidate.ID == source.ID || seen[candidate.ID] {
+			continue
+		}
+		// 同剧其它集不参与：「相似」不是在推荐本剧的下一集。
+		if key := seriesGroupKey(&candidate); key != "" && key == sourceKey {
+			continue
+		}
+		seen[candidate.ID] = true
+		scoredRows = append(scoredRows, scored{
+			media: candidate,
+			score: similarScore(source, &candidate, sourceGenres),
+		})
+	}
+	sort.SliceStable(scoredRows, func(i, j int) bool {
+		if scoredRows[i].score != scoredRows[j].score {
+			return scoredRows[i].score > scoredRows[j].score
+		}
+		if scoredRows[i].media.Rating != scoredRows[j].media.Rating {
+			return scoredRows[i].media.Rating > scoredRows[j].media.Rating
+		}
+		return scoredRows[i].media.Title < scoredRows[j].media.Title
+	})
+
+	if len(scoredRows) > limit {
+		scoredRows = scoredRows[:limit]
+	}
+	out := make([]model.Media, 0, len(scoredRows))
+	for _, row := range scoredRows {
+		out = append(out, row.media)
+	}
+	return out
+}
+
+// similarScore 计算单个候选的相似度。
+func similarScore(source, candidate *model.Media, sourceGenres map[string]struct{}) float64 {
+	score := float64(genreOverlap(sourceGenres, genreSet(candidate.Genres))) * 10
+
+	if source.Year > 0 && candidate.Year > 0 {
+		diff := source.Year - candidate.Year
+		if diff < 0 {
+			diff = -diff
+		}
+		if diff <= 5 {
+			score += float64(5 - diff)
+		}
+	}
+
+	if source.Rating > 0 && candidate.Rating > 0 {
+		diff := float64(source.Rating - candidate.Rating)
+		if diff < 0 {
+			diff = -diff
+		}
+		// 评分差 2 分以内才给分，最多 3 分。
+		if diff < 2 {
+			score += 3 * (2 - diff) / 2
+		}
+	}
+
+	return score
+}

internal/service/media_discovery_nextup_test.go

@@ -0,0 +1,246 @@
+package service
+
+import (
+	"context"
+	"strconv"
+	"testing"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// seedEpisode 插入一集，并把播放历史指向 `watched`（nil 表示没有历史）。
+func seedEpisode(
+	t *testing.T,
+	repos *repository.Container,
+	libID, seriesID, title string,
+	season, episode int,
+	watchedAt *time.Time,
+	completed bool,
+) *model.Media {
+	t.Helper()
+	m := &model.Media{
+		LibraryID:  libID,
+		SeriesID:   seriesID,
+		Title:      title,
+		SeasonNum:  season,
+		EpisodeNum: episode,
+		Path:       "/media/" + seriesID + "/S" + strconv.Itoa(season) + "E" + strconv.Itoa(episode) + ".mkv",
+	}
+	if err := repos.DB.WithContext(context.Background()).Create(m).Error; err != nil {
+		t.Fatal(err)
+	}
+	if watchedAt != nil || completed {
+		// 标记「已看完」也会产生一条历史行，因此 completed 为真时同样要写历史，
+		// 否则夹具与真实数据不一致（真实库里已看完一定有行）。
+		watched := time.Now().Add(-time.Hour)
+		if watchedAt != nil {
+			watched = *watchedAt
+		}
+		h := &model.PlaybackHistory{
+			UserID:     "user-1",
+			MediaID:    m.ID,
+			PositionMs: 1000,
+			DurationMs: 2000,
+			WatchedAt:  watched,
+			Completed:  completed,
+		}
+		if err := repos.DB.WithContext(context.Background()).Create(h).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+	return m
+}
+
+func nextUpIDs(t *testing.T, svc *MediaDiscoveryService, visibility MediaVisibility) []string {
+	t.Helper()
+	rows, err := svc.NextUpCandidates(context.Background(), "user-1", 20, visibility)
+	if err != nil {
+		t.Fatal(err)
+	}
+	out := make([]string, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, episodeLabel(row))
+	}
+	return out
+}
+
+// episodeLabel 把一集渲染成 "S1E2"，方便断言。
+func episodeLabel(m model.Media) string {
+	return "S" + strconv.Itoa(m.SeasonNum) + "E" + strconv.Itoa(m.EpisodeNum)
+}
+
+func TestNextUpPicksNextEpisode(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "tv")
+	watchedAt := time.Now().Add(-time.Hour)
+
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 1, &watchedAt, false)
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 2, nil, false)
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 3, nil, false)
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	got := nextUpIDs(t, svc, MediaVisibility{IncludeNSFW: true})
+	if len(got) != 1 || got[0] != "S1E2" {
+		t.Fatalf("next up = %v, want [S1E2]", got)
+	}
+}
+
+// 电影不进 NextUp：NextUp 的语义是「下一集」，电影由 Resume 接口负责。
+func TestNextUpSkipsMovies(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "movie")
+	watchedAt := time.Now().Add(-time.Hour)
+
+	seedEpisode(t, repos, libID, "", "电影", 0, 0, &watchedAt, false)
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	if got := nextUpIDs(t, svc, MediaVisibility{IncludeNSFW: true}); len(got) != 0 {
+		t.Fatalf("next up = %v, want empty", got)
+	}
+}
+
+// 同一部剧有多条未看完历史时，只能出一条，且指向最靠后的已看集的下一集。
+func TestNextUpOneEntryPerSeries(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "tv")
+	older := time.Now().Add(-48 * time.Hour)
+	newer := time.Now().Add(-2 * time.Hour)
+
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 1, &older, false)
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 2, &newer, false)
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 3, nil, false)
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	got := nextUpIDs(t, svc, MediaVisibility{IncludeNSFW: true})
+	if len(got) != 1 || got[0] != "S1E3" {
+		t.Fatalf("next up = %v, want [S1E3]", got)
+	}
+}
+
+// 跨季时下一集应是下一季的第一集。
+func TestNextUpCrossesSeason(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "tv")
+	watchedAt := time.Now().Add(-time.Hour)
+
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 12, &watchedAt, false)
+	seedEpisode(t, repos, libID, "series-1", "剧一", 2, 1, nil, false)
+	seedEpisode(t, repos, libID, "series-1", "剧一", 2, 2, nil, false)
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	got := nextUpIDs(t, svc, MediaVisibility{IncludeNSFW: true})
+	if len(got) != 1 || got[0] != "S2E1" {
+		t.Fatalf("next up = %v, want [S2E1]", got)
+	}
+}
+
+// 已标记看完的下一集要跳过。
+func TestNextUpSkipsCompletedEpisode(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "tv")
+	watchedAt := time.Now().Add(-time.Hour)
+
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 1, &watchedAt, false)
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 2, nil, true) // 已看完
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 3, nil, false)
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	got := nextUpIDs(t, svc, MediaVisibility{IncludeNSFW: true})
+	if len(got) != 1 || got[0] != "S1E3" {
+		t.Fatalf("next up = %v, want [S1E3]", got)
+	}
+}
+
+// 追到最后一集时没有下一集，结果为空而不是重复返回最后一集。
+func TestNextUpEmptyAtSeriesEnd(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "tv")
+	watchedAt := time.Now().Add(-time.Hour)
+
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 3, &watchedAt, false)
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	if got := nextUpIDs(t, svc, MediaVisibility{IncludeNSFW: true}); len(got) != 0 {
+		t.Fatalf("next up = %v, want empty", got)
+	}
+}
+
+// 不可见媒体库里的下一集不能被推荐出去。
+func TestNextUpRespectsVisibility(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	visibleLib := seedDiscoveryLibrary(t, repos, "tv")
+	hiddenLib := seedDiscoveryLibrary(t, repos, "tv")
+	watchedAt := time.Now().Add(-time.Hour)
+
+	seedEpisode(t, repos, visibleLib, "series-1", "剧一", 1, 1, &watchedAt, false)
+	seedEpisode(t, repos, hiddenLib, "series-1", "剧一", 1, 2, nil, false)
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	got := nextUpIDs(t, svc, MediaVisibility{IncludeNSFW: true, AllowedLibraryIDs: []string{visibleLib}})
+	if len(got) != 0 {
+		t.Fatalf("next up = %v, want empty (hidden library)", got)
+	}
+}
+
+// 最后一集看完（completed=true）后，下一部剧仍应出现在 NextUp 中，
+// 而不是因为没有 completed=false 的历史而消失（bug 1 回归测试）。
+func TestNextUpAfterCompletedEpisode(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "tv")
+	watchedAt := time.Now().Add(-time.Hour)
+
+	// S1E1 已看完，S1E2 尚未开始。
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 1, &watchedAt, true)
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 2, nil, false)
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 3, nil, false)
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	got := nextUpIDs(t, svc, MediaVisibility{IncludeNSFW: true})
+	if len(got) != 1 || got[0] != "S1E2" {
+		t.Fatalf("next up after completed S1E1 = %v, want [S1E2]", got)
+	}
+}
+
+// 整部剧看完（所有集都 completed=true）时不应出现在 NextUp（没有下一集）。
+func TestNextUpSeriesFullyWatchedIsEmpty(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "tv")
+	watchedAt := time.Now().Add(-time.Hour)
+
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 1, nil, true)
+	seedEpisode(t, repos, libID, "series-1", "剧一", 1, 2, &watchedAt, true) // 最近看完的最后一集
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	if got := nextUpIDs(t, svc, MediaVisibility{IncludeNSFW: true}); len(got) != 0 {
+		t.Fatalf("next up for fully-watched series = %v, want empty", got)
+	}
+}
+
+// 多部剧时按最近观看时间排序。
+func TestNextUpOrdersByRecency(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "tv")
+	older := time.Now().Add(-24 * time.Hour)
+	newer := time.Now().Add(-1 * time.Hour)
+
+	seedEpisode(t, repos, libID, "series-a", "剧A", 1, 1, &older, false)
+	seedEpisode(t, repos, libID, "series-a", "剧A", 1, 2, nil, false)
+	seedEpisode(t, repos, libID, "series-b", "剧B", 1, 1, &newer, false)
+	seedEpisode(t, repos, libID, "series-b", "剧B", 1, 2, nil, false)
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	rows, err := svc.NextUpCandidates(context.Background(), "user-1", 20, MediaVisibility{IncludeNSFW: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 2 {
+		t.Fatalf("rows = %d, want 2", len(rows))
+	}
+	if rows[0].SeriesID != "series-b" {
+		t.Fatalf("first row series = %q, want series-b (most recently watched)", rows[0].SeriesID)
+	}
+}

internal/service/media_discovery_similar_test.go

@@ -0,0 +1,167 @@
+package service
+
+import (
+	"context"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+func seedSimilarMedia(t *testing.T, repos *repository.Container, libID, title, genres string, year int, rating float32) *model.Media {
+	t.Helper()
+	m := &model.Media{
+		LibraryID: libID,
+		Title:     title,
+		Genres:    genres,
+		Year:      year,
+		Rating:    rating,
+		Path:      "/media/" + libID + "/" + title + ".mkv",
+	}
+	if err := repos.DB.WithContext(context.Background()).Create(m).Error; err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func similarTitles(t *testing.T, svc *MediaDiscoveryService, sourceID string, visibility MediaVisibility) []string {
+	t.Helper()
+	rows, err := svc.SimilarCandidates(context.Background(), sourceID, 12, visibility)
+	if err != nil {
+		t.Fatal(err)
+	}
+	out := make([]string, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, row.Title)
+	}
+	return out
+}
+
+func containsTitle(items []string, want string) bool {
+	for _, item := range items {
+		if item == want {
+			return true
+		}
+	}
+	return false
+}
+
+// 相似推荐必须排除自己，也要排除同剧的其他集（否则详情页会推荐本剧的其它集）。
+func TestSimilarExcludesSelfAndSameSeries(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "tv")
+
+	source := seedSimilarMedia(t, repos, libID, "剧一 E01", "Action", 2020, 8)
+	source.SeriesID = "series-1"
+	source.SeasonNum, source.EpisodeNum = 1, 1
+	if err := repos.DB.WithContext(context.Background()).Save(source).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	sibling := seedSimilarMedia(t, repos, libID, "剧一 E02", "Action", 2020, 8)
+	sibling.SeriesID = "series-1"
+	sibling.SeasonNum, sibling.EpisodeNum = 1, 2
+	if err := repos.DB.WithContext(context.Background()).Save(sibling).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	// 同库另一部剧的第 1 集：这才是剧集详情页该推荐的内容。
+	other := seedSimilarMedia(t, repos, libID, "另一部动作剧", "Action", 2021, 7)
+	other.SeriesID = "series-2"
+	other.SeasonNum, other.EpisodeNum = 1, 1
+	if err := repos.DB.WithContext(context.Background()).Save(other).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	got := similarTitles(t, svc, source.ID, MediaVisibility{IncludeNSFW: true})
+
+	if containsTitle(got, "剧一 E01") {
+		t.Fatalf("result must exclude the source itself: %v", got)
+	}
+	if containsTitle(got, "剧一 E02") {
+		t.Fatalf("result must exclude other episodes of the same series: %v", got)
+	}
+	if !containsTitle(got, "另一部动作剧") {
+		t.Fatalf("result = %v, want it to contain 另一部动作剧", got)
+	}
+}
+
+// 类型重合度高的条目要排在前面。
+func TestSimilarPrefersGenreOverlap(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "movie")
+
+	source := seedSimilarMedia(t, repos, libID, "源片", "Action,Adventure", 2010, 7)
+	seedSimilarMedia(t, repos, libID, "同类型", "Action,Adventure", 2010, 7)
+	seedSimilarMedia(t, repos, libID, "弱相关", "Comedy", 2010, 7)
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	got := similarTitles(t, svc, source.ID, MediaVisibility{IncludeNSFW: true})
+
+	if len(got) < 2 {
+		t.Fatalf("result = %v, want at least 2 entries", got)
+	}
+	if got[0] != "同类型" {
+		t.Fatalf("result = %v, want 同类型 ranked first", got)
+	}
+}
+
+// 不可见媒体库的条目不能被推荐。
+func TestSimilarRespectsVisibility(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	sourceLib := seedDiscoveryLibrary(t, repos, "movie")
+	hiddenLib := seedDiscoveryLibrary(t, repos, "movie")
+
+	source := seedSimilarMedia(t, repos, sourceLib, "源片", "Action", 2010, 7)
+	seedSimilarMedia(t, repos, hiddenLib, "隐藏片", "Action", 2010, 7)
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	got := similarTitles(t, svc, source.ID, MediaVisibility{IncludeNSFW: true, AllowedLibraryIDs: []string{sourceLib}})
+
+	if containsTitle(got, "隐藏片") {
+		t.Fatalf("hidden library leaked into similar: %v", got)
+	}
+}
+
+// 源条目不可见或不存在时返回空，不报错：客户端不该因此看到 500。
+func TestSimilarUnknownSourceReturnsEmpty(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+
+	rows, err := svc.SimilarCandidates(context.Background(), "missing", 12, MediaVisibility{IncludeNSFW: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 0 {
+		t.Fatalf("rows = %v, want empty", rows)
+	}
+}
+
+// limit 生效，且不返回重复条目。
+func TestSimilarHonoursLimit(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "movie")
+	source := seedSimilarMedia(t, repos, libID, "源片", "Action", 2010, 7)
+	for i := 0; i < 5; i++ {
+		seedSimilarMedia(t, repos, libID, "候选"+string(rune('A'+i)), "Action", 2010, 7)
+	}
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	rows, err := svc.SimilarCandidates(context.Background(), source.ID, 3, MediaVisibility{IncludeNSFW: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 3 {
+		t.Fatalf("rows = %d, want 3", len(rows))
+	}
+	seen := map[string]bool{}
+	for _, row := range rows {
+		if seen[row.ID] {
+			t.Fatalf("duplicate row %q in result", row.Title)
+		}
+		seen[row.ID] = true
+	}
+}

internal/service/media_discovery_test.go

@@ -0,0 +1,136 @@
+package service
+
+import (
+	"context"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// newDiscoveryTestDB 建好内存库并返回 repository 容器。
+func newDiscoveryTestDB(t *testing.T) *repository.Container {
+	t.Helper()
+	return repository.New(newServiceTestDB(t))
+}
+
+func seedDiscoveryLibrary(t *testing.T, repos *repository.Container, typ string) string {
+	t.Helper()
+	lib := &model.Library{Name: "库-" + typ, Path: "/media/" + typ, Type: typ, Enabled: true}
+	if err := repos.Library.Create(context.Background(), lib); err != nil {
+		t.Fatal(err)
+	}
+	return lib.ID
+}
+
+func seedDiscoveryMedia(t *testing.T, repos *repository.Container, m *model.Media) {
+	t.Helper()
+	if err := repos.DB.WithContext(context.Background()).Create(m).Error; err != nil {
+		t.Fatal(err)
+	}
+}
+
+func findGenre(genres []GenreCount, name string) int {
+	for _, g := range genres {
+		if g.Name == name {
+			return g.Count
+		}
+	}
+	return -1
+}
+
+func TestAggregateGenresSplitsAndCounts(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "movie")
+
+	seedDiscoveryMedia(t, repos, &model.Media{
+		LibraryID: libID, Title: "A", Path: "/media/movie/a.mkv", Genres: "Action,Drama",
+	})
+	seedDiscoveryMedia(t, repos, &model.Media{
+		LibraryID: libID, Title: "B", Path: "/media/movie/b.mkv", Genres: "action",
+	})
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	genres, err := svc.AggregateGenres(context.Background(), MediaVisibility{IncludeNSFW: true}, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 大小写不同视为同一类型，展示名保留首次出现的写法。
+	if got := findGenre(genres, "Action"); got != 2 {
+		t.Fatalf("Action count = %d, want 2 (genres=%+v)", got, genres)
+	}
+	if got := findGenre(genres, "Drama"); got != 1 {
+		t.Fatalf("Drama count = %d, want 1 (genres=%+v)", got, genres)
+	}
+}
+
+// 中文全角逗号在刮削结果里同样常见，必须一并切分。
+func TestAggregateGenresHandlesFullWidthComma(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	libID := seedDiscoveryLibrary(t, repos, "movie")
+	seedDiscoveryMedia(t, repos, &model.Media{
+		LibraryID: libID, Title: "A", Path: "/media/movie/a.mkv", Genres: "科幻，悬疑",
+	})
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	genres, err := svc.AggregateGenres(context.Background(), MediaVisibility{IncludeNSFW: true}, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if findGenre(genres, "科幻") != 1 || findGenre(genres, "悬疑") != 1 {
+		t.Fatalf("genres = %+v, want 科幻:1 and 悬疑:1", genres)
+	}
+}
+
+// libraryID 非空时只统计该库，供媒体库页面的筛选项使用。
+func TestAggregateGenresScopedToLibrary(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	movieLib := seedDiscoveryLibrary(t, repos, "movie")
+	tvLib := seedDiscoveryLibrary(t, repos, "tv")
+
+	seedDiscoveryMedia(t, repos, &model.Media{
+		LibraryID: movieLib, Title: "A", Path: "/media/movie/a.mkv", Genres: "Action",
+	})
+	seedDiscoveryMedia(t, repos, &model.Media{
+		LibraryID: tvLib, Title: "B", Path: "/media/tv/b.mkv", Genres: "Comedy",
+	})
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	genres, err := svc.AggregateGenres(context.Background(), MediaVisibility{IncludeNSFW: true}, movieLib)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if findGenre(genres, "Comedy") != -1 {
+		t.Fatalf("Comedy must not appear when scoped to the movie library: %+v", genres)
+	}
+	if findGenre(genres, "Action") != 1 {
+		t.Fatalf("Action count = %d, want 1", findGenre(genres, "Action"))
+	}
+}
+
+// 可见性过滤必须生效：不可见的库不应泄漏类型统计。
+func TestAggregateGenresRespectsVisibility(t *testing.T) {
+	repos := newDiscoveryTestDB(t)
+	allowedLib := seedDiscoveryLibrary(t, repos, "movie")
+	otherLib := seedDiscoveryLibrary(t, repos, "movie")
+
+	seedDiscoveryMedia(t, repos, &model.Media{
+		LibraryID: allowedLib, Title: "A", Path: "/media/a/a.mkv", Genres: "Action",
+	})
+	seedDiscoveryMedia(t, repos, &model.Media{
+		LibraryID: otherLib, Title: "B", Path: "/media/b/b.mkv", Genres: "Secret",
+	})
+
+	svc := NewMediaDiscoveryService(zap.NewNop(), repos)
+	genres, err := svc.AggregateGenres(context.Background(),
+		MediaVisibility{IncludeNSFW: true, AllowedLibraryIDs: []string{allowedLib}}, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if findGenre(genres, "Secret") != -1 {
+		t.Fatalf("hidden library leaked into genres: %+v", genres)
+	}
+}

internal/service/media_facets.go

@@ -0,0 +1,152 @@
+package service
+
+import (
+	"context"
+	"math/rand"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// LibraryFacets 是媒体库筛选面板需要的元数据：可选类型与年份区间。
+type LibraryFacets struct {
+	Genres  []GenreCount `json:"genres"`
+	YearMin int          `json:"year_min"`
+	YearMax int          `json:"year_max"`
+}
+
+// libraryFilterFrom 组装「可见性 + 用户筛选」的最终仓储条件，
+// 与列表查询保持完全一致的语义。
+func libraryFilterFrom(visibility MediaVisibility, filters MediaListFilters) repository.MediaQueryFilter {
+	return filters.apply(repository.MediaQueryFilter{
+		IncludeNSFW:       visibility.IncludeNSFW,
+		AllowedLibraryIDs: visibility.AllowedLibraryIDs,
+		HiddenLibraryIDs:  visibility.HiddenLibraryIDs,
+	})
+}
+
+// LibraryFacets 返回某个库的筛选项。类型统计复用 MediaDiscoveryService，
+// 避免在筛选面板与 Emby /Genres 之间出现两套口径。
+//
+// 作用范围必须与列表查询一致：列表用的是「合并网盘库」后的库 ID 集合，因此这
+// 里也把可见性收窄到同一集合，否则筛选项会漏掉列表里真实存在的条目。
+func (s *MediaService) LibraryFacets(
+	ctx context.Context,
+	libraryID string,
+	visibility MediaVisibility,
+	discovery *MediaDiscoveryService,
+) (LibraryFacets, error) {
+	var facets LibraryFacets
+	if s == nil || s.repo == nil || s.repo.Media == nil {
+		return facets, nil
+	}
+	visibility = ExpandMediaVisibilityForMergedCloudLibraries(ctx, s.repo, visibility)
+	merged, err := MergedLibraryIDsForLibrary(ctx, s.repo, libraryID)
+	if err != nil {
+		return facets, err
+	}
+	scoped, ok := scopeVisibilityToLibraries(visibility, merged)
+	if !ok {
+		facets.Genres = []GenreCount{}
+		return facets, nil
+	}
+
+	yearMin, yearMax, err := s.repo.Media.YearRange(ctx, libraryFilterFrom(scoped, MediaListFilters{}))
+	if err != nil {
+		return facets, err
+	}
+	facets.YearMin = yearMin
+	facets.YearMax = yearMax
+
+	if discovery != nil {
+		genres, err := discovery.AggregateGenres(ctx, scoped, "")
+		if err != nil {
+			return facets, err
+		}
+		facets.Genres = genres
+	}
+	if facets.Genres == nil {
+		facets.Genres = []GenreCount{}
+	}
+	return facets, nil
+}
+
+// scopeVisibilityToLibraries 把可见性收窄到给定库集合。
+//
+// 返回 ok=false 表示「这些库与用户的可见性没有交集」——此时必须返回空结果，
+// 而不是退化成不过滤，否则受限用户会看到别人的库。
+func scopeVisibilityToLibraries(visibility MediaVisibility, libraryIDs []string) (MediaVisibility, bool) {
+	allowed := make(map[string]struct{}, len(visibility.AllowedLibraryIDs))
+	for _, id := range visibility.AllowedLibraryIDs {
+		allowed[id] = struct{}{}
+	}
+	out := make([]string, 0, len(libraryIDs))
+	for _, id := range libraryIDs {
+		if len(allowed) > 0 {
+			if _, ok := allowed[id]; !ok {
+				continue
+			}
+		}
+		out = append(out, id)
+	}
+	if len(out) == 0 {
+		return visibility, false
+	}
+	visibility.AllowedLibraryIDs = out
+	return visibility, true
+}
+
+// RandomMedia 在「可见性 + 筛选」的结果集里随机取一条。
+//
+// 实现是「先 COUNT 再随机 offset」的两段查询：SQLite 没有 TABLESAMPLE，
+// ORDER BY RANDOM() 又会对整库排序（大库上会拖垮磁盘），因此用等价的
+// 偏移量取法，且两种数据库方言完全一致。
+//
+// 返回 (nil, nil) 表示结果集为空，由调用方决定响应码。
+func (s *MediaService) RandomMedia(
+	ctx context.Context,
+	libraryID string,
+	visibility MediaVisibility,
+	filters MediaListFilters,
+) (*model.Media, error) {
+	if s == nil || s.repo == nil || s.repo.Media == nil {
+		return nil, nil
+	}
+	visibility = ExpandMediaVisibilityForMergedCloudLibraries(ctx, s.repo, visibility)
+	libraryIDs, err := MergedLibraryIDsForLibrary(ctx, s.repo, libraryID)
+	if err != nil {
+		return nil, err
+	}
+	filter := libraryFilterFrom(visibility, filters)
+
+	_, total, err := s.repo.Media.ListByLibrariesFiltered(ctx, libraryIDs, 0, 1, filter)
+	if err != nil {
+		return nil, err
+	}
+	if total <= 0 {
+		return nil, nil
+	}
+
+	// 超大结果集直接对全部记录随机 OFFSET 会让数据库扫描海量行（SQLite 逐行计数）。
+	// 当总量超过阈值时，收窄到按更新时间最新的前 N 条（列表排序首列是
+	// release_date / updated_at，前 randomPoolCap 行即为"最新"子集），
+	// 偏移量取其中随机位置，兼顾性能与覆盖面。
+	const randomPoolCap = 5000
+	effectiveTotal := total
+	if effectiveTotal > randomPoolCap {
+		effectiveTotal = randomPoolCap
+	}
+	offset := 0
+	if effectiveTotal > 1 {
+		offset = rand.Intn(int(effectiveTotal))
+	}
+	items, err := s.repo.Media.ListByLibrariesFilteredNoCount(ctx, libraryIDs, offset, 1, filter)
+	if err != nil {
+		return nil, err
+	}
+	if len(items) == 0 {
+		return nil, nil
+	}
+	s.attachLibraryMetadata(ctx, items)
+	return &items[0], nil
+}

internal/service/media_filters_test.go

@@ -0,0 +1,88 @@
+package service
+
+import (
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// 系列路径的筛选在内存里复现 SQL 语义，必须与仓储侧一致，否则会出现
+// 「电影库能筛、剧集库筛不动」的行为差异。
+func TestMediaRowMatchesFilters(t *testing.T) {
+	row := &model.Media{
+		Base:   model.Base{ID: "m1"},
+		Title:  "片",
+		Genres: "Action,Drama",
+		Year:   2015,
+		Rating: 7.5,
+	}
+
+	cases := []struct {
+		name      string
+		filters   MediaListFilters
+		completed map[string]bool
+		want      bool
+	}{
+		{name: "no filters", filters: MediaListFilters{}, want: true},
+		{name: "genre hit", filters: MediaListFilters{Genres: []string{"Action"}}, want: true},
+		{name: "genre miss", filters: MediaListFilters{Genres: []string{"Comedy"}}, want: false},
+		{name: "year in range", filters: MediaListFilters{YearMin: 2010, YearMax: 2020}, want: true},
+		{name: "year below min", filters: MediaListFilters{YearMin: 2016}, want: false},
+		{name: "year above max", filters: MediaListFilters{YearMax: 2014}, want: false},
+		{name: "rating ok", filters: MediaListFilters{RatingMin: 7}, want: true},
+		{name: "rating too high", filters: MediaListFilters{RatingMin: 8}, want: false},
+		{name: "unwatched passes", filters: MediaListFilters{Unwatched: true}, want: true},
+		{
+			name:      "unwatched excludes completed",
+			filters:   MediaListFilters{Unwatched: true},
+			completed: map[string]bool{"m1": true},
+			want:      false,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := mediaRowMatchesFilters(row, tc.filters, tc.completed); got != tc.want {
+				t.Fatalf("matched = %t, want %t", got, tc.want)
+			}
+		})
+	}
+}
+
+// 多词类型（如 "Science Fiction"）在内存筛选中必须整词命中。
+func TestMediaRowMatchesFiltersMultiWordGenre(t *testing.T) {
+	row := &model.Media{
+		Base:   model.Base{ID: "m2"},
+		Title:  "科幻片",
+		Genres: "Science Fiction,Drama",
+	}
+	cases := []struct {
+		name    string
+		filters MediaListFilters
+		want    bool
+	}{
+		{name: "multi-word hit", filters: MediaListFilters{Genres: []string{"Science Fiction"}}, want: true},
+		{name: "partial word miss", filters: MediaListFilters{Genres: []string{"Science"}}, want: false},
+		{name: "case insensitive hit", filters: MediaListFilters{Genres: []string{"science fiction"}}, want: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := mediaRowMatchesFilters(row, tc.filters, nil); got != tc.want {
+				t.Fatalf("matched = %t, want %t", got, tc.want)
+			}
+		})
+	}
+}
+
+// 无筛选时 empty() 为真，调用方据此走带缓存的原路径。
+func TestMediaListFiltersEmpty(t *testing.T) {
+	if !(MediaListFilters{}).empty() {
+		t.Fatal("zero filters must be reported as empty")
+	}
+	if (MediaListFilters{Genres: []string{"Action"}}).empty() {
+		t.Fatal("genre filter must not be reported as empty")
+	}
+	if (MediaListFilters{Unwatched: true}).empty() {
+		t.Fatal("unwatched filter must not be reported as empty")
+	}
+}

internal/service/media_listing.go

@@ -12,11 +12,63 @@ import (
 )
 
 // ListMedia paginates media items inside a library.
+// MediaListFilters 是列表接口的可选筛选条件（来自查询串或库内筛选面板）。
+//
+// 与 MediaVisibility 分开：可见性是权限约束（服务端强制），这些是用户主动
+// 选择的浏览条件，两者在 SQL 层是「与」关系。
+type MediaListFilters struct {
+	Genres    []string
+	YearMin   int
+	YearMax   int
+	RatingMin float64
+	Unwatched bool
+	// UserID 是「未观看」判定所需的账号；为空时 Unwatched 被忽略。
+	UserID string
+}
+
+// empty 报告是否没有任何筛选条件。调用方据此走缓存友好的默认路径。
+func (f MediaListFilters) empty() bool {
+	return len(f.Genres) == 0 && f.YearMin <= 0 && f.YearMax <= 0 &&
+		f.RatingMin <= 0 && !f.Unwatched
+}
+
+// apply 把筛选条件叠加到仓储过滤条件上。
+func (f MediaListFilters) apply(filter repository.MediaQueryFilter) repository.MediaQueryFilter {
+	if len(f.Genres) > 0 {
+		filter.Genres = f.Genres
+	}
+	if f.YearMin > 0 {
+		filter.YearMin = f.YearMin
+	}
+	if f.YearMax > 0 {
+		filter.YearMax = f.YearMax
+	}
+	if f.RatingMin > 0 {
+		filter.RatingMin = f.RatingMin
+	}
+	if f.Unwatched && strings.TrimSpace(f.UserID) != "" {
+		filter.UnwatchedOnly = true
+		filter.UnwatchedUserID = f.UserID
+	}
+	return filter
+}
+
 func (s *MediaService) ListMedia(ctx context.Context, libraryID string, page, pageSize int) ([]model.Media, int64, error) {
 	return s.ListMediaVisible(ctx, libraryID, page, pageSize, MediaVisibility{IncludeNSFW: true})
 }
 
 func (s *MediaService) ListMediaVisible(ctx context.Context, libraryID string, page, pageSize int, visibility MediaVisibility) ([]model.Media, int64, error) {
+	return s.ListMediaVisibleFiltered(ctx, libraryID, page, pageSize, visibility, MediaListFilters{})
+}
+
+// ListMediaVisibleFiltered 在可见性之上叠加用户筛选条件。
+func (s *MediaService) ListMediaVisibleFiltered(
+	ctx context.Context,
+	libraryID string,
+	page, pageSize int,
+	visibility MediaVisibility,
+	filters MediaListFilters,
+) ([]model.Media, int64, error) {
 	if pageSize <= 0 {
 		pageSize = 50
 	}
@@ -31,11 +83,11 @@ func (s *MediaService) ListMediaVisible(ctx context.Context, libraryID string, p
 	if err != nil {
 		return nil, 0, err
 	}
-	filter := repository.MediaQueryFilter{
+	filter := filters.apply(repository.MediaQueryFilter{
 		IncludeNSFW:       visibility.IncludeNSFW,
 		AllowedLibraryIDs: visibility.AllowedLibraryIDs,
 		HiddenLibraryIDs:  visibility.HiddenLibraryIDs,
-	}
+	})
 	cacheKey := s.mediaListCacheKey(libraryID, libraryIDs, page, pageSize, filter)
 	var cached mediaListCacheValue
 	if s.cache != nil && s.cache.GetJSON(ctx, cacheKey, &cached) {
@@ -54,7 +106,6 @@ func (s *MediaService) ListMediaVisible(ctx context.Context, libraryID string, p
 }
 
 func (s *MediaService) ListMediaVisibleGrouped(ctx context.Context, libraryID string, page, pageSize int, visibility MediaVisibility) ([]MediaItem, int64, error) {
-	page, pageSize = normalizeGroupedMediaPage(page, pageSize)
 	grouped, err := s.GroupedMediaVisible(ctx, libraryID, visibility)
 	if err != nil {
 		return nil, 0, err
@@ -65,16 +116,29 @@ func (s *MediaService) ListMediaVisibleGrouped(ctx context.Context, libraryID st
 // GroupedMediaVisible returns the complete version-grouped media list before pagination.
 // The result is cached as an immutable slice; sort/pagination callers must copy it before mutating.
 func (s *MediaService) GroupedMediaVisible(ctx context.Context, libraryID string, visibility MediaVisibility) ([]MediaItem, error) {
+	return s.GroupedMediaVisibleFiltered(ctx, libraryID, visibility, MediaListFilters{})
+}
+
+// GroupedMediaVisibleFiltered 在可见性之上叠加用户筛选条件。
+//
+// 版本分组的筛选必须作用在原始行上（先筛后分组）：否则「按类型筛选」会把
+// 同一部作品的不同版本拆到不同筛选结果里，出现重复卡片。
+func (s *MediaService) GroupedMediaVisibleFiltered(
+	ctx context.Context,
+	libraryID string,
+	visibility MediaVisibility,
+	filters MediaListFilters,
+) ([]MediaItem, error) {
 	visibility = ExpandMediaVisibilityForMergedCloudLibraries(ctx, s.repo, visibility)
 	libraryIDs, err := MergedLibraryIDsForLibrary(ctx, s.repo, libraryID)
 	if err != nil {
 		return nil, err
 	}
-	filter := repository.MediaQueryFilter{
+	filter := filters.apply(repository.MediaQueryFilter{
 		IncludeNSFW:       visibility.IncludeNSFW,
 		AllowedLibraryIDs: visibility.AllowedLibraryIDs,
 		HiddenLibraryIDs:  visibility.HiddenLibraryIDs,
-	}
+	})
 	itemsCacheKey := s.groupedItemsCacheKey(libraryID, libraryIDs, filter)
 	value, err, _ := s.groupedMediaFlight.Do(itemsCacheKey, func() (any, error) {
 		if s.cache != nil {
@@ -86,7 +150,7 @@ func (s *MediaService) GroupedMediaVisible(ctx context.Context, libraryID string
 		}
 		loadCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 2*time.Minute)
 		defer cancel()
-		items, err := s.listMediaVisibleForGrouping(loadCtx, libraryID, visibility)
+		items, err := s.listMediaVisibleForGrouping(loadCtx, libraryID, visibility, filters)
 		if err != nil {
 			return nil, err
 		}
@@ -105,17 +169,17 @@ func (s *MediaService) GroupedMediaVisible(ctx context.Context, libraryID string
 	return nil, nil
 }
 
-func (s *MediaService) listMediaVisibleForGrouping(ctx context.Context, libraryID string, visibility MediaVisibility) ([]model.Media, error) {
+func (s *MediaService) listMediaVisibleForGrouping(ctx context.Context, libraryID string, visibility MediaVisibility, filters MediaListFilters) ([]model.Media, error) {
 	visibility = ExpandMediaVisibilityForMergedCloudLibraries(ctx, s.repo, visibility)
 	libraryIDs, err := MergedLibraryIDsForLibrary(ctx, s.repo, libraryID)
 	if err != nil {
 		return nil, err
 	}
-	filter := repository.MediaQueryFilter{
+	filter := filters.apply(repository.MediaQueryFilter{
 		IncludeNSFW:       visibility.IncludeNSFW,
 		AllowedLibraryIDs: visibility.AllowedLibraryIDs,
 		HiddenLibraryIDs:  visibility.HiddenLibraryIDs,
-	}
+	})
 	// 版本分组的 URL 分页发生在 Go 进程内，响应里的 total 是分组后的数量，
 	// 不需要数据库再为原始行做一次 COUNT(*)。全量 COUNT 在超大媒体库上
 	// 会重复扫描整个 library_id 范围，而这里只关心是否存在截断风险。
@@ -133,8 +197,7 @@ func (s *MediaService) listMediaVisibleForGrouping(ctx context.Context, libraryI
 }
 
 // GetMedia returns a single media row.
-func (s *MediaService) GetMedia(ctx context.Context, id string) (*model.Media, error) {
-	media, err := s.repo.Media.FindByID(ctx, id)
+func (s *MediaService) GetMedia(ctx context.Context, id string) (*model.Media, error) {	media, err := s.repo.Media.FindByID(ctx, id)
 	if err != nil || media == nil {
 		return media, err
 	}

internal/service/media_series.go

@@ -147,6 +147,98 @@ func (s *MediaService) ListLibrarySeriesCards(ctx context.Context, libraryID str
 	return cards, total, nil
 }
 
+// ListLibrarySeriesCardsFiltered 在系列卡片上应用筛选。
+//
+// 语义：先对原始剧集行做筛选，再分组 —— 于是「剧里任意一集命中条件」即可保留
+// 该剧。这比只筛代表行更符合直觉（用户勾选「动作」是想要动作剧，而不是
+// 「第一集恰好是动作的剧」）。
+//
+// 无筛选时直接走带缓存的原路径，避免平白多一次全库分组。
+func (s *MediaService) ListLibrarySeriesCardsFiltered(
+	ctx context.Context,
+	libraryID string,
+	visibility MediaVisibility,
+	filters MediaListFilters,
+) ([]SeriesCard, int64, error) {
+	if filters.empty() {
+		return s.ListLibrarySeriesCards(ctx, libraryID, visibility)
+	}
+	rows, err := s.libraryRowsWithIndex(ctx, libraryID, visibility)
+	if err != nil {
+		return nil, 0, err
+	}
+	completed := s.completedMediaIDSet(ctx, filters)
+	kept := make([]model.Media, 0, len(rows.Rows))
+	for _, row := range rows.Rows {
+		if !mediaRowMatchesFilters(&row, filters, completed) {
+			continue
+		}
+		kept = append(kept, row)
+	}
+	cards := groupMediaSeriesCards(kept)
+	if cards == nil {
+		cards = []SeriesCard{}
+	}
+	return cards, int64(len(cards)), nil
+}
+
+// mediaRowMatchesFilters 在内存里复现 SQL 层的筛选语义。
+//
+// 系列路径无法直接复用仓储过滤（它基于整库共享缓存），因此这里必须与
+// applyMediaQueryFilter 保持同一套判定，否则会出现「电影库能筛、剧集库不同」
+// 的行为差异。
+func mediaRowMatchesFilters(row *model.Media, filters MediaListFilters, completed map[string]bool) bool {
+	if row == nil {
+		return false
+	}
+	if filters.YearMin > 0 && row.Year < filters.YearMin {
+		return false
+	}
+	if filters.YearMax > 0 && row.Year > filters.YearMax {
+		return false
+	}
+	if filters.RatingMin > 0 && float64(row.Rating) < filters.RatingMin {
+		return false
+	}
+	if filters.Unwatched && completed[row.ID] {
+		return false
+	}
+	if len(filters.Genres) > 0 {
+		rowGenres := genreSet(row.Genres)
+		matched := false
+		for _, want := range filters.Genres {
+			if _, ok := rowGenres[strings.ToLower(strings.TrimSpace(want))]; ok {
+				matched = true
+				break
+			}
+		}
+		if !matched {
+			return false
+		}
+	}
+	return true
+}
+
+// completedMediaIDSet 返回该用户已标记看完的媒体 ID 集合（未启用未观看筛选时
+// 返回 nil，避免无谓查询）。
+func (s *MediaService) completedMediaIDSet(ctx context.Context, filters MediaListFilters) map[string]bool {
+	userID := strings.TrimSpace(filters.UserID)
+	if !filters.Unwatched || userID == "" {
+		return nil
+	}
+	var rows []model.PlaybackHistory
+	if err := s.repo.DB.WithContext(ctx).
+		Where("user_id = ? AND completed = ?", userID, true).
+		Find(&rows).Error; err != nil {
+		return nil
+	}
+	out := make(map[string]bool, len(rows))
+	for _, row := range rows {
+		out[row.MediaID] = true
+	}
+	return out
+}
+
 func (s *MediaService) ListRecentSeriesCards(ctx context.Context, limit int, visibility MediaVisibility) ([]SeriesCard, error) {
 	if limit <= 0 {
 		limit = 24

internal/service/scheduler.go

@@ -36,6 +36,7 @@ type SchedulerService struct {
 	organizePipeline *OrganizePipelineService
 	hub              *Hub
 	tasks            *TaskTrackerService
+	expiryWatcher    *TelegramExpiryWatcher
 	cacheDir         string
 	now              func() time.Time
 
@@ -59,6 +60,11 @@ func (s *SchedulerService) SetOrganizePipeline(pipeline *OrganizePipelineService
 	s.organizePipeline = pipeline
 }
 
+// SetExpiryWatcher 注入账号到期巡检。未注入时（例如测试）该任务不注册。
+func (s *SchedulerService) SetExpiryWatcher(watcher *TelegramExpiryWatcher) {
+	s.expiryWatcher = watcher
+}
+
 // ImageCachePolicy 是一次图片缓存清理要用的策略（全部为 0 表示不做任何清理）。
 type ImageCachePolicy struct {
 	TotalBytes     int64
@@ -139,6 +145,14 @@ func (s *SchedulerService) Start(ctx context.Context) {
 			run:      s.jobCleanImageCache,
 		},
 	}
+	// 到期提醒只在配置了巡检器时注册，避免测试与未启用通知的部署跑空转任务。
+	if s.expiryWatcher != nil {
+		s.jobs = append(s.jobs, &scheduledJob{
+			name:     "telegram_expiry_warning",
+			interval: 24 * time.Hour,
+			run:      s.jobTelegramExpiryWarning,
+		})
+	}
 	for _, j := range s.jobs {
 		initialDelay := 15 * time.Second
 		if j.name == "library_scan" || j.name == "organize_source" {

internal/service/scheduler_local_jobs.go

@@ -169,6 +169,14 @@ func (s *SchedulerService) organizeSourceInterval(ctx context.Context) time.Dura
 	return time.Duration(seconds) * time.Second
 }
 
+// jobTelegramExpiryWarning 每日巡检即将到期的账号并提醒用户。
+func (s *SchedulerService) jobTelegramExpiryWarning(ctx context.Context) error {
+	if s.expiryWatcher == nil {
+		return nil
+	}
+	return s.expiryWatcher.RunOnce(ctx)
+}
+
 // jobCleanTranscodeCache deletes HLS artefacts older than 24h.
 func (s *SchedulerService) jobCleanTranscodeCache(ctx context.Context) error {
 	if s.cacheDir == "" {

internal/service/service.go

@@ -59,6 +59,9 @@ type Container struct {
 	Token            *TokenService
 	ApiConfig        *ApiConfigService
 	Device           *DeviceService
+	Telegram         *TelegramService
+	TelegramExpiry   *TelegramExpiryWatcher
+	Discovery        *MediaDiscoveryService
 	Cache            *RuntimeCacheService
 	Sessions         *SessionTrackerService
 	RecognitionWords *RecognitionWordsService
@@ -103,6 +106,11 @@ func (c *Container) Boot() {
 	// 启动调度器定时任务
 	c.Scheduler.Start(c.stopCtx)
 
+	// Telegram 通知轮询（未启用或未配置 Token 时直接返回）
+	if c.Telegram != nil {
+		c.Telegram.Start(c.stopCtx)
+	}
+
 	// 远程 Emby 挂载兼容迁移：清理已删账号的残留挂载；旧账号无挂载时自动全量挂载
 	if c.EmbyRemote != nil {
 		c.EmbyRemote.CleanupOrphanMounts(c.stopCtx)

internal/service/service_builder.go

@@ -42,11 +42,22 @@ func newServiceContainer(cfg *config.Config, log *zap.Logger, repos *repository.
 	builder.initContentServices()
 	builder.initAccessAndStorageServices()
 	builder.initIdentityServices()
+	// Telegram 在 initIdentityServices 里构建，这里把失败告警接到任务状态机上。
+	builder.wireTaskNotifications()
 	builder.initImageProxy()
 	builder.attachRuntimeContext()
 	return builder.c
 }
 
+// wireTaskNotifications 把任务失败通知接到 Telegram。必须在 Tasks 与 Telegram
+// 都已构建之后调用：早于两者其一会静默漏接。
+func (b *serviceContainerBuilder) wireTaskNotifications() {
+	if b.c.Tasks == nil || b.c.Telegram == nil {
+		return
+	}
+	b.c.Tasks.SetFailureNotifier(b.c.Telegram.SendToAdmin)
+}
+
 func (b *serviceContainerBuilder) startRealtimeServices() {
 	b.c.WSHub = NewHub(b.log)
 	helper.Go(b.log, "ws.hub", b.c.WSHub.Run)
@@ -110,6 +121,9 @@ func (b *serviceContainerBuilder) initContentServices() {
 	b.c.DLNA = NewDLNAService(b.log)
 	b.c.Storage = NewStorageService(b.log, b.repos)
 	b.c.Emby = NewEmbyService(b.cfg, b.log, b.repos).SetTMDbProvider(b.c.TMDb).SetAdultProvider(b.c.Scraper.adult)
+	// 发现类查询（NextUp / Similar / Genres）：Emby 兼容层与媒体库筛选共用。
+	b.c.Discovery = NewMediaDiscoveryService(b.log, b.repos)
+	b.c.Emby.SetDiscovery(b.c.Discovery)
 	b.c.EmbyRemote = NewEmbyRemoteService(b.cfg, b.log, b.repos, b.c.Crypto).SetRuntimeCache(b.c.Cache)
 	b.c.Emby.SetEmbyRemote(b.c.EmbyRemote)
 	b.c.Backup = NewBackupService(b.cfg, b.log, b.repos.DB)
@@ -161,6 +175,7 @@ func (b *serviceContainerBuilder) initAccessAndStorageServices() {
 	b.c.Database = NewDatabaseAdminService(b.cfg, b.log, b.repos, b.repos.DB)
 	b.c.Emby.SetRuntimeCache(b.c.Cache)
 	b.c.Emby.SetSubtitleService(b.c.Subtitle)
+	b.c.Emby.SetDiscovery(b.c.Discovery)
 	b.c.Scheduler = NewSchedulerService(
 		b.log, b.repos, b.c.Scan, b.c.Transcoder,
 		b.c.Organizer, b.c.WSHub, b.cfg.Cache.CacheDir,
@@ -190,6 +205,15 @@ func (b *serviceContainerBuilder) initIdentityServices() {
 	b.c.Sessions = NewSessionTrackerService(b.log)
 	b.c.Device = NewDeviceService(b.log, b.repos)
 	b.c.Device.SetSessionTracker(b.c.Sessions)
+	// Telegram 通知：未启用时 Start 不会占用 goroutine，SendToUser 静默跳过。
+	b.c.Telegram = NewTelegramService(b.log, b.repos)
+	b.c.Device.SetNotifier(b.c.Telegram.SendToUser)
+	b.c.Device.SetAdminNotifier(b.c.Telegram.SendToAdmin)
+	// 账号到期巡检：只负责发现与去重，发送复用同一个 Telegram 通道。
+	b.c.TelegramExpiry = NewTelegramExpiryWatcher(b.log, b.repos)
+	b.c.TelegramExpiry.SetUserNotifier(b.c.Telegram.SendToUser)
+	// SetExpiryWatcher must run AFTER TelegramExpiry is constructed.
+	b.c.Scheduler.SetExpiryWatcher(b.c.TelegramExpiry)
 	b.c.ApiConfig = NewApiConfigService(b.cfg, b.log, b.repos, b.c.Crypto)
 }
 

internal/service/task_tracker.go

@@ -1,6 +1,9 @@
 package service
 
 import (
+	"context"
+	"html"
+	"strings"
 	"sync"
 	"time"
 
@@ -59,6 +62,9 @@ type TaskTrackerService struct {
 	log *zap.Logger
 	hub *Hub
 
+	// failureNotifier 在任务以失败收尾时通知管理员（Telegram）。nil 时静默。
+	failureNotifier func(ctx context.Context, text string)
+
 	mu        sync.Mutex
 	active    map[string]*BackgroundTask
 	recent    []BackgroundTask
@@ -179,8 +185,48 @@ func (t *TaskTrackerService) finish(id string, err error, update TaskUpdate) {
 	if len(t.recent) > t.maxRecent {
 		t.recent = t.recent[:t.maxRecent]
 	}
+	notifier := t.failureNotifier
 	t.mu.Unlock()
 	t.publish(snapshot)
+
+	// 失败通知放在锁外发送：网络请求绝不能阻塞任务状态机。
+	if err != nil && notifier != nil {
+		notifier(context.Background(), formatTaskFailureAlert(snapshot))
+	}
+}
+
+// SetFailureNotifier 注入任务失败时的管理员通知回调。
+func (t *TaskTrackerService) SetFailureNotifier(fn func(ctx context.Context, text string)) {
+	if t == nil {
+		return
+	}
+	t.mu.Lock()
+	t.failureNotifier = fn
+	t.mu.Unlock()
+}
+
+// formatTaskFailureAlert 生成面向管理员的失败摘要。错误信息可能很长
+// （ffmpeg 输出等），这里截断，避免超出 Telegram 单条消息长度。
+func formatTaskFailureAlert(task BackgroundTask) string {
+	const maxErrRunes = 500
+	text := strings.TrimSpace(task.Error)
+	runes := []rune(text)
+	if len(runes) > maxErrRunes {
+		text = string(runes[:maxErrRunes]) + "…"
+	}
+	var b strings.Builder
+	b.WriteString("⚠️ 任务失败：<b>")
+	b.WriteString(html.EscapeString(task.Name))
+	b.WriteString("</b>")
+	if task.SourcePath != "" {
+		b.WriteString("\n来源：")
+		b.WriteString(html.EscapeString(task.SourcePath))
+	}
+	if text != "" {
+		b.WriteString("\n错误：")
+		b.WriteString(html.EscapeString(text))
+	}
+	return b.String()
 }
 
 func (t *TaskTrackerService) currentTime() time.Time {

internal/service/telegram.go

@@ -0,0 +1,513 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/helper"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// Telegram 通知相关的设置键。全部存在 settings 表，由管理员在「设备与通知」
+// 设置分组里维护；带安全默认值：未启用时所有发送静默跳过。
+const (
+	SettingTelegramEnabled     = "telegram.enabled"      // 总开关（默认关）
+	SettingTelegramBotToken    = "telegram.bot_token"    // Bot API Token
+	SettingTelegramAdminChatID = "telegram.admin_chat_id" // 管理员接收运维通知的会话 ID
+)
+
+// telegramBindAlphabet 去掉容易看错的 0/O/1/I，降低手抄绑定码时的出错率。
+const telegramBindAlphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+
+const (
+	// telegramBindTTL 是绑定码的有效期。到期后必须重新生成。
+	telegramBindTTL = 5 * time.Minute
+	// telegramAPITimeout 覆盖单次 sendMessage 请求。
+	telegramAPITimeout = 10 * time.Second
+	// telegramPollClientTimeout 是长轮询专用 HTTP 客户端的超时，必须 > telegramPollTimeout。
+	telegramPollClientTimeout = 35 * time.Second
+	// telegramPollTimeout 是 getUpdates 的长轮询等待秒数。
+	telegramPollTimeout = 30
+	// telegramPollBackoff 是长轮询失败后的重试间隔，避免打爆 API。
+	telegramPollBackoff = 5 * time.Second
+	// telegramDisabledCheckInterval 是禁用状态下检查配置变化的间隔。
+	telegramDisabledCheckInterval = 10 * time.Second
+)
+
+var (
+	// ErrTelegramBindInvalid 表示绑定码不存在（不存在、已被使用，或已被新码取代）。
+	ErrTelegramBindInvalid = errors.New("telegram bind code not found")
+	// ErrTelegramBindExpired 表示绑定码已过期。
+	ErrTelegramBindExpired = errors.New("telegram bind code expired")
+)
+
+// telegramBindPending 记录一个待消费的绑定码。
+type telegramBindPending struct {
+	UserID    string
+	ExpiresAt time.Time
+}
+
+// TelegramService 负责把通知发到 Telegram，并提供账号绑定。
+//
+// 范围被刻意收窄：Bot 只处理 /bind 与 /start 两条命令，不做开注、签到、
+// 兑换码等命令体系。绑定走「网页生成一次性码 → Bot 端 /bind <code>」，
+// 这样服务端不需要用户手工填写 chat id。
+type TelegramService struct {
+	log  *zap.Logger
+	repo *repository.Container
+
+	mu      sync.Mutex
+	pending map[string]telegramBindPending // code -> pending
+	byUser  map[string]string              // userID -> code（同一用户只保留最新码）
+
+	// apiBase 允许测试指向本地假服务；生产固定为 Telegram 官方地址。
+	apiBase string
+	// lastUpdateID 是 getUpdates 的增量水位，避免重复处理同一条命令。
+	lastUpdateID int64
+	// client 可注入，便于测试替换传输层（sendMessage 等短请求）。
+	client *http.Client
+	// pollClient 专用于 getUpdates 长轮询，超时须 > telegramPollTimeout。
+	pollClient *http.Client
+}
+
+// NewTelegramService 构建 TelegramService。
+func NewTelegramService(log *zap.Logger, repo *repository.Container) *TelegramService {
+	return &TelegramService{
+		log:        log,
+		repo:       repo,
+		pending:    make(map[string]telegramBindPending),
+		byUser:     make(map[string]string),
+		apiBase:    "https://api.telegram.org",
+		client:     &http.Client{Timeout: telegramAPITimeout},
+		pollClient: &http.Client{Timeout: telegramPollClientTimeout},
+	}
+}
+
+// Start 在后台运行 Bot 命令长轮询。goroutine 始终启动；
+// 未启用或未配置 Token 时 pollLoop 内部休眠等待配置就绪，ctx 结束时停止。
+func (s *TelegramService) Start(ctx context.Context) {
+	if s == nil || s.repo == nil {
+		return
+	}
+	helper.Go(s.log, "service.telegramBotPoll", func() { s.pollLoop(ctx) })
+	if s.log != nil {
+		s.log.Info("telegram poller started")
+	}
+}
+
+type telegramConfig struct {
+	Enabled  bool
+	BotToken string
+	AdminID  string
+}
+
+func (s *TelegramService) config(ctx context.Context) telegramConfig {
+	return telegramConfig{
+		Enabled:  s.enabled(ctx),
+		BotToken: s.setting(ctx, SettingTelegramBotToken),
+		AdminID:  s.setting(ctx, SettingTelegramAdminChatID),
+	}
+}
+
+func (s *TelegramService) setting(ctx context.Context, key string) string {
+	if s == nil || s.repo == nil || s.repo.Setting == nil {
+		return ""
+	}
+	v, err := s.repo.Setting.Get(ctx, key)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(v)
+}
+
+func (s *TelegramService) enabled(ctx context.Context) bool {
+	return parseBoolSetting(s.setting(ctx, SettingTelegramEnabled), false)
+}
+
+// SendToUser 把消息发给用户绑定的 Telegram 会话。未绑定、未启用或发送失败
+// 都只记日志并返回：通知永远不能影响触发它的业务流程。
+func (s *TelegramService) SendToUser(ctx context.Context, userID, htmlText string) {
+	if s == nil || s.repo == nil || userID == "" || strings.TrimSpace(htmlText) == "" {
+		return
+	}
+	u, err := s.repo.User.FindByID(ctx, userID)
+	if err != nil || u == nil {
+		return
+	}
+	chatID := strings.TrimSpace(u.TelegramChatID)
+	if chatID == "" {
+		return
+	}
+	if err := s.sendMessage(ctx, chatID, htmlText); err != nil {
+		s.warn("telegram send to user failed", userID, err)
+	}
+}
+
+// SendToAdmin 把消息发给管理员会话，用于运维类事件（任务失败等）。
+func (s *TelegramService) SendToAdmin(ctx context.Context, htmlText string) {
+	if s == nil || s.repo == nil || strings.TrimSpace(htmlText) == "" {
+		return
+	}
+	chatID := s.setting(ctx, SettingTelegramAdminChatID)
+	if chatID == "" {
+		return
+	}
+	if err := s.sendMessage(ctx, chatID, htmlText); err != nil {
+		s.warn("telegram send to admin failed", chatID, err)
+	}
+}
+
+func (s *TelegramService) warn(msg, target string, err error) {
+	if s.log == nil {
+		return
+	}
+	s.log.Warn(msg, zap.String("target", target), zap.Error(err))
+}
+
+// Configured 报告通知是否已具备发送条件：启用 + Token + 管理员会话都齐了。
+func (s *TelegramService) Configured(ctx context.Context) bool {
+	if s == nil {
+		return false
+	}
+	cfg := s.config(ctx)
+	return cfg.Enabled && cfg.BotToken != "" && cfg.AdminID != ""
+}
+
+// SendToAdminChecked 是需要把失败反馈给管理员的场景（例如设置页的测试按钮）。
+// 它配置未就绪时返回错误；普通事件通知仍应使用静默的 SendToAdmin。
+func (s *TelegramService) SendToAdminChecked(ctx context.Context, htmlText string) error {
+	if s == nil || s.repo == nil {
+		return errors.New("telegram service unavailable")
+	}
+	chatID := s.setting(ctx, SettingTelegramAdminChatID)
+	if chatID == "" {
+		return errors.New("未配置管理员 Chat ID")
+	}
+	if !s.enabled(ctx) {
+		return errors.New("Telegram 通知未启用")
+	}
+	if s.setting(ctx, SettingTelegramBotToken) == "" {
+		return errors.New("未配置 Bot Token")
+	}
+	return s.sendMessage(ctx, chatID, htmlText)
+}
+
+// sendMessage 是唯一的出网点。所有前置条件在这里统一校验。
+func (s *TelegramService) sendMessage(ctx context.Context, chatID, htmlText string) error {
+	cfg := s.config(ctx)
+	if !cfg.Enabled || cfg.BotToken == "" {
+		return nil
+	}
+	payload := map[string]any{
+		"chat_id":    chatID,
+		"text":       htmlText,
+		"parse_mode": "HTML",
+	}
+	return s.call(ctx, cfg.BotToken, "sendMessage", payload, nil)
+}
+
+// call 发起一次 Bot API 调用（使用短请求客户端）。
+func (s *TelegramService) call(ctx context.Context, token, method string, payload map[string]any, out any) error {
+	return s.callWithClient(ctx, s.client, token, method, payload, out)
+}
+
+// callWithClient 发起一次 Bot API 调用，允许注入自定义 HTTP 客户端（例如长轮询专用）。
+// 失败时返回 Telegram 的 description，便于排查是 Token 错误、chat 不存在还是被限流。
+func (s *TelegramService) callWithClient(ctx context.Context, client *http.Client, token, method string, payload map[string]any, out any) error {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return err
+	}
+	url := fmt.Sprintf("%s/bot%s/%s", s.apiBase, token, method)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	if client == nil {
+		client = &http.Client{Timeout: telegramAPITimeout}
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return err
+	}
+	var envelope struct {
+		OK          bool            `json:"ok"`
+		Description string          `json:"description"`
+		Result      json.RawMessage `json:"result"`
+	}
+	if err := json.Unmarshal(raw, &envelope); err != nil {
+		return fmt.Errorf("telegram %s: decode response: %w", method, err)
+	}
+	if !envelope.OK {
+		if envelope.Description == "" {
+			envelope.Description = fmt.Sprintf("http %d", resp.StatusCode)
+		}
+		return fmt.Errorf("telegram %s: %s", method, envelope.Description)
+	}
+	if out != nil && len(envelope.Result) > 0 {
+		return json.Unmarshal(envelope.Result, out)
+	}
+	return nil
+}
+
+// StartBind 生成一次性绑定码。同一用户重复调用时旧码立即失效。
+func (s *TelegramService) StartBind(ctx context.Context, userID string) (string, error) {
+	if s == nil || strings.TrimSpace(userID) == "" {
+		return "", errors.New("telegram bind: empty user id")
+	}
+	code, err := randomBindCode()
+	if err != nil {
+		return "", err
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if prev, ok := s.byUser[userID]; ok {
+		delete(s.pending, prev)
+	}
+	s.pending[code] = telegramBindPending{UserID: userID, ExpiresAt: time.Now().Add(telegramBindTTL)}
+	s.byUser[userID] = code
+	return code, nil
+}
+
+// CompleteBind 消费绑定码并写入用户的 TelegramChatID。
+// 只在数据库写入成功后才删除 pending 中的绑定码；失败时码保留以便重试。
+func (s *TelegramService) CompleteBind(ctx context.Context, code, chatID string) error {
+	if s == nil || s.repo == nil {
+		return ErrTelegramBindInvalid
+	}
+	code = strings.ToUpper(strings.TrimSpace(code))
+	chatID = strings.TrimSpace(chatID)
+	if code == "" || chatID == "" {
+		return ErrTelegramBindInvalid
+	}
+
+	// 先读取，不删除——只有在操作成功后才消费绑定码。
+	s.mu.Lock()
+	pending, ok := s.pending[code]
+	s.mu.Unlock()
+	if !ok {
+		return ErrTelegramBindInvalid
+	}
+
+	if time.Now().After(pending.ExpiresAt) {
+		// 过期码：删除并返回，不再保留。
+		s.mu.Lock()
+		delete(s.pending, code)
+		if s.byUser[pending.UserID] == code {
+			delete(s.byUser, pending.UserID)
+		}
+		s.mu.Unlock()
+		return ErrTelegramBindExpired
+	}
+
+	if err := s.repo.User.UpdateFields(ctx, pending.UserID, map[string]any{"telegram_chat_id": chatID}); err != nil {
+		// DB 失败时保留 pending，调用方可重试。
+		return err
+	}
+
+	// 写入成功后再消费绑定码。
+	s.mu.Lock()
+	delete(s.pending, code)
+	if s.byUser[pending.UserID] == code {
+		delete(s.byUser, pending.UserID)
+	}
+	s.mu.Unlock()
+	return nil
+}
+
+// Unbind 清空用户的 Telegram 绑定。
+func (s *TelegramService) Unbind(ctx context.Context, userID string) error {
+	if s == nil || s.repo == nil {
+		return nil
+	}
+	s.mu.Lock()
+	if code, ok := s.byUser[userID]; ok {
+		delete(s.pending, code)
+		delete(s.byUser, userID)
+	}
+	s.mu.Unlock()
+	return s.repo.User.UpdateFields(ctx, userID, map[string]any{"telegram_chat_id": ""})
+}
+
+// Status 返回绑定状态与脱敏后的会话 ID，供个人资料页展示。
+func (s *TelegramService) Status(ctx context.Context, userID string) (bool, string) {
+	if s == nil || s.repo == nil || userID == "" {
+		return false, ""
+	}
+	u, err := s.repo.User.FindByID(ctx, userID)
+	if err != nil || u == nil || strings.TrimSpace(u.TelegramChatID) == "" {
+		return false, ""
+	}
+	return true, MaskSecret(u.TelegramChatID)
+}
+
+// MaskSecret 保留首尾各两个字符，中间以 *** 取代。用于 Token 与会话 ID
+// 这类「界面需要辨识、但不应完整下发」的凭据。
+func MaskSecret(value string) string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return ""
+	}
+	r := []rune(value)
+	if len(r) <= 4 {
+		return "***"
+	}
+	return string(r[:2]) + "***" + string(r[len(r)-2:])
+}
+
+func randomBindCode() (string, error) {
+	buf := make([]byte, 6)
+	if _, err := rand.Read(buf); err != nil {
+		return "", err
+	}
+	out := make([]byte, 6)
+	for i, b := range buf {
+		out[i] = telegramBindAlphabet[int(b)%len(telegramBindAlphabet)]
+	}
+	return string(out), nil
+}
+
+var telegramBindCommandPattern = regexp.MustCompile(`(?i)^/bind(?:@\w+)?\s+(\S+)\s*$`)
+
+// pollLoop 长轮询 Bot 更新，只处理绑定相关的两条命令。
+// 当 Telegram 未启用或 Token 未配置时，休眠后继续循环以便配置变更后自动激活。
+func (s *TelegramService) pollLoop(ctx context.Context) {
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		default:
+		}
+
+		cfg := s.config(ctx)
+		if !cfg.Enabled || cfg.BotToken == "" {
+			if !sleepCtx(ctx, telegramDisabledCheckInterval) {
+				return
+			}
+			continue
+		}
+		updates, err := s.fetchUpdates(ctx, cfg.BotToken)
+		if err != nil {
+			if s.log != nil && ctx.Err() == nil {
+				s.log.Warn("telegram getUpdates failed", zap.Error(err))
+			}
+			if !sleepCtx(ctx, telegramPollBackoff) {
+				return
+			}
+			continue
+		}
+		for _, u := range updates {
+			if u.UpdateID >= s.lastUpdateID {
+				s.lastUpdateID = u.UpdateID + 1
+			}
+			s.handleUpdate(ctx, cfg.BotToken, u)
+		}
+	}
+}
+
+type telegramUpdate struct {
+	UpdateID int64 `json:"update_id"`
+	Message  *struct {
+		Text string `json:"text"`
+		Chat struct {
+			ID int64 `json:"id"`
+		} `json:"chat"`
+	} `json:"message"`
+}
+
+func (s *TelegramService) fetchUpdates(ctx context.Context, token string) ([]telegramUpdate, error) {
+	s.mu.Lock()
+	offset := s.lastUpdateID
+	s.mu.Unlock()
+
+	payload := map[string]any{
+		"timeout": telegramPollTimeout,
+		// 只取消息更新，避免把频道/回调查询也塞进来。
+		"allowed_updates": []string{"message"},
+	}
+	if offset > 0 {
+		payload["offset"] = offset
+	}
+	var updates []telegramUpdate
+	if err := s.callWithClient(ctx, s.pollClient, token, "getUpdates", payload, &updates); err != nil {
+		return nil, err
+	}
+	return updates, nil
+}
+
+func (s *TelegramService) handleUpdate(ctx context.Context, token string, u telegramUpdate) {
+	if u.Message == nil {
+		return
+	}
+	text := strings.TrimSpace(u.Message.Text)
+	chatID := fmt.Sprintf("%d", u.Message.Chat.ID)
+	if chatID == "0" || text == "" {
+		return
+	}
+
+	if match := telegramBindCommandPattern.FindStringSubmatch(text); match != nil {
+		s.replyBind(ctx, token, chatID, match[1])
+		return
+	}
+	if strings.HasPrefix(strings.ToLower(text), "/start") {
+		if err := s.call(ctx, token, "sendMessage", map[string]any{
+			"chat_id":    chatID,
+			"text":       "MeBox 通知绑定：在网页「个人资料 → Telegram 通知」生成 6 位绑定码，然后发送 <code>/bind 绑定码</code>。",
+			"parse_mode": "HTML",
+		}, nil); err != nil {
+			s.warn("telegram /start reply failed", chatID, err)
+		}
+	}
+}
+
+func (s *TelegramService) replyBind(ctx context.Context, token, chatID, code string) {
+	message := ""
+	switch err := s.CompleteBind(ctx, code, chatID); {
+	case err == nil:
+		message = "✅ 绑定成功，之后 MeBox 的账号与设备通知会发到这里。"
+	case errors.Is(err, ErrTelegramBindExpired):
+		message = "⌛️ 绑定码已过期，请在网页重新生成。"
+	case errors.Is(err, ErrTelegramBindInvalid):
+		message = "❌ 绑定码无效，请在网页重新生成后再试。"
+	default:
+		message = "⚠️ 绑定失败，请稍后重试或查看服务日志。"
+	}
+	if err := s.call(ctx, token, "sendMessage", map[string]any{
+		"chat_id": chatID,
+		"text":    message,
+	}, nil); err != nil {
+		s.warn("telegram bind reply failed", chatID, err)
+	}
+}
+
+// sleepCtx 等待指定时长，ctx 结束则提前返回 false。
+func sleepCtx(ctx context.Context, d time.Duration) bool {
+	timer := time.NewTimer(d)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return false
+	case <-timer.C:
+		return true
+	}
+}

internal/service/telegram_alerts_test.go

@@ -0,0 +1,211 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// 任务失败必须通知管理员：否则只会停留在任务队列里等人自己发现。
+func TestTaskFailureNotifiesAdmin(t *testing.T) {
+	repos := repository.New(newServiceTestDB(t))
+	tracker := NewTaskTrackerService(zap.NewNop(), nil)
+
+	type call struct{ text string }
+	var adminCalls []call
+	tracker.SetFailureNotifier(func(_ context.Context, text string) {
+		adminCalls = append(adminCalls, call{text})
+	})
+
+	h := tracker.Start(TaskKindOrganize, "自动整理", TaskUpdate{})
+	h.Finish(errors.New("disk full"), TaskUpdate{})
+
+	if len(adminCalls) != 1 {
+		t.Fatalf("admin notifications = %d, want 1", len(adminCalls))
+	}
+	if !strings.Contains(adminCalls[0].text, "自动整理") {
+		t.Fatalf("notification = %q, want it to name the task", adminCalls[0].text)
+	}
+	if !strings.Contains(adminCalls[0].text, "disk full") {
+		t.Fatalf("notification = %q, want it to carry the error", adminCalls[0].text)
+	}
+	_ = repos
+}
+
+// 动态字段须 HTML 转义，避免路径/错误里的 <>& 破坏 parse_mode。
+func TestTaskFailureAlertEscapesHTML(t *testing.T) {
+	got := formatTaskFailureAlert(BackgroundTask{
+		Name:       "整理 <script>",
+		SourcePath: "C:\\a&b>c",
+		Error:      "fail <b>now</b>",
+	})
+	for _, bad := range []string{"<script>", "a&b>c", "<b>now</b>"} {
+		if strings.Contains(got, bad) {
+			t.Fatalf("alert still contains raw %q: %s", bad, got)
+		}
+	}
+	for _, want := range []string{"整理 &lt;script&gt;", "a&amp;b&gt;c", "fail &lt;b&gt;now&lt;/b&gt;"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("alert missing escaped %q: %s", want, got)
+		}
+	}
+}
+
+// 成功结束的任务不应触发失败通知。
+func TestTaskSuccessDoesNotNotifyAdmin(t *testing.T) {
+	tracker := NewTaskTrackerService(zap.NewNop(), nil)
+	var count int
+	tracker.SetFailureNotifier(func(context.Context, string) { count++ })
+
+	h := tracker.Start(TaskKindOrganize, "自动整理", TaskUpdate{})
+	h.Finish(nil, TaskUpdate{})
+
+	if count != 0 {
+		t.Fatalf("admin notifications = %d, want 0", count)
+	}
+}
+
+// 未接线通知时，任务路径必须照常完成。
+func TestTaskTrackerWorksWithoutNotifier(t *testing.T) {
+	tracker := NewTaskTrackerService(zap.NewNop(), nil)
+	h := tracker.Start(TaskKindScan, "扫描", TaskUpdate{})
+	h.Finish(errors.New("boom"), TaskUpdate{})
+}
+
+func TestExpiryWarningsTargetDueUsersOnly(t *testing.T) {
+	repos := repository.New(newServiceTestDB(t))
+	now := time.Date(2026, 9, 22, 12, 0, 0, 0, time.Local)
+	ctx := context.Background()
+
+	// 48h 内到期（落在 "3d" 桶：1-3 天）→ 应该提醒
+	soon := now.Add(48 * time.Hour)
+	// 三十天后到期 → 不应提醒
+	far := now.Add(30 * 24 * time.Hour)
+	for _, u := range []*model.User{
+		{Base: model.Base{ID: "u-soon"}, Username: "soon", PasswordHash: "x", Role: "user", IsActive: true, ExpiredAt: &soon, TelegramChatID: "111"},
+		{Base: model.Base{ID: "u-far"}, Username: "far", PasswordHash: "x", Role: "user", IsActive: true, ExpiredAt: &far, TelegramChatID: "222"},
+		{Base: model.Base{ID: "u-never"}, Username: "never", PasswordHash: "x", Role: "user", IsActive: true, TelegramChatID: "333"},
+	} {
+		if err := repos.User.Create(ctx, u); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	svc := NewTelegramExpiryWatcher(zap.NewNop(), repos)
+	svc.now = func() time.Time { return now }
+
+	var notified []string
+	svc.SetUserNotifier(func(_ context.Context, userID, _ string) { notified = append(notified, userID) })
+
+	if err := svc.RunOnce(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if len(notified) != 1 || notified[0] != "u-soon" {
+		t.Fatalf("notified = %v, want [u-soon]", notified)
+	}
+
+	// 同一桶重复运行不得重复打扰。
+	notified = nil
+	if err := svc.RunOnce(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if len(notified) != 0 {
+		t.Fatalf("second run notified %v, want none", notified)
+	}
+}
+
+// 未绑定 Telegram 的到期用户不应被通知，且不应写入标记键。
+func TestExpirySkipsUnboundUsers(t *testing.T) {
+	repos := repository.New(newServiceTestDB(t))
+	now := time.Date(2026, 9, 22, 12, 0, 0, 0, time.Local)
+	ctx := context.Background()
+
+	soon := now.Add(48 * time.Hour)
+	// 未绑定（TelegramChatID 为空）
+	unbound := &model.User{Base: model.Base{ID: "u-unbound"}, Username: "unbound", PasswordHash: "x", Role: "user", IsActive: true, ExpiredAt: &soon}
+	// 已绑定
+	bound := &model.User{Base: model.Base{ID: "u-bound"}, Username: "bound", PasswordHash: "x", Role: "user", IsActive: true, ExpiredAt: &soon, TelegramChatID: "999"}
+	for _, u := range []*model.User{unbound, bound} {
+		if err := repos.User.Create(ctx, u); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	svc := NewTelegramExpiryWatcher(zap.NewNop(), repos)
+	svc.now = func() time.Time { return now }
+
+	var notified []string
+	svc.SetUserNotifier(func(_ context.Context, userID, _ string) { notified = append(notified, userID) })
+
+	if err := svc.RunOnce(ctx); err != nil {
+		t.Fatal(err)
+	}
+	for _, id := range notified {
+		if id == "u-unbound" {
+			t.Fatal("unbound user must not be notified")
+		}
+	}
+	found := false
+	for _, id := range notified {
+		if id == "u-bound" {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatal("bound user must be notified")
+	}
+
+	// 未绑定用户不应写标记键：再次跑时仍然跳过（不重复通知）。
+	notified = nil
+	if err := svc.RunOnce(ctx); err != nil {
+		t.Fatal(err)
+	}
+	for _, id := range notified {
+		if id == "u-unbound" {
+			t.Fatal("unbound user notified on second run")
+		}
+	}
+}
+
+// 两个提醒桶（3d / 1d）各触发一次，互不干扰。
+func TestExpiryTwoBuckets(t *testing.T) {
+	repos := repository.New(newServiceTestDB(t))
+	ctx := context.Background()
+
+	now := time.Date(2026, 9, 22, 12, 0, 0, 0, time.Local)
+	// 用户的到期时间在 "1d" 桶内
+	oneDay := now.Add(12 * time.Hour)
+	u := &model.User{Base: model.Base{ID: "u1"}, Username: "alice", PasswordHash: "x", Role: "user", IsActive: true, ExpiredAt: &oneDay, TelegramChatID: "555"}
+	if err := repos.User.Create(ctx, u); err != nil {
+		t.Fatal(err)
+	}
+
+	svc := NewTelegramExpiryWatcher(zap.NewNop(), repos)
+	svc.now = func() time.Time { return now }
+
+	var count int
+	svc.SetUserNotifier(func(context.Context, string, string) { count++ })
+
+	// 第一次运行：1d 桶触发
+	if err := svc.RunOnce(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if count != 1 {
+		t.Fatalf("first run: count = %d, want 1", count)
+	}
+
+	// 第二次运行：1d 桶已标记，不再触发
+	if err := svc.RunOnce(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if count != 1 {
+		t.Fatalf("second run: count = %d, want still 1", count)
+	}
+}

internal/service/telegram_expiry.go

@@ -0,0 +1,117 @@
+package service
+
+import (
+	"context"
+	"fmt"
+	"html"
+	"strings"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// expiryNotifiedKeyPrefix 记录「某个用户在某个提醒桶已经提醒过」，防止重复打扰。
+// 键格式：telegram.expiry_notified.{userID}.{bucket}，bucket 为 "3d" 或 "1d"。
+const expiryNotifiedKeyPrefix = "telegram.expiry_notified."
+
+// expiryWarnWindow 是「即将到期」的判定总窗口（所有提醒桶中最大的上限）。
+const expiryWarnWindow = 72 * time.Hour
+
+// expiryBucket 描述一个提醒时间窗口。
+type expiryBucket struct {
+	name string
+	from time.Duration // 剩余时间下限（不含）
+	to   time.Duration // 剩余时间上限（含）
+}
+
+// expiryBuckets 定义两次提醒：约 3 天前 / 约 1 天前，各提醒一次。
+var expiryBuckets = []expiryBucket{
+	{"3d", 24 * time.Hour, 72 * time.Hour}, // 1–3 天
+	{"1d", 0, 24 * time.Hour},              // 0–1 天
+}
+
+// TelegramExpiryWatcher 每日巡检即将到期的账号并提醒用户。
+//
+// 只负责「发现 + 通知 + 去重」，发送本身交给注入的 notifier，因此没有配置
+// Telegram 时整条链路静默跳过。
+type TelegramExpiryWatcher struct {
+	log  *zap.Logger
+	repo *repository.Container
+	now  func() time.Time
+
+	userNotifier func(ctx context.Context, userID, text string)
+}
+
+// NewTelegramExpiryWatcher 构建巡检器。
+func NewTelegramExpiryWatcher(log *zap.Logger, repo *repository.Container) *TelegramExpiryWatcher {
+	return &TelegramExpiryWatcher{log: log, repo: repo, now: time.Now}
+}
+
+// SetUserNotifier 注入用户通知回调（通常是 TelegramService.SendToUser）。
+func (w *TelegramExpiryWatcher) SetUserNotifier(fn func(ctx context.Context, userID, text string)) {
+	if w == nil {
+		return
+	}
+	w.userNotifier = fn
+}
+
+// RunOnce 执行一次巡检。每个用户每个提醒桶（"3d" / "1d"）最多触发一次，
+// 未绑定 Telegram 的用户跳过且不写标记键。
+func (w *TelegramExpiryWatcher) RunOnce(ctx context.Context) error {
+	if w == nil || w.repo == nil || w.repo.User == nil || w.userNotifier == nil {
+		return nil
+	}
+	now := w.now()
+
+	for _, bucket := range expiryBuckets {
+		from := now.Add(bucket.from) // expired_at > from
+		to := now.Add(bucket.to)    // expired_at <= to
+
+		users, err := w.dueUsers(ctx, from, to)
+		if err != nil {
+			return err
+		}
+		for _, u := range users {
+			if u.ExpiredAt == nil {
+				continue
+			}
+			// 跳过未绑定 Telegram 的用户，且不消耗标记键。
+			if strings.TrimSpace(u.TelegramChatID) == "" {
+				continue
+			}
+			markKey := expiryNotifiedKeyPrefix + u.ID + "." + bucket.name
+			if seen, err := w.repo.Setting.Get(ctx, markKey); err == nil && strings.TrimSpace(seen) != "" {
+				continue
+			}
+			w.userNotifier(ctx, u.ID, fmt.Sprintf(
+				"⏳ 账号 <b>%s</b> 将于 %s 到期，请及时续期，避免到期后无法登录。",
+				html.EscapeString(u.Username), u.ExpiredAt.In(time.Local).Format("2006-01-02 15:04"),
+			))
+			// 仅在发送（尝试）后才写标记键。
+			if err := w.repo.Setting.Set(ctx, markKey, "1"); err != nil && w.log != nil {
+				w.log.Warn("telegram expiry mark failed", zap.String("user_id", u.ID), zap.Error(err))
+			}
+		}
+	}
+	return nil
+}
+
+// dueUsers 返回 (now, deadline] 内到期且仍处于启用状态的账号。
+func (w *TelegramExpiryWatcher) dueUsers(ctx context.Context, now, deadline time.Time) ([]*model.User, error) {
+	var users []model.User
+	err := w.repo.DB.WithContext(ctx).
+		Where("expired_at IS NOT NULL AND expired_at > ? AND expired_at <= ?", now, deadline).
+		Where("is_active = ?", true).
+		Find(&users).Error
+	if err != nil {
+		return nil, err
+	}
+	out := make([]*model.User, 0, len(users))
+	for i := range users {
+		out = append(out, &users[i])
+	}
+	return out, nil
+}

internal/service/telegram_test.go

@@ -0,0 +1,210 @@
+package service
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+func newTelegramTestService(t *testing.T) (*TelegramService, *repository.Container) {
+	t.Helper()
+	repos := repository.New(newServiceTestDB(t))
+	return NewTelegramService(zap.NewNop(), repos), repos
+}
+
+func seedTelegramTestUser(t *testing.T, repos *repository.Container, id, chatID string) {
+	t.Helper()
+	if err := repos.User.Create(context.Background(), &model.User{
+		Base:           model.Base{ID: id},
+		Username:       "tg-" + id,
+		PasswordHash:   "x",
+		Role:           "user",
+		IsActive:       true,
+		TelegramChatID: chatID,
+	}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestStartBindReturnsSixCharCode(t *testing.T) {
+	s, _ := newTelegramTestService(t)
+	code, err := s.StartBind(context.Background(), "u1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(code) != 6 {
+		t.Fatalf("code = %q, want 6 chars", code)
+	}
+	for _, r := range code {
+		if !strings.ContainsRune(telegramBindAlphabet, r) {
+			t.Fatalf("code %q contains unexpected rune %q", code, r)
+		}
+	}
+}
+
+// 同一用户重复申请绑定码时，旧码必须立即失效，避免多个有效码并存。
+func TestStartBindReplacesPreviousCode(t *testing.T) {
+	s, _ := newTelegramTestService(t)
+	first, err := s.StartBind(context.Background(), "u1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	second, err := s.StartBind(context.Background(), "u1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if first == second {
+		t.Skip("random collision, rerun")
+	}
+	if err := s.CompleteBind(context.Background(), first, "111"); err == nil {
+		t.Fatal("expected the superseded code to be rejected")
+	}
+}
+
+func TestCompleteBindRejectsExpiredCode(t *testing.T) {
+	s, _ := newTelegramTestService(t)
+	code, err := s.StartBind(context.Background(), "u1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	s.mu.Lock()
+	s.pending[code] = telegramBindPending{UserID: "u1", ExpiresAt: time.Now().Add(-time.Second)}
+	s.mu.Unlock()
+
+	if err := s.CompleteBind(context.Background(), code, "999"); err == nil {
+		t.Fatal("expected expired code to be rejected")
+	}
+}
+
+func TestCompleteBindWritesChatID(t *testing.T) {
+	s, repos := newTelegramTestService(t)
+	seedTelegramTestUser(t, repos, "u1", "")
+	code, err := s.StartBind(context.Background(), "u1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := s.CompleteBind(context.Background(), code, "987654321"); err != nil {
+		t.Fatal(err)
+	}
+	u, err := repos.User.FindByID(context.Background(), "u1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if u.TelegramChatID != "987654321" {
+		t.Fatalf("chat id = %q, want 987654321", u.TelegramChatID)
+	}
+	// 绑定成功后码必须被消费，不能重复使用。
+	if err := s.CompleteBind(context.Background(), code, "987654321"); err == nil {
+		t.Fatal("expected the consumed code to be rejected")
+	}
+}
+
+func TestStatusMasksChatID(t *testing.T) {
+	s, repos := newTelegramTestService(t)
+	seedTelegramTestUser(t, repos, "u1", "1234567890")
+
+	bound, masked := s.Status(context.Background(), "u1")
+	if !bound {
+		t.Fatal("expected bound user")
+	}
+	if strings.Contains(masked, "1234567890") {
+		t.Fatalf("chat id must not be exposed verbatim, got %q", masked)
+	}
+	if !strings.Contains(masked, "***") {
+		t.Fatalf("masked value should carry a *** marker, got %q", masked)
+	}
+}
+
+func TestUnbindClearsChatID(t *testing.T) {
+	s, repos := newTelegramTestService(t)
+	seedTelegramTestUser(t, repos, "u1", "555")
+
+	if err := s.Unbind(context.Background(), "u1"); err != nil {
+		t.Fatal(err)
+	}
+	u, err := repos.User.FindByID(context.Background(), "u1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if u.TelegramChatID != "" {
+		t.Fatalf("chat id = %q, want empty", u.TelegramChatID)
+	}
+}
+
+// 未启用 / 未配置 token 时，发送必须静默返回，绝不能发起网络请求或以 panic 收场。
+func TestSendNoopWhenDisabled(t *testing.T) {
+	s, repos := newTelegramTestService(t)
+	seedTelegramTestUser(t, repos, "u1", "1234567890")
+
+	s.SendToUser(context.Background(), "u1", "hello")
+	s.SendToAdmin(context.Background(), "hello")
+}
+
+// 未绑定 Telegram 的用户仍可能触发通知（例如首次登录），此时必须静默跳过。
+func TestSendNoopWhenUserUnbound(t *testing.T) {
+	s, _ := newTelegramTestService(t)
+	s.SendToUser(context.Background(), "missing-user", "hello")
+}
+
+// 数据库写入失败时绑定码必须保留，让用户可以重试。
+func TestCompleteBindKeepsPendingOnDBFailure(t *testing.T) {
+	db := newServiceTestDB(t)
+	repos := repository.New(db)
+	s := NewTelegramService(zap.NewNop(), repos)
+
+	code, err := s.StartBind(context.Background(), "u1")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 关闭底层数据库连接，强制 UpdateFields 失败。
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatal(err)
+	}
+	sqlDB.Close()
+
+	bindErr := s.CompleteBind(context.Background(), code, "999")
+	if bindErr == nil {
+		t.Fatal("expected an error from closed DB")
+	}
+
+	// 码必须还在 pending 里，以便重试。
+	s.mu.Lock()
+	_, stillPresent := s.pending[code]
+	s.mu.Unlock()
+	if !stillPresent {
+		t.Fatal("bind code must be retained when DB write fails, so the user can retry")
+	}
+}
+
+// pollLoop 在 Telegram 禁用状态下不应退出，而应持续等待配置开启。
+func TestPollLoopContinuesWhenDisabled(t *testing.T) {
+	repos := repository.New(newServiceTestDB(t))
+	s := NewTelegramService(zap.NewNop(), repos)
+
+	// 使用一个立即取消的 context 验证 goroutine 能正常退出（不阻塞）。
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		s.pollLoop(ctx)
+	}()
+
+	// 给 goroutine 启动时间，然后取消 context。
+	time.Sleep(20 * time.Millisecond)
+	cancel()
+
+	select {
+	case <-done:
+		// ok: goroutine 正常退出
+	case <-time.After(2 * time.Second):
+		t.Fatal("pollLoop did not exit after ctx cancellation")
+	}
+}