📚職涯停看聽・知識庫← 總部儀表板
📅最後更新：2026/04/25
📑 目錄

RCF-011：財務系統建置決策

日期：2026-04-25 觸發條件：條件 5（影響 2+ 個技術系統的架構決策） 影響系統：財務系統（SYS-09）新增；HQ 儀表板（SYS-07）整合點更新；預約系統（SYS-04）/api/summary 資料來源擴增 RCF 編號：011 決策者：Tim（總裁） 實施者：Claude（CEO）

背景

現有財務記錄架構（RCF-009，2026-04-24）採用混合方案 γ：

  • 收入來源：預約系統 /api/admin/daily-revenue（自動同步）+ finance/external-revenue.json（手動記錄）
  • 支出來源：finance/monthly-report.md（手動月報）
  • 呈現：HQ 儀表板 FinancePanel 彙總顯示

RCF-009 的設計限制：

  • 無交易級別（transaction-level）的時間軸 → Tim 看不到「某筆錢是什麼時候進帳的」
  • 支出只有月彙總，無法追蹤個別支出的日期與說明
  • 系統規模擴張後，事後搬移資料的成本高

Tim 的原始需求（Session 26 對話）：

「我認為需要一個完整的財務系統，像預約系統這樣，打造一個專業的財務系統」 「完整的系統可以獨立，總部只要截取部份重要數據，這樣整體應該會比較好」

方案評估

方案 A：擴充現有 HQ 儀表板

  • 優點：不增加新系統複雜度
  • 缺點：儀表板已有側邊欄 + 4 個 Tab，再加流水帳 UI 過重；儀表板是「呈現工具」而非「記帳工具」
  • 結論：排除

方案 B：Google Sheets 串接

  • 優點：Tim 已熟悉介面，公式計算方便
  • 缺點：需手動同步、引入外部 SaaS 依賴、無法呼叫 /api/summary 供儀表板自動拉取
  • 結論：排除

方案 C（採用）：獨立 Next.js Web App

  • 優點：
    • 沿用 GitHub-as-database pattern（已在 hq-dashboard 驗證）
    • 完整 CRUD（日期 / 金額 / 類型 / 備註 / 狀態）
    • 公開 /api/summary endpoint 供儀表板呼叫（RCF-009 整合）
    • PIN auth 輕量認證，無需建立帳號系統
    • 資料存於 tzlth-hq/finance/ledger/，與 HQ 同 repo 一致
    • 零額外費用（Vercel Free + GitHub Free）
    • 設計可隨業務擴張（多年份 JSON、新類別等）
  • 缺點：新增第 9 個系統，增加管理複雜度
  • 結論：選用

確認的設計決策

決策項目 決定 理由
網域 finance.careerssl.com（Cloudflare CNAME） 與其他子網域一致
現有資料遷移 遷入新系統 避免雙軌並行
RCF-009 整合 /api/summary 供儀表板呼叫；Phase 2 顯示預約待確認收入 保留 RCF-009 的自動化收入同步機制
資料存放位置 tzlth-hq/finance/ledger/income-YYYY.json + expense-YYYY.json 與現有 HQ 資料同一 repo，統一備份
認證機制 PIN-based cookie auth（httpOnly，7 天） 無多用戶需求，輕量優先
技術棧 Next.js App Router + GitHub API 沿用已驗證方案

系統架構

財務系統（SYS-09）
├── app/
│   ├── page.tsx          — Dashboard（KPI Cards + 快捷連結）
│   ├── income/page.tsx   — 收入流水帳（CRUD）
│   ├── expense/page.tsx  — 支出流水帳（CRUD）
│   ├── login/page.tsx    — PIN 登入
│   └── api/
│       ├── auth/login/   — 設 cookie
│       ├── income/       — GET/POST/DELETE
│       ├── expense/      — GET/POST/DELETE
│       └── summary/      — 公開 GET（供儀表板）
├── lib/
│   ├── github.ts         — GitHub API CRUD + computeMonthlySummary
│   └── auth.ts           — verifyPin / generateToken / verifyToken
└── middleware.ts         — 所有路由除 /login + /api/summary 均需驗證

資料層（tzlth-hq repo）
└── finance/ledger/
    ├── income-2026.json  — 收入流水帳（年度 JSON）
    └── expense-2026.json — 支出流水帳（年度 JSON）

與 RCF-009 的關係

機制 RCF-009 狀態 整合計畫
預約系統 /api/admin/daily-revenue 保留運作 Phase 2：finance app 顯示此資料作「待確認收入」
finance/daily-revenue.json 保留 Phase 2 決定是否廢棄或保留為備份
finance/external-revenue.json 可廢棄 改由 finance app income CRUD 替代
月報 GitHub Action 保留 仍每月產出 finance/YYYY-MM-auto-summary.md
HQ 儀表板 FinancePanel Phase 2 整合 改為呼叫 finance.careerssl.com/api/summary

Phase 1 完成狀態（2026-04-25）

  • 代碼建置完成（npm run build ✅）
  • GitHub repo 建立（shoppy09/tzlth-finance）
  • 現有資料遷移（income NT$1,350 + expense NT$3,545）
  • Vercel 部署（https://tzlth-finance.vercel.app）
  • Vercel 環境變數設定（Tim 操作中）
  • 功能驗證（環境變數設定後執行）

Phase 2 待辦

  • app/reports/page.tsx（月報 + 現金流時間軸）
  • HQ 儀表板整合 /api/summary
  • RCF-009 待確認收入整合
  • Cloudflare CNAME（Tim 操作）

關鍵學習

  1. GitHub-as-database 可橫向複製：從 hq-dashboard 的 checklist 機制到 finance ledger，pattern 一致，降低開發成本
  2. 公開 API endpoint 設計：/api/summary 無 auth 允許儀表板呼叫，同時主要 CRUD routes 有 PIN auth 保護，是正確的分層設計
  3. 從 Day 1 建立完整系統：RCF-009 的「先簡後繁」策略在資料量少時行得通，但 Tim 正確判斷：「現在就先架構完整的系統，避免日後搬移成本」

記錄人：Claude（CEO） 建立於：2026-04-25

← 返回 決策記錄