gahusb
d87ad2421d
- saju-web (Next.js+Supabase+OpenAI) → saju-lab (Python FastAPI+SQLite+Claude) - agent-office 내 tarot 모듈 → 독립 tarot-lab 컨테이너 분리 - Phase 1 tarot 분리 (DB 마이그레이션 스크립트 + cutover) - Phase 2 saju 신설 (TS→Python 계산엔진 포팅 + 사주/궁합 v1) - 포트: tarot-lab 18250, saju-lab 18300 - API: /api/tarot/*, /api/saju/* 완전 이전 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
671 lines
29 KiB
Markdown
671 lines
29 KiB
Markdown
# saju-lab 신설 + tarot-lab 분리 — 마이그레이션 설계
|
|
|
|
**작성일**: 2026-05-25
|
|
**상태**: Spec (구현 plan 작성 전)
|
|
|
|
---
|
|
|
|
## 1. 목표
|
|
|
|
1. **saju-lab 신설**: 별도 디렉토리에 있던 `saju-web` (Next.js + Supabase + OpenAI) 프로젝트를 web-backend 모노레포의 한 lab 서비스로 마이그레이션. Python FastAPI + Claude + SQLite 패턴으로 단순화.
|
|
2. **tarot-lab 분리**: 현재 `agent-office` 컨테이너 내부 모듈로 들어 있는 tarot 기능을 독립 컨테이너로 분리. agent-office가 가벼워지고 tarot은 자체 라이프사이클을 가짐.
|
|
|
|
두 작업이 같은 패턴(독립 lab 컨테이너 신설)을 공유하므로 하나의 spec에 담아 순차 구현.
|
|
|
|
---
|
|
|
|
## 2. 배경
|
|
|
|
### 2-1. saju-web 현황
|
|
- 위치: `C:\Users\jaeoh\Desktop\workspace\saju-web`
|
|
- 스택: Next.js 16, TypeScript, Supabase(OAuth+DB), OpenAI gpt-4o, PortOne 결제, Kakao 공유
|
|
- 기능 4종: 사주분석(10토큰), 궁합(15토큰), 토정비결(5토큰), 오늘의 운세
|
|
- 핵심 자산: `lib/saju-calculator.ts`, `lib/ai-interpretation.ts`, `lib/daeun-calculator.ts`, `lib/solar-terms.ts` (계산 엔진 ~1500줄)
|
|
- 현재 사용 중이 아님. 자산 보존 + 패턴 일치화를 위한 마이그레이션
|
|
|
|
### 2-2. tarot-lab 현황
|
|
- 위치: `agent-office/app/tarot/` (모듈), `agent-office/app/routers/tarot.py`
|
|
- DB: `agent_office.db`의 `tarot_readings` 테이블
|
|
- API: `/api/agent-office/tarot/*` 6개 endpoint (interpret, save, list, get, patch, delete)
|
|
- 21개 단위 테스트 존재
|
|
- 문제: agent-office가 점점 비대해짐 (텔레그램·로또·주식·청약·유튜브·타로 모두 한 컨테이너에). tarot은 독립 도메인이라 분리가 자연스러움
|
|
|
|
### 2-3. 다른 lab 패턴 (참조 기준)
|
|
`insta-lab`, `music-lab`, `realestate-lab`은 모두 동일 패턴:
|
|
```
|
|
<lab>/
|
|
├── Dockerfile (python:3.12-slim)
|
|
├── requirements.txt
|
|
├── pytest.ini
|
|
├── tests/
|
|
└── app/
|
|
├── main.py (FastAPI)
|
|
├── config.py
|
|
├── db.py (SQLite)
|
|
└── <도메인 모듈들>
|
|
```
|
|
- 인증 없음 (개인 NAS 서비스)
|
|
- nginx가 `/api/<name>/`로 라우팅
|
|
- docker-compose의 한 항목으로 등록
|
|
- Gitea Webhook → deployer가 rsync + docker compose up -d --build
|
|
|
|
---
|
|
|
|
## 3. 핵심 결정 사항
|
|
|
|
| 항목 | 결정 |
|
|
|------|------|
|
|
| 백엔드 언어 | Python FastAPI (saju 계산 엔진은 TypeScript → Python 포팅) |
|
|
| AI 모델 | Claude Sonnet 4.6 (`claude-sonnet-4-6`) + prompt-caching beta. tarot과 일관 |
|
|
| DB | SQLite 로컬 (saju-lab은 `saju.db`, tarot-lab은 `tarot.db`) |
|
|
| 인증 | 없음 (다른 lab 패턴 일치). saju-web의 Supabase/PortOne/Kakao 제거 |
|
|
| saju-lab v1 기능 | 사주 분석 + 궁합 + 사주 결과 내 세운(歲運) (오늘의 운세는 세운으로 통합). 토정비결은 v2 |
|
|
| tarot DB 마이그레이션 | 1회성 복사 스크립트 (agent_office.db → tarot.db), cutover 후 agent-office tarot 모듈 완전 제거 |
|
|
| saju-lab UI | 시안 기반 신규 (시안 추후 제공, Phase 2 마지막 단계) |
|
|
| API prefix | `/api/saju/*`, `/api/tarot/*` (완전 이전) — `/api/agent-office/tarot/*`는 제거 |
|
|
| 포트 (내부) | tarot-lab 18250, saju-lab 18300 |
|
|
| 진행 순서 | Phase 1 tarot 분리 → Phase 2 saju 신설 |
|
|
|
|
---
|
|
|
|
## 4. 디렉토리 구조
|
|
|
|
```
|
|
web-backend/
|
|
├── tarot-lab/ # [신설]
|
|
│ ├── Dockerfile
|
|
│ ├── requirements.txt
|
|
│ ├── pytest.ini
|
|
│ ├── tests/
|
|
│ │ ├── test_db.py # agent-office/tests/test_tarot_db.py 이관
|
|
│ │ ├── test_schema.py
|
|
│ │ ├── test_pipeline.py
|
|
│ │ └── test_routes.py # 6 endpoint (interpret + readings CRUD 5)
|
|
│ └── app/
|
|
│ ├── __init__.py
|
|
│ ├── main.py # FastAPI app + /api/tarot/* 라우터 6개
|
|
│ ├── config.py # TAROT_MODEL, TAROT_COST_*, ANTHROPIC_API_KEY, TAROT_TIMEOUT_SEC
|
|
│ ├── db.py # tarot.db: 5 CRUD + _tarot_row_to_dict
|
|
│ ├── models.py # Pydantic 모델 5개 (TarotCardDraw, TarotInterpretRequest, TarotInterpretResponse, TarotSaveRequest, TarotPatchRequest)
|
|
│ ├── pipeline.py # Claude 호출 + reroll 1회
|
|
│ ├── prompt.py # SYSTEM_PROMPT + build_user_message
|
|
│ └── schema.py # validate_interpretation
|
|
│
|
|
├── saju-lab/ # [신설]
|
|
│ ├── Dockerfile
|
|
│ ├── requirements.txt # fastapi, httpx, anthropic, pydantic, sxtwl(절기/음력)
|
|
│ ├── pytest.ini
|
|
│ ├── tests/
|
|
│ │ ├── fixtures/
|
|
│ │ │ └── reference_saju.json # Node.js 원본에서 추출한 입력→출력 쌍
|
|
│ │ ├── test_core.py # 천간/지지/십성/십이운성/calculate_saju
|
|
│ │ ├── test_solar_terms.py # 24절기
|
|
│ │ ├── test_lunar.py # 음력 변환
|
|
│ │ ├── test_analysis.py # 오행/신강신약/용신/세운
|
|
│ │ ├── test_daeun.py
|
|
│ │ ├── test_shinsal.py # 신살/공망/지장간
|
|
│ │ ├── test_compatibility.py # 궁합 점수
|
|
│ │ ├── test_pipeline.py # Claude mock + reroll
|
|
│ │ ├── test_compat_pipeline.py
|
|
│ │ ├── test_schema.py
|
|
│ │ ├── test_db.py
|
|
│ │ └── test_routes.py
|
|
│ └── app/
|
|
│ ├── __init__.py
|
|
│ ├── main.py # FastAPI app
|
|
│ ├── config.py # SAJU_MODEL, SAJU_COST_*, ANTHROPIC_API_KEY, SAJU_TIMEOUT_SEC
|
|
│ ├── db.py # saju.db: saju_records, compat_records 테이블 + CRUD
|
|
│ ├── models.py # SajuRequest, CompatRequest, etc.
|
|
│ ├── calculator/
|
|
│ │ ├── __init__.py
|
|
│ │ ├── constants.py # HEAVENLY_STEMS, EARTHLY_BRANCHES, FIVE_ELEMENTS, HIDDEN_STEMS, TEN_GODS, TWELVE_FORTUNES
|
|
│ │ ├── core.py # get_year_ganzi, get_month_ganzi, get_day_ganzi, get_hour_ganzi, get_ten_god, get_twelve_fortune, calculate_saju
|
|
│ │ ├── solar_terms.py # get_solar_term_date, get_current_solar_term, get_solar_term_month_branch, get_days_to_next_solar_term — sxtwl 사용
|
|
│ │ ├── lunar.py # solar_to_lunar, lunar_to_solar
|
|
│ │ ├── shinsal.py # get_hidden_stems, get_all_hidden_stems, analyze_branch_interactions, calculate_shinsal, calculate_gongmang
|
|
│ │ ├── analysis.py # calculate_detailed_element_balance, calculate_element_score, analyze_day_master_strength, estimate_yongshin, calculate_seun, perform_full_analysis
|
|
│ │ ├── daeun.py # calculate_daeun, get_current_daeun, get_daeun_description
|
|
│ │ └── compatibility.py # calculate_compatibility (오행 상생/상극 + 지지 합/충 점수화)
|
|
│ ├── interpret/
|
|
│ │ ├── __init__.py
|
|
│ │ ├── pipeline.py # Claude 호출 + reroll (tarot 패턴)
|
|
│ │ ├── compat_pipeline.py
|
|
│ │ ├── prompt.py # 사주 12항목 SYSTEM_PROMPT (Claude용 재작성, evidence-based)
|
|
│ │ ├── compat_prompt.py # 궁합 SYSTEM_PROMPT
|
|
│ │ └── schema.py # validate_saju_interpretation, validate_compat_interpretation
|
|
│ └── routers/
|
|
│ ├── __init__.py
|
|
│ ├── saju.py # POST /api/saju/interpret, /readings CRUD, /current-fortune
|
|
│ └── compat.py # POST /api/saju/compat/interpret, /readings CRUD
|
|
│
|
|
├── agent-office/ # [수정]
|
|
│ ├── app/
|
|
│ │ ├── tarot/ # [제거]
|
|
│ │ ├── routers/tarot.py # [제거]
|
|
│ │ ├── models.py # Tarot* 5개 제거
|
|
│ │ ├── db.py # tarot_readings 관련 CRUD 5개 + _tarot_row_to_dict + CREATE TABLE 제거
|
|
│ │ └── main.py # include_router(tarot_router.router) 줄 제거
|
|
│ ├── tests/ # test_tarot_*.py 4개 제거
|
|
│ └── scripts/
|
|
│ └── migrate_tarot_to_lab.py # [신설] 1회성 마이그레이션
|
|
│
|
|
├── docker-compose.yml # [수정] tarot-lab, saju-lab 추가
|
|
├── nginx/default.conf # [수정] /api/tarot/ → tarot-lab, /api/saju/ → saju-lab, /api/agent-office/tarot/ 제거
|
|
├── scripts/
|
|
│ ├── deploy-nas.sh # [수정] CONTAINERS 배열에 saju-lab, tarot-lab 추가
|
|
│ └── deploy.sh # [수정] 5위치 (CLAUDE.md memory의 "배포 스크립트 동기화" 항목 참조)
|
|
└── docs/superpowers/specs/
|
|
└── 2026-05-25-saju-tarot-lab-migration-design.md # 본 문서
|
|
```
|
|
|
|
**프론트엔드 (`web-ui/`)** — Phase 1·2 양쪽 변경:
|
|
```
|
|
web-ui/
|
|
├── src/
|
|
│ ├── api.js # [Phase 1 수정] tarot helpers 6개 URL prefix 변경 + [Phase 2 추가] saju/compat helpers
|
|
│ ├── routes.jsx # [Phase 2 수정] /saju, /saju/result, /saju/compatibility, /saju/compatibility/result 라우트
|
|
│ ├── components/Icons.jsx # [Phase 2 수정] IconSaju 추가
|
|
│ └── pages/
|
|
│ ├── tarot/ # [Phase 1] URL prefix만 변경, 그 외 변경 없음
|
|
│ └── saju/ # [Phase 2 신설, 시안 받은 후]
|
|
│ ├── Saju.jsx
|
|
│ ├── SajuForm.jsx
|
|
│ ├── SajuResult.jsx
|
|
│ ├── Compatibility.jsx
|
|
│ ├── CompatibilityForm.jsx
|
|
│ ├── CompatibilityResult.jsx
|
|
│ ├── data/
|
|
│ │ ├── constants.js # 천간/지지/오행 상수 (UI 표시용)
|
|
│ │ └── interpretations.js
|
|
│ ├── hooks/
|
|
│ │ ├── useSajuForm.js
|
|
│ │ └── useSajuInterpretation.js
|
|
│ └── components/
|
|
│ ├── SajuBoard.jsx # 4기둥 시각화
|
|
│ ├── ElementChart.jsx# 오행 차트
|
|
│ ├── DaeunTimeline.jsx
|
|
│ └── InterpretationPanel.jsx
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Phase 1: tarot-lab 분리
|
|
|
|
### 5-1. 신규 tarot-lab 컨테이너 생성
|
|
|
|
**파일 단순 복사 + 모듈 평탄화:**
|
|
- `agent-office/app/tarot/__init__.py` → `tarot-lab/app/__init__.py` (간단화)
|
|
- `agent-office/app/tarot/prompt.py` → `tarot-lab/app/prompt.py`
|
|
- `agent-office/app/tarot/pipeline.py` → `tarot-lab/app/pipeline.py` (import 경로 수정: `..config` → `.config`, `..models` → `.models`)
|
|
- `agent-office/app/tarot/schema.py` → `tarot-lab/app/schema.py`
|
|
|
|
**추출 파일:**
|
|
- `tarot-lab/app/config.py`: agent-office의 config.py에서 TAROT_* 환경변수만 추출
|
|
```python
|
|
import os
|
|
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY", "")
|
|
TAROT_MODEL = os.getenv("TAROT_MODEL", "claude-sonnet-4-6")
|
|
TAROT_COST_INPUT_PER_M = float(os.getenv("TAROT_COST_INPUT_PER_M", "3.0"))
|
|
TAROT_COST_OUTPUT_PER_M = float(os.getenv("TAROT_COST_OUTPUT_PER_M", "15.0"))
|
|
TAROT_TIMEOUT_SEC = int(os.getenv("TAROT_TIMEOUT_SEC", "180"))
|
|
TAROT_DATA_PATH = os.getenv("TAROT_DATA_PATH", "/app/data")
|
|
TAROT_DB_PATH = os.path.join(TAROT_DATA_PATH, "tarot.db")
|
|
```
|
|
- `tarot-lab/app/models.py`: agent-office models.py에서 Tarot* 5개만 추출
|
|
- `tarot-lab/app/db.py`:
|
|
- tarot_readings CREATE TABLE + WAL 활성화
|
|
- 5 CRUD (save/get/list/update/delete) + `_tarot_row_to_dict`
|
|
- DB 경로는 `TAROT_DB_PATH` (volume mount된 `/app/data/tarot.db`)
|
|
- `tarot-lab/app/main.py`:
|
|
```python
|
|
from fastapi import FastAPI, HTTPException
|
|
from .models import (...)
|
|
from . import pipeline, db as db_module
|
|
|
|
app = FastAPI(title="tarot-lab")
|
|
|
|
@app.on_event("startup")
|
|
def _init_db():
|
|
db_module.init_db()
|
|
|
|
# /api/tarot/* 5 endpoints (routers/tarot.py 코드 그대로)
|
|
```
|
|
|
|
**Dockerfile (insta-lab 패턴):**
|
|
```dockerfile
|
|
FROM python:3.12-slim
|
|
WORKDIR /app
|
|
COPY requirements.txt .
|
|
RUN pip install --no-cache-dir -r requirements.txt
|
|
COPY app/ ./app/
|
|
EXPOSE 8000
|
|
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
|
|
```
|
|
|
|
**requirements.txt:**
|
|
```
|
|
fastapi==0.115.0
|
|
uvicorn[standard]==0.32.0
|
|
httpx==0.27.2
|
|
pydantic==2.9.2
|
|
```
|
|
|
|
### 5-2. 테스트 이관
|
|
- `agent-office/tests/test_tarot_*.py` 4개 파일 → `tarot-lab/tests/test_*.py`
|
|
- import 경로 수정 (`from app.tarot.pipeline` → `from app.pipeline`)
|
|
- pytest.ini 추가 (`testpaths = tests`, `pythonpath = .`)
|
|
- 모두 통과 확인 (21 tests)
|
|
|
|
### 5-3. DB 마이그레이션 스크립트
|
|
|
|
`agent-office/scripts/migrate_tarot_to_lab.py`:
|
|
```python
|
|
"""1회성 — agent_office.db의 tarot_readings를 tarot.db로 복사.
|
|
멱등성: 이미 존재하는 id는 SKIP.
|
|
실행: docker exec agent-office python /app/scripts/migrate_tarot_to_lab.py
|
|
"""
|
|
import sqlite3
|
|
import os
|
|
|
|
SRC = os.getenv("AGENT_OFFICE_DB", "/app/data/agent_office.db")
|
|
DST = os.getenv("TAROT_DB", "/app/data/tarot.db")
|
|
|
|
def migrate():
|
|
src = sqlite3.connect(SRC)
|
|
dst = sqlite3.connect(DST)
|
|
dst.execute("""
|
|
CREATE TABLE IF NOT EXISTS tarot_readings (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
... (agent-office 스키마 그대로)
|
|
)
|
|
""")
|
|
rows = src.execute("SELECT * FROM tarot_readings").fetchall()
|
|
cols = [c[0] for c in src.execute("SELECT * FROM tarot_readings LIMIT 1").description]
|
|
placeholders = ",".join("?" * len(cols))
|
|
cols_str = ",".join(cols)
|
|
moved = 0
|
|
for r in rows:
|
|
cur = dst.execute(f"SELECT 1 FROM tarot_readings WHERE id = ?", (r[0],))
|
|
if cur.fetchone() is None:
|
|
dst.execute(f"INSERT INTO tarot_readings ({cols_str}) VALUES ({placeholders})", r)
|
|
moved += 1
|
|
dst.commit()
|
|
print(f"migrated {moved} / {len(rows)} rows")
|
|
|
|
if __name__ == "__main__":
|
|
migrate()
|
|
```
|
|
|
|
**볼륨 공유 전략**: tarot-lab의 `/app/data`를 agent-office의 `/app/data`와 같은 NAS 호스트 디렉토리에 마운트. tarot.db는 신규 파일이라 별도 마운트 가능.
|
|
|
|
### 5-4. docker-compose / nginx / deploy 갱신
|
|
|
|
**docker-compose.yml**에 추가:
|
|
```yaml
|
|
tarot-lab:
|
|
build: ./tarot-lab
|
|
container_name: tarot-lab
|
|
restart: unless-stopped
|
|
ports:
|
|
- "18250:8000"
|
|
environment:
|
|
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
|
|
- TAROT_MODEL=${TAROT_MODEL:-claude-sonnet-4-6}
|
|
- TAROT_DATA_PATH=/app/data
|
|
volumes:
|
|
- ${RUNTIME_PATH:-.}/data:/app/data
|
|
```
|
|
|
|
**nginx/default.conf**에 추가, 기존 `/api/agent-office/tarot/`은 제거:
|
|
```nginx
|
|
location /api/tarot/ {
|
|
proxy_pass http://tarot-lab:8000;
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_read_timeout 300s;
|
|
proxy_send_timeout 300s;
|
|
proxy_connect_timeout 60s;
|
|
}
|
|
```
|
|
|
|
**deploy 스크립트 5위치** (memory의 "배포 스크립트 동기화" 참조):
|
|
- `scripts/deploy-nas.sh`의 CONTAINERS 배열
|
|
- `scripts/deploy.sh`의 SERVICES, DIRS 배열
|
|
- 컨테이너 목록 하드코딩된 모든 위치에 `tarot-lab` 추가 (Phase 1) / `saju-lab` 추가 (Phase 2)
|
|
|
|
### 5-5. agent-office cutover
|
|
|
|
마이그레이션 + 데이터 검증 후:
|
|
- `agent-office/app/tarot/` 디렉토리 통째로 제거
|
|
- `agent-office/app/routers/tarot.py` 제거
|
|
- `agent-office/app/main.py`에서 tarot router import + include_router 줄 제거
|
|
- `agent-office/app/models.py`에서 `TarotCardDraw`, `TarotInterpretRequest`, `TarotInterpretResponse`, `TarotSaveRequest`, `TarotPatchRequest` 제거
|
|
- `agent-office/app/db.py`에서 `save_tarot_reading`, `get_tarot_reading`, `list_tarot_readings`, `update_tarot_reading`, `delete_tarot_reading`, `_tarot_row_to_dict` 제거
|
|
- `agent-office/app/db.py`의 CREATE TABLE에서 `tarot_readings` 줄 제거 (또는 idempotent 유지: 기존 DB 호환 위해 CREATE IF NOT EXISTS는 유지하되 코드 경로 제거)
|
|
- `agent-office/tests/test_tarot_*.py` 4개 제거
|
|
- agent-office pytest 통과 확인
|
|
|
|
### 5-6. web-ui api.js URL 변경
|
|
|
|
`web-ui/src/api.js`의 tarot helpers 6개:
|
|
- `tarotInterpret`: `/api/agent-office/tarot/interpret` → `/api/tarot/interpret`
|
|
- `tarotSaveReading`: `/api/agent-office/tarot/readings` → `/api/tarot/readings`
|
|
- `tarotListReadings`: 동일 변환
|
|
- `tarotGetReading`: 동일 변환
|
|
- `tarotPatchReading`: 동일 변환
|
|
- `tarotDeleteReading`: 동일 변환
|
|
|
|
Phase 1 검증: `npm run dev` → http://127.0.0.1:3007/tarot → 3장 리딩 1회 e2e 동작 확인.
|
|
|
|
---
|
|
|
|
## 6. Phase 2: saju-lab 신설
|
|
|
|
### 6-1. 계산 엔진 포팅 (TypeScript → Python)
|
|
|
|
**핵심 위험**: 계산 엔진은 ~1500줄 TypeScript로 매년 검증된 코드. Python으로 옮기면서 미세한 버그가 들어가면 모든 사주 해석이 잘못됨.
|
|
|
|
**대응 전략 — Reference Output 비교 테스트**:
|
|
1. saju-web의 `lib/saju-calculator.ts` 코드를 Node.js로 직접 실행 (`node -e "..."`)
|
|
2. 알려진 입력 30~50쌍에 대해 `calculateSaju(year, month, day, hour, gender)` + `performFullAnalysis(saju, currentYear)` + `calculateDaeun(...)` 호출 결과를 JSON 파일로 저장
|
|
3. `tests/fixtures/reference_saju.json` 형식:
|
|
```json
|
|
[
|
|
{
|
|
"input": {"year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "male"},
|
|
"expected": {
|
|
"saju": {...},
|
|
"analysis": {...},
|
|
"daeun": [...]
|
|
}
|
|
},
|
|
... (50개)
|
|
]
|
|
```
|
|
4. Python 포팅 후 pytest로 매 입력 → expected와 1:1 비교 (`assert deep_equal(actual, expected)`)
|
|
|
|
**포팅 순서** (의존성 그래프):
|
|
1. `calculator/constants.py` — 모든 상수 (천간 10·지지 12·오행 5·십성·십이운성·지장간·신살)
|
|
2. `calculator/solar_terms.py` — `sxtwl` Python 라이브러리 사용 (24절기 + 음력)
|
|
3. `calculator/lunar.py` — `sxtwl` 음력↔양력 변환
|
|
4. `calculator/core.py` — `get_year_ganzi`, `get_month_ganzi` (절기 기반), `get_day_ganzi`, `get_hour_ganzi`, `get_ten_god`, `get_twelve_fortune`, `calculate_saju`
|
|
5. `calculator/shinsal.py` — 지장간(`get_hidden_stems`, `get_all_hidden_stems`), 지지 상호작용(`analyze_branch_interactions`), 신살(`calculate_shinsal`), 공망(`calculate_gongmang`)
|
|
6. `calculator/analysis.py` — 오행 점수(`calculate_detailed_element_balance`, `calculate_element_score`), 신강신약(`analyze_day_master_strength`), 용신(`estimate_yongshin`), 세운(`calculate_seun`), 종합(`perform_full_analysis`)
|
|
7. `calculator/daeun.py` — `calculate_daeun`, `get_current_daeun`, `get_daeun_description`
|
|
8. `calculator/compatibility.py` — 두 사주의 오행 매칭 + 지지 합/충 점수화 → 0~100 점수
|
|
|
|
각 단계마다 reference test 통과를 게이트로.
|
|
|
|
### 6-2. Claude 프롬프트 (tarot 패턴 재활용)
|
|
|
|
**`interpret/prompt.py`** — 사주 12항목 해석:
|
|
- 시스템 프롬프트: "당신은 한국 전통 사주명리학 전문가다. 다음 사주 + 분석 결과를 보고, JSON 스키마로 12항목 해석을 작성하라. 각 항목은 evidence 필드를 포함해 어떤 사주 요소에서 결론을 도출했는지 명시하라."
|
|
- 12항목: 타고난 기질 / 오행 밸런스 / 지지 상호작용 / 신살 영향 / 재물운 / 직업 적성 / 애정운 / 건강운 / 현재 대운 / 올해 세운 / 인생 황금기 / 종합 조언
|
|
- JSON 응답 스키마:
|
|
```json
|
|
{
|
|
"items": [
|
|
{ "key": "기질", "title": "...", "content": "...", "evidence": {"saju_element": "...", "reasoning": "..."} },
|
|
...
|
|
],
|
|
"summary": "...",
|
|
"advice": "...",
|
|
"warning": "...",
|
|
"confidence": "high|medium|low"
|
|
}
|
|
```
|
|
- `cache_control: ephemeral`을 system 블록에 적용
|
|
|
|
**`interpret/compat_prompt.py`** — 궁합 해석:
|
|
- 두 사주 + 궁합 점수 + 오행 상생/상극 분석 → JSON 응답
|
|
- evidence: 어떤 지지 합/충에서 점수가 나왔는지 명시
|
|
|
|
**`interpret/schema.py`** — validate 함수:
|
|
- `validate_saju_interpretation(parsed)`: items 12개 존재 / 각 evidence 채워졌는지 / confidence 값 검증
|
|
- `validate_compat_interpretation(parsed)`: 마찬가지
|
|
|
|
**`interpret/pipeline.py`** — Claude 호출 (tarot pipeline.py 거의 그대로 복사 + 사주용 prompt/schema 사용):
|
|
- max_tokens 2400 (12항목 + 종합이라 더 길음)
|
|
- reroll 1회
|
|
- latency_ms / tokens 로깅
|
|
|
|
### 6-3. DB 스키마
|
|
|
|
`saju-lab/app/db.py`:
|
|
```python
|
|
SAJU_DB_SCHEMA = """
|
|
CREATE TABLE IF NOT EXISTS saju_records (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
birth_year INTEGER NOT NULL,
|
|
birth_month INTEGER NOT NULL,
|
|
birth_day INTEGER NOT NULL,
|
|
birth_hour INTEGER,
|
|
gender TEXT NOT NULL,
|
|
calendar_type TEXT DEFAULT 'solar',
|
|
saju_data JSON NOT NULL,
|
|
analysis_data JSON NOT NULL,
|
|
daeun_data JSON NOT NULL,
|
|
interpretation_json JSON,
|
|
model TEXT,
|
|
tokens_in INTEGER DEFAULT 0,
|
|
tokens_out INTEGER DEFAULT 0,
|
|
cost_usd REAL DEFAULT 0,
|
|
latency_ms INTEGER DEFAULT 0,
|
|
reroll_count INTEGER DEFAULT 0,
|
|
favorite INTEGER DEFAULT 0,
|
|
memo TEXT,
|
|
created_at TEXT DEFAULT CURRENT_TIMESTAMP
|
|
);
|
|
|
|
CREATE TABLE IF NOT EXISTS compat_records (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
person_a JSON NOT NULL,
|
|
person_b JSON NOT NULL,
|
|
score INTEGER NOT NULL,
|
|
breakdown JSON NOT NULL,
|
|
interpretation_json JSON,
|
|
model TEXT,
|
|
tokens_in INTEGER DEFAULT 0,
|
|
tokens_out INTEGER DEFAULT 0,
|
|
cost_usd REAL DEFAULT 0,
|
|
favorite INTEGER DEFAULT 0,
|
|
memo TEXT,
|
|
created_at TEXT DEFAULT CURRENT_TIMESTAMP
|
|
);
|
|
"""
|
|
```
|
|
|
|
CRUD 함수: `save_saju_record`, `get_saju_record`, `list_saju_records`, `update_saju_record`, `delete_saju_record` + compat 5개.
|
|
|
|
### 6-4. API 엔드포인트
|
|
|
|
**`routers/saju.py`**:
|
|
| 메서드 | 경로 | 설명 |
|
|
|--------|------|------|
|
|
| POST | `/api/saju/interpret` | 입력 → 계산 + AI 해석 + DB 저장. 응답에 saju/analysis/daeun/interpretation/reading_id 포함 |
|
|
| GET | `/api/saju/readings` | 페이지네이션 목록 (page, size, favorite) |
|
|
| GET | `/api/saju/readings/{id}` | 상세 조회 |
|
|
| PATCH | `/api/saju/readings/{id}` | favorite, memo 수정 |
|
|
| DELETE | `/api/saju/readings/{id}` | 삭제 |
|
|
| GET | `/api/saju/current-fortune?reading_id={id}` | 저장된 사주 기반 오늘의 세운 (실시간 계산, AI 호출 없음) |
|
|
|
|
**`routers/compat.py`**:
|
|
| 메서드 | 경로 | 설명 |
|
|
|--------|------|------|
|
|
| POST | `/api/saju/compat/interpret` | 두 사람 입력 → 두 사주 계산 + 궁합 점수 + AI 해석 + DB 저장 |
|
|
| GET | `/api/saju/compat/readings` | 목록 |
|
|
| GET | `/api/saju/compat/readings/{id}` | 상세 |
|
|
| PATCH | `/api/saju/compat/readings/{id}` | favorite, memo |
|
|
| DELETE | `/api/saju/compat/readings/{id}` | 삭제 |
|
|
|
|
### 6-5. docker-compose / nginx 등록
|
|
|
|
**docker-compose.yml**에 saju-lab 항목 추가 (tarot-lab과 동일 패턴, 포트 18300).
|
|
|
|
**nginx/default.conf**에 추가:
|
|
```nginx
|
|
location /api/saju/ {
|
|
proxy_pass http://saju-lab:8000;
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_read_timeout 300s;
|
|
proxy_send_timeout 300s;
|
|
proxy_connect_timeout 60s;
|
|
}
|
|
```
|
|
|
|
deploy 스크립트 5위치에 `saju-lab` 추가.
|
|
|
|
### 6-6. web-ui /saju 페이지
|
|
|
|
**시안 추후 제공** (사용자 확인). 시안 받은 후 tarot 페이지 패턴 따라 구현:
|
|
- 입력 폼: 생년월일 + 시간 + 성별 + 양력/음력 (양력 default)
|
|
- 결과 페이지: 사주판 시각화 + 오행 차트 + 대운 타임라인 + AI 12항목 아코디언
|
|
- 궁합: 두 사람 입력 폼 + 결과 카드
|
|
- 인사이트 패널 (tarot의 InterpretationPanel.jsx 패턴 차용)
|
|
|
|
`api.js`에 helpers 추가:
|
|
- `sajuInterpret`, `sajuListReadings`, `sajuGetReading`, `sajuPatchReading`, `sajuDeleteReading`, `sajuCurrentFortune`
|
|
- `compatInterpret`, `compatListReadings`, `compatGetReading`, `compatPatchReading`, `compatDeleteReading`
|
|
|
|
`routes.jsx`에 라우트 추가:
|
|
- `/saju` (입력), `/saju/result` (사주 결과), `/saju/compatibility` (입력), `/saju/compatibility/result` (궁합 결과)
|
|
|
|
`components/Icons.jsx`에 `IconSaju` 추가.
|
|
|
|
---
|
|
|
|
## 7. 데이터 흐름
|
|
|
|
### tarot-lab (Phase 1)
|
|
```
|
|
[web-ui /tarot/reading]
|
|
↓ POST /api/tarot/interpret { cards, question, category, spread_type }
|
|
[nginx /api/tarot/ → tarot-lab:8000]
|
|
↓ pipeline.interpret() → Claude API
|
|
↓ validate + reroll
|
|
[tarot-lab]
|
|
↓ POST /api/tarot/readings { ... save body }
|
|
↓ db.save_tarot_reading() → tarot.db INSERT
|
|
← { id, created_at }
|
|
```
|
|
|
|
### saju-lab (Phase 2)
|
|
```
|
|
[web-ui /saju/result]
|
|
↓ POST /api/saju/interpret { year, month, day, hour, gender, calendarType }
|
|
[nginx /api/saju/ → saju-lab:8000]
|
|
↓ calculator.calculate_saju() → SajuData
|
|
↓ calculator.perform_full_analysis() → SajuAnalysis
|
|
↓ calculator.calculate_daeun() → DaeunPillar[]
|
|
↓ interpret.pipeline.interpret() → Claude API
|
|
↓ validate + reroll
|
|
↓ db.save_saju_record() → saju.db INSERT
|
|
← { saju, analysis, daeun, interpretation, reading_id, cost_usd, latency_ms }
|
|
[web-ui]
|
|
```
|
|
|
|
### saju-lab 궁합
|
|
```
|
|
[web-ui /saju/compatibility/result]
|
|
↓ POST /api/saju/compat/interpret { person_a: {...}, person_b: {...} }
|
|
[saju-lab]
|
|
↓ calculate_saju(person_a) + calculate_saju(person_b)
|
|
↓ compatibility.calculate_compatibility(saju_a, saju_b) → { score, breakdown }
|
|
↓ interpret.compat_pipeline.interpret() → Claude API
|
|
↓ db.save_compat_record()
|
|
← { saju_a, saju_b, score, breakdown, interpretation, reading_id }
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 에러 처리
|
|
|
|
| 시나리오 | 처리 |
|
|
|---------|------|
|
|
| Claude API HTTP error | `TarotError` / `SajuError` raise → FastAPI 500 |
|
|
| Claude JSON 파싱 실패 | `_extract_json` codeblock 스트립 + 첫 `{` / 마지막 `}` 추출. 실패 시 reroll |
|
|
| validate 실패 (필수 필드 누락) | reroll 1회. 그래도 실패 시 `_Error("검증 실패")` raise → 500 |
|
|
| 계산 엔진 입력 오류 (잘못된 날짜 등) | Pydantic validation → 422 |
|
|
| DB 락 | sqlite WAL 모드. 짧은 retry 없이 raise (드물게 발생) |
|
|
| 마이그레이션 스크립트 중복 실행 | `INSERT OR IGNORE` 패턴 / 멱등 |
|
|
|
|
---
|
|
|
|
## 9. 테스트 전략
|
|
|
|
### tarot-lab
|
|
- 기존 21 tests 이관 + import 경로 수정 후 100% 통과
|
|
|
|
### saju-lab — 계산 엔진
|
|
- **Reference output 비교가 핵심**. 30~50개 입력 → JSON 저장 → Python 결과와 deep_equal 비교
|
|
- 각 모듈 단위 테스트 (constants, solar_terms, lunar, core, shinsal, analysis, daeun, compatibility)
|
|
- 회귀 방지: 추가 입력 케이스 발견 시 fixtures에 추가
|
|
|
|
### saju-lab — Claude 파이프라인
|
|
- httpx mock (respx 또는 monkeypatch) 사용 (tarot 패턴 그대로)
|
|
- validate / reroll / JSON 파싱 폴백 / cost 계산 검증
|
|
|
|
### saju-lab — 라우터
|
|
- TestClient 기반 e2e (FastAPI 표준)
|
|
- DB tmp_path fixture
|
|
|
|
### 통합 검증 (Phase 1, Phase 2 끝)
|
|
- `npm run dev` + http://127.0.0.1:3007/tarot에서 리딩 1회 (Phase 1)
|
|
- 같은 곳에서 /saju에서 사주 + 궁합 1회씩 (Phase 2, 시안 적용 후)
|
|
|
|
---
|
|
|
|
## 10. 환경변수 정리
|
|
|
|
**tarot-lab 신규 환경변수** (docker-compose env):
|
|
- `ANTHROPIC_API_KEY` (필수)
|
|
- `TAROT_MODEL` (기본 `claude-sonnet-4-6`)
|
|
- `TAROT_COST_INPUT_PER_M` (기본 3.0)
|
|
- `TAROT_COST_OUTPUT_PER_M` (기본 15.0)
|
|
- `TAROT_TIMEOUT_SEC` (기본 180)
|
|
- `TAROT_DATA_PATH` (기본 `/app/data`)
|
|
|
|
**saju-lab 신규 환경변수**:
|
|
- `ANTHROPIC_API_KEY` (필수)
|
|
- `SAJU_MODEL` (기본 `claude-sonnet-4-6`)
|
|
- `SAJU_COST_INPUT_PER_M`, `SAJU_COST_OUTPUT_PER_M`
|
|
- `SAJU_TIMEOUT_SEC`
|
|
- `SAJU_DATA_PATH`
|
|
|
|
---
|
|
|
|
## 11. 마이그레이션 위험 + 완화
|
|
|
|
| 위험 | 영향 | 완화 |
|
|
|------|------|------|
|
|
| TS→Python 포팅 미세 차이 (예: 절기 일자 1일 차이) | 모든 사주 결과 변형 | Reference output 비교 테스트 50건 + sxtwl로 절기 동일 알고리즘 사용 |
|
|
| tarot.db 마이그레이션 중 데이터 손실 | 사용자 리딩 이력 손실 | 멱등 스크립트 + 검증 후 cutover. agent-office의 원본 데이터는 cutover 후에도 30일 유지 (테이블만 DROP 안 함) |
|
|
| 두 컨테이너 추가로 NAS 메모리 압박 | 다른 서비스 OOM | python:3.12-slim 기반 ~150MB. 18GB RAM 여유 충분 |
|
|
| API prefix 변경 missed 위치 (web-ui에서 일부 호출만 변경) | 일부 페이지 404 | grep 검색 (`/api/agent-office/tarot`) 후 일괄 변경 |
|
|
| nginx restart 누락 | 라우팅 안 됨 | docker compose up -d --build → nginx 컨테이너 재시작 자동 (deployer 패턴) |
|
|
| saju-web 코드 사라짐 (참조 못 하게 됨) | 검증 어려움 | saju-web 디렉토리는 그대로 유지 (포팅 끝나도 archive로 보존) |
|
|
|
|
---
|
|
|
|
## 12. 향후 (v2, 본 spec 밖)
|
|
|
|
- 토정비결 (12개월 운세) — saju-lab v2에서 추가
|
|
- 정밀 음력 + 윤달 처리 검증
|
|
- 자동 마이그레이션 스크립트의 ON DELETE CASCADE 검토 (이력 정합성)
|
|
- agent-office의 tarot 관련 텔레그램 명령이 있다면 그것도 saju-lab에 추가할지 검토
|
|
- saju-lab UI 디자인 시안 확정 후 별도 짧은 plan으로 진행
|
|
|
|
---
|
|
|
|
## 13. 참고 자료
|
|
|
|
- saju-web/PROJECT_OVERVIEW.md — 마이그레이션 원본 명세
|
|
- web-backend/CLAUDE.md — lab 서비스 패턴 참조
|
|
- agent-office/app/tarot/, agent-office/app/routers/tarot.py — Phase 1 이관 원본
|
|
- web-backend/insta-lab/, music-lab/, realestate-lab/ — Dockerfile + 디렉토리 구조 참조 패턴
|
|
- sxtwl (Python 만세력 라이브러리) — solarlunar 대체
|
|
- docs/superpowers/specs/2026-05-23-tarot-lab-design.md — 본 작업의 직전 spec (tarot-lab 원본 설계)
|