@allbluecn/web-app 0.19.5 → 0.21.0

package/src/routes/_nav/bugs/$bugId/route.lazy.tsx

@@ -17,8 +17,8 @@
 
 import { createLazyFileRoute, useNavigate } from "@tanstack/react-router";
 import { useState } from "react";
-import type { BugDetail } from "@/components/bug/types";
-import type { UserBrief } from "@/components/story/types";
+import type { BugDetail } from "@/shared/bug/types";
+import type { UserBrief } from "@/shared/story/types";
 import { BugDetailBody } from "@/components/bug/detail/bug-detail-body";
 import { BugPanelHeader } from "@/components/bug/bug-panel-header";
 

package/src/routes/_nav/projects/$projectId/iterations/$iterationId/route.lazy.tsx

@@ -32,7 +32,7 @@ import { listProjectsBriefFn } from "@/server/serverFns/project";
 import { toast } from "@/components/ui/toast";
 import { useQuery } from "@tanstack/react-query";
 import type { IterationSummary } from "@/server/serverFns/iteration/schemas";
-import type { StoryState } from "@/components/story/constants";
+import type { StoryState } from "@/shared/story/constants";
 import type { AvatarConfig } from "@allbluecn/kernel";
 import { m } from "@/paraglide/messages.js";
 import { toastError } from "@/lib/toast-error";

package/src/routes/_nav/route.tsx

@@ -23,8 +23,7 @@ import { listPinnedWorkspacesBriefFn } from '@/server/serverFns/workspace'
 import { listKnowledgeFn } from '@/server/serverFns/knowledge'
 import { ensureVerifyReminderFn } from '@/server/serverFns/auth/verify-reminder'
 import { getSidebarStateFn } from '@/server/serverFns/sidebar-state'
-import { WORKSPACES_QUERY_KEY } from '@/lib/collections/reference/workspaces-collection'
-import { KNOWLEDGE_BASES_QUERY_KEY } from '@/lib/collections/knowledge/knowledge-bases-collection'
+import { WORKSPACES_QUERY_KEY, KNOWLEDGE_BASES_QUERY_KEY } from '@/lib/collections/query-keys'
 import { GlobalErrorBoundary } from '@/components/error/global-error-boundary'
 import { NavNotFound } from './-components/nav-not-found'
 

package/src/routes/_nav/stories/$storyId/route.lazy.tsx

@@ -17,9 +17,9 @@
 
 import { createLazyFileRoute, useNavigate, useRouter } from "@tanstack/react-router";
 import { useCallback, useState, type UIEvent } from "react";
-import type { StoryDetail, UserBrief, CommentWithReplies, ActivityItem, RelationsData } from "@/components/story/types";
+import type { StoryDetail, UserBrief, CommentWithReplies, ActivityItem, RelationsData } from "@/shared/story/types";
 import type { IterationSummary } from "@/server/serverFns/iteration/schemas";
-import type { StoryState } from "@/components/story/constants";
+import type { StoryState } from "@/shared/story/constants";
 import { StoryDetailBody } from "@/components/story/detail/story-detail-body";
 import { StoryPanelHeader } from "@/components/story/story-panel-header";
 

package/src/routes/_nav/stories/$storyId/route.tsx

@@ -35,7 +35,7 @@ import { listProjectsBriefFn } from "@/server/serverFns/project";
 import { listIterationsFn } from "@/server/serverFns/iteration";
 import { getCollabSnapshotFn } from "@/server/serverFns/collab-snapshot";
 import { isCollabEnabled } from "@/lib/collab/env";
-import type { RelationsData } from "@/components/story/types";
+import type { RelationsData } from "@/shared/story/types";
 import { StoryDetailSkeleton } from "../-components/story-detail-skeleton";
 
 // 「关联需求」选择源拉取上限：超过该数的需求会被静默截断（组件端无搜索补拉），

package/src/routes/api/design/prototype/__tests__/route.test.ts

