@allbluecn/web-app 0.17.2 → 0.18.1

package/src/server/bug-report/__tests__/report-handler.test.ts

@@ -0,0 +1,811 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 上报处理链测试（任务 14，规格 §8.2/§8.3）——测试即规格：
+// 鉴权 401 矩阵 / 载荷防线（400/413）/ 限流 429 / 新指纹建单 / P2002 降级 /
+// 去重计数 + 5 分钟采样窗口 / 重开联动 / autoReport 总开关。
+// prisma 与 checkRateLimit 全 mock（照 bug-activities.test.ts 样板）。
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { computeFingerprint } from "../fingerprint";
+
+const mocks = vi.hoisted(() => ({
+  checkRateLimit: vi.fn(),
+  tokenFindUnique: vi.fn(),
+  tokenUpdate: vi.fn(),
+  settingsUpsert: vi.fn(),
+  bugFindUnique: vi.fn(),
+  bugUpdate: vi.fn(),
+  $transaction: vi.fn(),
+  txProjectFindUnique: vi.fn(),
+  txSequenceCounterUpsert: vi.fn(),
+  txBugCreate: vi.fn(),
+  txBugEventCreate: vi.fn(),
+  txBugActivityCreate: vi.fn(),
+  txProjectActivityCreate: vi.fn(),
+  txBugFixRunCount: vi.fn(),
+  txBugFixRunCreate: vi.fn(),
+  prismaBugActivityCreate: vi.fn(),
+  prismaBugEventCreate: vi.fn(),
+  prismaBlobCreate: vi.fn(),
+  prismaBlobDelete: vi.fn(),
+  prismaProjectFindUnique: vi.fn(),
+  fireBugWebhook: vi.fn(),
+}));
+
+vi.mock("@allbluecn/database", () => {
+  const tx = {
+    project: { findUnique: mocks.txProjectFindUnique },
+    sequenceCounter: { upsert: mocks.txSequenceCounterUpsert },
+    bug: { create: mocks.txBugCreate },
+    bugEvent: { create: mocks.txBugEventCreate },
+    bugActivity: { create: mocks.txBugActivityCreate },
+    projectActivity: { create: mocks.txProjectActivityCreate },
+    bugFixRun: {
+      count: mocks.txBugFixRunCount,
+      create: mocks.txBugFixRunCreate,
+    },
+  };
+  const prisma = {
+    projectAccessToken: {
+      findUnique: mocks.tokenFindUnique,
+      update: mocks.tokenUpdate,
+    },
+    bugProjectSettings: { upsert: mocks.settingsUpsert },
+    bug: { findUnique: mocks.bugFindUnique, update: mocks.bugUpdate },
+    bugActivity: { create: mocks.prismaBugActivityCreate },
+    bugEvent: { create: mocks.prismaBugEventCreate },
+    blob: { create: mocks.prismaBlobCreate, delete: mocks.prismaBlobDelete },
+    project: { findUnique: mocks.prismaProjectFindUnique },
+    $transaction: mocks.$transaction,
+  };
+  return { prisma, Prisma: {} };
+});
+
+vi.mock("@/server/lib/rate-limit", () => ({
+  checkRateLimit: mocks.checkRateLimit,
+}));
+
+vi.mock("@/server/bug-report/webhook-out", () => ({
+  fireBugWebhook: mocks.fireBugWebhook,
+}));
+
+import { handleBugReport, parseScreenshotImageData } from "../report-handler";
+
+// ── 测试数据 ──
+const VALID_KEY = `abk_${"a".repeat(32)}`;
+const TOKEN_ROW = {
+  id: "tok1",
+  projectId: "p1",
+  scope: "bug.report",
+  revokedAt: null,
+};
+const SETTINGS_ROW = {
+  projectId: "p1",
+  autoReportEnabled: true,
+  sampleRate: 1,
+  reopenOnDuplicate: true,
+  autoFixEnabled: false,
+};
+const PROJECT_ROW = { id: "p1", ownerId: "u-owner", displayId: "ABC", name: "Alpha" };
+const CREATED_BUG = {
+  id: "bug1",
+  identifier: "ABC-B12",
+  projectId: "p1",
+  state: "open",
+};
+
+const validEvent = {
+  errorName: "TypeError",
+  message: "x is not a function",
+  stack: "at foo (app.ts:1:1)",
+};
+
+const validPayload = (over: Record<string, unknown> = {}) => ({
+  sdkVersion: "1.0.0",
+  type: "js_error",
+  events: [validEvent],
+  ...over,
+});
+
+const makeRequest = (body: unknown, headers: Record<string, string> = {}) =>
+  new Request("http://localhost:3020/api/bugs/report", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    body: typeof body === "string" ? body : JSON.stringify(body),
+  });
+
+const postWithKey = (payload: unknown, key: string | undefined = VALID_KEY) =>
+  handleBugReport(
+    makeRequest(payload, key === undefined ? {} : { "X-Bug-Key": key }),
+  );
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.checkRateLimit.mockReturnValue({ allowed: true, retryAfterMs: 0 });
+  mocks.tokenFindUnique.mockResolvedValue(TOKEN_ROW);
+  mocks.tokenUpdate.mockResolvedValue(TOKEN_ROW);
+  mocks.settingsUpsert.mockResolvedValue(SETTINGS_ROW);
+  mocks.bugFindUnique.mockResolvedValue(null); // 新指纹默认查空
+  mocks.bugUpdate.mockResolvedValue(CREATED_BUG);
+  mocks.$transaction.mockImplementation(async (fn: (tx: unknown) => unknown) =>
+    fn({
+      project: { findUnique: mocks.txProjectFindUnique },
+      sequenceCounter: { upsert: mocks.txSequenceCounterUpsert },
+      bug: { create: mocks.txBugCreate },
+      bugEvent: { create: mocks.txBugEventCreate },
+      bugActivity: { create: mocks.txBugActivityCreate },
+      projectActivity: { create: mocks.txProjectActivityCreate },
+      bugFixRun: {
+        count: mocks.txBugFixRunCount,
+        create: mocks.txBugFixRunCreate,
+      },
+    }),
+  );
+  mocks.txProjectFindUnique.mockResolvedValue(PROJECT_ROW);
+  mocks.txSequenceCounterUpsert.mockResolvedValue({ scope: "bug:p1", seq: 12 });
+  mocks.txBugCreate.mockResolvedValue(CREATED_BUG);
+  mocks.txBugEventCreate.mockResolvedValue({});
+  mocks.txBugActivityCreate.mockResolvedValue({});
+  mocks.txProjectActivityCreate.mockResolvedValue({});
+  mocks.txBugFixRunCount.mockResolvedValue(0);
+  mocks.txBugFixRunCreate.mockResolvedValue({ id: "run-auto-1" });
+  mocks.prismaBugActivityCreate.mockResolvedValue({});
+  mocks.prismaBugEventCreate.mockResolvedValue({});
+  mocks.prismaBlobCreate.mockResolvedValue({ id: "blob-1" });
+  mocks.prismaBlobDelete.mockResolvedValue({});
+  mocks.prismaProjectFindUnique.mockResolvedValue({ ownerId: "u-owner" });
+});
+
+describe("鉴权（§8.3 步骤 1）", () => {
+  it("无 X-Bug-Key → 401，且不查库", async () => {
+    // 直接构造无 key 请求（postWithKey 的默认参数会补 VALID_KEY）
+    const res = await handleBugReport(makeRequest(validPayload()));
+    expect(res.status).toBe(401);
+    expect(mocks.tokenFindUnique).not.toHaveBeenCalled();
+  });
+
+  it("格式错误 key（非 abk_+32 位）→ 401，不查库", async () => {
+    const res = await postWithKey(validPayload(), "bad-key");
+    expect(res.status).toBe(401);
+    expect(mocks.tokenFindUnique).not.toHaveBeenCalled();
+  });
+
+  it("格式合法但查无此 key → 401", async () => {
+    mocks.tokenFindUnique.mockResolvedValue(null);
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(401);
+    // hashToken(明文) 查 tokenHash
+    expect(mocks.tokenFindUnique).toHaveBeenCalledWith({
+      where: { tokenHash: expect.any(String) },
+    });
+  });
+
+  it("已吊销 token（revokedAt 非空）→ 401", async () => {
+    mocks.tokenFindUnique.mockResolvedValue({
+      ...TOKEN_ROW,
+      revokedAt: new Date(),
+    });
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(401);
+  });
+
+  it("scope 非 bug.report → 401", async () => {
+    mocks.tokenFindUnique.mockResolvedValue({
+      ...TOKEN_ROW,
+      scope: "bug.collect",
+    });
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(401);
+  });
+});
+
+describe("载荷防线（§8.2 约束）", () => {
+  it("11 个事件（>10）→ 400", async () => {
+    const events = Array.from({ length: 11 }, (_, i) => ({
+      ...validEvent,
+      message: `e${i}`,
+    }));
+    const res = await postWithKey(validPayload({ events }));
+    expect(res.status).toBe(400);
+  });
+
+  it("body ≥ 256KB → 413", async () => {
+    const big = validPayload({
+      events: [{ ...validEvent, message: "a".repeat(300 * 1024) }],
+    });
+    const res = await postWithKey(big);
+    expect(res.status).toBe(413);
+    expect(mocks.tokenFindUnique).not.toHaveBeenCalled();
+  });
+
+  it("非 JSON body → 400，服务不崩", async () => {
+    const res = await postWithKey("not-json{{{");
+    expect(res.status).toBe(400);
+  });
+
+  it("字段缺失（无 errorName）→ 400", async () => {
+    const res = await postWithKey({
+      type: "js_error",
+      events: [{ message: "no errorName" }],
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("events 为空数组 → 400", async () => {
+    const res = await postWithKey(validPayload({ events: [] }));
+    expect(res.status).toBe(400);
+  });
+});
+
+describe("限流（§8.3 步骤 2）", () => {
+  it("第 61 次/分钟（checkRateLimit 拒绝）→ 429 + Retry-After", async () => {
+    mocks.checkRateLimit.mockReturnValue({
+      allowed: false,
+      retryAfterMs: 4242,
+    });
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(429);
+    expect(res.headers.get("Retry-After")).toBe("5");
+    expect(mocks.checkRateLimit).toHaveBeenCalledWith(
+      "bug-report:p1",
+      { max: 60, windowMs: 60_000 },
+    );
+    expect(mocks.bugFindUnique).not.toHaveBeenCalled();
+  });
+
+  it("限流在鉴权之后：无效 key 不消耗限流配额", async () => {
+    mocks.tokenFindUnique.mockResolvedValue(null);
+    await postWithKey(validPayload());
+    expect(mocks.checkRateLimit).not.toHaveBeenCalled();
+  });
+});
+
+describe("新指纹建单（§8.3 步骤 3 存在分支的反面）", () => {
+  it("createBug：source 映射 js_error→sdk_auto + title + severity + fingerprint", async () => {
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      ok: boolean;
+      results: { bugId: string; deduplicated: boolean }[];
+    };
+    expect(body.ok).toBe(true);
+    expect(body.results).toEqual([
+      { bugId: "bug1", deduplicated: false },
+    ]);
+
+    expect(mocks.txBugCreate).toHaveBeenCalledTimes(1);
+    const data = mocks.txBugCreate.mock.calls[0][0].data;
+    expect(data.source).toBe("sdk_auto");
+    expect(data.title).toBe("TypeError: x is not a function");
+    expect(data.severity).toBe("high"); // TypeError ∈ 程序性异常 → high
+    expect(data.state).toBe("open");
+    expect(data.projectId).toBe("p1");
+    // FK 必填落点：SDK 无登录用户 → 项目 owner（同 collect 匿名先例）
+    expect(data.createdById).toBe("u-owner");
+    // 发号：SequenceCounter scope bug:{projectId}，identifier 前缀 displayId
+    expect(mocks.txSequenceCounterUpsert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { scope: "bug:p1" },
+      }),
+    );
+    expect(data.identifier).toBe("ABC-B12");
+    expect(data.sequenceId).toBe(12);
+    // 指纹服务端计算，与纯函数一致
+    expect(data.fingerprint).toBe(computeFingerprint(validEvent));
+  });
+
+  it("type=chrome_ext → source=chrome_ext", async () => {
+    await postWithKey(validPayload({ type: "chrome_ext" }));
+    const data = mocks.txBugCreate.mock.calls[0][0].data;
+    expect(data.source).toBe("chrome_ext");
+  });
+
+  it("title 截 80 字符：超长 message 只取前 80", async () => {
+    await postWithKey(
+      validPayload({ events: [{ ...validEvent, message: "m".repeat(200) }] }),
+    );
+    const data = mocks.txBugCreate.mock.calls[0][0].data;
+    expect(data.title).toBe(`TypeError: ${"m".repeat(80)}`);
+  });
+
+  it("BugEvent 快照 + BugActivity(sdk_reported) + ProjectActivity", async () => {
+    await postWithKey(validPayload());
+    expect(mocks.txBugEventCreate).toHaveBeenCalledTimes(1);
+    const eventData = mocks.txBugEventCreate.mock.calls[0][0].data;
+    expect(eventData.bugId).toBe("bug1");
+    expect(eventData.rawPayload).toMatchObject({
+      type: "js_error",
+      errorName: "TypeError",
+    });
+
+    const activityData = mocks.txBugActivityCreate.mock.calls[0][0].data;
+    expect(activityData).toMatchObject({
+      bugId: "bug1",
+      action: "sdk_reported",
+      actorType: "sdk",
+      userId: null,
+    });
+
+    const projActivity = mocks.txProjectActivityCreate.mock.calls[0][0].data;
+    expect(projActivity).toMatchObject({
+      projectId: "p1",
+      action: "created",
+      targetType: "bug",
+      targetId: "bug1",
+    });
+  });
+
+  it("lastUsedAt 更新（fire-and-forget）", async () => {
+    await postWithKey(validPayload());
+    expect(mocks.tokenUpdate).toHaveBeenCalledWith({
+      where: { id: "tok1" },
+      data: { lastUsedAt: expect.any(Date) },
+    });
+  });
+});
+
+describe("并发同指纹 P2002 降级（审查重点 1）", () => {
+  it("create 撞 @@unique(projectId, fingerprint) → 降级走存在分支返回 deduplicated:true，不 500", async () => {
+    const concurrentRow = {
+      id: "bug2",
+      projectId: "p1",
+      state: "open",
+      lastOccurAt: new Date(), // 并发方刚建 → 必在采样窗口内
+      totalCount: 1,
+    };
+    mocks.bugFindUnique
+      .mockResolvedValueOnce(null) // 首查：查空 → 走 create
+      .mockResolvedValueOnce(concurrentRow); // P2002 后重查：对方已建
+    mocks.txBugCreate.mockRejectedValue({
+      code: "P2002",
+      meta: { target: ["projectId", "fingerprint"] },
+    });
+
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      results: { bugId: string; deduplicated: boolean }[];
+    };
+    expect(body.results).toEqual([{ bugId: "bug2", deduplicated: true }]);
+    // 降级后是计数更新而非二次 create
+    expect(mocks.bugUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { id: "bug2" },
+        data: expect.objectContaining({ totalCount: { increment: 1 } }),
+      }),
+    );
+  });
+});
+
+describe("已有指纹去重（§8.3 存在分支）", () => {
+  const existingBug = (over: Record<string, unknown> = {}) => ({
+    id: "bug2",
+    projectId: "p1",
+    state: "open",
+    lastOccurAt: new Date(Date.now() - 60_000), // 1 分钟前 → 窗口内
+    totalCount: 5,
+    ...over,
+  });
+
+  it("totalCount increment + lastOccurAt 更新；窗口内不新增 BugEvent", async () => {
+    mocks.bugFindUnique.mockResolvedValue(existingBug());
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      results: { bugId: string; deduplicated: boolean }[];
+    };
+    expect(body.results).toEqual([{ bugId: "bug2", deduplicated: true }]);
+
+    expect(mocks.bugUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { id: "bug2" },
+        data: expect.objectContaining({
+          totalCount: { increment: 1 },
+          lastOccurAt: expect.any(Date),
+        }),
+      }),
+    );
+    // 同指纹 5 分钟窗口内第二条事件不存快照
+    expect(mocks.prismaBugEventCreate).not.toHaveBeenCalled();
+    expect(mocks.txBugActivityCreate).not.toHaveBeenCalled(); // 非 re-open 无活动
+    expect(mocks.prismaBugActivityCreate).not.toHaveBeenCalled();
+  });
+
+  it("距上次上报超 5 分钟 → 采样新增 BugEvent", async () => {
+    mocks.bugFindUnique.mockResolvedValue(
+      existingBug({ lastOccurAt: new Date(Date.now() - 6 * 60_000) }),
+    );
+    await postWithKey(validPayload());
+    expect(mocks.prismaBugEventCreate).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("重开联动（§8.3 存在分支）", () => {
+  it("state=fixed + reopenOnDuplicate=true → state=open + BugActivity(reopened_by_sdk)", async () => {
+    mocks.bugFindUnique.mockResolvedValue({
+      id: "bug2",
+      projectId: "p1",
+      state: "fixed",
+      lastOccurAt: new Date(Date.now() - 60_000),
+      totalCount: 5,
+    });
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(200);
+
+    expect(mocks.bugUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ state: "open" }),
+      }),
+    );
+    // 重开活动必须落库（actorType=sdk，更新分支不走事务）
+    expect(mocks.prismaBugActivityCreate).toHaveBeenCalledWith({
+      data: {
+        bugId: "bug2",
+        userId: null,
+        actorType: "sdk",
+        action: "reopened_by_sdk",
+        field: "state",
+        oldValue: "fixed",
+        newValue: "open",
+      },
+    });
+  });
+
+  it("reopenOnDuplicate=false → 不重开（state 保持 fixed）", async () => {
+    mocks.settingsUpsert.mockResolvedValue({
+      ...SETTINGS_ROW,
+      reopenOnDuplicate: false,
+    });
+    mocks.bugFindUnique.mockResolvedValue({
+      id: "bug2",
+      projectId: "p1",
+      state: "fixed",
+      lastOccurAt: new Date(Date.now() - 60_000),
+      totalCount: 5,
+    });
+    await postWithKey(validPayload());
+    const updateData = mocks.bugUpdate.mock.calls[0][0].data;
+    expect(updateData.state).toBeUndefined();
+  });
+});
+
+describe("autoReportEnabled 总开关（§3.10）", () => {
+  it("false → 返回 ok 但不落库", async () => {
+    mocks.settingsUpsert.mockResolvedValue({
+      ...SETTINGS_ROW,
+      autoReportEnabled: false,
+    });
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { ok: boolean; results: unknown[] };
+    expect(body.ok).toBe(true);
+    expect(body.results).toHaveLength(1);
+    expect(mocks.bugFindUnique).not.toHaveBeenCalled();
+    expect(mocks.$transaction).not.toHaveBeenCalled();
+  });
+});
+
+describe("逐事件错误隔离（契约：不向路由层抛业务错误）", () => {
+  it("单事件 DB 失败不拖垮其余事件，整批仍 200 {ok, results}", async () => {
+    mocks.bugFindUnique
+      .mockRejectedValueOnce(new Error("db jitter")) // 事件 1 查询抛错
+      .mockResolvedValueOnce(null); // 事件 2 正常走新指纹建单
+
+    const res = await postWithKey(
+      validPayload({ events: [{ ...validEvent, message: "will fail" }, validEvent] }),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      ok: boolean;
+      results: { bugId: string | null; deduplicated: boolean; error?: string }[];
+    };
+    expect(body.ok).toBe(true);
+    expect(body.results).toHaveLength(2);
+    // 失败事件：带错误标记（不外泄内部错误信息），不是 500
+    expect(body.results[0]).toEqual({
+      bugId: null,
+      deduplicated: false,
+      error: "internal_error",
+    });
+    // 健康事件：正常建单落库
+    expect(body.results[1]).toEqual({ bugId: "bug1", deduplicated: false });
+    expect(mocks.txBugCreate).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("autoFix 自动入队（任务 22，§10.3）", () => {
+  /** 按事件名过滤 fireBugWebhook 调用（任务 23 起 bug.created 与 fix.* 独立断言） */
+  const webhookCallsByEvent = (event: string) =>
+    mocks.fireBugWebhook.mock.calls.filter(([e]) => e === event);
+
+  it("autoFixEnabled=false（默认）→ 新指纹建单不建 run、不发 fix.requested（bug.created 照发）", async () => {
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(200);
+    expect(mocks.txBugFixRunCount).not.toHaveBeenCalled();
+    expect(mocks.txBugFixRunCreate).not.toHaveBeenCalled();
+    expect(webhookCallsByEvent("fix.requested")).toHaveLength(0);
+    // 任务 23：bug.created 在事务提交后恒发（§3.8）
+    expect(webhookCallsByEvent("bug.created")).toHaveLength(1);
+  });
+
+  it("autoFixEnabled=true + pending 计数 <20 → 事务内建 BugFixRun(pending, auto) + fix.requested webhook", async () => {
+    mocks.settingsUpsert.mockResolvedValue({ ...SETTINGS_ROW, autoFixEnabled: true });
+    mocks.txBugFixRunCount.mockResolvedValue(19); // 上限 20，19 可入队
+
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(200);
+
+    expect(mocks.txBugFixRunCount).toHaveBeenCalledWith({
+      where: { status: "pending", bug: { projectId: "p1" } },
+    });
+    expect(mocks.txBugFixRunCreate).toHaveBeenCalledWith({
+      data: {
+        bugId: "bug1",
+        status: "pending",
+        triggerType: "auto",
+      },
+      select: { id: true },
+    });
+    // webhook 在事务提交成功后触发（回滚不外发通知），body 为 §3.8 规范形状
+    expect(mocks.fireBugWebhook).toHaveBeenCalledWith(
+      "fix.requested",
+      expect.objectContaining({
+        projectId: "p1",
+        fixRunId: "run-auto-1",
+        bug: expect.objectContaining({ id: "bug1", identifier: "ABC-B12", state: "open" }),
+      }),
+    );
+    expect(webhookCallsByEvent("bug.created")).toHaveLength(1);
+  });
+
+  it("autoFixEnabled=true + pending 计数 20（≥上限）→ 不建 run + BugActivity(fix_queue_full)，无 fix.requested（bug.created 照发）", async () => {
+    mocks.settingsUpsert.mockResolvedValue({ ...SETTINGS_ROW, autoFixEnabled: true });
+    mocks.txBugFixRunCount.mockResolvedValue(20);
+
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(200);
+
+    expect(mocks.txBugFixRunCreate).not.toHaveBeenCalled();
+    expect(webhookCallsByEvent("fix.requested")).toHaveLength(0);
+    expect(webhookCallsByEvent("bug.created")).toHaveLength(1);
+    // 风暴上限跳过必须留痕（「自动修复队列已满」）
+    expect(mocks.txBugActivityCreate).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        bugId: "bug1",
+        actorType: "sdk",
+        action: "fix_queue_full",
+      }),
+    });
+  });
+
+  it("去重命中（更新分支）不触发自动入队，即使 autoFixEnabled=true", async () => {
+    mocks.settingsUpsert.mockResolvedValue({ ...SETTINGS_ROW, autoFixEnabled: true });
+    mocks.bugFindUnique.mockResolvedValue({
+      id: "bug2",
+      projectId: "p1",
+      state: "open",
+      lastOccurAt: new Date(Date.now() - 60_000),
+      totalCount: 5,
+    });
+
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(200);
+    expect((await res.json()).results).toEqual([{ bugId: "bug2", deduplicated: true }]);
+
+    expect(mocks.txBugFixRunCount).not.toHaveBeenCalled();
+    expect(mocks.txBugFixRunCreate).not.toHaveBeenCalled();
+    expect(mocks.fireBugWebhook).not.toHaveBeenCalled();
+  });
+
+  it("事务回滚（建单 P2002 指纹冲突降级）→ 不外发 fix.requested webhook", async () => {
+    mocks.settingsUpsert.mockResolvedValue({ ...SETTINGS_ROW, autoFixEnabled: true });
+    // 第一次 create 撞指纹 unique（P2002 非 identifier target）→ 返回 null 降级走存在分支
+    mocks.txBugCreate.mockRejectedValueOnce(
+      Object.assign(new Error("unique conflict"), {
+        code: "P2002",
+        meta: { target: ["projectId", "fingerprint"] },
+      }),
+    );
+    mocks.bugFindUnique
+      .mockResolvedValueOnce(null) // 首查无
+      .mockResolvedValueOnce({
+        id: "bug2",
+        projectId: "p1",
+        state: "open",
+        lastOccurAt: new Date(Date.now() - 60_000),
+        totalCount: 5,
+      }); // 竞态兜底重查命中
+
+    const res = await postWithKey(validPayload());
+    expect(res.status).toBe(200);
+    expect((await res.json()).results).toEqual([{ bugId: "bug2", deduplicated: true }]);
+    expect(mocks.fireBugWebhook).not.toHaveBeenCalled();
+  });
+});
+
+// ── 任务 25：chrome_ext 截图（extra.imageData → Blob + rawPayload.blobId）──
+// 约束（规格 §12）：PNG dataURL 解码落 Blob（userId 落项目 owner，同 collect 先例）；
+// rawPayload 顶层记 blobId 供详情缩略图读取；imageData 本体从 extra 剥离（大体积
+// 二进制不入 64KB 事件快照）；≤5MB 上限沿用 collect 截图语义，超限跳过不失败。
+const PNG_PIXEL =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+
+const chromeExtPayloadWithImage = (imageData: unknown) =>
+  validPayload({
+    type: "chrome_ext",
+    events: [
+      {
+        ...validEvent,
+        extra: { url: "https://app.example.com", imageData },
+      },
+    ],
+  });
+
+describe("chrome_ext 截图落 Blob（任务 25，§12）", () => {
+  it("extra.imageData（PNG dataURL）→ blob.create（image/png, userId=项目 owner）+ rawPayload.blobId", async () => {
+    const res = await postWithKey(chromeExtPayloadWithImage(PNG_PIXEL));
+    expect(res.status).toBe(200);
+    expect((await res.json()).results).toEqual([{ bugId: "bug1", deduplicated: false }]);
+
+    // blob 在建单事务外创建：userId 落项目 owner（Blob.userId FK 必填锚点）
+    expect(mocks.prismaProjectFindUnique).toHaveBeenCalledWith({
+      where: { id: "p1" },
+      select: { ownerId: true },
+    });
+    expect(mocks.prismaBlobCreate).toHaveBeenCalledTimes(1);
+    const blobData = mocks.prismaBlobCreate.mock.calls[0][0].data;
+    expect(blobData.mimeType).toBe("image/png");
+    expect(blobData.userId).toBe("u-owner");
+    expect(blobData.size).toBeGreaterThan(0);
+    expect(Uint8Array.from(blobData.bytes).byteLength).toBe(blobData.size);
+
+    // rawPayload 顶层记 blobId + extra 剥离 imageData
+    const eventData = mocks.txBugEventCreate.mock.calls[0][0].data;
+    expect(eventData.rawPayload.blobId).toBe("blob-1");
+    expect(eventData.rawPayload.extra.imageData).toBeUndefined();
+    expect(eventData.rawPayload.extra.url).toBe("https://app.example.com");
+  });
+
+  it("超限 imageData（>5MB 解码）→ 解析为 too_large（跳过不失败语义）", async () => {
+    // 注：body ≤256KB 防线使大载荷无法经 HTTP 到达截图链路（先 413，错误风暴防线
+    // 已有专属用例），5MB 上限属纵深防御——超限分支直接对导出的纯函数断言
+    const oversize = `data:image/png;base64,${"A".repeat(7 * 1024 * 1024)}`; // 解码 ≈5.25MB > 5MB
+    expect(parseScreenshotImageData({ imageData: oversize })).toEqual({
+      kind: "skip",
+      reason: "too_large",
+    });
+    // HTTP 通路的「跳过截图但事件成功」语义由非法前缀用例覆盖（invalid → 200 建单）
+  });
+
+  it("非法 imageData（非 PNG dataURL 前缀）→ 跳过不失败 + screenshotSkipped=invalid", async () => {
+    const res = await postWithKey(chromeExtPayloadWithImage("data:text/html;base64,PGI+"));
+    expect(res.status).toBe(200);
+    expect((await res.json()).results).toEqual([{ bugId: "bug1", deduplicated: false }]);
+    expect(mocks.prismaBlobCreate).not.toHaveBeenCalled();
+    const eventData = mocks.txBugEventCreate.mock.calls[0][0].data;
+    expect(eventData.rawPayload.screenshotSkipped).toBe("invalid");
+  });
+
+  it("无 imageData → 不触发 blob 链路，rawPayload 无 blobId/screenshotSkipped", async () => {
+    const res = await postWithKey(validPayload({ type: "chrome_ext" }));
+    expect(res.status).toBe(200);
+    expect(mocks.prismaProjectFindUnique).not.toHaveBeenCalled();
+    expect(mocks.prismaBlobCreate).not.toHaveBeenCalled();
+    const eventData = mocks.txBugEventCreate.mock.calls[0][0].data;
+    expect("blobId" in eventData.rawPayload).toBe(false);
+    expect("screenshotSkipped" in eventData.rawPayload).toBe(false);
+  });
+
+  it("非 chrome_ext 事件携带 imageData → 忽略（不落 Blob）", async () => {
+    const res = await postWithKey(chromeExtPayloadWithImage(PNG_PIXEL));
+    expect(res.status).toBe(200);
+    expect(mocks.prismaBlobCreate).toHaveBeenCalledTimes(1);
+
+    mocks.prismaBlobCreate.mockClear();
+    mocks.prismaProjectFindUnique.mockClear();
+    await postWithKey(
+      validPayload({
+        type: "js_error",
+        events: [{ ...validEvent, extra: { imageData: PNG_PIXEL } }],
+      }),
+    );
+    expect(mocks.prismaBlobCreate).not.toHaveBeenCalled();
+  });
+
+  it("blob.create 失败 → 事件不失败（screenshotSkipped=db_error），建单照常", async () => {
+    mocks.prismaBlobCreate.mockRejectedValue(new Error("db full"));
+    const res = await postWithKey(chromeExtPayloadWithImage(PNG_PIXEL));
+    expect(res.status).toBe(200);
+    expect((await res.json()).results).toEqual([{ bugId: "bug1", deduplicated: false }]);
+    const eventData = mocks.txBugEventCreate.mock.calls[0][0].data;
+    expect(eventData.rawPayload.screenshotSkipped).toBe("db_error");
+    expect("blobId" in eventData.rawPayload).toBe(false);
+  });
+
+  it("去重采样路径（超 5 分钟窗口）带 imageData → 同样落 Blob 记 blobId", async () => {
+    mocks.bugFindUnique.mockResolvedValue({
+      id: "bug2",
+      projectId: "p1",
+      state: "open",
+      lastOccurAt: new Date(Date.now() - 6 * 60_000),
+      totalCount: 5,
+    });
+    const res = await postWithKey(chromeExtPayloadWithImage(PNG_PIXEL));
+    expect(res.status).toBe(200);
+    expect((await res.json()).results).toEqual([{ bugId: "bug2", deduplicated: true }]);
+    expect(mocks.prismaBlobCreate).toHaveBeenCalledTimes(1);
+    expect(mocks.prismaBugEventCreate).toHaveBeenCalledTimes(1);
+    expect(mocks.prismaBugEventCreate.mock.calls[0][0].data.rawPayload.blobId).toBe("blob-1");
+  });
+
+  it("采样窗口内重复提交带 imageData → 不新增 Blob（孤儿泄漏修复，R1）", async () => {
+    // 窗口内去重只计数不建 BugEvent——blobId 无处引用即成孤儿（Blob 无 FK 无 GC），
+    // 故 persistScreenshot 必须在前置窗口判定短路，连 project 查询都不发生
+    mocks.bugFindUnique.mockResolvedValue({
+      id: "bug2",
+      projectId: "p1",
+      state: "open",
+      lastOccurAt: new Date(Date.now() - 60_000), // 1 分钟前 → 窗口内
+      totalCount: 5,
+    });
+    const res = await postWithKey(chromeExtPayloadWithImage(PNG_PIXEL));
+    expect(res.status).toBe(200);
+    expect((await res.json()).results).toEqual([{ bugId: "bug2", deduplicated: true }]);
+
+    expect(mocks.prismaBlobCreate).not.toHaveBeenCalled();
+    expect(mocks.prismaProjectFindUnique).not.toHaveBeenCalled();
+    expect(mocks.prismaBlobDelete).not.toHaveBeenCalled();
+    // 窗口内语义不变：只计数、不落快照
+    expect(mocks.bugUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ totalCount: { increment: 1 } }),
+      }),
+    );
+    expect(mocks.prismaBugEventCreate).not.toHaveBeenCalled();
+  });
+
+  it("P2002 竞态降级且截图已创建 → 清理孤儿 Blob（fire-and-forget delete）", async () => {
+    // 首查时对方尚未提交（查空）→ 窗口前置判定放行 → Blob 已创建 →
+    // create 撞指纹 P2002 → 重查命中对方刚建的 bug（lastOccurAt≈now）
+    const concurrentRow = {
+      id: "bug2",
+      projectId: "p1",
+      state: "open",
+      lastOccurAt: new Date(),
+      totalCount: 1,
+    };
+    mocks.bugFindUnique
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce(concurrentRow);
+    mocks.txBugCreate.mockRejectedValue({
+      code: "P2002",
+      meta: { target: ["projectId", "fingerprint"] },
+    });
+
+    const res = await postWithKey(chromeExtPayloadWithImage(PNG_PIXEL));
+    expect(res.status).toBe(200);
+    expect((await res.json()).results).toEqual([{ bugId: "bug2", deduplicated: true }]);
+
+    expect(mocks.prismaBlobCreate).toHaveBeenCalledTimes(1);
+    // 已创建的 Blob 在窗口内不会有事件引用 → 必须清理
+    expect(mocks.prismaBlobDelete).toHaveBeenCalledWith({
+      where: { id: "blob-1" },
+    });
+    // 窗口内不落快照（meta 已随清理置空）
+    expect(mocks.prismaBugEventCreate).not.toHaveBeenCalled();
+  });
+});