@goplusvn/core 0.1.58 → 0.1.59

package/PLATFORM.md

@@ -255,6 +255,71 @@ until `clearCache()`. The public endpoint is used for presigning only —
 a presigned signature is bound to the host that signed it, so signing with the
 internal endpoint yields URLs the browser cannot use.
 
+## Branch scope
+
+Multi-branch data visibility (`@goerp/core/branch-scope`). Two layers, on
+purpose — the second exists because the first is something a new route can
+simply forget.
+
+**Layer 1 — explicit filtering.** Every page/route/service that lists records
+does `const scope = await getBranchScope(session)` then spreads
+`scopedBranchWhere(scope)` into its `where`. `scopedBranchWhere` returns `{}`
+for view-all users, so there is no branching at the call site. Related helpers:
+`canAccessBranch(scope, row.branchId)` for detail pages, `clampBranchFilter`
+for a branch filter the client sent (out-of-scope selections collapse to the
+sentinel — 0 rows, never "no filter"), `clampIdFilter` for branch-owned things
+like warehouses. Records with `branchId: null` are treated as shared and stay
+visible to everyone.
+
+**Layer 2 — the safety net.** `createBranchGuardExtension({ models })` is a
+Prisma extension that ANDs the branch condition onto read operations
+(`findMany`, `findFirst`, `findFirstOrThrow`, `count`, `aggregate`, `groupBy`)
+for the declared models. It only acts inside a request context opened by the
+app's api-handler, so RSC pages, cron, webhooks and scripts see unfiltered data
+and must use layer 1. `findUnique*` is deliberately not guarded (its `where`
+only takes unique fields) — guard detail pages with `canAccessBranch`.
+
+Wiring, all in the app's composition root:
+
+```ts
+// src/lib/branch-scope.ts — the ONE door; nothing else imports the core module
+configureBranchScope<Session>({
+  getUserId: (session) => session.user?.id,
+  canViewAll: (session) => session.user.roles.includes("admin"),
+  getAllowedBranchIds: (session) => session.user.branches, // or pass `db` instead
+})
+
+// src/lib/prisma.ts
+db = rawClient.$extends(createBranchGuardExtension({ models: ["Invoice"] }))
+
+// src/lib/api-handler.ts (middleware) — resolve is lazy, so a request that
+// never touches a guarded model costs nothing
+runWithBranchScope({ resolve: () => getBranchScope(session) }, () => next())
+```
+
+Either give `configureBranchScope` a `db` (it reads `user_branches`) or
+`getAllowedBranchIds` when the session already carries the list.
+
+Three traps, each of which has cost a real incident:
+
+- **A guarded model MUST have a `branchId` column**, or you must route it
+  through a relation: `buildWhere: (model, scope) => model === "GoodsReceipt" ?
+  scopedBranchWhere(scope, "warehouse") : null`. Declare a model without the
+  column and Prisma throws a validation error on *every* read a scoped user
+  makes — a blank app, not a few missing rows.
+- **Document numbering must escape the guard.** `MAX(number)` filtered by
+  branch produces duplicate numbers and a unique violation. Wrap those queries
+  in `runWithoutBranchScope(...)`.
+- **"No branches assigned" means zero rows, not everything.** That is what
+  `NO_BRANCH_ACCESS` encodes; an empty `in: []` is ambiguous in Prisma and one
+  mistake there exposes the whole table.
+
+`runWithBranchScope` / `runWithoutBranchScope` pin a returned thenable to the
+context before handing it back, so `runWithoutBranchScope(() => db.doc.aggregate(…))`
+works even though a PrismaPromise does not run until it is awaited — otherwise
+the query would execute wherever the caller happened to await it, i.e. in the
+wrong scope.
+
 ## Utils
 
 `@goerp/core/utils` (formatCurrency, formatDate, cn, …) plus the granular:

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.58",
+  "version": "0.1.59",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/branch-scope/__tests__/branch-scope.test.ts

