# saju-lab UI v1 — 호령 사주 페이지 설계

**작성일**: 2026-05-26
**상태**: Spec (구현 plan 작성 전)
**전제**: saju-lab 백엔드 완성 (474 tests, SHA 8123f75) + web-ui Task 28 (api helpers + placeholder pages)

---

## 1. 목표

사용자 시안 4종(`source/images/saju_page/horyung_saju_main.png`, `_today.png`, `_gunghab.png`, `_saju.png`) + 캐릭터 시트(`source/characters/horyung.png`) + 컬러시트(`saju_color_sheet.png`) 기반으로 web-ui `/saju/*` 페이지를 호령 마스코트와 함께 구축한다.

v1 범위: **메인 / 오늘의 운세 / 사주풀이** 3개 페이지. 궁합은 v2 placeholder.

---

## 2. 결정된 핵심 사항

| 항목 | 결정 |
|------|------|
| 캐릭터 자산 | horyung.png + saju_color_sheet.png에서 PNG 6개 추출 |
| 백엔드 확장 | saju-lab에 fortune_scores + lucky + monthly_flow 산출 추가 |
| 입력 흐름 | 메인에서 사주 1회 입력 → reading_id를 다른 페이지 URL query로 공유 |
| v1 페이지 | 메인 + 사주풀이 + 오늘운세 (궁합은 v2) |
| 반응형 | 데스크탑(1280+) 우선 + 태블릿 그라데이션 |
| 컬러 | 시안 추출 — 크림 베이스 + 다크 네이비 + 골드 + 살구 + 청록 |
| 폰트 | Pretendard (본문) + Noto Serif KR (큰 제목, Google Fonts) |
| CSS 격리 | `.saju-page` scope (다른 페이지에 새지 않음) |

---

## 3. 백엔드 확장 (saju-lab)

### 3-1. 신설 모듈

**`saju-lab/app/calculator/fortune_scores.py`** — 4 카테고리 점수:

```
calculate_fortune_scores(saju, analysis, current_year) → {
  wealth:  0-100  (재물운)
  romance: 0-100  (연애운)
  social:  0-100  (인간관계)
  career:  0-100  (직장운)
  overall: 0-100  (가중평균: wealth*0.3 + career*0.3 + romance*0.2 + social*0.2)
}
```

알고리즘 (각 base 60에서 가산/감산, clamp 0-100):

- **wealth**: +정재 강도 / +편재 강도 / +식상→재 통로 / -비겁 강도 / +세운재성
- **romance**: +일지 합 / +정관·정재 균형 / -일지 충 / +세운 도화살
- **social**: +인성 / +비겁 적정 / +식상 / +격국 균형 / +천을귀인
- **career**: +정관 강도 / +편관 제어 / +일간 신강 / +세운 관성

**`saju-lab/app/calculator/lucky.py`** — 럭키 데이터:

```
calculate_lucky(saju, analysis, target_date) → {
  color: [str, str]   # 용신 오행 컬러 1~2개 (예: ["청록", "녹색"])
  number: int 1-9     # (일진 천간 idx + 시진 천간 idx) % 9 + 1
  direction: str      # 용신 오행 방향 (동/남/중앙/서/북)
  good_signs: [str]   # 세운 천간이 일간 재성 → "재물 기회" 등
  warnings: [str]     # 세운 지지가 일지 충 → "대인 갈등 주의"
}
```

오행→컬러/방향 매핑은 정적 dict. 럭키 숫자는 일진+시진(시간 미상 시 일진만)으로 산출.

**`saju-lab/app/calculator/monthly_flow.py`** — 12개월 운세 흐름:

```
calculate_monthly_flow(saju, year) → [
  {month: 1, stem: "壬", branch: "寅", score: 65, label: "변동"},
  {month: 2, stem: "癸", branch: "卯", score: 70, label: "성장"},
  ... 12 entries
]
```

각 월: 해당 월의 60갑자(寅월부터 12월 사이클) → 일간 관계(상생/상극/충/합) → score 0-100 + label(`변동`/`성장`/`안정`/`도전`/`정체` 등).

### 3-2. `routers/saju.py` 응답 확장

`SajuInterpretResponse`에 3 필드 추가:

```python
fortune_scores: dict   # {wealth, romance, social, career, overall}
lucky: dict            # {color, number, direction, good_signs, warnings}
monthly_flow: list[dict]  # 12 entries
```

`interpret_saju_endpoint`에서 계산 + DB 저장 + 응답 포함.

### 3-3. `db.py` 스키마 마이그레이션

