# QuickBooksからBeancountへの移行ガイド

## ステージ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には、_日付、取引番号、名前、勘定科目、メモ、借方、貸方、残高_（またはレポート形式によっては単一の金額列）などの列が必要です。

> **ヒント:** 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として保存します。各行は取引の1つの明細（仕訳）を表します。後で変換のために、取引ごとに行をグループ化する必要があります。

**勘定科目表およびその他のリスト:** QuickBooks Onlineでは、**[会計] → [勘定科目表] → [一括処理] → [Excelにエクスポート]** を介して勘定科目表をエクスポートできます。これを行って勘定科目名とタイプを取得します。同様に、メタデータ用に名前を転送したい場合は、顧客、ベンダーなどもエクスポートします。

**QuickBooks Online API (オプション):** プログラムによるアプローチとして、IntuitはQBOデータ用のREST APIを提供しています。上級ユーザーは、QuickBooks Onlineアプリケーションを作成し（開発者アカウントが必要）、APIを使用してデータをJSONで取得できます。たとえば、`Account`エンドポイントで勘定科目表を、`JournalEntry`または`GeneralLedger`レポートエンドポイントで取引を照会できます。`python-quickbooks`のようなPython SDKがAPIをラップしています。ただし、APIの使用にはOAuth認証が必要であり、自動化を好む場合を除き、一度きりの移行には過剰です。ほとんどの場合、**CSV/Excelへの手動エクスポートの方が簡単でエラーが発生しにくい**です。

---

## ステージ2：データの変換とクリーンアップ

QuickBooksのデータをCSV（および/またはIIF）で取得したら、次のステップはそれをBeancountのプレーンテキスト元帳形式に変換することです。これには、エクスポートの解析、QuickBooksの勘定科目をBeancountの勘定科目表にマッピングし、取引をBeancountの構文にフォーマットすることが含まれます。

### 2.1 PythonによるQuickBooksエクスポートの解析

Pythonを使用することで、変換の正確性と再現性が保証されます。ここでは、2つの主要なタスクのためのスクリプトを概説します：**勘定科目表のインポート**と**取引の変換**です。

**勘定科目のインポートとマッピング:** 取引を追加する前に、Beancountで勘定科目を設定することが重要です。QuickBooksの勘定科目にはタイプ（銀行、売掛金、費用など）があり、これらをBeancountの階層（資産、負債、収益、費用など）にマッピングします。たとえば、次のようなマッピングを使用できます：

```python
# 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では、サブ勘定を示すためにコロン（`:`）を使用することがあります（例："流動資産:当座預金"）。Beancountも階層に同じコロン表記を使用します。多くの場合、名前を直接再利用できます。QuickBooksの勘定科目名がカテゴリで始まらない場合は、マッピングされたカテゴリを先頭に追加します。たとえば、`BANK`タイプのQuickBooks勘定科目 "当座預金" は、Beancountでは `Assets:当座預金` になります。`EXP`（費用）勘定の "食事代" は `Expenses:食事代` になります。

- **有効な名前の確保:** Beancountを混乱させる可能性のある文字を削除または置換します。QuickBooksでは `&` や `/` などの文字が名前に使用できます。特殊文字を削除または置換する（例：`&` を `and` に置き換える、スラッシュやスペースを削除する）のが賢明です。また、変換後、**すべての勘定科目名が一意であること**を確認してください。QuickBooksでは、異なる親の下で同じサブ勘定名が許可されている場合がありますが、Beancountでは完全な名前（親を含む）が一意でなければなりません。必要に応じて、名前を変更するか、区別するための修飾子を追加します。

- **勘定開設の生成:** 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リーダーを使用して、エクスポートされた行を反復処理し、明細を蓄積します：

```python
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)

# 取引ごとに行をグループ化する（'取引番号'が取引を識別すると仮定）
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に変換します：

