优化阅读功能

internal/handler/handler.go

@@ -28,6 +28,18 @@ func Register(r *gin.Engine, cfg *config.Config, log *zap.Logger, svc *service.C
 		api.HEAD("/strm/play/:provider/:file", strmPlayHandler(svc))
 		// 阅读媒体代理：音频流/漫画图片，鉴权靠 HMAC 签名（audio/img 元素带不了 JWT）。
 		api.GET("/reader/media", readerMediaProxyHandler(svc))
+		// 本地书籍内嵌资源（EPUB 图片）：同样靠 HMAC 签名鉴权。
+		api.GET("/reader/local/asset", readerLocalAssetHandler(svc))
+		// 本地有声书音频流：同样靠 HMAC 签名鉴权，服务端处理 Range。
+		api.GET("/reader/local/audio", readerLocalAudioHandler(svc))
+		api.HEAD("/reader/local/audio", readerLocalAudioHandler(svc))
+		// 需要转码的音轨（WMA 等浏览器解不了的格式）：签名鉴权 + 服务端 ffmpeg 转码。
+		api.GET("/reader/audio/transcode", readerAudioTranscodeHandler(svc))
+		api.HEAD("/reader/audio/transcode", readerAudioTranscodeHandler(svc))
+		// 阅读书源浏览器页面与资源代理：java.startBrowserAwait 承载的页面填进
+		// <iframe src>，同样带不了 JWT，鉴权靠绑定待办 ID 的 HMAC 签名。
+		api.GET("/reader/browser/page", readerBrowserPageHandler(svc))
+		api.GET("/reader/browser/asset", readerBrowserAssetHandler(svc))
 		// 115 中继/CloudDrive 授权回跳（authorization_id 会话 + 共享密钥校验）
 		api.POST("/strm/oauth/callback", strm115OAuthCallbackHandler(svc))
 		api.GET("/strm/oauth/callback", strm115OAuthCallbackHandler(svc))

internal/handler/reader_browser_test.go

@@ -0,0 +1,247 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// 书源宿主浏览器的 HTTP 层测试：轮询待办 → 承载页面 → 回传 DOM。
+//
+// 这条链路对应真实书源的「切换线路」「用户后台」：
+// java.startBrowserAwait 会阻塞在 POST /sources/:id/login 上，
+// 前端必须能从 /reader/browser/pending 拿到页面，再把 DOM POST 回去。
+
+// browserHandlerSource 构造一个用 startBrowserAwait 切换线路的书源。
+func browserHandlerSource(sourceURL string) string {
+	loginJS := `function switchLine() {
+  let html = '<!DOCTYPE html><html><head></head><body><span id="serverValue">线路甲</span></body></html>';
+  let body = java.startBrowserAwait('data:text/html;base64,' + java.base64Encode(html), '线路设置', false).body();
+  let m = body.match(/id="serverValue"\s*>\s*([^<]*?)\s*<\/span>/);
+  source.setVariable(JSON.stringify({线路: m ? m[1] : ''}));
+}`
+	src := map[string]any{
+		"bookSourceUrl":  sourceURL,
+		"bookSourceName": "浏览器面板源",
+		"loginUrl":       loginJS,
+		"loginUi":        `[{"name":"切换线路","type":"button","action":"switchLine()"}]`,
+	}
+	out, _ := json.Marshal(src)
+	return string(out)
+}
+
+// registerBrowserRoutesForTest 挂载阅读路由 + 承载页面/资源代理（跳过鉴权）。
+// 生产环境里后两个是公开路由（iframe 带不了 JWT），鉴权靠 HMAC 签名。
+func registerBrowserRoutesForTest(cfg *service.Container) *gin.Engine {
+	r := registerReaderRoutesForTest(cfg)
+	r.GET("/api/reader/browser/page", readerBrowserPageHandler(cfg))
+	r.GET("/api/reader/browser/asset", readerBrowserAssetHandler(cfg))
+	return r
+}
+
+func TestReaderBrowserPanelRoutes(t *testing.T) {
+	container := newReaderHandlerContainer(t)
+	router := registerBrowserRoutesForTest(container)
+
+	// 导入书源
+	body, _ := json.Marshal(map[string]string{"text": browserHandlerSource("https://panel.example.com")})
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/reader/sources/import", strings.NewReader(string(body)))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("导入书源 status=%d body=%s", w.Code, w.Body.String())
+	}
+	w = httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/api/reader/sources", nil))
+	var list struct {
+		Sources []struct {
+			ID string `json:"id"`
+		} `json:"sources"`
+	}
+	_ = json.Unmarshal(w.Body.Bytes(), &list)
+	if len(list.Sources) != 1 {
+		t.Fatalf("应导入 1 个书源: %s", w.Body.String())
+	}
+	sourceID := list.Sources[0].ID
+
+	// 执行切换线路：这个请求会阻塞等待用户操作，放到后台跑
+	actionDone := make(chan *httptest.ResponseRecorder, 1)
+	go func() {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodPost, "/api/reader/sources/"+sourceID+"/login",
+			strings.NewReader(`{"action":"switchLine()","fields":{}}`))
+		req.Header.Set("Content-Type", "application/json")
+		router.ServeHTTP(rec, req)
+		actionDone <- rec
+	}()
+
+	// 轮询待办页面
+	var page struct {
+		ID       string `json:"id"`
+		Title    string `json:"title"`
+		Mode     string `json:"mode"`
+		PageURL  string `json:"page_url"`
+		SourceID string `json:"source_id"`
+	}
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		if time.Now().After(deadline) {
+			t.Fatal("等待超时：未出现待办页面")
+		}
+		w = httptest.NewRecorder()
+		router.ServeHTTP(w, httptest.NewRequest(http.MethodGet,
+			"/api/reader/browser/pending?source_id="+sourceID, nil))
+		if w.Code != http.StatusOK {
+			t.Fatalf("轮询 status=%d body=%s", w.Code, w.Body.String())
+		}
+		var pending struct {
+			Pages []json.RawMessage `json:"pages"`
+		}
+		if err := json.Unmarshal(w.Body.Bytes(), &pending); err != nil {
+			t.Fatalf("待办返回不是 JSON: %s", w.Body.String())
+		}
+		if len(pending.Pages) > 0 {
+			if err := json.Unmarshal(pending.Pages[0], &page); err != nil {
+				t.Fatal(err)
+			}
+			break
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	if page.Mode != "wait" || page.Title != "线路设置" {
+		t.Fatalf("待办描述异常: %+v", page)
+	}
+	if page.SourceID != sourceID {
+		t.Fatalf("待办应带书源 ID: %+v", page)
+	}
+
+	// 承载页面：签名正确应返回 HTML，签名错误应 403
+	w = httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, page.PageURL, nil))
+	if w.Code != http.StatusOK {
+		t.Fatalf("承载页面 status=%d body=%s", w.Code, w.Body.String())
+	}
+	if !strings.Contains(w.Body.String(), `id="serverValue"`) {
+		t.Fatalf("承载页面内容异常: %s", w.Body.String())
+	}
+	// 服务端注入的 DOM 回传脚本必须在（父窗口靠它取回用户操作后的页面）
+	if !strings.Contains(w.Body.String(), "data-mebox-browser-bridge") {
+		t.Fatalf("承载页面缺少 DOM 回传脚本: %s", w.Body.String())
+	}
+	w = httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/api/reader/browser/page?id="+page.ID+"&s=forged", nil))
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("伪造签名应 403，实际 %d", w.Code)
+	}
+
+	// 回传用户操作后的 DOM（模拟点了 √）
+	result, _ := json.Marshal(map[string]any{
+		"id":   page.ID,
+		"body": `<html><body><span id="serverValue">线路乙</span></body></html>`,
+	})
+	w = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodPost, "/api/reader/browser/result", strings.NewReader(string(result)))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("回传结果 status=%d body=%s", w.Code, w.Body.String())
+	}
+
+	// 阻塞的登录动作应被放行
+	select {
+	case rec := <-actionDone:
+		if rec.Code != http.StatusOK {
+			t.Fatalf("登录动作 status=%d body=%s", rec.Code, rec.Body.String())
+		}
+		var res struct {
+			OK bool `json:"ok"`
+		}
+		_ = json.Unmarshal(rec.Body.Bytes(), &res)
+		if !res.OK {
+			t.Fatalf("动作未成功: %s", rec.Body.String())
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("回传后阻塞未解除")
+	}
+
+	// 线路应已写进源变量
+	w = httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/api/reader/sources/"+sourceID+"/login", nil))
+	var info struct {
+		Variable string `json:"variable"`
+	}
+	_ = json.Unmarshal(w.Body.Bytes(), &info)
+	if !strings.Contains(info.Variable, "线路乙") {
+		t.Fatalf("线路未写入源变量: %q", info.Variable)
+	}
+
+	// 完成后待办清空
+	w = httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet,
+		"/api/reader/browser/pending?source_id="+sourceID, nil))
+	var after struct {
+		Pages []json.RawMessage `json:"pages"`
+	}
+	_ = json.Unmarshal(w.Body.Bytes(), &after)
+	if len(after.Pages) != 0 {
+		t.Fatalf("完成后待办未清理: %s", w.Body.String())
+	}
+}
+
+func TestReaderBrowserResultRejectsUnknownPage(t *testing.T) {
+	container := newReaderHandlerContainer(t)
+	router := registerBrowserRoutesForTest(container)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/reader/browser/result",
+		strings.NewReader(`{"id":"not-a-real-page","body":"x"}`))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("未知待办应 400，实际 %d body=%s", w.Code, w.Body.String())
+	}
+}
+
+func TestReaderBrowserResultRequiresID(t *testing.T) {
+	container := newReaderHandlerContainer(t)
+	router := registerBrowserRoutesForTest(container)
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/reader/browser/result", strings.NewReader(`{}`))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("缺少 id 应 400，实际 %d", w.Code)
+	}
+}
+
+// TestReaderBrowserPageBadQuery 承载地址参数缺失/非法时不应 500。
+func TestReaderBrowserPageBadQuery(t *testing.T) {
+	container := newReaderHandlerContainer(t)
+	router := registerBrowserRoutesForTest(container)
+
+	for _, target := range []string{"/api/reader/browser/page", "/api/reader/browser/page?id=x",
+		"/api/reader/browser/asset", "/api/reader/browser/asset?id=x&u=!!!&s=y"} {
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, target, nil))
+		if w.Code != http.StatusForbidden {
+			t.Fatalf("%s 应 403，实际 %d", target, w.Code)
+		}
+	}
+	// 合法 base64 但不匹配的签名
+	w := httptest.NewRecorder()
+	q := url.Values{"id": {"x"}, "u": {"aHR0cHM6Ly9leGFtcGxlLmNvbS8"}, "s": {"deadbeef"}}
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/api/reader/browser/asset?"+q.Encode(), nil))
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("签名不匹配应 403，实际 %d", w.Code)
+	}
+}

