@allbluecn/web-app 0.18.2 → 0.19.0

package/src/server/collab/__tests__/write-guard.test.ts

@@ -0,0 +1,373 @@
+// 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/>.
+
+// 写入门卫测试（Yjs 多人协作 §5.3，任务 17）——§5.3 第 1/3 条的 web 侧：
+// - 无 Y 属主字段（元数据 only）/ 无快照 / content 形状不支持 → 照旧直写
+//   （pass-through，零行为变化，不触 fetch）
+// - 快照存在 + content → 一律转发 /internal/apply（活跃判定在 collab 侧，
+//   web 进程不做活跃判定——复审修正），信封（域/actor/roomName/patch）齐备
+// - collab 不可达 → 内存排队重试（请求内同步），TTL 后降级直写（degraded，
+//   信任重种子化）；排队重试期间恢复 → 转发成功
+// - COLLAB_INTERNAL_URL 未配置 → 降级直写（warn-once，可用性优先）
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import {
+  INTERNAL_DOMAIN_APPLY,
+  INTERNAL_SIGNATURE_HEADER,
+  verifyInternalRequest,
+} from "@allbluecn/collab-core/internal";
+
+const M = vi.hoisted(() => ({
+  collabDocumentFindUnique: vi.fn(),
+}));
+
+vi.mock("@allbluecn/database/get-prisma", () => ({
+  getPrisma: async () => ({
+    collabDocument: { findUnique: M.collabDocumentFindUnique },
+  }),
+}));
+
+import { withCollabGuard } from "../write-guard";
+
+const SECRET = "test-web-guard-secret";
+const ROOM = "doc:knowledge:doc-1";
+const URL_BASE = "http://collab.test:3030";
+
+/** fetch mock 应答工厂 */
+function okResponse(body: unknown = { applied: "ydoc" }): Response {
+  return new Response(JSON.stringify(body), { status: 202 });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.stubEnv("COLLAB_SECRET", SECRET);
+  vi.stubEnv("COLLAB_INTERNAL_URL", URL_BASE);
+  // 缺省 fetch 空桩：断言「未触网络」与调用参数都走同一 mock
+  vi.stubGlobal("fetch", vi.fn());
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+});
+
+function lastFetchCall(): { url: string; init: RequestInit } {
+  const fetchMock = vi.mocked(globalThis.fetch);
+  expect(fetchMock).toHaveBeenCalled();
+  const call = fetchMock.mock.calls[fetchMock.mock.calls.length - 1]!;
+  return { url: String(call[0]), init: call[1] ?? {} };
+}
+
+describe("withCollabGuard（§5.3 写入路由门卫）", () => {
+  it("元数据 only（content 缺席）→ 照旧直写，不查快照不触网络", async () => {
+    const outcome = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { content: undefined },
+    });
+
+    expect(outcome).toEqual({ kind: "pass-through", reason: "no-y-owned-field" });
+    expect(M.collabDocumentFindUnique).not.toHaveBeenCalled();
+    expect(vi.mocked(globalThis.fetch)).not.toHaveBeenCalled();
+  });
+
+  it("content 非 {html:string} 形状（历史 {text}/string）→ 照旧直写", async () => {
+    const outcome = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { content: { text: "旧格式" } },
+    });
+
+    expect(outcome).toEqual({ kind: "pass-through", reason: "unsupported-content" });
+    expect(M.collabDocumentFindUnique).not.toHaveBeenCalled();
+  });
+
+  it("无 CollabDocument → 照旧直写（零行为变化），不触网络", async () => {
+    M.collabDocumentFindUnique.mockResolvedValue(null);
+
+    const outcome = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { content: { html: "<p>新</p>" } },
+    });
+
+    expect(outcome).toEqual({ kind: "pass-through", reason: "no-snapshot" });
+    expect(M.collabDocumentFindUnique).toHaveBeenCalledWith({
+      where: { roomName: ROOM },
+      select: { id: true },
+    });
+    expect(vi.mocked(globalThis.fetch)).not.toHaveBeenCalled();
+  });
+
+  it("C1：快照命中后先属主预检，失败即短路（不触网络、不重试）", async () => {
+    M.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+
+    await expect(
+      withCollabGuard({
+        roomName: ROOM,
+        docId: "doc-1",
+        actor: "attacker",
+        patch: { content: { html: "<p>越权写入</p>" } },
+        assertWriteAllowed: async () => {
+          throw new Error("未找到或无权限");
+        },
+      }),
+    ).rejects.toThrow("未找到或无权限");
+
+    // 关键断言：mutation 未发生——零转发请求（Y 态/业务列不会被触达）
+    expect(vi.mocked(globalThis.fetch)).not.toHaveBeenCalled();
+  });
+
+  it("C1：无快照（pass-through）不执行属主预检（非协同文档零额外查询）", async () => {
+    M.collabDocumentFindUnique.mockResolvedValue(null);
+    const assertWriteAllowed = vi.fn();
+
+    const outcome = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { content: { html: "<p>新</p>" } },
+      assertWriteAllowed,
+    });
+
+    expect(outcome).toEqual({ kind: "pass-through", reason: "no-snapshot" });
+    expect(assertWriteAllowed).not.toHaveBeenCalled();
+  });
+
+  it("快照存在 → 一律转发 /internal/apply（信封齐备，web 不做活跃判定）", async () => {
+    M.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(okResponse({ applied: "ydoc", connections: 2 })));
+
+    const outcome = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { content: { html: "<p>转发</p>" } },
+    });
+
+    expect(outcome).toEqual({ kind: "forwarded" });
+    const { url, init } = lastFetchCall();
+    expect(url).toBe(`${URL_BASE}/internal/apply`);
+    expect(init.method).toBe("POST");
+    const body = String(init.body);
+    const parsed = JSON.parse(body);
+    expect(parsed).toMatchObject({
+      domain: INTERNAL_DOMAIN_APPLY,
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { content: { html: "<p>转发</p>" } },
+    });
+    // 信封可被 collab 侧同密钥验签通过（ts 在时效窗内）
+    const verified = verifyInternalRequest({
+      secret: SECRET,
+      domain: INTERNAL_DOMAIN_APPLY,
+      body,
+      signature: (init.headers as Record<string, string>)[INTERNAL_SIGNATURE_HEADER],
+    });
+    expect(verified.ok).toBe(true);
+  });
+
+  it("快照存在但转发响应非 2xx → 持续失败至 TTL 降级直写（degraded）", async () => {
+    M.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("{}", { status: 500 })));
+    const sleep = vi.fn().mockResolvedValue(undefined);
+
+    const outcome = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { content: { html: "<p>x</p>" } },
+      ttlMs: 50,
+      sleep,
+    });
+
+    expect(outcome).toEqual({ kind: "degraded", reason: "unreachable" });
+    // 至少两次尝试（排队重试），间隔受 sleep 节流
+    expect(vi.mocked(globalThis.fetch).mock.calls.length).toBeGreaterThanOrEqual(2);
+    expect(sleep).toHaveBeenCalled();
+  });
+
+  it("排队重试期间恢复（首次失败、二次成功）→ forwarded", async () => {
+    M.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    vi.stubGlobal(
+      "fetch",
+      vi
+        .fn()
+        .mockRejectedValueOnce(new Error("connection refused"))
+        .mockResolvedValue(okResponse()),
+    );
+
+    const outcome = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { content: { html: "<p>x</p>" } },
+      ttlMs: 5000,
+      sleep: async () => {},
+    });
+
+    expect(outcome).toEqual({ kind: "forwarded" });
+    expect(vi.mocked(globalThis.fetch).mock.calls).toHaveLength(2);
+  });
+
+  it("COLLAB_INTERNAL_URL 未配置 → 降级直写（warn-once，不触网络）", async () => {
+    vi.stubEnv("COLLAB_INTERNAL_URL", "");
+    M.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const first = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { content: { html: "<p>x</p>" } },
+    });
+    const second = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-2",
+      actor: "u1",
+      patch: { content: { html: "<p>y</p>" } },
+    });
+
+    expect(first).toEqual({ kind: "degraded", reason: "no-url" });
+    expect(second).toEqual({ kind: "degraded", reason: "no-url" });
+    expect(vi.mocked(globalThis.fetch)).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledTimes(1); // warn-once
+    warn.mockRestore();
+  });
+
+  // R 审查修复（Minor）：secret 缺失与 no-url 同口径——降级直写而非抛错 500
+  it("COLLAB_SECRET 未配置 → 降级直写（warn-once，不触网络不抛错）", async () => {
+    vi.stubEnv("COLLAB_SECRET", "");
+    M.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const first = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { content: { html: "<p>x</p>" } },
+    });
+    const second = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-2",
+      actor: "u1",
+      patch: { content: { html: "<p>y</p>" } },
+    });
+
+    expect(first).toEqual({ kind: "degraded", reason: "no-secret" });
+    expect(second).toEqual({ kind: "degraded", reason: "no-secret" });
+    expect(vi.mocked(globalThis.fetch)).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledTimes(1); // warn-once
+    warn.mockRestore();
+  });
+
+  it("信封签名对 body 逐字节绑定（篡改即失效）——防 ticket 域混用", async () => {
+    M.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(okResponse()));
+
+    await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { content: { html: "<p>x</p>" } },
+    });
+
+    const { init } = lastFetchCall();
+    const body = String(init.body);
+    const signature = (init.headers as Record<string, string>)[INTERNAL_SIGNATURE_HEADER];
+    const expected = createHmac("sha256", SECRET)
+      .update(`${INTERNAL_DOMAIN_APPLY}\n${body}`)
+      .digest("hex");
+    expect(
+      signature!.length === expected.length &&
+        timingSafeEqual(Buffer.from(signature!), Buffer.from(expected)),
+    ).toBe(true);
+  });
+
+  // ── 任务 21：fields patch（Story 8 字段——entity room 的 Y 属主面）─────
+
+  it("fields only（无 content）+ 快照 → 转发，payload 携带 fields（无 content 键）", async () => {
+    M.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(okResponse()));
+
+    const outcome = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { fields: { state: "todo", labelIds: ["l-1"] } },
+    });
+
+    expect(outcome).toEqual({ kind: "forwarded" });
+    const parsed = JSON.parse(String(lastFetchCall().init.body));
+    expect(parsed.patch).toEqual({ fields: { state: "todo", labelIds: ["l-1"] } });
+  });
+
+  it("content + fields 混合 patch → 两者都进转发载荷（Story 描述 + 字段）", async () => {
+    M.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(okResponse()));
+
+    const outcome = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: {
+        content: { html: "<p>新</p>", markdown: "新" },
+        fields: { name: "新名" },
+      },
+    });
+
+    expect(outcome).toEqual({ kind: "forwarded" });
+    const parsed = JSON.parse(String(lastFetchCall().init.body));
+    expect(parsed.patch).toEqual({
+      content: { html: "<p>新</p>", markdown: "新" },
+      fields: { name: "新名" },
+    });
+  });
+
+  it("patch 全空（content 缺席 + fields 空）→ pass-through 不查快照（零行为变化）", async () => {
+    const outcome = await withCollabGuard({
+      roomName: ROOM,
+      docId: "doc-1",
+      actor: "u1",
+      patch: { fields: {} },
+    });
+
+    expect(outcome).toEqual({ kind: "pass-through", reason: "no-y-owned-field" });
+    expect(M.collabDocumentFindUnique).not.toHaveBeenCalled();
+  });
+
+  it("fields only 快照命中 → 属主预检照旧执行（C1 对字段面同样生效）", async () => {
+    M.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    const assertWriteAllowed = vi.fn().mockRejectedValue(new Error("未找到或无权限"));
+
+    await expect(
+      withCollabGuard({
+        roomName: ROOM,
+        docId: "doc-1",
+        actor: "attacker",
+        patch: { fields: { state: "todo" } },
+        assertWriteAllowed,
+      }),
+    ).rejects.toThrow("未找到或无权限");
+    expect(vi.mocked(globalThis.fetch)).not.toHaveBeenCalled();
+  });
+});

