create-entity-app-server 0.0.3

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

@@ -0,0 +1,112 @@
+/**
+ * Refiner — 추출된 텍스트 값을 비즈니스 형식으로 정제
+ * PHP NaverClovaRefine 포팅
+ */
+
+export class Refiner {
+    /** 값을 지정된 정제 타입에 따라 포맷팅한다 */
+    refine(value: string, refineType: string): string {
+        switch (refineType) {
+            case "date":
+                return this.refineDate(value);
+            case "biz_num":
+                return this.refineBizNum(value);
+            case "id_num":
+                return this.refineIdNum(value);
+            case "phone":
+                return this.refinePhone(value);
+            case "driver_license":
+                return this.refineDriverLicense(value);
+            case "trim":
+                return value.trim();
+            default:
+                return value;
+        }
+    }
+
+    /** 다양한 날짜 형식을 YYYY-MM-DD로 정제 */
+    private refineDate(value: string): string {
+        value = value.trim();
+        if (!value) return "";
+
+        const digits = value.match(/\d+/g);
+        if (!digits || digits.length < 3) return value;
+
+        let year = digits[0];
+        let month = digits[1];
+        let day = digits[2];
+
+        if (year.length === 2) year = "20" + year;
+        if (month.length === 1) month = "0" + month;
+        if (day.length === 1) day = "0" + day;
+
+        return `${year}-${month}-${day}`;
+    }
+
+    /** 사업자등록번호를 000-00-00000 형식으로 정제 */
+    private refineBizNum(value: string): string {
+        value = value.trim();
+        let digits = extractDigits(value);
+        if (digits.length > 10) digits = digits.slice(0, 10);
+        if (digits.length !== 10) return value.trim();
+        return `${digits.slice(0, 3)}-${digits.slice(3, 5)}-${digits.slice(5)}`;
+    }
+
+    /** 주민등록번호 뒤 7자리 마스킹 */
+    private refineIdNum(value: string): string {
+        value = value.trim();
+        if (value.includes("*")) return value;
+
+        const match = value.match(/(\d{6})-?(\d{7})/);
+        if (match) return `${match[1]}-*******`;
+
+        const digits = extractDigits(value);
+        if (digits.length === 13) return `${digits.slice(0, 6)}-*******`;
+
+        return value;
+    }
+
+    /** 전화번호를 표준 형식으로 정제 */
+    private refinePhone(value: string): string {
+        value = value.trim();
+        const digits = extractDigits(value);
+        if (!digits) return value;
+
+        if (digits.length === 10 && digits.startsWith("02")) {
+            return `${digits.slice(0, 2)}-${digits.slice(2, 6)}-${digits.slice(6)}`;
+        }
+        if (digits.length === 9 && digits.startsWith("02")) {
+            return `${digits.slice(0, 2)}-${digits.slice(2, 5)}-${digits.slice(5)}`;
+        }
+        if (digits.length === 11 && digits.startsWith("010")) {
+            return `${digits.slice(0, 3)}-${digits.slice(3, 7)}-${digits.slice(7)}`;
+        }
+        if (digits.length === 11) {
+            return `${digits.slice(0, 3)}-${digits.slice(3, 7)}-${digits.slice(7)}`;
+        }
+        if (digits.length === 10) {
+            return `${digits.slice(0, 3)}-${digits.slice(3, 6)}-${digits.slice(6)}`;
+        }
+        return value;
+    }
+
+    /** 운전면허번호 정제 */
+    private refineDriverLicense(value: string): string {
+        value = value.trim();
+        if (!value) return "";
+
+        // 이미 올바른 형식 (한글 지역코드 포함)
+        if (/[가-힣]{1,3}\s*\d{2}-\d{2}-\d{6}-\d{2}/.test(value)) return value;
+
+        const digits = extractDigits(value);
+        if (digits.length === 12) {
+            return `${digits.slice(0, 2)}-${digits.slice(2, 4)}-${digits.slice(4, 10)}-${digits.slice(10)}`;
+        }
+        return value;
+    }
+}
+
+/** 문자열에서 숫자만 추출 */
+function extractDigits(s: string): string {
+    return s.replace(/\D/g, "");
+}

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

@@ -0,0 +1,19 @@
+/**
+ * OCR 라우트 테이블
+ * 등록 경로: /api/v1/ocr/*
+ */
+
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+/** OCR 라우트 테이블을 등록한다 */
+export default async function ocrRoutes(app: FastifyInstance) {
+    app.post("/recognize", h.recognize);
+    app.post("/recognize/async", h.recognizeAsync);
+    app.post("/:docType", h.recognizeByDocType);
+    app.get("/results", h.listResults);
+    app.get("/results/:id", h.getResult);
+    app.get("/results/:id/text", h.getResultText);
+    app.delete("/results/:id", h.deleteResult);
+    app.get("/quota", h.getQuota);
+}

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

