node-resource-utils 0.0.0-stage → 1.1.7

package/resources/src/lib/http.ts

@@ -0,0 +1,157 @@
+'use client';
+
+import axios, { type AxiosRequestConfig, type InternalAxiosRequestConfig } from 'axios';
+import { beginTask, endTask } from './pending';
+
+/**
+ * 请求级等待追踪。
+ *
+ * ★ 这是「任何耗时场景都有提示」的**兜底层**：
+ *   在 Providers 里装一次拦截器，全站所有 axios 请求（现有 34 个接口 +
+ *   比赛新加的接口）都会自动登记到全局任务表，
+ *   超过 3 秒没有结束，右下角就会浮出一张「正在处理…已等待 N 秒」的小卡片。
+ *
+ *   也就是说：哪怕新写的页面忘了加 loading，用户也不会对着静止的界面猜。
+ *   页面里自己加的 spinner 是「锦上添花」，这一层是「不会翻车」。
+ *
+ * 不追踪的情况：给请求加 `{ __silent: true }`。
+ * 用于轮询、后台预取、以及自己已经有精细进度的上传。
+ */
+
+declare module 'axios' {
+  export interface AxiosRequestConfig {
+    /**
+     * 设为 true 时，这次请求不进入全局等待提示。
+     * 适合：定时轮询、页面预取、已有自己进度条的上传。
+     */
+    __silent?: boolean;
+  }
+}
+
+/**
+ * 路径 → 人话文案。
+ *
+ * 命中不到不算错，会回退成「正在处理数据…」。
+ * 比赛出了新题、加了新接口，想让提示更具体，在这里补一行正则即可 ——
+ * 不需要改页面、不需要改组件。
+ */
+const LABELS: { test: RegExp; text: string }[] = [
+  { test: /^\/api\/ai\/chat$/, text: 'AI 正在思考，请稍候…' },
+  { test: /^\/api\/ai\/report$/, text: '正在把真实数据交给本地模型…' },
+  { test: /^\/api\/ai\/act$/, text: '正在执行确认过的操作…' },
+  { test: /^\/api\/graph\/focus$/, text: '正在解析这条记录与图谱的关联…' },
+  { test: /^\/api\/graph\/node$/, text: '正在读取节点字段…' },
+  { test: /^\/api\/graph/, text: '正在加载图谱数据…' },
+  { test: /^\/api\/export/, text: '正在生成导出文件…' },
+  { test: /^\/api\/upload/, text: '正在上传文件…' },
+  { test: /^\/api\/stats/, text: '正在汇总统计数据…' },
+  { test: /^\/api\/search/, text: '正在全库检索…' },
+  { test: /^\/api\/auth/, text: '正在验证身份…' },
+  { test: /^\/api\/logs/, text: '正在读取操作日志…' },
+  { test: /^\/api\/files/, text: '正在读取文件…' },
+  { test: /^\/api\/docs/, text: '正在生成文档…' },
+];
+
+/** 把请求 URL 转成面向用户的一句话 */
+export function labelForRequest(url?: string, method?: string): string {
+  if (!url) return '正在处理数据…';
+  // 去掉 query / hash / 可能的绝对地址前缀，只留 pathname
+  const path = url.split('?')[0].split('#')[0].replace(/^https?:\/\/[^/]+/, '');
+  for (const item of LABELS) {
+    if (item.test.test(path)) return item.text;
+  }
+  if (method === 'DELETE') return '正在删除，请稍候…';
+  if (method === 'POST' || method === 'PUT' || method === 'PATCH') return '正在提交数据…';
+  return '正在加载数据…';
+}
+
+type TrackedConfig = InternalAxiosRequestConfig & { __pendingId?: string };
+
+function endFor(config?: AxiosRequestConfig | TrackedConfig | null) {
+  endTask((config as TrackedConfig | undefined)?.__pendingId);
+}
+
+let installed = false;
+
+/**
+ * 装上全局拦截器。幂等：重复调用只会生效一次。
+ * 由 Providers 在客户端挂载时调用，不放进模块顶层 —— 顶层执行会在 SSR 时也跑一遍。
+ */
+export function installRequestTracking(): void {
+  if (installed) return;
+  installed = true;
+
+  axios.interceptors.request.use((config) => {
+    const c = config as TrackedConfig;
+    if (!c.__silent) {
+      c.__pendingId = beginTask(labelForRequest(c.url, c.method?.toUpperCase()), 'request');
+    }
+    return config;
+  });
+
+  axios.interceptors.response.use(
+    (res) => {
+      endFor(res.config as TrackedConfig);
+      return res;
+    },
+    (err) => {
+      // 请求没发出去（断网、被取消）时 err.config 可能为空，endTask 对空 id 是安全的
+      endFor(err?.config as TrackedConfig | undefined);
+      return Promise.reject(err);
+    }
+  );
+}
+
+/**
+ * 客户端模块一被求值就装好拦截器。
+ *
+ * ★ 为什么不能只靠 Providers 的 useEffect：
+ *   React 的 effect 是「子先父后」，页面组件（DataTable 的 useQuery）的 effect
+ *   会比 Providers 的 effect 先跑 —— 首屏那一发请求就会漏掉追踪。
+ *   模块求值早于一切渲染，这里装最保险。 Providers 里那次调用留作幂等兜底。
+ */
+if (typeof window !== 'undefined') {
+  installRequestTracking();
+}
+
+/**
+ * fetch 版追踪包装。
+ *
+ * 为什么需要它：axios 的拦截器管不到原生 fetch，而 AI 对话（SSE 流式）、
+ * 图谱聚焦这些"最慢的请求"恰好都是 fetch。新代码一律用这个函数，
+ * 就能和 axios 请求一样，慢到一定程度自动出现在全局浮层里。
+ *
+ * 用法：
+ *   const res = await trackedFetch('/api/ai/chat', { method: 'POST', body });
+ *   // 需要精细控制时自己收尾：
+ *   const { res, done } = await trackedFetch.withHandle(...); done();
+ */
+export async function trackedFetch(input: string, init?: RequestInit): Promise<Response> {
+  const label = labelForRequest(input, init?.method?.toUpperCase());
+  const id = beginTask(label, 'request');
+  try {
+    return await fetch(input, init);
+  } finally {
+    endTask(id);
+  }
+}
+
+/**
+ * 流式/长连接专用：返回 res 的同时把「结束」的控制权交给调用方。
+ *
+ * 因为 SSE 是 `await fetch()` 就返回了 Response，真正的耗时在后续读流里，
+ * 用普通 trackedFetch 会在响应头到达时就把任务注销掉 —— 恰恰漏掉了最慢的那段。
+ */
+export async function trackedFetchStream(
+  input: string,
+  init?: RequestInit
+): Promise<{ res: Response; done: () => void }> {
+  const id = beginTask(labelForRequest(input, init?.method?.toUpperCase()), 'request');
+  try {
+    const res = await fetch(input, init);
+    return { res, done: () => endTask(id) };
+  } catch (e) {
+    endTask(id);
+    throw e;
+  }
+}

