# chinese-lunar-date 사용 안내서

> 버전：1.0.0 | 최종 업데이트：2025-06
> Copyright (c) 2025 北京锋通科技有限公司 (郭玉峰, 吴琼). MIT License.
>
> 🌐 언어 버전：简体中文 · 繁體中文(台) · 繁體中文(港) · 日本語 · **한국어** · Tiếng Việt

---

## 목차

- [1. 개요](#1-개요)
- [2. 설치 및 가져오기](#2-설치-및-가져오기)
- [3. 핵심 개념](#3-핵심-개념)
- [4. 날짜 생성](#4-날짜-생성)
- [5. 속성 읽기](#5-속성-읽기)
- [6. 날짜 변환](#6-날짜-변환)
- [7. 날짜 연산](#7-날짜-연산)
- [8. 포맷](#8-포맷)
- [9. 간지](#9-간지)
- [10. 띠](#10-띠)
- [11. 24절기](#11-24절기)
- [12. 전통 명절](#12-전통-명절)
- [13. 다역법](#13-다역법)
- [14. 다국어 / 다지역](#14-다국어--다지역)
- [15. 저수준 API](#15-저수준-api)
- [16. 중국어 숫자](#16-중국어-숫자)
- [17. 타입 레퍼런스](#17-타입-레퍼런스)
- [18. 자주 묻는 질문（FAQ）](#18-자주-묻는-질문faq)
- [19. 아키텍처 및 설계 원칙](#19-아키텍처-및-설계-원칙)
- [20. 업데이트 로그](#20-업데이트-로그)

---

## 1. 개요

`chinese-lunar-date`는 천문 알고리즘 기반 고정밀 음력 라이브러리입니다.

| 기능 | 설명 |
|------|------|
| **양력 ↔ 음력 변환** | VSOP87 행성 이론 기반 천문급 정밀도 |
| **간지** | 연주·월주·일주, 육십갑자 번호와 문자열 상호 변환 |
| **띠** | 12띠 다국어 명칭 + Emoji |
| **24절기** | 일 단위 정밀도 절기 계산, 6개 언어 |
| **전통 명절** | 13종 내장 명절, 지역별 자동 필터 |
| **포맷** | 5종 내장 + 커스텀 패턴（17종 Token） |
| **다역법** | 중국 / 일본 / 한국 / 베트남 4종 음력 변형 |
| **다국어** | 간체중국어 / 번체중국어(대만/홍콩) / 日本語 / 한국어 / Tiếng Việt |

**출력 형식：** ESM / CJS / IIFE, IIFE 압축 후 단 ~47 KB（gzip ~16 KB）.

---

## 2. 설치 및 가져오기

### 2.1 설치

```bash
npm install chinese-lunar-date
```

### 2.2 ESM 가져오기

```ts
import { ChineseDate, formatGanZhi, PATTERNS } from 'chinese-lunar-date'
```

### 2.3 CJS 가져오기

```js
const { ChineseDate, formatGanZhi, PATTERNS } = require('chinese-lunar-date')
```

### 2.4 브라우저 IIFE 가져오기

```html
<script src="dist/chinese-lunar-date.iife.js"></script>
<script>
  const date = ChineseDate.ChineseDate.fromGregorian(2024, 6, 21)
  console.log(date.formatFull('ko-KR'))  // "갑진용년 5월초육"

  const lunar = ChineseDate.gregorianToLunar(ChineseDate.CHINESE_CONFIG, 2024, 6, 21)
</script>
```

### 2.5 TypeScript 지원

네이티브 TypeScript로 작성되어 완전한 타입 정의를 내장합니다.

```ts
import type { LunarDateValue, GanZhiPair, LocaleCode } from 'chinese-lunar-date'
```

---

## 3. 핵심 개념

### 3.1 육십갑자 주기（cycle / year）

- **`cycle`** — 주기 번호（1 시작）, 몇 번째 60년 주기인지 표시
- **`year`** — 주기 내 연번（1-60）, 간지에 직접 대응

```ts
gregorianYear = epochYear + (cycle - 1) * 60 + (year - 1)
```

### 3.2 불변 값 객체

모든 날짜 인스턴스는**불변**입니다. 수정 조작은 새 인스턴스를 반환합니다.

### 3.3 역법 설정과 지역 차이

| 역법 | 시간대 | 기원 | 설정 상수 |
|------|--------|------|-----------|
| 중국 | UTC+8 | 기원전 2636년 | `CHINESE_CONFIG` |
| 일본 | UTC+9 | 기원전 2636년 | `JAPANESE_CONFIG` |
| 한국 | UTC+8:30 / UTC+9 | 기원전 2333년（단군） | `KOREAN_CONFIG` |
| 베트남 | UTC+7 / UTC+8 | 기원전 2636년 | `VIETNAMESE_CONFIG` |

### 3.4 언어 및 지역 코드

| 코드 | 언어 | 설명 |
|------|------|------|
| `zh-CN` | 간체중국어 | 중국 대륙 |
| `zh-TW` | 번체중국어 | 대만 |
| `zh-HK` | 번체중국어 | 홍콩 |
| `ja-JP` | 日本語 | 일본 |
| `ko-KR` | 한국어 | 한국 |
| `vi-VN` | Tiếng Việt | 베트남 |

---

## 4. 날짜 생성

```ts
const date = ChineseDate.fromGregorian(2024, 6, 21)
const date2 = ChineseDate.fromDate(new Date(2024, 5, 21))
const today = ChineseDate.today()
const date3 = ChineseDate.fromValue({ cycle: 78, year: 34, month: 5, leap: false, day: 6 })
const d1 = ChineseDate.fromISO('2024-06-21')
const date4 = ChineseDate.fromTimestamp(Date.now())
const date5 = ChineseDate.fromJDE(2460482.5)
```

---

## 5. 속성 읽기

### 5.1 음력 날짜 속성

```ts
date.cycle           // 78
date.year            // 34
date.month           // 5
date.leap            // false
date.day             // 6
date.calendarType    // 'chinese'
date.gregorianYear   // 2024
```

### 5.2 간지 속성

```ts
date.yearGanZhi      // "甲辰"
date.monthGanZhi     // "庚午"
date.dayGanZhi       // "甲寅"
date.ganZhiInfo      // { year: {gan:0,zhi:4}, month: {gan:6,zhi:6}, day: {gan:0,zhi:2} }
```

### 5.3 띠 속성

```ts
date.zodiac          // "용"
date.zodiacEmoji     // "🐉"
date.zodiacIndex     // 4

date.getZodiac('ko-KR')  // "용"
date.getZodiac('ja-JP')  // "辰"
date.getZodiac('vi-VN')  // "Thìn"
```

### 5.4 양력 및 요일 속성

```ts
date.weekday           // 5
date.weekdayName       // "금요일"（ko-KR）
date.weekdayShort      // "금"
date.gregorianYearCn   // "二〇二四"
```

---

## 6. 날짜 변환

```ts
date.toGregorian()  // { year: 2024, month: 6, day: 21 }
date.toDate()       // Date object
date.toJSON()       // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
```

---

## 7. 날짜 연산

```ts
const tomorrow = date.addDays(1)
const yesterday = date.addDays(-1)
const nextMonth = date.addMonths(1)
const lastYear = date.addYears(-1)
const firstDay = date.with({ day: 1 })

a.equals(b)      // false
a.isAfter(b)     // true
a.diffDays(b)    // 3
date.daysInMonth()  // 29 또는 30
```

---

## 8. 포맷

### 8.1 내장 포맷 메서드

```ts
date.formatFull('ko-KR')   // "갑진용년 5월초육"
date.formatGanZhi()        // "甲辰年 庚午月 甲寅日"
date.formatCompact()       // "78/34/5/0/6"
date.formatISO()           // "78-34-5-0-6"
```

### 8.2 커스텀 패턴

```ts
date.format('{Ygz}{Z}년 {Mname}{Dname}', 'ko-KR')   // "갑진용년 5월초육"
date.format('{GY}년{GM}월{GD}일', 'ko-KR')           // "2024년6월21일"
```

### 8.3 프리셋 포맷 상수 PATTERNS

```ts
import { PATTERNS } from 'chinese-lunar-date'

date.format(PATTERNS.LUNAR_FULL)               // "갑진용년 9월초구"
date.format(PATTERNS.GREGORIAN_CN_FULL)        // "二〇二五年十月十一日"
```

### 8.4 포맷 Token 전체 레퍼런스

#### 음력 관련

| Token | 출력 | 예 |
|-------|------|-----|
| `{CY}` | 주기 번호 | `78` |
| `{Y}` | 주기 내 연번 | `34` |
| `{Ygz}` | 연간지 | `甲辰` |
| `{Z}` | 띠 | `용` |
| `{M}` | 월 숫자 | `5` |
| `{Mname}` | 월명 | `5월` |
| `{L}` | 윤달 표시 | `윤` |
| `{D}` | 일 숫자 | `6` |
| `{Dname}` | 일명 | `초육` |

#### 양력 관련

| Token | 출력 | 예 |
|-------|------|-----|
| `{GY}` | 양력 연 | `2024` |
| `{GM}` | 양력 월 | `6` |
| `{GD}` | 양력 일 | `21` |

#### 요일 관련

| Token | 출력 | 예 |
|-------|------|-----|
| `{W}` | 요일 숫자 (0-6) | `5` |
| `{Wname}` | 요일 전칭 | `금요일` |
| `{Wshort}` | 요일 약칭 | `금` |

### 8.5 파싱

```ts
import { parseCompact, parseISO, parseGregorian } from 'chinese-lunar-date'

parseCompact('78/34/5/0/6')    // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
parseISO('78-34-5-0-6')        // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
parseGregorian('2025-10-11')   // { year: 2025, month: 10, day: 11 }
```

---

## 9. 간지

```ts
import { yearGanZhi, formatGanZhi, parseGanZhi, allGanZhi, ganZhiToCycleIndex } from 'chinese-lunar-date'

yearGanZhi(value)   // { gan: 3, zhi: 9 }  → 정유
formatGanZhi({ gan: 3, zhi: 9 })  // "丁酉"
parseGanZhi('甲子')  // { gan: 0, zhi: 0 }
allGanZhi()  // ["甲子", "乙丑", ..., "癸亥"]
```

---

## 10. 띠

```ts
import { zodiac, zodiacEmoji, zodiacFromGregorianYear, zodiacList } from 'chinese-lunar-date'

zodiac(value, 'ko-KR')  // "닭"
zodiacEmoji(value)       // "🐔"
zodiacFromGregorianYear(2024, 'ko-KR')  // "용"
zodiacList('ko-KR')  // ["쥐", "소", "호랑이", "토끼", "용", "뱀", "말", "양", "원숭이", "닭", "개", "돼지"]
```

---

## 11. 24절기

### 11.1 절기 날짜 가져오기

```ts
ChineseDate.solarTerm(1, 2024)   // 입춘
ChineseDate.solarTerm(5, 2024)   // 청명
ChineseDate.qingming(2024)       // 동일
```

**절기 번호 대조표：**

| 번호 | 명칭 | 번호 | 명칭 | 번호 | 명칭 | 번호 | 명칭 |
|------|------|------|------|------|------|------|------|
| 1 | 입춘 | 7 | 입하 | 13 | 입추 | 19 | 입동 |
| 2 | 우수 | 8 | 소만 | 14 | 처서 | 20 | 소설 |
| 3 | 경칩 | 9 | 망종 | 15 | 백로 | 21 | 대설 |
| 4 | 춘분 | 10 | 하지 | 16 | 추분 | 22 | 동지 |
| 5 | 청명 | 11 | 소서 | 17 | 한로 | 23 | 소한 |
| 6 | 곡우 | 12 | 대서 | 18 | 상강 | 24 | 대한 |

> 홀수 번호는**절기**（절）, 짝수 번호는**중기**（기）.

### 11.2 절기 명칭

```ts
import { solarTermName, solarTermNames } from 'chinese-lunar-date'

solarTermName(3, 'ko-KR')  // "경칩"
solarTermNames('ko-KR')    // ["입춘", "우수", "경칩", ...]
```

### 11.3 특정일의 절기 판정

```ts
date.getSolarTermName('ko-KR')  // "청명" 또는 null
```

### 11.4 연간 절기

```ts
ChineseDate.solarTermsInYear(2024, 'ko-KR')
// [{ index: 1, name: "입춘", date: {...}, jde: ... }, ...]
```

---

## 12. 전통 명절

```ts
ChineseDate.festivalDate('spring', 2024)       // 춘절
ChineseDate.festivalDate('mid-autumn', 2024)   // 중추절

date.getFestivals('ko-KR')
ChineseDate.festivalsInYear(2024, 'ko-KR')
```

---

## 13. 다역법

```ts
import { ChineseDate, JapaneseDate, KoreanDate, VietnameseDate } from 'chinese-lunar-date'

const cn = ChineseDate.fromGregorian(2024, 6, 21)    // UTC+8
const jp = JapaneseDate.fromGregorian(2024, 6, 21)   // UTC+9
const kr = KoreanDate.fromGregorian(2024, 6, 21)     // UTC+8:30/9, 단군기원
const vn = VietnameseDate.fromGregorian(2024, 6, 21) // UTC+7/8
```

> **참고**: 시간대 차이로 인해 같은 양력 날짜가 다른 역법에서 다른 음력 날짜에 해당할 수 있습니다.

### 한국 역법의 특수 기원

한국 역법은 단군기원（기원전 2333년）을 사용하므로 `cycle`과 `year`가 중국 역법과 다릅니다. 단 `gregorianYear`는 동일합니다.

---

## 14. 다국어 / 다지역

```ts
import { availableLocales, getLocale } from 'chinese-lunar-date'

availableLocales()  // ["zh-CN", "zh-TW", "zh-HK", "ja-JP", "ko-KR", "vi-VN"]

const loc = getLocale('ko-KR')
loc.zodiac        // ["쥐", "소", "호랑이", "토끼", "용", "뱀", "말", "양", "원숭이", "닭", "개", "돼지"]
loc.solarTerms    // ["입춘", "우수", "경칩", ...]
```

---

## 15. 저수준 API

```ts
import {
  gregorianToLunar, lunarToGregorian,
  CHINESE_CONFIG, JAPANESE_CONFIG, KOREAN_CONFIG, VIETNAMESE_CONFIG
} from 'chinese-lunar-date'

const lunar = gregorianToLunar(KOREAN_CONFIG, 2024, 6, 21)
const greg = lunarToGregorian(KOREAN_CONFIG, lunar)
```

---

## 16. 중국어 숫자

```ts
import { toChineseYear, toChineseNumber, getWeekdayName } from 'chinese-lunar-date'

toChineseYear(2025, 'upper')  // "二〇二五"
toChineseNumber(21, 'upper')  // "二十一"
getWeekdayName(6, 'ko-KR')    // "토요일"
```

---

## 17. 타입 레퍼런스

```ts
interface LunarDateValue {
  cycle: number
  year: number
  month: number
  leap: boolean
  day: number
}

interface GregorianDate {
  year: number
  month: number
  day: number
}

type CalendarType = 'chinese' | 'korean' | 'japanese' | 'vietnamese'

interface GanZhiPair {
  gan: number
  zhi: number
}

type LocaleCode = 'zh-CN' | 'zh-TW' | 'zh-HK' | 'ja-JP' | 'ko-KR' | 'vi-VN'
```

---

## 18. 자주 묻는 질문（FAQ）

### Q: `cycle`과 `year`의 차이는？

`cycle`은 몇 번째 60년 주기인지, `year`은 주기 내 연번（1-60）입니다. 대부분의 경우 `date.gregorianYear`을 사용하면 충분합니다.

### Q: 같은 양력 날짜인데 `ChineseDate`와 `JapaneseDate`의 음력이 다른 이유는？

시간대 차이 때문입니다. 초승달이 UTC+8 자정 부근에 발생하면 일본（UTC+9）은 이미 다음 날이 될 수 있습니다.

### Q: 한국 음력의 `cycle`이 중국과 다른 이유는？

한국 역법은 단군기원（기원전 2333년）을 사용하여 중국 기원보다 297년 늦기 때문입니다. 단 `gregorianYear`은 동일합니다.

### Q: IIFE 형식 사용법은？

```html
<script src="dist/chinese-lunar-date.iife.js"></script>
<script>
  const date = ChineseDate.ChineseDate.fromGregorian(2024, 6, 21)
</script>
```

---

## 피드백 및 협력

사용 중 문제가 발생하거나 기능 제안, 비즈니스 협력 등이 필요하신 경우 이메일로 연락해 주세요：

📧 **gyfinjava@163.com**

---

## 19. 아키텍처 및 설계 원칙

- **불변 값 객체** — 인스턴스 생성 후 변경 불가
- **순수 함수 코어** — 저수준 알고리즘은 모두 순수 함수
- **설정 구동** — 다른 역법을 `CalendarConfig`로 구분
- **캐시 최적화** — 천문 계산 결과 자동 캐시
- **TypeScript 우선** — 네이티브 TypeScript, 완전 타입 정의

---

## 20. 업데이트 로그

### 1.0.0

- 최초 릴리스
- 중국 / 일본 / 한국 / 베트남 4종 음력 변형 지원
- 6개 언어 / 지역 지원
- 간지（연월일 삼주）
- 띠（다국어 + Emoji）
- 24절기 계산
- 13종 전통 명절
- 포맷（5종 내장 + 커스텀 패턴）
- 자체 개발 경량 천문 모듈（VSOP87 절단 데이터）
- IIFE 압축 후 ~47 KB（gzip ~16 KB）