node-resource-utils 0.0.0-stage → 1.1.7

package/resources/src/app/api/feedback/approve/route.ts

@@ -0,0 +1,67 @@
+import bcrypt from 'bcryptjs';
+import { NextRequest } from 'next/server';
+import { BizError, CODE, audit, ok, withRoute } from '@/lib/api';
+import { currentUser } from '@/auth';
+import { prisma } from '@/lib/prisma';
+
+export const dynamic = 'force-dynamic';
+
+/**
+ * POST /api/feedback/approve —— 超级管理员通过「账号申诉」。
+ *
+ * 一次动作完成三件事：
+ *   1. 把目标账号密码重置为 123456
+ *   2. 标记 mustChangePassword = 1（首次登录强制改密）
+ *   3. 把申诉反馈置为已解决并写入回复
+ *
+ * 只有超管能调用：申诉本质是「绕过密保拿回账号」，权限必须比普通管理员更高。
+ */
+export const POST = withRoute(async (req: NextRequest) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+  if (!user.isSuper) throw new BizError('只有超级管理员可以审批账号申诉', CODE.FORBIDDEN, 403);
+
+  const body = (await req.json().catch(() => ({}))) as { id?: string };
+  const id = String(body.id ?? '');
+  if (!id) throw new BizError('缺少反馈 id', CODE.BAD_REQUEST);
+
+  const feedback = await prisma.feedback.findFirst({ where: { id, deletedAt: null } });
+  if (!feedback) throw new BizError('反馈不存在', CODE.NOT_FOUND);
+  if (feedback.type !== 'account') throw new BizError('该反馈不是账号申诉', CODE.BAD_REQUEST);
+  if (feedback.status === 'resolved' || feedback.status === 'closed') {
+    throw new BizError('该申诉已结束，请先将状态改回待处理再审批', CODE.CONFLICT);
+  }
+
+  const target = await prisma.user.findFirst({ where: { id: feedback.userId, deletedAt: null } });
+  if (!target) throw new BizError('申诉对应的账号不存在或已删除', CODE.NOT_FOUND);
+
+  await prisma.user.update({
+    where: { id: target.id },
+    data: {
+      password: await bcrypt.hash('123456', 10),
+      mustChangePassword: 1,
+    },
+  });
+
+  await prisma.feedback.update({
+    where: { id },
+    data: {
+      status: 'resolved',
+      reply: '账号申诉已通过，密码已重置为 123456。请使用 123456 登录，并按提示立即修改密码。',
+      readAt: null,
+    },
+  });
+
+  await audit({
+    userId: user.id,
+    username: user.username,
+    module: '账号安全',
+    action: '通过找回申诉',
+    method: 'POST',
+    path: req.nextUrl.pathname,
+    targetId: target.id,
+    detail: { feedbackId: id, username: target.username, resetTo: '123456' },
+  });
+
+  return ok(null, '已通过申诉，密码已重置为 123456');
+});

package/resources/src/app/api/feedback/report/route.ts

