feat: M3 — 伏笔账本 + 节奏引擎 + 大纲（含并发记账 bugfix）

- 伏笔账本：纯函数状态机(OPEN/PARTIAL/CLOSED/OVERDUE) + ForeshadowLedger repo；验收后到期扫描(BackgroundTask 自建 session 置 OVERDUE)；登记/状态变更端点
- 节奏 + 三审齐：foreshadow-analyst + pace-checker 并入 LangGraph 并行审(REVIEW_SPECS)，collect 分列落 chapter_reviews(conflicts/foreshadow_sug/pace)，review SSE 加 foreshadow/pace 事件
- 大纲：outliner Agent 产 OutlineResult(含 foreshadow_windows)，POST /outline 逐章 upsert outline 表；GET /foreshadow?status= 看板
- 前端：伏笔四泳道看板(OVERDUE 琥珀) + 大纲编辑器(窗口徽标) + 节奏节拍图(▁▃▅) + 审稿页消费 foreshadow/pace SSE
- bugfix(T3.8)：并行三审共用请求 session 记账触发 'Session is already flushing' → foreshadow/pace 静默丢失；SqlAlchemyLedgerSink.record 改 add-only(靠端点/事务 commit)，加并发回归测试
- M3 E2E：真实 DB + mock 网关零 token 走通 埋设→进展→验收后扫描 OVERDUE→看板 + 大纲含窗口 + 三审齐 SSE/留痕；E2E 暴露并钉住上述 bug
- 门禁绿：mypy 111 / pytest 228(0 xfailed) / alembic 无漂移；前端 gen:api/lint/tsc/vitest 69/build

apps/web/lib/outline/outline.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+
+import type {
+  ForeshadowWindowView,
+  OutlineChapterView,
+} from "@/lib/api/types";
+import {
+  groupByVolume,
+  isCloseWindow,
+  windowBadgeLabel,
+} from "./outline";
+
+const ch = (over: Partial<OutlineChapterView>): OutlineChapterView => ({
+  no: 1,
+  volume: 1,
+  beats: [],
+  foreshadow_windows: [],
+  ...over,
+});
+
+const win = (
+  over: Partial<ForeshadowWindowView>,
+): ForeshadowWindowView => ({ code: "F-012", ...over });
+
+describe("groupByVolume", () => {
+  it("groups by volume and sorts volumes and chapters ascending", () => {
+    const groups = groupByVolume([
+      ch({ no: 127, volume: 3 }),
+      ch({ no: 12, volume: 1 }),
+      ch({ no: 126, volume: 3 }),
+    ]);
+    expect(groups.map((g) => g.volume)).toEqual([1, 3]);
+    expect(groups[1]?.chapters.map((c) => c.no)).toEqual([126, 127]);
+  });
+
+  it("handles undefined", () => {
+    expect(groupByVolume(undefined)).toEqual([]);
+  });
+});
+
+describe("windowBadgeLabel", () => {
+  it("renders a range, half-open, or bare badge", () => {
+    expect(
+      windowBadgeLabel(win({ expected_close_from: 40, expected_close_to: 60 })),
+    ).toBe("⚑ F-012 (40-60)");
+    expect(windowBadgeLabel(win({ expected_close_to: 60 }))).toBe(
+      "⚑ F-012 (≤60)",
+    );
+    expect(windowBadgeLabel(win({ expected_close_from: 40 }))).toBe(
+      "⚑ F-012 (≥40)",
+    );
+    expect(windowBadgeLabel(win({}))).toBe("⚑ F-012");
+  });
+});
+
+describe("isCloseWindow", () => {
+  it("is true when chapter no is inside the recovery window", () => {
+    const w = win({ expected_close_from: 40, expected_close_to: 60 });
+    expect(isCloseWindow(ch({ no: 50 }), w)).toBe(true);
+    expect(isCloseWindow(ch({ no: 61 }), w)).toBe(false);
+    expect(isCloseWindow(ch({ no: 50 }), win({}))).toBe(false);
+  });
+});

apps/web/lib/outline/outline.ts

