create-entity-app-server 0.0.3 → 0.0.4

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

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

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

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

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