IMSaju — 만세력 · 사주풀이 · 궁합

생년월일시로 만세력(사주 원국) 을 계산해 보여주고, 그 결과를 근거로 Gemini 가 풀이를 써 주는 웹앱. 두 사람의 직장 궁합도 본다.

가장 신경 쓴 것은 UI가 아니라 계산의 신빙성이다.

화면	내용
/	두 갈래 선택
/saju	개인 사주 — 원국·오행·대운·세운
/compatibility	궁합 — 사람 카드 두 장 + 관계 설정
/admin	풀이 프롬프트 편집 (비밀번호)

---

전체 기획은 docs/product-spec.md 에 정리돼 있다.

---

만세력을 믿을 수 있게 만든 방법

만세력 결과가 서비스마다 갈리는 지점은 네 군데뿐이다. 각각을 추정이 아니라 계산으로 처리했다.

1. 절기를 표가 아니라 천문 계산으로

월주·연주 경계는 음력 달이 아니라 태양의 겉보기 황경이 정한다. 근사표를 쓰면 절입일 근처 출생에서 반드시 틀린다. astronomy-engine 으로 절입 순간을 초 단위로 직접 구한다.

검증: 공표된 분점·지점 시각과 1분 이내, lunar-javascript 절기표와 2분 이내 일치 (tests/solarTerms.test.ts).

2. 과거 표준시·서머타임은 IANA tzdb에 위임

한국 표준시는 여러 번 바뀌었다. 이걸 손으로 표에 적으면 반드시 틀리므로, Node 내장 ICU의 tz 데이터베이스에서 그 시점의 실제 오프셋을 가져온다.

시기	오프셋
~1908	+08:27:52 (서울 지방 평균시)
1908~1912	+08:30
1912~1954	+09:00
1954~1961	+08:30
1955~1960 여름	+09:30 (서머타임)
1987~1988 여름	+10:00 (서머타임)
1961~	+09:00

3. 진태양시는 경도로

절대 시각(UTC)에 출생지 경도만 더하면 그 장소의 평균태양시가 된다. 서울(126.9784°E)은 한국 표준시 대비 −32분. 표준시가 +8:30이던 시기에도 분기 없이 맞는다. 균시차(최대 ±16분)까지 반영하는 옵션도 있다.

4. 관법 차이는 숨기지 않고 옵션으로

야자시, 진태양시 보정 방식, 음력 윤달(KASI 기준)을 사용자가 고를 수 있게 노출했다. 결과가 다른 서비스와 갈리는 마지막 원인은 계산 오류가 아니라 유파 차이이기 때문이다.

5. 계산 근거를 끝까지 들고 간다

적용된 표준시 오프셋, 서머타임 여부, 보정량, 월주 기준 절입 시각을 결과(chart.basis)에 함께 기록하고, 풀이를 만들 때 그대로 프롬프트에 싣는다. 같은 입력이면 같은 근거가 나오므로 결과를 언제든 되짚어 확인할 수 있다.

화면에는 띄우지 않는다 — 결과 화면은 원국·오행·십신·대운과 사주풀이에 집중시켰다.

6. 만세력에는 LLM을 쓰지 않는다

음↔양력 변환, 절기, 4주, 지장간, 십신, 12운성, 공망, 납음, 오행 분포, 대운, 세운 — 전부 서버 내 순수 계산이다. Gemini는 풀이 텍스트를 쓸 때만 호출한다.

• 같은 입력 → 항상 같은 원국. 재현·검증 가능하고 환각이 원리적으로 불가능하다.
• 만세력만 보고 나가면 API 할당량 소비는 0.

---

궁합

두 사람의 사주를 맞대어 직장에서의 결을 본다. 여기도 같은 원칙이다 — 합·충·형·해는 고정된 표라서 계산하고, Gemini는 그 결과를 해석만 한다.

보는 것: 일간끼리의 천간합·충과 십신 친화도, 연·월·일·시 지지의 육합·삼합·방합·충·형·해·파·원진, 그리고 오행 보완도.

자리별 가중치 — 직장 관계를 보므로 사회 활동 영역인 월지를 일지보다 높게 둔다.

자리	가중치	이유
일간	×3.0	두 사람 본질이 직접 만나는 자리
월지	×2.0	사회 활동과 직업 영역
오행 보완	×2.0	서로 부족한 기운을 채워 주는 정도
연지 · 일지	×1.5	사회적 위치 / 내면의 친밀도
시지	×1.0	실무와 결과

점수만 던지지 않는다. 어느 자리에서 어떤 관계로 몇 점이 나왔는지 항목별로 전부 공개하고 배점 규칙도 화면에서 펼쳐 볼 수 있다.

관계 설정 (상사-직원 · 선임-후임 · 동료, 방향 포함)은 수치를 바꾸지 않는다. 관계에 따라 가중치를 흔들면 점수의 근거를 설명할 수 없어지기 때문이다. 관계는 프롬프트에만 들어가 해석의 관점을 정한다. 이 결정은 테스트로 고정돼 있다.

사람 카드는 이 브라우저(localStorage)에만 저장된다. 타인의 생년월일을 다루므로 서버에 남기지 않고, 풀이·궁합을 계산할 때만 요청으로 나갔다 응답과 함께 사라진다. 30일 동안 쓰지 않은 카드는 브라우저에서도 지운다 (PROFILE_TTL_DAYS, src/lib/profiles.ts).

---

검증

npm test

