90일 챌린지 · 포인트 — PRD

1. 개요

1-1. 학술 근거

1-2. 핵심 원칙

• 1 포인트 = 1원 골고루 키트 결제 차감 (현금 환전 X)
• 정액 적립 — 식단(끼니) 기록 1건 = +50P(반감기·Stage 없음, 1P=1원)
• 적립 단위 = 끼니 입력 1건 · 일일 한도 5끼(영유아 자연 한도·farming 방지) → 하루 최대 250P
• 사용처 = 골고루 키트 + 월 구독 결제 차감 — 마이페이지에서 잔액·적립/사용 내역 확인
• 인플레 한도 X — 많이 기록할수록 키트 매출로 환원

2. 시스템 컴포넌트

3. 기능 요구사항 (18개)

3-1. 포인트 적립 (정액) ✅ 구현 완료

3-2. Stage Controller (반감기) ⛔ DEPRECATED (정액 적립으로 대체)

3-3. 90일 챌린지

3-4. 친구 초대 (양방향 적립) ⛔ DEPRECATED

3-5. 룰렛 (가변비율 강화) ⛔ DEPRECATED

3-6. 댓글·리뷰 보상 ⛔ DEPRECATED

3-7. 사용처 (Redeem)

3-8. 카카오 알림톡 푸시

3-9. 어드민·운영

4. 비기능 요구사항 (6개)

5. 데이터 모델 (Supabase Postgres)

-- 마일리지 ledger (append-only, 모든 변동 기록)
CREATE TABLE mileage_ledger (
  id BIGSERIAL PRIMARY KEY,
  user_id UUID NOT NULL REFERENCES users(id),
  kind TEXT NOT NULL,
    -- 'meal_input'·'referral_inviter'·'referral_invitee'·'roulette'·'comment'·'review'·'challenge_completion'·'redeem_kit'·'admin_adjust'
  amount INT NOT NULL,                  -- +/- (적립 양수, 차감 음수)
  meta JSONB,                            -- {meal_chip, stage, order_id, ref_user_id, ...}
  idempotency_key TEXT UNIQUE,           -- 중복 적립 방지
  balance_after INT NOT NULL,            -- 거래 후 잔액 (감사용)
  created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_ledger_user_created ON mileage_ledger(user_id, created_at DESC);

-- 잔액 캐시 (read 성능)
CREATE TABLE mileage_balance (
  user_id UUID PRIMARY KEY REFERENCES users(id),
  balance INT DEFAULT 0,
  total_earned INT DEFAULT 0,
  total_redeemed INT DEFAULT 0,
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- 친구 초대 트래킹
CREATE TABLE referrals (
  id UUID PRIMARY KEY,
  inviter_id UUID REFERENCES users(id),
  invitee_id UUID REFERENCES users(id),
  referral_code TEXT,
  status TEXT,                            -- 'invited'·'signed_up'·'first_input'·'rewarded'
  inviter_ip INET,
  invitee_ip INET,
  invitee_device_fingerprint TEXT,
  rewarded_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 90일 챌린지 상태
CREATE TABLE challenges (
  user_id UUID PRIMARY KEY REFERENCES users(id),
  started_at TIMESTAMPTZ DEFAULT NOW(),
  current_stage INT DEFAULT 1,
  days_input INT DEFAULT 0,                 -- 입력한 일수
  completion_bonus_paid BOOLEAN DEFAULT FALSE,
  completed_at TIMESTAMPTZ
);

-- 카톡 알림톡 발송 로그
CREATE TABLE kakao_messages (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  template_id TEXT,                       -- 'stage_change'·'challenge_complete'·'reminder'·'jackpot'
  payload JSONB,
  status TEXT,                              -- 'sent'·'failed'·'retry'
  sens_message_id TEXT,
  sent_at TIMESTAMPTZ,
  cost_krw INT
);

6. API 명세 (9 엔드포인트)

6-1. POST /api/mileage/earn — 예시 페이로드

{
  "kind": "meal_input",
  "meta": {
    "meal_chip": "점심",
    "meal_id": "abc-123",
    "input_time": "2026-05-25T12:30:00+09:00"
  },
  "idempotency_key": "meal_abc-123"
}

// 응답
{
  "earned": 100,
  "stage": 1,
  "balance": 4200,
  "daily_count": 3,
  "daily_limit": 5,
  "toast": "+100 마일리지 적립!"
}

// 한도 도달 응답
{
  "earned": 0,
  "reason": "daily_limit_reached",
  "message": "5끼 한도 도달 — 기록만 저장"
}

7. 알고리즘

7-1. Stage 결정

function determineStage(user) {
  const daysSinceSignup = differenceInDays(now(), user.created_at);
  if (daysSinceSignup <= 21) return { stage: 1, reward: 100 };
  if (daysSinceSignup <= 45) return { stage: 2, reward: 50 };
  if (daysSinceSignup <= 66) return { stage: 3, reward: 25 };
  return { stage: 4, reward: 12 };  // 67일+
}

7-2. 적립 검증 흐름

async function earnMileage(userId, payload) {
  // 1. Idempotency 체크 (중복 차단)
  if (await ledger.exists(payload.idempotency_key)) return previousResult;

  // 2. 일일 한도 (5끼) 체크
  const todayCount = await ledger.countToday(userId, 'meal_input');
  if (todayCount >= 5) return { earned: 0, reason: 'daily_limit_reached' };

  // 3. 끼니 간격 1시간 체크
  const lastMeal = await ledger.lastMeal(userId);
  if (lastMeal && minutesSince(lastMeal) < 60) return { earned: 0, reason: 'too_soon' };

  // 4. chip 중복 체크
  if (await ledger.todayChip(userId, payload.meta.meal_chip)) return { earned: 0, reason: 'chip_duplicate' };

  // 5. Stage 결정
  const { stage, reward } = determineStage(user);

  // 6. Append-only ledger 기록 + balance 갱신 (트랜잭션)
  await db.transaction(async (tx) => {
    await tx.ledger.insert({ user_id: userId, kind: 'meal_input', amount: reward, meta: { ...payload.meta, stage } });
    await tx.balance.increment(userId, reward);
  });
  return { earned: reward, stage, balance: newBalance };
}

7-3. 룰렛 분포 (서버 결정)

90일 = 90회 룰렛 = 약 ₩16,500 평균 보상. 잭팟 2% × 90일 = 1.8회 발생 가능.

7-4. 90일 완주 판정 cron

async function processCompletionBonus() {
  const due = await challenges.findDue();  // signup +90일 + 미지급
  for (const user of due) {
    if (user.days_input >= 60) {  // 90일 중 60일 이상 입력
      await ledger.insert({ user_id: user.id, kind: 'challenge_completion', amount: 50774 });
      await challenges.markCompleted(user.id);
      await kakao.send(user.id, 'challenge_complete');
    }
  }
}

8. Cron Jobs (4개)

9. Farming 방지

10. 출시 단계 (3 phase)

11. KPI