身為一名大學講師，我知道很多研究生每天都在與時間賽跑。諸如論文進度、文獻閱讀、實驗數據以及與指導教授開會的會議記錄⋯⋯這些資訊，散落在不同的應用程式中：待辦事項用 Notion，筆記用 Heptabase，文獻管理用 Zotero，時間追蹤用番茄鐘 App。我看到很多人，每天光是在這些工具之間切換，就耗費了大量的認知負荷。作者：鄭緯筌（專欄作家，「臺灣電子商務暨創業聯誼會」共同創辦人，前「APP01」網站總監、《風傳媒》產品總監和《數位時代》雜誌主編）

Debug 之旅：當測試成為最好的老師

環境變數的隱形殺手

在本地測試時，一切運作正常。但當用戶回報「新增筆記失敗」時，我陷入了困惑。後端日誌顯示沒有收到任何 POST 請求，前端卻顯示「保存失敗，請稍後再試」。老實說，這種「幽靈錯誤」最難除錯，因為你不知道問題出在哪一個環節？

經過 Claude Code 仔細地檢查，發現前端開啟了兩個 Vite 開發伺服器實例，而且它們使用的環境變數可能不一致。問題的根源在於我在不同的終端視窗中多次執行 npm run dev，而 Vite 的熱重載機制讓我誤以為服務已經更新。

經過與 Claude Code 的討論，解決方法很直接：關閉所有 Vite 進程，重新啟動單一實例。但這個經驗讓我學會了使用 ps aux | grep vite 來檢查執行中的進程，以及在啟動服務前先確認沒有殘留的進程。更重要的是，我在專案中加入了 .env.example 檔案，明確記錄所有需要的環境變數，避免團隊成員（或未來的自己）踩到同樣的坑。

資料庫初始化的暗黑時刻

在準備部署時，我發現一個更嚴重的問題：本地測試用的 SQLite 資料庫檔案是 0 位元組。這意味著資料庫從未真正初始化成功，我一直在測試的是某個未知位置的資料庫檔案。

原來，Flask 的資料庫初始化邏輯預設會在 instance 目錄下創建資料庫檔案，而我的 app.py 中使用了相對路徑 sqlite:///gradpilot.db，這導致 Flask 在預期的位置找不到資料庫。更糟的是，我在 app.py 中實作了一個簡單的初始化機制：只有在第一次請求時才創建資料表。如果這個機制失敗，所有後續的請求都會失敗，但錯誤訊息卻不明確。

修復這個問題，需要手動執行資料庫初始化：進入 Python shell，匯入 app 和 db，然後執行 db.create_all()。從那之後，我學會了在專案的 README.md 中明確記錄初始化步驟，並在部署腳本中加入資料庫初始化指令。這個教訓告訴我，部署前的環境驗證絕對不能省略。

測試驅動的品質保證

當所有功能都實作完成後，我面臨一個問題：如何確保所有功能都能正常運作？手動測試既耗時，又容易遺漏細節。於是，我請 Claude Code 創建了一份詳盡的測試清單 TESTING_CHECKLIST.md，涵蓋 12 個主要功能模組、超過 300 個測試項目。

這份清單不僅僅是一個核取清單，它更像是一份互動式的測試指南。每個測試項目都包含明確的操作步驟和預期結果，讓任何人都能按圖索驥地完成測試。在測試過程中，我發現了前面提到的所有 bug，也驗證了修復的正確性。

在測試的過程中，也讓我重新審視了使用者體驗。例如，我發現番茄鐘的提示文字寫著「保持專注 25 分鐘」，但這個數字應該根據使用者設定動態改變。這種細節很容易在開發過程中被忽略，但對使用者體驗卻有顯著影響。

部署的最後一哩路

在本地端的程式順利執行之後，接下來會遇到另一個問題，就是不知要部署到哪個主機？得花多少錢？

經過 Claude Code 的建議，最後選擇了 Render 作為部署平臺。相比於 Heroku（已取消免費方案）和 AWS（對新手不友善），Render 提供了簡單易用的介面和慷慨的免費額度。更重要的是，它原生支援從 Git 倉庫自動部署，這讓 CI/CD 流程變得極其簡單。

