FinPal의 영수증·지출·구독 데이터를 연결하는 방법
영수증의 AI 분석부터 지출 저장까지의 흐름과, 구독 조건이 바뀌어도 결제 기록을 보존하는 데이터 구조를 정리했습니다.
기술 스택
Swift·SwiftUI로 iOS 앱을 만들고 TypeScript·Node.js 22 기반의 Firebase Cloud Functions에서 분석과 저장을 처리했습니다. 데이터는 Firestore에, 영수증 이미지는 Cloud Storage에 저장하며 영수증 분석에는 AI를 사용합니다.
- Swift
- SwiftUI
- TypeScript
- Node.js 22
- Firebase
- Firestore
- Cloud Storage
- AI
영수증 분석부터 지출 기록까지
촬영한 영수증은 서버에서 역할을 나누어 분석합니다. 기본 모드는 요약과 품목을 2개 작업으로 병렬 분석하고 정밀 모드는 품목·금액·가맹점 및 결제 정보를 3개 작업으로 나눕니다. 서버가 결과를 합친 뒤 계산 관계를 검증하고 정규화합니다. 정밀 모드에서는 검증을 통과하지 못한 항목을 골라 추가 분석을 시도합니다.
분석 결과는 앱으로 돌아와 사용자가 확인하고 수정할 수 있습니다. 사용자가 저장하면 별도 서버 함수가 영수증과 지출을 하나의 Firestore 트랜잭션에서 함께 기록합니다. 같은 저장 요청을 다시 보내도 기록이 중복 생성되지 않도록 요청 UUID를 확인합니다.
영수증에는 expenseId를, 지출에는 receiptId를 남겨 두 기록을 연결합니다. 영수증 편집 화면과 연결 지출 편집 화면은 공통 편집 로직을 사용합니다. v2 저장 경로에서는 서버가 소유자·상호 연결·수정 전 값을 확인한 뒤 변경된 공통 정보를 한 트랜잭션에서 갱신합니다. 다른 기기에서 먼저 수정했다면 오래된 값으로 덮어쓰는 요청을 거절합니다.
두 기록의 금액은 결제 방식에 맞게 구분합니다. 영수증은 결제 총액을 보존하고 지출은 상품권·포인트 결제를 차감한 실제 지출액을 기록합니다. 서버가 두 금액의 계산 관계와 통화를 검증하며 화면은 관찰 스트림과 변경 알림으로 저장된 결과를 갱신합니다.
scanReceipt앱에서 영수증 촬영
이미지·분석 모드를 서버에 전송
AI 역할별 병렬 분석
기본 2개 / 정밀 3개
병합·검증·정규화
정밀 모드는 필요한 항목만 추가 분석
앱에서 결과 확인
사용자가 편집 후 저장
submitReceipt확정한 데이터 저장
요청 UUID로 중복 저장 확인
하나의 Firestore 트랜잭션
영수증 Receipt
결제 총액·품목·결제 내역
expenseId연결 지출 ID
지출 Expense
실제 지출액·분류·날짜
receiptId연결 영수증 ID
지출액은 상품권·포인트 결제를 차감해 계산합니다. 영수증의 결제 총액과 항상 같은 값은 아닙니다.
연결 기록을 수정할 때 · v2 경로
영수증 또는 연결 지출 편집
mutateFinancialDataV2서버에서 변경 검증
소유자·원본 값·연결·금액 관계 확인
연결된 두 기록 함께 갱신
변경된 공통 정보를 한 트랜잭션에 반영
구독 조건과 결제 기록의 무결성
구독 정의와 회차별 지출을 구분해 관리합니다. 각 지출에는 구독 ID와 회차 식별자, 조건 버전, 생성 당시의 조건을 함께 저장합니다. 나중에 구독 이름이나 금액이 바뀌어도 과거 지출이 어떤 조건으로 생성됐는지 확인할 수 있습니다.
구독 조건을 수정해도 이미 기록된 지출과 영수증은 보존합니다. 서버는 저장된 시간대와 가격 적용일, 조건 변경 이력을 확인해 도래했지만 아직 기록되지 않은 회차만 생성합니다. 이미 생성했거나 수동으로 수정·삭제한 회차의 근거를 남겨 같은 결제가 다시 생기지 않도록 합니다.
개별 결제 내역을 수정할 때는 선택한 지출과 연결된 영수증의 공통 정보를 함께 갱신합니다. 이 수정으로 구독 정의가 바뀌지는 않습니다. 구독 조건의 변경과 개별 결제 기록의 수정을 구분해 과거 기록의 의미를 유지합니다.
청구 조건의 변경 이력은 원본을 보존하고 일반 계산에는 검증된 요약과 최근 변경분을 사용합니다. 이력을 확인하는 감사 경로도 별도로 유지합니다.
구독 정의·조건 변경 이력
금액·상태·일정·가격 적용일
서버에서 청구 회차 계산
저장된 시간대·적용일·조건 이력 확인
이미 기록된 회차와 수동 수정·삭제 회차는 다시 생성하지 않음
새 지출 Expense
도래했고 아직 기록되지 않은 회차
subscriptionId어느 구독의 결제인지subscriptionOccurrenceKey어느 결제 회차인지subscriptionTermsRevision적용한 조건 버전subscriptionTermsSnapshot생성 당시의 조건
기존 지출·영수증은 보존
구독 조건을 바꾸어도 과거 기록을 일괄 재가격하거나 삭제하지 않습니다.
개별 결제 내역을 수정할 때
선택한 지출·영수증 편집
연결·원본·금액 관계 검증
선택한 연결 쌍만 갱신
구독 정의는 그대로 유지