@allbluecn/web-app 0.5.0 → 0.5.1

package/src/server/serverFns/__tests__/project-kb.test.ts

@@ -0,0 +1,147 @@
+// 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 { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("@tanstack/react-start", () => ({
+  createServerFn: (config: any) => {
+    const api: any = {
+      _validator: undefined,
+      validator(schema: any) {
+        this._validator = schema;
+        return this;
+      },
+      handler(fn: Function) {
+        const wrapped = async (args: any) => {
+          let data = args?.data;
+          if (this._validator && data !== undefined) {
+            data = this._validator.parse ? this._validator.parse(data) : data;
+          }
+          return fn({ data });
+        };
+        return wrapped;
+      },
+    };
+    return api;
+  },
+}));
+
+vi.mock("@tanstack/react-start/server", () => ({ getRequest: () => ({}) }));
+
+const mocks = vi.hoisted(() => ({
+  pkbFindMany: vi.fn(),
+  pkbDeleteMany: vi.fn(),
+  pkbCreateMany: vi.fn(),
+  kbFindMany: vi.fn(),
+  projectFindMany: vi.fn(),
+  kbFindFirst: vi.fn(),
+  transaction: vi.fn(),
+  currentSession: vi.fn(),
+}));
+
+vi.mock("@allbluecn/database", () => {
+  const prisma = {
+    projectKnowledgeBase: {
+      findMany: mocks.pkbFindMany,
+      deleteMany: mocks.pkbDeleteMany,
+      createMany: mocks.pkbCreateMany,
+    },
+    knowledgeBase: { findMany: mocks.kbFindMany, findFirst: mocks.kbFindFirst },
+    project: { findMany: mocks.projectFindMany },
+    $transaction: mocks.transaction,
+  };
+  return { prisma, Prisma: {} };
+});
+
+vi.mock("@/server/auth-helpers", () => ({ requireAuth: mocks.currentSession }));
+vi.mock("@/server/permissions", () => ({ requirePermission: vi.fn().mockResolvedValue(undefined) }));
+vi.mock("@/server/audit", () => ({ auditLog: vi.fn() }));
+
+import { setProjectKbsFn, listProjectKbsFn } from "../project";
+import { setKbProjectsFn, listKbProjectsFn } from "../knowledge";
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.currentSession.mockResolvedValue({ user: { id: "u1" } });
+});
+
+describe("setProjectKbsFn 校验", () => {
+  it("仅接受 team 可见性 KB，非 team 抛错且不写库", async () => {
+    mocks.kbFindMany.mockResolvedValue([{ id: "kb1" }]); // 请求 [kb1(team), kb2(general)] 但只查回 kb1
+    await expect(
+      setProjectKbsFn({ data: { projectId: "p1", kbIds: ["kb1", "kb2"] } }),
+    ).rejects.toMatchObject({ message: expect.stringContaining("仅允许团队可见") });
+    expect(mocks.transaction).not.toHaveBeenCalled();
+  });
+
+  it("全量替换：删差集 + 增新增（事务）", async () => {
+    mocks.kbFindMany.mockResolvedValue([{ id: "kb1" }, { id: "kb2" }]);
+    mocks.transaction.mockImplementation(async (fn: (tx: any) => any) =>
+      fn({
+        projectKnowledgeBase: {
+          deleteMany: mocks.pkbDeleteMany,
+          createMany: mocks.pkbCreateMany,
+        },
+      }),
+    );
+    await setProjectKbsFn({ data: { projectId: "p1", kbIds: ["kb1", "kb2"] } });
+    expect(mocks.pkbDeleteMany).toHaveBeenCalledWith({
+      where: { projectId: "p1", kbId: { notIn: ["kb1", "kb2"] } },
+    });
+    expect(mocks.pkbCreateMany).toHaveBeenCalledWith({
+      data: [
+        { projectId: "p1", kbId: "kb1" },
+        { projectId: "p1", kbId: "kb2" },
+      ],
+      skipDuplicates: true,
+    });
+  });
+});
+
+describe("setKbProjectsFn 校验", () => {
+  it("general KB 拒绝关联", async () => {
+    mocks.kbFindFirst.mockResolvedValue({ id: "kbG", visibility: "general" });
+    await expect(
+      setKbProjectsFn({ data: { kbId: "kbG", projectIds: ["p1"] } }),
+    ).rejects.toMatchObject({ message: expect.stringContaining("通用知识库") });
+  });
+
+  it("private KB 拒绝关联", async () => {
+    mocks.kbFindFirst.mockResolvedValue({ id: "kbP", visibility: "private" });
+    await expect(
+      setKbProjectsFn({ data: { kbId: "kbP", projectIds: ["p1"] } }),
+    ).rejects.toMatchObject({ message: expect.stringContaining("私有知识库") });
+  });
+});
+
+describe("listProjectKbsFn / listKbProjectsFn", () => {
+  it("项目侧返回 KB 概要", async () => {
+    mocks.pkbFindMany.mockResolvedValue([
+      { kb: { id: "kb1", name: "团队库", icon: "notebook", visibility: "team" } },
+    ]);
+    const result = await listProjectKbsFn({ data: { projectId: "p1" } });
+    expect(result[0]).toMatchObject({ id: "kb1", name: "团队库" });
+  });
+
+  it("KB 侧返回项目概要", async () => {
+    mocks.pkbFindMany.mockResolvedValue([
+      { project: { id: "p1", name: "项目A", icon: "folder" } },
+    ]);
+    const result = await listKbProjectsFn({ data: { kbId: "kb1" } });
+    expect(result[0]).toMatchObject({ id: "p1", name: "项目A" });
+  });
+});

