node-resource-utils 0.0.0-stage → 1.1.8

package/resources/src/app/api/graph/node/move/route.ts

@@ -0,0 +1,48 @@
+import { ok, withRoute, audit, BizError, CODE } from '@/lib/api';
+import { currentUser } from '@/auth';
+import { moveNode, requireGraphWriter } from '@/lib/graph-node-write';
+
+/**
+ * POST /api/graph/node/move —— 变更节点类型（把节点迁移到另一个本体）。
+ *
+ * ★ 为什么单独一个接口，而不是 PATCH 里加个 toEntity：
+ *   节点"类型"不是某个字段，而是**它存在哪张表**。
+ *   换类型 = 目标本体新建一条记录 + 清掉旧记录（含级联置空/连带删除），
+ *   这和普通改字段完全不是一个量级的操作，必须走单独确认流程。
+ *
+ * 请求：{ fromEntity, id, toEntity, data? }
+ *   data 里只带用户在面板里改过的值；同名字段由服务端自动继承。
+ */
+export const POST = withRoute(async (req) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+  // 变更类型 = 建新记录 + 删旧记录，是破坏性最大的图谱写操作，同样只给超管
+  requireGraphWriter(user);
+
+  const body = (await req.json().catch(() => ({}))) as {
+    fromEntity?: string;
+    toEntity?: string;
+    id?: string;
+    data?: Record<string, unknown>;
+  };
+  const fromEntity = String(body.fromEntity ?? '');
+  const toEntity = String(body.toEntity ?? '');
+  const id = String(body.id ?? '');
+  if (!fromEntity || !toEntity || !id) {
+    throw new BizError('缺少 fromEntity / toEntity / id', CODE.BAD_REQUEST);
+  }
+
+  const res = await moveNode({ fromEntity, id, toEntity, data: body.data });
+
+  void audit({
+    module: '知识图谱',
+    action: '变更节点类型',
+    method: 'POST',
+    path: req.url,
+    detail: `${fromEntity}(${id}) → ${toEntity}(${res.id}) 继承字段=${res.inherited.join(',') || '无'}`,
+    userId: user.id,
+    username: user.username,
+  });
+
+  return ok(res);
+});

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

