create-entity-app-server 0.0.3

package/src/app/plugins/ocr/entity-adapter.ts

@@ -0,0 +1,198 @@
+/**
+ * OcrEntityAdapter — Entity Server를 통한 OCR 결과/사용량 영속화
+ */
+
+import type {
+    OcrEntityStore,
+    OcrResultRecord,
+    OcrResult,
+    OcrResultFilter,
+    OcrUsageRecord,
+} from "./types/index.ts";
+import { OcrError, ERR_RESULT_NOT_FOUND } from "./errors.ts";
+
+interface EntityServerClient {
+    submit(
+        entity: string,
+        data: unknown,
+    ): Promise<{ ok: boolean; seq?: number }>;
+    get<T>(
+        entity: string,
+        seq: number | string,
+    ): Promise<{ ok: boolean; data: T }>;
+    list(
+        entity: string,
+        params: unknown,
+    ): Promise<{ ok: boolean; data: unknown }>;
+    delete(entity: string, seq: number | string): Promise<{ ok: boolean }>;
+}
+
+export class OcrEntityAdapter implements OcrEntityStore {
+    /** Entity Server 클라이언트로 어댑터를 초기화한다 */
+    constructor(private readonly es: EntityServerClient) {}
+
+    /** OCR 결과 레코드를 생성한다 */
+    async createResult(record: OcrResultRecord): Promise<string> {
+        const resp = await this.es.submit("ocr_result", {
+            ocr_id: record.ocrId,
+            file_seq: record.fileSeq ?? 0,
+            file_hash: record.fileHash,
+            provider: record.provider,
+            doc_type: record.docType,
+            state: record.state,
+            ref_table: record.refTable ?? "",
+            ref_seq: record.refSeq ?? 0,
+        });
+        return record.ocrId; // ocr_id가 PK
+    }
+
+    /** OCR 결과 상태를 갱신한다 */
+    async updateResultState(
+        id: string,
+        state: string,
+        result: OcrResult | null,
+        errMsg: string,
+    ): Promise<void> {
+        const data: Record<string, unknown> = {
+            ocr_id: id,
+            state,
+            error_message: errMsg,
+        };
+        if (result?.raw) {
+            data.text = result.raw.fullText;
+            data.pages = JSON.stringify(result.raw.pages);
+            data.confidence = result.raw.confidence;
+            data.processing_ms = result.raw.processingMs;
+            data.provider_raw = JSON.stringify(result.raw.providerRaw);
+        }
+        if (result?.parsed) {
+            data.parsed = JSON.stringify(result.parsed);
+            data.parse_method = result.parseMethod;
+        }
+        await this.es.submit("ocr_result", data);
+    }
+
+    /** OCR 결과를 ID로 조회한다 */
+    async getResult(id: string): Promise<OcrResultRecord | null> {
+        try {
+            const resp = await this.es.list("ocr_result", {
+                filter_ocr_id: id,
+                limit: 1,
+            } as any);
+            const items = (resp.data as any)?.items ?? [];
+            if (items.length === 0) return null;
+            return this.mapResultRecord(items[0]);
+        } catch {
+            return null;
+        }
+    }
+
+    /** OCR 결과 목록을 필터 조건으로 조회한다 */
+    async listResults(
+        filter: OcrResultFilter,
+    ): Promise<{ items: OcrResultRecord[]; total: number }> {
+        const params: Record<string, unknown> = {
+            limit: filter.limit ?? 20,
+            offset: filter.offset ?? 0,
+        };
+        if (filter.provider) params.filter_provider = filter.provider;
+        if (filter.docType) params.filter_doc_type = filter.docType;
+        if (filter.state) params.filter_state = filter.state;
+        if (filter.refTable) params.filter_ref_table = filter.refTable;
+        if (filter.refSeq) params.filter_ref_seq = filter.refSeq;
+
+        const resp = await this.es.list("ocr_result", params as any);
+        const data = resp.data as any;
+        const items = (data?.items ?? []).map((r: any) =>
+            this.mapResultRecord(r),
+        );
+        return { items, total: data?.count ?? items.length };
+    }
+
+    /** OCR 결과를 삭제한다 */
+    async deleteResult(id: string): Promise<void> {
+        // ocr_id로 검색 후 seq 기반 삭제
+        const record = await this.getResult(id);
+        if (!record)
+            throw new OcrError("OCR result not found", ERR_RESULT_NOT_FOUND);
+        // seq를 사용해서 삭제 (entity-server는 seq 기반 삭제)
+        const resp = await this.es.list("ocr_result", {
+            filter_ocr_id: id,
+            limit: 1,
+        } as any);
+        const items = (resp.data as any)?.items ?? [];
+        if (items.length > 0 && items[0].seq) {
+            await this.es.delete("ocr_result", items[0].seq);
+        }
+    }
+
+    /** OCR 사용량 카운터를 증가시킨다 */
+    async incrementUsage(record: OcrUsageRecord): Promise<void> {
+        await this.es.submit("ocr_usage", {
+            usage_date: record.usageDate,
+            provider: record.provider,
+            doc_type: record.docType,
+            request_count: record.requestCount,
+            page_count: record.pageCount,
+        });
+    }
+
+    /** 특정 날짜의 일일 사용량을 조회한다 */
+    async getDailyQuotaUsage(date: string): Promise<number> {
+        try {
+            const resp = await this.es.list("ocr_usage", {
+                filter_usage_date: date,
+                limit: 1000,
+            } as any);
+            const items = (resp.data as any)?.items ?? [];
+            return items.reduce(
+                (sum: number, r: any) => sum + (r.request_count ?? 0),
+                0,
+            );
+        } catch {
+            return 0;
+        }
+    }
+
+    /** 특정 월의 월간 사용량을 조회한다 */
+    async getMonthlyQuotaUsage(month: string): Promise<number> {
+        try {
+            const resp = await this.es.list("ocr_usage", {
+                filter_usage_date_gte: `${month}-01`,
+                filter_usage_date_lte: `${month}-31`,
+                limit: 1000,
+            } as any);
+            const items = (resp.data as any)?.items ?? [];
+            return items.reduce(
+                (sum: number, r: any) => sum + (r.request_count ?? 0),
+                0,
+            );
+        } catch {
+            return 0;
+        }
+    }
+
+    /** Entity Server 응답을 OcrResultRecord로 변환한다 */
+    private mapResultRecord(r: any): OcrResultRecord {
+        return {
+            ocrId: r.ocr_id ?? "",
+            fileSeq: r.file_seq,
+            fileHash: r.file_hash ?? "",
+            provider: r.provider ?? "",
+            docType: r.doc_type ?? "",
+            state: r.state ?? "",
+            refTable: r.ref_table,
+            refSeq: r.ref_seq,
+            text: r.text,
+            pages: r.pages,
+            parsed: r.parsed,
+            confidence: r.confidence,
+            processingMs: r.processing_ms,
+            providerRaw: r.provider_raw,
+            errorMessage: r.error_message,
+            parseMethod: r.parse_method,
+            createdAt: r.created_at,
+            updatedAt: r.updated_at,
+        };
+    }
+}

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

