create-entity-app-server 0.0.3

package/src/app/plugins/taxinvoice/service.ts

@@ -0,0 +1,439 @@
+/**
+ * 전자세금계산서 서비스
+ *
+ * 비즈니스 로직 오케스트레이터:
+ * - RegistIssue: 등록 + 즉시 발행
+ * - Register: 임시 저장
+ * - Issue: 저장 건 발행
+ * - CancelIssue: 발행 취소
+ * - Dispatch Loop: 비동기 큐 처리 (setInterval)
+ * - Sync Loop: 프로바이더 상태 동기화
+ */
+
+import { logger } from "@gateway/api";
+import type {
+    TaxInvoiceConfig,
+    TaxInvoiceDriver,
+    TaxInvoiceQuerier,
+    InvoiceRequest,
+    IssueOptions,
+    IssueResult,
+    PendingTaxInvoiceLog,
+    Party,
+} from "./types/index.ts";
+
+/** 값을 문자열로 변환한다 */
+function toString(v: unknown): string {
+    if (v == null) return "";
+    return String(v);
+}
+
+/** 값을 숫자로 변환한다 */
+function toNumber(v: unknown): number {
+    if (v == null) return 0;
+    const n = Number(v);
+    return Number.isNaN(n) ? 0 : n;
+}
+
+export class TaxInvoiceService {
+    private cfg: TaxInvoiceConfig;
+    private drivers: Map<string, TaxInvoiceDriver>;
+    private querier!: TaxInvoiceQuerier;
+
+    private dispatchTimer: ReturnType<typeof setInterval> | null = null;
+    private syncTimer: ReturnType<typeof setInterval> | null = null;
+    private running = false;
+
+    /** TaxInvoiceService를 설정과 클라이언트로 초기화한다 */
+    constructor(cfg: TaxInvoiceConfig, drivers: Map<string, TaxInvoiceDriver>) {
+        this.cfg = cfg;
+        this.drivers = drivers;
+    }
+
+    /** 엔티티 어댑터를 주입한다 */
+    setQuerier(querier: TaxInvoiceQuerier): void {
+        this.querier = querier;
+    }
+
+    // ────────── Service Operations ──────────
+
+    /** 프로바이더 드라이버를 반환한다 */
+    getDriver(provider?: string): TaxInvoiceDriver {
+        const name = provider || this.cfg.default;
+        const driver = this.drivers.get(name);
+        if (!driver) throw new Error(`taxinvoice: unknown provider "${name}"`);
+        return driver;
+    }
+
+    /**
+     * 세금계산서 등록 + 즉시 발행
+     */
+    async registIssue(req: InvoiceRequest): Promise<IssueResult> {
+        if (!req.provider) req.provider = this.cfg.default;
+        const driver = this.getDriver(req.provider);
+
+        const invoicerSeq = await this.resolveParty(req.invoicer);
+        const invoiceeSeq = await this.resolveParty(req.invoicee);
+
+        const providerState = await driver.registIssue(req);
+
+        const seq = await this.persistInvoice(
+            req,
+            invoicerSeq,
+            invoiceeSeq,
+            providerState,
+        );
+        this.logAction(seq, "regist_issue", req.provider, req.mgt_key, "");
+
+        // NTS 자동 전송
+        if (this.cfg.nts?.auto_send) {
+            try {
+                await this.querier.submitTaxInvoiceLog({
+                    tax_invoice_seq: seq,
+                    log_type: "issue",
+                    provider: req.provider,
+                    mgt_key: req.mgt_key,
+                });
+            } catch (err) {
+                logger.warn(
+                    `[taxinvoice] failed to queue NTS send for seq=${seq}: ${err}`,
+                );
+            }
+        }
+
+        return {
+            seq,
+            mgt_key: req.mgt_key,
+            state: providerState.state,
+            nts_state: providerState.nts_state,
+            nts_confirm_num: providerState.nts_confirm_num,
+        };
+    }
+
+    /**
+     * 세금계산서 임시 저장
+     */
+    async register(req: InvoiceRequest): Promise<IssueResult> {
+        if (!req.provider) req.provider = this.cfg.default;
+        const driver = this.getDriver(req.provider);
+
+        const invoicerSeq = await this.resolveParty(req.invoicer);
+        const invoiceeSeq = await this.resolveParty(req.invoicee);
+
+        const providerState = await driver.register(req);
+
+        const seq = await this.persistInvoice(
+            req,
+            invoicerSeq,
+            invoiceeSeq,
+            providerState,
+        );
+        this.logAction(seq, "register", req.provider, req.mgt_key, "");
+
+        return {
+            seq,
+            mgt_key: req.mgt_key,
+            state: providerState.state,
+            nts_state: providerState.nts_state,
+        };
+    }
+
+    /**
+     * 임시 저장된 세금계산서 발행
+     */
+    async issue(seq: number, opts: IssueOptions): Promise<IssueResult> {
+        const invoice = await this.querier.getTaxInvoice(seq);
+        const provider = toString(invoice.provider);
+        const mgtKey = toString(invoice.mgt_key);
+        const driver = this.getDriver(provider);
+
+        const providerState = await driver.issue(mgtKey, opts);
+
+        await this.querier.updateTaxInvoice(seq, {
+            state: providerState.state,
+            nts_state: providerState.nts_state,
+        });
+
+        this.logAction(seq, "issue", provider, mgtKey, opts.memo ?? "");
+
+        return {
+            seq,
+            mgt_key: mgtKey,
+            state: providerState.state,
+            nts_state: providerState.nts_state,
+        };
+    }
+
+    /**
+     * 발행 취소
+     */
+    async cancelIssue(seq: number, memo: string): Promise<void> {
+        const invoice = await this.querier.getTaxInvoice(seq);
+        const provider = toString(invoice.provider);
+        const mgtKey = toString(invoice.mgt_key);
+        const driver = this.getDriver(provider);
+
+        await driver.cancelIssue(mgtKey, memo);
+
+        await this.querier.updateTaxInvoice(seq, { state: "issue_cancelled" });
+        this.logAction(seq, "cancel_issue", provider, mgtKey, memo);
+    }
+
+    /**
+     * 상태 조회
+     */
+    async getState(seq: number): Promise<Record<string, unknown>> {
+        const invoice = await this.querier.getTaxInvoice(seq);
+        const provider = toString(invoice.provider);
+        const mgtKey = toString(invoice.mgt_key);
+        const driver = this.getDriver(provider);
+
+        const providerState = await driver.getState(mgtKey);
+
+        // DB도 동기화
+        const updates: Record<string, unknown> = {};
+        if (
+            providerState.state &&
+            providerState.state !== toString(invoice.state)
+        ) {
+            updates.state = providerState.state;
+        }
+        if (
+            providerState.nts_state &&
+            providerState.nts_state !== toString(invoice.nts_state)
+        ) {
+            updates.nts_state = providerState.nts_state;
+        }
+        if (
+            providerState.nts_confirm_num &&
+            providerState.nts_confirm_num !== toString(invoice.nts_confirm_num)
+        ) {
+            updates.nts_confirm_num = providerState.nts_confirm_num;
+        }
+        if (Object.keys(updates).length > 0) {
+            await this.querier.updateTaxInvoice(seq, updates);
+        }
+
+        return {
+            seq,
+            mgt_key: mgtKey,
+            provider,
+            state: providerState.state,
+            nts_state: providerState.nts_state,
+            nts_confirm_num: providerState.nts_confirm_num,
+        };
+    }
+
+    // ────────── Dispatch Loop ──────────
+
+    /** 디스패치 및 동기화 루프를 시작한다 */
+    async start(): Promise<void> {
+        this.running = true;
+        const intervalMs = (this.cfg.dispatch_interval_sec || 10) * 1000;
+
+        this.dispatchTimer = setInterval(() => {
+            if (this.running)
+                this.dispatch().catch((e) =>
+                    logger.error(e, "[taxinvoice] dispatch error"),
+                );
+        }, intervalMs);
+
+        // Sync Loop
+        if (this.cfg.sync?.enabled && this.cfg.sync.interval_sec > 0) {
+            const syncMs = this.cfg.sync.interval_sec * 1000;
+            this.syncTimer = setInterval(() => {
+                if (this.running)
+                    this.syncStates().catch((e) =>
+                        logger.error(e, "[taxinvoice] sync error"),
+                    );
+            }, syncMs);
+        }
+
+        logger.info(
+            `[taxinvoice] service started: dispatch_interval=${this.cfg.dispatch_interval_sec}s`,
+        );
+    }
+
+    /** 디스패치 및 동기화 루프를 정지한다 */
+    stop(): void {
+        this.running = false;
+        if (this.dispatchTimer) {
+            clearInterval(this.dispatchTimer);
+            this.dispatchTimer = null;
+        }
+        if (this.syncTimer) {
+            clearInterval(this.syncTimer);
+            this.syncTimer = null;
+        }
+        logger.info("[taxinvoice] service stopped");
+    }
+
+    /** 대기 큐의 로그를 처리한다 */
+    private async dispatch(): Promise<void> {
+        const logs = await this.querier.claimPendingTaxInvoiceLogs(
+            this.cfg.queue_size,
+        );
+        if (logs.length === 0) return;
+
+        // Promise.allSettled로 동시 처리 (Go의 goroutine worker pool 대체)
+        const results = await Promise.allSettled(
+            logs.map((log) => this.processOne(log)),
+        );
+        for (const r of results) {
+            if (r.status === "rejected") {
+                logger.error(
+                    r.reason,
+                    "[taxinvoice] processOne unhandled error",
+                );
+            }
+        }
+    }
+
+    /** 단일 로그 항목을 처리한다 */
+    private async processOne(logEntry: PendingTaxInvoiceLog): Promise<void> {
+        try {
+            const driver = this.getDriver(logEntry.provider);
+
+            switch (logEntry.log_type) {
+                case "issue":
+                    await driver.sendToNTS(logEntry.mgt_key);
+                    break;
+                default:
+                    throw new Error(`unknown log_type: ${logEntry.log_type}`);
+            }
+
+            await this.querier.updateTaxInvoiceLogStatus(
+                logEntry.log_seq,
+                "completed",
+            );
+
+            await this.querier.updateTaxInvoice(logEntry.tax_invoice_seq, {
+                nts_state: "sending",
+            });
+        } catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            if (logEntry.retry_count < this.cfg.max_retries) {
+                await this.querier.updateTaxInvoiceLogStatus(
+                    logEntry.log_seq,
+                    "pending",
+                    { error: errMsg },
+                );
+            } else {
+                await this.querier.updateTaxInvoiceLogStatus(
+                    logEntry.log_seq,
+                    "failed",
+                    { error: errMsg },
+                );
+            }
+        }
+    }
+
+    // ────────── Sync Loop ──────────
+
+    /** 프로바이더 상태를 동기화한다 */
+    private async syncStates(): Promise<void> {
+        for (const [providerName, driver] of this.drivers) {
+            if (providerName === "esero") continue; // esero는 직접 제출이므로 sync 불필요
+
+            try {
+                const invoices =
+                    await this.querier.listTaxInvoicesForSync(providerName);
+                for (const inv of invoices) {
+                    const mgtKey = toString(inv.mgt_key);
+                    const seq = toNumber(inv.seq);
+
+                    try {
+                        const ps = await driver.getState(mgtKey);
+                        const updates: Record<string, unknown> = {};
+
+                        if (
+                            ps.nts_state &&
+                            ps.nts_state !== toString(inv.nts_state)
+                        ) {
+                            updates.nts_state = ps.nts_state;
+                        }
+                        if (
+                            ps.nts_confirm_num &&
+                            ps.nts_confirm_num !== toString(inv.nts_confirm_num)
+                        ) {
+                            updates.nts_confirm_num = ps.nts_confirm_num;
+                        }
+                        if (ps.state && ps.state !== toString(inv.state)) {
+                            updates.state = ps.state;
+                        }
+                        if (Object.keys(updates).length > 0) {
+                            await this.querier.updateTaxInvoice(seq, updates);
+                            this.logAction(
+                                seq,
+                                "state_sync",
+                                providerName,
+                                mgtKey,
+                                "",
+                            );
+                        }
+                    } catch (err) {
+                        logger.warn(
+                            `[taxinvoice] sync: GetState error for ${providerName} mgt_key=${mgtKey}: ${err}`,
+                        );
+                    }
+                }
+            } catch (err) {
+                logger.warn(
+                    `[taxinvoice] sync: list error for ${providerName}: ${err}`,
+                );
+            }
+        }
+    }
+
+    // ────────── Helpers ──────────
+
+    /** 거래처를 조회하거나 생성한다 */
+    private async resolveParty(party: Party): Promise<number> {
+        if (!party) throw new Error("party is null");
+        return this.querier.findOrCreateParty(party);
+    }
+
+    /** 세금계산서를 DB에 저장한다 */
+    private async persistInvoice(
+        req: InvoiceRequest,
+        invoicerSeq: number,
+        invoiceeSeq: number,
+        ps: {
+            state: string;
+            nts_state: string;
+            nts_confirm_num: string;
+        } | null,
+    ): Promise<number> {
+        req.invoicer_seq = invoicerSeq;
+        req.invoicee_seq = invoiceeSeq;
+        if (ps) {
+            req.state = ps.state;
+            req.nts_state = ps.nts_state;
+            req.nts_confirm_num = ps.nts_confirm_num;
+        }
+        return this.querier.submitTaxInvoice(req);
+    }
+
+    /** 세금계산서 액션 로그를 기록한다 */
+    private logAction(
+        seq: number,
+        logType: string,
+        provider: string,
+        mgtKey: string,
+        memo: string,
+    ): void {
+        this.querier
+            .submitTaxInvoiceLog({
+                tax_invoice_seq: seq,
+                log_type: logType,
+                provider,
+                mgt_key: mgtKey,
+                memo,
+            })
+            .catch((err) => {
+                logger.warn(
+                    `[taxinvoice] logAction: failed to write log for seq=${seq} type=${logType}: ${err}`,
+                );
+            });
+    }
+}

