@goplusvn/core 0.1.48 → 0.1.50

package/bin/goerp-features.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// CLI `goerp-features` — đồng bộ feature CÓ BẢNG DB của @goerp/core vào app.
+//
+//   pnpm goerp-features status          # feature/bước nào còn thiếu
+//   pnpm goerp-features sync            # copy schema + materialize migrations
+//   pnpm goerp-features sync --only background-tasks
+//
+// Sau sync: chạy `pnpm prisma migrate deploy` (flow deploy hiện có) rồi
+// `pnpm prisma generate`. SQL của core viết IDEMPOTENT nên app đã có bảng
+// từ trước chạy lại vô hại.
+
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { featureStatus, syncFeatures } from "../scripts/feature-sync.mjs";
+
+const featuresRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "features");
+const appRoot = process.cwd();
+
+const [, , command = "status", ...rest] = process.argv;
+const onlyIdx = rest.indexOf("--only");
+const only = onlyIdx >= 0 ? rest.slice(onlyIdx + 1).filter((a) => !a.startsWith("-")) : undefined;
+
+if (command === "status") {
+  const statuses = featureStatus({ featuresRoot, appRoot });
+  if (statuses.length === 0) {
+    console.log("Không có feature nào trong @goerp/core/features.");
+    process.exit(0);
+  }
+  for (const f of statuses) {
+    const pending = f.steps.filter((s) => !s.materialized).length;
+    console.log(
+      `${pending === 0 && (!f.hasSchema || f.schemaSynced) ? "✓" : "•"} ${f.feature}` +
+        `  (schema: ${f.hasSchema ? (f.schemaSynced ? "đã sync" : "CHƯA sync") : "—"};` +
+        ` migrations: ${f.steps.length - pending}/${f.steps.length})`
+    );
+    for (const s of f.steps.filter((s) => !s.materialized)) {
+      console.log(`    ↳ thiếu bước ${s.num}_${s.slug}`);
+    }
+  }
+  process.exit(0);
+}
+
+if (command === "sync") {
+  const actions = syncFeatures({ featuresRoot, appRoot, only });
+  if (actions.length === 0) {
+    console.log("✓ Không có gì để sync — app đã đủ schema + migrations.");
+  } else {
+    for (const a of actions) {
+      if (a.type === "schema") console.log(`✓ schema  ${a.feature} → ${a.target}`);
+      else console.log(`✓ migrate ${a.feature} + ${a.step} → prisma/migrations/${a.dir}`);
+    }
+    console.log(
+      "\nTiếp theo: pnpm prisma migrate deploy && pnpm prisma generate"
+    );
+  }
+  process.exit(0);
+}
+
+console.error(`Lệnh không hợp lệ: ${command}. Dùng: status | sync [--only <feature>…]`);
+process.exit(1);

package/features/README.md

@@ -0,0 +1,33 @@
+# @goerp/core features — tính năng có bảng DB
+
+Mỗi thư mục con là một feature core ship kèm **bảng DB**. App tiêu thụ chạy:
+
+```bash
+pnpm goerp-features status   # xem thiếu gì
+pnpm goerp-features sync     # copy schema + materialize migrations
+pnpm prisma migrate deploy && pnpm prisma generate
+```
+
+`sync` copy `schema.prisma` → `prisma/schema/goerp-<feature>.prisma` (file
+GENERATED — đừng sửa tay) và tạo thư mục migration
+`<timestamp>_goerp_<feature>_<NNN>_<slug>/` cho bước nào app chưa có. App giữ
+**một** hệ migration duy nhất (`prisma migrate deploy`), không có DDL lúc boot.
+
+## Luật viết feature (tác giả core PHẢI theo)
+
+1. **SQL idempotent tuyệt đối** — `CREATE TABLE IF NOT EXISTS`,
+   `CREATE INDEX IF NOT EXISTS`, `ALTER TABLE … ADD COLUMN IF NOT EXISTS`.
+   Lý do: app từng tự tạo bảng bằng migration tay (vinhhoa) chạy lại phải vô hại.
+2. **Bước đã publish là BẤT BIẾN** — không sửa file `NNN_*.sql` cũ; đổi schema
+   thì thêm bước mới `NNN+1_*.sql` (và cập nhật `schema.prisma` fragment khớp).
+3. Tên bước: `NNN_slug.sql` (NNN ≥ 3 chữ số, slug kebab-case).
+4. `schema.prisma` fragment chỉ chứa model của feature này, dùng `@map`/`@@map`
+   snake_case như convention chung.
+5. Feature cần seed/RBAC: ghi rõ trong README của feature — seed chạy phía app
+   (Permission Registry của app là nguồn sự thật quyền).
+
+## Feature hiện có
+
+- `background-tasks` — bảng `background_tasks` cho trung tâm tác vụ nền
+  (export/import chạy nền). Runtime hiện ở app (vinhhoa `src/server/tasks`);
+  sẽ dời lên core ở đợt F1.

