node-resource-utils 0.0.0-stage → 1.1.7

package/resources/src/lib/docs.ts

@@ -0,0 +1,381 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { cache } from 'react';
+import {
+  extractToc,
+  firstHeading,
+  firstParagraph,
+  formatDocDate,
+  plainTextOf,
+  readingMinutesOf,
+  parseFrontMatter,
+  searchDocs,
+  stripLeadingH1,
+  toTags,
+  type DocNav,
+  type DocNavGroup,
+  type DocNavPage,
+  type DocNavSection,
+  type DocRecord,
+  type DocSearchHit,
+  type DocsStats,
+  type FrontMatterValue,
+  type SearchableDoc,
+} from './docs-shared';
+
+/**
+ * 帮助文档内容引擎（服务端）。
+ *
+ * ★ 内容即目录：`content/docs` 下的 Markdown 文件自动成为文档页，
+ *   子目录自动成为分组；新增一篇文档 = 丢一个 .md 进去，不需要改任何页面代码。
+ *   这正是「通用底座」的关键 —— 比赛换题、加模块时，只需要补内容，不用改框架。
+ *
+ * 约定：
+ *   - 页面：`content/docs/<路径>.md`，URL 为 `/docs/<路径>`
+ *   - 分组：子目录，可选 `_meta.json` 提供 { title, description, order }
+ *   - 排序：front matter 的 `order`，缺省按文件名前缀数字（如 `01-account.md`）
+ *   - 隐藏：front matter `hidden: true`，不进导航与搜索，但 URL 仍可访问
+ *   - 元数据：title / description / tags / updated / order / hidden
+ *
+ * 每次请求重新读文件（`cache()` 只在单次请求内去重），
+ * 于是开发时改完 Markdown 刷新页面即可看到，不需要重启 dev server。
+ */
+
+const DOCS_ROOT = path.join(process.cwd(), 'content', 'docs');
+
+type DirMeta = {
+  title?: string;
+  description?: string;
+  order?: number;
+};
+
+type RawGroup = {
+  key: string;
+  title: string;
+  description: string;
+  order: number;
+  pages: DocRecord[];
+  groups: RawGroup[];
+  count: number;
+};
+
+type RawDir = {
+  pages: DocRecord[];
+  groups: RawGroup[];
+};
+
+function readMeta(absDir: string): DirMeta {
+  try {
+    const raw = fs.readFileSync(path.join(absDir, '_meta.json'), 'utf8');
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    return {
+      title: typeof parsed.title === 'string' ? parsed.title : undefined,
+      description: typeof parsed.description === 'string' ? parsed.description : undefined,
+      order: typeof parsed.order === 'number' ? parsed.order : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** 文件名兜底标题：去掉数字前缀、扩展名，分隔符换空格 */
+function humanize(name: string): string {
+  return name
+    .replace(/\.md$/i, '')
+    .replace(/^\d+[-_.\s]+/, '')
+    .replace(/[-_]+/g, ' ')
+    .trim();
+}
+
+function leadingOrder(name: string, fallback: number): number {
+  const m = name.match(/^(\d+)[-_.\s]/);
+  return m ? Number(m[1]) : fallback;
+}
+
+function asString(value: FrontMatterValue | undefined): string {
+  return typeof value === 'string' ? value.trim() : typeof value === 'number' ? String(value) : '';
+}
+
+function asOrder(value: FrontMatterValue | undefined): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && /^\d+$/.test(value.trim())) return Number(value);
+  return undefined;
+}
+
+function asHidden(value: FrontMatterValue | undefined): boolean {
+  return value === true || value === 'true';
+}
+
+function sortPages(a: { order: number; title: string }, b: { order: number; title: string }): number {
+  return a.order - b.order || a.title.localeCompare(b.title, 'zh-CN');
+}
+
+function toNavPage(page: DocRecord): DocNavPage {
+  return {
+    slug: page.slug,
+    title: page.title,
+    description: page.description,
+    order: page.order,
+    updated: page.updated,
+    readingMinutes: page.readingMinutes,
+  };
+}
+
+function toNavGroup(group: RawGroup): DocNavGroup {
+  const pages = group.pages.filter((page) => !page.hidden).sort(sortPages);
+  const groups = group.groups
+    .sort(sortPages)
+    .map(toNavGroup)
+    .filter((child) => child.count > 0);
+
+  return {
+    key: group.key,
+    title: group.title,
+    description: group.description,
+    order: group.order,
+    pages: pages.map(toNavPage),
+    groups,
+    count: pages.length + groups.reduce((sum, child) => sum + child.count, 0),
+  };
+}
+
+/**
+ * 把目录里的一个页面读成 DocRecord。
+ *
+ * `relSlug` 是相对 content/docs 的路径（无扩展名）。
+ * `index.md` 视为所在目录的落地页：`guide/index.md` → `/docs/guide`。
+ */
+function readPage(
+  absFile: string,
+  relSlug: string,
+  fallbackOrder: number,
+  groupTrail: string[]
+): DocRecord {
+  const raw = fs.readFileSync(absFile, 'utf8');
+  const fm = parseFrontMatter(raw);
+  const data = fm.data;
+
+  const h1 = firstHeading(fm.body);
+  const title =
+    asString(data.title) || h1 || humanize(path.basename(absFile)) || '未命名文档';
+
+  let updated = asString(data.updated) || formatDocDate(asString(data.date));
+  if (!updated) {
+    try {
+      updated = fs.statSync(absFile).mtime.toISOString().slice(0, 10);
+    } catch {
+      updated = '';
+    }
+  }
+
+  const body = stripLeadingH1(fm.body);
+  const description = asString(data.description) || firstParagraph(body);
+
+  return {
+    slug: relSlug,
+    title,
+    description,
+    tags: toTags(data.tags),
+    order: asOrder(data.order) ?? leadingOrder(path.basename(absFile), fallbackOrder),
+    hidden: asHidden(data.hidden),
+    updated,
+    body,
+    toc: extractToc(body),
+    readingMinutes: readingMinutesOf(plainTextOf(body)),
+    groupTrail,
+  };
+}
+
+/** 递归扫描目录：页面 + 子分组 */
+function readDir(absDir: string, relDir: string, groupTrail: string[]): RawDir {
+  let entries: fs.Dirent[] = [];
+  try {
+    entries = fs.readdirSync(absDir, { withFileTypes: true });
+  } catch {
+    return { pages: [], groups: [] };
+  }
+
+  // 文件名排序，保证缺省 order 时顺序稳定（不依赖文件系统返回顺序）
+  entries.sort((a, b) => a.name.localeCompare(b.name, 'zh-CN'));
+
+  const pages: DocRecord[] = [];
+  const groups: RawGroup[] = [];
+  let fileIndex = 0;
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue;
+    if (entry.name === 'README.md') continue; // 给维护者看的说明，不进文档站
+
+    const abs = path.join(absDir, entry.name);
+
+    if (entry.isFile()) {
+      if (!/\.md$/i.test(entry.name)) continue;
+      fileIndex += 1;
+      const base = entry.name.replace(/\.md$/i, '');
+      const parent = relDir ? `${relDir}/` : '';
+      // 目录里的 index.md 作为该目录的落地页；根目录的 index.md 仍保留独立 URL，
+      // 避免和文档站首页抢同一个地址。
+      const relSlug =
+        base.toLowerCase() === 'index' ? relDir || 'index' : `${parent}${base}`;
+      pages.push(
+        readPage(abs, relSlug.replace(/^\/+|\/+$/g, ''), fileIndex, groupTrail)
+      );
+      continue;
+    }
+
+    if (!entry.isDirectory()) continue;
+
+    const meta = readMeta(abs);
+    const key = relDir ? `${relDir}/${entry.name}` : entry.name;
+    const title = meta.title || humanize(entry.name) || entry.name;
+    const child = readDir(
+      abs,
+      relDir ? `${relDir}/${entry.name}` : entry.name,
+      [...groupTrail, title]
+    );
+
+    // 空目录不生成分组（否则侧边栏会留下一个点不开的空分组）
+    if (!child.pages.length && !child.groups.length) continue;
+
+    const count =
+      child.pages.length + child.groups.reduce((sum, g) => sum + g.count, 0);
+    const description =
+      meta.description ||
+      child.pages.find((p) => !p.hidden)?.description ||
+      child.groups.find((g) => g.description)?.description ||
+      '';
+
+    groups.push({
+      key,
+      title,
+      description,
+      order: meta.order ?? 1000 + groups.length,
+      pages: child.pages,
+      groups: child.groups,
+      count,
+    });
+  }
+
+  return { pages, groups };
+}
+
+/** 深度优先展开分组，顺序与侧边栏一致 */
+function flattenGroup(group: RawGroup, out: DocRecord[] = []): DocRecord[] {
+  for (const page of [...group.pages].sort(sortPages)) out.push(page);
+  for (const child of [...group.groups].sort(sortPages)) flattenGroup(child, out);
+  return out;
+}
+
+/**
+ * 一次请求内的文档全量快照。
+ *
+ * 用 React cache 而不是模块级缓存：单次渲染里 layout + page 只读一次磁盘，
+ * 但下一次请求会重新读 —— Markdown 改完刷新即生效。
+ */
+export const loadDocs = cache(async () => {
+  const raw = readDir(DOCS_ROOT, '', []);
+
+  const rootPages = [...raw.pages].sort(sortPages);
+  const navGroups = raw.groups.map(toNavGroup).filter((group) => group.count > 0);
+
+  const sections: DocNavSection[] = [
+    ...rootPages
+      .filter((page) => !page.hidden)
+      .map((page) => ({ type: 'page' as const, ...toNavPage(page) })),
+    ...navGroups.map((group) => ({ type: 'group' as const, ...group })),
+  ];
+  sections.sort((a, b) => {
+    const oa = a.order - b.order;
+    return oa !== 0 ? oa : a.title.localeCompare(b.title, 'zh-CN');
+  });
+
+  const nav: DocNav = { sections };
+
+  const visible: DocRecord[] = [
+    ...rootPages,
+    ...raw.groups
+      .filter((group) => group.count > 0)
+      .sort(sortPages)
+      .flatMap((group) => flattenGroup(group)),
+  ].filter((page) => !page.hidden);
+
+  const all: DocRecord[] = [
+    ...rootPages,
+    ...raw.groups.flatMap((group) => flattenGroup(group)),
+  ];
+
+  const stats: DocsStats = {
+    pageCount: visible.length,
+    groupCount: navGroups.length,
+    updatedAt: visible.reduce((latest, page) => (page.updated > latest ? page.updated : latest), ''),
+  };
+
+  return { nav, stats, visible, all };
+});
+
+function normalizeSlug(slug: string | string[]): string {
+  const raw = Array.isArray(slug) ? slug.join('/') : String(slug ?? '');
+  return raw
+    .split('/')
+    .map((part) => {
+      try {
+        return decodeURIComponent(part);
+      } catch {
+        return part;
+      }
+    })
+    .join('/')
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/\.md$/i, '');
+}
+
+/** 按 slug 取文档；隐藏页也能通过 URL 访问 */
+export async function getDoc(slug: string | string[]): Promise<DocRecord | null> {
+  const key = normalizeSlug(slug);
+  if (!key) return null;
+  const { all } = await loadDocs();
+  return all.find((page) => page.slug === key) ?? null;
+}
+
+/** 当前文档在阅读顺序中的上一篇 / 下一篇（隐藏页不参与） */
+export async function getDocNeighbors(
+  slug: string
+): Promise<{ prev: DocNavPage | null; next: DocNavPage | null }> {
+  const { visible } = await loadDocs();
+  const index = visible.findIndex((page) => page.slug === slug);
+  if (index < 0) return { prev: null, next: null };
+  return {
+    prev: index > 0 ? toNavPage(visible[index - 1]) : null,
+    next: index < visible.length - 1 ? toNavPage(visible[index + 1]) : null,
+  };
+}
+
+function toSearchable(page: DocRecord): SearchableDoc {
+  return {
+    slug: page.slug,
+    title: page.title,
+    description: page.description,
+    tags: page.tags,
+    groupTitle: page.groupTrail.join(' / '),
+    headings: page.toc.map((item) => item.text),
+    plainText: plainTextOf(page.body),
+  };
+}
+
+/**
+ * 搜索文档。
+ *
+ * 文件读取失败也不向外抛错：搜索是辅助功能，宁可返回空结果，
+ * 也不能让整个文档站因为一篇写坏的文档而报错。
+ */
+export async function searchDocumentation(query: string, limit = 12): Promise<DocSearchHit[]> {
+  const q = String(query ?? '').trim();
+  if (!q) return [];
+  try {
+    const { visible } = await loadDocs();
+    return searchDocs(visible.map(toSearchable), q.slice(0, 80), limit);
+  } catch (e) {
+    console.error('[docs] 搜索失败（已降级为空结果）', e);
+    return [];
+  }
+}

