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
2026-06-18 14:21:17 +02:00
parent 68f194a043
commit 5fb7bfb1de
74 changed files with 6529 additions and 126 deletions
--- a/apps/web/lib/review/history.test.ts
+++ b/apps/web/lib/review/history.test.ts
@@ -1,7 +1,12 @@
 import { describe, expect, it } from "vitest";

 import type { ReviewHistoryItem } from "@/lib/api/types";
-import { latestReview, normalizeConflicts } from "./history";
+import {
+  latestReview,
+  normalizeConflicts,
+  normalizeForeshadowSug,
+  normalizePace,
+} from "./history";

 const item = (
  conflicts: Record<string, unknown>[],
@@ -43,6 +48,56 @@ describe("normalizeConflicts", () => {
  });
 });

+describe("normalizeForeshadowSug", () => {
+  it("tightens flat list with kind, defaulting kind to planted", () => {
+    const out = normalizeForeshadowSug({
+      ...item([]),
+      foreshadow_sug: [
+        { kind: "resolved", code: "F-012", title: "神秘玉佩", where: "第4段" },
+        { title: "残破地图" },
+      ],
+    });
+    expect(out).toEqual([
+      {
+        kind: "resolved",
+        code: "F-012",
+        title: "神秘玉佩",
+        where: "第4段",
+        note: null,
+      },
+      { kind: "planted", code: null, title: "残破地图", where: null, note: null },
+    ]);
+  });
+
+  it("returns [] when missing", () => {
+    expect(normalizeForeshadowSug(item([]))).toEqual([]);
+    expect(normalizeForeshadowSug(undefined)).toEqual([]);
+  });
+});
+
+describe("normalizePace", () => {
+  it("tightens dict into PaceReport, filtering bad water/beats", () => {
+    const out = normalizePace({
+      ...item([]),
+      pace: {
+        water: [{ where: "第3段", reason: "注水" }, "junk"],
+        hook: true,
+        beat_map: [1, 3, "x", 5],
+      },
+    });
+    expect(out).toEqual({
+      water: [{ where: "第3段", reason: "注水" }],
+      hook: true,
+      beat_map: [1, 3, 5],
+    });
+  });
+
+  it("returns null when pace is missing or not a dict", () => {
+    expect(normalizePace(item([]))).toBeNull();
+    expect(normalizePace(undefined)).toBeNull();
+  });
+});
+
 describe("latestReview", () => {
  it("returns first item (history is newest-first)", () => {
    const a = item([]);
--- a/apps/web/lib/review/history.ts
+++ b/apps/web/lib/review/history.ts
@@ -2,17 +2,32 @@
 // 纯逻辑（可单测）；schema 把 conflicts 标成 {[k]:unknown}[]，这里安全收窄。

 import type { ReviewHistoryItem } from "@/lib/api/types";
-import type { ReviewConflict } from "./sse";
+import type {
+  ForeshadowKind,
+  ForeshadowSuggestion,
+  PaceIssue,
+  PaceReport,
+  ReviewConflict,
+} from "./sse";

 function asString(v: unknown, fallback = ""): string {
  return typeof v === "string" ? v : fallback;
 }

+function asOptionalString(v: unknown): string | null {
+  return typeof v === "string" ? v : null;
+}
+
 function asStringArray(v: unknown): string[] {
  if (!Array.isArray(v)) return [];
  return v.filter((x): x is string => typeof x === "string");
 }

+function asIntArray(v: unknown): number[] {
+  if (!Array.isArray(v)) return [];
+  return v.filter((x): x is number => typeof x === "number" && Number.isFinite(x));
+}
+
 // 把一条留痕的 conflicts 收紧（缺字段给安全默认；保持顺序=下标身份，对齐冲突 gate）。
 export function normalizeConflicts(
  item: ReviewHistoryItem | undefined,
@@ -26,6 +41,46 @@ export function normalizeConflicts(
  }));
 }

+// 把一条留痕的 foreshadow_sug（扁平 list，每条带 kind）收紧成建议（缺字段给安全默认）。
+// 对齐 collect 列映射（C4 扩 T3.3）：planted/resolved 扁平成单 list、每条加 kind。
+export function normalizeForeshadowSug(
+  item: ReviewHistoryItem | undefined,
+): ForeshadowSuggestion[] {
+  const raw = item?.foreshadow_sug ?? [];
+  return raw.map((s) => ({
+    kind: asKind(s["kind"]),
+    code: asOptionalString(s["code"]),
+    title: asString(s["title"], "（未命名线索）"),
+    where: asOptionalString(s["where"]),
+    note: asOptionalString(s["note"]),
+  }));
+}
+
+function asKind(v: unknown): ForeshadowKind {
+  return v === "resolved" ? "resolved" : "planted";
+}
+
+// 把一条留痕的 pace（dict）收紧成节奏报告；缺失/非 dict → null（不渲染节拍图）。
+export function normalizePace(
+  item: ReviewHistoryItem | undefined,
+): PaceReport | null {
+  const raw = item?.pace;
+  if (typeof raw !== "object" || raw === null) return null;
+  const dict = raw as Record<string, unknown>;
+  const waterRaw = Array.isArray(dict["water"]) ? dict["water"] : [];
+  const water: PaceIssue[] = waterRaw
+    .filter((w): w is Record<string, unknown> => typeof w === "object" && w !== null)
+    .map((w) => ({
+      where: asString(w["where"]),
+      reason: asString(w["reason"]),
+    }));
+  return {
+    water,
+    hook: dict["hook"] === true,
+    beat_map: asIntArray(dict["beat_map"]),
+  };
+}
+
 // 最近一条留痕（GET .../reviews 已按新→旧排序）。
 export function latestReview(
  items: readonly ReviewHistoryItem[] | undefined,
--- a/apps/web/lib/review/sse.test.ts
+++ b/apps/web/lib/review/sse.test.ts
@@ -49,6 +49,35 @@ describe("parseReviewBlock", () => {
    });
  });

+  it("parses foreshadow and pace frames (C4 扩 T3.3)", () => {
+    expect(
+      parseReviewBlock(
+        'event:foreshadow\ndata:{"kind":"resolved","code":"F-012","title":"神秘玉佩","where":"第4段","note":"疑似回收"}',
+      ),
+    ).toEqual({
+      event: "foreshadow",
+      data: {
+        kind: "resolved",
+        code: "F-012",
+        title: "神秘玉佩",
+        where: "第4段",
+        note: "疑似回收",
+      },
+    });
+    expect(
+      parseReviewBlock(
+        'event:pace\ndata:{"water":[{"where":"第3段","reason":"注水"}],"hook":false,"beat_map":[1,3,5,2,1,7]}',
+      ),
+    ).toEqual({
+      event: "pace",
+      data: {
+        water: [{ where: "第3段", reason: "注水" }],
+        hook: false,
+        beat_map: [1, 3, 5, 2, 1, 7],
+      },
+    });
+  });
+
  it("returns null for unknown event or malformed json", () => {
    expect(parseReviewBlock('event:token\ndata:{"text":"x"}')).toBeNull();
    expect(parseReviewBlock("event:conflict\ndata:{not json")).toBeNull();
@@ -107,6 +136,39 @@ describe("reduceReview", () => {
    ]);
  });

+  it("accumulates foreshadow suggestions and replaces pace report (last wins)", () => {
+    const events: ReviewSseEvent[] = [
+      {
+        event: "foreshadow",
+        data: { kind: "planted", title: "残破地图", where: "第5段" },
+      },
+      {
+        event: "foreshadow",
+        data: { kind: "resolved", code: "F-012", title: "神秘玉佩" },
+      },
+      {
+        event: "pace",
+        data: { water: [], hook: true, beat_map: [1, 2, 3] },
+      },
+      {
+        event: "pace",
+        data: {
+          water: [{ where: "第3段", reason: "注水" }],
+          hook: false,
+          beat_map: [3, 1, 5],
+        },
+      },
+    ];
+    const state = events.reduce(reduceReview, initialReviewState);
+    expect(state.foreshadow.map((f) => f.kind)).toEqual([
+      "planted",
+      "resolved",
+    ]);
+    expect(state.pace?.hook).toBe(false);
+    expect(state.pace?.beat_map).toEqual([3, 1, 5]);
+    expect(state.phase).toBe("reviewing");
+  });
+
  it("marks done and captures error preserving collected data", () => {
    let s = reduceReview(initialReviewState, {
      event: "section",
--- a/apps/web/lib/review/sse.ts
+++ b/apps/web/lib/review/sse.ts
@@ -19,6 +19,29 @@ export interface ReviewConflict {

 export type SectionStatus = "started" | "done" | "incomplete";

+// 伏笔建议（C4 扩 T3.3）：planted=新埋待确认 / resolved=疑似回收（只读建议）。
+export type ForeshadowKind = "planted" | "resolved";
+
+export interface ForeshadowSuggestion {
+  kind: ForeshadowKind;
+  code?: string | null;
+  title: string;
+  where?: string | null;
+  note?: string | null;
+}
+
+// 节奏报告（C4 扩 T3.3）：注水段 + 章末钩子 + 爽点节拍图。
+export interface PaceIssue {
+  where: string;
+  reason: string;
+}
+
+export interface PaceReport {
+  water: PaceIssue[];
+  hook: boolean;
+  beat_map: number[];
+}
+
 export interface SectionEvent {
  event: "section";
  data: { name: string; status: SectionStatus };
@@ -27,6 +50,24 @@ export interface ConflictEvent {
  event: "conflict";
  data: ReviewConflict;
 }
+export interface ForeshadowEvent {
+  event: "foreshadow";
+  data: {
+    kind: ForeshadowKind;
+    code?: string | null;
+    title: string;
+    where?: string | null;
+    note?: string | null;
+  };
+}
+export interface PaceEvent {
+  event: "pace";
+  data: {
+    water: PaceIssue[];
+    hook: boolean;
+    beat_map: number[];
+  };
+}
 export interface DoneEvent {
  event: "done";
  data: { length: number };
@@ -38,10 +79,19 @@ export interface ErrorEvent {
 export type ReviewSseEvent =
  | SectionEvent
  | ConflictEvent
+  | ForeshadowEvent
+  | PaceEvent
  | DoneEvent
  | ErrorEvent;

-const KNOWN_EVENTS = new Set(["section", "conflict", "done", "error"]);
+const KNOWN_EVENTS = new Set([
+  "section",
+  "conflict",
+  "foreshadow",
+  "pace",
+  "done",
+  "error",
+]);

 // 把一个完整 SSE 块（多行）解析成事件；无法解析则返回 null（跳过）。
 export function parseReviewBlock(block: string): ReviewSseEvent | null {
@@ -108,6 +158,8 @@ export interface ReviewStreamState {
  phase: ReviewPhase;
  sections: ReviewSection[];
  conflicts: ReviewConflict[];
+  foreshadow: ForeshadowSuggestion[];
+  pace: PaceReport | null;
  error: { code: string; message: string; request_id?: string | null } | null;
 }

@@ -115,6 +167,8 @@ export const initialReviewState: ReviewStreamState = {
  phase: "idle",
  sections: [],
  conflicts: [],
+  foreshadow: [],
+  pace: null,
  error: null,
 };

@@ -136,6 +190,18 @@ export function reduceReview(
        phase: "reviewing",
        conflicts: [...state.conflicts, event.data],
      };
+    case "foreshadow":
+      return {
+        ...state,
+        phase: "reviewing",
+        foreshadow: [...state.foreshadow, { ...event.data }],
+      };
+    case "pace":
+      return {
+        ...state,
+        phase: "reviewing",
+        pace: { ...event.data },
+      };
    case "done":
      return { ...state, phase: "done" };
    case "error":
--- a/apps/web/lib/review/useReviewStream.ts
+++ b/apps/web/lib/review/useReviewStream.ts
@@ -7,16 +7,24 @@ import {
  ReviewFrameBuffer,
  initialReviewState,
  reduceReview,
+  type ForeshadowSuggestion,
+  type PaceReport,
  type ReviewConflict,
  type ReviewStreamState,
 } from "./sse";

+export interface ReviewSeed {
+  conflicts: ReviewConflict[];
+  foreshadow: ForeshadowSuggestion[];
+  pace: PaceReport | null;
+}
+
 type Action =
  | { type: "start" }
  | { type: "events"; events: ReturnType<ReviewFrameBuffer["push"]> }
  | { type: "abort" }
  | { type: "fail"; code: string; message: string }
-  | { type: "seed"; conflicts: ReviewConflict[] };
+  | { type: "seed"; seed: ReviewSeed };

 function reducer(state: ReviewStreamState, action: Action): ReviewStreamState {
  switch (action.type) {
@@ -33,7 +41,12 @@ function reducer(state: ReviewStreamState, action: Action): ReviewStreamState {
        error: { code: action.code, message: action.message },
      };
    case "seed":
-      return { ...initialReviewState, conflicts: action.conflicts };
+      return {
+        ...initialReviewState,
+        conflicts: action.seed.conflicts,
+        foreshadow: action.seed.foreshadow,
+        pace: action.seed.pace,
+      };
    default:
      return state;
  }
@@ -45,8 +58,8 @@ export interface UseReviewStream {
  // 用当前编辑器草稿重新审稿。
  start: (projectId: string, chapterNo: number, draft: string) => Promise<void>;
  stop: () => void;
-  // 进页用历史留痕的冲突种入（无需重审即可裁决）。
-  seed: (conflicts: ReviewConflict[]) => void;
+  // 进页用历史留痕（冲突 + 伏笔建议 + 节奏）种入（无需重审即可裁决/查看）。
+  seed: (seed: ReviewSeed) => void;
 }

 // 消费 POST .../review 的 SSE 流：fetch+ReadableStream（EventSource 不支持 POST）。
@@ -62,8 +75,8 @@ export function useReviewStream(): UseReviewStream {
    dispatch({ type: "abort" });
  }, []);

-  const seed = useCallback((conflicts: ReviewConflict[]) => {
-    dispatch({ type: "seed", conflicts });
+  const seed = useCallback((seedData: ReviewSeed) => {
+    dispatch({ type: "seed", seed: seedData });
  }, []);

  const start = useCallback(