feat(web): throttled progress saver with keepalive flush, reader dispatch shell

web/src/App.tsx

@@ -3,12 +3,9 @@ import { AuthProvider, RequireAuth } from "./auth/AuthContext";
 import { ErrorBoundary } from "./components/ErrorBoundary";
 import { Toaster } from "./components/Toaster";
 import Login from "./pages/Login";
+import Reader from "./pages/Reader";
 import Shelf from "./pages/Shelf";
 
-function Placeholder({ name }: { name: string }) {
-  return <div className="p-8 text-zinc-500">{name}:待后续任务落地</div>;
-}
-
 export default function App() {
   return (
     <ErrorBoundary>
@@ -27,7 +24,7 @@ export default function App() {
             path="/book/:id"
             element={
               <RequireAuth>
-                <Placeholder name="阅读器" />
+                <Reader />
               </RequireAuth>
             }
           />

web/src/lib/progress.ts

@@ -0,0 +1,57 @@
+export type ProgressSend = (
+  locator: Record<string, unknown>,
+  percent: number,
+  keepalive: boolean,
+) => Promise<unknown>;
+
+export interface ProgressSaver {
+  report: (locator: Record<string, unknown>, percent: number) => void;
+  flush: () => void;
+}
+
+// spec §8:PUT 节流 5s(leading-edge + 尾部合并);关页兜底走 keepalive fetch
+//(spec 原文 sendBeacon,但 beacon 无法带 Authorization,后端 Bearer-only,语义等价替换)
+export function createProgressSaver(send: ProgressSend, intervalMs = 5000): ProgressSaver {
+  let lastKey = "";
+  let pending: { loc: Record<string, unknown>; pct: number } | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let lastAt = 0;
+
+  function doSend(keepalive: boolean): void {
+    if (!pending) return;
+    const { loc, pct } = pending;
+    pending = null;
+    const key = JSON.stringify([loc, pct]);
+    if (key === lastKey) return;
+    lastKey = key;
+    send(loc, pct, keepalive).catch(() => {
+      if (lastKey === key) lastKey = ""; // 失败允许下次重发同值
+    });
+  }
+
+  return {
+    report(locator, percent) {
+      pending = { loc: locator, pct: percent };
+      if (timer) return; // 已有尾部定时器:只更新挂起值
+      const t = Date.now();
+      if (lastAt === 0 || t - lastAt >= intervalMs) {
+        lastAt = t;
+        doSend(false);
+      } else {
+        timer = setTimeout(() => {
+          timer = null;
+          lastAt = Date.now();
+          doSend(false);
+        }, intervalMs - (t - lastAt));
+      }
+    },
+    flush() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      lastAt = Date.now();
+      doSend(true);
+    },
+  };
+}

web/src/lib/useProgress.ts

@@ -0,0 +1,38 @@
+import { useQueryClient } from "@tanstack/react-query";
+import { useEffect, useMemo } from "react";
+import { api } from "../api/client";
+import type { Book } from "../api/types";
+import { createProgressSaver, type ProgressSaver } from "./progress";
+
+export interface ReaderProps {
+  book: Book;
+  initialLocator?: Record<string, unknown>;
+}
+
+export function useProgressSaver(bookId: number): ProgressSaver {
+  const qc = useQueryClient();
+  const saver = useMemo(
+    () =>
+      createProgressSaver(async (loc, pct, ka) => {
+        await api.putProgress(bookId, loc, pct, ka);
+        if (!ka) qc.invalidateQueries({ queryKey: ["book", bookId] }); // spec §8:只 invalidate 单本
+      }),
+    [bookId, qc],
+  );
+
+  useEffect(() => {
+    const onPageHide = () => saver.flush();
+    const onVis = () => {
+      if (document.visibilityState === "hidden") saver.flush();
+    };
+    globalThis.addEventListener?.("pagehide", onPageHide);
+    document?.addEventListener?.("visibilitychange", onVis);
+    return () => {
+      saver.flush();
+      globalThis.removeEventListener?.("pagehide", onPageHide);
+      document?.removeEventListener?.("visibilitychange", onVis);
+    };
+  }, [saver]);
+
+  return saver;
+}

web/src/pages/Reader.tsx

@@ -0,0 +1,96 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Suspense, type ComponentType, type LazyExoticComponent } from "react";
+import { Link, useNavigate, useParams } from "react-router-dom";
+import { api } from "../api/client";
+import type { Format } from "../api/types";
+import { useAuth } from "../auth/AuthContext";
+import { toast } from "../components/Toaster";
+import { btn } from "../components/ui";
+import type { ReaderProps } from "../lib/useProgress";
+
+// reader 任务逐个往里加:Task 7 cbz → Task 8 txt/md → Task 9 pdf → Task 10 epub
+const READERS: Partial<Record<Format, LazyExoticComponent<ComponentType<ReaderProps>>>> = {};
+
+export default function Reader() {
+  const { id: idStr } = useParams();
+  const id = Number(idStr);
+  const qc = useQueryClient();
+  const nav = useNavigate();
+  const { isAdmin } = useAuth();
+
+  const bookQ = useQuery({ queryKey: ["book", id], queryFn: () => api.getBook(id), enabled: Number.isFinite(id) });
+  const progQ = useQuery({ queryKey: ["progress"], queryFn: api.listProgress });
+  const del = useMutation({
+    mutationFn: () => api.deleteBook(id),
+    onSuccess: () => {
+      toast("ok", "已删除");
+      qc.invalidateQueries({ queryKey: ["books"] });
+      nav("/");
+    },
+    onError: (e) => toast("err", e instanceof Error ? e.message : "删除失败"),
+  });
+
+  const book = bookQ.data;
+  const body = (() => {
+    if (!Number.isFinite(id)) return <Msg text="无效的书 id" />;
+    if (bookQ.isPending) return <Msg text="加载中…" />;
+    if (bookQ.isError)
+      return (
+        <Msg
+          text={"加载失败:" + (bookQ.error instanceof Error ? bookQ.error.message : "")}
+          retry={() => bookQ.refetch()}
+        />
+      );
+    if (!book) return <Msg text="未找到这本书" />;
+    if (book.state === "error") return <Msg text={`文件损坏:${book.error}`} />;
+    if (progQ.isPending) return <Msg text="恢复进度…" />;
+    const R = READERS[book.format];
+    if (!R) return <Msg text={`暂不支持的格式:${book.format}`} />;
+    const row = (progQ.data ?? []).find((r) => r.library_id === book.library_id && r.path === book.path);
+    return <R book={book} initialLocator={row?.locator} />;
+  })();
+
+  return (
+    <div className="flex h-full flex-col">
+      <header className="flex shrink-0 items-center gap-3 border-b border-zinc-800 px-4 py-2 text-sm">
+        <Link to="/" className="text-zinc-400 hover:text-zinc-100">
+          ← 书架
+        </Link>
+        <span className="truncate font-medium">{book?.title ?? "…"}</span>
+        <span className="text-zinc-500">
+          {book?.library ? book.library + " · " : ""}
+          {book?.format}
+          {book ? ` · ${Math.round(book.percent * 100)}%` : ""}
+        </span>
+        {isAdmin && book && (
+          <button
+            className={btn + " ml-auto text-red-300"}
+            onClick={() => {
+              if (confirm(`删除《${book.title}》?磁盘文件一并删除,阅读进度保留`)) del.mutate();
+            }}
+          >
+            删除
+          </button>
+        )}
+      </header>
+      <div className="min-h-0 flex-1">
+        <Suspense fallback={<Msg text="加载阅读器…" />}>{body}</Suspense>
+      </div>
+    </div>
+  );
+}
+
+function Msg({ text, retry }: { text: string; retry?: () => void }) {
+  return (
+    <div className="grid h-full place-items-center p-8 text-center text-zinc-500">
+      <div>
+        <p className="mb-3">{text}</p>
+        {retry && (
+          <button className={btn} onClick={retry}>
+            重试
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

web/test/progress.test.ts

@@ -0,0 +1,42 @@
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { createProgressSaver } from "../src/lib/progress";
+
+type Sent = [Record<string, unknown>, number, boolean];
+
+beforeEach(() => vi.useFakeTimers());
+afterEach(() => vi.useRealTimers());
+
+it("leading 立即发;间隔内多次 report 合并成一次 trailing", () => {
+  const sent: Sent[] = [];
+  const s = createProgressSaver((l, p, ka) => {
+    sent.push([l, p, ka]);
+    return Promise.resolve();
+  });
+  s.report({ page: 1 }, 0.1);
+  expect(sent.length).toBe(1);
+  s.report({ page: 2 }, 0.2);
+  s.report({ page: 3 }, 0.3);
+  expect(sent.length).toBe(1);
+  vi.advanceTimersByTime(4999);
+  expect(sent.length).toBe(1);
+  vi.advanceTimersByTime(1);
+  expect(sent.length).toBe(2);
+  expect(sent[1]).toEqual([{ page: 3 }, 0.3, false]);
+});
+
+it("flush 立刻尾随发送且 keepalive=true;重复值去重;清空挂起", () => {
+  const sent: Sent[] = [];
+  const s = createProgressSaver((l, p, ka) => {
+    sent.push([l, p, ka]);
+    return Promise.resolve();
+  });
+  s.report({ page: 0 }, 0);
+  s.report({ page: 5 }, 0.5);
+  s.flush();
+  expect(sent.length).toBe(2);
+  expect(sent[1]).toEqual([{ page: 5 }, 0.5, true]);
+  s.flush();
+  expect(sent.length).toBe(2);
+  vi.advanceTimersByTime(10_000);
+  expect(sent.length).toBe(2); // 挂起已被 flush 消费,定时器不再补发
+});