@goplusvn/core 0.1.72 → 0.1.73

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

package/src/branding/__tests__/identity.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveBranding, tenantWithBranding } from "../identity";
+import { buildAppManifest, buildBrandingMetadata } from "../pwa";
+
+import type { TenantConfig } from "../../providers/tenant-provider";
+
+const tenant: TenantConfig = {
+  id: "starter",
+  name: "GoERP Starter",
+  branding: {
+    logo: "/images/logos/goeat_logo.png",
+    companyName: "GoERP Starter",
+    tagline: "Nền tảng quản trị",
+  },
+  currency: "VND",
+};
+
+describe("resolveBranding", () => {
+  it("DB đè cấu hình tĩnh; systemName thắng tên pháp lý", () => {
+    const identity = resolveBranding({
+      tenant,
+      company: {
+        name: "CÔNG TY TNHH SPARTRONICS VIỆT NAM",
+        systemName: "Spartronics",
+        updatedAt: new Date("2026-08-01T00:00:00Z"),
+      },
+    });
+
+    expect(identity.appName).toBe("Spartronics");
+    expect(identity.companyName).toBe("CÔNG TY TNHH SPARTRONICS VIỆT NAM");
+  });
+
+  it("DB trống ⇒ giữ nguyên tenant tĩnh, logo không kèm ?v=", () => {
+    const identity = resolveBranding({ tenant, company: null });
+
+    expect(identity.appName).toBe("GoERP Starter");
+    expect(identity.logoUrl).toBe("/api/branding/logo");
+  });
+
+  it("logo LUÔN trỏ route branding kèm ?v=updatedAt, không trỏ file thô", () => {
+    const identity = resolveBranding({
+      tenant,
+      company: {
+        name: "Cty A",
+        // URL thô cần phiên đăng nhập — không được lọt ra ngoài.
+        logoUrl: "/api/files/branding/a.png",
+        updatedAt: new Date("2026-08-01T00:00:00Z"),
+      },
+    });
+
+    expect(identity.logoUrl).toBe(
+      `/api/branding/logo?v=${new Date("2026-08-01T00:00:00Z").getTime()}`,
+    );
+  });
+
+  it("tenantWithBranding thay tên + logo nhưng giữ phần còn lại", () => {
+    const identity = resolveBranding({
+      tenant,
+      company: {
+        systemName: "Spartronics",
+        // chuỗi ISO: đúng thứ nhận được khi hồ sơ đi qua serialize JSON
+        updatedAt: "2026-08-01T00:00:00.000Z",
+      },
+    });
+    const merged = tenantWithBranding(tenant, identity);
+
+    expect(merged.name).toBe("Spartronics");
+    expect(merged.branding.logo).toBe(identity.logoUrl);
+    expect(merged.branding.tagline).toBe("Nền tảng quản trị");
+    expect(merged.currency).toBe("VND");
+  });
+});
+
+describe("PWA", () => {
+  it("manifest cài được: start_url có locale, icon trỏ route branding", () => {
+    const identity = resolveBranding({
+      tenant,
+      company: { systemName: "Spartronics" },
+      themeColor: "#0f7b4c",
+      startUrl: "/vi",
+    });
+    const manifest = buildAppManifest(identity);
+
+    expect(manifest.display).toBe("standalone");
+    expect(manifest.start_url).toBe("/vi");
+    expect(manifest.scope).toBe("/");
+    expect(manifest.theme_color).toBe("#0f7b4c");
+    expect(manifest.icons?.map((i) => i.purpose)).toEqual(["any", "maskable"]);
+    expect(manifest.icons?.[0].src).toContain("/api/branding/logo?variant=");
+  });
+
+  it("metadata khai icons + manifest để đè convention app/icon.*", () => {
+    const identity = resolveBranding({ tenant, company: null });
+    const meta = buildBrandingMetadata(identity);
+
+    expect(meta.manifest).toBe("/manifest.webmanifest");
+    expect(JSON.stringify(meta.icons)).toContain("variant=favicon");
+    expect(JSON.stringify(meta.icons)).toContain("variant=apple");
+  });
+});

