keeper-out 1만원 게이트 통합 설계v3

01.한 줄 요약 (v3)

1만원 N페이는 자동 즉시 발송 X → 24시간 내 휴먼 승인 후 발송으로 바뀐다. 영업원 출장 종료 시점에 진단은 pending_review 상태로 큐 진입, TM(콜센터)가 사장님께 routine follow-up 콜을 거치며 통화 결과를 admin에 입력하면 그 시점에 [💸 발송 확인] 버튼 활성화되고 클릭 → Giftishow 발송. TM이 6시간 안에 처리 못한 건은 자동님 admin pending 큐로 escalate되어 일괄 검토. 공격 발생 시 자동님이 [ALL HOLD] 1클릭으로 모든 발송 일시 정지. 이 방식은 키퍼메이트의 ①룰(연락 가능)·③룰(도입 의향)을 콜로 자연 검증하면서, 해커 침투·잔액 노출 시 인간이 끼어들 시간을 확보한다.

02.왜 휴먼 승인이 필요한가 — 해커 위협 모델 갱신

v1·v2까지의 위협 모델은 어뷰징 위주(사례비 헌터, 봇, 영업원 본인 어뷰징). 어뷰징은 단가 높고 빈도 낮아 자동 게이트로 충분.

위협 모델 v3 — Actor × Scenario 갱신

03.24h 큐 — 정확한 timeline + 정책

큐 cap (해커 차단)

04.휴먼 승인 흐름 — 누가 / 어떻게 / 어디서

1차 승인자 — TM 콜센터 (이서경 등 발레리온 직원)

2차 승인자 — 자동님 admin fallback (TM 6h 미처리 건)

TM이 처리 못한 건은 자동님 admin /keeper-out/admin/fallback 큐로 escalate. 자동님은 일괄 [✓ 모두 승인] 또는 카드별 검토. 자동님 부담 절감 — TM 정상 운영 시 fallback 큐는 거의 비어있어야 함.

거부 사유 enum (TM·admin 공통)

05.UX — 사장님 / TM / 자동님 / ALL HOLD

5-1. 사장님 진단 종료 화면

5-2. 사장님 안내 SMS (T0 직후 발송)

5-3. TM 화면 — admin /keeper-out/admin/pending

5-4. TM 콜 outcome 입력 모달

5-5. 자동님 admin fallback 화면

5-6. ALL HOLD — 비상 정지 메커니즘

06.검증 차원 V1~V12 (V12 휴먼 승인 신설)

07.3-layer 통합 스키마 (v2 유지)

08.병렬 세션 진척 (P1 박힘)

P1.5/P2 대기, P3(휴먼 승인)가 이번 v3에서 신규.

09.P3 마이그레이션 — 누락 zero

-- supabase/migrations/2026MMDD_keeper_outbound_anti_abuse_v3.sql
-- v3: 휴먼 승인 큐 + 어뷰징 가드 풀 박기

-- ============================================================
-- 1. agents 테이블 — 영업원 코드 + Referio 매핑 + invalid률
-- ============================================================
alter table public.keeper_outbound_agents
  add column if not exists code text,                   -- ★ 5자리 영숫자 mixed case (예: K9bR2)
  add column if not exists referio_partner_id text,      -- 86Af9 매핑
  add column if not exists keeper_partner_id int,         -- 향후 키퍼 partners 통합
  add column if not exists kakao_user_id text,           -- 향후 SSO
  add column if not exists invalid_rate_30d numeric default 0,
  add column if not exists day_cap_count int default 0,
  add column if not exists week_cap_count int default 0,
  add column if not exists last_active_at timestamptz;

create unique index if not exists uniq_agent_code
  on public.keeper_outbound_agents(code) where code is not null;

-- ============================================================
-- 2. leads 테이블 — V4 강화 + 휴먼 승인 컬럼 + 핑거프린팅
-- ============================================================
alter table public.keeper_outbound_leads
  -- V4 유일성
  alter column naver_place_id set not null,                -- 자동완성 통과 강제

  -- 휴먼 승인 트래킹
  add column if not exists tm_called_at timestamptz,
  add column if not exists tm_outcome text check (tm_outcome in
    ('confirmed','no_answer','not_owner','rejected','fraud_suspect','wrong_phone')),
  add column if not exists tm_note text,
  add column if not exists approved_by uuid references auth.users(id),
  add column if not exists approved_at timestamptz,
  add column if not exists approval_tier int,                  -- 1=TM, 2=admin fallback, 3=auto-fallback

  -- 핑거프린팅 (V9)
  add column if not exists ip_address inet,
  add column if not exists user_agent text,

  -- L2 매칭 캐시 (사후 검수)
  add column if not exists external_user_id int,
  add column if not exists external_subscribed_at timestamptz,
  add column if not exists external_checked_at timestamptz;

