增强 OPDS 旧客户端下载兼容性

Author: zoffyultraman

docs/API.md

@@ -367,7 +367,8 @@ GET /api/comics?readingStatus=finished
 | GET | `/api/opds/search.xml` | OpenSearch 搜索描述 |
 | GET | `/api/opds/search` | OPDS 搜索 |
 | GET | `/api/opds/cover/:id` | OPDS 漫画封面 |
-| GET/HEAD | `/api/opds/download/:id` | 下载原始文件，支持字节范围请求 |
+| GET/HEAD | `/api/opds/download/:id/:filename` | 下载原始文件，支持字节范围请求 |
+| GET/HEAD | `/api/opds/download/:id` | 兼容旧版下载地址 |
 | GET | `/api/recommendations` | 个性化推荐 |
 | GET | `/api/recommendations/similar/:id` | 相似推荐 |
 | POST | `/api/recommendations/ai-reasons` | AI 推荐理由 |
@@ -381,6 +382,7 @@ GET /api/comics?readingStatus=finished
 - **内容范围**：只返回 `Comic.type=comic`、所属 `Library.type=comic` 且书库已启用的内容。小说不会出现在目录、搜索、最近更新或收藏中。
 - **文件格式**：CBZ/ZIP、CBR/RAR、CB7/7Z 和 PDF。EPUB、TXT 等小说格式不进入 OPDS。
 - **分段下载**：下载接口支持 `HEAD` 和 HTTP Range。合法范围请求返回 `206 Partial Content`、`Content-Range` 与分段 `Content-Length`，便于客户端读取大型 CBZ/PDF 的尾部目录。
+- **下载发现**：Feed 中的 acquisition URL 以经过转义的真实文件名结尾，并通过 Atom `length` 属性提供文件字节数。旧版不带文件名的下载地址继续可用。
 - **媒体类型**：CBZ/ZIP 使用标准媒体类型 `application/vnd.comicbook+zip`；CBR/RAR、CB7/7Z 和 PDF 分别使用对应的漫画归档或 PDF 媒体类型。
 - **权限**：OPDS 是获取目录，只返回当前用户拥有 `canDownload` 权限的书库内容。公开书库或仅有 `canView` 权限不会自动获得 OPDS 下载权限。
 - **合集导航**：根目录包含 `/api/opds/series` 入口。该接口返回 `kind=navigation`，每个合集链接到 `/api/opds/series/:id` 获取 Feed；合集内按现有篇章和成员顺序扁平排列，篇章名会作为条目标题前缀。

docs/api_doc.html

@@ -5750,20 +5750,21 @@ <h4>Response <span class="status-code">200</span></h4>
   </div>
 </div>
 
-<div class="endpoint auth-required" data-search="GET HEAD /api/opds/download/:id OPDS comic file range download" id="get-api-opds-download-id">
+<div class="endpoint auth-required" data-search="GET HEAD /api/opds/download/:id/:filename OPDS comic file range download" id="get-api-opds-download-id">
   <div class="endpoint-header">
     <span class="method method-GET">GET</span>
-    <span class="path">/api/opds/download/:id</span>
+    <span class="path">/api/opds/download/:id/:filename</span>
     <span class="summary">OPDS comic file download</span>
   </div>
   <div class="endpoint-body">
-    <p class="description">Downloads a supported comic file with permission checks. Supports HEAD and HTTP byte ranges for large-file and ZIP central-directory access.</p>
+    <p class="description">Downloads a supported comic file with permission checks. Feed links include the escaped source filename and Atom length metadata for older clients. The filename-free path remains available as a legacy alias. Supports HEAD and HTTP byte ranges.</p>
 
     <h4>Path Parameters</h4>
     <table class="params-table">
       <thead><tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr></thead>
       <tbody>
         <tr><td>id</td><td>string</td><td>Yes</td><td>Comic ID</td></tr>
+        <tr><td>filename</td><td>string</td><td>Yes</td><td>Escaped source filename used for client format detection</td></tr>
       </tbody>
     </table>
 

frontend/public/api-doc.html

@@ -6163,20 +6163,21 @@ <h4><span data-en="Response" data-zh="响应">Response</span> <span class="statu
   </div>
 </div>
 
