@allbluecn/web-app 0.18.2 → 0.19.0

package/src/server/serverFns/collab-snapshot.ts

@@ -0,0 +1,201 @@
+// 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/>.
+
+// 实体协同快照取用 serverFn（Yjs 多人协作 §5.2 首次种子化 / §6 SSR 初始
+// 快照链路，任务 14 知识库 + 任务 20 泛化 entity-story）：
+// requireAuth → assertCollabAccess（各 room 的唯一授权裁决点）→ §5.2 三态
+// 判定 → 返回 base64 编码的 Y.Doc update（客户端 Y.applyUpdate）。
+//
+// entityType 泛化（任务 20）：knowledge（缺省，任务 15 loader 兼容）与
+// story 两型按需分派「业务列读取 + 内容提取 + 种子化」策略；任务 22 的
+// bug/case 在枚举与分派表追加即可。两型共享同一三态语义与
+// CollabDocument 存取（room 名由 buildRoomName 按型构造）。
+//
+// 三态语义（规格 §5.2 逐字）：
+// - 无 CollabDocument 且业务列有内容 → 服务端种子化（html → Y.Doc → 写
+//   CollabDocument）后返回快照
+// - 有快照且业务列较新（旁路写入发生过，比较业务表 updatedAt vs
+//   CollabDocument.updatedAt）→ 重种子化（DB 内容覆盖 Y 快照）
+// - 正常 → 返回快照
+// - 业务列无内容（空文档）→ snapshot null，客户端自建空 Y.Doc
+//
+// serverFn 纯净纪律：本文件只准 export createServerFn 产物；种子化与内容
+// 解析在 @/server/collab/seed（handler 内引用，客户端 split 后剥离）。
+
+import { createServerFn } from '@tanstack/react-start'
+import { getRequest } from '@tanstack/react-start/server'
+import { z } from 'zod'
+import { getPrisma } from '@allbluecn/database/get-prisma'
+import { buildRoomName } from '@allbluecn/collab-core/rooms'
+import { normalizeCollabSteps } from '@allbluecn/collab-core/steps'
+import { requireAuth, ForbiddenError } from '@/server/auth-helpers'
+import { assertCollabAccess } from '@/server/collab-permissions'
+import {
+  extractKnowledgeDocHtml,
+  extractStoryDescriptionHtml,
+  extractDesignDocHtml,
+  hasDesignCanvasContent,
+  seedKnowledgeDoc,
+  seedStoryDoc,
+  seedBugDoc,
+  seedCaseDoc,
+  seedDesignPageDoc,
+} from '@/server/collab/seed'
+
+/**
+ * 打开知识库文档 / 需求 / BUG / 用例详情时的协同快照（首次种子化入口）。
+ * view/edit 均可调用（只读协同同样需要初始快照）；授权口径见
+ * assertCollabAccess（owner ≥ edit、viewer → view、空间外 Forbidden）。
+ */
+export const getCollabSnapshotFn = createServerFn({ method: 'POST' })
+  .validator(
+    z.object({
+      /** room 实体型（缺省 knowledge = 任务 15 知识库 loader 的既有入参形态） */
+      entityType: z.enum(['knowledge', 'story', 'bug', 'case', 'design']).default('knowledge'),
+      docId: z.string().min(1),
+    }),
+  )
+  .handler(async ({ data }) => {
+    const request = getRequest()
+    const session = await requireAuth(request)
+    const userId = session.user!.id!
+
+    await assertCollabAccess(data.entityType, data.docId, userId)
+
+    const prisma = await getPrisma()
+    const roomName =
+      data.entityType === 'story'
+        ? buildRoomName({ kind: 'entity-story', storyId: data.docId })
+        : data.entityType === 'bug'
+          ? buildRoomName({ kind: 'entity-bug', bugId: data.docId })
+          : data.entityType === 'case'
+            ? buildRoomName({ kind: 'entity-case', caseId: data.docId })
+            : data.entityType === 'design'
+              ? buildRoomName({ kind: 'design-canvas', pageId: data.docId })
+              : buildRoomName({ kind: 'knowledge-doc', docId: data.docId })
+    const existing = await prisma.collabDocument.findUnique({
+      where: { roomName },
+      select: { state: true, updatedAt: true },
+    })
+
+    // 按型分派：业务列读取（单次，消除双读 TOCTOU 窗口）+ 内容提取。
+    // 各型 select 形状不同，分支内各自读取后收敛为 (html, steps, updatedAt)。
+    let html: string | null
+    let steps: ReturnType<typeof normalizeCollabSteps> = null
+    let businessUpdatedAt: Date
+    let storyDescriptionRaw: string | null = null
+    let knowledgeContent: unknown
+    let designCanvas: unknown
+    if (data.entityType === 'story') {
+      const row = await prisma.story.findUnique({
+        where: { id: data.docId },
+        select: { description: true, updatedAt: true },
+      })
+      if (!row) {
+        // assertCollabAccess 对不存在文档 fail-closed，此处是竞态删除兜底
+        throw new ForbiddenError('协同实体不存在')
+      }
+      storyDescriptionRaw = row.description
+      html = extractStoryDescriptionHtml(row.description)
+      businessUpdatedAt = row.updatedAt
+    } else if (data.entityType === 'bug') {
+      const row = await prisma.bug.findUnique({
+        where: { id: data.docId },
+        select: { description: true, reproduceSteps: true, updatedAt: true },
+      })
+      if (!row) {
+        throw new ForbiddenError('协同实体不存在')
+      }
+      html = extractStoryDescriptionHtml(row.description)
+      // Bug.reproduceSteps 与 TestCase.steps 同构（{steps:[...]}）——同一归一化
+      steps = normalizeCollabSteps(row.reproduceSteps)
+      businessUpdatedAt = row.updatedAt
+    } else if (data.entityType === 'case') {
+      const row = await prisma.testCase.findUnique({
+        where: { id: data.docId },
+        select: { steps: true, updatedAt: true },
+      })
+      if (!row) {
+        throw new ForbiddenError('协同实体不存在')
+      }
+      html = null
+      steps = normalizeCollabSteps(row.steps)
+      businessUpdatedAt = row.updatedAt
+    } else if (data.entityType === 'design') {
+      // 任务 29（§7.1 设计画布行）：Y 属主面 = canvas Y 树 + 文档 fragment
+      // 双载体。canvas 双格式存量（新 LeaferJSONPackage / 旧扁平 SceneDocument）
+      // ——种子化惰性迁移；content 走 DocContent.html 提取。
+      const row = await prisma.designPage.findUnique({
+        where: { id: data.docId },
+        select: { canvas: true, content: true, updatedAt: true },
+      })
+      if (!row) {
+        throw new ForbiddenError('协同实体不存在')
+      }
+      designCanvas = row.canvas
+      html = extractDesignDocHtml(row.content)
+      businessUpdatedAt = row.updatedAt
+    } else {
+      const row = await prisma.knowledgeDocument.findUnique({
+        where: { id: data.docId },
+        select: { content: true, updatedAt: true },
+      })
+      if (!row) {
+        throw new ForbiddenError('协同实体不存在')
+      }
+      knowledgeContent = row.content
+      html = extractKnowledgeDocHtml(row.content)
+      businessUpdatedAt = row.updatedAt
+    }
+
+    const hasDesignCanvas =
+      data.entityType === 'design' && hasDesignCanvasContent(designCanvas)
+    if (!html && !steps && !hasDesignCanvas) {
+      // 空文档（含旁路清空）：DB 权威态为空，存量快照必须删除——
+      // 否则孤儿快照让 collab 服务载入旧房间态，被清空内容复活并可能
+      // 经回写固化。无快照则零成本空开（delete 不误发）。
+      if (existing) {
+        await prisma.collabDocument.delete({ where: { roomName } })
+      }
+      return { snapshot: null, seeded: false, roomName }
+    }
+    if (existing && businessUpdatedAt.getTime() <= existing.updatedAt.getTime()) {
+      return {
+        snapshot: Buffer.from(existing.state).toString('base64'),
+        seeded: false,
+        roomName,
+      }
+    }
+    // 无快照（首次种子化）或业务列较新（旁路写入 → 重种子化，DB 覆盖 Y 快照）
+    let state: Uint8Array
+    if (data.entityType === 'story') {
+      state = await seedStoryDoc(data.docId, storyDescriptionRaw)
+    } else if (data.entityType === 'bug') {
+      state = await seedBugDoc(data.docId, { html, steps })
+    } else if (data.entityType === 'case') {
+      state = await seedCaseDoc(data.docId, steps)
+    } else if (data.entityType === 'design') {
+      state = await seedDesignPageDoc(data.docId, { canvas: designCanvas, html })
+    } else {
+      state = await seedKnowledgeDoc(data.docId, knowledgeContent)
+    }
+    return {
+      snapshot: Buffer.from(state).toString('base64'),
+      seeded: true,
+      roomName,
+    }
+  })

