sdrplk/finance-audit

財務審計 — 個人財務長報告

將一資料夾的原始對帳單檔案轉換為個人財務長報告：驗證資料 加上敘述層，回答發生了什麼事？為什麼？接下來該怎麼做？

精準優先：金額照原文讀取，並與餘額流水核對 — 絕不虛構。

銀行通用。 只要提供交易清單，就能與任何銀行或帳戶匯出檔案搭配使用。 欄位、標題列和日期順序（DMY/MDY/YMD）會自動偵測每個檔案； 商家/交易對象清理器支援多種軌道（UPI、POS、ACH、SEPA、信用卡、電匯等）。 沒有任何程式碼是寫死給特定銀行的 — 你確認自動偵測的對應關係並調整分類關鍵字即可。

流程（5 個階段）

擷取  ->  解析  ->  分類（迴圈至 >=99%）  ->  分析  ->  報表（提供服務 + 熱重載）

腳本位於此技能目錄中。針對使用者的審計資料夾（包含對帳單檔案的資料夾）執行。 先設定兩個變數：

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 用於側邊欄頁尾 （預設為「主要帳戶」）。config/business.json 中的企業顯示名稱 → display_name（預設為「企業」）。

假設對帳單檔案已下載到 ROOT（PDF / XLSX / XLS / CSV / TXT）。

選擇執行環境（使用者偏好 Node.js）：

• 使用 Node：當 node 可用且沒有輸入是 PDF 時。
• 使用 Python：當有任何輸入是 PDF（Node 路徑無法解析 PDF）或 node 不可用時。

偵測並安裝依賴項：

# Node 路徑（偏好）
command -v node && node --version            # 需要 Node >= 22 以使用內建 sqlite
( 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" [參數]
# Python：  python3 "$SKILL/scripts/python/$STAGE.py" --root "$ROOT" [參數]

步驟 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）；向使用者確認 date_format。 每個檔案條目需要：header_row、data_start_row、date_format（一個 strptime 模式，如 %d/%m/%Y，或 auto）、columns（角色 → 0 為基礎的索引），以及 amount_mode：

• debit_credit — 獨立支出 + 存入欄位（最常見）
• signed — 一個 amount 欄位，其正負號表示方向
• amount_type — 一個 amount 欄位加上一個 type 欄位，內含 DR/CR

在解析前修正任何錯誤的索引。

步驟 2 — 解析、標準化、去重、驗證

node "$SKILL/scripts/node/parse.mjs" --root "$ROOT"       # 或 .../parse.py

寫入 output/audit.db（SQLite）。借貸拆分是從帶正負號的金額推導出的， 因此它始終與餘額鏈匹配（正確處理編碼為負支出的退款）。 要求完整性檢查必須通過（當沒有餘額欄位時則為 n/a）。如果失敗：

• 重新檢查 mapping.json 的欄位 / data_start_row / date_format。
• 重新讀取擷取步驟的 stdout 預覽（必要時重新執行擷取）；確認你沒有包含標題/頁尾行。
• 每個檔案的 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. 對於不明確的商家（不清楚是誰/做什麼，或個人vs.企業不明確）， 向使用者提出簡潔問題，然後加入規則。
4. 重新執行分類。重複直到 金額覆蓋率 ≥ 99%。

config/overrides.json 格式：

{ "rules": [
  { "keywords": ["ACME", "ACME CORP"], "primary": "收入", "sub": "Acme 保留款", "when": "credit" },
  { "keywords": ["BIGRENT"], "primary": "住房", "sub": "租金", "is_business": 0 }
] }

目標是讓每一筆交易都有 primary_cat 和 sub_cat。基於事實的 P2P 交易對象備用標籤可以標記轉帳，但會計入「需要審核」— 將重要的 轉換為真正的規則。

步驟 4 — 分析（建立 output/analysis.json）

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

從 output/audit.db 計算財務年度切片、分類報告、財務長敘述、 收入引擎、支出摘要、問題領域和企業事後檢討。寫入 output/analysis.json（和可選的 findings.md 到本地 — 絕不提交）。

需要 pandas。調整 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/ 開啟，並在資料庫/設定變更時熱重載 （重新執行分析 + 重新渲染）。使用 --refresh-analysis 可強制在一次建構中重新分析。

報表 UI（output/report.html）— Money.Audit 混合儀表板

外殼： 圓角應用程式框架、淺色側邊欄包含財務年度清單 + 區段導航（滾動監控）、 全寬主欄位。標題：關於你的金錢，什麼最重要。

外觀： Fraunces 襯線字體 + Spline Sans UI 字體；暖奶油色外殼（#f7f6f3）、金色 強調色。不是一般的灰色 SaaS。

區段（側邊欄）： 概覽、收入引擎、每月支出、問題領域、企業 事後檢討、現金與動向、行動計劃、全部分類、分類帳（搜尋 + 篩選）。

內嵌資料： const ANALYSIS = … 和 const LEDGER = … — 無外部請求。 側邊欄頁尾顯示 mapping.json 中的 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。透過分析 → 報表在本機重新生成。

報表內容

1. 概覽 — 健康分數、指標、三項財務長語錄。
2. 收入 / 支出 / 問題 — 以決策為先的區段，可向下鑽取至分類。
3. 企業審查 — 當 config/business.json 存在時。
4. 分類帳 — 可搜尋的交易證據（最多顯示前 350 筆相符項目）。

旗標：--port N、--no-open、--refresh-analysis。不使用 --serve 時，會寫入 output/report.html 一次（若缺少 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            # 分析階段（僅本地 — 含個資）
    ├── uncategorized.csv        # 審核佇列（每次執行分類時重新產生）
    └── report.html              # Money.Audit 儀表板（僅本地 — 含個資）

技能只寫入必要的內容：可編輯的設定、跨階段攜帶狀態的 SQLite 資料庫、 審核佇列以及最終報表。中間結果（擷取預覽、報表 JSON）會輸出/內嵌， 而不寫入額外檔案。mapping.json 和 audit.db 必須保留在磁碟上， 因為每個階段都是作為獨立程序執行。

備註

• 同一個 mapping.json / config / SQLite schema 在兩種執行環境下都能運作； 你可以在審計過程中切換執行環境。
• 將原始對帳單檔案保留在版本控制之外（它們包含個資）。
• 關於完整 schema、驗證數學邏輯和設定參考，請參閱 reference.md。
• 關於分析框架（儲蓄率、50/30/20、基準、建議邏輯）， 請參閱 references/financial_frameworks.md。

此技能可處理的常見請求

• 「審計 / 分類我的銀行對帳單並製作報表」— 完整流程。
• 「我 FY2024-25 的個人財務長報告是什麼？」— 報表後使用期間選擇器。
• 「我的儲蓄率是多少？該如何改善？」— 執行摘要 + 行動計劃。
• 「我在哪裡超支？」— 支出智慧分析 + 反事實模擬。
• 「我該停止/開始/繼續做什麼？」— 行動計劃區段。
• 「詢問我的財務長關於現金流動/債務/投資」— 使用與你的代理對話的「詢問財務長」提示。
• 「改善報表 UI / 讓它變成全寬 / 修正佈局」— 編輯 assets/report_template.html，依照 references/ui_style_guide.md； 在本機透過分析 → 報表重新生成。絕不提交 output/report.html。