package/resources/src/lib/inbox-types.ts

@@ -0,0 +1,57 @@
+/**
+ * 待办与消息中心的共享类型。
+ *
+ * 这个文件**不碰 Prisma / 文件系统**，服务端聚合结果和客户端组件共用同一套形状，
+ * 避免「接口返回的字段和页面取的字段对不上」这类低级错误。
+ */
+
+export type InboxTodoLevel = 'info' | 'warning' | 'error';
+
+export type InboxTodoItem = {
+  /** 业务侧唯一 id，仅用于 React key；不需要全局唯一 */
+  id: string;
+  title: string;
+  subtitle?: string;
+  /** 点击后去的内部路由，必须带足够信息定位到具体记录 */
+  link: string;
+  level?: InboxTodoLevel;
+  createdAt?: string;
+};
+
+export type InboxTodoGroup = {
+  key: string;
+  name: string;
+  description?: string;
+  /** 菜单图标名（与 menu-icons 的映射表一致） */
+  icon?: string;
+  /** 该来源的待办总数，可能大于 items.length */
+  count: number;
+  items: InboxTodoItem[];
+};
+
+export type NotificationLevel = 'info' | 'success' | 'warning' | 'error';
+
+export type InboxNotification = {
+  id: string;
+  title: string;
+  body: string | null;
+  type: string;
+  level: NotificationLevel;
+  link: string | null;
+  readAt: string | null;
+  createdAt: string;
+};
+
+/** 顶栏铃铛只需要这个摘要，不拉全量列表 */
+export type InboxSummary = {
+  todoCount: number;
+  unreadCount: number;
+  total: number;
+};
+
+export type InboxData = {
+  summary: InboxSummary;
+  todoGroups: InboxTodoGroup[];
+  /** 最近的消息（含已读），客户端按未读筛选 */
+  notifications: InboxNotification[];
+};

