Energy Meal 기능명세서 v2
— 사주팔자 · 오행 엔진 고도화

1.고도화 배경 및 목표

v1 추천 엔진은 사주 컨셉만 차용한 간이 규칙(출생 시각 · 생월 · 생일 일자 기반)으로, 실제 사주 요소가 없고 사용자별 · 날짜별 차별성이 부족했습니다. v2는 엔진을 만세력 기반 사주팔자 · 오행 분석으로 전면 교체합니다.

2.신규 추천 파이프라인

시간대 필터와 이미지 다양성 재정렬(v1 §5.2, §5.4)은 검증된 로직이므로 그대로 유지하고, 상태 추론과 스코어링 단계만 교체합니다.

3.기능 명세

FR-501음력 → 양력 변환

• calendarType이 음력인 경우, 사주 계산 전에 생년월일을 양력으로 변환합니다.
• 윤달 입력은 1차 범위에서 평달로 간주합니다(입력 UI에 윤달 구분이 없음).
• 변환 결과는 사주 계산에만 사용하며, 화면 표기는 사용자가 입력한 원본 값을 유지합니다.

FR-502사주팔자 계산

• 양력 기준 생년월일시로 년주 · 월주 · 일주 · 시주(각 천간 + 지지)를 계산합니다. 규칙 상세는 §4 참조.
• unknownBirthTime = true이면 시주를 제외한 3주 6자로 계산합니다.
• 시지(時支)는 사용자가 선택한 십이시 구간이 직접 결정합니다. 분 단위 진태양시 보정은 구간 선택 UI 특성상 적용하지 않습니다(§7 결정 참조).

FR-503오행 분포 및 부족 오행 판정

• 팔자 각 글자를 목(木) · 화(火) · 토(土) · 금(金) · 수(水)로 매핑해 분포를 집계합니다. 1차 범위는 지장간 없이 본기만 반영합니다.
• 일간(日干)을 "나의 기운"으로 정의하고, 분포에서 개수가 가장 적은 오행(동률 허용)을 부족 오행으로 판정합니다.
• 부족 오행이 곧 추천의 주 가점 기준이 됩니다(보완 컨셉 — v1의 "반대 속성 보완"을 오행으로 일반화).

FR-504오늘의 일진

• 접속일 기준 오늘의 일진(60갑자)을 계산하고, 일진 천간의 오행을 오늘의 기운으로 사용합니다.
• 일진 오행은 스코어링 보조 가점과 풀이 문구에 반영되어, 같은 사용자라도 날짜에 따라 추천과 풀이가 달라집니다.
• 결과 화면 하단 문구 "내일은 또 다른 기운이 찾아올 거예요"가 실제 동작과 일치하게 됩니다.

FR-505메뉴 오행 태깅

• 메뉴 전체(현행 253종 — 안주 전용 포함. 한때 1,000종까지 늘렸다가 v3.0.20에서 실제로 사 먹을 수 있는 메뉴 위주로 재정비)에 element(오행) 속성을 부여합니다. 분류 기준은 §5의 매핑표를 따릅니다.
• 기존 온도 · 무게 속성은 삭제하지 않고 보조 가중치 축으로 유지합니다.

FR-506오행 기반 스코어링 (확정)

시간대 후보군의 각 메뉴에 아래 가점을 합산해 정렬합니다.

• 동점 시 부족 오행 일치 메뉴 우선 → 날짜 시드 기반 랜덤 → 원본 데이터 순서로 정렬합니다. 랜덤 타이브레이크가 없으면 같은 조건의 날마다 동점 무리의 맨 앞 메뉴가 늘 1순위로 고정됩니다.
• 비일치 메뉴의 이론상 최대 점수는 +5(1+2+1+1)로, 부족 오행 일치 메뉴(최소 +5)와 동점이 되어도 타이브레이크에서 밀립니다.
• 이미지 다양성 재정렬은 v1 로직을 그대로 재사용합니다.

FR-507사주 풀이 노출

