매주 일요일이 지나면, 교회 재정 담당자에게는 또 다른 한 주가 시작된다. 헌금 봉투를 열고, 한 장 한 장 금액을 확인하고, Excel에 옮기고, 분류하고, 보고서를 만들어 이메일로 보낸다. 이 과정이 매주 반복된다.

Oikos Finance는 이 반복을 자동화하기 위해 만든 교회 재정 관리 시스템이다. 헌금 봉투 스캔부터 DB 저장, 보고서 생성, 이메일 발송, 주간 마감까지 — 교회 재정 업무의 전체 흐름을 하나의 시스템으로 묶었다.

왜 만들었나

교회 재정 업무는 생각보다 손이 많이 간다. 매주 수십 건의 헌금을 분류하고, 매월 사례비와 선교비를 정리하고, 분기마다 보고서를 만든다. 대부분의 교회가 아직 Excel 수작업에 의존하고 있고, 시중의 교회 관리 소프트웨어는 비용이 높거나 사용이 번거롭다.

직접 만들면 우리 교회 업무 흐름에 정확히 맞출 수 있다. 불필요한 기능 없이, 실제로 필요한 것만 넣을 수 있다. 그래서 시작했다.

핵심 기능

1. 헌금 OCR 파이프라인

Oikos Finance의 가장 핵심적인 자동화다.

Google Drive에서 헌금 전표 이미지 다운로드
  → Claude Vision API로 OCR (이름 + 금액 인식)
  → 이름 자동 보정
  → 사용자 확인
  → Excel + PostgreSQL DB에 동시 저장
  → Google Drive에 결과물 업로드

여기서 특히 신경 쓴 부분은 이름 보정이다. OCR이 "김영희"를 "김영히"로 인식하는 일이 잦다. 이를 3단계로 보정한다:

  1. 보정 이력: 이전에 "김영히 → 김영희"로 보정한 기록이 있으면 즉시 적용
  2. 교인 명부: 정확히 일치하는 이름이 명부에 있으면 채택
  3. 퍼지 매칭: 한글 자모를 분해해서 유사도 70% 이상이면 후보로 제시

보정 결과는 자동으로 학습되기 때문에, 쓸수록 정확해진다.

2. 수입 관리

주일 헌금뿐 아니라 모든 종류의 수입을 관리한다.

  • 입력 방식: 단건 직접 입력, JSON 대량 입력, Excel 파일 업로드
  • 피벗 테이블 뷰: 카테고리별(십일조, 감사헌금, 절기헌금 등) 집계를 한눈에
  • 교인명 검색: 특정 교인의 전체 헌금 내역을 검색하고 Excel로 다운로드
  • 변경 이력 + 롤백: 모든 수정/삭제 기록이 남고, 언제든 이전 상태로 되돌릴 수 있음

삭제는 소프트 삭제로 처리된다. 실수로 지워도 복구할 수 있다.

3. 지출 관리

지출도 수입과 마찬가지로 체계적으로 관리한다. 여기에 더해 교회 특유의 반복 지출을 자동화했다.

  • 반복 지출 자동화: 매월 고정으로 나가는 사례비, 선교비를 한 번에 일괄 입력
  • 미지급 추적: 연간 예산 대비 실제 지급 현황을 모니터링해서, 아직 입력하지 않은 월정 지출이 있으면 경고
  • 카테고리별 집계: 위원회별(재정위원회, 선교부, 교육부 등) 지출 현황 확인

반복 지출은 연간 예산을 12로 나눈 금액이 기본이지만, 특정 항목은 고정 금액을 별도로 지정할 수 있다.

4. 예산 관리

연간 예산을 편성하고, 실적과 비교 분석한다.

  • 예산 vs 실적: 집행률과 시간 비례 기대률을 비교한다. 2월이면 기대 집행률은 약 17%(2/12). 실제 집행률이 이보다 높으면 초과, 낮으면 미달
  • 전년도 예산 복사: 새해 예산 편성 시 전년도 데이터를 그대로 가져와서 수정
  • 예산 잠금: 확정된 예산을 잠금 처리하면 수정/삭제가 차단됨. 실수로 바뀌는 일을 방지
  • Excel 업로드/다운로드: 기존에 Excel로 관리하던 예산을 그대로 업로드 가능

5. 주간 마감

교회 재정의 정합성을 보장하는 핵심 장치다.

주간 마감은 6단계로 이루어진다:

  1. 데이터 검증: DB와 Excel 데이터를 크로스 체크. 불일치가 있으면 자동으로 재동기화
  2. Google Sheets 업로드: 주간 데이터를 공유 시트에 업로드
  3. 차주 시트 생성: 다음 주 입력용 시트를 미리 만들어둠
  4. 차주 Drive 폴더 생성: 다음 주 헌금 전표 이미지를 넣을 폴더 준비
  5. 이메일 발송: 재정 보고서를 관계자에게 자동 발송
  6. DB 백업: pg_dump로 백업 생성 + 개발용 시드 SQL 동시 생성

마감이 완료된 주차는 잠금 처리된다. API로든 CLI로든 해당 주차의 수입/지출 데이터를 수정할 수 없다. 해제하려면 사유를 반드시 입력해야 하고, 모든 잠금/해제 기록은 감사 로그로 남는다.

실패한 단계가 있으면 --resume 옵션으로 해당 지점부터 재시작할 수 있다.

6. 대시보드 & AI 인사이트

웹에 접속하면 가장 먼저 보이는 대시보드에서 재정 현황을 한눈에 파악한다.