@@ -0,0 +1,213 @@
+import type { NextRequest } from 'next/server';
+import { ok, withRoute, audit, BizError, CODE } from '@/lib/api';
+import { currentUser } from '@/auth';
+import { prisma } from '@/lib/prisma';
+import { aiChat, cleanAiText, AiError, AI_MODEL } from '@/lib/ai';
+
+/**
+ * 智能反馈分析报告（仅超级管理员）。
+ *
+ * 为什么单独一个接口，而不是复用 /api/ai/report：
+ *   通用报告只做「数据汇总」，说不了「用户到底想要什么」。
+ *   这里先把全部反馈读出来、算好真实统计，再让模型做**归类与优先级判断**，
+ *   最终产出固定四段式报告：总体概况 / 呼声最高的功能 / 改进建议 / 下一步行动。
+ *
+ * 权限：只有 isSuper === true 的超级管理员能调用。
+ *   反馈里可能包含用户联系方式、内部页面路径等敏感信息，
+ *   并且这是一次消耗较大的模型调用，不开放给普通管理员。
+ *
+ * POST /api/feedback/report
+ *   返回 { report, stats, total, analyzed, truncated, model, generatedAt }
+ */
+
+/** 单次最多送给模型分析的反馈条数（统计仍然按全量算） */
+const MAX_ROWS = 300;
+/** 反馈明细的字符预算，防止个别超长描述把模型上下文撑爆 */
+const MAX_PAYLOAD_CHARS = 18_000;
+
+const TYPE_LABEL: Record<string, string> = {
+  bug: '功能异常',
+  suggest: '体验建议',
+  data: '数据问题',
+  other: '其他',
+};
+
+const STATUS_LABEL: Record<string, string> = {
+  pending: '待处理',
+  doing: '处理中',
+  resolved: '已解决',
+  closed: '已关闭',
+};
+
+/** 压成一行，避免反馈里的换行把「一条一行」的明细格式打乱 */
+function oneLine(s: string | null | undefined, max: number): string {
+  return String(s ?? '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+}
+
+export const POST = withRoute(async (req: NextRequest) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+  if (!user.isSuper) {
+    throw new BizError('只有超级管理员可以生成反馈分析报告', CODE.FORBIDDEN, 403);
+  }
+
+  const where = { deletedAt: null };
+  const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+
+  // 统计按全量反馈算；明细只取最近 MAX_ROWS 条给模型。
+  // SQLite 上这些 count 都是毫秒级，并行发出去比取全量再在内存里数更稳。
+  const [
+    total,
+    pending,
+    doing,
+    resolved,
+    closed,
+    bug,
+    suggest,
+    dataIssue,
+    other,
+    last7,
+    userGroups,
+    rows,
+  ] = await Promise.all([
+    prisma.feedback.count({ where }),
+    prisma.feedback.count({ where: { ...where, status: 'pending' } }),
+    prisma.feedback.count({ where: { ...where, status: 'doing' } }),
+    prisma.feedback.count({ where: { ...where, status: 'resolved' } }),
+    prisma.feedback.count({ where: { ...where, status: 'closed' } }),
+    prisma.feedback.count({ where: { ...where, type: 'bug' } }),
+    prisma.feedback.count({ where: { ...where, type: 'suggest' } }),
+    prisma.feedback.count({ where: { ...where, type: 'data' } }),
+    prisma.feedback.count({ where: { ...where, type: 'other' } }),
+    prisma.feedback.count({ where: { ...where, createdAt: { gte: weekAgo } } }),
+    prisma.feedback.groupBy({ by: ['userId'], where }),
+    prisma.feedback.findMany({
+      where,
+      orderBy: { createdAt: 'desc' },
+      take: MAX_ROWS,
+      select: {
+        type: true,
+        title: true,
+        detail: true,
+        status: true,
+        pagePath: true,
+        reply: true,
+        createdAt: true,
+      },
+    }),
+  ]);
+
+  if (total === 0) {
+    throw new BizError('目前还没有反馈数据，暂时无法生成分析报告', CODE.BAD_REQUEST);
+  }
+
+  const stats = {
+    total,
+    pending,
+    doing,
+    resolved,
+    closed,
+    bug,
+    suggest,
+    data: dataIssue,
+    other,
+    last7,
+    users: userGroups.length,
+  };
+
+  // 按字符预算拼明细；至少保留 30 条，避免一条超长反馈就把后面全挤掉
+  const lines: string[] = [];
+  let usedChars = 0;
+  for (let i = 0; i < rows.length; i += 1) {
+    const r = rows[i];
+    const line =
+      `${i + 1}. [${TYPE_LABEL[r.type] ?? r.type}｜${STATUS_LABEL[r.status] ?? r.status}｜` +
+      `${r.createdAt.toISOString().slice(0, 10)}] ${oneLine(r.title, 80)}：${oneLine(r.detail, 160)}` +
+      (r.pagePath ? `（页面：${oneLine(r.pagePath, 80)}）` : '') +
+      (r.reply ? `（管理员回复：${oneLine(r.reply, 100)}）` : '');
+
+    if (usedChars + line.length > MAX_PAYLOAD_CHARS && lines.length >= 30) break;
+    lines.push(line);
+    usedChars += line.length;
+  }
+  const analyzed = lines.length;
+
+  const prompt = [
+    '请分析下面这组来自内部管理系统的用户反馈，写一份《用户反馈分析报告》。',
+    '',
+    '写作要求：',
+    '1. 只使用提供的真实反馈，不得编造用户、功能、数字或引用。样本不足时直接说明，不要硬凑。',
+    '2. 先通读全部反馈，把表达同一需求、同一痛点或同一类问题的条目合并归类。',
+    '3. 「用户呼声最高的功能」按被反馈提及的条数从多到少排序，最多 5 项。每项写清：需求名称、提及次数、典型反馈依据、价值判断。如果体验建议太少不足以形成功能排行，就基于真实痛点给出最迫切的改进方向，并注明这是从痛点反推的。',
+    '4. 「主要问题与改进建议」按 P0 / P1 / P2 排序。每条写清：问题表现、影响范围、具体可执行的改进动作、预期收益。改进动作要具体到能直接排期，不要只写「优化体验」。',
+    '5. 最后的「下一步行动建议」最多 3 条，按执行顺序排列。',
+    '6. 输出中文 Markdown，不要代码围栏。严格按以下结构：',
+    '## 一、总体概况',
+    '（2~3 段，引用真实数量，概括反馈结构、主要情绪和集中领域）',
+    '## 二、用户呼声最高的功能',
+    '（先给一句结论，再用表格：| 排名 | 需求 | 呼声 | 典型反馈 | 价值判断 |）',
+    '## 三、主要问题与改进建议',
+    '（表格：| 优先级 | 问题 | 改进建议 | 预期收益 |，表后补 1~2 句说明）',
+    '## 四、下一步行动建议',
+    '（有序列表，最多 3 条）',
+    '7. 不要使用「赋能」「闭环」「抓手」这类空泛词汇。语气像产品经理给团队做复盘：直接、具体、有依据。',
+    '8. 如果本次只分析了最近的一部分反馈，请在「总体概况」末尾注明样本范围。',
+    '',
+    '=== 系统统计（真实数据，可直接引用）===',
+    `反馈总数：${stats.total} 条；近 7 天新增：${stats.last7} 条；参与用户：${stats.users} 人`,
+    `类型分布：功能异常 ${stats.bug} 条，体验建议 ${stats.suggest} 条，数据问题 ${stats.data} 条，其他 ${stats.other} 条`,
+    `处理状态：待处理 ${stats.pending} 条，处理中 ${stats.doing} 条，已解决 ${stats.resolved} 条，已关闭 ${stats.closed} 条`,
+    `本次提供给模型分析：${analyzed} 条${
+      total > analyzed ? `（按时间倒序取最近 ${analyzed} 条，共 ${total} 条）` : `（全部 ${total} 条）`
+    }`,
+    '',
+    '=== 反馈明细（每条一行）===',
+    lines.join('\n'),
+  ].join('\n');
+
+  let report: string;
+  try {
+    report = cleanAiText(
+      await aiChat({
+        system:
+          '你是一名资深产品经理和体验分析师。你只依据给定的真实反馈做判断，' +
+          '善于合并同类诉求、区分事实与推测，输出结构清晰、可以直接指导排期的分析报告。',
+        messages: [{ role: 'user', content: prompt }],
+        maxTokens: 2200,
+        temperature: 0.3,
+        timeoutMs: 240_000,
+      })
+    );
+  } catch (e) {
+    if (e instanceof AiError) {
+      throw new BizError(
+        `${e.message}${e.hint ? `：${e.hint}` : ''}`,
+        CODE.SERVER_ERROR
+      );
+    }
+    throw e;
+  }
+
+  void audit({
+    module: '问题反馈',
+    action: '生成 AI 报告',
+    method: 'POST',
+    path: req.url,
+    detail: `反馈 ${stats.total} 条，分析 ${analyzed} 条`,
+    userId: user.id,
+    username: user.username,
+  });
+
+  return ok({
+    report,
+    stats,
+    total,
+    analyzed,
+    truncated: total > analyzed,
+    model: AI_MODEL,
+    generatedAt: new Date().toISOString(),
+  });
+});

package/resources/src/app/api/feedback/route.ts

@@ -0,0 +1,246 @@
+import { NextRequest } from 'next/server';
+import { ok, withRoute, audit, parseListQuery, pageResult, BizError, CODE } from '@/lib/api';
+import { currentUser } from '@/auth';
+import { prisma } from '@/lib/prisma';
+import { isFeedbackAdmin } from '@/lib/feedback-access';
+import { validateField } from '@/lib/validation';
+import { notify } from '@/lib/notifications';
+import type { NotificationLevel } from '@/lib/inbox-types';
+
+/**
+ * 问题反馈接口（骨架内置）。
+ *
+ * 设计要点：
+ *   - **任何登录用户都能提交**，不需要额外权限码 —— 否则反馈入口等于没有
+ *   - 普通用户只能看到自己的反馈；管理员能看全部并改状态
+ *   - 用软删（deletedAt），保留审计痕迹
+ *   - 状态变更（且没写回复）时给提交人发一条站内消息，见 PATCH 里的说明
+ *
+ * GET   /api/feedback?page=&pageSize=&status=&type=&q=&id=
+ *        普通用户自动只返回自己的；带 id 时只返回那一条（深链 /feedback?id=xxx 用）
+ * POST  /api/feedback   { type, title, detail, pagePath?, contact? }
+ * PATCH /api/feedback   { id, status?, reply? }   仅管理员
+ * DELETE /api/feedback? id=                       仅管理员，软删
+ */
+
+const TYPES = new Set(['bug', 'suggest', 'data', 'other', 'account']);
+const STATUSES = new Set(['pending', 'doing', 'resolved', 'closed']);
+
+/**
+ * 状态 → 站内消息文案与级别。
+ *
+ * 只在这里出现一次：管理员改状态时用户看到的那句话必须和页面上的状态标签一致，
+ * 两处各写一份文案迟早出现「状态是已解决、消息写已关闭」。
+ */
+const STATUS_NOTIFY: Record<string, { label: string; level: NotificationLevel }> = {
+  pending: { label: '待处理', level: 'info' },
+  doing: { label: '处理中', level: 'info' },
+  resolved: { label: '已解决', level: 'success' },
+  closed: { label: '已关闭', level: 'warning' },
+};
+
+/**
+ * 管理员判定放在 lib/feedback-access.ts：
+ * 侧边栏徽标要按同一套规则决定"显示全量待处理还是只显示自己的未读"，
+ * 两处各写一份正则迟早日久失修。判定本身直接读会话里的 isSuper / roleCodes ——
+ * 这两项登录时已算好放进 JWT，不必回查 user 表。
+ */
+const isAdmin = isFeedbackAdmin;
+
+export const GET = withRoute(async (req: NextRequest) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+
+  const q = parseListQuery(req);
+  const url = new URL(req.url);
+  const status = url.searchParams.get('status') || '';
+  const type = url.searchParams.get('type') || '';
+  const keyword = (url.searchParams.get('q') || '').trim();
+  // 单条查询：待办/消息里的 link 是 /feedback?id=xxx，而那条记录可能不在第 1 页。
+  // 不带这个过滤，页面上要么打不开详情，要么得把整表拉下来自己找。
+  const id = (url.searchParams.get('id') || '').trim();
+
+  const admin = isAdmin(user);
+  const where: Record<string, unknown> = { deletedAt: null };
+  // 普通用户只看自己的
+  if (!admin) where.userId = user.id;
+  if (id) where.id = id;
+  if (status && STATUSES.has(status)) where.status = status;
+  if (type && TYPES.has(type)) where.type = type;
+  if (keyword) {
+    where.OR = [{ title: { contains: keyword } }, { detail: { contains: keyword } }];
+  }
+
+  const [list, total] = await Promise.all([
+    prisma.feedback.findMany({
+      where,
+      orderBy: { createdAt: 'desc' },
+      skip: (q.page - 1) * q.pageSize,
+      take: q.pageSize,
+    }),
+    prisma.feedback.count({ where }),
+  ]);
+
+  return ok({ ...pageResult(list, total, q), canManage: admin });
+});
+
+export const POST = withRoute(async (req: NextRequest) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+
+  const body = (await req.json().catch(() => ({}))) as {
+    type?: string;
+    title?: string;
+    detail?: string;
+    pagePath?: string;
+    contact?: string;
+  };
+
+  const title = String(body.title ?? '').trim();
+  const detail = String(body.detail ?? '').trim();
+  if (title.length < 2) throw new BizError('请填写反馈标题（至少 2 个字）', CODE.BAD_REQUEST);
+  if (detail.length < 5) throw new BizError('请把问题描述清楚（至少 5 个字）', CODE.BAD_REQUEST);
+
+  // 联系方式选填，但填了就要像手机号/邮箱，避免管理员拿着错误号码回访不到人
+  const contactCheck = validateField('contact', body.contact, { label: '联系方式' });
+  if (!contactCheck.ok) throw new BizError(contactCheck.message!, CODE.BAD_REQUEST);
+
+  const type = TYPES.has(String(body.type)) ? String(body.type) : 'bug';
+
+  const row = await prisma.feedback.create({
+    data: {
+      type,
+      title: title.slice(0, 80),
+      detail: detail.slice(0, 2000),
+      pagePath: body.pagePath ? String(body.pagePath).slice(0, 200) : null,
+      contact: contactCheck.value ? contactCheck.value.slice(0, 254) : null,
+      userId: user.id,
+      username: user.username,
+    },
+  });
+
+  void audit({
+    module: '问题反馈',
+    action: '提交',
+    method: 'POST',
+    path: req.url,
+    detail: `${type}：${title}`,
+    userId: user.id,
+    username: user.username,
+  });
+
+  return ok({ id: row.id });
+});
+
+export const PATCH = withRoute(async (req: NextRequest) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+  if (!isAdmin(user)) throw new BizError('只有管理员能处理反馈', CODE.FORBIDDEN, 403);
+
+  const body = (await req.json().catch(() => ({}))) as {
+    id?: string;
+    status?: string;
+    reply?: string;
+  };
+  const id = String(body.id ?? '');
+  if (!id) throw new BizError('缺少 id', CODE.BAD_REQUEST);
+
+  // 先读旧值：既校验记录还在（软删的不许再改），也用来判断状态是否真的变了。
+  // 不比对就发通知的话，管理员把状态点成当前值也会给提交人推一条「状态已更新」的假消息。
+  const before = await prisma.feedback.findFirst({
+    where: { id, deletedAt: null },
+    select: { id: true, userId: true, title: true, status: true },
+  });
+  if (!before) throw new BizError('反馈不存在或已被删除', CODE.NOT_FOUND);
+
+  const data: Record<string, unknown> = {};
+  if (body.status) {
+    if (!STATUSES.has(body.status)) throw new BizError('状态值不合法', CODE.BAD_REQUEST);
+    data.status = body.status;
+  }
+  if (body.reply !== undefined) {
+    data.reply = String(body.reply).slice(0, 1000);
+    // 有新回复 → 重置已读时间，提交者的侧边栏会重新亮红点。
+    // 只改状态（没写回复）不动已读：那只是流程推进，没有"新消息"给他看。
+    if (data.reply) data.readAt = null;
+  }
+  if (!Object.keys(data).length) throw new BizError('没有要更新的内容', CODE.BAD_REQUEST);
+
+  const row = await prisma.feedback.update({ where: { id }, data });
+
+  /*
+   * 待办与消息的分工，这里是示例接线的核心：
+   *   写了回复 → 那条回复本身就是提交人的待办（见 src/lib/todos/feedback.ts），
+   *              业务处理完待办才消失，此时再发消息就是同一件事提醒两次；
+   *   只改状态 → 待办里什么都看不到（待办只收「未读回复」），
+   *              所以补一条站内消息，否则用户永远不知道进度动了。
+   */
+  const statusChanged = typeof data.status === 'string' && data.status !== before.status;
+  const replied = typeof data.reply === 'string' && data.reply.trim().length > 0;
+  if (statusChanged && !replied) {
+    const meta = STATUS_NOTIFY[String(data.status)] ?? {
+      label: String(data.status),
+      level: 'info' as const,
+    };
+    await notify({
+      userId: before.userId,
+      title: `反馈「${before.title}」状态更新为「${meta.label}」`,
+      body: '管理员更新了这条反馈的处理状态，点击查看详情。',
+      type: 'feedback',
+      level: meta.level,
+      link: `/feedback?id=${id}`,
+    });
+  }
+
+  void audit({
+    module: '问题反馈',
+    action: '处理',
+    method: 'PATCH',
+    path: req.url,
+    detail: `${id} -> ${String(data.status ?? '')}`,
+    userId: user.id,
+    username: user.username,
+  });
+
+  return ok({ id: row.id });
+});
+
+export const DELETE = withRoute(async (req: NextRequest) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+  if (!isAdmin(user)) throw new BizError('只有管理员能删除反馈', CODE.FORBIDDEN, 403);
+
+  const id = new URL(req.url).searchParams.get('id') || '';
+  if (!id) throw new BizError('缺少 id', CODE.BAD_REQUEST);
+
+  const before = await prisma.feedback.findFirst({
+    where: { id, deletedAt: null },
+    select: { userId: true, title: true },
+  });
+  if (!before) throw new BizError('反馈不存在或已被删除', CODE.NOT_FOUND);
+
+  await prisma.feedback.update({ where: { id }, data: { deletedAt: new Date() } });
+
+  // 删掉之后，提交人那条「未读回复」待办会一起消失。不发消息他只会觉得
+  // 自己的反馈凭空蒸发了；这是纯告知（不需要行动），所以走消息而不是待办。
+  await notify({
+    userId: before.userId,
+    title: `反馈「${before.title}」已被删除`,
+    body: '管理员删除了这条反馈，待办中的相关提醒已同时撤下。如有疑问请联系管理员。',
+    type: 'feedback',
+    level: 'warning',
+    link: '/feedback',
+  });
+
+  void audit({
+    module: '问题反馈',
+    action: '删除',
+    method: 'DELETE',
+    path: req.url,
+    detail: id,
+    userId: user.id,
+    username: user.username,
+  });
+
+  return ok({ id });
+});

