@goplusvn/core 0.1.75 → 0.1.77

package/src/workspace/scope.ts

@@ -0,0 +1,396 @@
+import { subtreePrefix } from "./tree";
+import { NO_WORKSPACE_ACCESS } from "./types";
+import type {
+  ScopeLevel,
+  WorkspaceMembership,
+  WorkspaceScope,
+  WorkspaceScopeConfig,
+} from "./types";
+
+/**
+ * LỚP 1 — lọc tường minh. Page/route/service gọi `getWorkspaceScope(session)`
+ * rồi nhét `scopedWhere(scope)` vào `where`. Lớp 2 (guard extension) là lưới an
+ * toàn cho chỗ quên, KHÔNG phải thay thế lớp này.
+ *
+ * Singleton phải cấu hình MỘT lần ở composition root của app, y như
+ * `configureBranchScope` / `configureStorage`. Import thẳng từ core lấy được
+ * hàm nhưng bỏ lỡ lời gọi cấu hình — và với module này, "bỏ lỡ" nghĩa là rò dữ
+ * liệu chéo không gian.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let configured: WorkspaceScopeConfig<any> | null = null;
+
+export function configureWorkspaces<TSession>(
+  config: WorkspaceScopeConfig<TSession>,
+): void {
+  configured = config;
+}
+
+/** Chỉ dùng trong test — app không được gọi. */
+export function resetWorkspaceConfig(): void {
+  configured = null;
+}
+
+function requireConfigured() {
+  if (!configured) {
+    throw new Error(
+      "[workspace] chưa configureWorkspaces(...) — 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 getWorkspaceConfig() {
+  return requireConfigured();
+}
+
+/** Cột mang phạm vi trên chứng từ; mặc định `branchId` để tương thích ngược. */
+export function workspaceScopeField(): string {
+  return configured?.scopeField ?? "branchId";
+}
+
+export function canViewAllWorkspaces<TSession>(session: TSession): boolean {
+  return requireConfigured().canViewAll(session);
+}
+
+/**
+ * Gói một phạm vi. Đặt `allowedBranchIds` TRỎ CÙNG mảng với `allowedIds` — đó
+ * là cây cầu tương thích để mọi hàm `branch-scope` cũ nhận thẳng
+ * `WorkspaceScope` mà không app nào phải sửa import (luật L2: additive).
+ * Đừng dựng scope bằng object literal, dùng hàm này.
+ */
+export function createWorkspaceScope(input: {
+  canViewAll: boolean;
+  rootIds?: string[];
+  allowedIds?: string[];
+  adminIds?: string[];
+  defaultId?: string;
+}): WorkspaceScope {
+  if (input.canViewAll) {
+    return {
+      canViewAll: true,
+      rootIds: input.rootIds ?? [],
+      adminIds: input.adminIds ?? [],
+      defaultId: input.defaultId,
+    };
+  }
+  const allowed =
+    input.allowedIds && input.allowedIds.length > 0
+      ? input.allowedIds
+      : [NO_WORKSPACE_ACCESS];
+  return {
+    canViewAll: false,
+    rootIds: input.rootIds ?? [],
+    allowedIds: allowed,
+    allowedBranchIds: allowed,
+    adminIds: input.adminIds ?? [],
+    defaultId: input.defaultId,
+  };
+}
+
+/**
+ * Phạm vi của user. Chưa được gán không gian 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 getWorkspaceScope<TSession>(
+  session: TSession,
+): Promise<WorkspaceScope> {
+  const config = requireConfigured();
+  if (config.canViewAll(session)) {
+    return createWorkspaceScope({ canViewAll: true });
+  }
+
+  const memberships = await readMemberships(config, session);
+  const rootIds = unique(memberships.map((m) => m.workspaceId));
+  const adminRootIds = unique(
+    memberships.filter((m) => m.isAdmin).map((m) => m.workspaceId),
+  );
+  const defaultId =
+    memberships.find((m) => m.isDefault)?.workspaceId ?? rootIds[0];
+
+  const allowedIds = await expand(config, rootIds);
+  // Quản trị viên của nhánh nào thì quản trị được cả con cháu nhánh đó — cùng
+  // luật cộng dồn với phạm vi đọc, nếu không thì admin nút cha lại không đụng
+  // được phòng ban con của chính mình.
+  const adminIds =
+    adminRootIds.length > 0 ? await expand(config, adminRootIds) : [];
+
+  return createWorkspaceScope({
+    canViewAll: false,
+    rootIds,
+    allowedIds,
+    adminIds,
+    defaultId,
+  });
+}
+
+async function readMemberships<TSession>(
+  config: WorkspaceScopeConfig<TSession>,
+  session: TSession,
+): Promise<WorkspaceMembership[]> {
+  if (config.getMemberships) {
+    const raw = (await config.getMemberships(session)) ?? [];
+    return raw
+      .map((entry) =>
+        typeof entry === "string" ? { workspaceId: entry } : entry,
+      )
+      .filter((m): m is WorkspaceMembership => Boolean(m?.workspaceId));
+  }
+
+  const userId = config.getUserId(session);
+  if (!userId) return [];
+
+  if (!config.db) {
+    throw new Error(
+      "[workspace] configureWorkspaces cần `db` (hoặc `getMemberships`) để biết user thuộc không gian nào.",
+    );
+  }
+  const rows = await config.db.userWorkspace.findMany({
+    where: { userId },
+    select: { workspaceId: true, isAdmin: true, isDefault: true },
+  });
+  return rows
+    .map((row) => row as Partial<WorkspaceMembership>)
+    .filter((row): row is WorkspaceMembership => Boolean(row.workspaceId));
+}
+
+/**
+ * Bung con cháu. Không khai `expandDescendants` và cũng không có `db` ⇒ **cây
+ * phẳng** (mức 0): allowedIds = rootIds. Hẹp hơn chứ không rộng hơn, nên app
+ * chưa có bảng `workspaces` vẫn an toàn.
+ */
+async function expand<TSession>(
+  config: WorkspaceScopeConfig<TSession>,
+  rootIds: string[],
+): Promise<string[]> {
+  if (rootIds.length === 0) return [];
+  if (config.expandDescendants) {
+    const ids = await config.expandDescendants(rootIds);
+    return unique([...rootIds, ...(ids ?? [])]);
+  }
+  if (!config.db) return rootIds;
+  return unique([...rootIds, ...(await expandViaDb(config.db, rootIds))]);
+}
+
+/**
+ * Hai truy vấn, cả hai đều đi được index: (1) lấy `path` của các nút gốc, (2)
+ * lấy mọi nút có path bắt đầu bằng các tiền tố đó. Cố ý KHÔNG dùng `contains`:
+ * `startsWith` mới tận dụng được btree trên `path`.
+ */
+async function expandViaDb(
+  db: NonNullable<WorkspaceScopeConfig["db"]>,
+  rootIds: string[],
+): Promise<string[]> {
+  const roots = await db.workspace.findMany({
+    where: { id: { in: rootIds } },
+    select: { id: true, path: true },
+  });
+  const prefixes = roots
+    .map((row) => (row as { path?: string | null }).path)
+    .filter((path): path is string => Boolean(path))
+    .map(subtreePrefix);
+  if (prefixes.length === 0) return [];
+
+  const descendants = await db.workspace.findMany({
+    where: { OR: prefixes.map((prefix) => ({ path: { startsWith: prefix } })) },
+    select: { id: true, path: true },
+  });
+  return descendants
+    .map((row) => (row as { id?: string | null }).id)
+    .filter((id): id is string => Boolean(id));
+}
+
+/**
+ * Guard trang chi tiết: user có được xem bản ghi thuộc không gian này không?
+ * Bản ghi không gắn không gian (null — dữ liệu cũ hoặc dùng chung) thì ai vào
+ * được trang đều xem được.
+ */
+export function canAccessWorkspace(
+  scope: WorkspaceScope,
+  workspaceId: string | null | undefined,
+): boolean {
+  if (scope.canViewAll) return true;
+  if (!workspaceId) return true;
+  return (scope.allowedIds ?? []).includes(workspaceId);
+}
+
+/**
+ * Người này có QUẢN TRỊ được không gian đó không (D1). Khác hẳn
+ * `canAccessWorkspace`: xem được ≠ cấp tài khoản được.
+ */
+export function isWorkspaceAdmin(
+  scope: WorkspaceScope,
+  workspaceId: string | null | undefined,
+): boolean {
+  if (scope.canViewAll) return true;
+  if (!workspaceId) return false;
+  return scope.adminIds.includes(workspaceId);
+}
+
+/** Có được uỷ quyền quản trị ở đâu đó không — dùng để bật/tắt nút "Thêm người dùng". */
+export function hasAdminScope(scope: WorkspaceScope): boolean {
+  return scope.canViewAll || scope.adminIds.length > 0;
+}
+
+/**
+ * Fragment `where` để lọc **NGƯỜI DÙNG** theo phạm vi — khác `scopedWhere` ở hai
+ * điểm cố ý:
+ *
+ *  1. Người dùng gắn không gian qua **bảng nối** (`user_workspaces` /
+ *     `user_branches`), không phải một cột ⇒ phải dùng `some`.
+ *  2. **KHÔNG có nhánh `null`.** Với chứng từ, "chưa gắn không gian" là dữ liệu
+ *     dùng chung nên cho xem. Với người dùng thì ngược lại: tài khoản chưa gắn
+ *     không gian nào là tài khoản của cấp trên hoặc tài khoản hệ thống — lộ ra
+ *     là lộ đúng thứ không được lộ.
+ *
+ * Đây là chỗ vá lỗ hổng đang có thật: trang Người dùng của core dựng `where` từ
+ * search/status/roleCode và KHÔNG có điều kiện phạm vi nào, nên admin nhánh nhìn
+ * thấy toàn bộ danh sách người dùng của mọi khách hàng khác.
+ */
+export function memberScopeWhere(
+  scope: WorkspaceScope,
+  options?: { relation?: string; field?: string; adminOnly?: boolean },
+): Record<string, unknown> {
+  if (scope.canViewAll) return {};
+  const config = configured;
+  const relation =
+    options?.relation ?? config?.membershipRelation ?? "userWorkspaces";
+  const field = options?.field ?? config?.membershipField ?? "workspaceId";
+  const ids = options?.adminOnly
+    ? scope.adminIds.length > 0
+      ? scope.adminIds
+      : [NO_WORKSPACE_ACCESS]
+    : (scope.allowedIds ?? [NO_WORKSPACE_ACCESS]);
+  return { [relation]: { some: { [field]: { in: ids } } } };
+}
+
+/**
+ * Fragment `where` cho model có cột phạm vi: thuộc không gian được phép HOẶC
+ * chưa gắn không gian. `{}` khi xem được tất.
+ *
+ * `relation` cho model scope qua quan hệ (kho → chi nhánh):
+ * `scopedWhere(scope, { relation: "warehouse" })`.
+ */
+export function scopedWhere(
+  scope: WorkspaceScope,
+  options?: { field?: string; relation?: string },
+): Record<string, unknown> {
+  if (scope.canViewAll) return {};
+  const field = options?.field ?? workspaceScopeField();
+  const ids = scope.allowedIds ?? [NO_WORKSPACE_ACCESS];
+  const inClause = { [field]: { in: ids } };
+  const nullClause = { [field]: null };
+  return options?.relation
+    ? {
+        OR: [
+          { [options.relation]: inClause },
+          { [options.relation]: nullClause },
+        ],
+      }
+    : { OR: [inClause, nullClause] };
+}
+
+/**
+ * `where` theo thang 5 nấc (Δ1). Nấc cao bao trọn nấc thấp, nên chỉ cần đúng
+ * một nhánh cho mỗi nấc:
+ *
+ * - `none`     → sentinel, 0 dòng
+ * - `own`      → chỉ bản ghi của chính user (cần `ownerField` + `userId`)
+ * - `workspace`→ đúng các nút được gán, KHÔNG bung con cháu
+ * - `subtree`  → nút được gán + con cháu (mặc định của `scopedWhere`)
+ * - `all`      → không thêm điều kiện
+ */
+export function scopeLevelWhere(
+  level: ScopeLevel,
+  scope: WorkspaceScope,
+  options?: {
+    field?: string;
+    relation?: string;
+    ownerField?: string;
+    userId?: string | null;
+  },
+): Record<string, unknown> {
+  const field = options?.field ?? workspaceScopeField();
+  switch (level) {
+    case "all":
+      return {};
+    case "none":
+      return { [field]: { in: [NO_WORKSPACE_ACCESS] } };
+    case "own": {
+      const ownerField = options?.ownerField ?? "createdBy";
+      // Không biết user là ai thì đóng lại, không mở ra.
+      return { [ownerField]: options?.userId ?? NO_WORKSPACE_ACCESS };
+    }
+    case "workspace": {
+      if (scope.canViewAll) return {};
+      const ids =
+        scope.rootIds.length > 0 ? scope.rootIds : [NO_WORKSPACE_ACCESS];
+      return scopedWhere(
+        createWorkspaceScope({ canViewAll: false, allowedIds: ids }),
+        options,
+      );
+    }
+    case "subtree":
+    default:
+      return scopedWhere(scope, options);
+  }
+}
+
+const SCOPE_LEVEL_RANK: Record<ScopeLevel, number> = {
+  none: 0,
+  own: 1,
+  workspace: 2,
+  subtree: 3,
+  all: 4,
+};
+
+/** Nấc `a` có rộng bằng hoặc hơn nấc `b` không — dùng khi so trần quyền. */
+export function scopeLevelAtLeast(a: ScopeLevel, b: ScopeLevel): boolean {
+  return SCOPE_LEVEL_RANK[a] >= SCOPE_LEVEL_RANK[b];
+}
+
+/**
+ * Kẹp bộ lọc client gửi lên vào trong phạm vi được phép. `undefined` = client
+ * không lọc gì. Chọn toàn không gian ngoài phạm vi → sentinel: thấy 0 dòng,
+ * chứ KHÔNG rơi về "không lọc".
+ */
+export function clampScopeFilter(
+  requested: string[] | string | null | undefined,
+  scope: WorkspaceScope,
+): string[] | undefined {
+  const ids = normalizeIds(requested);
+  if (ids.length === 0) return undefined;
+  if (scope.canViewAll) return ids;
+  const allowed = scope.allowedIds ?? [];
+  const valid = ids.filter((id) => allowed.includes(id));
+  return valid.length > 0 ? valid : [NO_WORKSPACE_ACCESS];
+}
+
+/**
+ * D1 — kẹp danh sách không gian mà người thao tác định GÁN cho một tài khoản
+ * vào đúng nhánh họ được uỷ quyền. Trả `null` = có id nằm ngoài `adminIds` ⇒
+ * caller phải TỪ CHỐI, không được lặng lẽ bỏ bớt: gán thiếu không gian cũng là
+ * sai, và người dùng sẽ tưởng đã cấp xong.
+ */
+export function clampToAdminScope(
+  requested: string[] | string | null | undefined,
+  scope: WorkspaceScope,
+): string[] | null {
+  const ids = normalizeIds(requested);
+  if (scope.canViewAll) return ids;
+  const outside = ids.filter((id) => !scope.adminIds.includes(id));
+  return outside.length > 0 ? null : ids;
+}
+
+function normalizeIds(
+  requested: string[] | string | null | undefined,
+): string[] {
+  return (Array.isArray(requested) ? requested : [requested]).filter(
+    (id): id is string => Boolean(id && id.trim()),
+  );
+}
+
+function unique(ids: string[]): string[] {
+  return [...new Set(ids.filter(Boolean))];
+}

package/src/workspace/service.ts

@@ -0,0 +1,301 @@
+/**
+ * Dịch vụ ghi cây không gian làm việc.
+ *
+ * Đây là **nơi duy nhất** được ghi cột `path` / `depth`. Lý do không cho INSERT
+ * tay: `path` là dữ liệu dẫn xuất từ cha, và đổi cha mà quên ghi lại path cho cả
+ * nhánh con thì cây trông vẫn đúng trên UI trong khi phạm vi đã sai — dạng lỗi
+ * im lặng, chỉ lộ ra lúc ai đó thấy dữ liệu đáng lẽ không được thấy.
+ *
+ * Ba luật cưỡng chế ở đây chứ không phải quy ước miệng: trần độ sâu (Δ9), chống
+ * chu trình, và repath cả nhánh khi đổi cha.
+ */
+
+import {
+  assertDepthLimit,
+  assertNoCycle,
+  buildPath,
+  pathDepth,
+  repathSubtree,
+  subtreePrefix,
+  WorkspaceTreeError,
+} from "./tree";
+import { getWorkspaceConfig } from "./scope";
+import { DEFAULT_MAX_CHILDREN, DEFAULT_MAX_DEPTH } from "./types";
+import type { WorkspaceKind, WorkspaceNode } from "./types";
+
+/**
+ * Delegate Prisma tối thiểu mà service cần. Cố ý không kéo `PrismaClient` vào
+ * core — app truyền `db` thật vào, kiểu khớp về mặt cấu trúc.
+ */
+export interface WorkspaceServiceDb {
+  workspace: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    findMany: (args?: any) => Promise<any[]>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    findUnique: (args: any) => Promise<any | null>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    create: (args: any) => Promise<any>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    update: (args: any) => Promise<any>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    count: (args?: any) => Promise<number>;
+  };
+}
+
+export interface CreateWorkspaceInput {
+  code: string;
+  name: string;
+  kind?: WorkspaceKind;
+  parentId?: string | null;
+  settings?: unknown;
+  /** Cho phép chỉ định id — dùng khi backfill để `workspace.id = branch.id`. */
+  id?: string;
+}
+
+export interface MoveWorkspaceInput {
+  id: string;
+  newParentId: string | null;
+}
+
+/** Đọc toàn bộ cây. Bảng này cỡ chục–trăm dòng, nạp hết rẻ hơn mọi cách khác. */
+async function loadTree(db: WorkspaceServiceDb): Promise<WorkspaceNode[]> {
+  const rows = await db.workspace.findMany({
+    select: { id: true, parentId: true, path: true, kind: true, name: true },
+  });
+  return rows as WorkspaceNode[];
+}
+
+/**
+ * Luật nhãn: `kinds` khai `childKinds` / `canHaveChildren` thì cưỡng chế ở đây.
+ * Không khai gì = cho hết, engine vẫn chạy.
+ */
+function assertKindAllowed(
+  parentKind: WorkspaceKind | undefined,
+  childKind: WorkspaceKind | undefined,
+): void {
+  const kinds = getWorkspaceConfig().kinds;
+  if (!kinds || !parentKind) return;
+  const parent = kinds.find((k) => k.key === parentKind);
+  if (!parent) return;
+  if (parent.canHaveChildren === false) {
+    throw new WorkspaceTreeError(
+      `"${parent.label}" không được có workspace con.`,
+    );
+  }
+  if (
+    parent.childKinds &&
+    childKind &&
+    !parent.childKinds.includes(childKind)
+  ) {
+    const allowed = parent.childKinds
+      .map((k) => kinds.find((x) => x.key === k)?.label ?? k)
+      .join(", ");
+    throw new WorkspaceTreeError(
+      `Dưới "${parent.label}" chỉ đặt được: ${allowed}.`,
+    );
+  }
+}
+
+/**
+ * Cảnh báo (KHÔNG chặn) khi một nút có quá nhiều con trực tiếp. GCP chốt cứng
+ * 300 folder/cha; ta cảnh báo ở 200 vì UI cây mới là chỗ gãy trước, và chặn
+ * cứng một thao tác tạo hợp lệ thì tệ hơn là báo cho người vận hành biết.
+ */
+async function warnIfTooManyChildren(
+  db: WorkspaceServiceDb,
+  parentId: string | null,
+  onWarn?: (message: string) => void,
+): Promise<void> {
+  if (!parentId || !onWarn) return;
+  const max = getWorkspaceConfig().maxChildren ?? DEFAULT_MAX_CHILDREN;
+  const count = await db.workspace.count({ where: { parentId } });
+  if (count >= max) {
+    onWarn(
+      `Không gian này đã có ${count} nút con (ngưỡng khuyến nghị ${max}) — cân nhắc chia thêm một tầng.`,
+    );
+  }
+}
+
+export interface WorkspaceServiceOptions {
+  onWarn?: (message: string) => void;
+}
+
+/**
+ * Tạo nút mới. `path` do service tính từ cha, `depth` suy ra từ `path` — người
+ * gọi không truyền hai trường này.
+ */
+export async function createWorkspace(
+  db: WorkspaceServiceDb,
+  input: CreateWorkspaceInput,
+  options: WorkspaceServiceOptions = {},
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Promise<any> {
+  const config = getWorkspaceConfig();
+  const maxDepth = config.maxDepth ?? DEFAULT_MAX_DEPTH;
+
+  let parentPath: string | null = null;
+  if (input.parentId) {
+    const parent = await db.workspace.findUnique({
+      where: { id: input.parentId },
+      select: { id: true, path: true, kind: true },
+    });
+    if (!parent) {
+      throw new WorkspaceTreeError("Không tìm thấy workspace cha.");
+    }
+    assertKindAllowed(parent.kind, input.kind);
+    parentPath = parent.path;
+  }
+
+  // Id phải biết TRƯỚC khi tính path (path chứa chính id nó). Prisma sinh cuid ở
+  // tầng client nên không lấy được id trước — vì vậy service tự sinh.
+  const id = input.id ?? generateId();
+  const path = buildPath(parentPath, id);
+  assertDepthLimit(path, maxDepth);
+  await warnIfTooManyChildren(db, input.parentId ?? null, options.onWarn);
+
+  return db.workspace.create({
+    data: {
+      id,
+      code: input.code,
+      name: input.name,
+      kind: input.kind ?? "unit",
+      parentId: input.parentId ?? null,
+      path,
+      depth: pathDepth(path),
+      settings: input.settings ?? undefined,
+    },
+  });
+}
+
+/**
+ * Đổi cha. Ghi lại `path` + `depth` cho **cả nhánh con**, trong một transaction
+ * nếu app truyền vào client có `$transaction`; không có thì tuần tự.
+ *
+ * Trả về số nút đã cập nhật (gồm chính nút được chuyển).
+ */
+export async function moveWorkspace(
+  db: WorkspaceServiceDb,
+  input: MoveWorkspaceInput,
+  options: WorkspaceServiceOptions = {},
+): Promise<number> {
+  const config = getWorkspaceConfig();
+  const maxDepth = config.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const nodes = await loadTree(db);
+
+  const moved = nodes.find((n) => n.id === input.id);
+  if (!moved)
+    throw new WorkspaceTreeError("Không tìm thấy workspace cần chuyển.");
+
+  assertNoCycle(input.id, input.newParentId, nodes);
+
+  let newParentPath: string | null = null;
+  if (input.newParentId) {
+    const parent = nodes.find((n) => n.id === input.newParentId);
+    if (!parent) throw new WorkspaceTreeError("Không tìm thấy workspace cha.");
+    assertKindAllowed(parent.kind, moved.kind);
+    newParentPath = parent.path;
+  }
+
+  const updates = repathSubtree(input.id, newParentPath, nodes);
+  // Kiểm trần TRƯỚC khi ghi bất cứ dòng nào: nhánh sâu chuyển xuống dưới một nút
+  // đã sâu sẵn là cách dễ nhất vượt trần mà không ai để ý.
+  for (const update of updates) {
+    assertDepthLimit(update.path, maxDepth);
+  }
+  await warnIfTooManyChildren(db, input.newParentId, options.onWarn);
+
+  for (const update of updates) {
+    await db.workspace.update({
+      where: { id: update.id },
+      data: {
+        path: update.path,
+        depth: update.depth,
+        // Chỉ nút được chuyển mới đổi cha; con cháu giữ nguyên cha của chúng.
+        ...(update.id === input.id ? { parentId: input.newParentId } : {}),
+      },
+    });
+  }
+  return updates.length;
+}
+
+/**
+ * Nút + toàn bộ con cháu. Dùng cho trang chi tiết và cho phép xoá theo nhánh.
+ */
+export async function listSubtree(
+  db: WorkspaceServiceDb,
+  rootId: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Promise<any[]> {
+  const root = await db.workspace.findUnique({
+    where: { id: rootId },
+    select: { id: true, path: true },
+  });
+  if (!root) return [];
+  return db.workspace.findMany({
+    where: { path: { startsWith: subtreePrefix(root.path) } },
+    orderBy: { path: "asc" },
+  });
+}
+
+/**
+ * Vô hiệu hoá cả nhánh. Cố ý KHÔNG xoá cứng: nút đã có chứng từ tham chiếu mà
+ * xoá đi thì phạm vi của những chứng từ đó thành mồ côi.
+ */
+export async function deactivateSubtree(
+  db: WorkspaceServiceDb,
+  rootId: string,
+): Promise<number> {
+  const nodes = await listSubtree(db, rootId);
+  for (const node of nodes) {
+    await db.workspace.update({
+      where: { id: node.id },
+      data: { isActive: false },
+    });
+  }
+  return nodes.length;
+}
+
+/** Dựng cây lồng nhau cho UI từ danh sách phẳng. */
+export interface WorkspaceTreeItem extends WorkspaceNode {
+  children: WorkspaceTreeItem[];
+}
+
+/** `T` cộng thêm nhánh con — giữ nguyên mọi trường app tự thêm. */
+export type WorkspaceTreeOf<T> = T & { children: WorkspaceTreeOf<T>[] };
+
+/**
+ * Dựng cây từ danh sách phẳng, GIỮ NGUYÊN kiểu của phần tử đầu vào.
+ *
+ * Generic chứ không nhận cứng `WorkspaceNode`: trang danh sách còn kèm `code`,
+ * `memberCount`, `kindLabel`… — những trường `WorkspaceNode` không khai. Nếu
+ * tham số cứng kiểu, mọi nơi gọi phải `as any` để lọt, và `as any` thì mất luôn
+ * việc kiểm kiểu ở đầu ra: cây trả về coi như `any`, gõ sai tên trường cũng
+ * không ai báo. Ràng buộc chỉ cần đúng hai thứ hàm này thật sự đọc.
+ */
+export function buildTree<T extends { id: string; parentId?: string | null }>(
+  nodes: readonly T[],
+): WorkspaceTreeOf<T>[] {
+  const byId = new Map<string, WorkspaceTreeOf<T>>();
+  for (const node of nodes)
+    byId.set(node.id, { ...node, children: [] } as WorkspaceTreeOf<T>);
+
+  const roots: WorkspaceTreeOf<T>[] = [];
+  for (const node of byId.values()) {
+    const parent = node.parentId
+      ? byId.get(node.parentId as string)
+      : undefined;
+    if (parent) parent.children.push(node);
+    else roots.push(node);
+  }
+  return roots;
+}
+
+/**
+ * Sinh id kiểu cuid rút gọn. Core không phụ thuộc `@paralleldrive/cuid2`, và id
+ * ở đây chỉ cần duy nhất + an toàn khi nhét vào `path` (chữ và số, không `/`).
+ */
+function generateId(): string {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  return `w${Array.from(bytes, (b) => b.toString(36).padStart(2, "0")).join("")}`;
+}