Hyunjin · Java 백엔드 개발자

프로젝트

한지갑 — 함께 쓰는 공동 가계부

역할

기획·백엔드(DB 스키마, RLS, RPC, 인프라)·앱 전부

기간

2026-09-17 착수, 9-19 기준 로드맵 M0~M7 코드 완료

운영

hanjigap.hyunjins.co.kr (PC 웹) · api.hanjigap.hyunjins.co.kr (API 게이트웨이)

규모

서버 테이블 17 · RLS 정책 42(테이블 39 + 스토리지 3) · RPC 10 · 마이그레이션 4 · Dart 파일 112 · 단위 테스트 94 · RLS 시나리오 35

왜 만들었나

부부 공유 가계부 앱 BuBoo를 실제로 쓰면서 불편했던 점이 출발점이다.

핵심 기능

아키텍처

[Flutter 앱: iOS / Android / PC 웹]
   │  혼자 모드: 기기 SQLite  ──(함께 쓰기 전환)──▶ 서버로 이전
   │  함께 모드: HTTPS / WebSocket
   ▼
Caddy (80/443, Let's Encrypt 자동 발급)
   ▼
gateway (nginx 1장, Kong 대체)
   ├─ /auth/v1      → GoTrue       (인증·세션·소셜 로그인)
   ├─ /auth/naver   → authbridge   (네이버 OAuth → GoTrue admin API → magiclink)
   ├─ /auth/passkey → authbridge   (WebAuthn 등록·검증 → magiclink)
   ├─ /rest/v1      → PostgREST    (테이블·RPC, RLS 적용)
   ├─ /realtime/v1  → Realtime     (WebSocket, wal2json 논리 복제)
   └─ /storage/v1   → storage-api  (영수증 사진)
   ▼
Postgres 16 (+wal2json) ── 마이그레이션 4개 · RLS · security definer RPC · 트리거
   ├─ mailpoller (IMAP → inbound_messages)
   ├─ OCI Email Delivery (SMTP) → 가입 확인·비밀번호 재설정 메일
   └─ backup.sh (pg_dump -Fc + 스토리지 tgz, 14세대, 오프사이트 rsync, heartbeat)

감시: Uptime Kuma(반대편 서버) · Beszel(자원) · Dozzle(로그) · 텔레그램 알림

운영 서버는 OCI A1(2 OCPU / 12GB) 1대. Supabase 클라우드 대신 부품만 띄운 이유는 이미 Postgres를 운영 중이었고, 앱 코드·마이그레이션·RLS가 Supabase 그대로라 나중에 pg_dump/pg_restore로 옮길 수 있기 때문이다.

백엔드 관점에서 고려한 것

접근 제어는 ledger_members 한 곳으로

모든 테이블은 RLS ON이고, 판단은 "내 user_id가 그 가계부의 ledger_members에 있는가"로만 한다. 멤버 행 하나를 지우면 그 사람의 모든 접근이 끊긴다.

create function is_member(p_ledger uuid) returns boolean
language sql stable security definer set search_path = public as $$
  select exists (select 1 from ledger_members where ledger_id = p_ledger and user_id = auth.uid()) $$;

create policy transactions_insert on transactions for insert
  with check (can_edit(ledger_id) and created_by = auth.uid());

트랜잭션이 필요한 쓰기는 security definer RPC

환불 상계와 중복 방지 — 제약은 지키고 집계에서 푼다

환불은 양수 금액 + refund_of 참조로 두고 집계에서만 부호를 바꾼다. 같은 규칙이 SQL 함수 signed_amount(t), Dart signedAmount, 기기 SQLite signedAmountSql 세 곳에 있다. 트리거 check_refund가 같은 가계부의 지출만 환불 대상으로 허용하고 공동/개인·카테고리를 원거래에서 상속시킨다.

create unique index on transactions(ledger_id, source_hash) where source_hash is not null;
create unique index transactions_recurring_occurrence_key on transactions(recurring_rule_id, occurred_on);

셀프호스팅 Supabase — Kong 대신 nginx 한 장

인증: GoTrue + 네이버 브리지 + 패스키

• 네이버 로그인: GoTrue 미지원. authbridge(Python, 525줄)가 네이버 OAuth → 이메일 조회 → GoTrue admin API로 사용자 생성 → magiclink로 세션 발급. state는 HMAC 서명, redirect는 허용 목록만.
• 패스키(WebAuthn): 등록·로그인 6개 엔드포인트. 자격 증명은 GoTrue app_metadata.passkeys(서비스 롤만 수정)에 보관, 검증 성공 시 magiclink hashed_token → 앱 verifyOTP. 챌린지 5분·1회용. soft-webauthn 가짜 인증기로 테스트 16건.
• 세션: 리프레시 토큰 회전, 30일 미사용 만료. 자동 로그인 끔은 초기화 전에 저장 키를 지운다(초기화 후 signOut하면 세션이 되살아나는 경합을 QA에서 발견).

저장 분리: 혼자 = 기기 SQLite, 함께 = 서버

• 리포지토리는 SupabaseClient 대신 Db/Query 인터페이스(PostgREST 부분집합)를 받는다. SupabaseDb와 LocalDb(sqflite) 두 구현, 같은 쿼리 코드.
• 서버 17개 테이블 중 계정·공동 전용 5개를 뺀 12개가 기기에 있다. RPC 5개와 트리거 2개를 Dart로 포팅.
• id는 클라이언트 uuid.v4()라 서버로 옮길 때 id를 그대로 쓴다. 의존 순서로 500행씩 복사, 실패하면 서버 가계부를 지워 되돌린다.
• 합치기: 카테고리·결제수단은 종류+이름으로 매핑, 같은 source_hash 거래는 건너뛰고(환불은 서버 거래 재참조), 실패하면 이번에 넣은 행만 되돌린다.

운영: 백업·감시·도메인 이전

• 매일 pg_dump -Fc + 스토리지 tgz, 14세대, 다른 계정·다른 서버로 오프사이트 rsync, 성공 시 heartbeat(25시간 무응답이면 알림).
• 생존 감시(Uptime Kuma)는 대상과 다른 서버에, 자원(Beszel)·로그(Dozzle)는 대상 서버 안에. 텔레그램 알림.
• 도메인 이전 회귀: API 호스트가 바뀌자 세션 저장 키(sb-<호스트 첫 라벨>-auth-token)가 바뀌어 모든 기기가 로그아웃됐다. 옛 키 → 새 키 세션 이전, 동의 게이트 수정, 회귀 테스트 4건, 옛 도메인 병행 서빙. 배포 체크리스트에 "기존 기기 로그인 유지 확인" 추가.
• 앱 .env는 웹 빌드에서 공개되므로 anon 키·플래그만. service_role 키·메일 비밀번호는 서버 전용.

검증 체계

기술 스택

realestate-pipeline / 실봄 — 실거래가 수집 파이프라인과 지도

역할

설계·수집 파이프라인·API·관리 UI·지도 앱·모바일 앱·배포 전부

기간

2026-09-11 착수, 9-19 기준 로드맵 0~5단계 대부분 완료, 커밋 184개

운영

OCI 서버, realestate.hyunjinssss.duckdns.org (지도 앱 /, 관리 UI /admin/, API /api/)

규모

Python 75파일 21,000줄 · TS/TSX 65파일 6,100줄 · ORM 모델 36 · alembic 마이그레이션 27 · 데이터셋 YAML 28 · API 라우트 86 · pytest 275건

왜 만들었나

호갱노노 같은 실거래가 지도 서비스를 공공데이터만으로 어디까지 만들 수 있는지 확인하고 싶었다. 국토부 실거래가 API는 누구나 받을 수 있지만 거래 고유 ID가 없고, 값은 전부 문자열이며, 해제 건은 별도 행으로 오고, 단지 키가 다른 공공 API와 다른 체계다. 그래서 "원본 보관 → 정규화·격리 → 검증 → 파티션 단위 원자적 공개"를 지키는 파이프라인을 먼저 세우고 그 위에 지도 앱과 뉴스 RAG를 올렸다.

핵심 기능

아키텍처

[외부 소스] 국토부 실거래가(XML) · K-apt(JSON) · 건축물대장 · VWorld · 청약홈 · KOSIS/행안부 · 뉴스 RSS
     │ collectors/ (커넥터: fetch(partition, cursor) → page, tenacity 재시도, 키 마스킹)
     ▼
raw_pages (원문 불변 보관, 본문 해시)                  ← ingestion_runs (파티션·설정 버전·코드 버전·건수)
     │ core/   (datasets/*.yaml 템플릿 상속 → 변환 함수 레지스트리 → 실패는 rejected_records 격리)
     │ enrich/ (지오코딩 + 캐시, K-apt 매칭, 공급면적, 임베딩, LLM 엔티티 추출)
     ▼
serving_generations (파티션 단위 원자적 전환. 실패한 실행은 기존 세대를 건드리지 않음)
     ├─ deals(deals_current 뷰) · property_master · property_summary(단지×거래종류×면적대)
     ├─ news_chunks(pgvector HNSW) · entities · relations · mentions ──▶ Neo4j 미러
     └─ region_stats · public_prices · building_registers …
     ▼
FastAPI ── 공개 조회 API · /admin/* (X-Admin-Key, audit_log) · /rag/* · 내장 스케줄러 · 메모리 감시
     ▼
nginx (SPA + /api 프록시) ◀── 리버스 프록시(TLS) ◀── 브라우저 / 실봄 앱

백엔드 관점에서 고려한 것

원본과 서빙을 분리하고, 공개는 파티션 단위로 원자적으로

수집 단위는 (dataset_id, lawd_cd, deal_ymd) = 시군구 × 계약월. 같은 파티션의 동시 실행은 pg_try_advisory_xact_lock으로 막고, 페이지 누락·건수 불일치가 있으면 공개를 보류하고 기존 세대를 유지한다. 서빙 테이블은 언제든 raw에서 다시 만든다(rp replay). 변환 실패는 조용히 보정하지 않고 사유와 함께 격리한다.

거래 식별자가 없다는 전제에서 정한 정책

사라진 행은 source_missing에 기록하되 "해제"로 해석하지 않는다. 상태를 cancelled / source_missing / superseded로 나눈다. 재수집은 최근 3개월 매 실행 + 과거 월 순환.

트랜잭션 경계 규칙 — 사고 5건 뒤에 코드로 강제

1. 외부 호출(HTTP·LLM·임베딩·Neo4j)은 열린 트랜잭션 안에서 하지 않는다. 읽고 commit()한 뒤 부른다.
2. 시군구·단지·기사 단위 반복 작업은 단위마다 커밋한다.
3. 여러 프로세스가 집는 큐는 FOR UPDATE SKIP LOCKED로 잡고 claimed로 바꿔 커밋한 뒤 처리한다.
4. 실패 기록을 별도 연결로 쓰기 전에 현재 세션을 rollback()한다.
5. 통째로 다시 쓰는 JSON 행은 with_for_update로 잠근다.

외부 API 페이징 사고와 메모리 감시

운영 중 uvicorn이 16.5GB까지 자라 스왑 없는 호스트 전체가 멈췄다. tracemalloc으로 잡은 원인은 VWorld API가 끝을 넘는 pageNo를 오류 없이 마지막 페이지로 되돌려 주는데 len(rows) < 1000으로만 끝을 판정해 같은 페이지를 무한히 이어 붙인 것. totalCount·응답 pageNo·상한으로 끝을 판정하도록 고치고 회귀 테스트를 추가했다. 함께 발견한 httpx.Client 미종료는 정적 검사로 강제. 방어는 두 겹: 컨테이너 mem_limit와 30초 주기 RSS 감시(memwatch.py).

설정으로 소스를 추가하는 구조

# molit-base / molit-trade-base (발췌)
fields:
  price:      { type: money_won, from: dealAmount, transform: [strip_comma, x10000] }
  deal_date:  { type: date, from: [dealYear, dealMonth, dealDay], transform: [ymd_concat] }
  cancelled:  { type: tri_state, from: cdealType, transform: [tri_state] }   # true / false / unknown

커넥터·변환 함수·처리부만 코드로 등록하고 조합은 YAML이 한다. 실행 시 해석된 설정을 config_version으로 고정하고, 관리 UI에서 breaking 변경(타입 변경·삭제)은 acknowledge_breaking 없이는 409로 거부한다.

조회 API 설계와 성능

• 넓은 bbox·낮은 줌은 개별 핀 대신 집계만. 집계값은 화면 안 개체가 아니라 지역 전체로 계산한다.
• 핀·집계는 property_summary 읽기 모델을 쓴다. 세대 공개 시 영향 단지만 재계산. 지도 집계 = 상세 목록 합을 테스트로 검증.
• QA에서 잡은 것: 전국 거래를 훑던 평당가 비교 6~15초 → 시도 한정 + 캐시로 0.13초. 시군구 집계 25초 → LATERAL + OFFSET 0 울타리로 2.9초.
• 공개 API 143케이스 매트릭스에서 500 없음. 검증 오류 문구는 한국어 한 줄로 통일.

뉴스 RAG → GraphRAG → 에이전트

• 뉴스도 같은 파이프라인. 청크(500자/겹침 80) → pgvector(HNSW) → LLM 엔티티·관계 추출(캐시 키 = 청크 해시 + 모델 + 프롬프트 버전). 관계에 출처·근거 문장·신뢰도, 기사 삭제 시 CASCADE 철회.
• Postgres가 정본, Neo4j 5.26은 미러. Neo4j가 꺼져도 재귀 CTE로 동작.
• LLM은 어댑터 하나(complete())로만 호출. 용도별 3트랙(추출은 로컬 Ollama, 답변은 Gemini 무료 티어, 임베딩 로컬). 에이전트는 LangGraph 없이 plan→act→answer, 도구는 읽기 전용, 평가 스크립트로 벡터/그래프/에이전트 비교.

배포와 운영

• deploy_oci.sh: git archive HEAD → 서버에서 api·web 이미지 재빌드 → /api/health 확인. 컨테이너 시작 시 alembic upgrade head.
• compose: postgres(포트 미개방) · neo4j · api(uvicorn workers 1 + 스케줄러, mem_limit) · web(nginx SPA + /api 프록시, index.html no-cache). 앞단 TLS는 서버의 리버스 프록시.
• 백업 pg_dump -Fc 14세대 + 체크섬, 다른 DB에 먼저 복원해 확인하는 절차. rp doctor로 구멍·격리·멈춘 잡·오래된 트랜잭션 점검.

검증 체계

합계 pytest 275건(45파일), ruff + pnpm lint/build.

기술 스택

AI 코딩 도구를 어떻게 썼나

Claude Code를 주 도구로 썼고 설계 검토에는 다른 도구(Codex CLI 등)를 리뷰어로 붙였다. 실제로 효과가 있었던 방식과 한계를 그대로 적는다.

• 문서 먼저, 코드는 그다음. 기획서에 기능마다 ID(TXN-13, LDG-06 …)를 붙이고 새 요청은 문서에 먼저 반영한 뒤 코드를 짰다. 커밋·테스트·RLS 시나리오가 ID로 연결된다. 설계 문서의 "확인 필요"·"제안값"은 검증된 사실이 아니라고 명시하고, 외부 API는 실제 호출로 fixture를 만들어 확인했다.
• 외부 리뷰는 재현한 뒤 반영. 리뷰 도구 두 개에 같은 프롬프트를 주고 지적 28건을 로컬 DB에서 재현해 타당한 것만 반영했다(예: 계정 삭제 시 FK 위반 → on delete set null + 회귀 시나리오). 오판("Dart 'key': ?value는 문법 오류")은 근거를 적고 기각했다.
• 사고를 규칙으로, 규칙을 테스트로. 트랜잭션 교착, 메모리 폭주, 페이징 무한 루프, postgrest .order() 기본 내림차순 같은 함정은 저장소의 CLAUDE.md에 한 줄씩 남기고 정적/런타임 테스트로 강제했다. 다음 세션의 도구가 같은 실수를 하면 테스트가 먼저 잡는다.
• 검증은 도구에 맡기지 않았다. RLS 시나리오는 기대 거부 수를 숫자로 고정해 스크립트가 판정하고, QA는 릴리스 APK와 운영 API를 직접 돌렸다. 도구가 "됐다"고 한 것 중 실제로 안 됐던 것이 여기서 잡혔다.
• 한계. Supabase 부품 셀프호스팅처럼 문서가 얇은 영역, 네이티브 지도 플러그인의 터치 히트 테스트처럼 실측이 필요한 영역에서는 도구도 틀렸고 결국 로그와 시뮬레이터로 확인하며 맞췄다. LLM 무료 티어 한도도 실제로 하루치를 날린 뒤에야 분리했다.