@@ -0,0 +1,288 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  getBranchScopeContext,
+  resolveAmbientBranchScope,
+  runWithBranchScope,
+  runWithoutBranchScope,
+  type BranchScopeContext,
+} from "../context";
+import { createBranchGuardExtension } from "../guard";
+import {
+  canAccessBranch,
+  clampBranchFilter,
+  clampIdFilter,
+  configureBranchScope,
+  getBranchScope,
+  scopedBranchWhere,
+} from "../scope";
+import { NO_BRANCH_ACCESS, type BranchScope } from "../types";
+
+const scoped: BranchScope = { canViewAll: false, allowedBranchIds: ["b1", "b2"] };
+const viewAll: BranchScope = { canViewAll: true };
+
+interface FakeSession {
+  id?: string;
+  admin?: boolean;
+}
+
+function configure(rows: { branchId: string | null }[]) {
+  const findMany = vi.fn(async () => rows);
+  configureBranchScope<FakeSession>({
+    db: { userBranch: { findMany } },
+    getUserId: (s) => s.id,
+    canViewAll: (s) => Boolean(s.admin),
+  });
+  return findMany;
+}
+
+describe("getBranchScope", () => {
+  it("người xem-tất không tốn truy vấn user_branches", async () => {
+    const findMany = configure([]);
+    expect(await getBranchScope({ id: "u1", admin: true })).toEqual({
+      canViewAll: true,
+    });
+    expect(findMany).not.toHaveBeenCalled();
+  });
+
+  it("lấy đúng chi nhánh được gán", async () => {
+    configure([{ branchId: "b1" }, { branchId: "b2" }]);
+    expect(await getBranchScope({ id: "u1" })).toEqual({
+      canViewAll: false,
+      allowedBranchIds: ["b1", "b2"],
+    });
+  });
+
+  it("chưa gán chi nhánh nào → sentinel = thấy 0 dòng, KHÔNG phải thấy tất", async () => {
+    configure([]);
+    expect(await getBranchScope({ id: "u1" })).toEqual({
+      canViewAll: false,
+      allowedBranchIds: [NO_BRANCH_ACCESS],
+    });
+  });
+
+  it("session không có userId → sentinel (không tra DB bằng undefined)", async () => {
+    const findMany = configure([{ branchId: "b1" }]);
+    expect(await getBranchScope({})).toEqual({
+      canViewAll: false,
+      allowedBranchIds: [NO_BRANCH_ACCESS],
+    });
+    expect(findMany).not.toHaveBeenCalled();
+  });
+});
+
+describe("scopedBranchWhere", () => {
+  it("xem tất → không thêm điều kiện", () => {
+    expect(scopedBranchWhere(viewAll)).toEqual({});
+  });
+
+  it("có phạm vi → CN được gán + bản ghi chưa gắn CN (dùng chung)", () => {
+    expect(scopedBranchWhere(scoped)).toEqual({
+      OR: [{ branchId: { in: ["b1", "b2"] } }, { branchId: null }],
+    });
+  });
+
+  it("scope qua quan hệ cho model không có cột branchId", () => {
+    expect(scopedBranchWhere(scoped, "warehouse")).toEqual({
+      OR: [
+        { warehouse: { branchId: { in: ["b1", "b2"] } } },
+        { warehouse: { branchId: null } },
+      ],
+    });
+  });
+});
+
+describe("canAccessBranch", () => {
+  it("xem tất → qua hết", () => {
+    expect(canAccessBranch(viewAll, "x")).toBe(true);
+  });
+  it("bản ghi không gắn CN = dùng chung", () => {
+    expect(canAccessBranch(scoped, null)).toBe(true);
+  });
+  it("đúng/sai theo danh sách được gán", () => {
+    expect(canAccessBranch(scoped, "b1")).toBe(true);
+    expect(canAccessBranch(scoped, "x")).toBe(false);
+  });
+});
+
+describe("kẹp bộ lọc client gửi lên", () => {
+  it("clampBranchFilter: giữ nguyên khi xem tất, lọc bỏ CN ngoài phạm vi", () => {
+    expect(clampBranchFilter(["x"], viewAll)).toEqual(["x"]);
+    expect(clampBranchFilter(["b1", "x"], scoped)).toEqual(["b1"]);
+  });
+
+  it("clampBranchFilter: toàn bộ ngoài phạm vi → sentinel, không rơi về không-lọc", () => {
+    expect(clampBranchFilter(["x", "y"], scoped)).toEqual([NO_BRANCH_ACCESS]);
+  });
+
+  it("clampBranchFilter: không lọc gì → undefined (phạm vi đã lo)", () => {
+    expect(clampBranchFilter(undefined, scoped)).toBeUndefined();
+    expect(clampBranchFilter("", scoped)).toBeUndefined();
+  });
+
+  it("clampIdFilter: ngoài danh sách cho phép → sentinel", () => {
+    expect(clampIdFilter(["w1", "x"], ["w1", "w2"])).toEqual(["w1"]);
+    expect(clampIdFilter(["x"], ["w1"])).toEqual([NO_BRANCH_ACCESS]);
+  });
+});
+
+describe("context", () => {
+  it("ngoài context → undefined (extension bất động cho cron/script)", () => {
+    expect(getBranchScopeContext()).toBeUndefined();
+    expect(resolveAmbientBranchScope()).toBeUndefined();
+  });
+
+  it("resolve lười và cache trong 1 request", async () => {
+    const resolve = vi.fn(async () => scoped);
+    await runWithBranchScope({ resolve }, async () => {
+      expect(resolve).not.toHaveBeenCalled();
+      expect(await resolveAmbientBranchScope()).toBe(scoped);
+      expect(await resolveAmbientBranchScope()).toBe(scoped);
+      expect(resolve).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("context sống qua await bên trong (PrismaPromise phải await TRONG context)", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, async () => {
+      await Promise.resolve();
+      expect(getBranchScopeContext()).toBeDefined();
+    });
+  });
+
+  it("runWithoutBranchScope thoát guard rồi trả lại context", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, async () => {
+      await runWithoutBranchScope(async () => {
+        await Promise.resolve();
+        expect(getBranchScopeContext()).toBeUndefined();
+        expect(resolveAmbientBranchScope()).toBeUndefined();
+      });
+      expect(getBranchScopeContext()).toBeDefined();
+    });
+  });
+
+  /**
+   * PrismaPromise lười: truy vấn chạy ở lần `.then()` đầu tiên, không phải lúc
+   * gọi `db.receipt.count()`. Giả lập đúng như vậy để chốt rằng callback KHÔNG
+   * async cũng chạy trong đúng phạm vi.
+   */
+  function lazyQuery(): Promise<BranchScopeContext | undefined> {
+    let started: Promise<BranchScopeContext | undefined> | undefined;
+    const thenable: PromiseLike<BranchScopeContext | undefined> = {
+      then(onFulfilled, onRejected) {
+        // Ngữ cảnh được chốt tại đây — chỗ đầu tiên ai đó await.
+        started ??= Promise.resolve(getBranchScopeContext());
+        return started.then(onFulfilled, onRejected);
+      },
+    };
+    // PrismaPromise cũng khai kiểu Promise nhưng chỉ chạy ở `.then` đầu tiên.
+    return thenable as Promise<BranchScopeContext | undefined>;
+  }
+
+  it("callback KHÔNG async trả PrismaPromise vẫn chạy TRONG context", async () => {
+    const ctx = await runWithBranchScope({ resolve: async () => scoped }, () =>
+      lazyQuery(),
+    );
+    expect(ctx).toBeDefined();
+  });
+
+  it("runWithoutBranchScope: callback KHÔNG async vẫn thoát guard", async () => {
+    const ctx = await runWithBranchScope(
+      { resolve: async () => scoped },
+      async () => runWithoutBranchScope(() => lazyQuery()),
+    );
+    expect(ctx).toBeUndefined();
+  });
+
+  it("giá trị đồng bộ đi qua nguyên vẹn (không bị bọc thành promise)", () => {
+    expect(runWithoutBranchScope(() => 42)).toBe(42);
+  });
+});
+
+describe("createBranchGuardExtension", () => {
+  const ext = createBranchGuardExtension({
+    models: ["Receipt", "GoodsReceipt"],
+    buildWhere: (model, scope) =>
+      model === "GoodsReceipt" ? scopedBranchWhere(scope, "warehouse") : null,
+  });
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const run = ext.query.$allModels.$allOperations as (a: any) => Promise<any>;
+
+  let seen: unknown;
+  const query = vi.fn(async (args: unknown) => {
+    seen = args;
+    return "ok";
+  });
+
+  beforeEach(() => {
+    seen = undefined;
+    query.mockClear();
+  });
+
+  const call = (model: string, operation: string, args: unknown) =>
+    run({ model, operation, args, query });
+
+  it("model ngoài danh sách → đi thẳng", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, () =>
+      call("Customer", "findMany", { where: { name: "a" } }),
+    );
+    expect(seen).toEqual({ where: { name: "a" } });
+  });
+
+  it("thao tác ghi và findUnique → không đụng vào", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, async () => {
+      await call("Receipt", "findUnique", { where: { id: "r1" } });
+      expect(seen).toEqual({ where: { id: "r1" } });
+      await call("Receipt", "update", { where: { id: "r1" }, data: {} });
+      expect(seen).toEqual({ where: { id: "r1" }, data: {} });
+    });
+  });
+
+  it("ngoài context (cron/script) → không cắt dữ liệu", async () => {
+    await call("Receipt", "findMany", { where: { a: 1 } });
+    expect(seen).toEqual({ where: { a: 1 } });
+  });
+
+  it("xem tất → không thêm điều kiện", async () => {
+    await runWithBranchScope({ resolve: async () => viewAll }, () =>
+      call("Receipt", "findMany", { where: { a: 1 } }),
+    );
+    expect(seen).toEqual({ where: { a: 1 } });
+  });
+
+  it("AND thêm điều kiện chi nhánh, GIỮ nguyên where cũ", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, () =>
+      call("Receipt", "findMany", { where: { status: "paid" } }),
+    );
+    expect(seen).toEqual({
+      where: {
+        AND: [
+          { status: "paid" },
+          { OR: [{ branchId: { in: ["b1", "b2"] } }, { branchId: null }] },
+        ],
+      },
+    });
+  });
+
+  it("không có where sẵn → guard trở thành where", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, () =>
+      call("Receipt", "count", {}),
+    );
+    expect(seen).toEqual({
+      where: { OR: [{ branchId: { in: ["b1", "b2"] } }, { branchId: null }] },
+    });
+  });
+
+  it("buildWhere riêng cho model không có cột branchId (chèn cột không tồn tại = Prisma ném lỗi cho MỌI truy vấn)", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, () =>
+      call("GoodsReceipt", "findMany", {}),
+    );
+    expect(seen).toEqual({
+      where: {
+        OR: [
+          { warehouse: { branchId: { in: ["b1", "b2"] } } },
+          { warehouse: { branchId: null } },
+        ],
+      },
+    });
+  });
+});

