@goplusvn/core 0.1.48 → 0.1.49

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goplusvn/core",
   "description": "GoPlusVN Platform Kit - ERP kernel: layout, RBAC, CRUD, multi-tenant, system pages",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/crud/__tests__/filter-tree.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+
+import { compileFilterTree } from "../lib/filter-tree";
+
+const allowAll = { isAllowed: () => true };
+
+describe("compileFilterTree", () => {
+  it("leaf đơn → điều kiện Prisma", () => {
+    expect(
+      compileFilterTree(
+        { field: "status", operator: "eq", value: "paid" },
+        allowAll,
+      ),
+    ).toEqual({ status: "paid" });
+  });
+
+  it("khoảng gte+lte CÙNG field không đè nhau (điểm yếu của filter phẳng)", () => {
+    expect(
+      compileFilterTree(
+        {
+          $and: [
+            { field: "total", operator: "gte", value: 1000 },
+            { field: "total", operator: "lte", value: 5000 },
+          ],
+        },
+        allowAll,
+      ),
+    ).toEqual({
+      AND: [{ total: { gte: 1000 } }, { total: { lte: 5000 } }],
+    });
+  });
+
+  it("$or lồng trong $and + dotted relation path", () => {
+    expect(
+      compileFilterTree(
+        {
+          $and: [
+            { field: "branchId", operator: "eq", value: "b1" },
+            {
+              $or: [
+                { field: "status", operator: "eq", value: "paid" },
+                { field: "customer.name", operator: "contains", value: "an" },
+              ],
+            },
+          ],
+        },
+        allowAll,
+      ),
+    ).toEqual({
+      AND: [
+        { branchId: "b1" },
+        {
+          OR: [
+            { status: "paid" },
+            { customer: { name: { contains: "an", mode: "insensitive" } } },
+          ],
+        },
+      ],
+    });
+  });
+
+  it("field bị cấm → bỏ leaf + báo onDisallowed, phần còn lại giữ nguyên", () => {
+    const disallowed: string[] = [];
+    const where = compileFilterTree(
+      {
+        $and: [
+          { field: "secretCost", operator: "gt", value: 0 },
+          { field: "status", operator: "eq", value: "paid" },
+        ],
+      },
+      {
+        isAllowed: (f) => f !== "secretCost",
+        onDisallowed: (f) => disallowed.push(f),
+      },
+    );
+    expect(where).toEqual({ status: "paid" });
+    expect(disallowed).toEqual(["secretCost"]);
+  });
+
+  it("value rỗng → bỏ leaf; isNull/isNotNull không cần value", () => {
+    expect(
+      compileFilterTree({ field: "status", operator: "eq", value: "" }, allowAll),
+    ).toBeNull();
+    expect(
+      compileFilterTree({ field: "deletedAt", operator: "isNull" }, allowAll),
+    ).toEqual({ deletedAt: null });
+    expect(
+      compileFilterTree({ field: "email", operator: "isNotNull" }, allowAll),
+    ).toEqual({ email: { not: null } });
+  });
+
+  it("nhóm 1 phần tử được rút gọn, nhóm rỗng → null", () => {
+    expect(
+      compileFilterTree(
+        { $or: [{ field: "status", operator: "eq", value: "paid" }] },
+        allowAll,
+      ),
+    ).toEqual({ status: "paid" });
+    expect(compileFilterTree({ $and: [] }, allowAll)).toBeNull();
+  });
+
+  it("chặn cây quá sâu và quá nhiều điều kiện", () => {
+    let node: Record<string, unknown> = {
+      field: "a",
+      operator: "eq",
+      value: 1,
+    };
+    for (let i = 0; i < 6; i++) node = { $and: [node] };
+    expect(() => compileFilterTree(node, allowAll)).toThrow(/độ sâu/);
+
+    const leaves = Array.from({ length: 31 }, (_, i) => ({
+      field: `f${i}`,
+      operator: "eq",
+      value: i,
+    }));
+    expect(() => compileFilterTree({ $and: leaves }, allowAll)).toThrow(/điều kiện/);
+  });
+
+  it("cấu trúc sai → throw (route trả 4xx, không âm thầm bỏ lọc)", () => {
+    expect(() => compileFilterTree("x", allowAll)).toThrow();
+    expect(() => compileFilterTree({ $and: "x" }, allowAll)).toThrow();
+    expect(() => compileFilterTree({ operator: "eq" }, allowAll)).toThrow();
+  });
+});

