@goplusvn/core 0.1.75 → 0.1.76

package/src/workspace/tree.ts

@@ -0,0 +1,193 @@
+/**
+ * Cây không gian làm việc — HÀM THUẦN, không DB, không singleton.
+ *
+ * Bung con cháu bằng **materialized path** (`/{ancestor}/…/{self}/`) chứ không
+ * đệ quy runtime hay CTE: gán một người vào "Spartronics" phải tự động cho họ
+ * thấy "Spartronics / Kho", "Spartronics / QC"… và việc đó phải là MỘT câu
+ * `path LIKE '/spartronics-id/%'`, chạy được với index btree.
+ *
+ * Luật hợp nhất (Δ7): quyền chảy XUỐNG và HỢP lại. Nút con KHÔNG siết được nút
+ * cha — cấp rộng ở cha rồi cấp hẹp ở con thì user vẫn giữ phần rộng. Đây là
+ * hành vi của cả GCP lẫn AWS; muốn cấm phải là cơ chế deny riêng, và kỳ đầu ta
+ * cố ý KHÔNG làm deny.
+ */
+
+import { DEFAULT_MAX_DEPTH } from "./types";
+import type { WorkspaceNode } from "./types";
+
+export const PATH_SEPARATOR = "/";
+
+/** Path của nút gốc — cha rỗng. */
+export const ROOT_PATH = PATH_SEPARATOR;
+
+/**
+ * `buildPath("/a/", "b")` → `"/a/b/"`. Luôn có `/` hai đầu để `startsWith` và
+ * `LIKE` không bắt nhầm id có tiền tố trùng nhau.
+ */
+export function buildPath(
+  parentPath: string | null | undefined,
+  id: string,
+): string {
+  const base = normalizePath(parentPath ?? ROOT_PATH);
+  return `${base}${id}${PATH_SEPARATOR}`;
+}
+
+/** Chuẩn hoá: luôn mở và đóng bằng `/`, không có `//`. */
+export function normalizePath(path: string): string {
+  const trimmed = path.split(PATH_SEPARATOR).filter(Boolean);
+  return `${PATH_SEPARATOR}${trimmed.join(PATH_SEPARATOR)}${trimmed.length ? PATH_SEPARATOR : ""}`;
+}
+
+/** Các id từ gốc xuống tới chính nó. */
+export function pathSegments(path: string): string[] {
+  return path.split(PATH_SEPARATOR).filter(Boolean);
+}
+
+/** Độ sâu — nút gốc = 1. */
+export function pathDepth(path: string): number {
+  return pathSegments(path).length;
+}
+
+/** Id của chính nút (đoạn cuối). */
+export function selfIdFromPath(path: string): string | undefined {
+  const segments = pathSegments(path);
+  return segments[segments.length - 1];
+}
+
+/** Id cha (đoạn áp cuối); `undefined` với nút gốc. */
+export function parentIdFromPath(path: string): string | undefined {
+  const segments = pathSegments(path);
+  return segments.length >= 2 ? segments[segments.length - 2] : undefined;
+}
+
+/**
+ * `path` nằm trong nhánh của `ancestorPath`? Mặc định TÍNH CẢ CHÍNH NÓ — vì
+ * "được gán nhánh X" luôn có nghĩa là thấy cả X.
+ */
+export function isInSubtree(
+  path: string,
+  ancestorPath: string,
+  options?: { includeSelf?: boolean },
+): boolean {
+  const self = normalizePath(path);
+  const ancestor = normalizePath(ancestorPath);
+  if (self === ancestor) return options?.includeSelf !== false;
+  return self.startsWith(ancestor);
+}
+
+/**
+ * Tiền tố dùng cho `path LIKE '<prefix>%'` / `startsWith` khi truy vấn con cháu
+ * của một nút. Truyền path của nút, KHÔNG phải id.
+ */
+export function subtreePrefix(path: string): string {
+  return normalizePath(path);
+}
+
+/**
+ * Bung `rootIds` thành `rootIds` + toàn bộ con cháu, dựa trên danh sách nút có
+ * sẵn trong bộ nhớ. Bản dùng cho test và cho app đã nạp sẵn cây; bản đi DB nằm
+ * ở `scope.ts`.
+ *
+ * Id không có trong `nodes` vẫn được GIỮ LẠI: app mức 0 (chưa có bảng
+ * `workspaces`) truyền cây rỗng, và mất id ở đây nghĩa là user đang có phạm vi
+ * bỗng thành không thấy gì.
+ */
+export function selfAndDescendants(
+  rootIds: string[],
+  nodes: readonly WorkspaceNode[],
+): string[] {
+  if (rootIds.length === 0) return [];
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const prefixes = rootIds
+    .map((id) => byId.get(id)?.path)
+    .filter((path): path is string => Boolean(path))
+    .map(subtreePrefix);
+
+  const result = new Set(rootIds);
+  if (prefixes.length > 0) {
+    for (const node of nodes) {
+      if (prefixes.some((prefix) => isInSubtree(node.path, prefix))) {
+        result.add(node.id);
+      }
+    }
+  }
+  return [...result];
+}
+
+/**
+ * Đổi cha một nút ⇒ phải ghi lại `path` cho CẢ nhánh con. Quên bước này thì cây
+ * trông đúng trên UI mà phạm vi thì sai — kiểu bug im lặng tệ nhất.
+ *
+ * Trả về danh sách `{ id, path }` cần UPDATE, gồm cả chính nút được chuyển.
+ */
+export function repathSubtree(
+  movedId: string,
+  newParentPath: string | null,
+  nodes: readonly WorkspaceNode[],
+): Array<{ id: string; path: string; depth: number }> {
+  const moved = nodes.find((node) => node.id === movedId);
+  if (!moved) return [];
+
+  const oldPrefix = subtreePrefix(moved.path);
+  const newPath = buildPath(newParentPath, movedId);
+  const updates: Array<{ id: string; path: string; depth: number }> = [
+    { id: movedId, path: newPath, depth: pathDepth(newPath) },
+  ];
+
+  for (const node of nodes) {
+    if (node.id === movedId) continue;
+    if (!isInSubtree(node.path, oldPrefix, { includeSelf: false })) continue;
+    const suffix = normalizePath(node.path).slice(oldPrefix.length);
+    const nextPath = `${newPath}${suffix}`;
+    updates.push({ id: node.id, path: nextPath, depth: pathDepth(nextPath) });
+  }
+  return updates;
+}
+
+export class WorkspaceTreeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkspaceTreeError";
+  }
+}
+
+/**
+ * Chống chu trình: không cho một nút nhận chính nó (hoặc con cháu của nó) làm
+ * cha. Chu trình trong cây phạm vi không chỉ làm treo truy vấn — nó làm
+ * `selfAndDescendants` trả về tập sai, tức là rò dữ liệu.
+ */
+export function assertNoCycle(
+  movedId: string,
+  newParentId: string | null | undefined,
+  nodes: readonly WorkspaceNode[],
+): void {
+  if (!newParentId) return;
+  if (newParentId === movedId) {
+    throw new WorkspaceTreeError("Không gian không thể là cha của chính nó.");
+  }
+  const parent = nodes.find((node) => node.id === newParentId);
+  const moved = nodes.find((node) => node.id === movedId);
+  if (!parent || !moved) return;
+  if (isInSubtree(parent.path, subtreePrefix(moved.path))) {
+    throw new WorkspaceTreeError(
+      "Không thể chuyển một không gian vào bên trong nhánh con của chính nó.",
+    );
+  }
+}
+
+/**
+ * Trần độ sâu (Δ9). GCP cho folder lồng 10 tầng; ta chốt 4 vì `path LIKE` và
+ * UI cây đều xuống cấp theo độ sâu, mà 4 tầng đã phủ hết
+ * `org → khách hàng → chi nhánh → phòng ban`.
+ */
+export function assertDepthLimit(
+  path: string,
+  maxDepth: number = DEFAULT_MAX_DEPTH,
+): void {
+  const depth = pathDepth(path);
+  if (depth > maxDepth) {
+    throw new WorkspaceTreeError(
+      `Cây không gian tối đa ${maxDepth} tầng — đường dẫn này sâu ${depth} tầng.`,
+    );
+  }
+}

