create-entity-app-server 0.0.3

package/src/app/plugins/oauth/types/index.ts

@@ -0,0 +1,52 @@
+/**
+ * OAuth 2.0 타입 정의
+ */
+
+export interface OAuthProviderConfig {
+    driver: string;
+    client_id: string;
+    client_secret: string;
+    redirect_url?: string;
+    scopes?: string[];
+    auth_url?: string;
+    token_url?: string;
+    user_info_url?: string;
+    email_field?: string;
+    name_field?: string;
+    pkce?: boolean;
+    /** Apple Sign-In 전용 */
+    apple_team_id?: string;
+    apple_key_id?: string;
+    apple_private_key?: string;
+}
+
+export interface OAuthConfig {
+    enabled: boolean;
+    state_secret?: string;
+    state_ttl_sec?: number;
+    success_redirect_url?: string;
+    failure_redirect_url?: string;
+    providers: OAuthProviderConfig[];
+}
+
+export interface OAuthUserInfo {
+    provider: string;
+    provider_id: string;
+    email: string;
+    name: string;
+    profile_image: string;
+    access_token: string;
+    refresh_token: string;
+    token_expires_at: string;
+}
+
+export interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    token_type?: string;
+    expires_in?: number;
+    id_token?: string;
+    scope?: string;
+    error?: string;
+    error_description?: string;
+}

package/src/app/plugins/oauth/upsert.ts

