create-entity-app-server 0.0.3

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

@@ -0,0 +1,200 @@
+/**
+ * AWS Textract OCR 드라이버
+ * DetectDocumentText API + SigV4 서명
+ */
+
+import { createHmac, createHash } from "node:crypto";
+import type {
+    OcrDriver,
+    OcrProviderConfig,
+    RawOcrResult,
+    RecognizeOptions,
+    TextBlock,
+    RawOcrPage,
+} from "../types/index.ts";
+
+export class AwsDriver implements OcrDriver {
+    private readonly accessKeyId: string;
+    private readonly secretAccessKey: string;
+    private readonly region: string;
+    private readonly timeout: number;
+
+    /** AWS Textract 드라이버를 설정으로 초기화한다 */
+    constructor(cfg: OcrProviderConfig) {
+        this.accessKeyId = cfg.accessKeyId ?? "";
+        this.secretAccessKey = cfg.secretAccessKey ?? "";
+        this.region = cfg.region ?? "ap-northeast-2";
+        this.timeout = (cfg.timeoutSec ?? 30) * 1000;
+    }
+
+    /** 드라이버 이름을 반환한다 */
+    name() {
+        return "aws_textract";
+    }
+    /** 지원하는 파일 형식 목록을 반환한다 */
+    supportedFormats() {
+        return ["image/jpeg", "image/png", "application/pdf"];
+    }
+    /** 드라이버 리소스를 해제한다 */
+    async close() {}
+
+    /** 이미지 데이터를 AWS Textract API로 인식한다 */
+    async recognize(
+        data: Buffer,
+        opts: RecognizeOptions,
+    ): Promise<RawOcrResult> {
+        const start = Date.now();
+        const host = `textract.${this.region}.amazonaws.com`;
+        const url = `https://${host}`;
+        const payload = JSON.stringify({
+            Document: { Bytes: data.toString("base64") },
+        });
+
+        const now = new Date();
+        const amzDate = now
+            .toISOString()
+            .replace(/[-:]/g, "")
+            .replace(/\.\d{3}/, "");
+        const dateStamp = amzDate.slice(0, 8);
+
+        const headers = this.buildAWSAuth(host, payload, amzDate, dateStamp);
+
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: {
+                ...headers,
+                "Content-Type": "application/x-amz-json-1.1",
+                "X-Amz-Target": "Textract.DetectDocumentText",
+            },
+            body: payload,
+            signal: AbortSignal.timeout(this.timeout),
+        });
+
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`AWS Textract API error ${resp.status}: ${text}`);
+        }
+
+        const json = (await resp.json()) as any;
+        const blocks: TextBlock[] = [];
+        const lineTexts: string[] = [];
+
+        for (const block of json.Blocks ?? []) {
+            if (block.BlockType === "WORD") {
+                const bb = block.Geometry?.BoundingBox ?? {};
+                const w = bb.Width ?? 0;
+                const h = bb.Height ?? 0;
+                const left = bb.Left ?? 0;
+                const top = bb.Top ?? 0;
+                const right = left + w;
+                const bottom = top + h;
+
+                // Textract는 정규화 좌표 (0~1) → 1000 기준 변환
+                const scale = 1000;
+                const sLeft = Math.round(left * scale);
+                const sTop = Math.round(top * scale);
+                const sRight = Math.round(right * scale);
+                const sBottom = Math.round(bottom * scale);
+
+                blocks.push({
+                    text: block.Text ?? "",
+                    boundingBox: {
+                        top: sTop,
+                        left: sLeft,
+                        right: sRight,
+                        bottom: sBottom,
+                    },
+                    centerX: (sLeft + sRight) / 2,
+                    centerY: (sTop + sBottom) / 2,
+                    slope: 0,
+                    confidence: (block.Confidence ?? 0) / 100,
+                    lineBreak: false,
+                });
+            } else if (block.BlockType === "LINE") {
+                lineTexts.push(block.Text ?? "");
+            }
+        }
+
+        const fullText = lineTexts.join("\n");
+        const avgConf =
+            blocks.length > 0
+                ? blocks.reduce((s, b) => s + b.confidence, 0) / blocks.length
+                : 0;
+
+        return {
+            provider: "aws_textract",
+            providerRaw: json,
+            fullText,
+            processingMs: Date.now() - start,
+            processedAt: new Date().toISOString(),
+            confidence: avgConf,
+            pages: [
+                {
+                    pageNum: 1,
+                    width: 1000,
+                    height: 1000,
+                    text: fullText,
+                    blocks,
+                },
+            ],
+        };
+    }
+
+    /** AWS SigV4 서명 헤더를 생성한다 */
+    private buildAWSAuth(
+        host: string,
+        payload: string,
+        amzDate: string,
+        dateStamp: string,
+    ): Record<string, string> {
+        const service = "textract";
+        const algorithm = "AWS4-HMAC-SHA256";
+        const credentialScope = `${dateStamp}/${this.region}/${service}/aws4_request`;
+
+        const payloadHash = createHash("sha256").update(payload).digest("hex");
+
+        const canonicalHeaders = `content-type:application/x-amz-json-1.1\nhost:${host}\nx-amz-date:${amzDate}\nx-amz-target:Textract.DetectDocumentText\n`;
+        const signedHeaders = "content-type;host;x-amz-date;x-amz-target";
+
+        const canonicalRequest = [
+            "POST",
+            "/",
+            "",
+            canonicalHeaders,
+            signedHeaders,
+            payloadHash,
+        ].join("\n");
+
+        const stringToSign = [
+            algorithm,
+            amzDate,
+            credentialScope,
+            createHash("sha256").update(canonicalRequest).digest("hex"),
+        ].join("\n");
+
+        const signingKey = this.getSignatureKey(dateStamp, service);
+        const signature = createHmac("sha256", signingKey)
+            .update(stringToSign)
+            .digest("hex");
+
+        const authorization = `${algorithm} Credential=${this.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+
+        return {
+            Host: host,
+            "X-Amz-Date": amzDate,
+            Authorization: authorization,
+        };
+    }
+
+    /** SigV4 서명 키를 생성한다 */
+    private getSignatureKey(dateStamp: string, service: string): Buffer {
+        const kDate = createHmac("sha256", `AWS4${this.secretAccessKey}`)
+            .update(dateStamp)
+            .digest();
+        const kRegion = createHmac("sha256", kDate)
+            .update(this.region)
+            .digest();
+        const kService = createHmac("sha256", kRegion).update(service).digest();
+        return createHmac("sha256", kService).update("aws4_request").digest();
+    }
+}

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

@@ -0,0 +1,183 @@
+/**
+ * Azure Document Intelligence OCR 드라이버
+ * 비동기 폴링 방식
+ */
+
+import type {
+    OcrDriver,
+    OcrProviderConfig,
+    RawOcrResult,
+    RecognizeOptions,
+    TextBlock,
+    RawOcrPage,
+} from "../types/index.ts";
+
+export class AzureDriver implements OcrDriver {
+    private readonly endpoint: string;
+    private readonly apiKey: string;
+    private readonly apiVersion: string;
+    private readonly timeout: number;
+
+    /** Azure Document Intelligence 드라이버를 설정으로 초기화한다 */
+    constructor(cfg: OcrProviderConfig) {
+        this.endpoint = (cfg.endpoint ?? "").replace(/\/$/, "");
+        this.apiKey = cfg.apiKey ?? "";
+        this.apiVersion = cfg.apiVersion ?? "2023-07-31";
+        this.timeout = (cfg.timeoutSec ?? 60) * 1000;
+    }
+
+    /** 드라이버 이름을 반환한다 */
+    name() {
+        return "azure";
+    }
+    /** 지원하는 파일 형식 목록을 반환한다 */
+    supportedFormats() {
+        return [
+            "image/jpeg",
+            "image/png",
+            "image/tiff",
+            "image/bmp",
+            "application/pdf",
+        ];
+    }
+    /** 드라이버 리소스를 해제한다 */
+    async close() {}
+
+    /** 이미지 데이터를 Azure Document Intelligence API로 인식한다 */
+    async recognize(
+        data: Buffer,
+        opts: RecognizeOptions,
+    ): Promise<RawOcrResult> {
+        const start = Date.now();
+        const url = `${this.endpoint}/documentintelligence/documentModels/prebuilt-read:analyze?api-version=${this.apiVersion}`;
+
+        // 1단계: 분석 요청
+        const submitResp = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Ocp-Apim-Subscription-Key": this.apiKey,
+                "Content-Type": opts.mimeType || "application/octet-stream",
+            },
+            body: data,
+            signal: AbortSignal.timeout(this.timeout),
+        });
+
+        if (!submitResp.ok && submitResp.status !== 202) {
+            const text = await submitResp.text();
+            throw new Error(
+                `Azure DI submit error ${submitResp.status}: ${text}`,
+            );
+        }
+
+        const operationLocation =
+            submitResp.headers.get("Operation-Location") ??
+            submitResp.headers.get("operation-location") ??
+            "";
+
+        if (!operationLocation) {
+            throw new Error("Azure DI: no Operation-Location header");
+        }
+
+        // 2단계: 폴링
+        const pollTimeout = Date.now() + this.timeout;
+        let resultJson: any;
+
+        while (Date.now() < pollTimeout) {
+            await new Promise((r) => setTimeout(r, 1500));
+
+            const pollResp = await fetch(operationLocation, {
+                headers: { "Ocp-Apim-Subscription-Key": this.apiKey },
+                signal: AbortSignal.timeout(30_000),
+            });
+
+            if (!pollResp.ok) {
+                throw new Error(`Azure DI poll error ${pollResp.status}`);
+            }
+
+            const pollData = (await pollResp.json()) as any;
+            if (pollData.status === "succeeded") {
+                resultJson = pollData.analyzeResult;
+                break;
+            }
+            if (pollData.status === "failed") {
+                throw new Error(
+                    `Azure DI analysis failed: ${JSON.stringify(pollData.error)}`,
+                );
+            }
+        }
+
+        if (!resultJson) {
+            throw new Error("Azure DI: polling timeout");
+        }
+
+        return this.buildResult(resultJson, start);
+    }
+
+    /** Azure 분석 결과를 RawOcrResult로 변환한다 */
+    private buildResult(analyzeResult: any, startMs: number): RawOcrResult {
+        const DPI = 72; // Azure inch → pixel 변환에 사용하는 기본 DPI
+        const pages: RawOcrPage[] = [];
+        let fullText = analyzeResult.content ?? "";
+
+        for (const ap of analyzeResult.pages ?? []) {
+            const blocks: TextBlock[] = [];
+            const unit: string = ap.unit ?? "pixel";
+            const scale = unit === "inch" ? DPI : 1;
+
+            for (const word of ap.words ?? []) {
+                const polygon = word.polygon ?? [];
+                const xs = polygon
+                    .filter((_: number, i: number) => i % 2 === 0)
+                    .map((v: number) => v * scale);
+                const ys = polygon
+                    .filter((_: number, i: number) => i % 2 === 1)
+                    .map((v: number) => v * scale);
+                const left = xs.length ? Math.min(...xs) : 0;
+                const right = xs.length ? Math.max(...xs) : 0;
+                const top = ys.length ? Math.min(...ys) : 0;
+                const bottom = ys.length ? Math.max(...ys) : 0;
+
+                const slope =
+                    right - left > 0 && ys.length >= 2
+                        ? (ys[1] - ys[0]) / (right - left)
+                        : 0;
+
+                blocks.push({
+                    text: word.content ?? "",
+                    boundingBox: { top, left, right, bottom },
+                    centerX: (left + right) / 2,
+                    centerY: (top + bottom) / 2,
+                    slope,
+                    confidence: word.confidence ?? 0,
+                    lineBreak: false,
+                });
+            }
+
+            pages.push({
+                pageNum: ap.pageNumber ?? pages.length + 1,
+                width: (ap.width ?? 0) * scale,
+                height: (ap.height ?? 0) * scale,
+                text: (ap.lines ?? [])
+                    .map((l: any) => l.content ?? "")
+                    .join("\n"),
+                blocks,
+            });
+        }
+
+        const totalConf = pages.reduce(
+            (s, p) => s + p.blocks.reduce((ss, b) => ss + b.confidence, 0),
+            0,
+        );
+        const totalBlocks = pages.reduce((s, p) => s + p.blocks.length, 0);
+
+        return {
+            provider: "azure",
+            providerRaw: analyzeResult,
+            fullText,
+            processingMs: Date.now() - startMs,
+            processedAt: new Date().toISOString(),
+            confidence: totalBlocks > 0 ? totalConf / totalBlocks : 0,
+            pages,
+        };
+    }
+}

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

@@ -0,0 +1,155 @@
+/**
+ * Google Cloud Vision OCR 드라이버
+ * DOCUMENT_TEXT_DETECTION API 사용
+ */
+
+import type {
+    OcrDriver,
+    OcrProviderConfig,
+    RawOcrResult,
+    RecognizeOptions,
+    TextBlock,
+    RawOcrPage,
+} from "../types/index.ts";
+
+export class GoogleDriver implements OcrDriver {
+    private readonly apiKey: string;
+    private readonly apiUrl: string;
+    private readonly timeout: number;
+
+    /** Google Cloud Vision 드라이버를 설정으로 초기화한다 */
+    constructor(cfg: OcrProviderConfig) {
+        this.apiKey = cfg.apiKey ?? "";
+        this.apiUrl =
+            cfg.apiUrl ??
+            `https://vision.googleapis.com/v1/images:annotate?key=${this.apiKey}`;
+        this.timeout = (cfg.timeoutSec ?? 30) * 1000;
+    }
+
+    /** 드라이버 이름을 반환한다 */
+    name() {
+        return "google";
+    }
+    /** 지원하는 파일 형식 목록을 반환한다 */
+    supportedFormats() {
+        return [
+            "image/jpeg",
+            "image/png",
+            "image/gif",
+            "image/bmp",
+            "image/webp",
+            "application/pdf",
+        ];
+    }
+    /** 드라이버 리소스를 해제한다 */
+    async close() {}
+
+    /** 이미지 데이터를 Google Vision API로 인식한다 */
+    async recognize(
+        data: Buffer,
+        opts: RecognizeOptions,
+    ): Promise<RawOcrResult> {
+        const start = Date.now();
+        const body = {
+            requests: [
+                {
+                    image: { content: data.toString("base64") },
+                    features: [{ type: "DOCUMENT_TEXT_DETECTION" }],
+                    imageContext: opts.languages?.length
+                        ? { languageHints: opts.languages }
+                        : undefined,
+                },
+            ],
+        };
+
+        const resp = await fetch(this.apiUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.timeout),
+        });
+
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`Google Vision API error ${resp.status}: ${text}`);
+        }
+
+        const json = (await resp.json()) as any;
+        const annotation = json.responses?.[0]?.fullTextAnnotation;
+        const fullText = annotation?.text ?? "";
+
+        // 페이지별 텍스트 블록 파싱
+        const gPages = annotation?.pages ?? [];
+        const resultPages: RawOcrPage[] = [];
+        let totalConf = 0;
+        let totalBlocks = 0;
+
+        for (let pi = 0; pi < gPages.length; pi++) {
+            const page = gPages[pi];
+            const blocks: TextBlock[] = [];
+            const pageTexts: string[] = [];
+            for (const block of page.blocks ?? []) {
+                for (const paragraph of block.paragraphs ?? []) {
+                    for (const word of paragraph.words ?? []) {
+                        const symbols = (word.symbols ?? [])
+                            .map((s: any) => s.text ?? "")
+                            .join("");
+                        const vertices = word.boundingBox?.vertices ?? [];
+                        const [tl, tr, br, bl] = [
+                            vertices[0] ?? {},
+                            vertices[1] ?? {},
+                            vertices[2] ?? {},
+                            vertices[3] ?? {},
+                        ];
+                        const top = Math.min(tl.y ?? 0, tr.y ?? 0);
+                        const bottom = Math.max(bl.y ?? 0, br.y ?? 0);
+                        const left = Math.min(tl.x ?? 0, bl.x ?? 0);
+                        const right = Math.max(tr.x ?? 0, br.x ?? 0);
+
+                        const conf = word.confidence ?? 0;
+                        const slope =
+                            right - left > 0
+                                ? ((tr.y ?? 0) - (tl.y ?? 0)) / (right - left)
+                                : 0;
+
+                        blocks.push({
+                            text: symbols,
+                            boundingBox: { top, left, right, bottom },
+                            centerX: (left + right) / 2,
+                            centerY: (top + bottom) / 2,
+                            slope,
+                            confidence: conf,
+                            lineBreak: false,
+                        });
+                        pageTexts.push(symbols);
+                    }
+                }
+            }
+
+            totalConf += blocks.reduce((s, b) => s + b.confidence, 0);
+            totalBlocks += blocks.length;
+
+            resultPages.push({
+                pageNum: pi + 1,
+                width: page.width ?? 0,
+                height: page.height ?? 0,
+                text: pageTexts.join(" "),
+                blocks,
+            });
+        }
+
+        const avgConf = totalBlocks > 0 ? totalConf / totalBlocks : 0;
+
+        const result: RawOcrResult = {
+            provider: "google",
+            providerRaw: json,
+            fullText,
+            processingMs: Date.now() - start,
+            processedAt: new Date().toISOString(),
+            confidence: avgConf,
+            pages: resultPages,
+        };
+
+        return result;
+    }
+}

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