@@ -450,6 +450,9 @@ describe('/api/design/prototype 流式生成', () => {
     expect(eventsOf(events, 'canvas/nodes')).toHaveLength(1)
     const dones = eventsOf(events, 'canvas/done')
     expect(dones).toHaveLength(1)
-    expect((dones[0].value as { message: string }).message.length).toBeGreaterThan(0)
+    // 文案协议化（2026-10-28）：服务端只回 status，完成文案由客户端 m.canvas_ai_doneFallback()
+    // 渲染；无 LLM 总结时 message 缺省（不再由服务端塞中文）
+    expect((dones[0].value as { status: string }).status).toBe('completed')
+    expect((dones[0].value as { message?: string }).message).toBeUndefined()
   })
 })

package/src/server/__tests__/task-executor.test.ts

@@ -20,6 +20,10 @@ vi.mock('@allbluecn/database', () => ({
     testCase: { findUnique: vi.fn() },
   },
 }))
+// 源条目属主校验（2026-10-28 审计 A4x-1）：测试默认按「是项目成员」放行，
+// 需要验证拒绝路径时在用例内改 mock
+vi.mock('@/server/lib/project-membership', () => ({ isProjectMember: vi.fn(async () => true) }))
+
 vi.mock('@/server/ai-task/context-builder', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@/server/ai-task/context-builder')>()
   return { ...actual, buildSourceContextBlock: vi.fn(() => '## 需求上下文（mock）') }
@@ -257,6 +261,7 @@ describe('executeAiTaskRun', () => {
 
   it('源型 story：查源表并注入 buildSourceContextBlock 输出到 systemPrompts', async () => {
     storyFindUnique.mockResolvedValue({
+      projectId: 'p1',
       identifier: 'ALB-S12',
       name: '登录页重构',
       description: null,
@@ -272,6 +277,7 @@ describe('executeAiTaskRun', () => {
     expect(storyFindUnique).toHaveBeenCalledWith({
       where: { id: 'story-1' },
       select: expect.objectContaining({
+        projectId: true,
         identifier: true,
         name: true,
         description: true,
@@ -308,6 +314,7 @@ describe('executeAiTaskRun', () => {
 
   it('源型分发：bug / testcase 各查对应表', async () => {
     bugFindUnique.mockResolvedValue({
+      projectId: 'p1',
       identifier: 'ALB-B3',
       title: '首页白屏',
       severity: 'critical',

package/src/server/ai-gateway/__tests__/ai-output-guard.test.ts

@@ -27,7 +27,7 @@ describe("scanAiOutputForSecrets 输出泄露检测", () => {
   })
 
   it.each([
-    ["OpenAI key 回显", "配置的密钥是 sk-proj-abc123def456ghi789jkl012"],
+    ["OpenAI key 回显", "配置的密钥是 sk-proj-abcdefghijkmnopqrstuv"],
     ["Bearer token 回显", "token 为 Bearer eyJhbGciOiJIUzI1NiJ9.payload"],
     ["anthropic key 回显", "sk-ant-api03-x7y8z9w0v1u2t3s4r5q6p7o8"],
     ["系统 prompt 回显", "我的系统提示词是：你是一个敏捷开发中的需求分析师。"],
@@ -41,7 +41,7 @@ describe("scanAiOutputForSecrets 输出泄露检测", () => {
   })
 
   it.each([
-    ["openai-key", "密钥 sk-proj-abc123def456ghi789jkl012"],
+    ["openai-key", "密钥 sk-proj-abcdefghijkmnopqrstuv"],
     ["anthropic-key", "密钥 sk-ant-api03-x7y8z9w0v1u2t3s4r5q6p7o8"],
     ["bearer-token", "token 为 Bearer eyJhbGciOiJIUzI1NiJ9.payload"],
     ["jwt", "令牌 eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiIxMjMifQ 已生成"],
@@ -60,13 +60,13 @@ describe("scanAiOutputForSecrets 输出泄露检测", () => {
   })
 
   it("命中清单不含原文泄露（防扫描器自身成为泄露面）", () => {
-    const secret = "sk-proj-abc123def456ghi789jkl012"
+    const secret = "sk-proj-abcdefghijkmnopqrstuv"
     const r = scanAiOutputForSecrets(`密钥 ${secret} 已泄露`)
     expect(JSON.stringify(r)).not.toContain(secret)
   })
 
   it("同一文本重复调用两次结果一致（/g 正则 lastIndex 复位）", () => {
-    const text = "配置 sk-proj-abc123def456ghi789jkl012 并部署到 192.168.1.100"
+    const text = "配置 sk-proj-abcdefghijkmnopqrstuv 并部署到 192.168.1.100"
     const a = scanAiOutputForSecrets(text)
     const b = scanAiOutputForSecrets(text)
     expect(b).toEqual(a)

package/src/server/ai-gateway/__tests__/tools-authorization.test.ts

@@ -208,4 +208,29 @@ describe("reindex_knowledge_base 归属", () => {
     expect(out).toEqual({ indexed: 1, documentCount: 1 })
     expect(mocks.deleteEmbeddings).toHaveBeenCalledWith("knowledge_embeddings", "kbId", "kb-1")
   })
+
+  it("S26：同 KB 重建进行中拒绝并发触发，完成后可再次重建", async () => {
+    mocks.kb.findFirst.mockResolvedValue({ id: "kb-2" })
+    // 用受控 promise 拉长首例重建，制造 in-flight 窗口
+    let release!: () => void
+    const gate = new Promise<void>((r) => { release = r })
+    mocks.doc.findMany.mockImplementation(async () => {
+      await gate
+      return [{ id: "d-1", title: "t", content: "c", kbId: "kb-2" }]
+    })
+
+    const first = run({ knowledgeBaseId: "kb-2" }, { context: ctxWith() })
+    await expect(
+      run({ knowledgeBaseId: "kb-2" }, { context: ctxWith() }),
+    ).rejects.toThrow("正在重建索引")
+    release()
+    await expect(first).resolves.toEqual({ indexed: 1, documentCount: 1 })
+
+    // 释放后可再次重建
+    mocks.doc.findMany.mockResolvedValue([{ id: "d-1", title: "t", content: "c", kbId: "kb-2" }])
+    await expect(run({ knowledgeBaseId: "kb-2" }, { context: ctxWith() })).resolves.toEqual({
+      indexed: 1,
+      documentCount: 1,
+    })
+  })
 })

package/src/server/ai-gateway/tools/server.ts

@@ -24,6 +24,7 @@ import { constrainKnowledgeBaseId, mergeKnowledgeResults, type KnowledgeSearchIn
 import { todoWriteTool } from "./todo-write"
 import { planSubmitTool } from "./plan-submit"
 import { ToolValidationError, toToolErrorMessage } from "./tool-errors"
+import { tryAcquireReindex, releaseReindex } from "@/server/knowledge/reindex-guard"
 
 /**
  * knowledge_search 的执行逻辑（从 tool 定义中抽出，使返回边界可被直接单测）。
@@ -288,25 +289,33 @@ const reindexKnowledgeBaseTool = reindexKnowledgeBaseDef.server<AppContext>(
     })
     if (!kb) throw new ToolValidationError("knowledgeBaseId 不存在或无权限")
 
-    const docs = await prisma.knowledgeDocument.findMany({
-      where: { kbId: knowledgeBaseId, isDeleted: false },
-      select: { id: true, title: true, content: true, kbId: true },
-    })
+    // S26：同 KB 重建进行中拒绝重复触发
+    if (!tryAcquireReindex(knowledgeBaseId)) {
+      throw new ToolValidationError("该知识库正在重建索引，请稍后再试")
+    }
+    try {
+      const docs = await prisma.knowledgeDocument.findMany({
+        where: { kbId: knowledgeBaseId, isDeleted: false },
+        select: { id: true, title: true, content: true, kbId: true },
+      })
 
-    const aiConfig = await getPorts().infra.resolveKnowledgeAiConfig(knowledgeBaseId)
+      const aiConfig = await getPorts().infra.resolveKnowledgeAiConfig(knowledgeBaseId)
 
-    await getPorts().infra.deleteEmbeddings("knowledge_embeddings", "kbId", knowledgeBaseId)
+      await getPorts().infra.deleteEmbeddings("knowledge_embeddings", "kbId", knowledgeBaseId)
 
-    let total = 0
-    for (const doc of docs) {
-      const indexed = await getPorts().infra.indexDocumentEmbeddings(
-        { id: doc.id, kbId: doc.kbId, title: doc.title, content: doc.content as string },
-        aiConfig
-      )
-      total += indexed
-    }
+      let total = 0
+      for (const doc of docs) {
+        const indexed = await getPorts().infra.indexDocumentEmbeddings(
+          { id: doc.id, kbId: doc.kbId, title: doc.title, content: doc.content as string },
+          aiConfig
+        )
+        total += indexed
+      }
 
-    return { indexed: total, documentCount: docs.length }
+      return { indexed: total, documentCount: docs.length }
+    } finally {
+      releaseReindex(knowledgeBaseId)
+    }
   },
 )
 

package/src/server/knowledge/reindex-guard.ts

@@ -0,0 +1,35 @@
+// 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/>.
+
+// S26（审计 A3x ⚪）：reindex 并发去抖——同 KB 重建进行中拒绝重复触发，
+// 防 embedding 配额双倍消耗与「先删后建」窗口交叠。进程内存态（与
+// rate-limit.ts 同边界声明）：多实例部署不共享，各实例至多一个重建在途；
+// 分布式锁（DB 标记/Redis）属独立架构任务，落地前不得把本守卫视为唯一防线。
+
+const inFlightReindex = new Set<string>();
+
+/** 尝试占用 kbId 的重建锁；false = 已有重建在途（调用方应拒绝请求） */
+export function tryAcquireReindex(kbId: string): boolean {
+  if (inFlightReindex.has(kbId)) return false;
+  inFlightReindex.add(kbId);
+  return true;
+}
+
+/** 释放重建锁（调用方 finally 中必须调用） */
+export function releaseReindex(kbId: string): void {
+  inFlightReindex.delete(kbId);
+}

package/src/server/lib/__tests__/cron-auth.test.ts

@@ -21,7 +21,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { isCronRequestAuthorized, verifyCronSecret } from "../cron-auth";
 
-const SECRET = "cron-secret-0123456789abcdef";
+const SECRET = "cron-secret-fakefakefakefakefake";
 
 const reqWith = (authorization: string | null): Request => {
   const h = new Headers();

package/src/server/serverFns/__tests__/legal-code-canonical.test.ts

@@ -0,0 +1,169 @@
+// 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/>.
+
+// 审计 S7（2026-10-28）LegalRegulation.code 持久化回归：
+// - update：canonicalId 仅在显式传 code 时重算（compliance 同款裁定），
+//   仅改 title 一律不漂移（有 code 行身份=code；无 code 存量行保持创建时 key）；
+// - code 落库 + 空串归一 null；
+// - create：code 落库 + canonicalId = code || title。
+
+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>) {
+        const wrapped = async (args: unknown) => {
+          let data = (args as { data?: unknown } | null | undefined)?.data
+          if (this._validator && data !== undefined) {
+            const v = this._validator as { parse?: (d: unknown) => unknown }
+            data = v.parse ? v.parse(data) : data
+          }
+          return fn({ data })
+        }
+        return wrapped
+      },
+    }
+    return api
+  },
+}))
+
+vi.mock('@tanstack/react-start/server', () => ({
+  getRequest: vi.fn(),
+}))
+
+const m = vi.hoisted(() => ({
+  legalRegulation: {
+    findUnique: vi.fn(),
+    create: vi.fn(),
+    update: vi.fn(),
+  },
+}))
+
+vi.mock('@allbluecn/database/get-prisma', () => ({ getPrisma: async () => m }))
+vi.mock('@allbluecn/database', () => ({ Prisma: {} }))
+
+vi.mock('@/server/auth-helpers', () => ({ requireAuth: vi.fn() }))
+
+import { requireAuth } from '@/server/auth-helpers'
+import * as updateMod from '../knowledge/public/legal/update'
+import * as createMod from '../knowledge/public/legal/create'
+
+const mockRequireAuth = vi.mocked(requireAuth)
+
+describe('updateLegalFn：code 持久化 + canonicalId 重算口径（S7）', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockRequireAuth.mockResolvedValue({ user: { id: 'u1', role: 'USER' } } as never)
+    m.legalRegulation.update.mockResolvedValue({ id: 'row-1' })
+  })
+
+  it('仅改 title（有 code 行）→ canonicalId 保持 code 维度不漂移，code 不重写', async () => {
+    m.legalRegulation.findUnique.mockResolvedValue({
+      id: 'row-1', userId: 'u1', title: '旧标题', code: 'GB 4943', canonicalId: 'GB 4943',
+    })
+    await updateMod.updateLegalFn({ data: { id: 'row-1', title: '新标题' } })
+    expect(m.legalRegulation.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.not.objectContaining({ canonicalId: expect.anything(), code: expect.anything() }),
+      }),
+    )
+  })
+
+  it('仅改 title（无 code 存量行）→ canonicalId 保持创建时 key 不失联', async () => {
+    m.legalRegulation.findUnique.mockResolvedValue({
+      id: 'row-1', userId: 'u1', title: '旧标题', code: null, canonicalId: '旧标题',
+    })
+    await updateMod.updateLegalFn({ data: { id: 'row-1', title: '新标题' } })
+    expect(m.legalRegulation.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.not.objectContaining({ canonicalId: expect.anything() }),
+      }),
+    )
+  })
+
+  it('显式传 code → code 落库且 canonicalId 以 code 重算', async () => {
+    m.legalRegulation.findUnique.mockResolvedValue({
+      id: 'row-1', userId: 'u1', title: '旧标题', code: null, canonicalId: '旧标题',
+    })
+    await updateMod.updateLegalFn({ data: { id: 'row-1', code: 'GB 4943' } })
+    expect(m.legalRegulation.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ code: 'GB 4943', canonicalId: 'GB 4943' }),
+      }),
+    )
+  })
+
+  it('code 传空串 → 归一为 null 落库，canonicalId 回落 title 维度', async () => {
+    m.legalRegulation.findUnique.mockResolvedValue({
+      id: 'row-1', userId: 'u1', title: '旧标题', code: 'GB 4943', canonicalId: 'GB 4943',
+    })
+    await updateMod.updateLegalFn({ data: { id: 'row-1', code: '' } })
+    expect(m.legalRegulation.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ code: null, canonicalId: '旧标题' }),
+      }),
+    )
+  })
+
+  it('code + title 同传 → code 维度优先', async () => {
+    m.legalRegulation.findUnique.mockResolvedValue({
+      id: 'row-1', userId: 'u1', title: '旧标题', code: null, canonicalId: '旧标题',
+    })
+    await updateMod.updateLegalFn({ data: { id: 'row-1', title: '新标题', code: 'GB 4943-2024' } })
+    expect(m.legalRegulation.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ code: 'GB 4943-2024', canonicalId: 'GB 4943-2024' }),
+      }),
+    )
+  })
+})
+
+describe('createLegalFn：code 落库（S7）', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockRequireAuth.mockResolvedValue({ user: { id: 'u1', role: 'USER' } } as never)
+    m.legalRegulation.create.mockResolvedValue({ id: 'new-1' })
+  })
+
+  it('传 code → 落库且 canonicalId = code', async () => {
+    await createMod.createLegalFn({
+      data: { title: '某标准', code: 'GB 4943', jurisdiction: 'CN_NATIONAL', category: '安全', tags: [] },
+    })
+    expect(m.legalRegulation.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ code: 'GB 4943', canonicalId: 'GB 4943' }),
+      }),
+    )
+  })
+
+  it('不传 code → code 落 null，canonicalId = title', async () => {
+    await createMod.createLegalFn({
+      data: { title: '某办法', jurisdiction: 'CN_LOCAL', category: '管理', tags: [] },
+    })
+    expect(m.legalRegulation.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ code: null, canonicalId: '某办法' }),
+      }),
+    )
+  })
+})

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

