create-entity-app-server 0.0.3

package/src/system/utils/date-prefixed-log-stream.ts

@@ -0,0 +1,176 @@
+import {
+    createWriteStream,
+    mkdirSync,
+    readdirSync,
+    rmSync,
+    type WriteStream,
+} from "fs";
+import path from "path";
+import { Writable } from "stream";
+
+type RotationFrequency = "daily" | "hourly";
+
+type DatePrefixedLogStreamOptions = {
+    logDir: string;
+    filename: string;
+    frequency: RotationFrequency;
+    maxFiles: number;
+};
+
+/** 로그 파일명을 `.log` 확장자를 포함한 표준 형식으로 정규화합니다. */
+function normalizeFilename(filename: string): string {
+    const trimmed = filename.trim();
+    if (!trimmed) {
+        return "app.log";
+    }
+    return trimmed.endsWith(".log") ? trimmed : `${trimmed}.log`;
+}
+
+/** 현재 시각과 회전 주기에 맞는 파일 접두 키를 생성합니다. */
+function makePeriodKey(date: Date, frequency: RotationFrequency): string {
+    const year = String(date.getFullYear());
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    if (frequency === "hourly") {
+        const hour = String(date.getHours()).padStart(2, "0");
+        return `${year}-${month}-${day}-${hour}`;
+    }
+    return `${year}-${month}-${day}`;
+}
+
+/** 접두 날짜 키와 원본 파일명으로 실제 로그 파일명을 구성합니다. */
+function buildLogFilename(periodKey: string, filename: string): string {
+    return `${periodKey}.${normalizeFilename(filename)}`;
+}
+
+/** 로그 파일명에서 회전 주기에 해당하는 날짜 키를 추출합니다. */
+function extractPeriodKey(
+    name: string,
+    frequency: RotationFrequency,
+): string | null {
+    const match =
+        frequency === "hourly"
+            ? name.match(/^(\d{4}-\d{2}-\d{2}-\d{2})\./)
+            : name.match(/^(\d{4}-\d{2}-\d{2})\./);
+    return match?.[1] ?? null;
+}
+
+/** 날짜 접두 기반 로그 로테이션과 보관 개수 정리를 담당하는 Writable 스트림입니다. */
+export class DatePrefixedLogStream extends Writable {
+    private readonly logDir: string;
+    private readonly filename: string;
+    private readonly frequency: RotationFrequency;
+    private readonly maxFiles: number;
+    private currentKey = "";
+    private currentStream: WriteStream | null = null;
+
+    constructor(options: DatePrefixedLogStreamOptions) {
+        super();
+        this.logDir = path.resolve(options.logDir);
+        this.filename = normalizeFilename(options.filename);
+        this.frequency = options.frequency;
+        this.maxFiles = Math.max(1, options.maxFiles);
+        mkdirSync(this.logDir, { recursive: true });
+    }
+
+    /** 현재 회전 파일 스트림에 로그 청크를 기록합니다. */
+    override _write(
+        chunk: Buffer | string,
+        encoding: BufferEncoding,
+        callback: (error?: Error | null) => void,
+    ): void {
+        try {
+            this.ensureStream();
+            if (!this.currentStream) {
+                callback();
+                return;
+            }
+
+            this.currentStream.write(chunk, encoding, callback);
+        } catch (error) {
+            callback(error as Error);
+        }
+    }
+
+    /** 스트림 종료 시 현재 열려 있는 로그 파일을 안전하게 닫습니다. */
+    override _final(callback: (error?: Error | null) => void): void {
+        if (!this.currentStream) {
+            callback();
+            return;
+        }
+
+        const stream = this.currentStream;
+        this.currentStream = null;
+        this.currentKey = "";
+        stream.end(() => callback());
+    }
+
+    /** 스트림 파기 시 현재 로그 파일 핸들을 정리합니다. */
+    override _destroy(
+        error: Error | null,
+        callback: (error?: Error | null) => void,
+    ): void {
+        if (!this.currentStream) {
+            callback(error);
+            return;
+        }
+
+        const stream = this.currentStream;
+        this.currentStream = null;
+        this.currentKey = "";
+        stream.end(() => callback(error));
+    }
+
+    /** 현재 시점에 맞는 로그 파일이 열려 있는지 확인하고 필요하면 교체합니다. */
+    private ensureStream(): void {
+        const nextKey = makePeriodKey(new Date(), this.frequency);
+        if (this.currentStream && this.currentKey === nextKey) {
+            return;
+        }
+
+        if (this.currentStream) {
+            this.currentStream.end();
+        }
+
+        const filePath = path.join(
+            this.logDir,
+            buildLogFilename(nextKey, this.filename),
+        );
+
+        this.currentStream = createWriteStream(filePath, { flags: "a" });
+        this.currentKey = nextKey;
+        this.pruneOldFiles();
+    }
+
+    /** 보관 개수를 초과한 오래된 로그 파일을 삭제합니다. */
+    private pruneOldFiles(): void {
+        const matched = readdirSync(this.logDir)
+            .filter((name) => name.endsWith(`.${this.filename}`))
+            .map((name) => ({
+                name,
+                key: extractPeriodKey(name, this.frequency),
+            }))
+            .filter(
+                (entry): entry is { name: string; key: string } =>
+                    entry.key !== null,
+            )
+            .sort((left, right) => right.key.localeCompare(left.key));
+
+        const stale = matched.slice(this.maxFiles);
+        for (const entry of stale) {
+            try {
+                const filePath = path.join(this.logDir, entry.name);
+                rmSync(filePath, { force: true });
+            } catch {
+                // ignore prune failures
+            }
+        }
+    }
+}
+
+/** 날짜 접두 기반 로그 스트림 인스턴스를 생성합니다. */
+export function createDatePrefixedLogStream(
+    options: DatePrefixedLogStreamOptions,
+): DatePrefixedLogStream {
+    return new DatePrefixedLogStream(options);
+}