package/src/server/serverFns/collab.ts

@@ -0,0 +1,153 @@
+// 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/>.
+
+// 协同 ticket 签发（Yjs 多人协作 §4.2）：
+// - createCollabTicketFn：成员实体协同（requireAuth → parseRoomName →
+//   roomAccessTarget → assertCollabAccess → 按 role 签发）。
+// - createSharePresenceTicketFn：分享页 presence（不要求登录，Share 有效性
+//   + 密码门禁复验 → guest/member ticket，role 恒 view，§9）。
+//
+// serverFn 纯净纪律：本文件只准 export createServerFn 产物；工具函数在
+// @/server/collab/ticket-utils。payload 语义与验签侧（apps/collab/src/auth.ts）
+// 对齐：room 原样写入（验签方校验与连接 room 严格相等）、exp 为 unix 秒。
+
+import { createServerFn } from '@tanstack/react-start'
+import { getRequest } from '@tanstack/react-start/server'
+import { z } from 'zod'
+import { getPrisma } from '@allbluecn/database/get-prisma'
+import { buildRoomName } from '@allbluecn/collab-core/rooms'
+import { signTicket } from '@allbluecn/collab-core/ticket'
+import { requireAuth, ForbiddenError } from '@/server/auth-helpers'
+import { getCurrentSession } from '@/lib/session'
+import {
+  assertCollabAccess,
+  parseRoomName,
+  roomAccessTarget,
+} from '@/server/collab-permissions'
+import {
+  TICKET_TTL_SECONDS,
+  getCollabSecret,
+  newGuestSub,
+  normalizeNickname,
+  avatarBriefFromSessionUser,
+  shareGateClientIp,
+  verifyShareGatePassword,
+} from '@/server/collab/ticket-utils'
+
+/**
+ * 成员实体协同 ticket。presence/share 两类非实体 room 在签发入口即拒
+ * （授权走 assertCollabAccess，owner ≥ edit、viewer → view，§4.1）。
+ */
+export const createCollabTicketFn = createServerFn({ method: 'POST' })
+  .validator(z.object({ roomName: z.string().min(1) }))
+  .handler(async ({ data }) => {
+    const request = getRequest()
+    const session = await requireAuth(request)
+    const user = session.user!
+    const userId = user.id!
+
+    const room = parseRoomName(data.roomName)
+    const target = room ? roomAccessTarget(room) : null
+    if (!target) {
+      throw new ForbiddenError('非法协同 room')
+    }
+
+    const { role } = await assertCollabAccess(
+      target.entityType,
+      target.entityId,
+      userId,
+    )
+
+    const ticket = signTicket(
+      {
+        sub: userId,
+        name: user.name ?? '',
+        avatarBrief: avatarBriefFromSessionUser(user),
+        room: data.roomName,
+        role,
+        kind: 'member',
+        exp: Math.floor(Date.now() / 1000) + TICKET_TTL_SECONDS,
+      },
+      getCollabSecret(),
+    )
+    return { ticket }
+  })
+
+/**
+ * 分享页 presence ticket（§9：share:{token} room 全部 view）。
+ * 不要求登录：有有效登录 session（非桌面 guest）标 member 身份，否则 guest。
+ * 密码态 Share 复用 verifySharePasswordFn 的同一判定原语（客户端把
+ * sessionStorage 里的密码随请求带上，服务端 verifySharePassword 复验 +
+ * SEC-10 失败计数）。
+ */
+export const createSharePresenceTicketFn = createServerFn({ method: 'POST' })
+  .validator(
+    z.object({
+      shareToken: z.string().min(1),
+      nickname: z.string().optional(),
+      password: z.string().optional(),
+    }),
+  )
+  .handler(async ({ data }) => {
+    const request = getRequest()
+    const prisma = await getPrisma()
+    const share = await prisma.share.findUnique({
+      where: { token: data.shareToken },
+      select: {
+        token: true,
+        status: true,
+        expiresAt: true,
+        hasPassword: true,
+        password: true,
+      },
+    })
+    if (!share || share.status !== 'ACTIVE') {
+      throw new ForbiddenError('分享链接不可用')
+    }
+    if (share.expiresAt && share.expiresAt.getTime() < Date.now()) {
+      throw new ForbiddenError('分享链接不可用')
+    }
+
+    if (share.hasPassword) {
+      const passed = await verifyShareGatePassword({
+        ip: shareGateClientIp(request),
+        password: data.password,
+        storedPassword: share.password,
+      })
+      if (!passed) {
+        throw new ForbiddenError('分享密码校验未通过')
+      }
+    }
+
+    const session = await getCurrentSession(request)
+    const member =
+      session?.user?.id && !session.user.isGuest ? session.user : null
+
+    const ticket = signTicket(
+      {
+        sub: member ? member.id! : newGuestSub(),
+        name: member ? (member.name ?? '') : normalizeNickname(data.nickname),
+        avatarBrief: avatarBriefFromSessionUser(member ?? {}),
+        room: buildRoomName({ kind: 'share', shareToken: data.shareToken }),
+        role: 'view',
+        kind: member ? 'member' : 'guest',
+        exp: Math.floor(Date.now() / 1000) + TICKET_TTL_SECONDS,
+      },
+      getCollabSecret(),
+    )
+    return { ticket }
+  })

