# 공휴일 플러그인 (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": "${DATAGOKR_API_KEY}"
}
```

### 설정 항목

| 항목         | 기본값         | 설명                                  |
| ------------ | -------------- | ------------------------------------- |
| `enabled`    | `true`         | 플러그인 활성화                       |
| `cron`       | `0 3 1 1,12 *` | 동기화 스케줄 (1월, 12월 1일 03:00)   |
| `yearsAhead` | `1`            | 현재 연도에서 추가로 수집할 미래 연수 |
| `entity`     | `holiday`      | 저장 엔티티명                         |
| `apiKey`     | —              | 공공데이터포털 서비스 키 (필수)       |

---

## 환경변수

```env
DATAGOKR_API_KEY=공공데이터포털_인코딩_서비스키
```

### API 키 발급

1. [data.go.kr](https://www.data.go.kr) 로그인 → 마이페이지 → 인증키 발급
2. 검색창에 `한국천문연구원_특일 정보` 또는 `SpcdeInfoService` 검색
3. 활용 신청 → 승인 후 인코딩 서비스키 복사
4. `.env`의 `DATAGOKR_API_KEY`에 설정

---

## 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      | 공휴일(법정 휴무일) 여부    |