@@ -0,0 +1,49 @@
+// 大纲编辑器纯逻辑：按卷分组、伏笔窗口徽标文案、接近回收窗口提示（UX §6.7）。
+// OutlineChapterView/ForeshadowWindowView 已由 OpenAPI 强类型，无需手动收窄。
+
+import type { ForeshadowWindowView, OutlineChapterView } from "@/lib/api/types";
+
+export interface VolumeGroup {
+  volume: number;
+  chapters: OutlineChapterView[];
+}
+
+// 按 volume 分组（保持章号升序）；卷号升序。
+export function groupByVolume(
+  chapters: readonly OutlineChapterView[] | undefined,
+): VolumeGroup[] {
+  const byVolume = new Map<number, OutlineChapterView[]>();
+  for (const ch of chapters ?? []) {
+    const list = byVolume.get(ch.volume) ?? [];
+    byVolume.set(ch.volume, [...list, ch]);
+  }
+  return [...byVolume.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([volume, list]) => ({
+      volume,
+      chapters: [...list].sort((a, b) => a.no - b.no),
+    }));
+}
+
+// 伏笔窗口徽标文案：`⚑ F-012 (40-60)` / `⚑ F-012 (≤60)` / `⚑ F-012`。
+export function windowBadgeLabel(window: ForeshadowWindowView): string {
+  const from = window.expected_close_from;
+  const to = window.expected_close_to;
+  if (typeof from === "number" && typeof to === "number") {
+    return `⚑ ${window.code} (${from}-${to})`;
+  }
+  if (typeof to === "number") return `⚑ ${window.code} (≤${to})`;
+  if (typeof from === "number") return `⚑ ${window.code} (≥${from})`;
+  return `⚑ ${window.code}`;
+}
+
+// 接近回收：本章号落在窗口 [from,to] 内（提示「本章可回收」，UX §6.7 ⚑ 可回收）。
+export function isCloseWindow(
+  chapter: OutlineChapterView,
+  window: ForeshadowWindowView,
+): boolean {
+  const to = window.expected_close_to;
+  if (typeof to !== "number") return false;
+  const from = window.expected_close_from ?? to;
+  return chapter.no >= from && chapter.no <= to;
+}

apps/web/lib/outline/useOutline.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useCallback, useState } from "react";
+
+import { api } from "@/lib/api/client";
+import { useToast } from "@/components/Toast";
+import type { OutlineChapterView } from "@/lib/api/types";
+
+export type OutlineStatus = "idle" | "generating" | "ready" | "error";
+
+export interface OutlineError {
+  code: string;
+  message: string;
+}
+
+export interface UseOutline {
+  chapters: OutlineChapterView[];
+  status: OutlineStatus;
+  error: OutlineError | null;
+  generate: (projectId: string, volume: number) => Promise<void>;
+}
+
+// 生成大纲：POST .../outline（body {volume}）。无凭据/网关失败 → 503 LLM_UNAVAILABLE
+// （流前 JSON 信封），经 error 检出、引导去设置（同 draft/review 范式）。
+export function useOutline(initial: OutlineChapterView[]): UseOutline {
+  const [chapters, setChapters] = useState<OutlineChapterView[]>(initial);
+  const [status, setStatus] = useState<OutlineStatus>(
+    initial.length > 0 ? "ready" : "idle",
+  );
+  const [error, setError] = useState<OutlineError | null>(null);
+  const toast = useToast();
+
+  const generate = useCallback<UseOutline["generate"]>(
+    async (projectId, volume) => {
+      setStatus("generating");
+      setError(null);
+      const { data, error: apiError } = await api.POST(
+        "/projects/{project_id}/outline",
+        {
+          params: { path: { project_id: projectId } },
+          body: { volume },
+        },
+      );
+      if (apiError || !data) {
+        const env = apiError as
+          | { error?: { code?: string; message?: string } }
+          | undefined;
+        const code = env?.error?.code ?? "OUTLINE_FAILED";
+        const message = env?.error?.message ?? "大纲生成失败，请重试。";
+        setError({ code, message });
+        setStatus("error");
+        toast(message, "error");
+        return;
+      }
+      setChapters(data.chapters ?? []);
+      setStatus("ready");
+      toast("大纲已生成", "success");
+    },
+    [toast],
+  );
+
+  return { chapters, status, error, generate };
+}