此外，部署配置檔 render.yaml 很重要，它定義了整個應用的架構：PostgreSQL 資料庫、Python 後端服務與靜態前端網站。Render 會自動讀取這個檔案，創建所有必要的資源，並設定正確的環境變數。唯一需要手動處理的是敏感資訊如 SECRET_KEY 和 JWT_SECRET_KEY，Render 提供了自動生成功能，確保每個部署環境都有獨立的密鑰。

第一次部署時，我遇到了 CORS 錯誤。前端部署在 gradpilot-frontend.onrender.com，後端部署在 gradpilot-backend.onrender.com，瀏覽器的同源政策阻止了跨域請求。解決方法是在後端配置 CORS 白名單，允許來自前端域名的請求。這個問題提醒我，本地開發環境和生產環境的差異永遠存在，必須在實際部署後進行完整測試。

效能優化：在免費方案的限制中求生存

值得注意的是，Render 的免費方案有一個顯著的限制：服務閒置 15 分鐘後會進入休眠狀態，下次訪問時需要 30-60 秒的喚醒時間。這對使用者體驗是個挑戰，但也促使我思考如何在前端層面進行優化。

在 Claude Code 的協助之下，我實作了一個簡單但有效的載入狀態管理系統。當使用者首次訪問時，如果後端還在喚醒，前端會顯示友善的載入動畫和提示訊息，而不是讓使用者面對一片空白。這個小小的改變大幅提升了使用者的容忍度。

另一個優化是實作資料快取。用戶的基本資訊在登入後會存放在 localStorage，避免每次頁面刷新都需要重新從後端獲取。這不僅加快了載入速度，也減少了後端的負擔。當然，敏感資訊如 JWT token 需要謹慎處理，我設定了合理的過期時間，並在登出時清除所有快取資料。

從 MVP 到產品：使用者回饋的力量

當 GradPilot 2.0 上線後，我邀請了幾位研究生朋友試用。他們的回饋既有鼓勵也有批評，但都極具價值。有人反映番茄鐘的預設時間太長，有人希望能在筆記中插入圖片，有人建議增加資料匯出功能以防資料遺失。

這些回饋，促使我重新思考產品的定位。GradPilot 不應該是一個功能完整的工具，而應該是一個恰到好處的工具。畢竟，研究生已經有太多複雜的工具需要學習，他們需要的是一個簡單、直覺又能專注於核心需求的平臺。

基於這個認知，我實作了資料匯出功能，支援 JSON、CSV 與 Markdown 等多種格式。這不僅解決了資料備份的需求，也讓使用者能自由地將資料遷移到其他工具。這種不鎖定使用者的設計哲學，反而增加了使用者的信任和忠誠度。

技術債與重構的永恆輪迴

隨著功能的增加，技術債也在累積。有些程式碼寫得匆忙，有些設計不夠優雅，有些測試覆蓋不足。但作為一個新手開發者，我必須在完美和完成之間取得平衡。

Claude Code 教會我採用漸進式重構的策略，也就是每次新增功能時，順帶重構相關的舊程式碼。例如，在實作文獻管理功能時，我發現待辦事項和筆記的標籤處理邏輯幾乎相同，於是我抽取了一個共用的 formatTags 函數。這種遇到問題就修改的策略，讓程式碼品質在不知不覺中持續提升。

當然，有些技術債必須專門騰出時間來處理。例如，前端的狀態管理一度變得非常混亂，有些狀態存在 Context，有些存在組件內部，有些存在 localStorage。我花了一個晚上梳理問題，統一了狀態管理的模式，大幅降低 bug 的發生率。

開源與社群：站在巨人的肩膀上

這個專案能取得初步的成功，很大程度上歸功於開源社群。Flask、React、Vite、TailwindCSS⋯⋯每一個工具都凝聚了無數開發者的心血。當我遇到問題時，往往能在 Stack Overflow、GitHub Issues 或官方文件中找到答案。

作為回饋，我選擇將 GradPilot 2.0 的完整原始碼開源在 GitHub 上，並撰寫了詳盡的文件和部署指南。我希望這個專案能幫助其他有類似需求的研究生，也希望它能成為初學者學習全端開發的參考案例。

開源不僅僅是分享程式碼，更是分享知識和經驗。在撰寫文件的過程中，我重新審視了自己的設計決策，發現了許多可以改進的地方。教學相長，這個過程本身就是一種學習。

展望未來：永不停歇的迭代

GradPilot 2.0 目前已經滿足了我的基本需求，但這只是開始。我已經在規劃 3.0 版本，計劃加入更多進階功能：與文獻資料庫的 API 整合、基於機器學習的文獻推薦或多人協作的研究筆記等。