package/src/workspace/types.ts

@@ -0,0 +1,182 @@
+/**
+ * Phạm vi dữ liệu theo KHÔNG GIAN LÀM VIỆC — hợp đồng chung.
+ *
+ * Tổng quát hoá `branch-scope`: chi nhánh / đơn vị / phòng ban / tổ chức không
+ * phải bốn cơ chế, mà là MỘT cây có nhãn `kind`. Coi chúng là bốn thứ khác nhau
+ * thì mỗi app phải tự đấu dây lại phần phân quyền — đó là lý do module này tồn
+ * tại.
+ *
+ * Xem `docs/WORKSPACE-MULTITENANT-PLAN.md` (thiết kế) và
+ * `docs/WORKSPACE-RESEARCH-IAM.md` (đối chiếu 10 hệ IAM lớn).
+ */
+
+import type { BranchScope } from "../branch-scope/types";
+import { NO_BRANCH_ACCESS } from "../branch-scope/types";
+
+/**
+ * Sentinel "không truy cập được gì". Cố ý DÙNG LẠI đúng hằng của branch-scope
+ * chứ không khai chuỗi mới: hai module chạy chung một lưới, hai sentinel khác
+ * nhau là kiểu bug chỉ lộ ra khi dữ liệu đã rò.
+ */
+export const NO_WORKSPACE_ACCESS = NO_BRANCH_ACCESS;
+
+/** Trần độ sâu cây (Δ9 — GCP cho folder 10 tầng; ta không cần quá 4). */
+export const DEFAULT_MAX_DEPTH = 4;
+
+/** Ngưỡng cảnh báo số con trực tiếp của một nút (GCP: 300 folder/cha). */
+export const DEFAULT_MAX_CHILDREN = 200;
+
+/**
+ * Nhãn của một nút. KHÔNG đổi logic — chỉ đổi chữ hiện trên UI và luật cấu
+ * hình. Vinhhoa hiện "Chi nhánh", spartronics hiện "Đơn vị", thingtodo hiện
+ * "Khách hàng → Phòng ban", cùng một engine.
+ */
+export type WorkspaceKind =
+  | "org"
+  | "unit"
+  | "branch"
+  | "department"
+  | (string & {});
+
+export interface WorkspaceKindConfig {
+  key: WorkspaceKind;
+  /** Chữ hiện trên UI, số ít. VD "Chi nhánh". */
+  label: string;
+  /** Nhãn con được phép nằm dưới nhãn này; bỏ trống = cho hết. */
+  childKinds?: WorkspaceKind[];
+  canHaveChildren?: boolean;
+}
+
+/** Nút trong cây — hình dạng TỐI THIỂU mà engine cần đọc. */
+export interface WorkspaceNode {
+  id: string;
+  parentId?: string | null;
+  /** Materialized path `/{ancestor}/…/{self}/`. Service ghi, KHÔNG cho sửa tay. */
+  path: string;
+  kind?: WorkspaceKind;
+  name?: string;
+}
+
+/** Một dòng `user_workspaces`. */
+export interface WorkspaceMembership {
+  workspaceId: string;
+  /** Quản trị viên của nhánh này — trả lời "nhánh nào", KHÔNG phải "được làm gì". */
+  isAdmin?: boolean;
+  isDefault?: boolean;
+}
+
+/**
+ * Phạm vi của một phiên.
+ *
+ * KẾ THỪA `BranchScope` là có chủ đích: `allowedBranchIds` giữ đúng mảng với
+ * `allowedIds`, nên một `WorkspaceScope` cắm thẳng vào mọi hàm branch-scope cũ
+ * (`scopedBranchWhere`, `canAccessBranch`, guard lớp 2) mà không app nào phải
+ * sửa một dòng import. Đừng gán tay hai trường này lệch nhau — dùng
+ * `createWorkspaceScope()`.
+ */
+export interface WorkspaceScope extends BranchScope {
+  canViewAll: boolean;
+  /** Nút được gán TRỰC TIẾP, chưa bung con cháu. */
+  rootIds: string[];
+  /** rootIds + toàn bộ con cháu. undefined khi canViewAll; [sentinel] khi chưa gán gì. */
+  allowedIds?: string[];
+  /** Nhánh user là quản trị viên, ĐÃ bung con cháu. Rỗng = không được uỷ quyền gì. */
+  adminIds: string[];
+  /** Không gian mở sẵn khi đăng nhập / gán cho bản ghi mới tạo. */
+  defaultId?: string;
+}
+
+/**
+ * Thang phạm vi 5 nấc (Δ1 — theo Dynamics 365: None → Basic → Local → Deep →
+ * Global). Nấc cao BAO TRỌN nấc thấp. Bản thiết kế đầu chỉ có 3 nấc và thiếu
+ * hẳn "chỉ bản ghi của tôi" — nấc mà vai trò nhân viên bán hàng / kỹ thuật viên
+ * cần tới.
+ */
+export type ScopeLevel = "none" | "own" | "workspace" | "subtree" | "all";
+
+/** Thứ tự từ hẹp tới rộng — index dùng để so "nấc nào cao hơn". */
+export const SCOPE_LEVELS: readonly ScopeLevel[] = [
+  "none",
+  "own",
+  "workspace",
+  "subtree",
+  "all",
+] as const;
+
+export const SCOPE_LEVEL_LABELS: Record<ScopeLevel, string> = {
+  none: "Không",
+  own: "Của tôi",
+  workspace: "Không gian của tôi",
+  subtree: "Cả nhánh con",
+  all: "Tất cả",
+};
+
+/** Chỉ cần đúng phần delegate mà scope dùng tới — không kéo PrismaClient vào core. */
+export interface WorkspaceScopeDb {
+  userWorkspace: {
+    findMany: (args: {
+      where: { userId: string };
+      select: { workspaceId: true; isAdmin: true; isDefault: true };
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }) => Promise<any[]>;
+  };
+  workspace: {
+    findMany: (args: {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      where: any;
+      select: { id: true; path: true };
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }) => Promise<any[]>;
+  };
+}
+
+export interface WorkspaceScopeConfig<TSession = unknown> {
+  /** Nhãn hiển thị theo app. Bỏ trống = engine vẫn chạy, UI tự đặt chữ. */
+  kinds?: WorkspaceKindConfig[];
+  /**
+   * Cột mang phạm vi trên chứng từ. Mỗi app một tên: `branchId` (vinhhoa),
+   * `departmentId` (thingtodo), `workspaceId` (app mới). Khai MỘT lần ở đây,
+   * không rải ra call-site.
+   */
+  scopeField?: string;
+  /**
+   * Quan hệ nối NGƯỜI DÙNG với không gian, dùng khi lọc chính danh sách người
+   * dùng (`memberScopeWhere`). Mức 0 khai `userBranches`; app đã lên feature
+   * `workspaces` để mặc định `userWorkspaces`.
+   */
+  membershipRelation?: string;
+  /** Cột khoá không gian trong quan hệ trên. Mặc định `workspaceId`. */
+  membershipField?: string;
+  /**
+   * Nguồn membership mặc định: 2 bảng `user_workspaces` + `workspaces`. Bỏ
+   * trống được NẾU đã khai `getMemberships`.
+   */
+  db?: WorkspaceScopeDb;
+  /**
+   * MỨC 0 — app chưa có bảng `workspaces` cắm thẳng nguồn sẵn có vào đây
+   * (vinhhoa: `user_branches`). Không có cây ⇒ không bung con cháu, hành vi
+   * giống hệt branch-scope hôm nay.
+   */
+  getMemberships?: (
+    session: TSession,
+  ) =>
+    | WorkspaceMembership[]
+    | string[]
+    | null
+    | undefined
+    | Promise<WorkspaceMembership[] | string[] | null | undefined>;
+  /**
+   * Bung con cháu. Bỏ trống + có `db` ⇒ dùng bản mặc định (2 truy vấn theo
+   * materialized path). Bỏ trống + không `db` ⇒ **cây phẳng**, allowedIds =
+   * rootIds. Đó là mức 0, an toàn: hẹp hơn chứ không rộng hơn.
+   */
+  expandDescendants?: (rootIds: string[]) => Promise<string[]> | string[];
+  /** Lấy id user từ session của app. */
+  getUserId: (session: TSession) => string | null | undefined;
+  /** "Xem mọi không gian" — app tự quyết (vai trò quản trị / quyền `view-all-workspaces`). */
+  canViewAll: (session: TSession) => boolean;
+  /** Trần độ sâu cây. Mặc định 4 (Δ9). */
+  maxDepth?: number;
+  /** Ngưỡng cảnh báo số con trực tiếp. Mặc định 200. */
+  maxChildren?: number;
+}