diff --git a/docs/superpowers/specs/2026-05-26-saju-ui-design.md b/docs/superpowers/specs/2026-05-26-saju-ui-design.md new file mode 100644 index 0000000..8e8ac4c --- /dev/null +++ b/docs/superpowers/specs/2026-05-26-saju-ui-design.md @@ -0,0 +1,387 @@ +# 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 + // 메인 좌상단 + // 사주풀이 + // 오늘운세 + // 점수 높을 때 (옵션) +``` + +`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 + + + +``` + +큰 제목(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 ( +
+ +
+ +

궁합보기는 곧 만나요!

+

두 사람의 사주를 함께 풀어보는 기능을 준비 중입니다.

+ 메인으로 돌아가기 +
+
+ ); +} +``` + +백엔드 `/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)