package/src/branch-scope/context.ts

@@ -0,0 +1,66 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import type { BranchScope } from "./types";
+
+/**
+ * Context của lưới an toàn lớp 2. `apiHandler` mở context cho MỌI request đã
+ * xác thực; extension branch-guard đọc ở đây.
+ *
+ * Phạm vi được resolve LƯỜI — lần đầu một model bị guard thực sự được đọc.
+ * Request không đụng model nào bị guard thì không tốn thêm truy vấn nào.
+ *
+ * File này cố ý không import phần scope: composition root của app tiêm hàm
+ * `resolve` vào lúc mở context, nhờ vậy context không kéo theo prisma và không
+ * tạo vòng import.
+ */
+
+export interface BranchScopeContext {
+  resolve: () => Promise<BranchScope>;
+  /** Cache trong phạm vi 1 request — extension gán ở lần resolve đầu. */
+  cached?: Promise<BranchScope>;
+}
+
+const store = new AsyncLocalStorage<BranchScopeContext>();
+
+/**
+ * PrismaPromise là LƯỜI: truy vấn chỉ thật sự chạy ở lần `.then()` đầu tiên.
+ * `run(ctx, () => db.receipt.count())` trả promise chưa chạy ra ngoài, người gọi
+ * `await` bên ngoài → truy vấn chạy NGOÀI context → guard im lặng không lọc
+ * (và với `exit` thì ngược lại: truy vấn cần toàn cục lại bị lọc → trùng số
+ * phiếu). Gọi `.then` ngay tại đây, khi còn ở trong/ngoài context đúng như ý,
+ * để việc chạy được ghim vào đúng phạm vi — bất kể người gọi await ở đâu.
+ */
+function pinToCurrentContext<T>(result: T): T {
+  const thenable = result as { then?: unknown };
+  if (typeof thenable?.then !== "function") return result;
+  return (result as unknown as Promise<unknown>).then((value) => value) as T;
+}
+
+export function runWithBranchScope<T>(
+  context: BranchScopeContext,
+  fn: () => T | Promise<T>,
+): T | Promise<T> {
+  return store.run(context, () => pinToCurrentContext(fn()));
+}
+
+export function getBranchScopeContext(): BranchScopeContext | undefined {
+  return store.getStore();
+}
+
+/** Phạm vi của request hiện tại (resolve + cache); undefined khi ở ngoài context. */
+export function resolveAmbientBranchScope(): Promise<BranchScope> | undefined {
+  const ctx = store.getStore();
+  if (!ctx) return undefined;
+  ctx.cached ??= ctx.resolve();
+  return ctx.cached;
+}
+
+/**
+ * Chạy `fn` NGOÀI lưới guard — cho truy vấn hạ tầng mà kết quả phải toàn cục
+ * bất kể phạm vi user. Ca kinh điển: đánh số phiếu (`MAX(number)` bị lọc theo
+ * chi nhánh là sinh trùng số → lỗi unique). Mọi `await` bên trong đều thoát
+ * guard, nên chỉ bọc đúng truy vấn cần toàn cục, đừng bọc cả handler.
+ */
+export function runWithoutBranchScope<T>(fn: () => T): T {
+  return store.exit(() => pinToCurrentContext(fn()));
+}

