create-entity-app-server 0.0.3

package/src/app/plugins/ocr/llm-parser.ts

@@ -0,0 +1,164 @@
+/**
+ * LlmParser — 템플릿 매칭 실패 시 LLM 서비스로 폴백
+ */
+
+import type { ParsedDocument, LlmPromptTemplate } from "./types/index.ts";
+import { TemplateLoader } from "./template-loader.ts";
+
+/** OCR이 LLM 서비스에 의존하기 위한 인터페이스 (순환 의존 방지) */
+export interface LlmServiceLike {
+    simpleChat(
+        providerName: string,
+        system: string,
+        user: string,
+    ): Promise<string>;
+}
+
+export class LlmParser {
+    /** LLM 파서를 서비스와 프롬프트 설정으로 초기화한다 */
+    constructor(
+        private readonly llmService: LlmServiceLike,
+        private readonly providerName: string,
+        private readonly promptDir: string,
+        private readonly loader: TemplateLoader,
+    ) {}
+
+    /** OCR 텍스트를 LLM으로 파싱 */
+    async parse(ocrText: string, docType: string): Promise<ParsedDocument> {
+        if (!this.llmService) throw new Error("LLM service not configured");
+
+        // 1. 프롬프트 템플릿 로드
+        const prompt = this.loader.loadPrompt(this.promptDir, docType);
+
+        // 2. 프롬프트 조립
+        const schemaJson = JSON.stringify(prompt.schema, null, 2);
+        let userMsg = prompt.userMsg.replace("{{ocr_text}}", ocrText);
+        userMsg = userMsg.replace("{{schema}}", schemaJson);
+
+        // 3. LLM 서비스 호출
+        const response = await this.llmService.simpleChat(
+            this.providerName,
+            prompt.systemMsg,
+            userMsg,
+        );
+
+        // 4. JSON 파싱
+        return parseResponse(docType, response);
+    }
+}
+
+/** LLM 응답을 ParsedDocument로 변환한다 */
+function parseResponse(docType: string, response: string): ParsedDocument {
+    const cleaned = stripMarkdownJSON(response.trim());
+
+    let raw: Record<string, string>;
+    try {
+        raw = JSON.parse(cleaned);
+    } catch {
+        throw new Error(`LLM JSON parse error: ${cleaned.slice(0, 200)}`);
+    }
+
+    const doc: ParsedDocument = { docType };
+
+    switch (docType) {
+        case "business_reg":
+            doc.businessReg = {
+                corpNum: raw["corp_num"],
+                corpName: raw["corp_name"],
+                ceoName: raw["ceo_name"],
+                address: raw["address"],
+                bizType: raw["biz_type"],
+                bizClass: raw["biz_class"],
+                openDate: raw["open_date"],
+            };
+            break;
+        case "receipt":
+            doc.receipt = {
+                storeName: raw["store_name"],
+                storeAddr: raw["store_addr"],
+                corpNum: raw["corp_num"],
+                date: raw["date"],
+                totalAmount: raw["total_amount"],
+                paymentType: raw["payment_type"],
+                cardNumber: raw["card_number"],
+            };
+            break;
+        case "invoice":
+            doc.invoice = {
+                invoiceNum: raw["invoice_num"],
+                issuerCorpNum: raw["issuer_corp_num"],
+                issuerName: raw["issuer_name"],
+                receiverCorpNum: raw["receiver_corp_num"],
+                receiverName: raw["receiver_name"],
+                writeDate: raw["write_date"],
+                amountTotal: raw["amount_total"],
+                taxTotal: raw["tax_total"],
+                totalAmount: raw["total_amount"],
+            };
+            break;
+        case "namecard":
+            doc.namecard = {
+                name: raw["name"],
+                company: raw["company"],
+                department: raw["department"],
+                title: raw["title"],
+                address: raw["address"],
+                website: raw["website"],
+            };
+            break;
+        case "id_card":
+            doc.idCard = {
+                name: raw["name"],
+                idNumber: raw["id_number"],
+                issueDate: raw["issue_date"],
+                issuer: raw["issuer"],
+            };
+            break;
+        case "driver_license":
+            doc.driverLicense = {
+                name: raw["name"],
+                idNumber: raw["id_number"],
+                licenseNum: raw["license_num"],
+                licenseType: raw["license_type"],
+                issueDate: raw["issue_date"],
+                expiryDate: raw["expiry_date"],
+                issuer: raw["issuer"],
+            };
+            break;
+        case "facility_card":
+            doc.facilityCard = {
+                buildingName: raw["building_name"],
+                address: raw["address"],
+                buildingUse: raw["building_use"],
+                structure: raw["structure"],
+                area: raw["area"],
+                floorCount: raw["floor_count"],
+                approvalDate: raw["approval_date"],
+                owner: raw["owner"],
+            };
+            break;
+        case "career_cert":
+            doc.careerCert = {
+                name: raw["name"],
+                idNumber: raw["id_number"],
+                company: raw["company"],
+                department: raw["department"],
+                position: raw["position"],
+                joinDate: raw["join_date"],
+                leaveDate: raw["leave_date"],
+                issueDate: raw["issue_date"],
+                issuer: raw["issuer"],
+            };
+            break;
+        default:
+            throw new Error(`Unsupported doc_type for LLM parsing: ${docType}`);
+    }
+    return doc;
+}
+
+/** 마크다운 코드 블록 구분자를 제거한다 */
+function stripMarkdownJSON(s: string): string {
+    s = s.replace(/^```json\s*/, "").replace(/^```\s*/, "");
+    s = s.replace(/\s*```$/, "");
+    return s.trim();
+}

package/src/app/plugins/ocr/parsing-pipeline.ts

@@ -0,0 +1,87 @@
+/**
+ * ParsingPipeline — 2단계 파싱 파이프라인
+ * 1차: JSON 템플릿 기반 규칙 매칭
+ * 2차: LLM 후처리 (폴백)
+ */
+
+import type {
+    RawOcrResult,
+    OcrResult,
+    OcrParsingConfig,
+} from "./types/index.ts";
+import { TemplateMatcher } from "./template-matcher.ts";
+import { LlmParser } from "./llm-parser.ts";
+
+export class ParsingPipeline {
+    /** 템플릿 매처와 LLM 파서로 파이프라인을 초기화한다 */
+    constructor(
+        private readonly templateMatcher: TemplateMatcher,
+        private readonly llmParser: LlmParser | null,
+        private readonly config: OcrParsingConfig,
+    ) {}
+
+    /** RawOcrResult를 구조화된 OcrResult로 변환 */
+    async parse(raw: RawOcrResult, docType: string): Promise<OcrResult> {
+        const result: OcrResult = {
+            raw,
+            parseMethod: "none",
+            parseConfidence: 0,
+        };
+
+        // general 타입은 파싱 없이 반환
+        if (!docType || docType === "general") return result;
+
+        const threshold = this.config.confidenceThreshold || 0.6;
+
+        // 1차: 템플릿 매칭
+        if (this.templateMatcher.hasTemplate(docType)) {
+            try {
+                const matchResult = this.templateMatcher.match(raw, docType);
+                if (
+                    matchResult.missingRequired.length === 0 &&
+                    matchResult.confidence >= threshold
+                ) {
+                    result.parsed = matchResult.parsed;
+                    result.parseMethod = "template";
+                    result.parseConfidence = matchResult.confidence;
+                    return result;
+                }
+
+                // 폴백 사유 로깅
+                if (matchResult.missingRequired.length > 0) {
+                    console.log(
+                        `[DEBUG] OCR template fallback: missing required fields ${JSON.stringify(matchResult.missingRequired)} (doc_type=${docType})`,
+                    );
+                } else {
+                    console.log(
+                        `[DEBUG] OCR template fallback: low confidence ${matchResult.confidence.toFixed(2)} < ${threshold.toFixed(2)} (doc_type=${docType})`,
+                    );
+                }
+            } catch (err) {
+                console.log(
+                    `[DEBUG] OCR template match error (doc_type=${docType}): ${err}`,
+                );
+            }
+        }
+
+        // 2차: LLM 폴백
+        if (this.llmParser) {
+            try {
+                const parsed = await this.llmParser.parse(
+                    raw.fullText,
+                    docType,
+                );
+                result.parsed = parsed;
+                result.parseMethod = "llm";
+                result.parseConfidence = 0.85;
+                return result;
+            } catch (err) {
+                console.log(
+                    `[WARN] OCR LLM fallback failed (doc_type=${docType}): ${err}`,
+                );
+            }
+        }
+
+        return result;
+    }
+}

package/src/app/plugins/ocr/pdf-converter.ts

@@ -0,0 +1,136 @@
+/**
+ * PDF → PNG 변환 (Go 서버 /v1/utils/pdf2png API 사용)
+ *
+ * 단일 페이지: image/png 바이너리 반환
+ * 다중 페이지: application/zip 반환 → 내부 page-001.png 등을 추출
+ */
+
+import { inflateRaw } from "node:zlib";
+import { promisify } from "node:util";
+import type { PageRange } from "./types/index.ts";
+
+const inflateRawAsync = promisify(inflateRaw);
+const DEFAULT_DPI = 300;
+
+/** Go 서버 pdf2png를 호출할 수 있는 최소 인터페이스 */
+export interface Pdf2PngClient {
+    pdf2png(
+        pdfData: ArrayBuffer | Uint8Array,
+        opts?: { dpi?: number; firstPage?: number; lastPage?: number },
+    ): Promise<ArrayBuffer>;
+}
+
+/**
+ * PDF를 PNG 이미지 Buffer 배열로 변환합니다.
+ * Go 서버 `/v1/utils/pdf2png` API를 사용합니다.
+ */
+export async function convertPDFToImages(
+    pdfData: Buffer,
+    pageRange?: PageRange,
+    dpi?: number,
+    client?: Pdf2PngClient,
+): Promise<Buffer[]> {
+    if (!client) {
+        throw new Error(
+            "pdf converter: entity server client is required (local CLI is no longer supported)",
+        );
+    }
+
+    const result = await client.pdf2png(pdfData, {
+        dpi: dpi && dpi > 0 ? dpi : DEFAULT_DPI,
+        firstPage: pageRange?.start,
+        lastPage: pageRange?.end,
+    });
+
+    const buf = Buffer.from(result);
+
+    // 단일 페이지 응답 → image/png (magic: \x89PNG)
+    if (
+        buf.length >= 4 &&
+        buf[0] === 0x89 &&
+        buf[1] === 0x50 &&
+        buf[2] === 0x4e &&
+        buf[3] === 0x47
+    ) {
+        return [buf];
+    }
+
+    // 다중 페이지 응답 → application/zip (magic: PK\x03\x04)
+    if (
+        buf.length >= 4 &&
+        buf[0] === 0x50 &&
+        buf[1] === 0x4b &&
+        buf[2] === 0x03 &&
+        buf[3] === 0x04
+    ) {
+        return extractZipPages(buf);
+    }
+
+    throw new Error(
+        "pdf converter: unexpected response format from Go server (not PNG or ZIP)",
+    );
+}
+
+/**
+ * ZIP 아카이브에서 PNG 페이지들을 추출합니다.
+ * Go 서버가 생성하는 page-001.png, page-002.png … 파일명 규칙을 따릅니다.
+ */
+async function extractZipPages(zipBuf: Buffer): Promise<Buffer[]> {
+    const pages: { name: string; data: Buffer }[] = [];
+    let offset = 0;
+
+    while (offset + 30 < zipBuf.length) {
+        // local file header signature: PK\x03\x04
+        if (
+            zipBuf[offset] !== 0x50 ||
+            zipBuf[offset + 1] !== 0x4b ||
+            zipBuf[offset + 2] !== 0x03 ||
+            zipBuf[offset + 3] !== 0x04
+        ) {
+            break;
+        }
+
+        const method = zipBuf.readUInt16LE(offset + 8); // 0=store, 8=deflate
+        const compressedSize = zipBuf.readUInt32LE(offset + 18);
+        const filenameLen = zipBuf.readUInt16LE(offset + 26);
+        const extraLen = zipBuf.readUInt16LE(offset + 28);
+        const filename = zipBuf
+            .subarray(offset + 30, offset + 30 + filenameLen)
+            .toString("utf8");
+
+        const dataStart = offset + 30 + filenameLen + extraLen;
+        const compressedData = zipBuf.subarray(
+            dataStart,
+            dataStart + compressedSize,
+        );
+
+        let fileData: Buffer;
+        if (method === 0) {
+            fileData = Buffer.from(compressedData);
+        } else if (method === 8) {
+            fileData = (await inflateRawAsync(compressedData)) as Buffer;
+        } else {
+            throw new Error(
+                `pdf converter: unsupported ZIP compression method ${method}`,
+            );
+        }
+
+        pages.push({ name: filename, data: fileData });
+        offset = dataStart + compressedSize;
+    }
+
+    if (pages.length === 0) {
+        throw new Error("pdf converter: ZIP archive contains no page files");
+    }
+
+    // page-001.png 순으로 정렬
+    pages.sort((a, b) => a.name.localeCompare(b.name));
+    return pages.map((p) => p.data);
+}
+
+/** %PDF- 매직 바이트로 PDF 판별 */
+export function isPDF(data: Buffer): boolean {
+    return (
+        data.length >= 5 && data.subarray(0, 5).toString("ascii") === "%PDF-"
+    );
+}

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

@@ -0,0 +1,313 @@
+/**
+ * TextPreprocessor — OCR 원시 텍스트 블록을 7단계로 전처리
+ * PHP NaverClovaTextProcessor 알고리즘 포팅
+ */
+
+import type {
+    TextBlock,
+    PreprocessConfig,
+    ProcessedItem,
+    ProcessedPage,
+} from "./types/index.ts";
+
+const DEFAULT_SLOPE_EXCEPTIONS = [
+    String.raw`^(\d{2}|\d{4})[\.\-\/년]?\s*(\d{1,2})[\.\-\/월]?\s*(\d{1,2})[\.\일]?$`,
+];
+
+export class TextPreprocessor {
+    /** 7단계 전처리 메인 함수 */
+    preprocess(blocks: TextBlock[], cfg: PreprocessConfig): ProcessedPage {
+        // 기본값
+        const maxSlope = cfg.maxSlope || 0.2;
+        const yTol = cfg.yTolerance || 15;
+        const xTol = cfg.xTolerance || 30;
+        const slopeExceptions = cfg.slopeExceptions?.length
+            ? cfg.slopeExceptions
+            : DEFAULT_SLOPE_EXCEPTIONS;
+        const keywords = cfg.keywords ?? {};
+
+        // ① 텍스트 추출 + 정렬
+        let items = this.extractAndSort(blocks, yTol);
+        // ② slope 필터
+        items = this.filterBySlope(items, maxSlope, slopeExceptions);
+        // ③ 문장 패턴 제거
+        items = this.removeTextPatterns(items, cfg.removePatterns ?? []);
+        // ④ 키워드 제거
+        items = this.removeKeywords(items, cfg.removeKeywords ?? []);
+        // ⑤ 텍스트 조각 병합
+        for (const [field, kwList] of Object.entries(keywords)) {
+            if (field === "dummy") continue;
+            for (const kw of kwList) {
+                items = this.mergePattern(items, kw, true);
+            }
+        }
+        for (const pattern of cfg.mergePatterns ?? []) {
+            items = this.mergePattern(items, pattern, false);
+        }
+        // ⑥ 인접 텍스트 그룹화
+        items = this.groupAdjacentTexts(items, yTol, xTol);
+        // ⑦ 키워드 식별 + 필드 할당
+        return this.processKeywords(items, keywords);
+    }
+
+    /** ① extractAndSort */
+    private extractAndSort(blocks: TextBlock[], yTol: number): ProcessedItem[] {
+        const items: ProcessedItem[] = blocks.map((b) => ({
+            text: b.text,
+            centerX: (b.boundingBox.left + b.boundingBox.right) / 2,
+            centerY: (b.boundingBox.top + b.boundingBox.bottom) / 2,
+            top: b.boundingBox.top,
+            bottom: b.boundingBox.bottom,
+            left: b.boundingBox.left,
+            right: b.boundingBox.right,
+            width: b.boundingBox.right - b.boundingBox.left,
+            height: b.boundingBox.bottom - b.boundingBox.top,
+            slope: b.slope,
+            isKeyword: false,
+            field: "",
+        }));
+
+        items.sort((a, b) => {
+            if (Math.abs(a.centerY - b.centerY) < yTol) return a.left - b.left;
+            return a.top - b.top;
+        });
+        return items;
+    }
+
+    /** ② filterBySlope */
+    private filterBySlope(
+        items: ProcessedItem[],
+        maxSlope: number,
+        exceptions: string[],
+    ): ProcessedItem[] {
+        const compiled = exceptions
+            .map((p) => {
+                try {
+                    return new RegExp(p);
+                } catch {
+                    return null;
+                }
+            })
+            .filter((r): r is RegExp => r !== null);
+
+        return items.filter((item) => {
+            if (Math.abs(item.slope) <= maxSlope) return true;
+            const trimmed = item.text.trim();
+            return compiled.some((re) => re.test(trimmed));
+        });
+    }
+
+    /** ③ removeTextPatterns */
+    private removeTextPatterns(
+        items: ProcessedItem[],
+        patterns: string[],
+    ): ProcessedItem[] {
+        if (!patterns.length) return items;
+        const clean = patterns.map((p) => p.toLowerCase().replace(/ /g, ""));
+        return items.filter((item) => {
+            const t = item.text.toLowerCase().replace(/ /g, "");
+            return !clean.some((cp) => cp.includes(t));
+        });
+    }
+
+    /** ④ removeKeywords */
+    private removeKeywords(
+        items: ProcessedItem[],
+        keywords: string[],
+    ): ProcessedItem[] {
+        if (!keywords.length) return items;
+        const clean = keywords.map((k) => k.toLowerCase().replace(/ /g, ""));
+        return items.filter((item) => {
+            const t = item.text.toLowerCase().replace(/ /g, "");
+            return !clean.includes(t);
+        });
+    }
+
+    /** ⑤ mergePattern */
+    private mergePattern(
+        items: ProcessedItem[],
+        pattern: string,
+        isKeyword: boolean,
+    ): ProcessedItem[] {
+        const cleanPattern = pattern.replace(/ /g, "");
+        if (!cleanPattern) return items;
+
+        const result: ProcessedItem[] = [];
+        let i = 0;
+
+        while (i < items.length) {
+            const matched: ProcessedItem[] = [];
+            let patternPos = 0;
+            let j = i;
+
+            while (j < items.length && patternPos < runeLength(cleanPattern)) {
+                const currentText = cleanTextForMatching(items[j].text);
+                if (!currentText) {
+                    j++;
+                    continue;
+                }
+
+                const currentLen = runeLength(currentText);
+                const patternPart = substringRunes(
+                    cleanPattern,
+                    patternPos,
+                    currentLen,
+                );
+                if (currentText === patternPart) {
+                    matched.push(items[j]);
+                    patternPos += currentLen;
+                    j++;
+                } else {
+                    break;
+                }
+            }
+
+            if (matched.length > 1 && patternPos >= runeLength(cleanPattern)) {
+                result.push(mergeMatchedItems(matched, pattern, isKeyword));
+                i = j;
+            } else {
+                result.push(items[i]);
+                i++;
+            }
+        }
+        return result;
+    }
+
+    /** ⑥ groupAdjacentTexts */
+    private groupAdjacentTexts(
+        items: ProcessedItem[],
+        yTol: number,
+        xTol: number,
+    ): ProcessedItem[] {
+        const groups: ProcessedItem[] = [];
+        let current: ProcessedItem | null = null;
+        let prevEndsWithColon = false;
+
+        for (const item of items) {
+            const curEndsWithColon =
+                item.text.endsWith(":") || item.text === ":";
+            const startNew =
+                !current ||
+                item.isKeyword ||
+                current.isKeyword ||
+                prevEndsWithColon ||
+                curEndsWithColon ||
+                Math.abs(current.centerY - item.centerY) >= yTol ||
+                item.left - current.right >= xTol;
+
+            if (startNew) {
+                if (current) groups.push(current);
+                current = { ...item };
+            } else {
+                current!.text += " " + item.text;
+                current!.top = Math.min(current!.top, item.top);
+                current!.bottom = Math.max(current!.bottom, item.bottom);
+                current!.left = Math.min(current!.left, item.left);
+                current!.right = Math.max(current!.right, item.right);
+                current!.centerX = (current!.left + current!.right) / 2;
+                current!.centerY = (current!.top + current!.bottom) / 2;
+                current!.width = current!.right - current!.left;
+                current!.height = current!.bottom - current!.top;
+            }
+            prevEndsWithColon = curEndsWithColon;
+        }
+        if (current) groups.push(current);
+        return groups;
+    }
+
+    /** ⑦ processKeywords */
+    private processKeywords(
+        items: ProcessedItem[],
+        keywords: Record<string, string[]>,
+    ): ProcessedPage {
+        const page: ProcessedPage = { keywordList: {}, valueList: [] };
+
+        for (const item of items) {
+            const cleanText = item.text.replace(/ /g, "");
+            item.isKeyword = false;
+
+            for (const [field, kwList] of Object.entries(keywords)) {
+                if (field === "dummy") continue;
+                for (const kw of kwList) {
+                    const cleanKw = kw.replace(/ /g, "");
+                    if (
+                        cleanText === cleanKw ||
+                        cleanText.startsWith(cleanKw)
+                    ) {
+                        item.text = cleanText.replace(/:$/, "");
+                        item.isKeyword = true;
+                        item.field = field;
+                        break;
+                    }
+                }
+                if (item.isKeyword) break;
+            }
+
+            if (item.isKeyword) {
+                if (!page.keywordList[item.field])
+                    page.keywordList[item.field] = [];
+                page.keywordList[item.field].push(item);
+            } else {
+                page.valueList.push(item);
+            }
+        }
+        return page;
+    }
+}
+
+// ─── 헬퍼 함수 ───
+
+/** 매칭용 텍스트를 정제한다 */
+function cleanTextForMatching(text: string): string {
+    text = text.trim();
+    if (text === ":") return "";
+    if (text.endsWith(":")) text = text.slice(0, -1);
+    return text.replace(/ /g, "");
+}
+
+/** 유니코드 룬(rune) 기준 문자열 길이를 반환한다 */
+function runeLength(s: string): number {
+    return [...s].length;
+}
+
+/** 유니코드 룬 기준으로 부분 문자열을 추출한다 */
+function substringRunes(s: string, start: number, length: number): string {
+    const runes = [...s];
+    return runes.slice(start, start + length).join("");
+}
+
+/** 일치한 항목들을 하나의 ProcessedItem으로 병합한다 */
+function mergeMatchedItems(
+    items: ProcessedItem[],
+    text: string,
+    isKeyword: boolean,
+): ProcessedItem {
+    let top = Infinity,
+        left = Infinity,
+        bottom = -Infinity,
+        right = -Infinity;
+    let slope = 0;
+
+    for (const item of items) {
+        top = Math.min(top, item.top);
+        bottom = Math.max(bottom, item.bottom);
+        left = Math.min(left, item.left);
+        right = Math.max(right, item.right);
+        if (item.slope !== 0) slope = item.slope;
+    }
+
+    return {
+        text,
+        isKeyword,
+        field: "",
+        centerX: (left + right) / 2,
+        centerY: (top + bottom) / 2,
+        top,
+        bottom,
+        left,
+        right,
+        width: right - left,
+        height: bottom - top,
+        slope,
+    };
+}