docs(product): app atmosphere entry spec 추가

2026-03-16 11:04:02 +09:00
parent 3c5154178d
commit 56385ec2eb
4 changed files with 518 additions and 71 deletions
--- a/docs/12_core_loop_execution_roadmap.md
+++ b/docs/12_core_loop_execution_roadmap.md
@@ -14,6 +14,7 @@ Last Updated: 2026-03-15
 - `../../product_principles.md`
 - `../../current_context.md`
 - `09_app_entry_detailed_spec.md`
 - `19_app_atmosphere_entry_spec.md`
 - `10_refocus_system_spec.md`
 - `11_away_return_recovery_spec.md`
 - `15_app_stats_entry_flow_spec.md`
@@ -55,6 +56,21 @@ VibeRoom은 아래 방식으로 진행한다.
  - planner/list-first 구조 제거
  - current session이 있으면 resume 우선
 ### 다음 Phase A. `/app` Atmosphere Entry Redesign
 - 문서: `19_app_atmosphere_entry_spec.md`
 - 목적:
  - `/app` no-session 상태를 `goal + duration + atmosphere` 중심의 premium entry stage로 재설계
  - scene/sound를 다시 entry 가치로 끌어올리되 planner/dashboard처럼 보이지 않게 유지
 - 핵심 변화:
  - microStep 제거
  - duration을 분 단위 직접 입력으로 전환
  - `Atmosphere` 12개 그리드 도입
  - weekly review는 quiet secondary dock로 유지
 - 상태:
  - 상세 기획 완료
  - 구현 전
 ### 완료 3. Refocus System 기본 구조
 - 문서: `10_refocus_system_spec.md`