• 결과 화면의 추천 이유 영역을 이미지별 고정 문구에서 사주 기반 동적 풀이로 교체합니다.
• 풀이 구성: 나의 기운(일간 오행) + 부족 오행 + 오늘의 일진 + 추천 근거.
• 쉬운 말 원칙(v2.5 개정) — 사주를 모르는 사용자가 "임수가 뭔지, 화 기운이 부족해서 뭘 어쩌라는 건지" 묻지 않게 합니다. 풀이 문장에는 일간 · 오행 · 일진 같은 용어와 "다섯 기운" 개념 자체를 쓰지 않고, 용어는 정보 칩에만 남깁니다. (같은 날 1차 개정은 "촛불처럼 따뜻하고 섬세한 정화(丁火)의 당신은 타고난 다섯 기운(오행) 중 나무(木)의 생기와 불(火)의 온기가 가장 적은 편이에요"처럼 용어를 괄호로 뒤에 두는 방식이었으나, "정화의 당신 · 다섯 기운 중 나무와 불이 적다는 내용 자체가 이해가 안 된다"는 피드백으로 같은 날 철회)
  • 짧게, 한두 문장(60자 이내) — 타입 설명("촛불처럼 따뜻하고 섬세한")은 칩 "나의 기운"에 맡기고 문장에 넣지 않습니다. 문장에는 이 메뉴가 채우는 부족한 것 한 가지 + 메뉴만 담습니다. 부족 오행은 사람에게 뜻하는 것(활력 · 온기 · 든든함 · 집중력 · 여유)으로, 메뉴에는 짧은 수식(뜨끈한 · 상큼한 · 구수한 · 담백한 · 깊은 맛의)을 붙입니다. (부족 오행은 사주에서 정해지므로 "오늘 부족한 하루"가 아니라 "부족해지기 쉬운 당신"처럼 타고난 경향으로)
  • 메뉴마다 문장 뼈대가 달라집니다 — "다시 추천하기"로 넘겨도 메뉴 이름만 바뀌고 나머지가 똑같다는 피드백(같은 날 2회: 이름만 바뀜 → 조각만 바꿔도 여전히 비슷하고 길다)으로, 부족 보완 뼈대 5종("○○이 부족해지기 쉬운 당신, 오늘 저녁은 뜨끈한 △△ 어때요?" / "오늘 저녁은 △△로 ○○을 채워 보세요. 밤이 한결 포근해질 거예요." / "△△이면 모자란 ○○이 채워질 거예요." / "○○ 충전이 필요한 날엔 △△만 한 게 없어요." / "○○이 모자라기 쉬운 당신에게 △△, 오늘 저녁 추천이에요.") · 일진 가점 뼈대 3종("오늘은 날짜의 기운이 △△을 밀어주는 날이에요 …") · 균형 뼈대 3종("기운의 균형을 지켜 주는 △△ …") · 음식 수식 오행별 3종을 골라 조합합니다. 뼈대는 추천 목록 위치 순서로 돌려("다시 추천하기" 1번째 → 2번째 → …) 연달아 같은 뼈대가 나오지 않게 하고, 음식 수식은 메뉴 id 해시(FNV-1a + fmix)로 고릅니다(같은 메뉴는 같은 수식). 위치가 없는 호출은 뼈대도 해시로 고릅니다.
  예: "온기가 부족해지기 쉬운 당신, 오늘 저녁은 뜨끈한 골뱅이무침 어때요?" / "뜨끈한 김치찌개면 모자란 온기가 채워질 거예요."
  (v2.0~v2.4: "정화(丁火) 기운의 당신은 오늘 목(木)·화(火) 기운이 부족한 하루예요. 부족한 화(火) 기운을 골뱅이무침으로 채워 …")
• 정보 칩은 사주 용어가 남는 유일한 자리 — "나의 기운 · 촛불 정화(丁火)" · "오늘의 기운 · 나무(木) · 갑진일"(당초 "나의 기운 · 정화(丁火)" · "오늘의 일진 · 갑진(甲辰)").
• 문구는 부족 오행(5) × 추천 근거(3 — 부족 보완 · 일진 상생 · 균형) × 시간대(3) 템플릿에 메뉴별 뼈대 · 수식 선택을 더해 생성합니다. 어휘표는 아래와 같고(각 칸의 첫 버전만 표기) lib/saju/interpretation.ts의 ELEMENT_PLAIN · STEM_PLAIN(칩용) · 뼈대 배열이 원본입니다.
• 내 정보 요약 카드의 십이시 표기(자시~해시)는 유지합니다.

FR-508최근 추천 이력 (재추천 방지)

• 끼니 알림을 보고 들어왔을 때 어제와 같은 메뉴가 떠 있으면 열어볼 이유가 없습니다. 화면에 실제로 띄운 메뉴를 이력으로 남기고, 다음 날 스코어링에서 감점합니다.
• 저장 위치는 localStorage의 energy-meal:recent-menus — { date, slot, name, baseMenu } 배열이며 최대 150건까지 보관하고 넘치면 오래된 것부터 버립니다.
• 기록 시점: ① 화면 진입 시 세 끼니의 현재 추천(탭을 열지 않아도 기록) ② "다시 추천"으로 갈아탄 메뉴.
• 오늘 날짜 이력은 감점 대상에서 제외합니다. 포함하면 새로고침할 때마다 방금 본 메뉴가 밀려나 하루 고정 원칙(§FR-506 시드)이 깨집니다.
• 필터가 아닌 감점이므로 이력이 후보군을 다 덮어도 추천이 비지 않습니다. 끼니별 후보가 194~409종이라 14일 창(하루 3건 + 다시 추천분)에는 여유가 있습니다.

