@goplusvn/core 0.1.57 → 0.1.59

package/src/storage/storage-service.ts

@@ -0,0 +1,280 @@
+import { mkdir, readFile, rm, stat, writeFile, readdir } from "fs/promises";
+import { dirname, join, sep } from "path";
+
+import { assertSafeKey } from "./keys";
+import {
+  StorageNotFoundError,
+  isNotFoundError,
+  type StorageConfigInput,
+  type StorageDriver,
+  type StorageObjectInfo,
+  type StorageRemoteConfig,
+} from "./types";
+
+/**
+ * Kho tập tin dùng chung của goerp.
+ *
+ * HAI CHẾ ĐỘ, chọn theo runtime chứ không theo build:
+ *   • `remote` — S3/MinIO, khi `STORAGE_TYPE=s3` trong `system_configs` VÀ app
+ *     có cắm driver (`@goerp/core/storage/s3`).
+ *   • `local`  — thư mục đĩa PRIVATE (mặc định `<cwd>/storage/files`). Đây là
+ *     mặc định để app mới chạy được ngay, chưa cần dựng MinIO.
+ *
+ * Cấu hình nằm trong DB (bảng `system_configs`) chứ không phải env: admin đổi
+ * endpoint trong màn hình cấu hình rồi `clearCache()` là ăn ngay, không cần
+ * deploy lại. App cắm phụ thuộc một lần ở composition root:
+ *
+ *   configureStorage({ db, driver: createS3Driver() })
+ */
+
+const CONFIG_KEYS = [
+  "STORAGE_TYPE",
+  "S3_ENDPOINT",
+  "S3_PUBLIC_ENDPOINT",
+  "S3_REGION",
+  "S3_BUCKET",
+  "S3_ACCESS_KEY",
+  "S3_SECRET_KEY",
+  "S3_REJECT_UNAUTHORIZED",
+] as const;
+
+let configured: StorageConfigInput | null = null;
+let cachedRemote: StorageRemoteConfig | null = null;
+let cacheLoaded = false;
+
+export function configureStorage(input: StorageConfigInput): void {
+  configured = input;
+  clearStorageCache();
+}
+
+/** Quên cấu hình đã đọc từ DB — gọi sau khi admin sửa S3_*. */
+export function clearStorageCache(): void {
+  cachedRemote = null;
+  cacheLoaded = false;
+}
+
+function requireConfigured(): StorageConfigInput {
+  if (!configured) {
+    throw new Error(
+      "[storage] chưa configureStorage({ db, driver? }) — gọi 1 lần lúc khởi tạo app (cạnh configureSettingsService).",
+    );
+  }
+  return configured;
+}
+
+function localRoot(): string {
+  return configured?.localDir ?? join(process.cwd(), "storage", "files");
+}
+
+/** Giá trị trong `system_configs` có thể là JSON string hoặc chuỗi thô. */
+function parseValue(raw: string | null): string {
+  if (raw == null) return "";
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "string" ? parsed : String(parsed);
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * Đọc cấu hình S3 từ DB (memo hoá). Trả `null` khi chưa bật hoặc thiếu trường
+ * bắt buộc — engine tự rơi về chế độ local thay vì ném lỗi giữa request.
+ */
+export async function getRemoteConfig(): Promise<StorageRemoteConfig | null> {
+  if (cacheLoaded) return cachedRemote;
+
+  const { db, driver } = requireConfigured();
+  cacheLoaded = true;
+  cachedRemote = null;
+
+  // Không có driver thì đọc config cũng vô nghĩa — khỏi phải hỏi DB.
+  if (!driver) return null;
+
+  const rows = await db.systemConfig.findMany({
+    where: { key: { in: [...CONFIG_KEYS] } },
+    select: { key: true, value: true },
+  });
+
+  const map: Record<string, string> = {};
+  for (const row of rows) map[row.key] = parseValue(row.value);
+
+  if ((map.STORAGE_TYPE || "").toLowerCase() !== "s3") return null;
+
+  const endpoint = map.S3_ENDPOINT || "";
+  const bucket = map.S3_BUCKET || "";
+  const accessKey = map.S3_ACCESS_KEY || "";
+  const secretKey = map.S3_SECRET_KEY || "";
+  if (!endpoint || !bucket || !accessKey || !secretKey) {
+    console.warn(
+      "[storage] STORAGE_TYPE=s3 nhưng thiếu S3_ENDPOINT/S3_BUCKET/S3_ACCESS_KEY/S3_SECRET_KEY — tạm dùng đĩa local.",
+    );
+    return null;
+  }
+
+  cachedRemote = {
+    endpoint,
+    publicEndpoint: map.S3_PUBLIC_ENDPOINT || endpoint,
+    region: map.S3_REGION || "us-east-1",
+    bucket,
+    accessKey,
+    secretKey,
+    rejectUnauthorized: map.S3_REJECT_UNAUTHORIZED === "true",
+  };
+  return cachedRemote;
+}
+
+/** Có đang chạy trên kho từ xa không (false = đĩa local). */
+export async function isRemoteStorageEnabled(): Promise<boolean> {
+  return (await getRemoteConfig()) !== null;
+}
+
+async function withRemote<T>(
+  fn: (driver: StorageDriver, config: StorageRemoteConfig) => Promise<T>,
+): Promise<T | null> {
+  const config = await getRemoteConfig();
+  if (!config) return null;
+  return fn(requireConfigured().driver as StorageDriver, config);
+}
+
+/**
+ * Chặn cửa hậu "im lặng rơi về local" ở app đã chạy S3: ghi thành công vào đĩa
+ * container = mất tập tin ở lần deploy sau, tệ hơn hẳn một lỗi ồn ào.
+ */
+function assertLocalAllowed(): void {
+  if (configured?.requireRemote) {
+    throw new Error(
+      "[storage] requireRemote=true nhưng kho S3 chưa sẵn sàng — kiểm tra STORAGE_TYPE/S3_* trong system_configs. Từ chối dùng đĩa local.",
+    );
+  }
+}
+
+function localPath(key: string): string {
+  assertLocalAllowed();
+  return join(localRoot(), ...assertSafeKey(key).split("/"));
+}
+
+/** Lưu tập tin. Trả về chính `key` để nơi gọi ghép URL. */
+export async function putFile(
+  key: string,
+  body: Buffer,
+  contentType = "application/octet-stream",
+): Promise<string> {
+  assertSafeKey(key);
+  const done = await withRemote((driver, config) =>
+    driver.put(config, key, body, contentType),
+  );
+  if (done === null) {
+    const path = localPath(key);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, body);
+  }
+  return key;
+}
+
+/** Đọc tập tin. Không có → ném `StorageNotFoundError`. */
+export async function getFile(key: string): Promise<Buffer> {
+  assertSafeKey(key);
+  const config = await getRemoteConfig();
+  if (config) {
+    try {
+      return await (requireConfigured().driver as StorageDriver).get(
+        config,
+        key,
+      );
+    } catch (error) {
+      if (isNotFoundError(error)) throw new StorageNotFoundError(key);
+      throw error;
+    }
+  }
+  try {
+    return await readFile(localPath(key));
+  } catch (error) {
+    if (isNotFoundError(error)) throw new StorageNotFoundError(key);
+    throw error;
+  }
+}
+
+/** Xoá tập tin. Không có sẵn cũng coi như thành công (idempotent). */
+export async function deleteFile(key: string): Promise<void> {
+  assertSafeKey(key);
+  const done = await withRemote((driver, config) => driver.remove(config, key));
+  if (done === null) {
+    await rm(localPath(key), { force: true });
+  }
+}
+
+/**
+ * URL có chữ ký để trình duyệt tải thẳng từ kho. Chế độ local không ký được →
+ * trả `null`, nơi gọi rơi về proxy `/api/files/<key>`.
+ */
+export async function getPresignedUrl(
+  key: string,
+  expiresIn = 3600,
+): Promise<string | null> {
+  assertSafeKey(key);
+  return withRemote((driver, config) => driver.presign(config, key, expiresIn));
+}
+
+/**
+ * URL công khai của object. Chế độ local (hoặc MinIO nội bộ) không có URL trực
+ * tiếp cho trình duyệt → dùng proxy của app.
+ */
+export async function getPublicUrl(
+  key: string,
+  proxyPrefix = "/api/files",
+): Promise<string> {
+  assertSafeKey(key);
+  const config = await getRemoteConfig();
+  if (!config) return `${proxyPrefix}/${key}`;
+  return `${config.publicEndpoint}/${config.bucket}/${key}`;
+}
+
+/** Liệt kê object theo tiền tố — dùng cho backup/dọn rác. */
+export async function listObjects(
+  prefix: string,
+): Promise<StorageObjectInfo[]> {
+  const config = await getRemoteConfig();
+  if (config) {
+    return (requireConfigured().driver as StorageDriver).list(config, prefix);
+  }
+
+  assertLocalAllowed();
+  const root = localRoot();
+  const results: StorageObjectInfo[] = [];
+  const walk = async (dir: string): Promise<void> => {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (error) {
+      if (isNotFoundError(error)) return;
+      throw error;
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+        continue;
+      }
+      const key = full.slice(root.length + 1).split(sep).join("/");
+      if (!key.startsWith(prefix)) continue;
+      const info = await stat(full);
+      results.push({ key, size: info.size, lastModified: info.mtime });
+    }
+  };
+  await walk(root);
+  return results;
+}
+
+/** Gom lại thành facade cho nơi gọi thích gọi kiểu `storage.getFile(...)`. */
+export const storage = {
+  clearCache: clearStorageCache,
+  getRemoteConfig,
+  isRemoteEnabled: isRemoteStorageEnabled,
+  put: putFile,
+  get: getFile,
+  delete: deleteFile,
+  getPresignedUrl,
+  getPublicUrl,
+  list: listObjects,
+};

