@goplusvn/core 0.1.71 → 0.1.73

package/src/crud/lib/permissions.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { getCrudPermissions, mergePermissions } from "./permissions";
+import type { Session } from "../../types";
+
+// Session non-admin với permissionMap gọn (resource → action codes) — đúng
+// dạng session callback nạp vào JWT.
+const staff = {
+  user: {
+    id: "u1",
+    permissionMap: { employee: ["view", "update", "reset-password"] },
+  },
+} as unknown as Session;
+
+const admin = {
+  user: { id: "a1", roles: ["SUPER_ADMIN"] },
+} as unknown as Session;
+
+describe("getCrudPermissions + extraActions (custom action từ registry)", () => {
+  it("điền custom action theo checkPermission, thiếu quyền = false", async () => {
+    const perms = await getCrudPermissions(staff, "employee", [
+      "reset-password",
+      "resync",
+    ]);
+    expect(perms.read).toBe(true);
+    expect(perms.update).toBe(true);
+    expect(perms.create).toBe(false);
+    expect(perms["reset-password"]).toBe(true);
+    expect(perms["resync"]).toBe(false);
+  });
+
+  it("admin có mọi custom action", async () => {
+    const perms = await getCrudPermissions(admin, "employee", ["resync"]);
+    expect(perms["resync"]).toBe(true);
+  });
+
+  it("extraActions trùng 8 action chuẩn không ghi đè kết quả chuẩn", async () => {
+    const perms = await getCrudPermissions(staff, "employee", ["update"]);
+    expect(perms.update).toBe(true);
+  });
+});
+
+describe("mergePermissions giữ custom action", () => {
+  it("không khai config permissions → trả nguyên map user (kể cả custom)", () => {
+    const user = { read: true, "reset-password": true };
+    expect(mergePermissions(undefined, user)).toEqual(user);
+  });
+
+  it("config permissions chỉ khai 1 key → custom action KHÔNG bị rơi mất", () => {
+    const merged = mergePermissions(
+      { create: false },
+      { create: true, read: true, "reset-password": true },
+    );
+    expect(merged.create).toBe(false);
+    expect(merged.read).toBe(true);
+    expect(merged["reset-password"]).toBe(true);
+  });
+});

package/src/crud/lib/permissions.ts

@@ -4,20 +4,29 @@ import type { Session } from "../../types";
 // Nguồn permission DUY NHẤT đã harden (BYPASS_AUTH chỉ hiệu lực ngoài
 // production, admin-role check chạy trước empty-permissions guard) — bản
 // divergent rbac/permissions.ts cũ đã xóa 2026-07 vì thiếu guard NODE_ENV.