package/src/server/serverFns/design/__tests__/designs.test.ts

@@ -56,8 +56,6 @@ vi.mock('@allbluecn/database', () => ({
   prisma: {
     design: { create: vi.fn(), findFirst: vi.fn(), findMany: vi.fn(), update: vi.fn() },
     designPage: { aggregate: vi.fn() },
-    designTag: { findMany: vi.fn(), deleteMany: vi.fn(), createMany: vi.fn() },
-    tag: { findFirst: vi.fn() },
   },
 }))
 

package/src/server/serverFns/design/designs.ts

@@ -45,7 +45,6 @@ export const listDesignsFn = createServerFn({ method: 'GET' })
         description: true,
         createdAt: true,
         updatedAt: true,
-        designTags: { include: { tag: true } },
       },
     })
   })
@@ -132,66 +131,3 @@ export const deleteDesignFn = createServerFn({ method: 'POST' })
     return { success: true }
   })
 
-const assignTagsSchema = z.object({
-  designId: z.string(),
-  tagIds: z.array(z.string()),
-})
-
-export const assignTagsToDesignFn = createServerFn({ method: 'POST' })
-  .validator(assignTagsSchema)
-  .handler(async ({ data }) => {
-    const prisma = await getPrisma()
-    const request = getRequest()
-    const session = await getServerSeam().requireAuth(request)
-    const userId = session.user!.id!
-
-    const prd = await prisma.design.findFirst({ where: { id: data.designId, userId }, select: { id: true } })
-    if (!prd) throw new Error('FORBIDDEN')
-
-    // DB-01：标签鉴权从逐 tagId findFirst（N 次查询）改为一次 findMany in（含 userId 过滤）。
-    // 查询次数 before: 1 + N + 2(差量写) → after: 4（常数）
-    const requestedIds = [...new Set(data.tagIds)]
-    const ownedTags = requestedIds.length
-      ? await prisma.tag.findMany({ where: { id: { in: requestedIds }, userId }, select: { id: true } })
-      : []
-    if (ownedTags.length !== requestedIds.length) throw new Error('FORBIDDEN')
-
-    const current = await prisma.designTag.findMany({ where: { designId: data.designId }, select: { tagId: true } })
-    const currentSet = new Set(current.map((r) => r.tagId))
-    const targetSet = new Set(data.tagIds)
-
-    const toRemove = [...currentSet].filter((id) => !targetSet.has(id))
-    const toAdd = [...targetSet].filter((id) => !currentSet.has(id))
-
-    // DB-07：标签 diff 两步写包 $transaction（消除删除/新增半批残留）
-    if (toRemove.length || toAdd.length) {
-      await prisma.$transaction(async (tx) => {
-        if (toRemove.length) {
-          await tx.designTag.deleteMany({ where: { designId: data.designId, tagId: { in: toRemove } } })
-        }
-        if (toAdd.length) {
-          await tx.designTag.createMany({ data: toAdd.map((tagId) => ({ designId: data.designId, tagId })) })
-        }
-      })
-    }
-
-    return { success: true, added: toAdd.length, removed: toRemove.length }
-  })
-
-export const getDesignTagsFn = createServerFn({ method: 'GET' })
-  .validator(z.object({ designId: z.string() }))
-  .handler(async ({ data }) => {
-    const prisma = await getPrisma()
-    const request = getRequest()
-    const session = await getServerSeam().requireAuth(request)
-    const userId = session.user!.id!
-
-    const prd = await prisma.design.findFirst({ where: { id: data.designId, userId }, select: { id: true } })
-    if (!prd) throw new Error('FORBIDDEN')
-
-    return prisma.designTag.findMany({
-      where: { designId: data.designId },
-      include: { tag: true },
-      orderBy: { tag: { sortOrder: 'asc' } },
-    })
-  })