package/src/app/plugins/taxinvoice/types/client.ts

@@ -0,0 +1,57 @@
+import type {
+    InvoiceRequest,
+    IssueOptions,
+    ProviderState,
+    ProviderLog,
+    ProviderSummary,
+    ListFilter,
+} from "./invoice.ts";
+import type { PendingTaxInvoiceLog } from "./queue.ts";
+import type { Party } from "./invoice.ts";
+
+export interface TaxInvoiceDriver {
+    name(): string;
+    registIssue(req: InvoiceRequest): Promise<ProviderState>;
+    register(req: InvoiceRequest): Promise<ProviderState>;
+    issue(docKey: string, opts: IssueOptions): Promise<ProviderState>;
+    cancelIssue(docKey: string, memo: string): Promise<void>;
+    registReverseRequest(req: InvoiceRequest): Promise<ProviderState>;
+    reverseRequest(docKey: string, memo: string): Promise<void>;
+    cancelReverseRequest(docKey: string, memo: string): Promise<void>;
+    refuse(docKey: string, memo: string): Promise<void>;
+    delete(docKey: string): Promise<void>;
+    getState(docKey: string): Promise<ProviderState>;
+    getDetail(docKey: string): Promise<unknown>;
+    getLogs(docKey: string): Promise<ProviderLog[]>;
+    list(filter: ListFilter): Promise<ProviderSummary[]>;
+    sendEmail(docKey: string, emails: string[]): Promise<void>;
+    sendSMS(docKey: string, to: string): Promise<void>;
+    sendToNTS(docKey: string): Promise<void>;
+}
+
+export interface TaxInvoiceQuerier {
+    submitTaxInvoiceLog(
+        logEntry: Partial<PendingTaxInvoiceLog>,
+    ): Promise<number>;
+    claimPendingTaxInvoiceLogs(limit: number): Promise<PendingTaxInvoiceLog[]>;
+    updateTaxInvoiceLogStatus(
+        logSeq: number,
+        status: string,
+        result?: unknown,
+    ): Promise<void>;
+    resetStaleTaxInvoiceLogs(staleMinutes: number): Promise<number>;
+    submitTaxInvoice(invoice: InvoiceRequest): Promise<number>;
+    updateTaxInvoice(
+        seq: number,
+        fields: Record<string, unknown>,
+    ): Promise<void>;
+    getTaxInvoice(seq: number): Promise<Record<string, unknown>>;
+    getTaxInvoiceByMgtKey(
+        provider: string,
+        mgtKey: string,
+    ): Promise<Record<string, unknown>>;
+    listTaxInvoicesForSync(
+        provider: string,
+    ): Promise<Record<string, unknown>[]>;
+    findOrCreateParty(party: Party): Promise<number>;
+}