package/src/server/serverFns/knowledge.ts

@@ -25,6 +25,12 @@ import { deleteEmbeddings } from '@/lib/pgvector'
 import { requirePermission } from '@/server/permissions'
 import { auditLog } from '@/server/audit'
 
+/** 读权限放宽：自己的 KB ∪ 他人 team/general KB */
+const READABLE_KB = (userId: string) => ({
+  isDeleted: false,
+  OR: [{ userId }, { visibility: { in: ['team', 'general'] } }],
+})
+
 export const listKnowledgeFn = createServerFn({ method: 'GET' })
   .validator(z.object({}).optional())
   .handler(async () => {
@@ -51,7 +57,7 @@ const createSchema = z.object({
   description: z.string().max(200).optional(),
   icon: z.string().default('notebook'),
   tags: z.array(z.string()).default([]),
-  visibility: z.enum(['private', 'team']).default('private'),
+  visibility: z.enum(['private', 'team', 'general']).default('private'),
 })
 
 export const createKnowledgeFn = createServerFn({ method: 'POST' })
@@ -95,7 +101,7 @@ export const getKnowledgeDetailFn = createServerFn({ method: 'GET' })
     const request = getRequest()
     const session = await requireAuth(request)
     const kb = await prisma.knowledgeBase.findFirst({
-      where: { id: data.id, userId: session.user!.id!, isDeleted: false },
+      where: { id: data.id, ...READABLE_KB(session.user!.id!) },
       select: { id: true, name: true, description: true, icon: true, tags: true, visibility: true, createdAt: true, updatedAt: true },
     })
     if (!kb) throw new Error('未找到或无权限')
@@ -130,7 +136,7 @@ const updateSchema = z.object({
   description: z.string().max(500).optional(),
   icon: z.string().optional(),
   tags: z.array(z.string()).optional(),
-  visibility: z.enum(['private', 'team']).optional(),
+  visibility: z.enum(['private', 'team', 'general']).optional(),
 })
 
 export const updateKnowledgeFn = createServerFn({ method: 'POST' })
@@ -202,7 +208,7 @@ export const createDocumentFn = createServerFn({ method: 'POST' })
     const userId = session.user!.id!
     await requirePermission(userId, 'knowledge', 'write')
     const kb = await prisma.knowledgeBase.findFirst({
-      where: { id: data.kbId, userId, isDeleted: false },
+      where: { id: data.kbId, ...READABLE_KB(session.user!.id!) },
       select: { id: true },
     })
     if (!kb) throw new Error('未找到或无权限')
@@ -581,3 +587,43 @@ export const getDocumentPreviewFn = createServerFn({ method: 'GET' })
       } : null,
     } satisfies DocumentPreviewData
   })
