@allbluecn/web-app 0.17.2 → 0.18.0

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

@@ -0,0 +1,148 @@
+// 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, beforeEach, afterEach, vi } from 'vitest'
+import {
+  LOGIN_RATE_LIMIT,
+  SHARE_PASSWORD_RATE_LIMIT,
+  isLoginBlocked,
+  recordLoginFailure,
+  clearLoginFailures,
+  isSharePasswordBlocked,
+  recordSharePasswordFailure,
+  clearSharePasswordFailures,
+  resetAuthRateLimitStoreForTest,
+  isAuthRateLimitBypassed,
+} from '../auth-rate-limit'
+
+// 模块在 NODE_ENV=test（vitest 默认）下豁免限流，为验证限流行为需切到 development
+beforeEach(() => {
+  vi.stubEnv('NODE_ENV', 'development')
+  vi.useFakeTimers()
+  resetAuthRateLimitStoreForTest()
+})
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+  vi.useRealTimers()
+})
+
+describe('登录限流（email+IP 维度）', () => {
+  it(`未达阈值（${LOGIN_RATE_LIMIT.max} 次）放行`, () => {
+    for (let i = 0; i < LOGIN_RATE_LIMIT.max - 1; i++) {
+      recordLoginFailure('a@test.com', '1.2.3.4')
+    }
+    expect(isLoginBlocked('a@test.com', '1.2.3.4')).toBe(false)
+  })
+
+  it('达到阈值后拦截', () => {
+    for (let i = 0; i < LOGIN_RATE_LIMIT.max; i++) {
+      recordLoginFailure('a@test.com', '1.2.3.4')
+    }
+    expect(isLoginBlocked('a@test.com', '1.2.3.4')).toBe(true)
+  })
+
+  it('成功登录清零失败计数', () => {
+    for (let i = 0; i < LOGIN_RATE_LIMIT.max; i++) {
+      recordLoginFailure('a@test.com', '1.2.3.4')
+    }
+    expect(isLoginBlocked('a@test.com', '1.2.3.4')).toBe(true)
+    clearLoginFailures('a@test.com', '1.2.3.4')
+    expect(isLoginBlocked('a@test.com', '1.2.3.4')).toBe(false)
+  })
+
+  it('窗口过期后重置', () => {
+    for (let i = 0; i < LOGIN_RATE_LIMIT.max; i++) {
+      recordLoginFailure('a@test.com', '1.2.3.4')
+    }
+    expect(isLoginBlocked('a@test.com', '1.2.3.4')).toBe(true)
+    vi.advanceTimersByTime(LOGIN_RATE_LIMIT.windowMs + 1)
+    expect(isLoginBlocked('a@test.com', '1.2.3.4')).toBe(false)
+  })
+
+  it('不同 email 或 IP 组合键独立计数', () => {
+    for (let i = 0; i < LOGIN_RATE_LIMIT.max; i++) {
+      recordLoginFailure('a@test.com', '1.2.3.4')
+    }
+    expect(isLoginBlocked('a@test.com', '5.6.7.8')).toBe(false)
+    expect(isLoginBlocked('b@test.com', '1.2.3.4')).toBe(false)
+  })
+
+  it('email 大小写/空白变体归一化（防绕过）', () => {
+    for (let i = 0; i < LOGIN_RATE_LIMIT.max; i++) {
+      recordLoginFailure('A@Test.com ', '1.2.3.4')
+    }
+    expect(isLoginBlocked('a@test.com', '1.2.3.4')).toBe(true)
+  })
+
+  it('IP 取不到时归入 unknown 桶（仍按 email 受限）', () => {
+    for (let i = 0; i < LOGIN_RATE_LIMIT.max; i++) {
+      recordLoginFailure('a@test.com', null)
+    }
+    expect(isLoginBlocked('a@test.com', null)).toBe(true)
+    expect(isLoginBlocked('a@test.com', '1.2.3.4')).toBe(false)
+  })
+})
+
+describe('分享密码限流（IP 维度）', () => {
+  it(`未达阈值（${SHARE_PASSWORD_RATE_LIMIT.max} 次）放行`, () => {
+    for (let i = 0; i < SHARE_PASSWORD_RATE_LIMIT.max - 1; i++) {
+      recordSharePasswordFailure('203.0.113.7')
+    }
+    expect(isSharePasswordBlocked('203.0.113.7')).toBe(false)
+  })
+
+  it('达到阈值后拦截', () => {
+    for (let i = 0; i < SHARE_PASSWORD_RATE_LIMIT.max; i++) {
+      recordSharePasswordFailure('203.0.113.7')
+    }
+    expect(isSharePasswordBlocked('203.0.113.7')).toBe(true)
+    expect(isSharePasswordBlocked('198.51.100.9')).toBe(false)
+  })
+
+  it('校验成功清零', () => {
+    for (let i = 0; i < SHARE_PASSWORD_RATE_LIMIT.max; i++) {
+      recordSharePasswordFailure('203.0.113.7')
+    }
+    expect(isSharePasswordBlocked('203.0.113.7')).toBe(true)
+    clearSharePasswordFailures('203.0.113.7')
+    expect(isSharePasswordBlocked('203.0.113.7')).toBe(false)
+  })
+
+  it('窗口过期后重置', () => {
+    for (let i = 0; i < SHARE_PASSWORD_RATE_LIMIT.max; i++) {
+      recordSharePasswordFailure('203.0.113.7')
+    }
+    vi.advanceTimersByTime(SHARE_PASSWORD_RATE_LIMIT.windowMs + 1)
+    expect(isSharePasswordBlocked('203.0.113.7')).toBe(false)
+  })
+})
+
+describe('测试环境豁免', () => {
+  it('NODE_ENV=test 时不计数不拦截', () => {
+    vi.stubEnv('NODE_ENV', 'test')
+    expect(isAuthRateLimitBypassed()).toBe(true)
+    for (let i = 0; i < LOGIN_RATE_LIMIT.max * 3; i++) {
+      recordLoginFailure('a@test.com', '1.2.3.4')
+    }
+    expect(isLoginBlocked('a@test.com', '1.2.3.4')).toBe(false)
+    for (let i = 0; i < SHARE_PASSWORD_RATE_LIMIT.max * 3; i++) {
+      recordSharePasswordFailure('203.0.113.7')
+    }
+    expect(isSharePasswordBlocked('203.0.113.7')).toBe(false)
+  })
+})

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

