优化

internal/repository/media_repository_upsert.go

@@ -115,7 +115,12 @@ func (r *MediaRepository) upsertWithDB(ctx context.Context, db *gorm.DB, m *mode
 		return m.ID, nil
 	}
 
-	updates := mediaUpsertUpdates(existing, *m)
+	// 孤儿行回收：原库已被删除时（DeleteLibrary 硬删库行；扫描与删除并发时扫描也会
+	// 把行写回已删库），这条行会钉死在不存在的 library_id 上。media.path 是全局唯一
+	// 索引，重扫既插不进同路径新行，又因 LibraryID 非空而拒绝迁移归属，于是新库/重建库
+	// 永远查不到这些条目（表现为"扫描明明有文件，库却是空的"）。这里显式识别并允许迁移。
+	reclaimLibrary := r.mediaRowLibraryIsOrphaned(ctx, db, existing.LibraryID, m.LibraryID, m.Path)
+	updates := mediaUpsertUpdates(existing, *m, reclaimLibrary)
 	if adopted {
 		updates["path"] = m.Path
 		if existing.DeletedAt.Valid {
@@ -139,6 +144,42 @@ func (r *MediaRepository) upsertWithDB(ctx context.Context, db *gorm.DB, m *mode
 	return existing.ID, nil
 }
 
+// mediaRowLibraryIsOrphaned reports whether a media row is still pinned to a
+// library that no longer exists.
+//
+// 删除媒体库会硬删库行（见 MediaService.DeleteLibrary），但扫描与删除并发时，
+// 已在途的扫描仍可能把这批文件写回已删库的 library_id；历史数据里也可能留下
+// 指向早已消失的库的行。因为 media.path 是全局唯一索引，这些行一旦存在：
+//  1. 重扫无法插入同路径的新行（唯一约束冲突）；
+//  2. addMediaPlacementUpdates 又因为 existing.LibraryID 非空而拒绝迁移归属。
+//
+// 结果就是新库 / 重建的同名库永远查不到这些条目，扫描报告有文件而库显示为空。
+// 这里把"原库已不存在"这种情况单独判定出来，交给扫描把归属迁移到当前库。
+func (r *MediaRepository) mediaRowLibraryIsOrphaned(ctx context.Context, db *gorm.DB, existingLibraryID, incomingLibraryID, incomingPath string) bool {
+	existingLibraryID = strings.TrimSpace(existingLibraryID)
+	incomingLibraryID = strings.TrimSpace(incomingLibraryID)
+	// 归属未变或原行为空（后者走既有的回填分支）时无需查库。
+	if existingLibraryID == "" || existingLibraryID == incomingLibraryID {
+		return false
+	}
+	// 云盘媒体的归属迁移由 addMediaPlacementUpdates 无条件处理，无需再查库。
+	if strings.HasPrefix(strings.ToLower(strings.TrimSpace(incomingPath)), "cloud://") {
+		return false
+	}
+	if db == nil || !db.Migrator().HasTable(&model.Library{}) {
+		return false
+	}
+	var count int64
+	// 刻意不加 Unscoped：软删除的库同样不再出现在库里，挂在它下面的媒体行
+	// 也属于"查不到"的孤儿，一并允许回收。查询失败时保守处理：宁可保留旧
+	// 归属，也不要把仍有效的库误判成孤儿。
+	if err := db.WithContext(ctx).Model(&model.Library{}).
+		Where("id = ?", existingLibraryID).Count(&count).Error; err != nil {
+		return false
+	}
+	return count == 0
+}
+
 func (r *MediaRepository) findOrCreateMediaByPath(ctx context.Context, db *gorm.DB, m *model.Media, aliasPaths []string) (model.Media, bool, bool, error) {
 	var existing model.Media
 	err := db.WithContext(ctx).Unscoped().Where("path = ?", m.Path).First(&existing).Error
@@ -194,14 +235,14 @@ func (r *MediaRepository) findMediaByAlias(ctx context.Context, db *gorm.DB, cur
 	return existing, err
 }
 
-func mediaUpsertUpdates(existing, incoming model.Media) map[string]any {
+func mediaUpsertUpdates(existing, incoming model.Media, reclaimLibrary bool) map[string]any {
 	updates := map[string]any{}
 	addMediaFileScanUpdates(updates, existing, incoming)
 	addMediaTitleUpdates(updates, existing, incoming)
 	addMediaExternalIDUpdates(updates, existing, incoming)
 	addMatchedMediaMetadataUpdates(updates, existing, incoming)
 	addMediaArtworkUpdates(updates, existing, incoming)
-	addMediaPlacementUpdates(updates, existing, incoming)
+	addMediaPlacementUpdates(updates, existing, incoming, reclaimLibrary)
 	addMediaSTRMUpdate(updates, existing, incoming)
 	return updates
 }
@@ -308,13 +349,15 @@ func addMediaArtworkUpdates(updates map[string]any, existing, incoming model.Med
 	}
 }
 
-func addMediaPlacementUpdates(updates map[string]any, existing, incoming model.Media) {
+func addMediaPlacementUpdates(updates map[string]any, existing, incoming model.Media, reclaimLibrary bool) {
 	// 云盘媒体：同一 cloud:// 文件可能先被父目录库扫描入库，之后用户按二级
 	// 分类重新挂载/扫描到更精确的分类库。此时让 library_id 迁移到当前扫描库，
 	// 否则媒体被钉死在旧库、新分类库里看不到(表现为"媒体部分消失")。
-	// 本地媒体物理位置固定：仅在原 library_id 为空时回填，不迁移。
+	// 本地媒体物理位置固定：仅在原 library_id 为空、或原库已不存在（孤儿行，
+	// reclaimLibrary）时才回填/迁移，既避免把仍属于其他库的本地媒体抢走，
+	// 又能让扫描回收被删除库遗留的行。
 	if isCloudMediaPath := strings.HasPrefix(strings.ToLower(strings.TrimSpace(incoming.Path)), "cloud://"); incoming.LibraryID != "" && incoming.LibraryID != existing.LibraryID {
-		if isCloudMediaPath || existing.LibraryID == "" {
+		if isCloudMediaPath || existing.LibraryID == "" || reclaimLibrary {
 			updates["library_id"] = incoming.LibraryID
 		}
 	}

internal/repository/reader_repository.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 
 	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
 
 	"github.com/truewhile/MeBox/internal/model"
 )
@@ -15,6 +16,17 @@ type ReaderRepository struct {
 	db *gorm.DB
 }
 
+// readerOrderBy 组装方言安全的 ORDER BY。
+//
+// 用 clause.Column 让 GORM 按当前方言给列名加引号（SQLite 反引号 / PostgreSQL 双引号），
+// 而不是把引号硬编码进排序字符串。reader_books.order、reader_chapters.index、
+// reader_replace_rules.order 都撞上了 SQL 关键字（order 在 PostgreSQL 里是保留字）：
+// 之前写成 .Order("`order` ASC")，SQLite 下正常，PostgreSQL 下反引号被词法分析成
+// 运算符，直接报 `syntax error at or near "order"`，书架 / 目录 / 替换规则整页 500。
+func readerOrderBy(columns ...clause.OrderByColumn) clause.OrderBy {
+	return clause.OrderBy{Columns: columns}
+}
+
 // ListSources 用户的书源列表（书源按用户独立，按 customOrder 排序）。
 func (r *ReaderRepository) ListSources(ctx context.Context, userID string) ([]model.ReaderBookSource, error) {
 	var out []model.ReaderBookSource
@@ -153,7 +165,11 @@ func (r *ReaderRepository) SaveSourceState(ctx context.Context, st *model.Reader
 // ListBooks 用户书架（按 order 排序）。
 func (r *ReaderRepository) ListBooks(ctx context.Context, userID string) ([]model.ReaderBook, error) {
 	var out []model.ReaderBook
-	err := r.db.WithContext(ctx).Where("user_id = ?", userID).Order("`order` ASC, updated_at DESC").Find(&out).Error
+	err := r.db.WithContext(ctx).Where("user_id = ?", userID).
+		Order(readerOrderBy(
+			clause.OrderByColumn{Column: clause.Column{Name: "order"}},
+			clause.OrderByColumn{Column: clause.Column{Name: "updated_at"}, Desc: true},
+		)).Find(&out).Error
 	return out, err
 }
 
@@ -231,7 +247,10 @@ func (r *ReaderRepository) SwitchBookOrigin(ctx context.Context, book *model.Rea
 // ListChapters 按序取章节。
 func (r *ReaderRepository) ListChapters(ctx context.Context, bookID string) ([]model.ReaderChapter, error) {
 	var out []model.ReaderChapter
-	err := r.db.WithContext(ctx).Where("book_id = ?", bookID).Order("`index` ASC").Find(&out).Error
+	err := r.db.WithContext(ctx).Where("book_id = ?", bookID).
+		Order(readerOrderBy(
+			clause.OrderByColumn{Column: clause.Column{Name: "index"}},
+		)).Find(&out).Error
 	return out, err
 }
 
@@ -433,7 +452,11 @@ func (r *ReaderRepository) SaveBookGroups(ctx context.Context, row *model.Reader
 // ListReplaceRules 用户替换规则（按 order 排序）。
 func (r *ReaderRepository) ListReplaceRules(ctx context.Context, userID string) ([]model.ReaderReplaceRule, error) {
 	var out []model.ReaderReplaceRule
-	err := r.db.WithContext(ctx).Where("user_id = ?", userID).Order("`order` DESC, created_at ASC").Find(&out).Error
+	err := r.db.WithContext(ctx).Where("user_id = ?", userID).
+		Order(readerOrderBy(
+			clause.OrderByColumn{Column: clause.Column{Name: "order"}, Desc: true},
+			clause.OrderByColumn{Column: clause.Column{Name: "created_at"}},
+		)).Find(&out).Error
 	return out, err
 }
 

internal/repository/reader_repository_dialect_test.go

@@ -0,0 +1,113 @@
+package repository
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	gormlogger "gorm.io/gorm/logger"
+)
+
+// sqlCaptureLogger 只记录 GORM 生成的 SQL，不打印任何日志。
+type sqlCaptureLogger struct {
+	mu    sync.Mutex
+	lines []string
+}
+
+func (l *sqlCaptureLogger) LogMode(gormlogger.LogLevel) gormlogger.Interface { return l }
+func (l *sqlCaptureLogger) Info(context.Context, string, ...interface{})     {}
+func (l *sqlCaptureLogger) Warn(context.Context, string, ...interface{})     {}
+func (l *sqlCaptureLogger) Error(context.Context, string, ...interface{})    {}
+
+func (l *sqlCaptureLogger) Trace(_ context.Context, _ time.Time, fc func() (string, int64), _ error) {
+	sql, _ := fc()
+	l.mu.Lock()
+	l.lines = append(l.lines, sql)
+	l.mu.Unlock()
+}
+
+func (l *sqlCaptureLogger) all() string {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	return strings.Join(l.lines, "\n")
+}
+
+// newPostgresDryRunRepos 返回使用 PostgreSQL 方言的 repository 容器：
+// DryRun 只构建 SQL 不执行，DisableAutomaticPing 让它无需真实数据库也能离线运行，
+// 于是可以直接断言生成语句在 PostgreSQL 下是否合法。
+func newPostgresDryRunRepos(t *testing.T) (*Container, *sqlCaptureLogger) {
+	t.Helper()
+	rec := &sqlCaptureLogger{}
+	db, err := gorm.Open(postgres.New(postgres.Config{
+		DSN: "postgres://mebox:mebox@127.0.0.1:5432/mebox?sslmode=disable",
+	}), &gorm.Config{
+		DryRun:               true,
+		DisableAutomaticPing: true,
+		Logger:               rec,
+	})
+	if err != nil {
+		t.Fatalf("open dry-run postgres: %v", err)
+	}
+	return New(db), rec
+}
+
+// TestReaderListsUseDialectQuotedReservedColumns 守住阅读子系统列表查询在
+// PostgreSQL 下的合法性。reader_books.order / reader_chapters.index /
+// reader_replace_rules.order 都是关键字级列名（order 在 PostgreSQL 里是保留字）。
+//
+// 排序条件曾经写成硬编码反引号的原始字符串，例如 .Order("`order` ASC")：
+// SQLite 正常，PostgreSQL 会把反引号词法分析成运算符，直接报
+// `syntax error at or near "order"` (SQLSTATE 42601)，书架 / 目录 / 替换规则整页 500。
+// 现在改用 clause.Column，由 GORM 按方言加引号（SQLite 反引号 / PostgreSQL 双引号）。
+func TestReaderListsUseDialectQuotedReservedColumns(t *testing.T) {
+	ctx := context.Background()
+	cases := []struct {
+		name  string
+		run   func(repos *Container) error
+		wants []string
+	}{
+		{
+			name:  "books",
+			run:   func(repos *Container) error { _, err := repos.Reader.ListBooks(ctx, "user-1"); return err },
+			wants: []string{`"order"`, `"updated_at" DESC`},
+		},
+		{
+			name:  "chapters",
+			run:   func(repos *Container) error { _, err := repos.Reader.ListChapters(ctx, "book-1"); return err },
+			wants: []string{`"index"`},
+		},
+		{
+			name:  "replace rules",
+			run:   func(repos *Container) error { _, err := repos.Reader.ListReplaceRules(ctx, "user-1"); return err },
+			wants: []string{`"order" DESC`, `"created_at"`},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			repos, rec := newPostgresDryRunRepos(t)
+			if err := tc.run(repos); err != nil {
+				t.Fatalf("build query: %v", err)
+			}
+			sql := rec.all()
+			if strings.TrimSpace(sql) == "" {
+				t.Fatal("no SQL captured from the repository call")
+			}
+			if strings.Contains(sql, "`") {
+				t.Fatalf("SQL uses backtick quoting, which PostgreSQL rejects:\n%s", sql)
+			}
+			if !strings.Contains(sql, "ORDER BY") {
+				t.Fatalf("SQL has no ORDER BY clause:\n%s", sql)
+			}
+			for _, want := range tc.wants {
+				if !strings.Contains(sql, want) {
+					t.Fatalf("SQL missing %q:\n%s", want, sql)
+				}
+			}
+		})
+	}
+}

internal/service/scanner_incremental_test.go

@@ -282,6 +282,106 @@ func TestScanLibraryUpdatesExistingPathFromOverlappingLibrary(t *testing.T) {
 	}
 }
 
+// TestScanLibraryReclaimsMediaOrphanedByDeletedLibrary covers the "scan reports
+// files but the library stays empty" failure: a row left behind by a deleted
+// library keeps its stale library_id, and because media.path carries a global
+// unique index the rescan can neither insert a fresh row nor rewrite the
+// ownership, so a rebuilt library stays empty forever. The scan must reclaim
+// such orphaned rows for the library being scanned.
+func TestScanLibraryReclaimsMediaOrphanedByDeletedLibrary(t *testing.T) {
+	sc, repos := newScannerTestEnv(t)
+	root := t.TempDir()
+	file := filepath.Join(root, "Orphaned Episode 1.mkv")
+	if err := os.WriteFile(file, []byte("payload"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	oldLib := model.Library{Name: "Old", Path: root, Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &oldLib); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := sc.ScanLibrary(t.Context(), oldLib.ID); err != nil {
+		t.Fatalf("first scan: %v", err)
+	}
+
+	// Reproduce the gap the scan cannot see: the library row is gone while its
+	// media rows survive (hard-deleted library, or an in-flight scan writing
+	// after DeleteLibrary).
+	if err := repos.DB.Unscoped().Delete(&model.Library{}, "id = ?", oldLib.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if got := countMediaInLibrary(t, repos, oldLib.ID); got != 1 {
+		t.Fatalf("precondition: rows still pinned to deleted library = %d, want 1", got)
+	}
+
+	newLib := model.Library{Name: "New", Path: root, Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &newLib); err != nil {
+		t.Fatal(err)
+	}
+	res, err := sc.ScanLibrary(t.Context(), newLib.ID)
+	if err != nil {
+		t.Fatalf("rescan: %v", err)
+	}
+	if res.ErrorCount != 0 {
+		t.Fatalf("rescan errors = %#v, want none", res.Errors)
+	}
+	if got := countMedia(t, repos); got != 1 {
+		t.Fatalf("media count = %d, want 1 (orphan reclaimed, not duplicated)", got)
+	}
+	if got := countMediaInLibrary(t, repos, newLib.ID); got != 1 {
+		t.Fatalf("rebuilt library media count = %d, want 1", got)
+	}
+	var media model.Media
+	if err := repos.DB.First(&media, "path = ?", file).Error; err != nil {
+		t.Fatal(err)
+	}
+	if media.LibraryID != newLib.ID {
+		t.Fatalf("media library_id = %q, want reclaimed to %q", media.LibraryID, newLib.ID)
+	}
+}
+
+// TestScanLibraryKeepsOwnershipWhenOwningLibraryStillExists pins the other half
+// of the rule: local media stays with its existing library as long as that
+// library is real, so overlapping libraries do not steal each other's rows.
+func TestScanLibraryKeepsOwnershipWhenOwningLibraryStillExists(t *testing.T) {
+	sc, repos := newScannerTestEnv(t)
+	root := t.TempDir()
+	file := filepath.Join(root, "Shared (2026).mkv")
+	if err := os.WriteFile(file, []byte("payload"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	ownerLib := model.Library{Name: "Owner", Path: root, Type: "movie", Enabled: true}
+	otherLib := model.Library{Name: "Other", Path: root, Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &ownerLib); err != nil {
+		t.Fatal(err)
+	}
+	if err := repos.Library.Create(t.Context(), &otherLib); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := sc.ScanLibrary(t.Context(), ownerLib.ID); err != nil {
+		t.Fatalf("owner scan: %v", err)
+	}
+	if _, err := sc.ScanLibrary(t.Context(), otherLib.ID); err != nil {
+		t.Fatalf("other scan: %v", err)
+	}
+	var media model.Media
+	if err := repos.DB.First(&media, "path = ?", file).Error; err != nil {
+		t.Fatal(err)
+	}
+	if media.LibraryID != ownerLib.ID {
+		t.Fatalf("media library_id = %q, want unchanged owner %q", media.LibraryID, ownerLib.ID)
+	}
+}
+
+func countMediaInLibrary(t *testing.T, repos *repository.Container, libraryID string) int64 {
+	t.Helper()
+	var n int64
+	if err := repos.DB.Model(&model.Media{}).Where("library_id = ?", libraryID).Count(&n).Error; err != nil {
+		t.Fatal(err)
+	}
+	return n
+}
+
 func TestScanLibrarySkipsUnchangedLocalMetadata(t *testing.T) {
 	sc, repos := newScannerTestEnv(t)
 	root := t.TempDir()