package/resources/src/app/api/files/[name]/route.ts

@@ -0,0 +1,82 @@
+import { promises as fsp } from 'fs';
+import { existsSync } from 'fs';
+import { NextResponse } from 'next/server';
+import { BizError, CODE, withRoute } from '@/lib/api';
+import { requireUser } from '@/auth';
+import { resolveUploadFile, uploadOwnerOf } from '@/lib/upload';
+
+export const dynamic = 'force-dynamic';
+
+const MIME: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.bmp': 'image/bmp',
+  '.ico': 'image/x-icon',
+  '.pdf': 'application/pdf',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.csv': 'text/csv; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.ppt': 'application/vnd.ms-powerpoint',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  '.zip': 'application/zip',
+};
+
+type Ctx = { params: Promise<{ name: string }> };
+
+/**
+ * GET /api/files/[name] —— 读取 uploads 下的文件。
+ *
+ * 三道防线：
+ *   1. resolveUploadFile 拒绝含 `/`、`\`、`..` 的名字（防路径穿越）
+ *   2. 拼完绝对路径后再用 path.relative 校验没跑出 uploads 目录（防 URL 编码变体）
+ *   3. `.meta.json` 归属校验：文件按上传人隔离，别人上传的读不到
+ *      —— 否则任何登录用户拿到文件名就能读走员工导入表这类敏感附件
+ */
+export const GET = withRoute<Ctx>(async (_req, ctx) => {
+  const user = await requireUser();
+
+  const { name } = await ctx.params;
+
+  let filePath: string;
+  try {
+    // 元数据文件本身不对外提供
+    if (name.endsWith('.meta.json')) throw new Error('非法的文件名');
+    filePath = resolveUploadFile(name);
+  } catch {
+    throw new BizError('非法的文件名', CODE.BAD_REQUEST);
+  }
+
+  const owner = await uploadOwnerOf(name);
+  // 超管是「全部数据」档，可以跨人读；其他人只能读自己上传的
+  if (owner && owner !== user.id && !user.isSuper) {
+    throw new BizError('无权访问该文件', CODE.FORBIDDEN, 403);
+  }
+
+  if (!existsSync(filePath)) throw new BizError('文件不存在或已被删除', CODE.NOT_FOUND);
+
+  const buffer = await fsp.readFile(filePath);
+  const ext = filePath.slice(filePath.lastIndexOf('.')).toLowerCase();
+  const contentType = MIME[ext] ?? 'application/octet-stream';
+
+  // 图片/PDF 走 inline 便于前端直接预览，其余强制下载
+  const inline = /^image\/|^application\/pdf|^text\//.test(contentType);
+  const asciiName = name.replace(/[^\x20-\x7E]/g, '_');
+
+  return new NextResponse(buffer as unknown as BodyInit, {
+    headers: {
+      'Content-Type': contentType,
+      'Content-Length': String(buffer.length),
+      'Content-Disposition': `${inline ? 'inline' : 'attachment'}; filename="${asciiName}"; filename*=UTF-8''${encodeURIComponent(name)}`,
+      'Cache-Control': 'private, max-age=3600',
+    },
+  });
+});

