create-entity-app-server 0.0.3

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

@@ -0,0 +1,122 @@
+# 공휴일 플러그인 (Holidays)
+
+공공데이터포털에서 한국 공휴일 데이터를 자동으로 수집·갱신합니다. 법정 공휴일, 국경일, 24절기, 잡절을 포함합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [환경변수](#환경변수)
+- [API](#api)
+- [데이터 구조](#데이터-구조)
+
+---
+
+## 개요
+
+| 항목        | 내용                                             |
+| ----------- | ------------------------------------------------ |
+| 데이터 소스 | 공공데이터포털 `SpcdeInfoService` (XML 응답)     |
+| 수집 항목   | 공휴일, 국경일, 24절기, 잡절                     |
+| 기본 주기   | 매년 1월 1일, 12월 1일 새벽 3시 (`0 3 1 1,12 *`) |
+| 초기 동기화 | 서버 시작 시 자동 1회 실행                       |
+
+---
+
+## 설정
+
+`config.json`:
+
+```json
+{
+    "enabled": true,
+    "cron": "0 3 1 1,12 *",
+    "yearsAhead": 1,
+    "entity": "holiday",
+    "apiKey": "${HOLIDAY_API_KEY}"
+}
+```
+
+### 설정 항목
+
+| 항목         | 기본값         | 설명                                  |
+| ------------ | -------------- | ------------------------------------- |
+| `enabled`    | `true`         | 플러그인 활성화                       |
+| `cron`       | `0 3 1 1,12 *` | 동기화 스케줄 (1월, 12월 1일 03:00)   |
+| `yearsAhead` | `1`            | 현재 연도에서 추가로 수집할 미래 연수 |
+| `entity`     | `holiday`      | 저장 엔티티명                         |
+| `apiKey`     | —              | 공공데이터포털 서비스 키 (필수)       |
+
+---
+
+## 환경변수
+
+```env
+HOLIDAY_API_KEY=공공데이터포털_인코딩_서비스키
+```
+
+### API 키 발급
+
+1. [data.go.kr](https://www.data.go.kr) 로그인 → 마이페이지 → 인증키 발급
+2. 검색창에 `한국천문연구원_특일 정보` 또는 `SpcdeInfoService` 검색
+3. 활용 신청 → 승인 후 인코딩 서비스키 복사
+4. `.env`의 `HOLIDAY_API_KEY`에 설정
+
+---
+
+## API
+
+기본 경로: `/api/v1/holidays`
+
+| 메서드 | 경로        | 인증        | 설명                      |
+| ------ | ----------- | ----------- | ------------------------- |
+| `GET`  | `/`         |             | 공휴일 목록 조회          |
+| `GET`  | `/:locdate` |             | 특정 날짜 조회 (YYYYMMDD) |
+| `POST` | `/sync`     | 로그인 필요 | 수동 동기화 (관리자용)    |
+
+### GET / 쿼리 파라미터
+
+| 파라미터  | 타입    | 설명                                      |
+| --------- | ------- | ----------------------------------------- |
+| `year`    | number  | 연도 필터 (예: `2026`)                    |
+| `month`   | number  | 월 필터 (예: `3`)                         |
+| `holiday` | boolean | `true` 시 공휴일만 반환 (is_holiday=true) |
+| `limit`   | number  | 최대 결과 수                              |
+| `offset`  | number  | 페이지 오프셋                             |
+
+### 응답 예시 (GET /)
+
+```json
+{
+    "ok": true,
+    "data": [
+        {
+            "seq": 1,
+            "locdate": "20260101",
+            "datename": "새해",
+            "is_holiday": true
+        },
+        {
+            "seq": 5,
+            "locdate": "20260205",
+            "datename": "설날 연휴",
+            "is_holiday": true
+        }
+    ]
+}
+```
+
+---
+
+## 데이터 구조
+
+Entity: `holiday`
+
+| 컬럼         | 타입         | 설명                        |
+| ------------ | ------------ | --------------------------- |
+| `seq`        | integer (PK) | 자동 증가                   |
+| `locdate`    | varchar      | 날짜 (YYYYMMDD)             |
+| `datename`   | varchar      | 명칭 (예: "설날", "삼일절") |
+| `is_holiday` | boolean      | 공휴일(법정 휴무일) 여부    |

package/src/app/plugins/holidays/entities/holiday.json

@@ -0,0 +1,22 @@
+{
+    "name": "holiday",
+    "description": "공휴일·국경일·24절기·잡절 정보. data.go.kr SpcdeInfoService API로 자동 동기화됩니다.",
+    "fields": {
+        "locdate": {
+            "index": true,
+            "comment": "날짜 YYYYMMDD 숫자 (예: 20260101)"
+        },
+        "date_name": {
+            "index": true,
+            "comment": "특일 이름 (예: 신정, 설날, 하지)"
+        },
+        "date_kind": {
+            "index": true,
+            "comment": "날짜 분류 코드 (01=공휴일, 02=기념일, 03=24절기, 04=잡절 등)"
+        },
+        "is_holiday": {
+            "index": true,
+            "comment": "공휴일 여부 Y/N"
+        }
+    }
+}

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

@@ -0,0 +1,135 @@
+/**
+ * 공휴일 API 핸들러
+ *
+ * GET  /api/v1/holidays          → 공휴일 목록 조회
+ * GET  /api/v1/holidays/:locdate → 단건 조회
+ * POST /api/v1/holidays/sync     → 수동 동기화 트리거 (관리자)
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, entityServer } from "@gateway/api";
+
+const ENTITY = "holiday";
+
+// ─── 헬퍼 ────────────────────────────────────────────────────────────────────
+
+const ensureSvc = (req: FastifyRequest, reply: FastifyReply) => {
+    if (!req.server.holidayService) {
+        reply.status(503).send(fail("Holidays plugin not enabled"));
+        return null;
+    }
+    return req.server.holidayService;
+};
+
+// ─── 핸들러 ──────────────────────────────────────────────────────────────────
+
+/**
+ * GET /api/v1/holidays
+ *
+ * 쿼리 파라미터:
+ *  year       - 연도 (예: 2025)
+ *  month      - 월 1-12 (예: 5)
+ *  is_holiday - Y 또는 N (공휴일 여부)
+ *  date_kind  - 날짜 분류 코드
+ *  page       - 페이지 번호 (기본 1)
+ *  limit      - 페이지당 건수 (기본 50)
+ */
+export async function handleList(request: FastifyRequest, reply: FastifyReply) {
+    const qs = request.query as Record<string, string>;
+
+    const year = qs.year ? parseInt(qs.year, 10) : undefined;
+    const month = qs.month ? parseInt(qs.month, 10) : undefined;
+    const isHoliday = qs.is_holiday;
+    const dateKind = qs.date_kind;
+    const page = qs.page ? parseInt(qs.page, 10) : 1;
+    const limit = qs.limit ? Math.min(parseInt(qs.limit, 10), 500) : 50;
+
+    // locdate 범위 조건 조합
+    const conditions: Record<string, unknown> = {};
+
+    if (year !== undefined && month !== undefined) {
+        // ex) 20250500 ~ 20250599
+        const prefix = year * 10000 + month * 100;
+        conditions.locdate_gte = prefix;
+        conditions.locdate_lte = prefix + 99;
+    } else if (year !== undefined) {
+        conditions.locdate_gte = year * 10000;
+        conditions.locdate_lte = year * 10000 + 1231;
+    }
+
+    if (isHoliday) conditions.is_holiday = isHoliday;
+    if (dateKind) conditions.date_kind = dateKind;
+
+    try {
+        const resp = await entityServer.list(ENTITY, {
+            conditions: Object.keys(conditions).length ? conditions : undefined,
+            page,
+            limit,
+            orderBy: "locdate",
+            orderDir: "ASC",
+        });
+        const data = (resp as any).data ?? resp;
+        return ok({
+            items: data.items ?? [],
+            total: data.total ?? 0,
+            page,
+            limit,
+        });
+    } catch (err) {
+        request.log.error({ err }, "holidays: list failed");
+        return reply.status(500).send(fail("failed to list holidays"));
+    }
+}
+
+/**
+ * GET /api/v1/holidays/:locdate
+ * locdate 형식: YYYYMMDD (숫자 8자리)
+ */
+export async function handleGetByDate(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const { locdate } = request.params as { locdate: string };
+    const locdateNum = parseInt(locdate, 10);
+
+    if (isNaN(locdateNum) || locdate.length !== 8) {
+        return reply
+            .status(400)
+            .send(fail("locdate must be 8-digit YYYYMMDD number"));
+    }
+
+    try {
+        const resp = await entityServer.list(ENTITY, {
+            conditions: { locdate: locdateNum },
+            limit: 20,
+            orderBy: "date_kind",
+        });
+        const data = (resp as any).data ?? resp;
+        const items = data.items ?? [];
+        if (items.length === 0) {
+            return reply.status(404).send(fail("no holidays on that date"));
+        }
+        return ok({ items, total: items.length });
+    } catch (err) {
+        request.log.error({ err }, "holidays: get by date failed");
+        return reply.status(500).send(fail("failed to get holiday"));
+    }
+}
+
+/**
+ * POST /api/v1/holidays/sync
+ * 즉시 동기화를 트리거한다 (관리자 전용).
+ */
+export async function handleSync(request: FastifyRequest, reply: FastifyReply) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    try {
+        await svc.sync();
+        return ok({ message: "Holiday sync completed" });
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        request.log.error({ err }, "holidays: manual sync failed");
+        return reply.status(500).send(fail(`sync failed: ${msg}`));
+    }
+}

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

@@ -0,0 +1,78 @@
+/**
+ * 공휴일 동기화 Fastify 플러그인
+ *
+ * 설정 로드 → HOLIDAY_API_KEY 확인 → onReady 시 즉시 동기화 → cron 스케줄 등록
+ *
+ * cron 표현식: 5-필드 표준 형식 (분 시 일 월 요일)
+ * 기본값: "0 3 1 1,12 *" = 1월 1일·12월 1일 새벽 3시
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { Cron } from "croner";
+import { loadHolidaysConfig } from "./config.ts";
+import { HolidayService } from "./service.ts";
+
+declare module "fastify" {
+    interface FastifyInstance {
+        holidayService: HolidayService | null;
+    }
+}
+
+export default fp(
+    async (app: FastifyInstance) => {
+        const config = loadHolidaysConfig();
+        if (!config) {
+            app.decorate("holidayService", null);
+            return;
+        }
+
+        const apiKey = config.apiKey ?? "";
+        if (!apiKey) {
+            app.log.warn(
+                "Holidays plugin: apiKey not set in config.json (or HOLIDAY_API_KEY env not set), skipping schedule",
+            );
+            app.decorate("holidayService", null);
+            return;
+        }
+
+        const service = new HolidayService(config, apiKey);
+        app.decorate("holidayService", service);
+
+        // 서버 준비 후 즉시 1회 동기화 (누락된 데이터 보완)
+        app.addHook("onReady", async () => {
+            try {
+                await service.sync();
+            } catch (err) {
+                app.log.error({ err }, "Holiday initial sync failed");
+            }
+        });
+
+        // cron 스케줄 등록
+        const job = new Cron(
+            config.cron,
+            { timezone: "Asia/Seoul", protect: true },
+            async () => {
+                try {
+                    await service.sync();
+                } catch (err) {
+                    app.log.error({ err }, "Holiday scheduled sync failed");
+                }
+            },
+        );
+
+        app.log.info(
+            {
+                cron: config.cron,
+                next: job.nextRun()?.toISOString(),
+            },
+            "Holiday sync scheduled",
+        );
+
+        // 서버 종료 시 cron 정리
+        app.addHook("onClose", async () => {
+            job.stop();
+        });
+    },
+    { name: "holidays-plugin" },
+);

package/src/app/plugins/holidays/routes.ts

@@ -0,0 +1,18 @@
+/**
+ * 공휴일 라우트 테이블
+ * 등록 경로: /api/v1/holidays/*  (routes loader가 자동 등록)
+ */
+
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+export default async function holidayRoutes(app: FastifyInstance) {
+    // GET /api/v1/holidays?year=2025&month=5&is_holiday=Y
+    app.get("/", h.handleList);
+
+    // GET /api/v1/holidays/20250101
+    app.get("/:locdate", h.handleGetByDate);
+
+    // POST /api/v1/holidays/sync  (관리자 전용)
+    app.post("/sync", h.handleSync);
+}

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

@@ -0,0 +1,241 @@
+/**
+ * 공휴일 동기화 서비스
+ *
+ * 공공데이터포털(data.go.kr) SpcdeInfoService 4개 엔드포인트를 호출해
+ * Entity Server의 holiday 엔티티에 저장합니다.
+ *
+ * 엔드포인트:
+ *  - getRestDeInfo      : 공휴일
+ *  - getHoliDeInfo      : 국경일
+ *  - get24DivisionsInfo : 24절기
+ *  - getSundryDayInfo   : 잡절
+ *
+ * 저장 필드: locdate, date_name, date_kind, is_holiday (PHP SpcdeInfoService 동일)
+ * 동기화 방식: 연도별 기존 레코드 전체 삭제 후 재삽입 (중복 방지)
+ *
+ * API Base: https://apis.data.go.kr/B090041/openapi/service/SpcdeInfoService
+ * 환경변수: HOLIDAY_API_KEY (data.go.kr 서비스 인증키, 디코딩된 값)
+ */
+
+import { entityServer, logger } from "@gateway/api";
+import type {
+    HolidaysConfig,
+    HolidayApiItem,
+    HolidayRecord,
+    SpcdeOperation,
+} from "./types/index.ts";
+import { SPCDE_OPERATIONS, DATE_NAME_MAP } from "./types/index.ts";
+
+const API_BASE =
+    "https://apis.data.go.kr/B090041/openapi/service/SpcdeInfoService";
+
+export class HolidayService {
+    private readonly config: HolidaysConfig;
+    private readonly apiKey: string;
+
+    constructor(config: HolidaysConfig, apiKey: string) {
+        this.config = config;
+        this.apiKey = apiKey;
+    }
+
+    /** 설정된 연도 범위의 공휴일을 모두 동기화한다 */
+    async sync(): Promise<void> {
+        const currentYear = new Date().getFullYear();
+        const targetYears: number[] = [];
+        for (
+            let y = currentYear;
+            y <= currentYear + this.config.yearsAhead;
+            y++
+        ) {
+            targetYears.push(y);
+        }
+
+        logger.info({ years: targetYears }, "Starting holiday sync");
+
+        let total = 0;
+        for (const year of targetYears) {
+            const records = await this.fetchYear(year);
+            await this.replaceYear(year, records);
+            total += records.length;
+        }
+
+        logger.info({ total }, "Holiday sync completed");
+    }
+
+    /** 특정 연도의 4개 엔드포인트 데이터를 전부 가져온다 */
+    private async fetchYear(year: number): Promise<HolidayRecord[]> {
+        const allItems: HolidayApiItem[] = [];
+
+        for (const operation of SPCDE_OPERATIONS) {
+            for (let month = 1; month <= 12; month++) {
+                const items = await this.fetchMonth(operation, year, month);
+                allItems.push(...items);
+            }
+        }
+
+        // locdate+dateName+dateKind 기준 중복 제거 (엔드포인트 간 겹치는 항목)
+        const seen = new Set<string>();
+        const unique: HolidayApiItem[] = [];
+        for (const item of allItems) {
+            const key = `${item.locdate}:${item.dateName}:${item.dateKind}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                unique.push(item);
+            }
+        }
+
+        return unique.map((item) => ({
+            locdate: item.locdate,
+            date_name: DATE_NAME_MAP[item.dateName] ?? item.dateName,
+            date_kind: item.dateKind,
+            is_holiday: item.isHoliday,
+        }));
+    }
+
+    /** 특정 엔드포인트·연도·월의 데이터를 API에서 가져온다 (페이지네이션 포함) */
+    private async fetchMonth(
+        operation: SpcdeOperation,
+        year: number,
+        month: number,
+    ): Promise<HolidayApiItem[]> {
+        const results: HolidayApiItem[] = [];
+        let pageNo = 1;
+        const numOfRows = 100;
+
+        while (true) {
+            const url = new URL(`${API_BASE}/${operation}`);
+            url.searchParams.set("ServiceKey", this.apiKey);
+            url.searchParams.set("solYear", String(year));
+            url.searchParams.set("solMonth", String(month).padStart(2, "0"));
+            url.searchParams.set("pageNo", String(pageNo));
+            url.searchParams.set("numOfRows", String(numOfRows));
+            url.searchParams.set("_type", "json");
+
+            const resp = await fetch(url.toString());
+            if (!resp.ok) {
+                logger.warn(
+                    { operation, year, month, status: resp.status },
+                    "Holiday API HTTP error, skipping",
+                );
+                break;
+            }
+
+            const json = (await resp.json()) as Record<string, unknown>;
+
+            const response = json["response"] as
+                | Record<string, unknown>
+                | undefined;
+            const header = response?.["header"] as
+                | { resultCode: string; resultMsg: string }
+                | undefined;
+
+            if (header?.resultCode !== "00") {
+                logger.warn(
+                    {
+                        operation,
+                        year,
+                        month,
+                        resultCode: header?.resultCode,
+                        resultMsg: header?.resultMsg,
+                    },
+                    "Holiday API result error, skipping",
+                );
+                break;
+            }
+
+            const body = response?.["body"] as
+                | { totalCount: number; items: unknown }
+                | undefined;
+
+            if (!body || body.totalCount === 0 || !body.items) break;
+
+            // items가 빈 문자열("")로 오는 경우 (결과 없음)
+            if (typeof body.items !== "object") break;
+
+            // API는 1건일 때 배열이 아닌 단일 객체를 반환하기도 함
+            const raw = (body.items as Record<string, unknown>)["item"] as
+                | HolidayApiItem
+                | HolidayApiItem[]
+                | undefined;
+
+            if (!raw) break;
+            const items = Array.isArray(raw) ? raw : [raw];
+            results.push(...items);
+
+            if (items.length < numOfRows) break;
+            pageNo++;
+        }
+
+        return results;
+    }
+
+    /**
+     * 특정 연도의 기존 holiday 레코드를 전부 삭제하고 새 데이터를 삽입한다.
+     * 중복 없이 항상 최신 API 데이터를 유지한다.
+     */
+    private async replaceYear(
+        year: number,
+        records: HolidayRecord[],
+    ): Promise<void> {
+        const yearStart = year * 10000 + 101; // YYYYMMDD: YYYY0101
+        const yearEnd = year * 10000 + 1231; // YYYYMMDD: YYYY1231
+
+        // 기존 레코드 조회 후 전체 삭제
+        try {
+            const existing = await entityServer.query<{ seq: number }>(
+                this.config.entity,
+                {
+                    sql: `SELECT seq FROM ${this.config.entity}
+                          WHERE locdate >= ? AND locdate <= ?`,
+                    params: [yearStart, yearEnd],
+                    limit: 1000,
+                },
+            );
+
+            for (const row of existing.data.items) {
+                await entityServer.delete(this.config.entity, row.seq, {
+                    hard: true,
+                });
+            }
+
+            if (existing.data.items.length > 0) {
+                logger.debug(
+                    { year, deleted: existing.data.items.length },
+                    "Deleted existing holiday records",
+                );
+            }
+        } catch (err) {
+            // 테이블 미존재 등 첫 동기화 시 정상
+            logger.debug(
+                { err, year },
+                "Could not delete existing holidays (may be first sync)",
+            );
+        }
+
+        // 새 데이터 삽입
+        for (const record of records) {
+            try {
+                await entityServer.submit(this.config.entity, {
+                    locdate: record.locdate,
+                    date_name: record.date_name,
+                    date_kind: record.date_kind,
+                    is_holiday: record.is_holiday,
+                });
+            } catch (err) {
+                logger.error(
+                    {
+                        err,
+                        locdate: record.locdate,
+                        date_name: record.date_name,
+                    },
+                    "Failed to save holiday record",
+                );
+            }
+        }
+
+        logger.info(
+            { year, inserted: records.length },
+            "Holiday year sync done",
+        );
+    }
+}

package/src/app/plugins/holidays/types/api.ts

@@ -0,0 +1,49 @@
+/**
+ * data.go.kr SpcdeInfoService API 응답 — 개별 항목
+ *
+ * 엔드포인트 4종 모두 동일한 구조를 반환합니다:
+ *  - getRestDeInfo      : 공휴일
+ *  - getHoliDeInfo      : 국경일
+ *  - get24DivisionsInfo : 24절기
+ *  - getSundryDayInfo   : 잡절
+ */
+export interface HolidayApiItem {
+    /** 날짜 분류 코드 (01=공휴일 등) */
+    dateKind: string;
+    /** 특일 이름 */
+    dateName: string;
+    /** 공휴일 여부 (Y/N) */
+    isHoliday: string;
+    /** 날짜: YYYYMMDD 숫자 */
+    locdate: number;
+    /** API 고유 시퀀스 */
+    seq: number;
+}
+
+/** Entity Server holiday 엔티티에 저장하는 레코드 (snake_case) */
+export interface HolidayRecord {
+    /** 날짜: YYYYMMDD 숫자 (API locdate와 동일) */
+    locdate: number;
+    /** 특일 이름 */
+    date_name: string;
+    /** 날짜 분류 코드 */
+    date_kind: string;
+    /** 공휴일 여부 Y/N */
+    is_holiday: string;
+}
+
+/** 이름 정규화 맵 — PHP SpcdeInfoService.php 기준 */
+export const DATE_NAME_MAP: Record<string, string> = {
+    "1월1일": "신정",
+    기독탄신일: "성탄절",
+};
+
+/** 호출할 SpcdeInfoService 오퍼레이션 목록 */
+export const SPCDE_OPERATIONS = [
+    "getRestDeInfo", // 공휴일
+    "getHoliDeInfo", // 국경일
+    "get24DivisionsInfo", // 24절기
+    "getSundryDayInfo", // 잡절
+] as const;
+
+export type SpcdeOperation = (typeof SPCDE_OPERATIONS)[number];

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

@@ -0,0 +1,8 @@
+/** 플러그인 디렉토리의 config.json 스키마 */
+export interface HolidaysConfig {
+    enabled: boolean; // 공휴일 동기화 활성화 여부
+    cron: string; // 실행 주기 — 5-필드 crontab 형식 (분 시 일 월 요일)
+    yearsAhead: number; // 현재 연도 기준 몇 년 앞까지 미리 동기화할지
+    entity: string; // 공휴일 데이터를 저장할 엔티티 이름
+    apiKey?: string; // data.go.kr 서비스 인증키 (디코딩된 값). ${HOLIDAY_API_KEY} 형식으로 환경변수 참조 가능
+}

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

@@ -0,0 +1,2 @@
+export * from "./config.ts";
+export * from "./api.ts";