package/src/branch-scope/guard.ts

@@ -0,0 +1,100 @@
+import { resolveAmbientBranchScope } from "./context";
+import { scopedBranchWhere } from "./scope";
+
+import type { BranchScope } from "./types";
+
+/**
+ * LỚP 2 — lưới an toàn ở tầng ORM (mô hình Odoo/NocoBase): route mới quên lọc
+ * chi nhánh thì vẫn không lộ dữ liệu.
+ *
+ * Chỉ chạm thao tác ĐỌC, chỉ trên model được khai, và chỉ khi có
+ * BranchScopeContext — ngoài context (RSC page, cron, webhook, script) extension
+ * bất động, nên tác vụ nền không bị cắt dữ liệu bất ngờ.
+ *
+ *   db.$extends(createBranchGuardExtension({
+ *     models: ["Receipt", "Expense", "CashCount"],
+ *     // model không có cột branchId thì khai đường đi riêng:
+ *     buildWhere: (model, scope) =>
+ *       model === "GoodsReceipt" ? scopedBranchWhere(scope, "warehouse") : null,
+ *   }))
+ *
+ * CẢNH BÁO: model đưa vào `models` PHẢI có cột branchId, hoặc phải có nhánh
+ * riêng trong `buildWhere`. Chèn điều kiện lên cột không tồn tại là Prisma ném
+ * validation error cho MỌI thao tác đọc của user bị scope — nghĩa là hỏng cả
+ * nghiệp vụ, không chỉ hỏng bộ lọc.
+ */
+
+export interface BranchGuardOptions {
+  /** Tên model Prisma (đúng chữ hoa/thường như trong schema). */
+  models: string[];
+  /**
+   * Điều kiện guard riêng theo model; trả `null` để dùng mặc định (cột
+   * branchId trực tiếp + cho phép null = dùng chung).
+   */
+  buildWhere?: (
+    model: string,
+    scope: BranchScope,
+  ) => Record<string, unknown> | null;
+  /** Mặc định: các thao tác đọc nhiều dòng. */
+  operations?: string[];
+}
+
+/**
+ * findUnique* cố ý không guard: `where` của nó chỉ nhận unique field, chèn thêm
+ * điều kiện là Prisma từ chối. Trang chi tiết guard bằng `canAccessBranch`.
+ * Mutation cũng không guard — create ghi vào chi nhánh của user, update/delete
+ * đi qua kiểm tra quyền riêng.
+ */
+const DEFAULT_OPERATIONS = [
+  "findMany",
+  "findFirst",
+  "findFirstOrThrow",
+  "count",
+  "aggregate",
+  "groupBy",
+];
+
+export function createBranchGuardExtension(options: BranchGuardOptions) {
+  const models = new Set(options.models);
+  const operations = new Set(options.operations ?? DEFAULT_OPERATIONS);
+  const buildWhere = options.buildWhere;
+
+  return {
+    name: "branch-guard",
+    query: {
+      $allModels: {
+        // Chữ ký thật do Prisma sinh theo schema của từng app; khai chặt ở core
+        // sẽ không assignable ở phía app (kiểu hẹp hơn, contravariance).
+        /* eslint-disable @typescript-eslint/no-explicit-any */
+        async $allOperations({
+          model,
+          operation,
+          args,
+          query,
+        }: {
+          model?: string;
+          operation: string;
+          args: any;
+          query: (args: any) => Promise<any>;
+        }): Promise<any> {
+          if (!model || !models.has(model)) return query(args);
+          if (!operations.has(operation)) return query(args);
+
+          const scopePromise = resolveAmbientBranchScope();
+          if (!scopePromise) return query(args);
+
+          const scope = await scopePromise;
+          if (scope.canViewAll) return query(args);
+
+          const guard = buildWhere?.(model, scope) ?? scopedBranchWhere(scope);
+          const prevWhere = args?.where;
+          return query({
+            ...args,
+            where: prevWhere ? { AND: [prevWhere, guard] } : guard,
+          });
+        },
+        /* eslint-enable @typescript-eslint/no-explicit-any */
+      },
+    },
+  };
+}