@@ -0,0 +1,333 @@
+/**
+ * OcrService — OCR 기능의 핵심 서비스
+ * 인식 → 캐시 → 쿼터 → 파싱 파이프라인 → 결과 저장 조율
+ */
+
+import type {
+    OcrConfig,
+    OcrDriver,
+    OcrResult,
+    OcrResultRecord,
+    OcrResultFilter,
+    RecognizeOptions,
+    RawOcrResult,
+    OcrEntityStore,
+    QuotaStatus,
+} from "./types/index.ts";
+import {
+    createOcrDriver,
+    retryRecognize,
+    validateFileSize,
+} from "./providers/index.ts";
+import { CacheManager, computeFileHash } from "./cache.ts";
+import { QuotaManager } from "./quota.ts";
+import { DispatchWorker } from "./dispatch.ts";
+import { TemplateLoader } from "./template-loader.ts";
+import { TemplateMatcher } from "./template-matcher.ts";
+import { LlmParser, type LlmServiceLike } from "./llm-parser.ts";
+import { ParsingPipeline } from "./parsing-pipeline.ts";
+import {
+    convertPDFToImages,
+    isPDF,
+    type Pdf2PngClient,
+} from "./pdf-converter.ts";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+import { OcrError, ERR_RESULT_NOT_FOUND } from "./errors.ts";
+
+export class OcrService {
+    private readonly config: OcrConfig;
+    private defaultDriver: OcrDriver | null = null;
+    private readonly drivers = new Map<string, OcrDriver>();
+    private readonly pipeline: ParsingPipeline;
+    private readonly cacheMan: CacheManager | null;
+    private readonly quotaMan: QuotaManager | null;
+    private readonly dispatcher: DispatchWorker;
+    private readonly entityStore: OcrEntityStore | null;
+    private readonly pdfClient: Pdf2PngClient | null;
+
+    /** OcrService를 설정과 클라이언트로 초기화한다 */
+    constructor(
+        cfg: OcrConfig,
+        entityStore: OcrEntityStore | null,
+        llmSvc: LlmServiceLike | null,
+        pdfClient?: Pdf2PngClient | null,
+    ) {
+        this.config = cfg;
+        this.entityStore = entityStore;
+        this.pdfClient = pdfClient ?? null;
+
+        // 드라이버 생성
+        for (const provCfg of cfg.providers) {
+            try {
+                const driver = createOcrDriver(provCfg);
+                this.drivers.set(driver.name(), driver);
+                if (provCfg.driver === cfg.default || !this.defaultDriver) {
+                    this.defaultDriver = driver;
+                }
+            } catch (err) {
+                console.log(
+                    `[WARN] OCR driver ${provCfg.driver} init failed: ${err}`,
+                );
+            }
+        }
+
+        // 파싱 파이프라인
+        const templateDir =
+            cfg.parsing.templateDir || join(__dirname, "templates");
+        const promptDir =
+            cfg.llmFallback.promptDir ||
+            join(__dirname, "templates", "prompts");
+        const loader = new TemplateLoader(templateDir);
+        const matcher = new TemplateMatcher(loader);
+        let llmParser: LlmParser | null = null;
+        if (llmSvc && cfg.llmFallback.enabled && cfg.llmFallback.provider) {
+            llmParser = new LlmParser(
+                llmSvc,
+                cfg.llmFallback.provider,
+                promptDir,
+                loader,
+            );
+        }
+        this.pipeline = new ParsingPipeline(matcher, llmParser, cfg.parsing);
+
+        // 캐시
+        this.cacheMan = cfg.cache.enabled ? new CacheManager(cfg.cache) : null;
+
+        // 쿼터
+        this.quotaMan = entityStore
+            ? new QuotaManager(cfg.quota, entityStore)
+            : null;
+
+        // 비동기 디스패처
+        this.dispatcher = new DispatchWorker(cfg.queueSize, cfg.workers);
+        this.dispatcher.init(
+            (data, opts) => this.recognizeInternal(data, opts),
+            entityStore,
+        );
+    }
+
+    /** OCR 디스패치 워커를 시작한다 */
+    start(): void {
+        this.dispatcher.start();
+    }
+
+    /** OCR 워커와 드라이버를 종료한다 */
+    stop(): void {
+        for (const d of this.drivers.values()) {
+            d.close().catch((e) =>
+                console.log(`[WARN] OCR driver close error: ${e}`),
+            );
+        }
+    }
+
+    /** 동기 OCR 인식 */
+    async recognize(data: Buffer, opts: RecognizeOptions): Promise<OcrResult> {
+        validateFileSize(data, this.config.maxFileSizeMB);
+
+        if (this.quotaMan) await this.quotaMan.check();
+
+        if (isPDF(data)) return this.recognizePDF(data, opts);
+        return this.recognizeInternal(data, opts);
+    }
+
+    /** 비동기 OCR 인식 (작업 ID 반환) */
+    async recognizeAsync(
+        data: Buffer,
+        opts: RecognizeOptions,
+    ): Promise<string> {
+        validateFileSize(data, this.config.maxFileSizeMB);
+        if (this.quotaMan) await this.quotaMan.check();
+
+        const jobId = this.dispatcher.submit(data, opts);
+
+        if (this.entityStore) {
+            const fileHash = computeFileHash(data);
+            try {
+                await this.entityStore.createResult({
+                    ocrId: jobId,
+                    fileHash,
+                    provider: this.resolveDriverName(opts),
+                    docType: opts.docType ?? "",
+                    state: "pending",
+                });
+            } catch (err) {
+                console.log(
+                    `[WARN] OCR async: create result record failed: ${err}`,
+                );
+            }
+        }
+        return jobId;
+    }
+
+    /** OCR 결과를 ID로 조회한다 */
+    async getResult(id: string): Promise<OcrResultRecord | null> {
+        if (!this.entityStore)
+            throw new OcrError("OCR result not found", ERR_RESULT_NOT_FOUND);
+        return this.entityStore.getResult(id);
+    }
+
+    /** OCR 결과 목록을 필터 조건으로 조회한다 */
+    async listResults(
+        filter: OcrResultFilter,
+    ): Promise<{ items: OcrResultRecord[]; total: number }> {
+        if (!this.entityStore) return { items: [], total: 0 };
+        return this.entityStore.listResults(filter);
+    }
+
+    /** OCR 결과를 삭제한다 */
+    async deleteResult(id: string): Promise<void> {
+        if (!this.entityStore)
+            throw new OcrError("OCR result not found", ERR_RESULT_NOT_FOUND);
+        await this.entityStore.deleteResult(id);
+    }
+
+    /** 현재 쿼터 상태를 조회한다 */
+    async getQuotaStatus(): Promise<QuotaStatus> {
+        if (!this.quotaMan) {
+            return {
+                dailyUsed: 0,
+                dailyLimit: this.config.quota.dailyLimit,
+                monthlyUsed: 0,
+                monthlyLimit: this.config.quota.monthlyLimit,
+            };
+        }
+        return this.quotaMan.getStatus();
+    }
+
+    // ─── 내부 메서드 ───
+
+    /** PDF 파일을 페이지별로 변환하여 OCR을 수행한다 */
+    private async recognizePDF(
+        data: Buffer,
+        opts: RecognizeOptions,
+    ): Promise<OcrResult> {
+        const pages = await convertPDFToImages(
+            data,
+            opts.pageRange,
+            undefined,
+            this.pdfClient ?? undefined,
+        );
+        const combined: RawOcrResult = {
+            provider: this.resolveDriverName(opts),
+            processedAt: new Date().toISOString(),
+            fullText: "",
+            pages: [],
+            confidence: 0,
+            processingMs: 0,
+        };
+
+        for (let i = 0; i < pages.length; i++) {
+            const pageOpts = {
+                ...opts,
+                mimeType: "image/png",
+                pageRange: undefined,
+            };
+            try {
+                const r = await this.recognizeInternal(pages[i], pageOpts);
+                if (r.raw) {
+                    for (const p of r.raw.pages) {
+                        p.pageNum = i + 1;
+                        combined.pages.push(p);
+                    }
+                    combined.fullText += r.raw.fullText;
+                    combined.processingMs += r.raw.processingMs;
+                }
+            } catch (err) {
+                console.log(`[WARN] OCR PDF page ${i + 1} error: ${err}`);
+            }
+        }
+
+        if (combined.pages.length === 0) {
+            throw new Error("ocr PDF: no pages processed");
+        }
+
+        // 평균 confidence 계산
+        let totalConf = 0,
+            blockCount = 0;
+        for (const p of combined.pages) {
+            for (const b of p.blocks) {
+                totalConf += b.confidence;
+                blockCount++;
+            }
+        }
+        combined.confidence = blockCount > 0 ? totalConf / blockCount : 0;
+
+        const parsed = await this.pipeline.parse(combined, opts.docType ?? "");
+        this.postProcess(data, opts, parsed);
+        return parsed;
+    }
+
+    /** 단일 이미지에 대해 OCR 인식을 수행한다 */
+    private async recognizeInternal(
+        data: Buffer,
+        opts: RecognizeOptions,
+    ): Promise<OcrResult> {
+        const fileHash = computeFileHash(data);
+        const driverName = this.resolveDriverName(opts);
+
+        // 캐시 히트 확인
+        if (this.cacheMan) {
+            const key = this.cacheMan.cacheKey(
+                fileHash,
+                driverName,
+                opts.docType ?? "",
+            );
+            const cached = this.cacheMan.get(key);
+            if (cached) return cached;
+        }
+
+        // 드라이버 선택
+        const driver = this.drivers.get(driverName) ?? this.defaultDriver;
+        if (!driver) throw new Error("ocr: no driver available");
+
+        const raw = await retryRecognize(driver, data, opts, {
+            maxRetries: 3,
+            retryDelayMs: 1000,
+        });
+
+        // 파싱 파이프라인
+        const result = await this.pipeline.parse(raw, opts.docType ?? "");
+
+        // 캐시 저장
+        if (this.cacheMan) {
+            const key = this.cacheMan.cacheKey(
+                fileHash,
+                driverName,
+                opts.docType ?? "",
+            );
+            this.cacheMan.set(key, result);
+        }
+
+        this.postProcess(data, opts, result);
+        return result;
+    }
+
+    /** 인식 후 쿼터 사용량을 기록한다 */
+    private postProcess(
+        data: Buffer,
+        opts: RecognizeOptions,
+        result: OcrResult,
+    ): void {
+        const driverName = this.resolveDriverName(opts);
+        let pageCount = 1;
+        if (result.raw) {
+            pageCount = result.raw.pages.length || 1;
+        }
+        if (this.quotaMan) {
+            this.quotaMan
+                .increment(driverName, opts.docType ?? "", pageCount)
+                .catch(() => {});
+        }
+    }
+
+    /** 옵션에서 사용할 드라이버 이름을 결정한다 */
+    private resolveDriverName(opts: RecognizeOptions): string {
+        if (this.defaultDriver) return this.defaultDriver.name();
+        if (this.config.default) return this.config.default;
+        return "unknown";
+    }
+}

