@goplusvn/core 0.1.75 → 0.1.77

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.1.76 — Multi-tenant + workspace: một cây tổ chức/chi nhánh/phòng ban, uỷ quyền cấp tài khoản trong phạm vi
+
+Nguồn: `docs/WORKSPACE-MULTITENANT-PLAN.md` + `docs/WORKSPACE-RESEARCH-IAM.md`
+(khảo sát Keycloak / AWS IAM / Azure AD / NetSuite / Odoo trước khi chọn hình
+dạng). Bài toán: một dự án có nhóm VẬN HÀNH toàn quyền và các nhóm KHÁCH HÀNG
+chỉ được tạo/phân quyền người dùng trong không gian của mình — trục không gian
+tuỳ dự án là tổ chức, chi nhánh, hay phòng ban.
+
+**Toàn bộ đợt này là ADDITIVE.** Không đổi, không xoá API cũ; app đang chạy
+không phải sửa dòng nào.
+
+**Core — feature `workspaces` (mới):**
+- `features/workspaces/` — `schema.prisma` + 2 migration SQL idempotent
+  (`0001_init`, `0002_delegation-columns`). Bảng `workspaces` (materialized
+  path) + `user_workspaces` (`is_admin`, `is_default`).
+- **MỘT cây, hai độ sâu** thay vì ba cơ chế theo ba trục: nhãn trục là `kind`
+  do app khai, độ sâu là `depth`. Spartronics dừng ở đơn vị, thingtodo đi
+  thêm một tầng phòng ban, vinhhoa nếu dùng thì là chi nhánh — cùng một engine.
+- `path`/`depth` CHỈ service được ghi (`createWorkspace`/`moveWorkspace`).
+  Ghi tay bằng `prisma.workspace.create` là cây vẫn hiện đúng trên UI trong
+  khi phạm vi đã hỏng — im lặng, không exception.
+- `WorkspaceScope` = `canViewAll` + `rootIds` + `allowedIds?` + `adminIds` +
+  `defaultId?`. Không có quyền nào → sentinel `NO_WORKSPACE_ACCESS`, KHÔNG
+  phải `in: []` (Prisma coi `in: []` là "không lọc" ở vài dạng lồng nhau).
+- `delegation.ts` — 7 bất biến D1–D7 chống leo thang: không tự nâng mình, không
+  cấp quyền mình không có, không đẩy nhánh sang tổ chức khác, không sửa người ở
+  ngoài phạm vi… có test cho từng cái.
+- `route-handlers.ts` — GET/POST/PATCH/DELETE + `move`, tự cắt `path`/`parentId`
+  khỏi payload. App bọc bằng cổng RBAC của mình: hai tầng gác chồng lên nhau
+  (cổng gác VAI, handler gác PHẠM VI) là CỐ Ý, bỏ tầng nào cũng hở.
+- UI: `WorkspaceListPage`, `WorkspaceTreeView`, `WorkspaceSwitcher`,
+  `ScopeLevelSelect`, `buildTree`.
+
+**Core — vá rò rỉ có thật ở danh sách người dùng:**
+- `user-service.ts` nhận `memberScopeWhere(scope)`. Trước đây trang Người dùng
+  trả về TOÀN BỘ user của hệ thống cho mọi vai có `user:view` — với mô hình
+  nhiều khách hàng dùng chung một app thì đó là danh bạ của khách hàng khác.
+- `memberScopeWhere` CỐ Ý **không có nhánh `null`**: tài khoản chưa gán không
+  gian nào là tài khoản hệ thống/cấp trên, lọt ra là lọt đúng thứ không được lọt.
+
+**Core — branch-scope dùng chung một AsyncLocalStorage với workspace:**
+- `branch-scope/context.ts` giữ NGUYÊN tên và hành vi 4 hàm cũ, nhưng thân dời
+  sang `workspace/context.ts`. Hai store riêng thì `runWithoutBranchScope()`
+  chỉ thoát được một store, store kia vẫn lọc, `MAX(số phiếu)` lại bị cắt theo
+  phạm vi ⇒ **trùng số phiếu** (sự cố RS-260727-0003).
+
+**Core — guardrails:**
+- Luật `one-door/workspace`: chỉ file cửa được `import "@goerp/core/workspace"`.
+- Luật `auth/server-action-bare-session`: cấm `getSession()` trần trong file
+  `"use server"` — phạm vi phải đi qua helper dùng chung, không chép ba dòng ở
+  mỗi action.
+- `primitives.ts`/`scanner.ts`/`types.ts` nhận luật theo thư mục cửa.
+
+**Core — đóng gói:**
+- `exports` thêm `./workspace/route-handlers`. Wildcard `./*` map sang
+  `./src/*/index.ts` nên subpath là FILE (không phải thư mục có index) buộc
+  phải khai tường minh — y như `./rbac/route-handlers` đã phải khai.
+
 ## 0.1.71 — Bịt gap từ pilot init spartronics: cron giờ thật, đăng nhập username, proxy publicPrefixes, template hết vấp
 
 Nguồn: docs/INIT-PILOT-SPARTRONICS-GAPS.md (dựng app thật từ goerp-init 0.1.70

package/bin/goerp-features.mjs

@@ -37,16 +37,20 @@ if (command === "status") {
     for (const s of f.steps.filter((s) => !s.materialized)) {
       console.log(`    ↳ thiếu bước ${s.num}_${s.slug}`);
     }
+    for (const file of f.ignored ?? []) {
+      console.log(`    ⚠ BỎ QUA ${file} — tên sai quy ước NNN_slug.sql (slug chỉ a-z0-9-)`);
+    }
   }
   process.exit(0);
 }
 
 if (command === "sync") {
   const actions = syncFeatures({ featuresRoot, appRoot, only });
-  if (actions.length === 0) {
+  if (actions.filter((a) => a.type !== "ignored").length === 0) {
     console.log("✓ Không có gì để sync — app đã đủ schema + migrations.");
   } else {
     for (const a of actions) {
+      if (a.type === "ignored") continue;
       if (a.type === "schema") console.log(`✓ schema  ${a.feature} → ${a.target}`);
       else console.log(`✓ migrate ${a.feature} + ${a.step} → prisma/migrations/${a.dir}`);
     }
@@ -54,6 +58,12 @@ if (command === "sync") {
       "\nTiếp theo: pnpm prisma migrate deploy && pnpm prisma generate"
     );
   }
+  // In sau cùng để không bị cuộn mất giữa danh sách "✓".
+  for (const a of actions.filter((a) => a.type === "ignored")) {
+    console.error(
+      `⚠ ${a.feature}: BỎ QUA ${a.file} — tên sai quy ước NNN_slug.sql (slug chỉ a-z0-9-). Bước này SẼ KHÔNG chạy.`
+    );
+  }
   process.exit(0);
 }
 

package/features/workspaces/README.md

@@ -0,0 +1,72 @@
+# feature `workspaces`
+
+Cây không gian làm việc + membership + cột uỷ quyền. **Opt-in** — app nào chưa
+cần thì không sync, không có bảng, không ảnh hưởng gì.
+
+```bash
+pnpm goerp-features sync --only workspaces
+pnpm prisma migrate deploy && pnpm prisma generate
+```
+
+## Bước thủ công (bắt buộc, sync không làm hộ)
+
+`sync` copy được `schema.prisma` fragment vì `Workspace`/`UserWorkspace` là model
+MỚI. Ba bảng còn lại (`users`, `roles`, `user_roles`) do **app sở hữu** — Prisma
+cấm khai trùng model, nên bước 0002 chỉ chạy SQL, còn model thì app tự thêm:
+
+```prisma
+model User {
+  // … giữ nguyên
+  isProtected             Boolean  @default(false) @map("is_protected")
+  permissionCeilingRoleId String?  @map("permission_ceiling_role_id")
+  userWorkspaces          UserWorkspace[]   // ← back-relation BẮT BUỘC
+}
+
+model Role {
+  // … giữ nguyên
+  workspaceId String? @map("workspace_id")
+  rank        Int     @default(100)
+  isSystem    Boolean @default(false)
+}
+
+model UserRole {
+  // … giữ nguyên
+  workspaceId String? @map("workspace_id")   // W7 — khai từ đầu, enforce sau
+}
+```
+
+Thiếu back-relation `userWorkspaces` thì `prisma generate` báo lỗi quan hệ.
+
+## Cấu hình runtime
+
+Composition root của app (cùng chỗ gọi `configureBranchScope`):
+
+```ts
+import { configureWorkspaces } from "@goerp/core/workspace"
+
+configureWorkspaces<Session>({
+  kinds: [
+    { key: "unit", label: "Đơn vị", childKinds: ["department"] },
+    { key: "department", label: "Bộ phận", canHaveChildren: false },
+  ],
+  db,                                   // đọc user_workspaces + workspaces
+  scopeField: "workspaceId",            // cột mang phạm vi trên chứng từ
+  getUserId: (s) => s.user?.id,
+  canViewAll: (s) => checkPermission(s, "workspace", "view-all-workspaces"),
+})
+```
+
+App **chưa** có bảng này (mức 0) thì bỏ `db`, cắm `getMemberships` vào nguồn sẵn
+có (`user_branches`): cây phẳng, hành vi giống hệt branch-scope hôm nay.
+
+## Seed
+
+Feature không seed dữ liệu — cây tổ chức là dữ liệu nghiệp vụ của từng app. Tạo
+nút bằng `createWorkspace()` của `@goerp/core/workspace` (nó tự ghi `path`/`depth`
+và cưỡng chế trần độ sâu), **đừng INSERT tay** rồi tự đặt `path`.
+
+## Quyền
+
+Feature không tự cấp quyền. App khai trong Permission Registry của mình rồi chạy
+`rbac-sync` — tối thiểu `workspace:view|create|update|delete` và action
+`view-all-workspaces`. **Chủ tự tick quyền**, sync không cấp.

package/features/workspaces/migrations/0001_init.sql

@@ -0,0 +1,63 @@
+-- goerp feature: workspaces — bước 0001 (idempotent).
+--
+-- Cây không gian làm việc + membership. YÊU CẦU: bảng "users" tồn tại (schema
+-- auth/RBAC chung của goerp) và model User của app khai back-relation
+-- `userWorkspaces UserWorkspace[]` — xem features/workspaces/README.md.
+--
+-- Không có FK nào trỏ tới bảng chứng từ: chứng từ giữ nguyên cột phạm vi sẵn có
+-- (`branch_id` / `department_id` / `workspace_id`), engine đọc cột đó qua
+-- `scopeField`. Nhờ vậy app lên feature này KHÔNG phải migrate một dòng dữ liệu
+-- chứng từ nào.
+CREATE TABLE IF NOT EXISTS "workspaces" (
+    "id" TEXT NOT NULL,
+    "code" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "kind" TEXT NOT NULL DEFAULT 'unit',
+    "parent_id" TEXT,
+    "path" TEXT NOT NULL,
+    "depth" INTEGER NOT NULL DEFAULT 1,
+    "is_active" BOOLEAN NOT NULL DEFAULT true,
+    "settings" JSONB,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "workspaces_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "workspaces_code_key" ON "workspaces"("code");
+-- Index chính của cả cơ chế: bung con cháu = `path LIKE '/x/%'`.
+CREATE INDEX IF NOT EXISTS "workspaces_path_idx" ON "workspaces"("path");
+CREATE INDEX IF NOT EXISTS "workspaces_parent_id_idx" ON "workspaces"("parent_id");
+CREATE INDEX IF NOT EXISTS "workspaces_kind_idx" ON "workspaces"("kind");
+
+CREATE TABLE IF NOT EXISTS "user_workspaces" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "workspace_id" TEXT NOT NULL,
+    "is_default" BOOLEAN NOT NULL DEFAULT false,
+    "is_admin" BOOLEAN NOT NULL DEFAULT false,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "user_workspaces_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "user_workspaces_user_id_workspace_id_key" ON "user_workspaces"("user_id", "workspace_id");
+CREATE INDEX IF NOT EXISTS "user_workspaces_user_id_idx" ON "user_workspaces"("user_id");
+CREATE INDEX IF NOT EXISTS "user_workspaces_workspace_id_idx" ON "user_workspaces"("workspace_id");
+
+-- FK thêm rời để chạy lại vô hại (Postgres không có ADD CONSTRAINT IF NOT EXISTS).
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'workspaces_parent_id_fkey') THEN
+        ALTER TABLE "workspaces" ADD CONSTRAINT "workspaces_parent_id_fkey"
+            FOREIGN KEY ("parent_id") REFERENCES "workspaces"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'user_workspaces_user_id_fkey') THEN
+        ALTER TABLE "user_workspaces" ADD CONSTRAINT "user_workspaces_user_id_fkey"
+            FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'user_workspaces_workspace_id_fkey') THEN
+        ALTER TABLE "user_workspaces" ADD CONSTRAINT "user_workspaces_workspace_id_fkey"
+            FOREIGN KEY ("workspace_id") REFERENCES "workspaces"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+    END IF;
+END $$;