package/src/branch-scope/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Phạm vi dữ liệu theo chi nhánh — hai lớp:
+ *
+ *   Lớp 1 (tường minh): `getBranchScope(session)` + `scopedBranchWhere(scope)`
+ *   trong page/route/service. Đây mới là lớp làm việc chính.
+ *
+ *   Lớp 2 (lưới an toàn): `createBranchGuardExtension` cắm vào Prisma, tự AND
+ *   điều kiện chi nhánh cho thao tác đọc trên model được khai — cứu chỗ quên.
+ *
+ * App cấu hình một lần ở composition root và import phạm vi qua đúng file đó
+ * (`src/lib/branch-scope.ts`), giống kho tập tin: engine là singleton, import
+ * thẳng từ core sẽ lấy được hàm nhưng bỏ lỡ lời gọi cấu hình.
+ */
+export {
+  configureBranchScope,
+  canViewAllBranches,
+  getBranchScope,
+  canAccessBranch,
+  scopedBranchWhere,
+  clampBranchFilter,
+  clampIdFilter,
+} from "./scope";
+
+export {
+  runWithBranchScope,
+  getBranchScopeContext,
+  resolveAmbientBranchScope,
+  runWithoutBranchScope,
+  type BranchScopeContext,
+} from "./context";
+
+export {
+  createBranchGuardExtension,
+  type BranchGuardOptions,
+} from "./guard";
+
+export {
+  NO_BRANCH_ACCESS,
+  type BranchScope,
+  type BranchScopeConfig,
+  type BranchScopeDb,
+} from "./types";