internal/handler/reader_local_audio_test.go

@@ -0,0 +1,174 @@
+package handler
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+// TestReaderLocalAudioStream 本地有声书音频流端点：
+// 签名鉴权 + Range 透传（播放器拖进度靠它）。
+func TestReaderLocalAudioStream(t *testing.T) {
+	container := newReaderHandlerContainer(t)
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.GET("/api/reader/local/audio", readerLocalAudioHandler(container))
+	router.HEAD("/api/reader/local/audio", readerLocalAudioHandler(container))
+
+	payload := []byte("0123456789abcdefghij")
+	path := filepath.Join(t.TempDir(), "track.mp3")
+	if err := os.WriteFile(path, payload, 0o640); err != nil {
+		t.Fatal(err)
+	}
+	signed := container.Reader.LocalAudioURL("book-1", path)
+
+	// 全量拉取
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, signed, nil))
+	if w.Code != http.StatusOK {
+		t.Fatalf("全量拉取 status=%d body=%s", w.Code, w.Body.String())
+	}
+	if w.Body.String() != string(payload) {
+		t.Fatalf("全量拉取 body=%q", w.Body.String())
+	}
+
+	// Range 请求要能拖进度
+	w = httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, signed, nil)
+	req.Header.Set("Range", "bytes=2-5")
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusPartialContent {
+		t.Fatalf("Range 请求 status=%d", w.Code)
+	}
+	if w.Body.String() != "2345" {
+		t.Fatalf("Range 请求 body=%q", w.Body.String())
+	}
+
+	// 篡改签名应被拒绝
+	w = httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, signed+"x", nil))
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("坏签名 status=%d，期望 403", w.Code)
+	}
+
+	// 文件不存在 → 404（而不是 500）
+	missing := container.Reader.LocalAudioURL("book-1", filepath.Join(t.TempDir(), "nope.mp3"))
+	w = httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, missing, nil))
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("缺失文件 status=%d，期望 404", w.Code)
+	}
+}
+
+// TestReaderAudioTranscodeRoute 转码端点：签名鉴权，命中缓存后按 Range 下发。
+// 用预置的缓存文件代替真实转码，避免测试依赖 ffmpeg。
+func TestReaderAudioTranscodeRoute(t *testing.T) {
+	container := newReaderHandlerContainer(t)
+	container.Cfg.App.DataDir = t.TempDir() // 转码缓存落在临时目录，别写进仓库
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.GET("/api/reader/audio/transcode", readerAudioTranscodeHandler(container))
+	router.HEAD("/api/reader/audio/transcode", readerAudioTranscodeHandler(container))
+
+	const bookID = "book-1"
+	source := `D:\media\斗破苍穹\001.wma`
+	payload := []byte("ID3FAKEMP3PAYLOAD0123456789")
+
+	cachePath, err := container.Reader.AudioTranscodeCachePath(bookID, source)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Dir(cachePath), 0o750); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(cachePath, payload, 0o640); err != nil {
+		t.Fatal(err)
+	}
+
+	signed := container.Reader.AudioTranscodeURL(bookID, source)
+
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, signed, nil))
+	if w.Code != http.StatusOK {
+		t.Fatalf("全量拉取 status=%d body=%s", w.Code, w.Body.String())
+	}
+	if w.Body.String() != string(payload) {
+		t.Fatalf("全量拉取 body=%q", w.Body.String())
+	}
+
+	// 拖进度靠 Range
+	w = httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, signed, nil)
+	req.Header.Set("Range", "bytes=3-7")
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusPartialContent {
+		t.Fatalf("Range 请求 status=%d", w.Code)
+	}
+	if w.Body.String() != "FAKEM" {
+		t.Fatalf("Range 请求 body=%q", w.Body.String())
+	}
+
+	// 篡改签名应被拒绝
+	w = httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, signed+"x", nil))
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("坏签名 status=%d，期望 403", w.Code)
+	}
+
+	// 换一本书（签名不匹配）同样拒绝
+	forged := strings.Replace(signed, "b=book-1", "b=book-2", 1)
+	w = httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, forged, nil))
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("换书后 status=%d，期望 403", w.Code)
+	}
+}
+
+// TestReaderAudioTranscodeRouteWithoutFFmpeg 没装 ffmpeg 且无缓存时返回明确错误，
+// 而不是空响应（前端据此提示用户去装 ffmpeg）。
+func TestReaderAudioTranscodeRouteWithoutFFmpeg(t *testing.T) {
+	container := newReaderHandlerContainer(t)
+	container.Cfg.App.DataDir = t.TempDir()
+	container.Cfg.App.FFmpegPath = filepath.Join(t.TempDir(), "definitely-missing-ffmpeg")
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.GET("/api/reader/audio/transcode", readerAudioTranscodeHandler(container))
+
+	signed := container.Reader.AudioTranscodeURL("book-1", `D:\media\001.wma`)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, signed, nil))
+	if w.Code != http.StatusBadGateway {
+		t.Fatalf("status=%d，期望 502", w.Code)
+	}
+	if !strings.Contains(w.Body.String(), "ffmpeg") {
+		t.Fatalf("错误正文应提到 ffmpeg: %q", w.Body.String())
+	}
+}
+
+// TestReaderLocalAudioRejectsOtherBook 换一本书的签名不通用：防止拿到别人的音频地址。
+func TestReaderLocalAudioRejectsOtherBook(t *testing.T) {
+	container := newReaderHandlerContainer(t)
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.GET("/api/reader/local/audio", readerLocalAudioHandler(container))
+
+	path := filepath.Join(t.TempDir(), "track.mp3")
+	if err := os.WriteFile(path, []byte("x"), 0o640); err != nil {
+		t.Fatal(err)
+	}
+	signed := container.Reader.LocalAudioURL("book-1", path)
+	forged := strings.Replace(signed, "b=book-1", "b=book-2", 1)
+	if forged == signed {
+		t.Fatal("测试用例未改写 book 参数")
+	}
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, forged, nil))
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("换书后签名应失效，status=%d", w.Code)
+	}
+}

