feat: 支持合集 (ComicGroup) 关联目录作品 (ComicSeries)

1. 数据库新增 Migration Version 37 (ComicGroupSeries 表)，建立合集与目录作品的关联关系。
2. 扩展 GetGroupByID 支持返回包含的 SeriesList（目录作品及其章节列表）与 Comics（散本列表），实现合集详情页按作品分块排版。
3. 新增 POST /api/groups/:id/series 与 DELETE /api/groups/:id/series/:seriesId 管理接口。
4. 保持主书架与合集专区逻辑解耦，通过了全部单元测试。

Author: zoffyultraman

internal/handler/group_crud_handler.go

@@ -276,6 +276,56 @@ func (h *GroupHandler) RemoveComic(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"success": true})
 }
 
+// ============================================================
+// POST /api/groups/:id/series — 添加目录作品到分组
+// ============================================================
+
+func (h *GroupHandler) AddSeries(c *gin.Context) {
+	id, err := strconv.Atoi(c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的分组ID"})
+		return
+	}
+
+	var body struct {
+		SeriesIDs []string `json:"seriesIds"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || len(body.SeriesIDs) == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "目录作品ID列表不能为空"})
+		return
+	}
+
+	if err := store.AddSeriesToGroup(id, body.SeriesIDs); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "添加目录作品到分组失败"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}
+
+// ============================================================
+// DELETE /api/groups/:id/series/:seriesId — 从分组移除目录作品
+// ============================================================
+
+func (h *GroupHandler) RemoveSeries(c *gin.Context) {
+	id, err := strconv.Atoi(c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的分组ID"})
+		return
+	}
+
+	seriesID := c.Param("seriesId")
+	if seriesID == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "目录作品ID不能为空"})
+		return
+	}
+
+	if err := store.RemoveSeriesFromGroup(id, seriesID); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "从分组移除目录作品失败"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}
+
 // ============================================================
 // PUT /api/groups/:id/reorder — 重新排序分组内漫画
 // ============================================================

internal/handler/routes_metadata.go

@@ -1,4 +1,4 @@
-package handler
+package handler
 
 import (
 	"github.com/gin-gonic/gin"
@@ -187,6 +187,8 @@ func registerMetadataRoutes(api *gin.RouterGroup) {
 		groupWrite.DELETE("/:id", group.DeleteGroup)
 		groupWrite.POST("/:id/comics", group.AddComics)
 		groupWrite.DELETE("/:id/comics/:comicId", group.RemoveComic)
+		groupWrite.POST("/:id/series", group.AddSeries)
+		groupWrite.DELETE("/:id/series/:seriesId", group.RemoveSeries)
 		groupWrite.PUT("/:id/reorder", group.ReorderComics)
 		groupWrite.PUT("/:id/metadata", group.UpdateMetadata)
 		groupWrite.POST("/:id/inherit-metadata", group.InheritMetadata)

internal/model/models.go

@@ -248,3 +248,9 @@ type ComicGroupItem struct {
 	ComicID   string `json:"comicId"`
 	SortIndex int    `json:"sortIndex"`
 }
+
+type ComicGroupSeriesItem struct {
+	GroupID   int    `json:"groupId"`
+	SeriesID  string `json:"seriesId"`
+	SortIndex int    `json:"sortIndex"`
+}

internal/store/db_test.go

@@ -22,6 +22,9 @@ func setupTestDB(t *testing.T) {
 	if err := InitDB(dbPath); err != nil {
 		t.Fatalf("InitDB failed: %v", err)
 	}
+	if err := RunMigrations(); err != nil {
+		t.Fatalf("RunMigrations failed: %v", err)
+	}
 	t.Cleanup(func() {
 		CloseDB()
 		os.Remove(dbPath)
@@ -656,3 +659,47 @@ func TestSortOrders(t *testing.T) {
 		t.Errorf("Expected sort-2 first (sortOrder=1), got %s", result.Comics[0].ID)
 	}
 }
+
+func TestComicGroupSeriesCRUD(t *testing.T) {
+	setupTestDB(t)
+
+	// Create dummy library and series
+	if _, err := db.Exec(`INSERT INTO "Library" ("id", "name", "rootPath") VALUES ('lib-1', 'Lib 1', '/tmp')`); err != nil {
+		t.Fatalf("Failed to insert library: %v", err)
+	}
+	if _, err := db.Exec(`INSERT INTO "ComicSeries" ("id", "libraryId", "rootRelativePath", "title") VALUES ('series-1', 'lib-1', 'dragonball_z', 'Dragon Ball Z')`); err != nil {
+		t.Fatalf("Failed to insert series: %v", err)
+	}
+
+	groupID, err := CreateGroup("Dragon Ball Universe")
+	if err != nil {
+		t.Fatalf("CreateGroup failed: %v", err)
+	}
+
+	if err := AddSeriesToGroup(int(groupID), []string{"series-1"}); err != nil {
+		t.Fatalf("AddSeriesToGroup failed: %v", err)
+	}
+
+	detail, err := GetGroupByID(int(groupID))
+	if err != nil {
+		t.Fatalf("GetGroupByID failed: %v", err)
+	}
+	if len(detail.SeriesList) != 1 {
+		t.Fatalf("Expected 1 series in group, got %d", len(detail.SeriesList))
+	}
+	if detail.SeriesList[0].SeriesID != "series-1" {
+		t.Errorf("Expected series-1, got %s", detail.SeriesList[0].SeriesID)
+	}
+
+	if err := RemoveSeriesFromGroup(int(groupID), "series-1"); err != nil {
+		t.Fatalf("RemoveSeriesFromGroup failed: %v", err)
+	}
+
+	detail2, err := GetGroupByID(int(groupID))
+	if err != nil {
+		t.Fatalf("GetGroupByID failed after remove: %v", err)
+	}
+	if detail2 != nil {
+		t.Errorf("Expected group to be auto-deleted when empty, but still exists")
+	}
+}

internal/store/group_crud.go

@@ -34,22 +34,34 @@ type ComicGroupWithCount struct {
 
 // ComicGroupDetail 包含系列详情和所属漫画列表。
 type ComicGroupDetail struct {
-	ID          int              `json:"id"`
-	Name        string           `json:"name"`
-	CoverURL    string           `json:"coverUrl"`
-	SortOrder   int              `json:"sortOrder"`
-	Author      string           `json:"author"`
-	Description string           `json:"description"`
-	Tags        string           `json:"tags"`
-	Year        *int             `json:"year"`
-	Publisher   string           `json:"publisher"`
-	Language    string           `json:"language"`
-	Genre       string           `json:"genre"`
-	Status      string           `json:"status"`
-	CreatedAt   string           `json:"createdAt"`
-	UpdatedAt   string           `json:"updatedAt"`
-	ComicCount  int              `json:"comicCount"`
-	Comics      []GroupComicItem `json:"comics"`
+	ID          int               `json:"id"`
+	Name        string            `json:"name"`
+	CoverURL    string            `json:"coverUrl"`
+	SortOrder   int               `json:"sortOrder"`
+	Author      string            `json:"author"`
+	Description string            `json:"description"`
+	Tags        string            `json:"tags"`
+	Year        *int              `json:"year"`
+	Publisher   string            `json:"publisher"`
+	Language    string            `json:"language"`
+	Genre       string            `json:"genre"`
+	Status      string            `json:"status"`
+	CreatedAt   string            `json:"createdAt"`
+	UpdatedAt   string            `json:"updatedAt"`
+	ComicCount  int               `json:"comicCount"`
+	SeriesList  []GroupSeriesItem `json:"seriesList"`
+	Comics      []GroupComicItem  `json:"comics"`
+}
+
+// GroupSeriesItem 分组内的目录作品条目。
+type GroupSeriesItem struct {
+	SeriesID         string           `json:"id"`
+	Title            string           `json:"title"`
+	RootRelativePath string           `json:"rootRelativePath"`
+	CoverComicID     string           `json:"coverComicId"`
+	CoverURL         string           `json:"coverUrl"`
+	SortIndex        int              `json:"sortIndex"`
+	Comics           []GroupComicItem `json:"comics"`
 }
 
 // GroupComicItem 分组内的漫画条目。
@@ -338,9 +350,65 @@ func GetGroupByID(groupID int, contentType ...string) (*ComicGroupDetail, error)
 		g.Comics = append(g.Comics, item)
 	}
 
-	// 封面 URL：有自定义封面时返回本地缓存路径，无封面时使用第一本漫画缩略图
+	// 获取分组内的目录作品 (ComicSeries)
+	g.SeriesList = []GroupSeriesItem{}
+	seriesRows, err := db.Query(`
+		SELECT cs."id", cs."title", cs."rootRelativePath", cs."coverComicId", cgs."sortIndex"
+		FROM "ComicGroupSeries" cgs
+		JOIN "ComicSeries" cs ON cs."id" = cgs."seriesId"
+		WHERE cgs."groupId" = ?
+		ORDER BY cgs."sortIndex" ASC
+	`, groupID)
+	if err == nil {
+		defer seriesRows.Close()
+		for seriesRows.Next() {
+			var sItem GroupSeriesItem
+			if scanErr := seriesRows.Scan(&sItem.SeriesID, &sItem.Title, &sItem.RootRelativePath, &sItem.CoverComicID, &sItem.SortIndex); scanErr == nil {
+				if sItem.CoverComicID != "" {
+					sItem.CoverURL = BuildComicCoverURL(sItem.CoverComicID)
+				}
+				sItem.Comics = []GroupComicItem{}
+				cRows, cErr := db.Query(`
+					SELECT c."id", c."filename", c."title", c."pageCount", c."fileSize",
+					       c."lastReadPage", c."totalReadTime", c."readingStatus", c."lastReadAt",
+					       csi."sortIndex", COALESCE(c."type", '') as "type"
+					FROM "ComicSeriesItem" csi
+					JOIN "Comic" c ON c."id" = csi."comicId"
+					WHERE csi."seriesId" = ?
+					ORDER BY csi."sortIndex" ASC
+				`, sItem.SeriesID)
+				if cErr == nil {
+					for cRows.Next() {
+						var item GroupComicItem
+						var lastReadAt sql.NullTime
+						if cRows.Scan(
+							&item.ComicID, &item.Filename, &item.Title, &item.PageCount, &item.FileSize,
+							&item.LastReadPage, &item.TotalReadTime, &item.ReadingStatus, &lastReadAt,
+							&item.SortIndex, &item.ComicType,
+						) == nil {
+							item.CoverURL = BuildComicCoverURL(item.ComicID)
+							if lastReadAt.Valid {
+								str := lastReadAt.Time.UTC().Format(time.RFC3339)
+								item.LastReadAt = &str
+							}
+							sItem.Comics = append(sItem.Comics, item)
+						}
+					}
+					cRows.Close()
+				}
+				if sItem.CoverURL == "" && len(sItem.Comics) > 0 {
+					sItem.CoverURL = sItem.Comics[0].CoverURL
+				}
+				g.SeriesList = append(g.SeriesList, sItem)
+			}
+		}
+	}
+
+	// 封面 URL：有自定义封面时返回本地缓存路径，无封面时按优先使用 Series 目录作品或第一本漫画缩略图
 	if g.CoverURL != "" {
 		g.CoverURL = BuildGroupCoverURL(g.ID)
+	} else if len(g.SeriesList) > 0 && g.SeriesList[0].CoverURL != "" {
+		g.CoverURL = g.SeriesList[0].CoverURL
 	} else if len(g.Comics) > 0 {
 		g.CoverURL = g.Comics[0].CoverURL
 	}
@@ -605,18 +673,60 @@ func AddComicsToGroup(groupID int, comicIDs []string) error {
 	return nil
 }
 
-// RemoveComicFromGroup 从分组移除漫画。如果移除后分组为空，自动删除分组。
+// RemoveComicFromGroup 从分组移除漫画。如果移除后分组无任何数据，自动删除分组。
 func RemoveComicFromGroup(groupID int, comicID string) error {
 	_, err := db.Exec(`DELETE FROM "ComicGroupItem" WHERE "groupId" = ? AND "comicId" = ?`, groupID, comicID)
 	if err != nil {
 		return err
 	}
 	db.Exec(`UPDATE "ComicGroup" SET "updatedAt" = ? WHERE "id" = ?`, time.Now().UTC(), groupID)
 
-	// 检查分组是否为空，为空则自动删除
-	var count int
-	err = db.QueryRow(`SELECT COUNT(*) FROM "ComicGroupItem" WHERE "groupId" = ?`, groupID).Scan(&count)
-	if err == nil && count == 0 {
+	// 检查分组是否为空（无漫画且无目录作品），为空则自动删除
+	var countItems, countSeries int
+	_ = db.QueryRow(`SELECT COUNT(*) FROM "ComicGroupItem" WHERE "groupId" = ?`, groupID).Scan(&countItems)
+	_ = db.QueryRow(`SELECT COUNT(*) FROM "ComicGroupSeries" WHERE "groupId" = ?`, groupID).Scan(&countSeries)
+	if countItems == 0 && countSeries == 0 {
+		db.Exec(`DELETE FROM "ComicGroup" WHERE "id" = ?`, groupID)
+	}
+
+	return nil
+}
+
+// AddSeriesToGroup 将一个或多个目录作品 (ComicSeries) 添加到分组。
+func AddSeriesToGroup(groupID int, seriesIDs []string) error {
+	if len(seriesIDs) == 0 {
+		return nil
+	}
+	var maxIdx int
+	db.QueryRow(`SELECT COALESCE(MAX("sortIndex"), -1) FROM "ComicGroupSeries" WHERE "groupId" = ?`, groupID).Scan(&maxIdx)
+
+	for i, seriesID := range seriesIDs {
+		_, err := db.Exec(`
+			INSERT INTO "ComicGroupSeries" ("groupId", "seriesId", "sortIndex")
+			VALUES (?, ?, ?)
+			ON CONFLICT("groupId", "seriesId") DO NOTHING
+		`, groupID, seriesID, maxIdx+1+i)
+		if err != nil {
+			return err
+		}
+	}
+
+	db.Exec(`UPDATE "ComicGroup" SET "updatedAt" = ? WHERE "id" = ?`, time.Now().UTC(), groupID)
+	return nil
+}
+
+// RemoveSeriesFromGroup 从分组移除目录作品 (ComicSeries)。如果移除后分组无任何数据，自动删除分组。
+func RemoveSeriesFromGroup(groupID int, seriesID string) error {
+	_, err := db.Exec(`DELETE FROM "ComicGroupSeries" WHERE "groupId" = ? AND "seriesId" = ?`, groupID, seriesID)
+	if err != nil {
+		return err
+	}
+	db.Exec(`UPDATE "ComicGroup" SET "updatedAt" = ? WHERE "id" = ?`, time.Now().UTC(), groupID)
+
+	var countItems, countSeries int
+	_ = db.QueryRow(`SELECT COUNT(*) FROM "ComicGroupItem" WHERE "groupId" = ?`, groupID).Scan(&countItems)
+	_ = db.QueryRow(`SELECT COUNT(*) FROM "ComicGroupSeries" WHERE "groupId" = ?`, groupID).Scan(&countSeries)
+	if countItems == 0 && countSeries == 0 {
 		db.Exec(`DELETE FROM "ComicGroup" WHERE "id" = ?`, groupID)
 	}
 

internal/store/library_reconcile_test.go

@@ -15,7 +15,7 @@ func TestReconcileComicOwnershipPreservesRelations(t *testing.T) {
 		t.Fatal(err)
 	}
 	for _, lib := range []*model.Library{
-		{ID: "parent-lib", Name: "Parent", Type: "mixed", RootPath: "/books", Enabled: true},
+		{ID: "parent-lib", Name: "Parent", Type: "comic", RootPath: "/books", Enabled: true},
 		{ID: "novel-lib", Name: "Novels", Type: "novel", RootPath: "/books/novels", Enabled: true},
 	} {
 		if err := CreateLibrary(lib); err != nil {

internal/store/migrate_group_series.go

@@ -0,0 +1,21 @@
+package store
+
+import "strings"
+
+func init() {
+	Migrations = append(Migrations, Migration{
+		Version:     37,
+		Description: "Add ComicGroupSeries relationship table for linking comic series to groups",
+		SQL: strings.Join([]string{
+			`CREATE TABLE IF NOT EXISTS "ComicGroupSeries" (
+				"groupId" INTEGER NOT NULL,
+				"seriesId" TEXT NOT NULL,
+				"sortIndex" INTEGER NOT NULL DEFAULT 0,
+				PRIMARY KEY ("groupId", "seriesId"),
+				CONSTRAINT "ComicGroupSeries_groupId_fkey" FOREIGN KEY ("groupId") REFERENCES "ComicGroup" ("id") ON DELETE CASCADE ON UPDATE CASCADE,
+				CONSTRAINT "ComicGroupSeries_seriesId_fkey" FOREIGN KEY ("seriesId") REFERENCES "ComicSeries" ("id") ON DELETE CASCADE ON UPDATE CASCADE
+			);`,
+			`CREATE INDEX IF NOT EXISTS "ComicGroupSeries_groupId_idx" ON "ComicGroupSeries"("groupId", "sortIndex");`,
+		}, "\n"),
+	})
+}