@allbluecn/web-app 0.18.2 → 0.19.0

package/src/server/lib/__tests__/sequence-number-retry.test.ts

@@ -0,0 +1,160 @@
+// 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/>.
+
+// 编号冲突重试助手单测：谓词只认 P2002 且 target 含 identifier/scope；
+// 助手重试至成功 / 非冲突立即 rethrow / 耗尽抛友好错误且 cause 保留原始 P2002 /
+// exhaustedMessage 自定义文案生效。P2002 构造方式对齐 story-crud.test.ts 既有
+// 写法（Object.assign 挂 code/meta）。
+import { describe, expect, it, vi } from "vitest";
+import {
+  isSequenceNumberConflict,
+  withSequenceNumberRetry,
+  SEQUENCE_NUMBER_MAX_ATTEMPTS,
+} from "@/server/lib/sequence-number-retry";
+
+const p2002 = (target: string[]) =>
+  Object.assign(new Error("Unique constraint failed"), {
+    code: "P2002",
+    meta: { target },
+  });
+
+describe("isSequenceNumberConflict", () => {
+  it("P2002 + target 含 identifier → true（并发撞编号唯一键）", () => {
+    expect(isSequenceNumberConflict(p2002(["projectId", "identifier"]))).toBe(true);
+  });
+
+  it("P2002 + target 为 scope → true（项目首创并发撞计数器行唯一键）", () => {
+    expect(isSequenceNumberConflict(p2002(["scope"]))).toBe(true);
+  });
+
+  it("P2002 + target 为其他字段（email）→ false", () => {
+    expect(isSequenceNumberConflict(p2002(["email"]))).toBe(false);
+  });
+
+  it("其他 Prisma 错误码（P2003）→ false", () => {
+    expect(
+      isSequenceNumberConflict(
+        Object.assign(new Error("FK violation"), { code: "P2003", meta: { target: [] } }),
+      ),
+    ).toBe(false);
+  });
+
+  it("普通 Error（无 code/meta）→ false", () => {
+    expect(isSequenceNumberConflict(new Error("x"))).toBe(false);
+  });
+
+  it("非 Error 值（字符串 / null）→ false", () => {
+    expect(isSequenceNumberConflict("string")).toBe(false);
+    expect(isSequenceNumberConflict(null)).toBe(false);
+  });
+});
+
+describe("withSequenceNumberRetry", () => {
+  it("首次成功：run 只调 1 次，返回值透传", async () => {
+    const run = vi.fn().mockResolvedValue({ id: "st-1" });
+
+    const res = await withSequenceNumberRetry(run);
+
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(res).toEqual({ id: "st-1" });
+  });
+
+  it("前两次抛 scope 冲突、第三次成功：调 3 次并返回成功值", async () => {
+    const run = vi
+      .fn<(...args: unknown[]) => Promise<{ ok: boolean }>>()
+      .mockRejectedValueOnce(p2002(["scope"]))
+      .mockRejectedValueOnce(p2002(["scope"]))
+      .mockResolvedValueOnce({ ok: true });
+
+    const res = await withSequenceNumberRetry(run);
+
+    expect(run).toHaveBeenCalledTimes(3);
+    expect(res).toEqual({ ok: true });
+  });
+
+  it("非冲突错误：只调 1 次即 rethrow 原错误（同一引用）", async () => {
+    const boom = new Error("负责人必须是团队成员");
+    const run = vi.fn().mockRejectedValue(boom);
+
+    await expect(withSequenceNumberRetry(run)).rejects.toBe(boom);
+    expect(run).toHaveBeenCalledTimes(1);
+  });
+
+  it(`连续 ${SEQUENCE_NUMBER_MAX_ATTEMPTS} 次冲突：调恰 ${SEQUENCE_NUMBER_MAX_ATTEMPTS} 次，抛默认友好错误且 cause 为最后一次原始错误`, async () => {
+    const first = p2002(["identifier"]);
+    const last = p2002(["scope"]);
+    const run = vi
+      .fn()
+      .mockRejectedValueOnce(first)
+      .mockRejectedValueOnce(first)
+      .mockRejectedValueOnce(first)
+      .mockRejectedValueOnce(first)
+      .mockRejectedValueOnce(last);
+
+    const err = await withSequenceNumberRetry(run).catch((e: unknown) => e);
+
+    expect(run).toHaveBeenCalledTimes(SEQUENCE_NUMBER_MAX_ATTEMPTS);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toBe("操作失败：编号冲突，请重试");
+    expect((err as Error & { cause?: unknown }).cause).toBe(last);
+  });
+
+  it("maxAttempts 参数生效：传 2 则总尝试恰 2 次", async () => {
+    const run = vi.fn().mockRejectedValue(p2002(["identifier"]));
+
+    await expect(withSequenceNumberRetry(run, { maxAttempts: 2 })).rejects.toThrow(
+      "操作失败：编号冲突，请重试",
+    );
+
+    expect(run).toHaveBeenCalledTimes(2);
+  });
+
+  it("maxAttempts: 0 钳制为至少 1 次：恰调 1 次且耗尽错误 cause 为该次原始错误", async () => {
+    const original = p2002(["identifier"]);
+    const run = vi.fn().mockRejectedValue(original);
+
+    const err = await withSequenceNumberRetry(run, { maxAttempts: 0 }).catch((e: unknown) => e);
+
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toBe("操作失败：编号冲突，请重试");
+    expect((err as Error & { cause?: unknown }).cause).toBe(original);
+  });
+
+  it("maxAttempts: NaN 同样钳制为 1 次：恰调 1 次且 cause 有值（非有限数不落空）", async () => {
+    const original = p2002(["scope"]);
+    const run = vi.fn().mockRejectedValue(original);
+
+    const err = await withSequenceNumberRetry(run, { maxAttempts: Number.NaN }).catch(
+      (e: unknown) => e,
+    );
+
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error & { cause?: unknown }).cause).toBe(original);
+  });
+
+  it("exhaustedMessage 自定义文案生效（调用方各自现有耗尽文案）", async () => {
+    const run = vi.fn().mockRejectedValue(p2002(["identifier"]));
+
+    await expect(
+      withSequenceNumberRetry(run, { maxAttempts: 1, exhaustedMessage: "创建 BUG 失败：编号冲突，请重试" }),
+    ).rejects.toThrow("创建 BUG 失败：编号冲突，请重试");
+
+    expect(run).toHaveBeenCalledTimes(1);
+  });
+});

