@allbluecn/web-app 0.17.2 → 0.18.0

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

@@ -0,0 +1,628 @@
+// 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/>.
+
+// SDK/扩展上报处理链（任务 14，规格 §8.2/§8.3）：
+// 鉴权（X-Bug-Key → sha256 → ProjectAccessToken）→ 限流 → 逐事件
+// （zod 校验 → 采样 → 指纹 → 新指纹建单 / 已有去重计数 + 采样窗口 + 重开联动）
+// → 响应 { ok, results }。路由层（routes/api/bugs/report.ts）只是薄壳。
+import { prisma } from "@allbluecn/database";
+import type { Prisma } from "@allbluecn/database";
+import { z } from "zod";
+import { computeFingerprint } from "./fingerprint";
+import { resolveSeverity } from "./severity-rules";
+import { hashToken, isValidTokenFormat } from "./tokens";
+import { fireBugWebhook } from "./webhook-out";
+import { checkRateLimit } from "@/server/lib/rate-limit";
+
+// ── 协议常量（§8.2 约束）──
+export const MAX_BODY_BYTES = 256 * 1024; // body ≤ 256KB，超限 413
+export const MAX_EVENTS = 10; // 单请求 ≤10 事件
+export const BUG_REPORT_RATE_LIMIT = { max: 60, windowMs: 60_000 } as const;
+// 同指纹采样窗口：窗口内重复上报只计数，不重复存 BugEvent 快照
+export const BUG_EVENT_SAMPLE_WINDOW_MS = 5 * 60_000;
+// autoFix 自动入队风暴上限（§10.3）：项目 pending 状态 run 数 ≥ 上限时跳过入队；
+// 仅约束自动入队，手动（requestBugFixFn）不受限
+export const AUTO_FIX_QUEUE_LIMIT = 20;
+
+// 落库截断（§3.2 Bug 注释）：title 截 80 字符、url/ua 截 2KB、堆栈/事件报文 ≤64KB
+const TITLE_MESSAGE_SLICE = 80;
+const URL_UA_MAX = 2048;
+const STACK_SUMMARY_MAX = 64 * 1024;
+const EVENT_PAYLOAD_MAX = 64 * 1024;
+const IDENTIFIER_MAX_RETRIES = 5;
+
+// chrome_ext 截图（任务 25，§12）：PNG dataURL → Blob，≤5MB 沿用 collect 截图
+// 语义（collect-handler MAX_SCREENSHOT_BYTES 同值）；超限/非法跳过该图不失败。
+export const MAX_SCREENSHOT_BYTES = 5 * 1024 * 1024;
+const IMAGE_DATAURL_PREFIX = "data:image/png;base64,";
+
+// ── 上报协议 zod schema（宽容解析：未知字段剥离，SDK 前向兼容）──
+const eventSchema = z.object({
+  errorName: z.string().min(1).max(300),
+  message: z.string().max(20_000).optional(),
+  stack: z.string().optional(),
+  url: z.string().optional(),
+  userAgent: z.string().optional(),
+  breadcrumbs: z.array(z.record(z.string(), z.unknown())).max(200).optional(),
+  extra: z.record(z.string(), z.unknown()).optional(),
+});
+
+const reportSchema = z.object({
+  sdkVersion: z.string().max(50).optional(),
+  type: z.string().max(50).optional(), // js_error|node_error|chrome_ext|custom
+  env: z.string().max(100).optional(),
+  events: z.array(eventSchema).min(1).max(MAX_EVENTS),
+});
+
+type ReportEvent = z.infer<typeof eventSchema>;
+
+/** 单事件处理结果（响应 results 数组元素，§8.2） */
+interface EventResult {
+  bugId: string | null;
+  deduplicated: boolean;
+  /** autoReport 关闭 / 采样丢弃 / 事件级失败时给出原因，正常路径无此字段 */
+  skipped?: "auto_report_disabled";
+  sampled?: boolean;
+  /** 事件级错误标记（不外泄内部错误详情），正常路径无此字段 */
+  error?: "internal_error";
+}
+
+const json = (
+  body: unknown,
+  status = 200,
+  headers: Record<string, string> = {},
+) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json", ...headers },
+  });
+
+const truncate = (value: string | null | undefined, max: number) =>
+  typeof value === "string" ? value.slice(0, max) : null;
+
+/** source 映射（§8.3）：扩展上报归 chrome_ext，其余（js_error/node_error/custom）归 sdk_auto */
+function mapReportSource(type: string | undefined): "sdk_auto" | "chrome_ext" {
+  return type === "chrome_ext" ? "chrome_ext" : "sdk_auto";
+}
+
+/**
+ * BugEvent.rawPayload：精简原始报文 + 按事件截断至 64KB（§3.2）。
+ * 超限依次丢弃 stack → breadcrumbs/extra（堆栈与面包屑是体积大头），
+ * 兜底保证 JSON 完整可解析。
+ */
+/** JSON 字段落库类型收敛：unknown 深度结构经 JSON round-trip 保证可序列化（Prisma InputJsonValue） */
+function toJsonValue(value: unknown): Prisma.InputJsonValue {
+  return JSON.parse(JSON.stringify(value)) as Prisma.InputJsonValue;
+}
+
+function buildEventPayload(
+  event: ReportEvent,
+  sdkVersion: string | undefined,
+  type: string,
+  screenshot?: ScreenshotMeta,
+): Prisma.InputJsonValue {
+  const base = {
+    sdkVersion,
+    type,
+    errorName: event.errorName,
+    message: event.message ?? null,
+    stack: truncate(event.stack, STACK_SUMMARY_MAX),
+    url: truncate(event.url, URL_UA_MAX),
+    userAgent: truncate(event.userAgent, URL_UA_MAX),
+    breadcrumbs: event.breadcrumbs ?? null,
+    extra: stripImageData(event.extra),
+    // 截图本体不进 64KB 快照（PNG dataURL 远超上限）；blobId 顶层记录供详情缩略图读取
+    ...(screenshot?.blobId ? { blobId: screenshot.blobId } : {}),
+    ...(screenshot?.skipped ? { screenshotSkipped: screenshot.skipped } : {}),
+  };
+  if (Buffer.byteLength(JSON.stringify(base)) <= EVENT_PAYLOAD_MAX) {
+    return toJsonValue(base);
+  }
+  const withoutStack = { ...base, stack: null, stackTruncated: true };
+  if (Buffer.byteLength(JSON.stringify(withoutStack)) <= EVENT_PAYLOAD_MAX) {
+    return toJsonValue(withoutStack);
+  }
+  return toJsonValue({
+    ...withoutStack,
+    breadcrumbs: null,
+    extra: null,
+    payloadTruncated: true,
+  });
+}
+
+/**
+ * 上报入口完整处理链。永远返回 Response，不向路由层抛业务错误：
+ * 畸形载荷/凭证失效是 4xx 响应而非异常；单事件 DB 失败（建单/计数任一步）
+ * 降级为带 error 标记的结果元素，不拖垮整批（错误风暴期 DB 抖动高发）。
+ */
+export async function handleBugReport(request: Request): Promise<Response> {
+  // ── 载荷体积防线（先于鉴权：拒绝 oversized body 不消耗 DB/限流资源）──
+  const contentLength = Number(request.headers.get("content-length") ?? "0");
+  if (contentLength > MAX_BODY_BYTES) {
+    return json({ error: "payload_too_large" }, 413);
+  }
+  const rawText = await request.text();
+  if (Buffer.byteLength(rawText) > MAX_BODY_BYTES) {
+    return json({ error: "payload_too_large" }, 413);
+  }
+
+  // ── body 解析 + 协议校验（§8.2：非 JSON 400）──
+  let raw: unknown;
+  try {
+    raw = JSON.parse(rawText);
+  } catch {
+    return json({ error: "invalid_json" }, 400);
+  }
+  const parsed = reportSchema.safeParse(raw);
+  if (!parsed.success) {
+    return json(
+      { error: "invalid_payload", detail: z.treeifyError(parsed.error) },
+      400,
+    );
+  }
+  const { events, type, sdkVersion, env: bodyEnv } = parsed.data;
+
+  // ── 鉴权（§8.3 步骤 1）：明文 → sha256 → 查 tokenHash ──
+  const key = request.headers.get("X-Bug-Key");
+  if (!key || !isValidTokenFormat(key)) {
+    return json({ error: "missing_or_invalid_key" }, 401);
+  }
+  const token = await prisma.projectAccessToken.findUnique({
+    where: { tokenHash: hashToken(key) },
+  });
+  if (!token) return json({ error: "invalid_token" }, 401);
+  if (token.revokedAt) return json({ error: "token_revoked" }, 401);
+  if (token.scope !== "bug.report") return json({ error: "invalid_scope" }, 401);
+
+  // ── 限流（§8.3 步骤 2）：按项目 60 次/分钟（内存滑动窗口，多实例线性衰减 MVP 接受）──
+  const rateLimitKey = `bug-report:${token.projectId}`;
+  const limit = checkRateLimit(rateLimitKey, { ...BUG_REPORT_RATE_LIMIT });
+  if (!limit.allowed) {
+    return json(
+      { error: "rate_limit_exceeded", retryAfterMs: limit.retryAfterMs },
+      429,
+      { "Retry-After": String(Math.ceil(limit.retryAfterMs / 1000)) },
+    );
+  }
+
+  // ── 项目设置惰性 upsert（§3.10：首次访问建行）──
+  const settings = await prisma.bugProjectSettings.upsert({
+    where: { projectId: token.projectId },
+    create: { projectId: token.projectId },
+    update: {},
+  });
+  if (!settings.autoReportEnabled) {
+    // 总开关关闭：对 SDK 返回 ok（不暴露配置），静默丢弃不落库
+    return json({
+      ok: true,
+      results: events.map<EventResult>(() => ({
+        bugId: null,
+        deduplicated: false,
+        skipped: "auto_report_disabled",
+      })),
+    });
+  }
+
+  // ── 逐事件处理（§8.3 步骤 3）──
+  // 逐事件错误隔离：错误风暴场景恰是 DB 抖动高发期，单事件失败（建单/计数
+  // 任一步）不拖垮整批——降级为带 error 标记的结果元素，整体仍 200。
+  const results = await Promise.all(
+    events.map(async (event): Promise<EventResult> => {
+      try {
+        return await processEvent(event, {
+          projectId: token.projectId,
+          type: type ?? "js_error",
+          sdkVersion,
+          env: bodyEnv,
+          settings,
+        });
+      } catch (error) {
+        console.error("[bug-report] event process failed:", error);
+        return { bugId: null, deduplicated: false, error: "internal_error" };
+      }
+    }),
+  );
+
+  // ── lastUsedAt（§8.3 步骤 5）：fire-and-forget，不阻塞响应 ──
+  void prisma.projectAccessToken
+    .update({ where: { id: token.id }, data: { lastUsedAt: new Date() } })
+    .catch(() => {});
+
+  return json({ ok: true, results });
+}
+
+interface ProcessContext {
+  projectId: string;
+  type: string;
+  sdkVersion?: string;
+  env?: string;
+  settings: { sampleRate: number; reopenOnDuplicate: boolean; autoFixEnabled: boolean };
+}
+
+async function processEvent(
+  event: ReportEvent,
+  ctx: ProcessContext,
+): Promise<EventResult> {
+  // 服务端二次采样（§8.3：与 SDK 端采样独立叠加；sampleRate=1 恒保留）
+  if (Math.random() >= ctx.settings.sampleRate) {
+    return { bugId: null, deduplicated: false, sampled: true };
+  }
+
+  const fingerprint = computeFingerprint(event);
+  const now = new Date();
+
+  let existing = await prisma.bug.findUnique({
+    where: { projectId_fingerprint: { projectId: ctx.projectId, fingerprint } },
+  });
+
+  // 采样窗口前置判定（R1 修复：孤儿 Blob 泄漏）：窗口内去重只计数不落任何
+  // 快照（dedupeExistingBug 不建 BugEvent）——截图 Blob 一并跳过持久化，
+  // 否则 blobId 无事件引用、Blob 无 FK 无 GC，每次窗口内重报泄漏一行。
+  const withinSampleWindow =
+    existing !== null &&
+    now.getTime() - existing.lastOccurAt.getTime() < BUG_EVENT_SAMPLE_WINDOW_MS;
+
+  // 截图在实际会消费它的分支前落 Blob（新指纹建单 / 窗口外的去重采样）
+  let screenshot = withinSampleWindow ? undefined : await persistScreenshot(event, ctx);
+
+  if (!existing) {
+    const created = await createBugFromEvent(event, ctx, fingerprint, now, screenshot);
+    if (created) return { bugId: created.id, deduplicated: false };
+    // 并发竞态兜底（§8.3 ⚠）：createBugFromEvent 内 create 撞
+    // @@unique(projectId, fingerprint)（P2002）时返回 null——对方刚建好，
+    // 重查后降级走下方「存在」分支计数，不当作错误。
+    existing = await prisma.bug.findUnique({
+      where: { projectId_fingerprint: { projectId: ctx.projectId, fingerprint } },
+    });
+    if (!existing) {
+      // 理论不可达（P2002 必有赢家）；防御性兜底不让请求 500
+      return { bugId: null, deduplicated: false };
+    }
+    // P2002 竞态（R1 修复）：对方 lastOccurAt≈now，本次必落采样窗口内只计数，
+    // 已创建的截图 Blob 不会有任何事件引用它——fire-and-forget 清理防孤儿
+    //（首查时对方尚未提交，窗口前置判定看不到它）。
+    if (screenshot?.blobId) {
+      const orphanBlobId = screenshot.blobId;
+      void prisma.blob.delete({ where: { id: orphanBlobId } }).catch(() => {});
+      screenshot = undefined;
+    }
+  }
+
+  return dedupeExistingBug(event, ctx, existing, now, screenshot);
+}
+
+/** 新指纹建单（事务内发号），identifier 撞号重试；指纹撞号（P2002）返回 null 交由调用方降级 */
+async function createBugFromEvent(
+  event: ReportEvent,
+  ctx: ProcessContext,
+  fingerprint: string,
+  now: Date,
+  screenshot?: ScreenshotMeta,
+): Promise<CreatedBugForWebhook | null> {
+  const title = `${event.errorName}: ${(event.message ?? "").slice(
+    0,
+    TITLE_MESSAGE_SLICE,
+  )}`;
+  const stackSummary = truncate(event.stack, STACK_SUMMARY_MAX);
+  const url = truncate(event.url, URL_UA_MAX);
+  const userAgent = truncate(event.userAgent, URL_UA_MAX);
+  const env = ctx.env ?? normalizeEnv(event.extra);
+  const rawPayload = buildEventPayload(event, ctx.sdkVersion, ctx.type, screenshot);
+  const severity = resolveSeverity({ errorName: event.errorName, type: ctx.type });
+
+  for (let attempt = 0; attempt < IDENTIFIER_MAX_RETRIES; attempt++) {
+    try {
+      const created = await prisma.$transaction(async (tx) => {
+        const project = await tx.project.findUnique({
+          where: { id: ctx.projectId },
+          select: { id: true, ownerId: true, displayId: true, name: true },
+        });
+        if (!project) throw new Error("token 指向的项目不存在");
+
+        // Bug 发号 scope 带 bug: 前缀，与 Story 序列隔离（照 bug-crud.ts）
+        const counter = await tx.sequenceCounter.upsert({
+          where: { scope: `bug:${ctx.projectId}` },
+          create: { scope: `bug:${ctx.projectId}`, seq: 1 },
+          update: { seq: { increment: 1 } },
+        });
+        const prefix =
+          (project.displayId ?? project.name ?? "")
+            .replace(/[^a-zA-Z0-9]/g, "")
+            .toUpperCase() || "PRJ";
+
+        // SDK 无登录用户，Bug.createdById 必填 FK 落项目 owner
+        //（同 collect 匿名提交先例，活动流以 actorType=sdk 区分）
+        const bug = await tx.bug.create({
+          data: {
+            sequenceId: counter.seq,
+            identifier: `${prefix}-B${counter.seq}`,
+            projectId: ctx.projectId,
+            title,
+            state: "open",
+            severity,
+            source: mapReportSource(ctx.type),
+            fingerprint,
+            env,
+            url,
+            userAgent,
+            stackSummary,
+            createdById: project.ownerId,
+          },
+          select: { id: true },
+        });
+
+        await tx.bugEvent.create({
+          data: { bugId: bug.id, rawPayload, userAgent },
+        });
+        await tx.bugActivity.create({
+          data: {
+            bugId: bug.id,
+            userId: null,
+            actorType: "sdk",
+            action: "sdk_reported",
+          },
+        });
+        await tx.projectActivity.create({
+          data: {
+            projectId: ctx.projectId,
+            userId: project.ownerId,
+            action: "created",
+            targetType: "bug",
+            targetId: bug.id,
+          },
+        });
+
+        // P4 任务 22：autoFixEnabled=true 时新指纹自动入队 AI 修复（§10.3，trigger=auto）。
+        // 事务边界：run 创建在事务内——与 BUG 建单原子（防「有 BUG 无 run」半态）；
+        // webhook（fix.requested）在事务提交成功后 fire-and-forget——回滚不外发通知。
+        // 去重命中的更新分支（dedupeExistingBug）不触发，避免错误风暴。
+        let autoFixRunId: string | null = null;
+        if (ctx.settings.autoFixEnabled) {
+          const pendingCount = await tx.bugFixRun.count({
+            where: { status: "pending", bug: { projectId: ctx.projectId } },
+          });
+          if (pendingCount < AUTO_FIX_QUEUE_LIMIT) {
+            const fixRun = await tx.bugFixRun.create({
+              data: { bugId: bug.id, status: "pending", triggerType: "auto" },
+              select: { id: true },
+            });
+            autoFixRunId = fixRun.id;
+          } else {
+            // 风暴上限跳过留痕：不建 run、不发 webhook，仅活动注明队列已满
+            await tx.bugActivity.create({
+              data: {
+                bugId: bug.id,
+                userId: null,
+                actorType: "sdk",
+                action: "fix_queue_full",
+                newValue: String(AUTO_FIX_QUEUE_LIMIT),
+              },
+            });
+          }
+        }
+
+        // P4 任务 23 接入点：bug.created webhook 在事务提交后 fire（见下方 fireCreationWebhooks）。
+
+        return {
+          id: bug.id,
+          projectId: ctx.projectId,
+          identifier: `${prefix}-B${counter.seq}`,
+          title,
+          severity,
+          url,
+          stackSummary,
+          autoFixRunId,
+        };
+      });
+      // 事务已提交：仅提交成功才外发通知（回滚路径到不了这里）
+      fireCreationWebhooks(created);
+      return created;
+    } catch (e: unknown) {
+      const code = (e as { code?: string }).code;
+      const target = (e as { meta?: { target?: string[] } }).meta?.target;
+      if (code === "P2002" && target?.includes("identifier") && attempt < IDENTIFIER_MAX_RETRIES - 1) {
+        continue; // 并发发号撞 identifier，重试取新 seq
+      }
+      if (code === "P2002") {
+        return null; // 指纹 unique 冲突：并发同指纹，调用方降级计数
+      }
+      throw e;
+    }
+  }
+  throw new Error("创建 BUG 失败：编号冲突，请重试");
+}
+
+/** 新建 BUG 事务返回值：含 webhook body 所需的 bug 摘要字段（§3.8） */
+interface CreatedBugForWebhook {
+  id: string;
+  projectId: string;
+  identifier: string;
+  title: string;
+  severity: string;
+  url: string | null;
+  stackSummary: string | null;
+  autoFixRunId: string | null;
+}
+
+/** 新指纹建单事务提交后外发 webhook：bug.created 恒发；autoFix 入队成功补发 fix.requested */
+function fireCreationWebhooks(created: CreatedBugForWebhook): void {
+  fireBugWebhook("bug.created", {
+    projectId: created.projectId,
+    bug: {
+      id: created.id,
+      identifier: created.identifier,
+      title: created.title,
+      severity: created.severity,
+      state: "open",
+      url: created.url,
+      stackSummary: created.stackSummary,
+    },
+  });
+  if (!created.autoFixRunId) return;
+  fireBugWebhook("fix.requested", {
+    projectId: created.projectId,
+    bug: {
+      id: created.id,
+      identifier: created.identifier,
+      title: created.title,
+      severity: created.severity,
+      state: "open",
+      url: created.url,
+      stackSummary: created.stackSummary,
+    },
+    fixRunId: created.autoFixRunId,
+  });
+}
+
+/** 已有指纹：原子计数 + 5 分钟窗口采样快照 + 重开联动（§8.3 存在分支） */
+async function dedupeExistingBug(
+  event: ReportEvent,
+  ctx: ProcessContext,
+  bug: { id: string; state: string; lastOccurAt: Date },
+  now: Date,
+  screenshot?: ScreenshotMeta,
+): Promise<EventResult> {
+  // 采样窗口：上次落快照距今不足 5 分钟则只计数（错误风暴不刷屏事件明细）
+  const withinSampleWindow =
+    now.getTime() - bug.lastOccurAt.getTime() < BUG_EVENT_SAMPLE_WINDOW_MS;
+  const shouldReopen =
+    (bug.state === "fixed" || bug.state === "closed") &&
+    ctx.settings.reopenOnDuplicate;
+
+  await prisma.bug.update({
+    where: { id: bug.id },
+    data: {
+      totalCount: { increment: 1 }, // 原子自增，并发安全
+      lastOccurAt: now,
+      ...(shouldReopen ? { state: "open" } : {}),
+    },
+  });
+
+  if (shouldReopen) {
+    await prisma.bugActivity.create({
+      data: {
+        bugId: bug.id,
+        userId: null,
+        actorType: "sdk",
+        action: "reopened_by_sdk",
+        field: "state",
+        oldValue: bug.state,
+        newValue: "open",
+      },
+    });
+  }
+
+  if (!withinSampleWindow) {
+    await prisma.bugEvent.create({
+      data: {
+        bugId: bug.id,
+        rawPayload: buildEventPayload(event, ctx.sdkVersion, ctx.type, screenshot),
+        userAgent: truncate(event.userAgent, URL_UA_MAX),
+      },
+    });
+  }
+
+  return { bugId: bug.id, deduplicated: true };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+// ── chrome_ext 截图链路（任务 25，§12）──
+
+/** 截图落库结果：blobId 记入 rawPayload 顶层；跳过时记录原因（事件本身不失败） */
+export interface ScreenshotMeta {
+  blobId?: string;
+  skipped?: "invalid" | "too_large" | "db_error";
+}
+
+/** extra.imageData 解析结果 */
+export type ParsedScreenshot =
+  | { kind: "ok"; mimeType: string; bytes: Uint8Array<ArrayBuffer>; size: number }
+  | { kind: "skip"; reason: "invalid" | "too_large" };
+
+/** 解析 extra.imageData（PNG dataURL → 字节）；缺失返回 null，非法/超限返回 skip */
+export function parseScreenshotImageData(
+  extra: Record<string, unknown> | undefined,
+): ParsedScreenshot | null {
+  const raw = isRecord(extra) ? extra.imageData : undefined;
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw !== "string" || !raw.startsWith(IMAGE_DATAURL_PREFIX)) {
+    return { kind: "skip", reason: "invalid" };
+  }
+  const bytes = Buffer.from(raw.slice(IMAGE_DATAURL_PREFIX.length), "base64");
+  if (bytes.byteLength === 0) return { kind: "skip", reason: "invalid" };
+  if (bytes.byteLength > MAX_SCREENSHOT_BYTES) return { kind: "skip", reason: "too_large" };
+  return {
+    kind: "ok",
+    mimeType: "image/png",
+    bytes: Uint8Array.from(bytes),
+    size: bytes.byteLength,
+  };
+}
+
+/** extra 进 rawPayload 前剥离 imageData（大体积二进制不入 64KB 事件快照） */
+function stripImageData(
+  extra: Record<string, unknown> | undefined,
+): Record<string, unknown> | null {
+  if (!extra) return null;
+  if (!("imageData" in extra)) return extra;
+  const { imageData: _dropped, ...rest } = extra;
+  return rest;
+}
+
+/**
+ * 截图落 Blob（在建单事务外：Blob 写失败不拖垮建单，降级为 skipped 记录）。
+ * Blob.userId 必填 FK 落项目 owner（与 collect 匿名截图同锚点）；仅 chrome_ext
+ * 事件处理（§12 截图是扩展专属能力）。
+ */
+async function persistScreenshot(
+  event: ReportEvent,
+  ctx: ProcessContext,
+): Promise<ScreenshotMeta | undefined> {
+  if (ctx.type !== "chrome_ext") return undefined;
+  const parsed = parseScreenshotImageData(event.extra);
+  if (!parsed) return undefined;
+  if (parsed.kind === "skip") return { skipped: parsed.reason };
+  try {
+    const project = await prisma.project.findUnique({
+      where: { id: ctx.projectId },
+      select: { ownerId: true },
+    });
+    if (!project) return { skipped: "invalid" };
+    const blob = await prisma.blob.create({
+      data: {
+        mimeType: parsed.mimeType,
+        bytes: parsed.bytes,
+        size: parsed.size,
+        userId: project.ownerId,
+      },
+      select: { id: true },
+    });
+    return { blobId: blob.id };
+  } catch (error) {
+    console.error("[bug-report] screenshot blob persist failed:", error);
+    return { skipped: "db_error" };
+  }
+}
+
+/** env 取值：请求级 env 优先，事件 extra.env 兜底（§8.2 extra 契约），截 100 字符 */
+function normalizeEnv(extra: Record<string, unknown> | undefined): string | null {
+  if (!isRecord(extra) || typeof extra.env !== "string" || !extra.env) return null;
+  return extra.env.slice(0, 100);
+}