"마이그레이션" 태그로 연결된 2개 게시물개의 게시물이 있습니다.

1단계: QuickBooks에서 데이터 내보내기​

5년치 데이터를 마이그레이션하는 작업은 모든 QuickBooks 기록을 사용 가능한 형식으로 내보내는 것부터 시작됩니다. QuickBooks Desktop과 QuickBooks Online은 서로 다른 내보내기 옵션을 제공합니다:

1.1 QuickBooks Desktop – 내보내기 옵션​

IIF (Intuit Interchange Format): QuickBooks Desktop은 목록(계정과목표, 고객, 공급업체 등)을 .IIF 텍스트 파일로 내보낼 수 있습니다. QuickBooks Desktop에서 파일 → 유틸리티 → 내보내기 → IIF로 목록 내보내기로 이동한 다음 필요한 목록(예: 계정과목표, 고객, 공급업체)을 선택하세요. 이렇게 하면 계정 이름, 유형 및 목록 데이터가 포함된 텍스트 파일이 생성됩니다. IIF는 독점적이지만 일반 텍스트 형식이므로 분석하기가 비교적 쉽습니다. 이를 사용하여 계정과목표와 연락처 목록을 캡처하여 Beancount에서 참조용으로 사용하세요.

CSV를 통한 총계정원장/분개장: 거래 데이터의 경우 QuickBooks Desktop은 원클릭 전체 내보내기 기능을 제공하지 않지만, 보고서를 사용할 수 있습니다. 권장되는 방법은 원하는 기간 동안의 분개장(모든 거래)을 내보내는 것입니다. QuickBooks Desktop에서 보고서 → 회계 및 세금 → 분개장을 열고, 날짜를 가장 빠른 거래부터 오늘까지로 설정한 다음, 내보내기 → Excel을 클릭하세요. 보고서 머리글/바닥글과 빈 열을 제거한 후 결과를 CSV로 저장하세요. 숫자 데이터가 깨끗한지 확인하세요: 센트 포함(예: 3이 아닌 3.00), 불필요한 따옴표 없음, CSV에 통화 기호나 이중 음수 부호 없음. CSV에는 Date, Trans #, Name, Account, Memo, Debit, Credit, Balance와 같은 열이 있어야 합니다(또는 보고서 형식에 따라 단일 Amount 열).

팁: QuickBooks Desktop 2015+ 버전에서는 찾기 대화상자를 통해서도 거래를 내보낼 수 있습니다. 편집 → 찾기 → 고급을 사용하고, 날짜 범위를 5년으로 설정한 다음, 결과를 CSV로 내보내세요. 경고: 일부 버전에서는 내보내기가 32,768줄로 제한됩니다. 데이터가 매우 큰 경우 잘림을 방지하기 위해 연도별(또는 더 작은 단위)로 내보낸 다음 나중에 결합하세요. 중복을 방지하기 위해 날짜 범위가 겹치지 않도록 하세요.

기타 형식 (QBO/QFX/QIF): QuickBooks Desktop은 .QBO (Web Connect) 또는 .QFX/.OFX 파일을 통해 은행 거래를 가져올 수 있지만, QuickBooks에서 내보내는 데는 일반적이지 않습니다. 목표가 은행 거래만 추출하는 것이라면 이미 은행에서 QBO/OFX 형식으로 가지고 있을 수 있습니다. 하지만 전체 원장 내보내기를 위해서는 IIF와 CSV를 사용하는 것이 좋습니다. QuickBooks Desktop은 타사 도구 없이는 QIF(Quicken Interchange Format)로 직접 내보낼 수 없습니다. 만약 QIF를 얻을 방법을 찾았다면, 일부 원장 도구(구 버전 Ledger 2.x)는 QIF를 읽을 수 있었지만, 저희 파이프라인에서는 CSV로 작업하는 것이 더 낫다는 점을 유의하세요.

1.2 QuickBooks Online – 내보내기 옵션​

내장된 Excel/CSV 내보내기: QuickBooks Online (QBO)은 데이터 내보내기 도구를 제공합니다. 설정 ⚙ → 도구 → 데이터 내보내기로 이동하세요. 내보내기 대화상자에서 보고서 탭을 사용하여 데이터(예: 총계정원장 또는 거래 목록)를 선택하고 목록 탭에서 목록(계정과목표 등)을 선택한 후, 모든 날짜를 선택하고 Excel로 내보내세요. QuickBooks Online은 선택한 보고서 및 목록(예: 손익계산서, 재무상태표, 총계정원장, 고객, 공급업체, 계정과목표 등)에 대한 여러 Excel 파일이 포함된 ZIP 파일을 다운로드합니다. 그런 다음 이 Excel 파일들을 처리하기 위해 CSV로 변환할 수 있습니다.

거래 세부 정보 보고서: QBO의 기본 내보내기에 단일 총계정원장 파일이 포함되지 않은 경우, 수동으로 상세 보고서를 실행할 수 있습니다:

1. 보고서로 이동하여 계정별 거래 세부 정보(또는 일부 QBO 버전에서는 총계정원장)를 찾습니다.
2. 보고 기간을 전체 5년 범위로 설정합니다.
3. 보고서 옵션에서 그룹화 기준 = 없음으로 설정합니다(소계 없이 개별 거래를 나열하기 위해).
4. 열을 사용자 정의하여 최소한 다음을 포함하도록 합니다: 날짜, 거래 유형, 번호, 이름(수취인/고객), 메모/설명, 계정, 차변, 대변(또는 단일 금액 열), 그리고 잔액. 사용했다면 클래스나 위치도 포함합니다.
5. 보고서를 실행한 다음 Excel로 내보내기를 합니다.

이렇게 하면 모든 거래의 상세 원장을 얻을 수 있습니다. 이것을 CSV로 저장하세요. 각 줄은 거래의 한 분개(posting)를 나타냅니다. 나중에 변환을 위해 거래별로 줄을 그룹화해야 합니다.

계정과목표 및 기타 목록: QuickBooks Online은 회계 → 계정과목표 → 일괄 작업 → Excel로 내보내기를 통해 계정과목표를 내보낼 수 있습니다. 계정 이름과 유형을 얻기 위해 이 작업을 수행하세요. 마찬가지로, 메타데이터로 이름을 가져오려면 고객, 공급업체 등을 내보내세요.