package/resources/src/lib/err-text.ts

@@ -0,0 +1,21 @@
+import axios from 'axios';
+
+/**
+ * 把任意异常翻成一句能给用户看的中文。
+ *
+ * 约定：后端业务失败也是 HTTP 200 + `{ code, message }`（见 lib/api.ts），
+ * 所以 axios 不报错、但 body 里有 message 的情况很常见 —— 两层都要看。
+ * 最后才回落到 JS 的原始 message，避免把一屏英文堆栈甩给评委。
+ */
+export function errText(e: unknown, fallback = '操作失败'): string {
+  if (axios.isAxiosError(e)) {
+    const body = e.response?.data as { message?: string } | undefined;
+    if (body?.message) return body.message;
+    if (e.code === 'ECONNABORTED') return '请求超时，服务可能正忙';
+    if (!e.response) return '连不上服务，请确认后端已启动';
+    return e.message || fallback;
+  }
+  if (e instanceof Error) return e.message || fallback;
+  const s = String(e ?? '').trim();
+  return s || fallback;
+}

package/resources/src/lib/excel.ts

@@ -0,0 +1,152 @@
+import { Workbook, type Cell } from 'exceljs';
+import { NextResponse } from 'next/server';
+import dayjs from 'dayjs';
+
+/**
+ * Excel 导入 / 导出。
+ *
+ * 选 exceljs 而不是 xlsx(SheetJS)：exceljs 是纯 JS + 自带类型，
+ * 内网离线装完即用；而且它对「样式」支持完整，
+ * 导出的表格能带表头底色、冻结行、自动筛选，评委一眼能看出是「认真做的」。
+ */
+
+export type ExcelColumn = {
+  /** 表头显示文案 */
+  header: string;
+  /** 取数键，与 rows 里的字段名对应 */
+  key: string;
+  /** 列宽，不传则按内容自动估算 */
+  width?: number;
+};
+
+/** 单元格取纯文本：富文本 / 公式 / 超链接 / 日期都要能兜住 */
+function cellText(cell: Cell): string {
+  const v = cell.value;
+  if (v === null || v === undefined) return '';
+  if (v instanceof Date) return dayjs(v).format('YYYY-MM-DD HH:mm:ss');
+  if (typeof v === 'object') {
+    const o = v as unknown as Record<string, unknown>;
+    if (Array.isArray(o.richText)) {
+      return (o.richText as { text: string }[]).map((r) => r.text).join('');
+    }
+    if ('text' in o && o.text !== undefined) return String(o.text);
+    if ('result' in o && o.result !== undefined) return String(o.result);
+    if ('hyperlink' in o) return String(o.text ?? o.hyperlink ?? '');
+  }
+  return String(v);
+}
+
+/** 按内容粗估列宽：中文按 2 个字符宽度算，上限 50 避免一列撑满屏 */
+function estimateWidth(header: string, rows: Record<string, unknown>[], key: string): number {
+  let max = header.length * 2;
+  for (const r of rows) {
+    const s = r[key] === null || r[key] === undefined ? '' : String(r[key]);
+    let w = 0;
+    for (const ch of s) w += ch.charCodeAt(0) > 255 ? 2 : 1;
+    if (w > max) max = w;
+  }
+  return Math.min(50, Math.max(8, max + 2));
+}
+
+/**
+ * 生成 xlsx Buffer。
+ * 表头：加粗 + 灰底 + 居中；首行冻结；开启自动筛选 —— 导出的表可以直接拿去分析。
+ */
+export async function exportToExcel(opts: {
+  filename: string;
+  sheetName?: string;
+  columns: ExcelColumn[];
+  rows: Record<string, unknown>[];
+}): Promise<Buffer> {
+  const { sheetName = 'Sheet1', columns, rows } = opts;
+
+  const wb = new Workbook();
+  wb.creator = 'biz-full';
+  wb.created = new Date();
+
+  const ws = wb.addWorksheet(sheetName, {
+    views: [{ state: 'frozen', ySplit: 1 }],
+  });
+
+  ws.columns = columns.map((c) => ({
+    header: c.header,
+    key: c.key,
+    width: c.width ?? estimateWidth(c.header, rows, c.key),
+  }));
+
+  for (const row of rows) {
+    // 单独取值而不是直接 addRow(row)：避免行里多出来的键被 exceljs 当成新列加进去
+    ws.addRow(Object.fromEntries(columns.map((c) => [c.key, row[c.key] ?? ''])));
+  }
+
+  const header = ws.getRow(1);
+  header.font = { bold: true };
+  header.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFF2F3F5' } };
+  header.alignment = { vertical: 'middle', horizontal: 'center' };
+  header.height = 20;
+
+  ws.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: columns.length } };
+
+  const out = await wb.xlsx.writeBuffer();
+  return Buffer.from(out as ArrayBuffer);
+}
+
+/**
+ * 读第一个 sheet。
+ *
+ * 表头行之外的空行会被丢掉：用户从业务系统里复制粘贴的表格
+ * 末尾经常拖着一堆空行，不过滤的话导入结果里会多出一批「全部字段为空」的脏数据。
+ */
+export async function parseExcel(
+  buffer: Buffer,
+  opts: { headerRow?: number } = {}
+): Promise<{ headers: string[]; rows: Record<string, string>[] }> {
+  const headerRow = opts.headerRow ?? 1;
+
+  const wb = new Workbook();
+  await wb.xlsx.load(buffer as unknown as ArrayBuffer);
+
+  const ws = wb.worksheets[0];
+  if (!ws) return { headers: [], rows: [] };
+
+  const headers: string[] = [];
+  ws.getRow(headerRow).eachCell({ includeEmpty: true }, (cell, col) => {
+    headers[col - 1] = cellText(cell).trim();
+  });
+  const headerCount = Math.max(headers.length, ws.columnCount);
+  for (let i = 0; i < headerCount; i++) {
+    if (!headers[i]) headers[i] = `列${i + 1}`;
+  }
+
+  const rows: Record<string, string>[] = [];
+  ws.eachRow({ includeEmpty: false }, (row, rowNumber) => {
+    if (rowNumber <= headerRow) return;
+    const obj: Record<string, string> = {};
+    headers.forEach((h, idx) => {
+      obj[h] = cellText(row.getCell(idx + 1));
+    });
+    if (Object.values(obj).some((v) => v !== '')) rows.push(obj);
+  });
+
+  return { headers, rows };
+}
+
+/**
+ * 组装下载响应。
+ *
+ * 中文文件名必须用 RFC 5987 的 `filename*=UTF-8''` 形式：
+ * 直接塞进 filename="中文.xlsx" 会被浏览器按 latin-1 解析成乱码。
+ * 同时保留一个 ASCII 的 filename 兜底，兼容老旧客户端。
+ */
+export function buildExcelResponse(buffer: Buffer, filename: string) {
+  const fallback = filename.replace(/[^\x20-\x7E]/g, '_') || 'export.xlsx';
+  const encoded = encodeURIComponent(filename);
+  return new NextResponse(buffer as unknown as BodyInit, {
+    headers: {
+      'Content-Type': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      'Content-Disposition': `attachment; filename="${fallback}"; filename*=UTF-8''${encoded}`,
+      'Content-Length': String(buffer.length),
+      'Cache-Control': 'no-store',
+    },
+  });
+}