@@ -0,0 +1,162 @@
+/**
+ * account_oauth + account upsert 로직
+ *
+ * Go auth_handler.go upsertOAuthAccount 포팅.
+ *
+ * 전략:
+ *  1) account_oauth (provider + provider_id) 조회 → account_seq로 account 로드
+ *  2) account email 조회 → account_oauth 자동 연결
+ *  3) 둘 다 없으면 account + account_oauth 신규 생성
+ */
+
+import { entityServer, logger } from "@gateway/api";
+import type { OAuthUserInfo } from "./types/index.ts";
+
+interface AccountRow {
+    seq: number;
+    email?: string;
+    name?: string;
+    status?: string;
+    rbac_role?: string;
+    has_password?: boolean | number;
+    totp_enabled?: boolean;
+    totp_locked_until?: string;
+    license_seq?: number;
+    [key: string]: unknown;
+}
+
+interface OAuthRow {
+    seq: number;
+    account_seq: number;
+    provider: string;
+    provider_id: string;
+    status?: string;
+    [key: string]: unknown;
+}
+
+export type { AccountRow };
+
+async function getAccountBySeq(seq: number): Promise<AccountRow | null> {
+    try {
+        const res = await entityServer.get<AccountRow>("account", seq);
+        return res?.data ?? null;
+    } catch {
+        return null;
+    }
+}
+
+function createOAuthData(
+    accountSeq: number,
+    ui: OAuthUserInfo,
+): Record<string, unknown> {
+    const data: Record<string, unknown> = {
+        account_seq: accountSeq,
+        provider: ui.provider,
+        provider_id: ui.provider_id,
+        email: ui.email,
+        name: ui.name,
+        profile_image: ui.profile_image,
+        status: "active",
+        linked_at: "now()",
+    };
+    if (ui.access_token) data.access_token = ui.access_token;
+    if (ui.refresh_token) data.refresh_token = ui.refresh_token;
+    if (ui.token_expires_at) data.token_expires_at = ui.token_expires_at;
+    return data;
+}
+
+async function createAccountOAuth(
+    accountSeq: number,
+    ui: OAuthUserInfo,
+): Promise<void> {
+    try {
+        await entityServer.submit(
+            "account_oauth",
+            createOAuthData(accountSeq, ui),
+        );
+    } catch (err) {
+        logger.warn(
+            { err, provider: ui.provider },
+            "OAuth: failed to create account_oauth",
+        );
+    }
+}
+
+async function syncNewUserProfile(ui: OAuthUserInfo): Promise<void> {
+    if (!ui.name && !ui.profile_image) return;
+    try {
+        const res = await entityServer.find<{ seq?: number }>("user", {
+            conditions: { email: ui.email },
+        });
+        const user = res?.data;
+        if (user?.seq) {
+            await entityServer.submit("user", {
+                seq: user.seq,
+                ...(ui.name ? { name: ui.name } : {}),
+                ...(ui.profile_image
+                    ? { profile_image: ui.profile_image }
+                    : {}),
+            });
+        }
+    } catch {
+        // user 엔티티가 없는 환경이면 무시
+    }
+}
+
+export async function upsertOAuthAccount(
+    ui: OAuthUserInfo,
+): Promise<AccountRow> {
+    // 1단계: account_oauth (provider + provider_id) 조회
+    try {
+        const r1 = await entityServer.list<OAuthRow>("account_oauth", {
+            conditions: {
+                provider: ui.provider,
+                provider_id: ui.provider_id,
+                status: "active",
+            },
+            limit: 1,
+        });
+        const items1 = (r1?.data?.items ?? []) as OAuthRow[];
+        if (items1.length > 0 && items1[0]!.account_seq) {
+            const account = await getAccountBySeq(items1[0]!.account_seq);
+            if (account) return account;
+        }
+    } catch {
+        // account_oauth 엔티티 없는 환경 무시
+    }
+
+    // 2단계: account email 조회
+    try {
+        const r2 = await entityServer.list<AccountRow>("account", {
+            conditions: { email: ui.email },
+            limit: 1,
+        });
+        const items2 = (r2?.data?.items ?? []) as AccountRow[];
+        if (items2.length > 0 && items2[0]!.seq) {
+            await createAccountOAuth(items2[0]!.seq, ui);
+            return items2[0]!;
+        }
+    } catch (err) {
+        logger.error({ err }, "OAuth: failed to find account by email");
+    }
+
+    // 3단계: 신규 account + account_oauth 생성
+    const newSeq = await entityServer.submit("account", {
+        email: ui.email,
+        status: "active",
+        rbac_role: "user",
+        has_password: false,
+    });
+
+    const newSeqNum = (newSeq as unknown as { seq?: number })?.seq ?? 0;
+    if (!newSeqNum) {
+        throw new Error("Failed to create account");
+    }
+
+    await createAccountOAuth(newSeqNum, ui);
+    void syncNewUserProfile(ui);
+
+    const created = await getAccountBySeq(newSeqNum);
+    if (!created) throw new Error("Failed to fetch created account");
+    return created;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * CacheManager — SHA-256 기반 OCR 결과 캐싱
+ */
+
+import { createHash } from "node:crypto";
+import type { OcrResult, OcrCacheConfig } from "./types/index.ts";
+
+export class CacheManager {
+    private readonly cache = new Map<
+        string,
+        { data: OcrResult; expireAt: number }
+    >();
+    private readonly ttlMs: number;
+
+    /** OCR 캐시를 TTL 설정으로 초기화한다 */
+    constructor(cfg: OcrCacheConfig) {
+        this.ttlMs = (cfg.ttlHours > 0 ? cfg.ttlHours : 168) * 3600 * 1000;
+    }
+
+    /** 캐시 키 생성: "ocr:{sha256(provider:docType:fileHash)}" */
+    cacheKey(fileHash: string, provider: string, docType: string): string {
+        const raw = `${provider}:${docType}:${fileHash}`;
+        const h = createHash("sha256").update(raw).digest("hex");
+        return `ocr:${h}`;
+    }
+
+    /** 캐시에서 OcrResult 조회 */
+    get(key: string): OcrResult | null {
+        const entry = this.cache.get(key);
+        if (!entry) return null;
+        if (Date.now() > entry.expireAt) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.data;
+    }
+
+    /** OcrResult를 캐시에 저장 */
+    set(key: string, result: OcrResult): void {
+        this.cache.set(key, {
+            data: result,
+            expireAt: Date.now() + this.ttlMs,
+        });
+    }
+}
+
+/** 파일 데이터의 SHA-256 해시 */
+export function computeFileHash(data: Buffer): string {
+    return createHash("sha256").update(data).digest("hex");
+}

package/src/app/plugins/ocr/config.example.json

@@ -0,0 +1,103 @@
+{
+    "enabled": false,
+    "default_provider": "naver",
+    "providers": {
+        "google": {
+            "driver": "google",
+            "api_key": "${OCR_GOOGLE_API_KEY}",
+            "endpoint": "https://vision.googleapis.com/v1/images:annotate",
+            "supported_formats": [
+                "image/jpeg",
+                "image/png",
+                "image/gif",
+                "image/webp",
+                "image/bmp",
+                "application/pdf"
+            ],
+            "max_file_size": 20971520,
+            "timeout": 30000
+        },
+        "naver": {
+            "driver": "naver",
+            "api_key": "${OCR_NAVER_SECRET}",
+            "endpoint": "${OCR_NAVER_INVOKE_URL}",
+            "supported_formats": [
+                "image/jpeg",
+                "image/png",
+                "image/gif",
+                "image/bmp",
+                "image/tiff",
+                "application/pdf"
+            ],
+            "max_file_size": 20971520,
+            "timeout": 30000
+        },
+        "aws_textract": {
+            "driver": "aws_textract",
+            "api_key": "${OCR_AWS_ACCESS_KEY}",
+            "api_secret": "${OCR_AWS_SECRET_KEY}",
+            "region": "${OCR_AWS_REGION}",
+            "supported_formats": ["image/jpeg", "image/png", "application/pdf"],
+            "max_file_size": 10485760,
+            "timeout": 30000
+        },
+        "azure": {
+            "driver": "azure",
+            "api_key": "${OCR_AZURE_KEY}",
+            "endpoint": "${OCR_AZURE_ENDPOINT}",
+            "supported_formats": [
+                "image/jpeg",
+                "image/png",
+                "image/bmp",
+                "image/tiff",
+                "application/pdf"
+            ],
+            "max_file_size": 52428800,
+            "timeout": 60000
+        },
+        "upstage": {
+            "driver": "upstage",
+            "api_key": "${OCR_UPSTAGE_API_KEY}",
+            "endpoint": "https://api.upstage.ai/v1/document-ai/ocr",
+            "supported_formats": ["image/jpeg", "image/png", "application/pdf"],
+            "max_file_size": 20971520,
+            "timeout": 30000
+        },
+        "tesseract": {
+            "driver": "tesseract",
+            "supported_formats": [
+                "image/jpeg",
+                "image/png",
+                "image/gif",
+                "image/bmp",
+                "image/tiff"
+            ],
+            "max_file_size": 52428800,
+            "timeout": 60000
+        }
+    },
+    "cache": {
+        "enabled": true,
+        "ttl": 3600
+    },
+    "quota": {
+        "daily_limit": 1000,
+        "monthly_limit": 20000,
+        "warn_percent": 80
+    },
+    "dispatch": {
+        "max_queue_size": 100,
+        "concurrency": 3,
+        "tick_interval": 200
+    },
+    "parsing": {
+        "confidence_threshold": 0.6,
+        "llm_fallback": true,
+        "llm_confidence_threshold": 0.85,
+        "template_dir": "configs/ocr-templates"
+    },
+    "retry": {
+        "max_retries": 2,
+        "retry_delay": 1000
+    }
+}

package/src/app/plugins/ocr/config.json

@@ -0,0 +1,110 @@
+{
+    "_comment": "OCR(문자 인식) 플러그인 — Google Vision·Naver CLOVA·AWS Textract·Azure·Upstage·Tesseract 멀티 프로바이더 지원",
+    "enabled": false,
+    "default_provider": "naver",
+    "providers": {
+        "google": {
+            "driver": "google",
+            "api_key": "${OCR_GOOGLE_API_KEY}",
+            "endpoint": "https://vision.googleapis.com/v1/images:annotate",
+            "supported_formats": [
+                "image/jpeg",
+                "image/png",
+                "image/gif",
+                "image/webp",
+                "image/bmp",
+                "application/pdf"
+            ],
+            "max_file_size": 20971520,
+            "timeout": 30000
+        },
+        "naver": {
+            "driver": "naver",
+            "api_key": "${OCR_NAVER_SECRET}",
+            "endpoint": "${OCR_NAVER_INVOKE_URL}",
+            "supported_formats": [
+                "image/jpeg",
+                "image/png",
+                "image/gif",
+                "image/bmp",
+                "image/tiff",
+                "application/pdf"
+            ],
+            "max_file_size": 20971520,
+            "timeout": 30000
+        },
+        "aws_textract": {
+            "driver": "aws_textract",
+            "api_key": "${OCR_AWS_ACCESS_KEY}",
+            "api_secret": "${OCR_AWS_SECRET_KEY}",
+            "region": "${OCR_AWS_REGION}",
+            "supported_formats": ["image/jpeg", "image/png", "application/pdf"],
+            "max_file_size": 10485760,
+            "timeout": 30000
+        },
+        "azure": {
+            "driver": "azure",
+            "api_key": "${OCR_AZURE_KEY}",
+            "endpoint": "${OCR_AZURE_ENDPOINT}",
+            "supported_formats": [
+                "image/jpeg",
+                "image/png",
+                "image/bmp",
+                "image/tiff",
+                "application/pdf"
+            ],
+            "max_file_size": 52428800,
+            "timeout": 60000
+        },
+        "upstage": {
+            "driver": "upstage",
+            "api_key": "${OCR_UPSTAGE_API_KEY}",
+            "endpoint": "https://api.upstage.ai/v1/document-ai/ocr",
+            "supported_formats": ["image/jpeg", "image/png", "application/pdf"],
+            "max_file_size": 20971520,
+            "timeout": 30000
+        },
+        "tesseract": {
+            "driver": "tesseract",
+            "supported_formats": [
+                "image/jpeg",
+                "image/png",
+                "image/gif",
+                "image/bmp",
+                "image/tiff"
+            ],
+            "max_file_size": 52428800,
+            "timeout": 60000
+        }
+    },
+    "cache": {
+        "enabled": true,
+        "ttl": 3600
+    },
+    "quota": {
+        "daily_limit": 1000,
+        "monthly_limit": 20000,
+        "warn_percent": 80
+    },
+    "dispatch": {
+        "max_queue_size": 100,
+        "concurrency": 3,
+        "tick_interval": 200
+    },
+    "parsing": {
+        "confidence_threshold": 0.6,
+        "template_dir": "configs/ocr-templates"
+    },
+    "llm_fallback": {
+        "enabled": true,
+        "provider": "",
+        "confidence_threshold": 0.85,
+        "prompt_dir": "configs/ocr-prompts"
+    },
+    "retry": {
+        "max_retries": 2,
+        "retry_delay": 1000
+    },
+    "deploy": true,
+    "minify": true
+}

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

@@ -0,0 +1,126 @@
+/**
+ * OCR 설정 로더
+ * 플러그인 디렉토리의 config.json 로드 + 환경변수 치환
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+    OcrConfig,
+    OcrProviderConfig,
+    OcrLlmFallbackConfig,
+} from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const DEFAULT_CONFIG: Omit<OcrConfig, "providers"> = {
+    enabled: false,
+    default: "",
+    workers: 2,
+    queueSize: 50,
+    maxFileSizeMB: 20,
+    supportedFormats: [
+        "image/jpeg",
+        "image/png",
+        "image/webp",
+        "image/tiff",
+        "application/pdf",
+    ],
+    cache: { enabled: false, ttlHours: 168 },
+    quota: { dailyLimit: 0, monthlyLimit: 0, notify: [] },
+    parsing: {
+        templateDir: join(__dirname, "templates"),
+        confidenceThreshold: 0.6,
+    },
+    llmFallback: {
+        enabled: false,
+        provider: "",
+        confidenceThreshold: 0.85,
+        promptDir: join(__dirname, "templates", "prompts"),
+    },
+};
+
+/** 문자열 내 ${ENV} 패턴을 환경변수 값으로 치환한다 */
+function expandEnv(val: string | undefined): string {
+    if (!val) return "";
+    return val.replace(/\$\{([^}]+)\}/g, (_, key) => process.env[key] ?? "");
+}
+
+/** 프로바이더 설정의 모든 환경변수를 치환한다 */
+function expandProviderEnv(p: OcrProviderConfig): OcrProviderConfig {
+    return {
+        ...p,
+        apiKey: expandEnv(p.apiKey),
+        apiUrl: expandEnv(p.apiUrl),
+        apiEndpoint: expandEnv(p.apiEndpoint),
+        secretKey: expandEnv(p.secretKey),
+        credentialsPath: expandEnv(p.credentialsPath),
+        accessKeyId: expandEnv(p.accessKeyId),
+        secretAccessKey: expandEnv(p.secretAccessKey),
+        region: expandEnv(p.region),
+        endpoint: expandEnv(p.endpoint),
+        dataPath: expandEnv(p.dataPath),
+    };
+}
+
+/** OCR 설정 파일을 로드하고 환경변수를 치환하여 반환한다 */
+export function loadOcrConfig(): OcrConfig | null {
+    const filePath = join(__dirname, "config.json");
+    if (!existsSync(filePath)) return null;
+
+    const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+    const cfg: OcrConfig = { ...DEFAULT_CONFIG, ...raw };
+
+    // JSON에서 snake_case → camelCase 변환
+    cfg.maxFileSizeMB = raw.max_file_size_mb ?? cfg.maxFileSizeMB;
+    cfg.queueSize = raw.queue_size ?? cfg.queueSize;
+    cfg.supportedFormats = raw.supported_formats ?? cfg.supportedFormats;
+    if (raw.cache) {
+        cfg.cache = {
+            enabled: raw.cache.enabled ?? false,
+            ttlHours: raw.cache.ttl_hours ?? 168,
+        };
+    }
+    if (raw.quota) {
+        cfg.quota = {
+            dailyLimit: raw.quota.daily_limit ?? 0,
+            monthlyLimit: raw.quota.monthly_limit ?? 0,
+            notify: raw.quota.notify ?? [],
+        };
+    }
+    if (raw.parsing) {
+        cfg.parsing = {
+            templateDir:
+                raw.parsing.template_dir ?? join(__dirname, "templates"),
+            confidenceThreshold: raw.parsing.confidence_threshold ?? 0.6,
+        };
+    }
+    if (raw.llm_fallback) {
+        const lf = raw.llm_fallback as OcrLlmFallbackConfig &
+            Record<string, unknown>;
+        cfg.llmFallback = {
+            enabled: (lf.enabled ?? false) as boolean,
+            provider: (lf.provider ?? "") as string,
+            confidenceThreshold: (lf.confidence_threshold ?? 0.85) as number,
+            promptDir: (lf.prompt_dir ??
+                join(__dirname, "templates", "prompts")) as string,
+        };
+    }
+
+    if (!cfg.enabled) return null;
+
+    // 환경변수 치환
+    cfg.providers = (cfg.providers ?? []).map(expandProviderEnv);
+
+    // 기본값 보정
+    if (!cfg.default && cfg.providers.length === 1) {
+        cfg.default = cfg.providers[0].driver;
+    }
+
+    if (cfg.providers.length === 0) {
+        throw new Error("ocr config: at least one provider must be configured");
+    }
+
+    return cfg;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * 8방향 상수 + 공간 방향 판정
+ * PHP 레거시 코드의 8방향 상수 계승
+ */
+
+import type { ProcessedItem } from "./types/index.ts";
+
+// 겹침 없는 방향 (A 영역과 B 영역이 완전히 분리)
+export const DIRECTION_RIGHT = "RIGHT";
+export const DIRECTION_LEFT = "LEFT";
+export const DIRECTION_DOWN = "DOWN";
+export const DIRECTION_UP = "UP";
+
+// 겹침 허용 방향 (중심점 비교만)
+export const DIRECTION_RIGHT_OVERLAP = "RIGHT_OVERLAP";
+export const DIRECTION_LEFT_OVERLAP = "LEFT_OVERLAP";
+export const DIRECTION_DOWN_OVERLAP = "DOWN_OVERLAP";
+export const DIRECTION_UP_OVERLAP = "UP_OVERLAP";
+
+/**
+ * item이 base에 대해 direction 조건을 만족하는지 확인합니다.
+ */
+export function checkDirectionMatch(
+    item: ProcessedItem,
+    base: ProcessedItem,
+    direction: string,
+): boolean {
+    switch (direction) {
+        case DIRECTION_RIGHT:
+            return item.left >= base.right;
+        case DIRECTION_LEFT:
+            return item.right <= base.left;
+        case DIRECTION_DOWN:
+            return item.top >= base.bottom;
+        case DIRECTION_UP:
+            return item.bottom <= base.top;
+        case DIRECTION_RIGHT_OVERLAP:
+            return item.centerX > base.centerX;
+        case DIRECTION_LEFT_OVERLAP:
+            return item.centerX < base.centerX;
+        case DIRECTION_DOWN_OVERLAP:
+            return item.centerY > base.centerY;
+        case DIRECTION_UP_OVERLAP:
+            return item.centerY < base.centerY;
+        default:
+            return false;
+    }
+}