@allbluecn/web-app 0.17.2 → 0.18.1

package/src/server/ai-gateway/skills/index.ts

@@ -32,7 +32,6 @@ import {
   MAX_CATALOG_TOKENS,
   resolveCatalogPlacement,
   trimSkillsToBudget,
-  type CatalogPlacement,
 } from "./governance"
 import { loadUserSkillSources } from "./user-source"
 

package/src/server/ai-gateway/story-handler.ts

@@ -109,7 +109,7 @@ export async function* handleStoryAiRequest(
   }
   const data = parsed.data
 
-  let providerConfig: ResolvedProviderConfig | null = data.model
+  const providerConfig: ResolvedProviderConfig | null = data.model
     ? await resolveAiConfigForModel(userId, data.model)
     : await resolveDefaultProviderConfig(userId)
   let fallbackConfig: AiConfig | null = null

package/src/server/ai-gateway/tools/create-pr.ts

@@ -18,7 +18,7 @@
 import { toolDefinition } from "@tanstack/ai"
 import { z } from "zod"
 import type { AppContext } from "../types"
-import { decryptApiKey } from "@/plugins/core/server/api-key-cipher"
+import { decryptApiKey } from "@/server/lib/api-key-cipher"
 import { assertFetchableUrl } from "@/server/fetch-guard"
 
 /** secrets 模式：匹配 .env / .env.* / secrets 等文件路径，防提交敏感信息 */

package/src/server/ai-gateway/tools/delegate-task.ts

@@ -17,7 +17,7 @@
 
 import { toolDefinition } from "@tanstack/ai"
 import { z } from "zod"
-import { BIZ_AGENT_KEYS, type BizAgentKey } from "../runs/biz-keys"
+import { BIZ_AGENT_KEYS } from "../runs/biz-keys"
 import { runChatAsAgent } from "../runs/agent-runtime"
 import type { AppContext } from "../types"
 import type { AgentToolKey } from "./select"

package/src/server/ai-gateway/tools/plugin-lifecycle-server.ts

@@ -19,7 +19,6 @@
 // 客户端 def 见 plugin-lifecycle-defs.ts（零 prisma import）
 
 import { prisma } from "@allbluecn/database";