+
+export const listKbProjectsFn = createServerFn({ method: 'GET' })
+  .validator(z.object({ kbId: z.string() }))
+  .handler(async ({ data }) => {
+    const request = getRequest()
+    const session = await requireAuth(request)
+    const rows = await prisma.projectKnowledgeBase.findMany({
+      where: { kbId: data.kbId },
+      select: { project: { select: { id: true, name: true, icon: true } } },
+      orderBy: { createdAt: 'asc' },
+    })
+    return rows.map((r) => r.project)
+  })
+
+export const setKbProjectsFn = createServerFn({ method: 'POST' })
+  .validator(z.object({ kbId: z.string(), projectIds: z.array(z.string()) }))
+  .handler(async ({ data }) => {
+    const request = getRequest()
+    const session = await requireAuth(request)
+    const userId = session.user!.id!
+    const kb = await prisma.knowledgeBase.findFirst({
+      where: { id: data.kbId, userId, isDeleted: false },
+      select: { visibility: true },
+    })
+    if (!kb) throw new Error('知识库不存在')
+    if (kb.visibility === 'general') throw new Error('通用知识库对所有项目可见，无需关联')
+    if (kb.visibility === 'private') throw new Error('私有知识库不可关联项目，请先切换为团队可见')
+    await prisma.$transaction(async (tx) => {
+      await tx.projectKnowledgeBase.deleteMany({
+        where: { kbId: data.kbId, projectId: { notIn: data.projectIds } },
+      })
+      if (data.projectIds.length > 0) {
+        await tx.projectKnowledgeBase.createMany({
+          data: data.projectIds.map((projectId) => ({ kbId: data.kbId, projectId })),
+          skipDuplicates: true,
+        })
+      }
+    })
+    return { ok: true }
+  })

package/src/server/serverFns/project.ts

@@ -573,3 +573,46 @@ export const ensureBuiltinProjectFn = createServerFn({ method: "GET" }).handler(
   const projectId = await ensureBuiltinIndependentProject(userId);
   return { id: projectId, name: BUILTIN_INDEPENDENT_NAME, displayId: BUILTIN_INDEPENDENT_DISPLAY_ID, icon: BUILTIN_INDEPENDENT_ICON };
 });
+
+export const listProjectKbsFn = createServerFn({ method: "GET" })
+  .validator(z.object({ projectId: z.string() }))
+  .handler(async ({ data }) => {
+    const request = getRequest();
+    await requireAuth(request);
+    const rows = await prisma.projectKnowledgeBase.findMany({
+      where: { projectId: data.projectId },
+      select: {
+        kb: { select: { id: true, name: true, icon: true, visibility: true } },
+      },
+      orderBy: { createdAt: "asc" },
+    });
+    return rows.map((r) => r.kb);
+  });
+
+export const setProjectKbsFn = createServerFn({ method: "POST" })
+  .validator(z.object({ projectId: z.string(), kbIds: z.array(z.string()) }))
+  .handler(async ({ data }) => {
+    const request = getRequest();
+    await requireAuth(request);
+    if (data.kbIds.length > 0) {
+      const valid = await prisma.knowledgeBase.findMany({
+        where: { id: { in: data.kbIds }, visibility: "team", isDeleted: false },
+        select: { id: true },
+      });
+      if (valid.length !== data.kbIds.length) {
+        throw new Error("仅允许团队可见的知识库关联项目");
+      }
+    }
+    await prisma.$transaction(async (tx) => {
+      await tx.projectKnowledgeBase.deleteMany({
+        where: { projectId: data.projectId, kbId: { notIn: data.kbIds } },
+      });
+      if (data.kbIds.length > 0) {
+        await tx.projectKnowledgeBase.createMany({
+          data: data.kbIds.map((kbId) => ({ projectId: data.projectId, kbId })),
+          skipDuplicates: true,
+        });
+      }
+    });
+    return { ok: true };
+  });