@@ -0,0 +1,274 @@
+import { ok, withRoute, audit, BizError, CODE } from '@/lib/api';
+import { currentUser, type SessionUser } from '@/auth';
+import ONTOLOGY from '@/lib/ontology';
+import { deleteWithCleanup, impactOf } from '@/lib/graph-cascade';
+import { delegateFor, requireGraphWriter, translatePrismaError } from '@/lib/graph-node-write';
+import { graphWhereOf } from '@/lib/graph-scope';
+import {
+  coercePayload,
+  fieldsForEntity,
+  fillRequired,
+  optionsOf,
+  type FieldMeta,
+} from '@/lib/graph-schema';
+
+/**
+ * 知识图谱节点增删改 —— 让"在图谱里操作 = 真的改数据库"。
+ *
+ * 这是图谱从"看着好看"变成"真能用"的关键：
+ * 用户在右侧面板里改名 / 改状态 / 改附加信息 / 删除节点，落库后重新拉图就能看到变化。
+ *
+ * 所有写操作都在**本体白名单**内进行：
+ *   只有 ONTOLOGY.entities 里声明的模型才允许写，
+ *   不允许借这个接口去改 User / Role 这类敏感表（除非本体里显式声明）。
+ * 字段白名单则由 graph-schema 从 prisma schema 反推，password / token 一类的列永远不许写。
+ *
+ * GET    /api/graph/node?entity&id             删除影响预览
+ * GET    /api/graph/node?entity&id&detail=1    节点全字段 + 字段元数据（详情面板用）
+ * GET    /api/graph/node?entity&meta=1         字段元数据（切换本体类型时预取）
+ * POST   /api/graph/node   { entity, data }    新增
+ * PATCH  /api/graph/node   { entity, id, data } 修改
+ * DELETE /api/graph/node   { entity, id }      删除（软删优先）
+ */
+
+/**
+ * 图谱直接写库只对超管开放（判断在 lib/graph-node-write.ts，三个写接口共用）。
+ *
+ * 业务数据的增删改必须走各自模块的接口 —— 那里才有业务权限码和数据范围校验。
+ * 否则任何登录用户都能绕过模块权限，用这个接口改/删别人部门的单据，
+ * 前面在列表和导出上做的行级过滤就白做了。
+ */
+function entityOf(id: string) {
+  const e = ONTOLOGY.entities.find((x) => x.id === id);
+  if (!e) {
+    throw new BizError(
+      `本体 ${id} 未在 ontology.ts 中声明。可用：${ONTOLOGY.entities.map((x) => x.id).join(', ')}`,
+      CODE.BAD_REQUEST
+    );
+  }
+  return e;
+}
+
+/** 字段值 → 可 JSON 化的展示值（Date 统一 ISO 字符串，前端好接 dayjs） */
+function displayValues(row: Record<string, unknown>, fields: FieldMeta[]) {
+  const out: Record<string, unknown> = {};
+  for (const f of fields) {
+    const v = row[f.name];
+    out[f.name] = v instanceof Date ? v.toISOString() : (v ?? null);
+  }
+  return out;
+}
+
+/**
+ * 详情面板要的数据：
+ *   fields  —— 有哪些字段、什么类型、什么选项（表单据此渲染）
+ *   values  —— 当前值
+ *   refs    —— 外键下拉选项
+ *   entities—— 可选本体（"类型"下拉）
+ */
+async function detailPayload(entityId: string, id?: string) {
+  const ent = entityOf(entityId);
+  const fields = fieldsForEntity(ent.id);
+  let values: Record<string, unknown> = {};
+  let title = ent.label;
+
+  if (id) {
+    const row = await delegateFor(ent.model).findUnique({ where: { id } });
+    if (!row) throw new BizError('节点不存在或已被删除', CODE.NOT_FOUND, 404);
+    values = displayValues(row, fields);
+    title = String(row[ent.titleField] ?? id);
+  }
+
+  const refs: Record<string, { label: string; value: string | number }[]> = {};
+  await Promise.all(
+    fields
+      .filter((f) => f.kind === 'fk' && f.refModel)
+      .map(async (f) => {
+        refs[f.name] = await optionsOf(f.refModel!);
+      })
+  );
+
+  return {
+    entity: {
+      id: ent.id,
+      label: ent.label,
+      model: ent.model,
+      titleField: ent.titleField,
+      subtitleFields: ent.subtitleFields ?? [],
+    },
+    /** "类型"下拉的候选项（含不在当前视图里的本体，切过去会重新取字段） */
+    entities: ONTOLOGY.entities.map((e) => ({ id: e.id, label: e.label, model: e.model })),
+    fields,
+    values,
+    refs,
+    title,
+  };
+}
+
+/**
+ * 详情面板 / 删除影响预览 的范围闸。
+ *
+ * 这两个入口都会返回**全字段**（薪资、电话这类敏感列都在里面），
+ * 且是按 id 直取的 —— 不过这一关，知道一个 id 就能把范围外的人看穿。
+ * 范围外、已软删的一律按「不存在」处理，不泄露"存在但你没权限"。
+ */
+async function assertNodeInScope(entityId: string, id: string | undefined, user: SessionUser) {
+  if (!id) return;
+  const ent = entityOf(entityId);
+  const row = await delegateFor(ent.model).findFirst?.({
+    where: { ...graphWhereOf(ent.model, user), id },
+  });
+  if (!row) throw new BizError('节点不存在或已被删除', CODE.NOT_FOUND, 404);
+}
+
+export const GET = withRoute(async (req) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+
+  const url = new URL(req.url);
+  const entity = String(url.searchParams.get('entity') ?? '');
+  const id = String(url.searchParams.get('id') ?? '');
+  if (!entity) throw new BizError('缺少 entity', CODE.BAD_REQUEST);
+
+  // 详情面板：有 id 取全字段，没 id（切类型时）只取字段定义
+  const detail = url.searchParams.get('detail');
+  const meta = url.searchParams.get('meta');
+  if (detail || meta) {
+    if (detail && !id) throw new BizError('缺少 id', CODE.BAD_REQUEST);
+    // ★ 详情面板是"全字段"出口（含薪资这类敏感列），范围外的节点按不存在处理
+    await assertNodeInScope(entity, id, user);
+    return ok(await detailPayload(entity, detail ? id : undefined));
+  }
+
+  if (!id) throw new BizError('缺少 entity / id', CODE.BAD_REQUEST);
+
+  try {
+    await assertNodeInScope(entity, id, user);
+    const impact = await impactOf(entity, id);
+    return ok(impact);
+  } catch (e) {
+    // 范围闸抛的 404 要原样透出，别被这层 catch 改成 400（前端靠状态码区分"没有"和"参数错"）
+    if (e instanceof BizError) throw e;
+    throw new BizError(e instanceof Error ? e.message : String(e), CODE.BAD_REQUEST);
+  }
+});
+
+export const POST = withRoute(async (req) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+  requireGraphWriter(user);
+
+  const body = (await req.json().catch(() => ({}))) as {
+    entity?: string;
+    data?: Record<string, unknown>;
+  };
+  const ent = entityOf(String(body.entity ?? ''));
+  // ★ 先清洗（只留真实字段 + 类型转换），再给必填字段补占位值
+  const payload = await fillRequired(ent.model, coercePayload(ent.model, body.data ?? {}));
+  if (!Object.keys(payload).length) {
+    throw new BizError('没有可写入的字段（检查字段名是否与 Prisma 模型一致）', CODE.BAD_REQUEST);
+  }
+
+  let row: Record<string, unknown>;
+  try {
+    row = await delegateFor(ent.model).create({ data: payload });
+  } catch (e) {
+    translatePrismaError(e);
+  }
+
+  void audit({
+    module: '知识图谱',
+    action: '新增节点',
+    method: 'POST',
+    path: req.url,
+    detail: `${ent.model} id=${String(row.id)}`,
+    userId: user.id,
+    username: user.username,
+  });
+  return ok({ id: row.id });
+});
+
+export const PATCH = withRoute(async (req) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+  requireGraphWriter(user);
+
+  const body = (await req.json().catch(() => ({}))) as {
+    entity?: string;
+    id?: string;
+    data?: Record<string, unknown>;
+  };
+  const ent = entityOf(String(body.entity ?? ''));
+  const id = String(body.id ?? '');
+  if (!id) throw new BizError('缺少 id', CODE.BAD_REQUEST);
+
+  const payload = coercePayload(ent.model, body.data ?? {});
+  if (!Object.keys(payload).length) {
+    throw new BizError(
+      '没有可更新的字段（可能提交的是只读字段，或字段名与该模型不一致）',
+      CODE.BAD_REQUEST
+    );
+  }
+
+  const d = delegateFor(ent.model);
+  const exists = await d.findUnique({ where: { id } });
+  if (!exists) throw new BizError('节点不存在或已被删除', CODE.NOT_FOUND, 404);
+
+  let row: Record<string, unknown>;
+  try {
+    row = await d.update({ where: { id }, data: payload });
+  } catch (e) {
+    translatePrismaError(e);
+  }
+
+  void audit({
+    module: '知识图谱',
+    action: '修改节点',
+    method: 'PATCH',
+    path: req.url,
+    detail: `${ent.model} id=${id} 字段=${Object.keys(payload).join(',')}`,
+    userId: user.id,
+    username: user.username,
+  });
+  return ok({ id: row.id, entity: ent.id, changed: Object.keys(payload) });
+});
+
+export const DELETE = withRoute(async (req) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+  requireGraphWriter(user);
+
+  const body = (await req.json().catch(() => ({}))) as { entity?: string; id?: string };
+  const ent = entityOf(String(body.entity ?? ''));
+  const id = String(body.id ?? '');
+  if (!id) throw new BizError('缺少 id', CODE.BAD_REQUEST);
+
+  const d = delegateFor(ent.model);
+  const row = await d.findUnique({ where: { id } });
+  if (!row) throw new BizError('节点不存在', CODE.NOT_FOUND, 404);
+
+  /**
+   * 删除 + 级联清理放在一个事务里（见 lib/graph-cascade.ts）：
+   *   - 可选外键 → 置空（解除关联，保留业务行）
+   *   - 必填外键 → 连带删除依赖行（递归）
+   *   - 有 deletedAt 的模型 → 只软删，不动引用
+   * 提交前还会复核所有反向引用是否归零，清理不彻底就整体回滚。
+   */
+  let res;
+  try {
+    res = await deleteWithCleanup(ent.id, id);
+  } catch (e) {
+    translatePrismaError(e);
+  }
+
+  void audit({
+    module: '知识图谱',
+    action: '删除节点',
+    method: 'DELETE',
+    path: req.url,
+    detail: `${ent.model} id=${id} 连带删除=${res.deleted} 置空=${res.nullified}${res.soft ? '（软删）' : ''}`,
+    userId: user.id,
+    username: user.username,
+  });
+  return ok({ id, ...res });
+});

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

