Prompt file imported from HyperLee/Demo (.github/prompts/PomodoroTechnique.prompt.md). Copyright stays with the author.

番茄鐘 (Pomodoro Technique) 規格書

文件資訊

• 文件版本：v1.0
• 最後更新：2025-09-25
• 文件擁有者：產品團隊

專案目標與價值

番茄鐘頁面旨在協助使用者透過「專注 + 休息」的節奏提升效率，降低疲勞並養成良好時間管理習慣。專案完成後應達成下列目標：

• 讓使用者能在單一頁面完成任務設定、計時、休息與進度追蹤。
• 透過視覺與音效強化提醒，減少使用者錯過休息或持續工作的情況。
• 支援多裝置使用與無障礙需求，擴大適用族群。
• 提供今日統計資訊，協助使用者掌握投入時間與完成番茄鐘數量。

成功指標 (Success Metrics)

• 90% 使用者能在首次進入頁面 1 分鐘內成功開始第一個番茄鐘週期。
• 80% 使用者在完成一次完整週期後，能識別並理解系統給出的休息提醒。
• 行動裝置載入速度於中階手機上須符合 Largest Contentful Paint < 2.5 秒。
• 音效提示符合 WCAG 2.1 AA 無障礙標準，可由使用者開啟/關閉。

範疇與系統位置

• 前端 Razor Page：/Users/qiuzili/Demo/Demo/Pages/PomodoroTechnique.cshtml
• 後端 PageModel：/Users/qiuzili/Demo/Demo/Pages/PomodoroTechnique.cshtml.cs
• 靜態資源可放置於 wwwroot/pomodoro/ (音效、圖示等)
• 本規格書聚焦單頁應用；不涉及整體導覽或其他模組整合

使用者角色與需求情境

假設與限制

• 初始版本僅針對單一使用者瀏覽器環境，不支援多人同步或帳號登入。
• 若瀏覽器阻擋音效自動播放，需提示使用者手動解鎖或提供備案提示。
• 本地儲存空間使用 localStorage，如空間不足需提示使用者清理。
• 時間計算以瀏覽器時間為準，不同步伺服器時間。
• 頁面需在 ASP.NET Core Razor Pages 結構內運作，無額外前端框架依賴。

高階流程概述

1. 使用者輸入任務名稱並啟動計時器。
2. 系統顯示倒數與動畫進度，並可暫停或重置。
3. 倒數結束時彈出提示並播放提示音，依週期自動切換至短休息或長休息。
4. 完成週期後更新今日統計並寫入本地儲存；若達四個番茄鐘，建議長休息。
5. 使用者可透過設定面板調整時間或切換語言 (屬於延伸區塊)。

使用者故事 (User Stories)

• 作為一名需要專注的使用者，我希望輸入任務名稱並啟動 25 分鐘倒數，讓我能專心完成當前任務。
• 作為一名容易被打斷的使用者，我希望能暫停或重置計時，以應對突發事件。
• 作為重視效率的使用者，我希望系統在每次倒數結束時提醒我，以免忘記休息或開始下一輪。
• 作為追蹤進度的使用者，我希望看到今日已完成的番茄鐘數量與投入時間，協助評估成效。
• 作為多語系使用者，我希望能切換語言介面，以便使用熟悉語言操作 (延伸需求)。

詳細功能需求

計時器狀態與設定

任務管理 (基礎)

• 單欄位輸入「任務名稱」，支援最多 120 字元。
• 當前週期綁定最新輸入的任務名稱；空白時以「未命名任務」顯示。
• 今日任務清單 (延伸需求) 可儲存多筆，預設版本僅維持最後一次輸入。

計時器視覺化

• 顯示 mm:ss 倒數，秒數需每秒更新。
• 以番茄圖示呈現進度動畫：考慮 SVG 或 CSS 圓形填滿方式。
• 若技術上難以前期完成動畫，可在 MVP 內提供靜態番茄圖示加上進度條，並於延伸需求中實作細緻動畫。

控制元件

• 開始：僅在 Idle 或 Paused 可觸發；啟動後按鈕轉為 暫停。
• 暫停：暫停計時，按鈕轉為 繼續。
• 重置：回到預設 25:00 並重置狀態為 Idle，同時重置番茄圖示填滿度。
• 跳過休息：在休息狀態下可顯示為次要按鈕，允許直接進入下一個工作週期。

提醒與提示

• 每次倒數歸零：
  • 顯示模態視窗或 Toast，內容包含：「工作完成，休息 5 分鐘」或「四個番茄鐘完成，建議長休息 15–30 分鐘」。
  • 播放提示音，可在設定面板中開關或調整音量。