package/features/workspaces/migrations/0002_delegation-columns.sql

@@ -0,0 +1,34 @@
+-- goerp feature: workspaces — bước 0002 (idempotent). Cột cho phần UỶ QUYỀN
+-- (bất biến D1–D7). Tất cả đều nullable hoặc có DEFAULT ⇒ app đang chạy không vỡ,
+-- và khi chưa có dòng nào dùng thì hành vi y hệt hôm nay.
+--
+-- CHÚ Ý: ba bảng dưới đây do APP sở hữu (roles / user_roles / users), nên
+-- `schema.prisma` fragment của feature KHÔNG khai lại chúng — Prisma cấm trùng
+-- model. App phải tự thêm các trường tương ứng vào model của mình; xem
+-- features/workspaces/README.md mục "Bước thủ công".
+
+-- D2 — trần quyền kiểu AWS permissions boundary. Quyền hiệu lực = GIAO của
+-- quyền vai trò và trần này, đánh giá MỖI request. Người tạo bị thu hồi quyền
+-- sau đó thì user họ tạo cũng hẹp lại theo, chứ không giữ nguyên quyền cũ.
+ALTER TABLE "users" ADD COLUMN IF NOT EXISTS "permission_ceiling_role_id" TEXT;
+
+-- D6 — tài khoản được bảo vệ: admin nhánh KHÔNG đổi mật khẩu / vô hiệu hoá /
+-- gỡ vai trò của tài khoản này, dù cùng workspace và dù D5 thoả.
+ALTER TABLE "users" ADD COLUMN IF NOT EXISTS "is_protected" BOOLEAN NOT NULL DEFAULT false;
+
+-- Vai trò riêng của một workspace (null = vai trò hệ thống, dùng chung).
+ALTER TABLE "roles" ADD COLUMN IF NOT EXISTS "workspace_id" TEXT;
+-- Cấp bậc: càng NHỎ càng cao. SUPER_ADMIN = 0. Admin nhánh chỉ tạo/gán được
+-- vai trò có rank LỚN HƠN rank của chính mình.
+ALTER TABLE "roles" ADD COLUMN IF NOT EXISTS "rank" INTEGER NOT NULL DEFAULT 100;
+-- Vai trò hệ thống: chỉ quản trị toàn cục sửa được.
+ALTER TABLE "roles" ADD COLUMN IF NOT EXISTS "is_system" BOOLEAN NOT NULL DEFAULT false;
+
+-- W7 — vai trò có hiệu lực ở đúng một workspace. KHAI CỘT TỪ ĐẦU, ENFORCE SAU:
+-- thêm cột vào bảng gán quyền khi đã có dữ liệu thật là việc đau. null = hành vi
+-- y hệt hôm nay (hiệu lực ở MỌI membership).
+ALTER TABLE "user_roles" ADD COLUMN IF NOT EXISTS "workspace_id" TEXT;
+
+CREATE INDEX IF NOT EXISTS "roles_workspace_id_idx" ON "roles"("workspace_id");
+CREATE INDEX IF NOT EXISTS "user_roles_workspace_id_idx" ON "user_roles"("workspace_id");
+CREATE INDEX IF NOT EXISTS "users_permission_ceiling_role_id_idx" ON "users"("permission_ceiling_role_id");

