node-resource-utils 0.0.0-stage → 1.1.8

package/resources/src/lib/graph-focus.ts

@@ -0,0 +1,301 @@
+import { prisma } from '@/lib/prisma';
+import ONTOLOGY, { type EntityDef, type RelationDef } from '@/lib/ontology';
+import { hasSoftDelete } from '@/lib/graph-schema';
+/**
+ * 「业务表 ↔ 知识图谱」的关联推导（全站通用）。
+ *
+ * 背景：业务列表页（员工、账号、订单……）每行都要能跳进图谱，而且跳法要分两种：
+ *   - 这条记录在图上只有 1 个节点          → 直接定位到该节点、打开详情面板
+ *   - 这条记录牵着好几个实体（人 + 项目 + 部门）→ 跳过去并高亮这一簇节点之间的连接线
+ *
+ * ★ 为什么不把"关联谁"写死在页面里
+ *   写死的话，每加一个业务模块就要改一次页面、改一次图谱页，
+ *   而且两边一旦不一致，就会出现"点了关联跳到一张空图"。
+ *   这里全部由 ontology.ts 推导：
+ *
+ *     1. 模型名 → 本体 id（entities[].model）
+ *     2. 从该节点沿 relations 走，**只往 layer 更小的方向**（业务单据 → 组织/人员/字典）
+ *     3. 最多两跳（订单 → 客户 → 部门），且不回头，所以不会把
+ *        "同一个客户的其它 30 条订单"顺着反向关系全拉进来
+ *     4. 走到 1 个节点 = single，多个 = multi
+ *
+ *   新增业务模块时只要在 ontology.ts 里给它 layer 和关系，这里一行都不用改。
+ */
+
+export interface FocusNode {
+  /** 图内唯一键 `entity:dbId`（和 /api/graph 下发的节点 id 完全一致） */
+  id: string;
+  dbId: string;
+  entity: string;
+  entityLabel: string;
+  label: string;
+  subtitle: string;
+  /** 该节点在关联里的角色，如"客户" */
+  role: string;
+}
+
+export interface FocusEdge {
+  source: string;
+  target: string;
+  label: string;
+  relation: string;
+}
+
+export interface FocusResult {
+  source: { model: string; dbId: string };
+  entity: { id: string; label: string };
+  /** 源记录在图上的标题（节点标签） */
+  title: string;
+  view: { id: string; label: string };
+  /** single：只有一个节点 → 打开详情；multi：多个节点 → 高亮连接线 */
+  mode: 'single' | 'multi';
+  /** `entity:dbId`，有它就能让 /api/graph?center= 只展开这一片 */
+  center: string;
+  nodes: FocusNode[];
+  edges: FocusEdge[];
+  /** 反向链接：回到这条记录所在的业务页面（ontology 里 entity.link 推导） */
+  backLink: string | null;
+  /** 一句话说明这行数据在图谱里连着什么（页面横幅直接显示） */
+  summary: string;
+}
+
+const MAX_FOCUS_NODES = 12;
+
+/* ------------------------------ 本体解析 ------------------------------ */
+
+export function entityOfModel(model: string): EntityDef | null {
+  return ONTOLOGY.entities.find((e) => e.model === model) ?? null;
+}
+
+export function entityById(id: string): EntityDef | null {
+  return ONTOLOGY.entities.find((e) => e.id === id) ?? null;
+}
+
+function layerOf(entityId: string): number {
+  const i = ONTOLOGY.entities.findIndex((e) => e.id === entityId);
+  return ONTOLOGY.entities[i]?.layer ?? i;
+}
+
+function defOf(entityId: string): EntityDef {
+  const e = ONTOLOGY.entities.find((x) => x.id === entityId);
+  if (!e) throw new Error(`本体 ${entityId} 未在 ontology.ts 中声明`);
+  return e;
+}
+
+/* ------------------------------ 取数工具 ------------------------------ */
+
+type Row = Record<string, unknown>;
+
+function delegateFor(model: string) {
+  const d = (prisma as unknown as Record<string, unknown>)[model] as
+    | {
+        findUnique?: (a: unknown) => Promise<Row | null>;
+        findMany?: (a: unknown) => Promise<Row[]>;
+      }
+    | undefined;
+  if (!d?.findUnique) throw new Error(`模型 ${model} 不存在（检查 ontology.ts 里的 model 名）`);
+  return d as {
+    findUnique: (a: unknown) => Promise<Row | null>;
+    findMany: (a: unknown) => Promise<Row[]>;
+  };
+}
+
+function liveWhere(model: string): Row {
+  return hasSoftDelete(model) ? { deletedAt: null } : {};
+}
+
+async function rowOf(model: string, id: string): Promise<Row | null> {
+  const row = await delegateFor(model).findUnique({ where: { id } });
+  if (!row) return null;
+  if (hasSoftDelete(model) && row.deletedAt) return null;
+  return row;
+}
+
+function subOf(def: EntityDef, row: Row): string {
+  return (def.subtitleFields ?? [])
+    .map((f) => String(row[f] ?? ''))
+    .filter(Boolean)
+    .slice(0, 2)
+    .join(' · ');
+}
+
+/** 与 /api/graph 完全一致的邻居取法（外键 / 中间表，两个方向都认） */
+async function neighborsOf(
+  cur: { entity: string; id: string },
+  rel: RelationDef
+): 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 = defOf(rel.from);
+    const toDef = defOf(rel.to);
+
+    if (cur.entity === rel.from) {
+      const row = await rowOf(fromDef.model, cur.id);
+      const fk = row?.[rel.via.field];
+      if (fk) {
+        const target = await rowOf(toDef.model, String(fk));
+        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, ...liveWhere(fromDef.model) },
+        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 {
+    const key = cur.entity === rel.from ? rel.via.fromField : rel.via.toField;
+    const otherEntity = cur.entity === rel.from ? rel.to : rel.from;
+    const otherDef = defOf(otherEntity);
+    const otherField = cur.entity === rel.from ? rel.via.toField : rel.via.fromField;
+
+    const mids = await delegateFor(rel.via.model).findMany({
+      where: { [key]: cur.id, ...liveWhere(rel.via.model) },
+      take: 50,
+    });
+    for (const m of mids) {
+      const other = await rowOf(otherDef.model, String(m[otherField]));
+      if (other) {
+        out.push({
+          entity: otherEntity,
+          id: String(other.id),
+          label: String(other[otherDef.titleField] ?? other.id),
+          subtitle: subOf(otherDef, other),
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/* ------------------------------ 主流程 ------------------------------ */
+
+/**
+ * 求一条业务记录在图谱里的"关联簇"。
+ *
+ * @param model    Prisma 模型名（业务页面只需要知道自己的模型名）
+ * @param dbId     记录主键
+ * @param maxHops  往上游最多走几跳（默认 2：订单 → 客户 → 部门）
+ */
+export async function focusOf(
+  model: string,
+  dbId: string,
+  maxHops = 2
+): Promise<FocusResult | null> {
+  const ent = entityOfModel(model);
+  if (!ent) return null;
+
+  const row = await rowOf(ent.model, dbId);
+  if (!row) return null;
+
+  const sourceKey = `${ent.id}:${dbId}`;
+  const nodes = new Map<string, FocusNode>();
+  const edges: FocusEdge[] = [];
+  const edgeKeys = new Set<string>();
+
+  const title = String(row[ent.titleField] ?? dbId);
+  nodes.set(sourceKey, {
+    id: sourceKey,
+    dbId,
+    entity: ent.id,
+    entityLabel: ent.label,
+    label: title,
+    subtitle: subOf(ent, row),
+    role: ent.label,
+  });
+
+  const addEdge = (a: string, b: string, label: string, relation: string) => {
+    if (a === b) return;
+    const [lo, hi] = a < b ? [a, b] : [b, a];
+    const k = `${relation}|${lo}|${hi}`;
+    if (edgeKeys.has(k)) return;
+    edgeKeys.add(k);
+    edges.push({ source: a, target: b, label, relation });
+  };
+
+  let frontier: { entity: string; id: string }[] = [{ entity: ent.id, id: dbId }];
+
+  for (let hop = 0; hop < maxHops && frontier.length; hop += 1) {
+    const next: { entity: string; id: string }[] = [];
+    for (const cur of frontier) {
+      const curKey = `${cur.entity}:${cur.id}`;
+      const curLayer = layerOf(cur.entity);
+      for (const rel of ONTOLOGY.relations) {
+        if (rel.from !== cur.entity && rel.to !== cur.entity) continue;
+        const nbs = await neighborsOf(cur, rel);
+        for (const nb of nbs) {
+          // ★ 只往 layer 更小的方向走：业务单据 → 人员/项目 → 部门。
+          //   反过来走会把"同一个客户的其它订单""同一部门的其它订单"全拉进来，
+          //   高亮就从"一簇"变成"一大片"，反而看不出关联。
+          if (layerOf(nb.entity) >= curLayer) continue;
+          const nbKey = `${nb.entity}:${nb.id}`;
+          if (!nodes.has(nbKey)) {
+            if (nodes.size >= MAX_FOCUS_NODES) continue;
+            const def = defOf(nb.entity);
+            nodes.set(nbKey, {
+              id: nbKey,
+              dbId: nb.id,
+              entity: nb.entity,
+              entityLabel: def.label,
+              label: nb.label,
+              subtitle: nb.subtitle,
+              role: def.label,
+            });
+            next.push({ entity: nb.entity, id: nb.id });
+          }
+          addEdge(curKey, nbKey, rel.label, rel.id);
+        }
+      }
+    }
+    frontier = next;
+  }
+
+  // 视图：优先选"能覆盖最多已收集实体"的那个
+  const inView = (viewId: string) =>
+    ONTOLOGY.views.find((v) => v.id === viewId)?.entities ?? [];
+  const candidates = ONTOLOGY.views.filter((v) => inView(v.id).includes(ent.id));
+  const view =
+    candidates.sort(
+      (a, b) =>
+        Array.from(nodes.values()).filter((n) => b.entities.includes(n.entity)).length -
+        Array.from(nodes.values()).filter((n) => a.entities.includes(n.entity)).length
+    )[0] ?? ONTOLOGY.views[0];
+
+  const multi = nodes.size > 1;
+  const list = Array.from(nodes.values());
+  const others = list.filter((n) => n.id !== sourceKey);
+
+  const summary = multi
+    ? `「${title}」在图谱中关联 ${list.length} 个实体：${list
+        .map((n) => `${n.label}（${n.role}）`)
+        .join('、')}`
+    : `「${title}」在图谱中只有 1 个节点，已直接定位到节点详情`;
+
+  return {
+    source: { model: ent.model, dbId },
+    entity: { id: ent.id, label: ent.label },
+    title,
+    view: { id: view?.id ?? ONTOLOGY.views[0]?.id ?? '', label: view?.label ?? '关系图' },
+    mode: multi ? 'multi' : 'single',
+    center: sourceKey,
+    nodes: list,
+    edges,
+    backLink: ent.link ? ent.link.replace(':id', dbId) : null,
+    summary: others.length ? summary : `${summary}`,
+  };
+}

package/resources/src/lib/graph-link.ts

@@ -0,0 +1,17 @@
+/**
+ * 业务表 → 知识图谱的链接工具（**纯函数，可被客户端组件引用**）。
+ *
+ * ★ 为什么单独一个文件：
+ *   推导关联簇要查库（prisma + node:fs 读 schema），只能在服务端跑；
+ *   而列表页的「关联」按钮只需要拼一个 URL。
+ *   两者放同一个模块时，客户端组件 import 一下就会把 prisma 打进浏览器包，
+ *   页面直接 500：Module build failed: Reading from "node:fs" is not handled by plugins。
+ *   所以：**URL 拼装留在这里，查库的留 graph-focus.ts**。
+ */
+
+/** 业务页面用的跳转地址：页面只需要传模型名 + 记录 id */
+export function graphHref(model: string, dbId: string, view?: string) {
+  const qs = new URLSearchParams({ src: `${model}:${dbId}` });
+  if (view) qs.set('view', view);
+  return `/graph?${qs.toString()}`;
+}

package/resources/src/lib/graph-node-write.ts

@@ -0,0 +1,150 @@
+import { BizError, CODE } from '@/lib/api';
+import { prisma } from '@/lib/prisma';
+import ONTOLOGY from '@/lib/ontology';
+import { deleteWithCleanup } from '@/lib/graph-cascade';
+import { coercePayload, fillRequired, sharedFields } from '@/lib/graph-schema';
+import { hasPerm, PERM_SUPER, type ScopeUser } from '@/lib/rbac';
+
+/**
+ * 图谱直接写库只对超管开放。
+ *
+ * 业务数据的增删改必须走各自模块的接口 —— 那里才有业务权限码和数据范围校验。
+ * 否则任何登录用户都能绕过模块权限，用图谱接口改/删别人部门的单据，
+ * 前面在列表、导出、AI 工具上做的行级过滤就白做了。
+ * 三个写接口（node 的 POST/PATCH/DELETE、node/move）共用这一个判断。
+ */
+export function requireGraphWriter(user: ScopeUser) {
+  if (!hasPerm(user, PERM_SUPER)) {
+    throw new BizError(
+      '图谱直接写库仅限超级管理员；业务数据请走对应模块的编辑入口',
+      CODE.FORBIDDEN,
+      403
+    );
+  }
+}
+
+/**
+ * 图谱节点的"重"写操作。
+ *
+ * 放在 lib 里而不是 route 里，有两个原因：
+ *   1. Next.js 的 route.ts 只允许导出 HTTP 方法，多导出一个函数会在 build 时报
+ *      "does not match the required types of a Next.js Route"；
+ *   2. 「变更类型」不是一次 update —— 是"在目标本体建新记录 + 清掉旧记录"，
+ *      需要事务式的补偿逻辑，塞在接口里会很难读。
+ */
+
+export type Delegate = {
+  create: (a: unknown) => Promise<Record<string, unknown>>;
+  update: (a: unknown) => Promise<Record<string, unknown>>;
+  delete: (a: unknown) => Promise<Record<string, unknown>>;
+  findUnique: (a: unknown) => Promise<Record<string, unknown> | null>;
+  findFirst?: (a: unknown) => Promise<Record<string, unknown> | null>;
+  count?: (a: unknown) => Promise<number>;
+};
+
+export function delegateFor(model: string): Delegate {
+  const d = (prisma as unknown as Record<string, unknown>)[model];
+  if (!d || typeof (d as { create?: unknown }).create !== 'function') {
+    throw new BizError(`模型 ${model} 不存在，请检查 ontology.ts`, CODE.BAD_REQUEST);
+  }
+  return d as Delegate;
+}
+
+/** 把 Prisma 的错误码翻译成用户能看懂的话（否则前端只能看到 500） */
+export function translatePrismaError(e: unknown): never {
+  const code = (e as { code?: string })?.code;
+  if (code === 'P2003') {
+    throw new BizError(
+      '该节点仍被其他数据引用（例如部门下还有员工、角色还绑定着用户）。请先解除关联再操作。',
+      CODE.CONFLICT
+    );
+  }
+  if (code === 'P2002') {
+    throw new BizError('字段值重复（唯一约束冲突），换个名称/编码再试', CODE.CONFLICT);
+  }
+  if (code === 'P2025') {
+    throw new BizError('节点不存在或已被删除', CODE.NOT_FOUND, 404);
+  }
+  throw e;
+}
+
+function entityOf(id: string) {
+  const e = ONTOLOGY.entities.find((x) => x.id === id);
+  if (!e) {
+    throw new BizError(
+      `${id} 不是已声明的本体。可用：${ONTOLOGY.entities.map((x) => x.id).join(', ')}`,
+      CODE.BAD_REQUEST
+    );
+  }
+  return e;
+}
+
+/**
+ * 变更节点类型（迁移本体）。
+ *
+ * 语义说清楚：节点不是"换了个标签"，而是**换了张表**。
+ * 所以做法是：目标本体建一条新记录（同名字段自动带过去）→ 按级联规则清掉旧记录。
+ * 旧记录被清掉时同样会置空可选外键、连带删除必填外键的依赖行，
+ * 前端必须先展示影响清单再让用户确认。
+ *
+ * 补偿：新记录建好、旧记录清理失败时，把新记录删掉再抛错，
+ * 避免留下一个"迁移了一半"的孤儿节点。
+ */
+export async function moveNode(params: {
+  fromEntity: string;
+  id: string;
+  toEntity: string;
+  data?: Record<string, unknown>;
+}) {
+  const from = entityOf(params.fromEntity);
+  const to = entityOf(params.toEntity);
+  if (from.id === to.id || from.model === to.model) {
+    throw new BizError('目标类型与当前类型相同，不需要变更', CODE.BAD_REQUEST);
+  }
+
+  const src = await delegateFor(from.model).findUnique({ where: { id: params.id } });
+  if (!src) throw new BizError('节点不存在或已被删除', CODE.NOT_FOUND, 404);
+
+  // 1) 同名字段直接继承（唯一列不继承，否则必然撞唯一约束）
+  const shared = sharedFields(from.model, to.model);
+  const payload: Record<string, unknown> = {};
+  for (const name of shared) {
+    const v = src[name];
+    if (v !== undefined && v !== null) payload[name] = v;
+  }
+
+  // 2) 用户刚在面板里改过的值覆盖上去（只保留目标模型认识的字段）
+  Object.assign(payload, coercePayload(to.model, params.data ?? {}));
+
+  // 3) 目标本体的必填字段兜底
+  await fillRequired(to.model, payload);
+
+  let created: Record<string, unknown>;
+  try {
+    created = await delegateFor(to.model).create({ data: payload });
+  } catch (e) {
+    translatePrismaError(e);
+  }
+
+  // 4) 清掉旧记录（软删模型只置 deletedAt，引用不断）
+  let cleanup;
+  try {
+    cleanup = await deleteWithCleanup(from.id, params.id);
+  } catch (e) {
+    try {
+      await delegateFor(to.model).delete({ where: { id: created.id } });
+    } catch {
+      // 补偿失败就算了，至少把原始错误抛给用户
+    }
+    translatePrismaError(e);
+  }
+
+  return {
+    id: String(created.id),
+    entity: to.id,
+    model: to.model,
+    from: { entity: from.id, model: from.model },
+    inherited: shared,
+    cleanup,
+  };
+}