@allbluecn/web-app 0.17.2 → 0.18.1

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

@@ -0,0 +1,162 @@
+// 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 截图成员代理测试——测试即规格（宽范围审查修复）：
+// 未登录 401 / 参数缺失或形态非法 400 / bug 不存在 404 / 非成员与 suspended 403 /
+// 跨 bug blobId 枚举 404（且不触达 blob 表）/ 成员与 owner 放行 /
+// report 顶层 blobId 与 collect screenshots[] 两种快照形态都认。
+// prisma / requireAuth 全 mock（照 bug-collect.test.ts 样板）；成员判定走真实
+// assertBugProjectMember（对 mocked getPrisma 查询），保证权限谓词不脱离实现。
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  requireAuth: vi.fn(),
+  getPrisma: vi.fn(),
+  bugFindUnique: vi.fn(),
+  memberFindUnique: vi.fn(),
+  eventFindMany: vi.fn(),
+  blobFindUnique: vi.fn(),
+}));
+
+vi.mock("@/server/auth-helpers", () => ({
+  requireAuth: mocks.requireAuth,
+}));
+
+vi.mock("@allbluecn/database/get-prisma", () => ({
+  getPrisma: mocks.getPrisma,
+}));
+
+import { handleBugScreenshot } from "../screenshot-handler";
+
+const MEMBER_ID = "user-member-1";
+const BUG_ID = "bug-1";
+const OWNED_BLOB_ID = "blob-owned-by-owner";
+
+function makeRequest(query: Record<string, string>): Request {
+  const params = new URLSearchParams(query);
+  return new Request(`http://localhost:3000/api/bugs/screenshot?${params}`);
+}
+
+describe("handleBugScreenshot（截图成员代理）", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.requireAuth.mockResolvedValue({ user: { id: MEMBER_ID } });
+    mocks.getPrisma.mockResolvedValue({
+      bug: { findUnique: mocks.bugFindUnique },
+      projectMember: { findUnique: mocks.memberFindUnique },
+      bugEvent: { findMany: mocks.eventFindMany },
+      blob: { findUnique: mocks.blobFindUnique },
+    });
+    // 默认链路全通：bug 存在 + 当前用户是 active 成员 + 事件快照含目标 blobId
+    mocks.bugFindUnique.mockResolvedValue({ projectId: "proj-1" });
+    mocks.memberFindUnique.mockResolvedValue({ status: "active" });
+    mocks.eventFindMany.mockResolvedValue([
+      { rawPayload: { blobId: OWNED_BLOB_ID, type: "chrome_ext" } },
+    ]);
+    mocks.blobFindUnique.mockResolvedValue({
+      mimeType: "image/png",
+      bytes: new Uint8Array([137, 80, 78, 71]),
+    });
+  });
+
+  it("未登录（requireAuth 抛 UNAUTHORIZED）→ 401", async () => {
+    mocks.requireAuth.mockRejectedValue(new Error("UNAUTHORIZED"));
+    const res = await handleBugScreenshot(makeRequest({ bugId: BUG_ID, blobId: OWNED_BLOB_ID }));
+    expect(res.status).toBe(401);
+  });
+
+  it.each([
+    ["缺 bugId", { blobId: OWNED_BLOB_ID }],
+    ["缺 blobId", { bugId: BUG_ID }],
+    ["bugId 形态非法", { bugId: "../etc/passwd", blobId: OWNED_BLOB_ID }],
+    ["blobId 形态非法", { bugId: BUG_ID, blobId: "not valid id!" }],
+  ])("%s → 400", async (_name, query) => {
+    const res = await handleBugScreenshot(makeRequest(query));
+    expect(res.status).toBe(400);
+  });
+
+  it("bug 不存在 → 404", async () => {
+    mocks.bugFindUnique.mockResolvedValue(null);
+    const res = await handleBugScreenshot(makeRequest({ bugId: BUG_ID, blobId: OWNED_BLOB_ID }));
+    expect(res.status).toBe(404);
+  });
+
+  it("已登录但非项目成员（无 membership 记录）→ 403", async () => {
+    mocks.memberFindUnique.mockResolvedValue(null);
+    const res = await handleBugScreenshot(makeRequest({ bugId: BUG_ID, blobId: OWNED_BLOB_ID }));
+    expect(res.status).toBe(403);
+  });
+
+  it("suspended 成员视同无权 → 403", async () => {
+    mocks.memberFindUnique.mockResolvedValue({ status: "suspended" });
+    const res = await handleBugScreenshot(makeRequest({ bugId: BUG_ID, blobId: OWNED_BLOB_ID }));
+    expect(res.status).toBe(403);
+  });
+
+  it("跨 bug blobId（不在该 bug 任何事件快照中）→ 404，且不触达 blob 表（防枚举）", async () => {
+    const res = await handleBugScreenshot(
+      makeRequest({ bugId: BUG_ID, blobId: "blob-of-other-bug" }),
+    );
+    expect(res.status).toBe(404);
+    expect(mocks.blobFindUnique).not.toHaveBeenCalled();
+  });
+
+  it("事件快照形态异常（非对象/数组/blobId 非字符串）一律视为无引用 → 404", async () => {
+    mocks.eventFindMany.mockResolvedValue([
+      { rawPayload: null },
+      { rawPayload: ["blob-in-array"] },
+      { rawPayload: { blobId: 42 } },
+    ]);
+    const res = await handleBugScreenshot(makeRequest({ bugId: BUG_ID, blobId: "blob-in-array" }));
+    expect(res.status).toBe(404);
+  });
+
+  it("active 成员 + 顶层 blobId（chrome_ext 形态）→ 200 回二进制", async () => {
+    const res = await handleBugScreenshot(makeRequest({ bugId: BUG_ID, blobId: OWNED_BLOB_ID }));
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/png");
+    expect(res.headers.get("Cache-Control")).toContain("private");
+    expect(Array.from(new Uint8Array(await res.arrayBuffer()))).toEqual([137, 80, 78, 71]);
+    expect(mocks.memberFindUnique).toHaveBeenCalledWith({
+      where: { projectId_userId: { projectId: "proj-1", userId: MEMBER_ID } },
+      select: { status: true },
+    });
+  });
+
+  it("collect screenshots[] 数组形态的快照引用同样放行", async () => {
+    mocks.eventFindMany.mockResolvedValue([
+      { rawPayload: { screenshots: ["blob-collect-1", "blob-collect-2"] } },
+    ]);
+    const res = await handleBugScreenshot(
+      makeRequest({ bugId: BUG_ID, blobId: "blob-collect-2" }),
+    );
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/png");
+  });
+
+  it("事件有引用但 blob 已被清理 → 404", async () => {
+    mocks.blobFindUnique.mockResolvedValue(null);
+    const res = await handleBugScreenshot(makeRequest({ bugId: BUG_ID, blobId: OWNED_BLOB_ID }));
+    expect(res.status).toBe(404);
+  });
+
+  it("owner 本人也放行（建项目时已种 membership 行，owner 即 active 成员）", async () => {
+    mocks.requireAuth.mockResolvedValue({ user: { id: "user-owner-1" } });
+    const res = await handleBugScreenshot(makeRequest({ bugId: BUG_ID, blobId: OWNED_BLOB_ID }));
+    expect(res.status).toBe(200);
+  });
+});

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

