sdrplk/finance-audit

Finance Audit — パーソナルCFOレポート

生の明細ファイルが入ったフォルダをパーソナルCFOレポートに変換します。検証済みデータに加え、何が起きたか？なぜか？次に何をすべきか？ に答えるナラティブレイヤーを提供します。

正確性第一：金額はそのまま読み取られ、残高と照合されます。架空のデータは一切作成しません。

銀行に依存しない。取引リストがあれば、どの銀行やアカウントのエクスポートでも動作します。列、ヘッダー行、日付順（DMY/MDY/YMD）はファイルごとに自動検出されます。取引先/カウンターパーティのクリーナーは決済手段に依存しません（UPI、POS、ACH、SEPA、カード、ワイヤーなど）。特定の銀行にハードコードされたものはありません。自動検出されたマッピングを確認し、カテゴリキーワードを調整するだけです。

パイプライン（5段階）

ingest  ->  parse  ->  categorize (loop to >=99%)  ->  analyze  ->  report (serve + hot reload)

スクリプトはこのスキルに含まれています。ユーザーの監査フォルダ（明細ファイルが入っているフォルダ）に対して実行します。最初に2つの変数を設定します。

SKILL="<このスキルディレクトリの絶対パス>"   # このSKILL.mdが入っているフォルダ
ROOT="<監査フォルダの絶対パス>"              # 明細ファイルが置かれている場所

プライバシー — 実際のデータを決してコミットしない

すべての明細ファイル、残高、ナレーション、生成された出力は、ROOT/ 内にローカルに残ります。スキルリポジトリはテンプレート、設定例、ダミーのフィクスチャ（assets/fixtures/sample_analysis.json）のみを同梱します。

gitignore対象（決してプッシュしない）： output/（report.html、analysis.json、audit.dbを含む）、明細ファイル、および実際の config/mapping.json / 上書きファイル。

config/mapping.json 内のオプションラベル：サイドバーフッター用の account_label または account_last4（デフォルトは "Primary account"）。config/business.json 内のビジネス表示名 → display_name（デフォルトは "Business"）。

明細ファイルはすでに ROOT にダウンロードされているものとします（PDF / XLSX / XLS / CSV / TXT）。

ランタイムを選択します（ユーザーはNode.jsを好みます）：

• Nodeを使用：node が利用可能で、かつ入力にPDFがない場合。
• Pythonを使用：入力にPDFがある場合（NodeパスではPDFを解析できません）、または node が利用できない場合。

依存関係を検出してインストールします。

# Nodeパス（推奨）
command -v node && node --version            # 組み込みsqliteにはNode >= 22が必要
( cd "$ROOT" && npm install xlsx )           # .xls/.xlsxの場合のみ；CSV/TXTは不要

# Pythonパス（フォールバック / PDFに必要）
python3 --version
pip install openpyxl "xlrd==2.0.1" pdfplumber pandas  # 分析段階には+ pandas

各段階の呼び出し方法を定義します（$STAGE = ingest|parse|categorize|analyze|report）：

# Node:    node   "$SKILL/scripts/node/$STAGE.mjs" --root "$ROOT" [args]
# Python:  python3 "$SKILL/scripts/python/$STAGE.py" --root "$ROOT" [args]

ステップ1 — 取り込みと検出

node "$SKILL/scripts/node/ingest.mjs" --root "$ROOT"      # または python3 .../ingest.py --root "$ROOT"

これにより、すべてのファイルがプレビューされ、config/mapping.json に自動検出されたヘッダー行、列の役割、明示的な date_format が書き込まれます。プレビューを読み、mapping.json を確認してください — 銀行によって異なります。エントリに _date_note がある場合、日付順が曖昧でした（例：03/04/2024）。日付形式をユーザーと確認してください。各ファイルエントリには、header_row、data_start_row、date_format（%d/%m/%Y のようなstrptimeパターン、または auto）、columns（役割 → 0ベースのインデックス）、および amount_mode が必要です：

• debit_credit — 引き出しと入金の列が別々（最も一般的）
• signed — 符号で方向を示す1つの amount 列
• amount_type — amount 列に加えて、DR/CRを保持する type 列

解析する前に、間違ったインデックスを修正してください。

ステップ2 — 解析、正規化、重複排除、検証

node "$SKILL/scripts/node/parse.mjs" --root "$ROOT"       # または .../parse.py

output/audit.db（SQLite）を書き込みます。借方/貸方の分割は符号付き金額から導出されるため、常に残高チェーンと一致します（マイナスの引き出しとしてエンコードされた返金を適切に処理します）。整合性チェックがPASSすることを必須とします（残高列がない場合は n/a）。FAILした場合：

• mapping.json の列 / data_start_row / date_format を再確認します。
• 取り込みの標準出力プレビューを再度読みます（必要に応じて取り込みを再実行）；ヘッダー/フッター行を含めていないことを確認します。
• ファイルごとの chain_issues > 0 は、誤って解析された正確な行を示します。

解析が調整されるまで、分類に進まないでください。

ステップ3 — 分類（値で >= 99% になるまでループ）

cp "$SKILL/config/categories.example.json" "$ROOT/config/categories.json"   # 初回のみ
# ビジネス/フリーランスアカウントの場合は、さらに：
cp "$SKILL/config/business.example.json"   "$ROOT/config/business.json"     # その後編集
node "$SKILL/scripts/node/categorize.mjs" --root "$ROOT"   # または .../categorize.py

ルールの優先順位：overrides.json > business.json > categories.json；最も高い priority が優先されます。分類はスクリプト優先です；次のようにして99%に到達します：

1. 分類を実行します。カバレッジサマリーと output/uncategorized.csv（マーチャントがグループ化され、最大値が最初）を読みます。
2. ナレーションから明らかなマーチャントについては、自分で config/overrides.json にルールを追加します（以下の形式を参照）— 尋ねる必要はありません。
3. 曖昧なマーチャント（誰/何か不明、または個人とビジネスの区別が不明）については、ユーザーに簡潔な質問をしてからルールを追加します。
4. 分類を再実行します。値カバレッジ >= 99% になるまで繰り返します。

config/overrides.json の形式：

{ "rules": [
  { "keywords": ["ACME", "ACME CORP"], "primary": "Income", "sub": "Acme retainer", "when": "credit" },
  { "keywords": ["BIGRENT"], "primary": "Housing", "sub": "Rent", "is_business": 0 }
] }

すべての取引に primary_cat と sub_cat が設定されることを目指します。事実上のP2Pカウンターパーティフォールバックは振替にラベル付けしますが、「レビューが必要」としてカウントされます — 重要なものを実際のルールに変換してください。

ステップ4 — 分析（output/analysis.json を構築）

python3 "$SKILL/scripts/python/analyze.py" --root "$ROOT"

FYスライス、カテゴリレポート、CFOナラティブ、収入エンジン、支出サマリー、問題領域、およびビジネス事後分析を output/audit.db から計算します。output/analysis.json（およびオプションの findings.md — 決してコミットしない）を書き込みます。

pandas が必要です。ビジネスセクションラベル（デフォルト "Business"）を調整するには、config/business.json → display_name を設定します。

ステップ5 — レポートを生成（サーブ + ホットリロード + 自動オープン）

python3 "$SKILL/scripts/python/report.py" --root "$ROOT" --serve

analysis.json + 元帳行をインラインで埋め込んだ output/report.html を構築します。--serve を指定すると、http://127.0.0.1:8765/ を開き、db/設定が変更されるとホットリロードします（分析を再実行 + 再レンダリング）。--refresh-analysis を使用して、ワンショットビルドで強制的に再分析します。

レポートUI（output/report.html）— Money.Auditハイブリッドダッシュボード

シェル： 角丸のアプリフレーム、FYリスト＋セクションナビゲーション（スクロールスパイ）付きのライトサイドバー、全幅メインカラム。タイトル：あなたのお金にとって重要なこと。

外観： Fraunces セリフ体 + Spline Sans UI；暖かみのあるクリームシェル（#f7f6f3）、ゴールドアクセント。一般的なグレーのSaaSではありません。

セクション（サイドバー）： スナップショット、収入エンジン、月間支出、問題領域、ビジネス事後分析、現金と動き、アクションプラン、全カテゴリ、元帳（検索＋フィルター）。

埋め込みデータ： const ANALYSIS = … および const LEDGER = … — 外部フェッチはありません。サイドバーフッターはマッピングからの account_label を表示します（テンプレートにアカウント番号をハードコードしないでください）。

モーション： emil-design-eng — :active scale(0.98)、バー幅のトランジション、動きの軽減対応。スタイルガイド： references/ui_style_guide.md。

テンプレート： assets/report_template.html。ドキュメント用のダミーフィクスチャ： assets/fixtures/sample_analysis.json。

レポートUIを変更する場合：テンプレート＋スタイルガイドを編集します。実際の output/report.html を決してコミットしないでください。analyze → report でローカルに再生成します。

レポートの内容

1. スナップショット — 健全性スコア、メトリクス、CFOの引用3つ。
2. 収入 / 支出 / 問題 — カテゴリへのドリルダウンが可能な意思決定優先のセクション。
3. ビジネスレビュー — config/business.json が存在する場合。
4. 元帳 — 検索可能な取引証拠（最初の350件の一致を表示）。

フラグ：--port N、--no-open、--refresh-analysis。--serve なしの場合、output/report.html を1回書き込みます（analysis.json がない場合は最初に分析を実行します）。

方法論： references/financial_frameworks.md。

注記： ハイブリッドMoney.Audit UIはPythonの分析＋レポートパスを使用します。Nodeの report.mjs は、分析なしの基本的な監査のために、従来のCFOテンプレートを引き続きレンダリングします。

監査フォルダに生成されるレイアウト

ROOT/
├── <明細ファイル>                   # 入力（PDF/XLSX/XLS/CSV/TXT）
├── config/
│   ├── mapping.json                 # 列マッピング（取り込み後に確認）
│   ├── categories.json              # カテゴリルール（例から）
│   ├── business.json                # オプション：ビジネス収入/給与/インフラ
│   └── overrides.json               # ループ中に追加したラベル
└── output/
    ├── audit.db                     # SQLiteの信頼できる情報源
    ├── analysis.json                # 分析段階（ローカル限定 — PII）
    ├── uncategorized.csv            # レビューキュー（分類実行のたびに再生成）
    └── report.html                  # Money.Auditダッシュボード（ローカル限定 — PII）

スキルは必要なものだけを書き込みます：編集可能な設定、ステージ間で状態を保持するSQLite db、レビューキュー、最終レポート。中間ダンプ（取り込みプレビュー、レポートJSON）は、別のファイルとして書き込まれるのではなく、出力/埋め込まれます。mapping.json と audit.db は、各ステージが個別のプロセスとして実行されるため、ディスク上に永続化する必要があります。

注記

• 同じ mapping.json / config / SQLiteスキーマが両方のランタイムで機能します。監査の途中でランタイムを切り替えることができます。
• 生の明細ファイルはバージョン管理から外してください（PIIが含まれています）。
• 完全なスキーマ、検証計算、設定リファレンスについては、reference.md を参照してください。
• 分析フレームワーク（貯蓄率、50/30/20、ベンチマーク、推奨ロジック）については、references/financial_frameworks.md を参照してください。

このスキルが対応する一般的なリクエスト

• 「銀行取引明細を監査/分類してレポートを作成して」 — フルパイプライン。
• 「2024-25年度のパーソナルCFOレポートは？」 — レポート表示後に期間セレクターを使用。
• 「私の貯蓄率とそれを改善する方法は？」 — エグゼクティブサマリー＋アクションプラン。
• 「どこで使いすぎている？」 — 支出インテリジェンス＋反事実分析。
• 「何をやめて、何を始めて、何を続けるべき？」 — アクションプランセクション。
• 「ランニング/負債/投資についてCFOに質問して」 — エージェントに「CFOに質問」プロンプトを使用。
• 「レポートUIを改善して/全幅にして/レイアウトを修正して」 — references/ui_style_guide.md に従って assets/report_template.html を編集し、analyze → report でローカルに再生成。output/report.html は決してコミットしない。