PRD 신규 작성 (AI-Ready PRD) - Beupgo 유튜브용

1.요약 (Executive Summary)

1.1 앱이름

• KindVerb(카인드법)

1.2 한 줄 가치 제안 (One-liner)

• “갈등의 언어를 공감의 언어로 바꾸는 NVC 기반 화해 편지 앱" (사용자가 겪는 관계 갈등을 단계별 질문으로 구조화하고, NVC 모델과 AI 제안으로 부드러운 화해 메시지를 만들어 가장 편한 방식 (텍스트)으로 전달할 수 있게 돕습니다.) 

1.3 핵심 가치 키워드 (Core Value)

• NVC 템플릿, 단계별성찰(5Q), 오프라인우선, 프라이버시 제일주의, 즉시성(로그인불필요), 간결한공유(텍스트) 

1.4 대상 사용자 (Target Users) 

• 말다툼 후 먼저 화해하고 싶은 사람
• 친구 또는 동료, 배우자 또는 연인, 부모 또는 자녀, 형제 또는 자매, 시댁 또는 처가
• 상담은 부담스럽지만 검증된 대화기술(NVC)을 쉽게 적용하고 싶은 사람
• 개인정보 노출 없이 오프라인으로 쓰고 싶은 사람

1.5 타깃 플랫폼 & 기술원칙 (Target Platform & Guardrails) 

• iOS 전용
• SwiftUI + MVVM, Swift Concurrency(async/await), 현대적 Error (throw/try/catch) 
• Completion Handler 금지, NSError 금지
• 버튼 형식 강제 : Button { /* action */ } label: { /* view */} 만 사용
• 현지화 강제 : 모든 사용자 노출 텍스트는 Localizable.xcstrings 의 Key로 참조 (기본 언어 영어, 한국어, 일본어, 중국어 총 4개국어 지원)
• 오프라인 우선 : 사용자 데이터(성찰 답변, 일기) 온디바이스 영구 저장(SwiftData) 
• AI로 초안 생성시에는 gemini-2.5-flash-lite 모델 사용
• AI 연동은 Firebase AI Logic 사용
• Firebase AppCheck 를 사용하여 승인되지 않은 클라이언트로부터 API를 보호
• 로그는 import os.log 를 사용하여 Apple의 통합 로깅 시스템을 사용, print 사용 금지

AI를 위한 코딩 수칙 요약
SwiftUI·MVVM, async/await만, NSError 금지, 모든 문자열은 Localizable.xcstrings 키로, 버튼은 지정 패턴만, 로그는 import os.log 를 사용.

1.6 MVP 스코프 (What’s In for v1.0) 

• Free: 친구 또는 동료
• Pro : 배우자 또는 연인, 부모 또는 자녀, 형제 또는 자매, 시댁 또는 처가 (Pro는 잠금 + Paywall 유도)

• 상황, 감정, 상처, 나의성찰, 진짜원했던것(최대 500자, 감정 태그 ≥8)
• 온디바이스 임시→최종 저장(SwiftData)

• 1단계 답변 → NVC 기반 초안 생성(Gemini AI) → 부드럽게/간결하게/다시 제안 등 어시스턴트 버튼

• 텍스트복사, 이미저장, 링크공유(Firestore 익명 저장, TTL 7일) 

• 1회성 IAP 12,900원 평생 이용권(Pro) 
• 결제 성공시 즉시 잠금 해제 및 UI 업데이트 (복원 포함) 

Out (MVP 범위 외)
회원 시스템/실시간 협업/웹·안드로이드 클라이언트/AI 장문 코칭(지속 대화)/크로스 디바이스 동기화.

1.7 차별점 (Why KindVerb)

• 심리 기술의 즉시 사용성 : NVC를 질문-요약-초안으로 즉시 실행
• 프라이버시: 로그인 없이 전 기능 사용, 온디바이스 저장 기본
• 낮은 진입장벽 : Free 카테고리로 가치 체험 → Pro 전환이 자연스럽게 연결
• 전달 다양성: 텍스트/이미지/링크(TTL7일)까지, 상대 선호에 맞춘 선택

1.8 비즈니스 모델 요약 (Monetization Snapshot)

• Free : 친구 또는 동료 카테고리 사용가능, 핵심 여정 전부 사용 가능
• Pro(12,900원, 1회성 IAP, 평생): 배우자 또는 연인, 부모 또는 자녀, 형제 또는 자매, 시댁 또는 처가 카테고리 잠금해제 + 전문가 라이브러리 + 마음노트고급
• 광고없음(집중, 신뢰유지)
• 페이월 트리거 : Pro 카테고리 선택시 또는 AI 고급 리라이팅 요청시
• Gemini API 요청 제한 : Free 사용자(0시 부터 24시 까지 하루 최대 1회), Pro 사용자(0시 부터 24시 까지 하루 최대 10회)

1.9 성공지표 (Success Metrics) 

1.10 일정(알파 → 출시) & 마일스톤 (4주 MVP)

• 주1 : 프로젝트 스캐폴드, 화면골격/네비게이션, 공통 컴포넌트, 현지화구조
• 주2: GuideJournal(5문항) UI/로직, SwiftData 저장, 상태관리
• 주3: AI 초안 생성/리라이팅 워크숍, 텍스트/이미지/링크공유(링크 TTL 7일)
• 주4: IAP + Paywall, 아이콘/애니메이션 폴리싱, 전체 시나리오 E2E 테스트 → App Store 제출

1.11 리스크 & 가드레일(요약)

• AI 품질 변동: 초안 재요청(리트라이), 프롬프트 체계화, 로컬 템플릿 백업
• IAP 심사: 명확한 가치 제시, 복원제공, 가이드라인 준수(영수증 검증)
• 개인정보/보안: 기본 오프라인, 링크는 익명 + TTL 7일 자동 삭제
• 성능: 메모리/스크롤 FPS 모니터링, 이미지 렌더 최적화

2.문제정의&맥락 (Problem Statement & Context)

2.1 문제(Problem)

• 사용자상황 :
• 일상적인 대화 속에서 갈등•오해•상처가 발생했을 때, 대부분의 사람들은 즉각적으로 사과하거나 감정을 정리해서 표현하기가 어렵습니다.
• 구체적불편 : 
• 감정이 격해져서 어떤 말을 해야 할지 떠오르지 않음
• 사과를 하고 싶지만 표현 방식을 잘못해 오히려 갈등이 커짐
• “나도 상처받았다"라는 마음을 부드럽게 전달할 방법을 찾기 힘듦
• 심리 상담•코칭 앱은 부담스럽거나 지속적인 비용이 듦
• 핵심 Pain Point 요약 : 
• “갈등 이후, 따뜻하고 관계 회복적인 언어를 찾는 것이 어렵다.”

2.2 기존 대안 & 한계 (Existing Alternatives & Limitations) 

• 메신저 바로 쓰기 : 충동적으로 보낸 메시지가 오해를 키움 → 후회 + 관계악화
• 검색 & 블로그 글 참고 : “사과 메시지 예시" 같은 글은 상황 맞춤형이 아님 → 진정성 부족
• 자필 편지/메모 : 따뜻하긴 하지만 형식•구조가 잡히지 않아 오해 여지 있음
• 심리 상담/커플 치료 : 효과적이지만 즉각적이지 않고, 비용•시간 장벽 큼
• 경쟁 앱/서비스 : 기존 저널링 앱은 **“나의 감정 기록”**에 집중, 상대방에게 건네는 언어까지 연결하지 못함

2.3 해결 가설 (Solution Hypothesis) 

1. 구조화된 5단계 자기 성찰 질문(5Q Flow)
• 사용자가 감정을 정리하고 진짜 전하고 싶은 마음을 발견
2. AI 기반 NVC 템플릿 메시지 생성
• “관찰 → 감정 → 필요 → 부탁" 구조로 안전한 문장 제공
3. 사용자 주도 리라이팅 옵션
• “부드럽게", “간결하게" 등 맥락에 맞게 조정
4. 다양한 전달 방식 지원
• 텍스트 복사, 이미지 저장, 링크 공유(7일 TTL)
5. 프라이버시 중심 설계
• 로그인 없이, 모든 기록은 온디바이스 저장

2.4 제품 경계 (Product Boundaries) 

• 하지 않을 것 (이번 범위 아님 / Later) 
• 실시간 채팅/상담 기능 : 전문가와 연결하거나, 사용자 간 익명 대화 지원 ❌
• 멀티 플랫폼(Web/Android): 초게이는 iOS 전용
• AI 장기 코칭/대화 세션 : MVP는 “편지 1회 완성"에 집중
• 지속 동기화·클라우드 백업 : 온디바이스 우선 전략 유지
• 이유 : MVP의 목표는 **단일 여정(Conflict → Reflection → Message → Delivery)**이 완성도 있게 동작하는 것

• 심리학적 배경: NVC(Nonviolent Communication, 비폭력 대화)는 연구적으로 긴장 완화와 갈등 회복에 효과가 검증됨.
  
• 디지털 환경의 맥락:
  
• 사람들은 실시간 대화보다 비동기적 텍스트 메시지에서 더 솔직해질 수 있음
  
• 프라이버시 걱정 없는 즉시성 앱은 기존 상담 대비 장벽을 크게 낮춤
  
• 비즈니스 맥락: 
• “셀프케어/마음 챙김” 앱 카테고리 성장 중
  
• 구독형보다는 저항이 적은 1회성 IAP가 관계 회복 툴에 더 적합
  

3.목표, 비목표, 성공지표 (Goals, Non-Goals, Success Metrics) 

3.1 목표(Goals, 우리가 반드시 달성해야 할 것)

• 사용자가 3탭 이내로 감정을 기록할 수 있어야 한다. 
• 오프라인 상황에서도 입력된 데이터는 로컬 큐에 저장되고, 온라인이 되면 자동 동기화한다. 

• 기록된 감정을 기반으로, 앱은 비폭력 대화(NVC) 구조에 맞는 문장 템플릿을 제안해야 한다. 
• 사용자는 추천된 문장을 복사・공유할 수 있어야 한다. 

• 앱은 **Crash-Free 세션 비율 ≥ 99.8%**를 유지해야 한다.
  
• 데이터 손실 없는 동기화와 **안정적인 첫 실행 경험(TTI ≤ 2.0s)**을 보장한다.
  

3.2 비목표 (Non-Goals, 이번 범위에 포함하지 않는 것)

• "Android / Web 버전 지원" → 이번 MVP에서는 iOS만 지원한다.
  
• "심층 AI 코칭 기능" (예: 상담형 대화, AI 기반 대화 분석) → 차후 유료 구독 모델에서 고려.
  
• "소셜 네트워크 공유/피드" → MVP 범위에는 포함하지 않는다. 단, 문장 복사 & 기본 공유 시트는 허용.
  
• "사용자 맞춤형 알림/리마인더" → MVP 이후 버전에 포함.
  

3.3 성공지표 (Success Metrics, 정량적으로 측정 가능한 목표)

4.페르소나 & JTBD (Personas & Jobs To Be Done)

4.1 주요 페르소나 (Key Personas)

• 상황/목표: 
• 직장에서 상사와 갈등이 생길 때, 감정을 바로 기록하고 싶음. 
• 퇴근 후 연인과의 대화에서 불필요한 싸움을 줄이고 싶음.
• 고통지점(Pain Points): 
• 순간적으로 화가 나면 감정을 정리하지 못하고, 말로 표현하다가 관계가 악화됨.
• 기존 메모 앱은 감정 분류/표현 지원이 없어 활용하기 어려움.
  
• 성공의 모습 (Success State):
  
• **“감정을 빠르게 기록하고, 앱이 제안하는 부드러운 문장을 사용”**하여 대화 갈등을 줄임.
  

• 상황/목표: 
• 가족 대화에서 불필요한 언성이 오가는 것을 줄이고 싶음.
  
• 아이에게 화내지 않고 차분하게 의사 표현을 하고 싶음.
  
• 고통지점 (Pain Points): 
• 순간적으로 감정을 표현하다가 아이와 배우자에게 상처 주는 말을 자주 함.
  
• 기존 일기/메모 앱은 단순 기록에 그쳐 실질적 도움을 주지 못함.
  
• 성공의 모습 (Success State): 
• **“앱이 제공하는 NVC 기반 문장 템플릿”**으로 아이와 배우자에게 상처 없는 대화를 이어감.
  

• 상황/목표: 
• 기숙사에서 룸메이트와 생활하면서 스트레스가 많음.
  
• 연인과 장거리 연애 중이라, 감정 조절이 어렵고 표현 방법을 찾고 있음.
  
• 고통지점 (Pain Points): 
• 친구/연인에게 감정을 전달하다가 의도치 않게 오해를 삼.
  
• SNS는 과하게 공개적이라 솔직한 감정 기록이 어려움.
  
• 성공의 모습 (Success State):
  
• **“앱에 비공개로 감정을 정리하고, 차분히 정제된 말”**을 건네 관계를 안정적으로 유지.
  

4.2 JTBD (Jobs To be Done) 

1. When I feel frustrated during a conversation with my partner,
   I want to record my emotions quickly in the app,
   so I can avoid saying things that might hurt them.
   
2. When I argue with my kids after work,
   I want to see a suggested kind sentence template,
   so I can calm the situation without raising my voice.
   
3. When I experience stress in daily life (school, work, or relationships),
   I want to log my feelings privately and safely,
   so I can reflect later and improve how I express myself to others.
   

5.주요 사용 사례 & 사용자 스토리 (Top Use Cases & User Stories) 

5.1 핵심 사용 사례 (Top Use Case)

• UC-1: 감정 기록 (Emotion Logging)
• Given 사용자가 직장에서 상사에게 부정적인 피드백을 받고 기분이 상함
  
• When 앱을 열어 감정을 선택하고 간단한 메모를 남김
  
• Then 앱은 해당 감정을 저장하고, 나중에 돌아볼 수 있도록 시각화된 기록을 제공
  
• UC-2: 친절한 문장 제안 (Kind Sentence Suggestion)
  
• Given 사용자가 연인과 다툼 중 감정을 바로 표현하고 싶음
  
• When 앱에서 “감정 기록”을 완료했을 때
  
• Then 앱은 NVC(비폭력대화) 기반의 친절한 문장 템플릿을 추천하여, 사용자가 그대로 활용하거나 수정 가능
  
• UC-3: 오프라인 기록 & 동기화 (Offline Logging & Sync)
  
• Given 사용자가 지하철이나 비행기 모드로 오프라인 상태임
  
• When 감정을 기록하면
  
• Then 앱은 이를 로컬 큐에 저장하고, 온라인 상태가 되면 자동으로 서버에 동기화
  
• UC-4: 감정 리플렉션 & 성장 (Emotion Reflection & Growth)
  
• Given 사용자가 지난 한 달간의 감정 기록을 조회함
  
• When 앱이 주요 감정 패턴과 긍정적 대화 비율을 분석하여 보여줄 때
  
• Then 사용자는 자신의 성장을 인식하고, 더 나은 대화 방식을 학습

5.2 사용자 스토리 (User Stories)

5.3 감동 포인트 요약 (PR/인터뷰용)

• 즉각적인 감정 기록 → 관계 악화를 막는 예방 장치
  
• AI 추천 친절 문장 → 가족·연인·동료와의 대화 품질 향상
  
• 리플렉션 → 사용자가 자신의 성장과 변화를 확인
  
• 오프라인 동작 → 언제 어디서든 감정을 놓치지 않음
  

5.4 앱스토어 설명문 (App Store Description) 

• KindVerb

• 말 한마디가 관계를 바꿉니다. 감정을 기록하고, 친절한 대화를 시작하세요.

• 빠른 감정 기록
• 순간의 감정을 선택하고 간단히 메모하세요. 앱은 기록을 안전하게 보관하며 언제든 돌아볼 수 있습니다.
  
• AI 기반 친절한 문장 추천
• 다툼이 커지기 전에, 상황에 맞는 부드러운 표현을 제안합니다. 그대로 사용할 수도 있고, 나만의 말로 다듬을 수도 있습니다.
  
• 오프라인 기록 & 동기화
• 지하철, 비행기 모드에서도 감정을 놓치지 않고 기록합니다. 온라인 상태가 되면 자동 동기화됩니다.
  
• 성장 리플랙션
• 지난 기록들을 차트와 패턴으로 확인하고, 점점 더 나은 대화를 만들어가는 자신을 발견하세요.
  