@@ -0,0 +1,80 @@
+/**
+ * OCR 드라이버 팩토리 + 재시도 + 파일 크기 검증
+ */
+
+import type {
+    OcrDriver,
+    OcrProviderConfig,
+    RawOcrResult,
+    RecognizeOptions,
+    RetryConfig,
+} from "../types/index.ts";
+import { OcrError, ERR_FILE_TOO_LARGE } from "../errors.ts";
+import { GoogleDriver } from "./google.ts";
+import { NaverDriver } from "./naver.ts";
+import { AwsDriver } from "./aws.ts";
+import { AzureDriver } from "./azure.ts";
+import { UpstageDriver } from "./upstage.ts";
+import { TesseractDriver } from "./tesseract.ts";
+
+const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50MB
+
+/** 프로바이더 설정에 따라 OCR 드라이버 인스턴스를 생성한다 */
+export function createOcrDriver(cfg: OcrProviderConfig): OcrDriver {
+    switch (cfg.driver) {
+        case "google":
+            return new GoogleDriver(cfg);
+        case "naver":
+            return new NaverDriver(cfg);
+        case "aws_textract":
+            return new AwsDriver(cfg);
+        case "azure":
+            return new AzureDriver(cfg);
+        case "upstage":
+            return new UpstageDriver(cfg);
+        case "tesseract":
+            return new TesseractDriver(cfg);
+        default:
+            throw new Error(`Unsupported OCR driver: ${cfg.driver}`);
+    }
+}
+
+/** 재시도 정책에 따라 OCR 인식을 수행한다 */
+export async function retryRecognize(
+    driver: OcrDriver,
+    data: Buffer,
+    opts: RecognizeOptions,
+    cfg: RetryConfig,
+): Promise<RawOcrResult> {
+    const maxRetries = cfg.maxRetries > 0 ? cfg.maxRetries : 3;
+    const delay = cfg.retryDelayMs > 0 ? cfg.retryDelayMs : 1000;
+
+    let lastErr: Error | undefined;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        if (attempt > 0) {
+            console.log(
+                `[INFO] OCR API retry #${attempt} (driver=${driver.name()})`,
+            );
+            await new Promise((r) => setTimeout(r, delay));
+        }
+        try {
+            return await driver.recognize(data, opts);
+        } catch (err) {
+            lastErr = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    throw new Error(
+        `OCR API failed after ${maxRetries} retries: ${lastErr?.message}`,
+    );
+}
+
+/** 파일 크기가 제한을 초과하는지 검증한다 */
+export function validateFileSize(data: Buffer, limitMB: number): void {
+    const limit = limitMB > 0 ? limitMB * 1024 * 1024 : MAX_FILE_SIZE_BYTES;
+    if (data.length > limit) {
+        throw new OcrError(
+            `file size exceeds limit: ${data.length} bytes (limit ${limit} bytes)`,
+            ERR_FILE_TOO_LARGE,
+        );
+    }
+}