但在追求新功能之前，我會先確保現有功能的穩定性和使用者體驗。這是我在這次開發中學到的最重要的一課：好的產品不是功能最多的產品，而是最能解決使用者問題的產品。

回顧這 30 個小時的開發旅程，在 Claude Code 的協助之下，我不僅建立了一個實用的工具，更重要的是培養了一種系統化的思考方式。面對複雜的問題，如何拆解成可管理的小任務？遇到 bug 時，如何有條理地排查？在資源有限的情況下，如何做出明智的技術選擇？

我覺得，這些能力遠比寫出漂亮的程式碼更重要。技術會過時，工具會更迭，但解決問題的思維方式是永恆的。GradPilot 2.0 對我來說不只是一個專案，它是一次完整的學習歷程，一次從想法到產品的實踐，一次對自己能力的挑戰和證明。

無論你是一位上班族或研究生，如果你也有想要解決的問題，我鼓勵你動手去做。不要被技術的複雜性嚇倒，不要等到準備好了才開始。正如我的經驗所示，最好的學習往往發生在實作的過程中，最大的成長往往來自於克服困難的時刻。

現在，就開始和 AI 共創你的第一行程式碼吧。你的作品正在呼喚你！

這篇文章 Vibe Coding 從零到部署： 30 個小時寫出一套學習儀表板（下）｜專家論點【鄭緯筌Vista】 最早出現於 科技島-掌握科技新聞、科技職場最新資訊。

身為一名大學講師，我知道很多研究生每天都在與時間賽跑。諸如論文進度、文獻閱讀、實驗數據以及與指導教授開會的會議記錄⋯⋯這些資訊，散落在不同的應用程式中：待辦事項用 Notion，筆記用 Heptabase，文獻管理用 Zotero，時間追蹤用番茄鐘 App。我看到很多人，每天光是在這些工具之間切換，就耗費了大量的認知負荷。作者：鄭緯筌（專欄作家，「臺灣電子商務暨創業聯誼會」共同創辦人，前「APP01」網站總監、《風傳媒》產品總監和《數位時代》雜誌主編）

當理想遇上現實：從研究生的數位焦慮談起

身為一名大學講師，我知道很多研究生每天都在與時間賽跑。諸如論文進度、文獻閱讀、實驗數據以及與指導教授開會的會議記錄⋯⋯這些資訊，散落在不同的應用程式中：待辦事項用 Notion，筆記用 Heptabase，文獻管理用 Zotero，時間追蹤用番茄鐘 App。我看到很多人，每天光是在這些工具之間切換，就耗費了大量的認知負荷。

「為什麼沒有一個專為研究生設計的整合平臺？」這個念頭在我腦海中盤旋許久。直到某個深夜，當我再次因為找不到某篇文獻筆記而焦慮時，我決定親手打造一個解決方案。這就是 GradPilot 2.0 （https://vista.im/gradpilot）的誕生契機——一個專為研究生設計的全方位學習儀表板。

技術選型：在理想與務實之間取得平衡

作為一個不諳程式設計的新手，之前只有少數使用 Lovable 和 Gemini 寫程式的經驗。這回，我改用 Claude Code 來開發。原本很擔心看不懂它的文字介面，但實際操作之後發現自己多慮了。遇到問題是很正常的事情，多跟 AI 討教就是了！不過，當然 tokens 也燒得很快。

在 Claude Code 的建議之下，我選擇了 Flask 作為後端框架。倒不是因為它最新潮，而是因為它夠簡單、文件完整，讓我能夠快速上手。前端則選擇 React 搭配 Vite，這個組合在 2024 年時已經非常成熟，社群資源豐富，遇到問題時能快速找到解決方案。

資料庫方面，開發環境使用 SQLite 讓我能快速迭代，生產環境則切換到 PostgreSQL。這種彈性得益於 SQLAlchemy 的抽象層，讓我不需要為了資料庫切換而重寫大量代碼。最重要的是，所有這些技術都能在 Render 的免費方案上運行，這對預算有限的開發者來說非常重要。

架構設計：從混亂到清晰的演進

老實說，因為自己不是資訊背景出身，所以最初的架構設計其實相當簡陋。我只是想著先讓它跑起來再說，結果就是一個巨大的 app.py 檔案，所有路由、邏輯和資料庫操作全部擠在一起。當檔案超過 500 行時，我開始感受到維護的痛苦。