package/resources/src/lib/favorite-path.ts

@@ -0,0 +1,60 @@
+import type { SearchEntry } from './menu-service';
+
+/**
+ * 收藏（书签）的**纯函数层** —— 客户端可以安全引用。
+ *
+ * 为什么单独一个文件：AdminShell 是 'use client' 组件，一旦 import 到
+ * 带 prisma 的模块，整个数据库驱动会被打进浏览器产物。所以这里只放
+ * 类型推导与常量，查库的部分全在 favorites.ts（服务端专用），
+ * 两边共用 MAX_FAVORITES，上限只有一处定义。
+ */
+
+/**
+ * 收藏条数上限。
+ *
+ * 刻意压得很低：系统已经有 Ctrl+K 全局搜索兜底，收藏只是省掉「敲三个字」，
+ * 一旦放到十几条，侧边栏顶部就变成第二个菜单，反而更难扫。
+ */
+export const MAX_FAVORITES = 8;
+
+export type FavoriteItem = {
+  path: string;
+  name: string;
+  icon: string | null;
+  /** 面包屑（不含自己），如「系统管理」；顶级菜单为空串 */
+  trail: string;
+};
+
+/**
+ * path → 菜单条目 的索引。
+ *
+ * 为什么要「择优」而不是简单 Map 覆盖：目录节点在 buildSearchEntries 里
+ * 会借用自己第一个可跳转后代的 path，于是同一个 path 可能同时对应
+ * 「演示业务」（目录）和「员工管理」（页面）两条。若先命中目录，
+ * 收藏区就会显示成"演示业务"，用户会以为自己收藏错了。
+ * 这里让真实页面（type !== 'dir'）优先。
+ */
+export function buildFavoriteIndex(entries: SearchEntry[]): Map<string, SearchEntry> {
+  const map = new Map<string, SearchEntry>();
+  for (const e of entries) {
+    const cur = map.get(e.path);
+    if (!cur || (cur.type === 'dir' && e.type !== 'dir')) map.set(e.path, e);
+  }
+  return map;
+}
+
+/**
+ * 收藏路径 → 可渲染条目。
+ *
+ * 查不到的路径**静默丢弃**：用户权限被收回、或该模块被功能开关关掉时，
+ * 菜单树里就没有这条了。收藏是便利功能，不能因为一条失效记录就弹红条，
+ * 更不能点进去是个 403 页面。
+ */
+export function resolveFavorites(paths: string[], index: Map<string, SearchEntry>): FavoriteItem[] {
+  const out: FavoriteItem[] = [];
+  for (const p of paths) {
+    const hit = index.get(p);
+    if (hit) out.push({ path: hit.path, name: hit.name, icon: hit.icon, trail: hit.trail });
+  }
+  return out;
+}

