node-resource-utils 0.0.0-stage → 1.1.7

package/resources/src/lib/formRules.ts

@@ -0,0 +1,76 @@
+import type { Rule } from 'antd/es/form';
+import {
+  fieldTypeLabel,
+  inferValidationType,
+  validateField,
+  type ValidationOptions,
+} from '@/lib/validation';
+
+/**
+ * 把校验底座接到 antd Form.Item 上。
+ *
+ * 用法：
+ *   <Form.Item name="phone" label="手机号"
+ *     rules={formRules('phone', { label: '手机号' })}>
+ *
+ * 字段类型推断得出来时也可以偷懒：
+ *   <Form.Item name="idCard" label="身份证号" rules={autoFormRules({ name: 'idCard', label: '身份证号' })}>
+ *
+ * 提示语由底座统一产出（「请输入姓名」「身份证号校验位不正确…」），
+ * 页面里不再散落正则和提示文案。
+ */
+
+export interface FormRuleOptions extends Omit<ValidationOptions, 'label'> {
+  /** 字段中文名 */
+  label?: string;
+  /** 字段名，用于自动推断（formRules 不需要，autoFormRules 使用） */
+  name?: string;
+  /** 追加到内置规则之后的规则 */
+  extra?: Rule[];
+}
+
+function labelOf(type: string, options: FormRuleOptions): string {
+  return options.label?.trim() || fieldTypeLabel(type);
+}
+
+/** 指定类型 → antd 规则 */
+export function formRules(type: string, options: FormRuleOptions = {}): Rule[] {
+  const label = labelOf(type, options);
+  const rules: Rule[] = [];
+
+  // required 规则让 Form.Item 自动显示红星；自定义 validator 负责格式与友好提示
+  if (options.required) {
+    rules.push({ required: true, whitespace: true, message: `请输入${label}` });
+  }
+
+  rules.push({
+    validator: (_rule, value) => {
+      const result = validateField(type, value, { ...options, label, required: options.required });
+      return result.ok ? Promise.resolve() : Promise.reject(new Error(result.message));
+    },
+  });
+
+  if (options.extra?.length) rules.push(...options.extra);
+  return rules;
+}
+
+export interface AutoFormRuleOptions extends FormRuleOptions {
+  name: string;
+  label: string;
+  /** 显式指定类型；不传则按 name/label 推断 */
+  type?: string;
+}
+
+/**
+ * 按字段名/标签自动选类型。
+ * 推断不出来时退化为「只做必填」——不拿一个错误的格式去拦正常输入。
+ */
+export function autoFormRules(options: AutoFormRuleOptions): Rule[] {
+  const type = options.type ?? inferValidationType(options.name, options.label);
+  if (!type) {
+    return options.required
+      ? [{ required: true, whitespace: true, message: `请输入${options.label}` }]
+      : [];
+  }
+  return formRules(type, options);
+}

package/resources/src/lib/format.ts