package/src/server/serverFns/design/detail.ts

@@ -33,7 +33,7 @@ export const getDesignDetailFn = createServerFn({ method: 'GET' })
 
     const prd = await prisma.design.findFirst({
       where: { id: data.id, userId: session.user.id },
-      select: { id: true, name: true, icon: true, description: true, designTags: { include: { tag: true } } },
+      select: { id: true, name: true, icon: true, description: true },
     })
     if (!prd) return { error: 'not_found' as const }
 
@@ -43,8 +43,42 @@ export const getDesignDetailFn = createServerFn({ method: 'GET' })
         name: prd.name,
         icon: prd.icon,
         description: prd.description,
-        designTags: prd.designTags,
       },
       session: { user: { id: session.user.id, name: session.user.name as string | undefined, email: session.user.email as string | undefined, role: session.user.role } },
     }
   })
+
+// 需求详情「设计」组预览卡数据源：属主口径（同 getDesignDetailFn），取首页
+// 文档内容 html（画板型/空文档返回 html=null，前端渲染占位卡）。非属主返回
+// not_found——预览内容仅属主可见，行级「打开」入口走 /design/canvas/$id 由
+// 路由 beforeLoad 再行校验。
+export const getDesignPreviewFn = createServerFn({ method: 'GET' })
+  .validator(detailSchema)
+  .handler(async ({ data }) => {
+    const prisma = await getPrisma()
+    const request = getRequest()
+    const session = await getServerSeam().getCurrentSession(request)
+    if (!session?.user?.id) return { error: 'unauthorized' as const }
+
+    const prd = await prisma.design.findFirst({
+      where: { id: data.id, userId: session.user.id, isDeleted: false },
+      select: { id: true, name: true, icon: true, description: true },
+    })
+    if (!prd) return { error: 'not_found' as const }
+
+    const firstPage = await prisma.designPage.findFirst({
+      where: { designId: prd.id },
+      orderBy: { order: 'asc' },
+      select: { content: true },
+    })
+    const raw = firstPage?.content as { html?: unknown } | string | null | undefined
+    const html =
+      raw && typeof raw === 'object' && typeof (raw as { html?: unknown }).html === 'string'
+        ? (raw as { html: string }).html
+        : null
+
+    return {
+      design: { id: prd.id, name: prd.name, icon: prd.icon, description: prd.description },
+      html,
+    }
+  })