package/src/crud/lib/filter-tree.ts

@@ -0,0 +1,150 @@
+/**
+ * Filter tree DSL → Prisma where.
+ *
+ * Bổ khuyết cho filter phẳng `ActiveFilter[]` của list(): phẳng chỉ AND ngầm
+ * và hai điều kiện cùng field ĐÈ nhau (không diễn đạt được khoảng gte+lte hay
+ * nhóm OR). Tree cho phép:
+ *
+ *   { $and: [ { field: "total", operator: "gte", value: 1e6 },
+ *             { field: "total", operator: "lte", value: 5e6 },
+ *             { $or: [ { field: "status", operator: "eq", value: "paid" },
+ *                      { field: "customer.name", operator: "contains", value: "an" } ] } ] }
+ *
+ * An toàn: mọi leaf đi qua CÙNG guard `isAllowed` với filter phẳng (field
+ * ngoài config bị bỏ + cảnh báo); chặn sâu (depth) và số leaf để không nhận
+ * cây tuỳ ý từ client.
+ */
+
+export interface FilterTreeLeaf {
+  field: string;
+  operator: string;
+  value?: unknown;
+}
+
+export type FilterTreeNode =
+  | { $and: FilterTreeNode[] }
+  | { $or: FilterTreeNode[] }
+  | FilterTreeLeaf;
+
+const MAX_DEPTH = 4;
+const MAX_LEAVES = 30;
+
+/** Điều kiện Prisma cho một toán tử — dùng chung với filter phẳng. */
+export function conditionForOperator(op: string, value: unknown): unknown {
+  switch (op) {
+    case "contains":
+      return { contains: value, mode: "insensitive" };
+    case "in":
+      return { in: value };
+    case "notIn":
+      return { notIn: value };
+    case "eq":
+      return value;
+    case "ne":
+      return { not: value };
+    case "gt":
+      return { gt: value };
+    case "gte":
+      return { gte: value };
+    case "lt":
+      return { lt: value };
+    case "lte":
+      return { lte: value };
+    case "startsWith":
+      return { startsWith: value, mode: "insensitive" };
+    case "endsWith":
+      return { endsWith: value, mode: "insensitive" };
+    case "isNull":
+      return null;
+    case "isNotNull":
+      return { not: null };
+    default:
+      return value;
+  }
+}
+
+/** isNull/isNotNull không cần value — mọi toán tử khác value rỗng là bỏ leaf. */
+const VALUELESS_OPS = new Set(["isNull", "isNotNull"]);
+
+export interface CompileFilterTreeOptions {
+  /** Cùng guard với filter phẳng: field/relation phải nằm trong entity config. */
+  isAllowed: (name: string) => boolean;
+  /** Gọi khi một leaf bị bỏ (field cấm) — để log cảnh báo. */
+  onDisallowed?: (field: string) => void;
+}
+
+/**
+ * Compile tree → Prisma where. Trả `null` khi cây rỗng/không còn leaf hợp lệ
+ * (caller bỏ qua). Throw khi cây sai cấu trúc hoặc vượt giới hạn — route trả
+ * 400 cho client sửa, không âm thầm nuốt.
+ */
+export function compileFilterTree(
+  node: unknown,
+  options: CompileFilterTreeOptions,
+): Record<string, unknown> | null {
+  const budget = { leaves: 0 };
+  return compileNode(node, options, 0, budget);
+}
+
+function compileNode(
+  node: unknown,
+  options: CompileFilterTreeOptions,
+  depth: number,
+  budget: { leaves: number },
+): Record<string, unknown> | null {
+  if (node === null || node === undefined) return null;
+  if (typeof node !== "object" || Array.isArray(node)) {
+    throw new Error("filterTree: node phải là object");
+  }
+  if (depth > MAX_DEPTH) {
+    throw new Error(`filterTree: vượt độ sâu tối đa ${MAX_DEPTH}`);
+  }
+
+  const group = node as { $and?: unknown; $or?: unknown };
+  if (group.$and !== undefined || group.$or !== undefined) {
+    const isAnd = group.$and !== undefined;
+    const children = isAnd ? group.$and : group.$or;
+    if (!Array.isArray(children)) {
+      throw new Error(`filterTree: ${isAnd ? "$and" : "$or"} phải là mảng`);
+    }
+    const compiled = children
+      .map((child) => compileNode(child, options, depth + 1, budget))
+      .filter((c): c is Record<string, unknown> => c !== null);
+    if (compiled.length === 0) return null;
+    if (compiled.length === 1) return compiled[0];
+    return isAnd ? { AND: compiled } : { OR: compiled };
+  }
+
+  // Leaf
+  const leaf = node as FilterTreeLeaf;
+  if (typeof leaf.field !== "string" || typeof leaf.operator !== "string") {
+    throw new Error("filterTree: leaf cần { field, operator }");
+  }
+  if (++budget.leaves > MAX_LEAVES) {
+    throw new Error(`filterTree: vượt ${MAX_LEAVES} điều kiện`);
+  }
+
+  const { field, operator, value } = leaf;
+  if (
+    !VALUELESS_OPS.has(operator) &&
+    (value === undefined ||
+      value === null ||
+      value === "" ||
+      (Array.isArray(value) && value.length === 0))
+  ) {
+    return null;
+  }
+  if (!options.isAllowed(field)) {
+    options.onDisallowed?.(field);
+    return null;
+  }
+
+  const condition = conditionForOperator(operator, value);
+  // Dotted path → lồng theo relation: "customer.name" → { customer: { name: cond } }
+  const parts = field.split(".");
+  let out: Record<string, unknown> = { [parts.pop()!]: condition };
+  while (parts.length) {
+    out = { [parts.pop()!]: out };
+  }
+  return out;
+}

