연속 출석 보너스

1. 목적 및 배경왜 만드는가

문제

• 럭키박스는 무료박스 1일 1회가 유일한 데일리 훅이다. 그런데 "오늘 안 하면 손해"라는 장치가 없어 하루 건너뛰어도 유저가 잃는 게 없다.
• 무료박스 평균 지급은 20팡(운영 실데이터, 174회 / 3,480팡). 1,000팡 = 유료박스 1개이므로 순수 무료 이용만으로는 50일이 걸린다. 체감 진척이 너무 느려 이탈 지점이 된다.
• 매체사 앱에서 유입되는 구조상 재방문 동기 = 팡 적립 속도다. 적립 속도에 가속 장치가 없으면 1회성 체험으로 끝난다.

해결

앱 접속만으로 자동 출석이 기록되고, 연속 출석일이 길수록 그날 무료박스의 팡 지급액에 보너스(+10 / +15 / +20%)가 붙는다. 하루라도 빠지면 리셋 → "연속을 끊고 싶지 않다"는 손실회피 심리로 습관을 만든다.

왜 이 방식이 안전한가

성공 지표 (KPI)

2. 핵심 규칙확정 정책

2.1 출석의 정의 — 앱 접속 자동 출석

• 럭키박스 웹뷰 진입 시 그날(KST) 자동으로 출석 기록. 출석 버튼 없음.
• 하루 1회만 기록(멱등). 같은 날 재접속은 no-op.
• 날짜 경계는 무료박스와 동일한 KST 자정 기준. 별도 기준을 만들지 않는다.
• 회원만 대상. 배너 유입 비회원(쿠키 세션)은 출석 미기록 → 로그인 유도 소재로 활용 (5장 참조).

2.2 보너스 tier

• 7일 이후에도 리셋 없이 +20% 유지. 8일차, 30일차 모두 +20%. 사이클 초기화하지 않는다 → "쌓아온 게 아깝다"는 심리를 계속 유지.
• 적용 대상은 무료박스 팡 지급액에만. 유료박스 당첨 상품, 룰렛, 환급 팡(300팡)에는 미적용.

2.3 리셋 규칙

• KST 기준 하루라도 미접속이면 연속 끊김 → 다음 접속일에 1일차로 재시작.
• 예: 월·화·수 출석(3일차, +10%) → 목 미접속 → 금 접속 = 1일차, +0%
• 최고 기록(best_streak)은 리셋되지 않고 별도 보존 (향후 뱃지/랭킹용).

2.4 적용 시점

무료박스를 플레이하는 그 시점의 연속 출석일로 tier를 결정한다. 앱 진입 시 자동 출석이 먼저 기록되므로 박스 플레이 시점에는 이미 "오늘 출석" 확정 상태다.

3. 팡 지급 계산식 변경기존 로직에 어떻게 얹히는가

3.1 기존 (AS-IS)

// 무료박스 팡 = 당첨 상품 판매가 × 레벨별 계수
divisor = 200 - (level - 1) * 10   // Lv1:200 … Lv10:110
pang    = floor(product_price / divisor)

3.2 변경 (TO-BE)

divisor    = 200 - (level - 1) * 10
basePang   = floor(product_price / divisor)          // 기존과 동일
bonusRate  = attendanceService.currentBonus(userId)  // 0 / 0.10 / 0.15 / 0.20
bonusPang  = floor(basePang * bonusRate)             // 가산분 (별도 산출)
totalPang  = basePang + bonusPang

3.3 예시 (평균 당첨가 3,000원 가정)

3.4 팡 유형 및 유효기간

• 보너스 팡은 이벤트 팡으로 적립 → 유효기간 30일, 사용 시 이벤트 팡 우선 차감.
• 기본 팡의 기존 유형 정책은 변경하지 않는다.
• 팡 원장에는 기본분과 보너스분을 별도 트랜잭션으로 2건 기록한다 → 정산·통계에서 보너스 비용을 독립 집계 가능.
  reason: FREE_BOX_REWARD / reason: ATTENDANCE_BONUS

4. 비용 영향 시뮬레이션얼마나 드는가

4.1 전제

4.2 연속일 분포 가정과 가중평균 보너스율

4.3 결과

4.4 상한 방어

• 보너스율 상한 +20% 하드캡 — 정책값이 잘못 입력돼도 코드에서 min(rate, 0.20) 로 이중 방어.
• 1회 보너스 팡 절대 상한 100팡 — 고가 상품 당첨(150만원 × Lv10 = 13,636팡) 시 보너스만 2,727팡이 나가는 것을 차단. 확정 필요