테스트	내용
crosscheck.test.ts	lunar-javascript 와 1900~2050년 무작위 2,000건의 4주 완전 일치
solarTerms.test.ts	공표 분점·지점과 1분 이내, 독립 구현과 2분 이내
timezone.test.ts	표준시 이력·서머타임·진태양시·균시차
luck.test.ts	대운 순행/역행, 간지 배열, 시작 연도(독립 구현과 대조)
chart.test.ts	입춘·자시 경계, 음력 윤달, 시각 미상
validate.test.ts	잘못된 입력을 조용히 다른 값으로 바꾸지 않는지
compatibility.test.ts	합·충·형·해 표가 대칭이고 12지지를 빠짐없이 덮는지, 점수가 항목 가중합에서 유도되는지, 관계를 바꿔도 수치가 같은지
prompt.test.ts	템플릿이 변수를 빠뜨리지 않았는지, 렌더 후 {{...}} 잔여물이 없는지, 원국·대운이 실제로 들어갔는지

궁합 표는 손으로 적은 것이라 반드시 오타가 난다. 그래서 개별 사례뿐 아니라 표의 구조를 검사한다 — 육합은 두 인덱스의 합이 12로 나눈 나머지 1, 충은 차이가 6, 방합은 연속된 세 지지 … 이런 규칙성이 깨지면 바로 걸린다.

교차검증이 핵심이다. 독자 구현이지만 성숙한 라이브러리와 수천 건을 대조해 통과하므로 "신빙성 있다"고 말할 근거가 있다.

---

시작하기

npm install

.env.local 을 만들고 채운다 (.env.example 참고):

GEMINI_API_KEY=<Google AI Studio 키>
ADMIN_PASSWORD=<관리자 페이지 비밀번호>

Gemini 키가 살아 있는지 먼저 확인한다:

npm run check:gemini

접근 가능한 모델을 실제로 호출해 보고 폴백 체인을 알려 준다. 개발 서버 실행:

npm run dev

---

Gemini 연동에서 알아둘 것

무료 티어는 모델 하나를 고정할 수 없다. 실측 결과는 docs/gemini-findings.md 참고.

• Pro 계열은 429 로 사실상 사용 불가
• 최신 flash 계열은 503 이 상시적 — gemini-3.8-flash 는 5회 연속 실패하기도 한다
• lite 계열만 안정적
• 목록에 있어도 못 쓰는 모델이 있다 (gemini-2.5-flash 는 404)

그래서 src/lib/gemini.ts 는 품질 높은 순으로 시도하다 실패하면 내려가는 폴백 체인을 쓰고, 실패한 모델은 60초 쿨다운에 넣는다. 스트리밍 도중 끊긴 모델도 쿨다운 대상이라 「다시 생성」이 같은 불안정한 모델에 다시 걸리지 않는다.

중간에 끊긴 응답은 완성된 것처럼 보여주지 않고 잘렸다고 알린다.

특정 모델로 고정하려면 .env.local 에 GEMINI_MODEL=<모델명> 을 넣는다.

---

프롬프트 편집

/admin 에서 ADMIN_PASSWORD 로 로그인하면 사주풀이 프롬프트를 편집할 수 있다. 치환 미리보기와 샘플 사주 테스트 실행을 제공한다.

풀이 말투

사주아이를 레퍼런스로 잡았다. 친근한 현대 존댓말("…해요"), 독자는 "○○ 프로님", 짧은 문단.

다만 전문용어를 통째로 걷어내지는 않는다. 그러면 "왜 그렇게 읽는지"가 사라져 이 프로젝트의 강점이 무너진다. 일상어로 먼저 말하고 근거는 괄호에 붙인다.

안 씀:  갑목 일간이 묘월에 태어나 득령(得令)하였으므로 신강한 사주입니다.
씀:     민경 프로님은 봄의 한가운데 태어난 나무예요. 계절이 등을 밀어주는
        자리라 기본 체력이 든든한 편입니다. (갑목 일간 · 묘월생 · 득령)

사주아이의 약점으로 지적되는 "지나치게 긍정적으로만 흐른다"는 따라가지 않는다. 약점을 짚되 대처법을 같은 문단에 붙이게 했다.

말투는 코드가 아니라 편집 가능한 템플릿에 있다. 배포 없이 /admin 에서 바꿀 수 있다.

기본 템플릿은 prompts/default.md, 수정본은 data/prompt-<kind>.md 에 저장된다. 파일 쓰기가 막힌 배포 환경에서는 프로세스 메모리에만 남으므로, 영구 반영은 prompts/default.md 커밋이나 SAJU_PROMPT 환경변수로 한다.

사용 가능한 변수: {{name}} {{gender}} {{birth_summary}} {{manse_table}} {{ohaeng}} {{daewoon}} {{sewoon}} {{manse_json}}

---

구조

src/lib/saju/     계산 엔진 (LLM 없음)
  constants.ts      천간·지지·지장간·납음·12운성 등 고정 표
  time.ts           표준시 역산, 진태양시, 균시차
  solarTerms.ts     천문 계산 기반 24절기
  pillars.ts        연·월·일·시주
  analyze.ts        오행 분포, 십신, 신강·신약
  luck.ts           대운·세운
src/lib/gemini.ts   폴백 체인 + 쿨다운
src/lib/prompt.ts   템플릿 로드·변수 치환
src/app/api/        manse(계산) · reading(스트리밍 풀이) · admin

---

범위 밖

신살(12신살·길흉신), 궁합, 결과 공유 링크, 로그인, 결제.

면책

사주풀이는 전통 명리학 해석이며 참고용이다. 의료·법률·투자 판단의 근거로 삼지 말 것.