package/src/app/plugins/taxinvoice/types/config.ts

@@ -0,0 +1,42 @@
+export interface TaxInvoiceConfig {
+    enabled?: boolean;
+    default: string;
+    workers: number;
+    queue_size: number;
+    dispatch_interval_sec: number;
+    max_retries: number;
+    providers: Record<string, TaxInvoiceProviderConfig>;
+    nts: TaxInvoiceNTSConfig;
+    notify: string[];
+    sync: TaxInvoiceSyncConfig;
+}
+
+export interface TaxInvoiceProviderConfig {
+    driver: string; // "barobill" | "popbill" | "bolta" | "smartbill" | "esero"
+    cert_key?: string;
+    corp_num?: string;
+    user_id?: string;
+    link_id?: string;
+    secret_key?: string;
+    api_key?: string;
+    customer_key?: string;
+    cert_path?: string;
+    cert_pass?: string;
+    api_endpoint: string;
+    timeout_sec?: number;
+}
+
+export interface TaxInvoiceNTSConfig {
+    auto_send: boolean;
+    taxation_option: number;
+    taxation_add_tax_allow: number;
+    tax_exemption_option: number;
+    tax_exemption_add_tax_allow: number;
+}
+
+export interface TaxInvoiceSyncConfig {
+    enabled: boolean;
+    interval_sec: number;
+    state_sync_interval_min: number;
+    max_list_days: number;
+}

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