-<div class="endpoint auth-required" data-search="GET HEAD /api/opds/download/:id OPDS comic file range download" id="get-api-opds-download-id">
+<div class="endpoint auth-required" data-search="GET HEAD /api/opds/download/:id/:filename OPDS comic file range download" id="get-api-opds-download-id">
   <div class="endpoint-header">
     <span class="method method-GET">GET</span>
-    <span class="path">/api/opds/download/:id</span>
+    <span class="path">/api/opds/download/:id/:filename</span>
     <span class="summary"><span data-en="OPDS comic file download" data-zh="OPDS漫画文件下载">OPDS comic file download</span></span>
   </div>
   <div class="endpoint-body">
-    <p class="description"><span data-en="Downloads a supported comic publication after rechecking content type, enabled comic library membership, and canDownload permission. Supports HEAD and HTTP byte ranges for large-file and ZIP central-directory access. Novel and unsupported-format IDs return 404; missing download permission returns 403." data-zh="重新检查内容类型、已启用漫画书库归属和 canDownload 权限后下载受支持的漫画文件。支持 HEAD 和 HTTP 字节范围请求，便于客户端读取大文件及 ZIP 中央目录。小说和不支持格式的 ID 返回 404；缺少下载权限返回 403。">Downloads a supported comic publication after rechecking content type, enabled comic library membership, and canDownload permission. Supports HEAD and HTTP byte ranges for large-file and ZIP central-directory access. Novel and unsupported-format IDs return 404; missing download permission returns 403.</span></p>
+    <p class="description"><span data-en="Downloads a supported comic publication after rechecking content type, enabled comic library membership, and canDownload permission. Feed links include the escaped source filename and Atom length metadata for older clients; /api/opds/download/:id remains available as a legacy alias. Supports HEAD and HTTP byte ranges." data-zh="重新检查内容类型、已启用漫画书库归属和 canDownload 权限后下载受支持的漫画文件。Feed 链接包含转义后的源文件名和 Atom length 字节数，以兼容旧客户端；/api/opds/download/:id 继续作为旧版别名。支持 HEAD 和 HTTP 字节范围请求。">Downloads a supported comic publication after rechecking content type, enabled comic library membership, and canDownload permission. Feed links include the escaped source filename and Atom length metadata for older clients; /api/opds/download/:id remains available as a legacy alias. Supports HEAD and HTTP byte ranges.</span></p>
 
     <h4><span data-en="Path Parameters" data-zh="路径参数">Path Parameters</span></h4>
     <table class="params-table">
       <thead><tr><th><span data-en="Name" data-zh="名称">Name</span></th><th><span data-en="Type" data-zh="类型">Type</span></th><th><span data-en="Required" data-zh="必填">Required</span></th><th><span data-en="Description" data-zh="说明">Description</span></th></tr></thead>
       <tbody>
         <tr><td>id</td><td>string</td><td>Yes</td><td>Comic ID</td></tr>
+        <tr><td>filename</td><td>string</td><td>Yes</td><td>Escaped source filename used for client format detection</td></tr>
       </tbody>
     </table>
 

internal/handler/opds_handler.go