package/src/crud/server-service.ts

@@ -15,6 +15,7 @@
 //     getModelName: (e) => getModelName(e, MODEL_MAP),
 //   });
 
+import { compileFilterTree } from "./lib/filter-tree";
 import type { CrudQueryParams, CrudResponse, EntityConfig } from "../types";
 import { serializeDecimalFields } from "../utils/serialize";
 
@@ -260,6 +261,19 @@ export function createServerCrudService(deps: ServerCrudDeps): ServerCrudService
           else target[key] = value;
         }
       }
+      // Bộ lọc nâng cao dạng cây ($and/$or, nhiều điều kiện cùng field) —
+      // cùng guard isAllowed với filter phẳng; AND vào where (search dùng OR
+      // nên không đụng nhau). Cây sai cấu trúc → throw (route trả lỗi 4xx).
+      if (params.filterTree) {
+        const compiled = compileFilterTree(params.filterTree, {
+          isAllowed,
+          onDisallowed: (field) =>
+            log.warn(`Ignoring filterTree condition on disallowed field "${field}" for entity "${entity}"`),
+        });
+        if (compiled) {
+          where.AND = [...(Array.isArray(where.AND) ? where.AND : where.AND ? [where.AND] : []), compiled];
+        }
+      }
 
       const orderBy: any = {};
       const applySort = (field: string, direction: any) => {

package/src/crud/server.ts

@@ -24,3 +24,4 @@ export {
   createCrudItemHandlers,
 } from './crud-route-handlers'
 export type { CrudHandlerDeps } from './crud-route-handlers'
+export { compileFilterTree, conditionForOperator, type FilterTreeLeaf, type FilterTreeNode } from "./lib/filter-tree";

package/src/types/index.ts

@@ -621,6 +621,8 @@ export interface CrudQueryParams {
   search?: string;
   sort?: SortingState;
   filters?: ActiveFilter[];
+  /** Bộ lọc nâng cao dạng cây $and/$or — xem crud/lib/filter-tree. */
+  filterTree?: import("../crud/lib/filter-tree").FilterTreeNode;
 }
 
 export interface CrudResponse<T = unknown> {