@@ -0,0 +1,42 @@
+/**
+ * OCR 커스텀 에러 타입 + HTTP 상태코드 매핑
+ */
+
+export class OcrError extends Error {
+    /** OCR 에러를 메시지와 코드로 생성한다 */
+    constructor(
+        message: string,
+        public readonly code: string,
+    ) {
+        super(message);
+        this.name = "OcrError";
+    }
+}
+
+export const ERR_FILE_TOO_LARGE = "FILE_TOO_LARGE";
+export const ERR_UNSUPPORTED_FORMAT = "UNSUPPORTED_FORMAT";
+export const ERR_QUOTA_EXCEEDED = "QUOTA_EXCEEDED";
+export const ERR_DRIVER_FAILED = "DRIVER_FAILED";
+export const ERR_TEMPLATE_NOT_FOUND = "TEMPLATE_NOT_FOUND";
+export const ERR_INVALID_DOC_TYPE = "INVALID_DOC_TYPE";
+export const ERR_RESULT_NOT_FOUND = "RESULT_NOT_FOUND";
+export const ERR_ASYNC_QUEUE_FULL = "ASYNC_QUEUE_FULL";
+
+/** OCR 에러 코드에 따른 HTTP 상태코드를 반환한다 */
+export function httpStatusFromError(err: unknown): number {
+    if (!(err instanceof OcrError)) return 500;
+    switch (err.code) {
+        case ERR_FILE_TOO_LARGE:
+        case ERR_UNSUPPORTED_FORMAT:
+        case ERR_INVALID_DOC_TYPE:
+            return 400;
+        case ERR_RESULT_NOT_FOUND:
+            return 404;
+        case ERR_QUOTA_EXCEEDED:
+            return 429;
+        case ERR_ASYNC_QUEUE_FULL:
+            return 503;
+        default:
+            return 500;
+    }
+}

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