package/features/background-tasks/migrations/0001_init.sql

@@ -0,0 +1,23 @@
+-- goerp feature: background-tasks — bước 0001 (idempotent: app đã tự tạo bảng
+-- từ trước chạy lại vô hại; quy ước MỌI bước SQL của core đều IF NOT EXISTS).
+CREATE TABLE IF NOT EXISTS "background_tasks" (
+    "id" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "status" TEXT NOT NULL DEFAULT 'pending',
+    "progress" INTEGER NOT NULL DEFAULT 0,
+    "params" JSONB,
+    "result" JSONB,
+    "error" TEXT,
+    "created_by" TEXT NOT NULL,
+    "branch_id" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "started_at" TIMESTAMP(3),
+    "finished_at" TIMESTAMP(3),
+
+    CONSTRAINT "background_tasks_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "background_tasks_created_by_created_at_idx" ON "background_tasks"("created_by", "created_at");
+
+CREATE INDEX IF NOT EXISTS "background_tasks_status_idx" ON "background_tasks"("status");

package/features/background-tasks/schema.prisma

@@ -0,0 +1,22 @@
+// Tác vụ nền (export/import lớn…): hàng đợi trong DB, worker in-process.
+// status: pending → running → success | error.
+// result: { fileKey?, fileName?, rowCount?, errorFileKey?, summary? }.
+model BackgroundTask {
+  id         String    @id @default(cuid()) @map("id")
+  type       String    @map("type")
+  title      String    @map("title")
+  status     String    @default("pending") @map("status")
+  progress   Int       @default(0) @map("progress")
+  params     Json?     @map("params")
+  result     Json?     @map("result")
+  error      String?   @map("error")
+  createdBy  String    @map("created_by")
+  branchId   String?   @map("branch_id")
+  createdAt  DateTime  @default(now()) @map("created_at")
+  startedAt  DateTime? @map("started_at")
+  finishedAt DateTime? @map("finished_at")
+
+  @@index([createdBy, createdAt])
+  @@index([status])
+  @@map("background_tasks")
+}

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.50",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -11,8 +11,14 @@
   "module": "./src/index.ts",
   "types": "./src/index.ts",
   "sideEffects": false,
+  "bin": {
+    "goerp-features": "./bin/goerp-features.mjs"
+  },
   "files": [
     "src",
+    "bin",
+    "scripts",
+    "features",
     "README.md",
     "CHANGELOG.md",
     "PLATFORM.md"

package/scripts/feature-sync.mjs

@@ -0,0 +1,145 @@
+// Feature sync — bộ máy cho CLI `goerp-features` (bin/goerp-features.mjs).
+//
+// BÀI TOÁN: @goerp/core ship tính năng CÓ BẢNG DB (background-tasks,
+// notifications, error-logs…) qua npm; mỗi app tiêu thụ (vinhhoa, thingtodo,
+// app init mới) trước đây phải chép tay schema + migration → thiếu sót, lệch.
+//
+// THIẾT KẾ (chọn "materialize vào prisma/migrations của app" thay vì ledger
+// runtime kiểu NocoBase — không DDL lúc boot, app giữ MỘT hệ migration duy
+// nhất `prisma migrate deploy`):
+//   - Core ship mỗi feature tại features/<name>/:
+//       schema.prisma            — fragment model (copy vào schema dir của app)
+//       migrations/NNN_slug.sql  — bước SQL đánh số, PHẢI viết IDEMPOTENT
+//                                  (CREATE TABLE IF NOT EXISTS…) để app đã có
+//                                  bảng từ trước (vinhhoa) chạy lại vô hại.
+//   - `sync`: copy fragment → prisma/schema/goerp-<feature>.prisma (đè, có
+//     header GENERATED) + với mỗi bước CHƯA materialize, tạo thư mục
+//     <timestamp>_goerp_<feature>_<NNN>_<slug>/migration.sql. Nhận bước đã
+//     materialize bằng ĐUÔI TÊN (bỏ qua timestamp) nên chạy lại idempotent.
+//   - `status`: liệt kê feature/bước, cái nào pending.
+//
+// Logic thuần (fs qua tham số path) để unit-test được bằng vitest trên tmp dir.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** features/<name>/migrations/NNN_slug.sql → [{num, slug, file}] theo thứ tự. */
+export function listFeatureSteps(featureDir) {
+  const dir = join(featureDir, "migrations");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => /^\d{3,}_[a-z0-9-]+\.sql$/.test(f))
+    .sort()
+    .map((f) => {
+      const m = f.match(/^(\d{3,})_([a-z0-9-]+)\.sql$/);
+      return { num: m[1], slug: m[2], file: join(dir, f) };
+    });
+}
+
+/** Tên mọi feature trong thư mục features/ của core. */
+export function listFeatures(featuresRoot) {
+  if (!existsSync(featuresRoot)) return [];
+  return readdirSync(featuresRoot, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
+/** Đuôi định danh của một bước — phần tên KHÔNG đổi giữa các app/timestamp. */
+export function stepDirSuffix(feature, step) {
+  return `goerp_${feature.replace(/-/g, "_")}_${step.num}_${step.slug.replace(/-/g, "_")}`;
+}
+
+/** Bước đã được materialize vào prisma/migrations của app chưa? */
+export function isStepMaterialized(appMigrationsDir, feature, step) {
+  if (!existsSync(appMigrationsDir)) return false;
+  const suffix = `_${stepDirSuffix(feature, step)}`;
+  return readdirSync(appMigrationsDir).some((d) => d.endsWith(suffix));
+}
+
+/**
+ * Timestamp prefix kiểu prisma (YYYYMMDDHHMMSS). `offset` giây cộng thêm để
+ * nhiều bước sinh trong cùng lần sync giữ đúng thứ tự.
+ */
+export function migrationTimestamp(now, offset = 0) {
+  const d = new Date(now.getTime() + offset * 1000);
+  const p = (n, w = 2) => String(n).padStart(w, "0");
+  return (
+    `${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}` +
+    `${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}`
+  );
+}
+
+/**
+ * Trạng thái toàn bộ feature so với một app.
+ * → [{feature, steps: [{num, slug, materialized}] , schemaTarget, schemaSynced}]
+ */
+export function featureStatus({ featuresRoot, appRoot }) {
+  const migrationsDir = join(appRoot, "prisma", "migrations");
+  return listFeatures(featuresRoot).map((feature) => {
+    const featureDir = join(featuresRoot, feature);
+    const schemaSource = join(featureDir, "schema.prisma");
+    const schemaTarget = join(appRoot, "prisma", "schema", `goerp-${feature}.prisma`);
+    const schemaSynced =
+      existsSync(schemaSource) &&
+      existsSync(schemaTarget) &&
+      readFileSync(schemaTarget, "utf8").includes(readFileSync(schemaSource, "utf8").trim());
+    return {
+      feature,
+      hasSchema: existsSync(schemaSource),
+      schemaTarget,
+      schemaSynced,
+      steps: listFeatureSteps(featureDir).map((step) => ({
+        ...step,
+        materialized: isStepMaterialized(migrationsDir, feature, step),
+      })),
+    };
+  });
+}
+
+const GENERATED_HEADER = (feature) =>
+  `// GENERATED từ @goerp/core (features/${feature}/schema.prisma) — ĐỪNG sửa tay.\n` +
+  `// Nâng cấp core xong chạy: pnpm goerp-features sync\n\n`;
+
+/**
+ * Đồng bộ 1 app: copy schema fragments + materialize các bước SQL còn thiếu.
+ * Trả về log hành động (để CLI in + test assert). KHÔNG chạy prisma — app tự
+ * `prisma migrate deploy` (giữ nguyên flow deploy hiện có).
+ *
+ * @param {{ featuresRoot: string, appRoot: string, now?: Date, only?: string[] }} options
+ */
+export function syncFeatures({ featuresRoot, appRoot, now = new Date(), only = [] }) {
+  const actions = [];
+  const migrationsDir = join(appRoot, "prisma", "migrations");
+  let offset = 0;
+
+  for (const feature of listFeatures(featuresRoot)) {
+    if (only.length > 0 && !only.includes(feature)) continue;
+    const featureDir = join(featuresRoot, feature);
+
+    // 1) Schema fragment → prisma/schema/goerp-<feature>.prisma (đè)
+    const schemaSource = join(featureDir, "schema.prisma");
+    if (existsSync(schemaSource)) {
+      const schemaDir = join(appRoot, "prisma", "schema");
+      mkdirSync(schemaDir, { recursive: true });
+      const target = join(schemaDir, `goerp-${feature}.prisma`);
+      const content = GENERATED_HEADER(feature) + readFileSync(schemaSource, "utf8");
+      const changed = !existsSync(target) || readFileSync(target, "utf8") !== content;
+      if (changed) {
+        writeFileSync(target, content);
+        actions.push({ type: "schema", feature, target });
+      }
+    }
+
+    // 2) Materialize các bước SQL chưa có
+    for (const step of listFeatureSteps(featureDir)) {
+      if (isStepMaterialized(migrationsDir, feature, step)) continue;
+      const dirName = `${migrationTimestamp(now, offset++)}_${stepDirSuffix(feature, step)}`;
+      const dir = join(migrationsDir, dirName);
+      mkdirSync(dir, { recursive: true });
+      cpSync(step.file, join(dir, "migration.sql"));
+      actions.push({ type: "migration", feature, step: `${step.num}_${step.slug}`, dir: dirName });
+    }
+  }
+  return actions;
+}

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/features/__tests__/feature-sync.test.ts

@@ -0,0 +1,135 @@
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { featureStatus, migrationTimestamp, syncFeatures } from "../../../scripts/feature-sync.mjs";
+
+let featuresRoot: string;
+let appRoot: string;
+
+function writeFeature(name: string, steps: Record<string, string>, schema?: string) {
+  const dir = join(featuresRoot, name);
+  mkdirSync(join(dir, "migrations"), { recursive: true });
+  if (schema) writeFileSync(join(dir, "schema.prisma"), schema);
+  for (const [file, sql] of Object.entries(steps)) {
+    writeFileSync(join(dir, "migrations", file), sql);
+  }
+}
+
+beforeEach(() => {
+  featuresRoot = mkdtempSync(join(tmpdir(), "goerp-features-"));
+  appRoot = mkdtempSync(join(tmpdir(), "goerp-app-"));
+  mkdirSync(join(appRoot, "prisma", "migrations"), { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(featuresRoot, { recursive: true, force: true });
+  rmSync(appRoot, { recursive: true, force: true });
+});
+
+describe("syncFeatures", () => {
+  it("materialize schema fragment + bước SQL vào app trắng", () => {
+    writeFeature(
+      "background-tasks",
+      { "0001_init.sql": "CREATE TABLE IF NOT EXISTS t(id text);" },
+      "model BackgroundTask { id String @id }"
+    );
+
+    const actions = syncFeatures({ featuresRoot, appRoot, now: new Date("2026-07-31T00:00:00Z") })
+    expect(actions.map((a: { type: string }) => a.type)).toEqual(["schema", "migration"])
+
+    // Schema fragment có header GENERATED
+    const schema = readFileSync(
+      join(appRoot, "prisma", "schema", "goerp-background-tasks.prisma"),
+      "utf8"
+    )
+    expect(schema).toContain("GENERATED từ @goerp/core")
+    expect(schema).toContain("model BackgroundTask")
+
+    // Migration folder đúng tên <ts>_goerp_<feature>_<step>
+    const dirs = readdirSync(join(appRoot, "prisma", "migrations"))
+    expect(dirs).toEqual(["20260731000000_goerp_background_tasks_0001_init"])
+    expect(
+      readFileSync(
+        join(appRoot, "prisma", "migrations", dirs[0], "migration.sql"),
+        "utf8"
+      )
+    ).toContain("CREATE TABLE IF NOT EXISTS")
+  })
+
+  it("idempotent: sync lần 2 không tạo gì thêm (bất kể timestamp khác)", () => {
+    writeFeature("background-tasks", { "0001_init.sql": "SELECT 1;" })
+    syncFeatures({ featuresRoot, appRoot, now: new Date("2026-07-31T00:00:00Z") })
+    const again = syncFeatures({ featuresRoot, appRoot, now: new Date("2026-08-01T09:09:09Z") })
+    expect(again).toEqual([])
+    expect(readdirSync(join(appRoot, "prisma", "migrations"))).toHaveLength(1)
+  })
+
+  it("nâng cấp core thêm bước mới → chỉ materialize bước thiếu, giữ thứ tự", () => {
+    writeFeature("background-tasks", { "0001_init.sql": "SELECT 1;" })
+    syncFeatures({ featuresRoot, appRoot, now: new Date("2026-07-31T00:00:00Z") })
+
+    writeFileSync(
+      join(featuresRoot, "background-tasks", "migrations", "0002_add-col.sql"),
+      "ALTER TABLE t ADD COLUMN IF NOT EXISTS x text;"
+    )
+    const actions = syncFeatures({ featuresRoot, appRoot, now: new Date("2026-08-02T00:00:00Z") })
+    expect(actions).toHaveLength(1)
+    expect(actions[0].step).toBe("0002_add-col")
+
+    const dirs = readdirSync(join(appRoot, "prisma", "migrations")).sort()
+    expect(dirs[0]).toContain("0001_init")
+    expect(dirs[1]).toContain("0002_add_col")
+  })
+
+  it("nhiều bước trong 1 lần sync giữ thứ tự qua timestamp tăng dần", () => {
+    writeFeature("f-a", { "0001_one.sql": "SELECT 1;", "0002_two.sql": "SELECT 2;" })
+    syncFeatures({ featuresRoot, appRoot, now: new Date("2026-07-31T00:00:00Z") })
+    const dirs = readdirSync(join(appRoot, "prisma", "migrations")).sort()
+    expect(dirs[0]).toContain("0001_one")
+    expect(dirs[1]).toContain("0002_two")
+    expect(dirs[0] < dirs[1]).toBe(true)
+  })
+
+  it("--only giới hạn feature; schema đổi nội dung thì được ghi đè", () => {
+    writeFeature("f-a", { "0001_a.sql": "SELECT 1;" }, "model A { id String @id }")
+    writeFeature("f-b", { "0001_b.sql": "SELECT 1;" })
+    const actions = syncFeatures({ featuresRoot, appRoot, only: ["f-a"] })
+    expect(actions.every((a: { feature: string }) => a.feature === "f-a")).toBe(true)
+
+    // core bump: schema fragment đổi → sync ghi đè bản GENERATED
+    writeFileSync(
+      join(featuresRoot, "f-a", "schema.prisma"),
+      "model A { id String @id\n  extra String? }"
+    )
+    const again = syncFeatures({ featuresRoot, appRoot, only: ["f-a"] })
+    expect(again.some((a: { type: string }) => a.type === "schema")).toBe(true)
+    expect(
+      readFileSync(join(appRoot, "prisma", "schema", "goerp-f-a.prisma"), "utf8")
+    ).toContain("extra String?")
+  })
+})
+
+describe("featureStatus", () => {
+  it("báo pending trước sync, đủ sau sync", () => {
+    writeFeature("f-a", { "0001_a.sql": "SELECT 1;" }, "model A { id String @id }")
+    let status = featureStatus({ featuresRoot, appRoot })
+    expect(status[0].steps[0].materialized).toBe(false)
+    expect(status[0].schemaSynced).toBe(false)
+
+    syncFeatures({ featuresRoot, appRoot })
+    status = featureStatus({ featuresRoot, appRoot })
+    expect(status[0].steps[0].materialized).toBe(true)
+    expect(status[0].schemaSynced).toBe(true)
+  })
+})
+
+describe("migrationTimestamp", () => {
+  it("dạng YYYYMMDDHHMMSS UTC + offset giây", () => {
+    const now = new Date("2026-07-31T01:02:03Z")
+    expect(migrationTimestamp(now)).toBe("20260731010203")
+    expect(migrationTimestamp(now, 2)).toBe("20260731010205")
+  })
+})

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> {