node-resource-utils 0.0.0-stage → 1.1.8

package/resources/src/lib/badge-count.ts

@@ -0,0 +1,146 @@
+import { prisma } from '@/lib/prisma';
+import type { SessionUser } from '@/auth';
+import type { MenuTreeNode } from '@/lib/menu-service';
+import { isFeedbackAdmin } from '@/lib/feedback-access';
+
+/**
+ * 侧边栏徽标的**计数实现**（仅服务端）。
+ *
+ * 分工：
+ *   badges.ts       有哪些计数源（元信息，客户端可引）
+ *   badge-count.ts  每个源怎么数、怎么清（查库，绝不能进客户端 bundle）
+ *
+ * 三个关键约定：
+ *   1. **计数失败不能拖垮页面**。徽标是锦上添花，计数器抛错就当 0，
+ *      并打日志。让一次 SQL 异常把整个后台布局打成 500 是本末倒置。
+ *   2. **只算当前用户菜单树里的菜单**。用户看不见的模块，其数字也不该被算，
+ *      否则会多出一次"莫名其妙"的查询，还可能泄露别的模块有多少待办。
+ *   3. **确认已读（ack）只做该做的事**。"待处理"类计数进页面不清零
+ *      （事情没处理完就不该消失），"未读"类计数进页面才清零。
+ *      哪个源是哪种语义，由它自己有没有 ACK 处理器决定，前端不需要知道。
+ */
+
+type Counter = (user: SessionUser) => Promise<number>;
+type Acker = (user: SessionUser) => Promise<void>;
+
+/** 待处理型 / 未读型计数器。key 必须与 BADGE_SOURCES 一致 */
+const COUNTERS: Record<string, Counter> = {
+  /**
+   * 问题反馈 · 待我关注
+   *
+   * 一个计数源覆盖两种角色视角，是因为菜单徽标只有"一个数字"的位置：
+   *   - 管理员：全库待处理（pending）数 —— 这是他要干的活
+   *   - 普通用户：我提交的、管理员已回复、我还没点开看的条数 —— 这是他的"未读"
+   * 如果给同一菜单挂两个源，只能显示一个，反而更困惑。
+   */
+  'feedback:attention': async (user) => {
+    if (isFeedbackAdmin(user)) {
+      return prisma.feedback.count({ where: { deletedAt: null, status: 'pending' } });
+    }
+    return prisma.feedback.count({
+      where: {
+        deletedAt: null,
+        userId: user.id,
+        readAt: null,
+        reply: { not: null }, // 只有"有人回过你"才算未读，自己提的单子在等处理不该一直亮红
+        status: { not: 'closed' },
+      },
+    });
+  },
+};
+
+/**
+ * 确认已读处理器。
+ *
+ * 只有"未读"语义的源才需要实现它。管理员侧不实现 ——
+ * 待处理数只能靠真的把单子处理掉来减少，进页面就清零等于骗人。
+ */
+const ACKERS: Record<string, Acker> = {
+  'feedback:attention': async (user) => {
+    if (isFeedbackAdmin(user)) return; // 管理员看的是待办，不是未读
+    await prisma.feedback.updateMany({
+      where: { deletedAt: null, userId: user.id, readAt: null, reply: { not: null } },
+      data: { readAt: new Date() },
+    });
+  },
+};
+
+export type BadgeMap = Record<string, number>;
+
+/** 菜单树里所有挂了计数源的叶子：path（徽标落点） + badgeKey（怎么数） */
+type Slot = { path: string; key: string };
+
+function collectSlots(nodes: MenuTreeNode[], out: Slot[] = []): Slot[] {
+  for (const n of nodes) {
+    if (n.type === 'button' || n.hidden === 1) continue;
+    if (n.path && n.badgeKey) out.push({ path: n.path, key: n.badgeKey });
+    collectSlots(n.children, out);
+  }
+  return out;
+}
+
+async function runCounter(user: SessionUser, key: string): Promise<number> {
+  const counter = COUNTERS[key];
+  if (!counter) {
+    // 配置了菜单但没写计数器：宁可显示 0，也不要让侧边栏报错
+    console.warn(`[badge] 未实现的计数源：${key}`);
+    return 0;
+  }
+  try {
+    const n = await counter(user);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+  } catch (e) {
+    console.error(`[badge] 计数源 ${key} 执行失败（已按 0 处理）`, e);
+    return 0;
+  }
+}
+
+/**
+ * 算出当前用户所有菜单徽标：`{ '/feedback': 3 }`。
+ *
+ * 同一个 key 被多个菜单引用时只查一次（比如"待我审批"既挂在顶栏也挂在业务目录下）。
+ */
+export async function collectBadges(user: SessionUser, menus: MenuTreeNode[]): Promise<BadgeMap> {
+  const slots = collectSlots(menus);
+  if (!slots.length) return {};
+
+  const cache = new Map<string, Promise<number>>();
+  const pairs = await Promise.all(
+    slots.map(async (s) => {
+      let pending = cache.get(s.key);
+      if (!pending) {
+        pending = runCounter(user, s.key);
+        cache.set(s.key, pending);
+      }
+      return [s.path, await pending] as const;
+    })
+  );
+
+  const out: BadgeMap = {};
+  for (const [path, count] of pairs) out[path] = count;
+  return out;
+}
+
+/**
+ * 用户进入了某个页面 → 该页面的徽标可以"确认已读"。
+ *
+ * 返回确认后的**最新全量计数**，前端一次请求就能同时完成"清零"和"刷新"。
+ * 传进来的 path 必须来自当前用户自己的菜单树（这里用 collectSlots 反查），
+ * 于是别人伪造一个 path 也 ack 不到任何东西。
+ */
+export async function ackBadge(
+  user: SessionUser,
+  menus: MenuTreeNode[],
+  path: string
+): Promise<BadgeMap> {
+  const slot = collectSlots(menus).find((s) => s.path === path);
+  const ack = slot ? ACKERS[slot.key] : undefined;
+  if (ack) {
+    try {
+      await ack(user);
+    } catch (e) {
+      console.error(`[badge] 确认已读 ${slot?.key} 失败（已忽略）`, e);
+    }
+  }
+  return collectBadges(user, menus);
+}

