create-entity-app-server 0.0.3

package/src/app/plugins/ocr/templates/receipt.json

@@ -0,0 +1,79 @@
+{
+    "doc_type": "receipt",
+    "label": "영수증",
+
+    "preprocess": {
+        "max_slope": 0.05,
+        "y_tolerance": 5,
+        "x_tolerance": 10,
+        "remove_patterns": ["^\\s*$"],
+        "merge_patterns": ["\\d{1,3}(,\\d{3})+원?"]
+    },
+
+    "keywords": {
+        "store_name": ["상호", "가맹점", "점포명"],
+        "corp_num": ["사업자번호", "사업자등록번호"],
+        "date": ["거래일시", "승인일시", "일시", "날짜"],
+        "total_amount": ["합계", "결제금액", "승인금액", "총금액", "금액"],
+        "payment_type": ["결제수단", "결제방법"],
+        "card_number": ["카드번호", "카드"]
+    },
+
+    "fields": {
+        "store_name": {
+            "output_key": "store_name",
+            "criteria": [
+                { "keyword": "상호", "direction": "RIGHT" },
+                { "keyword": "가맹점", "direction": "RIGHT" },
+                { "keyword": "점포명", "direction": "RIGHT" }
+            ]
+        },
+        "corp_num": {
+            "output_key": "corp_num",
+            "criteria": [
+                { "keyword": "사업자번호", "direction": "RIGHT" },
+                { "keyword": "사업자등록번호", "direction": "RIGHT" }
+            ],
+            "refine": "biz_num"
+        },
+        "date": {
+            "output_key": "date",
+            "mode": "regex_scan",
+            "pattern": "(\\d{4}[./-]\\d{2}[./-]\\d{2}(?:[\\s]\\d{2}:\\d{2}(?::\\d{2})?)?)",
+            "capture_group": 1,
+            "refine": "date"
+        },
+        "total_amount": {
+            "output_key": "total_amount",
+            "criteria": [
+                { "keyword": "합계", "direction": "RIGHT" },
+                { "keyword": "합계", "direction": "DOWN" },
+                { "keyword": "결제금액", "direction": "RIGHT" },
+                { "keyword": "승인금액", "direction": "RIGHT" }
+            ],
+            "refine": "number"
+        },
+        "payment_type": {
+            "output_key": "payment_type",
+            "criteria": [
+                { "keyword": "결제수단", "direction": "RIGHT" },
+                { "keyword": "결제방법", "direction": "RIGHT" }
+            ]
+        },
+        "card_number": {
+            "output_key": "card_number",
+            "mode": "regex_scan",
+            "pattern": "([0-9*]{4}[-\\s]?[0-9*]{4}[-\\s]?[0-9*]{4}[-\\s]?[0-9*]{4})",
+            "capture_group": 1
+        }
+    },
+
+    "required_fields": ["total_amount"],
+
+    "confidence_weight": {
+        "store_name": 0.2,
+        "corp_num": 0.15,
+        "date": 0.25,
+        "total_amount": 0.4
+    }
+}

package/src/app/plugins/ocr/types/config.ts

@@ -0,0 +1,60 @@
+/** OCR 서비스 전체 설정 */
+export interface OcrConfig {
+    enabled: boolean;
+    default: string;
+    workers: number;
+    queueSize: number;
+    maxFileSizeMB: number;
+    supportedFormats: string[];
+    cache: OcrCacheConfig;
+    quota: OcrQuotaConfig;
+    parsing: OcrParsingConfig;
+    llmFallback: OcrLlmFallbackConfig;
+    providers: OcrProviderConfig[];
+}
+
+export interface OcrCacheConfig {
+    enabled: boolean;
+    ttlHours: number;
+}
+
+export interface OcrQuotaConfig {
+    dailyLimit: number;
+    monthlyLimit: number;
+    notify: string[];
+}
+
+export interface OcrParsingConfig {
+    templateDir: string;
+    confidenceThreshold: number;
+}
+
+export interface OcrLlmFallbackConfig {
+    enabled: boolean;
+    provider: string;
+    confidenceThreshold: number;
+    promptDir: string;
+}
+
+/** 개별 OCR 프로바이더 연결 설정 */
+export interface OcrProviderConfig {
+    driver: string; // google, naver, aws_textract, azure, upstage, tesseract
+    credentialsPath?: string;
+    projectId?: string;
+    secretKey?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    region?: string;
+    endpoint?: string;
+    apiVersion?: string;
+    dataPath?: string;
+    defaultLang?: string;
+    psm?: number;
+    oem?: number;
+    apiKey?: string;
+    apiUrl?: string;
+    apiEndpoint?: string;
+    timeoutSec?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+}