```python
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:
            # 一部のエクスポートは単一の金額列を持つ（貸方は負）
            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形式にフォーマットします。
- 受取人（名前）とメモを取引の説明に使用します。例：
  `2020-05-01 * "ACME Corp" "請求書の支払い"`
  （受取人がない場合、QuickBooksの取引*タイプ*を使用するか、受取人を空の引用符で囲むことができます）。
- 参照番号（小切手番号、請求書番号など）がある場合は、`number`メタデータを追加します。
- 各明細行を反復処理します：
  - `account_map`辞書を使用して、QuickBooksの勘定科目名をBeancountの勘定にマッピングします（勘定科目表のステップで作成）。
  - 金額を決定します。エクスポートによっては、単一の*金額*列（正/負の値）または別々の借方と貸方列がある場合があります。上記のコードは両方のケースを処理します。貸方がBeancountの負の金額として表されることを確認します（Beancountでは、仕訳ごとに1つの符号付き数値が使用されるため）。
  - 通貨を付加します（別の通貨列がない限りUSDと仮定）。
  - 勘定、金額、および行メモのコメントを含むBeancountの仕訳行を書き込みます。例：
    ` Assets:Checking                         500.00 USD  ; 預金`
    ` Income:Sales                          -500.00 USD  ; 預金`
    これは\$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には2つの異なる親勘定があり、それぞれに "保険" という名前のサブ勘定があるかもしれません。Beancountでは、`Expenses:Insurance` は一意でなければなりません。これを解決するには、**エクスポート前**に一方の名前を変更する（例：「保険-車両」vs「保険-健康」）か、スクリプトで一意のBeancount勘定にマッピングします。一貫した命名規則（特殊文字なし、階層の使用）は頭痛の種を減らします。必要であれば、**再マッピングファイル**アプローチを使用します：古い名前→新しいBeancount名のCSVまたは辞書を保持し、変換中に適用します（我々のサンプルコードは`account_map`を使用し、ファイルから上書きを読み込むことができます）。

- **日付とフォーマット:** すべての日付が一貫してフォーマットされていることを確認してください。上記のスクリプトはM/D/YをISO形式に正規化します。また、5年間の期間が年度末をまたぐ場合、会計年度と暦年の問題に注意してください。Beancountは会計年度の境界を気にしませんが、後で便宜上、ファイルを年ごとに分割したい場合があります。

- **数値の精度:** QuickBooksは通貨をセント単位で処理するため、セント単位での作業は通常問題ありません。理想的には、すべての金額がCSVで小数点以下2桁を持つべきです。もし金額が整数に変換された（小数点なし）場合や、カンマ/括弧（負の場合）がある場合は、スクリプトでクリーンアップします（カンマを削除し、`(100.00)` を `-100.00` に変換するなど）。指示に従って正しく行われたCSVエクスポートは、これらのフォーマットの問題を既に回避しているはずです。

- **負の金額と符号:** QuickBooksのレポートでは、負の値を `-100.00`、`(100.00)`、または特定のExcelエクスポートでは `--100.00` として表示することがあります。クリーンアップステップでこれを処理する必要があります。各取引の借方と貸方がゼロになるようにバランスが取れていることを確認してください。Beancountはこれを強制します（バランスが取れていない場合、インポート時にエラーをスローします）。

- **重複した取引:** 取引をバッチで（例：年ごとや勘定ごと）エクスポートする必要があった場合、重複しないようにマージするように注意してください。ある年の最初の取引が前のバッチの最後の取引でもないことを確認するなど。境界で誤っていくつかの取引を重複させてしまうのは簡単です。重複が疑われる場合は、最終的なBeancountの仕訳を日付でソートし、同一のエントリを探すか、Beancountの一意の取引タグを使用して検出できます。戦略の1つは、QuickBooksの取引番号をメタデータとして含め（例：`取引番号`や請求書番号を`txn`タグや`quickbooks_id`メタデータとして使用）、それらのIDの重複がないことを確認することです。

- **不均衡な明細 / 未決算勘定:** QuickBooksには、QuickBooksが自動的に「期首残高純資産」または「利益剰余金」勘定に調整した*不均衡*を持つ取引のような奇妙なケースがあるかもしれません。たとえば、期首勘定残高を設定する際、QuickBooksはしばしば差額を純資産勘定に記録します。これらはエクスポートされた取引に現れます。Beancountは明示的なバランスを要求します。QuickBooksを反映させるために、期首残高用の純資産勘定（一般的に`Equity:Opening-Balances`）を導入する必要があるかもしれません。元帳の初日にすべての勘定の期首残高を設定する期首残高仕訳を持つのが良い習慣です（ステージ5参照）。

- **多通貨の特殊ケース:** 多通貨を使用する場合、QuickBooksのエクスポートはすべての金額を現地通貨またはネイティブ通貨でリストするかもしれません。理想的には、各勘定のネイティブ通貨でデータを取得します（QuickBooks Onlineのレポートは通常これを行います）。Beancountでは、各仕訳は通貨を持ちます。QuickBooksが為替レートまたは現地通貨への換算を提供した場合、それらを無視してBeancountの価格エントリに依存することができます。QuickBooksが為替レートをエクスポート**しなかった**場合、評価を一致させるために主要な日付に手動で価格レコードを追加したい場合があります（例：Beancountの`price`ディレクティブを使用）。ただし、元帳の基本的な整合性のためには、取引が元の通貨でバランスが取れていれば十分です。未実現損益は、同じレポートが必要でない限り、明示的に記録する必要はありません。

- **売掛金 / 買掛金:** QuickBooksは、プレーンテキスト元帳には完全には引き継がれない請求書や支払手形の詳細（支払期日、支払状況など）を追跡します。ARおよびAP取引（ARを増加させる請求書、ARを減少させる支払いなど）は取得できますが、請求書ドキュメントや請求書ごとの顧客残高は取得できません。その結果、移行後、BeancountのARおよびAP勘定の残高が、QuickBooksの未処理の顧客/ベンダー残高と一致することを確認する必要があります。請求書を追跡する必要がある場合は、Beancountのメタデータを使用できます（例：`invoice`タグやリンクを含める）。QuickBooksの請求書番号は`Num`または`Memo`フィールドに入っているはずです。我々のスクリプトは`Num`を取引メタデータの`number: "..."`として保持します。

- **非アクティブまたは閉鎖された勘定:** IIFエクスポートには非アクティブな勘定が含まれる場合があります（含めるように選択した場合）。これらをインポートしても問題ありません（取引がなく、本当に非アクティブであれば残高はゼロになります）。最後の取引日の後に`close`ディレクティブを使用してBeancountで閉鎖済みとしてマークできます。これにより、元帳が整理されます。例：
  `2023-12-31 close Expenses:OldAccount  ; 移行後に閉鎖`
  これはオプションであり、主に整理のためです。

上記のようにデータを慎重にクリーンアップし、マッピングすることで、QuickBooksのデータを構造的に反映したBeancount元帳ファイルができます。次のステップは、それがQuickBooksを**数値的に**も反映していることを確認することです。

---

## ステージ3：データの検証と照合

検証は、会計データ移行における**重要な段階**です。Beancount元帳がQuickBooksの帳簿とセント単位で一致することを確認する必要があります。いくつかの戦略とツールを使用できます：

### 3.1 試算表の照合

**試算表**レポートは、すべての勘定の期末残高（借方と貸方、または正/負で示される）をリストし、合計はゼロになるはずです。両方のシステムで同じ日付の試算表を実行することは、全体的な精度を最も迅速に確認する方法です。

- **QuickBooksで:** 最終年の最終日（例：2023年12月31日）の**試算表**レポートを実行します。このレポートは各勘定の残高を示します。それをエクスポートするか、主要な数値をメモします。

- **Beancountで:** Beancountのレポートを使用して試算表を生成します。簡単な方法はコマンドライン経由です：

  ```bash
  bean-report migrated.beancount balances
  ```

  `balances`レポートは、すべての勘定とその残高をリストする試算表です。Fava（BeancountのWebインターフェース）でファイルを開き、*残高*または*貸借対照表*セクションを見ることもできます。Beancountの各勘定残高は、QuickBooksの試算表と一致する必要があります。たとえば、QuickBooksが*売掛金 = $5,000*を示している場合、Beancountの`Assets:AccountsReceivable`勘定は$5,000（借方）になるはずです。*売上収益 = $200,000*の場合、Beancountの`Income:Sales`勘定は$200,000（貸方、クレジットを負として表示する試算表を使用している場合は-200,000と表示される可能性があります）を示すはずです。

食い違いがある場合は、特定します：

- 勘定全体が欠落しているか、余分にあるかを確認します（勘定を忘れたか、移行期間前に既に閉鎖されていたものを含めてしまったか？）。
- 残高が間違っている場合は、さらに詳しく調べます：QuickBooksでは、その勘定の**クイックレポート**または元帳詳細を実行でき、それをBeancountのその勘定のレジスタ（`bean-report migrated.beancount register -a AccountName`）と比較できます。差異は、取引の欠落や重複から生じることがあります。

また、Beancountの試算表で**すべての勘定の合計**がゼロであることを確認します（合計がゼロまたは非常にゼロに近い値として出力されるはずです）。Beancountは複式簿記を強制するため、ゼロでない不均衡がある場合、資産から負債と純資産を引いたものがゼロにならなかったことを意味し、問題を示しています（QuickBooksも通常はこれを許可しませんが、一部のデータが省略された場合に発生する可能性があります）。

### 3.2 勘定残高の比較

試算表以外に、特定の財務諸表を比較できます：

- **貸借対照表:** QuickBooksで最終日の貸借対照表を実行し、Beancountの貸借対照表（`bean-report migrated.beancount balsheet`）を実行します。これは試算表に似ていますが、資産、負債、純資産で整理されています。カテゴリごとの数値が一致する必要があります。より詳細なチェックのために、主要な勘定の合計を比較します：現金、売掛金、固定資産、買掛金、純資産など。

- **損益計算書:** QuickBooksとBeancount（期間全体の損益計算書は`bean-report migrated.beancount income`）で5年間の期間（または年ごと）の損益計算書を実行します。Beancountの純利益は、各期間でQuickBooksの純利益と等しくなければなりません。5年間すべてを移行した場合、累積純利益が一致する必要があります。また、個々の収益と費用の合計を比較して、カテゴリが省略または重複していないことを確認できます。

- **ランダムな取引のサンプリング:** ランダムにいくつかの取引（特に各年から、および各主要勘定から）を選び、それらが正しく移行されたかを確認します。たとえば、QuickBooksで3年前の請求書を見つけ、その金額やメモをBeancountファイルで検索します（すべての取引はテキストなので、`.beancount`ファイルをテキストエディタで開くか、検索ツールを使用できます）。日付、金額、勘定が一致することを確認します。これは、日付形式の問題や誤ってマッピングされた勘定を検出するのに役立ちます。

### 3.3 自動整合性チェック

Beancount自身の検証ツールを活用します：

- **bean-check:** `bean-check migrated.beancount` を実行します。これによりファイルが解析され、構文エラーやバランスエラーが報告されます。スクリプトが未開設の勘定やバランスの取れていない取引などを見逃した場合、`bean-check`がそれを指摘します。クリーンなパス（出力なし）は、ファイルが少なくとも内部的に一貫していることを意味します。

- **残高アサーション:** 追加のチェックとして、元帳に主要な勘定の明示的な残高アサーションを追加できます。たとえば、特定の日付の銀行口座の残高がわかっている場合は、次のような行を追加します：
  `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の行を数えることで推定できます（取引ヘッダー vs 明細）。Beancountでは、ファイル内の`txn`または`* "`の出現回数を数えるのが手っ取り早い方法です。これらはQuickBooksの数と等しいか、わずかに多くなるはずです（期首残高取引や調整を追加した場合）。大きな食い違いは、何かが省略されたか重複した可能性があることを意味します。メタデータで一意のIDを使用することで、重複が疑われる場合に、Beancountファイル内で同じ小切手番号や請求書番号が2回出現していないか検索できます。

- **照合ステータス:** スクリプトにQuickBooksの「照合済み」ステータスに基づいて`rec: "y"`または`"n"`のメタデータを含めました（例の`rec`など）。これはBeancountの標準機能ではありませんが（BeancountはLedgerのように「照合済み/保留中」を追跡しません）、便利なメタデータになる可能性があります。QuickBooksで照合されたすべての取引が存在することを確認できます。最終的に、Beancountで銀行口座を再照合する（明細書を使用）ことが、何も欠けていないことの最終的な証明になる可能性があります。

これらの検証を行うことで、移行がデータを保持したという信頼が生まれます。**この段階に時間をかけてください**。数ヶ月後に帳簿に依存するようになってから異常を修正するよりも、今修正する方が簡単です。検証が失敗した場合の一般的な問題：勘定の期首残高の欠落、範囲外の日付の取引、または仕訳の符号の反転。これらはすべて、特定されれば修正可能です。

---

## ステージ4：Beancount台帳への統合

クリーンアップと検証の後、データをBeancount元帳の構造に正式化する時が来ました。「統合」とは、元帳ファイルを完成させ、監査可能性のためにバージョン管理システムに登録することを意味します。

### 4.1 台帳ファイルと設定の整理

Beancount元帳ファイルをどのように構成するかを決定します。5年分のデータの場合、すべてを1つのファイルに保持するか、年またはカテゴリごとに分割することができます。一般的で明確な構造は次のとおりです：

- **メイン元帳ファイル:** 例：`ledger.beancount` – これは他のファイルを`include`できるエントリポイントです。グローバルオプションを含み、年次ファイルをインクルードすることができます。
- **勘定科目ファイル:** 勘定科目表と期首残高を定義します。例：`accounts.beancount`には、すべての`open`ディレクティブ（スクリプトによって生成）が含まれます。商品（通貨）もここでリストできます。
- **取引ファイル:** 年ごとに1つ、例：`2019.beancount`、`2020.beancount`など、その年の取引を含みます。これにより、各ファイルが管理可能なサイズに保たれ、必要に応じて1年に集中できます。あるいは、エンティティや勘定ごとに分割することもできますが、時間による分割は財務データにとって簡単です。

**メインファイルの例：**

```beancount
option "title" "私のビジネス元帳"
option "operating_currency" "USD"

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

このようにして、レポートを実行するとすべてのデータが集計されますが、秩序は維持されます。

Beancountは複数のファイルを必要としません（1つの大きなファイルでもかまいません）が、上記の構造は明瞭さとバージョン管理を向上させます。Beancountのベストプラクティスに従い、明確なセクションヘッダーを使用し、関連するエントリを論理的にグループ化することが良いでしょう。

### 4.2 開始残高と純資産の設定

移行が絶対的なゼロからの開始でない場合、期首残高を処理する必要があります。2つのシナリオがあります：

- **ゼロから始まる帳簿:** 5年間の期間が会社の設立時に始まる場合（例：2019年1月にQuickBooksを使い始め、初期の純資産を除いてすべての勘定がゼロだった場合）、別の期首残高取引は必要ないかもしれません。2019年の最初の取引（銀行口座への初期資金調達など）が自然に期首残高を設定します。*初期資本*や*以前の利益剰余金*が純資産取引を通じて計上されていることを確認してください。

- **途中からの帳簿（部分的な履歴）:** QuickBooksを以前から使用しており、2019年が中間点である場合、2019年1月1日時点で各勘定には繰越残高がありました。QuickBooksではそれらが期首残高または利益剰余金として記録されていたでしょう。Beancountでは、開始日の前日に期首残高仕訳を作成するのが一般的です：
  - すべての期首金額の合計を相殺するために、`Equity:Opening-Balances`（または同様の）という名前の純資産勘定を使用します。
  - 例：2018年12月31日時点で、現金が$10,000、売掛金が$5,000、買掛金が$3,000（貸方）だった場合、次のような取引を記述します：
    `2018-12-31 * "期首残高"`
    `  Assets:Cash                   10000.00 USD`
    `  Assets:AccountsReceivable     5000.00 USD`
    `  Liabilities:AccountsPayable  -3000.00 USD`
    `  Equity:Opening-Balances      -12000.00 USD`
    これにより、`Opening-Balances`には仕訳をバランスさせる負の合計（–$12k）が残ります。これで、すべての資産/負債勘定は2019年を正しい残高で開始します。これは、QuickBooksの「利益剰余金」や繰越残高を反映するはずです。
  - あるいは、Beancountの`pad`および`balance`ディレクティブを使用します：各勘定について、`Opening-Balances`から`pad`し、残高をアサートできます。これはより自動化された方法です。例：
    `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:RetainedEarnings`を作成しなかった場合、それがゼロであることに気づくかもしれません。Beancountでは、利益剰余金は単に前年度の利益です。利益剰余金勘定を作成し、毎新年の初日に前年度の利益をそれに振り替えるか、単に純資産をすべての収益/費用の合計とすることができます（これはレポートの純資産セクションに表示されます）。透明性を高めるために、一部のユーザーは毎年クロージングエントリを記録します。これはオプションであり、主に表示のためです。すべての取引を移行したため、各年の利益は年ごとのレポートを実行すれば自然に累積されます。

- **比較チェック:** 期首残高を設定した後、開始日の貸借対照表を実行して、すべてが正しいことを確認します（それらの期首残高と期首純資産がゼロになるはずです）。

### 4.3 最終処理とバージョン管理

データがBeancount形式になり、構造化された今、**ファイルをバージョン管理リポジトリ**（例：git）にコミットするのが賢明です。元帳の各変更を追跡でき、すべての修正の監査証跡が得られます。これはプレーンテキスト会計の重要な利点です。たとえば、QuickBooksでは変更を簡単に比較できないかもしれませんが、Beancountでは行ごとに差分を確認できます。一部のユーザーが指摘するように、Beancountでは透明性が得られ、必要に応じて変更を元に戻すことができます。各仕訳は変更履歴にリンクできます。

この初期移行のコミットに`v1.0`などのタグを付けることを検討してください。そうすれば、それがQuickBooksからインポートされた時点の帳簿の状態を表していることがわかります。将来的には、新しい取引を直接Beancountに入力する（または銀行明細書からインポートするなど）ことになり、通常のソフトウェア開発プラクティス（毎月または毎日コミットする、実験のためにブランチを使用するなど）を使用できます。

**Favaやその他のツールの設定:** FavaはBeancountのWebインターフェースで、レポートを簡単に表示できます。コミット後、`fava ledger.beancount`を実行して財務諸表を閲覧し、QuickBooksのレポートと最後の比較を行います。UIでは小さな違いをより簡単に見つけられるかもしれません（たとえば、ゼロであるべき勘定に小さな残高が表示されている場合は、クロージングエントリの欠落や見逃された取引を示しています）。

**命名規則と一貫性:** これで完全にコントロールできるようになったので、一貫性を確保してください：

- すべての勘定は明確な名前を持ち、大文字のカテゴリ名（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：移行後の監査と例

移行の成功を説明するために、財務諸表の移行前後の比較と、可能であれば取引の差分を準備します。これにより、帳簿が一貫していることの証拠が提供されます。

### 5.1 財務諸表の確認

QuickBooksとBeancountの両方から同じ日付の主要な財務レポートを作成し、比較します：

- **2023年12月31日の貸借対照表:** 資産、負債、純資産の合計を行ごとに比較します。これらは一致するはずです。たとえば、QuickBooksが**総資産 = $150,000**および**総負債 + 純資産 = $150,000**を示した場合、Beancountの貸借対照表も同じ合計を示すはずです。勘定の構成を少し変えた場合（いくつかのサブ勘定を統合したなど）、比較で調整するか、合計が等しいことを確認するために次のレベルまでドリルダウンします。

- **2019年–2023年の損益計算書:** 各年（または全期間）の総収益、総費用、および純利益が同一であることを確認します。QuickBooksがレポートで丸め処理を行った場合、わずかな差異が生じる可能性がありますが、取引は通常セント単位まで正確に記録されるため、純利益は正確であるはずです。いずれかの年の結果が異なる場合は、その年のデータを詳しく調べます。それはしばしば、その期間の仕訳の欠落または重複の指標です。

- **試算表の差分:** 可能であれば、各勘定とQuickBooks対Beancountの残高をリストしたスプレッドシートを作成します。一致することを期待しているので、これはすべてゼロの差分列になるかもしれません。これは本質的に、我々が議論した試算表のクロスチェックですが、それを書き留めることは文書化に役立ちます。

### 5.2 比較例（移行前 vs 移行後）

以下は、データの一貫性を示す**サンプル**の抜粋です。2023年12月31日のQuickBooksの試算表が次のようであったとします：

| 勘定科目                  | QuickBooks残高 (2023年12月31日) |
| ------------------------- | ------------------------------- |
| **資産**                  |                                 |
| Assets:Bank:Checking      | $12,500.00 (借方)               |
| Assets:AccountsReceivable | $3,200.00 (借方)                |
| **負債**                  |                                 |
| Liabilities:CreditCard    | $-1,200.00 (貸方)               |
| Liabilities:LoansPayable  | $-5,000.00 (貸方)               |
| **純資産**                |                                 |
| Equity:Opening-Balances   | $-7,500.00 (貸方)               |
| Equity:RetainedEarnings   | $-2,000.00 (貸方)               |
| Equity:CurrentYearProfit  | $0.00                           |

Beancountでは、2023年までのすべての取引をインポートして記録した後、`bean-report balances`（試算表）は次のように出力されます：

| 勘定科目                  | Beancount残高 (2023年12月31日) |
| ------------------------- | ------------------------------ |
| **Assets**                |                                |
| Assets:Bank:Checking      | 12,500.00 USD (借方)           |
| Assets:AccountsReceivable | 3,200.00 USD (借方)            |
| **Liabilities**           |                                |
| Liabilities:CreditCard    | -1,200.00 USD (貸方)           |
| Liabilities:LoansPayable  | -5,000.00 USD (貸方)           |
| **Equity**                |                                |
| Equity:Opening-Balances   | -7,500.00 USD (貸方)           |
| Equity:RetainedEarnings   | -2,000.00 USD (貸方)           |
| Equity:Profit (2019-2023) | 0.00 USD                       |

_(注意：純資産セクションは異なる構成にすることができます。重要なのは合計が一致することです。ここで、Beancountの「利益(2019-2023)」は、当期利益/利益剰余金の複合的な役割を果たし、利益が利益剰余金にクローズされたためゼロを示しています。)_

示されているように、各勘定はセント単位で一致しています。借方の合計は、両側で貸方の合計と等しくなります。

さらに、2023年の損益計算書を実行すると：

- QuickBooks: 収益 \$50,000、費用 \$48,000、純利益 \$2,000。
- Beancount: 収益 \$50,000、費用 \$48,000、純利益 \$2,000（その後、利益剰余金にクローズされたか、年末の貸借対照表の純資産の下に表示されます）。

必要であれば取引の差分を作成できますが、QuickBooksのデータは元帳形式ではないため、レポートに依存する方が効果的です。QuickBooksのCSVとBeancountの取引を両方とも日付でソートし、最終チェックとして主要なフィールドを比較することができます（これはExcelまたはスクリプトで行うことができます）。ただし、以前の検証に自信があるため、財務諸表のチェックで通常は十分です。

### 5.3 監査のヒント

- 監査人や利害関係者が保証を必要とする場合は、**移行前後の財務諸表**を並べて提示します。**Beancountの透明性**は、実際には監査を簡素化できます。なぜなら、財務諸表の各数値を元の仕訳まで迅速に追跡できるからです（特にFavaのドリルダウン機能を使用）。
- QuickBooksのバックアップとエクスポートされたCSVを監査証跡の一部として保持します。移行中に行われた調整を文書化します（例：「一貫性のために勘定XをYに改名」または「明確化のために取引Zを2つの仕訳に分割」など、そのような変更を行った場合）。
- 将来的には、Beancountで定期的なチェックを実施します。たとえば、銀行口座の月次照合とその期末残高のアサーションは、データの問題や入力エラーを検出するのに役立ちます。移行は良い基盤を提供します。新しいシステムで規律を維持することで、継続的な精度が保証されます。

最後に、移行の完了を祝いましょう：あなたはQuickBooksからBeancountへの5年間の会計データの転送に成功しました。データは現在、軽量でバージョン管理された、完全な複式簿記の整合性を持つテキスト形式になっています。データをエクスポートし、Pythonスクリプトで変換し、試算表とレポートを通じて整合性を検証し、整理されたBeancount元帳に統合しました。この包括的なプロセスにより、Beancount元帳が5年間の期間にわたって**QuickBooksの帳簿の正確で忠実な複製**であることが保証され、将来の簡素化された会計への道が開かれます。
