ADR-0020: 백엔드-facing 통합 채팅 프로비저닝 API를 별도 Next.js 앱(chat-api)으로 둔다
- Status: Accepted
- Date: 2026-10-14
- 관련: HMH-9927 (이번 작업) · 에픽 HMH-9765(Sendbird→Supabase 이관) · ADR-0019(chat-core 공용 패키지)
Context
Sendbird→Supabase 이관(HMH-9765)에서, 백엔드(FastAPI)가 Sendbird에 하던 채널/멤버/관리자메시지/operator 작업을 앞으로는 우리가 노출하는 HTTP API를 호출해 통합 Supabase 채팅(channel/channel_member/message, 마이그레이션 0014)에 쓰도록 바꾼다. 백엔드 Sendbird 호출은 12종(user 3·channel 5·message 4·operator 3 — lib/sendbird/__init__.py)이다.
제약:
- 0014 설계상 채널/멤버 생성은 클라(authenticated)에 열려 있지 않고 service_role 로만 가능하다(RLS·컬럼 GRANT). 즉 프로비저닝은 service_role 키를 쥔 서버가 해야 한다.
- 이 호출의 주체는 백엔드(서버) 다 — 사용자 세션(Bearer)이 아니라 server-to-server다.
- 기존 front-api(
apps/api,howmuchhome-front-api)는 앱 사용자 대행(native가 붙여 보내는 Bearer를 메인 백엔드에 위임 검증,signSupabaseJWT로 사용자 신원 JWT 발급 → anon key + RLS)으로 동작한다. service_role 키를 쥐지 않는다.
검토한 대안
| 대안 | 채택 안 한 이유 |
|---|---|
| front-api(apps/api)에 라우트 추가 | front-api는 “사용자 대행(Bearer→백엔드 위임, anon+RLS)” 모델이다. 여기에 service_role 키와 공유 시크릿(server-to-server) 인증을 섞으면, 사용자-facing 앱에 RLS를 우회하는 마스터 키가 들어가 공격 표면·사고 반경이 커진다. 인증 모델도 라우트마다 갈려 혼란. |
| 백엔드가 Supabase를 직접 호출(우리 API 없이) | 통합 모델 스키마·스코프 매핑(community:<chatUrl>)·멱등 규칙이 프론트(chat-core)와 백엔드에 이중 구현돼 드리프트. 스키마 변경 시 두 레포가 동시에 깨진다. 우리가 API를 소유하면 한 곳에서 계약을 통제. |
Decision
새 모노레포 앱 apps/chat-api(howmuchhome-chat-api) 를 만들어 백엔드-facing 프로비저닝/관리 API를 노출한다. front-api 패턴(Next.js 15 app router, typia, Sentry, 공유 env, 보안 헤더)을 미러하되 성격이 다르다:
- 인증: 공유 시크릿(
CHAT_API_INTERNAL_SECRET,X-Internal-Secret헤더, timing-safe 비교) — 백엔드만 호출. 배선:src/features/internalAuth.ts. - Supabase: service_role 클라이언트(
COMMUNITY_V2_SUPABASE_URL+COMMUNITY_V2_SUPABASE_SERVICE_ROLE_KEY)로 RLS 우회, 프로비저닝 전용. 배선:src/features/supabaseServiceRole.ts. - 엔드포인트(1차): 채널 upsert(
POST /internal/v1/channels, scope 멱등), 멤버 join/leave(.../[channelId]/membersPOST/DELETE, softleft_at), health. scope 매핑은 chat-coregetChannelByScope와 동일(community:<chatUrl>).
Consequences
좋아지는 것
- service_role 마스터 키가 사용자-facing 앱과 분리된 단일 서버에만 존재 — 사고 반경·감사 범위가 좁다.
- 통합 모델 쓰기 계약(스코프·멱등·컬럼)을 우리가 한곳에서 소유 → 백엔드/프론트 드리프트 방지.
- 후속(관리자메시지·operator·unread·공지)을 같은 앱·인증으로 확장.
감수하는 것
- 배포 단위가 하나 늘어난다(Vercel 프로젝트·env 관리). 공유 시크릿·service_role 키 운영 부담.
identity_scope에 아직 unique 제약이 없어 채널 upsert는 read-first(동시성 레이스 이론상 존재) — 프로비저닝 빈도상 실무 위험은 낮고, unique index로 강화 예정.
이 결정을 다시 열어야 할 때
- 백엔드가 Supabase를 직접 쓰는 게 더 단순하다고 판명되거나(스코프/멱등을 공유 라이브러리로 뽑을 수 있게 되거나), front-api와 통합하는 게 운영상 이득이 커질 때.
Last updated on