--- a/docs/19_app_atmosphere_entry_spec.md
+++ b/docs/19_app_atmosphere_entry_spec.md
@@ -0,0 +1,447 @@
 # 19. `/app` Atmosphere Entry Spec
 Last Updated: 2026-03-16
 이 문서는 `/app`을 **goal + duration + atmosphere` 중심의 premium focus entry surface**로 재설계하기 위한 기준 문서다.
 관련 문서:
 - `../../product_principles.md`
 - `../../current_context.md`
 - `09_app_entry_detailed_spec.md`
 - `14_weekly_review_reframe_spec.md`
 - `15_app_stats_entry_flow_spec.md`
 - `18_paused_session_reentry_spec.md`
 ---
 ## 1. 왜 다시 바꾸는가
 현재 `/app`은 single-goal commitment gate로 정리되어 있지만,  
 사용자가 실제로 “어떤 환경으로 들어갈지”를 고르는 감각 품질이 entry에서 충분히 살아 있지 않다.
 문제:
 - 시작은 빨라졌지만, entry가 아직 너무 추상적이다
 - `scene / sound / timer`가 제품 핵심 가치인데 `/app`에서는 거의 느껴지지 않는다
 - 첫 진입에서 VibeRoom만의 premium 감각이 충분히 전달되지 않는다
 따라서 `/app`은 다시 planning home으로 돌아가면 안 되지만,
 **goal + duration + atmosphere`를 한 화면에서 직관적으로 결정하는 premium entry stage**로 진화할 필요가 있다.
 핵심은 이것이다.
 > `/app`은 여전히 한 가지 목표만 정하는 화면이어야 하지만,  
 > 그 목표를 어떤 분위기에서 얼마나 붙잡을지까지 함께 결정하는 stage가 되어야 한다.
 ---
 ## 2. 한 줄 정의
 `/app`은 사용자가
 1. 이번 세션의 목표를 한 줄로 적고
 2. 이 목표에 얼마나 걸릴지 직접 입력하고
 3. 배경 + 사운드가 묶인 하나의 `Atmosphere`를 고른 뒤
 4. 바로 `/space`로 들어가는
 **premium focus staging screen**이다.
 ---
 ## 3. 핵심 제품 원칙
 ### 1. Single Goal First는 유지한다
 - goal은 1개만 입력한다
 - entry에서 multi-goal / list / planner affordance 금지
 ### 2. MicroStep은 `/app`에서 제거한다
 - 최초 entry에서는 microStep을 묻지 않는다
 - microStep은 `/space` 안의 recovery / refocus에서 다시 잡는다
 - 이유:
  - 첫 entry는 시작 마찰을 최소화해야 한다
  - goal, duration, atmosphere만으로도 결정량이 충분하다
 ### 3. Duration은 사용자가 직접 입력한다
 - 기존 preset `25/5`, `50/10` 중심 entry를 버린다
 - 사용자는 “이 목표를 끝내는 데 얼마나 걸릴지”를 분 단위로 적는다
 - 예: `70분`
 ### 4. 배경 + 사운드는 하나의 오브젝트로 다룬다
 - scene과 sound를 따로 고르게 하지 않는다
 - entry에서 사용자가 고르는 것은 `Atmosphere` 하나다
 - 즉 `/app`의 선택 단위는 `scene + sound pair`
 ### 5. Review는 entry를 방해하지 않는 secondary ritual이어야 한다
 - `/app`의 주인공은 시작이다
 - weekly review, achieved goals, “어떤 조합에서 잘 됐는지”는 보이되 start보다 앞서면 안 된다
 ---
 ## 4. 용어 정의
 ### 추천 명칭: `Atmosphere`
 배경 + 사운드가 결합된 카드의 공식 명칭은 `Atmosphere`로 고정한다.
 이유:
 - scene, sound, timer보다 더 제품적인 단위로 읽힌다
 - “배경 카드”보다 premium하고 감성적이다
 - 나중에 Pro 가치(`saved atmospheres`, `best atmosphere for mornings`)와도 자연스럽게 연결된다
 ### UI에서의 노출 방식
 - 섹션 제목: `어떤 분위기에서 들어갈까요?`
 - 카드 타입 명칭: `Atmosphere`
 - 예시 카드명:
  - Rain Window
  - Quiet Library
  - Forest Draft
  - Deep Night Desk
 ### 피해야 할 이름
 - `배경 카드`
 - `사운드 카드`
 - `조합 카드`
 - `프리셋`
 이런 이름은 값싸 보이거나 툴처럼 읽힌다.
 ---
 ## 5. 정보 구조
 `/app`은 아래 3층으로 구성한다.
 ### Layer 1. Entry Header
 - VibeRoom wordmark
 - quiet weekly review entry
 - plan pill / account
 ### Layer 2. Primary Start Stage
 - goal input
 - duration input
 - start CTA
 ### Layer 3. Atmosphere Grid
 - 12개의 curated atmosphere card
 - row당 4개
 - 첫 구현은 더미 데이터
 핵심은
 **review / archive / history가 main stage를 먹지 않고, atmosphere grid도 secondary decoration이 아니라 실제 선택 surface로 작동해야 한다**는 점이다.
 ---
 ## 6. 화면 구성
 ### A. Goal Input
 - 가장 위, 가장 크게
 - 한 줄 입력
 - placeholder 예시:
  - `예: 여행 계획 짜기`
  - `예: 제안서 첫 문단 정리`
 규칙:
 - 필수
 - 한 줄
 - Enter로 start 가능
 ### B. Duration Input
 - goal 바로 아래 또는 옆
 - 분 단위 숫자 입력
 - label:
  - `얼마나 붙잡을까요?`
  - `예상 시간(분)`
 규칙:
 - 필수
 - 숫자만
 - 권장 범위:
  - 최소 10분
  - 최대 180분
 - helper:
  - `이 목표를 끝내는 데 걸릴 것 같은 시간을 적어요.`
 ### C. Atmosphere Grid
 - 12개 dummy card
 - desktop: 4열 x 3행
 - tablet: 3열
 - mobile: 2열
 각 카드 구성:
 - 배경 썸네일
 - 카드명
 - sound label
 - 1줄 description
 예시:
 - `Rain Window` / `Soft Rain`
 - `Quiet Library` / `Air + Page Rustle`
 - `Forest Draft` / `Forest Birds`
 - `Deep Night Desk` / `Low White`
 ### D. Start CTA
 - 문구 예시:
  - `이 분위기로 들어가기`
  - `지금 시작`
 추천:
 - 기본 CTA는 `이 분위기로 들어가기`
 - 이유:
  - goal + duration + atmosphere가 모두 한 번에 묶여 entry action으로 읽힌다
 ### E. Weekly Review Entry
 이건 main stage 바깥의 quiet secondary placement로 둔다.
 권장 위치:
 - desktop: header 아래 우상단 quiet insight panel
 - mobile: hero 하단의 얇은 secondary card
 보여줄 것:
 - 이번 주 가장 잘 맞았던 atmosphere
 - 시작 성공률 또는 복귀율 1줄
 - CTA: `이번 주 review`
 보이지 말아야 할 것:
 - achieved goals 리스트 전체
 - 작은 차트 여러 개
 - dashboard처럼 보이는 summary wall
 ---
 ## 7. Weekly Review / Achieved Goals를 어디에 둘 것인가
 결론:
 > `/app`에는 full review를 두지 않고,  
 > `quiet review dock`만 둔다.  
 > 자세한 achieved goals와 “어떤 조합에서 잘 됐는지”는 `/stats`에서 본다.
 ### 왜 `/app`에 다 보여주면 안 되는가
 - 메인 entry의 집중력이 깨진다
 - goal 입력과 review 해석이 같은 레벨로 보인다
 - planner/dashboard처럼 읽힌다
 ### 추천 구조
 #### `/app`
 - 작은 weekly review dock
 - 보여주는 정보는 1~2줄만
 - 예:
  - `이번 주엔 Rain Window에서 가장 오래 이어졌어요.`
  - `여행 계획 같은 넓은 목표는 70분보다 45분에서 더 잘 닫혔어요.`
 #### `/stats`
 - achieved goals history
 - best-performing atmospheres
 - duration fit
 - recovery quality
 즉:
 - `/app`은 “review를 여는 문”
 - `/stats`는 “review desk”
 ---
 ## 8. 상태별 유저 플로우
 ### Flow A. First Entry / No Session
 1. 사용자가 `/app` 진입
 2. goal 입력
 3. duration 입력
 4. atmosphere 1개 선택
 5. CTA 클릭
 6. `/space` 진입
 핵심:
 - microStep 없음
 - list 없음
 - wizard 없음
 ### Flow B. Running Session Exists
 1. 사용자가 `/app` 진입
 2. 바로 `/space` redirect
 이유:
 - 이미 실행 중인 세션은 다시 decision gate에 세우지 않는다
 ### Flow C. Paused Session Exists
 1. 사용자가 `/app` 진입
 2. paused resume gate 노출
 3. 선택:
  - `이어서 몰입하기`
  - `한 조각 다시 잡기`
  - `새 목표로 전환`
 중요:
 - 이 상태에서는 atmosphere grid를 메인 UI로 먼저 보여주지 않는다
 - resume가 primary다
 ### Flow D. Review Entry
 1. 사용자가 `/app`의 quiet review dock 클릭
 2. `/stats`
 3. carry-forward CTA
 4. 다시 `/app`
 ---
 ## 9. UI 방향
 ### 톤
 - premium
 - calm
 - stage-like
 - card-heavy dashboard 금지
 ### 중요한 시각 원칙
 - 상단 input stage는 “form”보다 “entry surface”처럼 보여야 한다
 - atmosphere grid는 catalog처럼 보이되, ecommerce처럼 보이면 안 된다
 - card는 selection object이지 콘텐츠 카드가 아니다
 - hover, selected, focus state가 매우 명확해야 한다
 ### Selected Card
 - 다른 카드보다 1단 더 선명
 - subtle border glow
 - sound label이 더 읽히게
 - 선택되면 CTA 문구가 `이 분위기로 들어가기`와 연결돼야 함
 ### Unselected Card
 - 너무 장식적이면 안 된다
 - 배경 썸네일이 주인공
 - 텍스트는 간결
 ---
 ## 10. 비즈니스 모델 관점
 이 redesign은 BM에도 직접 연결된다.
 ### Free
 - curated atmosphere 12개 제공
 - goal + custom duration + basic review dock
 - best atmosphere insight는 1줄만
 ### Pro
 - personalized atmosphere recommendations
 - saved favorite atmospheres
 - goal type / time-of-day 기반 추천
 - “이 목표 유형에서 잘 맞았던 조합” 인사이트
 - duration suggestion
 - deeper review
 즉 Pro는 “카드를 더 많이 준다”가 아니라
 **더 잘 맞는 atmosphere를 더 빨리 고르게 해준다**가 되어야 한다.
 ---
 ## 11. 서버 / 데이터 영향
 이번 redesign은 backend contract까지 건드린다.
 ### 필요한 변화
 1. `startSession`이 custom duration minutes를 받도록 확장
 2. session에 `focusDurationMinutes` 저장
 3. break duration 계산 정책 정의
 4. atmosphere 선택 단위를 위한 `sceneId + soundPresetId` 조합 저장
 ### break duration 정책 제안
 - 10~30분: 5분
 - 31~60분: 10분
 - 61~120분: 15분
 - 121분 이상: 20분
 이건 사용자가 break를 직접 고르지 않아도 자연스럽게 이어지게 하기 위한 기본 정책이다.
 ---
 ## 12. 구현 순서
 ### Slice 1. Atmosphere Model / Dummy Data
 - atmosphere card dummy 12개 정의
 - 카드명 / scene / sound / thumbnail 연결
 ### Slice 2. `/app` Entry Shell Redesign
 - goal input
 - duration input
 - 4x3 atmosphere grid
 - selected card state
 - start CTA
 ### Slice 3. Paused Gate Coexistence
 - paused session일 때는 새로운 entry shell 대신 resume gate를 우선 유지
 - no-session일 때만 새 shell 노출
 ### Slice 4. Custom Duration Contract
 - web -> server `custom minutes`
 - break duration policy
 - `/space` timer HUD와 연동
 ### Slice 5. Weekly Review Dock
 - `/app`의 quiet secondary review entry를 새 shell에 맞게 재배치
 - `/stats` entry/handoff 유지
 ### Slice 6. Pro Personalization
 - recommended atmosphere
 - best-fit insight
 - duration suggestion
 ---
 ## 13. 검증 기준
 - 사용자가 `/app`에서 10초 안에 goal + duration + atmosphere를 정하고 들어갈 수 있다
 - atmosphere grid가 decorator가 아니라 실제 선택 surface로 읽힌다
 - weekly review가 start보다 앞서지 않는다
 - `/app`이 planner/dashboard처럼 보이지 않는다
 - paused session에서는 resume gate가 새 entry shell보다 우선한다
 - `70분` 같은 custom duration이 실제 세션 길이로 반영된다