package/src/server/serverFns/design/pages.ts

@@ -20,6 +20,8 @@ import { getRequest } from '@tanstack/react-start/server'
 import { z } from 'zod'
 import { getPrisma } from '@allbluecn/database/get-prisma'
 import { getServerSeam } from '@allbluecn/kernel'
+import { buildRoomName } from '@allbluecn/collab-core/rooms'
+import { withCollabGuard } from '@/server/collab/write-guard'
 
 async function verifyDesignOwner(designId: string, userId: string) {
   const prisma = await getPrisma()
@@ -114,18 +116,74 @@ export const updateDesignPageFn = createServerFn({ method: 'POST' })
     const prisma = await getPrisma()
     const request = getRequest()
     const session = await getServerSeam().requireAuth(request)
+    const userId = session.user!.id!
+    // §5.3 写入门卫（任务 29）：Y 属主面 = canvas（整场景 replace 语义）+
+    // content（文档 fragment 面）。快照存在 → 转发 collab 内部通道（活跃判定
+    // 在 collab 侧）；无快照 pass-through、不可达 TTL 降级 → 照旧直写（非协同
+    // 态零行为变化）。元数据（name/parentId/order）不归 Y——无属主面时连门卫
+    // 都不进（直写即正确路由）。门卫放事务外（T21 教训：网络 I/O 不进事务）；
+    // 本路径无事务。属主预检（C1）在转发前执行（verifyPageOwner = 直写 WHERE
+    // 的同口径）。
+    const forwarded =
+      data.canvas !== undefined || data.content !== undefined
+        ? (
+            await withCollabGuard({
+              roomName: buildRoomName({ kind: 'design-canvas', pageId: data.pageId }),
+              docId: data.pageId,
+              actor: userId,
+              patch: {
+                ...(data.canvas !== undefined && { canvas: data.canvas }),
+                ...(data.content !== undefined && { content: data.content }),
+              },
+              assertWriteAllowed: async () => {
+                if (!(await verifyPageOwner(data.pageId, userId))) {
+                  throw new Error('无权限')
+                }
+              },
+            })
+          ).kind === 'forwarded'
+        : false
+    const hasMetadataWrite =
+      data.name !== undefined || data.parentId !== undefined || data.order !== undefined
+    if (forwarded && !hasMetadataWrite) {
+      // 纯 Y patch（自动保存的典型形态）：web 侧零 mutation（不 bump updatedAt，
+      // 防误判旁路写触发重种子化）；返回既有行（返回值消费方仅关心成败，
+      // 形态与 updateManyAndReturn 的满行一致）
+      const existing = await prisma.designPage.findUnique({ where: { id: data.pageId } })
+      if (!existing) throw new Error('无权限')
+      return existing
+    }
+    // R11（审查修复）：生效写入为「元数据-only」（直写数据剥离 Y 属主面后——
+    // forwarded 组合 patch 与无属主面的元数据 patch 同属此态）时，@updatedAt
+    // 仍会被 bump——不回同步快照则下次打开 businessUpdatedAt > snapshot.updatedAt
+    // 误判旁路写 → 全量重种子化（Y 协作历史重置）。同事务 touch
+    // collabDocument.updatedAt = 回读行 updatedAt（T21 锚点 M② 的 web 侧镜像：
+    // exporter 写业务列后 touch / 此处 web 写元数据后 touch，同一不变式）。
+    // updateMany 对不存在快照计 0 天然不误建；含 Y 属主面的直写
+    // （pass-through/degraded 落 canvas/content）刻意不 touch——旁路写必须让
+    // 业务列反超快照，重种子化兜底才有正确输入。
+    const writesYFace = !forwarded && (data.canvas !== undefined || data.content !== undefined)
     // DB-03：属主校验（经 design.userId 关系过滤）合并进写入，单查询返回更新行
-    const rows = await prisma.designPage.updateManyAndReturn({
-      where: { id: data.pageId, design: { userId: session.user!.id! } },
-      data: {
-        ...(data.name !== undefined && { name: data.name }),
-        ...(data.parentId !== undefined && { parentId: data.parentId }),
-        ...(data.order !== undefined && { order: data.order }),
-        ...(data.canvas !== undefined && { canvas: data.canvas }),
-        ...(data.content !== undefined && { content: data.content }),
-      },
+    const rows = await prisma.$transaction(async (tx) => {
+      const updated = await tx.designPage.updateManyAndReturn({
+        where: { id: data.pageId, design: { userId } },
+        data: {
+          ...(data.name !== undefined && { name: data.name }),
+          ...(data.parentId !== undefined && { parentId: data.parentId }),
+          ...(data.order !== undefined && { order: data.order }),
+          ...(!forwarded && data.canvas !== undefined && { canvas: data.canvas }),
+          ...(!forwarded && data.content !== undefined && { content: data.content }),
+        },
+      })
+      if (updated.length === 0) throw new Error('无权限')
+      if (!writesYFace) {
+        await tx.collabDocument.updateMany({
+          where: { roomName: buildRoomName({ kind: 'design-canvas', pageId: data.pageId }) },
+          data: { updatedAt: updated[0]!.updatedAt },
+        })
+      }
+      return updated
     })
-    if (rows.length === 0) throw new Error('无权限')
     return rows[0]
   })
 
@@ -150,6 +208,11 @@ export const deleteDesignPageFn = createServerFn({ method: 'POST' })
       const ids = descendants.map((d) => d.id)
       if (ids.length > 0) {
         await tx.designPage.deleteMany({ where: { id: { in: ids } } })
+        // 协同快照同事务清理（story/bug/testcase 删除同构口径）：防已删页面的
+        // room 被后续装载为幽灵（此前仅靠 collab 侧守卫兜底）
+        await tx.collabDocument.deleteMany({
+          where: { roomName: { in: ids.map((id) => buildRoomName({ kind: 'design-canvas', pageId: id })) } },
+        })
       }
     })
     return { success: true }