`saju_records` 테이블에 ALTER TABLE로 3 컬럼 추가 (idempotent):
- `fortune_scores_json TEXT`
- `lucky_json TEXT`
- `monthly_flow_json TEXT`

`init_db()`에 try/except OperationalError 패턴 (이미 존재하면 skip).

`_saju_row_to_dict`에서 3 컬럼 JSON 파싱하여 응답에 포함.

### 3-4. 테스트

- `test_fortune_scores.py` — 5-8 case (정재 강함 → wealth 80+, 일지 충 → romance 50-, clamp 검증)
- `test_lucky.py` — 5 case (오행→컬러/방향 매핑, 럭키 숫자 1-9 범위)
- `test_monthly_flow.py` — 3 case (12 entries 정확, 일간 충 월 score 낮음)

기존 30 reference fixture 비교는 영향 없음 (응답에 새 필드만 추가).

---

## 4. 프론트엔드 구조 (web-ui)

### 4-1. 디렉토리

```
web-ui/
├── public/images/saju/
│   ├── horyung/
│   │   ├── horyung-front.png        # 시안 main hero용 (정면, 큰 사이즈)
│   │   ├── horyung-bust.png         # 작은 카드용 (가슴샷)
│   │   ├── horyung-greeting.png     # 인사 표정 (메인 좌상단)
│   │   ├── horyung-thinking.png     # 생각하는 표정 (사주풀이)
│   │   ├── horyung-pointing.png     # 가르치는 표정 (오늘운세)
│   │   └── horyung-happy.png        # 기쁜 표정 (점수 높을 때)
│   ├── frame-cloud.png              # 시안의 한국화 산 배경 (hero용)
│   ├── pattern-cloud.svg            # 한국 전통 구름 패턴
│   └── icons/
│       ├── icon-today.svg
│       ├── icon-heart.svg
│       └── icon-book.svg
└── src/pages/saju/
    ├── Saju.css                     # 모든 saju 페이지 공통 스타일 (격리)
    ├── data/
    │   └── constants.js             # 4 카테고리 메타, 컬러 토큰
    ├── hooks/
    │   ├── useSajuForm.js
    │   └── useSajuReading.js        # reading_id → fetched data + 캐시
    ├── components/
    │   ├── HoryungMascot.jsx
    │   ├── SajuNav.jsx              # 시안 상단 네비게이션 (호령사주 로고 + nav)
    │   ├── SajuInputForm.jsx
    │   ├── ActionCard.jsx           # 3 카드 (오늘운세/궁합/사주풀이)
    │   ├── ScoreCard.jsx            # 카테고리 점수 카드
    │   ├── FortuneRing.jsx          # 종합점 ring SVG
    │   ├── LuckyBox.jsx             # 럭키 컬러/숫자/방향
    │   ├── ElementBarChart.jsx      # 오행 5색 가로 바
    │   ├── SajuPillars.jsx          # 4기둥 8자 표시
    │   ├── MonthlyFlow.jsx          # 12개월 운세 흐름 차트
    │   ├── InterpretAccordion.jsx   # AI 12항목 아코디언
    │   └── HoryungQuote.jsx         # 호령 말풍선
    ├── Saju.jsx                     # 메인 페이지
    ├── SajuResult.jsx               # 사주풀이 결과
    ├── Today.jsx                    # 오늘의 운세
    └── Compatibility.jsx            # v2 placeholder
```

### 4-2. 라우팅 (변경 없음, Task 28에서 등록됨)

| 경로 | 컴포넌트 | reading_id 필요 |
|------|---------|----------------|
| `/saju` | Saju.jsx (메인) | 아니오 |
| `/saju/result?rid=N` | SajuResult.jsx | 예 |
| `/saju/today?rid=N` | Today.jsx | 예 |
| `/saju/compatibility` | Compatibility.jsx (placeholder) | — |

기존 `/saju/result` 등은 Task 28에서 placeholder로 등록 — 본 task에서 실제 컴포넌트로 교체.

### 4-3. 데이터 흐름

```
[사용자] → /saju (메인)
   ↓ 사주 입력
   ↓ sajuInterpret(form)
   ↓ POST /api/saju/interpret
[saju-lab] 계산 + Claude AI + fortune_scores + lucky + monthly_flow
   ↓ 응답: { reading_id, ... 풍부한 데이터 }
[프론트] navigate(`/saju/result?rid=${reading_id}`)

[사주풀이 페이지] /saju/result?rid=N
   ↓ useSajuReading(N) → sajuGetReading(N)
   ↓ GET /api/saju/readings/N
   ↓ saju_data + analysis_data + daeun_data + interpretation_json + fortune_scores + lucky + monthly_flow
   ↓ 렌더

[오늘운세] /saju/today?rid=N — 사용자가 메인 또는 사주풀이에서 클릭
   ↓ useSajuReading(N) + sajuCurrentFortune(N)
   ↓ 렌더: ring + 4 score + lucky + 오늘 세운
```