@@ -0,0 +1,117 @@
+// 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/>.
+
+/**
+ * 认证类端点失败限流（SEC-09 登录 / SEC-10 分享密码）——进程内存态固定窗口。
+ *
+ * ⚠️ 架构边界：计数器存于单进程内存（Map），**多实例部署不共享**，
+ * 实际阈值 = 配置值 × 实例数。本期不实施分布式限流（Redis 等），
+ * 多实例部署落地前不得将本模块视为唯一防线。
+ *
+ * 设计要点：
+ * - 仅失败尝试计数（登录：用户不存在/密码错误；分享密码：校验失败），
+ *   成功后清零——正常用户与自动化 e2e（成功登录）不受影响
+ * - key 归一化：email 小写去空白，避免大小写变体绕过；IP 取不到时归入
+ *   `unknown` 桶（按 email 维度仍受限流保护）
+ * - 测试环境豁免：NODE_ENV=test（vitest）时不计数不拦截，防单测互踩
+ * - 账号状态类失败（封禁/未激活）不计入——非口令爆破向量
+ */
+
+const store = new Map<string, { count: number; resetAt: number }>()
+
+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?.()
+
+/** 测试环境豁免（vitest 注入 NODE_ENV=test） */
+export function isAuthRateLimitBypassed(): boolean {
+  return process.env.NODE_ENV === 'test'
+}
+
+function isBlocked(key: string, max: number): boolean {
+  if (isAuthRateLimitBypassed()) return false
+  const entry = store.get(key)
+  if (!entry) return false
+  if (Date.now() > entry.resetAt) {
+    store.delete(key)
+    return false
+  }
+  return entry.count >= max
+}
+
+function recordFailure(key: string, windowMs: number): void {
+  if (isAuthRateLimitBypassed()) return
+  const now = Date.now()
+  const entry = store.get(key)
+  if (!entry || now > entry.resetAt) {
+    store.set(key, { count: 1, resetAt: now + windowMs })
+    return
+  }
+  entry.count++
+}
+
+function loginKey(email: string, ip: string | null): string {
+  return `login:${email.toLowerCase().trim()}:${ip ?? 'unknown'}`
+}
+
+/** 登录是否已被限流（email+IP 维度）。被限流时调用方应返回与密码错误不可区分的失败。 */
+export function isLoginBlocked(email: string, ip: string | null): boolean {
+  return isBlocked(loginKey(email, ip), LOGIN_RATE_LIMIT.max)
+}
+
+/** 记录一次登录失败（用户不存在或密码错误） */
+export function recordLoginFailure(email: string, ip: string | null): void {
+  recordFailure(loginKey(email, ip), LOGIN_RATE_LIMIT.windowMs)
+}
+
+/** 登录成功后清零失败计数 */
+export function clearLoginFailures(email: string, ip: string | null): void {
+  store.delete(loginKey(email, ip))
+}
+
+function sharePasswordKey(ip: string | null): string {
+  return `sharePwd:${ip ?? 'unknown'}`
+}
+
+/** 分享密码校验是否已被限流（IP 维度）。被限流时调用方应返回 valid:false（不泄露限流细节）。 */
+export function isSharePasswordBlocked(ip: string | null): boolean {
+  return isBlocked(sharePasswordKey(ip), SHARE_PASSWORD_RATE_LIMIT.max)
+}
+
+/** 记录一次分享密码校验失败 */
+export function recordSharePasswordFailure(ip: string | null): void {
+  recordFailure(sharePasswordKey(ip), SHARE_PASSWORD_RATE_LIMIT.windowMs)
+}
+
+/** 分享密码校验成功后清零失败计数 */
+export function clearSharePasswordFailures(ip: string | null): void {
+  store.delete(sharePasswordKey(ip))
+}
+
+/** 测试辅助：清空整个 store（用例隔离用，生产勿调） */
+export function resetAuthRateLimitStoreForTest(): void {
+  store.clear()
+}

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