QuickBooks Online API (선택 사항): 프로그래밍 방식의 접근을 위해 Intuit는 QBO 데이터용 REST API를 제공합니다. 고급 사용자는 QuickBooks Online 앱을 생성하고(개발자 계정 필요) API를 사용하여 JSON 형식으로 데이터를 가져올 수 있습니다. 예를 들어, Account 엔드포인트를 쿼리하여 계정과목표를, JournalEntry 또는 GeneralLedger 보고서 엔드포인트를 쿼리하여 거래를 가져올 수 있습니다. API를 래핑하는 python-quickbooks와 같은 Python SDK가 있습니다. 그러나 API를 사용하는 것은 OAuth 인증을 포함하며, 자동화를 선호하지 않는 한 일회성 마이그레이션에는 과도한 작업입니다. 대부분의 경우, CSV/Excel로 수동 내보내기하는 것이 더 간단하고 오류가 적습니다.

2단계: 데이터 변환 및 정리​

QuickBooks 데이터를 CSV(및/또는 IIF)로 얻었다면, 다음 단계는 이를 Beancount의 일반 텍스트 원장 형식으로 변환하는 것입니다. 여기에는 내보낸 파일을 파싱하고, QuickBooks 계정을 Beancount 계정과목표에 매핑하며, 거래를 Beancount 구문으로 형식화하는 작업이 포함됩니다.

2.1 Python으로 QuickBooks 내보내기 파일 파싱하기​

Python을 사용하면 변환의 정확성과 재현성을 보장할 수 있습니다. 두 가지 주요 작업인 계정과목표 가져오기와 거래 변환을 위한 스크립트 개요를 설명하겠습니다.

계정 가져오기 및 매핑: 거래를 추가하기 전에 Beancount에서 계정을 설정하는 것이 중요합니다. QuickBooks 계정에는 유형(은행, 매출채권, 비용 등)이 있으며, 이를 Beancount의 계층 구조(자산, 부채, 수익, 비용 등)에 매핑할 것입니다. 예를 들어, 다음과 같은 매핑을 사용할 수 있습니다:

# QuickBooks 계정 유형을 Beancount 루트 카테고리에 매핑
AccountTypeMap = {
    'BANK': 'Assets',
    'CCARD': 'Liabilities',
    'AR': 'Assets',       # 매출채권을 자산으로
    'AP': 'Liabilities',  # 매입채무를 부채로
    'FIXASSET': 'Assets',
    'OASSET': 'Assets',   # 기타 자산
    'OCASSET': 'Assets',  # 기타 유동 자산
    'LTLIAB': 'Liabilities', # 장기 부채
    'OCLIAB': 'Liabilities', # 기타 유동 부채
    'EQUITY': 'Equity',
    'INC': 'Income',
    'EXP': 'Expenses',
    'EXINC': 'Income',    # 기타 수익
    'EXEXP': 'Expenses',  # 기타 비용
}

QuickBooks Desktop IIF 내보내기 파일 또는 QBO의 계정 목록 CSV를 사용하여 각 계정의 이름과 유형을 검색합니다. 그런 다음:

• Beancount 계정 이름 생성: QuickBooks는 때때로 계정 이름에 콜론(:)을 사용하여 하위 계정을 나타냅니다(예: "Current Assets:Checking"). Beancount도 계층 구조에 동일한 콜론 표기법을 사용합니다. 종종 이름을 직접 재사용할 수 있습니다. QuickBooks 계정 이름이 카테고리로 시작하지 않으면 매핑된 카테고리를 앞에 붙입니다. 예를 들어, 유형이 BANK이고 이름이 "Checking"인 QuickBooks 계정은 Beancount에서 Assets:Checking이 됩니다. EXP(비용) 계정 "Meals"는 Expenses:Meals이 됩니다.

• 유효한 이름 지정 보장: Beancount를 혼란스럽게 할 수 있는 문자를 제거하거나 대체합니다. QuickBooks는 이름에 &나 /와 같은 문자를 허용합니다. 특수 문자를 제거하거나 대체하는 것이 좋습니다(예: &를 and로 바꾸고, 슬래시나 공백 제거). 또한, 변환 후 모든 계정 이름이 고유한지 확인하세요. QuickBooks는 다른 상위 계정 아래에 동일한 하위 계정 이름을 허용했을 수 있지만, Beancount에서는 전체 이름(상위 포함)이 고유해야 합니다. 필요한 경우 이름을 바꾸거나 구분자를 추가하여 구별하세요.

• 계정 개설(open) 구문 출력: Beancount에서는 사용되는 모든 계정이 open 지시어로 개설되어야 합니다. 첫 거래 이전 날짜를 선택할 수 있습니다(예: 2019-2023 데이터를 마이그레이션하는 경우 모든 개설에 2018-12-31 또는 더 이른 날짜 사용). 스크립트는 다음과 같은 줄을 작성합니다: 2018-12-31 open Assets:Checking USD 2018-12-31 open Expenses:Meals USD 각 계정에 대해 위와 같이 작성합니다(USD가 주 통화라고 가정). 각 계정에 적합한 통화를 사용하세요(아래 다중 통화 참고).

거래 변환: 가장 큰 과제는 QuickBooks 거래 내보내기 파일(CSV)을 Beancount 항목으로 변환하는 것입니다. 각 QuickBooks 거래(송장, 청구서, 수표, 분개 등)는 여러 개의 분개(줄)를 가질 수 있으며, 이를 하나의 Beancount 거래로 모아야 합니다.

Python의 CSV 리더를 사용하여 내보낸 줄을 반복하고 분개를 누적할 것입니다:

import csv
from collections import defaultdict

# QuickBooks 분개장 CSV에서 모든 줄 읽기
rows = []
with open('quickbooks_exported_journal.csv', 'r', encoding='utf-8') as f:
    reader = csv.DictReader(f)
    for line in reader:
        rows.append(line)

# 거래별로 줄 그룹화('Trans #'가 거래를 식별한다고 가정)
transactions = defaultdict(list)
for line in rows:
    trans_id = line.get('Trans #') or line.get('Transaction ID') or line.get('Num')
    transactions[trans_id].append(line)

이제 transactions는 각 키가 거래 ID/번호이고 값이 해당 거래의 분개 목록인 딕셔너리가 되었습니다. 다음으로, 각 그룹을 Beancount로 변환합니다:

def format_date(qb_date):
    # QuickBooks 날짜는 "12/31/2019"와 같을 수 있음
    m, d, y = qb_date.split('/')
    return f"{y}-{int(m):02d}-{int(d):02d}"

output_lines = []
for trans_id, splits in transactions.items():
    # 필요한 경우 줄 순서대로 분개 정렬 (보통 순서대로 나옴)
    splits = sorted(splits, key=lambda x: x.get('Line') or 0)
    first = splits[0]
    date = format_date(first['Date'])
    payee = first.get('Name', "").strip()
    memo = first.get('Memo', "").strip()
    # 거래 헤더
    output_lines.append(f"{date} * \"{payee}\" \"{memo}\"")
    if first.get('Num'):  # 참조 번호가 있으면 포함
        output_lines.append(f"  number: \"{first['Num']}\"")
    # 각 분개/포스팅 반복
    for split in splits:
        acct_name = split['Account'].strip()
        # QuickBooks 계정 이름을 Beancount 계정으로 매핑 (이전 매핑 사용)
        beancount_acct = account_map.get(acct_name, acct_name)
        # 부호가 있는 금액 결정:
        amount = split.get('Amount') or ""
        debit = split.get('Debit') or ""
        credit = split.get('Credit') or ""
        if amount:
            # 일부 내보내기 파일은 단일 Amount 열을 가짐 (크레딧은 음수)
            amt_str = amount
        else:
            # 별도의 차변/대변 열이 있는 경우
            amt_str = debit if debit else f"-{credit}"
        # 안전을 위해 숫자의 쉼표 제거
        amt_str = amt_str.replace(",", "")
        # 통화 추가
        currency = split.get('Currency') or "USD"
        amt_str = f"{amt_str} {currency}"
        # 분개에 대한 메모/설명
        line_memo = split.get('Memo', "").strip()
        comment = f" ; {line_memo}" if line_memo else ""
        output_lines.append(f"  {beancount_acct:<40} {amt_str}{comment}")
    # 거래 끝 – 빈 줄
    output_lines.append("")

이 스크립트 로직은 다음을 수행합니다:

• 날짜를 Beancount를 위해 YYYY-MM-DD 형식으로 바꿉니다.

• 수취인(Name)과 메모를 거래 설명으로 사용합니다. 예를 들어: 2020-05-01 * "ACME Corp" "Invoice payment" (수취인이 없는 경우 QuickBooks 거래 유형을 사용하거나 수취인을 빈 따옴표로 남길 수 있습니다).

• 참조 번호(수표 번호, 송장 번호 등)가 있는 경우 number 메타데이터를 추가합니다.

• 각 분개 줄을 반복합니다:

  • account_map 딕셔너리(계정과목표 단계에서 채워짐)를 사용하여 QuickBooks 계정 이름을 Beancount 계정으로 매핑합니다.
  • 금액을 결정합니다. 내보내기 파일에 따라 단일 Amount 열(양수/음수 값) 또는 별도의 차변 및 대변 열이 있을 수 있습니다. 위 코드는 두 경우 모두 처리합니다. Beancount에서는 포스팅당 부호가 있는 단일 숫자를 사용하므로 대변이 음수 금액으로 표시되도록 합니다.
  • 통화를 첨부합니다(다른 통화 열이 없는 한 USD로 가정).
  • 계정, 금액 및 줄 메모가 있는 주석과 함께 Beancount 포스팅 줄을 작성합니다. 예를 들어: Assets:Checking 500.00 USD ; Deposit Income:Sales -500.00 USD ; Deposit 이는 $500 입금(수익에서 예금으로)을 반영합니다.

• 모든 분개를 나열한 후 빈 줄로 거래를 구분합니다.

다중 통화 처리: QuickBooks 데이터에 여러 통화가 포함된 경우, 각 포스팅에 통화 코드를 포함하세요(위에서 보인 바와 같이). 외화로 된 계정은 해당 통화로 개설되었는지 확인하세요. 예를 들어, EUR 은행 계좌가 있다면 open Assets:Bank:Checking EUR를 출력하고 해당 계좌의 거래는 EUR를 사용할 것입니다. Beancount는 다중 통화 원장을 지원하며 암묵적인 환산을 추적하지만, 보고서에서 기준 통화로의 환산을 원한다면 환율에 대한 가격 항목을 추가해야 할 수도 있습니다. Beancount 파일 상단에 주 운영 통화를 선언하는 것도 권장됩니다(예: option "operating_currency" "USD").

변환 실행: Python 스크립트(예: qb_to_beancount.py)를 저장하고 내보낸 파일에 대해 실행하세요. 모든 계정과 거래가 포함된 .beancount 파일을 생성해야 합니다.

2.2 특이 사례 및 데이터 정리 처리하기​

변환 중에는 다음과 같은 일반적인 문제점과 해결 방법을 유념해야 합니다:

• 계정 이름 불일치: QuickBooks 계정 이름이 Beancount의 계층적 이름과 충돌할 수 있습니다. 예를 들어, QuickBooks에는 각각 "Insurance"라는 하위 계정을 가진 두 개의 다른 상위 계정이 있을 수 있습니다. Beancount에서 Expenses:Insurance는 고유해야 합니다. 내보내기 전에 하나를 ("Insurance-Vehicle" vs "Insurance-Health")로 이름을 바꾸거나 스크립트에서 고유한 Beancount 계정으로 매핑하여 해결하세요. 일관된 이름 지정 규칙(특수 문자 없음, 계층 구조 사용)은 골칫거리를 줄여줍니다. 필요한 경우 재매핑 파일 접근 방식을 사용하세요: 이전 이름 → 새 Beancount 이름의 CSV 또는 딕셔너리를 유지하고 변환 중에 적용합니다(예제 코드는 account_map을 사용하며 파일에서 재정의를 로드할 수 있습니다).

• 날짜 및 형식: 모든 날짜가 일관되게 형식화되었는지 확인하세요. 위 스크립트는 M/D/Y를 ISO 형식으로 정규화합니다. 또한, 5년 기간이 연말을 넘는 경우 회계 연도 대 달력 연도 문제에 주의하세요. Beancount는 회계 연도 경계를 신경 쓰지 않지만, 나중에 편의를 위해 파일을 연도별로 분할하고 싶을 수 있습니다.