FR-509알림 진입 시 본 끼니 교체

• 추천은 하루 고정(§FR-506 시드)이라, 아침에 점심 · 저녁 탭까지 미리 열어본 사용자는 점심 알림을 눌러도 이미 본 메뉴를 다시 보게 됩니다. 알림을 눌러 들어온 진입에 한해 그 끼니를 다음 후보로 갈아 끼웁니다.
• "봤다"의 기준(v2.4 개정): 끼니 탭을 직접 누르면 그 즉시, 화면을 열 때 펴진 첫 탭도 즉시 본 것으로 기록합니다. 당초(v2.3)는 탭이 1.5초 이상 떠 있어야 했는데, 메뉴만 빠르게 훑고 넘기는 사용 습관에서는 기록이 남지 않아 알림으로 들어와도 이미 본 메뉴가 그대로 떴습니다(사용자 피드백). 1.5초 체류 기준은 자동으로 펴진 탭(백그라운드 복귀로 끼니가 넘어간 경우, 화면을 켜둔 채 자정을 넘겨 다시 만든 경우)에만 남깁니다 — 알림 진입 직전의 자동 전환까지 본 것으로 세면 정작 처음 보는 메뉴가 교체됩니다. 저장 위치는 energy-meal:viewed-slots — { date, slots }이며 날짜가 바뀌면 비워집니다.
• 열어보지 않은 끼니는 그대로 둡니다. 아침 · 점심만 봤다면 저녁 알림은 그날의 원래 추천을 보여줍니다.
• 진입 경로는 네이티브 셸이 붙이는 쿼리 /today?entry=meal-reminder&slot=<끼니>&n=<토큰>입니다. 토큰(알림 식별자 + 발생 시각)은 energy-meal:handled-entry에 남겨, 같은 알림으로 두 번 들어와도 연달아 교체되지 않게 합니다. 처리 후 쿼리는 주소창에서 지웁니다.
• 교체했을 때는 "오늘 이미 본 OO 메뉴라 새로 골랐어요" 안내와 "이전 메뉴 보기"를 함께 띄웁니다. 아침에 본 메뉴로 이미 마음을 정한 경우를 되돌릴 수 있어야 합니다.
• 그냥 앱을 다시 열거나 백그라운드에서 복귀한 경우에는 교체하지 않습니다. 메뉴가 바뀌는 계기는 알림 진입뿐입니다. 다만 백그라운드에 있는 동안 끼니가 넘어갔다면(아침 → 점심) 복귀 시 지금 끼니 탭으로 옮겨 줍니다.
• 결과 화면의 첫 탭은 지금 끼니입니다 — 0~10시 아침 · 11~16시 점심 · 17~23시 저녁(추천 엔진의 시간대 구분과 같음). 당초 0~4시는 저녁 탭이었으나, 날짜 시드가 자정에 바뀌어 새 날의 메뉴가 뜨므로 자정 직후 "오늘 메뉴"를 보러 온 사용자가 지난 저녁이 아닌 다음 날 저녁부터 보게 됐습니다 — v2.4에서 아침 탭으로 변경(사용자 결정).

4.사주 계산 규칙 상세

4.1 계산 예시 — 팔자 조합에서 추천까지

1996-08-22(양력) 진시(07:00–08:59) 출생 사용자의 실제 계산 흐름입니다.

시간을 모르는 경우 시주(壬辰)를 제외한 6자 분포로 같은 흐름을 적용합니다.

5.오행 · 음식 매핑 기준

메뉴 오행 태깅(FR-505)은 전통 오행 식품 분류(맛 · 색 · 성질)를 기준으로 하되, 메뉴의 주 재료와 조리 방식으로 판단합니다.

상생 관계(일진 가점 판정용): 목→화→토→금→수→목. 전체 메뉴의 확정 태깅은 web/lib/menu-data.ts의 시드 테이블(MENU_SEEDS)에 기록되어 있습니다.

6.데이터 스키마 변경

7.기술 결정 사항

8.구현 단계 계획

9.테스트 계획

10.개정 이력