package/src/storage/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Kho tập tin — kiểu dùng chung cho engine, driver và các route factory.
+ *
+ * Core KHÔNG phụ thuộc aws-sdk: driver S3/MinIO nằm ở subpath riêng
+ * `@goerp/core/storage/s3` và được app cắm vào qua `configureStorage`. App nào
+ * chỉ cần đĩa local thì không phải cài thêm gói nào.
+ */
+
+/** Cấu hình S3/MinIO đọc từ bảng `system_configs`. */
+export interface StorageRemoteConfig {
+  /** Endpoint NỘI BỘ — dùng cho upload/get/delete từ phía server. */
+  endpoint: string;
+  /**
+   * Endpoint CÔNG KHAI — chỉ dùng khi ký presigned URL để trình duyệt gọi
+   * thẳng. Khác endpoint nội bộ thì chữ ký phải ký bằng cái này, nếu không
+   * URL trả về trỏ vào host mà trình duyệt không thấy.
+   */
+  publicEndpoint: string;
+  region: string;
+  bucket: string;
+  accessKey: string;
+  secretKey: string;
+  /**
+   * Verify chứng chỉ TLS của endpoint. MẶC ĐỊNH `false` vì MinIO self-hosted
+   * thường dùng cert tự ký — bật `true` (key `S3_REJECT_UNAUTHORIZED`) khi
+   * endpoint có cert hợp lệ.
+   */
+  rejectUnauthorized: boolean;
+}
+
+export interface StorageObjectInfo {
+  key: string;
+  size: number;
+  lastModified?: Date;
+}
+
+/**
+ * Driver kho từ xa. Nhận config theo từng lời gọi (thay vì giữ state) để
+ * `clearCache()` của engine đổi config là ăn ngay — driver tự memo client theo
+ * dấu vân tay config.
+ */
+export interface StorageDriver {
+  put(
+    config: StorageRemoteConfig,
+    key: string,
+    body: Buffer,
+    contentType: string,
+  ): Promise<void>;
+  get(config: StorageRemoteConfig, key: string): Promise<Buffer>;
+  remove(config: StorageRemoteConfig, key: string): Promise<void>;
+  presign(
+    config: StorageRemoteConfig,
+    key: string,
+    expiresIn: number,
+  ): Promise<string>;
+  list(
+    config: StorageRemoteConfig,
+    prefix: string,
+  ): Promise<StorageObjectInfo[]>;
+}
+
+/**
+ * Delegate Prisma tối thiểu — args để `any` CÓ CHỦ ĐÍCH (cùng bài học
+ * SettingsDb/TaskDb: generated types của mỗi app hẹp hơn nên khai chặt sẽ
+ * không assignable).
+ */
+export interface StorageDb {
+  systemConfig: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    findMany(args: any): Promise<{ key: string; value: string | null }[]>;
+  };
+}
+
+export interface StorageConfigInput {
+  db: StorageDb;
+  /**
+   * Driver kho từ xa. Bỏ trống → luôn dùng đĩa local (`localDir`), kể cả khi
+   * `STORAGE_TYPE=s3` trong DB.
+   */
+  driver?: StorageDriver;
+  /** Thư mục fallback khi không có driver / STORAGE_TYPE != s3. */
+  localDir?: string;
+  /**
+   * `true` = CẤM rơi về đĩa local: thiếu/hỏng cấu hình S3 thì ném lỗi thay vì
+   * âm thầm ghi vào đĩa container. Bật cho app production đã chạy S3 — mất
+   * cấu hình mà vẫn "thành công" nghĩa là tập tin bay theo lần deploy sau.
+   */
+  requireRemote?: boolean;
+}
+
+/** Lỗi "không có key này" — engine và driver đều ném ra dạng này. */
+export class StorageNotFoundError extends Error {
+  readonly key: string;
+  constructor(key: string) {
+    super(`Không tìm thấy tập tin: ${key}`);
+    this.name = "StorageNotFoundError";
+    this.key = key;
+  }
+}
+
+/** Nhận diện lỗi 404 từ mọi phía (driver S3 ném NoSuchKey, local ném ENOENT). */
+export function isNotFoundError(error: unknown): boolean {
+  if (error instanceof StorageNotFoundError) return true;
+  const err = error as { name?: string; code?: string; message?: string } | null;
+  if (!err) return false;
+  if (err.name === "NoSuchKey" || err.name === "NotFound") return true;
+  if (err.code === "ENOENT" || err.code === "NoSuchKey") return true;
+  return Boolean(
+    err.message?.includes("NoSuchKey") || err.message?.includes("ENOENT"),
+  );
+}

