Energy Meal 기능명세서 v3
— 술 · 안주 페어링

1.배경 및 확정 방향

v2까지의 Energy Meal은 사주(오행) 기반 식사 추천에 집중했습니다. v3는 저녁 추천을 받은 사용자가 "오늘 한잔" 상황일 때, 마실 술을 고르면 사주 개인화를 유지한 채 어울리는 안주를 추천하는 안주 모드를 추가합니다. 기존 오행 스코어링 위에 술↔안주 궁합 축을 결합하는 확장이며, 식사 추천 엔진 자체는 건드리지 않습니다.

2.사용자 플로우 · 화면 구성

안주 결과에서 나가는 동선은 3종입니다.

• 술 바꾸기 — 상단 술 바에서 술 선택(06)으로 복귀
• 다른 안주 보기 — 재추천 (기존 diversity 로직 재사용)
• 식사 추천으로 돌아가기 — 푸터 링크. 안주 모드를 해제하고 today 결과로 복귀

3.기능 명세

FR-601안주 모드 진입

• 진입 배너("오늘 한잔?")는 모든 끼니 탭 결과에 상시 노출합니다. 아침 · 점심에도 저녁 술자리를 미리 계획할 수 있도록 v3.0.1에서 dinner 한정 노출을 해제했습니다.
• 배너는 나이트 톤(§7)으로 렌더링하여 모드 전환을 시각적으로 예고합니다.
• 안주 모드는 화면 전환 상태이며, 사용자 저장 데이터(UserData)에는 아무것도 기록하지 않습니다.

FR-602술 선택

• 대분류 6종(소주 / 맥주 / 와인 / 막걸리·전통주 / 위스키·하이볼 / 사케)을 2×3 카드 그리드로 노출합니다.
• 단일 선택이며, 선택 전에는 CTA를 비활성화합니다.
• 세부 주종(레드/화이트, 라거/에일 등) 구분은 하지 않습니다(§8 범위 제외).

FR-603안주 후보 구성

• 안주 후보는 시간대 필터 대신 안주 태깅된 메뉴 전체로 구성합니다(페어링 가능 술이 1종 이상인 메뉴).
• 안주 전용 신규 메뉴는 일반 식사 추천 후보에 섞이지 않게 처리합니다. 확정 — time: [] 방식(별도 플래그 없음, 기존 시간대 필터가 자연 제외. §6 참조).

FR-604안주 스코어링

• 선택한 술의 궁합 계열(baseMenu 매칭)에 +4 가점을 부여하고, 기존 오행 가점(부족 오행 +5 · 일진 상생 +2 · 랜덤 10% +1)을 유지합니다. 상세는 §5.
• 온도 · 무게 반대 가점(각 +1)은 안주 모드에서 제외를 검토합니다 — 안주는 "식사 균형"보다 "술과의 궁합"이 우선이므로. 구현 · 테스트 단계에서 확정합니다.

FR-605페어링 코멘트

• 결과 카드에 술 오행 + 오늘의 사주를 결합한 코멘트를 노출합니다.
  예: "오늘 부족한 화(火) 기운을 매콤한 안주로 채워요."
• 술 오행 태깅(§4)은 코멘트 생성("술 기운 + 오늘 일진")에 사용하고, 점수 비중은 작게 둡니다.

FR-606안주 추천 결과 화면

• 기존 결과 카드 레이아웃을 재사용하고, 상단에 선택한 술 배지(술 바)를 추가합니다.
• "다른 안주 보기" 재추천은 기존 diversity 로직(baseMenu 계열 순환)을 그대로 사용합니다.
• 이탈 동선 3종(술 바꾸기 · 다른 안주 보기 · 식사 추천으로 돌아가기)을 제공합니다(§2).

FR-607나이트 모드 전환

• 술 선택(06) · 안주 결과(07) 화면은 나이트 팔레트(§7)를 전면 적용합니다.
• CTA · 뱃지 · 칩 · 소형 버튼은 나이트 전용 컴포넌트(§7.1)를 사용합니다.
• 식사 추천으로 돌아가면 즉시 기존 cream/terra 팔레트로 복귀합니다.

FR-608데이터 · 이미지 확장

