create-entity-app-server 0.0.3

package/src/app/plugins/ocr/providers/naver.ts

@@ -0,0 +1,186 @@
+/**
+ * Naver CLOVA General OCR 드라이버
+ * multipart/form-data 기반 API
+ */
+
+import type {
+    OcrDriver,
+    OcrProviderConfig,
+    RawOcrResult,
+    RecognizeOptions,
+    TextBlock,
+    RawOcrPage,
+} from "../types/index.ts";
+
+const EXTENSION_MAP: Record<string, string> = {
+    "image/jpeg": "jpg",
+    "image/png": "png",
+    "image/tiff": "tiff",
+    "image/bmp": "bmp",
+    "image/webp": "webp",
+    "application/pdf": "pdf",
+};
+
+export class NaverDriver implements OcrDriver {
+    private readonly apiUrl: string;
+    private readonly secretKey: string;
+    private readonly timeout: number;
+
+    /** Naver CLOVA OCR 드라이버를 설정으로 초기화한다 */
+    constructor(cfg: OcrProviderConfig) {
+        this.apiUrl = cfg.apiUrl ?? "";
+        this.secretKey = cfg.secretKey ?? "";
+        this.timeout = (cfg.timeoutSec ?? 30) * 1000;
+    }
+
+    /** 드라이버 이름을 반환한다 */
+    name() {
+        return "naver";
+    }
+    /** 지원하는 파일 형식 목록을 반환한다 */
+    supportedFormats() {
+        return [
+            "image/jpeg",
+            "image/png",
+            "image/tiff",
+            "image/bmp",
+            "application/pdf",
+        ];
+    }
+    /** 드라이버 리소스를 해제한다 */
+    async close() {}
+
+    /** 이미지 데이터를 Naver CLOVA API로 인식한다 */
+    async recognize(
+        data: Buffer,
+        opts: RecognizeOptions,
+    ): Promise<RawOcrResult> {
+        const start = Date.now();
+        const ext = EXTENSION_MAP[opts.mimeType] ?? "jpg";
+
+        const message = {
+            version: "V2",
+            requestId: crypto.randomUUID(),
+            timestamp: Date.now(),
+            lang: opts.languages?.[0] ?? "ko",
+            images: [{ format: ext, name: "image" }],
+        };
+
+        const formData = new FormData();
+        formData.append("message", JSON.stringify(message));
+        formData.append(
+            "file",
+            new Blob([data], { type: opts.mimeType }),
+            `image.${ext}`,
+        );
+
+        const resp = await fetch(this.apiUrl, {
+            method: "POST",
+            headers: { "X-OCR-SECRET": this.secretKey },
+            body: formData,
+            signal: AbortSignal.timeout(this.timeout),
+        });
+
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`Naver OCR API error ${resp.status}: ${text}`);
+        }
+
+        const json = (await resp.json()) as any;
+        const images = json.images ?? [];
+        const resultPages: RawOcrPage[] = [];
+        let fullText = "";
+
+        for (let pi = 0; pi < images.length; pi++) {
+            const img = images[pi];
+            const blocks: TextBlock[] = [];
+            const lines: string[] = [];
+
+            for (const field of img.fields ?? []) {
+                const tb = parseNaverField(field);
+                if (tb) {
+                    blocks.push(tb);
+                    lines.push(tb.text);
+                }
+            }
+
+            const pageText = lines.join(" ");
+            fullText += (pi > 0 ? "\n" : "") + pageText;
+
+            const avgConf =
+                blocks.length > 0
+                    ? blocks.reduce((s, b) => s + b.confidence, 0) /
+                      blocks.length
+                    : 0;
+
+            // 이미지 크기 추정 (bounding box 기반)
+            let maxRight = 0,
+                maxBottom = 0;
+            for (const b of blocks) {
+                if (b.boundingBox.right > maxRight)
+                    maxRight = b.boundingBox.right;
+                if (b.boundingBox.bottom > maxBottom)
+                    maxBottom = b.boundingBox.bottom;
+            }
+
+            resultPages.push({
+                pageNum: pi + 1,
+                width: maxRight,
+                height: maxBottom,
+                text: pageText,
+                blocks,
+            });
+        }
+
+        const totalConf = resultPages.reduce(
+            (s, p) => s + p.blocks.reduce((ss, b) => ss + b.confidence, 0),
+            0,
+        );
+        const totalBlocks = resultPages.reduce(
+            (s, p) => s + p.blocks.length,
+            0,
+        );
+
+        return {
+            provider: "naver",
+            providerRaw: json,
+            fullText,
+            processingMs: Date.now() - start,
+            processedAt: new Date().toISOString(),
+            confidence: totalBlocks > 0 ? totalConf / totalBlocks : 0,
+            pages: resultPages,
+        };
+    }
+}
+
+/** Naver OCR 필드 데이터를 TextBlock으로 변환한다 */
+function parseNaverField(field: any): TextBlock | null {
+    const text = field.inferText ?? "";
+    if (!text) return null;
+
+    const conf = field.inferConfidence ?? 0;
+    const vertices = field.boundingPoly?.vertices ?? [];
+    if (vertices.length < 4) return null;
+
+    const xs = vertices.map((v: any) => v.x ?? 0);
+    const ys = vertices.map((v: any) => v.y ?? 0);
+    const left = Math.min(...xs);
+    const right = Math.max(...xs);
+    const top = Math.min(...ys);
+    const bottom = Math.max(...ys);
+
+    const slope =
+        right - left > 0
+            ? ((vertices[1]?.y ?? 0) - (vertices[0]?.y ?? 0)) / (right - left)
+            : 0;
+
+    return {
+        text,
+        boundingBox: { top, left, right, bottom },
+        centerX: (left + right) / 2,
+        centerY: (top + bottom) / 2,
+        slope,
+        confidence: conf,
+        lineBreak: field.lineBreak?.type === "SPACE" ? false : true,
+    };
+}

