Barbelic devdocs

Appearance

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

Architecture Work Plan ​

Updated: 2026-06-22

This document keeps the next app-wide architecture work split into mergeable PRs. The goal is to avoid one large branch while still moving the system toward a cleaner, faster data architecture.

Baseline ​

  • main is the integration branch.
  • Before committing to an existing PR branch, check whether that PR is still open.
  • PR titles, descriptions, and follow-up comments should be written in Korean.
  • New Supabase DB changes must use supabase/migrations/*.sql.
  • Local diagnostic, preview, confirm, reset, and repair SQL files are scratch files. They are not production migrations and should not appear in normal git status.

PR Split ​

PR 1. 기준선 정리 ​

Scope:

  • Sync local main with the latest merged PRs.
  • Confirm currently open/merged PR state.
  • Keep local Supabase scratch SQL files out of git status.
  • Record the follow-up PR split.

Exit criteria:

  • git status only shows intentional tracked changes.
  • No functional app behavior changes.

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

Scope:

  • Add lightweight app/data-loading performance logging where it is still missing.
  • Keep auth failures and data failures visibly separate in diagnostics.
  • Add a compact DB/app health checklist for releases.

Exit criteria:

  • Slow login, slow RPC, and slow import reports can point to a specific layer.
  • Debug logs remain opt-in and do not expose raw private payloads.

PR 3. 화면 RPC 계약 강화 ​

Scope:

  • Version the screen RPC response contracts.
  • Add runtime adapters that validate required keys before UI mapping.
  • Keep normal app screens behind bounded read models such as get_home_dashboard, get_calendar_month_summary, get_calendar_day_summary, get_session_detail, get_pr_overview, and get_volume_overview.

Exit criteria:

  • Normal app screens do not know raw table composition.
  • Contract tests fail if raw payloads or detail rows leak into summary RPCs.

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

Scope:

  • Tighten Wodup import job status transitions.
  • Make stats refresh jobs observable and retryable.
  • Keep dirty-range recalculation as the only path after session/import changes.

Exit criteria:

  • Re-running the same import is idempotent.
  • A failed stats refresh leaves an inspectable job, not a silent stale dashboard.

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

Scope:

  • Split remaining large service modules by domain where risk is low.
  • Keep admin/debug/export raw reads separate from normal app screen reads.
  • Extend large-data regression checks around 4-year and 10-year datasets.

Exit criteria:

  • Screen code consumes BFF-style service calls, not database tables.
  • Large-data performance gates cover initial load, calendar paging, session detail, PR dashboard, import, and stats refresh paths.