feat(saju-lab): solar_terms.py — sxtwl 기반 24절기 + 月支 매핑

saju-lab/tests/test_solar_terms.py

@@ -0,0 +1,129 @@
+"""solar_terms.py — sxtwl 기반 24절기 + 月支 매핑 테스트.
+
+⚠️ Reference fixture(`reference_saju.json`)의 month branch는 모두 "丑"으로 동일하다.
+이는 saju-web의 `solar-terms.ts`가 tsx 런타임에서 `require('solarlunar')`를 잡지 못해
+fallback(`return 23`, 大寒)으로 떨어지고, 大寒 → 丑 매핑이 적용된 결과로 보인다.
+따라서 reference fixture는 절기 검증에 사용할 수 없으며, 본 테스트는
+- 절기 boundary (입춘 day) 동작 검증
+- sxtwl JieQi index 순서 가정 검증
+- 月支 자체 일관성(여러 날짜에서 기대되는 月支 산출) 검증
+세 가지로 구성한다.
+"""
+import json
+from pathlib import Path
+
+import pytest
+
+from app.calculator import solar_terms as st
+
+
+REF_PATH = Path(__file__).parent / "fixtures" / "reference_saju.json"
+REF = json.loads(REF_PATH.read_text(encoding="utf-8"))
+
+BRANCHES = ["子", "丑", "寅", "卯", "辰", "巳", "午", "未", "申", "酉", "戌", "亥"]
+
+
+def test_jieqi_index_order_lichun_is_3():
+    """sxtwl JieQi index에서 立春은 3(冬至=0 기준 황경 +45°).
+
+    1995-02-04는 입춘 당일. sxtwl이 그 날짜에 jqIndex=3을 반환해야 함.
+    """
+    import sxtwl
+
+    qi_list = sxtwl.getJieQiByYear(1995)
+    # 1995-02-04 ±1일 안에 jqIndex=3인 항목이 있어야 함
+    found = False
+    for info in qi_list:
+        t = sxtwl.JD2DD(info.jd)
+        if int(info.jqIndex) == 3 and int(t.Y) == 1995 and int(t.M) == 2 and 3 <= int(t.D) <= 5:
+            found = True
+            break
+    assert found, "1995년 立春(jqIndex=3) 절기가 2/3~2/5 사이에서 발견되지 않음"
+
+
+def test_get_current_solar_term_ipchun_boundary():
+    """1995-02-04는 입춘 당일."""
+    idx_4 = st.get_current_solar_term(1995, 2, 4)
+    idx_5 = st.get_current_solar_term(1995, 2, 5)
+    idx_3 = st.get_current_solar_term(1995, 2, 3)
+    # 2/4와 2/5는 같은 절기 인덱스 (立春=3)
+    assert idx_4 == idx_5
+    # 2/3은 다른 인덱스 (立春 이전 — 大寒=2)
+    assert idx_4 != idx_3
+
+
+def test_get_solar_term_month_branch_ipchun_day():
+    """1995-02-04는 입춘 → 月支 = 寅(인덱스 2)."""
+    branch_idx = st.get_solar_term_month_branch(1995, 2, 4)
+    assert BRANCHES[branch_idx] == "寅"
+
+
+def test_get_solar_term_month_branch_before_ipchun():
+    """1995-02-03은 입춘 이전 → 月支 = 丑(인덱스 1)."""
+    branch_idx = st.get_solar_term_month_branch(1995, 2, 3)
+    assert BRANCHES[branch_idx] == "丑"
+
+
+@pytest.mark.parametrize(
+    "year,month,day,expected_branch",
+    [
+        # 표준 절기 경계 기준 月支 검증 (saju 일반 상식)
+        (1990, 5, 15, "巳"),    # 立夏(5/6) ~ 芒種(6/6) 사이 → 巳월
+        (1990, 6, 6, "午"),     # 芒種 당일 → 午월
+        (1980, 6, 6, "午"),     # 芒種 ~ 小暑 → 午월
+        (1995, 2, 5, "寅"),     # 立春 다음날 → 寅
+        (1995, 2, 3, "丑"),     # 立春 이전 → 丑
+        (2000, 2, 29, "寅"),    # 立春 이후 → 寅
+        (2010, 12, 31, "子"),   # 大雪 이후 → 子
+        (1985, 1, 1, "子"),     # 1/1은 小寒(1/5) 이전 → 子
+        (1985, 1, 20, "丑"),    # 小寒 이후 → 丑
+        (1972, 7, 24, "未"),    # 小暑 ~ 立秋 사이 → 未
+        (1992, 8, 8, "申"),     # 立秋 ~ 白露 → 申
+        (1988, 9, 9, "酉"),     # 白露 ~ 寒露 → 酉
+        (2005, 6, 22, "午"),    # 芒種 ~ 小暑 → 午
+        (2020, 9, 23, "酉"),    # 白露 ~ 寒露 → 酉
+    ],
+)
+def test_month_branch_standard_cases(year, month, day, expected_branch):
+    """일반 사주 상식 기준 月支 검증 — sxtwl 절기와 일치해야 함."""
+    branch_idx = st.get_solar_term_month_branch(year, month, day)
+    actual = BRANCHES[branch_idx]
+    assert actual == expected_branch, (
+        f"{year}-{month:02d}-{day:02d}: expected {expected_branch}, got {actual}"
+    )
+
+
+def test_get_days_to_next_solar_term_positive():
+    """다음 절기까지 일수는 항상 양수, 16일 이내."""
+    # 立春(2/4) 다음날 → 雨水(2/19)까지 약 15일
+    days = st.get_days_to_next_solar_term(1995, 2, 5)
+    assert 1 <= days <= 16, f"days = {days} (expected 1~16)"
+
+
+@pytest.mark.parametrize(
+    "case",
+    REF,
+    ids=lambda c: f"{c['input']['year']}-{c['input']['month']:02d}-{c['input']['day']:02d}",
+)
+def test_month_branch_matches_reference(case):
+    """Reference fixture의 month branch와 sxtwl 기반 절기 계산 일치.
+
+    ⚠️ 알려진 이슈: reference_saju.json의 모든 30 케이스 month branch가 "丑"으로 동일하다.
+    이는 saju-web `solar-terms.ts`가 tsx 런타임에서 solarlunar require 실패 →
+    `return 23` 폴백 → 大寒 → 丑으로 떨어진 reference 측 버그.
+
+    본 테스트는 BUGGY reference와 일치하는지 검증하기 위한 것이 아니라,
+    sxtwl 기반 계산이 reference와 자연스럽게 어긋남을 명시적으로 기록하기 위해 xfail로 마킹.
+    """
+    inp = case["input"]
+    expected_branch = case["expected"]["saju"]["month"]["branch"]
+    branch_idx = st.get_solar_term_month_branch(inp["year"], inp["month"], inp["day"])
+    actual_branch = BRANCHES[branch_idx]
+    if expected_branch == "丑":
+        pytest.xfail(
+            f"reference_saju.json buggy: 모든 케이스 month='丑'으로 고정. "
+            f"sxtwl 정답은 {actual_branch} (input={inp})"
+        )
+    assert actual_branch == expected_branch, (
+        f"mismatch for {inp}: got {actual_branch}, expected {expected_branch}"
+    )