internal/handler/reader_routes.go

@@ -4,6 +4,7 @@ package handler
 import (
 	"io"
 	"net/http"
+	"os"
 	"strconv"
 	"strings"
 
@@ -31,6 +32,13 @@ func registerReaderRoutes(authed *gin.RouterGroup, svc *service.Container) {
 	g.PUT("/sources/:id/variable", readerSetSourceVariableHandler(svc))
 	g.PUT("/sources/:id/login-info", readerSetSourceLoginInfoHandler(svc))
 
+	// 书源 JS 的宿主浏览器（java.startBrowser / startBrowserAwait）：
+	// 前端轮询待办 → 在 iframe 里承载页面 → 用户点 √ 回传 DOM。
+	g.GET("/browser/pending", readerBrowserPendingHandler(svc))
+	g.POST("/browser/result", readerBrowserResultHandler(svc))
+	// 页面内的 fetch/XHR 经此转发（iframe 是不透明源，请求带不上书源 Cookie）
+	g.POST("/browser/xhr", readerBrowserXHRHandler(svc))
+
 	// 搜索（多源聚合）
 	g.POST("/search", readerSearchHandler(svc))
 
@@ -42,8 +50,14 @@ func registerReaderRoutes(authed *gin.RouterGroup, svc *service.Container) {
 	// 书架
 	g.GET("/books", readerListBooksHandler(svc))
 	g.POST("/books", readerAddBookHandler(svc))
+	// 本地书籍（TXT / EPUB 上传导入）
+	g.POST("/local/books", readerImportLocalBookHandler(svc))
+	// 服务器已有文件/目录导入：原地引用不复制，仅管理员（会读取允许根目录内的文件）
+	g.POST("/local/books/from-path", middleware.AdminRequired(), readerImportLocalBookFromPathHandler(svc))
+	g.POST("/local/audiobooks", middleware.AdminRequired(), readerImportLocalAudioDirHandler(svc))
 	g.DELETE("/books/:id", readerRemoveBookHandler(svc))
 	g.PUT("/books/:id/progress", readerSaveProgressHandler(svc))
+	g.PUT("/books/:id/audio-config", readerSaveAudioConfigHandler(svc))
 	g.GET("/books/:id/chapters", readerListChaptersHandler(svc))
 	g.POST("/books/:id/chapters", readerReplaceChaptersHandler(svc))
 	g.GET("/books/:id/content", readerBookContentHandler(svc))
@@ -131,7 +145,8 @@ func readerDebugSourceHandler(svc *service.Container) gin.HandlerFunc {
 
 func readerSourceLoginInfoHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		info, err := svc.Reader.GetSourceLogin(c.Request.Context(), c.Param("id"))
+		userID := c.GetString(middleware.CtxUserID)
+		info, err := svc.Reader.GetSourceLogin(c.Request.Context(), userID, c.Param("id"))
 		if err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
@@ -151,7 +166,8 @@ func readerSourceLoginActionHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
-		res, err := svc.Reader.RunLoginAction(c.Request.Context(), c.Param("id"), body.Action, body.Fields)
+		userID := c.GetString(middleware.CtxUserID)
+		res, err := svc.Reader.RunLoginAction(c.Request.Context(), userID, c.Param("id"), body.Action, body.Fields)
 		if err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
@@ -160,6 +176,103 @@ func readerSourceLoginActionHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }
 
+// readerBrowserPendingHandler 前端轮询：该用户在某书源下待用户完成的页面。
+// 书源的 java.startBrowserAwait 会阻塞在服务端，前端据此把页面呈现出来。
+func readerBrowserPendingHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		userID := c.GetString(middleware.CtxUserID)
+		pages := svc.Reader.PendingBrowserPages(userID, c.Query("source_id"))
+		c.JSON(http.StatusOK, gin.H{"pages": pages})
+	}
+}
+
+// readerBrowserResultHandler 用户完成页面后回传 DOM（或取消），解除服务端阻塞。
+func readerBrowserResultHandler(svc *service.Container) gin.HandlerFunc {
+	var body struct {
+		ID        string `json:"id" binding:"required"`
+		Body      string `json:"body"`
+		URL       string `json:"url"`
+		Cancelled bool   `json:"cancelled"`
+	}
+	return func(c *gin.Context) {
+		if err := c.ShouldBindJSON(&body); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		userID := c.GetString(middleware.CtxUserID)
+		if err := svc.Reader.ResolveBrowser(body.ID, userID, body.Body, body.URL, body.Cancelled); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"ok": true})
+	}
+}
+
+// readerBrowserXHRHandler 转发承载页面内的接口请求。
+//
+// 页面在 iframe 里是不透明源，自己的 XHR 既带不上书源 Cookie 也会被 CORS 拦，
+// 所以由父窗口（持 JWT）把请求转交到这里，服务端补上书源凭据再发。
+func readerBrowserXHRHandler(svc *service.Container) gin.HandlerFunc {
+	var body struct {
+		ID      string            `json:"id" binding:"required"`
+		URL     string            `json:"url" binding:"required"`
+		Method  string            `json:"method"`
+		Headers map[string]string `json:"headers"`
+		Body    string            `json:"body"`
+	}
+	return func(c *gin.Context) {
+		if err := c.ShouldBindJSON(&body); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		res, err := svc.Reader.ProxyBrowserXHR(
+			c.Request.Context(), body.ID, body.Method, body.URL, body.Headers, body.Body)
+		if err != nil {
+			// 交给页面自己处理失败，别把 4xx 泄成框架错误
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, res)
+	}
+}
+
+// readerBrowserPageHandler 承载待办页面本体。//
+// 鉴权走 HMAC 签名而非 JWT：这个地址要填进 <iframe src>，而 iframe 的请求
+// 带不上 Authorization 头。签名绑定待办 ID，链接随待办一起过期。
+func readerBrowserPageHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		snap, err := svc.Reader.VerifyBrowserPage(c.Query("id"), c.Query("s"))
+		if err != nil {
+			c.String(http.StatusForbidden, "%s", err.Error())
+			return
+		}
+		c.Header("Cache-Control", "no-store")
+		c.Data(http.StatusOK, "text/html; charset=utf-8", []byte(snap.HTML))
+	}
+}
+
+// readerBrowserAssetHandler 页面资源/表单/站内链接的同源代理。
+// 服务端补上书源 Cookie 与请求头，使「用户后台」这类页面在 iframe 里保持登录态。
+func readerBrowserAssetHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		target, sourceURL, err := svc.Reader.VerifyBrowserAsset(c.Query("id"), c.Query("u"), c.Query("s"))
+		if err != nil {
+			c.String(http.StatusForbidden, "%s", err.Error())
+			return
+		}
+		contentType, status, data, err := svc.Reader.FetchBrowserAsset(c.Request.Context(), sourceURL, target)
+		if err != nil {
+			c.String(http.StatusBadGateway, "资源加载失败: %s", err.Error())
+			return
+		}
+		if strings.Contains(strings.ToLower(contentType), "text/css") {
+			data = []byte(svc.Reader.RewriteBrowserCSS(string(data), target, c.Query("id")))
+		}
+		c.Header("Cache-Control", "no-store")
+		c.Data(status, contentType, data)
+	}
+}
+
 func readerSourceLogoutHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		if err := svc.Reader.ClearSourceLogin(c.Request.Context(), c.Param("id")); err != nil {
@@ -238,9 +351,10 @@ func readerBookInfoHandler(svc *service.Container) gin.HandlerFunc {
 
 func readerTocHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
+		userID := c.GetString(middleware.CtxUserID)
 		chapters, err := svc.Reader.GetToc(
 			c.Request.Context(),
-			c.Query("source_id"), c.Query("source_url"), c.Query("book_url"), c.Query("toc_url"),
+			userID, c.Query("source_id"), c.Query("source_url"), c.Query("book_url"), c.Query("toc_url"),
 		)
 		if err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
@@ -294,6 +408,96 @@ func readerAddBookHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
 		}
+		// 后台补目录缓存，让书架能显示未读章数；失败不影响加入书架本身。
+		svc.Reader.WarmUpBookChaptersAsync(c.Request.Context(), userID, book)
+		c.JSON(http.StatusOK, book)
+	}
+}
+
+// readerImportLocalBookHandler 上传本地书籍（TXT / EPUB）并加入书架。
+// 正文落盘到 data/reader/local，目录切分后与网络书籍共用阅读器链路。
+func readerImportLocalBookHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 先卡住请求体大小，避免超大文件把内存打满（多给 1MB 放 multipart 头）
+		c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, int64(reader.LocalBookMaxBytes)+(1<<20))
+		header, err := c.FormFile("file")
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "缺少上传文件（表单字段 file），或文件超过大小上限"})
+			return
+		}
+		f, err := header.Open()
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "读取上传文件失败: " + err.Error()})
+			return
+		}
+		defer f.Close()
+		data, err := io.ReadAll(io.LimitReader(f, int64(reader.LocalBookMaxBytes)+1))
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "读取上传文件失败: " + err.Error()})
+			return
+		}
+		if len(data) > reader.LocalBookMaxBytes {
+			c.JSON(http.StatusRequestEntityTooLarge, gin.H{"error": "文件超过大小上限"})
+			return
+		}
+		userID := c.GetString(middleware.CtxUserID)
+		book, err := svc.Reader.ImportLocalBook(c.Request.Context(), userID, header.Filename, data)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, book)
+	}
+}
+
+// readerImportLocalBookFromPathHandler 从服务器已有文件导入书籍（TXT / EPUB），原地引用。
+// 仅管理员：会读取服务器上允许根目录内的任意文件。
+func readerImportLocalBookFromPathHandler(svc *service.Container) gin.HandlerFunc {
+	var body struct {
+		Path string `json:"path" binding:"required"`
+	}
+	return func(c *gin.Context) {
+		if err := c.ShouldBindJSON(&body); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		abs, err := svc.FileManager.ResolvePath(body.Path)
+		if err != nil {
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+			return
+		}
+		userID := c.GetString(middleware.CtxUserID)
+		book, err := svc.Reader.ImportLocalBookFromPath(c.Request.Context(), userID, abs)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, book)
+	}
+}
+
+// readerImportLocalAudioDirHandler 把一个服务器目录导入为一本有声书，原地引用。
+// 仅管理员；目录下的音频文件与 .strm 播放指针按相对路径排序成为章节。
+func readerImportLocalAudioDirHandler(svc *service.Container) gin.HandlerFunc {
+	var body struct {
+		Path string `json:"path" binding:"required"`
+	}
+	return func(c *gin.Context) {
+		if err := c.ShouldBindJSON(&body); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		abs, err := svc.FileManager.ResolvePath(body.Path)
+		if err != nil {
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+			return
+		}
+		userID := c.GetString(middleware.CtxUserID)
+		book, err := svc.Reader.ImportLocalAudioDir(c.Request.Context(), userID, abs)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
 		c.JSON(http.StatusOK, book)
 	}
 }