### 4-4. 호령 마스코트

`HoryungMascot.jsx` — `pose` prop으로 6개 PNG 중 선택.

```jsx
<HoryungMascot pose="greeting" size="lg" />     // 메인 좌상단
<HoryungMascot pose="thinking" size="md" />      // 사주풀이
<HoryungMascot pose="pointing" size="md" />      // 오늘운세
<HoryungMascot pose="happy" size="sm" />         // 점수 높을 때 (옵션)
```

`onError` 핸들러로 PNG 누락 시 silent (디자인 깨짐 방지).

### 4-5. CSS 격리 + 컬러 시스템

`Saju.css`:

```css
.saju-page {
  /* 베이스 */
  --saju-cream: #FAF6EE;
  --saju-paper: #F2EAD8;
  --saju-ink: #2E2D45;        /* 다크 네이비 (헤더, 본문) */
  --saju-ink-deep: #1F1D38;
  
  /* 액센트 */
  --saju-gold: #D4A574;
  --saju-gold-deep: #B5874E;
  --saju-apricot: #C58F76;
  --saju-rose: #D9A2A6;
  --saju-jade: #4B7065;
  --saju-violet: #6A5285;
  
  /* 카테고리 (3 ActionCard) */
  --saju-today-bg: #4B7065;      /* 청록 (오늘운세) */
  --saju-gunghab-bg: #A8736E;    /* 살구 (궁합) */
  --saju-saju-bg: #4F4A78;       /* 보라 (사주풀이) */
  
  /* 점수 카테고리 (4 ScoreCard) */
  --saju-wealth: #D4A574;        /* 골드 (재물) */
  --saju-romance: #D9A2A6;       /* 로즈 (연애) */
  --saju-social: #4B7065;        /* 청록 (인간관계) */
  --saju-career: #6A5285;        /* 보라 (직장) */
  
  min-height: 100vh;
  background: var(--saju-cream);
  color: var(--saju-ink);
  font-family: 'Pretendard', sans-serif;
}

.saju-page .saju-h1,
.saju-page .saju-h2 {
  font-family: 'Noto Serif KR', serif;
  font-weight: 700;
  letter-spacing: -0.02em;
}
```

모든 saju 컴포넌트의 클래스는 `saju-` prefix로 시작 (다른 페이지와 격리).

### 4-6. 반응형

- 기준: `1280px+` 데스크탑 (시안 그대로)
- `768~1280px` 태블릿: hero 컬럼 → 세로 스택, action card 3 → 2x2 grid
- `~768px` 모바일: 호령 작게 (size="sm"), action card 1열, 입력 폼 세로

`@media` 쿼리로 `Saju.css` 안에서 처리.

### 4-7. 폰트

