create-entity-app-server 0.0.3 → 0.0.4

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

@@ -1,112 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-/**
- * 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

@@ -1,333 +0,0 @@
-/**
- * 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

@@ -1,72 +0,0 @@
-/**
- * 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;
-    }
-}