@@ -0,0 +1,116 @@
+// 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 截图成员代理（宽范围审查修复）。背景：report-handler / collect-handler
+// 落截图 Blob 时 userId 一律写项目 owner（写侧不动），而 /api/blob/$id 只服务
+// blob 属主 → 非 owner 成员永远看不到 BUG 详情截图。本代理以「bug 项目成员」
+// 为授权口径读同一 Blob：登录 → bug 存在且当前用户是项目成员（owner 建项目时
+// 已种 membership 行，同谓词覆盖）→ 目标 blobId 必须出现在该 bug 任一事件
+// 快照（防跨 bug 枚举）→ 回二进制。
+// 供 routes/api/bugs/screenshot.ts（server.handlers.GET 薄壳）调用；
+// 二进制响应不走 serverFn（JSON RPC 不宜回二进制），照 report 路由模式落路由层。
+import { getPrisma } from "@allbluecn/database/get-prisma";
+import { requireAuth } from "@/server/auth-helpers";
+import { assertBugProjectMember } from "@/server/bug/bug-permissions";
+
+// id 形态白名单（cuid 兼容字符）——query 参数是不可信外部输入，与
+// detail-select.ts 的 BLOB_ID_PATTERN 同口径
+const ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+
+/**
+ * 从单条事件 rawPayload 提取截图 blobId 集合（防御式不抛）：
+ * report chrome_ext 路径记顶层 `blobId`；collect 路径记 `screenshots: string[]`。
+ */
+export function collectEventScreenshotBlobIds(rawPayload: unknown): string[] {
+  if (!rawPayload || typeof rawPayload !== "object" || Array.isArray(rawPayload)) return [];
+  const record = rawPayload as Record<string, unknown>;
+  const ids: string[] = [];
+  if (typeof record.blobId === "string" && ID_PATTERN.test(record.blobId)) {
+    ids.push(record.blobId);
+  }
+  if (Array.isArray(record.screenshots)) {
+    for (const item of record.screenshots) {
+      if (typeof item === "string" && ID_PATTERN.test(item)) ids.push(item);
+    }
+  }
+  return ids;
+}
+
+/**
+ * BUG 截图代理（GET 语义，cookie 鉴权）。
+ * 状态码：401 未登录 / 400 参数缺失或形态非法 / 404 bug 或 blob 不存在
+ * （含 blobId 不属于该 bug 的枚举防御，不区分「存在但跨 bug」避免侧信道）/
+ * 403 已登录但非该项目成员（suspended 视同无权）。
+ */
+export async function handleBugScreenshot(request: Request): Promise<Response> {
+  try {
+    const session = await requireAuth(request);
+    const userId = session.user?.id;
+    if (!userId) return new Response("Unauthorized", { status: 401 });
+
+    const url = new URL(request.url);
+    const bugId = url.searchParams.get("bugId") ?? "";
+    const blobId = url.searchParams.get("blobId") ?? "";
+    if (!ID_PATTERN.test(bugId) || !ID_PATTERN.test(blobId)) {
+      return new Response("Bad request", { status: 400 });
+    }
+
+    // 成员圈定：bug 不存在 → 404；非成员/suspended → 403
+    try {
+      await assertBugProjectMember(bugId, userId);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "";
+      if (message === "BUG 不存在") return new Response("Not found", { status: 404 });
+      return new Response("Forbidden", { status: 403 });
+    }
+
+    const prisma = await getPrisma();
+
+    // 防跨 bug 枚举：目标 blobId 必须出现在该 bug 任一事件快照中。事件数受
+    // 指纹采样窗口约束（窗口内只计数不建事件），全量扫描快照可接受
+    const events = await prisma.bugEvent.findMany({
+      where: { bugId },
+      select: { rawPayload: true },
+    });
+    const knownBlobIds = new Set(
+      events.flatMap((event) => collectEventScreenshotBlobIds(event.rawPayload)),
+    );
+    if (!knownBlobIds.has(blobId)) return new Response("Not found", { status: 404 });
+
+    const blob = await prisma.blob.findUnique({
+      where: { id: blobId },
+      select: { mimeType: true, bytes: true },
+    });
+    if (!blob || !blob.bytes) return new Response("Not found", { status: 404 });
+
+    const body = new Uint8Array(blob.bytes);
+    return new Response(body, {
+      headers: {
+        "Content-Type": blob.mimeType || "application/octet-stream",
+        "Content-Length": String(body.byteLength),
+        "Content-Disposition": `inline; filename*=UTF-8''${encodeURIComponent(blobId)}`,
+        "Cache-Control": "private, max-age=31536000, immutable",
+      },
+    });
+  } catch (error) {
+    // requireAuth 抛 UnauthorizedError（message=UNAUTHORIZED）→ 401，其余 500
+    // （与 /api/blob/$id 同口径）
+    const message = error instanceof Error ? error.message : "读取失败";
+    const status = message === "UNAUTHORIZED" ? 401 : 500;
+    return new Response(message, { status });
+  }
+}

