adt109119

jijun

# 輕鬆記帳 2.0 - 現代化 PWA 這是「輕鬆記帳」應用程式的現代化版本，採用最新的前端技術重新打造，旨在提供更美觀、更易用、更穩健的記帳體驗。  📋 **[查看完整更新日誌](CHANGE_LOG.md)** - 了解所有版本的詳細更新內容 |  |  |  |------|------|------| ## 🚀 新功能特色與 UI/UX 改進 ### ✨ 全新設計與視覺效果 - **現代化 UI**: 採用 Tailwind CSS 打造的簡潔美觀介面，並使用漸層背景增添視覺層次。 - **響應式設計**: 完美適配手機、平板和桌面裝置，確保在不同裝置上都有一致且良好的視覺體驗。 - **流暢動畫**: 豐富的互動動畫提升使用體驗，例如分類按鈕的選中效果、滑動切換頁面等。 - **圖標顯示與顏色**: 整合 Font Awesome 6，所有圖標風格統一且清晰。分類按鈕支援自定義顏色，並有明確的選中狀態視覺回饋。 ### 📊 強化功能 - **資料視覺化**: 使用 Chart.js 提供圓餅圖（支出分類）和水位圖（預算管理），讓使用者能直觀地分析收支狀況。 - **智能統計**: 多維度收支分析和分類統計，首頁快速統計功能移至最上方，方便用戶快速概覽。 - **記錄管理**: 完整的增刪改查功能，記錄明細間距修復，同日記錄顯示更清晰。 - **智能攤提/分期**: 整合精準的攤提/分期引擎，自動處理四捨五入尾款，支援智能溢繳防護與即時狀態追蹤。 - **明細搜尋**: 明細頁面新增搜尋欄位，可依備註內容或交易金額即時篩選記錄。 - **帳戶餘額調整**: 帳戶管理頁面新增「平衡」按鈕，輸入實際餘額後自動計算差額，並可選擇自動建立「平帳」調整紀錄以維持帳目正確。 - **每月預算設定**: 可設定每月支出預算，水位圖動態顯示預算使用情況，並有超支警告。 - **自定義分類**: 完整的分類管理功能，可新增自定義分類、選擇圖示和顏色，並與預設分類無縫整合。 - **多帳本分類獨立化**: 自訂分類設定（包含分類、排序與隱藏）由原本全域共享重構為隨帳本獨立儲存。切換帳本時會自動重新載入該帳本專屬的分類設定。 - **共用日期選擇器**: 將明細與統計頁面的日期選擇 Modal 變為共用元件，解決先前統計頁面日期選擇異常的問題，並確保了介面體驗的一致性。 - **滑動手勢功能**: 首頁支援左右滑動切換支出分類和預算管理，實時跟隨手指移動，同時支援標籤點擊和圓點指示器。智能手勢識別，不會干擾頁面垂直滾動。 - **資料匯出入**: 支援完整的資料匯出和匯入功能，向下相容舊版資料格式，提供安全的資料備份和遷移。 - **PWA 更新機制**: 智能版本控制和自動更新提示，解決 PWA 快取問題，確保用戶始終使用最新版本。 - **PWA 管理功能**: 設定頁面新增「強制更新」、「分享 App」、「安裝為應用程式」等功能，提升 PWA 使用體驗。 - **版本管理**: 設定頁面顯示當前版本號和最後更新時間，支援手動檢查更新功能。 - **完整更新日誌**: 內建版本更新日誌系統，可查看所有歷史版本的詳細更新記錄。 - **可摺疊介面**: 記帳頁面的小鍵盤支援最小化功能，點擊備註列旁的鍵盤圖示按鈕即可切換顯示，緊湊設計節省螢幕空間。 - **智能導覽**: 底部導覽五欄式設計，涵蓋首頁、明細、記帳、統計、設定，核心功能一鍵直達。 - **詳細記錄管理**: 完整的記錄編輯功能，支援修改類型、分類、金額、說明和日期。 - **視覺化增強**: 支出分類甜甜圈圖中央顯示總額，提供直觀的支出概覽。 - **首頁小工具排序**: 支援自訂首頁小工具的排列順序，並可透過眼睛圖示切換各小工具的顯示狀態，讓常用資訊觸手可及。 - **自訂分類功能**: 支援自訂圖標輸入，可使用任何 Font Awesome 圖標類別創建個性化分類。 - **雲端備份與同步**: 整合 Google Drive，支援自動備份與多裝置間的資料同步，確保資料安全且隨處可用。 - **優化輸入體驗**: 記帳面板緊湊設計，日期輸入帶標籤，類別選擇使用統一的綠色主題效果。 ### 🧭 導覽系統 - **底部導覽列**: 優化的五欄式導覽，包含「首頁 (🏠)」、「明細 (📋)」、「記帳 (➕)」、「統計 (📊)」、「設定 (⚙️)」，核心功能一鍵直達。 - **設定頁面**: 整合了資料管理、應用程式管理與版本資訊，提供一站式的功能操作。 ### 📱 用戶介面改進 - **可摺疊小鍵盤**: 記帳頁面的數字鍵盤支援最小化功能 - 點擊備註列旁的鍵盤圖示按鈕可切換鍵盤的顯示狀態 - 最小化後隱藏數字鍵盤，節省螢幕空間 - 編輯時自動預設選擇原始分類，提升使用體驗 - 鍵盤高度優化，更緊湊的設計 - 平滑的動畫效果和懸停視覺回饋 - **緊湊輸入面板**: 記帳輸入區域空間優化 - 日期輸入採用同行布局（標籤與輸入框並排） - 統一的內邊距和間距設計（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 # 主應用程式 │ │ ├── dataService.js # 資料服務 │ │ ├── categories.js # 分類配置 │ │ ├── statistics.js # 統計圖表 │ │ ├── recordsList.js # 記錄列表 │ │ ├── budgetManager.js # 預算管理模組 │ │ ├── categoryManager.js # 自定義分類管理模組 │ │ ├── changelog.js # 版本更新日誌模組 │ │ ├── datePickerModal.js # 共用日期選擇器模組 │ │ └── utils.js # 工具函數 │ ├── css/ # 樣式檔案 │ │ └── main.css # 主樣式 │ └── index.html # 開發用 HTML ├── public/ # 公共資源 │ ├── manifest.json # PWA 配置 │ └── serviceWorker.js # Service Worker ├── icon/ # 圖示檔案 ├── package.json # 專案配置 ├── vite.config.js # Vite 配置 └── index.html # 入口檔案 ``` ### 開發環境設置 1. **安裝依賴**: ```bash npm install ``` 2. **開發模式**: ```bash npm run dev ``` 這會啟動 Vite 開發伺服器，通常在 `http://localhost:3000`。 3. **建置生產版本**: ```bash npm run build ``` 4. **預覽生產版本**: ```bash npm run preview ``` 5. **程式碼檢查**: ```bash npm run lint ``` 6. **程式碼格式化**: ```bash npm run format ``` ### 🤖 Android 開發（Capacitor） > [!IMPORTANT] > 在執行任何 Capacitor 同步指令前，**必須先建置**（`npm run build`）。Capacitor 會將 `dist/` 目錄打包進 Android 專案，不接受開發伺服器的 HMR 輸出。 #### 日常開發同步流程（最常用） 每次修改 Web 端程式碼後，依序執行： ```bash # 1. 建置 Web 產出物 npm run build # 2. 將 dist/ 同步進 android/ 原生專案 npx cap sync android # 3. 開啟 Android Studio（選用，如需檢視原生層） npx cap open android ``` 若只修改了 Web 資源（HTML/CSS/JS），不需要重新編譯原生模組，可以使用更快的 `copy`： ```bash npm run build && npx cap copy android ``` #### 常用指令速查 | 指令 | 說明 | |------|------| | `npx cap sync android` | 完整同步：複製 Web 資源 **+** 更新原生插件（推薦每次依賴更動後使用）| | `npx cap copy android` | 僅複製 Web 資源，跳過插件更新（速度較快）| | `npx cap open android` | 在 Android Studio 開啟原生專案 | | `npx cap run android` | 在連接的裝置 / 模擬器上直接執行（需要 ADB）| | `npx cap update android` | 更新原生插件至最新版本（`npm update` 後使用）| | `npx cap doctor` | 檢查 Capacitor 環境是否正確配置 | #### 完整首次建置流程 第一次在新環境建置 Android APK： ```bash # 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`](capacitor.config.json) ```json { "appId": "com.walkingfish.easyaccounting", "appName": "輕鬆記帳", "webDir": "dist" } ``` - `webDir: "dist"` — Capacitor 會從此目錄讀取 Web 資源，因此 **build 是同步前提**。 - `androidScheme: "https"` — 讓 WebView 以 HTTPS 方式載入本地資源，避免混合內容錯誤。 ## 🎨 外觀主題系統 輕鬆記帳提供完整的主題系統，讓開發者可以透過 JSON 定義視覺風格，無需修改任何程式碼。 ### 主題運作原理 - **主題是一個 `.json` 檔案**，放在 `public/themes/` 目錄下 - 系統讀取主題後，將顏色注入全域 CSS 變數（`--wabi-*`），並透過 `MutationObserver` 監聽 DOM 持續替換指定圖示 - 主題可從「設定 → 外觀主題 → 主題商店」安裝，或直接匯入 `.json` 檔 ### 主題 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" } } } ``` > **完整開發文件** → 詳見 **[THEME_DEV_GUIDE.md](THEME_DEV_GUIDE.md)** ### 內建主題 | 主題 ID | 名稱 | 特色 | |---------|------|------| | `com.walkingfish.theme.dark` | 深色模式 | 護眼深色，自動更新，不可刪除 | | `com.walkingfish.theme.sakura` | 櫻花粉 | 粉紅色系＋自訂五瓣花 SVG 圖示 | | `com.walkingfish.theme.ocean` | 深海湛藍 | 沉穩藍色系 | | `com.walkingfish.theme.cyberpunk` | 賽博龐克 | 霓虹黃／粉／青交錯 | | `com.walkingfish.theme.hightech` | 高科技駭客 | Matrix 黑綠代碼風 | ### 主題商店商店條目（`public/themes/index.json`） 每個主題在商店中需要額外提供以下資訊： ```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` 資料。 ## 🔧 問題排除與修復 ### 已修復的問題 - `getDateRange is not defined` 錯誤：已在 `main.js` 中正確導入 `getDateRange`。 - `Cannot read properties of null (reading 'classList')` 錯誤：在所有 DOM 操作前添加存在性檢查。 - IndexedDB 相容性問題：添加了 `localStorage` 備用機制。 - 圖表重複渲染問題：添加圖表實例管理，渲染前先銷毀舊圖表。 - 圖標顯示問題：在所有相關位置將圖標顯示從 `${categoryIcon}` 改為 `<i class="${categoryIcon}"></i>`。 - 分類按鈕樣式問題：使用內聯樣式強制覆蓋，確保樣式生效。 ### 常見問題 - **首頁圖表不顯示？** 確保有記帳資料，新用戶會顯示「本月暫無支出記錄」。 - **甜甜圈圖中央沒有總額？** 等待圖表載入完成，或重新整理頁面讓圖表重新渲染。 - **自定義分類不見了？** 自定義分類儲存在 `localStorage`，清除瀏覽器資料會遺失。 - **預算設定無效？** 檢查是否正確儲存，重新設定預算。 - **圖表顯示異常？** 重新整理頁面，圖表會重新渲染。 - **小鍵盤無法最小化？** 確保在記帳頁面，點擊備註列旁的鍵盤圖示按鈕（⌨️）即可切換鍵盤顯示。 - **記錄編輯無法修改分類？** 在編輯模態框中先選擇類型（收入/支出），再選擇對應的分類。 - **找不到統計頁面？** 統計功能有專屬的底部導覽頁籤（📊 統計），直接點擊即可進入詳細分析。 - **自訂圖標不顯示？** 確保輸入正確的 Font Awesome class 名稱（如：fas fa-heart），可使用預覽功能檢查。 - **新增分類視窗被裁切？** 視窗現在支援滾動，可以滾動查看所有內容和選項。 - **首頁無法滾動？** 在 slider 區域上下滑動現在可以正常滾動頁面，不會被手勢識別干擾。 - **編輯記錄時分類沒有預設選擇？** 現在會自動選擇記錄的原始分類，無需重新選擇。 - **類別選擇沒有視覺回饋？** 選中的類別會顯示綠色漸變背景和黑色邊框，確保已正確選擇。 - **記帳面板太大？** 面板已優化為緊湊設計，可點擊標題列最小化以節省更多空間。 - **檢查更新沒反應？** 檢查網路連線，或嘗試重新整理頁面後再試。 - **版本資訊不正確？** 版本資訊從應用程式內部讀取，如有問題請清除瀏覽器快取。 - **更新後功能異常？** 嘗試清除瀏覽器快取或重新安裝 PWA。 ## 📥📤 資料管理 ### 資料匯出功能 - **一鍵匯出**：點擊首頁右上角設定按鈕 → 匯出資料 - **格式支援**：JSON 格式，包含完整的記帳記錄和元數據 - **檔案命名**：自動以日期命名（例：`記帳資料_2024-01-15.json`） - **資料完整性**：包含版本資訊、匯出日期、記錄總數等元數據 ### 資料匯入功能 - **向後相容**：完全支援舊版資料格式自動轉換 - **格式檢測**：自動識別新版和舊版資料格式 - **資料驗證**：匯入前驗證資料完整性，過濾無效記錄 - **安全確認**：匯入前會提示確認是否覆蓋現有資料 - **錯誤處理**：提供友善的錯誤訊息和處理建議 ### 版本管理功能 - **版本資訊顯示**：設定頁面顯示當前應用程式版本號和最後更新時間 - **手動檢查更新**：點擊「檢查更新」按鈕主動檢查新版本 - **更新狀態提示**：智能識別並提示不同的更新狀態 - 🆕 發現新版本 → 顯示更新提示橫幅 - ⬇️ 正在下載新版本 → 顯示下載進度 - ✅ 已是最新版本 → 確認訊息 - ❌ 檢查失敗 → 錯誤提示和建議 - **自動時間記錄**：每次更新後自動記錄更新時間戳 ### 使用方法 1. **匯出資料**：設定頁面 → 資料管理 → 匯出資料 2. **匯入資料**：設定頁面 → 資料管理 → 匯入資料 → 選擇檔案 3. **檢查更新**：設定頁面 → 關於 → 檢查更新 4. **查看版本日誌**：設定頁面 → 關於 → 更新日誌 5. **應用程式管理**: 設定頁面 → 應用程式 → 點擊「強制更新」、「分享 App」或「安裝為應用程式」 ## 🔄 PWA 更新機制 ### 智能版本控制 - **自動檢測**：應用程式會自動檢測新版本的可用性 - **版本管理**：使用語義化版本號（如 v2.1.0.2）進行版本控制 - **快取策略**：採用多層快取策略確保更新的可靠性 ### 更新流程 1. **檢測更新**：當有新版本時，會自動在背景下載 2. **用戶通知**：顯示藍色更新橫幅提示新版本可用 3. **選擇更新**：用戶可選擇「立即更新」或「稍後更新」 4. **自動重載**：更新完成後自動重新載入頁面使用新版本 5. **手動更新**：使用者可至「設定」頁面點擊「強制更新」來手動清除快取並重載。 ### 安裝與分享 - **安裝提示**: 「設定」頁面提供「安裝為應用程式」按鈕，引導用戶將網站安裝為 PWA，此按鈕在安裝後會自動隱藏。 - **應用分享**: 「設定」頁面提供「分享此 App」按鈕，方便用戶透過原生分享功能推薦給朋友。 ### 快取管理 - **版本化快取**：每個版本使用獨立的快取空間 - **自動清理**：更新時自動清除舊版本快取 - **智能策略**： - **網路優先**：JS/CSS 檔案優先從網路獲取最新版本 - **快取優先**：圖片等靜態資源優先使用快取 - **離線支援**：網路不可用時回退到快取版本 ### 開發者更新指南 發布新版本時只需： 1. 修改 `package.json` 中的 `version` 欄位。 2. 執行 `npm run build`。 3. 建置過程會自動將版本號注入到 `src/js/` 的 JS 檔案與 `dist/serviceWorker.js` 中。 4. 部署應用程式，用戶訪問時會自動檢測並提示更新。 > [!NOTE] > 採用新的「單一來源版本注入」機制後，不再需要手動修改 `serviceWorker.js` 中的版本號。 ### 解決的問題 - ✅ **PWA 快取問題**：徹底解決已安裝 PWA 無法更新的問題 - ✅ **用戶體驗**：提供友善的更新提示和選擇權 - ✅ **自動管理**：無需手動清除快取或重新安裝 - ✅ **即時生效**：更新後立即使用最新功能 - ✅ **離線相容**：保持離線功能的同時確保及時更新 ## 📈 未來規劃 - [x] 雲端備份&同步功能 - [x] 多帳戶支援 - [x] 深色模式 - 多語言支援 - [x] 推送通知 (每日提醒) - 更多圖表類型 ## 📚 相關文件 - **[完整更新日誌](CHANGE_LOG.md)** - 查看所有版本的詳細更新記錄 ## 🤝 貢獻 歡迎提交 Issue 和 Pull Request 來改善這個專案！ ## 📄 授權 MIT License --- **輕鬆記帳 2.0** - 讓記帳變得更簡單、更美觀、更智能！