create-entity-app-server 0.0.3

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

@@ -0,0 +1,130 @@
+/**
+ * DispatchWorker — 비동기 OCR 큐 + 워커 (Node.js setInterval 패턴)
+ * Go goroutine+channel 패턴을 Node.js 싱글 스레드용으로 변환
+ */
+
+import type {
+    DispatchJob,
+    RecognizeOptions,
+    OcrEntityStore,
+    OcrResult,
+} from "./types/index.ts";
+import { OcrError, ERR_ASYNC_QUEUE_FULL } from "./errors.ts";
+
+export class DispatchWorker {
+    private readonly queue: DispatchJob[] = [];
+    private readonly queueSize: number;
+    private readonly concurrency: number;
+    private running = 0;
+    private timer: ReturnType<typeof setInterval> | null = null;
+    private stopped = false;
+
+    // OcrService의 recognize 함수를 받아 사용
+    private recognizeFn:
+        | ((data: Buffer, opts: RecognizeOptions) => Promise<OcrResult>)
+        | null = null;
+    private entityStore: OcrEntityStore | null = null;
+
+    /** 비동기 OCR 큐를 지정된 큐 크기와 동시성으로 초기화한다 */
+    constructor(queueSize: number, concurrency: number) {
+        this.queueSize = queueSize > 0 ? queueSize : 50;
+        this.concurrency = concurrency > 0 ? concurrency : 2;
+    }
+
+    /** recognize 함수 및 entityStore 주입 */
+    init(
+        recognizeFn: (
+            data: Buffer,
+            opts: RecognizeOptions,
+        ) => Promise<OcrResult>,
+        entityStore: OcrEntityStore | null,
+    ): void {
+        this.recognizeFn = recognizeFn;
+        this.entityStore = entityStore;
+    }
+
+    /** 워커 시작 (200ms 간격 폴링) */
+    start(): void {
+        this.stopped = false;
+        this.timer = setInterval(() => this.tick(), 200);
+        console.log(
+            `[INFO] OCR dispatch workers started (concurrency=${this.concurrency})`,
+        );
+    }
+
+    /** 워커 종료 */
+    stop(): void {
+        this.stopped = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+
+    /** 작업 큐에 추가 → 작업 ID 반환 */
+    submit(data: Buffer, opts: RecognizeOptions): string {
+        if (this.queue.length >= this.queueSize) {
+            throw new OcrError(
+                `async processing queue is full: queue size ${this.queueSize}`,
+                ERR_ASYNC_QUEUE_FULL,
+            );
+        }
+        const id = crypto.randomUUID();
+        this.queue.push({
+            id,
+            data,
+            opts,
+            createdAt: new Date().toISOString(),
+        });
+        return id;
+    }
+
+    /** 큐에서 작업을 가져와 처리한다 */
+    private tick(): void {
+        while (
+            this.running < this.concurrency &&
+            this.queue.length > 0 &&
+            !this.stopped
+        ) {
+            const job = this.queue.shift()!;
+            this.running++;
+            this.processJob(job).finally(() => {
+                this.running--;
+            });
+        }
+    }
+
+    /** 단일 OCR 작업을 실행하고 결과를 저장한다 */
+    private async processJob(job: DispatchJob): Promise<void> {
+        if (!this.recognizeFn) return;
+
+        try {
+            // 상태: processing
+            if (this.entityStore) {
+                await this.entityStore
+                    .updateResultState(job.id, "processing", null, "")
+                    .catch(() => {});
+            }
+
+            const result = await this.recognizeFn(job.data, job.opts);
+
+            // 상태: completed
+            if (this.entityStore) {
+                await this.entityStore
+                    .updateResultState(job.id, "completed", result, "")
+                    .catch(() => {});
+            }
+            console.log(
+                `[INFO] OCR async job ${job.id} completed (parse=${result.parseMethod} conf=${result.parseConfidence.toFixed(2)})`,
+            );
+        } catch (err) {
+            console.log(`[ERROR] OCR async job ${job.id} failed: ${err}`);
+            if (this.entityStore) {
+                const msg = err instanceof Error ? err.message : String(err);
+                await this.entityStore
+                    .updateResultState(job.id, "failed", null, msg)
+                    .catch(() => {});
+            }
+        }
+    }
+}

package/src/app/plugins/ocr/docs/README.md

@@ -0,0 +1,125 @@
+# OCR 플러그인
+
+Google Vision, Naver CLOVA, AWS Textract, Azure AI, Upstage, Tesseract를 지원하는 광학 문자 인식(OCR) 플러그인입니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [환경변수](#환경변수)
+- [API 요약](#api-요약)
+- [API 상세](api.md)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+| 항목            | 내용                                                                   |
+| --------------- | ---------------------------------------------------------------------- |
+| 지원 프로바이더 | Google Vision, Naver CLOVA, AWS Textract, Azure AI, Upstage, Tesseract |
+| 지원 형식       | 이미지 (JPEG, PNG, WebP, TIFF), PDF                                    |
+| 비동기 처리     | 대용량 파일은 비동기 큐 방식으로 처리                                  |
+| 캐싱            | 파일 해시 기반 중복 요청 방지                                          |
+| 쿼터 관리       | 프로바이더별 일별/월별 사용량 제한                                     |
+| LLM 폴백        | OCR 후 LLM으로 결과 정제 가능                                          |
+
+> 기본 비활성화(`enabled: false`)입니다. 최소 1개 프로바이더 API 키 설정 후 활성화하세요.
+
+---
+
+## 설정
+
+`config.json` 핵심 구조:
+
+```json
+{
+    "enabled": false,
+    "default": "naver",
+    "providers": {
+        "naver": {
+            "driver": "naver",
+            "api_url": "${NAVER_OCR_API_URL}",
+            "secret_key": "${NAVER_OCR_SECRET_KEY}",
+            "max_file_size_mb": 10,
+            "supported_formats": ["image/jpeg", "image/png", "application/pdf"]
+        },
+        "google": {
+            "driver": "google",
+            "api_key": "${GOOGLE_VISION_API_KEY}",
+            "max_file_size_mb": 20
+        },
+        "tesseract": {
+            "driver": "tesseract",
+            "lang": "kor+eng"
+        }
+    }
+}
+```
+
+### 설정 항목
+
+| 항목                           | 설명               |
+| ------------------------------ | ------------------ |
+| `default`                      | 기본 프로바이더 키 |
+| `providers.*.driver`           | 프로바이더 식별자  |
+| `providers.*.api_key`          | 프로바이더 API 키  |
+| `providers.*.max_file_size_mb` | 최대 파일 크기(MB) |
+
+---
+
+## 환경변수
+
+```env
+# Naver CLOVA OCR
+NAVER_OCR_API_URL=https://...clova.ai/custom/v1/...
+NAVER_OCR_SECRET_KEY=...
+
+# Google Vision
+GOOGLE_VISION_API_KEY=AIza...
+
+# AWS Textract
+AWS_REGION=ap-northeast-2
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+
+# Azure AI Vision
+AZURE_OCR_ENDPOINT=https://...cognitiveservices.azure.com
+AZURE_OCR_KEY=...
+
+# Upstage
+UPSTAGE_API_KEY=up_...
+```
+
+Tesseract는 별도 API 키 없이 서버에 `tesseract-ocr` 패키지 설치 필요.
+
+---
+
+## API 요약
+
+기본 경로: `/api/v1/ocr`
+
+| 메서드   | 경로                | 인증        | 설명                               |
+| -------- | ------------------- | ----------- | ---------------------------------- |
+| `POST`   | `/recognize`        | 로그인 필요 | 동기 OCR 인식                      |
+| `POST`   | `/recognize/async`  | 로그인 필요 | 비동기 OCR 인식                    |
+| `POST`   | `/:docType`         | 로그인 필요 | 문서 유형별 인식 (명함, 신분증 등) |
+| `GET`    | `/results`          | 로그인 필요 | 인식 결과 목록                     |
+| `GET`    | `/results/:id`      | 로그인 필요 | 인식 결과 단건 조회                |
+| `GET`    | `/results/:id/text` | 로그인 필요 | 텍스트만 반환                      |
+| `DELETE` | `/results/:id`      | 로그인 필요 | 인식 결과 삭제                     |
+| `GET`    | `/quota`            | 로그인 필요 | 사용량 및 쿼터 조회                |
+
+> 전체 요청/응답 형식은 [api.md](api.md)를 참조하세요.
+
+---
+
+## 운영 팁
+
+- 동기 (`/recognize`)는 빠른 응답이 필요한 경우, 비동기 (`/recognize/async`)는 대용량 PDF에 사용
+- Naver CLOVA는 한국어 인식 정확도가 높음, Google Vision은 다국어에 강함
+- 파일 해시 캐싱으로 동일 파일 재인식 시 API 호출 없이 캐시 결과 반환
+- Tesseract는 오프라인(무료)이지만 정확도가 상업용 대비 낮음 — 개발/테스트용으로 권장
+- LLM 폴백 활성화 시 OCR 결과를 LLM으로 재가공하여 구조화된 JSON 출력 가능

package/src/app/plugins/ocr/docs/api.md

@@ -0,0 +1,159 @@
+# OCR API 레퍼런스
+
+기본 경로: `/api/v1/ocr`
+
+---
+
+## 엔드포인트 목록
+
+| 메서드   | 경로                                        | 인증        | 설명                |
+| -------- | ------------------------------------------- | ----------- | ------------------- |
+| `POST`   | [`/recognize`](#post-recognize)             | 로그인 필요 | 동기 OCR 인식       |
+| `POST`   | [`/recognize/async`](#post-recognizeasync)  | 로그인 필요 | 비동기 OCR 인식     |
+| `POST`   | [`/:docType`](#post-doctype)                | 로그인 필요 | 문서 유형별 인식    |
+| `GET`    | [`/results`](#get-results)                  | 로그인 필요 | 인식 결과 목록      |
+| `GET`    | [`/results/:id`](#get-results-id)           | 로그인 필요 | 인식 결과 단건 조회 |
+| `GET`    | [`/results/:id/text`](#get-results-id-text) | 로그인 필요 | 텍스트만 반환       |
+| `DELETE` | [`/results/:id`](#delete-results-id)        | 로그인 필요 | 인식 결과 삭제      |
+| `GET`    | [`/quota`](#get-quota)                      | 로그인 필요 | 사용량 및 쿼터 조회 |
+
+---
+
+## POST /recognize
+
+파일을 업로드하여 즉시 OCR 결과를 반환합니다.
+
+**Content-Type:** `multipart/form-data`
+
+| 필드       | 타입   | 필수 | 설명                                  |
+| ---------- | ------ | ---- | ------------------------------------- |
+| `file`     | file   | ✅   | 인식할 이미지 또는 PDF                |
+| `provider` | string |      | 사용할 프로바이더 (기본값: `default`) |
+| `lang`     | string |      | 언어 힌트 (예: `ko`, `en`, `ko+en`)   |
+
+**응답:**
+
+```json
+{
+    "ok": true,
+    "data": {
+        "id": "ocr_uuid",
+        "text": "인식된 전체 텍스트...",
+        "provider": "naver",
+        "confidence": 0.97,
+        "created_at": "2026-03-22T06:00:00Z"
+    }
+}
+```
+
+---
+
+## POST /recognize/async
+
+대용량 파일을 비동기로 처리합니다. 요청 즉시 `id`를 반환하고, 완료 후 `GET /results/:id`로 조회합니다.
+
+**Content-Type:** `multipart/form-data` (`/recognize`와 동일)
+
+**응답:**
+
+```json
+{
+    "ok": true,
+    "data": {
+        "id": "ocr_uuid",
+        "status": "pending"
+    }
+}
+```
+
+**상태 값:**
+
+| 상태         | 설명         |
+| ------------ | ------------ |
+| `pending`    | 처리 대기 중 |
+| `processing` | 인식 진행 중 |
+| `done`       | 인식 완료    |
+| `failed`     | 인식 실패    |
+
+---
+
+## POST /:docType
+
+문서 유형에 맞는 파싱 파이프라인을 적용합니다. 반환 결과가 구조화된 JSON입니다.
+
+**docType 유효값:**
+
+| docType         | 설명   |
+| --------------- | ------ |
+| `business_card` | 명함   |
+| `id_card`       | 신분증 |
+| `invoice`       | 청구서 |
+| `receipt`       | 영수증 |
+
+**응답 예시 (명함):**
+
+```json
+{
+    "ok": true,
+    "data": {
+        "name": "홍길동",
+        "company": "엔티티 주식회사",
+        "position": "개발팀장",
+        "email": "hong@example.com",
+        "phone": "010-1234-5678"
+    }
+}
+```
+
+---
+
+## GET /results
+
+이전 인식 결과 목록을 조회합니다.
+
+| 파라미터   | 타입   | 설명                            |
+| ---------- | ------ | ------------------------------- |
+| `provider` | string | 프로바이더 필터                 |
+| `status`   | string | 상태 필터 (`done`, `failed` 등) |
+| `limit`    | number | 최대 결과 수 (기본 20)          |
+| `offset`   | number | 페이지 오프셋                   |
+
+---
+
+## GET /results/:id
+
+특정 인식 결과를 조회합니다.
+
+---
+
+## GET /results/:id/text
+
+인식된 텍스트만 `text/plain`으로 반환합니다.
+
+---
+
+## DELETE /results/:id
+
+인식 결과를 삭제합니다.
+
+---
+
+## GET /quota
+
+프로바이더별 사용량 및 남은 쿼터를 조회합니다.
+
+**응답 예시:**
+
+```json
+{
+    "ok": true,
+    "data": {
+        "naver": {
+            "used_today": 42,
+            "daily_limit": 1000,
+            "used_this_month": 850,
+            "monthly_limit": 10000
+        }
+    }
+}
+```

package/src/app/plugins/ocr/entities/ocr_result.json

@@ -0,0 +1,98 @@
+{
+    "name": "ocr_result",
+    "description": "OCR 처리 결과 저장. 비동기 작업 상태 추적 및 결과 재사용을 위한 캐시 역할.",
+    "fields": {
+        "ocr_id": {
+            "type": "varchar(36)",
+            "comment": "결과 고유 ID (UUID)",
+            "required": true,
+            "unique": true
+        },
+        "file_seq": {
+            "index": true,
+            "nullable": true,
+            "comment": "파일 seq (uploads 테이블 참조)",
+            "type": "bigint"
+        },
+        "file_hash": {
+            "index": true,
+            "comment": "파일 SHA-256 해시 (중복 인식 방지)",
+            "type": "varchar(64)",
+            "required": true
+        },
+        "provider": {
+            "index": true,
+            "comment": "사용된 OCR 드라이버 (google, naver, aws_textract, azure, upstage, tesseract)",
+            "type": "varchar(30)",
+            "required": true
+        },
+        "doc_type": {
+            "index": true,
+            "comment": "문서 유형 (general, business_reg, receipt, invoice, namecard, id_card, driver_license, facility_card, career_cert)",
+            "type": "varchar(30)",
+            "required": true
+        },
+        "state": {
+            "index": true,
+            "comment": "처리 상태 (pending, processing, completed, failed)",
+            "type": "varchar(20)",
+            "required": true,
+            "default": "pending"
+        },
+        "parse_method": {
+            "nullable": true,
+            "comment": "파싱 방법 (none, template, llm)",
+            "type": "varchar(20)"
+        },
+        "ref_table": {
+            "index": true,
+            "nullable": true,
+            "comment": "연관 테이블명"
+        },
+        "ref_seq": {
+            "index": true,
+            "nullable": true,
+            "comment": "연관 레코드 seq",
+            "type": "bigint"
+        },
+        "text": {
+            "nullable": true,
+            "comment": "OCR 추출 전체 텍스트",
+            "type": "text"
+        },
+        "pages": {
+            "nullable": true,
+            "comment": "페이지별 블록 데이터 (JSON)",
+            "type": "json"
+        },
+        "parsed": {
+            "nullable": true,
+            "comment": "파싱된 구조화 데이터 (JSON)",
+            "type": "json"
+        },
+        "confidence": {
+            "nullable": true,
+            "comment": "인식 신뢰도 (0.0~1.0)",
+            "type": "decimal(5,4)"
+        },
+        "processing_ms": {
+            "nullable": true,
+            "comment": "처리 시간 (밀리초)",
+            "type": "int"
+        },
+        "provider_raw": {
+            "nullable": true,
+            "comment": "프로바이더 원본 응답 (JSON)",
+            "type": "json"
+        },
+        "error_message": {
+            "nullable": true,
+            "comment": "처리 실패 시 오류 메시지"
+        },
+        "user_seq": {
+            "nullable": true,
+            "comment": "요청 사용자 seq"
+        }
+    },
+    "indexes": [["file_hash", "provider", "doc_type"]]
+}

package/src/app/plugins/ocr/entities/ocr_usage.json

@@ -0,0 +1,57 @@
+{
+    "name": "ocr_usage",
+    "description": "OCR API 일별 사용량 집계. 쿼터 모니터링 및 비용 추적용.",
+    "compress": true,
+    "read_only": true,
+    "fields": {
+        "usage_date": {
+            "index": true,
+            "comment": "사용 날짜 (YYYY-MM-DD)",
+            "type": "varchar(10)",
+            "required": true
+        },
+        "provider": {
+            "index": true,
+            "comment": "OCR 드라이버 이름",
+            "type": "varchar(30)",
+            "required": true
+        },
+        "doc_type": {
+            "index": true,
+            "comment": "문서 유형",
+            "type": "varchar(30)",
+            "required": true
+        },
+        "request_count": {
+            "comment": "총 요청 수",
+            "type": "int",
+            "default": 0
+        },
+        "page_count": {
+            "comment": "총 처리 페이지 수",
+            "type": "int",
+            "default": 0
+        },
+        "success_count": {
+            "comment": "성공 요청 수",
+            "type": "int",
+            "default": 0
+        },
+        "fail_count": {
+            "comment": "실패 요청 수",
+            "type": "int",
+            "default": 0
+        },
+        "total_ms": {
+            "comment": "총 처리 시간 합계 (ms)",
+            "type": "bigint",
+            "default": 0
+        },
+        "avg_confidence": {
+            "nullable": true,
+            "comment": "평균 신뢰도",
+            "type": "decimal(5,4)"
+        }
+    },
+    "indexes": [["usage_date", "provider", "doc_type"]]
+}