@@ -1 +1 @@
-export * from '@/plugins/core/server/rate-limit'
+export * from '@/server/lib/rate-limit'

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

@@ -1,5 +1,9 @@
 import { getRequest } from '@tanstack/react-start/server'
 
+// ⚠️ 架构边界：限流状态存于单进程内存（store Map），多实例部署不共享，
+// 实际阈值 = 配置值 × 实例数。本期不实施分布式限流（Redis 等），
+// 多实例部署落地前不得将本模块视为唯一防线。
+
 const store = new Map<string, { count: number; resetAt: number }>()
 
 function check(key: string, max: number, windowMs: number): boolean {

package/src/server/notifications/notification-service.ts

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { prisma } from '@allbluecn/database'
 import type {
-  CategoryFrequencies,
   NotificationCategory,
   NotificationItem,
   NotificationPreferences,
@@ -133,12 +132,15 @@ export async function createNotification(input: CreateNotificationInput): Promis
     if (input.force || frequency === 'realtime') {
       notificationBus.emit(input.userId, { kind: 'notification', notification: item })
       // 邮件镜像（fire-and-forget，不阻塞站内通知）：条件 1-5 在此判定，条件 6（频控）由 outbox 内部执行
+      // .catch 兜底：mirrorToEmail 内部虽有全量 try/catch，此处防未来改动漏出 rejection
       void mirrorToEmail({
         userId: input.userId,
         category: input.category,
         title: input.title,
         body: input.body ?? null,
         link: input.link ?? null,
+      }).catch((e) => {
+        console.error('[notifications] mirror to email failed (unhandled rejection):', e)
       })
     }
   } catch (e) {
@@ -214,49 +216,54 @@ export async function deliverDueDigests(userId: string): Promise<void> {
     const digestCats = (Object.keys(prefs.categories) as NotificationCategory[]).filter(
       (c) => prefs.categories[c] === 'digest-daily' || prefs.categories[c] === 'digest-weekly'
     )
-    for (const category of digestCats) {
-      const frequency = prefs.categories[category] as 'digest-daily' | 'digest-weekly'
-      const type = DIGEST_TYPE[frequency]
+    // DB-01：原每分类 3 次串行查询（findFirst→count→findMany）。改为：分类间并行；
+    // 分类内 findFirst 先行（水位线），count+findMany 同 where 并行（1 轮替代 2 轮）。
+    // 查询次数 before: 3N 串行 → after: 3N（两轮并行，墙钟时间 ≈ 2 次 RTT）
+    const pending = await Promise.all(
+      digestCats.map(async (category) => {
+        const frequency = prefs.categories[category] as 'digest-daily' | 'digest-weekly'
+        const type = DIGEST_TYPE[frequency]
 
-      const lastDigest = await prisma.notification.findFirst({
-        where: { userId, category, type },
-        orderBy: { createdAt: 'desc' },
-        select: { createdAt: true },
-      })
-      if (lastDigest && Date.now() - lastDigest.createdAt.getTime() < DIGEST_MIN_INTERVAL_MS[frequency]) {
-        continue
-      }
+        const lastDigest = await prisma.notification.findFirst({
+          where: { userId, category, type },
+          orderBy: { createdAt: 'desc' },
+          select: { createdAt: true },
+        })
+        if (lastDigest && Date.now() - lastDigest.createdAt.getTime() < DIGEST_MIN_INTERVAL_MS[frequency]) {
+          return null
+        }
 
-      const since = lastDigest?.createdAt ?? new Date(0)
-      const pendingCount = await prisma.notification.count({
-        where: {
+        const since = lastDigest?.createdAt ?? new Date(0)
+        const pendingWhere = {
           userId,
           category,
           type: { not: { startsWith: 'digest.' } },
           createdAt: { gt: since },
-        },
-      })
-      if (pendingCount === 0) continue
-
-      const pending = await prisma.notification.findMany({
-        where: {
-          userId,
-          category,
-          type: { not: { startsWith: 'digest.' } },
-          createdAt: { gt: since },
-        },
-        orderBy: { createdAt: 'desc' },
-        select: { title: true },
-        take: DIGEST_SUMMARY_ITEMS,
-      })
+        }
+        const [pendingCount, recent] = await Promise.all([
+          prisma.notification.count({ where: pendingWhere }),
+          prisma.notification.findMany({
+            where: pendingWhere,
+            orderBy: { createdAt: 'desc' },
+            select: { title: true },
+            take: DIGEST_SUMMARY_ITEMS,
+          }),
+        ])
+        if (pendingCount === 0) return null
+        return { category, frequency, type, pendingCount, recent }
+      }),
+    )
 
-      const periodLabel = frequency === 'digest-daily' ? '今日' : '本周'
+    // 写入保持串行（总线推送顺序与原实现一致）
+    for (const item of pending) {
+      if (!item) continue
+      const periodLabel = item.frequency === 'digest-daily' ? '今日' : '本周'
       await createNotification({
         userId,
-        category,
-        type,
-        title: `${periodLabel}${CATEGORY_LABELS[category]}有 ${pendingCount} 条新通知`,
-        body: formatDigestBody(pending.map((n) => n.title), pendingCount),
+        category: item.category,
+        type: item.type,
+        title: `${periodLabel}${CATEGORY_LABELS[item.category]}有 ${item.pendingCount} 条新通知`,
+        body: formatDigestBody(item.recent.map((n) => n.title), item.pendingCount),
         force: true,
       })
     }

package/src/server/references/engine.ts

@@ -19,6 +19,18 @@ import { prisma } from "@allbluecn/database"
 import type { Reference, ResolvedRef, RefDisplay, SearchResult } from "@allbluecn/kernel"
 import { moduleRegistry } from "@allbluecn/kernel"
 
+// SEC-14：$queryRawUnsafe 拼接的表名/字段名白名单断言。
+// 标识符均来自 moduleRegistry 的开发者配置（非用户输入），此处 throw 是最后一道
+// 防线——配置被污染（依赖投毒/误改）时让查询显式失败而非拼出任意 SQL。
+const SAFE_IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+function assertSafeIdent(name: string, what: string): string {
+  if (!SAFE_IDENT_RE.test(name)) {
+    throw new Error(`[references] 非法 SQL 标识符（${what}）：${name}`)
+  }
+  return name
+}
+
 async function resolveDisplay(
   targetModule: string,
   targetEntityId: string,
@@ -33,10 +45,13 @@ async function resolveDisplay(
   if (!entity) return { title: `[${targetModule}:${targetEntityId}]` }
 
   try {
-    const safeFields = [...entity.displayFields, "id"].filter(f => /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(f))
-    const fields = safeFields.join(", ")
+    // 断言失败抛错 → 落入 catch 返回占位 title（运行时安全降级）
+    const fields = [...entity.displayFields, "id"]
+      .map((f) => assertSafeIdent(f, "displayField"))
+      .join(", ")
+    const table = assertSafeIdent(entity.table, "table")
     const rows = await prisma.$queryRawUnsafe<Record<string, unknown>[]>(
-      `SELECT ${fields} FROM \`${entity.table}\` WHERE id = ?`,
+      `SELECT ${fields} FROM \`${table}\` WHERE id = ?`,
       targetEntityId
     )
     if (!rows.length) return { title: `Deleted ${entity.type}`, status: "deleted" }
@@ -81,15 +96,16 @@ export async function searchReferences(
   for (const config of filtered) {
     const mod = moduleRegistry.getModule(config.module)
     if (!mod) continue
-const searchField = config.fields[0]
-      const safeSearchField = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(searchField) ? searchField : "id"
-      const safeFields = config.fields.filter(f => /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(f))
-      const { prisma: p } = await import("@allbluecn/database")
-      try {
-        const rows = await p.$queryRawUnsafe<Record<string, unknown>[]>(
-          `SELECT id, ${safeFields.join(", ")} FROM \`${mod.entities[0].table}\` WHERE \`${safeSearchField}\` LIKE ? LIMIT 20`,
-          `%${query}%`
-        )
+    const { prisma: p } = await import("@allbluecn/database")
+    try {
+      // SEC-14：全部标识符断言通过才拼接，任一非法即 throw → catch 跳过该模块
+      const table = assertSafeIdent(mod.entities[0].table, "table")
+      const fields = config.fields.map((f) => assertSafeIdent(f, "searchField")).join(", ")
+      const searchField = assertSafeIdent(config.fields[0], "searchField")
+      const rows = await p.$queryRawUnsafe<Record<string, unknown>[]>(
+        `SELECT id, ${fields} FROM \`${table}\` WHERE \`${searchField}\` LIKE ? LIMIT 20`,
+        `%${query}%`
+      )
       for (const row of rows) {
         const display = mod.referenceDisplay(config.type, row)
         results.push({
@@ -101,7 +117,7 @@ const searchField = config.fields[0]
           url: display.url,
         })
       }
-    } catch { /* skip tables that don't exist yet */ }
+    } catch { /* skip tables that don't exist yet / 非法标识符配置 */ }
   }
   return results
 }

package/src/server/resources.ts

@@ -17,9 +17,7 @@
 
 import { prisma } from '@allbluecn/database'
 import {
-  RESOURCE_KEYS,
   type ResourceSnapshots,
-  type ResourceSnapshot,
 } from '@allbluecn/kernel'
 import { requireAuth } from '@/server/auth-helpers'
 import { verifyActiveLicense } from '@/server/entitlements'

package/src/server/serverFns/__tests__/ai-hosted-models.test.ts

@@ -44,7 +44,7 @@ vi.mock('@/server/ai-gateway/pro-services', () => ({
   getProService: vi.fn(),
 }))
 
-import { listHostedModelsFn } from '@/plugins/core/prd/serverFns/ai/hosted-models'
+import { listHostedModelsFn } from '@/server/serverFns/design/ai/hosted-models'
 import { getProService } from '@/server/ai-gateway/pro-services'
 
 describe('listHostedModelsFn', () => {

package/src/server/serverFns/__tests__/ai-source-mode.test.ts

@@ -60,7 +60,7 @@ vi.mock('@/server/ai-gateway/source-mode', () => ({
   setSourceMode: sourceMocks.setSourceMode,
 }))
 
-import { setAiSourceModeFn, getAiSourceModeFn } from '@/plugins/core/prd/serverFns/ai/source-mode'
+import { setAiSourceModeFn, getAiSourceModeFn } from '@/server/serverFns/design/ai/source-mode'
 
 describe('setAiSourceModeFn 权限闸', () => {
   beforeEach(() => {

package/src/server/serverFns/__tests__/knowledge-breadcrumb.test.ts

@@ -0,0 +1,158 @@
+// 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/>.
+
+// getDocBreadcrumbFn 两轮 findMany 收敛（DB-01）的形状与等价性回归：
+// 关键断言：第二轮 title 查询必须带 kbId + isDeleted 过滤（审查 K-1——
+// 首节点不在图内仍会进 chainIds，缺过滤会返回已删除/跨 kb 文档的 1 项面包屑，
+// 原逐级 findFirst 实现为空数组）。
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('@tanstack/react-start', () => ({
+  createServerFn: (_config: unknown) => {
+    const api = {
+      _validator: undefined as unknown,
+      validator(schema: unknown) {
+        this._validator = schema
+        return this
+      },
+      handler(fn: (args: { data: unknown }) => Promise<unknown>) {
+        return async (args: unknown) => fn({ data: (args as { data?: unknown } | null | undefined)?.data })
+      },
+    }
+    return api
+  },
+}))
+
+vi.mock('@tanstack/react-start/server', () => ({
+  getRequest: vi.fn(),
+}))
+
+/** 全量文档 fixture（跨 kb、含已删除）——findMany mock 的过滤数据源 */
+const ALL_DOCS = [
+  { id: 'doc-a', kbId: 'kb-1', parentId: null, isDeleted: false, title: '根文档' },
+  { id: 'doc-b', kbId: 'kb-1', parentId: 'doc-a', isDeleted: false, title: '子文档' },
+  { id: 'doc-c', kbId: 'kb-1', parentId: 'doc-b', isDeleted: false, title: '孙文档' },
+  { id: 'doc-del', kbId: 'kb-1', parentId: null, isDeleted: true, title: '已删除文档' },
+  { id: 'doc-other', kbId: 'kb-2', parentId: null, isDeleted: false, title: '别家文档' },
+]
+
+const m = vi.hoisted(() => {
+  const prismaMock = {
+    knowledgeBase: { findFirst: vi.fn(), findMany: vi.fn() },
+    knowledgeDocument: { findMany: vi.fn() },
+  }
+  // 同 knowledge-search.test.ts：getPrisma 走 database 包 globalThis.prisma 单例缓存注入
+  ;(globalThis as { prisma?: unknown }).prisma = prismaMock
+  return prismaMock
+})
+
+vi.mock('@allbluecn/database/get-prisma', () => ({ getPrisma: async () => m }))
+vi.mock('@allbluecn/database', () => ({ prisma: m }))
+
+vi.mock('@/server/auth-helpers', () => ({ requireAuth: vi.fn() }))
+vi.mock('@/server/permissions', () => ({ requirePermission: vi.fn() }))
+vi.mock('@/server/audit', () => ({ auditLog: vi.fn() }))
+vi.mock('@/server/knowledge/knowledge-index-utils', () => ({
+  resolveAiConfig: vi.fn(),
+  KB_EMBEDDINGS_TABLE: 'knowledge_embeddings' as const,
+  indexDocumentById: vi.fn(),
+  extractText: vi.fn(),
+}))
+vi.mock('@/server/ai-gateway/embedding', () => ({
+  generateEmbedding: vi.fn(),
+  chunkText: vi.fn((t: string) => [t]),
+}))
+vi.mock('@/server/ai-gateway/rerank', () => ({
+  rerankCandidates: vi.fn(),
+  RECALL_MULTIPLIER: 4,
+}))
+vi.mock('@/lib/vector-store', () => ({
+  getVectorStore: vi.fn(async () => ({
+    searchByVector: vi.fn(),
+    insertEmbedding: vi.fn(),
+    deleteEmbeddings: vi.fn(),
+  })),
+}))
+
+import { getDocBreadcrumbFn } from '../knowledge'
+import { requireAuth } from '@/server/auth-helpers'
+
+const SESSION = { user: { id: 'user-1' } }
+
+describe('getDocBreadcrumbFn 两轮 findMany 收敛（DB-01）', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(requireAuth).mockResolvedValue(SESSION as never)
+    m.knowledgeBase.findFirst.mockResolvedValue({ id: 'kb-1' })
+    // 两轮共用一个 mock：无 id.in = 第一轮（kb 图，窄投影）；有 id.in = 第二轮（title 补齐）
+    m.knowledgeDocument.findMany.mockImplementation(async ({ where }: { where: Record<string, never> }) => {
+      const w = where as unknown as {
+        id?: { in: string[] }
+        kbId?: string
+        isDeleted?: boolean
+      }
+      if (w.id?.in) {
+        return ALL_DOCS.filter(
+          (d) => w.id!.in.includes(d.id) && d.kbId === w.kbId && d.isDeleted === false,
+        ).map((d) => ({ id: d.id, title: d.title }))
+      }
+      return ALL_DOCS.filter((d) => d.kbId === w.kbId && d.isDeleted === false).map((d) => ({
+        id: d.id,
+        parentId: d.parentId,
+      }))
+    })
+  })
+
+  it('链上全在图内：按根→叶顺序返回 title（第二轮带 kbId/isDeleted 过滤）', async () => {
+    const res = await getDocBreadcrumbFn({ data: { docId: 'doc-c', kbId: 'kb-1' } })
+    expect(res).toEqual([
+      { id: 'doc-a', title: '根文档' },
+      { id: 'doc-b', title: '子文档' },
+      { id: 'doc-c', title: '孙文档' },
+    ])
+    // 审查 K-1 契约：第二轮 title 查询与原逐级 findFirst 同口径（kbId + isDeleted）
+    expect(m.knowledgeDocument.findMany).toHaveBeenCalledTimes(2)
+    expect(m.knowledgeDocument.findMany).toHaveBeenLastCalledWith({
+      where: { id: { in: ['doc-c', 'doc-b', 'doc-a'] }, kbId: 'kb-1', isDeleted: false },
+      select: { id: true, title: true },
+    })
+  })
+
+  it('已删除文档（不在图内）：返回空面包屑（原行为），不泄露 title', async () => {
+    const res = await getDocBreadcrumbFn({ data: { docId: 'doc-del', kbId: 'kb-1' } })
+    expect(res).toEqual([])
+  })
+
+  it('跨 kb docId（他人知识库文档）：返回空面包屑，不泄露 title', async () => {
+    const res = await getDocBreadcrumbFn({ data: { docId: 'doc-other', kbId: 'kb-1' } })
+    expect(res).toEqual([])
+  })
+
+  it('祖先链中段缺失（父被删除）：截断于已收集链，与原逐级 break 语义一致', async () => {
+    // doc-c → doc-b 正常；doc-b 的父 doc-a 被删除 → 图中 doc-b.parentId 指向不存在的节点？
+    // 本 fixture 反其道：图内 doc-b.parentId = 'doc-a'，但第二轮过滤掉 doc-a（模拟已删除）
+    ALL_DOCS[0].isDeleted = true
+    const res = await getDocBreadcrumbFn({ data: { docId: 'doc-c', kbId: 'kb-1' } })
+    // doc-a title 缺失 → break 于 doc-c/doc-b 两项
+    expect(res).toEqual([
+      { id: 'doc-b', title: '子文档' },
+      { id: 'doc-c', title: '孙文档' },
+    ])
+    ALL_DOCS[0].isDeleted = false
+  })
+})

package/src/server/serverFns/__tests__/knowledge-index.test.ts

@@ -74,7 +74,7 @@ vi.mock('@/lib/vector-store', () => ({
   }),
 }))
 
-import { extractText, resolveAiConfig } from '../knowledge-index-utils'
+import { extractText, resolveAiConfig } from '../../knowledge/knowledge-index-utils'
 
 const KB = { id: 'kb-1', userId: 'user-1' }