• 관계를 지켜주는 즉각적인 감정 기록 + 친절한 문장 추천
  
• 오프라인에서도 놓치지 않는 안정성
  
• 나의 성장 과정을 시각화하는 리플렉션 기능
  

1. “단 3초, 감정을 기록하세요.”
   
2. “AI가 제안하는 친절한 문장으로 대화를 이어가세요.”
   
3. “지난 대화를 돌아보며 성장하세요.”
   
4. “오프라인에서도 감정을 놓치지 마세요.”
   

5.5 마케팅 에셋 (AppStore, SNS, Landing Page용 카피)

• “말 한마디가 관계를 바꿉니다. KindVerb와 함께 대화를 더 따뜻하게.”
  
• “화가 날 때, 그냥 말하기 전에 잠시 기록하세요. KindVerb가 도와드립니다.”
  
• “사랑하는 사람과 더 좋은 대화를 나누고 싶나요? KindVerb가 답입니다.”
  

• Hero Section (첫 화면) 
• 말 한마디가 관계를 바꿉니다.
• KindVerb - 감정을 기록하고, 더 친절한 대화를 시작하세요. 
• Features Section 
• 감정 기록 → 단 3초면 충분합니다.
  
• AI 추천 → 상황에 맞는 친절한 문장을 제안합니다.
  
• 오프라인 모드 → 어디서든 감정을 놓치지 않습니다.
  
• 리플렉션 → 나의 성장과 변화를 차트로 확인하세요.
  
• Call to Action 
• “오늘부터 더 따뜻한 대화를 시작하세요.”
  
• 👉 [앱스토어 다운로드 버튼]
  

• “KindVerb는 사람 사이의 오해와 상처를 줄이고, 따뜻한 대화를 가능하게 합니다.”
  
• “우리는 단순히 감정을 기록하는 것이 아니라, 관계를 지켜내는 기술을 만들고 있습니다.”
  
• “KindVerb의 미션은 더 많은 사람들이 ‘말 한마디로 사랑을 지킬 수 있도록 돕는 것’입니다.”
  

6.범위&우선순위 (Scope & Prioritization - Gherkin)

6.1 기능 목록 요약 (MoSCoW)

6.2 RICE 우선순위 (MVP 기준 가정치) 

• R(Reach) = MVP 3개월 예상 도달 사용자수
• I(Impact) = 전환/리텐션 기여(3=높음, 2=중, 1=낮음)
• C(Confidence) = 추정 신뢰도(0~1)
• E(Effort) = 주(엔지니어 1명 기준)
• RICE = (R × I × C) / E
  

6.3 기능별 스펙 (Gherkin + 수용 기준) 

• 비즈니스 규칙
• 카드 5종: friend, partner = Free / parent_child, siblings, in_laws = Pro
  
• 선택 시 다음 화면으로 conflictType 전달
  
• 텍스트/버튼 라벨은 모두 현지화 키 사용(예: conflict.title, conflict.button.start_free)
  
• Gherkin

Feature: Conflict type selection
  As a user I want to start with a relationship context to receive tailored guidance.

  Scenario: Show 5 conflict cards with Free/Pro badges
    Given app launched first time
    When the user reaches the conflict selection screen
    Then 5 cards are visible
      And "friend" and "partner" cards show a "Free" badge via key "conflict.badge.free"
      And "parent_child", "siblings", "in_laws" cards show a "Pro" badge via key "conflict.badge.pro"

  Scenario: Start Free journey
    Given the user is on the conflict selection screen
    When the user taps the "Start" button on "friend"
    Then navigate to Guided Journal with conflictType="friend"

  Scenario: Tap Pro card leads to paywall
    Given the user is on the conflict selection screen
    When the user taps the "Start Pro" button on "parent_child"
    Then show Paywall screen

  Scenario: Accessibility and localization keys are used
    Given voiceover is on
    Then card titles/CTA use localization keys only

• 수용기준
• 5개 카드/배지 정확 표시, Free→F-02 진입, Pro→F-05 진입
  
• 현지화 키 강제, 하드코딩 문자열 금지
  
• 포커스 이동/VoiceOver 레이블 정상
  
• 오류키(표시문구는 키로만)
• error.navigation.missing_conflict_type
  

• 문항
1. 상황기록(텍스트 ≤500자)
   
2. 감정선택(최소 8개 태그+직접입력, 복수 선택)
   
3. 상처받은 지점(텍스트)
   
4. 나의 반성(텍스트, 건너뛰기 허용)
   
5. 진짜 원했던 것(텍스트 + 예시 안내)
   
• Gherkin

Feature: Guided journal (5 steps)
  Scenario: Complete all steps and proceed
    Given the user selected conflictType="friend"
    When the user enters valid inputs for steps 1..5
    Then tap "journal.complete" button
      And navigate to JournalCompletion

  Scenario Outline: Validation and limits
    Given the user is on step <step>
    When the user enters input exceeding the limit or invalid
    Then show error with key <errorKey>
  Examples:
    | step | errorKey                         |
    | 1    | error.journal.too_long          |
    | 2    | error.journal.emotion_empty     |
    | 5    | error.journal.want_empty        |

  Scenario: Skip reflection (step 4)
    Given the user is on step 4
    When the user taps "journal.skip.reflection"
    Then proceed to step 5

  Scenario: Offline saving
    Given the device is offline
    When the user completes step 5
    Then data is saved locally (SwiftData)
      And queued for sync when online (event "sync.queue_enqueued")

• 수용 기준
• 입력 검증/건너뛰기/오프라인 저장 동작
  
• 키보드 가림 방지, 진행 표시(1/5)
  
• 완료 시 Journal 엔티티 온디바이스 영구 저장
  
• 오류 키
• error.journal.too_long, error.journal.emotion_empty, error.journal.want_empty, error.storage.failed
  

• 행동
• 화면 진입 시 NVC 프롬프트로 초안 자동 생성
  
• 어시스턴트 버튼 4종: 다시 제안/부드럽게/간결하게/더 진솔하게
  
• 평균 응답 ≤ 5초(타임아웃 시 재시도 UI)
  
• Gherkin

Feature: AI message composer
  Scenario: Draft is generated on entry
    Given the user completed Guided Journal
    When opening MessageComposer
    Then show loading indicator
      And populate editor with AI draft within 5 seconds or show "composer.retry" action

  Scenario: Assistant buttons transform text
    Given the editor has a draft
    When the user taps "composer.assist.soften"
    Then the text updates with a softer tone
      And event "ai.rewrite" is logged with variant="soften"

  Scenario: Failure and recovery
    Given the AI service is unreachable
    When draft generation fails
    Then show error key "error.ai.unavailable"
      And expose "composer.retry" action

• 수용 기준
• 초안 자동 생성, 4 버튼 각각 변환 로직 적용
  
• 로딩/실패/재시도 UX 분기
  
• 모든 라벨은 키 사용(예: composer.button.soften)
• 오류키
• error.ai.unavailable, error.ai.timeout, error.ai.transform_failed
  

• 행동
• 복사: 클립보드 성공 토스트
  
• 이미지: 편지지 배경 합성, 앨범 저장 권한 흐름 포함
  
• 링크: Firestore letters 쓰기(익명), TTL 7일, URL 생성
  
• Gherkin

Feature: Delivery options
  Scenario: Copy to clipboard
    Given a finalized letter in editor
    When the user taps "delivery.copy"
    Then letter text is in clipboard
      And toast with key "delivery.copied" is shown

  Scenario: Save as image
    Given photo permission is granted or requested
    When the user taps "delivery.image"
    Then save a high-resolution image to Photos
      And show "delivery.image_saved"

  Scenario: Share via link (online)
    Given the device is online
    When the user taps "delivery.link"
    Then create Firestore document with { content, createdAt }
      And return URL "https://kindverb.com/letter/<id>"
      And show iOS share sheet

  Scenario: Share via link (offline)
    Given the device is offline
    When the user taps "delivery.link"
    Then show error "error.network.offline"

• 수용 기준
• 세 옵션 모두 정상 동작, 링크는 7일 후 자동 만료 전제
  
• 권한 거부/실패 케이스 명확 처리
  
• 오류키
• error.delivery.copy_failed, error.delivery.image_failed, error.network.offline, error.link.create_failed
  

• 행동
• Paywall: 장점·가격·구매/복원 버튼
  
• 성공 시 즉시 Pro 해제(자물쇠 제거), 실패/취소 분기
• Gherkin

Feature: In-App Purchase (Pro Lifetime)
  Scenario: Purchase success unlocks Pro features
    Given the user is on Paywall
    When the user completes purchase successfully
    Then unlock all Pro categories immediately
      And replace Pro badges with unlocked state
      And log "iap.purchase_succeeded"

  Scenario: Restore purchases
    Given the user taps "iap.restore"
    When a valid receipt is found
    Then set Pro state to true
      And show "iap.restore_success"

  Scenario: Purchase failure
    When the purchase fails or is canceled
    Then show error key "error.iap.failed" or "error.iap.canceled"

• 수용 기준
• 구매/복원 정상, UI 즉시 반영
  
• 스토어 가이드라인 100% 준수
  
• 오류 키
• error.iap.failed, error.iap.canceled, error.iap.restore_failed
  

• Gherkin

Feature: Offline-first storage and retry
  Scenario: Save journal offline
    Given no connectivity
    When the user completes step 5
    Then journal is persisted locally (SwiftData)
      And a sync job is enqueued

  Scenario: Auto-retry on reconnect
    Given queued jobs exist
    When connectivity is restored
    Then jobs are sent
      And success clears the queue

• 수용 기준
• 로컬 저장 실패율 < 0.1%, 재시도 지수백오프
  
• 앱 재시작 후에도 큐 유지
  
• 오류키 
• error.storage.save_failed, error.sync.retry_exhausted

6.4 에지 케이스 (공통)

• 네트워크: 타임아웃/오프라인/느린 연결 → 로딩·재시도·취소 UI 제공
• 권한: 사진 접근 거부 시 가이드 키 permission.photos.denied_guide
• 중복 탭 방지: CTA 탭 시 일시 비활성화
  
• 긴 텍스트: 5,000자 초과 시 저장/공유 차단 및 안내
  
• 접근성: 다크모드/동적 폰트/VoiceOver 레이블 키 필수

6.5 텔레메트리 이벤트(요약)

6.6 AI-Ready 작성 가드레일

• 현지화 강제: 모든 사용자 노출 텍스트는 키만 사용(예: Text("journal.title")).
  
• 버튼 규칙: SwiftUI 버튼은 반드시 Button { /* action */ } label: { /* view */ } 형식.
  
• 동시성: 모든 비동기 로직은 async/await, NSError 금지(Swift Error + throw/try/catch).
  
• 아키텍처: MVVM( View ↔ ViewModel ↔ UseCase/Repository ↔ Service ) 경계 준수.
  
• 테스트 용이성: 각 시나리오는 Gherkin → UI Test / VM Unit Test로 1:1 매핑 가능.
  

7.앱플로우&정보구조 (App Flow & Information Architecture, IA) 

7.1 네비게이션 모델 (MVP)

• 루트 컨테이너: NavigationStack
• 탭바: 없음(단일 핵심 여정 집중)
• 모달(Presented): V03_PaywallView(시트), iOS 공유 시트(시스템), 포토 권한 알림(시스템)
• 전체 흐름: Launch → Conflict 선택 → 1단계 성찰 → 1단계 완료 → 2단계 편지 작업실 → 전달(복사/이미지/링크) → 완료

V01_LaunchScreen
   ↓ auto
V02_ConflictSelectionView
   ├─[Free 선택]→ V04_GuidedJournalView
   └─[Pro 선택] → V03_PaywallView (sheet)
                      ├─[구매 성공]→ V04_GuidedJournalView
                      └─[취소/닫기]→ V02
V04_GuidedJournalView (5-step)
   ↓ [정리 완료]
V05_JournalCompletionView
   ↓ [2단계로]
V06_MessageComposerView
   ├─[텍스트 복사]
   ├─[이미지 저장]→ (포토 권한 요청·성공 시 저장)
   └─[링크 공유]→ (온라인만 활성/성공 시 URL 발급)
   ↓
V07_CompletionView → V02 로 귀환

7.2 화면 인벤토리 (Screen Inventory)

주의: 모든 화면의 사용자 노출 텍스트는 직접 문자열 금지, 반드시 현지화 키 사용. 버튼은 Button { } label: { } 형식만.

7.3 상태 다이어그램 (요약) 

[앱 시작]
   ├─ Network: Online / Offline
   │   ├─ Online: 링크 공유 가능
   │   └─ Offline: 링크 공유 비활성 (토스트: error.network.offline)
   ├─ Entitlement: Free / Pro (paywall 성공·복원 시 Pro)
   └─ Photo Permission: NotDetermined → Denied/Authorized
       ├─ 이미지 저장 시 요청
       └─ Denied면 설정 이동 안내 키 노출

Q1 → Q2 → Q3 → Q4(건너뛰기 허용) → Q5 → [정리 완료] → 완료화면
   (각 스텝은 ViewModel 임시 상태에 저장, 완료 시 SwiftData 영구 저장)

Free → (구매 성공/복원) → Pro
   실패/취소 → Free 유지 (에러 키/가이드 표시)

7.4 권한 플로우 (Permissions)

MVP에서는 포토 권한만 필수. 알림은 후속 버전 고려.

7.5 딥링크 & 라우팅 (Deeplink / Routing) 

MVP에서는 링크 뷰어 웹 우선. 나중에 Universal Links를 앱에 매핑해 읽기 전용 뷰 추가 가능.

7.6 정보구조 (Information Architecture)

7.6.1 도메인 엔티티 & 소유권

• ConflictType (enum): 화면 선택값. 소유: ViewModel(세션 메모리)
• JournalDraft (struct): Q1~Q5 답변. 소유: SwiftData(영구), VM(임시)
• MessageDraft (struct): AI 초안/수정 결과. 소유: VM(세션), 필요 시 로컬 저장 옵션
• Entitlement (struct): free | pro. 소유: IAPService + VM 캐시
• Settings (struct): 로컬화/접근성/테마. 소유: AppStorage/환경

7.6.2 레이어별 책임 (MVVM 가드레일)

• View: 렌더링/유저 입력. 텍스트=현지화 키, 버튼 표준 형식.
• ViewModel: 상태 관리, 검증, 유스케이스 호출, 에러 매핑(키).
• UseCase/Repository: 도메인 로직, SwiftData CRUD, IAP/LLM/Firestore 호출 조정.
• Service/DAO: 외부 API·스토리지 실제 호출(LLM, StoreKit, Firestore).

7.7 화면별 데이터 계약(요약)

7.8 로딩/빈 상태/에러 패턴

모든 에러는 NSError 금지, 현대적 Error → ViewModel에서 로컬라이즈드 키로 매핑.

7.9 디자인 토큰 적용 지점 (요약)

• 컬러: color.primary, color.bg, color.text.muted
• 간격: spacing.s/m/l (4pt 그리드)
• 라운드: radius.l(카드), radius.m(버튼)
• 타이포: 본문 가독성 우선, Dynamic Type 100% 지원

7.10 접근성(A11y) & 키보드 UX

• 모든 상호작용 요소 44pt 이상
• VoiceOver 레이블: 키 기반(a11y.conflict.card.friend, …)
• 입력 폼: 키보드 회피, Return 키 행동 정의(다음 스텝으로 이동)
• 컬러 대비: WCAG AA 이상

7.11 로컬라이제이션 키 레지스트리(발췌)

예시 키만. 실제 문자열은 Localizable.xcstrings에서 관리.

• Launch: launch.tagline, launch.accessibility_label
• Conflict: conflict.title, conflict.card.friend.title, conflict.cta.free, conflict.cta.pro
• Journal: journal.title, journal.q1.title, journal.q2.title, …, journal.next, journal.complete
• Composer: composer.title, composer.tools.retry, composer.tools.soften, composer.share.copy, composer.share.image, composer.share.link
• Completion: completion.title, completion.tip, completion.ok
• Errors/State: error.network.offline, perm.photos.rationale, iap.error.timeout, …

7.12 텔레메트리(화면 매핑)