@@ -0,0 +1,4 @@
+export * from "./config.ts";
+export * from "./invoice.ts";
+export * from "./queue.ts";
+export * from "./client.ts";

package/src/app/plugins/taxinvoice/types/invoice.ts

@@ -0,0 +1,128 @@
+export interface Party {
+    corp_num: string;
+    corp_name: string;
+    tax_reg_id?: string;
+    ceo_name?: string;
+    addr?: string;
+    biz_type?: string;
+    biz_class?: string;
+    contact_name?: string;
+    tel?: string;
+    hp?: string;
+    email?: string;
+}
+
+export interface Item {
+    item_seq: number;
+    purchase_date?: string;
+    name?: string;
+    information?: string;
+    quantity?: number;
+    unit_price?: number;
+    amount: number;
+    tax: number;
+    description?: string;
+}
+
+export interface InvoiceRequest {
+    mgt_key: string;
+    provider?: string;
+    write_date: string;
+    issue_direction: string; // "forward" | "reverse" | "trustee"
+    tax_type: string; // "taxation" | "zero" | "exempt"
+    purpose_type: number;
+    tax_invoice_type: number;
+    amount_total: number;
+    tax_total: number;
+    total_amount: number;
+    cash?: number;
+    chk_bill?: number;
+    note?: number;
+    credit?: number;
+    remark1?: string;
+    remark2?: string;
+    remark3?: string;
+    invoicer: Party;
+    invoicee: Party;
+    broker?: Party;
+    items: Item[];
+    force_issue?: boolean;
+    send_sms?: boolean;
+    send_email?: boolean;
+    extra?: Record<string, unknown>;
+    invoicer_seq?: number;
+    invoicee_seq?: number;
+    broker_seq?: number;
+    state?: string;
+    nts_state?: string;
+    nts_confirm_num?: string;
+}
+
+export interface IssueOptions {
+    force_issue?: boolean;
+    memo?: string;
+    send_sms?: boolean;
+    send_email?: boolean;
+}
+
+export interface ProviderState {
+    state: string;
+    nts_state: string;
+    nts_confirm_num: string;
+    raw?: unknown;
+}
+
+export interface ProviderLog {
+    log_type: string;
+    log_time: string;
+    description?: string;
+    memo?: string;
+    raw?: unknown;
+}
+
+export interface ProviderSummary {
+    doc_key: string;
+    mgt_key: string;
+    state: string;
+    nts_state: string;
+    write_date: string;
+    invoicer_name: string;
+    invoicee_name: string;
+    amount_total: number;
+    tax_total: number;
+    nts_confirm_num?: string;
+}
+
+export interface IssueResult {
+    seq: number;
+    mgt_key: string;
+    provider_doc_key?: string;
+    state: string;
+    nts_state: string;
+    nts_confirm_num?: string;
+    message?: string;
+}
+
+export interface InvoiceState {
+    mgt_key: string;
+    state: string;
+    nts_state: string;
+    nts_confirm_num?: string;
+}
+
+export interface ListFilter {
+    direction?: string;
+    start_date: string;
+    end_date: string;
+    state?: string;
+    nts_state?: string;
+    page: number;
+    limit: number;
+}
+
+export interface PagedResult {
+    items: ProviderSummary[];
+    total_count: number;
+    page: number;
+    limit: number;
+}

package/src/app/plugins/taxinvoice/types/queue.ts

@@ -0,0 +1,22 @@
+import type { InvoiceRequest, IssueOptions } from "./invoice.ts";
+
+export interface TaxInvoiceJob {
+    provider: string;
+    action: string;
+    mgt_key: string;
+    request?: InvoiceRequest;
+    options?: IssueOptions;
+    memo?: string;
+    ref_entity?: string;
+    ref_seq?: number;
+}
+
+export interface PendingTaxInvoiceLog {
+    log_seq: number;
+    tax_invoice_seq: number;
+    log_type: string;
+    provider: string;
+    mgt_key: string;
+    memo: string;
+    retry_count: number;
+}

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

@@ -0,0 +1,9 @@
+{
+    "enabled": true,
+    "entity": "vessel_kr_entry",
+    "apiKey": "N5Z27Cv+zStCwMXI7xlsDYMBIA1NNWUIFMqQxq2u9XAgUEHzvrTQBwNEpWo5WpmWz7i8ylRmR1lFc2xesrYY0w==",
+    "prtAgCodes": ["011", "021"],
+    "syncDays": 1,
+    "deploy": true,
+    "minify": false
+}