@goplusvn/core 0.1.58 → 0.1.60

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.
@@ -255,6 +273,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/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.58",
+  "version": "0.1.60",
   "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/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()));
+}