ziwei-doushu 딥다이브
— 동양 점성술 "자미두수"를 코드로 푼 오픈소스 엔진

1프로젝트 한줄 요약

"생년월일시를 입력하면, 자미두수 점성술의 명반을 자동으로 그리고 길흉 격국까지 판정해 주는 웹 계산 엔진"입니다. 점술 그 자체보다도, 천문 계산 + 규칙 기반 패턴 인식 + 지식 베이스가 하나로 묶인 도메인 엔진의 구조가 학습 가치의 핵심입니다. 별점 앱이 아니라 "규칙이 복잡한 도메인을 코드로 모델링하는 법"의 교본으로 읽으세요.

2왜 주목받는가

① "닫힌 전통 지식"을 통째로 MIT 라이선스로 열었다

자미두수는 보통 비싼 강의나 폐쇄적인 유료 앱으로만 접할 수 있었습니다. 이 레포는 배치 알고리즘 · 사화 시스템 · 1,100줄짜리 격국 지식 베이스 · 고전 원문 데이터를 전부 코드로 공개했습니다. README는 한발 더 나아가 51만 8,400개의 명반 샘플 데이터셋(5.5GB)까지 GitHub Releases로 풀었습니다 — 소형 모델 파인튜닝·RAG 검색 소스로 쓰라는 의도입니다.

② AI 시대의 "도메인 지식 공급원"이라는 포지셔닝

이 프로젝트의 진짜 노림수는 점술 앱이 아니라 LLM에게 먹일 정형 지식입니다. README는 "AI 해석 프롬프트와 백엔드 API는 일부러 뺐으니, 공개된 지식 베이스를 근거로 /api/interpret를 직접 만들어 아무 LLM에나 붙이라"고 안내합니다. 격국 판정(코드) + 고전 원문(데이터) + 51만 샘플(파인튜닝) = 전통 점술을 위한 RAG/파인튜닝 풀스택 재료를 한 레포에 담은 셈입니다.

③ "유파 분쟁"을 코드 주석으로 못 박은 고집

자미두수에는 여러 유파가 있는데, 이 레포는 倪海厦(니하이샤)의 정통 노선을 따르며 "비성파(飛星派)"를 명시적으로 거부합니다. 코드 곳곳에 "사화성은 영원히 고정, 움직이지 않는다(四化星永遠固定不動)"는 주석이 박혀 있고, 비성파의 핵심 기법인 "궁간자화(宮干自化)"는 함수로 구현은 해놓되 배치 과정에서 일부러 비활성화했습니다. 학술적 입장을 코드 설계로 표현한 흔치 않은 사례입니다.

비슷한 선택지와의 비교

3기술 스택 전체 지도

이 레포는 평범한 Next.js 앱처럼 보이지만, 무게중심은 화면(프론트)이 아니라 lib/ 아래의 순수 함수·데이터에 있습니다. 계층별로 끊어 보면 이렇게 됩니다.

4아키텍처 심화 분석

전체 동작 흐름

설계 패턴 ① "외부 엔진 래핑 + 자체 타입 모델" (Anti-Corruption Layer)

핵심 함수 generateChart()는 점성 계산을 직접 하지 않고 iztro에 위임한 뒤, iztro의 출력을 이 프로젝트만의 타입 ZiweiChart로 다시 매핑합니다. 외부 라이브러리의 데이터 모양에 앱 전체가 종속되지 않도록 "번역 막(膜)"을 한 겹 둔 것입니다. DDD에서 말하는 부패 방지 계층(Anti-Corruption Layer)의 교과서적 예시입니다.

// lib/ziwei/algorithm.ts (요지)
const astrolabe = astro.bySolar(`${y}-${m}-${d}`, hour, gender, true, 'zh-CN');
const palaces = astrolabe.palaces.map(p => ({
  name: p.name,                              // 命宮·財帛·官祿…
  branch: p.earthlyBranch,
  stars: [...p.majorStars, ...p.minorStars, ...p.adjectiveStars]
           .map(s => ({ name:s.name, type: mapStarType(s),
                        brightness: mapBrightness(s.brightness) })),
}));
// → 외부 iztro 모델을 우리 ZiweiChart 타입으로 격리 변환

설계 패턴 ② 데이터 주도 룩업 테이블 (Table-Driven)

