@goplusvn/core 0.1.59 → 0.1.61

package/PLATFORM.md

@@ -10,6 +10,24 @@ implementation of every pattern here.
 > mechanism, or a CAS update into an app, stop — it belongs in core. Promote it
 > and re-export a thin shim from the app so call sites don't change.
 
+## Starting a new app
+
+This package ships the starter app it documents, plus the scaffolder:
+
+```bash
+npx -p @goplusvn/core goerp-init my-app --port 3010
+cd my-app && pnpm install
+# edit DATABASE_URL in the generated .env
+pnpm prisma:deploy && pnpm seed && pnpm rbac-sync && pnpm dev
+```
+
+`goerp-init` fills in the app name, port, branding (`src/configs/tenant.ts`) and
+a random `BETTER_AUTH_SECRET`; it never touches a database. `seed` must run
+**before** `rbac-sync` — see the generated `README.md` for why. What you get is
+a working login, RBAC, CRUD, audit/error logs, notifications, background tasks
+and cron — all from core, not copied code. Do not copy the template directory by
+hand: the rename steps are the whole point of the command.
+
 ## Design system (styles)
 
 One import gives the whole token system; override only your brand.

package/bin/goerp-init.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// Khởi tạo một app mới từ template đi kèm gói này.
+//
+//   npx -p @goplusvn/core goerp-init <ten-app> [--dir <đường-dẫn>] [--port 3010]
+//   pnpm init-app <ten-app> ...                      (từ trong repo goerp-core)
+//
+// Template nằm trong chính gói npm (packages/core/templates/starter-app) nên
+// lệnh này chạy được ở máy trắng, không cần clone goerp-core.
+//
+// App mới là repo ĐỘC LẬP, không phải thành viên workspace của core: nó cài
+// @goerp/core từ npm như mọi app thật, nên lỗi kiểu "chạy được nhờ workspace"
+// không lọt qua được.
+//
+// Script chỉ chép + thay tên/cổng + sinh secret. Không chạy pnpm install,
+// không đụng DB — những việc đó in ra cho người dùng tự chạy.
+
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const templateDir = path.join(packageRoot, "templates", "starter-app");
+
+// Thứ sinh ra lúc build/cài: chép sang chỉ tổ làm app mới hỏng theo cách khó hiểu.
+// `.env` cũng bỏ — nó là bí mật của máy đang chép, app mới sinh secret riêng.
+const SKIP = new Set([
+  "node_modules",
+  ".next",
+  ".turbo",
+  ".git",
+  ".env",
+  "tsconfig.tsbuildinfo",
+  "next-env.d.ts",
+]);
+
+function fail(message) {
+  console.error(`✗ ${message}`);
+  process.exit(1);
+}
+
+// ── Tham số ──────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+const name = argv.find((a) => !a.startsWith("-"));
+if (!name) fail("Thiếu tên app. Dùng: goerp-init <ten-app> [--dir <path>] [--port 3010]");
+if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+  fail(`Tên "${name}" không hợp lệ — dùng kebab-case (chữ thường, số, gạch ngang).`);
+}
+
+const flag = (key, fallback) => {
+  const i = argv.indexOf(`--${key}`);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : fallback;
+};
+
+const port = Number(flag("port", "3010"));
+if (!Number.isInteger(port) || port < 1024 || port > 65535) fail(`Cổng không hợp lệ: ${port}`);
+
+const targetDir = path.resolve(flag("dir", path.join(process.cwd(), name)));
+
+if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+  fail(`${targetDir} đã tồn tại và không rỗng — chọn thư mục khác cho chắc.`);
+}
+if (!fs.existsSync(templateDir)) fail(`Không thấy template ở ${templateDir}`);
+
+// ── Chép ─────────────────────────────────────────────────────────────────────
+function copyDir(from, to) {
+  fs.mkdirSync(to, { recursive: true });
+  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+    if (SKIP.has(entry.name)) continue;
+    const src = path.join(from, entry.name);
+    const dst = path.join(to, entry.name);
+    if (entry.isDirectory()) copyDir(src, dst);
+    else fs.copyFileSync(src, dst);
+  }
+}
+copyDir(templateDir, targetDir);
+
+const read = (p) => fs.readFileSync(path.join(targetDir, p), "utf8");
+const write = (p, content) => fs.writeFileSync(path.join(targetDir, p), content);
+
+// npm/pnpm KHÔNG đóng gói file tên `.gitignore` (nuốt hoặc đổi thành
+// `.npmignore` khi cài). Template ship nó dưới tên `gitignore`, trả lại dấu
+// chấm ở đây — thiếu bước này thì `git add .` đầu tiên của app mới commit luôn
+// `.env` vừa sinh (kèm BETTER_AUTH_SECRET) và cả node_modules.
+fs.renameSync(path.join(targetDir, "gitignore"), path.join(targetDir, ".gitignore"));
+
+// "quan-ly-kho" → "Quan Ly Kho": nhãn hiển thị mặc định, chủ app sửa lại sau.
+const title = name
+  .split("-")
+  .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+  .join(" ");
+
+// ── package.json: tên + cổng ─────────────────────────────────────────────────
+const pkg = JSON.parse(read("package.json"));
+pkg.name = name;
+pkg.version = "0.1.0";
+for (const key of ["dev", "start"]) {
+  if (pkg.scripts?.[key]) pkg.scripts[key] = pkg.scripts[key].replace(/--port \d+/, `--port ${port}`);
+}
+write("package.json", `${JSON.stringify(pkg, null, 2)}\n`);
+
+// ── .env: điền sẵn thứ điền được, để trống thứ chỉ người dùng biết ───────────
+// BETTER_AUTH_SECRET sinh ngay tại đây: bỏ trống thì lần đăng nhập đầu tiên đổ
+// lỗi khó đoán, mà nhét placeholder thì có ngày nó lên production.
+const dbName = name.replace(/-/g, "_");
+const env = read(".env.example")
+  .replace(/^DATABASE_URL=.*$/m, `DATABASE_URL="postgresql://postgres:postgres@localhost:5432/${dbName}"`)
+  .replace(/^BETTER_AUTH_SECRET=.*$/m, `BETTER_AUTH_SECRET="${randomBytes(32).toString("base64")}"`)
+  .replace(/^BETTER_AUTH_URL=.*$/m, `BETTER_AUTH_URL="http://localhost:${port}"`);
+write(".env", env);
+
+// ── Thương hiệu: một chỗ duy nhất đổi tên hiển thị toàn app ──────────────────
+// Bỏ qua bước này thì app mới chạy lên vẫn đề "GoERP Starter" trên sidebar,
+// trang đăng nhập và tiêu đề tab — người dựng app phải đi tìm mới sửa được.
+const tenantPath = "src/configs/tenant.ts";
+write(
+  tenantPath,
+  read(tenantPath)
+    .replace(/(\bid:\s*)"[^"]*"/, `$1"${name}"`)
+    .replace(/(\bname:\s*)"[^"]*"/, `$1"${title}"`)
+    .replace(/(\bcompanyName:\s*)"[^"]*"/, `$1"${title}"`),
+);
+
+// ── Tài liệu: điền tên app ───────────────────────────────────────────────────
+write("AGENTS.md", read("AGENTS.md").replace(/<APP-NAME>/g, name));
+write("README.md", read("README.md").replace(/^# GoERP starter app$/m, `# ${title}`));
+
+// ── Xong ─────────────────────────────────────────────────────────────────────
+const relative = path.relative(process.cwd(), targetDir);
+// Đường dẫn tương đối chỉ dễ đọc khi app nằm gần; xa quá thì in tuyệt đối.
+const rel = relative && relative.length < targetDir.length ? relative : targetDir;
+console.log(`✓ Đã tạo ${name} tại ${targetDir}\n`);
+console.log("Tiếp theo:\n");
+console.log(`  cd ${rel}`);
+console.log("  pnpm install");
+console.log("  # sửa DATABASE_URL trong .env cho trỏ đúng Postgres của bạn");
+console.log("  pnpm prisma:deploy   # dựng bảng (migration _init có sẵn)");
+console.log("  pnpm seed            # vai trò + tài khoản admin");
+console.log("  pnpm rbac-sync       # PHẢI chạy SAU seed, xem README");
+console.log(`  pnpm dev             # http://localhost:${port}`);
+console.log("\n.env đã có sẵn BETTER_AUTH_SECRET sinh ngẫu nhiên — đừng commit file này.");

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.59",
+  "version": "0.1.61",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -12,13 +12,15 @@
   "types": "./src/index.ts",
   "sideEffects": false,
   "bin": {
-    "goerp-features": "./bin/goerp-features.mjs"
+    "goerp-features": "./bin/goerp-features.mjs",
+    "goerp-init": "./bin/goerp-init.mjs"
   },
   "files": [
     "src",
     "bin",
     "scripts",
     "features",
+    "templates",
     "README.md",
     "CHANGELOG.md",
     "PLATFORM.md"
@@ -88,8 +90,6 @@
     "./audit": "./src/audit/index.ts",
     "./rbac/role-service": "./src/rbac/role-service.ts",
     "./rbac/resource-service": "./src/rbac/resource-service.ts",
-    "./infrastructure/cron/cron-manager": "./src/infrastructure/cron/cron-manager.ts",
-    "./infrastructure/cron/types": "./src/infrastructure/cron/types.ts",
     "./crud/pages/entity-crud-page": "./src/crud/pages/entity-crud-page.tsx",
     "./auth/auth-service": "./src/auth/auth-service.ts",
     "./package.json": "./package.json",

package/src/cron/db-cron-manager.ts

@@ -1,15 +1,15 @@
-import { SimpleCronJob } from "../infrastructure/cron/cron-manager";
+import { SimpleCronJob } from "./simple-cron-job";
 
 import type {
   CronJob,
   CronJobManager,
   CronJobOptions,
-} from "../infrastructure/cron/types";
+} from "./types";
 
 /**
  * Cron CÓ TRẠNG THÁI TRONG DB — engine dùng chung mọi app goerp (bảng
  * `system_jobs` + `job_execution_logs` ship qua `goerp-features sync`, feature
- * system-jobs). Bản `infrastructure/cron` chỉ hẹn giờ trong RAM: restart là
+ * system-jobs). Bản `SimpleCronJob` cạnh đây chỉ hẹn giờ trong RAM: restart là
  * mất bật/tắt, không có lịch sử chạy, admin không nhìn thấy gì.
  *
  * Vai trò từng lớp:

package/src/cron/index.ts

@@ -16,9 +16,9 @@ export {
   cronJobManager,
   CronJobManagerImpl,
   SimpleCronJob,
-} from "../infrastructure/cron/cron-manager";
+} from "./simple-cron-job";
 export type {
   CronJob,
   CronJobManager,
   CronJobOptions,
-} from "../infrastructure/cron/types";
+} from "./types";

package/src/{infrastructure/cron/cron-manager.ts → cron/simple-cron-job.ts}

@@ -3,7 +3,7 @@ import type {
   CronJobManager as ICronJobManager,
   CronJobOptions,
 } from "./types";
-import { createLogger } from "../logger";
+import { createLogger } from "../infrastructure/logger";
 
 const logger = createLogger("CronJobManager");
 

package/src/crud/lib/mutation-builder.ts

@@ -0,0 +1,105 @@
+import type { EntityConfig } from "../../types";
+import type { ServerCrudLogger } from "../server-service";
+
+export interface PrepareMutationDataOptions {
+  data: any;
+  config?: EntityConfig;
+  mode: "create" | "update";
+  systemFields: string[];
+  relationFieldSkip?: string[];
+  logger: ServerCrudLogger;
+  touchUpdatedAtOnCreate?: boolean;
+}
+
+export function prepareMutationData(options: PrepareMutationDataOptions) {
+  const { data, config, mode, systemFields, relationFieldSkip, logger, touchUpdatedAtOnCreate } = options;
+
+  let filtered = data;
+  
+  if (config) {
+    // 1. Filter valid fields
+    const valid = new Set(config.fields.filter((f) => !(f as any).isDisplayOnly).map((f) => f.name));
+    for (const f of systemFields) valid.add(f);
+    filtered = {};
+    for (const [k, v] of Object.entries(data)) {
+      if (valid.has(k)) {
+        filtered[k] = v;
+      } else {
+        logger.warn(`Filtering out invalid field "${k}" for entity "${config.name}"`);
+      }
+    }
+
+    // 2. Cast field values (boolean, number)
+    for (const field of config.fields) {
+      const value = filtered[field.name];
+      if (value === undefined || value === null) continue;
+      
+      if (field.type === "boolean" || field.type === "switch") {
+        let isTrue: boolean;
+        if (typeof value === "string") {
+          const lv = value.toLowerCase();
+          isTrue = lv === "true" || lv === "active" || value === "1" || value === "on";
+        } else {
+          isTrue = Boolean(value);
+        }
+        
+        if (field.type === "switch" && field.options && field.options.length >= 2) {
+          filtered[field.name] = isTrue ? (field.options[0] as any).value : (field.options[1] as any).value;
+        } else {
+          filtered[field.name] = isTrue;
+        }
+      } else if (field.type === "number" || (field.type as string) === "integer") {
+        if (typeof value === "string") {
+          if (value.trim() === "") {
+            filtered[field.name] = null;
+          } else {
+            const num = Number(value);
+            if (!isNaN(num)) filtered[field.name] = num;
+          }
+        }
+      }
+    }
+  }
+
+  // 3. System defaults for create
+  if (mode === "create") {
+    if (!filtered.id) {
+      filtered.id = crypto.randomUUID();
+    }
+    if (touchUpdatedAtOnCreate && !filtered.updatedAt) {
+      filtered.updatedAt = new Date();
+    }
+  }
+
+  // 4. Transform relation fields (*Id -> connect/disconnect)
+  const skip = new Set([
+    "id",
+    "createdBy",
+    "updatedBy",
+    "citizenId",
+    "targetId",
+    ...(relationFieldSkip ?? []),
+  ]);
+  
+  const prismaData = { ...filtered };
+  for (const key of Object.keys(prismaData)) {
+    if (skip.has(key)) continue;
+    
+    if (key.endsWith("Id") && key.length > 2) {
+      const rel = key.slice(0, -2);
+      const value = prismaData[key];
+      
+      if (value && typeof value === "string" && value.trim() !== "") {
+        prismaData[rel] = { connect: { id: value } };
+        delete prismaData[key];
+      } else if (value === null || value === undefined || value === "") {
+        if (mode === "update") {
+          prismaData[rel] = { disconnect: true };
+        }
+        delete prismaData[key];
+      }
+    }
+  }
+
+  return prismaData;
+}

package/src/crud/lib/query-builder.ts

@@ -0,0 +1,119 @@
+import { compileFilterTree } from "./filter-tree";
+import type { CrudQueryParams, EntityConfig } from "../../types";
+
+export interface BuildListQueryOptions {
+  entity: string;
+  config: EntityConfig;
+  params: CrudQueryParams;
+  scopeWhere?: Record<string, unknown>;
+  onDisallowedFilter?: (field: string) => void;
+}
+
+export function buildListQuery({
+  entity,
+  config,
+  params,
+  scopeWhere,
+  onDisallowedFilter,
+}: BuildListQueryOptions) {
+  const { page = 1, pageSize = 10, search, sort, filters, filterTree } = params;
+  const MAX_PAGE_SIZE = 200;
+  
+  const safePage = Math.max(1, Number(page) || 1);
+  const safePageSize = Math.min(Math.max(1, Number(pageSize) || 10), MAX_PAGE_SIZE);
+  const skip = (safePage - 1) * safePageSize;
+  const take = safePageSize;
+
+  const allowedFields = new Set<string>([
+    ...config.fields.map((f) => f.name),
+    "id", "createdAt", "updatedAt", "createdBy", "updatedBy", config.idField || "id",
+  ]);
+  const allowedRelations = new Set<string>(config.include || []);
+  const isAllowed = (name: string) => {
+    if (!name) return false;
+    if (name.includes(".")) return allowedRelations.has(name.split(".")[0]);
+    return allowedFields.has(name);
+  };
+
+  const where: any = { ...(scopeWhere ?? {}) };
+  if (search && search.trim()) {
+    const term = search.trim();
+    const searchFields = config.fields.filter((f) => f.filterable && f.type === "text").map((f) => f.name);
+    if (searchFields.length) where.OR = searchFields.map((f) => ({ [f]: { contains: term, mode: "insensitive" } }));
+  }
+
+  if (filters && filters.length) {
+    for (const filter of filters) {
+      const { name, value, operator } = filter as any;
+      if (value === undefined || value === null || (Array.isArray(value) && value.length === 0)) continue;
+      if (!isAllowed(name)) {
+        if (onDisallowedFilter) onDisallowedFilter(name);
+        continue;
+      }
+      let target = where;
+      let key = name;
+      if (name.includes(".")) {
+        const parts = name.split(".");
+        key = parts.pop()!;
+        for (const p of parts) { if (!target[p]) target[p] = {}; target = target[p]; }
+      }
+      const op = operator as string;
+      if (op === "contains") target[key] = { contains: value, mode: "insensitive" };
+      else if (op === "in") target[key] = { in: value };
+      else if (op === "notIn") target[key] = { notIn: value };
+      else if (op === "eq") target[key] = value;
+      else if (op === "ne") target[key] = { not: value };
+      else if (op === "gt") target[key] = { gt: value };
+      else if (op === "gte") target[key] = { gte: value };
+      else if (op === "lt") target[key] = { lt: value };
+      else if (op === "lte") target[key] = { lte: value };
+      else if (op === "startsWith") target[key] = { startsWith: value, mode: "insensitive" };
+      else if (op === "endsWith") target[key] = { endsWith: value, mode: "insensitive" };
+      else if (op === "isNull") target[key] = null;
+      else if (op === "isNotNull") target[key] = { not: null };
+      else target[key] = value;
+    }
+  }
+
+  if (filterTree) {
+    const compiled = compileFilterTree(filterTree, {
+      isAllowed,
+      onDisallowed: (field) => {
+        if (onDisallowedFilter) onDisallowedFilter(field);
+      },
+    });
+    if (compiled) {
+      where.AND = [...(Array.isArray(where.AND) ? where.AND : where.AND ? [where.AND] : []), compiled];
+    }
+  }
+
+  const orderBy: any = {};
+  const applySort = (field: string, direction: any) => {
+    if (field.includes(".")) {
+      const parts = field.split(".");
+      const leaf = parts.pop()!;
+      let t = orderBy;
+      for (const p of parts) { t[p] = t[p] || {}; t = t[p]; }
+      t[leaf] = direction;
+    } else orderBy[field] = direction;
+  };
+
+  if (sort && isAllowed(sort.field)) applySort(sort.field, sort.direction);
+  else if (config.defaultSort) applySort(config.defaultSort.field, config.defaultSort.direction);
+  else if (config.fields.some((f) => f.name === "createdAt")) orderBy.createdAt = "desc";
+  else orderBy[config.idField || "id"] = "desc";
+
+  const include: any = {};
+  if (config.include?.length) config.include.forEach((inc) => (include[inc] = true));
+  const includeOption = Object.keys(include).length ? { include } : {};
+
+  return {
+    where,
+    orderBy,
+    includeOption,
+    skip,
+    take,
+    safePage,
+    safePageSize,
+  };
+}