5. UI 설계 — 배치 맵어느 화면 어디에 넣는가

화면 흐름

6. UI 설계 — 화면별 시안디자인팀 전달용 · 실제 앱 스타일 기준

6.7 규칙 안내 바텀시트 (위젯 탭 시)

하단 안내 문구(카피 확정안):

7. 디자인 스펙컬러 · 타이포 · 모션 토큰

7.1 컬러

7.2 타이포

7.3 컴포넌트 규격

• 위젯 카드: radius 14px, padding 13px, border 2px orange(활성) / 1px #E5E7EB(비활성), 외곽 glow 0 0 0 4px rgba(255,122,0,.10)
• 도트: 높이 30px, radius 8px, 7개 균등 flex, gap 5px
• 오늘 도트: 2px dashed orange + 흰 배경 → "아직 진행 중"을 시각적으로 구분
• 토스트: radius 12px, bg rgba(27,36,64,.95), 좌우 12px 마진, bottom nav 상단 12px

7.4 모션

7.5 디자인 산출물 요청 목록 디자인

• 홈 위젯 — 4개 상태 (1일차 / 3일차 / 7일 초과 / 비회원 잠금)
• 토스트 — 2종 (일반 / tier 승급)
• 무료박스 결과 팡 표기 영역 — 2종 (보너스 있음 / 없음)
• 진입 모달 배지 — 2종 (보너스 있음 / 0%)
• 내 정보 요약 행 — 1종
• 규칙 안내 바텀시트 — 1종
• 7일 초과 상태의 트래커 대체 표현 (완주 배지 + 연속일 카운터)

8. 데이터 모델 DB신규 마이그레이션 2 테이블 + 정책 시드

8.1 attendance_logs — 출석 원장 (append-only)

8.2 user_attendance_streaks — 연속 상태 캐시 (1인 1행)

8.3 정책값 — reward_policies 시드

key   : "attendance_bonus"
value : {
  "enabled": true,
  "tiers": [
    { "days": 2, "rate": 0.10 },
    { "days": 4, "rate": 0.15 },
    { "days": 7, "rate": 0.20 }
  ],
  "maxRate": 0.20,        // 하드캡
  "maxBonusPang": 100,    // 1회 보너스 팡 절대 상한
  "pangType": "EVENT",   // 이벤트 팡 (30일)
  "applyTo": ["FREE_BOX"]
}

8.4 팡 원장 확장

기존 팡 트랜잭션 테이블에 사유 코드 ATTENDANCE_BONUS 추가. 무료박스 1회당 최대 2건 기록:

9. API 명세 BE

9.1 POST /api/attendance/checkin — 자동 출석

인증 필요 · 멱등 · 클라이언트 앱 마운트 시 1회 호출

Response 200

{
  "isNew": true,            // 오늘 최초 기록이면 true (토스트 노출 조건)
  "isTierUp": false,        // 오늘 tier가 올라갔으면 true (강조 토스트)
  "currentStreak": 3,
  "bestStreak": 9,
  "bonusRate": 0.10,
  "bonusPercent": 10,       // UI 표기 편의
  "nextTier": { "days": 4, "rate": 0.15, "remainDays": 1 },
  "last7": [true,true,true,false,false,false,false],
  "todayAttended": true,
  "kstDate": "2026-08-07"
}

nextTier가 null이면 최고 tier 도달(7일+) 상태.

9.2 GET /api/attendance/status — 위젯 조회

응답 스키마는 9.1과 동일(isNew, isTierUp 제외). 홈 위젯·내 정보 렌더용. 쓰기 없음.

9.3 무료박스 응답 확장 — POST /api/freebox/open

{
  "product": { ... },
  "pang": {
    "base": 15,
    "bonus": 1,
    "total": 16,
    "bonusRate": 0.10,
    "streakDay": 3,
    "nextTier": { "days": 4, "rate": 0.15, "remainDays": 1 }
  },
  "level": 1,
  "exp": 140
}

9.4 에러 정책

10. 서버 로직 BE

10.1 체크인 (유저 단위 락 필수)