• 若瀏覽器不支援自動播放音效，需在頁面表頭顯示提醒文字。
• 在視覺上同步顯示狀態標籤 (例如：專注中、短休息、長休息)。

今日進度追蹤

• 顯示以下資訊：
  • 已完成番茄鐘數量（工作週期）
  • 今日累積專注時間 (分鐘)
  • 目前迴圈完成情況 (例如 2 / 4)
• 數據需儲存在 localStorage，鍵值結構建議：

{
  "date": "YYYY-MM-DD",
  "focusSessions": 3,
  "totalFocusMinutes": 75,
  "sessions": [
    { "task": "撰寫報告", "duration": 25, "completedAt": "2025-09-25T09:15:00" }
  ]
}

• 重新整理頁面後需自動讀取當日資料並顯示。

教學引導

• 首次進入頁面需顯示簡短導覽 (3~4 步驟)：輸入任務、開始計時、休息提醒、查看統計。
• 導覽完成後在本地儲存紀錄，不再自動顯示；提供「重新查看指南」連結。

多語言支援 (延伸)

• 預計支援繁體中文、英文。
• 多語系字串集中管理，使用 JSON 或 RESX。
• 頁面提供語言切換選單，切換後即時更新文字。

無障礙設計

• 符合 WCAG 2.1 AA：對比度、鍵盤操作、ARIA 標籤。
• 計時器倒數需具備螢幕閱讀器友善描述。
• 音效提示須提供文字說明與可視化提示。

音效處理

• 預設使用單一提示音檔 (≤ 5 秒，檔案大小 ≤ 200KB)。
• 使用者可透過設定面板選擇是否播放音效，偏好儲存在本地儲存。
• 手機端需考量靜音模式，若無法播放需顯示提示文字。

響應式規範

• Desktop ≥ 1024px：左右分欄，左側計時器，右側統計與任務詳細。
• Tablet 768~1023px：上下堆疊，按鈕改為寬版。
• Mobile ≤ 767px：單欄排列，字體與按鈕尺寸符合可點擊性 (最小 44px 高)。

外觀設定

• 主色：#FF6347 (番茄紅)、#FFA500 (橙)、#FFD54F (暖黃)。
• 背景採用柔和淺色，避免過度亮眼。
• 按鈕與進度條需展現漸層或陰影，增加溫暖感。

延伸與優先順序

後端與資料處理考量

• PageModel 提供初始載入資料 (例如使用者名稱、預設設定)，並處理音效或多語系設定的伺服器端控制。
• 若未登入則僅使用本地儲存；若後續導入登入機制，需提供 API 將 JSON 結構同步到伺服器端。
• 考量日後擴充，可預留服務層介面，以便接入資料庫或雲端儲存。

監測與日誌

• 前端需記錄下列事件 (以 console 訊息或後續遙測管道為主)：
  • 啟動/暫停/重置/倒數完成
  • 長休息提醒顯示次數
  • 教學導覽完成狀態
• 若後端存取，需記錄 API 呼叫錯誤與資料寫入狀態。

品質保證與驗收標準

• 功能驗收清單：
  • 能夠輸入任務名稱並開始倒數。
  • 倒數結束時顯示提示並更新統計。
  • 連續完成四個番茄鐘後觸發長休息提醒。
  • 本地儲存資料於重新整理後仍能正確顯示。
  • 音效可依使用者偏好開啟或關閉。
• 無障礙驗收：鍵盤操作無障礙、螢幕閱讀器可朗讀主要資訊。
• 響應式驗收：Chrome DevTools 三個斷點寬度測試顯示正常。
• 效能：首屏載入資源大小 < 1MB，計時器運作對主執行緒負擔低 (利用 requestAnimationFrame 或 setInterval，間隔 1 秒)。

已知風險與待決議事項

• 動畫呈現複雜度：若 CSS / SVG 動畫工時過高，可優先交付基本進度條。
• 音效授權：需確認提示音檔案是否可於商業環境使用。
• 多語系字串來源：需決定由產品團隊或在地化團隊提供翻譯。
• 長時間停留頁面可能導致瀏覽器睡眠，需評估是否需要背景工作或提醒。

後續建議 (迭代方向)

• 與行事曆整合，自動安排番茄鐘時段。
• 引入社群挑戰或成就徽章增加動機。
• 與習慣追蹤模組整合，提供跨模組統計。

此規格書供產品、設計、開發與測試團隊對齊番茄鐘頁面之完整需求與預期成果，後續若有變更請更新文件版本並通知相關人員。