package/src/branding/__tests__/logo-route.test.ts

@@ -0,0 +1,143 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createBrandingLogoHandler } from "../logo-route";
+
+/**
+ * Hợp đồng của `/api/branding/logo`. Hai điều KHÔNG được vỡ:
+ * 1. Không bao giờ 500 — favicon và sidebar gọi route này ở mọi trang, 500 là
+ *    bơm rác vào `error_logs` và làm hỏng cả trang đăng nhập.
+ * 2. Chưa upload / file hỏng ⇒ rơi về logo mặc định trong `public/`.
+ */
+
+const readFile = vi.hoisted(() => vi.fn());
+vi.mock("node:fs/promises", () => ({ readFile, default: { readFile } }));
+
+const FILE_BYTES = Buffer.from("logo-tu-kho");
+const PUBLIC_BYTES = Buffer.from("logo-mac-dinh");
+
+function request(url = "http://localhost/api/branding/logo") {
+  return new Request(url);
+}
+
+beforeEach(() => {
+  readFile.mockReset();
+  readFile.mockResolvedValue(PUBLIC_BYTES);
+});
+
+describe("createBrandingLogoHandler", () => {
+  it("phục vụ logo đã upload qua getFile, giữ đúng MIME theo đuôi key", async () => {
+    const getFile = vi.fn().mockResolvedValue(FILE_BYTES);
+    const GET = createBrandingLogoHandler({
+      getCompany: async () => ({
+        logoUrl: "/api/files/branding/logo%20cong%20ty.webp",
+      }),
+      getFile,
+    });
+
+    const res = await GET(request());
+
+    expect(getFile).toHaveBeenCalledWith("branding/logo cong ty.webp");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/webp");
+    expect(Buffer.from(await res.arrayBuffer())).toEqual(FILE_BYTES);
+  });
+
+  it("chưa upload ⇒ dùng ảnh mặc định dưới public/", async () => {
+    const GET = createBrandingLogoHandler({ getCompany: async () => null });
+
+    const res = await GET(request());
+
+    expect(res.status).toBe(200);
+    expect(String(readFile.mock.calls[0][0])).toContain(
+      "public/images/logos/goeat_logo.png",
+    );
+    expect(Buffer.from(await res.arrayBuffer())).toEqual(PUBLIC_BYTES);
+  });
+
+  it("key trỏ file đã xoá ⇒ rơi về mặc định chứ không 500", async () => {
+    const GET = createBrandingLogoHandler({
+      getCompany: async () => ({ logoUrl: "/api/files/da-xoa.png" }),
+      getFile: async () => {
+        throw new Error("NoSuchKey");
+      },
+    });
+
+    const res = await GET(request());
+
+    expect(res.status).toBe(200);
+    expect(Buffer.from(await res.arrayBuffer())).toEqual(PUBLIC_BYTES);
+  });
+
+  it("DB chập chờn ⇒ vẫn trả ảnh mặc định", async () => {
+    const GET = createBrandingLogoHandler({
+      getCompany: async () => {
+        throw new Error("connection refused");
+      },
+    });
+
+    expect((await GET(request())).status).toBe(200);
+  });
+
+  it("không có cả ảnh mặc định ⇒ 404, không ném lỗi", async () => {
+    readFile.mockRejectedValue(new Error("ENOENT"));
+    const GET = createBrandingLogoHandler({ getCompany: async () => null });
+
+    expect((await GET(request())).status).toBe(404);
+  });
+
+  it("?variant= gọi sharp và trả PNG; nhận module có default", async () => {
+    const resized = Buffer.from("png-da-resize");
+    const chain = {
+      resize: vi.fn(() => chain),
+      composite: vi.fn(() => chain),
+      png: vi.fn(() => chain),
+      toBuffer: vi.fn(async () => resized),
+    };
+    const sharp = vi.fn(() => chain);
+    const GET = createBrandingLogoHandler({
+      getCompany: async () => null,
+      loadSharp: async () => ({ default: sharp }),
+    });
+
+    const res = await GET(
+      request("http://localhost/api/branding/logo?variant=apple"),
+    );
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/png");
+    expect(Buffer.from(await res.arrayBuffer())).toEqual(resized);
+    // apple = 180×180, không padding
+    expect(chain.resize).toHaveBeenCalledWith(180, 180, expect.anything());
+  });
+
+  it("sharp lỗi ⇒ trả ảnh gốc thay vì 500", async () => {
+    const GET = createBrandingLogoHandler({
+      getCompany: async () => null,
+      loadSharp: async () => {
+        throw new Error("sharp chưa cài");
+      },
+    });
+
+    const res = await GET(
+      request("http://localhost/api/branding/logo?variant=favicon"),
+    );
+
+    expect(res.status).toBe(200);
+    expect(Buffer.from(await res.arrayBuffer())).toEqual(PUBLIC_BYTES);
+  });
+
+  it("variant lạ ⇒ bỏ qua, không gọi sharp", async () => {
+    const sharp = vi.fn();
+    const GET = createBrandingLogoHandler({
+      getCompany: async () => null,
+      loadSharp: async () => sharp,
+    });
+
+    const res = await GET(
+      request("http://localhost/api/branding/logo?variant=../../etc/passwd"),
+    );
+
+    expect(res.status).toBe(200);
+    expect(sharp).not.toHaveBeenCalled();
+  });
+});

