사주팔자 서비스를 직접 만들어보겠다는 생각, 한 번쯤 해본 사람이 많을 것이다. 운세 플랫폼 '점신'의 운영사 테크랩스는 2023년 매출 829억 원, 영업이익 100억 원을 기록했고, '포스텔러'는 같은 해 99억 원 매출을 올렸다. 한국 모바일 운세 시장은 약 3,000억 원, 오프라인까지 합치면 약 1조 4,000억 원 규모로 추산된다. 미국의 점성술 앱 Chani는 구독료만으로 연간 680만 달러(약 102억 원)를 벌어들인다. 돈이 되는 시장인 것은 확실하다.
문제는 진입 비용이다. 전문 업체에 사주 앱 외주를 맡기면 위시켓 기준 최소 600만 원(단순 정보 제공)에서 기능이 붙을수록 1,000~3,000만 원 이상 올라간다. 사주팔자 계산 로직 자체가 절기 기반 월주 산출, 둔간법 시주 계산, 60갑자 순환, 지장간, 12운성 등 고유한 규칙 덩어리라 일반 CRUD 앱보다 개발 난이도가 높기 때문이다.
하지만 2025~2026년 현재, 건당 과금형 운세 API, 한국천문연구원의 무료 음양력 Open API, GitHub의 만세력 라이브러리와 MCP 사주 서버, 바이브코딩 도구(Cursor, Claude Code)가 결합되면서 비개발자도 MVP를 직접 조립할 수 있는 환경이 열렸다. 거기에 AI 해석을 접목하면 건당 수십 원 수준의 비용으로 개인화된 상담급 결과를 만들 수 있다.
다만 한 가지 강력한 경고부터 해야 한다. 사주팔자로 본격적으로 돈을 벌겠다는 강력한 의지와 사업 계획이 아니라면, 서비스를 공개 배포하지 말고 자체 사용 목적으로만 개발하는 것을 권장한다. 이유는 명확하다. 생년월일시·성별이라는 개인정보를 수집하는 순간 개인정보보호법의 적용 대상이 되고, 2026년 2월 국회를 통과한 개정안에 따르면 중대한 개인정보 유출 사고 시 전체 매출액의 최대 10% 과징금이 부과된다. 보안 전문 인력 없이 1인이 운영하는 서비스에서 해킹 한 번이면 끝이다.
이 문서는 사주팔자 앱·사이트를 만드는 다섯 가지 경로를 전부 해부하고, AI 모델별 건당 해석 비용을 원화로 환산한 비교표, 만세력 계산의 기술 쟁점, 바이브코딩 실전 프로세스, 수익 모델, 그리고 개인정보 유출 위험과 보안 체크리스트까지 빠짐없이 다룬다.
1. 다섯 가지 개발 경로 — 비용·난이도·위험 전면 비교
1.1 경로 1: UN7 운세 API 건당 과금
-
UN7(un7.kr)은 일별운세·연간운세·평생운세를 RESTful API로 제공하는 국내 서비스다. 사업자등록번호가 있는 법인(AWN, 서울 강북구, 대표 한승범)이 운영하며 건당 과금 구조여서 DB 일괄 구매 비용 없이 시작할 수 있다. 사이트 주소: https://un7.kr/
-
API 엔드포인트는 세 가지다. 일간운세(
api.un7.kr/api/v1/day), 연간운세(api.un7.kr/api/v1/year), 평생운세(api.un7.kr/api/v1/life)이며, GET 방식으로 생년월일시·음양력 여부·대상 날짜를 파라미터로 보내면 JSON으로 운세 텍스트가 돌아온다. -
평생운세 한 건에 성격운·직업운·연애운·건강운·재물운·부부궁·배우자 외모·궁합 등 46개 항목이 포함된다. 테스트용 API 키(
943156c8f56a4c88fad1ba1379e3bf00)가 공개되어 있어 개발 단계에서 응답 구조를 먼저 확인할 수 있고, 실 서비스 전환 시 운영 키를 별도 발급받는다. -
장점: 초기 비용 극소, 구현 난이도 최하, 1~2주 내 MVP 가능. 단점: 운세 텍스트가 정형화되어 있어 차별화 어려움, 건당 비용이 트래픽에 비례 증가, API 제공사 의존도 높음.
1.2 경로 2: 직접 개발 — 만세력 계산 엔진 + AI 해석
-
사주팔자 계산(만세력)은 오픈소스 라이브러리로 직접 구현하고, 해석 부분만 GPT·Claude·Gemini 같은 AI에 맡기는 하이브리드 방식이다. min-inter.co.kr의 사주팔자 웹앱이 이 구조를 따른다.
-
핵심 장점은 해석 품질을 무한히 조절할 수 있다는 것이다. AI 시스템 프롬프트에 명리학 고전(적천수·궁통보감·자평진전·삼명통회)의 해석 원칙을 주입하고, 사주 원국 데이터를 구조화해서 전달하면 전문 상담사 수준의 결과가 나온다.
-
AI API 호출 비용은 뒤에서 상세하게 다루지만, 가장 저렴한 모델(Claude Haiku 4.5) 기준 건당 약 6원, 가장 비싼 모델(Claude Opus 4.6) 기준 건당 약 135원 수준이다. 하루 100건 해석해도 월 비용이 수만 원에 불과하다.
-
장점: 최대 차별화, 원가 통제, 확장성 무한. 단점: 만세력 계산 정확성 검증 필수, AI 프롬프트 설계 난이도 높음, 개발 기간 4~8주.
1.3 경로 3: 한국천문연구원 음양력 API(보조 도구)
-
한국천문연구원(KASI)은 공공데이터포털(data.go.kr)을 통해 음양력 변환·24절기·출몰시각 등 6종 Open API를 무료로 제공한다. 엔드포인트는
apis.data.go.kr/B090041/openapi/service/LrsrCldInfoService이며 JSON·XML 두 포맷을 지원한다. 한국 천문연구원 정부 API 활용 사이트 주소: https://astro.kasi.re.kr/information/pageView/31 -
개발·운영 계정 모두 자동승인, 이용허락 범위 제한 없음이므로 상업적 서비스에도 바로 활용할 수 있다. 음력일 기준 양력 변환, 양력일 기준 음력 변환, 특정 음력일 조회, 24절기 정보 조회 등이 가능하다.
-
한계: 이 API는 음양력 변환과 절기 날짜만 제공한다. 천간지지 배당, 둔간법 시주 계산, 대운 산출 등 사주 고유의 계산은 포함되어 있지 않으므로, 단독으로 사주팔자 계산이 불가능하다. 아래의 라이브러리와 조합해야 한다.
1.4 경로 4: MCP 사주 서버 — fortuneteller 프로젝트
-
GitHub의 hjsh200219/fortuneteller는 MCP(Model Context Protocol) 기반 사주 서버다. Claude Desktop 등 AI 클라이언트에서 사주 분석 도구를 직접 호출할 수 있다. MIT 라이선스이므로 상업적 활용이 가능하다. 깃헙 프로젝트 주소(MIT 오픈소스): https://github.com/hjsh200219/fortuneteller
-
7가지 통합 도구를 제공한다:
analyze_saju(기본 분석·운세·용신·학파 비교·용신 판정법 5가지 모드),check_compatibility(궁합),convert_calendar(음양력 변환, 1900~2200년),get_daily_fortune(일일 운세),get_dae_un(10년 대운),get_fortune_by_period(연·월·시·다년 운세),manage_settings(해석 가중치 설정). -
1900~2200년까지의 절기 데이터·음력 테이블·한국 162개 지역 경도 테이블을 내장하고 있어 외부 API 호출 없이 오프라인 계산이 가능하다. 15종 신살, 지장간 강도, 격국 판정, 용신 산출까지 포함한다.
-
npm 패키지(
@hoshin/saju-mcp-server)로 배포되어 있고 Docker·Smithery 원클릭 설치도 지원한다. 웹 서비스 백엔드로 응용하려면 MCP 프로토콜 대신 Express·Fastify 같은 HTTP 서버로 감싸서 REST API로 노출하는 방식이 일반적이다.
1.5 경로 5: manseryeok 라이브러리 — 순수 계산 엔진
-
GitHub의 yhj1024/manseryeok은 TypeScript 기반 순수 만세력 계산 라이브러리다.
npm install manseryeok으로 설치하며, 핵심 함수calculateFourPillars에 연·월·일·시·분을 넣으면 사주 원국(천간지지)을 반환한다. 깃헙 프로젝트 주소(MIT 오픈소스): https://github.com/yhj1024/manseryeok -
분 단위 계산, 음력 입력(
isLunar: true), 윤달 처리(isLeapMonth),solarToLunar·lunarToSolar변환을 모두 지원한다. 커버 범위는 1900~2100년이다. -
해석 로직은 없으므로, 이 라이브러리로 사주 원국을 계산한 뒤 AI API에 넘겨서 해석을 받는 조합이 가장 효율적이다. 브라우저에서도 동작하므로 서버 없이 클라이언트 측 계산이 가능하다는 것이 큰 장점이다.
| 개발 경로 | 초기 비용 | 기술 난이도 | 개발 기간(1인) | 해석 차별화 | 유지보수 | 확장성 |
|---|---|---|---|---|---|---|
| UN7 API 건당 과금 | API 건당 비용만 | 하 | 1~2주 | 불가(정형 텍스트) | 하 | 제한적 |
| 직접 개발(만세력+AI) | AI API 비용만 | 중상 | 4~8주 | 무한 | 중 | 매우 높음 |
| 한국천문연구원 API | 무료 | 중 | 보조 도구 | 해당 없음 | 하 | 음양력 한정 |
| MCP 사주 서버 | 무료(MIT) | 중 | 2~4주 | 높음(AI 조합 시) | 중 | 높음 |
| manseryeok 라이브러리 | 무료(MIT) | 중하 | 1~2주(계산만) | AI 조합 필요 | 하 | 계산 한정 |
핵심 포인트: 사업 목적이 아닌 개인 사용이라면 manseryeok + AI API 조합을 로컬에서 돌리는 것이 가장 안전하다. 서버에 타인의 생년월일을 저장하지 않으므로 개인정보보호법 적용 대상 자체가 되지 않는다.
2. AI 모델별 사주 해석 건당 비용 — KIE.ai 기준 원화 환산
사주 해석 한 건에 AI API를 호출할 때, 입력(사주 원국 데이터 + 시스템 프롬프트)은 약 1,500~2,000토큰, 출력(해석 텍스트)은 약 1,000~2,000토큰 정도 소모된다. 아래 표는 KIE.ai(kie.ai) 기준 가격이며, 1크레딧 = $0.005, 환율 1,500원/USD로 환산했다. KIE.ai는 공식 가격 대비 60~75% 할인된 단가를 제공하는 API 게이트웨이다.
Kie AI API 저렴하게 호출하는 사이트: https://min-inter.co.kr/link/kie-ai-api
2.1 모델별 입출력 단가 비교
| 모델 | 입력 (100만 토큰당) | 출력 (100만 토큰당) | 건당 추정 비용 (원) | 특징 |
|---|---|---|---|---|
| Claude Haiku 4.5 | $0.35 (70크레딧) | $1.75 (350크레딧) | 약 6~8원 | 최저가, 빠른 응답, 간단 해석에 적합 |
| Gemini 3.1 Pro | $0.50 (100크레딧) | $3.50 (700크레딧) | 약 9~12원 | 가성비 우수, 긴 컨텍스트 |
| GPT-5 Codex | $0.50 (100크레딧) | $4.00 (800크레딧) | 약 10~13원 | 코드+텍스트 겸용 |
| GPT-5.2 | $0.44 (87.5크레딧) | $3.50 (700크레딧) | 약 8~12원 | 입력 단가 최저급 |
| GPT-5.4 / GPT-5.4 Codex | $0.70 (140크레딧) | $5.60 (1,120크레딧) | 약 13~18원 | 고성능, 복잡한 해석 |
| Claude Sonnet 4.5 / 4.6 | $1.05 (210크레딧) | $5.25 (1,050크레딧) | 약 13~17원 | 균형형, 품질 우수 |
| Claude Opus 4.5 / 4.6 | $1.75 (350크레딧) | $8.75 (1,750크레딧) | 약 22~27원 | 최고 품질, 심층 해석 |
2.2 건당 비용 계산 예시
-
Claude Haiku 4.5로 간단한 사주 해석 1건(입력 2,000토큰, 출력 1,500토큰): 입력 $0.35 x 0.002 = $0.0007, 출력 $1.75 x 0.0015 = $0.002625, 합계 $0.003325 x 1,500원 = 약 5원.
-
Claude Opus 4.6으로 심층 종합 분석 1건(입력 3,000토큰, 출력 3,000토큰): 입력 $1.75 x 0.003 = $0.00525, 출력 $8.75 x 0.003 = $0.02625, 합계 $0.0315 x 1,500원 = 약 47원.
-
월간 비용 시뮬레이션: 하루 100건 x 30일 = 월 3,000건. Haiku 기준 약 15,000원/월, Opus 기준 약 141,000원/월. Gemini 3.1 Pro 기준 약 30,000원/월.
| 월 이용량 | Claude Haiku 4.5 | Gemini 3.1 Pro | Claude Sonnet 4.6 | Claude Opus 4.6 |
|---|---|---|---|---|
| 월 1,000건 | 약 5,000원 | 약 10,000원 | 약 15,000원 | 약 47,000원 |
| 월 3,000건 | 약 15,000원 | 약 30,000원 | 약 45,000원 | 약 141,000원 |
| 월 10,000건 | 약 50,000원 | 약 100,000원 | 약 150,000원 | 약 470,000원 |
| 월 100,000건 | 약 50만 원 | 약 100만 원 | 약 150만 원 | 약 470만 원 |
핵심 포인트: Haiku 4.5로 기본 해석을 제공하고, 유료 사용자에게만 Opus 4.6 심층 분석을 제공하는 이중 구조가 원가 최적화의 핵심이다. 월 1만 건까지는 Haiku 기준 5만 원, Opus 기준 47만 원이면 충분하다.
3. 만세력·음양력 계산의 다섯 가지 기술 쟁점
사주팔자 서비스의 신뢰도는 계산의 정확성에 달려 있다. 같은 생년월일시를 넣었는데 앱마다 결과가 다르면 사용자는 즉시 이탈한다.
3.1 절기 기준 월주·태양시 보정·자시대 처리
-
절기 기준 월주: 사주의 월주는 음력 1일이 아니라 절기(節氣) 기준으로 바뀐다. 입춘(양력 2월 3~5일)부터 인월이 시작되고, 24절기 중 '절(節)'에 해당하는 12개가 월주 전환점이다. 절기가 들어오는 정확한 시·분이 매년 다르므로, 한국천문연구원 데이터나 fortuneteller의 내장 절기 테이블로 분 단위까지 확보해야 한다.
-
태양시(진태양시) 보정: 한국 표준시(KST)는 동경 135도 기준이지만 서울은 동경 약 127도로, 실제 태양과 약 32분 차이가 난다. 이 차이로 시주가 달라질 수 있다. 보정 공식은 (출생지 경도 - 135) x 4분이다. fortuneteller는 162개 지역 경도 테이블을 내장하고 있다.
-
자시대(夜子·早子): 23:00~01:00 자시 구간에서 23:00~00:00을 그날의 '밤자시(夜子)'로 볼지, 다음 날의 '이른 자시(早子)'로 볼지 학파마다 다르다. 일주(日柱)가 달라지면 사주 해석 전체가 바뀌므로, 일반·야자·조자 세 가지 옵션을 사용자에게 제공하는 것이 업계 표준이다.
3.2 윤달 처리·서머타임 보정
-
음력 윤달: 약 3년마다 삽입되는 윤달에 태어난 사람의 날짜를 잘못 변환하면 한 달가량 어긋난다. 사용자 입력 화면에서 음력 선택 시 윤달 여부 체크박스를 반드시 노출하고, 해당 연도에 실제 윤달이 존재하는지 유효성 검증 로직을 넣어야 한다.
-
서머타임(일광절약시간): 한국은 1948~1951년, 1955~1960년, 1987~1988년에 서머타임을 시행했다. 이 기간 출생자의 시각은 현재 시계보다 1시간 앞당겨져 기록되었으므로 1시간을 빼야 정확하다. 서머타임 기간 자동 보정 또는 수동 선택 옵션을 제공해야 한다.
-
검증 방법: 최소 20개 이상의 테스트 케이스(절기 경계, 자시대, 윤달, 서머타임 기간 포함)에 대해 한국천문연구원 만세력이나 도사폰 같은 검증된 전문 도구의 결과와 1:1 대조한다.
4. 바이브코딩으로 사주 앱 만들기 — 실전 프로세스
바이브코딩은 자연어로 AI에게 코드를 지시해서 앱을 만드는 방식이다. Cursor, Claude Code, Windsurf, Google AI Studio가 대표 도구다. 사주팔자 앱은 계산 로직이 명확하고 UI가 비교적 단순해서 바이브코딩 입문 프로젝트로 적합하다.
4.1 6단계 진행 순서
-
기획 문서(PRD) 생성: AI에게 기능 명세를 먼저 만들게 한다. 입력 화면(양력/음력, 윤달, 생년월일시, 성별, 태양시 보정, 야자/조자 옵션), 결과 화면(사주 원국표, 오행 분포 시각화, 해석 텍스트), 추가 기능(궁합, 대운, 연간 운세)을 구체적으로 정의한다.
-
만세력 엔진 선택 및 설치:
npm install manseryeok또는 fortuneteller 프로젝트를 클론한다. Cursor에서 'manseryeok 라이브러리를 사용해서 생년월일시를 입력받아 사주 원국을 계산하고, 오행 분포를 객체로 반환하는 함수를 만들어줘'라고 지시하면 기본 구조가 잡힌다. -
AI 해석 연동: KIE.ai 또는 공식 API를 통해 AI 모델을 호출한다. 시스템 프롬프트에 격국 판단법, 용신 선정 기준, 십신 해석 원칙, 12운성 의미, 합충형파해 규칙, 출력 형식을 명시한다.
-
프론트엔드 구현: Next.js·React(웹) 또는 Flutter(앱)를 선택한다. '사주 입력 폼과 결과 표시 화면을 만들어줘. 모바일 반응형으로. 오행별 색상(목-녹색, 화-적색, 토-황색, 금-백색, 수-흑색)을 적용해서 원국표를 시각화해줘'처럼 지시한다.
-
보안 점검: 이 단계가 가장 중요하다. AI가 생성한 코드에서 API 키 하드코딩, 입력값 미검증, HTTPS 미적용 등을 반드시 수동으로 확인한다.
-
배포: 개인 사용이면 로컬 실행으로 충분하다. 공개 서비스라면 Vercel(웹), Google Play(안드로이드), App Store(iOS)에 배포하되, 개인정보처리방침·면책조항 게시가 필수다.
5. 개인정보 유출 위험과 보안 — 사업이 아니라면 공개하지 마라
이 섹션이 이 문서에서 가장 중요한 부분이다. 사주팔자 서비스는 생년월일시·성별이라는 개인정보를 다루며, 이 데이터가 유출되면 보이스피싱·스미싱의 표적 정보로 악용될 수 있다. 2026년 2월 MBN 팩트체크 보도에서도 'AI 사주 서비스의 개인정보 유출 가능성'이 절반의 사실로 판정된 바 있다.
5.1 개인정보보호법 — 2026년 강화된 처벌 수위
-
2026년 2월 12일 국회 본회의를 통과한 개인정보보호법 개정안에 따르면, 중대한 개인정보 유출 사고에 대해 전체 매출액의 최대 10% 과징금을 부과할 수 있다. 매출액이 없거나 산정이 곤란한 경우에도 50억 원 이하 범위에서 과징금이 부과된다.
-
기존에도 2021~2024년간 공공부문 개인정보 유출 사고의 95.5%가 외부 해킹에 의한 것이었고, 사건당 평균 과징금은 약 7억 원, 과태료는 약 617만 원 수준이었다.
-
1인 개발자가 운영하는 소규모 서비스라 해도 예외가 아니다. 개인정보보호법은 처리하는 개인정보의 규모가 아니라 수집 행위 자체에 적용된다.
5.2 사주 서비스에서 수집하는 개인정보의 법적 분류
-
생년월일: 개인정보보호법상 '개인정보'에 해당한다. 다른 정보와 결합 시 특정 개인 식별이 가능하기 때문이다. 다만 건강·성생활 등 '민감정보'에는 해당하지 않아 별도 민감정보 동의는 불필요하다.
-
성별·이름: 역시 개인정보다. 특히 이름+생년월일+성별의 조합은 개인 식별력이 매우 높다.
-
출생 시각·출생지: 그 자체로는 식별력이 낮지만, 생년월일·이름과 결합되면 개인정보로 간주된다.
5.3 자체 사용 vs 공개 서비스 — 위험도 비교
| 항목 | 자체 사용(로컬/비공개) | 공개 서비스(웹·앱) |
|---|---|---|
| 개인정보보호법 적용 | 비적용 (본인 정보만 처리) | 적용 (타인 정보 수집) |
| 개인정보처리방침 | 불필요 | 필수 게시 |
| HTTPS | 불필요 | 필수 |
| 해킹·유출 위험 | 거의 없음 | 상시 존재 |
| 과징금·과태료 위험 | 없음 | 매출액 10%까지 |
| 면책조항 | 불필요 | 필수 |
| 앱 스토어 심사 | 해당 없음 | 통과 필수 |
| 서버 비용 | 없음 (로컬) | 월 수만~수십만 원 |
5.4 그래도 공개 서비스를 하겠다면 — 보안 체크리스트
-
HTTPS 필수 적용: 생년월일 데이터가 평문으로 전송되면 안 된다. Let's Encrypt 무료 SSL이면 충분하다.
-
서버 측 데이터 최소화: 가능하면 사주 계산을 클라이언트(브라우저) 측에서 수행하고, 서버에 생년월일을 저장하지 않는 구조가 이상적이다. manseryeok은 브라우저에서 동작하므로 이 구조가 가능하다.
-
비회원 즉시 파기 원칙: 회원가입 없이 이용하는 경우, 결과 제공 후 서버 메모리에서 입력 데이터를 즉시 삭제한다. DB에 저장 자체를 하지 않는 것이 가장 안전하다.
-
API 키 보호: UN7 API 키, AI API 키를 프론트엔드 코드에 절대 노출하면 안 된다. 반드시 백엔드 프록시를 통해 호출하고 환경 변수(
.env)로 관리한다. 바이브코딩으로 생성된 코드에서 API 키가 하드코딩되어 있는지 배포 전 반드시 검색한다. -
로그 관리: 서버 로그에 사용자 생년월일이 남지 않도록 로그 정책을 설정한다. 디버깅용이라면 마스킹 처리(예: 1990--)를 적용한다.
-
입력값 검증: SQL 인젝션, XSS 공격을 방지하기 위해 모든 사용자 입력에 대한 서버 측 검증을 수행한다. 생년월일 필드에 스크립트를 주입하는 공격은 실제로 흔하다.
-
접근 통제: 관리자 페이지에 2단계 인증(2FA) 적용, 데이터베이스 접근 권한 최소 인원 제한.
-
개인정보처리방침 필수 기재: 수집 항목(필수: 성별·달력구분·생년월일·출생시분 / 선택: 이름·출생지), 수집 목적, 보유 기간, 파기 절차, 14세 미만 아동 보호 조치, 개인정보보호 책임자 연락처를 명시한다.
-
면책조항 게시: '본 서비스는 전통 명리학을 기반으로 한 참고 정보이며, 의료·법률·재정 상담을 대체하지 않습니다. 중요한 결정은 전문가와 상의하십시오.' — 이 문구를 앱 내 눈에 띄는 곳과 이용약관에 반드시 포함한다.
-
앱 스토어 심사 대비: Apple App Store는 개인정보처리방침 URL 제출 필수, Google Play는 데이터 안전 섹션에 수집 항목을 정확히 기재해야 한다. 연령 제한은 전체이용가(4+)로 설정하는 것이 일반적이다.
6. 실전 개발 참고 문서 — 사주·만세력형 웹앱 아키텍처
아래는 Next.js App Router 기반 모노레포에서 사주팔자·대운·AI 해석 기능을 제공하는 SPA를 실제로 구축할 때 참고할 수 있는 개발 문서다. 디렉터리·파일·API 경로·스토리지 키는 모두 가상의 이름으로 표기했으며, 배포 URL·API 키·토큰·.env 값은 기록하지 않는다. 운영 시 필요한 환경 변수 이름은 코드 검색으로 확인하고, 값은 비밀 관리 도구에만 둔다.
실전 사이트 예시 큐레이터 단비 개발: https://min-inter.co.kr/data-analysis/saju-palja-four-pillars-destiny 사주 명리 마스터 프롬프트 예시: https://min-inter.co.kr/youtube-curator-danbi/easy-ai-agent-persona-and-prompt
| 항목 | 내용 |
|---|---|
| 문서 버전 | 1.0 |
| 기준일 | 2026-04-11 |
| 대상 | 모노레포 내 사주(四柱)·대운·AI 해석 기능을 제공하는 운세 분석 카테고리 SPA |
6.1 목적과 범위
이 문서의 목적은 생년월일시(양력/음력, 시·분, 지역 보정 옵션)를 입력받아 사주 팔자·대운 등 구조화 데이터를 계산하고, 선택적으로 LLM 스트리밍 해석을 제공하는 클라이언트·서버 구조를 기술하는 것이다. 범위는 해당 SPA 모듈, 연동 API 라우트, 공용 보안·AI 설정과의 관계, 주요 의존성 버전이며, 다른 앱이나 본 앱이 직접 쓰지 않는 인프라는 비범위에 해당한다.
6.2 기술 스택 요약
| 구분 | 기술 | 버전 기준 |
|---|---|---|
| 런타임 | Node.js | >=24.0.0 |
| 패키지 매니저 | npm | >=9.0.0 |
| 프레임워크 | Next.js (App Router) | ^16.x |
| UI | React / React DOM | ^19.x |
| 언어 | TypeScript | ^5.9.x (dev) |
| 스타일 | Tailwind CSS | ^3.4.x (dev) |
| 만세력·사주 계산 | manseryeok | ^1.0.x |
| 스키마 검증 | zod | ^4.x |
| 날짜 처리 | date-fns | ^4.x |
| AI SDK | @ai-sdk/openai, @ai-sdk/react | ^2.x |
| 마크다운/표현 | react-markdown, dompurify 등 | 프로젝트 설정 참고 |
루트는 단일 package.json을 사용하므로 위 버전은 앱 전용이 아니라 워크스페이스 전체 기준이다.
6.3 디렉터리 구조
아래는 완전히 가상의 경로명이며, 실제 프로젝트에서는 자신의 네이밍 규칙에 맞게 변경해야 한다.
앱 루트 — app/(modules)/fortune-tools/saju-destiny/ 하위에 page.tsx(단계형 입력·결과 오케스트레이션)와 layout.tsx(앱 레이아웃·메타)가 최상위에 위치한다.
ui-parts 디렉터리 — birth-form/(생년월일·장소·분석 유형 UI), reading-select/(분석 종류·상세 질문 선택), outcome-view/(표·타임라인·종합 뷰), day-planner/(일운 캘린더 UI), common/(공유 버튼 등)으로 나뉜다.
custom-hooks 디렉터리 — usePillarEngine.ts(사주·대운 계산 + 히스토리 저장 트리거), useLlmStream.ts(스트리밍 분석 요청), useRuleBasedReading.ts(규칙 엔진 기반 일관 분석) 세 개의 커스텀 훅이 핵심이다.
core 디렉터리 — pillar-calc/(계산기, 대운, 십신, manseryeok 래퍼 등), http-client/(클라이언트→내부 API fetch 래퍼), ai-templates/(시스템 페르소나·프롬프트 템플릿), interpretation-db/(JSON 규칙·해석 테이블·룰 엔진), helpers/(날짜, 클립보드, 조회 기록)로 구성된다.
models 디렉터리 — PillarInput, PillarResult, NatalInfo 등 타입 정의 파일이 위치한다.
API 라우트 — app/api/fortune-stream/ 하위에 POST 스트리밍 라우트(handler.ts)가 위치하며, 보안·레이트리밋·업스트림 LLM 호출을 담당한다.
프로젝트 루트 공용 모듈 — shared/guard.ts(동일 출처 검사, 레이트 리밋, 로깅)와 shared/llm-config.ts(모델·엔드포인트·환경 변수 로딩)가 있다. 키 값은 환경 변수에서만 읽는다.
모노레포의 앱 레지스트리 모듈에 slug·카테고리·메타가 등록되어 홈·라우팅과 연결된다.
6.4 데이터 흐름
전체 데이터 흐름은 다음 6단계로 정리된다.
-
입력 — 사용자가 생년월일시·달력 종류·성별·야자/조자·지역 시각 보정 등을 제출한다.
-
클라이언트 계산 —
usePillarEngine훅이core/pillar-calc/main-calculator를 호출하고, 만세력 엔진으로 년·월·일·시 기둥을 산출한다. 절기 데이터는 앱 내 로컬 테이블을 사용하며 외부 천문 API에 의존하지 않는다. -
대운 산출 — 일간·월주·성별·생년 등을 넘겨 대운 배열을 계산한다.
-
히스토리 저장(선택) — 계산 성공 시 브라우저 localStorage에 최근 조회를 제한 개수만큼 저장할 수 있다. 생년월일 등 민감정보이므로 제품 정책·개인정보 문구와 반드시 맞춰야 한다.
-
AI 해석 요청 — 클라이언트가 상대 경로 내부 API로 systemPrompt·userPrompt·구조화된 사주·대운 데이터를 POST 전송한다.
-
LLM 스트리밍 응답 — API 라우트에서만 외부 LLM 게이트웨이를 호출하고, SSE 유사 스트림 형태로 클라이언트에 토큰을 전달한다.
흐름을 도식화하면, 입력 폼 → 계산 훅 → 만세력·대운 모듈 → React 상태 → 결과 UI 경로와, React 상태 → 내부 API POST → 외부 LLM 게이트웨이 → SSE 스트림 → 결과 UI 경로가 병렬로 존재한다.
6.5 주요 모듈 역할
| 역할 | 가상 모듈명 | 설명 |
|---|---|---|
| 통합 계산 진입점 | core/pillar-calc/main-calculator.ts |
입력 정규화, 만세력 엔진 호출, 절기·지역 보정 정보 부착 |
| 기둥 산출 코어 | core/pillar-calc/korean-calendar-engine.ts |
manseryeok 기반 상세 기둥 계산 |
| 대운 | core/pillar-calc/grand-fortune.ts |
대운 기둥·나이 구간 |
| 십신·오행 등 | core/pillar-calc/celestial-relations.ts, five-phase-breakdown.ts |
표시용 도메인 로직 |
| 규칙 기반 해석 | core/interpretation-db/matcher/* |
JSON 규칙 + 일관된 텍스트 분석 |
| LLM 프롬프트 | core/ai-templates/character.ts, blueprints.ts |
시스템 페르소나·유저 프롬프트 생성 |
| 스트리밍 클라이언트 | core/http-client/stream-fetcher.ts |
내부 API fetch + ReadableStream 파싱 |
| 서버 프록시 | app/api/fortune-stream/handler.ts |
동일 출처 검사, 레이트 리밋, 본문 크기 제한, 업스트림 호출 |
6.6 API 라우트 동작 개요
메서드는 POST이며, 클라이언트가 넘긴 systemPrompt·userPrompt를 검증한 뒤 서버에서만 LLM API를 호출하고 토큰 스트림을 클라이언트로 전달한다.
보안 처리 개념 — 동일 출처(Origin/Referer) 검사 실패 시 403 응답, IP 기준 레이트 리밋(분당 요청 수 상한), JSON 본문 파싱 실패 시 400, 과대 본문 시 413 및 보안 로그 기록, API 키 유효성 실패 시 구체 사유 없이 500으로 응답하여 키 노출을 방지한다.
6.7 환경 변수·비밀 유출 방지 규칙
| 원칙 | 설명 |
|---|---|
| 문서에 값 금지 | API 키, JWT, DB URL, 프라이빗 엔드포인트 전체 URL 등 시크릿 값 일체 기록 금지 |
| 이름만 문서화 | 필요 시 내부 위키에 어떤 변수가 필요한지만 기록, 값은 CI/CD 시크릿에만 보관 |
| 코드 단일 진실 | LLM URL·모델 alias·키 읽기 위치는 프로젝트 공용 shared 모듈에 집중, 변경 시 한 곳만 수정 |
| 로그 정책 | 요청 본문 전체·생년월일시·이름을 서버 로그에 평문으로 남기지 않도록 정책 수립 |
클라이언트 번들에는 NEXT_PUBLIC_* 접두어 변수만 노출된다. LLM 키는 서버 전용 변수에만 둔다.
6.8 민감 데이터 처리 체크리스트
입력 데이터 — 생년월일·시각·성별·이름(선택)은 개인정보에 해당할 수 있으므로 수집 동의·처리 방침 게시가 필요하다.
localStorage — 최근 조회 캐시가 동일 기기·동일 브라우저에 평문으로 남을 수 있다. 민감도가 높으면 저장 자체를 하지 않거나, 암호화 또는 세션 스토리지만 사용하는 등 정책 검토가 필요하다.
LLM 전송 — 프롬프트에 생년월일 등 개인정보가 포함되면 제3자 처리자(LLM 제공사)의 데이터 처리 정책과 DPA(Data Processing Agreement)를 반드시 검토해야 한다.
에러 메시지 — 스택 트레이스·내부 경로가 사용자에게 노출되지 않도록 sanitize 패턴을 유지한다.
6.9 테스트·빌드·품질
앱 하위 specs/ 디렉터리에 계산 로직 단위 테스트가 존재할 수 있으며, E2E는 프로젝트 전역 playwright 설정을 따른다.
| 스크립트 | 용도 |
|---|---|
npm run dev |
개발 서버 |
npm run build |
프로덕션 빌드 |
npm run lint |
ESLint |
npm run type-check |
tsc --noEmit |
6.10 핵심 의존성 스냅샷 (2026-04-11 기준)
dependencies 주요 항목 — @ai-sdk/openai ^2.0.x, @ai-sdk/react ^2.0.x, ai ^5.0.x, date-fns ^4.x, dompurify ^3.x, framer-motion ^12.x, lucide-react ^0.562.x, manseryeok ^1.0.x, next ^16.x, react ^19.x, react-dom ^19.x, react-hook-form ^7.x, react-markdown ^10.x, recharts ^3.x, sharp ^0.34.x, zod ^4.x, zustand ^5.x.
devDependencies 주요 항목 — @modelcontextprotocol/sdk ^1.x, @playwright/test ^1.x, @tailwindcss/typography ^0.5.x, eslint ^9.x, eslint-config-next ^16.x, tailwindcss ^3.4.x, typescript ^5.9.x.
루트 단일 package.json을 사용하므로 앱이 직접 import하지 않는 패키지도 포함된다. 앱 전용 추가 패키지가 없다면 별도 package.json은 존재하지 않는다.
7. 수익 모델 — 단계별 확장 전략
7.1 5가지 수익 모델과 단계별 적합성
-
광고 수익: 무료 기본 운세 + 배너·전면 광고. 점신이 이 방식으로 초기에 연 23억 원 매출을 달성했다. 사용자 진입 장벽이 가장 낮아 트래픽 확보에 유리하다.
-
부분유료화(인앱 결제): 기본 운세 무료, 상세 분석(평생운·궁합·대운 등) 건당 1,000~5,000원. AI 해석 원가가 5~50원이므로 마진이 극히 높다.
-
구독 모델: 월 3,900~9,900원에 무제한 분석·월별 알림·맞춤 리포트 제공. 안정적 반복 매출이 가능하지만 충성 사용자 확보가 전제 조건이다.
-
디지털 굿즈: 부적 이미지, 용신 배경화면, 행운 아이템 판매. 원가 거의 없음.
-
전문가 연결 플랫폼: 실제 역술인과의 유료 상담 중개, 수수료 20~30%. 포스텔러가 이 모델을 병행한다.
| 수익 모델 | 초기 투자 | 사용자 장벽 | AI 원가 활용 | 적합 단계 |
|---|---|---|---|---|
| 광고 | 낮음 | 매우 낮음 | 무료 기능에 Haiku | 출시 직후 |
| 부분유료화 | 중간 | 낮음 | 유료에 Sonnet/Opus | 월 1만 MAU 이후 |
| 구독 | 높음 | 중간 | Opus 심층 분석 | 충성 사용자 확보 후 |
| 디지털 굿즈 | 매우 낮음 | 낮음 | AI 이미지 생성 | 전 단계 보조 |
| 전문가 연결 | 높음 | 중간 | 해당 없음 | 플랫폼 확장기 |
8. 마무리
위에서 살펴본 사주팔자 앱·사이트 개발의 핵심 내용을 정리하면 다음과 같습니다.
핵심 요약:
- UN7 운세 API는 건당 과금으로 1~2주 내 MVP가 가능하지만, 정형화된 텍스트 때문에 차별화가 어렵다. manseryeok 라이브러리 + AI 해석 조합은 4~8주 걸리지만 건당 5~50원 수준으로 개인화된 상담급 결과를 만들 수 있다
- KIE.ai 기준 AI 해석 비용은 Claude Haiku 4.5가 건당 약 5원, Gemini 3.1 Pro가 약 10원, Claude Opus 4.6이 약 47원이며, 월 1만 건 처리해도 5~47만 원 수준이다
- 만세력 계산에서 절기 기준 월주, 태양시 보정, 야자시·조자시, 윤달, 서머타임 — 다섯 가지 중 하나라도 틀리면 사주 원국 전체가 어긋난다
- 사업 목적이 아니라면 공개 배포하지 말고 자체 사용을 강력 권장한다. 개인정보보호법 개정으로 중대 유출 시 매출액 최대 10%, 매출 없어도 50억 원 이하 과징금이 부과된다
- 그래도 공개 서비스를 하겠다면 HTTPS·서버 측 데이터 미저장·API 키 보호·입력값 검증·개인정보처리방침·면책조항이 필수이며, 바이브코딩으로 생성된 코드의 보안 취약점을 반드시 수동 점검해야 한다
- 수익 모델은 광고→부분유료화→구독 순서로 확장하되, Haiku로 무료 기본 해석 + Opus로 유료 심층 분석이라는 이중 구조가 원가 최적화의 핵심이다
사주팔자에 대한 도메인 지식이 있고, 돈을 벌겠다는 의지가 확실하다면 바이브코딩으로 직접 만드는 것이 외주 비용 600~3,000만 원을 아끼는 가장 현실적인 방법이다. 하지만 보안에 자신이 없다면 절대로 타인의 생년월일을 서버에 저장하는 서비스를 공개하지 말아야 한다. 로컬에서 본인과 가족 사주만 보는 용도라면, 개인정보 걱정 없이 마음껏 AI 해석의 품질을 끌어올리는 데 집중할 수 있다.