• 기존 282종 중 저녁 117종을 중심으로 안주 적합 메뉴 78종에 페어링 술을 태깅했습니다(치킨 · 튀김 · 회 · 전골 · 멕시칸 등 재사용, MENU_PAIRINGS 맵).
• 안주 전용 메뉴 23종을 신규 추가했습니다 — 마른안주 7(치즈 플레이트 · 육포 · 믹스넛 · 황태포 · 노가리 · 쥐포 · 프로슈토), 꼬치 4(닭꼬치 · 염통 · 야키토리 · 소떡소떡), 전 3(감자전 · 녹두전 · 모둠전), 훈제 · 무침 2 · 계란 · 구이 · 멕시칸 · 튀김 · 만두 · 치킨 각 1.
• 신규 이미지는 v2.1 파이프라인을 재사용했습니다(Pencil 생성 → webp export → scripts/build-menu-image-map.mjs). 씬 스타일에 포차 · 호프 · 이자카야 · 전집 · 위스키/와인바 씬을 추가.

아래 두 건은 안주 페어링이 아니라 셸 · 신뢰성 영역입니다. v1 FR-401(PWA · 오프라인) · FR-402(WebView 임베드)의 후속으로, 문서 관행에 따라 현행 명세인 이곳에 기록합니다.

FR-609404 · 오프라인 화면

