(
+ () => ({
+ user: meQ.data ?? null,
+ isAdmin: meQ.data?.role === "admin",
+ ready: !token || !meQ.isPending,
+ login: async (u, p) => {
+ const r = await api.login(u, p);
+ setToken(r.token);
+ setTok(r.token);
+ await qc.invalidateQueries({ queryKey: ["me"] });
+ },
+ logout: () => {
+ setToken(null);
+ setTok(null);
+ qc.clear();
+ },
+ }),
+ [meQ.data, meQ.isPending, meQ.isError, token, qc],
+ );
+
+ return {children};
+}
+
+export function useAuth(): AuthState {
+ const v = useContext(Ctx);
+ if (!v) throw new Error("useAuth 必须在 AuthProvider 内使用");
+ return v;
+}
+
+export function RequireAuth({ children }: { children: ReactNode }) {
+ const { user, ready } = useAuth();
+ const loc = useLocation();
+ if (!getToken()) return ;
+ if (!ready || !user) return 加载中…
;
+ return <>{children};
+}
+
+export function RequireAdmin({ children }: { children: ReactNode }) {
+ const { isAdmin } = useAuth();
+ return isAdmin ? <>{children} : ;
+}
+```
+
+- [ ] **Step 6: 实现 `src/pages/Login.tsx`**
+
+```tsx
+import { useState, type FormEvent } from "react";
+import { Navigate, useLocation, useNavigate } from "react-router-dom";
+import { useAuth } from "../auth/AuthContext";
+import { toast } from "../components/Toaster";
+import { btnPrimary, card, input } from "../components/ui";
+
+export default function Login() {
+ const { login, user } = useAuth();
+ const loc = useLocation() as { state?: { from?: string } };
+ const nav = useNavigate();
+ const [u, setU] = useState("");
+ const [p, setP] = useState("");
+ const [busy, setBusy] = useState(false);
+
+ if (user) return ;
+
+ async function submit(e: FormEvent) {
+ e.preventDefault();
+ setBusy(true);
+ try {
+ await login(u, p);
+ nav("/", { replace: true });
+ } catch (err) {
+ toast("err", err instanceof Error ? err.message : "登录失败");
+ } finally {
+ setBusy(false);
+ }
+ }
+
+ return (
+
+
+
+ );
+}
+```
+
+- [ ] **Step 7: 替换 `src/main.tsx` 与 `src/App.tsx`**
+
+`src/main.tsx`:
+
+```tsx
+import { QueryClientProvider } from "@tanstack/react-query";
+import { BrowserRouter } from "react-router-dom";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+import { queryClient } from "./lib/qc";
+import "./index.css";
+
+createRoot(document.getElementById("root")!).render(
+
+
+
+
+ ,
+);
+```
+
+`src/App.tsx`(Task 5/6/11 会再整文件替换):
+
+```tsx
+import { Navigate, Route, Routes } from "react-router-dom";
+import { AuthProvider, RequireAuth } from "./auth/AuthContext";
+import { ErrorBoundary } from "./components/ErrorBoundary";
+import { Toaster } from "./components/Toaster";
+import Login from "./pages/Login";
+
+function Placeholder({ name }: { name: string }) {
+ return {name}:待后续任务落地
;
+}
+
+export default function App() {
+ return (
+
+
+
+ } />
+
+
+
+ }
+ />
+ } />
+
+
+
+
+ );
+}
+```
+
+- [ ] **Step 8: 门槛 + 人工冒烟(可选)**
+
+Run: `cd web && npm run check` → 全绿。
+人工(有环境时):起 dev 后端 + `npm run dev`,浏览器访问 :5173,未登录应跳 `/login`,错误密码出红色 toast。
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add web && git commit -m "feat(web): auth context, login page, route guards, toast/error shell"
+```
+
+---
+
+### Task 4: 鉴权图片通道 + 封面组件 + 目录分组(纯逻辑先行)
+
+**Files:**
+- Create: `web/src/lib/authImage.ts`、`web/src/lib/group.ts`、`web/src/components/Cover.tsx`
+- Test: `web/test/authImage.test.ts`、`web/test/group.test.ts`
+
+**Interfaces:**
+- Consumes: Task 2 `apiRaw`;Task 3 `btn`
+- Produces:
+ - `fetchObjectUrl(url: string, signal?: AbortSignal): Promise` — 带鉴权取图 → objectURL;LRU(600)缓存;失败自动出缓存可重试;`__resetImageCache()` 供测试
+ - `useAuthedImage(url: string | undefined): { src: string; failed: boolean; retry: () => void }`(`Cover.tsx` 内导出)
+ - `Cover({ book, className })`(3:4 占位、失败显示重试按钮,spec §9)
+ - `group.ts`:`interface Group { dir: string; books: Book[] }`;`groupByDir(books: Book[]): Group[]`
+
+- [ ] **Step 1: 写失败测试**
+
+`test/group.test.ts`:
+
+```ts
+import { expect, it } from "vitest";
+import { groupByDir } from "../src/lib/group";
+import type { Book } from "../src/api/types";
+
+let seq = 1;
+const mk = (path: string): Book => ({
+ id: seq++, library_id: 1, path, title: path, format: "cbz", size: 1, mtime: 1, pages: 0,
+ state: "ready", error: "", added_at: "", percent: 0, cover_url: "/api/books/0/cover",
+});
+
+it("根目录组为空串且排最前;目录组按字典序;组内保持输入顺序", () => {
+ const gs = groupByDir([mk("b.cbz"), mk("z/1.cbz"), mk("a/2.cbz"), mk("a/sub/3.cbz")]);
+ expect(gs.map((g) => g.dir)).toEqual(["", "a", "a/sub", "z"]);
+ expect(gs[0].books.map((x) => x.path)).toEqual(["b.cbz"]);
+ expect(gs[1].books.map((x) => x.path)).toEqual(["a/2.cbz"]);
+});
+
+it("空输入出空数组", () => {
+ expect(groupByDir([])).toEqual([]);
+});
+```
+
+`test/authImage.test.ts`:
+
+```ts
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { setToken } from "../src/api/client";
+import { __resetImageCache, fetchObjectUrl } from "../src/lib/authImage";
+
+beforeEach(() => {
+ __resetImageCache();
+ setToken("T");
+ (URL as any).createObjectURL = vi.fn(() => "blob:gen");
+});
+afterEach(() => vi.unstubAllGlobals());
+
+it("blob → objectURL;同 URL 只发一次请求", async () => {
+ const f = vi.fn(async (_url: any, init: any) => {
+ expect(init.headers.Authorization).toBe("Bearer T");
+ return new Response(new Blob(["img"]), { status: 200 });
+ });
+ vi.stubGlobal("fetch", f);
+ expect(await fetchObjectUrl("/api/books/1/cover?v=h")).toBe("blob:gen");
+ expect(await fetchObjectUrl("/api/books/1/cover?v=h")).toBe("blob:gen");
+ expect(f).toHaveBeenCalledTimes(1);
+});
+
+it("失败不入缓存,重试重新请求", async () => {
+ let n = 0;
+ vi.stubGlobal("fetch", async () => {
+ n++;
+ return n === 1 ? new Response("x", { status: 500 }) : new Response(new Blob(["img"]), { status: 200 });
+ });
+ await expect(fetchObjectUrl("/api/books/2/pages/0?v=h")).rejects.toThrow();
+ expect(await fetchObjectUrl("/api/books/2/pages/0?v=h")).toBe("blob:gen");
+ expect(n).toBe(2);
+});
+```
+
+- [ ] **Step 2: 跑,确认失败**
+
+Run: `cd web && npx vitest run test/group.test.ts test/authImage.test.ts`
+Expected: FAIL(模块不存在)
+
+- [ ] **Step 3: 实现 `src/lib/group.ts`**
+
+```ts
+import type { Book } from "../api/types";
+
+export interface Group {
+ dir: string; // path 去掉文件名即分组键(spec §4);根目录为 ""
+ books: Book[];
+}
+
+export function groupByDir(books: Book[]): Group[] {
+ const m = new Map();
+ for (const bk of books) {
+ const i = bk.path.lastIndexOf("/");
+ const dir = i < 0 ? "" : bk.path.slice(0, i);
+ let arr = m.get(dir);
+ if (!arr) {
+ arr = [];
+ m.set(dir, arr);
+ }
+ arr.push(bk);
+ }
+ return [...m.entries()]
+ .sort((a, b) => (a[0] === "" ? -1 : b[0] === "" ? 1 : a[0].localeCompare(b[0])))
+ .map(([dir, bs]) => ({ dir, books: bs }));
+}
+```
+
+- [ ] **Step 4: 实现 `src/lib/authImage.ts` 与 `src/components/Cover.tsx`**
+
+`src/lib/authImage.ts`:
+
+```ts
+import { apiRaw } from "../api/client";
+
+const MAX = 600;
+const cache = new Map>(); // 插入序 ≈ LRU(命中时重插)
+
+// 带鉴权取图 → objectURL。后端 Bearer-only,![]()
/