package/src/server/lib/rate-limit.ts

@@ -20,7 +20,7 @@ import { RateLimiter } from '@tanstack/pacer'
 /**
  * ⚠️ 架构边界：本模块限流状态存于单进程内存（limiterCache Map），
  * **多实例部署不共享**，实际阈值 = 配置值 × 实例数。本期不实施分布式限流
- * （Redis 等），多实例部署落地前不得将本模块视为唯一防线。
+ * （Redis 等），多实例部署落地前不得将本模块视为唯一防线。Cloudflare Workers 多 isolate 同语义（每个 isolate 各持一份），与 Vercel serverless 现状同级；分布式化（Redis/DO）为独立后续任务。
  *
  * 两个注册表：
  * - AI_RATE_LIMIT：AI 类端点（chat/媒体生成/原型等），checkAiRateLimit 按 userId 限流
@@ -43,6 +43,7 @@ export const AI_RATE_LIMIT = {
   // 轮询端点：任务进行期间会被周期调用，放宽阈值防误伤（仍封死无任务空转滥用）
   mediaPoll: { max: 60, windowMs: 60_000 },
   mediaPrototype: { max: 5, windowMs: 60_000 },
+  aiTask: { max: 5, windowMs: 60_000 },
 } as const
 
 /** 非 AI 的一般用户动作 per-minute 限流（与 AI_RATE_LIMIT 同一进程内存态口径） */
@@ -78,12 +79,22 @@ function purgeStaleEntries() {
   }
 }
 