package/features/workspaces/schema.prisma

@@ -0,0 +1,56 @@
+/// Cây KHÔNG GIAN LÀM VIỆC — đơn vị / tổ chức / chi nhánh / phòng ban là MỘT
+/// cây, khác nhau ở nhãn `kind` và độ sâu, không phải bốn cơ chế song song.
+///
+/// `path` là materialized path `/{ancestor}/…/{self}/` — bung con cháu bằng một
+/// câu `path LIKE '/x/%'` đi được index btree, không đệ quy runtime, không CTE.
+/// **Service ghi cột này, KHÔNG cho sửa tay**: đổi cha mà quên ghi lại path cho
+/// cả nhánh con thì cây trông đúng trên UI mà phạm vi thì sai.
+model Workspace {
+  id        String   @id @default(cuid()) @map("id")
+  code      String   @unique @map("code")
+  name      String   @map("name")
+  /// "org" | "unit" | "branch" | "department" | app tự thêm. Chỉ là NHÃN hiển
+  /// thị + luật cấu hình, không đổi logic phạm vi.
+  kind      String   @default("unit") @map("kind")
+  parentId  String?  @map("parent_id")
+  path      String   @map("path")
+  depth     Int      @default(1) @map("depth")
+  isActive  Boolean  @default(true) @map("is_active")
+  /// Cấu hình riêng của đơn vị (logo, ca làm, chính sách…).
+  settings  Json?    @map("settings")
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  parent   Workspace?      @relation("WorkspaceTree", fields: [parentId], references: [id])
+  children Workspace[]     @relation("WorkspaceTree")
+  members  UserWorkspace[]
+
+  @@index([path])
+  @@index([parentId])
+  @@index([kind])
+  @@map("workspaces")
+}
+
+/// Membership `user ↔ workspace`.
+///
+/// `isAdmin` trả lời "nhánh NÀO", quyền RBAC trả lời "được LÀM GÌ" — hai trục
+/// vuông góc, cố ý không gộp. Có `isAdmin` mà không có quyền `user:manage` thì
+/// vẫn không tạo được tài khoản, và ngược lại.
+model UserWorkspace {
+  id          String   @id @default(cuid()) @map("id")
+  userId      String   @map("user_id")
+  workspaceId String   @map("workspace_id")
+  /// Không gian mở sẵn khi đăng nhập / gán cho bản ghi mới tạo.
+  isDefault   Boolean  @default(false) @map("is_default")
+  /// Quản trị viên của nhánh này (uỷ quyền cấp tài khoản trong phạm vi).
+  isAdmin     Boolean  @default(false) @map("is_admin")
+  createdAt   DateTime @default(now()) @map("created_at")
+
+  user      User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+  workspace Workspace @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, workspaceId])
+  @@index([userId])
+  @@index([workspaceId])
+  @@map("user_workspaces")
+}

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.75",
+  "version": "0.1.77",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -54,6 +54,7 @@
     "./import": "./src/import/index.ts",
     "./auth/proxy-gate": "./src/auth/proxy-gate.ts",
     "./rbac/route-handlers": "./src/rbac/route-handlers.ts",