--- a/docs/session_brief.md
+++ b/docs/session_brief.md
@@ -14,13 +14,19 @@ Last Updated: 2026-03-15
 ## 현재 우선순위
-1. `Core Loop Alignment` browser audit
+1. `/app` Atmosphere Entry Shell
-2. `Weekly Review` ritual fit highlight
+2. `Custom Duration Contract`
-3. `Premium Ambience`
+3. `Weekly Review Dock Reposition`
-4. `Pause / Break / Return` browser polish
+4. `Core Loop Alignment` browser audit
 ## 최근 세션 상태
 - `/app` 전면 재설계 방향을 새 spec으로 고정했다.
  - no-session `/app`은 `goal + duration + atmosphere` 중심의 premium entry stage로 바뀐다.
  - microStep은 `/app`에서 제거하고, duration은 분 단위 직접 입력으로 전환한다.
  - scene + sound 조합 카드는 `Atmosphere`로 부르며, 첫 구현은 12개 dummy grid를 사용한다.
  - weekly review와 achieved-goal insight는 main stage가 아니라 quiet secondary dock로 유지한다.
 - `Paused Session Takeover Flow`를 구현했다.
  - `/app` paused gate에 `새 목표로 전환` 액션이 추가됐다.
  - takeover confirm sheet에서만 기존 paused session을 정리하고 새로 시작할 수 있다.