package/src/system/utils/errors.ts

@@ -0,0 +1,66 @@
+/**
+ * 커스텀 에러 클래스
+ */
+
+/** 애플리케이션 공통 베이스 에러입니다. */
+export class AppError extends Error {
+    constructor(
+        message: string,
+        public readonly statusCode: number = 500,
+        public readonly code?: string,
+    ) {
+        super(message);
+        this.name = "AppError";
+    }
+}
+
+/** 잘못된 요청 입력을 나타내는 400 에러입니다. */
+export class BadRequestError extends AppError {
+    constructor(message = "Bad Request") {
+        super(message, 400, "BAD_REQUEST");
+        this.name = "BadRequestError";
+    }
+}
+
+/** 인증 실패를 나타내는 401 에러입니다. */
+export class UnauthorizedError extends AppError {
+    constructor(message = "Unauthorized") {
+        super(message, 401, "UNAUTHORIZED");
+        this.name = "UnauthorizedError";
+    }
+}
+
+/** 권한 부족을 나타내는 403 에러입니다. */
+export class ForbiddenError extends AppError {
+    constructor(message = "Forbidden") {
+        super(message, 403, "FORBIDDEN");
+        this.name = "ForbiddenError";
+    }
+}
+
+/** 리소스를 찾지 못했음을 나타내는 404 에러입니다. */
+export class NotFoundError extends AppError {
+    constructor(message = "Not Found") {
+        super(message, 404, "NOT_FOUND");
+        this.name = "NotFoundError";
+    }
+}
+
+/** 리소스 충돌을 나타내는 409 에러입니다. */
+export class ConflictError extends AppError {
+    constructor(message = "Conflict") {
+        super(message, 409, "CONFLICT");
+        this.name = "ConflictError";
+    }
+}
+
+/** 유효성 검증 실패 상세를 담는 422 에러입니다. */
+export class ValidationError extends AppError {
+    constructor(
+        message = "Validation Error",
+        public readonly details?: unknown,
+    ) {
+        super(message, 422, "VALIDATION_ERROR");
+        this.name = "ValidationError";
+    }
+}

