---
title: "핸드오프 — 가입 온보딩 동의(필수4+마케팅) + 소셜 OAuth 전용 흐름 + 충전식 가격·결제 시스템 W1~W11(PG mock 직전까지)"
category: "handoff"
document_type: "핸드오프"
source_status: "generated"
knowledge_group: "03_history"
priority: "High"
purpose: "2026-06-10 하루의 종합 인계 핸드오프. 핸드오프 33번(06-09)에서 끊긴 갭을 복원한다. ① OAuth 최초 로그인 시 표준 고객동의를 강제하는 온보딩 게이트(가-① #77)와 자체 ID/PW를 만들지 않는 소셜 OAuth 전용 로그인·회원가입·계정찾기 구조(#78), 동의 필수항목 4종+마케팅 선택(#79)을 완성했고, ② 코치AI 충전식 가격·결제 시스템 W1~W11을 SQL 7종·구독관리 페이지·PG mock 어댑터·결제 webhook 워커·약관 충전금 조항까지 PG 실키 교체 직전 상태로 배선했다(#80). 다음 스레드가 충전식 잔여분과 PG 연동을 즉시 이어받게 기술상태·미해결·운영규칙을 정리한 인계 문서다."
read_when: ["최신상태복구","충전식","결제","약관","동의","소셜OAuth","온보딩","DB·RLS·보안"]
updated: "2026-06-10"
work_timestamp: "20260610_234300"
context: "달록본레포CC (D:\\dallog\\dallog_git) — 06-10 가입동의·소셜OAuth전용·충전식가격결제(PR#77~80) 인계"
source_of_truth: "https://dallog-tools.hansbridge.co.kr/knowledge/"
---

# 핸드오프 — 가입 온보딩 동의 + 소셜 OAuth 전용 + 충전식 가격·결제 W1~W11

> **이 문서가 무엇인가 (비개발자용 한 줄 설명)**
> 2026년 6월 10일 하루 동안 달록에 ① 가입 시 약관·개인정보 동의를 반드시 받는 절차와 ② 코치 AI를 "돈 내고 충전해서 쓰는" 가격·결제 구조를 통째로 깔아둔 작업을, 다음 작업자(다른 Claude Code 세션)가 곧바로 이어받을 수 있도록 정리한 인수인계 문서다. 결제는 실제 카드 연동(PG) 바로 직전까지 가짜(mock)로 끝까지 동작하게 만들어 두었다.

---

## 0. 한 줄 요약

OAuth 로그인 직후 **표준 고객동의(필수4 + 마케팅 선택)** 를 강제하는 온보딩 게이트를 세우고, 자체 ID/PW 없이 **소셜 OAuth 전용** 으로 로그인·회원가입·계정찾기를 정리했으며, 그 위에 코치AI **충전식 가격·결제 시스템(W1~W11)** 을 PG 실키 교체 직전까지 배선했다. 전부 main 머지 + 자동배포. 본인인증은 미도입 유지([[project_verification_policy]]).

## 1. 이번 구간 완료 (PR, 전부 main 머지 + CF Pages 자동배포)

| PR | 내용 | 검수 |
|---|---|---|
| **#77** | 가입 온보딩 동의(가-①) — OAuth 직후 신규/미동의 유저에게 표준 고객동의 별도 체크박스 게이트(미동의 시 진입 차단) + `user_consent` append-only 이력 테이블 + 설정>계정 동의이력 열람·마케팅 토글. 로그인 브랜딩(타이틀·파비콘 라임) 복귀 | Codex 2사이클 |
| **#78** | 소셜 OAuth 전용 흐름 — 자체 ID/PW 가입·계정찾기 미생성, `SocialAuthInfoPage`(/signup·/find-account 안내) 신설. 필수 동의 3종으로 조정 + `oauth_provider` 캡처 + 보호경로 리다이렉트 보존(open-redirect 차단) + 네이버 state 검증 강화 | Codex 2사이클 |
| **#79** | 동의 항목 조정 — 사장님 지시로 **건강정보(민감정보) 별도동의를 필수에 재포함(필수4)** + 마케팅(선택) 추가. 완료버튼은 필수4만 게이트. 약관 예시 동의문구 정합화 | Codex 1사이클 |
| **#80** | **충전식 가격·결제 시스템 W1~W11** — 지갑·원장·차감 신모델·구독관리·단발 이용권·PG mock·결제 webhook·AI 원가레버·약관 충전금 조항 (아래 §3 상세) | Codex 4사이클 |