package/src/app/plugins/ocr/types/driver.ts

@@ -0,0 +1,71 @@
+import type { ParsedDocument } from "./parsed.ts";
+
+export interface OcrDriver {
+    recognize(data: Buffer, opts: RecognizeOptions): Promise<RawOcrResult>;
+    name(): string;
+    supportedFormats(): string[];
+    close(): Promise<void>;
+}
+
+export interface RecognizeOptions {
+    mimeType: string;
+    docType?: string;
+    languages?: string[];
+    pageRange?: PageRange;
+    includeBoxes?: boolean;
+    confidenceThreshold?: number;
+}
+
+export interface PageRange {
+    start: number;
+    end: number;
+}
+
+export interface RawOcrResult {
+    fullText: string;
+    pages: RawOcrPage[];
+    confidence: number;
+    providerRaw?: unknown;
+    processingMs: number;
+    processedAt: string;
+    provider: string;
+}
+
+export interface RawOcrPage {
+    pageNum: number;
+    width: number;
+    height: number;
+    text: string;
+    blocks: TextBlock[];
+}
+
+export interface TextBlock {
+    text: string;
+    boundingBox: BoundingBox;
+    centerX: number;
+    centerY: number;
+    slope: number;
+    confidence: number;
+    lineBreak: boolean;
+}
+
+export interface BoundingBox {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+}
+
+export interface OcrResult {
+    raw?: RawOcrResult;
+    parsed?: ParsedDocument;
+    parseMethod: string;
+    parseConfidence: number;
+}
+
+export interface DispatchJob {
+    id: string;
+    data: Buffer;
+    opts: RecognizeOptions;
+    createdAt: string;
+}

package/src/app/plugins/ocr/types/index.ts

@@ -0,0 +1,5 @@
+export * from "./config.ts";
+export * from "./parsed.ts";
+export * from "./driver.ts";
+export * from "./template.ts";
+export * from "./store.ts";

package/src/app/plugins/ocr/types/parsed.ts

@@ -0,0 +1,101 @@
+export interface ParsedDocument {
+    docType: string;
+    receipt?: ParsedReceipt;
+    namecard?: ParsedNamecard;
+    invoice?: ParsedInvoice;
+    businessReg?: ParsedBusinessReg;
+    idCard?: ParsedIdCard;
+    driverLicense?: ParsedDriverLicense;
+    facilityCard?: ParsedFacilityCard;
+    careerCert?: ParsedCareerCert;
+}
+
+export interface ParsedReceipt {
+    storeName?: string;
+    storeAddr?: string;
+    corpNum?: string;
+    date?: string;
+    totalAmount?: string;
+    items?: ReceiptItem[];
+    paymentType?: string;
+    cardNumber?: string;
+}
+
+export interface ReceiptItem {
+    name: string;
+    quantity?: string;
+    price?: string;
+}
+
+export interface ParsedNamecard {
+    name?: string;
+    company?: string;
+    department?: string;
+    title?: string;
+    phone?: string[];
+    email?: string[];
+    address?: string;
+    website?: string;
+}
+
+export interface ParsedInvoice {
+    invoiceNum?: string;
+    issuerCorpNum?: string;
+    issuerName?: string;
+    receiverCorpNum?: string;
+    receiverName?: string;
+    writeDate?: string;
+    amountTotal?: string;
+    taxTotal?: string;
+    totalAmount?: string;
+}
+
+export interface ParsedBusinessReg {
+    corpNum?: string;
+    corpName?: string;
+    ceoName?: string;
+    address?: string;
+    bizType?: string;
+    bizClass?: string;
+    openDate?: string;
+}
+
+export interface ParsedIdCard {
+    name?: string;
+    idNumber?: string;
+    issueDate?: string;
+    issuer?: string;
+}
+
+export interface ParsedDriverLicense {
+    name?: string;
+    idNumber?: string;
+    licenseNum?: string;
+    licenseType?: string;
+    issueDate?: string;
+    expiryDate?: string;
+    issuer?: string;
+}
+
+export interface ParsedFacilityCard {
+    buildingName?: string;
+    address?: string;
+    buildingUse?: string;
+    structure?: string;
+    area?: string;
+    floorCount?: string;
+    approvalDate?: string;
+    owner?: string;
+}
+
+export interface ParsedCareerCert {
+    name?: string;
+    idNumber?: string;
+    company?: string;
+    department?: string;
+    position?: string;
+    joinDate?: string;
+    leaveDate?: string;
+    issueDate?: string;
+    issuer?: string;
+}