重構的契機，來自於新增文獻管理功能。我意識到如果繼續這樣下去，專案很快就會變成無法維護的龐大代碼。於是我花了半天光景，請 Claude Code 將專案重構成清晰的模組化架構：

後端採用藍圖（Blueprint）模式，將認證、待辦事項、筆記、番茄鐘與文獻管理等功能分離成獨立的模組。每個模組都有自己的路由檔案和業務邏輯，資料庫模型則統一放在 models 目錄下。這樣的架構讓我能夠專注於單一功能的開發，而不會被其他部分干擾。

前端的組件化，也遵循類似的思路。每個功能都有自己的組件目錄，包含相關的子組件。例如待辦事項功能包含 TodoList、TodoItem、TodoForm 等組件，每個組件職責單一，易於測試和維護。

功能實現：細節中的魔鬼

番茄鐘的時間魔法

番茄鐘功能看似簡單，實際上充滿了細節考量。最初的實現中，我直接在組件內硬寫入 25 分鐘的專注時間和 5 分鐘的休息時間。這在開發階段沒有問題，但當用戶回饋希望能自訂時長時，問題就來了。

第一個挑戰，是如何在組件中讀取用戶設定。我使用 React Context 來管理全域的用戶狀態，但番茄鐘組件卻忘記從 Context 中讀取 pomodoro_duration 和 break_duration。這導致了一個有趣的 bug：用戶在設定頁面修改時長後，回到 Dashboard 卻發現番茄鐘仍然顯示 25:00。

若想修復這個問題，就需要在多個地方調整，好比：初始化狀態時使用用戶設定、重置時使用用戶設定、模式切換時使用用戶設定以及進度計算時使用用戶設定。每一個地方，都需要將硬編碼的數字替換成從 Context 讀取的動態值。這個看似簡單的改動，實際上觸及了組件的每個角落。

文獻管理的格式化陷阱

文獻管理功能，則是整個專案中最複雜的部分。學術引用有多種格式標準（APA、MLA、Chicago、Harvard等），每種格式都有嚴格的規範。Claude Code 幫我實作了一個 formatter.py 模組來處理不同的引用格式，每種格式都有對應的類別和格式化方法。

然而，一個看似無害的設計決策差點毀了整個功能：在格式化期刊名稱時，我使用了 Markdown 的斜體語法 *Journal Name*，希望在顯示時能呈現斜體效果。問題是，當用戶複製引用格式到 Word 或其他編輯器時，這些星號也被一併複製了，導致引用格式不符合標準。

這個 bug 的修復看似簡單——移除星號即可。但實際上我需要在六個不同的格式化方法中找出所有使用星號的地方，確保期刊名稱、書名與網站名稱等都使用純文字而非 Markdown 格式。這提醒了我一個重要的原則：資料的儲存格式應該與顯示格式分離。Markdown 應該只用於顯示層，而不應該滲透到資料層。

標籤系統的陣列與字串之爭

在待辦事項和筆記中，都有使用標籤功能。後端資料庫將標籤儲存為逗號分隔的字串（例如 "研究,論文,實驗"），但為了方便前端處理，我在 to_dict() 方法中將其轉換為陣列（例如 ["研究", "論文", "實驗"]）。

這個設計在大多數情況下運作良好，直到用戶嘗試編輯筆記。編輯表單期望 tags 是一個字串（因為 input 欄位只能接受字串），但從 API 獲取的筆記物件中 tags 是一個陣列。當我直接將陣列賦值給表單的 tags 欄位時，JavaScript 會隱式地將陣列轉換成字串，結果變成了 "研究,論文,實驗"——看起來沒問題，但當有空格時就會出現意外的行為。

最終的解決方案，是在 handleEdit 函數中明確地進行轉換：tags: Array.isArray(note.tags) ? note.tags.join(',') : (note.tags || '')。這行代碼確保無論後端返回的是陣列還是字串，都能正確地轉換成表單需要的格式。這個經驗告訴我，資料類型的一致性非常重要，在資料流轉的每個環節都需要明確定義期望的類型。

這篇文章 Vibe Coding 從零到部署： 30 個小時寫出一套學習儀表板（上）｜專家論點【鄭緯筌Vista】 最早出現於 科技島-掌握科技新聞、科技職場最新資訊。