배당1초

1,500라인 설계 문서로 시작하는 부동산 NPL 자동화 프로젝트

등기부등본 PDF를 1초 만에 분석해 배당금을 계산하는 서비스 '배당1초'의 설계 과정과 SSOT 문서 구조를 소개합니다.

#Dividend1s #docs

30분을 1초로 줄이는 아이디어

부동산 NPL(부실채권) 투자자들이 등기부등본을 분석할 때, 전문가도 엑셀에 권리 내용을 하나씩 입력하며 30분씩 소요한다고 합니다. 이 과정에서 휴먼 에러도 빈번하죠. 배당1초는 이런 반복 작업을 자동화해 PDF 업로드 한 번으로 배당금과 수익률을 즉시 계산해주는 B2B 서비스입니다.

최근 커밋을 보면 흥미로운 점이 있습니다. 코드 한 줄 쓰기 전에 1,500라인이 넘는 설계 문서를 먼저 작성했다는 것이죠. 이런 접근이 왜 필요했는지, 어떤 구조로 설계했는지 살펴보겠습니다.

SSOT 문서 구조로 혼돈 방지하기

프로젝트 초기에 가장 큰 고민은 “여러 서비스가 얽힌 복잡한 시스템을 어떻게 일관성 있게 개발할 것인가”였습니다. Next.js 프론트엔드, Spring Boot API 서버, FastAPI 파싱 서비스가 각각 다른 언어와 패러다임을 사용하면서도 하나의 제품으로 동작해야 하니까요.

해결책으로 SSOT(Single Source of Truth) 방식의 문서 구조를 만들었습니다:

docs/
├── 00-index.md              # 문서 맵 + 변경 이력
├── 01-prd.md                 # 제품 요구사항
├── 02-architecture.md        # 시스템 아키텍처
├── 03-db-schema.md           # DB 스키마 + DDL
├── 04-tech-stack.md          # 기술 스택 제약
├── 05-api-contracts.md       # 서비스 간 API 계약
└── 06-coding-conventions.md  # 코딩 규칙

특히 CLAUDE.md 파일에는 “코드 작성 전 반드시 문서부터 읽을 것”이라는 강제 규칙을 넣었습니다. AI나 팀원이 작업할 때 설계 의도를 벗어나지 않도록 하는 게이트키퍼 역할이죠.

복잡한 법률 로직을 데이터베이스로 모델링

등기부등본 분석에서 가장 까다로운 부분은 배당 순위 계산입니다. 경매 낙찰금을 여러 채권자에게 나눠줄 때 법정 우선순위가 있거든요:

-- 권리 정보를 저장하는 핵심 테이블
CREATE TABLE rights (
    section_type             CHAR(1) CHECK (section_type IN ('A','B')),
    right_type               VARCHAR(50) NOT NULL,
    creditor_name            VARCHAR(200),
    max_claim_amount         BIGINT,
    receipt_date             DATE,
    is_cancelled             BOOLEAN DEFAULT false
    -- ... 기타 20개 컬럼
);

이 테이블 하나에 갑구(소유권 관련)와 을구(담보권 관련) 정보를 모두 담고, receipt_date로 접수일자 순서를 관리합니다. Rule Engine에서 이 데이터를 읽어 “경매집행비용 → 당해세 → 최우선변제금 → 설정일자순 담보물권” 순으로 배당을 계산하죠.

3-레이어 아키텍처와 비동기 처리

시스템 구조는 책임을 명확히 분리했습니다:

  • Frontend (Next.js): 파일 업로드, 결제 UI, 리포트 조회
  • Core API (Spring Boot): 비즈니스 로직, 결제, Rule Engine
  • Parsing Service (FastAPI): PDF 텍스트 추출, OCR, 정형 데이터 변환

PDF 파싱은 시간이 걸리는 작업이라 **Server-Sent Events(SSE)**로 실시간 진행 상황을 전달합니다. 사용자는 “파싱 중… 계산 중…” 단계별 피드백을 받으면서 기다리게 되죠.

Paywall 전략으로 수익 모델 검증

흥미로운 점은 결과를 보기 직전에 결제를 받는 Paywall 구조입니다. 무료로 PDF를 업로드하고 분석까지 끝낸 다음, 최종 리포트 열람 시점에서만 결제하도록 했어요.

계산 완료 → "리포트 보기" 버튼 → 결제 페이지 → PDF 다운로드

이렇게 하면 사용자는 서비스 품질을 먼저 경험하고 결제 결정을 내릴 수 있습니다. 특히 B2B 고객들에게는 “정말 정확한 결과를 주는가?”에 대한 확신이 필요하니까요.

환경변수 관리와 보안 설계

실제 서비스에서는 DB 접속 정보, API 키, 결제 토큰 등 민감한 정보가 많습니다. .env.example 파일로 키 이름만 관리하고 실제 값은 절대 커밋하지 않도록 했어요:

# Core API (Spring Boot)
SPRING_DATASOURCE_URL=
JWT_SECRET=
TOSS_SECRET_KEY=

# Parsing Service (FastAPI)
GOOGLE_VISION_CREDENTIALS=

또한 raw_response JSONB 컬럼에는 “카드번호 등 민감 정보 저장 금지” 규칙을 명시해 결제 관련 보안 이슈를 예방했습니다.

설계 우선 개발의 효과

이런 식으로 코드보다 문서를 먼저 작성한 이유는 복잡성 관리 때문입니다. 등기부등본 파싱 로직, 배당 순위 법률 규칙, 3개 서비스 간 API 통신, 결제-리포트 생성 플로우까지… 머릿속으로만 관리하기엔 너무 복잡하거든요.

특히 이런 금융/법률 도메인에서는 “왜 이렇게 설계했는지” 근거가 중요합니다. 나중에 법률 개정이나 요구사항 변경이 있을 때, 설계 문서가 있으면 영향 범위를 빠르게 파악하고 안전하게 수정할 수 있죠.

앞으로 실제 구현 단계에서 어떤 기술적 도전들이 기다리고 있을지 기대됩니다. PDF 파싱 정확도, Rule Engine 성능, 대용량 처리 등… 설계와 현실의 갭을 어떻게 메워나갈지 지켜봐 주세요.