@@ -0,0 +1,272 @@
+import { ok, withRoute, BizError, CODE } from '@/lib/api';
+import { currentUser, type SessionUser } from '@/auth';
+import { prisma } from '@/lib/prisma';
+import { graphWhereOf } from '@/lib/graph-scope';
+import ONTOLOGY from '@/lib/ontology';
+
+/**
+ * 知识图谱数据接口（通用引擎）。
+ *
+ * 前端只要传 view id，就能拿到一张完整的图。
+ * 画什么由 src/lib/ontology.ts 的声明式配置决定，这个接口本身不认识任何业务。
+ *
+ * GET /api/graph?view=dispatch&center=<节点id>&depth=2
+ *   view   视图 id，对应 ontology.ts 里的 views[].id
+ *   center 可选，指定中心节点（只保留与它相距 depth 跳以内的节点）
+ *   depth  默认 2
+ */
+
+type Node = {
+  /** 图内唯一键：`${entity}:${dbId}`，ECharts 的边靠它连节点 */
+  id: string;
+  /** 数据库主键。增删改必须用它 —— 直接拿 id 去 findUnique 会 404（踩过） */
+  dbId: string;
+  label: string;
+  entity: string;
+  color: string;
+  borderColor?: string;
+  subtitle: string;
+  link?: string;
+};
+type Edge = { source: string; target: string; label: string; relation: string };
+
+const MAX_NODES = 120; // 节点太多会糊成一团，也拖慢渲染
+
+export const GET = withRoute(async (req) => {
+  const user = await currentUser();
+  if (!user) throw new BizError('请先登录', CODE.UNAUTHORIZED, 401);
+
+  const url = new URL(req.url);
+  const viewId = url.searchParams.get('view') || ONTOLOGY.views[0]?.id;
+  const center = url.searchParams.get('center');
+  /**
+   * depth 允许 0 —— 只要中心节点本身，不展开任何关系。
+   * 业务表「关联」跳到"单实体"时用 depth=0：一个字典项在图谱里就一个节点，
+   * 展开它的反向关系只会得到几十条成绩记录，把画布铺成一团扇形，反而看不清。
+   */
+  const depthRaw = url.searchParams.get('depth');
+  const depth = depthRaw === null ? 2 : Math.min(Math.max(Number(depthRaw) || 0, 0), 4);
+
+  const view = ONTOLOGY.views.find((v) => v.id === viewId);
+  if (!view) {
+    throw new BizError(
+      ONTOLOGY.views.length
+        ? `图谱视图 ${viewId} 不存在。可用视图：${ONTOLOGY.views.map((v) => v.id).join(', ')}`
+        : 'ontology.ts 没有配置 views —— 知识图谱无法渲染。请在 ontology.ts 里加一个视图（entities / relations / root）',
+      CODE.BAD_REQUEST
+    );
+  }
+
+  const entMap = new Map(ONTOLOGY.entities.map((e) => [e.id, e]));
+  const relMap = new Map(ONTOLOGY.relations.map((r) => [r.id, r]));
+
+  const nodes: Node[] = [];
+  const nodeKeys = new Set<string>();
+  const edges: Edge[] = [];
+  const edgeKeys = new Set<string>();
+
+  const pushNode = (entity: string, id: string, label: string, subtitle: string) => {
+    const key = `${entity}:${id}`;
+    if (nodeKeys.has(key)) return;
+    const def = entMap.get(entity)!;
+    nodeKeys.add(key);
+    nodes.push({
+      id: key,
+      dbId: id,
+      label,
+      entity,
+      color: def.color,
+      borderColor: def.borderColor,
+      subtitle,
+      link: def.link?.replace(':id', id),
+    });
+  };
+
+  /** 按 depth 做 BFS 展开，避免一上来把整库拉进来 */
+  let frontier: { entity: string; id: string }[] = [];
+
+  // ---- 根节点：center 指定了就用它，否则取视图里每个本体的前若干条 ----
+  if (center) {
+    const [entity, id] = center.split(':');
+    if (!entMap.has(entity)) throw new BizError(`未知本体 ${entity}`, CODE.BAD_REQUEST);
+    const def = entMap.get(entity)!;
+    const row = await rowOf(def.model, id, user);
+    if (!row) throw new BizError('中心节点不存在', CODE.BAD_REQUEST);
+    pushNode(entity, id, String(row[def.titleField] ?? id), subOf(def, row));
+    frontier = [{ entity, id }];
+  } else {
+    for (const eid of view.entities) {
+      const def = entMap.get(eid);
+      if (!def) continue;
+      const rows = await rowsOf(def.model, 12, user);
+      for (const r of rows) {
+        pushNode(eid, String(r.id), String(r[def.titleField] ?? r.id), subOf(def, r));
+        frontier.push({ entity: eid, id: String(r.id) });
+      }
+      if (nodes.length >= MAX_NODES) break;
+    }
+  }
+
+  // ---- 逐跳展开关系 ----
+  for (let hop = 0; hop < depth && frontier.length; hop++) {
+    const next: { entity: string; id: string }[] = [];
+    for (const cur of frontier) {
+      for (const rid of view.relations) {
+        const rel = relMap.get(rid);
+        if (!rel || (rel.from !== cur.entity && rel.to !== cur.entity)) continue;
+        // 从 cur 出发能拿到哪些邻居
+        const neighbors = await neighborsOf(cur, rel, user);
+        for (const n of neighbors) {
+          pushNode(n.entity, n.id, n.label, n.subtitle);
+          const a = `${cur.entity}:${cur.id}`;
+          const b = `${n.entity}:${n.id}`;
+          if (a === b) continue;
+          // ⚠️ 同一条关系会被 BFS 从两侧各展开一次（cur 是 from 时一次、是 to 时一次），
+          //   以前用带方向的 key 去重，结果一条关系出现两条方向相反的边，
+          //   页面按边数统计"下属"直接翻倍（部门 (16) 实际是 8）。
+          //   现在：方向固定为 ontology 声明的 from → to，去重键按无向排序。
+          const src = n.entity === rel.from ? b : a;
+          const dst = n.entity === rel.from ? a : b;
+          const [lo, hi] = src < dst ? [src, dst] : [dst, src];
+          const ek = `${rel.id}|${lo}|${hi}`;
+          if (!edgeKeys.has(ek)) {
+            edgeKeys.add(ek);
+            edges.push({ source: src, target: dst, label: rel.label, relation: rel.id });
+          }
+          next.push(n);
+        }
+      }
+      if (nodes.length >= MAX_NODES) break;
+    }
+    frontier = next;
+    if (nodes.length >= MAX_NODES) break;
+  }
+
+  return ok({
+    view: { id: view.id, label: view.label },
+    // 视图列表随数据返回，页面据此渲染下拉，不在前端硬编码——避免两边漂移
+    views: ONTOLOGY.views.map((v) => ({ label: v.label, value: v.id })),
+    nodes: nodes.slice(0, MAX_NODES),
+    edges,
+    truncated: nodes.length >= MAX_NODES,
+    entities: ONTOLOGY.entities
+      .filter((e) => view.entities.includes(e.id))
+      .map((e) => ({
+        id: e.id,
+        label: e.label,
+        color: e.color,
+        layer: e.layer ?? 0,
+        // ★ 标题字段随数据下发：前端不再维护 entity → 字段名的硬编码映射，
+        //   换业务本体时只改 ontology.ts 就够了（曾经页面里有一份 TITLE_FIELD，
+        //   换成请销假本体后编辑节点会发空 payload，报"没有可更新的字段"）。
+        titleField: e.titleField,
+      })),
+  });
+});
+
+/* ------------------------------ 内部工具 ------------------------------ */
+
+function subOf(def: (typeof ONTOLOGY.entities)[number], row: Record<string, unknown>): string {
+  return (def.subtitleFields ?? [])
+    .map((f) => String(row[f] ?? ''))
+    .filter(Boolean)
+    .slice(0, 2)
+    .join(' · ');
+}
+
+function delegateFor(model: string) {
+  const d = (prisma as unknown as Record<string, unknown>)[model];
+  if (!d || typeof (d as { findMany?: unknown }).findMany !== 'function') {
+    throw new BizError(`ontology.ts 里的模型 ${model} 不存在，请检查 Prisma 模型名`, CODE.BAD_REQUEST);
+  }
+  return d as {
+    findMany: (a: unknown) => Promise<Record<string, unknown>[]>;
+    findUnique: (a: unknown) => Promise<Record<string, unknown> | null>;
+    findFirst: (a: unknown) => Promise<Record<string, unknown> | null>;
+  };
+}
+
+async function rowsOf(model: string, take: number, user: SessionUser) {
+  return delegateFor(model).findMany({
+    where: graphWhereOf(model, user),
+    take,
+    orderBy: { id: 'asc' },
+  });
+}
+
+async function rowOf(model: string, id: string, user: SessionUser) {
+  // findFirst 而不是 findUnique：where 里要带范围；范围外 / 已软删的节点就是「不存在」
+  return delegateFor(model).findFirst({
+    where: { ...graphWhereOf(model, user), id },
+  });
+}
+
+/** 找出与 cur 相邻的所有节点（含关系方向处理） */
+async function neighborsOf(
+  cur: { entity: string; id: string },
+  rel: (typeof ONTOLOGY.relations)[number],
+  user: SessionUser
+): Promise<{ entity: string; id: string; label: string; subtitle: string }[]> {
+  const out: { entity: string; id: string; label: string; subtitle: string }[] = [];
+
+  if ('field' in rel.via) {
+    // 外键关系：查起点的行，拿外键值，再去终点表取那一行
+    const fromDef = ONTOLOGY.entities.find((e) => e.id === rel.from)!;
+    const toDef = ONTOLOGY.entities.find((e) => e.id === rel.to)!;
+
+    if (cur.entity === rel.from) {
+      const row = await rowOf(fromDef.model, cur.id, user);
+      const fk = row?.[rel.via.field];
+      if (fk) {
+        const target = await rowOf(toDef.model, String(fk), user);
+        if (target) {
+          out.push({
+            entity: rel.to,
+            id: String(target.id),
+            label: String(target[toDef.titleField] ?? target.id),
+            subtitle: subOf(toDef, target),
+          });
+        }
+      }
+    } else if (cur.entity === rel.to) {
+      // 反向：谁的外键指向我
+      const rows = await delegateFor(fromDef.model).findMany({
+        where: { [rel.via.field]: cur.id, ...graphWhereOf(fromDef.model, user) },
+        take: 30,
+      });
+      for (const r of rows) {
+        out.push({
+          entity: rel.from,
+          id: String(r.id),
+          label: String(r[fromDef.titleField] ?? r.id),
+          subtitle: subOf(fromDef, r),
+        });
+      }
+    }
+  } else {
+    // 中间表：model.fromField -> cur.id，取 toField
+    const toDef = ONTOLOGY.entities.find((e) => e.id === rel.to)!;
+    const fromDef = ONTOLOGY.entities.find((e) => e.id === rel.from)!;
+    const key = cur.entity === rel.from ? rel.via.fromField : rel.via.toField;
+    const otherEntity = cur.entity === rel.from ? rel.to : rel.from;
+    const otherDef = cur.entity === rel.from ? toDef : fromDef;
+    const otherField = cur.entity === rel.from ? rel.via.toField : rel.via.fromField;
+
+    const mids = await delegateFor(rel.via.model).findMany({
+      where: { [key]: cur.id, ...graphWhereOf(rel.via.model, user) },
+      take: 50,
+    });
+    for (const m of mids) {
+      const other = await rowOf(otherDef.model, String(m[otherField]), user);
+      if (other) {
+        out.push({
+          entity: otherEntity,
+          id: String(other.id),
+          label: String(other[otherDef.titleField] ?? other.id),
+          subtitle: subOf(otherDef, other),
+        });
+      }
+    }
+  }
+  return out;
+}

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