• V02 진입: ui.conflict_shown
• 관계 선택: ui.conflict_selected { conflict_type }
• 1단계 각 스텝 노출: journal.step_shown { step_index }
• 1단계 완료: journal.completed
• AI 초안 생성: ai.draft_generated
• AI 리라이트: ai.rewrite { variant }
• 전달: delivery.text_copied | delivery.image_saved | delivery.link_shared
• 세션 종료: user.session_end { duration_ms, crash_free }

7.13 엣지 케이스 정의

• 앱 재시작 시 미완료 JournalDraft 자동 복원(사용자 동의 키 journal.resume.prompt)
• 링크 공유 실패 후 재시도 시, 중복 저장 방지(클라이언트 UUID로 멱등 키)
• 장문 편지(예: >4000자) 생성 시 스냅 성능 저하 방지(가상화 스크롤 또는 지연 렌더링 정책)

[ConflictType]───┐
                  ├──> [JournalDraft] ──> [MessageDraft] ──> [Delivery (copy|image|link)]
[Entitlement]  ──┘              │
                                 └──(SwiftData 저장)
Services: AI(Large Language Model), IAP(StoreKit), LinkShare(Firestore), Photos

8.UI/UX 요구사항 (UI/UX Requirements) 

8.0 제품 UX 원칙 (Design Principles)

1. 평온함(Composed): 시각적 소음 최소화, 글 읽기·쓰기 집중 지원
2. 단순함(Focused): 한 화면 = 한 과업. 기본 선택지를 명확히 안내
3. 친절함(Kind): 실패·거절에도 사용자를 비난하지 않음(격려형 카피)
4. 안심(Private): 온디바이스 저장·오프라인 우선 UI로 신뢰 제공
5. 예측 가능성(Consistent): 동일한 액션은 동일한 위치·모양·문구

8.1 디자인 토큰 (Design Tokens)

코드에서는 토큰 이름만 참조합니다. 실제 값은 테마 파일에서 관리.

8.1.1 컬러

규칙: Dynamic Type 100% 지원. 대비 WCAG AA 이상 유지.

8.2 핵심 컴포넌트 (Components)

버튼 형식 강제: 모든 SwiftUI 버튼은 Button { /* action */ } label: { /* view */ } 형식만 사용.
문구는 반드시 현지화 키로 표기(예: Text("composer.share.link")).

8.2.1 PrimaryButton

• 모양: 가로폭 꽉 채움, 높이 48–52pt, radius.m, 배경 color.primary, 텍스트 Color.white
• 상태: 기본 / 비활성(불투명도 0.4) / 로딩(스피너) / 성공(체크 아이콘)
• 접근성: 최소 44pt 터치, VoiceOver 라벨 키 제공
• 예시 키: button.primary.start, button.primary.next, button.primary.buy

8.2.2 SecondaryButton (Outline)

• 테두리 color.border, 텍스트 color.text.primary, 배경 투명
• Paywall의 “복원”, “다음에 하기” 등 보조 액션에 사용
• 키: button.secondary.restore, button.secondary.later

8.2.3 Tag/EmotionChip

• Pill 형태, radius.s, 선택 시 color.primary 배경 + 흰색 텍스트
• 멀티 선택 허용, 선택/해제 애니메이션 120ms
• 키: emotion.happy, emotion.sad … + emotion.custom

8.2.4 Card

• color.surface 배경, radius.l, shadow.card
• Conflict 카드, “나의 마음” 요약 카드 등에 사용
• 타이틀·서브텍스트·배지(Free/Pro)·CTA 버튼 슬롯 제공
• 키: conflict.card.friend.title, conflict.badge.free, conflict.cta.free

8.2.5 InlineBanner

• 정보/경고/오류 3종. 좌측 아이콘 + 본문 + 선택적 CTA
• 오프라인 경고, 권한 가이드, 저장 성공 안내에 사용
• 키: banner.offline.title, banner.offline.body, banner.cta.retry

8.2.6 TextArea (Journal Input)

• 최소 높이 140pt, 자리표시자(키), 글자수 카운트(예: 0/500)
• 포커스 시 테두리 color.primary로 전환
• 키: journal.q1.placeholder, journal.char_count

8.2.7 Loading Indicator / Skeleton

• AI 생성·IAP 처리 중 중앙 인디케이터 또는 스켈레톤
• 키: state.loading.generating_draft, state.loading.processing

8.3 UI 패턴 (Patterns)

8.3.1 빈 상태 (Empty States)

• 원칙: “무엇(현재 상태)” + “왜(상태 이유)” + “다음 행동(CTA)”
• 예) Journal 첫 진입:
• 타이틀: empty.journal.title
• 본문: empty.journal.body(짧은 예시 2–3개 포함: journal.example.1…)
• CTA: button.primary.start → Q1로 포커스

8.3.2 로딩 (Loading)

• 2초 이상 로딩 시 “무엇을 하는 중인지” 서술: state.loading.generating_draft
• 8초 이상 시 “재시도/취소” 버튼 제공(가능 시)

8.3.3 오류 (Errors) — 현대 Error → 키 매핑

• 네트워크 없음:
• 배너: error.network.offline.title, error.network.offline.body
• CTA: banner.cta.retry
• 링크 공유 버튼 비활성 + 토스트 error.network.offline.toast
• IAP 실패:
• 시트/알럿: iap.error.canceled|timeout|unknown + iap.cta.retry
• 포토 권한 거부:
• 시트: perm.photos.denied.title, perm.photos.denied.body, perm.photos.go_settings

8.3.4 오프라인 UX

• 상단 인앱 배너 고정(필요 시): banner.offline.title/body
• 링크 공유 버튼 비활성 + 툴팁: delivery.link.disabled_offline
• 로컬 작업(기록/수정/이미지 저장)은 정상 허용

8.3.5 권한 UX (Just-in-time)

• 이미지 저장 시 최초 한 번 요청(거부 시 친절 가이드로 대체)
• 키: perm.photos.rationale, perm.photos.request.title, perm.photos.request.body

8.3.6 진행(Progress) & 단계 표시

• Journal 1/5, 2/5… 상단 진행 표시(텍스트+약한 bar)
• 키: journal.progress (예: “{current}/{total}” 바인딩)

8.3.7 제스처 & 뒤로가기

• 뒤로 제스처 허용하되 입력 상태 보존
• 단계 중 이탈 시 확인 시트(선택): journal.exit_confirm.title/body

8.4 특수 화면 UX 스펙

8.4.1 ConflictSelectionView

• 카드 캐러셀: 1.05x 확대 중심 카드, 좌우 8pt 프리뷰
• 배지: Free = 녹색, Pro = 잠금 아이콘+회색
• CTA 위치 고정: 하단 안전영역 위 16pt
• 텔레메트리: ui.conflict_selected { conflict_type }

8.4.2 PaywallView (Sheet)

• 구성: 헤드라인 → 혜택 3~4개(아이콘+짧은 문구) → 가격/정책 → CTA(구매) → 보조(복원/다음에)
• 신뢰 요소: “1회 구매 · 평생 이용”(키), 환불 정책 미니문구(키)
• 로드 상태: 구매 중 인터랙션 잠금 + 스피너
• 키: paywall.title, paywall.benefits.*, paywall.buy, paywall.one_time.lifetime, paywall.restore, paywall.later

8.4.3 GuidedJournalView (5 스텝)

• 한 화면 한 질문 원칙, 예시 문구 제공
• 글자수 제한 시 실시간 카운트 + 긍정 피드백(journal.counter.ok)
• [다음] 비활성 조건 명확화(검증 실패 키 제공)
• 키: journal.q{n}.title, journal.q{n}.helper, journal.next, journal.complete

8.4.4 MessageComposerView

• 상단 “나의 마음 요약 카드”: 감정 태그+핵심 욕구 키워드 수평 스크롤
• 본문 에디터(고정 폭 + 충분한 라인 높이)
• AI 도우미 4버튼: 다시 제안 / 더 부드럽게 / 더 간결하게 / 더 진솔하게
• 키: composer.tools.retry|soften|concise|authentic
• 공유 섹션 3버튼: 복사 / 이미지 저장 / 링크 공유
• 키: composer.share.copy|image|link
• 상태 안내(로딩·성공 토스트): composer.toast.copied, composer.toast.image_saved, composer.toast.link_ready

8.4.5 CompletionView

• 큰 칭찬 문구 + “앞으로를 위한 팁” 1~2개
• 홈으로 돌아가는 명확한 CTA
• 키: completion.title, completion.tip, completion.ok

8.5 모션 & 햅틱 (Motion & Haptics)

• 모션 지침: 120–200ms 내 자연스러운 이징(easeInOut), 과도한 패럴랙스 금지
• 피드백 타이밍:
• 카드 선택, 구매 성공, 편지 저장 성공 = success 햅틱
• 오류 배너 표시 = warning 햅틱(약하게)
• 감정 태그 토글 = light 탭틱
• 애니메이션 예: AI 텍스트 갱신 시 “타자 효과” 400–800ms (사용자 취소 불필요)

8.6 접근성 (A11y)

• 터치 타겟: 최소 44×44pt
• VoiceOver 라벨/힌트: 모든 버튼·칩·카드에 키 제공
• 예: a11y.conflict.card.friend, a11y.button.buy_pro
• 다크 모드: 대비 AA 유지, 색의 의미에 텍스트/아이콘 보조(색상 단독 의존 금지)
• 동적 폰트: Large 이상에서도 레이아웃 파손 없는 자동 줄바꿈
• 감정 아이콘: 텍스트 라벨 병기(아이콘 단독 사용 금지)

8.7 현지화 규칙 (Localization)

• 절대 규칙: UI 내 직접 문자열 금지, 모두 Localizable.xcstrings 키로 참조
• 플레이스홀더/매개변수: ICU 형식 권장(예: 진행률 “{current}/{total}”)
• 복수형: 필요 시 언어별 규칙 반영 키 분리(.one/.other)
• 톤 & 보이스: 부드럽고 격려형(“괜찮아요”, “다시 해볼까요?”)

• Buttons: button.primary.start, button.primary.next, button.primary.buy, button.secondary.restore, button.secondary.later
• States: state.loading.generating_draft, state.saved, state.network.checking
• Errors: error.network.offline, error.unknown, iap.error.canceled, perm.photos.denied.title/body
• Journal: journal.q1.title, journal.q1.placeholder, journal.complete, journal.example.1/2/3
• Composer: composer.tools.retry/soften/concise/authentic, composer.share.copy/image/link, composer.toast.*

8.8 이미지 내보내기(“이미지로 저장”) 스펙

• 해상도: 최소 1080×1920px(2× 스케일), 여백 spacing.xl
• 배경: 차분한 종이 질감(Assets), 대비 충분
• 폰트: 본문 type.body 라인 높이 1.4–1.5
• 워터마크(선택): 하단 “KindVerb” 미세 그레이(접근성 침해 없도록)
• 성공 피드백: 토스트 composer.toast.image_saved + success 햅틱

8.9 링크 공유 UX (온라인)

• 버튼 활성 조건: 네트워크 Online + AI 본문 1자 이상
• 클릭 → 상태: 로딩 인디케이터 + “링크 생성 중”(delivery.link.creating)
• 성공: 시스템 공유 시트 표시, 토스트 composer.toast.link_ready
• 실패: 배너 error.network.offline 또는 error.link.create_failed
• 만료 안내: 텍스트 키 delivery.link.ttl_notice (예: “7일 후 자동 삭제”)

8.10 분석 이벤트(UX 관점 요약)

8.11 수용 기준 체크리스트 (UI/UX)

• 모든 버튼은 표준 형식 사용(액션/라벨 분리)
• 모든 문구는 현지화 키로만 표기
• 터치 타겟 44pt 이상, Dynamic Type 완전 대응
• AI 로딩 2초 초과 시 상태 문구 노출, 8초 초과 시 재시도 제공
• 오프라인 시 링크 공유 비활성 + 배너/토스트 안내
• 포토 권한 거부 시 설정 이동 시트 표준 제공
• Paywall “1회 구매·평생 이용” 문구와 복원 버튼 노출
• 이미지 내보내기 결과 가독성 및 대비 AA 충족
• 텔레메트리 이벤트가 표에 맞게 전부 발화
• 다크 모드 대비·아이콘/색 의존 최소화

9.플랫폼 & 기술결정 + 에러 도메인 (Platform & Tech Decisions + Error Domain)

9.1 지원 환경 & 빌드 정책

• Target OS: iOS 17+ (SwiftData 사용·현대 접근성·새로운 StoreKit UI 사용 목적)
• Language/Runtime: Swift 6+, Swift Concurrency(Structured Concurrency) 100%
• UI: SwiftUI 100% (UIKit 혼합 금지. 필요 시 wrapper 컴포넌트로 격리)
• 아키텍처: MVVM + UseCase + Repository + Service (의존성 역전 유지)
• 패키지 관리자: Swift Package Manager (SPM)
• 서드파티: 최소화. 필요 시 Firebase(Firestore) & StoreKit만 사용
• 현지화: Localizable.xcstrings 키 기반(기본 언어 en, ko/ja/zh-Hans 병행)
• 접근성: Dynamic Type/VoiceOver/색상대비 AA 이상

9.2 계층 구조(레이어) & 책임

원칙: View는 표시와 입력만, ViewModel은 상태·의도 관리, UseCase는 업무 규칙, Repository는 도메인 I/O, Service는 외부/플랫폼 호출.

View (SwiftUI)
  ↕ @Published / intents
ViewModel (ObservableObject)
  ↕ UseCase (async)
Repository (protocols → impl: Local/Remote)
  ↕
Services (SwiftData, File, Network(Firestore), IAP, ShareLink)

• View: UI 그리기, 사용자 액션을 Intent로 위임, 문자열은 키만 사용
• ViewModel: 상태머신(Idle/Loading/Success/Error), 취소(Cancellation) 관리
• UseCase: 업무 규칙 캡슐화(예: “AI 초안 생성 후 텍스트 정제”)
• Repository: 도메인 모델 중심 I/O(예: Journal 저장/조회, Letter 업로드)
• Service: 플랫폼·라이브러리 상세 구현(교체 가능한 낮은 레벨)

9.3 동시성 & 성능 가드레일 (async/await)

• Structured Concurrency: Task {} / TaskGroup / withTimeout 활용
• MainActor 규칙: UI state 변경은 @MainActor에서만
• 취소 전파: 화면 이탈 시 진행 중 작업 자동 취소(메모리·배터리 보호)
• 백오프 재시도: 네트워크 계열은 exponential backoff (max 3회)
• 타임아웃: AI/공유링크 8초 타임아웃 → 사용자 재시도 유도
• 메모리/스토리지: SwiftData로 로컬 우선, 대용량 텍스트는 파일 분리 고려

9.4 저장소 & 네트워크 결정

• 로컬 영속성: SwiftData (온디바이스 100%)
• 모델: Journal, EmotionEntry, Settings, PurchaseState 등
• 마이그레이션: SchemaVersion 명시, 파괴적 변경 금지
• 원격(Firestore): 선택적 링크 공유에 한정(문서 TTL 7일)
• 인증 불필요(익명 쓰기 규칙 + 읽기 금지)
• 오프라인 시 링크 공유 비활성/대기 큐 없음(명시적 디자인)

9.5 인앱결제(StoreKit 2)

• 상품: 일회성(Lifetime) kindverb.pro.lifetime
• 구매 흐름: Paywall → 구매/복원 → PurchaseState 갱신 → UI 리프레시
• 오류 처리: 사용자 메시지는 현지화 키로만 표기(IAP 전용 에러 키 별도)

9.6 로깅 & 텔레메트리

• Logger: os.Logger 채택, 카테고리(“UI”, “IAP”, “AI”, “LINK”, “STORE”, “DATA”)
• 개인정보: 민감 데이터 로그 금지. 이벤트는 PRD 6.5/8.10 정의에 일치
• 레벨 규칙: debug(개발용), info(흐름), error(에러 도메인 코드 포함)

9.7 피처 플래그 & 구성

• 간단 플래그: AppConfig 구조체 / @Environment(\.appConfig) 주입
• 예시: enableTypingAnimation, enableLinkShare, aiModel="gpt-5"
• 원격 플래그: 초기 릴리스는 없음(단순성 유지). 필요 시 UserDefaults 동기화

9.8 테스트 전략