package/resources/src/lib/inbox.ts

@@ -0,0 +1,55 @@
+import type { SessionUser } from '@/auth';
+import type { InboxData, InboxNotification, InboxSummary, InboxTodoGroup } from './inbox-types';
+import { listTodoGroups, countTodos } from './todos';
+import { countUnreadNotifications, listNotifications } from './notifications';
+
+/**
+ * 待办与消息的聚合层（服务端）。
+ *
+ * 顶栏铃铛只要摘要，/inbox 要摘要 + 分组待办 + 最近消息。
+ * 所有子查询都做失败降级：某个来源、消息表或计数出错时，
+ * 页面仍然能打开，只是对应区块为空，而不是整页 500。
+ */
+
+export async function getInboxSummary(user: SessionUser): Promise<InboxSummary> {
+  const [todoResult, unreadResult] = await Promise.allSettled([
+    countTodos(user),
+    countUnreadNotifications(user.id),
+  ]);
+
+  if (todoResult.status === 'rejected') {
+    console.error('[inbox] 待办计数失败（已按 0 处理）', todoResult.reason);
+  }
+  if (unreadResult.status === 'rejected') {
+    console.error('[inbox] 未读消息计数失败（已按 0 处理）', unreadResult.reason);
+  }
+
+  const todoCount = todoResult.status === 'fulfilled' ? todoResult.value : 0;
+  const unreadCount = unreadResult.status === 'fulfilled' ? unreadResult.value : 0;
+
+  return { todoCount, unreadCount, total: todoCount + unreadCount };
+}
+
+export async function getInboxData(user: SessionUser): Promise<InboxData> {
+  const [groupsResult, notificationsResult] = await Promise.allSettled([
+    listTodoGroups(user, 20),
+    listNotifications(user.id, 100),
+  ]);
+
+  let todoGroups: InboxTodoGroup[] = [];
+  if (groupsResult.status === 'fulfilled') {
+    todoGroups = groupsResult.value;
+  } else {
+    console.error('[inbox] 待办列表加载失败（已按空处理）', groupsResult.reason);
+  }
+
+  let notifications: InboxNotification[] = [];
+  if (notificationsResult.status === 'fulfilled') {
+    notifications = notificationsResult.value;
+  } else {
+    console.error('[inbox] 消息列表加载失败（已按空处理）', notificationsResult.reason);
+  }
+
+  const summary = await getInboxSummary(user);
+  return { summary, todoGroups, notifications };
+}

package/resources/src/lib/menu-service.ts