package/resources/src/lib/badges.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { BADGE_MAX, BADGE_SOURCES, badgeText, sumBadges } from './badges';
+
+/**
+ * 徽标纯函数测试。
+ *
+ * 这几条看着琐碎，但都是侧边栏每天要渲染几十次的分支：
+ * 0 要不要显示、三位数会不会把菜单挤变形、后端返回 null 时会不会渲染出 "NaN"。
+ * NaN 尤其致命 —— 它会原样出现在侧边栏上，是评委一眼就能看见的那种 bug。
+ */
+describe('badgeText', () => {
+  it('0 和负数不显示', () => {
+    expect(badgeText(0)).toBe('');
+    expect(badgeText(-3)).toBe('');
+  });
+
+  it('非法数字一律当 0，不渲染 NaN', () => {
+    expect(badgeText(Number.NaN)).toBe('');
+    expect(badgeText(Number.POSITIVE_INFINITY)).toBe('');
+  });
+
+  it('正常数字原样显示', () => {
+    expect(badgeText(1)).toBe('1');
+    expect(badgeText(BADGE_MAX)).toBe(String(BADGE_MAX));
+  });
+
+  it('超过上限折成 99+，不把侧边栏撑开', () => {
+    expect(badgeText(BADGE_MAX + 1)).toBe(`${BADGE_MAX}+`);
+    expect(badgeText(12345)).toBe(`${BADGE_MAX}+`);
+  });
+
+  it('小数向下取整（计数不该出现 2.5 条待办）', () => {
+    expect(badgeText(2.9)).toBe('2');
+  });
+});
+
+describe('sumBadges', () => {
+  it('目录汇总：只累加有效正数', () => {
+    expect(sumBadges([1, 2, 3])).toBe(6);
+    expect(sumBadges([1, undefined, null, 2])).toBe(3);
+    expect(sumBadges([-5, 4])).toBe(4);
+    expect(sumBadges([])).toBe(0);
+  });
+});
+
+describe('BADGE_SOURCES', () => {
+  it('key 唯一，否则菜单上挂哪个源会变得不确定', () => {
+    const keys = BADGE_SOURCES.map((s) => s.key);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it('每条都有给人看的说明（菜单管理里要显示）', () => {
+    for (const s of BADGE_SOURCES) {
+      expect(s.label.length).toBeGreaterThan(0);
+      expect(s.hint.length).toBeGreaterThan(0);
+    }
+  });
+});

package/resources/src/lib/badges.ts

@@ -0,0 +1,79 @@
+/**
+ * 侧边栏徽标（红色数字提示）—— 共享元信息与纯函数。
+ *
+ * ★ 这个文件**必须保持客户端安全**：侧边栏、菜单管理页都要 import 它，
+ *   所以这里只放常量与纯函数，一行数据库代码都不能有。
+ *   真正的"怎么数"在 badge-count.ts（仅服务端）。
+ *
+ * 设计取舍：
+ *   - 徽标挂在**菜单**上（Menu.badgeKey），不是写死在页面里。
+ *     于是"给某个模块加红点"变成一条数据配置，新模块不用改侧边栏。
+ *   - 计数源用注册表（key → 计数器），而不是在菜单表里存一条 SQL。
+ *     菜单表存 SQL 会把注入面和维护成本一起带进来。
+ *   - 一个菜单只有一个计数源。需要"未读 + 待办"两个维度时，
+ *     在计数器内部按角色/状态合成一个数字（见 feedback:attention）。
+ */
+
+/** 一个可挂到菜单上的计数源 */
+export type BadgeSource = {
+  /** 存进 Menu.badgeKey 的值，全局唯一 */
+  key: string;
+  /** 菜单管理里显示的名字 */
+  label: string;
+  /** 一句话说明这个数字代表什么，给配置的人看 */
+  hint: string;
+};
+
+/**
+ * 内置计数源。
+ *
+ * 加新的业务模块时，照 feedback 的样子走三步：
+ *   1. 这里登记一条（label + hint）
+ *   2. badge-count.ts 的 COUNTERS 里写计数器（必须同名，check:config 会比对）
+ *   3. 菜单管理里给对应菜单选上这个源，或 seed 里直接写 badgeKey
+ */
+export const BADGE_SOURCES: BadgeSource[] = [
+  {
+    key: 'feedback:attention',
+    label: '问题反馈 · 待我关注',
+    hint: '管理员看到的是全部待处理反馈数；普通用户看到的是「我提交的、有新回复但还没看」的条数',
+  },
+];
+
+export const BADGE_META: Record<string, BadgeSource> = Object.fromEntries(
+  BADGE_SOURCES.map((s) => [s.key, s])
+);
+
+/**
+ * 徽标底色。
+ *
+ * 不用 antd 默认的 #ff4d4f：那是给白底设计的，放到深军绿侧边栏上会发粉、发飘。
+ * #C93F31 是与 MILITARY.error(#B4472F) 同族的砖红，压深一档后
+ * 白字对比度 5.3:1（小字号也够读），在深绿底上是一块干净的实心色块。
+ */
+export const BADGE_COLOR = '#C93F31';
+
+/** 超过这个数显示 99+，避免侧边栏被三位数撑开 */
+export const BADGE_MAX = 99;
+
+/** 数字 → 展示文案。非法值一律当 0，宁可不显示也不要显示 NaN */
+export function badgeText(n: number): string {
+  const v = Number.isFinite(n) ? Math.floor(n) : 0;
+  if (v <= 0) return '';
+  return v > BADGE_MAX ? `${BADGE_MAX}+` : String(v);
+}
+
+/**
+ * 目录节点的汇总数：自身 + 所有可见子项。
+ *
+ * 为什么目录也要显示：侧边栏折叠（以及分组收起）时，子项徽标是看不见的，
+ * 父级没有汇总就等于"这个分组里有待办"这件事彻底消失了。
+ * 隐藏项（hidden=1）不计入 —— 用户点不进去，算了只会让人对不上账。
+ */
+export function sumBadges(values: (number | null | undefined)[]): number {
+  let total = 0;
+  for (const v of values) {
+    if (typeof v === 'number' && Number.isFinite(v) && v > 0) total += Math.floor(v);
+  }
+  return total;
+}

package/resources/src/lib/brand-mark.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+import { MARK_UNITS, brandMark } from './brand-mark';
+
+/**
+ * 侧栏收起后方块里的短名。
+ *
+ * 这组用例盯的是 2026-10-23 修的那个 bug 的两端：
+ *   · 英文缩写不许再被砍（'BIZ' → 'BI' 那种，按字符数 slice 的后果）；
+ *   · 中文不许超宽（两个中文 26px，旧方块内容区只有 24px → 折行、掉出方块）。
+ * 宽度单位：中文/全角 1，拉丁字母与数字 0.6，上限 MARK_UNITS。
+ */
+
+describe('brandMark —— 收起态（按宽度取前缀）', () => {
+  it('3 字母英文缩写完整保留（旧代码会砍成 BI）', () => {
+    expect(brandMark('BIZ', true)).toBe('BIZ');
+  });
+
+  it('4 字母缩写截到 3 个（再多就超过 2 个单位）', () => {
+    expect(brandMark('YJXT', true)).toBe('YJX');
+  });
+
+  it('2 个中文完整保留', () => {
+    expect(brandMark('车辆', true)).toBe('车辆');
+  });
+
+  it('4 个中文只留 2 字', () => {
+    expect(brandMark('综合管理', true)).toBe('综合');
+  });
+
+  it('中日韩 + 拉丁混排按实际宽度累加', () => {
+    // 车(1) + B(0.6) = 1.6，再加 i(0.6) = 2.2 > 2 → 只留「车B」
+    expect(brandMark('车Bi', true)).toBe('车B');
+  });
+
+  it('单字中文原样返回', () => {
+    expect(brandMark('业', true)).toBe('业');
+  });
+
+  it('前后空格不算宽度', () => {
+    expect(brandMark('  车辆  ', true)).toBe('车辆');
+  });
+
+  it('空串返回空串（兜底交给调用方，不在这里编一个假名字）', () => {
+    expect(brandMark('', true)).toBe('');
+    expect(brandMark('   ', true)).toBe('');
+  });
+
+  it('全角标点按 1 个单位算（和中文同宽）', () => {
+    expect(brandMark('系统（一）', true)).toBe('系统');
+  });
+});
+
+describe('brandMark —— 展开态', () => {
+  it('只取首字（旁边就是全名）', () => {
+    expect(brandMark('业务管理系统', false)).toBe('业');
+  });
+
+  it('英文全名也只取首字母', () => {
+    expect(brandMark('Vehicle Dispatch', false)).toBe('V');
+  });
+
+  it('空串返回空串', () => {
+    expect(brandMark('', false)).toBe('');
+  });
+});
+
+describe('brandMark —— 与方块尺寸的约定', () => {
+  /**
+   * 这组是"代码里的数字"和"CSS 里的尺寸"之间的暗号：
+   * 收起态方块 30px、描边 1px、字号 13px（见 AdminShell 的 fs(collapsed ? 30 : 26)）。
+   * 一旦有人改方块尺寸或字号却没同步 MARK_UNITS，这里先红。
+   */
+  const MARK_BOX = 30;
+  const BORDER = 1;
+  const FONT = 13;
+  const UNIT_PX = FONT; // 一个中文字 ≈ 1em
+
+  it('2 个单位的中文确实塞得进方块内容区', () => {
+    const contentWidth = MARK_BOX - BORDER * 2;
+    expect(MARK_UNITS * UNIT_PX).toBeLessThanOrEqual(contentWidth);
+  });
+
+  it('3 个拉丁字母（1.8 个单位）也塞得进', () => {
+    const contentWidth = MARK_BOX - BORDER * 2;
+    expect(1.8 * UNIT_PX).toBeLessThanOrEqual(contentWidth);
+  });
+});

package/resources/src/lib/brand-mark.ts

@@ -0,0 +1,45 @@
+/**
+ * 侧栏品牌方块里那几个字怎么取。
+ *
+ * 为什么单独一个模块：
+ *   1. 这是纯函数，行数/宽度算错了**只有肉眼看截图才发现**（旧 bug 就是这样漏出去的），
+ *      放进 lib 才能被 vitest 直接按住。
+ *   2. AdminShell 是 'use client' 大组件，往里塞一段字符串算法没人看得见。
+ *
+ * 方块里能放几个字由**宽度**决定，不是由字符数决定（2026-10-23 修）：
+ *   · 旧写法 `APP_SHORT.slice(0, 2)` 按字符切，英文缩写永远被砍：
+ *     'BIZ' → 'BI'、'YJXT' → 'YJ'，而 APP_SHORT 的注释写的是「2~4 个字符，或英文缩写」。
+ *   · 反过来中文刚好卡在边界：「车辆」是 2 个字符，但两个 13px 中文 = 26px，
+ *     收起态方块内容区（30px − 2px 描边 = 28px）在旧版本只有 24px，
+ *     于是折行成竖排、「辆」掉到方块外面。
+ *
+ * 现在按宽度单位取前缀：中文/全角 1 个单位、拉丁字母与数字 0.6 个单位，
+ * 上限 2 个单位 —— 中文最多 2 字、拉丁最多 3 字母，两种都塞得下。
+ */
+
+/** 方块内容区能装下的宽度单位数 */
+export const MARK_UNITS = 2;
+
+/** 全角 / 中日韩文字按 1 个单位；其余（拉丁字母、数字、符号）按 0.6 个单位 */
+const WIDE_CHAR = /[\u3000-\u303f\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uff00-\uffef]/;
+
+/**
+ * 取品牌方块要显示的文字。
+ *
+ * @param text      候选文案（收起态传 APP_SHORT，展开态传 APP_NAME）
+ * @param collapsed 是否收起。展开态方块旁边就是全名，取首字即可
+ * @returns 能放进方块的前缀；传空串时返回空串，由调用方决定兜底
+ */
+export function brandMark(text: string, collapsed: boolean): string {
+  // 展开态：方块 26px、旁边就是全名，一个字足够
+  if (!collapsed) return text.slice(0, 1);
+
+  let used = 0;
+  let out = '';
+  for (const ch of text.trim()) {
+    used += WIDE_CHAR.test(ch) ? 1 : 0.6;
+    if (used > MARK_UNITS + 1e-6) break;
+    out += ch;
+  }
+  return out;
+}

package/resources/src/lib/docs-shared.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+import {
+  excerptAround,
+  extractToc,
+  headingId,
+  parseFrontMatter,
+  readingMinutesOf,
+  searchDocs,
+  stripLeadingH1,
+  toTags,
+  type SearchableDoc,
+} from './docs-shared';
+
+const doc = (patch: Partial<SearchableDoc> = {}): SearchableDoc => ({
+  slug: 'guide/account',
+  title: '账号与登录',
+  description: '登录、退出与找回密码',
+  tags: ['账号', '密码'],
+  groupTitle: '使用指南',
+  headings: ['登录', '修改密码'],
+  plainText: '登录系统后建议立即修改密码。忘记密码可以走密保问题。',
+  ...patch,
+});
+
+describe('parseFrontMatter', () => {
+  it('解析标题、数字、布尔、数组与引号', () => {
+    const { data, body } = parseFrontMatter(
+      [
+        '---',
+        'title: "快速开始"',
+        'order: 2',
+        'hidden: false',
+        'tags: [入门, 登录]',
+        'description: 三分钟上手',
+        '---',
+        '',
+        '## 正文',
+      ].join('\n')
+    );
+
+    expect(data.title).toBe('快速开始');
+    expect(data.order).toBe(2);
+    expect(data.hidden).toBe(false);
+    expect(data.tags).toEqual(['入门', '登录']);
+    expect(data.description).toBe('三分钟上手');
+    expect(body.trim()).toBe('## 正文');
+  });
+
+  it('没有 front matter 时原样返回正文', () => {
+    const raw = '## 标题\n正文';
+    expect(parseFrontMatter(raw)).toEqual({ data: {}, body: raw });
+  });
+
+  it('未闭合的 front matter 降级为正文，不丢内容', () => {
+    const raw = '---\ntitle: 坏的\n\n正文仍然要显示';
+    const parsed = parseFrontMatter(raw);
+    expect(parsed.data).toEqual({});
+    expect(parsed.body).toBe(raw);
+  });
+
+  it('tags 支持逗号分隔字符串', () => {
+    expect(toTags('账号, 密码、安全')).toEqual(['账号', '密码', '安全']);
+  });
+});
+
+describe('headingId / extractToc', () => {
+  it('重名标题自动去重，中文标题保留可读 id', () => {
+    const used = new Set<string>();
+    expect(headingId('登录', used)).toBe('登录');
+    expect(headingId('登录', used)).toBe('登录-2');
+    expect(headingId('账号 与 登录', used)).toBe('账号-与-登录');
+  });
+
+  it('目录只收 h2 / h3，并跳过代码块里的井号', () => {
+    const body = [
+      '# 页面标题',
+      '## 第一节',
+      '```bash',
+      '## 代码里的井号不是标题',
+      '```',
+      '### 子节',
+      '## 第一节',
+      '#### 太深',
+    ].join('\n');
+
+    const toc = extractToc(body);
+    expect(toc.map((item) => [item.level, item.text, item.id])).toEqual([
+      [2, '第一节', '第一节'],
+      [3, '子节', '子节'],
+      [2, '第一节', '第一节-2'],
+    ]);
+  });
+
+  it('去掉正文开头的 H1，保留后面的内容', () => {
+    expect(stripLeadingH1('# 标题\n\n正文')).toBe('正文');
+    expect(stripLeadingH1('前言\n# 标题')).toBe('前言\n# 标题');
+  });
+});
+
+describe('searchDocs', () => {
+  it('多关键词按 AND 匹配', () => {
+    const docs = [
+      doc(),
+      doc({
+        slug: 'guide/data',
+        title: '数据导入',
+        description: '',
+        tags: [],
+        headings: [],
+        plainText: '账号权限与导入',
+      }),
+    ];
+    const hits = searchDocs(docs, '账号 密码');
+    expect(hits).toHaveLength(1);
+    expect(hits[0].slug).toBe('guide/account');
+  });
+
+  it('标题命中排在正文命中之前', () => {
+    const docs = [
+      doc({ slug: 'a', title: '普通文档', plainText: '这里有账号两个字', tags: [], description: '' }),
+      doc({ slug: 'b', title: '账号管理', plainText: '与关键词无关', tags: [], description: '' }),
+    ];
+    const hits = searchDocs(docs, '账号');
+    expect(hits.map((h) => h.slug)).toEqual(['b', 'a']);
+  });
+
+  it('别名标签也能命中', () => {
+    const hits = searchDocs([doc()], '密码');
+    expect(hits[0]?.slug).toBe('guide/account');
+  });
+
+  it('无结果时返回空数组', () => {
+    expect(searchDocs([doc()], '完全不存在的词')).toEqual([]);
+  });
+});
+
+describe('展示工具', () => {
+  it('摘要截取命中词附近的内容', () => {
+    const text = `${'前'.repeat(80)}关键词${'后'.repeat(80)}`;
+    const excerpt = excerptAround(text, ['关键词'], 40);
+    expect(excerpt).toContain('关键词');
+    expect(excerpt.startsWith('…')).toBe(true);
+  });
+
+  it('阅读时长至少 1 分钟', () => {
+    expect(readingMinutesOf('短文本')).toBe(1);
+  });
+});