@@ -0,0 +1,11 @@
+import { NextResponse } from 'next/server';
+
+export const dynamic = 'force-dynamic';
+
+export function GET() {
+  return NextResponse.json({
+    ok: true,
+    runtime: process.version,
+    time: new Date().toISOString(),
+  });
+}

package/resources/src/app/api/inbox/read/route.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { ok, withRoute } from '@/lib/api';
+import { requireUser } from '@/auth';
+import { markAllNotificationsRead, markNotificationRead } from '@/lib/notifications';
+
+export const dynamic = 'force-dynamic';
+
+const schema = z
+  .object({
+    /** 单条消息 id */
+    id: z.string().trim().min(1).optional(),
+    /** 全部标为已读 */
+    all: z.boolean().optional(),
+  })
+  .refine((body) => body.all === true || Boolean(body.id), {
+    message: '缺少 id 或 all',
+  });
+
+/**
+ * POST /api/inbox/read   { id } | { all: true }
+ *
+ * 只能操作当前登录用户自己的消息：where 里同时带 userId 和 id，
+ * 传别人的消息 id 不会生效，也不会泄露该消息是否存在。
+ */
+export const POST = withRoute(async (req) => {
+  const user = await requireUser();
+  const body = schema.parse(await req.json().catch(() => ({})));
+
+  if (body.all) {
+    await markAllNotificationsRead(user.id);
+    return ok({ unread: 0, all: true });
+  }
+
+  const unread = await markNotificationRead(user.id, body.id as string);
+  return ok({ id: body.id, unread });
+});

package/resources/src/app/api/inbox/summary/route.ts

@@ -0,0 +1,15 @@
+import { ok, withRoute } from '@/lib/api';
+import { requireUser } from '@/auth';
+import { getInboxSummary } from '@/lib/inbox';
+
+export const dynamic = 'force-dynamic';
+
+/**
+ * GET /api/inbox/summary
+ *
+ * 顶栏铃铛的轻量摘要。只返回三个数字，不拉待办和消息明细。
+ */
+export const GET = withRoute(async () => {
+  const user = await requireUser();
+  return ok(await getInboxSummary(user));
+});