자미두수 규칙은 if-else 지옥이 되기 쉽습니다. 이 레포는 대신 규칙을 데이터(배열·맵)로 표현합니다. 대표가 사화표입니다 — 천간 10개 각각에 대해 [녹·권·과·기] 4개 별을 매핑한 2차원 표 하나로, 수십 줄의 분기를 인덱싱 한 번으로 대체합니다.

// lib/ziwei/constants.ts — 四化表 (일부)
export const SI_HUA_TABLE = {
  甲: ['廉貞','破軍','武曲','太陽'],   // [化祿, 化權, 化科, 化忌]
  庚: ['太陽','武曲','太陰','天同'],
  // … 천간 10개 전부
};
// 연도 → 천간 인덱스 : 결정론적 산식
const getYearStemIndex = (year) => (((year - 4) % 10) + 10) % 10;

설계 패턴 ③ 규칙 엔진 + 디스패처 (격국 판정)

가장 무거운 파일 patterns.ts(1,118줄)는 작은 규칙 엔진입니다. detectPatterns(chart) 하나가 detectJunChenQingHui()(군신경회), detectShaPoLang()(살파랑) 같은 독립된 판정 함수 41개를 차례로 호출합니다. 각 격국은 동일한 타입으로 표준화됩니다.

// 격국 타입 — 모든 패턴이 같은 모양
interface Pattern {
  name: string;
  level: 'excellent' | 'good' | 'neutral' | 'caution';  // 上格~惡格
  conditions: { required: ...; bonus: ...; breaking: ... }; // 必須/加分/破格
  source: string;   // 예: 《紫微斗數全書·君臣慶會格》 — 古書 출처 명시
}
// 기하 헬퍼 — 한 궁에서 三方四正 네 자리 계산
const sanFangSiZheng = (m) => [m, (m+4)%12, (m+8)%12, (m+6)%12];

핵심 데이터: 12궁과 14주성

5디렉토리 구조 해부

6학습 포인트

① 도메인 모델링 — 모호한 지식을 타입으로 굳히기

이 레포의 최고 교본 가치입니다. "운명"처럼 막연한 개념을 ZiweiChart → Palace[] → Star[], Pattern{level, conditions, source}처럼 닫힌 타입 계층으로 표현했습니다. 점술이 아니라 법률·세무·보험·게임 룰처럼 "전문가만 아는 복잡한 규칙"을 코드로 옮길 때 그대로 응용할 수 있습니다.

② 테이블 주도 개발 (Table-Driven) 실전

constants.ts의 SI_HUA_TABLE, TIANKUI_TABLE, LUCUN_TABLE은 분기문을 데이터로 바꾸는 기법의 살아있는 예제입니다. 조건이 많을수록 코드가 아니라 표를 늘리는 방식이 왜 유지보수에 유리한지 체감할 수 있습니다. 원전(전문가의 표)과 코드(프로그램의 표)가 1:1 대응돼 검증도 쉽습니다.

③ 외부 라이브러리 격리 (Wrapper/ACL 패턴)

generateChart()가 iztro를 직접 노출하지 않고 자체 타입으로 번역하는 방식은, 실무에서 결제 SDK·지도 API·LLM SDK 같은 외부 의존성을 다룰 때 그대로 쓰는 패턴입니다. 외부 모델이 바뀌어도 번역 함수 한 곳만 고치면 되는 안전망의 가치를 배울 수 있습니다.

④ 전통 도메인을 AI 학습 데이터로 정형화하기

"결정론적 엔진 → 전수 데이터 생성 → 파인튜닝/RAG"라는 파이프라인은 이 레포만의 독특한 학습거리입니다. 규칙이 명확한 도메인이라면 가능한 입력을 전수 계산해 (입력→출력) 쌍을 무한 생성할 수 있다는 발상은, 합성 데이터(synthetic data) 전략의 실전 예시입니다.

⑤ 정적 데이터로 만든 전문(full-text) 검색

classics/index.ts의 searchClassics(query)는 DB 없이 정적 TS 객체만으로 ±40자 문맥 스니펫과 <mark> 하이라이트를 만들어냅니다(HTML 이스케이프 포함). "검색에 꼭 DB·엘라스틱서치가 필요한 건 아니다"는 걸 보여주는 가벼운 예제입니다.

7하드웨어/시스템 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크