@@ -0,0 +1,204 @@
+import { prisma } from '@/lib/prisma';
+import type { SessionUser } from '@/auth';
+import { isPathEnabled } from './features';
+
+/**
+ * 菜单树服务。
+ *
+ * 为什么单独抽一层：`/api/menus/mine`（前端动态菜单）和 `(admin)/layout.tsx`
+ * （服务端首屏渲染侧边栏）要的是同一份数据。抽出来后，
+ * 「谁能看到哪些菜单」这条规则全项目只有一处实现，不会出现
+ * 「接口给的菜单和布局给的菜单不一致」这种诡异 bug。
+ */
+
+export type MenuNode = {
+  id: string;
+  parentId: string | null;
+  name: string;
+  path: string | null;
+  icon: string | null;
+  keywords: string | null;
+  /** 侧边栏徽标的计数源（见 badges.ts）；null = 不显示徽标 */
+  badgeKey: string | null;
+  type: string; // dir | menu | button
+  permCode: string | null;
+  sort: number;
+  hidden: number;
+  status: number;
+};
+
+export type TreeItem<T> = T & { children: TreeItem<T>[] };
+export type MenuTreeNode = TreeItem<MenuNode>;
+
+const MENU_SELECT = {
+  id: true,
+  parentId: true,
+  name: true,
+  path: true,
+  icon: true,
+  keywords: true,
+  badgeKey: true,
+  type: true,
+  permCode: true,
+  sort: true,
+  hidden: true,
+  status: true,
+} as const;
+
+/**
+ * 扁平列表 → 树。
+ * 找不到父节点的条目会被当成根节点，而不是被丢弃 ——
+ * 权限只勾了子菜单没勾父目录时，子菜单依然要能显示出来。
+ */
+export function buildTree<T extends { id: string; parentId: string | null }>(list: T[]): TreeItem<T>[] {
+  const map = new Map<string, TreeItem<T>>();
+  for (const item of list) {
+    map.set(item.id, { ...item, children: [] } as TreeItem<T>);
+  }
+
+  const roots: TreeItem<T>[] = [];
+  for (const node of map.values()) {
+    const parent = node.parentId ? map.get(node.parentId) : undefined;
+    if (parent) parent.children.push(node);
+    else roots.push(node);
+  }
+
+  const sortRec = (arr: TreeItem<T>[]) => {
+    arr.sort(
+      (a, b) =>
+        Number((a as { sort?: number }).sort ?? 0) - Number((b as { sort?: number }).sort ?? 0)
+    );
+    for (const n of arr) sortRec(n.children);
+  };
+  sortRec(roots);
+
+  return roots;
+}
+
+/**
+ * 当前用户可见的菜单树。
+ *
+ * - 超管：全部启用中的菜单
+ * - 普通用户：其「启用角色」关联到的、且本身启用中的菜单
+ *
+ * 注意返回里包含 type='button' 的条目：前端按钮级鉴权要用它，
+ * 渲染侧边栏时由前端自己过滤掉。
+ */
+export async function getUserMenuTree(user: SessionUser): Promise<MenuTreeNode[]> {
+  const where = user.isSuper
+    ? { status: 1 }
+    : {
+        status: 1,
+        roles: {
+          some: {
+            role: {
+              status: 1,
+              users: { some: { userId: user.id } },
+            },
+          },
+        },
+      };
+
+  const menus = await prisma.menu.findMany({
+    where,
+    orderBy: { sort: 'asc' },
+    select: MENU_SELECT,
+  });
+
+  return buildTree(menus as MenuNode[]);
+}
+
+/**
+ * 按功能开关过滤菜单树。
+ *
+ * 与 toSidebarTree 的区别：这里**保留按钮节点**，因为菜单管理页和角色授权
+ * 抽屉需要维护/勾选按钮级权限。但被开关关闭的模块（连同其下的按钮）整体移除，
+ * 否则在管理界面里仍能直接看到，等于没关。
+ */
+function filterByFeatures(nodes: MenuTreeNode[]): MenuTreeNode[] {
+  return nodes
+    .map((n) => ({ ...n, children: filterByFeatures(n.children) }))
+    .filter((n) => (n.path ? isPathEnabled(n.path) : n.children.length > 0));
+}
+
+/** 全部菜单树（菜单管理页 / 角色授权抽屉用） */
+export async function getFullMenuTree(): Promise<MenuTreeNode[]> {
+  const menus = await prisma.menu.findMany({ orderBy: { sort: 'asc' }, select: MENU_SELECT });
+  return filterByFeatures(buildTree(menus as MenuNode[]));
+}
+
+/** 侧边栏渲染用：剔除按钮、隐藏项，以及功能开关关闭的模块 */
+export function toSidebarTree(nodes: MenuTreeNode[]): MenuTreeNode[] {
+  const walk = (list: MenuTreeNode[]): MenuTreeNode[] =>
+    list
+      .filter((n) => n.type !== 'button' && n.hidden !== 1)
+      .map((n) => ({ ...n, children: walk(n.children) }))
+      // 开关关掉的模块不出现；目录的子项全被滤掉时，目录本身也一并去掉，
+      // 否则会留下一个点开什么都没有的空分组。
+      .filter((n) => (n.path ? isPathEnabled(n.path) : n.children.length > 0));
+  return walk(nodes);
+}
+
+/* ============================ 全局搜索索引 ============================ */
+
+/**
+ * 搜索索引条目。
+ *
+ * `path` 一定是**可跳转的真实路由**：目录节点自己没有 path，
+ * 取其第一个可跳转的后代页面，这样搜「AI 能力」也能落到 AI 中心。
+ */
+export type SearchEntry = {
+  id: string;
+  name: string;
+  path: string;
+  icon: string | null;
+  type: string;
+  /** 空格/逗号分隔的别名，原样传给前端做匹配 */
+  keywords: string;
+  /** 面包屑文案（不含自己），如「AI 能力」；顶级菜单为空串 */
+  trail: string;
+};
+
+/** 目录的第一个可跳转后代（按 sort 深度优先）；找不到返回 null */
+function firstLeafPath(node: MenuTreeNode): string | null {
+  for (const child of node.children) {
+    if (child.type !== 'button' && child.hidden !== 1 && child.path) return child.path;
+    const deep = firstLeafPath(child);
+    if (deep) return deep;
+  }
+  return null;
+}
+
+/**
+ * 菜单树 → 全局搜索索引。
+ *
+ * 为什么拿菜单树当唯一数据源：**菜单就是这个系统的「功能注册表」** ——
+ * AI 每加一个业务模块都会在 seed 里登记菜单（见通用提示词铁律），
+ * 所以新功能不用为搜索写任何代码，进了侧边栏就等于进了搜索。
+ * 按钮（type=button）没有页面、隐藏菜单用户看不见，两者都不进索引。
+ */
+export function buildSearchEntries(nodes: MenuTreeNode[]): SearchEntry[] {
+  const out: SearchEntry[] = [];
+  const walk = (list: MenuTreeNode[], trail: string) => {
+    for (const n of list) {
+      if (n.type === 'button' || n.hidden === 1) continue;
+      const path = n.path || firstLeafPath(n);
+      // 开关关掉的模块不进搜索索引，否则搜到了点进去是空
+      if (path && !isPathEnabled(path)) continue;
+      if (path) {
+        out.push({
+          id: n.id,
+          name: n.name,
+          path,
+          icon: n.icon,
+          type: n.type,
+          keywords: n.keywords ?? '',
+          trail,
+        });
+      }
+      walk(n.children, trail ? `${trail} / ${n.name}` : n.name);
+    }
+  };
+  walk(nodes, '');
+  return out;
+}