@@ -0,0 +1,250 @@
+/**
+ * OCR 핸들러 구현
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail } from "@gateway/api";
+import { httpStatusFromError } from "./errors.ts";
+import type { RecognizeOptions, OcrResultFilter } from "./types/index.ts";
+
+/** OCR 서비스가 활성화되어 있는지 확인한다 */
+const ensureSvc = (req: FastifyRequest, reply: FastifyReply) => {
+    if (!req.server.ocrService) {
+        reply.status(503).send(fail("OCR plugin not enabled"));
+        return null;
+    }
+    return req.server.ocrService;
+};
+
+// ─── 인식 ───
+
+/** OCR 인식을 요청한다 */
+export async function recognize(request: FastifyRequest, reply: FastifyReply) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const { data, mimeType } = await readOcrFile(request);
+    const body = (request.body ?? {}) as Record<string, any>;
+    const opts: RecognizeOptions = {
+        mimeType,
+        docType: body.doc_type ?? body.docType ?? "",
+        languages: body.lang ? [].concat(body.lang) : undefined,
+    };
+
+    try {
+        const result = await svc.recognize(data, opts);
+        return ok(result);
+    } catch (err) {
+        const status = httpStatusFromError(err);
+        return reply
+            .status(status)
+            .send(fail(err instanceof Error ? err.message : String(err)));
+    }
+}
+
+/** 비동기 OCR 인식을 요청한다 */
+export async function recognizeAsync(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const { data, mimeType } = await readOcrFile(request);
+    const body = (request.body ?? {}) as Record<string, any>;
+    const opts: RecognizeOptions = {
+        mimeType,
+        docType: body.doc_type ?? body.docType ?? "",
+        languages: body.lang ? [].concat(body.lang) : undefined,
+    };
+
+    try {
+        const jobId = await svc.recognizeAsync(data, opts);
+        return ok({ job_id: jobId });
+    } catch (err) {
+        const status = httpStatusFromError(err);
+        return reply
+            .status(status)
+            .send(fail(err instanceof Error ? err.message : String(err)));
+    }
+}
+
+/** 문서 타입 지정 OCR 인식을 요청한다 */
+export async function recognizeByDocType(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const { docType } = request.params as { docType: string };
+    const { data, mimeType } = await readOcrFile(request);
+    const opts: RecognizeOptions = { mimeType, docType };
+
+    try {
+        const result = await svc.recognize(data, opts);
+        return ok(result);
+    } catch (err) {
+        const status = httpStatusFromError(err);
+        return reply
+            .status(status)
+            .send(fail(err instanceof Error ? err.message : String(err)));
+    }
+}
+
+// ─── 결과 조회 ───
+
+/** OCR 결과 목록을 조회한다 */
+export async function listResults(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const q = request.query as Record<string, string>;
+    const filter: OcrResultFilter = {
+        provider: q.provider,
+        docType: q.doc_type,
+        state: q.state,
+        refTable: q.ref_table,
+        refSeq: q.ref_seq ? parseInt(q.ref_seq) : undefined,
+        limit: parseInt(q.limit ?? "20"),
+        offset: parseInt(q.offset ?? "0"),
+    };
+
+    try {
+        const { items, total } = await svc.listResults(filter);
+        return ok({ items, total });
+    } catch (err) {
+        return reply
+            .status(500)
+            .send(fail(err instanceof Error ? err.message : String(err)));
+    }
+}
+
+/** OCR 결과를 ID로 조회한다 */
+export async function getResult(request: FastifyRequest, reply: FastifyReply) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const { id } = request.params as { id: string };
+    try {
+        const record = await svc.getResult(id);
+        if (!record)
+            return reply.status(404).send(fail("OCR result not found"));
+        return ok(record);
+    } catch (err) {
+        const status = httpStatusFromError(err);
+        return reply
+            .status(status)
+            .send(fail(err instanceof Error ? err.message : String(err)));
+    }
+}
+
+/** OCR 결과의 텍스트만 조회한다 */
+export async function getResultText(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const { id } = request.params as { id: string };
+    try {
+        const record = await svc.getResult(id);
+        if (!record)
+            return reply.status(404).send(fail("OCR result not found"));
+        return ok({ text: record.text });
+    } catch (err) {
+        const status = httpStatusFromError(err);
+        return reply
+            .status(status)
+            .send(fail(err instanceof Error ? err.message : String(err)));
+    }
+}
+
+/** OCR 결과를 삭제한다 */
+export async function deleteResult(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const { id } = request.params as { id: string };
+    try {
+        await svc.deleteResult(id);
+        return ok({ deleted: id });
+    } catch (err) {
+        const status = httpStatusFromError(err);
+        return reply
+            .status(status)
+            .send(fail(err instanceof Error ? err.message : String(err)));
+    }
+}
+
+/** OCR 할당량 정보를 반환한다 */
+export async function getQuota(request: FastifyRequest, reply: FastifyReply) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    try {
+        const status = await svc.getQuotaStatus();
+        return ok(status);
+    } catch (err) {
+        return reply
+            .status(500)
+            .send(fail(err instanceof Error ? err.message : String(err)));
+    }
+}
+
+// ─── 파일 읽기 헬퍼 ───
+
+/** 요청에서 OCR 파일 데이터를 읽는다 */
+async function readOcrFile(
+    request: FastifyRequest,
+): Promise<{ data: Buffer; mimeType: string }> {
+    const file = await (request as any).file?.();
+    if (file) {
+        const chunks: Buffer[] = [];
+        for await (const chunk of file.file) {
+            chunks.push(chunk);
+        }
+        const data = Buffer.concat(chunks);
+        const mimeType = file.mimetype || detectMimeType(data);
+        return { data, mimeType };
+    }
+
+    const body = request.body;
+    if (Buffer.isBuffer(body)) {
+        const mimeType =
+            request.headers["content-type"] || detectMimeType(body);
+        return { data: body, mimeType };
+    }
+
+    throw new Error("file required (multipart 'file' field or raw body)");
+}
+
+/** 파일 매직 바이트로 MIME 타입을 감지한다 */
+function detectMimeType(data: Buffer): string {
+    if (data.length < 4) return "application/octet-stream";
+    if (data[0] === 0xff && data[1] === 0xd8) return "image/jpeg";
+    if (
+        data[0] === 0x89 &&
+        data[1] === 0x50 &&
+        data[2] === 0x4e &&
+        data[3] === 0x47
+    )
+        return "image/png";
+    if (
+        data[0] === 0x25 &&
+        data[1] === 0x50 &&
+        data[2] === 0x44 &&
+        data[3] === 0x46
+    )
+        return "application/pdf";
+    if (data[0] === 0x47 && data[1] === 0x49 && data[2] === 0x46)
+        return "image/gif";
+    return "application/octet-stream";
+}

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