-- phone unique lifetime (V4)
create unique index if not exists uniq_leads_phone
  on public.keeper_outbound_leads(phone);

-- ============================================================
-- 3. payouts — payout_status 확장
-- ============================================================
alter table public.keeper_outbound_payouts
  drop constraint if exists keeper_outbound_payouts_status_check,
  add constraint keeper_outbound_payouts_status_check check (status in
    ('pending','pending_review','pending_dispatch','sent','failed','invalid','on_hold'));

-- ============================================================
-- 4. OTP 세션 (V1)
-- ============================================================
create table if not exists public.keeper_outbound_otp_sessions (
  id uuid primary key default gen_random_uuid(),
  phone text not null,
  code char(6) not null,
  expires_at timestamptz not null,
  attempts int default 0,
  verified_at timestamptz,
  ip_address inet,
  user_agent text,
  created_at timestamptz default now()
);
create index idx_otp_phone_active on public.keeper_outbound_otp_sessions(phone)
  where verified_at is null;

-- ============================================================
-- 5. 어뷰징 신호 (V7)
-- ============================================================
create table if not exists public.keeper_outbound_fraud_signals (
  id uuid primary key default gen_random_uuid(),
  lead_id uuid references public.keeper_outbound_leads(id) on delete cascade,
  agent_id uuid references public.keeper_outbound_agents(id),
  rule text not null,                                  -- self_referral / unknown_responses /
                                                          --   cluster / wrong_owner / tm_suspect / all_hold
  severity text check (severity in ('low','med','high')),
  payload jsonb,
  resolved_at timestamptz,
  resolved_by uuid references auth.users(id),
  resolution_note text,
  flagged_at timestamptz default now()
);
create index idx_fraud_lead on public.keeper_outbound_fraud_signals(lead_id);
create index idx_fraud_unresolved
  on public.keeper_outbound_fraud_signals(severity, flagged_at desc)
  where resolved_at is null;

-- ============================================================
-- 6. 시스템 캡 (해커 차단 + 운영 안전)
-- ============================================================
create table if not exists public.keeper_outbound_system_state (
  key text primary key,                                 -- 'all_hold' / 'minute_count' / 'hour_count' /
                                                          --   'day_count' / 'last_balance_check_at'
  value jsonb not null,
  updated_at timestamptz default now()
);

-- ============================================================
-- 7. RLS
-- ============================================================
alter table public.keeper_outbound_otp_sessions enable row level security;
alter table public.keeper_outbound_fraud_signals enable row level security;
alter table public.keeper_outbound_system_state enable row level security;

create policy "service_all_otp" on public.keeper_outbound_otp_sessions
  for all to service_role using (true) with check (true);
create policy "service_all_fraud" on public.keeper_outbound_fraud_signals
  for all to service_role using (true) with check (true);
create policy "service_all_system" on public.keeper_outbound_system_state
  for all to service_role using (true) with check (true);

10.P3 API endpoint 명세

request-otp 명세

// POST /api/keeper-out/diagnose/request-otp
// Body
{
  payload: DiagnoseSubmitPayload,    // 진단 데이터 전체 (clinet 임시 보관)
  agent_name: string,                // V3 영업원 이름
  agent_code: string,                // V3 5자리 영숫자
}
// 게이트 순서 (모두 통과 시 OTP 발송)
1. V3: agents.code + agents.name 매칭 + active=true + day_cap·week_cap 미달
2. V4: payload.naver_place_id NOT NULL + DB 미존재
3. V4: payload.phone DB 미존재 (lifetime unique)
4. V5: system_state.minute_count·hour_count·day_count 미달 + system_state.all_hold !== true
5. V5: Giftishow checkBalance() ≥ ₩50,000
6. V8: place 실재성 (Naver Place API)
7. V2: GPS × place 거리 ≤ 200m
8. await sendOtp(phone)  // balerion SMS proxy
9. INSERT otp_sessions (5분 만료, attempts=0)
// Response
{ ok: true, otp_session_id: uuid }   // 클라이언트가 verify로 다시 보냄

verify 명세

// POST /api/keeper-out/diagnose/verify
{
  otp_session_id: uuid,
  otp_code: string,                  // 6자리
  payload: DiagnoseSubmitPayload,    // request-otp와 동일
  agent_code: string,
}
// 게이트
1. V1: otp_sessions row 매칭 + expires_at > now() + attempts < 3
2. V6: photo EXIF 검증 (soft, agent confirm 옵션)
3. INSERT leads (agent_id resolved, payout_status='pending_review', ip_address, user_agent)
4. INSERT payouts × 3 (naver_pay_10k status='pending_review', lead_30k 2건 status='pending')
5. funnel_event 'review.queued'
6. balerion SMS — 사장님 안내 SMS 발송
// Response
{ ok: true, lead_id: uuid, expected_dispatch_within: '24h' }