package/src/branding/identity.ts

@@ -0,0 +1,74 @@
+import type { TenantConfig } from "../providers/tenant-provider";
+import type { BrandingCompany, BrandingIdentity } from "./types";
+
+export const DEFAULT_BRANDING_LOGO_PATH = "/api/branding/logo";
+
+export interface ResolveBrandingOptions {
+  /** Hồ sơ công ty đọc từ DB (`getSystemCompany()`). */
+  company?: BrandingCompany | null;
+  /** Cấu hình tĩnh trong `src/configs/tenant.ts` — làm nền khi DB còn trống. */
+  tenant: TenantConfig;
+  /** Đổi nếu app đặt route logo ở đường khác. */
+  logoPath?: string;
+  themeColor?: string;
+  backgroundColor?: string;
+  /** `start_url` của PWA — PHẢI có locale sẵn (`/vi`), tránh 2 chặng redirect. */
+  startUrl?: string;
+}
+
+/**
+ * Hoà giải thương hiệu: **DB đè cấu hình tĩnh**.
+ *
+ * `systemName` (tên ngắn hiển thị app) tách khỏi `name` (tên pháp lý in trên
+ * hoá đơn) có chủ đích — sidebar và tên PWA không thể là "CÔNG TY TNHH ..."
+ * dài ba dòng.
+ *
+ * `logoUrl` LUÔN trỏ route `/api/branding/logo`, không bao giờ trỏ thẳng file
+ * trong `public/`: đổi logo một lần trong DB là mọi bề mặt đổi theo. `?v=` lấy
+ * từ `updatedAt` để phá cache trình duyệt ngay sau khi lưu.
+ */
+export function resolveBranding(
+  options: ResolveBrandingOptions,
+): BrandingIdentity {
+  const { company, tenant } = options;
+  const logoPath = options.logoPath ?? DEFAULT_BRANDING_LOGO_PATH;
+
+  const companyName =
+    company?.name?.trim() || tenant.branding.companyName || tenant.name;
+  const appName = company?.systemName?.trim() || companyName;
+
+  const stamp = company?.updatedAt
+    ? new Date(company.updatedAt).getTime()
+    : null;
+
+  return {
+    appName,
+    companyName,
+    tagline: tenant.branding.tagline ?? "",
+    logoPath,
+    logoUrl: stamp ? `${logoPath}?v=${stamp}` : logoPath,
+    themeColor: options.themeColor ?? "#ffffff",
+    backgroundColor: options.backgroundColor ?? "#ffffff",
+    startUrl: options.startUrl ?? "/",
+  };
+}
+
+/**
+ * Bản `TenantConfig` đã áp thương hiệu từ DB, để truyền thẳng vào
+ * `TenantProvider` — sidebar, header và trang đăng nhập đọc qua
+ * `useOptionalTenant()`.
+ */
+export function tenantWithBranding(
+  tenant: TenantConfig,
+  identity: BrandingIdentity,
+): TenantConfig {
+  return {
+    ...tenant,
+    name: identity.appName,
+    branding: {
+      ...tenant.branding,
+      logo: identity.logoUrl,
+      companyName: identity.appName,
+    },
+  };
+}