## 2. 동의·인증 구조 (가-① ~ #79) — 근본 설계

- **동의 필수항목 4종** — 이용약관 / 개인정보 수집·이용 / 개인정보처리방침 확인 / 건강정보(민감정보) 별도동의. + 마케팅(선택).
- **`user_consent` 테이블** — append-only 이력(UPDATE/DELETE 정책 없음 = **변조 금지**), RLS 본인만, `oauth_provider` 컬럼 + `consent_type` CHECK. 약관 버전 상수(2026-06-05) 기준이며 **버전 개정 시 재동의 자동 트리거**.
- **게이트 훅** — `useOnboardingConsent`(getSession 기반, 조회 실패 시 **fail-closed**, 로컬테스트세션·데모는 우회). 기존 OAuth 계정도 미동의면 1회 동의.
- **소셜 전용 근거** — 자체 비밀번호를 두지 않아 비밀번호 유출·재설정·계정찾기 공격면을 없앤다. 본인인증도 OAuth 신뢰 기반으로 미도입 유지([[project_verification_policy]]·[[project_legal_no_lawyer_policy]] — 변호사 자문 없이 표준약관+표준동의만).

## 3. 충전식 가격·결제 W1~W11 (#80) — 인계 핵심

> 충전식 정책 본체는 [[project_pricing_charge_policy]] 다. B-라이트 확정: 무료0 / 1단계 5,900 / 2단계(주력) 9,900 / 히든 24,900(VAT 포함 KRW, 방어환율 1,750). 차감=일일할당 자유책임(방당캡/할증=가중소모) → 소진 시 단발 150(무료·유료 공통). 충전금=선수금 분리회계·만료 없음·환불(실충전만).

| 단계 | 내용 |
|---|---|
| **W1** | 플랜표 재시드 — 5,900/9,900/hidden 24,900, tier3(구) 은퇴 (`coach_plan_catalog`) |
| **W2** | 지갑 + **append-only 원장** + 쿠폰 + 결제 멱등 + 일사용량 테이블 |
| **W3** | `consume_turn` 신모델 — SECURITY DEFINER·잠금순서 고정·billing 가드 (999줄, 시스템의 심장부) |
| **W5** | 온보딩 부스트(가입 보너스) |
| **W6/W7** | 구독관리 페이지(`/coach/subscription`) + 단발 이용권 흐름(방단위 동의·자동적용) + 턴캡 할증경고(누적배수 N배) + 전환 funnel 이벤트 |
| **W8** | 매출 분리표시 뷰(선수금 vs 매출) |
| **W9** | AI 원가레버 — 룸단위 memoize + 조건부 티어(input 35~60% 절감) + Flash-Lite 화이트리스트 라우팅(서버 건강가드 + recall 테스트 통과) + 출력토큰 상한 |
| **W10** | **PG mock 어댑터 끝까지 배선(실키 교체만 남김)** + `payment-webhook` 워커(서명검증·원자충전 RPC) + 충전/환불/자동충전 UI |
| **W11** | 약관 충전금 조항(제9~11조)·전자상거래 고지·자가발행 예외 메모·대사(정산 대조) 운영규칙 |