• 단위 테스트: ViewModel/UseCase/Repository에 집중(Mock Service 주입)
• 스냅샷: 핵심 View(Conflict/Journal/Composer/Paywall) 다크/라이트·동적폰트
• E2E(선택): XCUITest로 핵심 플로우(선택→기록→초안→공유→완료)
• 회귀 방지: 에러 도메인 매핑·현지화 키 누락 체크

9.9 에러 도메인(분류 체계) — 사용자 메시지는 전부 “키”로

개발자는 타입 안전 Error로 원인·복구전략 결정 → ViewModel이 UI 상태로 매핑 → View는 키만 표시.

9.9.1 에러 최상위 분류

• AppError (enum)
• .network(NetworkError) — 연결·타임아웃·상태코드
• .storage(StorageError) — SwiftData 읽기/쓰기/마이그레이션
• .iap(IAPError) — 결제/영수증/복원
• .permission(PermissionError) — 포토 등 권한 거부
• .ai(AIError) — 초안 생성 실패·쿼터·포맷
• .link(LinkError) — Firestore 쓰기/TTL 정책 위반
• .validation(ValidationError) — 입력 검증 실패
• .unknown(underlying: Error?) — 미분류(로깅만 상세)

9.9.2 서브 도메인 예시

• NetworkError = .offline, .timeout, .unreachable, .http(code:Int)
• StorageError = .saveFailed, .fetchFailed, .migrationRequired
• IAPError = .canceled, .notFound, .verificationFailed, .unknown
• PermissionError = .photosDenied, .photosRestricted, .notDetermined
• AIError = .serviceUnavailable, .rateLimited, .invalidResponse, .timeout
• LinkError = .createFailed, .unauthorizedRule, .quotaExceeded
• ValidationError = .empty(field), .tooLong(field,max), .invalidFormat(field)

9.9.3 에러 → UI 매핑(현지화 키)

직접 문자열 금지: 모든 사용자 문구는 키로만 표기.
개발자용 상세는 Logger에 남김(PII 금지).

9.10 실패-복구(UX) 표준 플로우

1. 탐지: catch AppError
2. 분류: 도메인별로 ErrorViewState 변환(배너/토스트/시트)
3. 복구 옵션: 재시도, 설정 이동, 입력 수정, 오프라인 대체
4. 기록: 텔레메트리 이벤트(error.domain, error.code, screen)
5. 사용자 보장: “진행 중 입력/초안은 소실되지 않음” 원칙 준수

9.11 코드 스니펫(아주 작은 예시, 규칙 준수)

실제 구현은 다음 섹션에서 파일 단위로 제공합니다. 여기서는 원칙 준수 예시만 간단히 남깁니다. (문자열은 키, 버튼 형식 고정, async/await, 현대 Error)

// 한 줄 한 줄 주석: 왜 이렇게 구성하는지 설명합니다.

// App 전역에서 사용할 에러 최상위 타입을 정의합니다.
// 이유: 도메인별 세부 에러를 하나의 공통 타입으로 모아
// ViewModel에서 일관된 방식으로 UI 상태를 만들기 위함입니다.
enum AppError: Error {
    // 네트워크 관련 에러(오프라인, 타임아웃 등)를 감쌉니다.
    case network(NetworkError)
    // 로컬 저장(SwiftData) 관련 에러를 감쌉니다.
    case storage(StorageError)
    // 인앱결제 관련 에러를 감쌉니다.
    case iap(IAPError)
    // 권한 거부 등 권한 관련 에러를 감쌉니다.
    case permission(PermissionError)
    // AI 초안 생성 실패 등 AI 관련 에러를 감쌉니다.
    case ai(AIError)
    // 링크 공유(Firestore) 관련 에러를 감쌉니다.
    case link(LinkError)
    // 입력값 검증 실패를 감쌉니다.
    case validation(ValidationError)
    // 분류되지 않은 모든 에러를 안전하게 수용합니다.
    case unknown(underlying: Error?)
}

// 네트워크 하위 에러 예시입니다.
// 이유: 사용자 메시지는 동일하지만, 로깅과 정책은 코드별로 달라질 수 있기 때문입니다.
enum NetworkError: Error { case offline, timeout, unreachable, http(code: Int) }

// 이 함수는 AppError를 받아서 화면에 표시할 "키"를 결정합니다.
// 이유: 사용자 문구는 코드에 직접 쓰지 않고, 항상 키를 반환하기 위함입니다.
func localizedKeys(for error: AppError) -> (titleKey: String, bodyKey: String?, ctaKey: String?) {
    switch error {
    case .network(.offline):
        return ("error.network.offline.title", "error.network.offline.body", "banner.cta.retry")
    case .network(.timeout):
        return ("error.network.timeout.title", "error.network.timeout.body", "banner.cta.retry")
    case .iap(.canceled):
        return ("iap.error.canceled", nil, nil)
    case .permission(.photosDenied):
        return ("perm.photos.denied.title", "perm.photos.denied.body", "perm.photos.go_settings")
    case .link(.createFailed):
        return ("error.link.create_failed", nil, "banner.cta.retry")
    default:
        return ("error.unknown", nil, nil)
    }
}

// 규칙 1: 버튼은 반드시 action/label 분리 형식을 사용합니다.
// 규칙 2: 사용자 노출 문자열은 키만 사용합니다.
Button {
    // 액션: 재시도 같은 복구 로직을 실행합니다(비동기).
    Task { await viewModel.retry() }
} label: {
    // 라벨: 현지화 키를 Text에 넣습니다(직접 문자열 금지).
    Text("banner.cta.retry")
}
.accessibilityLabel(Text("a11y.banner.retry")) // 접근성 라벨도 키 사용

9.12 보안·개인정보(플랫폼 차원 결정 요약)

• 데이터 경계: 온디바이스 99%, 링크 공유만 익명 원격 쓰기
• 민감데이터: 외부 전송 금지. 로그·이벤트에 원문 텍스트 금지(길이·해시만)
• 키 관리: API 키·IAP 상품 ID는 빌드 설정/환경 주입, 코드 하드코딩 금지
• 네트워크: TLS 1.2+, ATS 기본, 중간자 공격 방어(증명서 핀닝 불필요)

9.13 유지보수·확장성 고려

• 교체 가능성: AIResponseService는 프로토콜로 추상화(모델·벤더 교체 용이)
• 백엔드 축소: 기본은 오프라인. 링크 공유 외 서버 의존 제거(비용↓, 위험↓)
• 모듈화: Services/ 하위 컴포넌트는 독립 테스트 가능하도록 최소 결합
• 관측성: 실패율, 초안 지연 시간, IAP 전환율 핵심 지표 대시보드화 전제

9.14 이 섹션의 “확정/보류” 목록

• 확정: iOS17+, SwiftUI/MVVM, SwiftData, StoreKit2, async/await, Error 도메인, 키 기반 현지화, 링크 공유 Firestore(TTL 7일)
• 보류: 원격 피처 플래그(초기 릴리스 제외), 푸시 인앱 메시지 타게팅(추후 16단계에서 상세)

10. 데이터모델 (Entities · JSON · Relationships/States)

10.1 모델링 원칙 (Design Principles)

• 온디바이스 99%: 사용자의 모든 민감 데이터는 SwiftData 로컬 저장.
• 클라우드 1%: 선택 기능 “링크 공유”만 Firestore에 익명 저장(읽기 금지 + TTL 7일).
• 단순·명확: 엔티티는 “한 가지 책임”. 긴 텍스트는 최대 길이 제한(일관된 검증).
• 상태 머신: 주요 엔티티는 유한 상태(STATE) + 전이(TRANSITION) 를 명확히 정의.
• 버전 관리: schemaVersion 필드로 점진적 마이그레이션 대비.
• 테스트 가능성: ID는 UUID v4, 시간은 ISO8601/Z(저장 시 시스템 타임존→UTC 정규화).

10.2 엔티티 개요(요약 표)

10.3 상세 스펙 — 엔티티별 정의

A) ConflictType (열거형 · 코드 상수)

• 역할: 관계 시나리오 구분 + 무료/Pro 게이팅.
• 값 (고정, 키 문자열은 로컬라이즈 키와 매핑 가능):
• friends (Free), couple (Free), parentChild (Pro), siblings (Pro), inLaws (Pro)
• 표시 키 예시: conflict.friends.title, conflict.couple.title, …
• 검증 규칙: Journal.conflictType ∈ {위 5개}

B) Journal (자기 성찰 세션)

• draft → (모든 필수 질문 통과) → completed
• completed 상태에서만 편지 초안 생성 허용.

{
  "Journal": {
    "id": "uuid",
    "schemaVersion": 1,
    "conflictType": "friends | couple | parentChild | siblings | inLaws",
    "status": "draft | completed",
    "situationText": "string(max:500)",
    "feelings": ["string(max:24)"],
    "hurtText": "string(max:500)",
    "reflectionText": "string(max:500)|null",
    "desiredNeedText": "string(max:500)",
    "createdAt": "2025-08-21T03:14:15Z",
    "updatedAt": "2025-08-21T03:14:15Z"
  }
}

{
  "id": "b8c7d5d7-4a8b-4f0f-9a64-6d78f1b8c1ab",
  "schemaVersion": 1,
  "conflictType": "couple",
  "status": "completed",
  "situationText": "주말 약속을 깜빡해서 다투었다.",
  "feelings": ["guilty", "anxious"],
  "hurtText": "내가 지키지 못한 약속 때문에 상대가 존중받지 못했다고 느꼈을 수 있다.",
  "reflectionText": "변명보다 책임을 먼저 인정해야겠다.",
  "desiredNeedText": "서로의 약속을 더 확실히 확인하고 싶은 마음.",
  "createdAt": "2025-08-20T12:00:00Z",
  "updatedAt": "2025-08-20T12:30:00Z"
}

C) LetterDraft (편지 초안: AI + 사용자 편집)

• drafted(AI 생성 직후) → edited(사용자 수정) → finalized(전달 준비 완료)
• finalized에서만 ShareRecord 생성 허용

{
  "LetterDraft": {
    "id": "uuid",
    "journalId": "uuid",
    "schemaVersion": 1,
    "status": "drafted | edited | finalized",
    "content": "string(max:10000)",
    "aiModel": "gpt-5",
    "promptVersion": 1,
    "tone": "neutral_warm | softer | concise | sincere",
    "iteration": 1,
    "createdAt": "2025-08-21T03:14:15Z",
    "updatedAt": "2025-08-21T03:14:15Z"
  }
}

D) ShareRecord (링크 공유 로컬 추적)

• pending(업로드 시도) → success(원격ID 발급) / failed / canceled

• 필드:
• content: string(max:10000)
• createdAt: timestamp(서버시간) → TTL 7일 후 자동 삭제
• 규칙: create만 허용, read/update/delete 전면 금지.

E) PurchaseState (Pro 구매 상태)

F) Settings (앱 설정)

10.4 관계(ER 다이어그램 텍스트)

• Journal(1) — LetterDraft(N)
  한 번의 성찰 세션에서 여러 편지 버전을 만들 수 있음.
• LetterDraft(1) — ShareRecord(0..1)
  최종 확정된 초안만 공유 레코드를 가질 수 있음.

• Journal 삭제 → 관련 LetterDraft 전부 삭제 → 연결된 ShareRecord도 삭제
• LetterDraft 삭제 → 연결 ShareRecord 있으면 함께 삭제
• 원격 Firestore 문서는 TTL로 자동 삭제(로컬에서 강제 삭제 동작 없음)

10.5 검증 규칙 (Validation)

• 길이 제한 (모두 “문자 수” 기준)
• situationText, hurtText, reflectionText, desiredNeedText ≤ 500
• LetterDraft.content ≤ 10000
• feelings 배열 길이 ≤ 8, 각 항목 ≤ 24
• 필수 입력
• Journal: conflictType, situationText, feelings(≥1 권장), hurtText, desiredNeedText
• LetterDraft: journalId, content, status
• 상태 전이 시점 검사
• Journal.completed 전환 전에 필수 항목 충족 확인
• LetterDraft.finalized 전환 전에 길이/금칙어(욕설 등 선택 사항) 검사
• 무결성
• ShareRecord: contentHash는 업로드 당시 LetterDraft.content의 SHA-256
• ShareRecord.status == success이면 remoteId,url,expiresAt 존재해야 함

10.6 인덱싱 & 조회 패턴 (SwiftData)

• 주요 인덱스:
• Journal: createdAt DESC, status, conflictType
• LetterDraft: journalId, updatedAt DESC, status
• ShareRecord: status, createdAt DESC
• 대표 쿼리
• 홈: 최근 Journal 5건 (completed 우선)
• 작업실: journalId로 최신 LetterDraft 1건
• 공유 히스토리: ShareRecord where status in (success,failed) order by createdAt DESC

10.7 상태 머신 정리(표)

Journal

LetterDraft

ShareRecord

10.8 오류 메시지 키(데이터 계층 관련)

UI 문구는 키만 사용(실 문자열 금지). 아래 키는 9장에서 정의한 에러 도메인과 합치.

10.9 샘플 픽스처 (End-to-End)

완료된 세션 → 초안 2개 중 1개 확정 → 공유 성공 흐름

{
  "Journal": {
    "id": "3c1f7a15-4b1c-4e94-a05f-9f2a4a6b0c11",
    "schemaVersion": 1,
    "conflictType": "parentChild",
    "status": "completed",
    "situationText": "숙제 문제로 언성을 높였다.",
    "feelings": ["worried", "frustrated"],
    "hurtText": "아이의 자율성을 침해했다고 느꼈을 수 있다.",
    "reflectionText": "지적보다 공감을 먼저 하자.",
    "desiredNeedText": "서로 일정을 합의하고 존중받고 싶은 마음.",
    "createdAt": "2025-08-19T10:00:00Z",
    "updatedAt": "2025-08-19T10:15:00Z"
  },
  "LetterDrafts": [
    {
      "id": "7e6f8d9a-3d1e-44a7-9b02-8e0f2e9d1234",
      "journalId": "3c1f7a15-4b1c-4e94-a05f-9f2a4a6b0c11",
      "schemaVersion": 1,
      "status": "edited",
      "content": "어제 내 말투가 상처가 되었을 것 같아...",
      "aiModel": "gpt-5",
      "promptVersion": 1,
      "tone": "softer",
      "iteration": 2,
      "createdAt": "2025-08-19T10:16:00Z",
      "updatedAt": "2025-08-19T10:20:00Z"
    },
    {
      "id": "1a2b3c4d-55aa-66bb-77cc-8899ddeeff00",
      "journalId": "3c1f7a15-4b1c-4e94-a05f-9f2a4a6b0c11",
      "schemaVersion": 1,
      "status": "finalized",
      "content": "어제 네 마음을 충분히 듣지 못한 점 미안해...",
      "aiModel": "gpt-5",
      "promptVersion": 1,
      "tone": "sincere",
      "iteration": 3,
      "createdAt": "2025-08-19T10:21:00Z",
      "updatedAt": "2025-08-19T10:25:00Z"
    }
  ],
  "ShareRecord": {
    "id": "0f9e8d7c-6b5a-4321-9abc-ef0123456789",
    "letterId": "1a2b3c4d-55aa-66bb-77cc-8899ddeeff00",
    "remoteId": "a7Xp2Rz0KLMn",
    "url": "https://kindverb.com/letter/a7Xp2Rz0KLMn",
    "status": "success",
    "contentHash": "b1f79e2a5c2b1a...<총64자리sha256>...",
    "expiresAt": "2025-08-26T10:25:00Z",
    "createdAt": "2025-08-19T10:25:05Z",
    "updatedAt": "2025-08-19T10:25:05Z"
  }
}

10.10 마이그레이션 전략

• Schema v1: 본 문서의 필드 집합.
• 향후 변경 예: feelings를 구조화([{code,label}])하거나 content에 서식 추가.
• 원칙: 파괴적 변경 회피 → 새로운 필드는 옵셔널로 추가 → 마이그레이션 태스크에서 기본값 세팅.

10.11 성능·용량 가드

• LetterDraft.content 상한 10KB 수준 → 편지 1천자 내외 안정.
• 인덱스는 “최근/상태/참조” 위주로 최소화.
• 공유 실패 재시도는 사용자 의도형(자동 무한재시도 금지).

10.12 개인정보 & 보안

• 로컬 저장 암호화는 OS 보호 영역(File Protection) 신뢰.
• 로그/이벤트에 원문 텍스트 절대 기록 금지(길이·해시만).
• Firestore는 읽기 금지 + TTL 7일로 자동 삭제.