package/src/server/serverFns/story/__tests__/kb-scope.test.ts

@@ -0,0 +1,56 @@
+// 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 { describe, it, expect } from "vitest";
+import { isIndependentProject, buildKbScopeWhere } from "../kb-scope";
+
+describe("kb-scope 可用范围判定", () => {
+  it("独立需求项目（displayId=STORY）识别", () => {
+    expect(isIndependentProject("STORY")).toBe(true);
+    expect(isIndependentProject("story")).toBe(false);
+    expect(isIndependentProject(null)).toBe(false);
+    expect(isIndependentProject("PROJ")).toBe(false);
+  });
+
+  it("普通项目：general ∪ 项目关联（不含他人 private/team）", () => {
+    const where = buildKbScopeWhere({
+      projectId: "p1",
+      projectDisplayId: "PROJ",
+      userId: "u1",
+    });
+    expect(where).toEqual({
+      OR: [
+        { visibility: "general" },
+        { projectLinks: { some: { projectId: "p1" } } },
+      ],
+    });
+  });
+
+  it("独立需求项目：自己的全部 ∪ 他人 team/general", () => {
+    const where = buildKbScopeWhere({
+      projectId: "p2",
+      projectDisplayId: "STORY",
+      userId: "u1",
+    });
+    expect(where).toEqual({
+      OR: [
+        { userId: "u1" },
+        { visibility: { in: ["team", "general"] } },
+      ],
+    });
+  });
+});

package/src/server/serverFns/story/__tests__/story-assoc.test.ts