package/src/server/serverFns/iteration/iteration-crud.ts

@@ -30,7 +30,7 @@ import {
 } from "./schemas";
 import type { StoryState } from "@/components/story/constants";
 import { ensureUpcomingIterations, ensureAutoRollover } from "@/server/iteration/auto-schedule-internal";
-import { resolveStoryScopeProjectId } from "@/server/builtin-project";
+import { resolveStoryScopeProjectId, resolveStoryScopeProjectIds } from "@/server/builtin-project";
 
 const ITERATION_SELECT = {
   id: true,
@@ -117,6 +117,30 @@ export const listIterationsFn = createServerFn({ method: "GET" })
     return { items: items.map((i) => toSummary(i, counts.get(i.id) ?? {})) };
   });
 
+/**
+ * 甘特迭代基线数据源（需求时间轴 timeline-view）：按项目范围聚合批量取迭代
+ * 窗口。与 listIterationsFn 的两点差异：
+ * - scope 用聚合版 resolveStoryScopeProjectIds（「全部项目」→ 成员关系内全部
+ *   projectId，与 listStoryDependenciesFn 同口径）；
+ * - **不做自愈**：不调 ensureUpcomingIterations/ensureAutoRollover——甘特渲染
+ *   是高频只读路径，写路径副作用（补建迭代/自动转移）留给迭代页与
+ *   listIterationsFn 的读时惰性自愈，避免只读视图触发建行。
+ */
+export const listIterationsScopeFn = createServerFn({ method: "GET" })
+  .validator(z.object({ projectId: z.string().optional() }))
+  .handler(async ({ data }) => {
+    const prisma = await getPrisma()
+    const request = getRequest();
+    const session = await requireAuth(request);
+    const projectIds = await resolveStoryScopeProjectIds(data.projectId, session.user!.id!);
+    const items = await prisma.iteration.findMany({
+      where: { projectId: { in: projectIds }, archived: false },
+      select: { id: true, name: true, startDate: true, endDate: true },
+      orderBy: { startDate: "desc" },
+    });
+    return { items };
+  });
+
 export const getIterationFn = createServerFn({ method: "GET" })
   .validator(iterationIdSchema)
   .handler(async ({ data }) => {

package/src/server/serverFns/{knowledge-public → knowledge/public}/bookmarks/create.ts

@@ -20,9 +20,9 @@ import { createServerFn } from '@tanstack/react-start'
 import { getRequest } from '@tanstack/react-start/server'
 import { z } from 'zod'
 import { requireAuth } from '@/server/auth-helpers'
-import { bookmarkCanonicalId, parseGithubUrl } from '@/server/knowledge-public/canonical-id'
-import { fetchGithubData } from '@/server/knowledge-public/github-sync'
-import { resolveFavicon } from '@/server/knowledge-public/favicon'
+import { bookmarkCanonicalId, parseGithubUrl } from '@/server/knowledge/public/canonical-id'
+import { fetchGithubData } from '@/server/knowledge/public/github-sync'
+import { resolveFavicon } from '@/server/knowledge/public/favicon'
 
 const createSchema = z.object({
   title: z.string().min(1).max(200),

package/src/server/serverFns/{knowledge-public → knowledge/public}/bookmarks/detail.ts

@@ -20,7 +20,7 @@ import { createServerFn } from '@tanstack/react-start'
 import { getRequest } from '@tanstack/react-start/server'
 import { z } from 'zod'
 import { requireAuth } from '@/server/auth-helpers'
-import { aggregateSharers } from '@/server/knowledge-public/share-merge'
+import { aggregateSharers, type PublicSharer } from '@/server/knowledge/public/share-merge'
 
 export const getBookmarkDetailFn = createServerFn({ method: 'GET' })
   .validator(z.object({ id: z.string() }))
@@ -37,7 +37,7 @@ export const getBookmarkDetailFn = createServerFn({ method: 'GET' })
     if (item.visibility === 'private' && item.userId !== userId) {
       throw new Error('无权限')
     }
-    let sharers: any[] = []
+    let sharers: PublicSharer[] = []
     if (item.visibility === 'public') {
       const map = await aggregateSharers('bookmark', [item.canonicalId])
       sharers = map.get(item.canonicalId) ?? []