11.API 개요 (API Overview - Auth, Endpoints, Errors, Rate)

11.1 철학 & 범위

• 기본 원칙: 로그인/회원가입 없음. 읽기 금지, 쓰기 전용 원격 저장. 사용자 원문은 원칙적으로 기기 밖으로 나가지 않음.
• 네 가지 통신만 허용
1. Firestore letters.create: “링크로 공유하기” 시 편지 원문을 익명 단발성으로 업로드(읽기 불가, TTL 7일).
2. (옵션) LLM Draft API: 사용자가 “클라우드 초안 향상” 기능을 켰을 때만, 비식별 프롬프트로 초안 생성.
3. Apple StoreKit: 인앱결제 영수증 온디바이스 검증(서버 불필요).
4. App Check/Attestation: 파이어스토어 남용 방지용 기기 무결성 검증.
• 버전 전략: 모든 원격 스키마/엔드포인트는 /v1 고정. 필드 추가 시 하위 호환 유지.

11.2 인증(Auth) & 보안(Sec)

• 사용자 인증: 없음(완전 익명).
• 남용 방지: Firebase App Check(디바이스 무결성) 필수. iOS는 DeviceCheck/앱 무결성 공급자 사용.
• 보안 규칙(Firestore):
• 컬렉션: letters
• 허용: create(쓰기)만. read/update/delete 전면 금지.
• 필수 필드: content (string, ≤10000자), createdAt (serverTimestamp)
• TTL: createdAt + 7일 자동 삭제.
• 개인정보: UI/텔레메트리/로그에 원문 텍스트 저장 금지. 로컬에도 OS 보호 영역(File Protection) 신뢰.

11.3 엔드포인트 일람(요약)

주의: Firestore “읽기”는 절대 제공하지 않습니다. 링크 페이지 조회는 웹(KindVerb.com) 에서만 가능하며 앱·서버는 해당 문서를 읽지 않습니다.

11.4 상세 스펙 — Firestore letters.create (유일한 원격 저장)

요청(Request) (클라이언트가 Firestore SDK로 add)

{
  "content": "string (<=10000)",         // 편지 원문 (최종본)
  "createdAt": "serverTimestamp()"       // 서버 타임스탬프 (클라이언트 입력 금지)
}

• 전송 전 강제 규칙(클라이언트 측)
• content 길이 ≤ 10000
• contentHash = SHA-256(content) 계산 → 로컬 ShareRecord.contentHash에 저장(중복/재시도 판단용)
• 비속어 필터(선택): 금칙어 있으면 사용자 경고(서버로 전송 자체는 막지 않음—표현 자유, 단 앱 정책 경고)

보안 규칙(Sample)

• allow create: if request.resource.data.keys().hasAll(['content', 'createdAt']) && request.resource.data.content is string && request.resource.data.content.size() < 10000;
• allow read, update, delete: if false;
• TTL: 콘솔에서 createdAt 필드에 7일 정책 지정.

응답(Response)

• Firestore SDK는 문서 ID를 반환.
• 앱은 이 ID로 **https://kindverb.com/letter/{id}**를 구성하여 공유 시트에 전달.
• 앱은 문서를 읽지 않으므로 Firestore에서 내용을 가져오지 않음.

에러(클라이언트 맵핑)

• permission-denied → error.link.permission_denied
• resource-exhausted(쿼터/속도) → error.link.rate_limited
• unavailable(네트워크/서버) → error.network.unavailable
• invalid-argument(검증 실패) → error.link.invalid_content
• unknown → error.common.unknown

11.5 (옵션) LLM Draft API — 비식별 프록시 계약

개요

• 기본값 OFF → 사용자가 “AI 초안 생성” 기능을 명시적으로 켰을 때만 호출.
• 모델 고정: Google Gemini 2.5 Flash Lite.
• API Key 관리: 앱 내 Secrets.plist 파일에 "GeminiAPIKey" 항목으로 저장.
• .gitignore 적용 필수.
• 런타임 시 Bundle.main.path(forResource: "Secrets", ofType: "plist") 로 안전하게 로드.
• 비식별화 원칙: 모든 사용자 입력(성찰 답변, 일기 텍스트)은 전송 전 온디바이스에서 고유명사/민감정보 토큰화(<PERSON_1>, <DATE_1> 등).
• 로깅: 네트워크 요청/응답은 import os.log를 이용한 Apple 통합 로깅에 메타데이터만 기록. (print 금지, PII 금지)

엔드포인트

• URL: https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent
• 메서드: POST
• 헤더:
• Authorization: Bearer <GeminiAPIKey>
• Content-Type: application/json

요청(Request) JSON (비식별화된 상태)

{
  "contents": [
    {
      "parts": [
        {
          "text": "Please draft a warm, empathetic message based on the following context:\nSituation: <PERSON_1> said something hurtful\nFeelings: [sad, disappointed]\nHurt: I felt ignored\nReflection: I may have overreacted\nNeed: I want to feel respected"
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "topK": 40,
    "topP": 0.95,
    "maxOutputTokens": 800
  }
}

응답(Response) JSON

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "I felt hurt when I was ignored. I may have overreacted, but what I need most is to feel respected..."
          }
        ]
      },
      "safetyRatings": [
        { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 120,
    "candidatesTokenCount": 95,
    "totalTokenCount": 215
  }
}

클라이언트 후처리

1. 응답의 candidates[0].content.parts[0].text 추출.
2. 토큰화된 엔터티(<PERSON_1>, <DATE_1>)를 역치환하여 원래 사용자 문맥 복원.
3. LetterDraft 엔티티에 저장 (status="drafted", aiModel="gemini-2.5-flash-lite").

Rate Limit (앱 차원에서 강제)

• 디바이스당 ≤ 20회/일, ≤ 6회/분.
• 실패 시 지수 백오프: 1s → 2s → 4s → … 최대 32s, 5회 재시도.

오류 매핑 (현지화 Key 기반)

• 모든 사용자 표시 문구는 Localizable.xcstrings Key 참조 필수.
• 로깅은 os_log("Gemini API failed: %{public}@", log: .network, type: .error, error.localizedDescription) 형식 사용.

11.6 인앱결제(StoreKit) 검증

• 전략: 온디바이스 영수증 검증(서버 불필요).
• 상태 전파: 성공 시 PurchaseState.isPro = true, purchaseDate 세팅, originalTransactionId 저장.
• 구매 복원: Apple 영수증 재검증 → 동일 originalTransactionId 확인.
• 에러 키:
• 검증 실패: error.iap.verify_failed
• 복원 실패: error.iap.restore_failed
• 취소: error.iap.user_canceled

11.7 레이트 리밋 & 백오프 (클라이언트 관점)

Firestore 자체 쿼터/스루풋 한계 발생 시에도 위 정책이 우선 적용되어 사용자 경험을 보호합니다.

11.8 에러 규약(통합 포맷)

• 앱 내부 표준 에러 객체

{
  "domain": "link|ai|iap|network|common",
  "code": "permission_denied|rate_limited|timeout|verify_failed|unknown",
  "messageKey": "error.link.rate_limited.message",     // UI 표기용 현지화 키
  "debugInfo": { "httpLike": 429, "provider": "firestore" } // 로그 전용(PII 금지)
}

• 표시 규칙: 사용자 메시지는 항상 messageKey → Localizable.xcstrings로 렌더링.

11.9 보안·프라이버시 가드레일

• 원격 전송 데이터는 최소 필드 집합만: content(letters), nvc 요약(옵션 LLM).
• LLM 전송 전 개인정보 토큰화 필수. 토큰 목록은 디바이스 내에서만 보관.
• 읽기 금지 설계로, 앱·서버 모두 사용자의 편지 원문을 재다운로드할 수 없음.
• 텔레메트리에는 해시/길이/상태만 기록(원문 절대 금지).

11.10 계약 테스트(수용 기준)

• letters.create
• (성공) 문서 ID 수신 → ShareRecord.status=success, remoteId/url 채움, expiresAt=+7d 표시
• (권한오류) App Check 미설정 시 permission-denied → error.link.permission_denied 매핑
• (과다요청) 1분 내 3건 전송시 1건 블록 → error.link.rate_limited
• drafts.create(옵션)
• (성공) 5초 이내 응답, content 길이 ≤10000
• (정책위반) 금칙어 다량 포함 시 공급자 에러→ error.ai.content_policy

11.11 변경/확장 여지

• 서버리스 함수 추가 시나리오(향후):
• 조기 만료(“즉시 파기”) 토큰 기반 delete — 현 시점은 미도입(읽기/삭제 금지 유지)
• 링크 조회수 카운팅(서버 측 집계만, 원문 접근 없이)
• LLM 프록시: 기업용 배포에서 키 관리/프롬프트 로깅(비식별) 요구 시 프록시 권장.

12.오프라인・동기화・캐싱 (Offline・Sync・Caching)

12.1 원칙 (Principles)

• 오프라인 우선(Offline-First): 주요 기능(관계 선택, 성찰, 편지 작성/편집, 로컬 저장)은 네트워크 없이 100% 동작.
• 클라우드 1%만 사용: Firestore는 ‘링크로 공유’ 기능에 한하여 쓰기(Create)만 사용(읽기/수정/삭제 없음, TTL 7일).
• 로컬 영구 저장: 사용자 생성 데이터는 SwiftData(온디바이스)로 저장. iCloud/서버 백업 없음(프라이버시 최우선).
• 현대적 오류 처리: throw/try/catch 기반 도메인 에러. NSError/Completion Handler 금지.
• UX 일관성: 연결 상태와 무관하게 같은 플로우를 제공하되, 온라인 기능은 명확한 상태 안내와 복구 경로 제공.
• 로깅: os.log 사용, PII/콘텐츠 본문 기록 금지(메타데이터만).

12.2 데이터 구분 (Data Residency & Classes)

12.3 로컬 저장 구조 (SwiftData 모델 스냅샷)

실제 코드 구현은 Xcode에서 진행. 여기서는 스키마/필수 필드만 정의.

• Journal: id(UUID), createdAt(Date), relationType(Enum), situation(Text≤2000), feelings([String]≤20), hurt(Text≤2000), reflection(Text≤2000?), need(Text≤2000), version(Int).
• LetterDraft: id(UUID), journalId(UUID?), stage(Enum: draft|edited|final), content(Text≤6000), aiModel(String?), updatedAt(Date), version(Int).
• ShareTask(아웃박스): id(UUID), letterId(UUID), status(Enum: queued|uploading|succeeded|failed), attempts(Int), lastErrorCode(String?), shareURL(String?), expiresAt(Date?), createdAt(Date), updatedAt(Date).

12.4 읽기/쓰기 경로 (Read/Write Path)

12.4.1 쓰기(오프라인)

1. View → ViewModel이 Journal/LetterDraft를 즉시 로컬 저장
2. 성공 시 UI 피드백(토스트/배지)
3. 실패 시 도메인 에러 storage.write_failed를 발생 → 현지화 키로 사용자 안내

12.4.2 읽기

• SwiftData 단일 소스(Single Source of Truth).
• 리스트 화면은 시간 역순 정렬 캐시, 상세 화면 진입 시 최신 로드.

12.5 캐싱 정책 (Caching Policy)

• 뷰 캐시: 화면 전환 간 5분 이내 재진입 시, ViewModel 메모리 캐시 우선 → 백그라운드 진입 시 무효화.
• 이미지 렌더 캐시: 편지 이미지 저장 프리셋 렌더 결과를 파일 캐시에 저장(해시 키: letterId+스타일). 24시간 후 자동 삭제.
• AI 결과 캐시: LetterDraft.content 자체가 캐시. 같은 입력으로 재요청 방지.

12.6 링크 공유 동기화 (Outbox Sync)

12.6.1 개념

• 네트워크 의존 기능은 **아웃박스 큐(ShareTask)**를 통해 신뢰성 있는 비동기 전송.
• UI는 즉시 완료 피드백 대신 “전송 대기/업로드 중/성공/실패” 상태를 명확히 표현.

12.6.2 상태 머신

• queued: 네트워크 불가/사용자 트리거 생성 직후
• uploading: Firestore Create 실행 중
• succeeded: shareURL·expiresAt(=createdAt+7d) 기록
• failed: 재시도 가능, attempts 증가, lastErrorCode 기록

12.6.3 재시도 정책

• 지수 백오프: 1s → 2s → 4s → 8s → 16s(최대 5회)
• 치명 오류(401/403/400 policy)는 즉시 실패 전환 + 사용자 안내
• 429/5xx/네트워크오류는 백오프 재시도

12.6.4 트리거

• 사용자 액션(‘링크로 공유’) 즉시 queued
• 앱 포그라운드 전환 시
• 백그라운드 태스크(BGTask, 아래 12.8)
• 수동 재시도 버튼(접근성 레이블 포함)

12.7 연결성 및 복구 UX (Connectivity & Recovery)

모든 버튼은 Button { } label: { } 형식, 모든 문구는 Localizable.xcstrings Key로만.

12.8 백그라운드 실행 (Background Tasks)

• BGTaskScheduler ID 권장:
• com.kindverb.share.sync (ProcessingTask: 아웃박스 동기화)
• com.kindverb.cache.purge (AppRefresh/Processing: 캐시 청소)
• 스케줄 가이드:
• 앱 진입/종료 시 등록, iOS 힌트 주기 15~60분.
• **작업 제한 시간 내(≈30초)**에서 최대 3개 Task만 처리(절전/배터리 고려).
• 실패 시 setTaskCompleted(success: false) + 다음 윈도우 요청.

12.9 저장 한도 & 정리 (Storage Limits & Purge)

• 편지 이미지 캐시: 50MB 상한 → LRU 방식으로 삭제.
• 아웃박스 큐: 100건 상한 → failed 7일 경과 항목 자동 정리.
• 로컬 데이터 내보내기/삭제: v1.1에서 “모든 데이터 초기화” 옵션 제공 예정(개인정보 보호 강화).

12.10 에러 도메인 & 매핑 (Error Domain & Mapping)

• 로깅: os_log로 메타데이터만 기록(예: taskId, status, httpCode). 본문/개인정보 금지.

12.11 접근성/현지화 (A11y & L10n) — 오프라인 맥락 특화

• 오프라인/대기열 상태는 VoiceOver로 명확히 읽히는 라벨 제공(예: “링크 공유 대기열에 저장됨”).
• 로더/스켈레톤 사용 시 진행률/상태 문구 키 필수(“업로드 중… 2/3”).
• 시간/만료 안내는 지역/캘린더/24h 설정을 따름. 예: “링크 만료: 2025-08-28 18:00”.

12.12 보안·프라이버시(오프라인 관점)

• SwiftData 파일은 iOS 데이터보호 NSFileProtectionComplete 기본 준수.
• 백업: iCloud 백업 비권장(민감 데이터). 필요 시 isExcludedFromBackup.
• Firestore 보안 규칙: letters 컬렉션 Create만 허용(읽기/수정/삭제 금지) + TTL 7일.
• 로그에 PII 금지, 에러 상세는 내부코드만.

12.13 성능 기준 (SLO) — 오프라인/캐시

12.14 텔레메트리(오프라인/동기화 관련)

실제 사용자 노출 문구는 xcstrings 키로만 표시, 텔레메트리는 내부 스키마.

12.15 수용 기준 (Acceptance Criteria)

1. 완전 오프라인에서: 성찰 입력 → 편지 작성/수정/저장까지 모든 경로 수행 가능.
2. 오프라인에서 “링크로 공유”: ShareTask(queued) 생성, UI에 대기열 안내 표출.
3. 온라인 복귀 시: 백그라운드/포그라운드/수동 재시도 중 하나 이상의 경로로 전송 시도.
4. 정책 오류(401/403/400) 시: 재시도 중지 + 사용자 안내 + 도움말 링크(내부 가이드) 노출.
5. 성공 시: URL 생성·만료일 계산(7일 후)·클립보드/공유시트 연결.
6. 캐시 상한 초과 시: LRU로 삭제되고, UI는 오류 없이 동작.
7. 모든 에러는 도메인/코드/현지화 키로 매핑되어 사용자에게 명확히 전달.

12.16 테스트 계획(샘플)