• 수치 정밀도: QuickBooks는 센트 단위로 통화를 처리하므로 센트로 작업하는 것은 보통 괜찮습니다. 모든 금액은 CSV에서 이상적으로 두 자리 소수점을 가져야 합니다. 금액이 정수(소수점 없음)로 바뀌거나 쉼표/괄호(음수용)가 있는 경우 스크립트에서 정리하세요(쉼표 제거, (100.00)를 -100.00으로 변환 등). 지침에 따라 올바르게 CSV를 내보냈다면 이러한 형식 문제는 이미 피했을 것입니다.

• 음수 금액 및 부호: QuickBooks 보고서는 때때로 음수를 -100.00 또는 (100.00)로, 특정 Excel 내보내기에서는 --100.00로 표시하기도 합니다. 정리 단계에서 이를 처리해야 합니다. 각 거래의 차변과 대변이 합계가 0이 되는지 확인하세요. Beancount는 이를 강제합니다(균형이 맞지 않으면 가져오기 시 오류 발생).

• 거래 중복: 거래를 배치로 내보내야 했다면(예: 연도별 또는 계정별), 중복 없이 병합하도록 주의하세요. 한 해의 첫 거래가 이전 배치의 마지막 거래가 아닌지 확인하세요. 경계에서 몇 개의 거래를 실수로 중복하기 쉽습니다. 중복이 의심되면 최종 Beancount 항목을 날짜순으로 정렬하고 동일한 항목을 찾거나, Beancount의 고유한 거래 태그를 사용하여 잡아낼 수 있습니다. 한 가지 전략은 QuickBooks 거래 번호를 메타데이터로 포함하고(예: Trans # 또는 송장 번호를 txn 태그 또는 quickbooks_id 메타데이터로 사용) 해당 ID의 중복이 없는지 확인하는 것입니다.

• 불균형 분개 / 미결산 계정: QuickBooks는 QuickBooks가 "기초자본금" 또는 "이익잉여금"으로 자동 조정한 불균형 거래와 같은 이상한 사례가 있을 수 있습니다. 예를 들어, 초기 계정 잔액을 설정할 때 QuickBooks는 종종 차액을 자본 계정으로 게시합니다. 이것들은 내보낸 거래에 나타날 것입니다. Beancount는 명시적인 균형을 요구합니다. QuickBooks를 모방하기 위해 기초 잔액을 위한 자본 계정(일반적으로 Equity:Opening-Balances)을 도입해야 할 수도 있습니다. 원장의 첫날에 모든 계정의 시작 잔액을 설정하는 기초 잔액 항목을 두는 것이 좋습니다(5단계 참조).

• 다중 통화 특이 사례: 다중 통화를 사용하는 경우, QuickBooks의 내보내기는 모든 금액을 자국 통화 또는 원래 통화로 나열할 수 있습니다. 이상적으로는 각 계정에 대해 원래 통화로 데이터를 얻으세요(QuickBooks Online의 보고서는 보통 그렇게 합니다). Beancount에서는 각 포스팅이 통화를 가집니다. QuickBooks가 환율이나 자국 통화 환산을 제공했다면, 그것들을 무시하고 Beancount의 가격 항목에 의존할 수 있습니다. QuickBooks가 환율을 내보내지 않았다면, 가치 평가를 맞추기 위해 주요 날짜에 대한 가격 기록(예: Beancount의 price 지시어 사용)을 수동으로 추가하고 싶을 수 있습니다. 그러나 기본 원장 무결성을 위해, 거래가 원래 통화로 균형을 맞추는 것만으로도 충분합니다. 미실현 손익은 동일한 보고서를 원하지 않는 한 명시적으로 기록할 필요가 없습니다.

• 매출채권 / 매입채무: QuickBooks는 송장 및 청구서 세부 정보(만기일, 지급 상태 등)를 추적하지만 일반 원장에서는 완전히 이전되지 않습니다. A/R 및 A/P 거래(A/R을 증가시키는 송장, A/R을 감소시키는 지불 등)는 얻을 수 있지만, 송장 문서나 송장별 고객 잔액은 얻을 수 없습니다. 결과적으로, 마이그레이션 후 Beancount의 A/R 및 A/P 계정 잔액이 QuickBooks의 고객/공급업체 미결제 잔액과 동일한지 확인해야 합니다. 송장을 추적해야 하는 경우 Beancount의 메타데이터를 사용할 수 있습니다(예: invoice 태그 또는 링크 포함). QuickBooks 송장 번호는 Num 또는 Memo 필드를 통해 전달되었어야 합니다. 저희 스크립트는 Num을 거래 메타데이터에 number: "..."로 보존합니다.

• 비활성 또는 폐쇄된 계정: IIF 내보내기에는 비활성 계정이 포함될 수 있습니다(포함하도록 선택한 경우). 가져와도 괜찮습니다(거래가 없고 정말 비활성이면 잔액이 0일 것입니다). 마지막 거래 날짜 이후에 Beancount에서 close 지시어로 폐쇄된 것으로 표시할 수 있습니다. 이렇게 하면 원장이 깔끔하게 유지됩니다. 예를 들어: 2023-12-31 close Expenses:OldAccount ; closed after migration 이것은 선택 사항이며 주로 깔끔함을 위한 것입니다.

위와 같이 데이터를 신중하게 정리하고 매핑함으로써, 구조적으로 QuickBooks 데이터를 미러링하는 Beancount 원장 파일을 갖게 될 것입니다. 다음 단계는 그것이 수치적으로도 QuickBooks를 미러링하는지 확인하는 것입니다.

3단계: 데이터 검증 및 조정​

검증은 회계 데이터 마이그레이션에서 매우 중요한 단계입니다. Beancount 원장이 QuickBooks 장부와 한 푼도 틀림없이 일치하는지 확인해야 합니다. 여러 전략과 도구를 사용할 수 있습니다:

3.1 시산표 조정​

시산표 보고서는 모든 계정의 기말 잔액(차변과 대변 또는 양수/음수로 표시)을 나열하며 합계가 0이 되어야 합니다. 두 시스템에서 동일한 날짜에 대한 시산표를 실행하는 것이 전반적인 정확성을 확인하는 가장 빠른 방법입니다.

• QuickBooks에서: 마지막 해의 마지막 날(예: 2023년 12월 31일)에 대한 시산표 보고서를 실행하세요. 이 보고서는 각 계정의 잔액을 보여줍니다. 내보내거나 주요 수치를 기록해 두세요.

• Beancount에서: Beancount의 보고 기능을 사용하여 시산표를 생성하세요. 쉬운 방법 중 하나는 명령줄을 이용하는 것입니다:

  bean-report migrated.beancount balances
  

  balances 보고서는 모든 계정과 그 잔액을 나열하는 시산표입니다. Fava(Beancount의 웹 UI)에서 파일을 열고 잔액 또는 재무상태표 섹션을 볼 수도 있습니다. Beancount의 모든 계정 잔액은 QuickBooks 시산표와 일치해야 합니다. 예를 들어, QuickBooks가 *매출채권 = $5,000*를 표시하면 Beancount의 Assets:Accounts Receivable 계정의 합계는$5,000(차변)이 되어야 합니다. *매출 수익 = $200,000*이면 Beancount의 Income:Sales는$200,000(대변)를 보여주어야 합니다 (대변을 음수로 표시하는 시산표를 사용하면 -200,000으로 표시될 수 있음).

불일치가 있는 경우, 원인을 찾아내세요:

• 계정 전체가 누락되었거나 추가되었는지 확인하세요(계정을 잊었거나 마이그레이션 기간 전에 이미 폐쇄된 계정을 포함했는지?).
• 잔액이 틀리면, 더 깊이 파고드세요: QuickBooks는 해당 계정에 대한 계정 빠른 보고서 또는 원장 세부 정보를 실행할 수 있으며, Beancount의 해당 계정 원장(bean-report migrated.beancount register -a AccountName)과 비교할 수 있습니다. 때로는 누락된 거래나 중복으로 인해 차이가 발생합니다.

또한 Beancount의 시산표에서 모든 계정의 합계가 0인지 확인하세요(0 또는 0에 매우 가까워야 하는 총계를 인쇄합니다). Beancount는 복식 부기를 강제하므로, 0이 아닌 불균형이 있다면 자산에서 부채-자본을 뺀 값이 0이 되지 않았음을 의미하며, 이는 문제를 나타냅니다(QuickBooks도 보통 허용하지 않지만 데이터가 일부 누락되면 발생할 수 있음).

3.2 계정 잔액 비교​

시산표 외에도 특정 재무제표를 비교할 수 있습니다:

• 재무상태표: QuickBooks 재무상태표를 마지막 날짜에 대해 실행하고 Beancount 재무상태표(bean-report migrated.beancount balsheet)를 실행하세요. 이는 시산표와 유사하지만 자산, 부채, 자본별로 정리되어 있습니다. 숫자는 범주별로 일치해야 합니다. 더 세분화된 확인을 위해 주요 계정 총액(현금, A/R, 고정 자산, 매입채무, 자본 등)을 비교하세요.

• 손익계산서: QuickBooks와 Beancount에서 5년 기간(또는 연도별)에 대한 손익계산서를 실행하세요(bean-report migrated.beancount income은 전체 기간 손익계산서). Beancount의 순이익은 각 기간 동안 QuickBooks와 동일해야 합니다. 5년 전체를 마이그레이션했다면 누적 순이익이 일치해야 합니다. 또한 개별 수익 및 비용 총액을 비교하여 누락되거나 중복된 범주가 없는지 확인할 수 있습니다.

• 무작위 거래 샘플링: 몇 개의 무작위 거래(특히 각 연도 및 각 주요 계정에서)를 선택하여 올바르게 마이그레이션되었는지 확인하세요. 예를 들어, 3년 전의 송장을 QuickBooks에서 찾은 다음 Beancount 파일에서 그 금액이나 메모를 검색하세요(모든 거래가 텍스트이므로 .beancount 파일을 텍스트 편집기에서 열거나 검색 도구를 사용할 수 있음). 날짜, 금액 및 계정이 일치하는지 확인하세요. 이는 날짜 형식 문제나 잘못 매핑된 계정을 찾는 데 도움이 됩니다.

3.3 자동 무결성 검사​

Beancount 자체의 검증 도구를 활용하세요:

• bean-check: bean-check migrated.beancount를 실행하세요. 이 명령은 파일을 파싱하고 구문이나 잔액 오류를 보고합니다. 스크립트가 개설되지 않은 계정이나 균형이 맞지 않는 거래와 같은 것을 놓쳤다면 bean-check가 이를 표시할 것입니다. 깨끗한 통과(출력 없음)는 파일이 최소한 내부적으로 일관성이 있다는 것을 의미합니다.

• 잔액 검증(Balance Assertions): 추가적인 확인을 위해 주요 계정에 대한 명시적인 잔액 검증을 원장에 추가할 수 있습니다. 예를 들어, 특정 날짜의 은행 계좌 잔액을 알고 있다면 다음과 같은 줄을 추가하세요: 2023-12-31 balance Assets:Bank:Checking 10000.00 USD 그러면 bean-check는 원장에서 해당 날짜에 잔액이 실제로 $10,000인지 확인할 것입니다. 이것은 선택 사항이지만 중요도가 높은 계정에 유용할 수 있습니다. QuickBooks에서 기말 잔액(예: 각 연말)을 가져와 Beancount 파일에서 검증할 수 있습니다. 검증에 실패하면 Beancount가 차액을 보고합니다.

• 시산표 롤포워드: 선호한다면, 기간별 확인을 할 수 있습니다. 각 연도에 대해 순 변화를 비교하세요. 예를 들어, QuickBooks 2020년 순이익 대 Beancount 2020년 순이익 등을 비교하여 각 연도가 자본으로 제대로 마감되었는지 확인합니다(QuickBooks는 매년 순이익을 이익잉여금으로 자동 이월합니다. Beancount에서는 누적 자본만 보게 될 것입니다). 차이가 보인다면 특정 연도 데이터에 문제가 있음을 나타낼 수 있습니다.

• 거래 수 및 중복: QuickBooks 대 Beancount의 거래 수를 세어보세요. QuickBooks는 직접적인 수를 쉽게 보여주지 않지만, CSV의 줄 수를 세어(각 거래 헤더 대 분개) 가늠할 수 있습니다. Beancount에서는 파일에서 txn 또는 * "의 발생 횟수를 세는 것이 빠른 방법입니다. QuickBooks와 같거나 약간 높아야 합니다(기초 잔액 거래나 조정을 추가한 경우). 상당한 불일치는 무언가 생략되었거나 중복되었을 수 있음을 의미합니다. 메타데이터에 고유 ID를 사용하면 도움이 될 수 있습니다. 중복이 의심되면 Beancount 파일에서 동일한 수표 번호나 송장 번호가 두 번 나타나는지 검색해 보세요.

• 대사 상태: 저희 스크립트에서는 QuickBooks의 확인된 상태에 따라 rec: "y" 또는 "n" 메타데이터를 포함했습니다(예제에서 rec로). 이것은 표준 Beancount 기능은 아니지만(Beancount는 Ledger와 같은 방식으로 확인/미결제 상태를 추적하지 않음), 유용한 메타데이터가 될 수 있습니다. QuickBooks에서 대사된 모든 거래가 있는지 확인할 수 있습니다. 궁극적으로 Beancount에서 은행 계좌를 새로 대사하는 것(명세서 사용)이 누락된 것이 없다는 최종 증거가 될 수 있습니다.

이러한 검증을 수행함으로써, 마이그레이션이 데이터를 보존했다는 확신을 가질 수 있습니다. 이 단계에 시간을 충분히 할애하세요 – 몇 달 후 장부에 의존하게 될 때보다 지금 이상 현상을 수정하는 것이 더 쉽습니다. 검증 실패 시 일반적인 문제는 계정의 기초 잔액 누락, 범위를 벗어난 날짜의 거래, 또는 항목의 부호 반전 등입니다. 모두 식별되면 수정할 수 있습니다.

4단계: Beancount 원장으로 커밋하기​

정리 및 검증 후에는 데이터를 Beancount 원장 구조로 공식화할 차례입니다. 여기서 "커밋"이란 원장 파일을 최종화하고 감사 가능성을 위해 버전 관리 시스템에 체크인하는 것을 의미합니다.

4.1 원장 파일 및 구성 정리하기​

Beancount 원장 파일을 어떻게 구성할지 결정하세요. 5년치 데이터의 경우 모든 것을 한 파일에 보관하거나 연도별 또는 카테고리별로 분할할 수 있습니다. 일반적이고 명확한 구조는 다음과 같습니다:

• 메인 원장 파일: 예: ledger.beancount – 이것은 다른 파일을 include할 수 있는 진입점입니다. 전역 옵션을 포함하고 연간 파일을 포함할 수 있습니다.
• 계정 파일: 계정과목표와 기초 잔액을 정의합니다. 예를 들어, 모든 open 지시어가 있는 accounts.beancount(스크립트에 의해 생성됨). 여기에 상품(통화)을 나열할 수도 있습니다.
• 거래 파일: 연도별로 하나씩, 예: 2019.beancount, 2020.beancount 등, 해당 연도의 거래를 포함합니다. 이렇게 하면 각 파일을 관리 가능한 크기로 유지하고 필요할 때 특정 연도에 집중할 수 있습니다. 또는 엔티티나 계정별로 분할할 수도 있지만, 시간 기반 분할이 금융 데이터에 직관적입니다.

메인 파일 예시:

option "title" "내 사업 원장"
option "operating_currency" "USD"

include "accounts.beancount"
include "2019.beancount"
include "2020.beancount"
...
include "2023.beancount"

이렇게 하면 보고서를 실행할 때 모든 데이터가 집계되지만, 순서를 유지할 수 있습니다.

Beancount는 여러 파일을 요구하지 않으므로 하나의 큰 파일을 가질 수도 있지만, 위 구조는 명확성과 버전 관리를 향상시킵니다. Beancount 모범 사례에 따르면, 명확한 섹션 헤더를 사용하고 관련 항목을 논리적으로 그룹화하는 것이 좋습니다.

4.2 기초 잔액 및 자본 설정하기​

마이그레이션이 절대적인 0에서 시작하는 것이 아니라면, 기초 잔액을 처리해야 합니다. 두 가지 시나리오가 있습니다:

• 처음부터 시작하는 장부: 5년 기간이 사업 시작 시점부터 시작한다면(예: 2019년 1월에 모든 계정이 0이고 초기 자본만 있는 상태에서 QuickBooks 사용 시작), 별도의 기초 잔액 거래가 필요하지 않을 수 있습니다. 2019년의 첫 거래(은행 계좌로의 초기 자금 조달 등)가 자연스럽게 시작 잔액을 설정할 것입니다. 초기 자본금이나 이전 이익잉여금이 자본 거래를 통해 회계 처리되었는지 확인하기만 하면 됩니다.

• 중간부터 시작하는 장부(부분 이력): QuickBooks를 더 일찍 시작했고 2019년이 중간 지점이라면, 2019년 1월 1일 기준으로 각 계정에는 이월된 잔액이 있었습니다. QuickBooks는 이를 기초 잔액 또는 이익잉여금으로 가지고 있었을 것입니다. Beancount에서는 시작 날짜 전날에 기초 잔액 항목을 만드는 것이 일반적입니다:

  • Equity:Opening-Balances(또는 유사한 이름)라는 자본 계정을 사용하여 모든 기초 금액의 합계를 상쇄합니다.
  • 예: 2018년 12월 31일에 현금이 $10,000, A/R이$5,000, A/P가 $3,000(대변)이었다면 다음과 같은 거래를 작성합니다: `2018-12-31 * "기초 잔액"` `Assets:Cash 10000.00 USD` `Assets:Accounts Receivable 5000.00 USD` `Liabilities:Accounts Payable -3000.00 USD` `Equity:Opening-Balances -12000.00 USD` 이렇게 하면 Opening-Balances는 음수 합계(-$12k)를 가지게 되어 항목의 균형을 맞춥니다. 이제 모든 자산/부채 계정은 2019년을 올바른 잔액으로 시작합니다. 이것은 QuickBooks의 "이익잉여금"이나 이월 잔액을 반영해야 합니다.
  • 또는 Beancount의 pad와 balance 지시어를 사용합니다: 각 계정에 대해 Opening-Balances에서 pad하고 잔액을 balance로 검증할 수 있습니다. 이것은 더 자동화된 방법입니다. 예를 들어: 2018-12-31 pad Assets:Cash Equity:Opening-Balances 2018-12-31 balance Assets:Cash 10000.00 USD 이는 Beancount에게 해당 날짜에 현금이 10000 USD가 되도록 필요한 항목(Opening-Balances로)을 삽입하라고 지시합니다. 각 계정에 대해 이 작업을 수행하세요. 결과는 비슷하지만, 첫 번째 방법처럼 명시적인 거래를 작성하는 것도 간단합니다.

• 이익잉여금: QuickBooks는 "이익잉여금" 거래를 명시적으로 내보내지 않으며, 단지 계산만 합니다. 마이그레이션 후, 생성하지 않았다면 Equity:Retained Earnings가 0인 것을 발견할 수 있습니다. Beancount에서 이익잉여금은 단지 이전 연도들의 이익입니다. 이익잉여금 계정을 만들어 매년 첫날에 이전 이익을 이체하거나, 자본이 모든 수익/비용의 합이 되도록 할 수 있습니다(보고서의 자본 섹션에 나타남). 투명성을 위해 일부 사용자는 매년 마감 분개를 합니다. 이것은 선택 사항이며 주로 표현을 위한 것입니다. 모든 거래를 마이그레이션했으므로, 매년 이익은 연간 보고서를 실행하면 자연스럽게 합산될 것입니다.

• 비교 검사: 기초 잔액을 설정한 후, 시작 날짜에 재무상태표를 실행하여 모든 것이 올바른지 확인하세요(기초 잔액 대 기초 자본이 상쇄되어 0이 되는 것을 보여야 함).

4.3 최종화 및 버전 관리​

이제 데이터가 Beancount 형식으로 정리되고 구조화되었으므로, 파일을 버전 관리 저장소(예: git)에 커밋하는 것이 현명합니다. 원장에 대한 각 변경 사항을 추적할 수 있으며, 모든 수정 사항에 대한 감사 추적을 가질 수 있습니다. 이것은 일반 텍스트 회계의 주요 장점입니다. 예를 들어, QuickBooks에서는 변경 사항을 쉽게 비교(diff)할 수 없지만, Beancount에서는 줄 단위 차이를 볼 수 있습니다. 일부 사용자들이 언급했듯이, Beancount를 사용하면 투명성을 얻고 필요할 때 변경 사항을 되돌릴 수 있는 능력을 갖게 됩니다. 모든 항목은 변경 이력에 연결될 수 있습니다.

이 초기 마이그레이션의 커밋을 v1.0 등으로 태그를 지정하여 QuickBooks에서 가져온 책의 상태를 나타내도록 하세요. 앞으로는 Beancount에 직접 새로운 거래를 입력하거나(또는 은행 피드에서 가져오기 등), 일반적인 소프트웨어 개발 관행(매월 또는 매일 커밋, 실험을 위한 브랜치 사용 등)을 사용할 수 있습니다.

Fava 또는 다른 도구 설정: Fava는 Beancount용 웹 인터페이스로 보고서를 쉽게 볼 수 있게 해줍니다. 커밋 후 fava ledger.beancount를 실행하여 재무제표를 탐색하고 QuickBooks 보고서와 마지막으로 한 번 더 비교하세요. UI에서는 작은 차이점을 더 쉽게 발견할 수 있습니다(예: 0이어야 할 계정이 작은 잔액을 보이는 것은 마감 항목이 누락되었거나 잘못된 거래가 있음을 나타냄).

이름 지정 규칙 및 일관성: 이제 완전한 통제권을 가졌으므로 일관성을 확보하세요:

• 모든 계정은 대문자 카테고리 이름(Assets, Liabilities 등)으로 시작하는 명확한 이름을 가져야 합니다. 이상하게 보이는 것이 있다면(예: QuickBooks의 대소문자 불일치로 인한 Assets:assets:SomeAccount), 계정 파일에서 이름을 바꾸고 거래를 업데이트하세요(파일에서 빠른 찾기/바꾸기를 하거나 Beancount의 bean-format 또는 편집기의 다중 커서 사용).
• 상품 기호(통화 코드)는 일관성이 있어야 합니다. USD의 경우 모든 곳에서 USD를 사용하세요($나 US$가 아님). 다른 통화의 경우 표준 코드(EUR, GBP 등)를 사용하세요. 이 일관성은 Beancount의 가격 조회 및 보고서에 중요합니다.
• 생성되었을 수 있는 임시 또는 더미 계정을 제거하세요(예: 스크립트에서 알 수 없는 계정을 위해 Expenses:Miscellaneous를 포괄적으로 사용했다면, 모든 계정을 올바르게 매핑하여 제거하도록 노력하세요).

QuickBooks 닫기: 이 시점에서 QuickBooks와 일치하는 병렬 장부를 Beancount에 가지고 있어야 합니다. 일부는 누락된 것이 없는지 확인하기 위해 짧은 기간 동안 두 시스템을 병행하여 실행하기도 합니다. 그러나 검증이 확실하다면 QuickBooks 장부를 "닫을" 수 있습니다:

• 이것이 기업 환경이라면, QuickBooks 원본 문서(송장, 청구서, 영수증)를 모두 기록용으로 내보내는 것을 고려하세요. 수동으로 첨부하지 않는 한 Beancount에는 존재하지 않을 것입니다.
• QuickBooks 데이터의 백업(회사 파일과 내보내기 파일 모두)을 보관하세요.
• 앞으로는 Beancount 원장을 기본 기록 시스템으로 유지하세요.

Beancount 원장에 데이터를 커밋함으로써 마이그레이션 파이프라인을 완료했습니다. 마지막 단계는 감사 및 재무제표의 일관성을 입증하여, 마이그레이션이 성공적이었음을 자신(그리고 모든 이해관계자나 감사인)에게 만족시키는 것입니다.

5단계: 마이그레이션 후 감사 및 예시​

마이그레이션의 성공을 입증하기 위해, 재무제표의 전후 비교와 가능한 경우 거래의 차이(diff)를 준비하세요. 이는 장부가 일관성이 있다는 증거를 제공합니다.

5.1 재무제표 검증​

QuickBooks와 Beancount 모두에서 동일한 날짜에 대한 주요 재무 보고서를 생성하고 비교하세요:

• 2023년 12월 31일 기준 재무상태표: 자산, 부채, 자본 총액을 줄 단위로 비교하세요. 일치해야 합니다. 예를 들어, QuickBooks가 총 자산 = $150,000** 및 **총 부채 + 자본 =$150,000를 보였다면, Beancount 재무상태표도 동일한 총액을 보여야 합니다. 계정을 약간 다르게 구성했다면(예: 일부 하위 계정을 병합했다면), 비교 시 이를 조정하거나 다음 수준으로 세분화하여 합계가 동일한지 확인하세요.

• 2019–2023 손익계산서: 각 연도(또는 전체 기간)의 총 수익, 총 비용, 순이익이 동일한지 확인하세요. QuickBooks가 보고서에서 일부 반올림을 했다면 사소한 차이가 발생할 수 있지만, 거래는 보통 센트 단위까지 정확하게 전달되므로 순이익은 정확해야 합니다. 특정 연도의 이익이 다른 경우, 해당 연도의 데이터를 자세히 살펴보세요. 종종 해당 기간의 누락 또는 중복 항목을 나타내는 지표입니다.

• 시산표 차이: 가능하다면, 각 계정과 QuickBooks 대 Beancount의 잔액을 나열하는 스프레드시트를 만드세요. 일치할 것으로 예상되므로, 차이 열은 모두 0이 될 수 있습니다. 이것은 본질적으로 우리가 논의한 시산표 교차 확인이지만, 작성해 두면 문서화에 도움이 됩니다.

5.2 예시 비교 (전 vs 후)​

아래는 데이터 일관성을 보여주는 예시 스니펫입니다. 2023년 12월 31일의 QuickBooks 시산표가 다음과 같다고 가정해 봅시다:

Beancount에서 2023년까지 모든 거래를 가져오고 게시한 후, bean-report balances(시산표)는 다음을 출력합니다:

(참고: 자본 섹션은 다르게 구성될 수 있습니다. 중요한 것은 총액이 일치한다는 것입니다. 여기서 Beancount의 "Profit (2019-2023)"은 당기 순이익/이익잉여금을 합친 역할을 하며, 이익이 이익잉여금으로 마감되었기 때문에 0을 보여줍니다.)

보시다시피, 모든 계정이 센트 단위까지 일치합니다. 양쪽 모두 차변의 합계와 대변의 합계가 같습니다.

또한, 2023년 손익계산서를 실행하면:

• QuickBooks: 수익 $50,000, 비용$48,000, 순이익 $2,000.
• Beancount: 수익 $50,000, 비용$48,000, 순이익 $2,000 (이후 이익잉여금으로 마감되거나 연말 재무상태표의 자본 항목 아래에 나타남).

필요하다면 거래의 차이(diff)를 생성할 수 있지만, QuickBooks 데이터는 원장 형태가 아니므로 보고서에 의존하는 것이 더 효과적입니다. QuickBooks CSV와 Beancount 거래를 모두 날짜순으로 정렬하고 주요 필드를 비교하는 것을 최종 확인으로 할 수 있습니다(Excel이나 스크립트로 가능). 그러나 이전 검증을 신뢰한다면, 재무제표 확인만으로도 보통 충분합니다.

5.3 감사 팁​

• 감사인이나 이해관계자가 확신을 필요로 한다면, 전후 재무제표를 나란히 제시하세요. Beancount의 투명성은 실제로 감사를 단순화할 수 있습니다. 왜냐하면 재무제표의 모든 숫자를 원본 항목까지 신속하게 추적할 수 있기 때문입니다(특히 Fava의 드릴다운 기능 사용).
• QuickBooks 백업과 내보낸 CSV를 감사 추적의 일부로 보관하세요. 마이그레이션 중에 이루어진 모든 조정 사항을 문서화하세요(예: "일관성을 위해 계정 X를 Y로 이름 변경" 또는 "명확성을 위해 거래 Z를 두 항목으로 분할" 등).
• 앞으로는 Beancount에서 정기적인 확인을 구현하세요. 예를 들어, 은행 계좌의 월별 대사와 기말 잔액 검증은 데이터 문제나 입력 실수를 잡는 데 도움이 됩니다. 마이그레이션은 좋은 기준선을 제공합니다. 새로운 시스템에서 규율을 유지하면 지속적인 정확성을 보장할 수 있습니다.

마지막으로, 마이그레이션 완료를 축하하세요: QuickBooks에서 Beancount로 5년간의 회계 데이터를 성공적으로 이전했습니다. 이제 데이터는 완벽한 복식 부기 무결성을 갖춘 가볍고 버전 관리되는 텍스트 형식으로 존재합니다. 데이터를 내보내고, Python 스크립트로 변환하고, 시산표와 보고서를 통해 무결성을 검증했으며, 잘 정리된 Beancount 원장으로 커밋했습니다. 이 포괄적인 과정은 Beancount 원장이 5년 동안 QuickBooks 장부의 정확하고 충실한 복제본임을 보장하며, 앞으로의 회계 작업을 간소화할 수 있도록 준비시켜 줍니다.

사고 요약​

2021-08-03 오후 2시 35분 PST에 엔지니어 한 명이 잘못된 데이터베이스 마이그레이션을 수행하여 인덱싱된 데이터와 데이터베이스의 실제 데이터 간에 불일치가 발생했습니다. 이는 39명의 사용자에게 영향을 미쳤으며, 우리는 데이터를 재입력하고 오후 4시 46분 PST에 문제를 해결했습니다.

영향​

영향을 받은 39명의 사용자는 2021-08-03 오후 2시 35분 PST부터 오후 4시 46분 PST 사이에 추가된 데이터를 잃을 수 있습니다. 우리는 데이터를 재입력했지만 100% 복구를 보장할 수 없습니다.

근본 원인​

근본 원인은 파일 구조를 재구성하고 Dropbox 통합을 준비하기 위한 새로운 데이터베이스 마이그레이션입니다. 안타깝게도 배포 중 이 서비스를 이용하는 사용자 수를 과소평가했습니다.

교훈​

다음에 유사한 상황이 발생하면 우리는

1. 데이터베이스 마이그레이션에 더욱 신중을 기할 것입니다. 마이그레이션 중에도 데이터 삽입이 발생한다는 점을 인지합니다.
2. 모든 트래픽과 경쟁 조건을 중단해야 할 경우 사이트를 유지보수 모드로 전환합니다.