package/src/branch-scope/scope.ts

@@ -0,0 +1,149 @@
+import {
+  NO_BRANCH_ACCESS,
+  type BranchScope,
+  type BranchScopeConfig,
+} from "./types";
+
+/**
+ * LỚP 1 — lọc tường minh. Page/route/service gọi `getBranchScope(session)` rồi
+ * nhét `scopedBranchWhere(scope)` vào `where`. Lớp 2 (branch-guard extension)
+ * là lưới an toàn cho chỗ quên, KHÔNG phải thay thế lớp này: guard chỉ chạm các
+ * model được khai và chỉ trong request đi qua apiHandler.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let configured: BranchScopeConfig<any> | null = null;
+
+export function configureBranchScope<TSession>(
+  config: BranchScopeConfig<TSession>,
+): void {
+  configured = config;
+}
+
+function requireConfigured() {
+  if (!configured) {
+    throw new Error(
+      "[branch-scope] chưa configureBranchScope(...) — gọi một lần ở composition root (src/lib/branch-scope.ts) rồi import phạm vi qua đúng file đó.",
+    );
+  }
+  return configured;
+}
+
+export function canViewAllBranches<TSession>(session: TSession): boolean {
+  return requireConfigured().canViewAll(session);
+}
+
+/**
+ * Phạm vi chi nhánh của user. Chưa được gán chi nhánh nào → sentinel, tức thấy
+ * 0 dòng — KHÔNG phải "thấy tất": mặc định an toàn là không thấy gì.
+ */
+export async function getBranchScope<TSession>(
+  session: TSession,
+): Promise<BranchScope> {
+  const config = requireConfigured();
+  if (config.canViewAll(session)) return { canViewAll: true };
+
+  const branchIds = await readAllowedBranchIds(config, session);
+
+  return {
+    canViewAll: false,
+    allowedBranchIds: branchIds.length > 0 ? branchIds : [NO_BRANCH_ACCESS],
+  };
+}
+
+async function readAllowedBranchIds<TSession>(
+  config: BranchScopeConfig<TSession>,
+  session: TSession,
+): Promise<string[]> {
+  if (config.getAllowedBranchIds) {
+    const ids = await config.getAllowedBranchIds(session);
+    return (ids ?? []).filter((id): id is string => Boolean(id));
+  }
+
+  const userId = config.getUserId(session);
+  if (!userId) return [];
+
+  if (!config.db) {
+    throw new Error(
+      "[branch-scope] configureBranchScope cần `db` (hoặc `getAllowedBranchIds`) để biết user thuộc chi nhánh nào.",
+    );
+  }
+  const rows = await config.db.userBranch.findMany({
+    where: { userId },
+    select: { branchId: true },
+  });
+  return rows
+    .map((row) => (row as { branchId?: string | null }).branchId)
+    .filter((id): id is string => Boolean(id));
+}
+
+/**
+ * Guard trang chi tiết: user có được xem bản ghi thuộc chi nhánh này không?
+ * Bản ghi không gắn chi nhánh (null — dữ liệu cũ hoặc dùng chung) thì ai vào
+ * được trang đều xem được.
+ */
+export function canAccessBranch(
+  scope: BranchScope,
+  branchId: string | null | undefined,
+): boolean {
+  if (scope.canViewAll) return true;
+  if (!branchId) return true;
+  return scope.allowedBranchIds!.includes(branchId);
+}
+
+/**
+ * Fragment `where` cho model có cột branchId: thuộc CN được phép HOẶC chưa gắn
+ * CN. `{}` khi xem được tất — nhét thẳng vào where là xong, không cần rẽ nhánh.
+ *
+ * `field` cho model scope qua quan hệ, ví dụ kho: `scopedBranchWhere(scope,
+ * "warehouse")` → `{ OR: [{ warehouse: { branchId: { in } } }, { warehouse: {
+ * branchId: null } }] }`.
+ */
+export function scopedBranchWhere(
+  scope: BranchScope,
+  relation?: string,
+): Record<string, unknown> {
+  if (scope.canViewAll) return {};
+  const ids = scope.allowedBranchIds!;
+  const inClause = { branchId: { in: ids } };
+  const nullClause = { branchId: null };
+  return relation
+    ? { OR: [{ [relation]: inClause }, { [relation]: nullClause }] }
+    : { OR: [inClause, nullClause] };
+}
+
+/**
+ * Kẹp bộ lọc chi nhánh client gửi lên vào trong phạm vi được phép. `undefined`
+ * = client không lọc gì (phạm vi đã do allowedBranchIds lo). Chọn toàn CN ngoài
+ * phạm vi → sentinel: thấy 0 dòng, chứ KHÔNG rơi về "không lọc".
+ */
+export function clampBranchFilter(
+  requested: string[] | string | null | undefined,
+  scope: BranchScope,
+): string[] | undefined {
+  const ids = normalizeIds(requested);
+  if (ids.length === 0) return undefined;
+  if (scope.canViewAll) return ids;
+  const valid = ids.filter((id) => scope.allowedBranchIds!.includes(id));
+  return valid.length > 0 ? valid : [NO_BRANCH_ACCESS];
+}
+
+/**
+ * Kẹp danh sách id client chọn vào danh sách được phép — dùng cho thực thể đi
+ * theo chi nhánh (kho, quầy, điểm bán). Ngoài danh sách → sentinel.
+ */
+export function clampIdFilter(
+  requested: string[] | string | null | undefined,
+  allowedIds: string[],
+): string[] {
+  const valid = normalizeIds(requested).filter((id) => allowedIds.includes(id));
+  return valid.length > 0 ? valid : [NO_BRANCH_ACCESS];
+}
+
+function normalizeIds(
+  requested: string[] | string | null | undefined,
+): string[] {
+  return (Array.isArray(requested) ? requested : [requested]).filter(
+    (id): id is string => Boolean(id && id.trim()),
+  );
+}