package/resources/src/lib/favorites.ts

@@ -0,0 +1,59 @@
+import { BizError, CODE } from '@/lib/api';
+import { prisma } from '@/lib/prisma';
+import { MAX_FAVORITES } from './favorite-path';
+
+/**
+ * 收藏的持久化层（**仅服务端**，客户端不要 import —— 会拖进 prisma）。
+ *
+ * 三条约定，改之前先读：
+ *   1. 只存 path，不存 menuId。菜单主键是 cuid()，重跑 prisma/seed.ts 会重新生成，
+ *      存 id 的话所有人的收藏会集体失效；path 稳定，而且天然可跳转。
+ *   2. 不写操作日志。收藏一天可能被点几十次，写进 OperationLog 只会把
+ *      真正的业务审计（谁的增删改）淹掉，得不偿失。
+ *   3. 上限共用 MAX_FAVORITES。前端拦截一次给即时反馈，这里再拦一次兜底，
+ *      因为接口是可以被直接调的。
+ */
+
+export async function listFavoritePaths(userId: string): Promise<string[]> {
+  const rows = await prisma.userFavorite.findMany({
+    where: { userId },
+    orderBy: [{ sort: 'asc' }, { createdAt: 'asc' }],
+    select: { path: true },
+  });
+  return rows.map((r) => r.path);
+}
+
+/**
+ * 新增收藏。已存在时视为成功（幂等）——
+ * 用户连点两下星标不该报"已收藏过"这种错。
+ */
+export async function addFavoritePath(userId: string, path: string): Promise<string[]> {
+  const exists = await prisma.userFavorite.findUnique({
+    where: { userId_path: { userId, path } },
+    select: { id: true },
+  });
+
+  if (!exists) {
+    const count = await prisma.userFavorite.count({ where: { userId } });
+    if (count >= MAX_FAVORITES) {
+      throw new BizError(`最多收藏 ${MAX_FAVORITES} 个，先移除一个再添加`, CODE.BAD_REQUEST);
+    }
+    // sort 接着当前最大值往后排：新收藏固定在末尾，不会插到别人前面跳来跳去
+    const last = await prisma.userFavorite.findFirst({
+      where: { userId },
+      orderBy: { sort: 'desc' },
+      select: { sort: true },
+    });
+    await prisma.userFavorite.create({
+      data: { userId, path, sort: (last?.sort ?? -1) + 1 },
+    });
+  }
+
+  return listFavoritePaths(userId);
+}
+
+/** 移除收藏。删不到也算成功（幂等），前端无需要区分。 */
+export async function removeFavoritePath(userId: string, path: string): Promise<string[]> {
+  await prisma.userFavorite.deleteMany({ where: { userId, path } });
+  return listFavoritePaths(userId);
+}