package/src/system/utils/format.ts

@@ -0,0 +1,45 @@
+/**
+ * 문자열 포맷팅 유틸리티
+ *
+ * 전화번호, 사업자번호, 날짜 등 반복되는 포맷 변환을
+ * 플러그인(SMS, OCR, Identity, TaxInvoice)에서 공유한다.
+ */
+
+/** 문자열에서 숫자만 추출한다 */
+export function extractDigits(s: string): string {
+    return s.replace(/[^0-9]/g, "");
+}
+
+/** Date 값을 SQL datetime 문자열(YYYY-MM-DD HH:mm:ss)로 변환한다. */
+export function formatSqlDateTime(date: Date = new Date()): string {
+    return date.toISOString().replace("T", " ").replace("Z", "").slice(0, 19);
+}
+
+/**
+ * 한국 전화번호를 E.164 형식으로 변환한다.
+ *
+ * - "01012345678"  → "+821012345678" (0 제거 + 82 추가)
+ * - "+821012345678" → 그대로
+ *
+ * @param phone    전화번호 문자열
+ * @param country  국가 코드 (기본 "82")
+ */
+export function normalizePhoneE164(phone: string, country = "82"): string {
+    if (phone.startsWith("+")) return phone;
+    const cleaned = extractDigits(phone);
+    if (cleaned.startsWith("0")) {
+        return `+${country}${cleaned.slice(1)}`;
+    }
+    return `+${cleaned}`;
+}
+
+/**
+ * 사업자번호를 NNN-NN-NNNNN 형식으로 정규화한다.
+ *
+ * "1234567890" → "123-45-67890"
+ */
+export function formatBizNum(raw: string): string {
+    const digits = extractDigits(raw);
+    if (digits.length !== 10) return raw;
+    return `${digits.slice(0, 3)}-${digits.slice(3, 5)}-${digits.slice(5)}`;
+}

package/src/system/utils/http-client.ts

@@ -0,0 +1,79 @@
+/**
+ * HTTP 클라이언트 헬퍼 — fetch + 타임아웃 + 에러 처리
+ *
+ * 모든 외부 API provider (SMS, PG, TaxInvoice, Identity, Holidays 등)에서
+ * 반복되는 fetch + AbortController + setTimeout 패턴을 통합한다.
+ */
+
+export interface FetchOptions extends Omit<RequestInit, "signal"> {
+    /** 요청 타임아웃 (ms). 기본: 30000 */
+    timeoutMs?: number;
+}
+
+export interface FetchResult<T = unknown> {
+    ok: boolean;
+    status: number;
+    data: T;
+    headers: Headers;
+}
+
+/**
+ * 타임아웃 지원 fetch 래퍼.
+ * 지정된 시간 내 응답이 없으면 AbortError 를 throw 한다.
+ *
+ * @param url     요청 URL
+ * @param options fetch 옵션 + timeoutMs
+ * @returns       FetchResult (JSON 파싱 시도, 실패 시 text)
+ */
+export async function fetchWithTimeout<T = unknown>(
+    url: string,
+    options: FetchOptions = {},
+): Promise<FetchResult<T>> {
+    const { timeoutMs = 30_000, ...fetchOpts } = options;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+        const response = await fetch(url, {
+            ...fetchOpts,
+            signal: controller.signal,
+        });
+
+        let data: T;
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+            data = (await response.json()) as T;
+        } else {
+            data = (await response.text()) as unknown as T;
+        }
+
+        return {
+            ok: response.ok,
+            status: response.status,
+            data,
+            headers: response.headers,
+        };
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+/**
+ * JSON POST 요청을 공통 헤더와 함께 전송합니다.
+ */
+export function fetchJson<T = unknown>(
+    url: string,
+    body: unknown,
+    options: FetchOptions = {},
+): Promise<FetchResult<T>> {
+    return fetchWithTimeout<T>(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            ...((options.headers as Record<string, string>) ?? {}),
+        },
+        body: JSON.stringify(body),
+        ...options,
+    });
+}

