Barbelic devdocs

Appearance

[ARCHIVED 2026-08-19] 역사 자료 — 현행 규범이 아니다. 아카이브 사유와 대체 문서는 docs/README.md의 Archive 섹션을 참조.

아키텍처 작업 계획 ​

한국어 번역본

이 문서는 원문(영어)의 한국어 번역이다. 정본은 원문이며, 계약·게이트 판단이 갈리면 원문을 따른다. 원문: docs/archive/architecture-work-plan.md

갱신: 2026-06-22

이 문서는 다음 차례의 앱 전역 아키텍처 작업을 머지 가능한 PR 단위로 쪼개어 관리한다. 목표는 하나의 거대한 브랜치를 피하면서도 시스템을 더 깔끔하고 빠른 데이터 아키텍처 쪽으로 계속 움직이는 것이다.

기준선 ​

  • main이 통합 브랜치다.
  • 기존 PR 브랜치에 커밋하기 전에, 그 PR이 아직 열려 있는지 확인한다.
  • PR 제목, 설명, 후속 코멘트는 한국어로 작성한다.
  • 새 Supabase DB 변경은 반드시 supabase/migrations/*.sql을 사용한다.
  • 로컬 진단·프리뷰·확인·리셋·수리용 SQL 파일은 스크래치 파일이다. 이들은 프로덕션 마이그레이션이 아니며 평소 git status에 나타나서는 안 된다.

PR 분할 ​

PR 1. 기준선 정리 ​

범위:

  • 로컬 main을 최근 머지된 PR들과 동기화한다.
  • 현재 열려 있거나 머지된 PR 상태를 확인한다.
  • 로컬 Supabase 스크래치 SQL 파일이 git status에 잡히지 않게 한다.
  • 후속 PR 분할을 기록한다.

종료 기준:

  • git status에 의도한 추적 변경만 보인다.
  • 앱의 기능 동작 변화는 없다.

PR 2. 관측성과 운영 안전망 ​

범위:

  • 아직 빠져 있는 곳에 가벼운 앱/데이터 로딩 성능 로깅을 추가한다.
  • 진단에서 인증 실패와 데이터 실패를 눈에 띄게 분리해 유지한다.
  • 릴리스용 간결한 DB/앱 헬스 체크리스트를 추가한다.

종료 기준:

  • 느린 로그인, 느린 RPC, 느린 인입 신고가 특정 계층을 지목할 수 있다.
  • 디버그 로그는 옵트인으로 유지되며 원시 개인 페이로드를 노출하지 않는다.

PR 3. 화면 RPC 계약 강화 ​

범위:

  • 화면 RPC 응답 계약에 버전을 부여한다.
  • UI 매핑 전에 필수 키를 검증하는 런타임 어댑터를 추가한다.
  • 일반 앱 화면은 get_home_dashboard, get_calendar_month_summary, get_calendar_day_summary, get_session_detail, get_pr_overview, get_volume_overview 같이 경계가 정해진 read model 뒤에 둔다.

종료 기준:

  • 일반 앱 화면은 원시 테이블 구성을 알지 못한다.
  • 원시 페이로드나 상세 행이 요약 RPC로 새어 나오면 계약 테스트가 실패한다.

PR 4. 인입/통계 작업 큐 안정화 ​

범위:

  • Wodup 인입 잡의 상태 전이를 조인다.
  • 통계 갱신 잡을 관측 가능하고 재시도 가능하게 만든다.
  • 세션/인입 변경 이후에는 dirty 구간 재계산을 유일한 경로로 유지한다.

종료 기준:

  • 같은 인입을 다시 실행해도 멱등하다.
  • 통계 갱신이 실패하면, 조용히 낡은 대시보드가 남는 대신 들여다볼 수 있는 잡이 남는다.

PR 5. 도메인 경계와 대량 데이터 회귀 ​

범위:

  • 위험이 낮은 곳에서 남아 있는 대형 서비스 모듈을 도메인별로 분할한다.
  • 관리자/디버그/내보내기의 원시 읽기를 일반 앱 화면 읽기와 분리해 유지한다.
  • 4년치·10년치 데이터셋을 중심으로 대량 데이터 회귀 검사를 확장한다.

종료 기준:

  • 화면 코드는 데이터베이스 테이블이 아니라 BFF 스타일 서비스 호출을 소비한다.
  • 대량 데이터 성능 게이트가 초기 로드, 달력 페이징, 세션 상세, PR 대시보드, 인입, 통계 갱신 경로를 포괄한다.