checkin(userId):
  lock("attendance:" + userId)          // advisory lock — 동시 진입 중복 방지
  today = kstToday()
  s     = streakRepo.findOrCreate(userId)
  prevRate = rateOf(s.current_streak)

  if s.last_attend_kst == today:
      return { isNew:false, ...snapshot(s) }

  if s.last_attend_kst == today.minus(1 day):
      s.current_streak += 1                // 연속 이어짐
  else:
      s.current_streak = 1                 // 최초 또는 공백 → 리셋

  s.last_attend_kst   = today
  s.best_streak       = max(s.best_streak, s.current_streak)
  s.total_attend_days += 1
  streakRepo.save(s)

  newRate = rateOf(s.current_streak)
  logRepo.upsertIgnoreConflict(userId, today, s.current_streak, newRate, "APP_ENTER")

  return { isNew:true, isTierUp: newRate > prevRate, ...snapshot(s) }

10.2 보너스율 계산

rateOf(streak):
  p = policy("attendance_bonus")
  if !p.enabled: return 0
  r = max(t.rate for t in p.tiers if t.days <= streak, default=0)
  return min(r, p.maxRate)               // 하드캡 이중 방어

currentBonus(userId):
  s = streakRepo.find(userId)
  // 오늘 출석이 확정된 경우에만 보너스 인정
  if s == null or s.last_attend_kst != kstToday(): return 0
  return rateOf(s.current_streak)

10.3 무료박스 지급부 수정

freeBoxService.open(userId):
  // ── 방어: 출석 누락 시 그 자리에서 보정 ──
  if streakRepo.find(userId)?.last_attend_kst != kstToday():
      attendanceService.checkin(userId, source="FREE_BOX_FALLBACK")

  winner   = drawFromPreset("DEFAULT")        // 무료박스는 항상 기본 프리셋
  divisor  = 200 - (user.level - 1) * 10
  basePang = floor(winner.price / divisor)

  rate      = attendanceService.currentBonus(userId)
  bonusPang = min(floor(basePang * rate), policy.maxBonusPang)

  tx:
     pangRepo.grant(userId, basePang,  "FREE_BOX_REWARD",   type=<기존정책>)
     if bonusPang > 0:
        pangRepo.grant(userId, bonusPang, "ATTENDANCE_BONUS", type="EVENT", expire=+30d)
     expRepo.add(userId, 10)                     // 무료박스 경험치 (기존)

  return { base:basePang, bonus:bonusPang, total:basePang+bonusPang, rate, streakDay }

10.4 KST 날짜 유틸

11. 관리자 페이지 BE FE

11.1 정책 관리 (신규 메뉴: 이벤트 관리 > 출석 보너스)

• 기능 ON/OFF 토글 (킬스위치)
• tier 편집 — 행 추가/삭제/수정 (일수, 보너스율)
• maxRate, maxBonusPang 수정
• 저장 시 변경 이력 로깅 (누가, 언제, 이전값→새값)

11.2 대시보드 지표 추가

11.3 유저 상세 화면

기존 사용자 관리 상세에 연속 출석 / 최고 기록 / 최근 30일 출석 캘린더 표시. CS 문의("출석했는데 보너스 안 붙었어요") 대응용.

12. 엣지케이스 · 어뷰징

12.1 엣지케이스

12.2 어뷰징

12.3 컴플라이언스

• 약관 개정 불필요. 기존 이벤트 포인트(30일) 정책 범위 내 운영 → 이벤트 공지로 갈음.
• 단, 이벤트 페이지에 tier 표와 리셋 규칙을 반드시 명시한다. "받을 줄 알았는데 리셋됐다"는 분쟁의 유일한 방어선이다.
• 보너스 팡은 현금 전환 불가 — 기존 팡 정책과 동일하게 안내.
• 확률형 요소 없음 → 확률 고지 의무 대상 아님.

13. QA 테스트 케이스

14. 개발 범위 · 일정

단계별 릴리즈

• Phase 1 (P0, 약 8MD) — 출석 기록 + 보너스 지급 + 홈 위젯 + 토스트 + 결과 표기. 이것만으로 기능이 성립한다.
• Phase 2 (P1, 약 6.5MD) — 진입 모달 배지, 내 정보 요약, 비회원 위젯, 규칙 시트, 관리자 화면.

15. 확정 필요 사항개발 착수 전 결론이 필요한 항목

범위 밖 (2차 검토)

• 연속 끊김 임박 리마인드 푸시 (효과는 가장 크지만 푸시 인프라 선행 필요)
• 출석 달력 뷰 / 월간 개근 보상 / 출석 뱃지 · 명예의 전당 연동
• 연속 복구권(팡 소모로 끊긴 연속 되살리기) — 수익화 여지 있으나 정책 복잡도 상승
• 매체사별 출석 보너스 차등 (파트너 프로모션용)