package/resources/src/app/api/graph/focus/route.ts

@@ -0,0 +1,75 @@
+import { ok, withRoute, BizError, CODE } from '@/lib/api';
+import { currentUser } from '@/auth';
+import { focusOf, entityOfModel, entityById } from '@/lib/graph-focus';
+import { graphHref } from '@/lib/graph-link';
+import { delegateFor } from '@/lib/graph-node-write';
+import { DATA_SCOPE, deptScope, effectiveDataScope } from '@/lib/rbac';
+import { fieldsOfModel } from '@/lib/graph-schema';
+
+/**
+ * 业务记录 → 图谱关联 的解析接口（全站通用，不认识任何具体业务）。
+ *
+ * GET /api/graph/focus?src=FitnessRecord:clx123
+ * GET /api/graph/focus?model=FitnessRecord&id=clx123
+ * GET /api/graph/focus?entity=record&id=clx123
+ *
+ * 返回：这条记录在图谱里的关联簇（节点 / 边 / 视图 / single|multi）+
+ *      一个可直接跳转的 /graph 地址。
+ *
+ * ★ 业务页面只需要知道自己的 **模型名**，不用记图谱本体 id。
+ *   模型没有在 ontology.ts 里声明时，这里会明确说出"还没接图谱"，
+ *   而不是让用户跳到一张空图。
+ */
+export const dynamic = 'force-dynamic';
+
+export const GET = withRoute(async (req) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+
+  const sp = new URL(req.url).searchParams;
+  const src = (sp.get('src') ?? '').trim();
+  const cut = src.indexOf(':');
+  const srcModel = cut > 0 ? src.slice(0, cut) : '';
+  const srcId = cut > 0 ? src.slice(cut + 1) : '';
+
+  const model = (sp.get('model') ?? '').trim() || srcModel;
+  const id = (sp.get('id') ?? '').trim() || srcId;
+  // 备用入口：直接给本体 id（图谱节点链接、手工排查时用）
+  const entityId = (sp.get('entity') ?? '').trim();
+  const byEntity = entityId ? entityById(entityId)?.model : undefined;
+
+  const modelName = model || byEntity || '';
+
+  if (!modelName || !id) {
+    throw new BizError('缺少参数：src=<模型名>:<记录id>，或 model + id', CODE.BAD_REQUEST);
+  }
+
+  // 数据范围：范围外的记录按「不存在」处理，别泄露「存在但你没权限」这件事本身
+  if (
+    effectiveDataScope(user) !== DATA_SCOPE.ALL &&
+    fieldsOfModel(modelName).some((f) => f.name === 'deptId')
+  ) {
+    const row = await delegateFor(modelName).findFirst?.({
+      where: { id, ...deptScope(user) },
+    });
+    if (!row) throw new BizError('记录不存在或已被删除', CODE.NOT_FOUND, 404);
+  }
+
+  const focus = await focusOf(modelName, id);  if (!entityOfModel(modelName)) {
+    throw new BizError(
+      `模型 ${modelName} 还没有接入知识图谱：请在 src/lib/ontology.ts 的 entities 里声明它（model: '${modelName}'），并给它 layer 与至少一条 relations`,
+      CODE.NOT_FOUND,
+      404
+    );
+  }
+  if (!focus) {
+    // 模型接入了图谱，但这条记录取不到（不存在 / 已被软删）
+    throw new BizError('记录不存在或已被删除', CODE.NOT_FOUND, 404);
+  }
+
+  return ok({
+    ...focus,
+    /** 业务页面直接跳这个地址；图谱页读到 src 后会再调一次本接口拿高亮信息 */
+    url: graphHref(focus.source.model, focus.source.dbId, focus.view.id),
+  });
+});