+    "./workspace/route-handlers": "./src/workspace/route-handlers.ts",
     "./rbac/permissions-version": "./src/rbac/permissions-version.ts",
     "./ui/shared/table-styles": "./src/ui/shared/table-styles.ts",
     "./errors/app-error": "./src/errors/app-error.ts",

package/scripts/feature-sync.mjs

@@ -23,19 +23,38 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-/** features/<name>/migrations/NNN_slug.sql → [{num, slug, file}] theo thứ tự. */
+const STEP_NAME = /^(\d{3,})_([a-z0-9-]+)\.sql$/;
+
+/**
+ * features/<name>/migrations/NNN_slug.sql → [{num, slug, file}] theo thứ tự.
+ *
+ * Slug chỉ nhận `a-z0-9-` (KHÔNG gạch dưới) vì tên bước đi thẳng vào tên thư mục
+ * migration của app. File `.sql` đặt sai tên bị BỎ QUA — và bỏ qua im lặng là
+ * bẫy thật sự: bước tạo bảng chạy, bước thêm cột thì không, app deploy xanh mà
+ * cột không tồn tại. Đã dính đúng ca này với `0002_delegation_columns.sql`.
+ * Vì vậy trả kèm `ignored` để CLI kêu to.
+ */
 export function listFeatureSteps(featureDir) {
   const dir = join(featureDir, "migrations");
   if (!existsSync(dir)) return [];
   return readdirSync(dir)
-    .filter((f) => /^\d{3,}_[a-z0-9-]+\.sql$/.test(f))
+    .filter((f) => STEP_NAME.test(f))
     .sort()
     .map((f) => {
-      const m = f.match(/^(\d{3,})_([a-z0-9-]+)\.sql$/);
+      const m = f.match(STEP_NAME);
       return { num: m[1], slug: m[2], file: join(dir, f) };
     });
 }
 