@@ -402,6 +402,7 @@ func toOPDSComics(rows []store.OPDSComicRow) []service.OPDSComic {
 			Publisher:   row.Publisher,
 			Year:        row.Year,
 			PageCount:   row.PageCount,
+			FileSize:    row.FileSize,
 			AddedAt:     row.AddedAt,
 			UpdatedAt:   row.UpdatedAt,
 			Tags:        row.Tags,

internal/handler/opds_handler_test.go

@@ -131,7 +131,8 @@ func TestOPDSDownloadSupportsFullRangeAndHeadRequests(t *testing.T) {
 		t.Fatalf("SetUserLibraryAccess failed: %v", err)
 	}
 
-	full := performOPDSRequest(router, http.MethodGet, "/api/opds/download/opds-range-comic", user.Username, token, nil)
+	downloadPath := "/api/opds/download/opds-range-comic/Range%20Comic.cbz"
+	full := performOPDSRequest(router, http.MethodGet, downloadPath, user.Username, token, nil)
 	if full.Code != http.StatusOK {
 		t.Fatalf("full download returned %d: %s", full.Code, full.Body.String())
 	}
@@ -153,7 +154,7 @@ func TestOPDSDownloadSupportsFullRangeAndHeadRequests(t *testing.T) {
 
 	const tailSize = 22
 	rangeHeader := map[string]string{"Range": "bytes=-22"}
-	partial := performOPDSRequest(router, http.MethodGet, "/api/opds/download/opds-range-comic", user.Username, token, rangeHeader)
+	partial := performOPDSRequest(router, http.MethodGet, downloadPath, user.Username, token, rangeHeader)
 	if partial.Code != http.StatusPartialContent {
 		t.Fatalf("range download returned %d: %s", partial.Code, partial.Body.String())
 	}
@@ -165,7 +166,7 @@ func TestOPDSDownloadSupportsFullRangeAndHeadRequests(t *testing.T) {
 		t.Fatal("range response does not contain the requested ZIP tail")
 	}
 
-	head := performOPDSRequest(router, http.MethodHead, "/api/opds/download/opds-range-comic", user.Username, token, nil)
+	head := performOPDSRequest(router, http.MethodHead, downloadPath, user.Username, token, nil)
 	if head.Code != http.StatusOK {
 		t.Fatalf("HEAD download returned %d: %s", head.Code, head.Body.String())
 	}
@@ -175,6 +176,11 @@ func TestOPDSDownloadSupportsFullRangeAndHeadRequests(t *testing.T) {
 	if got := head.Header().Get("Content-Length"); got != strconv.Itoa(len(content)) {
 		t.Fatalf("HEAD Content-Length = %q, want %d", got, len(content))
 	}
+
+	legacy := performOPDSRequest(router, http.MethodGet, "/api/opds/download/opds-range-comic", user.Username, token, nil)
+	if legacy.Code != http.StatusOK || !bytes.Equal(legacy.Body.Bytes(), content) {
+		t.Fatalf("legacy filename-free download failed with status %d", legacy.Code)
+	}
 }
 
 func TestOPDSSeriesFeedsAreDownloadScopedAndFlattenSections(t *testing.T) {

internal/handler/routes_metadata.go

@@ -119,6 +119,8 @@ func registerMetadataRoutes(api *gin.RouterGroup) {
 		opdsGroup.GET("/cover/:id", opds.Cover)
 		opdsGroup.GET("/download/:id", opds.Download)
 		opdsGroup.HEAD("/download/:id", opds.Download)
+		opdsGroup.GET("/download/:id/:filename", opds.Download)
+		opdsGroup.HEAD("/download/:id/:filename", opds.Download)
 	}
 
 	// Recommendations — require auth

internal/service/opds.go

@@ -3,6 +3,7 @@ package service
 import (
 	"encoding/xml"
 	"fmt"
+	"net/url"
 	"path/filepath"
 	"strconv"
 	"strings"
@@ -31,6 +32,7 @@ type OPDSComic struct {
 	Publisher   string
 	Year        int
 	PageCount   int
+	FileSize    int64
 	AddedAt     string
 	UpdatedAt   string
 	Tags        []string
@@ -96,10 +98,11 @@ type atomAuthor struct {
 }
 
 type atomLink struct {
-	Rel   string `xml:"rel,attr"`
-	Href  string `xml:"href,attr"`
-	Type  string `xml:"type,attr,omitempty"`
-	Title string `xml:"title,attr,omitempty"`
+	Rel    string `xml:"rel,attr"`
+	Href   string `xml:"href,attr"`
+	Type   string `xml:"type,attr,omitempty"`
+	Title  string `xml:"title,attr,omitempty"`
+	Length string `xml:"length,attr,omitempty"`
 }
 
 type atomEntry struct {
@@ -271,7 +274,12 @@ func GenerateAcquisitionFeed(opts OPDSAcquisitionFeedOptions) string {
 			Links: []atomLink{
 				{Rel: "http://opds-spec.org/image", Href: absoluteOPDSURL(opts.BaseURL, "/api/opds/cover/"+comic.ID)},
 				{Rel: "http://opds-spec.org/image/thumbnail", Href: absoluteOPDSURL(opts.BaseURL, "/api/opds/cover/"+comic.ID)},
-				{Rel: "http://opds-spec.org/acquisition", Href: absoluteOPDSURL(opts.BaseURL, "/api/opds/download/"+comic.ID), Type: mimeType},
+				{
+					Rel:    "http://opds-spec.org/acquisition",
+					Href:   absoluteOPDSURL(opts.BaseURL, opdsDownloadPath(comic.ID, comic.Filename)),
+					Type:   mimeType,
+					Length: opdsFileLength(comic.FileSize),
+				},
 			},
 			Language:  strings.TrimSpace(comic.Language),
 			Publisher: strings.TrimSpace(comic.Publisher),
@@ -327,6 +335,21 @@ func GenerateAcquisitionFeed(opts OPDSAcquisitionFeedOptions) string {
 	return marshalOPDSXML(feed)
 }
 
+func opdsDownloadPath(comicID, filename string) string {
+	name := filepath.Base(strings.TrimSpace(filename))
+	if name == "" || name == "." {
+		return "/api/opds/download/" + comicID
+	}
+	return "/api/opds/download/" + comicID + "/" + url.PathEscape(name)
+}
+
+func opdsFileLength(fileSize int64) string {
+	if fileSize <= 0 {
+		return ""
+	}
+	return strconv.FormatInt(fileSize, 10)
+}
+
 func appendOPDSPaginationLinks(feed *atomFeed, baseURL string, pagination OPDSPagination, feedType string) {
 	links := []struct {
 		rel  string

internal/service/opds_test.go

@@ -56,6 +56,7 @@ func TestAcquisitionFeedMetadataPaginationAndLinks(t *testing.T) {
 			Publisher:   "Publisher",
 			Year:        2025,
 			PageCount:   42,
+			FileSize:    123456,
 			AddedAt:     "2025-01-02T03:04:05Z",
 			UpdatedAt:   "2025-02-03T04:05:06Z",
 			Tags:        []string{"Drama", "Complete"},
@@ -85,7 +86,7 @@ func TestAcquisitionFeedMetadataPaginationAndLinks(t *testing.T) {
 		`rel="next"`,
 		`rel="previous"`,
 		`href="http://example.test/api/opds/cover/comic-1"`,
-		`href="http://example.test/api/opds/download/comic-1" type="application/vnd.comicbook+zip"`,
+		`href="http://example.test/api/opds/download/comic-1/comic.cbz" type="application/vnd.comicbook+zip" length="123456"`,
 		`rel="collection" href="http://example.test/api/opds/series/series-1" type="` + OPDSAcquisitionMIME + `" title="Series One"`,
 		`<dcterms:language>zh-CN</dcterms:language>`,
 		`<dcterms:publisher>Publisher</dcterms:publisher>`,
@@ -196,6 +197,14 @@ func TestOPDSAcquisitionMIMEForFilename(t *testing.T) {
 	}
 }
 
+func TestOPDSDownloadPathIncludesEscapedBasename(t *testing.T) {
+	got := opdsDownloadPath("comic-1", "Series/Comic 01 [中文].cbz")
+	want := "/api/opds/download/comic-1/Comic%2001%20%5B%E4%B8%AD%E6%96%87%5D.cbz"
+	if got != want {
+		t.Fatalf("opdsDownloadPath() = %q, want %q", got, want)
+	}
+}
+
 func assertValidXML(t *testing.T, value string) {
 	t.Helper()
 	decoder := xml.NewDecoder(strings.NewReader(value))

internal/store/comic_query.go

@@ -974,6 +974,7 @@ type OPDSComicRow struct {
 	Publisher    string
 	Year         int
 	PageCount    int
+	FileSize     int64
 	AddedAt      string
 	UpdatedAt    string
 	Tags         []string
@@ -1102,7 +1103,7 @@ func GetOPDSComics(opts OPDSQueryOptions) ([]OPDSComicRow, int, error) {
 	}
 	query := fmt.Sprintf(`
 		SELECT c."id", c."title", c."author", c."description", c."language",
-		       c."genre", c."publisher", c."year", c."pageCount",
+		       c."genre", c."publisher", c."year", c."pageCount", c."fileSize",
 		       c."addedAt", c."updatedAt", c."filename",
 		       COALESCE(cs."id", ''), COALESCE(cs."title", ''),
 		       COALESCE(css."title", ''), COALESCE(csi."displayLabel", '')
@@ -1129,7 +1130,7 @@ func GetOPDSComics(opts OPDSQueryOptions) ([]OPDSComicRow, int, error) {
 
 		if err := rows.Scan(
 			&c.ID, &c.Title, &c.Author, &c.Description, &c.Language,
-			&c.Genre, &c.Publisher, &year, &c.PageCount,
+			&c.Genre, &c.Publisher, &year, &c.PageCount, &c.FileSize,
 			&addedAt, &updatedAt, &c.Filename, &c.SeriesID, &c.SeriesTitle,
 			&c.SectionTitle, &c.DisplayLabel,
 		); err != nil {