package/src/branding/index.ts

@@ -0,0 +1,36 @@
+/**
+ * `@goerp/core/branding` — thương hiệu chạy bằng DỮ LIỆU, không bằng file tĩnh.
+ *
+ * Admin đổi logo/tên ở trang "Hồ sơ công ty" ⇒ sidebar, trang đăng nhập, đầu
+ * trang in, favicon, icon PWA và thẻ chia sẻ đổi theo, vì tất cả cùng trỏ
+ * `/api/branding/logo`. Chưa upload gì thì rơi về logo GoEat mặc định.
+ *
+ * Barrel này CHỈ dùng ở phía server (route handler, layout, manifest) — nó kéo
+ * `node:fs`.
+ */
+
+export {
+  DEFAULT_BRANDING_FALLBACK,
+  createBrandingLogoHandler,
+} from "./logo-route";
+export type {
+  BrandingLogoOptions,
+  SharpFactory,
+  SharpLike,
+} from "./logo-route";
+
+export {
+  DEFAULT_BRANDING_LOGO_PATH,
+  resolveBranding,
+  tenantWithBranding,
+} from "./identity";
+export type { ResolveBrandingOptions } from "./identity";
+
+export { PwaMetaTags, buildAppManifest, buildBrandingMetadata } from "./pwa";
+export type { AppManifestOptions } from "./pwa";
+
+export type {
+  BrandingCompany,
+  BrandingIdentity,
+  BrandingLogoVariant,
+} from "./types";

package/src/branding/logo-route.ts