@@ -0,0 +1,52 @@
+import dayjs, { type Dayjs } from 'dayjs';
+
+/**
+ * 展示层格式化工具。
+ *
+ * 为什么要单独抽出来：表格 cell、详情页、导出都会用到同一套格式，
+ * 散落在各处会导致「同一个日期在一页显示成 2024-01-01，另一页显示成 2024/1/1」。
+ * 统一入口后，改格式只改一个地方。
+ *
+ * 空值一律返回 '-'：表格里 null 直接渲染会出现一片空白，视觉上分不清
+ * 「值为空」和「渲染出错」，给个占位符更利于排查。
+ */
+
+const EMPTY = '-';
+
+type DateInput = string | number | Date | Dayjs | null | undefined;
+
+function toDayjs(v: DateInput): Dayjs | null {
+  if (v === null || v === undefined || v === '') return null;
+  const d = dayjs(v);
+  return d.isValid() ? d : null;
+}
+
+/** 日期：2024-01-01 */
+export function fmtDate(v: DateInput, pattern = 'YYYY-MM-DD'): string {
+  return toDayjs(v)?.format(pattern) ?? EMPTY;
+}
+
+/** 日期时间：2024-01-01 12:30:00 */
+export function fmtDateTime(v: DateInput): string {
+  return fmtDate(v, 'YYYY-MM-DD HH:mm:ss');
+}
+
+/** 金额：¥12,345.00 */
+export function fmtMoney(v: number | string | null | undefined, prefix = '¥'): string {
+  if (v === null || v === undefined || v === '') return EMPTY;
+  const n = Number(v);
+  if (Number.isNaN(n)) return EMPTY;
+  return prefix + n.toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+/**
+ * 把表单/组件里的日期值转成接口参数用的字符串。
+ *
+ * 注意：这里空值返回空串而不是 '-'。
+ * '-' 是「给人看的占位符」，一旦被当作查询参数发到后端，
+ * `startDate=-` 会让 dayjs 解析出一个非法日期，反而制造 bug；
+ * 空串在 URL 里会被安全忽略。
+ */
+export function parseDateInput(v: DateInput, pattern = 'YYYY-MM-DD'): string {
+  return toDayjs(v)?.format(pattern) ?? '';
+}

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

@@ -0,0 +1,304 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { prisma } from '@/lib/prisma';
+import ONTOLOGY from '@/lib/ontology';
+
+/**
+ * 图谱节点删除的级联清理。
+ *
+ * 设计前提（业务方确认过）：
+ *   删一个节点**允许连带改动引用它的数据** —— 这是预期行为，不是 bug。
+ *   但必须满足两条：
+ *     1. 删之前能说清楚"会影响什么"（前端弹二次确认）；
+ *     2. 删之后**不能留下悬挂外键**（可选外键置空、必填外键连带删除）。
+ *
+ * 规则：
+ *   - 可选外键（`deptId String?`）→ 置 null（保留业务行，只解除关联）
+ *   - 必填外键（`userId String`）→ 连带删除依赖行，并递归处理它的依赖
+ *   - 自关联（如部门树 parentId）也是可选外键 → 下级提升为顶级，不删子树
+ *   - 模型有 deletedAt → 只软删目标行，不清理引用（行还在，引用不断）
+ *
+ * 整个清理在**一个事务**里做完，并在提交前复核"引用已归零"，
+ * 任何一步失败就整体回滚 —— 不会出现删了一半的中间状态。
+ */
+
+export type RefInfo = {
+  model: string;
+  field: string;
+  optional: boolean;
+  onDelete?: string;
+};
+
+export type ImpactAction = {
+  kind: 'delete' | 'nullify';
+  model: string;
+  label: string;
+  field: string;
+  count: number;
+};
+
+export type Impact = {
+  entity: string;
+  model: string;
+  title: string;
+  soft: boolean;
+  actions: ImpactAction[];
+  deleteCount: number;
+  nullifyCount: number;
+};
+
+let schemaCache: string | null | undefined;
+
+function schemaText(): string | null {
+  if (schemaCache === undefined) {
+    try {
+      schemaCache = readFileSync(join(process.cwd(), 'prisma', 'schema.prisma'), 'utf8');
+    } catch {
+      schemaCache = null;
+    }
+  }
+  return schemaCache;
+}
+
+/** 解析出所有模型的反向引用（谁的外键指向我） */
+let refCache: Map<string, RefInfo[]> | undefined;
+
+export function refsOf(targetModel: string): RefInfo[] {
+  if (!refCache) {
+    refCache = new Map();
+    const src = schemaText();
+    if (src) {
+      for (const block of src.matchAll(/model\s+(\w+)\s*\{([\s\S]*?)\n\}/g)) {
+        const [, model, body] = block;
+        for (const line of body.split('\n')) {
+          const m = line.match(
+            /^\s*\w+\s+([A-Za-z_]\w*)(\?)?\s+@relation\(([^)]*)\)/
+          );
+          if (!m) continue;
+          const [, type, opt, args] = m;
+          const fields = args.match(/fields:\s*\[(\w+)\]/);
+          const references = args.match(/references:\s*\[(\w+)\]/);
+          if (!fields || !references || references[1] !== 'id') continue;
+          const od = args.match(/onDelete:\s*(\w+)/);
+          const list = refCache.get(type) ?? [];
+          list.push({
+            model,
+            field: fields[1],
+            optional: !!opt,
+            onDelete: od?.[1],
+          });
+          refCache.set(type, list);
+        }
+      }
+    }
+  }
+  return refCache.get(targetModel) ?? [];
+}
+
+export function hasSoftDelete(model: string): boolean {
+  const src = schemaText();
+  if (!src) return false;
+  const block = src.match(new RegExp(`model\\s+${model}\\s*\\{([\\s\\S]*?)\\n\\}`));
+  return !!block && /\bdeletedAt\b/.test(block[1]);
+}
+
+type Delegate = {
+  findMany: (a: unknown) => Promise<Record<string, unknown>[]>;
+  findFirst: (a: unknown) => Promise<Record<string, unknown> | null>;
+  updateMany: (a: unknown) => Promise<{ count: number }>;
+  deleteMany: (a: unknown) => Promise<{ count: number }>;
+  delete: (a: unknown) => Promise<Record<string, unknown>>;
+  update: (a: unknown) => Promise<Record<string, unknown>>;
+  count: (a: unknown) => Promise<number>;
+};
+
+function delegateOf(client: unknown, model: string): Delegate {
+  const d = (client as Record<string, unknown>)[model];
+  if (!d || typeof (d as { findMany?: unknown }).findMany !== 'function') {
+    throw new Error(`模型 ${model} 不存在，请检查 ontology.ts / schema.prisma`);
+  }
+  return d as Delegate;
+}
+
+export function entityOf(entityId: string) {
+  const e = ONTOLOGY.entities.find((x) => x.id === entityId);
+  if (!e) throw new Error(`本体 ${entityId} 未在 ontology.ts 中声明`);
+  return e;
+}
+
+const MODEL_LABELS: Record<string, string> = {
+  User: '账号',
+  Department: '部门',
+  Employee: '员工',
+  Role: '角色',
+  Menu: '菜单',
+  UserRole: '用户角色关联',
+  RoleMenu: '角色菜单关联',
+  OperationLog: '操作日志',
+  Feedback: '反馈',
+};
+
+export function labelOfModel(model: string): string {
+  return ONTOLOGY.entities.find((e) => e.model === model)?.label ?? MODEL_LABELS[model] ?? model;
+}
+
+/** 模型有没有 id 主键（UserRole / RoleMenu 是 @@id 复合主键，没有 id 字段） */
+function hasIdField(model: string): boolean {
+  const src = schemaText();
+  if (!src) return true;
+  const block = src.match(new RegExp(`model\\s+${model}\\s*\\{([\\s\\S]*?)\\n\\}`));
+  if (!block) return true;
+  return /^\s*id\s+\w+/m.test(block[1]);
+}
+
+type PlannedDelete = { model: string; where: Record<string, unknown>; count: number };
+type PlannedNullify = { model: string; field: string; where: Record<string, unknown>; count: number };
+
+/**
+ * 规划清理动作（只读，不写库）。
+ * deletes 的顺序是"依赖先、被依赖后"，执行时直接按顺序删即可。
+ */
+async function plan(model: string, id: string) {
+  const deletes: PlannedDelete[] = [];
+  const nullifies: PlannedNullify[] = [];
+  const seen = new Set<string>();
+
+  async function walk(m: string, rowId: string, depth: number) {
+    if (depth > 5) return;
+    for (const ref of refsOf(m)) {
+      const where = { [ref.field]: rowId };
+      const rows = await delegateOf(prisma, ref.model).findMany({
+        where,
+        select: hasIdField(ref.model) ? { id: true } : { [ref.field]: true },
+      });
+      if (!rows.length) continue;
+
+      if (ref.optional) {
+        // 可选外键用条件更新（不依赖主键类型），把引用置空即可
+        nullifies.push({ model: ref.model, field: ref.field, where, count: rows.length });
+        continue;
+      }
+
+      // 复合主键的关联表（UserRole/RoleMenu）没有 id，也没有下级依赖，直接按条件删
+      if (!hasIdField(ref.model)) {
+        deletes.push({ model: ref.model, where, count: rows.length });
+        continue;
+      }
+
+      for (const r of rows) {
+        const rid = String(r.id);
+        const key = `${ref.model}:${rid}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        // 先处理它的依赖，再删它自己
+        await walk(ref.model, rid, depth + 1);
+        deletes.push({ model: ref.model, where: { id: rid }, count: 1 });
+      }
+    }
+  }
+
+  await walk(model, id, 0);
+  return { deletes, nullifies };
+}
+
+/** 汇总成"给人看"的列表（同一模型同一字段合并计数） */
+function summarize(model: string, deletes: PlannedDelete[], nullifies: PlannedNullify[]) {
+  const map = new Map<string, ImpactAction>();
+  const bump = (kind: 'delete' | 'nullify', m: string, field: string, n: number) => {
+    const key = `${kind}|${m}|${field}`;
+    const hit = map.get(key);
+    if (hit) hit.count += n;
+    else map.set(key, { kind, model: m, label: labelOfModel(m), field, count: n });
+  };
+
+  for (const n of nullifies) bump('nullify', n.model, n.field, n.count);
+  for (const d of deletes) bump('delete', d.model, '', d.count);
+  return [...map.values()].sort((a, b) => b.count - a.count);
+}
+
+/** 预览：这次删除会影响什么（不写库） */
+export async function impactOf(entityId: string, id: string): Promise<Impact> {
+  const ent = entityOf(entityId);
+  const soft = hasSoftDelete(ent.model);
+  const row = await delegateOf(prisma, ent.model).findFirst({ where: { id } });
+  const title = row ? String(row[ent.titleField] ?? id) : id;
+
+  if (soft) {
+    return {
+      entity: ent.id,
+      model: ent.model,
+      title,
+      soft: true,
+      actions: [],
+      deleteCount: 0,
+      nullifyCount: 0,
+    };
+  }
+
+  const { deletes, nullifies } = await plan(ent.model, id);
+  const actions = summarize(ent.model, deletes, nullifies);
+  return {
+    entity: ent.id,
+    model: ent.model,
+    title,
+    soft: false,
+    actions,
+    deleteCount: deletes.reduce((s, d) => s + d.count, 0),
+    nullifyCount: nullifies.reduce((s, n) => s + n.count, 0),
+  };
+}
+
+/**
+ * 执行删除 + 清理（单事务）。
+ *
+ * 提交前会复核：目标模型的每条反向引用都应归零，
+ * 否则抛错回滚 —— 保证"删改彻底、没有引用残留"。
+ */
+export async function deleteWithCleanup(entityId: string, id: string) {
+  const ent = entityOf(entityId);
+
+  if (hasSoftDelete(ent.model)) {
+    await delegateOf(prisma, ent.model).update({
+      where: { id },
+      data: { deletedAt: new Date() },
+    });
+    return { soft: true, deleted: 1, nullified: 0 };
+  }
+
+  const { deletes, nullifies } = await plan(ent.model, id);
+
+  const result = await prisma.$transaction(
+    async (tx) => {
+      let nullified = 0;
+      for (const n of nullifies) {
+        const r = await delegateOf(tx, n.model).updateMany({
+          where: n.where,
+          data: { [n.field]: null },
+        });
+        nullified += r.count;
+      }
+
+      let deleted = 0;
+      for (const d of deletes) {
+        const r = await delegateOf(tx, d.model).deleteMany({ where: d.where });
+        deleted += r.count;
+      }
+
+      await delegateOf(tx, ent.model).delete({ where: { id } });
+      deleted += 1;
+
+      // 复核：任何一条反向引用都不应再指向已删除的 id
+      for (const ref of refsOf(ent.model)) {
+        const left = await delegateOf(tx, ref.model).count({ where: { [ref.field]: id } });
+        if (left > 0) {
+          throw new Error(`清理不彻底：${ref.model}.${ref.field} 还有 ${left} 条引用`);
+        }
+      }
+
+      return { soft: false, deleted, nullified };
+    },
+    { timeout: 20000 }
+  );
+
+  return result;
+}