KPI 카드: 월간 수입/지출/잔액 + 연간 예산 달성률을 카드 형태로 표시

6가지 SQL 기반 인사이트:

  • 잔액 요약 + 연간 예산 달성률
  • 예산 초과/미달 카테고리 자동 감지 (5% 허용 범위)
  • 주간 헌금 추세 (상승/하락 방향 감지)
  • 전월 대비 비교 (20% 이상, 50만원 이상 변동 하이라이트)
  • 참여율 분석 (고유 기여자 수, 복귀자 추적)
  • 액션 아이템 (경고/긍정/정보 알림 자동 생성)

LLM 내러티브: 위 데이터를 Gemini 또는 Claude에게 보내서, 자연어로 된 재정 코멘터리를 생성한다. "이번 달 수입은 전월 대비 12% 증가했으며, 특히 감사헌금 카테고리에서 큰 폭의 증가가 있었습니다..." 같은 문장이 자동으로 만들어진다. 결과는 1시간 동안 캐시되어 반복 조회 시 즉시 응답한다.

7. 보고서

보고서 설명
월간 보고서 월별 수입/지출 상세를 Excel로 다운로드
연간 결산 연도 전체 결산 보고서 (월별 피벗 + 예산 대비 실적)
개인별 조회 교인 이름으로 헌금 내역 검색 + Excel 다운로드
전년 대비 전년도 대비 수입/지출 비교 분석

보고서는 웹 UI에서 버튼 클릭으로 다운로드하거나, CLI로도 생성할 수 있다.

8. 관리자 기능

  • DB 백업/복원: pg_dump 기반 백업 생성, 목록 조회, 미리보기(현재 vs 백업 레코드 수 비교), 복원(비밀번호 확인 필요)
  • 사용자 관리: 이메일/비밀번호 인증 + Google OAuth SSO. 역할은 admin(읽기/쓰기)과 user(읽기 전용)
  • 반복 지출 설정: 항목별 활성/비활성 토글, 고정 금액 오버라이드
  • 기능 플래그: AI 인사이트 같은 실험 기능을 on/off

기술 아키텍처

백엔드

  • FastAPI + Python: 50개 이상의 REST API 엔드포인트
  • PostgreSQL 16: 계정 과목(122개) 기반의 정규화된 스키마
  • Repository 패턴: income/expense/budget/weekly_closing 각각 독립된 리포지토리
  • 마이그레이션: SQL 기반 수동 마이그레이션 (init_db.py로 관리)

프론트엔드

  • React + TypeScript: Vite 기반 SPA
  • TanStack Query: 서버 상태 관리
  • Tailwind CSS: 유틸리티 기반 스타일링
  • 키보드 단축키: 1~5 키로 페이지 이동, N으로 신규 입력, /로 검색

인프라

  • Docker Compose: 개발(로컬 PostgreSQL), 운영(ghcr.io 이미지 + pgvector 네트워크)
  • 멀티 테넌트 준비: instance/ 디렉토리로 교회별 설정 분리. 코드와 데이터가 완전히 분리되어 있어, 다른 교회에서도 자체 인스턴스를 운영할 수 있는 구조
  • 575+ 테스트: API 엔드포인트, 리포지토리, 이름 보정, 날짜 유틸, 인사이트 계산 등

CLI + 웹 이중 인터페이스

같은 기능을 CLI와 웹 UI 두 가지로 사용할 수 있다:

  • process_offering.py: OCR → DB 저장 파이프라인 (CLI)
  • close_offering.py: 6단계 주간 마감 (CLI)
  • finance_cli.py: 수입/지출/예산/보고서 전체 (CLI)
  • 웹 UI: 위 기능 대부분을 브라우저에서 (React SPA)

자동화 스크립트는 CLI로, 일상적인 조회와 입력은 웹으로 — 상황에 맞게 선택할 수 있다.

차별점

교회 업무 흐름에 정확히 맞춤

일반적인 회계 소프트웨어는 교회에 맞지 않는 부분이 많다. 헌금은 주 단위로 처리되고, 기여자 이름으로 추적해야 하고, 사례비/선교비 같은 반복 지출 패턴이 있다. Oikos Finance는 이런 교회 고유의 워크플로에 맞춰 설계했다.

OCR로 수작업 제거

헌금 전표 이미지를 Claude Vision으로 읽고, 이름까지 자동 보정한다. 매주 수십 건의 데이터를 손으로 입력하던 작업이 "확인" 한 번으로 줄어든다.

데이터 정합성 보장

주간 마감 잠금, 예산 잠금, 소프트 삭제, 변경 이력 + 롤백. 재정 데이터는 한 번 실수하면 복구가 어렵다는 점을 고려해서, 여러 겹의 안전장치를 두었다.

AI가 숫자를 읽어준다

SQL로 계산한 인사이트에 LLM 내러티브를 더했다. 숫자만 나열하는 대신, "이번 달은 전월 대비 수입이 증가했고, 선교부 지출이 예산의 80%에 도달했습니다"라고 알려준다.

설치형 + 멀티 테넌트

코드와 데이터(instance/)가 분리되어 있어, 교회마다 독립 인스턴스를 운영할 수 있다. Docker 이미지 하나로 어디서든 배포 가능하다.

현재 상태

프로덕션에서 운영 중이다. 매주 헌금 처리, 월정 지출 입력, 보고서 생성, 주간 마감까지 실제 교회에서 사용하고 있다. 아직 개선하고 싶은 부분은 많지만, 핵심 기능은 안정적으로 동작하고 있다.

프로젝트는 오픈소스로 GitHub에 공개되어 있다.