• 없는 주소로 들어오면 Next.js 기본 404 대신 브랜드 화면(app/not-found.tsx)을 보여줍니다 — 아이콘 원 · 404 · 끊긴 경로 칩(현재 pathname) · 오늘의 추천 보기 / 이전으로 · 빠른 이동 칩 3종(오늘의 추천 · 정보 입력 · 안주 추천). 끊긴 경로는 마운트 뒤 window.location.pathname 으로 읽습니다 — usePathname 은 프리렌더 시 /_not-found 를 줘서 매 방문마다 하이드레이션 불일치(React #418)가 났습니다(v3.1.2). 이전으로는 히스토리가 없으면(외부 링크 · 알림 · 새 탭) /today 로 보냅니다.
• 오프라인 폴백(/offline)은 같은 디자인 언어로 개편했습니다 — 아이콘 원 · 오프라인 상태 칩 · 다시 시도 / 홈으로 · 점검 칩 3종(Wi-Fi · 모바일 데이터 · 비행기 모드) · 자동 복구 안내. 브라우저 online 이벤트를 받으면 현재 주소를 다시 불러옵니다 — 이 화면은 원래 가려던 주소(알림 딥링크 등) 위에 서비스워커가 덮어씌운 것이라, / 로 보내면 그 목적지를 잃습니다(v3.1.2).
• 두 화면 모두 prefers-color-scheme: dark에서 나이트 팔레트(§7)로 넘어갑니다. 공통 조각은 components/status-screen.tsx(쉘 · 아이콘 원 · 칩 · 구분선 + 인라인 SVG 아이콘)에 모았습니다.
• 오프라인 화면은 서버 컴포넌트입니다(v3.1.1). 이 화면이 뜨는 순간은 정의상 네트워크가 없는 때라 /_next/ 청크를 받을 수 없습니다 — 클라이언트 컴포넌트로 두면 하이드레이션이 붙지 않아 버튼이 죽은 장식이 됩니다. 동작에 필요한 최소한(다시 시도 · 복구 시 자동 복귀)만 인라인 스크립트로 싣고, 홈으로는 SSR 에서 평범한 <a href> 로 나오는 링크라 스크립트가 통째로 실패해도 눌립니다. 서비스워커는 내용 해시가 붙은 빌드 자산(/_next/static/)을 받는 대로 쟁여 두어, 캐시된 /offline 이 CSS 없이 맨 HTML 로 뜨지 않게 합니다(v3.1.2 — 이전엔 폴백 분기만 있고 쟁이는 곳이 없어 죽은 코드였습니다). precache 는 /offline 만 필수이고 아이콘류가 실패해도 설치를 막지 않습니다.
• 운영 주의 — 서비스워커 캐시 버전. public/sw.js는 /offline을 APP_SHELL로 precache합니다. 이 페이지를 고쳤으면 CACHE_NAME(energy-meal-vN)도 반드시 함께 올려야 합니다 — sw.js가 한 바이트도 바뀌지 않으면 브라우저는 갱신을 시도조차 하지 않아 옛 화면이 계속 나옵니다(v3.1.0 배포 직후 실제로 발생, v3.1.1에서 v3 → v4). 갱신은 온라인에서 완전히 로드된 뒤 적용되므로, 검증은 ① 온라인 완전 로드 → ② 앱 완전 종료 → ③ 오프라인 전환 순서로 합니다.
• 색 · 간격 · 라운드는 전부 기존 토큰 값을 씁니다. 시안은 design/energy-meal.pen 「웹 404 · 데이/나이트」 · 「웹 오프라인 · 데이/나이트」.

FR-610앱 웹뷰 오프라인 복구

• 앱 셸은 네트워크가 끊기거나 로드에 실패하면 웹뷰 내장 에러 페이지가 그대로 노출됐습니다. renderError로 이를 막고 그 자리에 오프라인 화면(components/offline-state.tsx)을 그립니다.
• CTA는 다시 시도 = 같은 웹뷰 reload(), 홈으로 = 웹뷰 재마운트 후 시작 주소로 복귀입니다. 에러 상태에서도 웹뷰를 걷지 않아 복구 시 히스토리를 잃지 않습니다.
• 연결 복구는 네이티브 의존성 없이 감지합니다 — 오프라인 화면이 떠 있는 동안에만 3초 주기로 시작 주소에 HEAD 요청을 보내고(타임아웃 4초), 응답이 오면 자동으로 reload() 합니다. 포그라운드 복귀(AppState active)에는 주기를 기다리지 않고 즉시 확인합니다. 응답 코드는 보지 않습니다 — 서버에 닿았다는 것 자체가 연결이 돌아온 신호입니다.
  NetInfo(@react-native-community/netinfo)를 쓰면 복구를 더 빨리 잡지만 네이티브 모듈이라 APK 재빌드가 필요해, 재빌드 없이 가는 쪽을 택했습니다(사용자 결정).
• 아이콘은 앱에 react-native-svg가 없어 .pen에서 PNG로 뽑아 app/assets/offline/에 두고, 작은 칩 아이콘은 단색 실루엣 + tintColor로 테마 색을 입힙니다.
• 앱 셸은 아직 크림(데이) 한 벌로만 돌기 때문에 화면은 데이 톤으로 뜹니다. 나이트 팔레트는 tone 값으로 함께 갖춰 두어, 안주 모드처럼 어두운 화면에서 끊겼을 때 바로 쓸 수 있습니다.
• 서비스워커는 웹뷰 안에서 등록하지 않습니다(v3.1.2). 등록돼 있으면 네트워크가 끊길 때 sw 가 캐시된 웹 /offline(FR-609)을 먼저 내줘 이 화면과 probe 가 영영 안 탑니다 — v3.1.0~v3.1.1 에서 "잘 된다"고 확인한 앱 오프라인 화면은 실은 그 웹 화면이었고, 진짜 renderError 경로는 검증되지 않은 채였습니다. 그 경로의 결함도 같이 고쳤습니다: renderError 가 돌려준 뷰는 웹뷰 위에 덮이는 게 아니라 형제로 나란히 붙어서, flex: 1 만으로는 화면이 반으로 갈리고 위 절반에 크로미움 내장 에러 페이지가 남았습니다 → 절대 위치로 꽉 채웁니다. 이전 버전이 등록해 둔 sw 는 다음 온라인 로드 때 걷어냅니다. 검증은 앱 데이터 삭제 후 오프라인 첫 실행으로 합니다 — 온라인으로 한 번이라도 뜬 뒤라면 (구버전에선) sw 가 가로채 이 화면을 볼 수 없었습니다.
• 자동 복구가 실제로는 한 번도 돌지 않았습니다(v3.1.2 수정). 로드가 실패하면 크로미움이 내부 에러 페이지로 넘어가면서 loadStart를 한 번 더 쏘는데, 그 핸들러가 hasError를 풀어 probe 가 무장되자마자 해제됐습니다(logcat: error → effect armed → loadStart, 이후 probe 시작 로그 없음). 에러는 성공한 로드에서만 오는 onLoad에서 풀도록 바꿨고, 에뮬레이터에서 오프라인 → 네트워크 복구 → 자동 재로드를 확인했습니다.

FR-611앱 스플래시 · 첫 화면 전환

• 스플래시는 2단계입니다 — 네이티브(배경색만) → RN 오버레이(로고 + 워드마크 + 태그라인) → 웹. 안드로이드 12+ 네이티브 스플래시는 "배경색 + 중앙 아이콘"만 허용해 워드마크 · 태그라인을 실을 수 없습니다.
• 네이티브는 배경색만(v3.1.2) — 처음엔 네이티브에 로고를 띄우고 오버레이에서 로고 + 타이틀로 이어 붙였는데(v3.1.1), 두 단계의 로고 위치를 완전히 맞출 수 없었습니다. 맞추면 덩어리가 처지고(v3.1.1 은 56dp 아래), 덩어리를 중앙에 두면(v1.1.9) 넘어가는 순간 로고가 45dp 튑니다. 그래서 네이티브 이미지를 완전 투명 PNG(splash-blank.png)로 바꿔 크림 배경(#f6efe5)만 보이게 하고, 오버레이의 로고 + 타이틀이 그 위로 페이드로 떠오르게 했습니다 — 튈 것이 없습니다. 오버레이 덩어리는 화면 중앙입니다.
• 이음매 — preventAutoHideAsync()로 네이티브를 붙잡아 뒀다가 오버레이의 첫 onLayout에서 내립니다(fade 300ms). 자동 숨김을 막았으므로 hideAsync는 onLayout · 로드 완료 · 로드 실패 · 최후 안전장치 네 곳에서 부릅니다.
• 노출 시간 — 첫 실행의 오버레이는 최소 1.5초(오버레이 첫 레이아웃 기준) 머문 뒤 걷습니다(v3.1.3). v3.1.1 에서 vidding-app 을 따라 최소 노출을 없앴는데, 그쪽이 몇 초 보이는 건 웹이 무거워 로드가 오래 걸려서일 뿐 코드엔 최소 시간이 없습니다 — 이 웹은 서버 없는 정적 페이지라 1초 안에 떠서 같은 코드가 여기선 깜빡임이 됐습니다(사용자 피드백). 1.8초(v3.0.x)는 매번 기다리는 느낌이 있어 1.5초로. 재시도 · 홈으로에는 적용하지 않습니다. 다만 onLoadEnd는 HTML을 받은 시점일 뿐이라 그때 걷으면 빈 화면이 비칩니다 — 첫 화면을 클라이언트에서 그리고 /에서 /today로 갈아타기 때문입니다. 웹이 <main>에 실제 콘텐츠를 넣으면 painted 신호를 보내고(config/webview-bridge.ts, 안 오면 1.2초 백업), 그 신호에 맞춰 450ms 페이드로 걷어 웹의 진입 애니메이션(0.45초)과 겹칩니다.
• 스피너 — 오버레이가 뜬 뒤 10초를 넘겼을 때만 붙입니다. 타이머는 오버레이가 뜰 때마다 새로 셉니다(v3.1.2 — 앱 기동 기준 한 번만 재면 재시도 · 홈으로 이후 오버레이에 스피너가 즉시 붙었습니다). 평소에는 브랜드 화면만 보입니다.

FR-612웹 화면 셸 — 가운데 열 · 문서 스크롤

• 넓은 화면(브라우저)에서 화면을 폰 베젤(둥근 모서리 · 검은 테두리 · 820px 고정 높이) 안에 그리고 그 안에서만 스크롤하던 방식을 걷어냈습니다(v3.1.4, 사용자 피드백 "아래로 스크롤했는지 구분이 안 간다"). 스크롤바를 숨겨 둔 탓에 아래에 내용이 더 있는지 알 수 없었고, 베젤 바깥에서 휠을 굴리면 아무 일도 없었습니다.
• 이제 모든 화면(온보딩 · 정보 입력 · 오늘의 추천 · 술 고르기 · 안주 결과)은 공용 components/app-shell.tsx 위에 놓입니다 — 열 폭 --shell-width(globals.css)를 가운데 두고 문서 자체가 스크롤합니다(vidding-re 와 같은 방식). 브라우저 스크롤바가 돌아오고 휠이 어디서든 먹습니다. 열 좌우 경계선은 마우스가 있는 기기에서만(pointer: fine) 긋고, 태블릿 · 펼친 폴드에서는 선 없이 가운데 정렬만 합니다.
• 마우스로 보는 웹(데스크톱 · 노트북)은 430px 폰 화면 그대로를 가운데 둡니다(v3.1.6) — 넓게 펼치면 한눈에 보기 힘듭니다(사용자 피드백). 터치 기기(폰 · 펼친 폴드 · 아이패드)는 열이 화면 폭을 그대로 채웁니다 — 글자 크기는 그대로 두고 카드 · 탭 · 버튼만 폭에 따라 늘어나는, 모바일 반응형과 같은 방식입니다. 구분은 @media (pointer: coarse) 하나(globals.css, 터치 기기에서 --shell-width 를 none 으로) — 기기 목록을 들고 있지 않으므로 폴드 6/7/8 · 폴드형 아이패드처럼 새 기기가 나와도 손댈 것이 없습니다. 폴드는 접힌 커버(≈384px)에서 전폭, 펼치면(≈750~790px) 그 폭을 그대로 채우고, 접고 펼치는 순간 다시 흐릅니다(높이 고정 없음, min-h-dvh). 앱 웹뷰는 종전대로 폭 제한 없음.
• 넓은 열에서 정사각 이미지 카드가 세로를 넘치지 않게 카드 높이는 뷰포트의 60%(max-h-[60dvh])로 누르고 가운데를 잘라 보입니다(object-cover). 크로미움 실측: 폴드6 펼침 750×884 → 열 750, 카드 684×530 · 폴드7 펼침 790×890 → 열 790 · 아이패드 11 세로 820×1180 → 열 820, 카드 754×708 · 아이패드 가로 1180×820 → 열 1180, 카드 1114×492 · 폴드 커버 384 → 전폭 · 노트북 1280×720 · 데스크톱 1440×900 → 열 430(마우스). v3.1.5 의 폰 화면 통째 확대(zoom, min(폭/430, 높이/600)≤1.5)는 데스크톱에서 너무 커 보기 힘들어 같은 날 걷어냈습니다 — 그때 넣은 배율 스크립트 · suppressHydrationWarning 도 함께 제거.
• 앱 웹뷰에서는 종전과 같이 폭 제한도 경계선도 없습니다(창이 곧 화면). 추천 ↔ 술 고르기 ↔ 안주 결과는 같은 라우트 안에서 화면만 갈아 끼우므로, 전환 때 문서 스크롤을 맨 위로 올립니다 — 예전엔 화면마다 제 스크롤 영역이 있어 저절로 맨 위였습니다.

4.술 6종 프로파일

• 술 오행 태깅은 v2 §5 매핑 기준(수=차가움 · 해산물, 토=곡물 · 구수함 등)을 술에 적용한 안입니다. 페어링 코멘트(FR-605)에 사용하며 점수 비중은 작게 둡니다.
• 궁합 계열은 기존 baseMenu(계열) 값과 매칭합니다.

5.안주 스코어링

안주 후보(FR-603) 각 메뉴에 아래 가점을 합산해 정렬합니다. 동점은 궁합 매칭 → 부족 오행 매칭 → 원본 순서로 정렬합니다.

6.데이터 스키마 변경

7.디자인 파운데이션 — 나이트 모드

식사 모드(cream 배경 + terra 액센트)와 안주 모드를 시각적으로 구분하는 전용 팔레트입니다. 배경은 coal 그라데이션(coal-800 → coal-900), 액센트는 amber 계열을 사용하고, CTA는 amber 배경 위 다크 텍스트(night-on-accent)로 대비를 확보합니다. 토큰은 design/energy-meal.pen의 DS / Colors NIGHT 섹션에 등록되어 있습니다.

• 적용 범위 — 06 술 선택 · 07 안주 결과는 전면 적용, 05 진입 배너는 배너 영역만 나이트 톤(모드 전환 예고).
• 구현 시 웹 토큰(CSS 변수)으로 이식하며, 모드 전환에 따른 테마 스위칭 방식은 구현 단계에서 결정합니다.

7.1 나이트 컴포넌트

나이트 모드 전용 재사용 컴포넌트 4종입니다. design/energy-meal.pen의 DS / Components · Night 프레임에 등록되어 있으며(기존 DS / Components와 별도 프레임), 06 · 07 화면의 CTA · 뱃지 · 칩 · 소형 버튼은 모두 이 컴포넌트의 인스턴스입니다. 구현 시 기존 컴포넌트의 나이트 변형(variant)으로 이식합니다.

8.범위 제외 (v3에서 안 하는 것)

• 세부 주종(레드/화이트, 라거/에일), 도수 · 브랜드, 논알콜, 여러 술 조합.
• 홈 별도 진입점 — 반응을 보고 v3.1 후보로 검토.

9.구현 단계 계획

10.테스트 계획

11.개정 이력