-import { getCurrentSession } from "@/lib/session";
 import { precheckPluginCode } from "@/server/serverFns/plugins/plugin-precheck";
 import type { AppContext } from "../types";
 import {
@@ -39,29 +38,22 @@ export const pluginDefineTool = pluginDefineDef.server<AppContext>(
       throw new Error(`Plugin precheck failed: ${precheck.errors.join("; ")}`);
     }
 
-    const existing = await prisma.harnessPlugin.findFirst({
-      where: { userId, name, isDeleted: false },
-    });
-
-    if (existing) {
-      const updated = await prisma.harnessPlugin.update({
-        where: { id: existing.id },
-        data: {
-          purpose,
-          codeHost: codeHost ?? null,
-          codeClient: codeClient ?? null,
-          version: existing.version + 1,
-          status: "defined",
-          lastError: null,
-        },
-      });
-      return { id: updated.id, version: updated.version, status: updated.status };
-    }
-
-    const created = await prisma.harnessPlugin.create({
-      data: { userId, name, purpose, codeHost: codeHost ?? null, codeClient: codeClient ?? null },
+    // DB-03：查后写合并为单次 upsert（@@unique([userId,name])）；version 原子自增
+    // 等价原 existing.version + 1，update 段补 isDeleted:false 兜底同名软删行复活
+    const row = await prisma.harnessPlugin.upsert({
+      where: { userId_name: { userId, name } },
+      update: {
+        purpose,
+        codeHost: codeHost ?? null,
+        codeClient: codeClient ?? null,
+        version: { increment: 1 },
+        status: "defined",
+        lastError: null,
+        isDeleted: false,
+      },
+      create: { userId, name, purpose, codeHost: codeHost ?? null, codeClient: codeClient ?? null },
     });
-    return { id: created.id, version: created.version, status: created.status };
+    return { id: row.id, version: row.version, status: row.status };
   }
 );
 
@@ -69,6 +61,8 @@ export const pluginRunTool = pluginRunDef.server<AppContext>(
   async ({ name }, { context }) => {
     const userId = context.userId;
 
+    // 行上 codeHost/codeClient/tools 在后续校验与返回值中继续使用——保留回读，
+    // 不适用 updateMany 合并（DB-03 例外：消费行字段的查后写）
     const plugin = await prisma.harnessPlugin.findFirst({
       where: { userId, name, isDeleted: false },
     });
@@ -94,15 +88,12 @@ export const pluginStopTool = pluginStopDef.server<AppContext>(
   async ({ name }, { context }) => {
     const userId = context.userId;
 
-    const plugin = await prisma.harnessPlugin.findFirst({
+    // DB-03：属主校验合并进写入（updateMany 计数判定），1 次查询替代 2 次
+    const res = await prisma.harnessPlugin.updateMany({
       where: { userId, name, isDeleted: false },
-    });
-    if (!plugin) throw new Error("Plugin not found");
-
-    await prisma.harnessPlugin.update({
-      where: { id: plugin.id },
       data: { status: "stopped" },
     });
+    if (res.count === 0) throw new Error("Plugin not found");
 
     return { stopped: true };
   }
@@ -112,15 +103,12 @@ export const pluginUndefineTool = pluginUndefineDef.server<AppContext>(
   async ({ name }, { context }) => {
     const userId = context.userId;
 
-    const plugin = await prisma.harnessPlugin.findFirst({
+    // DB-03：软删属主校验合并进写入（updateMany 计数判定）
+    const res = await prisma.harnessPlugin.updateMany({
       where: { userId, name, isDeleted: false },
-    });
-    if (!plugin) throw new Error("Plugin not found");
-
-    await prisma.harnessPlugin.update({
-      where: { id: plugin.id },
       data: { isDeleted: true },
     });
+    if (res.count === 0) throw new Error("Plugin not found");
 
     return { deleted: true };
   }

package/src/server/ai-gateway/tools/registry.ts

@@ -35,7 +35,6 @@ import {
 } from "./plugin-lifecycle-defs"
 import { delegateTaskDef } from "./delegate-task"
 import { createPullRequestDef } from "./create-pr"
-import { type AgentToolKey } from "./keys"
 
 export const AGENT_TOOL_DEFS = [
   knowledgeSearchDef,

package/src/server/ai-ports.ts

@@ -27,7 +27,7 @@ import { getVectorStore } from "@/lib/vector-store"
 import {
   indexDocumentEmbeddings as knowledgeIndexDocumentEmbeddings,
   resolveAiConfig as resolveKnowledgeAiConfigRaw,
-} from "@/server/serverFns/knowledge-index-utils"
+} from "@/server/knowledge/knowledge-index-utils"
 import type { AiConfig } from "@/server/ai-gateway"
 import { registerGatewayPorts, registerProServiceResolver } from "@/server/ai-gateway"
 import type { PartialGatewayPorts } from "@/server/ai-gateway";

package/src/server/bug/bug-permissions.ts

@@ -0,0 +1,47 @@
+// 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/>.
+
+// BUG 评论/活动流的成员圈定（任务 3 同谓词：有效成员关系，suspended 视同无权）。
+// 独立模块而非复用 bug-crud 内部私有函数——serverFn 文件禁止非 createServerFn 导出
+// （同 bug-list-query.ts 先例）。
+import { getPrisma } from "@allbluecn/database/get-prisma";
+
+// 按 projectId 直判成员资格（bug-crud.ts 内私有函数的同名变体收编于此，供跨文件
+// 复用：BUG 设置页凭证/设置读写等无 bugId 入口的操作）；suspended 视同无权。
+export async function assertProjectMembership(projectId: string, userId: string): Promise<void> {
+  const prisma = await getPrisma();
+  const membership = await prisma.projectMember.findUnique({
+    where: { projectId_userId: { projectId, userId } },
+    select: { status: true },
+  });
+  if (!membership || membership.status === "suspended") {
+    throw new Error("无权限操作该项目的 BUG");
+  }
+}
+
+// 反查 bug 所属项目后校验当前用户成员资格；返回 projectId 供调用方复用（免二次反查）
+export async function assertBugProjectMember(bugId: string, userId: string): Promise<string> {
+  const prisma = await getPrisma();
+  const bug = await prisma.bug.findUnique({
+    where: { id: bugId },
+    select: { projectId: true },
+  });
+  if (!bug) throw new Error("BUG 不存在");
+
+  await assertProjectMembership(bug.projectId, userId);
+  return bug.projectId;
+}

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

@@ -0,0 +1,335 @@
+// 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/>.
+
+// 公开收集页核心逻辑（任务 18，规格 §9）：collect token 解析（sha256 查库口径与
+// 任务 14 report-handler 一致）→ 限流 → honeypot 静默成功 → 建单（source=collect，
+// 匿名 createdById 落项目 owner，登录落 reporter）+ 截图 blobId 归属校验 + 上传。
+// 本模块被 bug-collect.ts（serverFn 文件）顶层 import，dev 客户端会加载其 import 图——
+// prisma 一律走 getPrisma() 惰性获取（同 serverFns 惯例），禁止顶层 import { prisma }。
+import { getPrisma } from "@allbluecn/database/get-prisma";
+import type { Prisma } from "@allbluecn/database";
+import { checkRateLimit } from "@/server/lib/rate-limit";
+import { hashToken, isValidTokenFormat } from "@/server/bug-report/tokens";
+import type { BugSeverity } from "@/shared/bug/constants";
+
+// ── 限额（§9：提交 10 次/15min/IP；上传未定量，取提交预算 2 倍容忍重试）──
+export const COLLECT_RATE_LIMIT = { max: 10, windowMs: 15 * 60_000 } as const;
+export const COLLECT_UPLOAD_RATE_LIMIT = { max: 20, windowMs: 15 * 60_000 } as const;
+// 上传上限（合理默认，任务 19 UI 同步）：PNG/JPEG、单张 ≤5MB、每次 ≤3 张
+export const MAX_COLLECT_SCREENSHOTS = 3;
+export const MAX_SCREENSHOT_BYTES = 5 * 1024 * 1024;
+const ALLOWED_SCREENSHOT_MIME = new Set(["image/png", "image/jpeg"]);
+// 复现步骤行数上限（防超长文本滥用；单步截 2000 字符）
+const MAX_STEPS = 20;
+const MAX_STEP_LENGTH = 2000;
+
+export interface CollectSubmitInput {
+  token: string;
+  title: string;
+  description?: string;
+  reproduceSteps?: string;
+  severity?: BugSeverity;
+  screenshotBlobIds?: string[];
+  /** 蜜罐字段：表单隐藏域，UI 命名为常规字段（不泄露反机器人性质），非空即机器人 */
+  companyWebsite?: string;
+}
+
+export type CollectSubmitResult =
+  | { ok: true; bugId: string; identifier: string }
+  /** honeypot 命中：与真实成功同形状（bugId 为空），机器人无法据响应区分 */
+  | { ok: true; bugId: null; identifier: null }
+  | {
+      ok: false;
+      reason: "invalid_token" | "rate_limited" | "invalid_screenshots";
+    };
+
+export interface CollectPageConfig {
+  title: string | null;
+  description: string | null;
+  severityVisible: boolean;
+  screenshotEnabled: boolean;
+}
+
+export interface CollectPageData {
+  projectName: string;
+  projectDisplayId: string | null;
+  config: CollectPageConfig;
+}
+
+/** collect token 解析（§9）：明文 → sha256 → 查库（与任务 14 同口径），校验未吊销 + scope=bug.collect */
+export async function resolveCollectToken(
+  key: string | null | undefined,
+): Promise<{ id: string; projectId: string; config: unknown } | null> {
+  if (!key || !isValidTokenFormat(key)) return null;
+  const prisma = await getPrisma();
+  const token = await prisma.projectAccessToken.findUnique({
+    where: { tokenHash: hashToken(key) },
+  });
+  if (!token || token.revokedAt || token.scope !== "bug.collect") return null;
+  return { id: token.id, projectId: token.projectId, config: token.config };
+}
+
+/** token.config（Json）宽容解析：缺省回落默认开关全开（§9 config 契约） */
+function parseCollectConfig(raw: unknown): CollectPageConfig {
+  const cfg = (typeof raw === "object" && raw !== null ? raw : {}) as Record<string, unknown>;
+  return {
+    title: typeof cfg.title === "string" && cfg.title ? cfg.title : null,
+    description: typeof cfg.description === "string" && cfg.description ? cfg.description : null,
+    severityVisible: cfg.severityVisible !== false,
+    screenshotEnabled: cfg.screenshotEnabled !== false,
+  };
+}
+
+/** 收集页数据（免鉴权）：无效返回 null，由路由 beforeLoad 转 throw notFound()（§9，照 share/$versionId 范本） */
+export async function getCollectPage(token: string): Promise<CollectPageData | null> {
+  const resolved = await resolveCollectToken(token);
+  if (!resolved) return null;
+  const prisma = await getPrisma();
+  const project = await prisma.project.findUnique({
+    where: { id: resolved.projectId },
+    select: { name: true, displayId: true },
+  });
+  if (!project) return null;
+  return {
+    projectName: project.name,
+    projectDisplayId: project.displayId,
+    config: parseCollectConfig(resolved.config),
+  };
+}
+
+/** 多行复现文本 → steps 单步数组（§9）：非空行各为一步，order 从 1 起 */
+function parseReproduceSteps(
+  text: string | undefined,
+): Prisma.InputJsonValue | undefined {
+  if (!text) return undefined;
+  const lines = text
+    .split(/\r?\n/)
+    .map((line) => line.trim().slice(0, MAX_STEP_LENGTH))
+    .filter(Boolean)
+    .slice(0, MAX_STEPS);
+  if (lines.length === 0) return undefined;
+  return { steps: lines.map((action, i) => ({ order: i + 1, action })) };
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null;
+
+/**
+ * 收集提交完整链（§9 顺序：限流 → token → honeypot → 建单）。
+ * 免 requireAuth，token 是唯一信任锚；session 可选存在时落 reporter。
+ * 结构化结果而非抛错：收集页面向匿名访客，错误也必须是可渲染的表单提示。
+ */
+export async function submitCollectedBug(params: {
+  ip: string;
+  session: { user?: { id?: string | null } | null } | null | undefined;
+  input: CollectSubmitInput;
+}): Promise<CollectSubmitResult> {
+  const { ip, input } = params;
+
+  // ── 限流（先于 token：扫描器流量不触达查库；§9 checkAuthRateLimit(ip, 10, 15min) 同预算，
+  // 用 checkRateLimit 显式 ip key 承接——现有 checkAuthRateLimit 内部自行取 request 且抛错，
+  // 此处结构化返回更贴合免鉴权表单语义）──
+  const limit = checkRateLimit(`bug-collect:${ip}`, { ...COLLECT_RATE_LIMIT });
+  if (!limit.allowed) return { ok: false, reason: "rate_limited" };
+
+  // ── token 校验（无效/吊销/scope 不符统一 invalid_token，不泄露吊销状态）──
+  const token = await resolveCollectToken(input.token);
+  if (!token) return { ok: false, reason: "invalid_token" };
+
+  // ── honeypot：非空即机器人，静默成功（同形状响应 + 零落库）──
+  if (input.companyWebsite && input.companyWebsite.trim().length > 0) {
+    return { ok: true, bugId: null, identifier: null };
+  }
+
+  const prisma = await getPrisma();
+  const project = await prisma.project.findUnique({
+    where: { id: token.projectId },
+    select: { id: true, ownerId: true, displayId: true, name: true },
+  });
+  // token 级联删除保证项目存在；防御性兜底按无效处理
+  if (!project) return { ok: false, reason: "invalid_token" };
+
+  const sessionUserId = params.session?.user?.id ?? null;
+  // Bug.createdById 必填 FK：登录落 reporter，匿名落项目 owner（活动流 actorType 区分）
+  const creatorId = sessionUserId ?? project.ownerId;
+
+  // ── 截图 blob 归属校验：上传端点以项目 owner 落 Blob.userId，此处防跨项目/他人 blobId 注入 ──
+  const blobIds = input.screenshotBlobIds ?? [];
+  if (blobIds.length > 0) {
+    const blobs = await prisma.blob.findMany({
+      where: { id: { in: blobIds } },
+      select: { id: true, userId: true },
+    });
+    const owned = new Set(blobs.filter((b) => b.userId === project.ownerId).map((b) => b.id));
+    if (owned.size !== blobIds.length) return { ok: false, reason: "invalid_screenshots" };
+  }
+
+  const reproduceSteps = parseReproduceSteps(input.reproduceSteps);
+  const severity = input.severity ?? "medium";
+
+  // ── 建单（事务发号 + identifier 撞号重试，照 bug-crud.ts）──
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      const bug = await prisma.$transaction(async (tx) => {
+        const counter = await tx.sequenceCounter.upsert({
+          where: { scope: `bug:${project.id}` },
+          create: { scope: `bug:${project.id}`, seq: 1 },
+          update: { seq: { increment: 1 } },
+        });
+        const prefix =
+          (project.displayId ?? project.name ?? "")
+            .replace(/[^a-zA-Z0-9]/g, "")
+            .toUpperCase() || "PRJ";
+
+        const created = await tx.bug.create({
+          data: {
+            sequenceId: counter.seq,
+            identifier: `${prefix}-B${counter.seq}`,
+            projectId: project.id,
+            title: input.title,
+            description: input.description ?? null,
+            ...(reproduceSteps ? { reproduceSteps } : {}),
+            state: "open",
+            severity,
+            source: "collect",
+            createdById: creatorId,
+          },
+          select: { id: true, identifier: true },
+        });
+
+        // 截图经上传端点预先落 Blob，此处以 blobId 列表记入事件快照（§9）
+        if (blobIds.length > 0) {
+          await tx.bugEvent.create({
+            data: { bugId: created.id, rawPayload: { screenshots: blobIds } },
+          });
+        }
+
+        await tx.bugActivity.create({
+          data: {
+            bugId: created.id,
+            userId: sessionUserId,
+            actorType: sessionUserId ? "user" : "system",
+            action: "created",
+          },
+        });
+        await tx.projectActivity.create({
+          data: {
+            projectId: project.id,
+            userId: project.ownerId,
+            action: "created",
+            targetType: "bug",
+            targetId: created.id,
+          },
+        });
+
+        return created;
+      });
+
+      // lastUsedAt fire-and-forget（不阻塞响应）
+      void prisma.projectAccessToken
+        .update({ where: { id: token.id }, data: { lastUsedAt: new Date() } })
+        .catch(() => {});
+
+      return { ok: true, bugId: bug.id, identifier: bug.identifier };
+    } catch (e: unknown) {
+      const err = isRecord(e) ? e : {};
+      const code = typeof err.code === "string" ? err.code : undefined;
+      const target = isRecord(err.meta) && Array.isArray(err.meta.target) ? err.meta.target : [];
+      // 并发发号撞 identifier（P2002）取新 seq 重试；其余照常抛出
+      if (code === "P2002" && target.includes("identifier") && attempt < 4) continue;
+      throw e;
+    }
+  }
+  throw new Error("创建 BUG 失败：编号冲突，请重试");
+}
+
+// ── 截图上传端点（POST /api/bugs/collect-upload，§9）──
+
+const json = (body: unknown, status = 200, headers: Record<string, string> = {}) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json", ...headers },
+  });
+
+/** multipart 条目守卫：结构化判断（File 与测试桩共用 duck-typing） */
+const isUploadFile = (v: FormDataEntryValue): v is File =>
+  typeof v === "object" && typeof (v as File).arrayBuffer === "function";
+
+/**
+ * 上传处理链：token 鉴权（X-Bug-Key, scope=bug.collect）→ IP 限流 →
+ * multipart 解析（web 标准 request.formData()）→ 类型/数量/大小校验 → 落 Blob 表
+ * （userId 落项目 owner——与匿名建单的 createdById 同锚点）→ 返回 blobId 列表。
+ */
+export async function handleCollectUpload(request: Request): Promise<Response> {
+  const key = request.headers.get("X-Bug-Key");
+  const token = await resolveCollectToken(key);
+  if (!token) return json({ error: "invalid_token" }, 401);
+
+  const ip = request.headers.get("x-forwarded-for") ?? "unknown";
+  const limit = checkRateLimit(`bug-collect-upload:${ip}`, { ...COLLECT_UPLOAD_RATE_LIMIT });
+  if (!limit.allowed) {
+    return json(
+      { error: "rate_limit_exceeded", retryAfterMs: limit.retryAfterMs },
+      429,
+      { "Retry-After": String(Math.ceil(limit.retryAfterMs / 1000)) },
+    );
+  }
+
+  let formData: FormData | null = null;
+  try {
+    formData = await request.formData();
+  } catch {
+    return json({ error: "invalid_form" }, 400);
+  }
+  const files = formData.getAll("files").filter(isUploadFile);
+  if (files.length === 0) return json({ error: "no_files" }, 400);
+  if (files.length > MAX_COLLECT_SCREENSHOTS) return json({ error: "too_many_files" }, 400);
+  for (const file of files) {
+    if (!ALLOWED_SCREENSHOT_MIME.has(file.type)) return json({ error: "unsupported_type" }, 415);
+    if (file.size > MAX_SCREENSHOT_BYTES) return json({ error: "file_too_large" }, 413);
+  }
+
+  const prisma = await getPrisma();
+  const project = await prisma.project.findUnique({
+    where: { id: token.projectId },
+    select: { ownerId: true },
+  });
+  if (!project) return json({ error: "invalid_token" }, 401);
+
+  // DB-06：逐文件 blob.create（N 次往返，bytes 大字段）改单次 createManyAndReturn
+  // 批量写并取回自增 id（MAX_COLLECT_SCREENSHOTS=3 上限内单批即可，无需分批）。
+  // file 字节全部预读完成后才批量写入：失败路径 0 写入，优于原实现的
+  // 逐文件「读→写」交错（中途失败会留下部分已写 blob）。
+  const blobRows = await prisma.blob.createManyAndReturn({
+    data: await Promise.all(
+      files.map(async (file) => ({
+        mimeType: file.type,
+        bytes: Uint8Array.from(Buffer.from(await file.arrayBuffer())),
+        size: file.size,
+        userId: project.ownerId,
+      })),
+    ),
+    select: { id: true },
+  });
+  const blobIds = blobRows.map((row) => row.id);
+
+  void prisma.projectAccessToken
+    .update({ where: { id: token.id }, data: { lastUsedAt: new Date() } })
+    .catch(() => {});
+
+  return json({ ok: true, blobIds });
+}

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

@@ -0,0 +1,131 @@
+// 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/>.
+
+import { createHash } from "node:crypto";
+import { describe, it, expect } from "vitest";
+import { computeFingerprint, normalizeStack } from "../fingerprint";
+
+function sha256Hex(input: string): string {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+/** 构造 n 行 at 帧的堆栈（行号列号会归一化消除，帧名保留） */
+function frames(n: number, name = "fn"): string {
+  return Array.from({ length: n }, (_, i) => `    at ${name}${i} (http://a/app.js)`).join("\n");
+}
+
+describe("normalizeStack（规格 §8.4 归一化正则）", () => {
+  it("行:列 归一化消除（带或不带括号）", () => {
+    expect(normalizeStack("at foo (a.js:12:34)")).toBe(normalizeStack("at foo (a.js:56:7)"));
+    expect(normalizeStack("a.js:1:2")).toBe(normalizeStack("a.js:3:4"));
+  });
+
+  it("webpack hash（8+ 位十六进制 + 点）归一化消除", () => {
+    expect(normalizeStack("app.8f3a1b2c.js")).toBe(normalizeStack("app.d41e09fa.js"));
+  });
+
+  it("query 串归一化消除", () => {
+    expect(normalizeStack("chunk.js?v=abc123")).toBe(normalizeStack("chunk.js?h=ffff"));
+  });
+
+  it("连续空白折叠为单个空格", () => {
+    expect(normalizeStack("a    b\n\t c")).toBe("a b c");
+  });
+});
+
+describe("computeFingerprint（规格 §8.4）", () => {
+  it("指纹 = sha256(`${errorName}::${归一化堆栈}`)", () => {
+    const stack = "Error: boom\n    at foo (http://a/app.js:1:2)";
+    expect(computeFingerprint({ errorName: "TypeError", stack })).toBe(
+      sha256Hex(`TypeError::${normalizeStack(stack)}`),
+    );
+  });
+
+  it("同一错误不同行号列号 → 同指纹", () => {
+    const a = computeFingerprint({
+      errorName: "TypeError",
+      stack: `TypeError: x is undefined\n    at render (app.js:12:34)\n    at commit (react.js:56:7)`,
+    });
+    const b = computeFingerprint({
+      errorName: "TypeError",
+      stack: `TypeError: x is undefined\n    at render (app.js:98:76)\n    at commit (react.js:5:432)`,
+    });
+    expect(a).toBe(b);
+  });
+
+  it("带 webpack hash / query 的资源名 → 同指纹", () => {
+    // query 取值避开数字串：规格行:列正则 \d+:\d+ 会与 query 里的 "1.2.3:1:2"
+    // 产生重叠匹配留下非对称残渣（"…:2)" vs 无），属规格正则固有行为
+    const a = computeFingerprint({
+      errorName: "Error",
+      stack: `Error: chunk failed\n    at load (http://a/app.8f3a1b2c.js?ver=abc:1:2)`,
+    });
+    const b = computeFingerprint({
+      errorName: "Error",
+      stack: `Error: chunk failed\n    at load (http://a/app.d41e09fa.js?h=def:3:4)`,
+    });
+    expect(a).toBe(b);
+  });
+
+  it("不同 errorName → 异指纹", () => {
+    const stack = "boom\n    at foo (a.js:1:2)";
+    expect(computeFingerprint({ errorName: "TypeError", stack })).not.toBe(
+      computeFingerprint({ errorName: "ReferenceError", stack }),
+    );
+  });
+
+  it("无 stack 时退 sha256(`${errorName}::${message}`)", () => {
+    const expected = sha256Hex("TypeError::x is not a function");
+    expect(
+      computeFingerprint({ errorName: "TypeError", message: "x is not a function" }),
+    ).toBe(expected);
+    expect(
+      computeFingerprint({
+        errorName: "TypeError",
+        message: "x is not a function",
+        stack: null,
+      }),
+    ).toBe(expected);
+    expect(
+      computeFingerprint({
+        errorName: "TypeError",
+        message: "x is not a function",
+        stack: "   ",
+      }),
+    ).toBe(expected);
+  });
+
+  it("堆栈超 10 帧截断：前 10 行相同、其后不同 → 同指纹", () => {
+    // 1 行错误头 + 14 帧 = 15 行，仅前 10 行参与指纹
+    const a = computeFingerprint({ errorName: "Error", stack: `Error: boom\n${frames(14)}` });
+    const b = computeFingerprint({
+      errorName: "Error",
+      stack: `Error: boom\n${frames(10)}\n${frames(4, "other")}`,
+    });
+    expect(a).toBe(b);
+  });
+
+  it("截断边界：第 10 行内的差异仍影响指纹", () => {
+    const a = computeFingerprint({ errorName: "Error", stack: `Error: boom\n${frames(14)}` });
+    // 第 10 行（index 9）换成 changed，index 0-8 与 a 一致
+    const b = computeFingerprint({
+      errorName: "Error",
+      stack: `Error: boom\n${frames(8)}\n    at changed (http://a/app.js)\n${frames(5)}`,
+    });
+    expect(a).not.toBe(b);
+  });
+});