package/src/app/plugins/ocr/types/store.ts

@@ -0,0 +1,70 @@
+import type { OcrResult } from "./driver.ts";
+
+export interface OcrResultRecord {
+    ocrId: string;
+    fileSeq?: number;
+    fileHash: string;
+    provider: string;
+    docType: string;
+    state: string; // pending/processing/completed/failed
+    refTable?: string;
+    refSeq?: number;
+    text?: string;
+    pages?: unknown;
+    parsed?: unknown;
+    confidence?: number;
+    processingMs?: number;
+    providerRaw?: unknown;
+    errorMessage?: string;
+    parseMethod?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+
+export interface OcrUsageRecord {
+    usageDate: string;
+    provider: string;
+    docType: string;
+    requestCount: number;
+    pageCount: number;
+    successCount?: number;
+    failCount?: number;
+    totalMs?: number;
+    avgConfidence?: number;
+}
+
+export interface OcrResultFilter {
+    provider?: string;
+    docType?: string;
+    state?: string;
+    fileSeq?: number;
+    refTable?: string;
+    refSeq?: number;
+    offset?: number;
+    limit?: number;
+}
+
+export interface OcrEntityStore {
+    createResult(record: OcrResultRecord): Promise<string>;
+    updateResultState(
+        id: string,
+        state: string,
+        result: OcrResult | null,
+        errMsg: string,
+    ): Promise<void>;
+    getResult(id: string): Promise<OcrResultRecord | null>;
+    listResults(
+        filter: OcrResultFilter,
+    ): Promise<{ items: OcrResultRecord[]; total: number }>;
+    deleteResult(id: string): Promise<void>;
+    incrementUsage(record: OcrUsageRecord): Promise<void>;
+    getDailyQuotaUsage(date: string): Promise<number>;
+    getMonthlyQuotaUsage(month: string): Promise<number>;
+}
+
+export interface QuotaStatus {
+    dailyUsed: number;
+    dailyLimit: number;
+    monthlyUsed: number;
+    monthlyLimit: number;
+}

package/src/app/plugins/ocr/types/template.ts

@@ -0,0 +1,89 @@
+import type { ParsedDocument } from "./parsed.ts";
+
+export interface Template {
+    docType: string;
+    label: string;
+    preprocess: PreprocessConfig;
+    keywords: Record<string, string[]>;
+    fields: Record<string, FieldConfig>;
+    requiredFields: string[];
+    confidenceWeight: Record<string, number>;
+}
+
+export interface FieldConfig {
+    outputKey: string;
+    mode?: string; // anchor(기본), region, regex_scan
+    criteria?: Criterion[];
+    region?: RegionConfig;
+    pattern?: string;
+    captureGroup?: number;
+    refine?: string;
+    required?: boolean;
+}
+
+export interface Criterion {
+    keyword: string;
+    direction: string;
+}
+
+export interface RegionConfig {
+    from: string;
+    to: string;
+    direction?: string;
+    xMinAnchor?: string;
+}
+
+export interface PreprocessConfig {
+    maxSlope: number;
+    slopeExceptions: string[];
+    yTolerance: number;
+    xTolerance: number;
+    removeKeywords: string[];
+    removePatterns: string[];
+    mergePatterns: string[];
+    keywords: Record<string, string[]>;
+}
+
+export interface ProcessedItem {
+    text: string;
+    isKeyword: boolean;
+    field: string;
+    centerX: number;
+    centerY: number;
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    width: number;
+    height: number;
+    slope: number;
+}
+
+export interface ProcessedPage {
+    keywordList: Record<string, ProcessedItem[]>;
+    valueList: ProcessedItem[];
+}
+
+export interface BaseItem {
+    item: ProcessedItem;
+    direction: string;
+}
+
+export interface MatchResult {
+    parsed?: ParsedDocument;
+    confidence: number;
+    missingRequired: string[];
+    extracted: Record<string, string>;
+}
+
+export interface LlmPromptTemplate {
+    docType: string;
+    systemMsg: string;
+    userMsg: string;
+    schema: unknown;
+}
+
+export interface RetryConfig {
+    maxRetries: number;
+    retryDelayMs: number;
+}

package/src/app/plugins/ocr/utils.ts

@@ -0,0 +1,18 @@
+/**
+ * OCR 모듈 유틸리티
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/** CLI 도구 존재 여부 확인 */
+export async function which(cmd: string): Promise<boolean> {
+    try {
+        await execFileAsync("which", [cmd]);
+        return true;
+    } catch {
+        return false;
+    }
+}

package/src/app/plugins/pg/config.example.json

@@ -0,0 +1,79 @@
+{
+    "enabled": false,
+    "default": "toss_payments",
+    "webhook_secret": "",
+    "order_id_prefix": "ORD",
+    "success_url": "/payment/success",
+    "fail_url": "/payment/fail",
+    "webhook_url": "/api/v1/pg/webhook",
+    "amount_limit": {
+        "min": 100,
+        "max": 10000000
+    },
+    "workers": 2,
+    "providers": {
+        "toss_payments": {
+            "driver": "toss_payments",
+            "_comment": "토스페이먼츠 V2",
+            "client_key": "${TOSS_CLIENT_KEY}",
+            "secret_key": "${TOSS_SECRET_KEY}",
+            "api_url": "https://api.tosspayments.com",
+            "api_version": "2024-06-01"
+        },
+        "kakaopay": {
+            "driver": "kakaopay",
+            "_comment": "카카오페이",
+            "cid": "${KAKAO_PAY_CID}",
+            "admin_key": "${KAKAO_PAY_ADMIN_KEY}",
+            "api_url": "https://kapi.kakao.com"
+        },
+        "nice_payments": {
+            "driver": "nice_payments",
+            "_comment": "나이스페이먼츠 V2",
+            "client_key": "${NICE_CLIENT_KEY}",
+            "secret_key": "${NICE_SECRET_KEY}",
+            "api_url": "https://api.nicepay.co.kr",
+            "api_version": "v1"
+        },
+        "inicis": {
+            "driver": "inicis",
+            "_comment": "KG이니시스",
+            "mid": "${INICIS_MID}",
+            "sign_key": "${INICIS_SIGN_KEY}",
+            "iv": "${INICIS_IV}",
+            "api_url": "https://iniapi.inicis.com"
+        },
+        "naverpay": {
+            "driver": "naverpay",
+            "_comment": "네이버페이 주문형",
+            "partner_id": "${NAVER_PAY_PARTNER_ID}",
+            "client_id": "${NAVER_PAY_CLIENT_ID}",
+            "client_secret": "${NAVER_PAY_CLIENT_SECRET}",
+            "chain_id": "${NAVER_PAY_CHAIN_ID}",
+            "api_url": "https://pay.naver.com"
+        },
+        "payco": {
+            "driver": "payco",
+            "_comment": "PAYCO",
+            "partner_id": "${PAYCO_PARTNER_ID}",
+            "partner_secret": "${PAYCO_PARTNER_SECRET}",
+            "api_url": "https://apis.payco.com"
+        },
+        "payletter": {
+            "driver": "payletter",
+            "_comment": "페이레터 (Payletter) — Authorization: PLKEY {api_key}",
+            "client_id": "${PAYLETTER_CLIENT_ID}",
+            "api_key": "${PAYLETTER_API_KEY}",
+            "api_key_search": "${PAYLETTER_API_KEY_SEARCH}",
+            "api_url": "https://pgapi.payletter.com"
+        },
+        "paypal": {
+            "driver": "paypal",
+            "_comment": "PayPal REST API v2 — Sandbox: api-m.sandbox.paypal.com / Live: api-m.paypal.com",
+            "client_id": "${PAYPAL_CLIENT_ID}",
+            "secret_key": "${PAYPAL_CLIENT_SECRET}",
+            "api_url": "https://api-m.sandbox.paypal.com",
+            "webhook_secret": "${PAYPAL_WEBHOOK_ID}"
+        }
+    }
+}

package/src/app/plugins/pg/config.json

@@ -0,0 +1,35 @@
+{
+    "_comment": "결제(PG) 플러그인 — 토스페이먼츠·페이레터 등 결제 프로바이더 연동, 웹훅 처리 및 주문 관리 지원",
+    "enabled": false,
+    "default": "toss_payments",
+    "webhook_secret": "",
+    "order_id_prefix": "ORD",
+    "success_url": "/payment/success",
+    "fail_url": "/payment/fail",
+    "webhook_url": "/api/v1/pg/webhook",
+    "amount_limit": {
+        "min": 100,
+        "max": 10000000
+    },
+    "workers": 2,
+    "providers": {
+        "toss_payments": {
+            "driver": "toss_payments",
+            "_comment": "토스페이먼츠 V2",
+            "client_key": "${TOSS_CLIENT_KEY}",
+            "secret_key": "${TOSS_SECRET_KEY}",
+            "api_url": "https://api.tosspayments.com",
+            "api_version": "2024-06-01"
+        },
+        "payletter": {
+            "driver": "payletter",
+            "_comment": "페이레터 (Payletter) — Authorization: PLKEY {api_key}",
+            "client_id": "${PAYLETTER_CLIENT_ID}",
+            "api_key": "${PAYLETTER_API_KEY}",
+            "api_key_search": "${PAYLETTER_API_KEY_SEARCH}",
+            "api_url": "https://pgapi.payletter.com"
+        }
+    },
+    "deploy": true,
+    "minify": false
+}

package/src/app/plugins/pg/config.ts

@@ -0,0 +1,58 @@
+/**
+ * PG 결제 설정 로더
+ *
+ * 플러그인 디렉토리의 config.json을 읽고 환경변수 치환을 수행합니다.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import type { PgConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+/** PG 결제 설정을 로드한다 */
+export function loadPgConfig(): PgConfig | null {
+    try {
+        let raw = readFileSync(CONFIG_PATH, "utf-8");
+
+        // 환경변수 치환: ${VAR} → process.env.VAR
+        raw = raw.replace(
+            /\$\{([^}]+)\}/g,
+            (_match, name) => process.env[name] ?? "",
+        );
+
+        const cfg: PgConfig = JSON.parse(raw);
+
+        if (cfg.enabled === false) {
+            logger.info("PG plugin disabled in config");
+            return null;
+        }
+
+        if (!cfg.providers || Object.keys(cfg.providers).length === 0) {
+            logger.warn("PG: no providers configured, plugin disabled");
+            return null;
+        }
+
+        // 기본값 보정
+        if (!cfg.workers || cfg.workers <= 0) cfg.workers = 2;
+        if (!cfg.order_id_prefix) cfg.order_id_prefix = "ORD";
+        if (cfg.amount_limit) {
+            if (!cfg.amount_limit.min || cfg.amount_limit.min <= 0)
+                cfg.amount_limit.min = 100;
+            if (!cfg.amount_limit.max || cfg.amount_limit.max <= 0)
+                cfg.amount_limit.max = 10_000_000;
+        }
+
+        return cfg;
+    } catch (err: unknown) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            logger.info("PG config not found, plugin skipped");
+        } else {
+            logger.error({ err }, "Failed to load pg config");
+        }
+        return null;
+    }
+}