package/src/app/plugins/ocr/providers/tesseract.ts

@@ -0,0 +1,198 @@
+/**
+ * 로컬 Tesseract CLI OCR 드라이버
+ * tesseract CLI → TSV 파싱
+ */
+
+import { execFile } from "node:child_process";
+import { writeFile, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import type {
+    OcrDriver,
+    OcrProviderConfig,
+    RawOcrResult,
+    RecognizeOptions,
+    TextBlock,
+} from "../types/index.ts";
+
+const execFileAsync = promisify(execFile);
+
+// TSV 컬럼 인덱스 (Tesseract output)
+const TSV_LEVEL = 0;
+const TSV_PAGE_NUM = 1;
+const TSV_BLOCK_NUM = 2;
+const TSV_PAR_NUM = 3;
+const TSV_LINE_NUM = 4;
+const TSV_WORD_NUM = 5;
+const TSV_LEFT = 6;
+const TSV_TOP = 7;
+const TSV_WIDTH = 8;
+const TSV_HEIGHT = 9;
+const TSV_CONF = 10;
+const TSV_TEXT = 11;
+
+export class TesseractDriver implements OcrDriver {
+    private readonly lang: string;
+    private readonly dataPath: string;
+    private readonly psm: number;
+    private readonly oem: number;
+    private readonly timeout: number;
+
+    /** Tesseract CLI 드라이버를 설정으로 초기화한다 */
+    constructor(cfg: OcrProviderConfig) {
+        this.lang = cfg.defaultLang ?? "kor+eng";
+        this.dataPath = cfg.dataPath ?? "";
+        this.psm = cfg.psm ?? 3;
+        this.oem = cfg.oem ?? 3;
+        this.timeout = (cfg.timeoutSec ?? 30) * 1000;
+    }
+
+    /** 드라이버 이름을 반환한다 */
+    name() {
+        return "tesseract";
+    }
+    /** 지원하는 파일 형식 목록을 반환한다 */
+    supportedFormats() {
+        return [
+            "image/jpeg",
+            "image/png",
+            "image/tiff",
+            "image/bmp",
+            "image/webp",
+        ];
+    }
+    /** 드라이버 리소스를 해제한다 */
+    async close() {}
+
+    /** 이미지 데이터를 Tesseract CLI로 인식한다 */
+    async recognize(
+        data: Buffer,
+        opts: RecognizeOptions,
+    ): Promise<RawOcrResult> {
+        const start = Date.now();
+        const tmpDir = await mkdtemp(join(tmpdir(), "ocr-tess-"));
+
+        try {
+            const inputPath = join(tmpDir, "input");
+            const outputBase = join(tmpDir, "output");
+            await writeFile(inputPath, data);
+
+            const args = [
+                inputPath,
+                outputBase,
+                "-l",
+                opts.languages?.[0] ?? this.lang,
+                "--psm",
+                String(this.psm),
+                "--oem",
+                String(this.oem),
+                "tsv",
+            ];
+            if (this.dataPath) {
+                args.unshift("--tessdata-dir", this.dataPath);
+            }
+
+            await execFileAsync("tesseract", args, { timeout: this.timeout });
+
+            const { readFile } = await import("node:fs/promises");
+            const tsvData = await readFile(outputBase + ".tsv", "utf-8");
+            const { blocks, fullText } = parseTesseractTSV(tsvData);
+
+            const result: RawOcrResult = {
+                provider: "tesseract",
+                providerRaw: tsvData,
+                fullText,
+                processingMs: Date.now() - start,
+                processedAt: new Date().toISOString(),
+                confidence: 0,
+                pages: [],
+            };
+
+            if (blocks.length > 0) {
+                let maxRight = 0,
+                    maxBottom = 0,
+                    totalConf = 0;
+                for (const b of blocks) {
+                    if (b.boundingBox.right > maxRight)
+                        maxRight = b.boundingBox.right;
+                    if (b.boundingBox.bottom > maxBottom)
+                        maxBottom = b.boundingBox.bottom;
+                    totalConf += b.confidence;
+                }
+                result.pages = [
+                    {
+                        pageNum: 1,
+                        width: maxRight,
+                        height: maxBottom,
+                        text: fullText,
+                        blocks,
+                    },
+                ];
+                result.confidence = totalConf / blocks.length;
+            }
+
+            return result;
+        } finally {
+            await rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+        }
+    }
+}
+
+/**
+ * Tesseract TSV 출력을 파싱합니다.
+ */
+function parseTesseractTSV(tsv: string): {
+    blocks: TextBlock[];
+    fullText: string;
+} {
+    const blocks: TextBlock[] = [];
+    const lines: string[] = [];
+    let curLine = "";
+    let prevLineNum = -1;
+
+    const rows = tsv.split("\n");
+    // 헤더 스킵
+    for (let i = 1; i < rows.length; i++) {
+        const fields = rows[i].split("\t");
+        if (fields.length <= TSV_TEXT) continue;
+
+        const text = fields[TSV_TEXT];
+        if (!text) continue;
+
+        let conf = parseFloat(fields[TSV_CONF]) || 0;
+        if (conf < 0) conf = 0;
+
+        const left = parseInt(fields[TSV_LEFT]) || 0;
+        const top = parseInt(fields[TSV_TOP]) || 0;
+        const width = parseInt(fields[TSV_WIDTH]) || 0;
+        const height = parseInt(fields[TSV_HEIGHT]) || 0;
+        const lineNum = parseInt(fields[TSV_LINE_NUM]) || 0;
+        const right = left + width;
+        const bottom = top + height;
+
+        if (lineNum !== prevLineNum && prevLineNum !== -1) {
+            const trimmed = curLine.trim();
+            if (trimmed) lines.push(trimmed);
+            curLine = "";
+        }
+        curLine += text + " ";
+        prevLineNum = lineNum;
+
+        blocks.push({
+            text,
+            confidence: conf / 100,
+            boundingBox: { top, left, right, bottom },
+            centerX: (left + right) / 2,
+            centerY: (top + bottom) / 2,
+            slope: 0,
+            lineBreak: false,
+        });
+    }
+
+    if (curLine.trim()) {
+        lines.push(curLine.trim());
+    }
+
+    return { blocks, fullText: lines.join("\n") };
+}

package/src/app/plugins/ocr/providers/upstage.ts

@@ -0,0 +1,156 @@
+/**
+ * Upstage Document AI OCR 드라이버
+ * multipart/form-data 기반 API
+ */
+
+import type {
+    OcrDriver,
+    OcrProviderConfig,
+    RawOcrResult,
+    RawOcrPage,
+    RecognizeOptions,
+    TextBlock,
+} from "../types/index.ts";
+
+export class UpstageDriver implements OcrDriver {
+    private readonly apiKey: string;
+    private readonly apiUrl: string;
+    private readonly timeout: number;
+
+    /** Upstage Document AI 드라이버를 설정으로 초기화한다 */
+    constructor(cfg: OcrProviderConfig) {
+        this.apiKey = cfg.apiKey ?? "";
+        this.apiUrl = cfg.apiUrl ?? "https://api.upstage.ai/v1/document-ai/ocr";
+        this.timeout = (cfg.timeoutSec ?? 60) * 1000;
+    }
+
+    /** 드라이버 이름을 반환한다 */
+    name() {
+        return "upstage";
+    }
+    /** 지원하는 파일 형식 목록을 반환한다 */
+    supportedFormats() {
+        return ["image/jpeg", "image/png", "image/tiff", "application/pdf"];
+    }
+    /** 드라이버 리소스를 해제한다 */
+    async close() {}
+
+    /** 이미지 데이터를 Upstage API로 인식한다 */
+    async recognize(
+        data: Buffer,
+        opts: RecognizeOptions,
+    ): Promise<RawOcrResult> {
+        const start = Date.now();
+
+        const formData = new FormData();
+        formData.append(
+            "document",
+            new Blob([data], { type: opts.mimeType }),
+            "document",
+        );
+
+        const resp = await fetch(this.apiUrl, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.apiKey}` },
+            body: formData,
+            signal: AbortSignal.timeout(this.timeout),
+        });
+
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`Upstage OCR API error ${resp.status}: ${text}`);
+        }
+
+        const json = (await resp.json()) as any;
+        const blocks: TextBlock[] = [];
+        let fullText = "";
+        const resultPages: RawOcrPage[] = [];
+
+        for (let pi = 0; pi < (json.pages ?? []).length; pi++) {
+            const page = json.pages[pi];
+            const pageBlocks: TextBlock[] = [];
+            for (const word of page.words ?? []) {
+                // Upstage: bounding_box는 [{x,y}, {x,y}, {x,y}, {x,y}] 형태
+                const bbox = word.bounding_box ?? word.boundingBox ?? [];
+                let left = 0,
+                    right = 0,
+                    top = 0,
+                    bottom = 0;
+
+                if (
+                    bbox.length > 0 &&
+                    typeof bbox[0] === "object" &&
+                    bbox[0] !== null
+                ) {
+                    // [{x,y}, ...] 형태
+                    const xs = bbox.map((p: any) => p.x ?? 0);
+                    const ys = bbox.map((p: any) => p.y ?? 0);
+                    left = Math.min(...xs);
+                    right = Math.max(...xs);
+                    top = Math.min(...ys);
+                    bottom = Math.max(...ys);
+                } else if (bbox.length > 0) {
+                    // flat [x1,y1,x2,y2,...] 형태 (폴백)
+                    const xs = bbox.filter(
+                        (_: number, i: number) => i % 2 === 0,
+                    );
+                    const ys = bbox.filter(
+                        (_: number, i: number) => i % 2 === 1,
+                    );
+                    left = xs.length ? Math.min(...xs) : 0;
+                    right = xs.length ? Math.max(...xs) : 0;
+                    top = ys.length ? Math.min(...ys) : 0;
+                    bottom = ys.length ? Math.max(...ys) : 0;
+                }
+
+                const tb: TextBlock = {
+                    text: word.text ?? "",
+                    boundingBox: { top, left, right, bottom },
+                    centerX: (left + right) / 2,
+                    centerY: (top + bottom) / 2,
+                    slope: 0,
+                    confidence: word.confidence ?? 0,
+                    lineBreak: false,
+                };
+                pageBlocks.push(tb);
+                blocks.push(tb);
+            }
+
+            const pageWidth =
+                page.width ??
+                (pageBlocks.length > 0
+                    ? Math.max(...pageBlocks.map((b) => b.boundingBox.right))
+                    : 0);
+            const pageHeight =
+                page.height ??
+                (pageBlocks.length > 0
+                    ? Math.max(...pageBlocks.map((b) => b.boundingBox.bottom))
+                    : 0);
+
+            resultPages.push({
+                pageNum: pi + 1,
+                width: pageWidth,
+                height: pageHeight,
+                text: pageBlocks.map((b) => b.text).join(" "),
+                blocks: pageBlocks,
+            });
+        }
+
+        fullText = json.text ?? blocks.map((b) => b.text).join(" ");
+
+        const avgConf =
+            blocks.length > 0
+                ? blocks.reduce((s, b) => s + b.confidence, 0) / blocks.length
+                : 0;
+
+        return {
+            provider: "upstage",
+            providerRaw: json,
+            fullText,
+            processingMs: Date.now() - start,
+            processedAt: new Date().toISOString(),
+            confidence: avgConf,
+            pages: resultPages,
+        };
+    }
+}

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

@@ -0,0 +1,108 @@
+/**
+ * QuotaManager — 일/월 단위 OCR 사용 쿼터 관리
+ */
+
+import type {
+    OcrQuotaConfig,
+    OcrEntityStore,
+    OcrUsageRecord,
+    QuotaStatus,
+} from "./types/index.ts";
+import { OcrError, ERR_QUOTA_EXCEEDED } from "./errors.ts";
+
+export class QuotaManager {
+    /** 쿼터 매니저를 설정과 엔티티 스토어로 초기화한다 */
+    constructor(
+        private readonly config: OcrQuotaConfig,
+        private readonly entityStore: OcrEntityStore,
+    ) {}
+
+    /** 현재 사용량이 쿼터를 초과하는지 확인 (80% 경고, 100% 에러) */
+    async check(): Promise<void> {
+        if (this.config.dailyLimit <= 0 && this.config.monthlyLimit <= 0)
+            return;
+
+        const today = new Date().toISOString().slice(0, 10);
+        const month = today.slice(0, 7);
+
+        let dailyUsed = 0;
+        let monthlyUsed = 0;
+
+        try {
+            dailyUsed = await this.entityStore.getDailyQuotaUsage(today);
+        } catch {
+            return; // 조회 실패 시 통과
+        }
+        try {
+            monthlyUsed = await this.entityStore.getMonthlyQuotaUsage(month);
+        } catch {
+            return;
+        }
+
+        if (this.config.dailyLimit > 0) {
+            const pct = (dailyUsed / this.config.dailyLimit) * 100;
+            if (dailyUsed >= this.config.dailyLimit) {
+                throw new OcrError(
+                    `daily limit reached (${dailyUsed}/${this.config.dailyLimit})`,
+                    ERR_QUOTA_EXCEEDED,
+                );
+            }
+            if (pct >= 80) {
+                console.log(
+                    `[WARN] OCR daily quota at ${pct.toFixed(0)}% (${dailyUsed}/${this.config.dailyLimit})`,
+                );
+            }
+        }
+
+        if (this.config.monthlyLimit > 0) {
+            const pct = (monthlyUsed / this.config.monthlyLimit) * 100;
+            if (monthlyUsed >= this.config.monthlyLimit) {
+                throw new OcrError(
+                    `monthly limit reached (${monthlyUsed}/${this.config.monthlyLimit})`,
+                    ERR_QUOTA_EXCEEDED,
+                );
+            }
+            if (pct >= 80) {
+                console.log(
+                    `[WARN] OCR monthly quota at ${pct.toFixed(0)}% (${monthlyUsed}/${this.config.monthlyLimit})`,
+                );
+            }
+        }
+    }
+
+    /** 사용량 카운터 1 증가 */
+    async increment(
+        provider: string,
+        docType: string,
+        pageCount: number,
+    ): Promise<void> {
+        const today = new Date().toISOString().slice(0, 10);
+        await this.entityStore.incrementUsage({
+            usageDate: today,
+            provider,
+            docType,
+            requestCount: 1,
+            pageCount,
+        });
+    }
+
+    /** 현재 쿼터 상태 조회 */
+    async getStatus(): Promise<QuotaStatus> {
+        const today = new Date().toISOString().slice(0, 10);
+        const month = today.slice(0, 7);
+
+        const dailyUsed = await this.entityStore
+            .getDailyQuotaUsage(today)
+            .catch(() => 0);
+        const monthlyUsed = await this.entityStore
+            .getMonthlyQuotaUsage(month)
+            .catch(() => 0);
+
+        return {
+            dailyUsed,
+            dailyLimit: this.config.dailyLimit,
+            monthlyUsed,
+            monthlyLimit: this.config.monthlyLimit,
+        };
+    }
+}