AriWeb-Suite/modules/webmaker/docs/CALENDAR.md

# 일정관리 모듈 · 만세력 — v1.4.18

사이트 기본 제공 모듈 `calendar`(일정관리). 월간·주간·일간 캘린더에 예정된 일정을 보여 주고, 음력 날짜·만세력 간지·24절기 표시와
반복 일정·음력 기준 일정 등록을 지원한다.

## 구성
| 파일 | 역할 |
|---|---|
| `lib/lunar.js` | 만세력 계산: 양력 ↔ 음력, 사주식 간지(연주·월주·일주), 24절기. 자료표 없이 천문 계산(아래) |
| `lib/calendar.js` | 일정 데이터 규칙(`normalizeEvent`), 반복·음력 일정의 발생 전개(`expand`), 캘린더 조회(`range`), 다음 발생일 |
| `lib/modules.js` | 카탈로그 `calendar`(설정 스키마·`events` 컬렉션), 공개 조회 `listCalendar`, 관리 CRUD(`/c/events`) |
| `modules/calendar/widget.html` | 사이트에 들어가는 표준 위젯 마크업 (`data-view`·`data-lunar`·`data-ganji`·`data-category`) |
| `public/wm-modules.js` `R.calendar` | 브라우저 런타임: 월간 격자·주간/일간 시간표·일정 상세 팝업 |
| `public/site-admin.js` | 사이트 관리자 페이지 › 일정관리: 날짜 조회, 일정 표(다음 발생), 일정 편집기 |

## 공개 API (`/api/m/<사이트ID>/calendar/…`, 모듈이 켜져 있을 때)
- `GET range?from=YYYY-MM-DD&to=YYYY-MM-DD[&cat=분류]` — 최대 70일. `days[]`(날짜마다 음력·간지·절기), `events[]`(공개 일정의 발생), `settings`
- `GET settings` — 기본 보기, 음력·간지·절기 표시, 주 시작 요일, 주간·일간 시간 범위, 분류
- `GET day?date=YYYY-MM-DD` — 한 날의 음력·간지(한글·한자·띠)·절기
- `GET lunar?year&month&day&leap=1` — 음력 → 양력, 그 해 윤달·달 길이

## 일정 형식
| 항목 | 뜻 |
|---|---|
| `unit` | `time` 시·분 단위(한 날의 시작~종료 시각) / `day` 일 단위(`length` 일) / `week` 주 단위(`length` 주) |
| `cal` | `solar` 양력 / `lunar` 음력 — 음력이면 `lunar:{year,month,day,leap}` 가 시작일, `date` 에 변환한 양력 시작일을 함께 둔다 |
| `repeat` | `freq` none·daily·weekly·monthly·yearly, `interval`(1~99), `until`(종료일), `weekdays`(매주 반복 요일) |

규칙
- 양력 매월·매년 반복에서 없는 날(31일, 2월 29일)은 그 달 마지막 날.
- 음력 매년 반복은 해마다 같은 음력 달·날. 윤달에 시작한 일정은 그 해에 같은 윤달이 있을 때만 윤달, 없으면 평달(윤달 생일을 평달에 지내는 관행). 30일이 없는 달은 29일.
- 음력 매월 반복은 음력 달마다 같은 날(윤달도 한 달로 센다). 음력 일정의 매일·매주 반복은 변환한 양력 시작일부터 이어진다.
- 발생(occurrence) id 는 `<일정ID>@<시작일>`.

## 만세력 계산 방법 (`lib/lunar.js`)
한국천문연구원 만세력과 같은 규칙을 한국 표준시(KST) 기준으로 적용한다.
- **합삭(새달)**: Meeus 『Astronomical Algorithms』 49장 급수. 합삭 순간이 든 KST 날짜가 음력 1일.
- **태양 황경**: VSOP87 지구 급수 축약(Meeus 부록 III, 약 1″)에 장동·광행차를 더한 시황경. 24절기는 황경이 15° 배수가 되는 순간(뉴턴 반복).
  역표시 ↔ 세계시 차(ΔT)는 Espenak-Meeus 다항식.
- **달 번호·윤달**: 동지가 든 달이 11월. 동지에서 다음 동지 사이(歲)에 달이 13개면 중기(황경 30° 배수)가 없는 첫 달이 윤달.
- **간지**: 일주는 60일 주기(2000-01-01 = 무오일), 연주는 입춘(315°)에 바뀌고, 월주는 절기(15°+30°k)에 바뀌며 월간은 오호둔. 캘린더는 날짜 단위라 절입 당일부터 새 달·새 해로 표시한다.
- 검증(scratch 테스트): 설날 1990~2033, 추석 2000~2027, 윤달 2001~2047(2033 윤11월 포함), 절기 시각(2025 동지 12-22 00:03, 2026 춘분 03-20 23:46), 일진(2024-01-01 갑자, 2026-10-14 병오년 무술월 신유일) 모두 일치.
  KST 기준이라 중국 음력과 다른 해(예: 2027 설날 2/7, 2028 설날 1/27 — 합삭이 KST 자정 직후)도 한국 기준으로 나온다.
- 한계: 합삭·절기가 KST 자정 수십 초 안에 드는 극히 드문 날은 하루 차이가 날 수 있다. 유효 범위 1900~2100년.

## 위젯 표시
- 월간: 7×6 격자, 날짜 칸에 `음 9.4 · 신유`(설정에 따라 음력·일진) 와 절기 배지, 일정 3개 + "+n개 더". 칸을 누르면 그 날의 일간 보기.
- 주간·일간: 종일 줄(일·주 단위 일정) + 시간표(관리자 설정 시작~끝 시각, 겹치는 일정은 열로 나눔). 일간 보기 위에는 전체 간지(병오년 무술월 신유일)와 절기.
- 일정 클릭 → 상세 팝업(날짜·시간, 단위, 분류, 음력 기준 여부, 장소, 설명).
- 한국어가 아닌 페이지에서는 간지·절기를 한자(丙午年 戊戌月 辛酉日, 寒露)로 보인다. 문구는 `locales/site/ko.json` 의 `calendar.*`.