+/** File `.sql` nằm trong migrations/ nhưng sai quy ước tên — không bao giờ chạy. */
+export function listIgnoredStepFiles(featureDir) {
+  const dir = join(featureDir, "migrations");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".sql") && !STEP_NAME.test(f))
+    .sort();
+}
+
 /** Tên mọi feature trong thư mục features/ của core. */
 export function listFeatures(featuresRoot) {
   if (!existsSync(featuresRoot)) return [];
@@ -93,6 +112,7 @@ export function featureStatus({ featuresRoot, appRoot }) {
         ...step,
         materialized: isStepMaterialized(migrationsDir, feature, step),
       })),
+      ignored: listIgnoredStepFiles(featureDir),
     };
   });
 }
@@ -110,6 +130,14 @@ const GENERATED_HEADER = (feature) =>
  */
 export function syncFeatures({ featuresRoot, appRoot, now = new Date(), only = [] }) {
   const actions = [];
+  // Kêu trước khi làm gì: file sai tên sẽ không bao giờ chạy, mà app vẫn deploy
+  // xanh — người dùng chỉ phát hiện khi một cột không tồn tại lúc runtime.
+  for (const feature of listFeatures(featuresRoot)) {
+    if (only.length > 0 && !only.includes(feature)) continue;
+    for (const file of listIgnoredStepFiles(join(featuresRoot, feature))) {
+      actions.push({ type: "ignored", feature, file });
+    }
+  }
   const migrationsDir = join(appRoot, "prisma", "migrations");
   let offset = 0;
 

package/src/branch-scope/context.ts

@@ -1,4 +1,10 @@
-import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  getScopeContext,
+  resolveAmbientScope,
+  runWithScope,
+  runWithoutScope,
+} from "../workspace/context";
+import type { ScopeContext } from "../workspace/context";
 
 import type { BranchScope } from "./types";
 