-setInterval(purgeStaleEntries, 60_000)
+// 清扫定时器懒启动：workerd 禁止在 global scope（模块顶层）设定时器
+// （Disallowed operation within global scope），首次创建 limiter（handler
+// 上下文）时才开启；Node 场景行为不变。
+let purgeTimerStarted = false
+function ensurePurgeTimer() {
+  if (purgeTimerStarted) return
+  purgeTimerStarted = true
+  const timer = setInterval(purgeStaleEntries, 60_000)
+  timer.unref?.()
+}
 
 function getRateLimiter(
   key: string,
   config: RateLimitConfig
 ): RateLimiter<(...args: unknown[]) => boolean> {
+  ensurePurgeTimer()
   const existing = limiterCache.get(key)
   if (existing) {
     existing.lastAccess = Date.now()

package/src/server/lib/sequence-number-retry.ts

@@ -0,0 +1,85 @@
+// 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 编号冲突重试助手（纯模块，不 import prisma——客户端安全，放
+// server/lib/ 而非 serverFns/ 树内：check-serverfn-purity 口径②禁止新增纯
+// helper 模块；跨域复用不互串——bug 域不 import story 域模块）。需求创建
+// （createStoryFn / convertBugToStoryFn）、BUG 创建（createBugFn）、需求转移
+// （story-transfer）共用。
+//
+// 可重试的唯一冲突目标有两类：
+// - "identifier"：并发写撞需求/BUG 的编号唯一键（两事务发出同一个号后先后提交）。
+// - "scope"：项目「首次」建单/建 BUG 的并发竞态——sequence_counters 行尚不存在，
+//   两方 upsert 都走 INSERT 分支，输方拿到 P2002(target=["scope"])
+//   （SequenceCounter.scope @unique，全 schema 唯一挂 scope 的约束）。重试时
+//   计数器行已被赢方建好，upsert 走 update 分支即成。
+//
+// 「计数器落后存量」类冲突（seq <= max）不由此处重试——重试每轮重发同一个号，
+// 结构性无效；需求域由 create-story-internal 发号时以存量 max 为下界自愈。
+
+export const SEQUENCE_NUMBER_MAX_ATTEMPTS = 5;
+
+export interface SequenceRetryOptions {
+  /**
+   * 总尝试次数上限（非「重试次数」）：循环条件 `attempt < maxAttempts`，
+   * 传 5 = 最多调用 run() 5 次（即至多重试 4 次）。默认 SEQUENCE_NUMBER_MAX_ATTEMPTS。
+   * ≤0 / 非整数会被钳制为「至少尝试 1 次」（见实现内 Math.max / Math.floor）。
+   */
+  maxAttempts?: number;
+  /** 耗尽后的友好错误文案，默认「操作失败：编号冲突，请重试」；调用方传各自现有文案 */
+  exhaustedMessage?: string;
+}
+
+/**
+ * 是否为可重试的编号唯一冲突：P2002 且 meta.target 为数组且含
+ * "identifier" 或 "scope"；其余 target / 其他 code / 非 Error / 非对象 → false。
+ */
+export function isSequenceNumberConflict(e: unknown): boolean {
+  if (!(e instanceof Error)) return false;
+  const withCode = e as Error & { code?: unknown; meta?: { target?: unknown } };
+  if (withCode.code !== "P2002") return false;
+  const target = withCode.meta?.target;
+  return Array.isArray(target) && (target.includes("identifier") || target.includes("scope"));
+}
+
+/**
+ * 以固定上限重试 run()（每轮完整重跑事务——发号 upsert 重走、赢方已建的计数器行走
+ * update 分支；run 须幂等可重跑，鉴权/网络面副作用留在 run 之外）；非冲突错误立即
+ * rethrow；冲突耗尽后抛 exhaustedMessage 友好错误（cause 保留最后一次原始 P2002
+ * 供日志排查），各调用方原「循环后 throw」死代码自此真正可达。
+ */
+export async function withSequenceNumberRetry<T>(
+  run: () => Promise<T>,
+  options?: SequenceRetryOptions,
+): Promise<T> {
+  const maxAttempts = options?.maxAttempts ?? SEQUENCE_NUMBER_MAX_ATTEMPTS;
+  const exhaustedMessage = options?.exhaustedMessage ?? "操作失败：编号冲突，请重试";
+  // 钳制下界：≤0 / 小数归一为「至少完整尝试 1 次」，非有限数（NaN/±Infinity）
+  // 同样钳到 1（Math.max(1, Math.floor(NaN)) 仍是 NaN，会让循环零执行、
+  // 耗尽错误的 cause 落空）——保证耗尽错误的 cause 恒有值。
+  const attempts = Number.isFinite(maxAttempts) ? Math.max(1, Math.floor(maxAttempts)) : 1;
+  let lastError: unknown;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      return await run();
+    } catch (e: unknown) {
+      if (!isSequenceNumberConflict(e)) throw e;
+      lastError = e;
+    }
+  }
+  throw new Error(exhaustedMessage, { cause: lastError });
+}