@@ -0,0 +1,222 @@
+// 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 { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("@tanstack/react-start", () => ({
+  createServerFn: (config: any) => {
+    const api: any = {
+      _validator: undefined,
+      validator(schema: any) {
+        this._validator = schema;
+        return this;
+      },
+      handler(fn: Function) {
+        const wrapped = async (args: any) => {
+          let data = args?.data;
+          if (this._validator && data !== undefined) {
+            data = this._validator.parse ? this._validator.parse(data) : data;
+          }
+          return fn({ data });
+        };
+        return wrapped;
+      },
+    };
+    return api;
+  },
+}));
+
+vi.mock("@tanstack/react-start/server", () => ({
+  getRequest: () => ({}),
+}));
+
+const mocks = vi.hoisted(() => ({
+  storyFindUnique: vi.fn(),
+  kbFindMany: vi.fn(),
+  kbFindFirst: vi.fn(),
+  docFindMany: vi.fn(),
+  linkFindMany: vi.fn(),
+  linkCreateMany: vi.fn(),
+  extLinkFindMany: vi.fn(),
+  extLinkCreateMany: vi.fn(),
+  extLinkDeleteMany: vi.fn(),
+  activityCreate: vi.fn(),
+  currentSession: vi.fn(),
+}));
+
+vi.mock("@allbluecn/database", () => {
+  const prisma = {
+    story: { findUnique: mocks.storyFindUnique },
+    knowledgeBase: { findMany: mocks.kbFindMany, findFirst: mocks.kbFindFirst },
+    knowledgeDocument: { findMany: mocks.docFindMany },
+    storyDocLink: { findMany: mocks.linkFindMany, createMany: mocks.linkCreateMany },
+    storyExternalLink: {
+      findMany: mocks.extLinkFindMany,
+      createMany: mocks.extLinkCreateMany,
+      deleteMany: mocks.extLinkDeleteMany,
+    },
+    storyActivity: { create: mocks.activityCreate },
+  };
+  return { prisma, Prisma: {} };
+});
+
+vi.mock("@/server/auth-helpers", () => ({
+  requireAuth: mocks.currentSession,
+}));
+
+import {
+  listStoryAvailableKbsFn,
+  searchKbDocsFn,
+  linkDocsFn,
+  getLinkedDocsFn,
+} from "../story-assoc";
+
+const SESSION = { user: { id: "u1" } };
+const STORY_WITH_PROJECT = {
+  project: { id: "p1", displayId: "PROJ" },
+};
+const STORY_INDEPENDENT = {
+  project: { id: "p2", displayId: "STORY" },
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.currentSession.mockResolvedValue(SESSION);
+  mocks.storyFindUnique.mockResolvedValue(STORY_WITH_PROJECT);
+  mocks.extLinkFindMany.mockResolvedValue([]);
+  mocks.extLinkCreateMany.mockResolvedValue({ count: 0 });
+  mocks.extLinkDeleteMany.mockResolvedValue({ count: 0 });
+  mocks.activityCreate.mockResolvedValue({
+    id: "act1",
+    action: "kb_linked",
+    field: null,
+    oldValue: null,
+    newValue: "1",
+    isAI: false,
+    createdAt: new Date("2026-08-31T00:00:00Z"),
+    user: { id: "u1", username: "u1", email: "e", avatarConfig: null, bgShape: null, bgColor: null },
+  });
+});
+
+describe("listStoryAvailableKbsFn", () => {
+  it("普通项目：按 scope 查询返回 KB 列表", async () => {
+    mocks.kbFindMany.mockResolvedValue([
+      { id: "kb1", name: "团队库", icon: "notebook", visibility: "team" },
+      { id: "kb2", name: "通用库", icon: "book", visibility: "general" },
+    ]);
+    const result = await listStoryAvailableKbsFn({ data: { storyId: "s1" } });
+    expect(result).toHaveLength(2);
+    expect(result[0]).toMatchObject({ id: "kb1", name: "团队库" });
+    const where = mocks.kbFindMany.mock.calls[0][0].where;
+    expect(where.AND).toBeDefined(); // AND: [scope, { isDeleted: false }]
+  });
+
+  it("需求不存在抛错", async () => {
+    mocks.storyFindUnique.mockResolvedValue(null);
+    await expect(listStoryAvailableKbsFn({ data: { storyId: "nope" } })).rejects.toMatchObject({
+      message: expect.stringContaining("需求不存在"),
+    });
+  });
+});
+
+describe("searchKbDocsFn 两态", () => {
+  it("指定 kbId：全量树查询（take 500，含 parentId/type/kb 元数据）", async () => {
+    mocks.storyFindUnique.mockResolvedValue(STORY_WITH_PROJECT);
+    mocks.kbFindFirst.mockResolvedValue({ id: "kb1" }); // 范围内
+    mocks.docFindMany.mockResolvedValue([
+      { id: "d1", title: "页1", parentId: null, kb: { id: "kb1", name: "团队库", icon: "notebook" }, icon: "doc" },
+    ]);
+    const result = await searchKbDocsFn({ data: { storyId: "s1", kbId: "kb1", query: "" } });
+    expect(result.items[0]).toMatchObject({ id: "d1", kbName: "团队库" });
+    expect(result.nextCursor).toBeNull();
+    const args = mocks.docFindMany.mock.calls[0][0];
+    expect(args.take).toBe(500);
+    expect(args.where.kbId).toBe("kb1");
+  });
+
+  it("指定范围外 kbId：抛越界错误", async () => {
+    mocks.storyFindUnique.mockResolvedValue(STORY_WITH_PROJECT);
+    mocks.kbFindFirst.mockResolvedValue(null); // 不在 scope 内
+    await expect(
+      searchKbDocsFn({ data: { storyId: "s1", kbId: "kbX", query: "" } }),
+    ).rejects.toMatchObject({ message: expect.stringContaining("不在可用范围") });
+  });
+
+  it("全部模式：平铺分页（take 21 判 hasMore）", async () => {
+    mocks.storyFindUnique.mockResolvedValue(STORY_WITH_PROJECT);
+    mocks.docFindMany.mockResolvedValue([]);
+    await searchKbDocsFn({ data: { storyId: "s1", query: "关键词" } });
+    const args = mocks.docFindMany.mock.calls[0][0];
+    expect(args.take).toBe(21);
+    expect(args.where.kb).toBeDefined(); // scope 下推到 kb 关系
+  });
+});
+
+describe("linkDocsFn 批量关联", () => {
+  it("合法项批量建链、已存在跳过、越界归 failed", async () => {
+    mocks.storyFindUnique.mockResolvedValue(STORY_WITH_PROJECT);
+    mocks.docFindMany.mockResolvedValue([
+      { id: "d1", kbId: "kb1" }, // 合法
+      { id: "d2", kbId: "kb9" }, // 越界（kb9 不在 scope）
+    ]);
+    mocks.kbFindMany.mockResolvedValue([{ id: "kb1" }, { id: "kb2" }]); // scope 内 KB 集合
+    mocks.linkFindMany.mockResolvedValue([{ docId: "d1" }]); // d1 已关联
+    mocks.linkCreateMany.mockResolvedValue({ count: 0 });
+
+    const result = await linkDocsFn({ data: { storyId: "s1", docIds: ["d1", "d2"] } });
+    expect(result.linked).toEqual([]);
+    expect(result.skipped).toEqual(["d1"]);
+    expect(result.failed).toEqual([{ docId: "d2", reason: "outOfScope" }]);
+    expect(mocks.linkCreateMany).not.toHaveBeenCalled(); // 无新增
+  });
+
+  it("新增项走 createMany skipDuplicates", async () => {
+    mocks.docFindMany.mockResolvedValue([{ id: "d3", kbId: "kb1" }]);
+    mocks.kbFindMany.mockResolvedValue([{ id: "kb1" }]);
+    mocks.linkFindMany.mockResolvedValue([]);
+    mocks.linkCreateMany.mockResolvedValue({ count: 1 });
+    const result = await linkDocsFn({ data: { storyId: "s1", docIds: ["d3"] } });
+    expect(result.linked).toEqual(["d3"]);
+    expect(mocks.linkCreateMany.mock.calls[0][0].data).toEqual([{ storyId: "s1", docId: "d3" }]);
+  });
+});
+
+describe("getLinkedDocsFn 扩展返回 KB 元数据", () => {
+  it("返回对齐 DocBrief 的字段", async () => {
+    mocks.linkFindMany.mockResolvedValue([
+      {
+        doc: {
+          id: "d1",
+          title: "页1",
+          kb: { id: "kb1", name: "团队库", icon: "notebook" },
+          icon: "doc",
+          parentId: null,
+        },
+      },
+    ]);
+    const result = await getLinkedDocsFn({ data: { storyId: "s1" } });
+    expect(result[0]).toEqual({
+      id: "d1",
+      title: "页1",
+      kbId: "kb1",
+      kbName: "团队库",
+      kbIcon: "notebook",
+      docIcon: "doc",
+      parentId: null,
+    });
+  });
+});