package/resources/src/lib/notifications.ts

@@ -0,0 +1,113 @@
+import { prisma } from '@/lib/prisma';
+import type { InboxNotification, NotificationLevel } from './inbox-types';
+
+/**
+ * 站内消息服务（服务端）。
+ *
+ * 任何业务模块都可以调用 `notify()` 给一个或多个用户写消息；
+ * 收件人、已读状态和跳转链接都由调用方决定，消息中心本身不关心业务。
+ *
+ * 设计取舍：
+ *   - 一条记录只属于一个用户。广播消息由这里拆成多条写入，
+ *     换取最简单的「单用户已读」语义，也避免再维护一张已读表。
+ *   - 写消息失败绝不阻塞主业务：消息是通知，不是交易。
+ *   - link 只允许站内路径，防止业务侧传进外链造成开放重定向。
+ */
+
+export type NotifyInput = {
+  userId?: string;
+  userIds?: string[];
+  title: string;
+  body?: string | null;
+  type?: string;
+  level?: NotificationLevel;
+  link?: string | null;
+};
+
+const LEVELS = new Set<NotificationLevel>(['info', 'success', 'warning', 'error']);
+
+function normalizeLevel(value: unknown): NotificationLevel {
+  return LEVELS.has(value as NotificationLevel) ? (value as NotificationLevel) : 'info';
+}
+
+function normalizeLink(value: unknown): string | null {
+  const link = typeof value === 'string' ? value.trim() : '';
+  if (!link || !link.startsWith('/')) return null;
+  return link.slice(0, 500);
+}
+
+/** 给一个或多个用户写消息；重复 userId 会自动去重 */
+export async function notify(input: NotifyInput): Promise<void> {
+  try {
+    const ids = Array.from(
+      new Set([...(input.userIds ?? []), ...(input.userId ? [input.userId] : [])].filter(Boolean))
+    );
+    if (!ids.length) return;
+
+    const title = String(input.title ?? '').trim();
+    if (!title) return;
+
+    await prisma.notification.createMany({
+      data: ids.map((userId) => ({
+        userId,
+        title: title.slice(0, 200),
+        body: input.body ? String(input.body).slice(0, 1000) : null,
+        type: (input.type ?? 'system').slice(0, 40),
+        level: normalizeLevel(input.level),
+        link: normalizeLink(input.link),
+      })),
+    });
+  } catch (e) {
+    // 消息写不进去也不能让业务回滚；日志留给管理员排查
+    console.error('[notify] 写入站内消息失败（已忽略，不影响主业务）', e);
+  }
+}
+
+export async function notifyUsers(
+  userIds: string[],
+  input: Omit<NotifyInput, 'userId' | 'userIds'>
+): Promise<void> {
+  await notify({ ...input, userIds });
+}
+
+/** 最近消息（含已读）；消息中心不需要无限历史，默认取最近 100 条 */
+export async function listNotifications(userId: string, limit = 100): Promise<InboxNotification[]> {
+  const rows = await prisma.notification.findMany({
+    where: { userId },
+    orderBy: { createdAt: 'desc' },
+    take: Math.min(200, Math.max(1, limit)),
+  });
+
+  return rows.map((row) => ({
+    id: row.id,
+    title: row.title,
+    body: row.body,
+    type: row.type,
+    level: normalizeLevel(row.level),
+    link: row.link,
+    readAt: row.readAt ? row.readAt.toISOString() : null,
+    createdAt: row.createdAt.toISOString(),
+  }));
+}
+
+export async function countUnreadNotifications(userId: string): Promise<number> {
+  return prisma.notification.count({ where: { userId, readAt: null } });
+}
+
+/** 标记一条消息已读，返回剩余未读数；只能操作自己的消息 */
+export async function markNotificationRead(userId: string, id: string): Promise<number> {
+  await prisma.notification.updateMany({
+    where: { id, userId, readAt: null },
+    data: { readAt: new Date() },
+  });
+  return countUnreadNotifications(userId);
+}
+
+/** 标记当前用户全部消息已读 */
+export async function markAllNotificationsRead(userId: string): Promise<number> {
+  await prisma.notification.updateMany({
+    where: { userId, readAt: null },
+    data: { readAt: new Date() },
+  });
+  return 0;
+}