package/src/server/mcp/__tests__/tools.test.ts

@@ -56,6 +56,7 @@ const mocks = vi.hoisted(() => ({
   execRunUpdateMany: vi.fn(),
   projectActivityCreate: vi.fn(),
   transaction: vi.fn(),
+  collabDocumentFindUnique: vi.fn(),
   scheduleFlakyRetry: vi.fn(),
 }));
 
@@ -98,6 +99,14 @@ vi.mock("@allbluecn/database", () => ({
   Prisma: {},
 }));
 
+// 任务 23：report_result fixed 路径接协同门卫——缺省无快照（pass-through
+// 照旧直写，保持本文件既有断言零变化）
+vi.mock("@allbluecn/database/get-prisma", () => ({
+  getPrisma: async () => ({
+    collabDocument: { findUnique: mocks.collabDocumentFindUnique },
+  }),
+}));
+
 vi.mock("@/server/bug-report/webhook-out", () => ({
   fireBugWebhook: mocks.fireBugWebhook,
 }));
@@ -212,6 +221,7 @@ beforeEach(() => {
   vi.clearAllMocks();
   mocks.bugActivityCreate.mockResolvedValue({});
   mocks.bugUpdate.mockResolvedValue({});
+  mocks.collabDocumentFindUnique.mockResolvedValue(null); // 任务 23：无快照（门卫 pass-through）
   mocks.fixRunUpdateMany.mockResolvedValue({ count: 1 });
   mocks.storyFindUnique.mockResolvedValue(null);
   // test 域默认桩：条件更新全部命中、finalize 阶段空集（不触发 run completed）

package/src/server/mcp/tools.ts

@@ -45,6 +45,9 @@
 // failed 进归因队列）。uncertain 既有 retest 语义不参与 flaky 链。
 import { prisma } from "@allbluecn/database";
 import type { Prisma } from "@allbluecn/database";
+import { buildMachineActor } from "@allbluecn/collab-core/actors";
+import { buildRoomName } from "@allbluecn/collab-core/rooms";
+import { withCollabGuard, COLLAB_GUARD_TTL_MS } from "@/server/collab/write-guard";
 import type { McpRequestContext, McpToolCallResult, McpToolDefinition } from "./protocol";
 import {
   claimExecSchema,
@@ -426,8 +429,27 @@ async function reportResultHandler(
 
   // 仅 result=fixed 联动 Bug.state；failed/cannot_reproduce 留人工裁决（§10.2）
   const bugState = args.result === "fixed" ? "fixed" : bug.state;
+
+  // ── Yjs 多人协作 §5.3 机器写入门卫（任务 23）：state 是协同 room 的 Y 属主
+  // 面。快照存在 → 一律转发 collab 内部通道（在线应用 Y 广播 / 离线直落业务
+  // 列）；collab 不可达 → 3s TTL（§5.3.2）排队重试后降级直写（不丢修复结果）。
+  // 机器身份 actor=`agent:<agentName>`：经 collab 落活动时 actorType=agent +
+  // agentName 保留。无 assertWriteAllowed：MCP token → 项目 scope 定位 BUG 即
+  // 信任链（同 requireBug 的 projectId 过滤）。
+  let stateForwarded = false;
   if (args.result === "fixed") {
-    await prisma.bug.update({ where: { id: bug.id }, data: { state: "fixed" } });
+    const guard = await withCollabGuard({
+      roomName: buildRoomName({ kind: "entity-bug", bugId: bug.id }),
+      docId: bug.id,
+      actor: buildMachineActor("agent", run.agentName || "mcp"),
+      patch: { fields: { state: "fixed" } },
+      ttlMs: COLLAB_GUARD_TTL_MS,
+    });
+    stateForwarded = guard.kind === "forwarded";
+    // forwarded 时 state 由 collab 接管（Y 是权威），直写即双写互吞
+    if (!stateForwarded) {
+      await prisma.bug.update({ where: { id: bug.id }, data: { state: "fixed" } });
+    }
   }
 
   await prisma.bugActivity.create({
@@ -438,7 +460,9 @@ async function reportResultHandler(
       agentName: run.agentName,
       action: "fix_completed",
       isAI: true,
-      ...(args.result === "fixed"
+      // forwarded 时 state diff 活动由 collab 侧 writeBugColumns 产出
+      // （actorType=agent）——此处剥离 diff 面防重复流水；run 完成语义照旧
+      ...(args.result === "fixed" && !stateForwarded
         ? { field: "state", oldValue: bug.state, newValue: "fixed" }
         : {}),
       metadata: toJsonValue({ result: args.result }),

package/src/server/middlewares/auth-rate-limit.ts

@@ -20,7 +20,7 @@
  *
  * ⚠️ 架构边界：计数器存于单进程内存（Map），**多实例部署不共享**，
  * 实际阈值 = 配置值 × 实例数。本期不实施分布式限流（Redis 等），
- * 多实例部署落地前不得将本模块视为唯一防线。
+ * 多实例部署落地前不得将本模块视为唯一防线。Cloudflare Workers 多 isolate 同语义；分布式化（Redis/DO）为独立后续任务。
  *
  * 设计要点：
  * - 仅失败尝试计数（登录：用户不存在/密码错误；分享密码：校验失败），
@@ -37,14 +37,22 @@ export const LOGIN_RATE_LIMIT = { max: 5, windowMs: 15 * 60 * 1000 } as const
 export const SHARE_PASSWORD_RATE_LIMIT = { max: 10, windowMs: 15 * 60 * 1000 } as const
 
 const CLEANUP_INTERVAL = 60_000
-const cleanupTimer = setInterval(() => {
-  const now = Date.now()
-  for (const [key, entry] of store) {
-    if (now > entry.resetAt) store.delete(key)
-  }
-}, CLEANUP_INTERVAL)
-// 防止 timer 阻止进程退出（jsdom 环境 setInterval 返回 number，无 unref）
-cleanupTimer.unref?.()
+// 清扫定时器懒启动：workerd 禁止在 global scope（模块顶层）设定时器/fetch
+// （Disallowed operation within global scope），首次进入限流调用（handler
+// 上下文）时才开启；Node 场景行为不变。
+let cleanupStarted = false
+function ensureCleanupTimer() {
+  if (cleanupStarted) return
+  cleanupStarted = true
+  const cleanupTimer = setInterval(() => {
+    const now = Date.now()
+    for (const [key, entry] of store) {
+      if (now > entry.resetAt) store.delete(key)
+    }
+  }, CLEANUP_INTERVAL)
+  // 防止 timer 阻止进程退出（jsdom 环境 setInterval 返回 number，无 unref）
+  cleanupTimer.unref?.()
+}
 
 /** 测试环境豁免（vitest 注入 NODE_ENV=test） */
 export function isAuthRateLimitBypassed(): boolean {
@@ -64,6 +72,7 @@ function isBlocked(key: string, max: number): boolean {
 
 function recordFailure(key: string, windowMs: number): void {
   if (isAuthRateLimitBypassed()) return
+  ensureCleanupTimer()
   const now = Date.now()
   const entry = store.get(key)
   if (!entry || now > entry.resetAt) {

package/src/server/notifications/event-bus.ts

@@ -3,6 +3,9 @@ import { EventEmitter } from 'node:events'
 import type { NotificationSseValue } from '@allbluecn/kernel'
 
 const emitter = new EventEmitter()
+// ⚠️ 进程级总线：EventEmitter 状态存于单进程/isolate 内存，跨 isolate 不投递
+// （Cloudflare Workers 多 isolate 与 Vercel serverless 同级限制）；分布式化
+// （DO pub/sub 等）为独立后续任务。
 emitter.setMaxListeners(0)
 
 export const notificationBus = {