package/src/system/utils/user-agent.ts

@@ -0,0 +1,82 @@
+export type ParsedUserAgent = {
+    raw: string;
+    platform?: string;
+    deviceType?: string;
+    browser?: string;
+    browserVersion?: string;
+};
+
+/** User-Agent 문자열에서 플랫폼 값을 추론합니다. */
+export function detectPlatform(userAgent: string): string | undefined {
+    const ua = userAgent.toLowerCase();
+    if (!ua) return undefined;
+    if (ua.includes("android")) return "android";
+    if (ua.includes("iphone") || ua.includes("ipad") || ua.includes("ios")) {
+        return "ios";
+    }
+    if (ua.includes("windows")) return "windows";
+    if (ua.includes("mac os") || ua.includes("macintosh")) return "macos";
+    if (ua.includes("linux")) return "linux";
+    return "web";
+}
+
+/** User-Agent 문자열에서 기기 유형을 추론합니다. */
+export function detectDeviceType(userAgent: string): string | undefined {
+    const ua = userAgent.toLowerCase();
+    if (!ua) return undefined;
+    if (ua.includes("ipad") || ua.includes("tablet")) return "tablet";
+    if (
+        ua.includes("mobile") ||
+        ua.includes("iphone") ||
+        ua.includes("android")
+    ) {
+        return "mobile";
+    }
+    return "desktop";
+}
+
+/** User-Agent 문자열에서 브라우저 이름을 추론합니다. */
+export function detectBrowser(userAgent: string): string | undefined {
+    const ua = userAgent.toLowerCase();
+    if (!ua) return undefined;
+    if (ua.includes("edg/")) return "edge";
+    if (ua.includes("chrome/")) return "chrome";
+    if (ua.includes("safari/") && !ua.includes("chrome/")) return "safari";
+    if (ua.includes("firefox/")) return "firefox";
+    if (ua.includes("whale/")) return "whale";
+    return undefined;
+}
+
+/** User-Agent 문자열에서 브라우저 버전을 추출합니다. */
+export function detectBrowserVersion(userAgent: string): string | undefined {
+    const patterns = [
+        /Edg\/([\d.]+)/,
+        /Chrome\/([\d.]+)/,
+        /Version\/([\d.]+)/,
+        /Firefox\/([\d.]+)/,
+        /Whale\/([\d.]+)/,
+    ];
+    for (const pattern of patterns) {
+        const match = userAgent.match(pattern);
+        if (match?.[1]) return match[1];
+    }
+    return undefined;
+}
+
+/** User-Agent 문자열을 공통 필드 구조로 정규화합니다. */
+export function parseUserAgent(
+    userAgent: string | null | undefined,
+): ParsedUserAgent {
+    const raw = String(userAgent ?? "").trim();
+    if (!raw) {
+        return { raw: "" };
+    }
+
+    return {
+        raw,
+        platform: detectPlatform(raw),
+        deviceType: detectDeviceType(raw),
+        browser: detectBrowser(raw),
+        browserVersion: detectBrowserVersion(raw),
+    };
+}

package/tsconfig.app.json

@@ -0,0 +1,17 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "./dist",
+        "declaration": false,
+        "declarationMap": false,
+        "sourceMap": true
+    },
+    "include": [
+        "src/app/**/*.ts",
+        "src/system/types/**/*.ts"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}

package/tsconfig.json

@@ -0,0 +1,39 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "allowImportingTsExtensions": true,
+        "noEmit": true,
+        "lib": [
+            "ES2022"
+        ],
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "paths": {
+            "@system/*": [
+                "./src/system/*"
+            ],
+            "@app/*": [
+                "./src/app/*"
+            ],
+            "@gateway/api": [
+                "./src/system/public-api.ts"
+            ]
+        }
+    },
+    "include": [
+        "src/**/*.ts"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "tests"
+    ]
+}