@allbluecn/web-app 0.18.2 → 0.19.0

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

@@ -0,0 +1,258 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 写入路由协议门卫（Yjs 多人协作 §5.3，任务 17）——serverFn 写路径的统一
+// 前置封装。协议语义（复审定稿）：
+//
+// 1. 门卫检查：查 CollabDocument（roomName 唯一键）。不存在 → 照旧直写
+//    （pass-through，零行为变化）。元数据列（title/tags/icon/properties）
+//    不归 Y（协同 room 只拥有 content），patch 无 content 时连查询都省——
+//    直写即正确路由，无互吞面。
+// 2. 快照存在 + content → **一律转发** collab 内部通道
+//    `POST ${COLLAB_INTERNAL_URL}/internal/apply`（信封 HMAC，域
+//    collab-internal-apply:v1）。**活跃判定在 collab 侧**（复审修正：web
+//    进程不做活跃判定）——room 在线由 collab 应用到 Y 并广播（整文档
+//    replace，DB 旁路写是权威时刻）；room 离线由 collab 直接落库业务列
+//    （视为旁路写，重种子化兜底）。两种情形 web 都不再直写 content。
+// 3. collab 不可达 → 内存排队重试（**请求内同步**：await 重试直至 TTL，
+//    缺省 3s——规格 §5.3.2），TTL 后降级直写 DB（degraded，信任重种子化
+//    兜底）。刻意不做「先降级后后台重试」：降级直写之后的迟到应用会把
+//    collab 侧旧态广播回 Y，正是 §5.3 要防的互吞。
+//
+// 工具函数文件（非 serverFn）：仅由 serverFn handler 引用；serverFn 纯净
+// 纪律下客户端 split 不会保留本模块（无值导出消费）。
+//
+// 故障口径：COLLAB_INTERNAL_URL / COLLAB_SECRET 未配置 → warn-once 降级直写
+// （可用性优先，配置缺失日志显式）；转发异常/非 2xx → 重试至 TTL 后降级。
+
+import { getPrisma } from "@allbluecn/database/get-prisma";
+import {
+  INTERNAL_DOMAIN_APPLY,
+  signInternalRequest,
+} from "@allbluecn/collab-core/internal";
+import type { CollabStep } from "@allbluecn/collab-core/steps";
+
+/** 门卫裁决（调用方按 kind 分支） */
+export type CollabGuardOutcome =
+  | {
+      kind: "pass-through";
+      reason: "no-y-owned-field" | "no-snapshot" | "unsupported-content";
+    }
+  | { kind: "forwarded" }
+  | { kind: "degraded"; reason: "no-url" | "no-secret" | "unreachable" };
+
+/** 门卫入参 patch（content = 富文本 Y 属主面；fields = entity room 字段 Y 属主面） */
+export interface CollabGuardPatch {
+  content?: unknown;
+  /**
+   * entity room 的字段 patch（任务 21，Story 8 字段；任务 22 扩 bug/case 6
+   * 字段——键值与客户端 Y 写端同形：JSON 兼容原值）。仅对象非空才视为 Y
+   * 属主写入；知识库不传。
+   */
+  fields?: Record<string, unknown>;
+  /**
+   * entity room 的步骤 patch（任务 22，§7.1 steps 行）：门卫归一化列表
+   * （normalizeCollabSteps 产物——数组顺序即步骤顺序，order 已剥）。仅非空
+   * 数组才视为 Y 属主写入（业务 schema 步骤 min(1)，空列表直写保持原行为）。
+   */
+  steps?: CollabStep[];
+  /**
+   * design-canvas room 的画布 patch（任务 29，§7.1 设计画布行）：LeaferJSONPackage
+   * / 旧扁平 SceneDocument 原值（web 直写 canvas 列的同形值），应用语义 =
+   * 整场景 replace（collab 侧 seedYTreeFromCanvas 覆写 Y 树）。仅 undefined
+   * 之外才视为 Y 属主写入（内容形状由 collab 应用侧 fail-closed 把关）。
+   */
+  canvas?: unknown;
+  /**
+   * 语义活动 hint（entity-bug 机器/旁路写入，如 reopened_by_sdk）：透传至
+   * collab /internal/apply——live 路径入队随落库成行、离线路径随直落活动行。
+   * 仅随 Y 属主面一起转发；action 必须为非空字符串（collab 侧 fail-closed）。
+   */
+  activity?: { action: string; field?: unknown; oldValue?: unknown; newValue?: unknown };
+}
+
+export interface WithCollabGuardOptions {
+  /** §3.1 注册表 room 名（buildRoomName 产物） */
+  roomName: string;
+  /** 业务实体 id（与 roomName 互相印证，collab 侧复核） */
+  docId: string;
+  /** 写入者（session user id；collab 侧系统 client 归属用它） */
+  actor: string;
+  patch: CollabGuardPatch;
+  /**
+   * 属主预检（C1，任务 17 复审修复）：快照命中后、转发前执行，抛错即短路
+   * （不触网络、不排队）。**用户会话调用点必须传入**——requirePermission
+   * 是模块级权限（普通用户默认 write），不构成资源属主校验；不预检则
+   * 「collab 已应用、web 侧才报无权限」的越权窗口成立。回调内做只读
+   * assertOwned；直写路径（pass-through/degraded）不经此回调，属主校验
+   * 保持合并在写库 WHERE。
+   *
+   * 机器路径豁免口径（任务 23）：SDK/MCP 机器写入调用点可省略本回调，条件
+   * 是资源定位已绑定凭证 scope、token 即授权主体——SDK 上报经 X-Bug-Key
+   * （token 含 projectId）+ projectId_fingerprint 定位 BUG，MCP 经
+   * requireBug 的 findFirst({ id, projectId }) 结构性消除跨项目面。省略
+   * 前须做同等信任链分析并在调用点注释留痕（现豁免点：report-handler
+   * dedupeExistingBug、mcp/tools reportResultHandler）；普通用户调用点
+   * （session userId）不适用本豁免，仍必须传入。
+   */
+  assertWriteAllowed?: () => Promise<void>;
+  /** 重试总预算（§5.3.2 TTL 3s）；超时降级直写 */
+  ttlMs?: number;
+  /** 单次转发请求超时 */
+  requestTimeoutMs?: number;
+  /** 重试间隔（测试注入即时 sleep） */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+/** §5.3.2 降级 TTL（ms） */
+export const COLLAB_GUARD_TTL_MS = 3000;
+/** 单次转发请求超时（ms） */
+export const COLLAB_GUARD_REQUEST_TIMEOUT_MS = 2000;
+/** 重试退避序列（指数；TTL 截断） */
+const RETRY_BACKOFF_MS = [250, 500, 1000, 1000];
+
+/** COLLAB_INTERNAL_URL 缺失的 warn-once 标记（进程级） */
+let warnedNoUrl = false;
+/** COLLAB_SECRET 缺失的 warn-once 标记（进程级） */
+let warnedNoSecret = false;
+
+/**
+ * 门卫主入口。返回裁决；「直写」类裁决（pass-through/degraded）由调用方
+ * 执行原 updateManyAndReturn，forwarded 时调用方须把 content 从直写数据中
+ * 剥离（content 已由 collab 接管）。
+ */
+export async function withCollabGuard(opts: WithCollabGuardOptions): Promise<CollabGuardOutcome> {
+  // ① 无 Y 属主字段：patch 既无 content/canvas 也无非空 fields/steps（元数据
+  //    等不归协同 room）→ 直写即正确路由（省一次查询）
+  const hasFields =
+    opts.patch.fields !== undefined &&
+    typeof opts.patch.fields === "object" &&
+    Object.keys(opts.patch.fields).length > 0;
+  const hasSteps = Array.isArray(opts.patch.steps) && opts.patch.steps.length > 0;
+  const hasCanvas = opts.patch.canvas !== undefined;
+  if (opts.patch.content === undefined && !hasCanvas && !hasFields && !hasSteps) {
+    return { kind: "pass-through", reason: "no-y-owned-field" };
+  }
+  // ② content 形状守卫：仅 { html: string } 可同构进 Y（编辑器 onChange
+  //    产物）；历史 {text}/string 形状照旧直写，重种子化兜底换算。
+  //    content 缺席（纯 fields/canvas patch）跳过此守卫。
+  const html =
+    typeof opts.patch.content === "object" && opts.patch.content !== null
+      ? (opts.patch.content as Record<string, unknown>).html
+      : undefined;
+  if (opts.patch.content !== undefined && typeof html !== "string") {
+    return { kind: "pass-through", reason: "unsupported-content" };
+  }
+  // ③ 快照检查：无 CollabDocument = 该文档从未协同，照旧直写（零行为变化）
+  const prisma = await getPrisma();
+  const snapshot = await prisma.collabDocument.findUnique({
+    where: { roomName: opts.roomName },
+    select: { id: true },
+  });
+  if (!snapshot) {
+    return { kind: "pass-through", reason: "no-snapshot" };
+  }
+  // ③a 属主预检（C1）：快照命中即可能转发——先校验属主，失败短路抛错，
+  // 杜绝「content 已进受害者 Y 态/业务列、web 才报无权限」的水平越权
+  if (opts.assertWriteAllowed) {
+    await opts.assertWriteAllowed();
+  }
+  // ④ 转发（活跃判定在 collab 侧；web 不判活跃）
+  const base = process.env.COLLAB_INTERNAL_URL;
+  if (!base) {
+    if (!warnedNoUrl) {
+      warnedNoUrl = true;
+      console.warn(
+        "[collab-write-guard] COLLAB_INTERNAL_URL 未配置：协同文档的旁路 content 写入无法转发，" +
+          "已降级直写 DB（下次协同打开时重种子化兜底）。请补配该 env。",
+      );
+    }
+    return { kind: "degraded", reason: "no-url" };
+  }
+
+  // ③b secret 检查（R 审查修复 Minor）：缺失与 COLLAB_INTERNAL_URL 缺失同
+  //  口径——warn-once 降级直写（可用性优先），不再抛错 500。行为变化：
+  //  「快照存在但 secret 缺失」原为 500（写入失败），现降级直写 DB，
+  //  重种子化兜底。
+  const secret = process.env.COLLAB_SECRET;
+  if (!secret) {
+    if (!warnedNoSecret) {
+      warnedNoSecret = true;
+      console.warn(
+        "[collab-write-guard] COLLAB_SECRET 未配置：协同文档的旁路写入无法签发内部通道信封，" +
+          "已降级直写 DB（下次协同打开时重种子化兜底）。请补配该 env。",
+      );
+    }
+    return { kind: "degraded", reason: "no-secret" };
+  }
+
+  const signed = signInternalRequest({
+    secret,
+    domain: INTERNAL_DOMAIN_APPLY,
+    payload: {
+      roomName: opts.roomName,
+      docId: opts.docId,
+      actor: opts.actor,
+      patch: {
+        // 只携带出现的属主面：knowledge 仅 content；story 为 content/fields
+        // 组合；bug/case 为 content/fields/steps 组合（任务 22）；design 为
+        // canvas/content 组合（任务 29）
+        ...(opts.patch.content !== undefined && { content: opts.patch.content }),
+        ...(hasCanvas && { canvas: opts.patch.canvas }),
+        ...(hasFields && { fields: opts.patch.fields }),
+        ...(hasSteps && { steps: opts.patch.steps }),
+        ...(opts.patch.activity !== undefined && { activity: opts.patch.activity }),
+      },
+    },
+  });
+
+  const ttlMs = opts.ttlMs ?? COLLAB_GUARD_TTL_MS;
+  const requestTimeoutMs = opts.requestTimeoutMs ?? COLLAB_GUARD_REQUEST_TIMEOUT_MS;
+  const sleep =
+    opts.sleep ??
+    ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const startedAt = Date.now();
+  let attempt = 0;
+  // ⑤ 内存排队重试（请求内同步）：失败即重试直至 TTL 耗尽——调用方在本
+  // 请求内拿到最终裁决，绝不出现「已降级直写、后台又迟到应用」的互吞。
+  while (true) {
+    attempt += 1;
+    try {
+      const response = await fetch(`${base.replace(/\/$/, "")}/internal/apply`, {
+        method: "POST",
+        headers: signed.headers,
+        body: signed.body,
+        signal: AbortSignal.timeout(requestTimeoutMs),
+      });
+      if (response.ok) {
+        return { kind: "forwarded" };
+      }
+      console.warn(
+        `[collab-write-guard] /internal/apply 响应 ${response.status}（room=${opts.roomName} 第 ${attempt} 次）`,
+      );
+    } catch (err) {
+      console.warn(
+        `[collab-write-guard] /internal/apply 不可达（room=${opts.roomName} 第 ${attempt} 次）：`,
+        err instanceof Error ? err.message : err,
+      );
+    }
+    if (Date.now() - startedAt >= ttlMs) {
+      return { kind: "degraded", reason: "unreachable" };
+    }
+    await sleep(RETRY_BACKOFF_MS[Math.min(attempt - 1, RETRY_BACKOFF_MS.length - 1)]!);
+  }
+}

package/src/server/collab-permissions.ts

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 协同授权统一入口（Yjs 多人协作 §4.1）+ room 名解析（§3.1 注册表）。
+// assertCollabAccess(entityType, entityId, userId) 是协同 ticket 签发与协同态
+// serverFn 的唯一授权裁决点；工作空间反查组合 collab/resolve.ts 的查询层。
+//
+// 裁决口径（2026-10-07 控制者裁决）：
+// - owner ≥ edit：owner 判定（实体 userId）独立于工作空间成员判定，
+//   owner 对自己实体永远拿到 edit、永不 Forbidden（私人项目 / private KB /
+//   未关联 Design 的 owner 均不被锁外）。
+// - WorkspaceMember role=viewer → view（只读）；其他角色 → edit。
+// - 空间外（归属链解析出的工作空间与该用户成员身份无交集）→ Forbidden。
+// - 实体不存在 / room 解析失败一律 fail-closed 拒绝。
+//
+// 边界：presence:team 与 share: 两类 room 不是实体 room，本模块仅提供
+// parseRoomName 解析（roomAccessTarget 映射为 null）；其校验由 P1 任务各自实现。
+// deleted/archived 过滤与 §4.1 口径一致暂不收紧（渐进策略，P1 ticket 层按需加守卫）。
+
+import { prisma } from "@allbluecn/database";
+import { ForbiddenError } from "@/server/auth-helpers";
+import {
+  resolveEntityWorkspace,
+  resolveKbAccess,
+  resolveDesignWorkspaces,
+  type CollabEntityType,
+} from "./collab/resolve";
+
+/** 协同角色：edit 可编辑（ticket readOnly=false），view 只读 */
+export type CollabRole = "edit" | "view";
+
+/**
+ * assertCollabAccess 支持的实体类型（§3.1 七类 room 名映射的值域）：
+ * doc:knowledge→knowledge、entity:*→story|bug|case、canvas:design→design。
+ * presence/share 两类 room 不在值域内（类型层面阻止越界实现）。
+ */
+export type CollabAccessEntityType = CollabEntityType | "knowledge" | "design";
+
+/** §3.1 七类 room 名的解析结果（ discriminated union，供 collab-core 镜像对齐） */
+export type CollabRoomName =
+  | { kind: "presence-team"; ownerId: string }
+  | { kind: "share"; shareToken: string }
+  | { kind: "knowledge-doc"; docId: string }
+  | { kind: "entity-story"; storyId: string }
+  | { kind: "entity-bug"; bugId: string }
+  | { kind: "entity-case"; caseId: string }
+  | { kind: "design-canvas"; pageId: string };
+
+/**
+ * 解析 §3.1 注册表的七类 room 名；格式不符（缺段 / 空 id / 未知前缀 / 多余段）
+ * 返回 null（fail-closed：调用方对 null 一律拒绝签发 ticket，防越权复用）。
+ * id 段不含 `:`（实体 id 为 cuid；Share.token 为 nanoid 字母数字表），
+ * 故按严格段数切分，不做宽松截断。
+ */
+export function parseRoomName(roomName: string): CollabRoomName | null {
+  const parts = roomName.split(":");
+  // share:{token} 两段；其余六类均为三段
+  if (parts.length === 2 && parts[0] === "share" && parts[1]) {
+    return { kind: "share", shareToken: parts[1] };
+  }
+  if (parts.length !== 3 || parts.some((part) => part.length === 0)) return null;
+  const [scope, kind, id] = parts;
+  if (scope === "presence" && kind === "team") {
+    return { kind: "presence-team", ownerId: id };
+  }
+  if (scope === "doc" && kind === "knowledge") {
+    return { kind: "knowledge-doc", docId: id };
+  }
+  if (scope === "entity" && kind === "story") {
+    return { kind: "entity-story", storyId: id };
+  }
+  if (scope === "entity" && kind === "bug") {
+    return { kind: "entity-bug", bugId: id };
+  }
+  if (scope === "entity" && kind === "case") {
+    return { kind: "entity-case", caseId: id };
+  }
+  if (scope === "canvas" && kind === "design") {
+    return { kind: "design-canvas", pageId: id };
+  }
+  return null;
+}
+
+/**
+ * room 权限映射（§3.1 七类 → 实体类型）：实体类 room 返回
+ * assertCollabAccess 的入参对；presence/share 非实体 room → null
+ * （P1 ticket 流程对 null 拒绝，presence/share 校验由各自任务实现）。
+ */
+export function roomAccessTarget(
+  room: CollabRoomName,
+): { entityType: CollabAccessEntityType; entityId: string } | null {
+  switch (room.kind) {
+    case "knowledge-doc":
+      return { entityType: "knowledge", entityId: room.docId };
+    case "entity-story":
+      return { entityType: "story", entityId: room.storyId };
+    case "entity-bug":
+      return { entityType: "bug", entityId: room.bugId };
+    case "entity-case":
+      return { entityType: "case", entityId: room.caseId };
+    case "design-canvas":
+      return { entityType: "design", entityId: room.pageId };
+    case "presence-team":
+    case "share":
+      return null;
+  }
+}
+
+/**
+ * owner + 授权锚点查询：room 的 id 即实体 id（docId / pageId 亦然），
+ * knowledge 经文档反查 KB（owner=KnowledgeBase.userId，private KB 不协同
+ * 即仅 KB owner），design 经页反查 Design（owner=Design.userId）。
+ * 实体不存在 → ownerUserId 与锚点均为 null（后续路径 fail-closed）。
+ */
+type EntityOwnership = {
+  ownerUserId: string | null;
+  kbId: string | null;
+  designId: string | null;
+};
+
+const findOwnership: Record<
+  CollabAccessEntityType,
+  (id: string) => Promise<EntityOwnership>
+> = {
+  story: async (id) => {
+    const row = await prisma.story.findUnique({
+      where: { id },
+      select: { createdById: true },
+    });
+    return { ownerUserId: row?.createdById ?? null, kbId: null, designId: null };
+  },
+  bug: async (id) => {
+    const row = await prisma.bug.findUnique({
+      where: { id },
+      select: { createdById: true },
+    });
+    return { ownerUserId: row?.createdById ?? null, kbId: null, designId: null };
+  },
+  case: async (id) => {
+    const row = await prisma.testCase.findUnique({
+      where: { id },
+      select: { createdById: true },
+    });
+    return { ownerUserId: row?.createdById ?? null, kbId: null, designId: null };
+  },
+  knowledge: async (docId) => {
+    const doc = await prisma.knowledgeDocument.findUnique({
+      where: { id: docId },
+      select: { kbId: true, kb: { select: { userId: true } } },
+    });
+    return {
+      ownerUserId: doc?.kb.userId ?? null,
+      kbId: doc?.kbId ?? null,
+      designId: null,
+    };
+  },
+  design: async (pageId) => {
+    const page = await prisma.designPage.findUnique({
+      where: { id: pageId },
+      select: { designId: true, design: { select: { userId: true } } },
+    });
+    return {
+      ownerUserId: page?.design.userId ?? null,
+      kbId: null,
+      designId: page?.designId ?? null,
+    };
+  },
+};
+
+/**
+ * 实体的协同授权工作空间集合（组合 collab/resolve.ts 反查）：
+ * - story/bug/case → 项目直挂的单个工作空间（未挂 → 空集）
+ * - knowledge → open KB 挂载的三条路径并集（private / 空 → 空集）
+ * - design → StoryDesignLink 间接反查（无关联 → 空集）
+ */
+async function resolveAccessWorkspaces(
+  entityType: CollabAccessEntityType,
+  entityId: string,
+  ownership: EntityOwnership,
+): Promise<string[]> {
+  if (entityType === "knowledge") {
+    if (!ownership.kbId) return [];
+    const access = await resolveKbAccess(ownership.kbId);
+    return access.kind === "open" ? access.workspaceIds : [];
+  }
+  if (entityType === "design") {
+    if (!ownership.designId) return [];
+    return resolveDesignWorkspaces(ownership.designId);
+  }
+  const workspaceId = await resolveEntityWorkspace(entityType, entityId);
+  return workspaceId ? [workspaceId] : [];
+}
+
+/**
+ * 协同授权统一裁决（§4.1 单一入口）。
+ * 返回协同角色（{role:'edit'}|{role:'view'}）；
+ * 无权限（空间外 / private-非 owner / 实体不存在）抛 ForbiddenError。
+ *
+ * - owner（实体 userId）→ 恒为 edit，不查成员表（owner ≥ edit 裁决）。
+ * - 其余用户：归属链解析工作空间 → active WorkspaceMember 全取 →
+ *   任一非 viewer 角色 → edit；仅有 viewer → view；无成员身份 → Forbidden。
+ */
+export async function assertCollabAccess(
+  entityType: CollabAccessEntityType,
+  entityId: string,
+  userId: string,
+): Promise<{ role: CollabRole }> {
+  const ownership = await findOwnership[entityType](entityId);
+  if (ownership.ownerUserId && ownership.ownerUserId === userId) {
+    return { role: "edit" };
+  }
+
+  const workspaceIds = await resolveAccessWorkspaces(
+    entityType,
+    entityId,
+    ownership,
+  );
+  if (workspaceIds.length === 0) {
+    throw new ForbiddenError("无协同访问权限");
+  }
+
+  const memberships = await prisma.workspaceMember.findMany({
+    where: { workspaceId: { in: workspaceIds }, userId, status: "active" },
+    select: { role: true },
+  });
+  if (memberships.length === 0) {
+    throw new ForbiddenError("无协同访问权限");
+  }
+  return {
+    role: memberships.some((membership) => membership.role !== "viewer")
+      ? "edit"
+      : "view",
+  };
+}

package/src/server/csv.ts

@@ -0,0 +1,61 @@
+// 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/>.
+
+// CSV 序列化共享纯函数（四期 Q8 任务 44）。落 src/server/（serverFns 树外，
+// 照 server/testcase/list-query.ts 先例——serverFn 文件只准导出 createServerFn
+// 产物，纯 helper 须放树外客户端安全位置）。零依赖、零 IO；testcase/bug 两
+// 导出 serverFn 消费，后续模块导出（story 等）复用同款编码规则。
+//
+// 编码规则（RFC 4180 + Excel 兼容加固）：
+// ① BOM：整体输出以 \uFEFF 前缀——Excel 无 BOM 按 ANSI 解码，中文乱码；
+// ② 转义：值含 " , \n \r 任一字符时整格包裹双引号，内部 " 翻倍为 ""；
+// ③ 公式注入防护（CSV Injection / Excel formula injection）：值首字符为
+//    = + - @ \t 时前置单引号 '，防导出文件被 Excel/WPS 当公式求值（设计 §8
+//    审查重点；\t 为控制者补充——tab 开头同样触发公式解释器）；
+// ④ 行分隔符 CRLF（RFC 4180 口径，Excel/Numbers/WPS 全兼容）；
+// ⑤ null/undefined 收敛为空单元格。
+//
+// 表头为服务端硬编码中文（serverFn 无客户端 locale 上下文，与 serverFn 错误
+// 文案「无权限操作…」同一口径）；枚举值（type/priority/state…）输出 DB 原值
+// 保持机器可读。若需 en 表头，后续可加 locale 入参（YAGNI 暂不做）。
+
+/** 单次导出最大数据行数（设计 R10：上限截断 + 前端提示「已导出前 20000 行」） */
+export const CSV_EXPORT_MAX_ROWS = 20000;
+
+/** 公式注入防护前缀集：命中即前置 ' */
+const CSV_INJECTION_PREFIXES = new Set(["=", "+", "-", "@", "\t"]);
+
+/** CSV 单元格值（服务端行数据允许原始类型；日期等由调用方先转 ISO 字符串） */
+export type CsvCell = string | number | null | undefined;
+
+/** 单格编码：注入防护 → 含分隔符则包裹引号 */
+function encodeCell(value: CsvCell): string {
+  let s = value === null || value === undefined ? "" : String(value);
+  if (s.length > 0 && CSV_INJECTION_PREFIXES.has(s[0]!)) {
+    s = `'${s}`;
+  }
+  if (/[",\n\r]/.test(s)) {
+    s = `"${s.replace(/"/g, '""')}"`;
+  }
+  return s;
+}
+
+/** 行数组 → CSV 文本（含 BOM 前缀；行间 CRLF，尾部无行分隔符） */
+export function toCsv(rows: CsvCell[][]): string {
+  const body = rows.map((row) => row.map(encodeCell).join(",")).join("\r\n");
+  return `\uFEFF${body}`;
+}

package/src/server/{knowledge-public → knowledge/public}/github-sync.ts

@@ -24,6 +24,16 @@ export interface GithubData {
   versionDate: Date | null
 }
 
+interface GithubRepoJson {
+  stargazers_count?: number
+  updated_at?: string
+}
+
+interface GithubReleaseJson {
+  tag_name?: string
+  published_at?: string
+}
+
 const API = 'https://api.github.com'
 const HEADERS: HeadersInit = {
   Accept: 'application/vnd.github+json',
@@ -53,7 +63,7 @@ export async function fetchGithubData(
   }
   const repoRes = await fetch(repoUrl, { headers: HEADERS, redirect: 'error' })
   if (!repoRes.ok) return null
-  const repoJson: any = await repoRes.json()
+  const repoJson: GithubRepoJson = await repoRes.json()
 
   let latestVersion: string | null = null
   let versionDate: Date | null = null
@@ -64,7 +74,7 @@ export async function fetchGithubData(
     }
     const relRes = await fetch(relUrl, { headers: HEADERS, redirect: 'error' })
     if (relRes.ok) {
-      const relJson: any = await relRes.json()
+      const relJson: GithubReleaseJson = await relRes.json()
       latestVersion = relJson.tag_name ?? null
       versionDate = relJson.published_at ? new Date(relJson.published_at) : null
     }

package/src/server/{knowledge-public → knowledge/public}/share-merge.ts

@@ -15,7 +15,7 @@
 // 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 { prisma } from '@allbluecn/database'
+import { Prisma, prisma } from '@allbluecn/database'
 
 type EntityType = 'legal' | 'compliance' | 'dictionary' | 'bookmark'
 
@@ -30,10 +30,35 @@ interface ShareInput {
 
 export type ShareResult = { action: 'created' | 'appended' | 'already' }
 
+export interface PublicSharer {
+  id: string
+  username: string
+  // Prisma Json 列：用 JsonValue（可序列化）而非 unknown，过 serverFn 序列化校验
+  avatarConfig: Prisma.JsonValue
+  bgShape: string | null
+  bgColor: string | null
+}
+
+/** 四个公共库模型 delegate 的公共操作面（仅用到公共列，收窄 prisma 动态访问类型） */
+interface PublicModelDelegate {
+  findFirst(args: {
+    where: { canonicalId: string; visibility: string; isDeleted: boolean }
+    select: { id: boolean; canonicalId: boolean }
+  }): Promise<{ id: string; canonicalId: string } | null>
+  update(args: { where: { id: string }; data: Record<string, unknown> }): Promise<unknown>
+}
+
+const modelDelegates = {
+  legalRegulation: prisma.legalRegulation,
+  industryCompliance: prisma.industryCompliance,
+  dictionaryTerm: prisma.dictionaryTerm,
+  websiteBookmark: prisma.websiteBookmark,
+}
+
 export async function shareToPublic(input: ShareInput): Promise<ShareResult> {
   const { model, entityType, userId, cloneData } = input
   const canonicalId = String(cloneData.canonicalId)
-  const table = (prisma as any)[model]
+  const table = modelDelegates[model] as unknown as PublicModelDelegate
 
   const existing = await table.findFirst({
     where: { canonicalId, visibility: 'public', isDeleted: false },
@@ -42,7 +67,7 @@ export async function shareToPublic(input: ShareInput): Promise<ShareResult> {
 
   if (existing) {
     const { canonicalId: _cid, visibility: _vis, userId: _uid, ...updateData } = cloneData
-    await table.update({ where: { id: existing.id }, data: updateData as any })
+    await table.update({ where: { id: existing.id }, data: updateData })
     const already = await prisma.knowledgeShareRecord.findFirst({
       where: { entityType, canonicalId, userId },
       select: { id: true },
@@ -68,10 +93,8 @@ export async function shareToPublic(input: ShareInput): Promise<ShareResult> {
 export async function aggregateSharers(
   entityType: EntityType,
   canonicalIds: string[],
-) {
-  if (canonicalIds.length === 0) return new Map<string, Array<{
-    id: string; username: string; avatarConfig: unknown; bgShape: string | null; bgColor: string | null
-  }>>()
+): Promise<Map<string, PublicSharer[]>> {
+  if (canonicalIds.length === 0) return new Map()
   const records = await prisma.knowledgeShareRecord.findMany({
     where: { entityType, canonicalId: { in: canonicalIds } },
     select: {
@@ -82,7 +105,7 @@ export async function aggregateSharers(
     },
     orderBy: { sharedAt: 'asc' },
   })
-  const map = new Map<string, typeof records[number]['user'][]>()
+  const map = new Map<string, PublicSharer[]>()
   for (const r of records) {
     const arr = map.get(r.canonicalId) ?? []
     arr.push(r.user)