package/src/server/collab/knowledge-additions.ts

@@ -0,0 +1,37 @@
+// 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/>.
+
+// 知识库 web 自定义节点追加集已于任务 16 下沉 @allbluecn/collab-core
+// （collab 回写导出器与 web 种子化必须用同一扩展组合，而 apps 间无依赖
+// 关系，故实现移入共享包）。本文件保留为兼容 re-export：seed.ts 与
+// 对账测试（__tests__/knowledge-additions.test.ts，对比 web 编辑器扩展集）
+// 的既有引用路径不变。
+
+export {
+  createKnowledgeDocAdditions,
+  KnowledgeMention,
+  KnowledgeDocCard,
+  KnowledgeTocNode,
+  KnowledgeMindmap,
+  KnowledgeAnnotation,
+  KnowledgeImageUpload,
+  KnowledgeAiSuggestionMark,
+  KnowledgeIndent,
+  KnowledgeNodeBackground,
+  KnowledgeNodeAlignment,
+  KnowledgeTocAnchor,
+} from "@allbluecn/collab-core/knowledge-additions";

package/src/server/collab/reindex-endpoint.ts

@@ -0,0 +1,75 @@
+// 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/>.
+
+// collab → web 向量索引重建通知接收端（Yjs 多人协作 §5.2 回写，任务 16；
+// R7 裁决升级：随任务 17 统一切到内部 HMAC 信封——签名体含 domain+ts，
+// 验签拒时钟偏移 >60s，与 ticket 同密钥不同 payload 域防重放）：
+// 协同落库回写业务列后，collab 服务 fire-and-forget POST 本端点，web 复用
+// 现有 indexDocumentById 重建该文档的向量索引（索引逻辑单源在 web——
+// @/server/ai-gateway 的 apiKey 解密与 @/lib/vector-store 不可跨 app 复制）。
+//
+// 认证：信封见 @allbluecn/collab-core/internal（server-only 子路径）。
+// 缺 COLLAB_SECRET → 503 fail-closed（比放行更安全：索引滞后可接受，
+// 未认证写入不可接受）。
+//
+// 路由薄壳见 routes/api/internal/collab-reindex.ts（server.handlers 豁免），
+// 业务在本文件以便单测直接调用。
+
+import {
+  INTERNAL_DOMAIN_REINDEX,
+  INTERNAL_SIGNATURE_HEADER,
+  verifyInternalRequest,
+} from "@allbluecn/collab-core/internal";
+import { indexDocumentById } from "@/server/knowledge/knowledge-index-utils";
+
+/** 签名请求头名（信封模块常量的再导出，调用方免再 import） */
+export const REINDEX_SIGNATURE_HEADER = INTERNAL_SIGNATURE_HEADER;
+
+export async function handleCollabReindex(request: Request): Promise<Response> {
+  const secret = process.env.COLLAB_SECRET;
+  if (!secret) {
+    return Response.json({ error: "internal channel unavailable" }, { status: 503 });
+  }
+  const raw = await request.text();
+  const verified = verifyInternalRequest({
+    secret,
+    domain: INTERNAL_DOMAIN_REINDEX,
+    body: raw,
+    signature: request.headers.get(REINDEX_SIGNATURE_HEADER) ?? "",
+  });
+  if (!verified.ok) {
+    console.warn(
+      `[collab-reindex] 信封验签拒绝 reason=${verified.reason}（索引通知丢弃，下次落库重试）`,
+    );
+    return Response.json({ error: "unauthorized" }, { status: 401 });
+  }
+
+  const payload = verified.payload as { docId?: unknown };
+  if (typeof payload.docId !== "string" || payload.docId.length === 0) {
+    return Response.json({ error: "docId required" }, { status: 400 });
+  }
+  const docId = payload.docId;
+
+  // fire-and-forget：与 updateDocumentFn 的索引口径一致——失败不阻塞响应，
+  // 但不静默（warn 留排查线索）。索引逻辑内部自查文档存在性（已删文档返回 0）。
+  indexDocumentById(docId).catch((err: unknown) => {
+    console.warn(
+      `知识库向量索引重建失败 documentId=${docId}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  });
+  return Response.json({ queued: true }, { status: 202 });
+}

package/src/server/collab/resolve.ts

@@ -0,0 +1,122 @@
+// 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/>.
+
+// 协同归属解析查询层（Yjs 多人协作 §4.1）：实体 → 工作空间反查。
+// 纯查询 helper（非 serverFn）：只做归属链读取，不做权限裁决——
+// 授权判定（assertCollabAccess）在后续任务中组合这些 resolver 实现。
+// 编辑授权域 = 实体归属链反查的工作空间，与用户当前路由无关（无全局工作空间概念）。
+
+import { prisma } from "@allbluecn/database";
+
+/** 支持归属反查的协同实体类型（room 命名 `entity:story|bug|case:{id}`） */
+export type CollabEntityType = "story" | "bug" | "case";
+
+/** 知识库协同访问形态：private 仅 owner（不协同）；open 限列出的工作空间成员 */
+export type KbAccess =
+  | { kind: "private" }
+  | { kind: "open"; workspaceIds: string[] };
+
+/** Story/Bug/TestCase → 所属 Project 的工作空间 id（同构查询形状） */
+const PROJECT_WS_SELECT = {
+  project: { select: { workspaceId: true } },
+} as const;
+
+/** 按 entity 类型分派反查（Prisma delegate 联合调用签名不兼容，须显式分派） */
+const findEntityWithProject: Record<
+  CollabEntityType,
+  (id: string) => Promise<{ project: { workspaceId: string | null } } | null>
+> = {
+  story: (id) =>
+    prisma.story.findUnique({ where: { id }, select: PROJECT_WS_SELECT }),
+  bug: (id) =>
+    prisma.bug.findUnique({ where: { id }, select: PROJECT_WS_SELECT }),
+  case: (id) =>
+    prisma.testCase.findUnique({ where: { id }, select: PROJECT_WS_SELECT }),
+};
+
+/**
+ * Story / Bug / TestCase → Project.workspaceId 反查。
+ * 实体不存在、或项目未挂工作空间（workspaceId=null，私人项目）→ null（不开放协同）。
+ */
+export async function resolveEntityWorkspace(
+  entityType: CollabEntityType,
+  entityId: string,
+): Promise<string | null> {
+  const row = await findEntityWithProject[entityType](entityId);
+  return row?.project.workspaceId ?? null;
+}
+
+/**
+ * 知识库文档协同访问解析（visibility 三态 + 工作空间归属）。
+ * - private（或 KB 不存在，fail-closed）→ { kind: "private" }
+ * - team/general → { kind: "open", workspaceIds }：挂在工作空间的三条路径取并集
+ *   去重升序（直挂 workspaceId、WorkspaceKnowledgeBase join、
+ *   ProjectKnowledgeBase→Project.workspaceId），
+ *   未挂任何工作空间时为空集（无人可协同，公开可读不放大为可编）。
+ */
+export async function resolveKbAccess(kbId: string): Promise<KbAccess> {
+  const kb = await prisma.knowledgeBase.findUnique({
+    where: { id: kbId },
+    select: {
+      visibility: true,
+      workspaceId: true,
+      workspaceLinks: { select: { workspaceId: true } },
+      projectLinks: { select: { project: { select: { workspaceId: true } } } },
+    },
+  });
+  if (!kb || kb.visibility === "private") return { kind: "private" };
+  const ids = new Set<string>();
+  if (kb.workspaceId) ids.add(kb.workspaceId);
+  for (const link of kb.workspaceLinks) ids.add(link.workspaceId);
+  for (const link of kb.projectLinks) {
+    if (link.project.workspaceId) ids.add(link.project.workspaceId);
+  }
+  return { kind: "open", workspaceIds: [...ids].sort() };
+}
+
+/**
+ * Design（文档/画布）无归属字段，经 StoryDesignLink→Story→Project 间接反查。
+ * 返回去重后的工作空间 id 集合；无关联或关联项目均未挂工作空间 → 空集（视为私人）。
+ */
+export async function resolveDesignWorkspaces(
+  designId: string,
+): Promise<string[]> {
+  const links = await prisma.storyDesignLink.findMany({
+    where: { designId },
+    select: { story: { select: { project: { select: { workspaceId: true } } } } },
+  });
+  const ids = new Set<string>();
+  for (const link of links) {
+    if (link.story.project.workspaceId) ids.add(link.story.project.workspaceId);
+  }
+  return [...ids].sort();
+}
+
+/**
+ * 用户是否为工作空间成员（status 精确匹配，默认 active）。
+ * WorkspaceMember 以 (workspaceId, userId) 唯一，count 命中即成员。
+ */
+export async function isWorkspaceMember(
+  workspaceId: string,
+  userId: string,
+  status = "active",
+): Promise<boolean> {
+  const count = await prisma.workspaceMember.count({
+    where: { workspaceId, userId, status },
+  });
+  return count > 0;
+}