bookquote

2026-05-10 — Stage 1 완료 (매니저 모드 도입)

하루에 인프라 0% → 폰에서 매직링크 로그인 + 책 검색 + 내 서재 추가까지. 16 커밋.

출발점

오늘 시작 시 상태:

• Stage 0a/0b 산출물 완비 (기획·디자인 문서, 디자인 토큰, 카드 템플릿 5종)
• Flutter scaffold + Riverpod/Supabase/freezed/go_router 의존성 설치만
• git 미초기화, 외부 인프라 100% 미설정
• placeholder home 화면 1개

오늘 끝 시 상태:

• Stage 1 전체 항목 완료, Stage 2 진입 직전
• Android 실기기에서 풀 흐름 동작 (매직링크 로그인 → 책 검색 → 내 서재 추가)
• 외부 인프라 다 연결 (GitHub/Supabase/Aladin/Kakao 콘솔/Resend/Android SDK)

협업 방식 변경

사용자 지시: 매니저 모드 도입. 가상 팀 = Dart 개발자 2 + UI/UX 2 + 기획자 2 + QA 2. 의사결정마다 관련 직무를 OMC 에이전트로 병렬 위임 → 결과 종합 → 사용자 승인 흐름.

핵심 자문 세션 5회:

1. 폰트 번들링 (Dart 아키텍트 + UI/UX 디자이너) — 디자이너 코드 검증 의견 채택
2. go_router 구조 (Dart 아키텍트 + 기획자) — BottomNav 4탭 vs 5탭 충돌, 기획자 cold-start 방어 채택
3. go_router QA·비용 검토 (QA 테스터) — refreshListenable P0 트랩 + Edge Function Stage 1 앞당김
4. 책 검색 + Edge Function (Dart 아키텍트 + 기획자 + QA) — 캐시 사전조회 + ON CONFLICT DO UPDATE + 400ms debounce

16 커밋 타임라인

Hash	메시지	핵심
88da5df	feat(theme): build AppTheme from design tokens	Material 3 ColorScheme + TextTheme 토큰화
2554985	feat(fonts): bundle Pretendard (R/M/SB) + NotoSerifKR variable	28 MB 번들 (가변 폰트로 25 MB 절감)
92c5d23	feat(config): wire Env via --dart-define-from-file	.env.json 패턴 + Env 컴파일 타임 상수
c3b0a7f	feat(supabase): wire client init through Env	initSupabase graceful skip
8ef3225	feat(routing): wire StatefulShellRoute + auth gate	4탭 BottomNav, refreshListenable, /splash
54e328b	feat(auth): email magic link end-to-end	profiles 테이블 + AuthController
903f632	fix(web): use path URL strategy so /auth/callback resolves cleanly	usePathUrlStrategy()
5612884	feat(auth): kakao OAuth alongside magic link	(이후 V1.5로 미룸)
a49f310	fix(auth): restrict Kakao OAuth scopes to nickname + profile image	KOE205 1차 우회 시도
a2820c4	chore(auth): defer Kakao OAuth to V1.5	Supabase GoTrue 충돌 확정 후 deferral
532acba	feat(book): aladin search via edge function + book search sheet	Edge Function + books 테이블 + BookSearchSheet
863f568	feat(mobile): deep-link auth callback + Supabase CLI pipeline	AndroidManifest intent-filter + app_links + CLI 파이프라인
bee0404	fix(router): map mobile deep-link path /callback alongside /auth/callback	Dart Uri 파싱 host/path 차이 보정
964999d	feat(library): user_books table + 내 서재 list UI	사용자별 서재 카탈로그
2e1aa5d	feat(book-search): saving overlay + per-pick toast	(사용자 직접 편집)
231aaaa	chore(auth): debug logs around session hydrate / persist	세션 영속화 진단

외부 셋업 완료

자원	상태	비고
GitHub repo	https://github.com/tgparkk/bookquote (public)
Supabase 프로젝트	ndbvptxwznogcuuumzzh (Seoul) + CLI 파이프라인	supabase db push / functions deploy 둘 다 수동 한 번 매니저가 처리
Supabase Auth URL Config	Site URL http://localhost:8080, Redirect URLs (localhost wildcard + mobile scheme)
Supabase Edge Function	aladin-search 배포 + ALADIN_TTB_KEY secrets 등록
Aladin OpenAPI	TTB 키 ttbshow04181423001 (5,000건/일)
Kakao Developer Console	앱 ID 1453058, REST API 키 + Client Secret 등록 (Auth는 V1.5로 미룸)
Resend SMTP	가입 + Supabase에 SMTP 연결 (sandbox 모드, 본인 이메일만)	베타 직전 도메인 verify 필요
Android	SDK 36 자동 설치 + debug APK 빌드 + Z Fold 6 실기기 동작
iOS	Info.plist URL Types 설정 (Mac 빌드 시 즉시)	Mac 미보유

결정 (DECISIONS.md 외 본 세션 한정 흐름 기록)

자세한 결정 근거는 DECISIONS.md 2026-05-10 섹션 참고. 본 세션의 자문 → 매니저 판단 흐름:

• 폰트 weight: 자문가 둘 다 정적 OTF 권고 → 매니저가 NotoSerifKR 가변 폰트 채택 (25 MB 절감 + 모든 weight 무료, 디자이너 Regular 누락 우려도 자동 해소)
• BottomNav 탭 수: 아키텍트 5탭 vs 기획자 3탭+[+] → 기획자 채택 (인터뷰 데이터 근거, 친구 탭 cold start 함정)
• /book/:id 인증: 기획자 게스트 미리보기 채택 (deep-link install funnel)
• Edge Function 도입 시점: QA 권고로 Stage 4 → Stage 1 앞당김 (키 노출·rate limit 보호)
• 카카오 V1.5 미룸: GoTrue가 account_email scope를 강제 요청, 카카오 개인 앱은 비즈 인증 없이 거부
• books upsert 충돌: QA 권고로 ON CONFLICT (isbn13) DO UPDATE (메타 갱신용)
• 마이그레이션 명명: 14자리 timestamp YYYYMMDDHHMMSS_*.sql (Supabase CLI 표준)

알게 된 함정 (다음 사람 안 빠지게)

1. Kakao 개인 앱은 account_email scope 등록 불가 — 비즈니스 인증 받기 전엔 동의항목 page에서 회색. Supabase GoTrue가 이 scope를 강제 요청해서 KOE205 발생. 우회: 비즈 인증 또는 kakao_flutter_sdk + signInWithIdToken
2. Supabase Redirect URLs ** 와일드카드는 custom scheme에 안 먹음 — io.github.tgparkk.bookquote://**는 매칭 실패, 정확한 URL 등록 필요
3. flutter install은 매번 uninstall + install — SharedPreferences (Supabase 세션 저장소) wipe됨. dev엔 adb install -r build/app/outputs/flutter-apk/app-debug.apk 사용
4. Supabase 무료 SMTP 시간당 2건 제한 — dev 검증 5번이면 1시간 대기. 처음부터 Resend 같은 외부 SMTP 권장
5. Resend free tier sandbox는 가입 이메일에만 발송 가능 — 다른 이메일은 unexpected_failure 반환. 베타 친구 5명 발송하려면 도메인 verify 필요
6. Mobile deep link io.github.tgparkk.bookquote://auth/callback Uri 파싱 — Dart는 host=auth, path=/callback으로 쪼갬. go_router는 path만 보니 라우터에 /callback 별도 추가 필요
7. Supabase 마이그레이션 파일명 — 14자리 timestamp 강제 (YYYYMMDDHHMMSS_*.sql). 우리는 처음 YYYYMMDD_NNN_*.sql 썼다가 CLI가 같은 timestamp로 인식해서 rename 필요
8. Riverpod 3.x에서 StateProvider, AutoDispose* 클래스 제거 — Notifier + AsyncNotifier 패턴으로 전환. 기존 가이드 자료 다수가 구버전 기준
9. Flutter web 기본 hash URL 전략 — magic link redirect URL과 충돌. usePathUrlStrategy() 호출 필수
10. palette_generator discontinued — V1엔 그대로 사용, V2에서 Flutter 내장 ColorScheme.fromImageProvider 마이그레이션 검토

보류 / 다음 세션 시작점

즉시 가능:

• Stage 2 인용구 입력 — 직접 입력 폼 + 사진 OCR (ML Kit) + 책-인용구 매핑 (quotes 테이블)

조건부:

• Resend 도메인 verify — 베타 친구 5명에게 매직링크 발송 직전. chaekgwi.com 같은 도메인 $12/년
• Stage 0a 마무리 — 실제 친구 5명 인터뷰 (docs/discovery/real-interview-guide.md)
• 카카오 OAuth 재시도 — 카카오 비즈니스 인증 후 또는 kakao_flutter_sdk_user 도입

기술 부채 (V1.5 또는 출시 직전):

• ALADIN_TTB_KEY 클라이언트 측 .env.json에서 제거 (Edge Function이 사용하므로 클라이언트엔 불필요)
• palette_generator 마이그레이션 검토
• 카드 편집기 palette_generator 호출을 compute() isolate로 분리 (UI 스레드 차단 방지)
• Notifier 기반 BookSearchQueryNotifier를 @riverpod 코드젠으로 전환 검토

매니저 회고

잘 동작한 패턴:

• 자문가 충돌 → 매니저 종합 → 사용자 승인 흐름이 매끄러움. 디자이너가 코드를 실제로 읽고 의견 낸 점이 결정적이었음 (폰트 weight 케이스)
• QA 자문가가 P0 함정 (refreshListenable trap, books race condition) 짚어준 게 출시 직전 디버깅 회피 효과
• 외부 셋업은 사용자에게 위임하되 단계별 클릭 위치까지 정확히 안내한 게 효율적

개선할 점:

• Kakao OAuth는 매니저가 사전에 “개인 앱 + Supabase 충돌” 알고 있어야 했음 (자문 단계에서 미발견 → 사용자 시간 소비)
• Resend sandbox 제한도 사전 안내 부족했음
• Flutter install vs adb install -r 차이도 처음부터 알려줬어야 (세션 유실 의심으로 진단 logging까지 추가)
• flutter install 같은 도구 디테일은 매니저가 외부 정보로 미리 검증하는 게 사용자 시간 절약