tm-call + dispatch 명세

// POST /api/keeper-out/admin/leads/[id]/tm-call
{
  outcome: 'confirmed' | 'no_answer' | 'not_owner' | ...,
  note: string,
}
// → leads.tm_outcome + tm_called_at + tm_note 갱신
// → outcome === 'fraud_suspect' 시 fraud_signal INSERT + admin alarm

// POST /api/keeper-out/admin/leads/[id]/dispatch
{ approval_tier: 1 | 2 | 3 }   // 1=TM, 2=admin, 3=auto-fallback
// 게이트
1. payout_status === 'pending_review'
2. system_state.all_hold !== true
3. cap 재확인 (분당/시간당/일별)
4. Giftishow checkBalance() 재확인
5. await sendNaverPayCoupon(...)
6. payouts.naver_pay_10k status='sent' + leads.approved_by + approved_at + approval_tier
7. funnel_event 'payout.dispatched'

11.P3 admin UI — 신규 페이지 + 섹션

신규 페이지 2건

LeadDetailClient (이미 박힌 P1)에 추가할 섹션 4개

신규 컴포넌트 5건

• app/diagnose/components/AgentGateModal.tsx — 사장님 "지원금 받기" 클릭 시 영업원 이름+코드 입력 (V3)
• app/diagnose/components/OtpVerifyModal.tsx — V1 OTP 6자리 입력 (5분 카운트다운)
• app/keeper-out/admin/pending/PendingQueue.tsx — TM 큐 카드 리스트
• app/keeper-out/admin/fallback/FallbackQueue.tsx — 자동님 fallback 큐
• app/keeper-out/admin/components/AllHoldButton.tsx — ALL HOLD 토글 (PM+ 권한)

12.대시보드 에이전트 작업 룰 (필독)

다른 Claude/Codex 세션이 P3 진입 시 따라야 할 룰. 위반 시 PM 검증 fail.

커밋 단위 (P3 — 권장 8 commits)

1. feat(keeper-out): migration v3 — agent code, leads approval columns, otp/fraud/system_state tables
2. feat(keeper-out): /diagnose request-otp + verify endpoints + AgentGateModal + OtpVerifyModal
3. feat(keeper-out/admin): pending queue page + TM call API
4. feat(keeper-out/admin): dispatch + reject API + balance preflight + cap check
5. feat(keeper-out/admin): fallback queue page (TM 6h escalate)
6. feat(keeper-out/admin): ALL HOLD toggle + system_state CRUD
7. feat(keeper-out/admin): LeadDetailClient sections 14·15·16·17 (검증/외부매칭/승인/액션)
8. feat(keeper-out): cron — recheck-completion + escalate-fallback (24h dual-layer)

13.Phase 분할 — P1·P1.5·P2·P3·P4

14.측정 KPI

15.결정 6건 누적

16.미해결 정책 결정 1건

비결정 5건 (v1~v2 이월)

1. OTP 발송 채널 — balerion SMS proxy / KISA / NICE / NHN
2. 영업원 우회로 — 관리자 PIN 백도어 / 코드 없는 진단 거부
3. review-on과 잔액 격리 — Giftishow 키 별도 / 모니터링만 분리
4. agent.code 발급 운영 — 본사 admin 수동 / 자율가입 후 승인 / Referio 매핑
5. 05-policy.md 어뷰징 정책 명문화 별도 문서 — 만들까?

17.참조 — 보고서 체인 + in-repo 문서

보고서 체인 (시간순)

• pain_points 백엔드 (기반 작업)
• 병렬 세션 — admin Lead Detail 13섹션 plan
• Codex Brief P1 작업지시서
• PM Review — Codex P1 PASS
• Codex Brief #2 — P1.5 + P2 + main merge
• v1 — 1만원 게이트 검증 시스템 설계
• v2 — 통합 스키마 합본
• v3 (이 문서) — 24h 휴먼 승인 큐 + 작업 지시서

in-repo 문서 (4건)

• docs/keeper-out/anti-abuse/01-current-state.md
• docs/keeper-out/anti-abuse/02-verification-requirements.md
• docs/keeper-out/anti-abuse/03-re-candidates.md
• docs/keeper-out/anti-abuse/04-keeper-platform-re.md

주요 식별자