# 휴일 데이터 동기화 플러그인

공공데이터포털 data.go.kr 휴일 데이터 API에서 국가 공휴일을 주기적으로 동기화하고 조회하는 플러그인입니다.

이 문서는 플러그인 개요/설정/운영 가이드를 다룹니다.  
실제 라우트표, 호출 예제, 응답 예제는 [Holidays Routes](../routes/holidays-routes.md) 문서를 참고하세요.

---

## 목차

- [개요](#개요)
- [필수 환경변수](#필수-환경변수)
- [설정](#설정)
- [동기화 동작](#동기화-동작)
- [운영 팁](#운영-팁)

---

## 개요

- 서버 시작 시 즉시 1회 동기화 (누락 데이터 보완)
- cron 스케줄에 따라 자동 재동기화
- Entity Server의 `holiday` 엔티티에 데이터 저장
- GET/단건 조회 및 수동 동기화 API 제공

---

## 필수 환경변수

| 변수명            | 설명                      |
| ----------------- | ------------------------- |
| `DATAGOKR_API_KEY` | data.go.kr API 키 |

`.env` 파일에 추가:

```
DATAGOKR_API_KEY=your_api_key_here
```

> 공공데이터포털(data.go.kr) → [한국천문연구원\_특일 정보](https://www.data.go.kr/data/15012690/openapi.do) 에서 발급

---

## 설정

`src/app/plugins/holidays/config.json`:

```json
{
    "enabled": true,
    "cron": "0 3 1 1,12 *",
    "yearsAhead": 1,
    "entity": "holiday"
}
```

| 항목         | 설명                                              | 기본값           |
| ------------ | ------------------------------------------------- | ---------------- |
| `enabled`    | 플러그인 활성화 여부                              | `false`          |
| `cron`       | 자동 동기화 스케줄 (5-필드 cron, Asia/Seoul 기준) | `"0 3 1 1,12 *"` |
| `yearsAhead` | 현재 연도 기준 몇 년 앞까지 동기화할지            | `1`              |
| `entity`     | Entity Server에서 사용하는 엔티티 이름            | `"holiday"`      |

### cron 예시

| cron 표현식    | 설명                               |
| -------------- | ---------------------------------- |
| `0 3 1 1,12 *` | 1월 1일·12월 1일 새벽 3시 (기본값) |
| `0 2 1 * *`    | 매월 1일 새벽 2시                  |
| `0 0 * * 0`    | 매주 일요일 자정                   |

---

## 동기화 동작

1. **서버 시작 시**: `onReady` 훅에서 즉시 1회 동기화 실행
2. **cron 스케줄**: 설정된 주기마다 자동 실행
3. **수동 트리거**: `POST /v1/holidays/sync` API 호출

동기화 대상 연도: 현재 연도 ~ `(현재 연도 + yearsAhead)`

---

## 운영 팁

- `DATAGOKR_API_KEY`가 없으면 플러그인이 비활성화됩니다. 로그에 경고가 출력됩니다.
- 공공 API 호출 실패 시 기존 데이터는 유지되며 에러 로그만 남습니다.
- 연초(1월 1일)와 연말(12월 1일) 자동 갱신으로 다음 해 공휴일을 미리 확보합니다.
- Entity Server의 `holiday` 엔티티 스키마가 없으면 동기화 시 에러가 발생합니다.

---

## 관련 문서

- [Holidays Routes](../routes/holidays-routes.md)
- [PG Guide](./pg.md)
- [LLM Guide](./llm.md)