- **검수** — Codex 협업 4루프(보안 RLS 경계·원자성·멱등·race 집중).
- **마이그레이션** — `2026-06-10_coach_charge_w*` 7종. ⚠️ W10 등 일부는 다음 날(06-11) 재적용·정정 이력이 있다(W3 UNIT7 누락 → 재적용). SQL은 CC 직접 실행·검증 체제로 전환([[reference_supabase_direct_sql]]).

## 4. 핵심 기술 상태 (다음 스레드 참고)

- **신규 lib** — `src/lib/coachChat/` 하위 entitlement·billingPhase·funnel·wallet 등. 지갑/원장/플랜 모델이 코치 사용량 차감의 토대다.
- **신규 페이지/컴포넌트** — `CoachSubscription`(구독관리), `OnboardingConsent`(동의게이트), `SocialAuthInfoPage`, `ExhaustNotice`·`TurnCapModal`·`PlanShopPanel`(소진·할증·플랜).
- **결제 워커** — `workers/payment-webhook`(서명검증 + 원자충전 RPC). 실 PG 키만 교체하면 실결제 전환.
- **turn_type 원가분리** — 도구턴은 코칭 회 무차감(원가만 로깅)이 과금모델 권고([[project_coach_tool_turn_billing]]). 병행 스레드(workreport #101)의 turn_type 인프라와 정합.

## 5. 미해결 · 다음 스레드 작업 후보 (인계)

1. **충전식 잔여분** — 온보딩 부스트 프론트 배선, 계좌 1원인증 흐름, 어드민 분리표시·통화(USD→KRW) 정정, 사이드바 잔액 표시, 충전 UI 정렬. (→ 실제로 다음 날 06-11 PR#81에서 착수됨.)
2. **PG 실연동** — 현재 mock 어댑터. 실 PG사 선정 + 실키 교체 + webhook 서명검증 실값.
3. **충전식 E2E 검증** — mock 전구간(충전→차감→환불) 자동 검증 하네스. (→ 06-11 PR#82.)
4. **모델 단가 placeholder** — `coach_price_table` 단가가 전부 placeholder. 자동 원가캐치 시스템 필요([[project_auto_cost_catch_system]]). (→ 06-11 PR#85.)
5. **상시 대기(누락금지)** — 약관(작업5)·디자인 이식·KB 훅 승인 / "AI에게 보내기" 문구 "30일"→실제 전체기간([[project_ai_handoff_30day_label_todo]]) / 외부 LLM KB 열람 차단 해제([[project_kb_external_llm_access_todo]]).

## 6. Codex 협업 검토 결과 (요약)

- #77·#78 각 사후검수 2사이클, #79 증분 1사이클, #80 4루프(가장 민감 = 결제·원장·RLS). 사전공유 + 사후검수 반영, [즉시반영] 위주.
- 핵심 교훈 — 결제·원장은 **원자성·멱등·잠금순서·RLS 경계**가 생명이라 검수 루프를 최다로 돌렸다.

## 7. 지킬 운영 규칙 (요약)

- 본레포 = 개발만(브랜치+PR, push·머지는 사장님 명시 시 진행 [[feedback_git_workflow]]). git pull 금지(fetch→origin/main 분기). reset/checkout(discard)/add -A 금지·수정파일만 명시 스테이징.
- 워커 배포 = CC 자율([[feedback_deploy_autonomy]]). 배포 후 URL 테스트 보고. cwd 유지 주의(`cd workers/...` + pwd 확인 후 deploy).
- SQL = CC 직접 실행·검증([[reference_supabase_direct_sql]]). 수동 적용=조용한 실패 위험. [필수보존]/🗑️DELETE AFTER USE 태그. 비밀정보 금지.
- KB 발행 = dallog-tools kb-inbox frontmatter + 분리블록 → push([[feedback_kb_record_workflow]]). 비개발 사장님께 평어 해설·콜론 종결 금지.

## 8. 작업 리드타임

- 작업일: 2026-06-10 (PR#77~80). 본 핸드오프 발행: 2026-06-10 23:43 경(KST) 기준 복원.

---