@@ -0,0 +1,249 @@
+import { readFile } from "node:fs/promises";
+import { join, normalize } from "node:path";
+
+import { logger } from "../utils";
+
+import type { BrandingCompany, BrandingLogoVariant } from "./types";
+
+/**
+ * `GET /api/branding/logo` — MỘT URL duy nhất cho mọi bề mặt thương hiệu.
+ *
+ * Trước đây mỗi app tự viết lại route này (vinhhoa, thingtodo) còn app init từ
+ * core thì KHÔNG có: trang "Hồ sơ công ty" cho upload logo, lưu vào
+ * `companies.logo_url`, rồi không ai đọc — sidebar/favicon vẫn trỏ file tĩnh
+ * trong `public/`. Đây là mắt xích còn thiếu đó, lift lên core.
+ *
+ * Nguyên tắc:
+ * - **Công khai.** Trang đăng nhập và favicon render TRƯỚC khi có phiên, nên
+ *   app phải khai `/api/branding` vào `publicPrefixes` của proxy. Route không
+ *   đọc gì ngoài cột logo nên không mở thêm bề mặt dữ liệu.
+ * - **Không bao giờ 500.** Thiếu logo, hỏng file, sai key ⇒ 404. Favicon và
+ *   sidebar gọi nó ở mọi trang; trả 500 là bơm rác vào `error_logs`.
+ * - **Chưa upload thì rơi về logo GoEat** trong `public/` của app (file
+ *   `images/logos/goeat_logo.png` do `goerp-init` chép sẵn) — không phải logo
+ *   của khách hàng khác còn sót lại từ lúc fork mã nguồn.
+ */
+
+const WHITE = { r: 255, g: 255, b: 255, alpha: 1 };
+const TRANSPARENT = { r: 0, g: 0, b: 0, alpha: 0 };
+
+const VARIANTS: Record<
+  BrandingLogoVariant,
+  { w: number; h: number; bg: typeof WHITE; pad?: number }
+> = {
+  favicon: { w: 64, h: 64, bg: TRANSPARENT },
+  apple: { w: 180, h: 180, bg: WHITE }, // iOS không ưa nền trong suốt
+  icon: { w: 512, h: 512, bg: TRANSPARENT }, // PWA purpose "any"
+  maskable: { w: 512, h: 512, bg: WHITE, pad: 56 }, // safe-zone ~80%
+  og: { w: 1200, h: 630, bg: WHITE, pad: 96 }, // thẻ chia sẻ mạng xã hội
+};
+
+const MIME: Record<string, string> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  gif: "image/gif",
+  svg: "image/svg+xml",
+  ico: "image/x-icon",
+};
+
+function mimeFor(path: string): string {
+  const ext = (path.split("?")[0].split(".").pop() || "").toLowerCase();
+  return MIME[ext] || "application/octet-stream";
+}
+
+/** Ảnh mặc định khi công ty chưa cấu hình logo riêng — nằm dưới `public/`. */
+export const DEFAULT_BRANDING_FALLBACK = "images/logos/goeat_logo.png";
+
+/**
+ * Kiểu tối thiểu của `sharp` mà route cần — khai theo CẤU TRÚC để core không
+ * phải phụ thuộc gói đó.
+ */
+type SharpBackground = { r: number; g: number; b: number; alpha: number };
+export interface SharpLike {
+  resize(
+    width: number,
+    height: number,
+    options: { fit: "contain"; background: SharpBackground },
+  ): SharpLike;
+  composite(items: Array<{ input: Buffer; gravity: string }>): SharpLike;
+  png(): SharpLike;
+  toBuffer(): Promise<Buffer>;
+}
+export type SharpFactory = (
+  input?:
+    | Buffer
+    | {
+        create: {
+          width: number;
+          height: number;
+          channels: 4;
+          background: SharpBackground;
+        };
+      },
+) => SharpLike;
+
+export interface BrandingLogoOptions {
+  /** Đọc hồ sơ công ty. App cắm service của mình vào đây. */
+  getCompany: () => Promise<BrandingCompany | null | undefined>;
+  /**
+   * Đọc tập tin từ kho (`@goerp/core/storage` `getFile`). Bỏ trống thì logo lưu
+   * dạng `/api/files/<key>` sẽ không đọc được và route rơi về ảnh mặc định.
+   */
+  getFile?: (key: string) => Promise<Buffer>;
+  /**
+   * Nạp `sharp` để render `?variant=`. CỐ Ý để app truyền vào
+   * (`() => import("sharp")`): `import` chữ literal nằm trong mã app mới được
+   * Next trace vào bản standalone — core tự `import` bằng biến thì gói bị rơi
+   * khỏi Docker image. Bỏ trống ⇒ route trả ảnh gốc.
+   *
+   * Kiểu là `unknown` vì `sharp` có nhiều overload, khai theo cấu trúc thì mỗi
+   * app phải tự ép kiểu ở chỗ gọi. Nhận cả module namespace lẫn `default`.
+   */
+  loadSharp?: () => Promise<unknown>;
+  /** Ảnh mặc định (đường dẫn tương đối dưới `public/`). */
+  fallbackPublicPath?: string;
+  /** TTL cache trình duyệt. URL luôn kèm `?v=<updatedAt>` nên để dài được. */
+  cacheSeconds?: number;
+}
+
+async function readPublic(relPath: string): Promise<Buffer> {
+  // relPath nằm dưới public/. Giá trị đến từ DB do admin nhập nên rủi ro thấp,
+  // vẫn normalize để chặn path traversal.
+  const safe = normalize(relPath).replace(/^(\.\.([/\\]|$))+/, "");
+  return readFile(join(process.cwd(), "public", safe));
+}
+
+interface LoadedLogo {
+  buffer: Buffer;
+  contentType: string;
+}
+
+async function loadLogo(
+  options: BrandingLogoOptions,
+): Promise<LoadedLogo | null> {
+  const fallbackPath = options.fallbackPublicPath ?? DEFAULT_BRANDING_FALLBACK;
+
+  let configured: string | null = null;
+  try {
+    const company = await options.getCompany();
+    configured = company?.logoUrl ?? company?.logo ?? null;
+  } catch (error) {
+    // DB chập chờn không được phép làm mất favicon của cả app.
+    logger.warn("[branding] không đọc được hồ sơ công ty, dùng logo mặc định", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  if (configured) {
+    try {
+      const clean = configured.split("?")[0];
+      if (clean.startsWith("/api/files/")) {
+        const key = decodeURIComponent(clean.slice("/api/files/".length));
+        if (options.getFile) {
+          return {
+            buffer: await options.getFile(key),
+            contentType: mimeFor(key),
+          };
+        }
+      } else if (clean.startsWith("/")) {
+        // Ảnh nằm sẵn trong public/ (kho local kiểu cũ, hoặc file tĩnh).
+        return {
+          buffer: await readPublic(clean.slice(1)),
+          contentType: mimeFor(clean),
+        };
+      }
+    } catch (error) {
+      // Key trỏ file đã xoá / kho chưa cấu hình — rơi về mặc định, KHÔNG 500.
+      logger.warn("[branding] logo cấu hình không đọc được, dùng mặc định", {
+        logoUrl: configured,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  try {
+    return {
+      buffer: await readPublic(fallbackPath),
+      contentType: mimeFor(fallbackPath),
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function renderVariant(
+  logo: LoadedLogo,
+  variant: BrandingLogoVariant,
+  sharp: SharpFactory,
+): Promise<LoadedLogo> {
+  const spec = VARIANTS[variant];
+  const pad = spec.pad ?? 0;
+  const inner = await sharp(logo.buffer)
+    .resize(spec.w - pad * 2, spec.h - pad * 2, {
+      fit: "contain",
+      background: spec.bg,
+    })
+    .toBuffer();
+
+  const buffer = await sharp({
+    create: {
+      width: spec.w,
+      height: spec.h,
+      channels: 4,
+      background: spec.bg,
+    },
+  })
+    .composite([{ input: inner, gravity: "centre" }])
+    .png()
+    .toBuffer();
+
+  return { buffer, contentType: "image/png" };
+}
+
+function isVariant(value: string | null): value is BrandingLogoVariant {
+  return value !== null && value in VARIANTS;
+}
+
+/**
+ * Dựng handler `GET` cho `app/api/branding/logo/route.ts`.
+ *
+ * Route PHẢI khai `export const dynamic = "force-dynamic"` — logo đổi ngay khi
+ * admin bấm Lưu, không được đóng băng vào build.
+ */
+export function createBrandingLogoHandler(options: BrandingLogoOptions) {
+  const cacheSeconds = options.cacheSeconds ?? 3600;
+
+  return async function GET(request: Request): Promise<Response> {
+    const logo = await loadLogo(options);
+    if (!logo) {
+      // 404 chứ không 500: favicon/sidebar gọi route này ở mọi trang.
+      return new Response("Chưa cấu hình logo", { status: 404 });
+    }
+
+    const variant = new URL(request.url).searchParams.get("variant");
+    let output = logo;
+    if (isVariant(variant) && options.loadSharp) {
+      try {
+        const mod = await options.loadSharp();
+        const sharp = (
+          typeof mod === "function" ? mod : (mod as { default: unknown }).default
+        ) as SharpFactory;
+        output = await renderVariant(logo, variant, sharp);
+      } catch (error) {
+        logger.warn("[branding] resize thất bại, trả ảnh gốc", {
+          variant,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    return new Response(new Uint8Array(output.buffer), {
+      headers: {
+        "Content-Type": output.contentType,
+        "Cache-Control": `public, max-age=${cacheSeconds}`,
+      },
+    });
+  };
+}