@@ -6,61 +12,38 @@ 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.
+ * Thân của module này đã dời sang `workspace/context.ts` để `branch-scope` và
+ * `workspace` dùng **chung đúng một AsyncLocalStorage**. Đây không phải dọn dẹp
+ * cho đẹp: hai store riêng thì `runWithoutBranchScope()` chỉ thoát được một
+ * store, store kia vẫn lọc, và `MAX(số phiếu)` lại bị cắt theo phạm vi ⇒ **trùng
+ * số phiếu** (sự cố có thật RS-260727-0003).
  *
- * 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.
+ * API dưới đây giữ nguyên tên và hành vi cũ — app không phải sửa một dòng nào.
  */
 
-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 type BranchScopeContext = ScopeContext<BranchScope>;
 
 export function runWithBranchScope<T>(
   context: BranchScopeContext,
   fn: () => T | Promise<T>,
 ): T | Promise<T> {
-  return store.run(context, () => pinToCurrentContext(fn()));
+  return runWithScope<T, BranchScope>(context, fn);
 }
 
 export function getBranchScopeContext(): BranchScopeContext | undefined {
-  return store.getStore();
+  return getScopeContext() as BranchScopeContext | undefined;
 }
 
 /** 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;
+  return resolveAmbientScope<BranchScope>();
 }
 
 /**
  * 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.
+ * bất kể phạm vi user. Ca kinh điển: đánh số phiếu. 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()));
+  return runWithoutScope(fn);
 }

package/src/features/__tests__/feature-sync.test.ts

@@ -126,6 +126,47 @@ describe("featureStatus", () => {
   })
 })
 
+describe("file .sql sai quy ước tên", () => {
+  // Ca có thật: `0002_delegation_columns.sql` (gạch DƯỚI) bị bỏ qua im lặng, nên
+  // bảng thì được tạo mà cột uỷ quyền thì không — app deploy xanh, lỗi chỉ lộ ra
+  // lúc runtime. Bỏ qua thì vẫn bỏ qua, nhưng phải KÊU.
+  it("không materialize, nhưng có mặt trong `ignored` và trong log sync", () => {
+    writeFeature(
+      "f-a",
+      { "0001_init.sql": "SELECT 1;", "0002_bad_name.sql": "SELECT 2;" },
+      "model A { id String @id }"
+    )
+
+    const status = featureStatus({ featuresRoot, appRoot })
+    const feature = status.find((f: { feature: string }) => f.feature === "f-a")!
+    expect(feature.steps.map((s: { slug: string }) => s.slug)).toEqual(["init"])
+    expect(feature.ignored).toEqual(["0002_bad_name.sql"])
+
+    const actions = syncFeatures({ featuresRoot, appRoot, only: ["f-a"] })
+    expect(
+      actions.filter((a: { type: string }) => a.type === "migration")
+    ).toHaveLength(1)
+    expect(
+      actions.find((a: { type: string }) => a.type === "ignored")
+    ).toMatchObject({ feature: "f-a", file: "0002_bad_name.sql" })
+  })
+
+  it("tên đúng quy ước (gạch ngang) thì chạy bình thường", () => {
+    writeFeature(
+      "f-b",
+      { "0001_init.sql": "SELECT 1;", "0002_delegation-columns.sql": "SELECT 2;" },
+      "model B { id String @id }"
+    )
+    const status = featureStatus({ featuresRoot, appRoot })
+    const feature = status.find((f: { feature: string }) => f.feature === "f-b")!
+    expect(feature.steps.map((s: { slug: string }) => s.slug)).toEqual([
+      "init",
+      "delegation-columns",
+    ])
+    expect(feature.ignored).toEqual([])
+  })
+})
+
 describe("migrationTimestamp", () => {
   it("dạng YYYYMMDDHHMMSS UTC + offset giây", () => {
     const now = new Date("2026-07-31T01:02:03Z")

package/src/guardrails/__tests__/guardrails.test.ts

@@ -121,6 +121,53 @@ describe("rule bắt được vi phạm thật", () => {
     );
   });
 
+  it("one-door/workspace — import thẳng bị bắt; cửa branch-scope cũng là cửa hợp lệ", () => {
+    const leaky = fixture({
+      "lib/branch-scope.ts":
+        'import { configureWorkspaces } from "@goerp/core/workspace"\nconfigureWorkspaces({ getUserId: (s) => s.id, canViewAll: () => false })',
+      "app/(main)/don-hang/page.tsx":
+        'import { getWorkspaceScope } from "@goerp/core/workspace"\nexport default function Page() { return null }',
+    });
+    expect(resultOf(run(leaky), "one-door/workspace").violations).toEqual([
+      "app/(main)/don-hang/page.tsx",
+    ]);
+
+    // Dùng lớp 1 (getWorkspaceScope) mà cửa quên cấu hình singleton → bắt.
+    const unconfigured = fixture({
+      "lib/branch-scope.ts":
+        'export { getWorkspaceScope } from "@goerp/core/workspace"',
+      "app/api/x/route.ts": "const s = await getWorkspaceScope(session)",
+    });
+    expect(
+      resultOf(run(unconfigured), "one-door/workspace").violations.join(),
+    ).toContain("KHÔNG gọi configureWorkspaces()");
+  });
+
+  it("one-door/workspace — chỉ dùng lớp 2 / hàm cây thì không đòi configureWorkspaces", () => {
+    const root = fixture({
+      "lib/branch-scope.ts":
+        'export { createScopeGuardExtension } from "@goerp/core/workspace"',
+    });
+    expect(resultOf(run(root), "one-door/workspace").violations).toEqual([]);
+  });
+
+  it("one-door/* — `import type` không tính là đi cửa sau, nhưng `import { type X }` thì có", () => {
+    const root = fixture({
+      "lib/branch-scope.ts":
+        'import { configureWorkspaces } from "@goerp/core/workspace"\nconfigureWorkspaces({ getUserId: (s) => s.id, canViewAll: () => false })',
+      // Chỉ mượn `interface` để chú kiểu — biên dịch xong là biến mất, không
+      // module nào bị nạp nên không thể bỏ lỡ configureWorkspaces().
+      "configs/workspace.config.ts":
+        'import type { WorkspaceKindConfig } from "@goerp/core/workspace"\nexport const KINDS: WorkspaceKindConfig[] = []',
+      // Vẫn nạp module thật, chỉ là gắn `type` bên trong ngoặc → vẫn bắt.
+      "app/(main)/x/page.tsx":
+        'import { buildTree, type WorkspaceNode } from "@goerp/core/workspace"\nexport default function Page() { return buildTree([]) }',
+    });
+    expect(resultOf(run(root), "one-door/workspace").violations).toEqual([
+      "app/(main)/x/page.tsx",
+    ]);
+  });
+
   it("auth/api-route-gated — không gác thì phải được KHAI công khai ở proxy.ts", () => {
     const root = fixture({
       "proxy.ts":

package/src/guardrails/primitives.ts

@@ -141,8 +141,21 @@ interface SingleDoorSpec {
  * theo lời gọi cấu hình — code chạy tới lúc thật mới nổ, và với branch-scope
  * thì "nổ" nghĩa là người chi nhánh này nhìn thấy dữ liệu chi nhánh khác.
  */