• 오프라인 시나리오: 기내모드에서 전체 핵심 루프(성찰→작성→저장) 수행.
• 대기열→성공: 기내모드에서 공유 생성→네트워크 복귀→자동 업로드 확인.
• 429/5xx: 목 서버로 응답 조작→지수 백오프 로그/상태 전이 검증.
• 정책 오류: 401/403/400→즉시 실패/안내 확인.
• 캐시 LRU: 이미지 캐시 초과→오류 없이 자동 정리 확인.
• 접근성: VoiceOver로 상태/진행률/만료 텍스트 읽기 검증.

메모 (개발 시작용 체크)

• SwiftData 모델에 ShareTask 포함
• BGTaskScheduler 등록(ID 2개)
• 네트워크 리치어빌리티 옵저버 → 아웃박스 트리거
• Firestore Create 전송 유스케이스 + 지수 백오프 공통 유틸
• 현지화 키: share.*, error.*, cache.* 세트 추가
• OSLog 카테고리 분리: .storage, .network, .sync, .cache

13.보안・개인정보보호・컴플라이언스(Security・Privacy・Compliance)

13.1 원칙 & 범위

• 데이터 최소화: 계정/로그인/식별자 수집 없음. 모든 핵심 데이터는 온디바이스(SwiftData).
• 오프라인-우선: 네트워크가 없어도 핵심 여정(성찰→편지 작성→보관) 100% 동작.
• 클라우드 1%: Firestore는 **링크 공유(Create만)**에 한정, TTL 7일 자동 삭제.
• 현대적 오류 처리: throw/try/catch 기반 도메인 에러. NSError/Completion Handler 금지.
• 로깅 가드레일: os.log만 사용, 민감 내용/본문/토큰 미기록.
• 투명성 & 제어권: 로컬 데이터 내보내기/삭제(차기 버전 포함)와 명확한 안내.

13.2 데이터 분류표 (Data Classification)

설계 원칙: 이름/이메일/광고ID 등 식별자 비수집.

13.3 데이터 흐름(요약)

1. 사용자가 성찰·편지를 작성 → SwiftData 로컬 저장
2. “링크로 공유” 선택 시 → ShareTask(아웃박스) 생성 → 온라인 시 Firestore에 Create
3. Firestore 문서 ID 기반 URL 발급 → 7일 후 자동 삭제(TTL)
4. 서버에서 읽기/수정/삭제는 불가(규칙상 차단)

13.4 보안 통제(Technical Controls)