package/src/server/design/annotation-prompt.ts

@@ -0,0 +1,61 @@
+// 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 { resolveSystemPrompt } from "@/server/ai-gateway"
+
+/**
+ * buildFillPrompt 的入参形状。
+ * editableProps 类型宽松（type 为 string），兼容 zod schema 推断结果与 EditablePropField 子集。
+ */
+export interface FillComponentInfo {
+  type: string
+  name: string
+  editableProps?: Array<{ key: string; label: string; type: string }>
+  commentTemplate?: string
+  overrides?: Record<string, unknown>
+}
+
+/**
+ * 构建 AI 注释填充的 systemPrompts（模板正文已收编到 PromptRegistry 的 design.fill-annotation）。
+ * componentInfo 承载「类型/名称/可编辑属性/注释模板」整块，由本函数拼装。
+ */
+export async function buildFillPrompt(info: FillComponentInfo): Promise<string[]> {
+  const propList = info.editableProps?.length
+    ? info.editableProps
+        .map((p) => {
+          const val = info.overrides?.[p.key]
+          const valHint =
+            val !== undefined && val !== ""
+              ? `（当前值：${typeof val === "object" ? JSON.stringify(val) : String(val)}）`
+              : ""
+          return `- ${p.label}（${p.key}）${valHint}`
+        })
+        .join("\n")
+    : "（无声明属性）"
+
+  const templateSection = info.commentTemplate
+    ? `\n注释模板（保持此 HTML 结构不变，在每个字段文字后面补充具体内容）：\n${info.commentTemplate}\n`
+    : "\n（无预设模板，请生成简洁的描述性 HTML 段落）\n"
+
+  const componentInfo = `- 类型：${info.type}
+- 名称：${info.name}
+- 可编辑属性：
+${propList}
+${templateSection}`
+
+  return resolveSystemPrompt("design.fill-annotation", { componentInfo })
+}

