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사주 풀이 노출

• 결과 화면의 추천 이유 영역을 이미지별 고정 문구에서 사주 기반 동적 풀이로 교체합니다.
• 풀이 구성: 나의 기운(일간 오행) + 부족 오행 + 오늘의 일진 + 추천 근거.
  예: "목(木) 기운의 당신은 오늘 수(水) 기운이 부족한 하루예요. 시원한 국물의 물냉면으로 균형을 채워보세요."
• 문구는 일간 오행(5) × 부족 오행(5) × 시간대(3) 조합의 템플릿으로 생성합니다.
• 내 정보 요약 카드의 십이시 표기(자시~해시)는 유지하며, 일간 정보(예: "갑목(甲木)의 하루")를 추가 노출할 수 있습니다.

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.개정 이력