• 전송구간 암호화: ATS 강제(HTTP 금지), TLS 1.2+.
• 저장구간 암호화: SwiftData 파일은 iOS 기본 NSFileProtectionComplete 적용. 백업 제외 필요 시 isExcludedFromBackup 플래그 사용.
• 도메인 화이트리스트: 네트워크는 Firestore 엔드포인트 및 kindverb.com만 허용(ATS 예외 금지).
• 비밀관리:
• 가드레일 상 **Secrets.plist의 "GeminiAPIKey"`**를 사용. 클라이언트 내 비밀은 노출 가능하다는 전제에서 동작(완전 보호 불가).
• 완화책: 문자열 난독화, 키 롤테이션 계획, 최소 권한 API 키, 도메인-기반 제한(가능 시), 요청량 제한, 런타임 키 검증(형식/길이).
• 로깅: os_log의 프라이버시 레드액션 사용, 본문·개인정보·API 키 절대 기록 금지.
• 권한 최소화: 사진 저장 권한(옵트인)만 요청, 마이크/연락처/위치 권한 불사용.
• 무결성 가드(선택): 탈옥 휴리스틱, 디버거/프록시 탐지 등 소프트 가드(하드 차단 아님).

13.5 개인정보 보호(Privacy)

• 설계 기본: 계정/광고 ID/크래시 시 사용자 식별 정보 수집하지 않음.
• 로컬 우선: 모든 성찰/편지는 기본적으로 기기 내에만 존재.
• 공유 시 단서고지:
• 링크 공유 선택 전 명확한 설명(7일 자동 삭제·공개 URL 특성·조회 통계 없음).
• 생성된 URL은 사생활에 취약(소유자 외 접근 가능)하므로, 사용자에게 민감정보 포함 자제 안내.
• 연령/건강 고지:
• 의료/치료 앱 아님 공지(정보성 도구).
• 아동 지향 아님(COPPA 회피). 가족 계정 사용 시 보호자 지도 권장.
• 사용자 권리:
• 온디바이스 데이터 삭제/내보내기 제공(차기: “모든 데이터 초기화”, 내보내기 파일).
• 서버(링크)는 TTL 만료 외 개별 삭제 미지원(보안 규칙 상 읽기/삭제 차단) → PRD/정책에 명시.

13.6 Firestore 보안 규칙 & TTL

• 보안 규칙(요지): letters 컬렉션 Create만 허용, Read/Update/Delete 전면 차단. content ≤ 5000자, createdAt 필수.
• TTL: createdAt + 7일 지나면 자동 영구 삭제.
• 리스크 노트: URL은 타인 공유 시 누구나 열람 가능. 앱/웹에서는 광고/추적 없음.

13.7 권한(Privacy Prompts) & 현지화 키

• 사진 저장: 최초 사용 시 설명 → privacy.photos.purpose 키.
• 알림(선택): 리마인더 사용 시 사전 교육 화면 → privacy.notifications.purpose.
• 링크 공유 경고: privacy.share.link.warning_title, privacy.share.link.warning_body.

모든 노출 문자열은 Localizable.xcstrings 키만 사용.

13.8 규정 준수 매핑(간단 가이드)

• GDPR/CCPA:
• 데이터 최소 수집, 목적 제한, 저장 제한(TTL), 투명성(프라이버시 정책) 준수.
• 식별자 미수집이므로 데이터 권리 처리 부담 최소. 온디바이스 삭제 기능 제공.
• COPPA:
• 아동 대상 아님 명시, 마케팅/스토어 페이지에 표시.
• App Store Review:
• 개인정보 라벨(Data Nutrition) → “데이터 수집 안 함”, 단 링크 공유 시 서버에 일시 보관을 “앱 기능용 데이터(사용자 입력, 링크)”로 명확히 표기.
• Health/Medical 카테고리 회피, “교육/자기개선” 톤. 치료/진단 주장 금지.

법률 자문이 필요한 경우 별도 검토. 위는 제품 설계 기준 준수 가이드.

13.9 인시던트 대응(Incident Response)

• 범위 최소화: 서버에 PII 미보관 → 리스크 표면 최소.
• 시나리오:
1. Firestore 규칙 오구성 → 즉시 규칙 롤백, 신규 쓰기 일시 중단, 공지.
2. API 키 남용 감지 → 키 회수/교체, 앱 긴급 업데이트 플래그(원격 차단이 어려우므로 키 롤테이션 준비가 핵심).
3. 악성 링크 크롤링 징후 → URL 스킴 강화(난수 길이), 로봇 차단 헤더/메타(웹).
• 연습: 분기별 플레이북 리허설(담당/연락망/체크리스트).

13.10 제3자 의존성 & 라이선스

• 프레임워크: Firebase(Firestore), Gemini SDK/HTTP.
• 관리: SPM 고정 버전, 취약점 공지 모니터링, 연 1회 OSS 감사.
• 라이선스 고지: Settings>About>Licenses 화면에 자동 생성 고지.

13.11 보안/프라이버시 수용기준(AC)

1. 식별자/추적자 비수집이 코드/설정/스토어 라벨로 일치한다.
2. 앱은 완전 오프라인에서 핵심 기능이 동작한다.
3. 링크 공유 시 사전 고지가 현지화 키로 표시되고, 사용자 동의 후에만 진행된다.
4. Firestore는 Create만 성공, Read/Update/Delete는 실패한다(규칙 테스트 통과).
5. Firestore 문서는 7일 후 자동 삭제가 검증된다(스테이징 환경 시뮬레이션).
6. os.log에 민감 본문/토큰이 기록되지 않음이 점검된다.
7. ATS 우회 없음(HTTP 금지), 허용 도메인만 접속 가능.
8. 사진 권한 프롬프트 목적 문구가 현지화되어 표시된다.
9. 프라이버시 정책(웹)과 앱 내 고지가 기능/데이터 흐름과 일치한다.
10. 키 노출 가정하더라도 남용 감지/차단/교체 플랜이 문서화되어 있다.

13.12 테스트 계획(샘플)

• 규칙 테스트: 스테이징 Firestore에 Create/Read/Update/Delete 시도 → C만 200, R/U/D 403 확인.
• TTL 테스트: TTL=10분 환경에서 만료/삭제 관찰 → 프로덕션 7일 설정과 동등성 검증.
• 로그 스캔: 시나리오 실행 후 Console.app으로 민감값 노출 탐지(정규식: 키/URL/본문 길이).
• 권한 UX: 사진 저장/알림 프롬프트가 교육 화면 뒤에 등장, 거부→재요청 경로 검증.
• 오프라인 시나리오: 링크 공유 시 ShareTask 대기열 생성 및 온라인 복귀 후 전송 검증.
• 침투 표면 점검: ATS 설정 파일 점검, 디버그 플래그/개발자 메뉴 빌드 제외 확인.

13.13 위험 & 완화

13.14 준비물 체크리스트(출시 전)

• App Privacy 라벨: “데이터 수집 안 함(링크 공유 예외 설명)” 정합성 확인
• 프라이버시 정책(웹) 최신화: 오프라인-우선, TTL 7일, 식별자 비수집 명시
• Firestore 규칙/TTL IaC 적용 + CI 테스트 통과
• os.log 민감값 레드액션 래퍼 도입, print 탐지 린팅
• 권한 프롬프트 교육 화면/현지화 키 존재 확인
• 키 롤테이션 절차 문서/담당 지정
• 라이선스 고지 화면 동작 확인

14.성능목표 & 품질기준 (Performance SLOs & Quality Bars)

14.1 핵심 성능 SLO (앱 전반)

TTI는 탭 가능 상태 진입 시점(첫 Interaction 가능한 상태)을 기준.

14.2 화면별 퍼포먼스 예산 (View Budget)

14.3 네트워크/AI SLO (클라우드 1%)

14.4 오프라인·저장소 SLO

14.5 접근성·현지화 품질 바

14.6 코드 품질 바 (CI 게이트)

14.7 실측·모니터링 설계

• 계측 원칙: os_log + Signpost로 주요 구간(Launch, View Appear, Save, LLM Call, Share Create)을 마킹.
• 수집:
• 로컬 개발: Instruments 템플릿(Launch, Time Profiler, Animation, Energy).
• 배포 후: MetricKit(크래시/행/CPU/메모리/디스크/애니메이션) + Crashlytics(최소 메타만).
• 이벤트 스키마(요약):
• perf.launch, perf.view_show{viewId}, perf.ai_draft{ms, promptType, outcome}, perf.share_create{ms, outcome}, perf.save_local{ms}
• 개인 콘텐츠/프롬프트 본문 비수집(키만).

14.8 테스트 리그 & 시나리오

• Low: iPhone SE (3세대)
• Mid: iPhone 12/13
• High: 최신 Pro 라인 1종

• 오프라인, Wi-Fi, 4G, 5G(네트워크 링크 컨디셔너: 100ms/3% 패킷드랍)

• 저널 2k, 편지 500, 감정태그 5k 조합

1. 콜드 스타트→V02→V04 입력→저장→V06 LLM 생성→편집→링크 공유(오프라인/온라인 전환)
2. 다국어 전환(영/한), Dynamic Type XXL, 다크 모드
3. 연속 세션 30분 스크롤/편집(메모리/에너지 관찰)

14.9 회귀 방지(성능 가드)

• 골든 벤치마크: 기준 빌드의 TTI/FPS/메모리 스냅샷을 CI 아티팩트로 저장.
• 자동 비교: PR마다 xcodebuild test의 Performance 측정치와 ±10% 이상 변동 시 실패.
• 대체 구현 금지 규칙:
• 메인스레드 블로킹 I/O, 동기 네트워크 호출, 대용량 이미지 동기 디코딩 금지.
• View에서 비즈니스 로직 금지(계산은 ViewModel/UseCase).
• 버튼은 Button { … } label: { … } 형식만.

14.10 에러 예산 & 완화 정책

14.11 출고 체크리스트 (Quality Bars)

• 콜드 스타트 p50 ≤ 2.0s, p95 ≤ 3.0s (SE 포함)
• 스크롤 FPS 평균 ≥ 55fps, 드롭 ≤ 1.5%
• Crash-free ≥ 99.8%, Hang ≤ 0.2%
• V06 LLM p50 ≤ 5s / p95 ≤ 9s (스켈레톤 즉시 표시)
• 링크 공유 p95 ≤ 1.2s, 오프라인 아웃박스 재전송 p95 ≤ 60s
• 메모리 피크 p95 ≤ 350MB, Energy 등급 Low
• A11y/현지화/동시성/버튼 규칙 100% 준수
• CI 성능 회귀 ≤ +10%, 경고 0, print 0, 테스트 커버리지 기준 충족

15.분석&텔레메트리 (Analytics & Telemetry) 

15.1 목적 & 가드레일

• 목적: (1) 핵심 가치 루프 완주율 상승, (2) 수익화 전환 개선, (3) 성능/안정성 회귀 조기 탐지.
• 가드레일
• 오프라인-우선: 모든 이벤트는 먼저 온디바이스에 누적·샘플링. 업로드는 사용자가 settings.privacy.share_diagnostics에 Opt-in한 경우에만 수행.
• 민감 데이터 금지: 감정/메시지 원문 텍스트, 사람/관계 실명 등 PII/민감정보 비수집. 이벤트는 키/부울/카테고리 코드만.
• 도구: 기능 이벤트는 os_log(카테고리: analytics), 성능/안정성은 MetricKit, 크래시는 Apple 경로 우선(필요시 Crashlytics 보조, 단 텍스트 최소화).
• LLM: 프롬프트/응답 원문 불가. 길이, 토큰 추정치, 프리셋 코드만 수집.

15.2 데이터 등급 & 동의

15.3 세션/사용자 식별 규칙

• 세션 정의: 포그라운드 진입부터 30분 무활동 또는 앱 종료까지.
• 익명 사용자 ID: 앱 최초 실행 시 로컬에 생성한 UUIDv4(해시). 서버 업로드 시 해시+솔트(앱 버전별 변경)로 재식별 곤란성 확보.
• 리텐션 측정용 키: install_ts, first_open_ts, last_open_ts (Epoch ms).

15.4 이벤트 택소노미 (마스터 목록)

A) 앱/세션 라이프사이클

1. app.install
2. app.first_open
3. session.start
4. session.end

B) 온보딩/관계 선택

5. onboarding.shown
6. relationship.card_view
7. relationship.select (props: type=friend|partner|parent|sibling|inlaw, locked=bool)

C) 저널(성찰 5단계)

8. journal.step_view (props: step=1..5)
9. journal.step_complete (props: step=1..5, input_type=tag|text, char_count)
10. journal.finish

D) 메시지 작업실(LLM)

11. draft.request (props: prompt_preset=initial|regenerate|softer|concise|sincere, estimated_tokens_in)
12. draft.result (props: latency_ms, success=bool, retry_count, estimated_tokens_out)
13. draft.edit_local (props: edit_chars, duration_ms)

E) 전달(공유)

14. share.copy_text
15. share.save_image (props: success=bool)
16. share.link_create (props: success=bool, latency_ms, offline_queued=bool)
17. share.link_open (웹(선택): 익명 파라미터만, 리퍼러/UA만)

F) 수익화

18. paywall.view
19. iap.purchase_attempt
20. iap.purchase_result (props: success=bool, error_code)
21. iap.restore_attempt
22. iap.restore_result (props: success=bool)

G) 성능/품질 (요약 이벤트: 14장에서 정의한 SLO와 호응)

23. perf.launch (cold/warm, tti_ms)
24. perf.view_show (view_id, tti_ms)
25. perf.ai_draft (preset, latency_ms, outcome)
26. perf.share_create (latency_ms, outcome)
27. perf.save_local (latency_ms, outcome)

H) 오류/복구

28. error.shown (props: domain, code, retriable=bool)
29. recovery.action (props: type=retry|offline_queue|open_settings)

I) 실험/플래그

30. exp.exposure (props: exp_key, variant)

중요: 어떤 이벤트에도 사용자 원문 문자열을 넣지 않는다. 감정/메시지 내용은 길이·선택코드만.

15.5 핵심 이벤트 스키마 (샘플 표)

15.5.1 relationship.select

15.5.2 journal.step_complete

15.5.3 draft.result

15.5.4 share.link_create

15.5.5 iap.purchase_result

15.6 퍼널 정의 (비즈니스 핵심)

15.6.1 핵심 가치 퍼널 (Activation)

• 지표: Activation 완료율(최초 실행 24h 내), 단계별 이탈률, 평균 소요 시간.

15.6.2 수익화 퍼널

• 분해: 유입 경로(락 카드/기능 진입/세션 시간대), 변환까지의 스텝 수, 실패 코드 분포.

15.6.3 리텐션/재참여 퍼널

• 지표: D1/D7 리텐션, 세션당 핵심 액션 수.

15.7 사용자 속성(익명) & 디바이스 속성

15.8 계측 아키텍처 & 파이프

• 클라이언트:
• AnalyticsClient → os_log 로 즉시 기록 + 온디바이스 큐(JSONL) 롤링 파일(최대 1MB × 5).
• 업로드 워커: 사용자가 Opt-in 한 경우, Wi-Fi & 충전 중 백그라운드 전송(배치/압축). 실패 시 지수 백오프.
• 서버(선택): 간단한 수신 엔드포인트(익명 토큰/버전만). 콘텐츠/PII 필드 수신 불가 스키마 검증.
• 대시보드: 사내 노트북/데스크탑에서 주기 수집 or App Store Connect(App Analytics) + 내부 노트북 리포트.

대안(서버 없이): MetricKit + App Store Connect만으로 크래시/성능을 추적하고, 기능 이벤트는 **온디바이스 집계(카운터/퍼널 완료 플래그)**로만 사용해도 됨. (완전 프라이버시 극대화 모드)

15.9 샘플링 & 보존

• 샘플링: 기본 100%. 세션 길이 30분 초과 시 행태 이벤트 50% 샘플링 전환(성능 보호). 성능/오류 이벤트는 항상 100%.
• 보존: 온디바이스 로그는 최대 7일(또는 5MB) 후 순환 삭제. 서버 업로드 시 90일 보관 후 집계값만 유지.

15.10 QA & 검증(출시 게이트)

• 스키마 린터: 이벤트/프로퍼티가 허용된 화이트리스트에 없으면 컴파일 실패(스위프트 제네릭 래퍼로 키 상수화).
• 페이크 시나리오: UI테스트에서 전체 퍼널 재현 → 각 단계 이벤트 수/순서 검증.
• 현지화 키 누락 차단: 사용자 노출 문자열은 키만 사용(분석 이벤트는 영문 코드만 사용).
• 리플레이 보호: 업로드 시 중복 방지 해시(session_id+seq_no) 포함.

15.11 대시보드(권장 차트)

• Activation 퍼널: 단계별 전환/이탈, 평균 단계 소요.
• LLM 품질판: draft.result 성공률, p50/p95 지연(프리셋별).
• 수익화: 페이월 뷰→구매 시도→성공, 실패 코드 분포.
• 성능 요약: TTI p50/p95, FPS 평균/드롭, Crash/Hang 추이(14장 SLO 연동).
• 언어/기기별 분해: locale, device_tier별 핵심지표.

15.12 거버넌스 & 버저닝

• 이벤트 키 네이밍 규칙: domain.action(소문자·점 표기). 속성은 snake_case.
• 변경 정책: 이벤트 삭제 금지(비활성만). 스키마 변경은 v2 suffixed 신규 키로 추가. 릴리스 노트에 이벤트 변경 섹션 필수.
• 권한: 스키마 변경은 PM(소유), iOS TL(리뷰), 보안 담당(승인) 3자 승인.

15.13 개인정보 고지(설정 화면 복사 문구 제안)

• 제목 키: settings.privacy.title
• 본문 요지:
• “KindVerb는 원문 글/개인정보를 수집하지 않습니다.”
• “앱 품질 개선을 위해 **익명 사용 통계(화면 이동, 버튼 클릭, 성능 지표)**를 사용자 동의 시 전송합니다.”
• 토글 키: settings.privacy.share_diagnostics (기본 Off)

15.14 (선택) 웹 링크 열람 텔레메트리

• 링크 페이지는 광고/쿠키 배너 없음.
• 수집 가능 항목: share.link_open(문서ID 해시, 생성 후 경과시간 범주, 브라우저 UA 범주).
• 수집 금지: 발신자/수신자 텍스트, IP 저장(실시간 지오 추정 없음).

15.15 PRD 연계 맵

• 3장 지표: D1/D7 리텐션, Crash-free, TTI, 구매 전환 → 모두 이벤트/MetricKit로 계산 가능.
• 14장 SLO: perf.* 이벤트 + MetricKit으로 대시보드 자동 생성.
• 17장 수익화: paywall.*, iap.*로 전환 퍼널 구성.
• 12장 오프라인 정책: offline_queued로 재시도 품질 가시화.

16.알림&인앱메시징 (Notifications & In-App Messaging)

16.1 목적 & 전략

• 목적
• (1) 사용자의 성찰 루틴(Daily Reflection)을 습관화
• (2) 완성된 메시지를 공유 행동으로 이어지게
• (3) **재참여(Retention)**와 수익화 전환을 유도
• 전략
• iOS 네이티브 로컬 알림 중심 → 알림센터 과잉 사용 금지
• 개인 맞춤형 컨텍스트: “오늘 기록한 감정을 다시 읽어볼까요?” 등
• 인앱 메시징은 페이월·기능 안내 등 맥락적 트리거에서만 사용

16.2 가드레일

• 사용자 동의 (Opt-in): 앱 최초 실행 시 알림 권한 요청은 첫 성찰 완료 후에만 노출 → 사용자가 앱 가치를 체험한 후 요청.
• 빈도 제한
• 푸시: 1일 최대 1회(주간 5회 상한)
• 인앱 메시징: 세션당 최대 1회, 중복 차단
• 현지화 필수: 모든 텍스트는 Localizable.xcstrings 키 참조
• 민감정보 금지: 알림/배너에 감정 원문 텍스트 삽입 금지 → 태그 기반 요약, 일반적 톤으로만

16.3 알림 유형 (로컬)

16.4 인앱 메시징 유형

16.5 UX 설계 원칙

• 맥락적 호출(Contextual Triggers): 단순 “앱에 돌아오세요”가 아닌 진행 중인 여정과 연결.
• A/B 테스트 가능성: 알림 문구, 시각, 인앱 배너 형식을 실험(→ 18. 실험 장과 연결).
• 취소/해제 용이성: 인앱 메시지에는 “다시 보지 않기” 버튼 제공. 알림은 설정에서 토글 가능.

16.6 동의 UX (Consent UX)

1. 앱 설치 → 온보딩 완료 → 첫 성찰 성공
2. 인앱 시트:
• 제목: consent.notif.title (“알림으로 더 꾸준히 기록해보세요”)
• 본문: consent.notif.body (“시간을 직접 설정할 수 있으며 언제든 끌 수 있어요”)
• CTA 버튼: consent.notif.allow (→ iOS 시스템 권한 요청 호출)
• Secondary CTA: consent.notif.later

16.7 기술 구현 (iOS)

• 프레임워크: UserNotifications (로컬 알림), SwiftUI 뷰 + MVVM
• 스케줄링:
• Daily Reflection: UNCalendarNotificationTrigger
• Draft Follow-up: UNTimeIntervalNotificationTrigger
• 오프라인 우선: 네트워크 필요 없음 (단, 업그레이드 안내 알림은 앱 내 로직으로만 제어)
• 인앱 메시징:
• OverlayManager (MVVM Store) → 특정 이벤트 발생 시 ViewModifier로 배너/모달 삽입
• “다시 보지 않기” 상태는 SwiftData에 저장

16.8 텔레메트리 & 측정 (15장 연계)

• 이벤트 로깅:
• notif.permission.requested / notif.permission.granted
• notif.scheduled (props: type, ts)
• notif.tapped (props: type, delivered_ts, latency)
• inapp.shown (props: type, screen_id)
• inapp.cta_clicked (props: type, action=upgrade|dismiss|later)
• 지표
• 권한 허용률(Granted/Requested)
• 알림 클릭률(Tap/Delivered)
• 알림 → 세션 시작 전환율
• 인앱 메시지 CTA 클릭률

16.9 빈도 & 지능형 제어

• 빈도 제어 엔진
• 로컬 DB에 “알림/인앱 메시지 최근 노출 기록” 저장
• 24시간 내 같은 유형 중복 금지
• 지능형 추천(후속 버전)
• 사용자의 성찰/공유 패턴에 따라 알림 시각 조정
• 예: 자주 기록하는 시각에 맞춤 푸시

16.10 개인정보 보호 고려사항

• 알림/인앱 메시지 내용은 일반적 톤으로만 (예: “당신의 기록” → O, “오늘 화났다고 쓴 글 다시 읽어보세요” → X)
• 알림 전달 여부 자체는 개인 식별 불가 이벤트(notif.scheduled/notif.tapped)로만 기록
• 사용자 거부/설정 변경은 즉시 반영 (다음 알림부터 중단)

16.11 향후 확장 (Roadmap)

• WidgetKit: 홈 화면 위젯으로 성찰 리마인더 확장
• Live Activity: Draft 생성 중 실시간 진행률 표시
• Cross-platform (Optional): 현재는 iOS 전용. 향후 macOS 버전 고려 가능

17.수익화&가격정책 (Monetization & Pricing)

17.1 수익 철학 & 전략 요약

• 가치 증명형 Freemium: 첫 세션에서 “와, 이거 된다”를 느끼게 한 뒤, 고통-해결의 확신이 생긴 시점에 자연스럽게 결제.
• 광고 없음: 신뢰·몰입 최우선. 사용자의 감정 데이터를 상품화하지 않음.
• 오프라인 우선: 핵심 가치는 온디바이스. 결제 권한만 StoreKit 2로 관리.
• 단일 핵심 SKU(평생권) + 선택적 확장 SKU(콘텐츠 팩): 헷갈리지 않게 단순화하되, 고가치 유저에게는 추가 업셀 포인트 제공.

17.2 오퍼 구조 (Offer Structure)

17.2.1 무료(Free)

• 사용할 수 있는 것:
• 관계 유형 1개(친구 또는 동료) 코어 여정 전체
• AI 편지 초안 10회/1일(0시 부터 24시 까지) 
• 기본 알림 1종(성찰 리마인더)
• 잠금(🔒) 표시: 배우자 또는 연인, 부모 또는 자녀, 형제 또는 자매, 시댁 또는 처가 4개 관계 카드, 전문가 라이브러리, 고급 노트

17.2.2 Pro (Lifetime – 1회성 결제)

• 가격(권장 KRW): ₩12,900 (T1) (가격 실험은 17.5)
• 잠금 해제:
• 모든 관계 유형 (총 5종)
• 전문가 라이브러리(칼럼/가이드)
• 마음 노트 고급 기능(감정 태그 통계, 감사 리마인더 커스텀 시간 등)
• 링크 공유 고급 옵션(만료일 커스텀: 3/7/30일)

17.2.3 선택적 확장 SKU(옵션, v1.1+)

• 시즌 팩(명절/기념일 대화 팩): 비소모성 IAP, 2~3천원대
• 전문가 템플릿 팩: 가족·육아·부부에 특화된 템플릿 모음

출시 4~8주 뒤 ARPPU 상승을 위한 2차 업셀 포인트로 오픈

17.3 Paywall UX 설계 (윤리·전환 최적화)

• 노출 타이밍(권장 시나리오 3단계)
1. 코어 가치 체험 직후: 첫 편지 초안이 화면에 나타난 순간 → 상단에 “Pro에서 모든 관계 열기” 미니 배너(비침습)
2. 잠금 기능 진입 시: Pro 관계 카드 탭 → 풀스크린 Paywall
3. 두 번째 성공 경험 후: 2번째 편지 공유 완료 직후, 축하 모달 → Pro 혜택 제안
• 페이월 핵심 요소
• 사회적 증거(키 메시지): paywall.hero.title, paywall.hero.subtitle
• 혜택 리스트(3~5개): 체크아이콘 + 한 줄 가치 키 paywall.benefit.*
• 가격/정책: “1회 결제, 평생 이용”, paywall.price_note.lifetime
• 행동 버튼(권장 2개): 구매, 나중에
• 보조링크: 구매 복원
• 다크패턴 금지: 타이머·가짜 할인가·과장 표현 금지

• paywall.hero.title, paywall.benefit.all_relations, paywall.benefit.library, paywall.benefit.advanced_notes, paywall.cta.buy, paywall.cta.later, paywall.cta.restore, paywall.price_note.lifetime

17.4 상품 정책 (App Store 가이드 준수)

• 비소모성 IAP (Lifetime) + Family Sharing 지원(선택)
• Refund: Apple 정책 고지(인앱 어뷰징 방지 문구는 비노출)
• 구매 복원: Settings → settings.restore_purchases
• 구매 전 대가리뷰 유도 금지

17.5 가격 정책 & 실험 (Tiering & Tests)

• 초기 권장가: ₩12,900 (한국) / $9.99 (글로벌 레퍼런스)
• 앵커링 카드(페이월): “평생 이용(1회 결제) vs 매달 고민 Zero”
• 가격 밴드 실험(AB)
• KR: 9,900 / 12,900 / 15,000
• US: 7.99 / 9.99 / 12.99
• 콘텐츠 팩: 1,900 / 2,900 / 3,900
• 프로모션
• 런치 14일 내 첫 세션 후 24h 한정 -10% (StoreKit Offer Code / Intro Offer 대체 불가 시 메시지로만 안내)
• 비활성 30일 복귀 유저 대상 재방문 쿠폰 코드(웹/이벤트 카드 연계)

측정 지표: Paywall 뷰율 → 결제 클릭률 → 결제 성공률 → 환불률, ARPPU, LTV, 지역별 전환

17.6 기능 게이팅 매트릭스 (Free vs Pro)

17.7 StoreKit 2 권한·영수증(온디바이스) 설계

• 비소모성 kindverb.pro.lifetime
• 온디바이스 자격(Entitlement):
• 최초 구매 성공 → Transaction 검증 → Pro 플래그 SwiftData 저장
• 앱 시작 시 Transaction.currentEntitlements / Transaction.updates로 재확인
• 오프라인에서도 Pro 동작(마지막 유효한 서명 캐시)
• 오류·에지 케이스
• 네트워크 단절: 결제 플로우 재시도 유도, 중복 결제 방지
• 가족공유: 동일 Apple ID 패밀리 → 최신 엔타이틀먼트 동기화
• 환불: Transaction.revocationDate 감지 시 Pro 플래그 즉시 해제, 부드러운 안내

• iap.status.purchasing, iap.status.purchased, iap.status.failed, iap.status.restored

17.8 업셀 트리거 & 윤리 가드레일

• 권장 트리거
• Pro 관계 카드 탭
• 2회 이상 성공적 편지 공유 후
• 전문가 라이브러리 3개 이상 열람 시
• 차단 조건
• 24h 내 2회 이상 Paywall 금지
• 알림/인앱 메시지 중복 노출 방지

17.9 텔레메트리 이벤트 & KPI (15장 연계)

• paywall.viewed (props: source=card|share_success|library_lock, country, price_tier)
• iap.purchase_tap (props: product_id)
• iap.purchase_result (props: product_id, result=success|fail|cancel, duration_ms, reason_if_fail)
• entitlement.changed (props: to=pro|free, cause=purchase|restore|revoke)
• content_pack.purchase_result
• share.completed → 업셀 경로 분석용

• Paywall → 결제 성공 전환율
• MAU 대비 Pro 비율(유료 침투)
• ARPPU / ARPDAU / LTV(60일)
• 환불률(주/월)
• Pro 사용자 30·90일 리텐션

17.10 App Store 메타 & 외부 성장

• 스토어 스크린샷: “1회 결제, 평생 이용” 명확 표기(지역별 현지화)
• 인앱 이벤트 카드: “사과 편지 주간”, “명절 대화 팩 출시”
• 추천 키워드: 관계 회복, 사과 편지, NVC, 연인/가족 대화

17.11 수익 예측(샘플 모델 – 내부 참고)

• 가정: 월 신규 10K 설치, Paywall 노출 60%, 전환 3.5%, 가격 ₩12,900
• 월 결제건 ≈ 10,000 × 0.60 × 0.035 = 210건
• 매출(총) ≈ 210 × 12,900 = ₩2,709,000
• Apple 수수료(가정 15%) 차감 후 순매출 ≈ ₩2.30M

실제는 지역·세율·환율에 영향 → AB 테스트로 전환 최적화 + 스토어 추천 노출로 탄력 확장

17.12 리스크 & 완화

• 가격 민감도: 초기 반응 저조 시 9,900 테스트 롤백 경로 사전 정의
• 환불 증가: 페이월 설명 명확화, 기대치 관리(기능 비교표 노출)
• 복제 앱 출현: 브랜드/도메인(KindVerb) 자산 강화, 고유 라이브러리 업데이트 주기 유지
• 어뷰징: 환불 후 사용 방지(엔타이틀먼트 즉시 해제 로직), 링크 공유는 TTL로 노출 최소화

17.13 수용 기준 (Acceptance Criteria)

• v1.0: kindverb.pro.lifetime 비소모성 IAP로 결제·복원 100% 동작
• Paywall 3 트리거 소스 구현: 관계 카드, 공유 완료, 라이브러리 잠금
• Family Sharing 설정 시 동작 확인(선택)
• 결제 실패/취소/환불 경로 UX 제공(현지화 키 사용)
• 텔레메트리 이벤트(§17.9) 100% 발화 및 스키마 검증
• 알림·인앱 빈도 제한 로직 동작(§16 연계)

17.14 현지화 키 패키지(요약)

• Paywall: paywall.*
• paywall.hero.title, paywall.hero.subtitle, paywall.benefit.*(5개 내), paywall.cta.buy, paywall.cta.later, paywall.cta.restore, paywall.price_note.lifetime
• IAP 상태: iap.status.*
• 업셀: upsell.share_success.title, upsell.library_lock.title

17.15 로드맵(수익 확장)

• D+30~60: 시즌 팩(명절/기념일) 출시 → 콘텐츠 IAP 첫 실험
• D+90: Pro 사용자 전용 “깊이 학습 코스” 파일럿(향후 구독화 검토)
• 파트너십: 가족상담/부부 교육기관 B2B ‘대량 코드’ 판매(외부 영업 채널)

Feature: Pro Lifetime Purchase
  Scenario: User unlocks all relations via lifetime purchase
    Given the user taps a Pro-locked relation card
    When the paywall is shown and the user confirms purchase of "kindverb.pro.lifetime"
    Then the purchase succeeds and entitlement becomes "pro"
    And the locked relations become accessible immediately
    And an "entitlement.changed" event is logged with to=pro

  Scenario: Restore purchases on new device
    Given the user installs the app on a new device
    When the user taps "Restore Purchases"
    Then the app verifies transactions and sets entitlement to "pro" if found
    And a success toast appears

실행 메모 (iOS 기술 가드레일 재확인)

• StoreKit 2 + Swift Concurrency(async/await)
• 현대적 Error (throw/try/catch), NSError/CompletionHandler 금지
• SwiftUI 버튼 형식 강제: Button { } label: { }
• 모든 텍스트 키 참조: Localizable.xcstrings
• 오프라인 우선: 엔타이틀먼트 캐시+서명 검증, 서버 불필요

18.실험(Experimentation - A/B, Feature Flags) 

18.1 목적 & 원칙

• 목적: 핵심 루프(성찰 → AI 초안 → 전달)의 전환 효율을 검증·최적화하여 **Pro 전환·리텐션·바이럴(공유)**을 체계적으로 개선.
• 원칙
• 오프라인 우선: 원격 설정/원격 실험 도구 미사용. 모든 실험 배정·기록은 온디바이스(SwiftData + os.log).
• 윤리 우선: 다크 패턴 금지(페이월 강제·가짜 타이머·허위 한정 세일 금지).
• 재현성: 결정적 해시 기반 코호트 배정(동일 디바이스는 항상 동일 변형).
• 단순성: 한 번에 적은 변수(1~2개)만 바꾸고, 명확한 1차 지표와 안전 가드레일 지표를 함께 본다.
• 지역/버전 안정화: 실험은 앱 버전·리전·언어를 명시적으로 타기팅.

18.2 실험 타입

1. 오프라인 A/B / A/B/n (기본): 디바이스 단위 무작위 배정, 결과는 온디바이스 집계 → TestFlight/내부 QA용 내보내기(수기 분석) + App Store Connect 지표와 교차 확인.
2. 점진적 롤아웃(퍼센트 플래그): 신규 UX의 안정성 검증(5% → 25% → 100%).
3. 시퀀셜 테스트(내부용): 기간을 분리해 전후 비교(데이터 적을 때 유용).

※ 서버 없는 구조이므로 글로벌 자동 밴딧은 사용하지 않음(디바이스 로컬 밴딧은 제품 전체 최적화에 불리).

18.3 코호트 배정(온디바이스, 결정적 해시)

• Seed: identifierForVendor(UUID) + experiment_id + app_version.
• Hash → Bucket: 0–99 버킷.
• 할당 규칙: 예) A=0–49, B=50–99 (50:50).
• 지속성: 배정 결과는 SwiftData에 저장(앱 재설치 전까지 유지).
• 타기팅: 언어/지역/앱버전/Pro 여부 필터.

PRD 키: exp.id, exp.name, exp.variant_keys = ["A","B","C"], exp.target = { region:"KR", lang:"ko|en", appVersion: ">=1.0.0" }, exp.rollout: 0..100.

18.4 기능 플래그(Feature Flags) 스키마

• 정의 위치: 번들 내 Resources/Experiments.json (정적), v1.x는 앱 업데이트로 변경.
• 런타임 오브젝트 예
• flag.paywall.copy.variant ∈ {A_plain, B_empathy}
• flag.ai.tone.variant ∈ {calm, concise, warm}
• flag.share.order ∈ {text_first, image_first}
• 가드레일: 플래그 평가 실패 시 안전 기본값 사용. 크래시/에러 3회↑ 세션에서 자동 Off.

18.5 우선 실험 목록(가설·변형·지표)

E-01 페이월 카피 톤

• 가설: 공감형 카피가 일반형 대비 결제 전환↑.
• 변형:
• A 일반형: paywall.hero.title=A1.title, subtitle=A1.subtitle
• B 공감형: paywall.hero.title=B1.title, subtitle=B1.subtitle
• 대상: KR, 앱 v1.0+, Free 유저.
• 1차 지표: iap.purchase_result=success / paywall.viewed (전환율).
• 가드레일: paywall.dismiss_rate, session.exit_after_paywall 증가 금지.

E-02 페이월 노출 타이밍

• 가설: “첫 편지 초안 표시 직후 미니 배너”가 잠금 화면 직행 대비 반감 없이 거부감↓.
• 변형:
• A: Pro 잠금 탭 시 풀스크린
• B: 초안 표시 직후 미니 배너 → 자발적 진입
• 1차 지표: iap.purchase_result 전환, 보조: paywall.viewed/세션, D1 리텐션.

E-03 가격 밴드 (KR)

• 가설: ₩12,900이 ₩9,900·₩15,000 대비 매출/전환 균형 최적.
• 변형: 9,900 / 12,900 / 15,000 (각 33%).
• 1차 지표: ARPPU, 전환율, 환불률.

E-04 AI 초안 톤

• 가설: warm 톤이 공유 완료율↑.
• 변형: calm vs concise vs warm (초안 내부 문체만 다름).
• 1차 지표: share.completed / message_drafted.
• 가드레일: 편지 길이 과도 증가로 TTI↑ 금지.

E-05 공유 버튼 순서

• 가설: image_first가 저장/재열람 증가로 관계 개선 체감↑.
• 변형: text_first vs image_first.
• 1차 지표: share.image_saved, 보조: 재방문률(D7).

E-06 감정 선택 UI 레이아웃

• 가설: 그리드+검색이 스크롤 리스트 대비 선택 완료 시간↓, 이탈↓.
• 변형: list vs grid_search.
• 1차 지표: journal.step2.time_to_complete, step2.abandon_rate.

모든 실험은 동시에 최대 2개만 노출(간섭 최소화).

18.6 측정 & 분석(§15 이벤트 매핑)

• 필수 이벤트(요약):
• experiment.assigned(id, variant, seed)
• paywall.viewed / iap.purchase_result / entitlement.changed
• message.drafted / share.completed / share.image_saved
• journal.step2.completed / journal.step2.abandoned
• 세션/유저 식별: 온디바이스 임의키(PII 없음).
• 집계: SwiftData에 일/주 단위 롤업 스냅샷.
• 내보내기: 설정>개발자 메뉴에서 CSV 내보내기(테스트/리뷰용).
• 외부 벤치마크: App Store Connect 전환/리텐션과 교차확인.

18.7 윤리·컴플라이언스 가드레일

• 금지: 가짜 희소성·타이머·숨은 가격.
• 표시: 가격·평생권·복원 경로 명확 표기(§17 키 사용).
• 개인정보: 실험 배정·로그에 PII 저장 금지, 네트워크 전송 없음.
• 접근성: 각 변형 모두 A11y 준수(폰트/대비/VO 레이블).

18.8 운영 절차(End-to-End)

1. 설계: 가설-지표-기간-표본 크기 정의(최소 7일, 주말 포함).
2. 구현: Experiments.json 정의→플래그/배정 로직 연결→키 텍스트 추가(Localizable.xcstrings).
3. QA: 디버그 화면에서 강제 배정/변형 미리보기, 로깅 확인.
4. 롤아웃: 5% 퍼센트 플래그로 크래시/에러 모니터→25%→100%.
5. 판정: 전환(주지표) + 가드레일 지표 동시 충족 시 승자 승격.
6. 정리: 승자 변형을 기본값으로 고정, 실패 실험 플래그 제거.

18.9 수용 기준(AC)

• Experiments.json 스키마/유효성 검사 통과(없는 키 참조 시 앱이 기본값으로 안전 복귀).
• 코호트 배정이 결정적이며 앱 재실행/재부팅 후에도 변하지 않음.
• 디버그 메뉴에서 실험 강제 배정/해제 가능(내부 테스트용).
• §15 이벤트가 실험 속성(experiment_id, variant)을 포함해 100% 발화.
• 접근성·현지화 키 누락 없음(A/B 모든 화면).
• 퍼센트 플래그(5→25→100) 시 크래시/에러 증가 없음.

18.10 현지화 키(예시)

• exp.paywall.copy.A1.title, exp.paywall.copy.A1.subtitle
• exp.paywall.copy.B1.title, exp.paywall.copy.B1.subtitle
• exp.ai.tone.calm.label, exp.ai.tone.concise.label, exp.ai.tone.warm.label
• exp.share.order.text_first, exp.share.order.image_first

18.11 Gherkin 시나리오(샘플)

Feature: On-device AB assignment
  Scenario: Deterministic cohort on same device
    Given a device with identifierForVendor = X
    And experiment "exp_paywall_tone_v1" is active with split A:50 B:50
    When the user starts the app
    Then the app assigns a variant deterministically for this device
    And the same variant is used across sessions

Feature: Paywall timing experiment
  Scenario: Mini banner vs full screen
    Given the user is Free and completes AI draft
    When experiment "exp_paywall_timing_v1" assigns variant B
    Then a mini banner is shown instead of immediate full-screen paywall
    And analytics "paywall.viewed" includes experiment metadata

18.12 리스크 & 완화

• 표본 부족: 기간 연장 또는 시퀀셜 테스트로 전환.
• 변형 교차 간섭: 동일 세그먼트에 동시 노출 2개 이하로 제한.
• 현지화 누락: 실험용 문구도 반드시 키 사용(런타임 검증).
• 버전 파편화: 실험은 최신 버전 한정으로 운영.

19.수용기준&테스트계획 (Acceptance Criteria & Test Plan + Converage Mapping)

• 명확한 품질 기준: 기능이 "완료"되었음을 판단하는 측정 가능한 조건 정의.
• 테스트 구조화: 기능별 테스트 케이스와 커버리지 매핑을 통해 QA가 누락 없이 점검.
• 자동화 기반: 가능한 범위는 XCTest + async/await으로 자동화, 나머지는 QA 매뉴얼 체크리스트.

• 앱은 SwiftUI + MVVM + Swift Concurrency(async/await) 원칙으로 작성되어야 한다.
• 모든 사용자 노출 텍스트는 Localizable.xcstrings 키를 통해 참조된다.
• 모든 네트워크/AI 호출은 try/throw/catch 기반의 현대적 에러 처리를 따른다.
• print() 사용 금지, 로그는 os.log를 통해 기록된다.
• 오프라인 모드에서도 핵심 루프(성찰 기록 → AI 초안 → 저장)는 완전하게 동작한다.
• Firestore 연동은 링크 공유 시, TTL 7일 한정으로 동작한다.
• Gemini API 호출은 Secrets.plist의 GeminiAPIKey를 통해 안전하게 인증된다.

기능별 AC (예시)

저널링(성찰 기록)

• 사용자는 감정·상황·상처·자기성찰·욕구 단계를 순서대로 기록할 수 있다.
• 각 단계는 건너뛰기 불가, 진행률 표시 UI가 작동한다.
• 데이터는 SwiftData에 영구 저장되며, 앱 재실행 후에도 유지된다.

AI 초안 생성

• 사용자가 성찰 완료 후 "AI 초안 받기"를 선택하면 Gemini 2.5 Flash Lite API가 호출된다.
• AI 응답은 비식별화된 텍스트 기반으로 수신·저장된다.
• 응답 실패 시, 앱은 error.ai.* 현지화 키를 사용해 오류 메시지를 노출한다.

공유 & 페이월

• Free 유저는 작성 초안을 읽을 수 있지만 공유 시 Pro 페이월을 만난다.
• Pro 구독 성공 시 즉시 entitlement=pro 로 상태가 변경된다.
• 공유 링크는 Firestore에 저장되며 7일 후 자동 만료된다.

알림 & 인앱 메시징

• 사용자는 성찰 리마인더를 하루 1회 이상 받을 수 있다.
• 알림은 로컬 푸시 기반으로 작동하며 오프라인에서도 예약된다.
• 인앱 배너는 Experiments.json 플래그에 따라 변형이 다르게 나타난다.

19.3 테스트계획 (Test Plan)

1) 단위 테스트 (XCTest)

• 대상: ViewModel 로직, 데이터 모델 직렬화/역직렬화, AI 응답 파서, 에러 매핑.
• 도구: XCTest, XCTExpect (async/await 지원).
• 커버리지 목표: 핵심 비즈니스 로직(감정 → 초안 → 공유) 90% 이상.

2) UI 테스트 (XCUITest)

• 대상: 성찰 플로우, 페이월 전환, 공유 플로우, 알림 수신.
• 도구: XCUITest 스냅샷 비교, 접근성 라벨 확인.
• 커버리지 목표: 주요 사용자 시나리오(Gherkin 기반) 100%.

3) 수동 테스트 (QA)

• 대상: 다국어 현지화, 접근성(VoiceOver/다크모드), 네트워크 끊김 시나리오, iAP 결제.
• 체크리스트: PRD 각 섹션의 Acceptance Criteria와 매핑된 항목.

4) 실험 검증

• 대상: Experiments.json 플래그 배정 로직, 이벤트 로깅.
• 테스트 방법: 디버그 모드에서 강제 배정 → 이벤트 정상 발화 확인.

19.4 커버리지 매핑 (Coverage Mapping)

19.5 Definition of Done (DoD)

• 모든 Acceptance Criteria 체크박스가 통과해야만 기능은 완료.
• 모든 신규 기능은 단위 테스트 & UI 테스트가 포함되어야만 머지 가능.
• 테스트 실패 시 CI 파이프라인이 빌드 차단.
• QA 승인 + PO 리뷰 이후에만 출시 가능.

20.위험・가정・의존성 (Risks・Assumptions・Dependencies) 

20.1 목적 & 범위

• 목적: 출시/운영에 치명적 영향을 줄 수 있는 리스크를 사전에 규정·감시·완화하여 일정·품질·수익을 안정화.
• 범위: 제품/기술/보안·컴플라이언스/운영/시장·수익 리스크 전 영역 + 가정(검증 필요 사실) + 외부·내부 의존성.

20.2 리스크 분류 & 점수 체계