package/src/server/email/templates/auth/verify-email.tsx

@@ -1,4 +1,4 @@
-import { Link, Section, Text } from '@react-email/components'
+import { Section, Text } from '@react-email/components'
 import { EmailLayout } from '../_base/email-layout'
 import { EmailButton } from '../_base/button'
 import { registerTemplate, type EmailLocale } from '../../registry'

package/src/server/entitlements.ts

@@ -85,9 +85,15 @@ export async function requireFeature(
 
   if (meta.tier === 'oss') return
 
-  // 点式豁免（P3/P4e）：沙箱与媒体生成为 desktop 用户 BYOK 自担能力（P4c §8.5 承诺），
-  // 桌面端无订阅体系。仅豁免这两个 key——不引入「desktop 全放行」的机制级旁路。
-  if ((feature === 'sandboxExecution' || feature === 'mediaGeneration') && isDesktopDeployment()) return
+  // 点式豁免（P3/P4e）：沙箱/媒体生成/AI 生成用例为 desktop 用户 BYOK 自担能力（P4c §8.5 承诺，
+  // testcase 生成编排同款口径），桌面端无订阅体系。仅豁免这三个 key——不引入「desktop 全放行」的机制级旁路。
+  if (
+    (feature === 'sandboxExecution' ||
+      feature === 'mediaGeneration' ||
+      feature === 'testGeneration') &&
+    isDesktopDeployment()
+  )
+    return
 
   if (meta.module && getProService(meta.module as ProFeature) === null) {
     throw new FeatureUnavailableError(feature)

package/src/server/fetch-guard.ts

@@ -27,12 +27,23 @@ export class FetchGuardError extends Error {
 }
 
 export interface FetchGuardOptions {
-  /** 显式允许私网/回环目标（SearXNG 等自托管内网服务场景） */
+  /** 显式允许私网/回环目标（SearXNG 等自托管内网服务、桌面端本地 Ollama 场景） */
   allowPrivate?: boolean
   /** 主机白名单（提供时仅放行列表内主机，与 allowPrivate 独立判定） */
   allowedHosts?: string[]
 }
 
+/**
+ * 桌面端运行时判定：desktop 端以 Tauri sidecar 形态单机部署，数据库走
+ * DATABASE_PROVIDER=sqlite；此时 localhost/私网是合法服务地址（如本地
+ * Ollama http://localhost:11434），BYOK 请求的私网 baseUrl 应放行。
+ * 云端 SaaS 为 postgres，恒返回 false——SSRF 防护默认语义不变（未知取值
+ * 按云端处理，fail-closed）。
+ */
+export function isDesktopRuntime(): boolean {
+  return process.env.DATABASE_PROVIDER === "sqlite"
+}
+
 /**
  * 判定点分十进制 IPv4 是否落在私网/回环/链路本地/未指定/组播保留段。
  * 这些地址段是 SSRF 的主要攻击面：本机服务（127.0.0.1）、内网资产（10/172.16/192.168）、
@@ -155,6 +166,7 @@ export function assertFetchableUrl(
   const isPrivate =
     host === "localhost" ||
     host.endsWith(".localhost") ||
+    host.endsWith(".local") ||
     host.endsWith(".internal") ||
     (host.includes(":") ? isPrivateIPv6(host) : isPrivateIPv4(normalizeIntegerIp(host) ?? host))
 

package/src/server/harness/attach-guards.ts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+import { getPrisma } from "@allbluecn/database/get-prisma"
+
+/** P4d 回流守卫（ADR 34）：源 GenerationRun 与目标实体归属校验，非本人一律按 not found 拒绝（不泄露存在性）。 */
+
+export async function assertRunOwnership(generationRunId: string, userId: string) {
+  const prisma = await getPrisma()
+  const run = await prisma.generationRun.findFirst({ where: { id: generationRunId, userId } })
+  if (!run) throw new Error("Generation run not found")
+  return run
+}
+
+export async function assertStoryOwnership(storyId: string, userId: string) {
+  const prisma = await getPrisma()
+  const story = await prisma.story.findFirst({ where: { id: storyId, project: { ownerId: userId } } })
+  if (!story) throw new Error("Story not found")
+  return story
+}
+
+export async function assertKbOwnership(kbId: string, userId: string) {
+  const prisma = await getPrisma()
+  const kb = await prisma.knowledgeBase.findFirst({ where: { id: kbId, userId, isDeleted: false } })
+  if (!kb) throw new Error("Knowledge base not found")
+  return kb
+}
+
+export async function assertDesignOwnership(designId: string, userId: string) {
+  const prisma = await getPrisma()
+  const prd = await prisma.design.findFirst({ where: { id: designId, userId } })
+  if (!prd) throw new Error("PRD not found")
+  return prd
+}

package/src/server/iteration/transfer-internal.ts

@@ -0,0 +1,86 @@
+// 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 { getPrisma } from "@allbluecn/database/get-prisma"
+import { deriveIterationStatus, toDatePart } from "@/lib/iteration/status";
+
+/** 项目有效成员校验（口径同 testcase-crud / deleteBugFn：suspended 视同无权限） */
+async function assertProjectMembership(projectId: string, userId: string) {
+  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("无权限操作该项目的迭代");
+  }
+}
+
+/** 内部复用（用户勾选路径 + autoRollover）：目标校验 + 幂等 where 批量转移（规格 §3.5） */
+export async function transferStoriesInternal(
+  sourceIterationId: string,
+  targetIterationId: string,
+  storyIds?: string[],
+  userId?: string,
+): Promise<number> {
+  const prisma = await getPrisma();
+  const target = await prisma.iteration.findUnique({
+    where: { id: targetIterationId },
+    select: { startDate: true, endDate: true, archived: true, name: true, projectId: true },
+  });
+  if (!target || target.archived) throw new Error("迭代不存在");
+  if (deriveIterationStatus(toDatePart(target.startDate), toDatePart(target.endDate)) === "completed") {
+    throw new Error("不能将需求加入已完成的迭代");
+  }
+  // 用户发起的转移：源/目标迭代所属项目都须为有效成员（SEC-03）；
+  // autoRollover 系统路径（userId 缺省）不做成员校验
+  if (userId) {
+    const source = await prisma.iteration.findUnique({
+      where: { id: sourceIterationId },
+      select: { projectId: true },
+    });
+    if (!source) throw new Error("迭代不存在");
+    await assertProjectMembership(source.projectId, userId);
+    await assertProjectMembership(target.projectId, userId);
+  }
+  const unfinished = await prisma.story.findMany({
+    where: {
+      iterationId: sourceIterationId,
+      state: { notIn: ["done", "cancelled"] },
+      ...(storyIds ? { id: { in: storyIds } } : {}),
+    },
+    select: { id: true },
+  });
+  if (unfinished.length === 0) return 0;
+  const ids = unfinished.map((s) => s.id);
+  let actorId = userId;
+  if (!actorId) {
+    const owner = await prisma.project.findUnique({ where: { id: target.projectId }, select: { ownerId: true } });
+    actorId = owner!.ownerId!;
+  }
+  await prisma.story.updateMany({ where: { id: { in: ids } }, data: { iterationId: targetIterationId } });
+  await prisma.storyActivity.createMany({
+    data: ids.map((storyId) => ({
+      storyId,
+      userId: actorId,
+      action: "iteration_changed",
+      field: "iterationId",
+      newValue: target.name,
+    })),
+  });
+  return ids.length;
+}

package/src/server/knowledge/kb-doc-search.ts

@@ -0,0 +1,113 @@
+// 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/>.
+
+// 知识库文档搜索共享工具（story 关联弹窗 / 工作空间快捷文档弹窗共用）。
+// 服务端工具模块，仅供 serverFn 文件 import。
+
+import { getPrisma } from "@allbluecn/database/get-prisma"
+import {
+  GENERAL_GROUP_TABLES,
+  EXTERNAL_ID_PREFIX,
+  externalDocId,
+  type GeneralGroup,
+} from "./kb-general";
+
+export const SEARCH_DOC_SELECT = {
+  id: true,
+  title: true,
+  parentId: true,
+  icon: true,
+  type: true,
+  kb: { select: { id: true, name: true, icon: true } },
+} as const;
+
+/** 搜索/列表行 = DocBrief + 树形父引用（树形渲染用） */
+export type SearchDocRow = {
+  id: string;
+  title: string;
+  kbId: string;
+  kbName: string;
+  kbIcon: string;
+  docIcon: string | null;
+  parentId: string | null;
+};
+
+export function toSearchDocRow(doc: {
+  id: string;
+  title: string;
+  parentId: string | null;
+  icon: string | null;
+  kb: { id: string; name: string; icon: string };
+}): SearchDocRow {
+  return {
+    id: doc.id,
+    title: doc.title,
+    kbId: doc.kb.id,
+    kbName: doc.kb.name,
+    kbIcon: doc.kb.icon,
+    docIcon: doc.icon,
+    parentId: doc.parentId,
+  };
+}
+
+/** 通用组条目搜索（复用 story 侧收藏过滤逻辑）；summary 无实体表返回空 */
+export async function searchGeneralGroupDocs(
+  group: GeneralGroup,
+  userId: string,
+  query: string,
+): Promise<SearchDocRow[]> {
+  if (group === "summary") return [];
+  const prisma = await getPrisma();
+  const favoriteIds = await prisma.articleFavorite
+    .findMany({ where: { entityType: group, userId }, select: { entityId: true } })
+    .then((r) => r.map((f) => f.entityId));
+
+  const rows = await (
+    prisma[GENERAL_GROUP_TABLES[group]!] as unknown as {
+      findMany: (args: Record<string, unknown>) => Promise<Array<{ id: string; title: string }>>;
+    }
+  ).findMany({
+    where: {
+      isDeleted: false,
+      ...(query ? { title: { contains: query, mode: "insensitive" as const } } : {}),
+      OR: [{ userId }, ...(favoriteIds.length > 0 ? [{ id: { in: favoriteIds } }] : [])],
+    },
+    select: { id: true, title: true },
+    orderBy: { updatedAt: "desc" as const },
+    take: 100,
+  });
+
+  return rows.map((row) => ({
+    id: externalDocId(group, row.id),
+    title: row.title,
+    kbId: `${EXTERNAL_ID_PREFIX}${group}`,
+    kbName: group,
+    kbIcon: "book",
+    docIcon: null,
+    parentId: null,
+  }));
+}
+
+/** 当前用户可作为快捷文档来源的 team 库 id 集合 */
+export async function listUserTeamKbIds(userId: string): Promise<string[]> {
+  const prisma = await getPrisma();
+  const rows = await prisma.knowledgeBase.findMany({
+    where: { visibility: "team", isDeleted: false, userId },
+    select: { id: true },
+  });
+  return rows.map((r) => r.id);
+}