package/src/storage/upload-handler.ts

@@ -0,0 +1,100 @@
+import type { NextRequest } from "next/server";
+
+import { safeFileName } from "./keys";
+import { putFile } from "./storage-service";
+
+/**
+ * Route factory nhận tập tin tải lên.
+ *
+ * Trả về URL dạng `/api/files/<key>` cho MỌI chế độ kho (S3 hay đĩa local) —
+ * cố ý: URL đã lưu trong cột `attachments` không được đổi nghĩa khi admin bật
+ * hay tắt S3. Bản cũ ở app ghi thẳng vào `public/uploads` khi chưa có S3, tức
+ * chứng từ tài chính và CCCD nằm trong thư mục web đọc công khai không cần
+ * phiên; ở đây đĩa local là thư mục PRIVATE và vẫn phải đi qua proxy có quyền.
+ *
+ *   // src/app/api/upload/route.ts
+ *   export const POST = apiHandler(createUploadHandler())
+ */
+
+export interface UploadHandlerOptions {
+  /** Mặc định 25MB. */
+  maxBytes?: number;
+  /** Đuôi cho phép (chữ thường, không dấu chấm). */
+  allowedExtensions?: string[];
+  /** Tiền tố key trong kho. Mặc định `uploads`. */
+  prefix?: string;
+  /** Tiền tố URL trả về. Mặc định `/api/files`. */
+  urlPrefix?: string;
+  onError?: (error: unknown, req: NextRequest) => Response | Promise<Response>;
+}
+
+const DEFAULT_ALLOWED = [
+  "pdf",
+  "jpg",
+  "jpeg",
+  "png",
+  "gif",
+  "webp",
+  "doc",
+  "docx",
+  "xls",
+  "xlsx",
+  "csv",
+  "txt",
+];
+
+/** Thư mục theo ngày (YYYYMMDD) để một ngày gom về một chỗ. */
+function dateDir(now: Date): string {
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, "0");
+  const d = String(now.getDate()).padStart(2, "0");
+  return `${y}${m}${d}`;
+}
+
+export function createUploadHandler(options: UploadHandlerOptions = {}) {
+  const maxBytes = options.maxBytes ?? 25 * 1024 * 1024;
+  const allowed = new Set(options.allowedExtensions ?? DEFAULT_ALLOWED);
+  const prefix = (options.prefix ?? "uploads").replace(/^\/|\/$/g, "");
+  const urlPrefix = (options.urlPrefix ?? "/api/files").replace(/\/$/, "");
+
+  return async function handler(req: NextRequest): Promise<Response> {
+    try {
+      const formData = await req.formData();
+      const file = formData.get("file");
+      if (!file || typeof file === "string") {
+        return Response.json({ error: "No file uploaded" }, { status: 400 });
+      }
+
+      if (file.size > maxBytes) {
+        const mb = Math.round(maxBytes / (1024 * 1024));
+        return Response.json(
+          { error: `Tập tin quá lớn (tối đa ${mb}MB)` },
+          { status: 413 },
+        );
+      }
+
+      const safeName = safeFileName(file.name || "file");
+      const ext = (safeName.split(".").pop() || "").toLowerCase();
+      if (!allowed.has(ext)) {
+        return Response.json(
+          { error: "Định dạng tập tin không được hỗ trợ" },
+          { status: 415 },
+        );
+      }
+
+      // Chèn timestamp trước phần mở rộng — cùng tên tải lên hai lần không đè nhau.
+      const dot = safeName.lastIndexOf(".");
+      const base = dot > 0 ? safeName.slice(0, dot) : safeName;
+      const key = `${prefix}/${dateDir(new Date())}/${base}_${Date.now()}.${ext}`;
+
+      const buffer = Buffer.from(await file.arrayBuffer());
+      await putFile(key, buffer, file.type || "application/octet-stream");
+
+      return Response.json({ url: `${urlPrefix}/${key}`, key });
+    } catch (error) {
+      if (options.onError) return options.onError(error, req);
+      console.error("[storage] upload lỗi:", error);
+      return Response.json({ error: "Upload failed" }, { status: 500 });
+    }
+  };
+}