@@ -0,0 +1,68 @@
+/**
+ * OCR 플러그인 Fastify 플러그인
+ */
+
+import { fileURLToPath } from "url";
+import path from "path";
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { ensurePluginEntities } from "@gateway/api";
+import { loadOcrConfig } from "./config.ts";
+import { OcrService } from "./service.ts";
+import { OcrEntityAdapter } from "./entity-adapter.ts";
+
+declare module "fastify" {
+    interface FastifyInstance {
+        ocrService: OcrService | null;
+    }
+}
+
+/** OCR 플러그인을 등록한다 */
+export default fp(async (app: FastifyInstance) => {
+    const cfg = loadOcrConfig();
+    if (!cfg) {
+        app.decorate("ocrService", null);
+        return;
+    }
+
+    // 필요한 엔티티가 서버에 없으면 자동 생성
+    const pluginDir = path.dirname(fileURLToPath(import.meta.url));
+    await ensurePluginEntities(pluginDir).catch((err) =>
+        app.log.warn(err, "OCR: entity setup failed, continuing"),
+    );
+
+    // Entity Server 클라이언트 가져오기 (auth 플러그인에서 데코레이션됨)
+    const entityServer = (app as any).entityServer ?? null;
+    const entityStore = entityServer
+        ? new OcrEntityAdapter(entityServer)
+        : null;
+
+    // LLM 서비스 연동 (llmService가 있으면 simpleChat 어댑터 생성)
+    const llmService = (app as any).llmService ?? null;
+    let llmAdapter = null;
+    if (llmService && cfg.llmFallback.enabled && cfg.llmFallback.provider) {
+        llmAdapter = {
+            async simpleChat(
+                providerName: string,
+                system: string,
+                user: string,
+            ): Promise<string> {
+                return llmService.chat(providerName, system, user);
+            },
+        };
+    }
+
+    const service = new OcrService(cfg, entityStore, llmAdapter, entityServer);
+    service.start();
+
+    app.decorate("ocrService", service);
+
+    app.addHook("onClose", async () => {
+        service.stop();
+        console.log("OCR plugin stopped");
+    });
+
+    console.log(
+        `OCR plugin enabled — default: ${cfg.default}, providers: ${cfg.providers.map((p) => p.driver).join(", ")}`,
+    );
+});