package/src/branch-scope/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Phạm vi dữ liệu theo chi nhánh — hợp đồng chung.
+ *
+ * Bài toán: app nhiều chi nhánh thì "danh sách phiếu thu" của kế toán CN A phải
+ * KHÁC của CN B, còn giám đốc thì thấy tất. Lọc bằng tay ở từng route là cách
+ * chắc chắn sẽ rò: chỉ cần một route mới quên `where branchId`.
+ */
+
+/**
+ * Sentinel cho "user chưa được gán chi nhánh nào" và "client lọc toàn chi nhánh
+ * ngoài phạm vi". Là một chuỗi KHÔNG BAO GIỜ khớp branchId thật, nên
+ * `branchId: { in: [NO_BRANCH_ACCESS] }` trả 0 dòng. Không dùng mảng rỗng: Prisma
+ * hiểu `in: []` là "không có gì khớp" ở vài chỗ nhưng `undefined`/bỏ mệnh đề ở
+ * chỗ khác — nhầm một lần là lộ toàn bộ dữ liệu.
+ */
+export const NO_BRANCH_ACCESS = "__NO_ACCESS__";
+
+export interface BranchScope {
+  canViewAll: boolean;
+  /** undefined khi canViewAll — ngược lại LUÔN ≥1 phần tử (sentinel nếu user chưa gán CN). */
+  allowedBranchIds?: string[];
+}
+
+/** Chỉ cần đúng phần delegate `user_branches` mà scope dùng tới. */
+export interface BranchScopeDb {
+  userBranch: {
+    findMany: (args: {
+      where: { userId: string };
+      select: { branchId: true };
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }) => Promise<any[]>;
+  };
+}
+
+export interface BranchScopeConfig<TSession = unknown> {
+  /**
+   * Nguồn mặc định của phạm vi: bảng `user_branches`. Bỏ trống được NẾU đã khai
+   * `getAllowedBranchIds`.
+   */
+  db?: BranchScopeDb;
+  /**
+   * Session đã mang sẵn danh sách chi nhánh (app nhồi vào lúc đăng nhập) thì
+   * khai ở đây — khỏi phải truy vấn user_branches mỗi lần cần phạm vi. Trả mảng
+   * rỗng/null = user chưa được gán chi nhánh nào (→ sentinel, thấy 0 dòng).
+   */
+  getAllowedBranchIds?: (
+    session: TSession,
+  ) => string[] | null | undefined | Promise<string[] | null | undefined>;
+  /** Lấy id user từ session của app. */
+  getUserId: (session: TSession) => string | null | undefined;
+  /**
+   * "Xem mọi chi nhánh" — app tự quyết: vai trò quản trị, hoặc quyền
+   * `view-all-branches` trên resource nào đó. Trả true thì scope bỏ qua luôn
+   * truy vấn user_branches.
+   */
+  canViewAll: (session: TSession) => boolean;
+}