@@ -82,7 +82,6 @@ import {
   addChildFn,
   removeChildFn,
 } from "../story/story-tree";
-import { STORY_LIST_SELECT, castStoryUsers } from "../../story/types";
 
 const USER = "u-current";
 const PARENT = "st-parent";

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

@@ -123,7 +123,8 @@ describe("castStoryUsers", () => {
   it("头像配置保留非空 JSON", () => {
     const cfg = { bgShape: "blob", bgColor: "#0000ff", parts: [] };
     const res = castStoryUsers(storyFull({ assignee: userBrief({ avatarConfig: cfg }) }));
-    expect(res.assignee.avatarConfig).toEqual(cfg);
+    // 测试构造的入参 assignee 非空，按行类型声明收窄
+    expect(res.assignee!.avatarConfig).toEqual(cfg);
   });
 
   it("主列表 select 携带 iteration（甘特迭代分组数据源，缺失即退化为单一无迭代组）", () => {

package/src/server/serverFns/__tests__/update-bug-guard.test.ts

@@ -92,7 +92,7 @@ vi.mock("@/server/collab/write-guard", () => ({
 }));
 
 import { updateBugFn } from "../bug/bug-crud";
-import { BUG_LIST_SELECT } from "@/components/bug/types";
+import { BUG_LIST_SELECT } from "@/shared/bug/types";
 
 const U = "u-1";
 const P = "pr-1";

package/src/server/serverFns/bug/__tests__/bug-comments.test.ts

@@ -93,7 +93,7 @@ import {
   listCommentsFn,
   updateCommentFn,
 } from "../bug-comments";
-import { BUG_USER_BRIEF_SELECT } from "@/components/bug/types";
+import { BUG_USER_BRIEF_SELECT } from "@/shared/bug/types";
 
 const USER = "u-current";
 const OTHER = "u-other";
@@ -133,18 +133,29 @@ beforeEach(() => {
 });
 
 describe("listCommentsFn", () => {
-  it("按 createdAt 升序取出后组装为多级回复树", async () => {
-    mocks.bugCommentFindMany.mockResolvedValue([
-      commentRow({ id: "c1", parentId: null }),
-      commentRow({ id: "c2", parentId: "c1" }),
-      commentRow({ id: "c3", parentId: "c2" }),
-    ]);
+  // 新契约（S39）：根评论分页查询 + 回复整树查询，两次 findMany 分别 mock
+  const mockRootsAndReplies = (roots: unknown[], replies: unknown[] = []) => {
+    mocks.bugCommentFindMany.mockResolvedValueOnce(roots).mockResolvedValueOnce(replies);
+  };
+
+  it("首页取根评论（take+1 探测）+ 回复整树随根，组装多级回复树", async () => {
+    mockRootsAndReplies(
+      [
+        commentRow({ id: "c1", parentId: null }),
+        commentRow({ id: "c2", parentId: null }),
+      ],
+      [
+        commentRow({ id: "r1", parentId: "c1" }),
+        commentRow({ id: "r2", parentId: "r1" }),
+      ],
+    );
 
     const res = await listCommentsFn({ data: { bugId: BUG_ID } });
 
-    expect(mocks.bugCommentFindMany).toHaveBeenCalledWith({
-      where: { bugId: BUG_ID },
-      orderBy: { createdAt: "asc" },
+    expect(mocks.bugCommentFindMany).toHaveBeenNthCalledWith(1, {
+      where: { bugId: BUG_ID, parentId: null },
+      orderBy: [{ createdAt: "asc" }, { id: "asc" }],
+      take: 51,
       select: {
         id: true,
         content: true,
@@ -155,57 +166,97 @@ describe("listCommentsFn", () => {
         reactions: { select: { emoji: true, userId: true } },
       },
     });
-    expect(res).toHaveLength(1);
-    expect(res[0].id).toBe("c1");
-    expect(res[0].parentId).toBeNull();
-    expect(res[0].createdAt).toBe(T1.toISOString());
-    expect(res[0].user.id).toBe(USER);
-    expect(res[0].reactions).toEqual([]);
-    expect(res[0].replies).toHaveLength(1);
-    expect(res[0].replies[0].id).toBe("c2");
-    expect(res[0].replies[0].parentId).toBe("c1");
-    expect(res[0].replies[0].reactions).toEqual([]);
-    expect(res[0].replies[0].replies).toHaveLength(1);
-    expect(res[0].replies[0].replies[0].id).toBe("c3");
-    expect(res[0].replies[0].replies[0].replies).toEqual([]);
+    expect(mocks.bugCommentFindMany).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ where: { bugId: BUG_ID, parentId: { in: ["c1", "c2"] } } }),
+    );
+    expect(res.nextCursor).toBeNull();
+    expect(res.items).toHaveLength(2);
+    expect(res.items[0].id).toBe("c1");
+    expect(res.items[0].createdAt).toBe(T1.toISOString());
+    expect(res.items[0].user.id).toBe(USER);
+    expect(res.items[0].replies).toHaveLength(1);
+    expect(res.items[0].replies[0].id).toBe("r1");
+    expect(res.items[0].replies[0].replies[0].id).toBe("r2");
+    expect(res.items[1].id).toBe("c2");
+    expect(res.items[1].replies).toEqual([]);
   });
 
-  it("评论 reaction 计数聚合并入评论查询（当前用户已表态 reacted=true）", async () => {
-    mocks.bugCommentFindMany.mockResolvedValue([
-      commentRow({
-        id: "c1",
-        reactions: [
-          { emoji: "👍", userId: USER },
-          { emoji: "👍", userId: OTHER },
-          { emoji: "🎉", userId: OTHER },
-        ],
-      }),
+  it("超过 take 时 nextCursor 指向下一页锚点，items 截到 take", async () => {
+    mockRootsAndReplies([
+      commentRow({ id: "c1", parentId: null }),
+      commentRow({ id: "c2", parentId: null }),
+      commentRow({ id: "c3", parentId: null, createdAt: T2 }), // take+1 探测行
     ]);
 
+    const res = await listCommentsFn({ data: { bugId: BUG_ID, take: 2 } });
+
+    expect(mocks.bugCommentFindMany).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ take: 3 }),
+    );
+    expect(res.items.map((c) => c.id)).toEqual(["c1", "c2"]);
+    expect(res.nextCursor).toBe("c3");
+  });
+
+  it("cursor 续拉：skip 1 跳过锚行，回复只查当前页根", async () => {
+    mockRootsAndReplies([commentRow({ id: "c9", parentId: null, createdAt: T2 })]);
+
+    const res = await listCommentsFn({ data: { bugId: BUG_ID, cursor: "c2" } });
+
+    expect(mocks.bugCommentFindMany).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ cursor: { id: "c2" }, skip: 1, take: 51 }),
+    );
+    expect(mocks.bugCommentFindMany).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ where: { bugId: BUG_ID, parentId: { in: ["c9"] } } }),
+    );
+    expect(res.items).toHaveLength(1);
+    expect(res.nextCursor).toBeNull();
+  });
+
+  it("评论 reaction 计数聚合并入评论查询（当前用户已表态 reacted=true）", async () => {
+    mockRootsAndReplies(
+      [
+        commentRow({
+          id: "c1",
+          reactions: [
+            { emoji: "👍", userId: USER },
+            { emoji: "👍", userId: OTHER },
+            { emoji: "🎉", userId: OTHER },
+          ],
+        }),
+      ],
+      [],
+    );
+
     const res = await listCommentsFn({ data: { bugId: BUG_ID } });
 
-    expect(res[0].reactions).toEqual([
+    expect(res.items[0].reactions).toEqual([
       { emoji: "👍", count: 2, userIds: [USER, OTHER], reacted: true },
       { emoji: "🎉", count: 1, userIds: [OTHER], reacted: false },
     ]);
   });
 
   it("parentId 指向不存在评论的孤儿回复被丢弃（照 story 实际行为）", async () => {
-    mocks.bugCommentFindMany.mockResolvedValue([
-      commentRow({ id: "c1", parentId: null }),
-      commentRow({ id: "c-orphan", parentId: "c-missing" }),
-    ]);
+    mockRootsAndReplies(
+      [commentRow({ id: "c1", parentId: null })],
+      [commentRow({ id: "c-orphan", parentId: "c-missing" })],
+    );
 
     const res = await listCommentsFn({ data: { bugId: BUG_ID } });
 
-    expect(res).toHaveLength(1);
-    expect(res[0].id).toBe("c1");
-    expect(res[0].replies).toEqual([]);
+    expect(res.items).toHaveLength(1);
+    expect(res.items[0].id).toBe("c1");
+    expect(res.items[0].replies).toEqual([]);
   });
 
-  it("无评论时返回空数组", async () => {
-    mocks.bugCommentFindMany.mockResolvedValue([]);
-    await expect(listCommentsFn({ data: { bugId: BUG_ID } })).resolves.toEqual([]);
+  it("无评论时返回空 items 且不发起回复查询", async () => {
+    mockRootsAndReplies([]);
+    const res = await listCommentsFn({ data: { bugId: BUG_ID } });
+    expect(res).toEqual({ items: [], nextCursor: null });
+    expect(mocks.bugCommentFindMany).toHaveBeenCalledTimes(1);
   });
 
   it("项目非成员拒绝且不查询评论", async () => {