--- a/docs/work.md
+++ b/docs/work.md
@@ -18,111 +18,89 @@
 ## 작업 1
- 제목: `Paused Session Re-entry` Session Routing Contract
+- 제목: `/app` Atmosphere Entry Shell
 - 목적:
-  - `18_paused_session_reentry_spec.md` 기준으로 running / paused / break 상태의 route policy를 코드에 고정한다.
+  - `19_app_atmosphere_entry_spec.md` 기준으로 `/app` no-session 상태를 `goal + duration + atmosphere` 중심의 premium entry screen으로 재설계한다.
-  - `/app`과 `/space`가 같은 session state를 두고 서로 다른 해석을 하지 않게 만든다.
+  - entry에서 scene/sound의 감각 품질을 다시 살리되 planner/dashboard 톤으로 흐르지 않게 만든다.
 - 변경 범위:
-  - current session route gating
+  - no-session `/app` shell
-  - `/app` 진입 정책
+  - atmosphere dummy 12개
-  - `/space` direct re-entry 정책
+  - goal input
  - duration input
  - 4x3 atmosphere grid
  - primary CTA
 - 제외 범위:
-  - visual redesign 직접 착수 금지
+  - paused resume gate 재설계 금지
-  - takeover flow UI 구현 금지
+  - weekly review 상세 IA 변경 금지
-  - weekly review 집계 확장 금지
+  - server contract 변경 금지
 - 완료 조건:
-  - `running focus -> /space`
+  - current session이 없을 때만 새 entry shell이 보인다
-  - `running break -> /space`
+  - goal + duration + selected atmosphere가 start surface 안에서 명확히 읽힌다
-  - `paused focus -> /app`
+  - 12개 dummy atmosphere가 4열 그리드로 배치된다
  - `no session -> /app`
  규칙이 코드와 문서에서 일치한다
 - 진행 상태:
-  - 완료
+  - 대기
 - 검증:
-  - source-of-truth 문서 대조
+  - `/app` no-session browser QA
 - 커밋 힌트:
-  - feat(flow): session routing contract 정리
+  - feat(app): atmosphere entry shell 1차 구현
 ## 작업 2
- 제목: `/app` Paused Resume Gate
+- 제목: `Custom Duration Contract`
 - 목적:
-  - paused session 사용자가 `/app`에서 현재 상태를 이해하고, 한 번의 결정으로 다시 들어가게 만든다.
+  - `/app`의 분 단위 duration 입력을 실제 세션 길이로 반영한다.
 - 변경 범위:
-  - paused resume card
+  - web start payload
-  - `이어서 몰입하기`
+  - server startSession contract
-  - `한 조각 다시 잡기`
+  - break duration 정책
-  - quiet `주간 review 보기`
+  - `/space` timer 연동
 - 제외 범위:
-  - new start takeover flow 금지
+  - weekly review recommendation 확장 금지
-  - bulk visual redesign 금지
+  - atmosphere personalization 금지
 - 완료 조건:
-  - paused 사용자가 2초 안에 다음 행동을 이해할 수 있다
+  - `70분` 같은 값이 실제 focus duration으로 반영된다
-  - review는 보이지만 resume보다 앞서지 않는다
+  - break duration이 정책 기준으로 계산된다
 - 진행 상태:
-  - 완료
+  - 대기
 - 검증:
-  - `/app` paused state browser QA
+  - start -> `/space` -> timer duration 확인
 - 커밋 힌트:
-  - feat(app): paused resume gate 추가
+  - feat(flow): custom duration contract 연결
 ## 작업 3
- 제목: `/space` Auto-Resume Handoff
+- 제목: `Weekly Review Dock Reposition`
 - 목적:
-  - `/app`에서 explicit continue를 눌렀다면 `/space`에서 다시 start를 누르지 않게 만든다.
+  - 새 `/app` entry shell 안에서 weekly review를 start를 방해하지 않는 quiet secondary dock로 재배치한다.
 - 변경 범위:
-  - `/app -> /space` handoff
+  - `/app` review teaser placement
-  - resume trigger
+  - desktop/mobile responsive placement
-  - re-entry transition
+  - review return hint placement
 - 제외 범위:
-  - takeover flow 금지
+  - `/stats` IA 변경 금지
-  - break semantics 재정의 금지
+  - paused resume gate 재설계 금지
 - 완료 조건:
-  - `/app -> /space -> start` 이중 클릭이 사라진다
+  - review entry는 항상 발견 가능하지만 start보다 앞서지 않는다
-  - explicit continue 이후에는 `/space`에서 바로 실행 상태로 들어간다
+  - no-session shell과 paused gate에서 위계가 일관된다
 - 진행 상태:
-  - 완료
+  - 대기
 - 검증:
-  - paused -> continue 브라우저 QA
+  - `/app` no-session / paused browser QA
 - 커밋 힌트:
-  - feat(space): paused auto-resume handoff 연결
+  - fix(app): review dock 위치 재정렬
 ## 작업 4
 - 제목: `Paused Session Takeover Flow`
 - 목적:
  - paused session 위에서 새 목표를 시작하고 싶을 때 상태 오염 없이 명시적으로 전환하게 만든다.
 - 변경 범위:
  - takeover confirm sheet
  - close-and-start-new 경로
  - silent abandon 방지
 - 제외 범위:
  - weekly review 확장 금지
  - visual redesign 직접 착수 금지
 - 완료 조건:
  - paused 상태에서 direct new start는 불가능하다
  - 사용자는 기존 paused session을 어떻게 처리할지 먼저 고른다
 - 진행 상태:
  - 완료
 - 검증:
  - paused -> new start 브라우저 QA
 - 커밋 힌트:
  - feat(app): paused session takeover flow 추가
 ## 작업 5
 - 제목: `Core Loop Alignment Audit` browser slice
 - 목적:
-  - paused re-entry까지 포함한 핵심 흐름을 브라우저에서 실제로 검증한다.
+  - 새 `/app` entry shell까지 포함한 핵심 흐름을 브라우저에서 실제로 검증한다.
 - 변경 범위:
-  - `/app` first entry
+  - `/app` no-session
  - `/app` paused resume
  - `/app -> /stats -> /app`
  - `/space` pause / return / next beat / complete
  - `/space` complete -> setup -> weekly review teaser
 - 제외 범위:
  - bulk visual redesign 금지
  - new feature 추가 금지
 - 완료 조건:
  - browser QA findings가 ledger에 반영된다