+/**
+ * Bỏ các câu `import type { … } from "…"` trước khi soi.
+ *
+ * Import chỉ-kiểu bị xoá sạch lúc biên dịch: nó không kéo được module nào vào
+ * bundle, nên cũng không thể bỏ lỡ `configureX()` — cái mà rule này canh. Đếm
+ * nó thành vi phạm chỉ ép người ta hoặc bỏ chú kiểu, hoặc dựng một cửa vòng
+ * vèo chỉ để mượn một `interface`. Import THƯỜNG có kèm `type` bên trong ngoặc
+ * (`import { type X, y }`) vẫn tính — nó vẫn nạp module thật.
+ */
+const TYPE_ONLY_IMPORT = /^\s*import\s+type\s[^\n]*$/gm;
+
 export function singleDoorImport(spec: SingleDoorSpec): GuardrailRule {
   const test = stateless(spec.pattern);
+  const readValueImports = (ctx: GuardrailContext, file: string) =>
+    ctx.readCode(file).replace(TYPE_ONLY_IMPORT, "");
   return {
     id: spec.id,
     title: spec.title,
@@ -157,7 +170,7 @@ export function singleDoorImport(spec: SingleDoorSpec): GuardrailRule {
       for (const file of ctx.files) {
         const rel = ctx.rel(file);
         if (doors.includes(rel)) continue;
-        if (test.test(ctx.readCode(file))) offenders.push(rel);
+        if (test.test(readValueImports(ctx, file))) offenders.push(rel);
       }
 
       if (spec.mustConfigure && (spec.mustConfigureWhen?.(ctx) ?? true)) {