HBSA260_National Holidays (공휴일 동기화)
(Hereby) 시스템 관리 > [[HBSA200]] > Holidays
| 앱 | System Admin (포트 4100) |
| 부모 화면 | [[HBSA200]] |
| 대상 사용자 | 플랫폼 운영자(OPERATOR) |
| 프로토타입 | TBU |
| 관련 정책 | [[POL_권한(RBAC)]] |
| Status | draft (코드 기반 — 라이브 실사 불가: dev 라우트 AccessDenied 격리, 2026-08-25 확인) |
| Owner | 카나 |
개요
국가 공휴일·대체공휴일을 공공데이터포털 특일정보 API로 동기화한다. 동기화된 데이터가 공휴일 판정의 유일한 정본이며, 동기화 없는 연도는 판정이 비어 있다. 콘솔에서 "작년·올해·내년"을 즉시 동기화하거나 연도별 상세를 볼 수 있다. DATA_GO_KR_SERVICE_KEY 미설정 시 동기화 불가.
문서 히스토리
| 날짜 | 작성자 | 팀 | 변경 내용 |
|---|---|---|---|
| 2026-08-25 | 카나 | 콸 | 최초 작성 (redesign PR #583 코드 census 기반, 라이브 미실사) |
Data I/O
Client → Server
| 액션 | 콘솔 REST | systemProcedure |
|---|---|---|
| 연도 목록 | GET /api/national-holidays (fan-out) | systemHolidayYears |
| 연도 상세 | GET /api/national-holidays/:year | systemHolidaysByYear |
| 동기화 | POST /api/national-holidays/sync | systemSyncNationalHolidays(코어 syncNationalHolidays 재사용) |
Server → Client
| 변수 | 소스 | 비고 |
|---|---|---|
holidayStatus.years[] | systemHolidayYears | year/count/apiCount/lastChangedAt |
holidayStatus.keyConfigured | 서버 | 키 없으면 동기화 disabled |
holidayDetailItems[] | systemHolidaysByYear | date/name |
코드 근거: tabs/national-holidays.html, server/routes/national-holidays.ts.
화면 플로우
National Holidays 사양표
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 00 | 화면 진입 조건 | - | activeTab === 'national-holidays' | - | |
| 01 | 초기 상태 | Output | 안내 "국가 공휴일·대체공휴일 — 특일정보 API 동기화 데이터가 판정의 유일한 정본. 동기화 없는 연도는 공휴일 판정이 비어 있음" + "refresh" + 동기화 버튼 | - | |
| 10 | 동기화 버튼 | Button | "동기화 (작년·올해·내년)" → syncNationalHolidaysNow(). !keyConfigured 또는 진행 중 disabled("동기화 중...") | systemSyncNationalHolidays | |
| 20 | 키 미설정 경고 | Alert | !keyConfigured 시 yellow 배너 "DATA_GO_KR_SERVICE_KEY가 설정되지 않아 동기화할 수 없습니다... 키만 설정하면 API 서버가 매일 자동 동기화합니다." | - | |
| 30 | 동기화 결과 | Alert | holidaySyncMessage 시 green 배너 | - | 실측 문구 TBU |
| 40 | 연도 상태 테이블 | List | [List] 컬럼 연도/휴일 수/API 동기화분/마지막 갱신/달력. 각 행 "보기"/"닫기" → toggleHolidayYear(year) | holidayStatus.years | |
| 40-E | ㄴ Empty | Text | "동기화 이력이 없습니다 — 동기화 전까지 공휴일 판정이 비어 있으므로 동기화를 실행해 주세요." | - | |
| 50 | 연도 상세 | List | holidayDetailYear 선택 시 "{year}년 동기화된 공휴일 ({n}건)" + date/name 목록 | holidayDetailItems | |
| 50-E | ㄴ Empty | Text | "동기화된 데이터가 없습니다." | - | |
| 60 | 값 없음 처리 | - | lastChangedAt 없으면 "-" | - | |
| 70 | 권한별 차이 | - | OPERATOR org-less 쓰기(audit org=null) | [[POL_권한(RBAC)]] |
권한 / 상태 요약
| 시나리오 | 트리거 | 결과 | 비고 |
|---|---|---|---|
case01 [키 미설정] | 진입 | 경고 + 동기화 비활성 | |
case02 [동기화] | 버튼 | 3개년 fetch + 결과 메시지 | design 라이브: 2025 fetched 19 |
case03 [상세 보기] | 보기 | 연도별 공휴일 목록 |
OQ
- count vs apiCount 차이 의미(수동 보정분 등) = TBU