package/src/app/plugins/ocr/template-loader.ts

@@ -0,0 +1,72 @@
+/**
+ * TemplateLoader — JSON 템플릿/프롬프트 파일 로드 + 캐싱
+ */
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { Template, LlmPromptTemplate } from "./types/index.ts";
+import { OcrError, ERR_TEMPLATE_NOT_FOUND } from "./errors.ts";
+
+export class TemplateLoader {
+    private readonly templateDir: string;
+    private readonly cache = new Map<string, Template>();
+
+    /** 템플릿 디렉토리 경로로 로더를 초기화한다 */
+    constructor(templateDir: string) {
+        this.templateDir = templateDir;
+    }
+
+    /** doc_type에 해당하는 템플릿 로드 (캐시됨) */
+    load(docType: string): Template {
+        const cached = this.cache.get(docType);
+        if (cached) return cached;
+
+        const path = join(this.templateDir, `${docType}.json`);
+        if (!existsSync(path)) {
+            throw new OcrError(
+                `template not found: ${docType}`,
+                ERR_TEMPLATE_NOT_FOUND,
+            );
+        }
+
+        const data = JSON.parse(readFileSync(path, "utf-8")) as Template;
+        this.cache.set(docType, data);
+        return data;
+    }
+
+    /** doc_type 템플릿 파일 존재 여부 확인 */
+    has(docType: string): boolean {
+        if (this.cache.has(docType)) return true;
+        return existsSync(join(this.templateDir, `${docType}.json`));
+    }
+
+    /** 템플릿 디렉토리의 모든 doc_type 반환 */
+    listDocTypes(): string[] {
+        try {
+            return readdirSync(this.templateDir)
+                .filter((f) => f.endsWith(".json") && !f.startsWith("."))
+                .map((f) => f.replace(/\.json$/, ""));
+        } catch {
+            return [];
+        }
+    }
+
+    /** 특정 doc_type 캐시 제거 */
+    invalidate(docType: string): void {
+        this.cache.delete(docType);
+    }
+
+    /** 전체 캐시 초기화 */
+    invalidateAll(): void {
+        this.cache.clear();
+    }
+
+    /** LLM 폴백용 프롬프트 템플릿 로드 */
+    loadPrompt(promptDir: string, docType: string): LlmPromptTemplate {
+        const path = join(promptDir, `${docType}.json`);
+        if (!existsSync(path)) {
+            throw new Error(`prompt template not found: ${docType}`);
+        }
+        return JSON.parse(readFileSync(path, "utf-8")) as LlmPromptTemplate;
+    }
+}