`index.html`에 Google Fonts preconnect + Noto Serif KR 추가:

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Noto+Serif+KR:wght@500;700&display=swap" rel="stylesheet">
```

큰 제목(h1/h2)만 Noto Serif KR, 본문은 기존 Pretendard.

---

## 5. 컴포넌트별 세부

### 5-1. Saju.jsx (메인)

레이아웃 (시안 horyung_saju_main.png):
- 상단: SajuNav (호령사주 로고 + 4 nav + "사주풀이 시작하기" 버튼)
- Hero: 좌측 호령(front + greeting 박스) / 우측 큰 h1 + 3 ActionCard
- Bottom: 좌측 통계 미리보기 / 우측 SajuInputForm

폴백: reading_id가 query에 있으면 (`/saju?rid=N`) 통계 영역에 미리보기 점수 + 마지막 분석 결과로.

### 5-2. SajuResult.jsx (사주풀이)

레이아웃 (시안 horyung_saju_saju.png):
- 상단: SajuNav + "사주풀이" 큰 타이틀 + 기본 정보 (이름, 생년월일) + 호령(thinking)
- 중단 좌: 사주 4기둥 표 (SajuPillars) + 오행 바 차트 (ElementBarChart)
- 중단 우: 호령의 비전 박스 (HoryungQuote — interpretation의 summary 발췌)
- 하단: 성격강점 / 직업운 / 재물운 / 연애운 4 카드 (12항목 중 추출) + 12개월 운세 흐름 (MonthlyFlow)
- 우하단: 이번 달 핵심 결정 포인트 (interpretation_json.advice)

데이터: `useSajuReading(rid)` → saju + analysis + daeun + interpretation_json + monthly_flow

### 5-3. Today.jsx (오늘의 운세)

레이아웃 (시안 horyung_saju_today.png):
- 상단: SajuNav + "오늘의 운세" 큰 타이틀 + 호령(pointing) + 풍경 배경
- 중단: FortuneRing(overall) + 4 ScoreCard(wealth/romance/social/career) + LuckyBox
- 하단: 행운 알림 / 위험 알림 (lucky.good_signs, lucky.warnings)
- 최하단: 다음 페이지 (사주풀이 / 궁합보기) 버튼

데이터: `useSajuReading(rid)` → fortune_scores + lucky + `sajuCurrentFortune(rid)` → 오늘 세운

### 5-4. Compatibility.jsx (v2 placeholder)

```jsx
export default function Compatibility() {
  return (
    <div className="saju-page saju-page--compat-stub">
      <SajuNav />
      <div className="saju-stub">
        <HoryungMascot pose="thinking" />
        <h2>궁합보기는 곧 만나요!</h2>
        <p>두 사람의 사주를 함께 풀어보는 기능을 준비 중입니다.</p>
        <Link to="/saju">메인으로 돌아가기</Link>
      </div>
    </div>
  );
}
```

백엔드 `/api/saju/compat/*`는 이미 동작하지만 UI는 v2에서 정식 구현.

---

## 6. 에러 처리

| 시나리오 | 처리 |
|---------|------|
| 메인 입력 폼 — 잘못된 날짜 | Pydantic 422 → 폼에서 "올바른 날짜를 입력해주세요" |
| Claude API 504/500 | "잠시 후 다시 시도해주세요" + 사용자 입력 보존 |
| reading_id 무효(404) | "사주 결과를 찾을 수 없습니다" + 메인으로 돌아가기 버튼 |
| 호령 PNG 누락 | onError로 silent hide (디자인은 살짝 빈 자리, 동작은 정상) |
| fortune_scores 산출 실패 (예외) | 기본값 60/60/60/60으로 fallback + 콘솔 warn |

---

## 7. 테스트 전략

### 백엔드
- fortune_scores: 5-8 unit test (각 카테고리 high/low 케이스 + clamp)
- lucky: 5 unit test (오행→컬러 매핑, 숫자 1-9 범위, 방향)
- monthly_flow: 3 unit test (12 entries, 점수 범위, 충/합 영향)
- 기존 30 reference fixture 비교: 영향 없음 (응답 추가 필드만)

### 프론트
- 컴포넌트 단위 테스트는 v1 범위 밖 (수동 e2e 검증)
- 로컬 e2e: `npm run dev` + 입력 → 사주풀이/오늘운세 1회 정상 동작
- 호령 6 PNG 모두 존재 확인 (수동)
- 반응형 — Chrome DevTools 1280/1024/768 3가지 확인

---

## 8. 위험 + 완화

| 위험 | 완화 |
|------|------|
| 호령 PNG crop 좌표가 부정확 | plan 단계에서 PIL로 trial-and-error + 사용자 검수. onError로 silent fallback |
| fortune_scores 점수 산식이 명리학적 부정확 | v1은 plausible default + base 60으로 보수적. 실사용 피드백으로 튜닝 |
| 시안 색상과 미세 차이 | 시안 PNG에서 color picker로 hex 추출 후 CSS variable로 명시 |
| Noto Serif KR Google Fonts 로드 지연 | display=swap로 폰트 fallback (Pretendard) → 깜빡임 최소화 |
| reading_id 만료(DB row 삭제) | 404 graceful fallback + 새 입력 유도 |
| Claude 응답 시간 초과 | nginx timeout 300s + 폼에서 progress 표시 |

---

## 9. 향후 (v2, 본 spec 밖)

- 궁합보기 페이지 정식 구현 (시안 horyung_saju_gunghab.png 기반)
- 상담안내 페이지 (nav에 있는 메뉴)
- 즐겨찾기/히스토리 페이지 (sajuListReadings 활용)
- 사주풀이 PDF 내보내기
- 호령 캐릭터 lottie 애니메이션 (정적 PNG → 동적)

---

## 10. 참고

- 시안: `source/images/saju_page/horyung_saju_{main,today,gunghab,saju}.png`
- 캐릭터: `source/characters/horyung.png`
- 컬러시트: `source/images/saju_page/saju_color_sheet.png`
- 백엔드: web-backend/saju-lab/ (SHA 8123f75)
- 직전 spec: `docs/superpowers/specs/2026-05-25-saju-tarot-lab-migration-design.md` (saju-lab 백엔드 설계)
- web-ui Task 28 commit: e634cde (api.js + routes + IconSaju + placeholder pages)