package/src/server/serverFns/story/__tests__/story-dependencies.test.ts

@@ -50,6 +50,7 @@ const mocks = vi.hoisted(() => ({
   depCreate: vi.fn(),
   depDelete: vi.fn(),
   storyFindMany: vi.fn(),
+  activityCreate: vi.fn(),
   currentSession: vi.fn(),
 }));
 
@@ -62,6 +63,7 @@ vi.mock("@allbluecn/database", () => {
       delete: mocks.depDelete,
     },
     story: { findMany: mocks.storyFindMany },
+    storyActivity: { create: mocks.activityCreate },
   };
   return { prisma, Prisma: {} };
 });
@@ -104,6 +106,24 @@ beforeEach(() => {
   mocks.currentSession.mockResolvedValue({ user: { id: "u1" } });
   // 默认 DB 无既有依赖边（handler 开头一次性取全边建邻接表，必须返回数组）
   mocks.depFindMany.mockResolvedValue([]);
+  // 活动写入段：端点 label 查询 + create 返回（含 select 字段）
+  mocks.storyFindMany.mockResolvedValue([
+    { id: "a", identifier: "A-1", name: "story a" },
+    { id: "b", identifier: "B-1", name: "story b" },
+  ]);
+  mocks.activityCreate.mockImplementation(({ data }: any) =>
+    Promise.resolve({
+      id: `act-${data.storyId}`,
+      action: "dependency_added",
+      field: null,
+      oldValue: null,
+      newValue: data.newValue,
+      isAI: false,
+      createdAt: new Date("2026-08-31T00:00:00Z"),
+      storyId: data.storyId,
+      user: { id: "u1", username: "u1", email: "e", avatarConfig: null, bgShape: null, bgColor: null },
+    }),
+  );
 });
 
 describe("addDependenciesFn", () => {
@@ -187,6 +207,12 @@ describe("addDependenciesFn", () => {
     expect(mocks.depFindMany).toHaveBeenCalledWith({
       select: { sourceId: true, targetId: true },
     });
+    // 活动契约：依赖两端各记一条「添加依赖关系」，newValue 为对方描述
+    expect(res.activities).toHaveLength(2);
+    expect(res.activities.map((x) => [x.storyId, x.newValue]).sort()).toEqual([
+      ["a", "B-1 story b"],
+      ["b", "A-1 story a"],
+    ]);
   });
 
   it("validator 拒绝旧枚举值：BLOCKED_BY 不再合法", async () => {

package/src/server/serverFns/story/index.ts

@@ -93,11 +93,11 @@ export {
   getLinksFn,
 } from "./story-links";
 
+export { checkLinkEmbeddableFn } from "./link-preview";
+
 export {
-  uploadAttachmentFn,
   removeAttachmentFn,
   getAttachmentsFn,
-  mockCloudStorageFn,
 } from "./story-attachments";
 
 export {
@@ -105,10 +105,12 @@ export {
   unlinkPrdFn,
   getLinkedPrdsFn,
   searchPrdsFn,
-  linkDocFn,
+  listStoryAvailableKbsFn,
+  searchKbDocsFn,
+  linkDocsFn,
   unlinkDocFn,
   getLinkedDocsFn,
-  searchDocsFn,
+  type SearchDocRow,
 } from "./story-assoc";
 
 export {

package/src/server/serverFns/story/kb-general.ts

@@ -0,0 +1,39 @@
+// 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-assoc.ts（serverFn 模块）纯净：客户端可安全导入。
+
+export const GENERAL_GROUPS = ["legal", "compliance", "dictionary", "bookmark", "summary"] as const;
+export type GeneralGroup = (typeof GENERAL_GROUPS)[number];
+
+export const EXTERNAL_ID_PREFIX = "ext:";
+
+export function parseExternalDocId(id: string): { group: GeneralGroup; externalId: string } | null {
+  if (!id.startsWith(EXTERNAL_ID_PREFIX)) return null;
+  const rest = id.slice(EXTERNAL_ID_PREFIX.length);
+  const idx = rest.indexOf(":");
+  if (idx <= 0) return null;
+  const group = rest.slice(0, idx);
+  const externalId = rest.slice(idx + 1);
+  if (!(GENERAL_GROUPS as readonly string[]).includes(group) || !externalId) return null;
+  return { group: group as GeneralGroup, externalId };
+}
+
+export function externalDocId(group: GeneralGroup, externalId: string): string {
+  return `${EXTERNAL_ID_PREFIX}${group}:${externalId}`;
+}