-import { getCrudPermissionsFromSession } from "../../auth";
+import {
+  checkPermission,
+  getActionCode,
+  getCrudPermissionsFromSession,
+} from "../../auth";
 
 /**
  * Get CRUD permissions for a user based on their session
  * Permissions are read from session (loaded from cache in session callback)
- * Uses memoization to return stable object references with TTL
+ *
+ * `extraActions`: custom action ngoài 8 action CRUD chuẩn (khai trong registry,
+ * vd "reset-password", "resync") — mỗi cái tra checkPermission và điền vào map
+ * trả về, để RowAction.permissionAction gate được theo ĐÚNG action code thay vì
+ * mượn tạm "update". BYPASS_AUTH/admin đã xử lý bên trong checkPermission.
  */
 export async function getCrudPermissions(
   session: Session | null,
   entity: string,
+  extraActions?: string[],
 ): Promise<CrudPermissions> {
   // Get permissions from session (already loaded in JWT)
   const perms = getCrudPermissionsFromSession(session, entity);
-  return {
+  const result: CrudPermissions = {
     create: perms.create,
     read: perms.view,
     update: perms.update,
@@ -27,12 +36,20 @@ export async function getCrudPermissions(
     approve: perms.approve,
     reject: perms.reject,
   };
+  for (const action of extraActions ?? []) {
+    if (result[action] !== undefined) continue; // 8 action chuẩn đã có
+    result[action] = checkPermission(session, entity, getActionCode(action));
+  }
+  return result;
 }
 
 /**
  * Merge config permissions with user permissions
  * User permissions take precedence
  * Config permissions are optional, so undefined means "allow if user has permission"
+ *
+ * Merge theo TOÀN BỘ key của userPermissions (kể cả custom action) — bản cũ
+ * liệt kê cứng 8 key nên custom action bị rơi mất sau merge.
  */
 export function mergePermissions(
   configPermissions: EntityConfig["permissions"],
@@ -42,14 +59,9 @@ export function mergePermissions(
     return userPermissions;
   }
 
-  return {
-    create: (configPermissions.create ?? true) && userPermissions.create,
-    read: (configPermissions.read ?? true) && userPermissions.read,
-    update: (configPermissions.update ?? true) && userPermissions.update,
-    delete: (configPermissions.delete ?? true) && userPermissions.delete,
-    export: (configPermissions.export ?? true) && userPermissions.export,
-    import: (configPermissions.import ?? true) && userPermissions.import,
-    approve: (configPermissions.approve ?? true) && userPermissions.approve,
-    reject: (configPermissions.reject ?? true) && userPermissions.reject,
-  };
+  const result: CrudPermissions = {};
+  for (const key of Object.keys(userPermissions)) {
+    result[key] = (configPermissions[key] ?? true) && userPermissions[key];
+  }
+  return result;
 }

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

@@ -1,4 +1,5 @@
 import { compileFilterTree } from "./filter-tree";
+import { CrudRequestError } from "./errors";
 import type { CrudQueryParams, EntityConfig } from "../../types";
 
 export interface BuildListQueryOptions {
@@ -76,12 +77,18 @@ export function buildListQuery({
   }
 
   if (filterTree) {
-    const compiled = compileFilterTree(filterTree, {
-      isAllowed,
-      onDisallowed: (field) => {
-        if (onDisallowedFilter) onDisallowedFilter(field);
-      },
-    });
+    let compiled;
+    try {
+      compiled = compileFilterTree(filterTree, {
+        isAllowed,
+        onDisallowed: (field) => {
+          if (onDisallowedFilter) onDisallowedFilter(field);
+        },
+      });
+    } catch (e) {
+      // Cây sai cấu trúc/vượt giới hạn là lỗi CLIENT — route trả 400, không 500.
+      throw new CrudRequestError(e instanceof Error ? e.message : "filterTree không hợp lệ");
+    }
     if (compiled) {
       where.AND = [...(Array.isArray(where.AND) ? where.AND : where.AND ? [where.AND] : []), compiled];
     }

package/src/crud/pages/entity-crud-page.tsx

@@ -110,15 +110,18 @@ export async function EntityCrudPage({
       dictionary,
     );
 
-    // Get user permissions for this entity if available in session or passed explicitly?
-    // In vinhhoa/page.tsx: getCrudPermissions(session, entity) is called.
-    // We should probably rely on `session` having what we need OR generic permissions logic.
-    // The `mergePermissions` below merges generic config perms with USER perms.
-    // We need user perms.
-
-    // We can import getCrudPermissions from ../lib/permissions if it effectively uses session
     const { getCrudPermissions } = await import("../lib/permissions");
-    const userPermissions = await getCrudPermissions(session, entity);
+    // Custom action trong rowActions (permissionAction ngoài 8 action CRUD
+    // chuẩn) cũng phải vào map quyền — không gom thì nút bị fail-closed ẩn
+    // vĩnh viễn dù user CÓ quyền trong registry.
+    const extraActions = (config.rowActions ?? [])
+      .map((a) => a.permissionAction)
+      .filter((a): a is string => Boolean(a));
+    const userPermissions = await getCrudPermissions(
+      session,
+      config.permissionResource ?? entity,
+      extraActions,
+    );
 
     const permissions = mergePermissions(config.permissions, userPermissions);
 

package/src/crud/server-service.test.ts

@@ -0,0 +1,112 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createServerCrudService } from "./server-service";
+import { CrudRequestError } from "./lib/errors";
+import type { EntityConfig } from "../types";
+
+const makeModel = () => ({
+  findUnique: vi.fn(async () => ({ id: 1, name: "A" })),
+  findMany: vi.fn(async () => []),
+  count: vi.fn(async () => 0),
+  create: vi.fn(async ({ data }: any) => data),
+  update: vi.fn(async () => ({ id: 1 })),
+  delete: vi.fn(async () => ({ id: 1 })),
+  deleteMany: vi.fn(async () => ({ count: 2 })),
+});
+
+const makeConfig = (over: Partial<EntityConfig> = {}): EntityConfig => ({
+  name: "job-title",
+  label: "Chức danh",
+  pluralLabel: "Chức danh",
+  apiEndpoint: "/api/crud/job-titles",
+  idField: "id",
+  displayField: "name",
+  fields: [
+    { name: "id", label: "ID", type: "text" },
+    { name: "name", label: "Tên", type: "text" },
+  ],
+  ...over,
+});
+
+const logger = { warn: vi.fn(), error: vi.fn() };
+
+describe("createServerCrudService", () => {
+  let model: ReturnType<typeof makeModel>;
+  let prisma: Record<string, any>;
+
+  beforeEach(() => {
+    model = makeModel();
+    // Model chỉ tồn tại dưới tên "jobTitle" — convention từ entity key khác
+    // ("weird-things") sẽ trượt nếu không đọc config.modelName.
+    prisma = { jobTitle: model };
+  });
+
+  it("ưu tiên config.modelName hơn convention getModelName", async () => {
+    const service = createServerCrudService({ prisma, logger });
+    const config = makeConfig({ modelName: "jobTitle" });
+    await service.getById("weird-things", "x", config);
+    expect(model.findUnique).toHaveBeenCalled();
+  });
+
+  it("thiếu modelName thì fallback convention (job-titles → jobTitle)", async () => {
+    const service = createServerCrudService({ prisma, logger });
+    await service.getById("job-titles", "x", makeConfig());
+    expect(model.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { id: "x" } }),
+    );
+  });
+
+  it("where dùng config.idField thay vì hardcode id", async () => {
+    const service = createServerCrudService({ prisma, logger });
+    const config = makeConfig({ modelName: "jobTitle", idField: "code" });
+    await service.delete("job-titles", "JT01", config);
+    expect(model.delete).toHaveBeenCalledWith({ where: { code: "JT01" } });
+  });
+
+  it("idKind int: id trên URL được ép Number cho mọi method", async () => {
+    const service = createServerCrudService({ prisma, logger });
+    const config = makeConfig({ modelName: "jobTitle", idKind: "int" });
+
+    await service.getById("job-titles", "42", config);
+    expect(model.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { id: 42 } }),
+    );
+
+    await service.update("job-titles", "42", { name: "B" }, config);
+    expect(model.update).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { id: 42 } }),
+    );
+
+    await service.delete("job-titles", "42", config);
+    expect(model.delete).toHaveBeenCalledWith({ where: { id: 42 } });
+  });
+
+  it("idKind int: id không phải số nguyên → CrudRequestError 400", async () => {
+    const service = createServerCrudService({ prisma, logger });
+    const config = makeConfig({ modelName: "jobTitle", idKind: "int" });
+    await expect(service.getById("job-titles", "abc", config)).rejects.toThrow(
+      CrudRequestError,
+    );
+    expect(model.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("deleteMany: ép cả mảng id, một phần tử hỏng là fail cả request", async () => {
+    const service = createServerCrudService({ prisma, logger });
+    const config = makeConfig({ modelName: "jobTitle", idKind: "int" });
+
+    await service.deleteMany("job-titles", ["1", "2"], config);
+    expect(model.deleteMany).toHaveBeenCalledWith({ where: { id: { in: [1, 2] } } });
+
+    await expect(
+      service.deleteMany("job-titles", ["1", "x"], config),
+    ).rejects.toThrow(CrudRequestError);
+    expect(model.deleteMany).toHaveBeenCalledTimes(1);
+  });
+
+  it("idKind mặc định: id giữ nguyên chuỗi (UUID)", async () => {
+    const service = createServerCrudService({ prisma, logger });
+    const config = makeConfig({ modelName: "jobTitle" });
+    await service.delete("job-titles", "uuid-1", config);
+    expect(model.delete).toHaveBeenCalledWith({ where: { id: "uuid-1" } });
+  });
+});

package/src/crud/server-service.ts

@@ -7,16 +7,15 @@
 // lives here so every app stops re-implementing it.
 //
 // Usage (app side):
-//   import { createServerCrudService, getModelName } from "@goerp/core/crud/server";
+//   import { createServerCrudService } from "@goerp/core/crud/server";
 //   import { prisma } from "@/lib/prisma";
-//   const MODEL_MAP = { customers: "customer", "fee-schedules": "feeSchedule" };
-//   export const crudService = createServerCrudService({
-//     prisma,
-//     getModelName: (e) => getModelName(e, MODEL_MAP),
-//   });
+//   export const crudService = createServerCrudService({ prisma });
+// Tên model Prisma khai ngay trong EntityConfig (`modelName: "feeSchedule"`),
+// không cần MODEL_MAP riêng; thiếu modelName thì fallback convention getModelName.
 
 import { buildListQuery } from "./lib/query-builder";
 import { prepareMutationData } from "./lib/mutation-builder";
+import { CrudRequestError } from "./lib/errors";
 import type { CrudQueryParams, CrudResponse, EntityConfig } from "../types";
 import { serializeDecimalFields } from "../utils/serialize";
 
@@ -24,14 +23,16 @@ type PrismaLike = Record<string, any>;
 
 export interface ServerCrudService {
   list(entity: string, config: EntityConfig, params: CrudQueryParams): Promise<CrudResponse>;
-  /** `config` (tùy chọn) để áp cùng `include` như list — detail không hiện raw FK id. */
+  /** `config` (tùy chọn) để áp cùng `include` như list — detail không hiện raw FK id.
+   *  Mọi method nhận id dạng chuỗi thô từ URL; entity `idKind: "int"` được ép
+   *  Number bên trong (sai định dạng → {@link CrudRequestError} 400). */
   getById(entity: string, id: string, config?: EntityConfig): Promise<any>;
   /** `tx` (tùy chọn) để app chạy create CÙNG transaction với sinh số phiếu
    *  advisory-lock (document-number yêu cầu cùng tx với insert). */
   create(entity: string, data: any, config?: EntityConfig, tx?: PrismaLike): Promise<any>;
   update(entity: string, id: string, data: any, config?: EntityConfig, tx?: PrismaLike): Promise<any>;
-  delete(entity: string, id: string): Promise<any>;
-  deleteMany(entity: string, ids: string[]): Promise<any>;
+  delete(entity: string, id: string, config?: EntityConfig): Promise<any>;
+  deleteMany(entity: string, ids: string[], config?: EntityConfig): Promise<any>;
 }
 
 export interface ServerCrudLogger {
@@ -79,13 +80,31 @@ const DEFAULT_SYSTEM_FIELDS = [
 
 const MAX_PAGE_SIZE = 200;
 
-// Default plural→model resolver: strip trailing "s", camelCase kebab. Apps with
-// irregular names pass a map: getModelName(entity, { "fee-schedules": "feeSchedule" }).
+// Default plural→model resolver: strip trailing "s", camelCase kebab. Ưu tiên
+// khai `modelName` ngay trong EntityConfig; map ở đây chỉ còn cho chỗ gọi cũ
+// chưa có config trong tay.
 export function getModelName(entity: string, map?: Record<string, string>): string {
   if (map && map[entity]) return map[entity];
   return entity.replace(/s$/, "").replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
 
+// Ép id từ URL theo idKind của entity — "abc" vào cột Int phải trả 400 rõ
+// ràng thay vì để Prisma nổ 500.
+function coerceIdParam(
+  entity: string,
+  config: EntityConfig | undefined,
+  id: string,
+): string | number {
+  if (config?.idKind !== "int") return id;
+  const num = Number(id);
+  if (!Number.isInteger(num)) {
+    throw new CrudRequestError(
+      `Id không hợp lệ cho "${entity}": "${id}" (idKind=int cần số nguyên)`,
+    );
+  }
+  return num;
+}
+
 // Opt-in audit-name resolver. Overwrites createdByName/updatedByName from a User
 // model. `nameField` handles schema drift (vinhhoa: "name", wu: "fullName").
 export function createAuditUserNameResolver(opts: {
@@ -130,18 +149,18 @@ export function createServerCrudService(deps: ServerCrudDeps): ServerCrudService
 
   const systemFields = deps.systemFields ?? DEFAULT_SYSTEM_FIELDS;
 
-  const model = (entity: string, client: PrismaLike = prisma) => {
-    const name = resolveModel(entity);
+  // config.modelName thắng convention/MODEL_MAP — một registry duy nhất ở
+  // entity config, app không phải nuôi map song song.
+  const model = (entity: string, config?: EntityConfig, client: PrismaLike = prisma) => {
+    const name = config?.modelName ?? resolveModel(entity);
     const m = client[name];
     if (!m) throw new Error(`Prisma model not found for entity: ${entity} (${name})`);
     return m;
   };
 
-
-
   return {
     async list(entity, config, params) {
-      const prismaModel = model(entity);
+      const prismaModel = model(entity, config);
       
       const {
         where,
@@ -174,12 +193,13 @@ export function createServerCrudService(deps: ServerCrudDeps): ServerCrudService
     },
 
     async getById(entity, id, config) {
-      const prismaModel = model(entity);
+      const prismaModel = model(entity, config);
       // Áp cùng include như list — detail dialog hiện label relation thay raw FK id.
       const include: any = {};
       if (config?.include?.length) config.include.forEach((inc) => (include[inc] = true));
       const includeOption = Object.keys(include).length ? { include } : {};
-      const result = await prismaModel.findUnique({ where: { id }, ...includeOption });
+      const where = { [config?.idField ?? "id"]: coerceIdParam(entity, config, id) };
+      const result = await prismaModel.findUnique({ where, ...includeOption });
       if (!result) return null;
       const serialized = serializeDecimalFields(result);
       const [resolved] = await resolveAuditNames([serialized]);
@@ -187,7 +207,7 @@ export function createServerCrudService(deps: ServerCrudDeps): ServerCrudService
     },
 
     async create(entity, data, config, tx) {
-      const prismaModel = model(entity, tx ?? prisma);
+      const prismaModel = model(entity, config, tx ?? prisma);
       try {
         const prismaData = prepareMutationData({
           data,
@@ -206,7 +226,8 @@ export function createServerCrudService(deps: ServerCrudDeps): ServerCrudService
     },
 
     async update(entity, id, data, config, tx) {
-      const prismaModel = model(entity, tx ?? prisma);
+      const prismaModel = model(entity, config, tx ?? prisma);
+      const where = { [config?.idField ?? "id"]: coerceIdParam(entity, config, id) };
       try {
         const prismaData = prepareMutationData({
           data,
@@ -216,27 +237,31 @@ export function createServerCrudService(deps: ServerCrudDeps): ServerCrudService
           relationFieldSkip: deps.relationFieldSkip,
           logger: log,
         });
-        return serializeDecimalFields(await prismaModel.update({ where: { id }, data: prismaData }));
+        return serializeDecimalFields(await prismaModel.update({ where, data: prismaData }));
       } catch (error) {
         log.error(`Error updating ${entity}:`, error);
         throw error;
       }
     },
 
-    async delete(entity, id) {
-      const prismaModel = model(entity);
+    async delete(entity, id, config) {
+      const prismaModel = model(entity, config);
+      const where = { [config?.idField ?? "id"]: coerceIdParam(entity, config, id) };
       try {
-        return await prismaModel.delete({ where: { id } });
+        return await prismaModel.delete({ where });
       } catch (error) {
         log.error(`Error deleting ${entity}:`, error);
         throw error;
       }
     },
 
-    async deleteMany(entity, ids) {
-      const prismaModel = model(entity);
+    async deleteMany(entity, ids, config) {
+      const prismaModel = model(entity, config);
+      // Ép cả mảng — một phần tử sai định dạng là 400 cả request, không xóa nửa vời.
+      const idField = config?.idField ?? "id";
+      const where = { [idField]: { in: ids.map((id) => coerceIdParam(entity, config, id)) } };
       try {
-        return await prismaModel.deleteMany({ where: { id: { in: ids } } });
+        return await prismaModel.deleteMany({ where });
       } catch (error) {
         log.error(`Error deleting many ${entity}:`, error);
         throw error;

package/src/crud/server.ts

@@ -22,6 +22,16 @@ export type {
 export {
   createCrudCollectionHandlers,
   createCrudItemHandlers,
+  createCrudExportHandler,
+  createCrudImportHandler,
 } from './crud-route-handlers'
-export type { CrudHandlerDeps } from './crud-route-handlers'
+export type {
+  CrudHandlerDeps,
+  CrudExportHandlerDeps,
+  CrudImportHandlerDeps,
+} from './crud-route-handlers'
+export { readImportRows, coerceBooleanCell } from './lib/import-request'
 export { compileFilterTree, conditionForOperator, type FilterTreeLeaf, type FilterTreeNode } from "./lib/filter-tree";
+export { CrudRequestError } from "./lib/errors";
+export { coerceFieldValue } from "./lib/coerce";
+export { getEntityEndpoints } from "./lib/entity-endpoints";

package/src/guardrails/rules/design.ts

@@ -72,12 +72,13 @@ export const designRules: GuardrailRule[] = [
 
   {
     id: "design/list-table-uses-kit",
-    title: "bảng mới trong app/ dùng DataTableWrapper, không tự dựng <Table>",
+    title:
+      "bảng mới trong app/ dùng DataTable (@goerp/core/ui — import { DataTable }), không tự dựng <Table>",
     why:
       "Bảng tự dựng lại thiếu một trong: header dính, phân trang, trạng thái " +
       "rỗng, hàng bấm được, footer tổng. Mỗi bảng thiếu một thứ khác nhau, và " +
       "người dùng học lại thao tác ở mỗi trang.",
-    fix: "Dùng `DataTableWrapper` + cột tanstack trong `*-columns.tsx`. Thật sự phải tự dựng thì thêm vào allowlist kèm lý do.",
+    fix: "Dùng `DataTable` (@goerp/core/ui — `import { DataTable }`) + cột tanstack trong `*-columns.tsx`. Thật sự phải tự dựng thì thêm vào allowlist kèm lý do.",
     run(ctx) {
       const allowed = new Set(ctx.options.allowlists["design/list-table-uses-kit"] ?? []);
       const handRolled = ctx.files

package/src/styles/base.css

@@ -108,6 +108,22 @@
   --radius-md: calc(var(--radius) - 2px);
   --radius-sm: calc(var(--radius) - 4px);
 
+  /* Màn trạng thái (404/403/400/lỗi): hình và chữ nổi lên MỘT lần lúc mở.
+     Dùng kèm `motion-safe:` — người bật "giảm chuyển động" thấy trang tĩnh. */
+  --animate-status-in: status-in 0.34s cubic-bezier(0.22, 1, 0.36, 1) both;
+
+  @keyframes status-in {
+    from {
+      opacity: 0;
+      transform: translateY(6px);
+    }
+
+    to {
+      opacity: 1;
+      transform: none;
+    }
+  }
+
   --animate-accordion-down: accordion-down 0.2s ease-out;
   --animate-accordion-up: accordion-up 0.2s ease-out;
   --animate-collapsible-down: collapsible-down 0.2s ease-out;

package/src/types/index.ts

@@ -302,7 +302,28 @@ export interface EntityConfig {
    */
   permissionResource?: string;
   apiEndpoint: string;
+  /**
+   * Endpoint import/export. Không khai thì suy từ apiEndpoint theo CÙNG MỘT
+   * quy tắc: `${base}/import|/export` (giữ nguyên query params nếu có) —
+   * xem getEntityEndpoints ở crud/lib/entity-endpoints.
+   */
+  endpoints?: {
+    import?: string;
+    export?: string;
+  };
+  /**
+   * Tên model Prisma (camelCase, vd "jobTitle"). Không khai thì engine suy
+   * theo convention từ entity key (bỏ "s" cuối + camelCase kebab) — khai ở
+   * đây thay cho MODEL_MAP riêng phía app.
+   */
+  modelName?: string;
   idField: string;
+  /**
+   * Kiểu khóa chính. "string" (default): create thiếu id sẽ tự sinh UUID.
+   * "int": KHÔNG BAO GIỜ tự sinh (DB autoincrement), id trên URL được ép
+   * Number — sai định dạng trả 400.
+   */
+  idKind?: "string" | "int";
   displayField: string;
   fields: FieldConfig[];
   filters?: FilterConfig[];
@@ -345,19 +366,32 @@ export interface FormModeConfig {
   sheetSide?: "top" | "right" | "bottom" | "left";
 }
 
+/** Các action built-in có icon + hành vi mặc định trong CrudPage/CrudRowActions. */
+export type BuiltinRowActionKind =
+  | "copy"
+  | "duplicate"
+  | "view"
+  | "archive"
+  | "custom"
+  | "approve"
+  | "reject"
+  | "set-default"
+  | "view-history";
+
 export interface RowAction {
   label: string;
   icon?: string;
-  action:
-    | "copy"
-    | "duplicate"
-    | "view"
-    | "archive"
-    | "custom"
-    | "approve"
-    | "reject"
-    | "set-default"
-    | "view-history";
+  /**
+   * Built-in giữ hành vi/icon cũ; chuỗi tự do = action tự khai — đi kèm
+   * `urlTemplate` (dispatcher HTTP của CrudPage) hoặc handler app-side.
+   * `(string & {})` để vẫn gợi ý được literal built-in.
+   */
+  action: BuiltinRowActionKind | (string & {});
+  /**
+   * handler/visibleWhen/transformData KHÔNG sống sót qua serializeConfig
+   * (RSC → client) — chỉ dùng khi config đi thẳng vào CrudPage phía client.
+   * Cần action serialize an toàn thì dùng bộ urlTemplate/method bên dưới.
+   */
   handler?: (
     rowId: string,
     rowData: Record<string, unknown>,
@@ -372,6 +406,24 @@ export interface RowAction {
     | "link";
   excludeFields?: string[];
   transformData?: (rowData: Record<string, unknown>) => Record<string, unknown>;
+
+  // ── Biến thể HTTP thuần data (serialize qua RSC được) ──
+  /** URL gọi khi bấm — "{id}" được thay bằng id dòng, vd "/api/employees/{id}/reset-password". */
+  urlTemplate?: string;
+  /** Method cho urlTemplate. Default: POST. */
+  method?: "POST" | "PATCH" | "DELETE";
+  /** Có khai thì window.confirm trước khi gọi. */
+  confirmMessage?: string;
+  /** Toast khi thành công. Không khai thì dùng message "updated" chung. */
+  successMessage?: string;
+  /**
+   * Gate hiển thị + thực thi theo action code trong quyền. Nhận cả 8 action
+   * CRUD chuẩn ("update", "approve"…) lẫn CUSTOM ACTION khai trong registry
+   * ("reset-password", "resync"…) — EntityCrudPage tự gom các permissionAction
+   * custom trong rowActions và hỏi checkPermission cho từng cái. Fail-closed:
+   * action không có trong map quyền thì nút bị chặn.
+   */
+  permissionAction?: string;
 }
 
 // ============================================================================
@@ -402,6 +454,13 @@ export interface FieldConfig {
   name: string;
   label: string;
   type: FieldType;
+  /**
+   * Kiểu GIÁ TRỊ thô của field khi kiểu cột không suy được từ `type` — cột FK
+   * Int autoincrement hiện qua select/multiselect/relation: form và URL chở
+   * chuỗi "3", khai `valueType: "int"` để coercion tập trung (coerceFieldValue)
+   * ép Number trước khi vào Prisma. Default: "string" (giữ nguyên).
+   */
+  valueType?: "string" | "int";
   required?: boolean;
   defaultValue?: unknown;
   placeholder?: string;
@@ -658,6 +717,12 @@ export interface CrudPermissions {
   import?: boolean;
   approve?: boolean;
   reject?: boolean;
+  /**
+   * Custom action từ registry (vd "reset-password") — getCrudPermissions nhận
+   * danh sách extraActions và điền vào đây; RowAction.permissionAction tra
+   * thẳng map này, thiếu key = false (fail-closed).
+   */
+  [action: string]: boolean | undefined;
 }
 
 export interface CrudFeatures {