@@ -329,6 +533,27 @@ func readerSaveProgressHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }
 
+// readerSaveAudioConfigHandler 保存听书片头/片尾跳过秒数（0 为不跳过）。
+func readerSaveAudioConfigHandler(svc *service.Container) gin.HandlerFunc {
+	var body struct {
+		OpenCredits  int `json:"open_credits"`
+		CloseCredits int `json:"close_credits"`
+	}
+	return func(c *gin.Context) {
+		if err := c.ShouldBindJSON(&body); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		userID := c.GetString(middleware.CtxUserID)
+		if err := svc.Reader.SaveAudioConfig(
+			c.Request.Context(), userID, c.Param("id"), body.OpenCredits, body.CloseCredits); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"ok": true})
+	}
+}
+
 func readerListChaptersHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		chapters, err := svc.Reader.ListChapters(c.Request.Context(), c.Param("id"))
@@ -460,6 +685,77 @@ func readerMediaProxyHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }
 
+// readerLocalAssetHandler 本地书籍内嵌资源（EPUB 图片等）：
+// 鉴权走 HMAC 签名（<img src> 带不上 JWT），与 /reader/media 同一套做法。
+func readerLocalAssetHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		bookID := c.Query("b")
+		entry, err := svc.Reader.VerifyLocalAssetURL(bookID, c.Query("p"), c.Query("s"))
+		if err != nil {
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+			return
+		}
+		data, contentType, err := svc.Reader.ReadLocalAsset(c.Request.Context(), bookID, entry)
+		if err != nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+			return
+		}
+		// 同一本书的图片不会变，可长缓存
+		c.Header("Cache-Control", "private, max-age=604800")
+		c.Data(http.StatusOK, contentType, data)
+	}
+}
+
+// readerAudioTranscodeHandler 需要转码的有声书音轨：签名鉴权（<audio src> 带不上 JWT），
+// 首次请求跑 ffmpeg 转成 mp3 落缓存，之后按 Range 下发，播放器可以拖动进度。
+func readerAudioTranscodeHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		bookID := c.Query("b")
+		source, err := svc.Reader.VerifyAudioTranscodeURL(bookID, c.Query("u"), c.Query("s"))
+		if err != nil {
+			c.String(http.StatusForbidden, "%s", err.Error())
+			return
+		}
+		path, err := svc.Reader.EnsureTranscodedAudio(c.Request.Context(), bookID, source)
+		if err != nil {
+			c.String(http.StatusBadGateway, "%s", err.Error())
+			return
+		}
+		f, err := os.Open(path) // #nosec G304 -- 路径由签名校验 + 缓存目录哈希生成
+		if err != nil {
+			c.String(http.StatusNotFound, "转码结果已丢失")
+			return
+		}
+		defer f.Close()
+		info, err := f.Stat()
+		if err != nil {
+			c.String(http.StatusNotFound, "转码结果不可用")
+			return
+		}
+		c.Header("Cache-Control", "private, max-age=604800")
+		http.ServeContent(c.Writer, c.Request, info.Name(), info.ModTime(), f)
+	}
+}
+
+// readerLocalAudioHandler 本地有声书音频流：签名鉴权（<audio src> 带不上 JWT），
+// 交给 http.ServeContent 处理 Range，播放器才能拖动进度。
+func readerLocalAudioHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		path, err := svc.Reader.VerifyLocalAudioURL(c.Query("b"), c.Query("p"), c.Query("s"))
+		if err != nil {
+			c.String(http.StatusForbidden, "%s", err.Error())
+			return
+		}
+		f, info, err := svc.Reader.OpenLocalAudio(path)
+		if err != nil {
+			c.String(http.StatusNotFound, "%s", err.Error())
+			return
+		}
+		defer f.Close()
+		http.ServeContent(c.Writer, c.Request, info.Name(), info.ModTime(), f)
+	}
+}
+
 // readerBookContentHandler 书架维度正文（服务端应用替换净化规则）。
 func readerBookContentHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {