adt109119/jijun repository overview

⁠輕鬆記帳 2.0 - 現代化 PWA

繁體中文⁠ | English⁠

這是「輕鬆記帳」應用程式的現代化版本，採用最新的前端技術重新打造，旨在提供更美觀、更易用、更穩健的記帳體驗。

📋 查看完整更新日誌⁠ - 了解所有版本的詳細更新內容

⁠🚀 新功能特色與 UI/UX 改進

⁠✨ 全新設計與視覺效果

• 現代化 UI: 採用 Tailwind CSS 打造的簡潔美觀介面，並使用漸層背景增添視覺層次。

• 深淺色模式自動切換與外觀管理: 支援跟隨系統（prefers-color-scheme）自動即時切換深淺色外觀，並提供「跟隨系統」、「淺色」、「深色」三態等寬切換器，自動同步手機頂部狀態列色彩（meta theme-color）。

• 響應式設計: 完美適配手機、平板和桌面裝置，確保在不同裝置上都有一致且良好的視覺體驗。

• 流暢動畫: 豐富的互動動畫提升使用體驗，例如分類按鈕的選中效果、滑動切換頁面等。

• 圖標顯示與顏色: 整合 Font Awesome 6，所有圖標風格統一且清晰。分類按鈕支援自定義顏色，並有明確的選中狀態視覺回饋。

• AI 離線語音記帳助手: 整合端側 58M LLM (WASM/[email protected]) 進行免連網語意 Tool Calling 解析，支援真實 GGUF 模型下載與 OPFS 離線快取，具備前端語意守門（applySemanticGuardrail）校準機制防止「花了100元」消費誤判為收入，輸入口述中文自動擷取金額、收支類型、動態分類、帳戶與日期，並搭配高質感霧面玻璃、圓角與 Gemini 彩虹霓虹動態光罩，並提供離線規則引擎作為模型未就緒時的優雅降級機制。

• 資料視覺化: 使用 Chart.js 提供圓餅圖（支出分類）和水位圖（預算管理），讓使用者能直觀地分析收支狀況。

• 智能統計: 多維度收支分析和分類統計，首頁快速統計功能移至最上方，方便用戶快速概覽。

• 記錄管理與類別篩選: 完整的增刪改查功能，明細頁類別篩選彈窗遵循會計學總額原則分離「支出類別」與「收入類別」，支援獨立計算與精準篩選其他收支，並提供全選/取消全選切換；同日記錄顯示更清晰。

• 行事曆金流檢視與 Android 桌面 Widget: 收支分析頁提供直觀的月曆收支分佈視圖，顯示每日 Top 3 支出分類標籤與金額，並可點擊彈出當日交易明細 Modal；Android 平台同步支援桌面行事曆 Widget，免開 App 即刻概覽當月每日收支事實。

• 真實信用卡分期與智能攤提: 支援真實信用卡分期（刷卡當下全額入帳佔額度、每月自動產生「扣款帳戶支出 + 信用卡收入」轉帳對還款與額度釋放），整合精準的攤提/分期引擎，自動處理四捨五入尾款與末期差額，支援智能溢繳防護、佔用額度追蹤與編輯防護。

• 首屏 0 第三方 CDN 與極致離線化: 全站資源（Tailwind CSS、Font Awesome、Google Fonts woff2、QRCode.js、html5-qrcode）改由本地打包，Google SDK 採登入/同步時按需載入，搭配 Service Worker 預快取清單 (precachemanifest.json) 與即時離線狀態提示列，實現 100% 離線可用。

• 明細搜尋: 明細頁面新增搜尋欄位，可依備註內容或交易金額即時篩選記錄。

• 帳戶餘額調整與可用額度: 帳戶管理頁面新增「平衡」按鈕，輸入實際餘額後自動計算差額，並可選擇自動建立「平帳」調整紀錄以維持帳目正確；信用卡帳戶即時計算並顯示欠款、總額度與可用額度。

• 每月預算設定: 可設定每月支出預算，水位圖動態顯示預算使用情況，並有超支警告。支援勾選特定支出分類進行「預算排除」，該分類實際消費不計入全局預算統計。

• 自定義分類: 完整的分類管理功能，可新增自定義分類、選擇圖示和顏色，並與預設分類無縫整合。

• 多帳本分類獨立化: 自訂分類設定（包含分類、排序與隱藏）由原本全域共享重構為隨帳本獨立儲存。切換帳本時會自動重新載入該帳本專屬的分類設定。

• 信用卡智慧管理、即時消費/出帳明細分離與扣繳平帳: 支援信用卡類型帳戶，可自訂信用額度、出帳日與繳款日。首頁雙列清晰區分「準備繳納（已出帳）」與「即時消費（未出帳）」，並提供專屬帳務明細彈窗折疊檢視各期帳單明細。支援到期自動扣繳平帳與手動單筆扣繳（以轉帳性質記帳不計入日常支出），並提供欠款歸零時的「單向扣款平帳」與銀行餘額矯正補記卡費，徹底防杜溢繳款並維持帳目精確。當還款入帳時，透過先進先出 (FIFO) 沖銷演算法自動更新帳單狀態為已繳 (paid)。

• 共用日期選擇器: 將明細與統計頁面的日期選擇 Modal 變為共用元件，解決先前統計頁面日期選擇異常的問題，並確保了介面體驗的一致性。

• 滑動手勢功能: 首頁支援左右滑動切換支出分類和預算管理，實時跟隨手指移動，同時支援標籤點擊和圓點指示器。智能手勢識別，不會干擾頁面垂直滾動。

• 資料匯出入: 支援完整的資料匯出和匯入功能，向下相容舊版資料格式，提供安全的資料備份和遷移。

• PWA 更新機制: 智能版本控制和自動更新提示，解決 PWA 快取問題，確保用戶始終使用最新版本。

• PWA 管理功能: 設定頁面新增「強制更新」、「分享 App」、「安裝為應用程式」等功能，提升 PWA 使用體驗。

• PWA 進階原生整合能力:

  • Launch Handler (單一實體限制): 限制單一執行視窗（focus-existing），防止重開分頁時造成 IndexedDB 寫入死鎖。
  • Share Target (簡訊記帳)：支援接收外部分享文字，自動擷取簡訊中之金額並預填至記帳頁面的金額與備註中。
  • Edge / Windows Widget (桌面小工具)：整合 Windows 桌面小工具面板顯示今日收支事實表，支援 Service Worker 在背景使用原生 IndexedDB 動態統計，並提供一鍵刷新。

• 版本管理: 設定頁面顯示當前版本號和最後更新時間，支援手動檢查更新功能。

• 完整更新日誌: 內建版本更新日誌系統，可查看所有歷史版本的詳細更新記錄。

• 可摺疊介面: 記帳頁面的小鍵盤支援最小化功能，點擊備註列旁的鍵盤圖示按鈕即可切換顯示，緊湊設計節省螢幕空間。

• 智能導覽: 底部導覽五欄式設計，涵蓋首頁、明細、記帳、統計、設定，核心功能一鍵直達。

• 詳細記錄管理: 完整的記錄編輯功能，支援修改類型、分類、金額、說明和日期。

• 視覺化增強: 支出分類甜甜圈圖中央顯示總額，提供直觀的支出概覽。

• 首頁小工具排序: 支援自訂首頁小工具的排列順序，並可透過眼睛圖示切換各小工具的顯示狀態，讓常用資訊觸手可及。

• 自訂分類功能: 支援自訂圖標輸入，可使用任何 Font Awesome 圖標類別創建個性化分類。

• 雲端備份與 Per-Device 獨立日誌共用帳本同步: 整合 Google Drive，個人資料使用專屬備份空間，共用帳本採用先進的 Per-Device 獨立變更日誌（Append-only）與 Manifest 清單架構，透過 ETag CAS 樂觀鎖防競態並支援 Google Drive 權限即時閉環撤銷，徹底杜絕多人並行記帳時的資料覆蓋衝突與時鐘偏差丟失。

• Google Drive 漸進式授權: 將雲端同步權限拆分為基礎備份 (drive.appdata) 與共用帳本 (drive.file)，初次僅要求最低限度基礎權限，保護隱私與提升安全性。

• 擴充功能修改 API: 於沙箱環境中，對獲得 data:write 權限的插件開放 updateRecord 與 updateDebt API，支援更進階的資料庫實體雙向關聯功能。

• 單元測試基礎建設: 引入 Vitest + jsdom，覆蓋核心業務邏輯模組，確保重構與修改時的程式碼穩定性。

• 優化輸入體驗: 記帳面板緊湊設計，日期輸入帶標籤，類別選擇使用統一的綠色主題效果。

⁠🧭 導覽系統

• 全方位新手與功能導覽 (Onboarding & Feature Tour):
  • 初次開啟歡迎 Modal: 採用毛玻璃高質感遮罩與 Slider Track 翻頁容器，支援觸控左右滑動手勢、鍵盤方向鍵導航與無障礙 ARIA 標註。
  • 互動式實操記帳引導演練: 自動引導「新增消費 ➔ 儲存 ➔ 明細查看 ➔ 編輯金額 ➔ 刪除測試紀錄」真實流程，具備中斷保護與資料自動清理，零髒資料殘留。
  • 全功能模組情境引導: 涵蓋欠款借貸、多帳戶資產、大額分期攤提、群組分帳、AI 語音記帳、預算進度、收支統計、週期交易與多帳本管理等逐步教學。
  • 功能開關即時介紹與重置入口: 設定頁啟用進階功能時即時彈出功能簡介氣泡，並於「關於」提供「導覽教學」按鈕供隨時重新重溫。
• 底部導覽列: 優化的五欄式導覽，包含「首頁 (🏠)」、「明細 (📋)」、「記帳 (➕)」、「統計 (📊)」、「設定 (⚙️)」，核心功能一鍵直達。
• 設定頁面: 整合了資料管理、應用程式管理與版本資訊，提供一站式的功能操作。

⁠📱 用戶介面改進

• 計算機模式與可摺疊小鍵盤: 記帳頁面的數字鍵盤全新升級
  • 支援最小化功能：點擊備註列旁的鍵盤圖示按鈕可切換鍵盤的顯示狀態，隱藏小鍵盤以節省螢幕空間。
  • 內建計算機模式：支援在輸入金額時直接進行加、減、乘、除運算。
  • 設定頁面提供開關以切換是否預設啟用計算機功能。
  • 編輯時自動預設選擇原始分類，提升使用體驗。
  • 鍵盤高度與間距優化，提供平滑的動畫效果和懸停視覺回饋。
• 緊湊輸入面板: 記帳輸入區域空間優化
  • 日期輸入採用同行布局（標籤與輸入框並排）
  • 統一的內邊距和間距設計（p-3, mb-3）
  • 金額顯示和輸入框高度調整，保持美觀的同時節省空間
  • 清晰的標籤系統，提升可用性
• 視覺化數據: 支出分析圖表增強
  • 甜甜圈圖中央顯示支出總額，多重渲染確保顯示
  • 支出分析區域添加「詳細統計」快速入口
  • 動態圖表渲染，確保中央文字正確顯示
• 類別選擇優化: 統一的視覺回饋系統
  • 選中類別使用綠色漸變背景配黑色邊框
  • 與記帳成功狀態保持一致的設計語言
  • 無放大效果，保持界面穩定性
• 自訂分類與帳戶圖示: 完整的圖示自訂能力
  • 支援自訂 Font Awesome 圖標輸入與關鍵字搜尋
  • 提供超過 2000 個 FontAwesome 內建圖示快速挑選
  • 即時圖標預覽功能
  • 可滾動的圖示選擇視窗，解決內容裁切問題
• 記錄編輯功能: 詳細記錄頁面的完整編輯能力
  • 支援修改記錄類型（收入/支出）
  • 動態分類選擇器，包含自定義分類
  • 完整的記錄屬性編輯（金額、說明、日期、分類）
  • 直觀的選中狀態視覺回饋
• 設定頁面增強: 重新設計的設定介面
  • 新增「應用程式」區塊，包含「強制更新」、「分享 App」、「安裝為應用程式」等實用功能。
  • 清晰的功能分組和視覺層次，將資料管理、應用程式設定與版本資訊分開。
  • 版本資訊卡片顯示當前版本號。

⁠🛠️ 技術升級與開發環境

⁠核心技術棧

• 前端框架: 原生 HTML/CSS/JS，無任何框架。
• CSS 框架: Tailwind CSS，提供原子化的 class，客製化彈性高。
• 圖表庫: Chart.js，用於資料視覺化。
• 圖標庫: Font Awesome 6。
• 資料儲存: 從 localStorage 升級到 IndexedDB，提供更強大的非同步儲存和查詢能力。

⁠開發工具

• 建置工具: Vite，提供快速的開發伺服器和建置功能。
• 程式碼品質: ESLint 進行程式碼檢查。
• 程式碼格式化: Prettier 統一程式碼風格。

⁠專案結構

輕鬆記帳/
├── src/                    # 源碼目錄
│   ├── js/                # JavaScript 模組
│   │   ├── main.js        # 主應用程式 (樞紐與路由控制)
│   │   ├── themeManager.js # 主題與外觀管理 (深淺色即時切換)
│   │   ├── aiService.js   # 離線 AI 語意記帳助手 (WASM/wllama)
│   │   ├── dataService.js # IndexedDB 資料存取層 (Schema v15)
│   │   ├── ledgerManager.js # 帳本管理商業邏輯
│   │   ├── groupManager.js # 群組分帳管理
│   │   ├── categories.js  # 分類常數與工具函數
│   │   ├── categoryManager.js # 自定義分類 UI 邏輯
│   │   ├── statistics.js  # 統計分析頁面 (含比較報表)
│   │   ├── recordsList.js # 記帳紀錄列表
│   │   ├── budgetManager.js # 預算管理
│   │   ├── quickSelectManager.js # 快速選擇管理
│   │   ├── debtManager.js  # 欠款管理
│   │   ├── changelog.js   # 版本更新日誌
│   │   ├── datePickerModal.js # 共用日期選擇器彈窗
│   │   ├── pluginManager.js # 擴充功能系統
│   │   ├── pluginStorage.js # 插件沙箱化儲存
│   │   ├── syncService.js # Google Drive 雲端同步 (Per-Device 獨立日誌與 Manifest)
│   │   ├── rewardService.js # 雙平台廣告服務
│   │   ├── tourManager.js # 新手引導與功能導覽核心
│   │   ├── tours/         # 模組導覽情境腳本
│   │   ├── router.js      # 路由管理
│   │   ├── utils.js       # 共用工具函數
│   │   └── pages/         # 頁面組件目錄 (首頁、帳戶、帳本、分攤等)
│   ├── css/               # 樣式檔案
│   │   └── main.css       # 主樣式
│   └── index.html         # 開發用 HTML
├── tests/                  # 測試代碼目錄
│   └── unit/              # 單元測試 (38 個測試檔案，1687 項測試全部通過)
├── public/                # 公共資源
│   ├── manifest.json      # PWA 配置
│   └── serviceWorker.js   # Service Worker
├── package.json           # 專案配置
├── vite.config.js         # Vite 配置
└── index.html             # 入口檔案

⁠開發環境設置

1. 安裝依賴:

   npm install
   

   Copy

2. 開發模式:

   npm run dev
   

   Copy

   這會啟動 Vite 開發伺服器，通常在 http://localhost:3000。

3. 建置生產版本:

   npm run build
   

   Copy

4. 預覽生產版本:

   npm run preview
   

   Copy

5. 程式碼檢查:

   npm run lint
   

   Copy

6. 程式碼格式化:

   npm run format
   

   Copy

7. 執行單元測試:

   # 單次執行所有測試
   npx vitest run
   
   # 開啟監聽模式 (Watch Mode)
   npx vitest
   

   Copy

⁠🤖 Android 開發（Capacitor）

⁠日常開發同步流程（最常用）

每次修改 Web 端程式碼後，依序執行：

# 1. 建置 Web 產出物
npm run build

# 2. 將 dist/ 同步進 android/ 原生專案
npx cap sync android

# 3. 開啟 Android Studio（選用，如需檢視原生層）
npx cap open android

若只修改了 Web 資源（HTML/CSS/JS），不需要重新編譯原生模組，可以使用更快的 copy：

npm run build && npx cap copy android

⁠常用指令速查

⁠完整首次建置流程

第一次在新環境建置 Android APK：

# 1. 安裝 Node 依賴
npm install

# 2. 建置 Web 端
npm run build

# 3. 同步到 Android 專案（含插件）
npx cap sync android

# 4. 開啟 Android Studio，在 Studio 內 Build → Generate Signed APK
npx cap open android

⁠Capacitor 設定說明

專案設定檔：capacitor.config.json⁠

{
    "appId": "com.walkingfish.easyaccounting",
    "appName": "輕鬆記帳",
    "webDir": "dist"
}

• webDir: "dist" — Capacitor 會從此目錄讀取 Web 資源，因此 build 是同步前提。
• androidScheme: "https" — 讓 WebView 以 HTTPS 方式載入本地資源，避免混合內容錯誤。

⁠🎨 外觀主題系統

輕鬆記帳提供完整的主題系統，讓開發者可以透過 JSON 定義視覺風格，無需修改任何程式碼。

⁠外觀模式支援

系統支援四種外觀模式（THEME_MODES）：

• 跟隨系統 (system)：預設模式，即時監聽作業系統 prefers-color-scheme 偏好自動切換深淺色。
• 淺色模式 (light)：固定使用清新亮色 Wabi-sabi 風格。
• 深色模式 (dark)：固定使用內建護眼深色主題。
• 自訂主題 (custom)：套用從主題商店下載或手動匯入的第三方主題包。

⁠主題運作原理

• 主題是一個 .json 檔案，放在 public/themes/ 目錄下
• 系統讀取主題後，將顏色注入全域 CSS 變數（--wabi-*），並透過 MutationObserver 監聽 DOM 持續替換指定圖示
• 主題可從「設定 → 外觀主題 → 主題商店」安裝，或直接匯入 .json 檔

⁠主題 JSON 結構摘要

{
    "id": "com.yourname.themename",
    "name": "主題名稱",
    "version": "1.0",
    "author": "作者",
    "colors": {
        "wabi-primary": "#...",
        "wabi-bg": "#...",
        "wabi-surface": "#...",
        "wabi-keypad": "#..."
    },
    "icons": {
        "nav#bottom-nav a[data-page='add'] i.fa-plus": {
            "type": "svg",
            "svg": "<svg ...>...</svg>",
            "className": "w-8 h-8"
        }
    }
}

⁠內建主題

⁠主題商店商店條目（public/themes/index.json）

每個主題在商店中需要額外提供以下資訊：

{
    "id": "...",
    "file": "themes/yourtheme.json",
    "svgPreview": "<svg>...</svg>",
    "iconPreview": "fa-solid fa-moon",
    "colorsPreview": {
        "bg": "#...",
        "primary": "#..."
    }
}

• svgPreview（優先）：以 SVG 字串作為商店卡片縮圖，系統以主色為背景、白色呈現圖示
• iconPreview：使用 FontAwesome class，以背景色＋主色文字呈現
• 兩者若都缺省，則以色點顯示
• colorsPreview 提供預覽色塊，最多顯示 5 色

⁠🔄 資料遷移

新版本會自動檢測並遷移舊版本的資料：

1. 檢測 localStorage 中的 AllTheData。
2. 自動轉換格式並匯入 IndexedDB。
3. 備份原始資料為 AllTheData_backup。
4. 清除舊的 localStorage 資料。

⁠📚 相關文件

• English Documentation (英文說明文件)⁠ - Complete project documentation in English
• Per-Device 同步架構技術文件 (English Spec)⁠ - Technical specification for the multi-user shared ledger sync protocol
• 完整更新日誌⁠ - 查看所有版本的詳細更新記錄
• 主題開發指南⁠ - 深入了解外觀主題自訂與商店規格
• 擴充功能開發指南⁠ - 插件系統 API 與沙箱架構說明

⁠🤝 貢獻

歡迎提交 Issue 和 Pull Request 來改善這個專案！

⁠

⁠📄 授權

MIT License

輕鬆記帳 2.0 - 讓記帳變得更簡單、更美觀、更智能！