<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Ioariroi on Medium]]></title>
        <description><![CDATA[Stories by Ioariroi on Medium]]></description>
        <link>https://medium.com/@ioariroi?source=rss-f4d71b1c82ec------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*9_WZScYu74I-Jy_r1f0CSg@2x.jpeg</url>
            <title>Stories by Ioariroi on Medium</title>
            <link>https://medium.com/@ioariroi?source=rss-f4d71b1c82ec------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 08:06:00 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@ioariroi/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[從需求到系統設計：我怎麼把一個 Todo App，做成一個真正可落地的 iPhone 本機系統]]></title>
            <link>https://medium.com/@ioariroi/%E5%BE%9E%E9%9C%80%E6%B1%82%E5%88%B0%E7%B3%BB%E7%B5%B1%E8%A8%AD%E8%A8%88-%E6%88%91%E6%80%8E%E9%BA%BC%E6%8A%8A%E4%B8%80%E5%80%8B-todo-app-%E5%81%9A%E6%88%90%E4%B8%80%E5%80%8B%E7%9C%9F%E6%AD%A3%E5%8F%AF%E8%90%BD%E5%9C%B0%E7%9A%84-iphone-%E6%9C%AC%E6%A9%9F%E7%B3%BB%E7%B5%B1-4088ed5325b4?source=rss-f4d71b1c82ec------2</link>
            <guid isPermaLink="false">https://medium.com/p/4088ed5325b4</guid>
            <category><![CDATA[reactive-native]]></category>
            <category><![CDATA[sqlite]]></category>
            <category><![CDATA[mobile-app-development]]></category>
            <dc:creator><![CDATA[Ioariroi]]></dc:creator>
            <pubDate>Tue, 24 Mar 2026 15:32:15 GMT</pubDate>
            <atom:updated>2026-03-25T15:03:08.164Z</atom:updated>
            <content:encoded><![CDATA[<p><em>不是從畫畫面開始，而是先把產品問題、系統邊界與狀態規則想清楚。</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*g5njJD0NQ2KllP9tXBKqAw.png" /><figcaption>Todo App</figcaption></figure><p>如果今天有人說：「我想做一個待辦事項 App。」多數人的第一反應，通常會是先想到幾個熟悉的畫面。</p><p>首頁清單、建立任務表單、完成按鈕、分類、提醒，大概就這些。</p><p>但真正開始定義需求之後，你很快就會發現，Todo App 真正麻煩的地方，從來都不是畫面本身，而是那些藏在畫面背後的規則。</p><p>任務完成後要不要立刻消失？<br>重複任務的下一筆什麼時候產生？<br>子任務全部勾完時，主任務要不要自動完成？<br>刪除是永久刪除，還是先進垃圾桶？<br>如果任務時間被修改了，提醒通知要怎麼重排？</p><p>這些問題一旦出現，Todo App 就不再只是「一個 CRUD 練習」，而是一個完整的系統設計題。</p><p>這篇文章想談的，就是我如何從 PRD 與 SRS 出發，把一個看似普通的 Todo App，拆成一個可以真正落地實作的 iPhone 本機型系統。</p><h3>這個專案想解決的，其實不是「記一筆待辦」而已</h3><p>這個專案的產品定位很明確：它不是團隊協作工具，也不是跨平台同步服務，而是一個只支援 iPhone、完全本機使用、不需要登入的待辦事項 App。</p><p>這個選擇乍看很保守，但我反而覺得它很有力量。</p><p>因為它等於先把很多常見的複雜度主動排除掉了：</p><ul><li>帳號登入</li><li>雲端同步</li><li>跨裝置一致性</li><li>多人協作</li><li>第三方日曆整合</li></ul><p>一旦把這些東西拿掉，整個產品的重心就回到最核心的問題上：</p><p>使用者能不能快速建立任務、準時被提醒、清楚整理清單，並且在不依賴任何後端服務的情況下，穩定完成這整條流程。</p><p>這也讓產品價值變得非常聚焦：</p><ul><li>快速記錄與整理待辦事項</li><li>透過提醒與逾期機制降低遺漏風險</li><li>用分類、子任務、優先級與重複規則處理日常節奏</li><li>用 JSON 匯出為未來備份與匯入保留空間</li></ul><p>換句話說，這不是一個「什麼都想做」的 productivity app，而是一個把個人任務管理做深、做穩的 local-first app。</p><h3>真正困難的地方，是需求一多就不再只是畫面問題</h3><p>我一開始就很清楚，這個專案不能只用「首頁 + 表單 + 詳情頁」的角度去想。</p><p>因為 PRD 一旦把需求寫完整，問題會立刻從畫面切換成規則：</p><ul><li>任務有 active、overdue、completed、trashed 幾種狀態</li><li>刪除後不是消失，而是進垃圾桶保留 30 天</li><li>垃圾桶不可還原，但可立即永久刪除</li><li>重複任務完成後要立刻建立下一筆</li><li>甚至在某些情況下，重複任務逾期未完成，後續任務仍要持續產生</li><li>子任務全完成時，可能要自動完成主任務</li><li>提醒通知不只是建立，還包含更新、取消、重排與逾期提醒</li></ul><p>這些需求有一個共同點：它們都不是單一畫面自己能決定的。</p><p>它們牽涉的是：</p><ul><li>資料模型</li><li>狀態轉換</li><li>多資料表關聯</li><li>通知副作用</li><li>清單查詢規則</li><li>文案與使用者預期的一致性</li></ul><p>也就是說，這個專案真正要解的，不是「怎麼列出任務」，而是「怎麼把任務生命週期定義清楚，並讓系統穩定執行」。</p><h3>所以我先決定：把它當成一個系統設計題，而不是 UI 題</h3><p>當我開始看 SRS 時，我最先抓到的一個核心觀點是：這個 App 應該被拆成幾個責任明確的層，而不是把資料處理直接寫進畫面。</p><p>我最後認同的方向是這樣：</p><ul><li>UI Layer 負責畫面渲染與互動</li><li>UseCase Layer 負責任務生命週期與規則</li><li>Repository Layer 負責資料讀寫邊界</li><li>Local Database Layer 負責 SQLite schema、migration 與查詢</li><li>Notification Scheduler Layer 負責提醒通知</li><li>Export Layer 負責 JSON 匯出與版本化</li></ul><p>這個決定其實很關鍵。</p><p>因為它等於先回答了一個問題：<strong>產品規則到底要住在哪裡？</strong></p><p>如果沒有這一層思考，最常發生的情況就是：</p><ul><li>完成任務的邏輯有一半寫在清單頁</li><li>子任務自動完成的判斷寫在 detail 頁</li><li>通知取消寫在某個按鈕 handler</li><li>匯出格式組裝散在不同 service 裡</li></ul><p>功能短期看起來都能動，但規則很快就會四散。</p><p>對 Todo App 這種功能不算難、但狀態與邏輯很多的產品來說，這種分層比「先把頁面做出來」重要得多。</p><h3>幾個我覺得最重要的設計決策</h3><h3>1. 先把它做成真正的 local-first app</h3><p>這是整個專案最早、也最重要的產品決策。</p><p>一旦確認這個版本不做登入、不做同步、不做多人協作，很多技術選擇就自然收斂了。</p><p>例如資料儲存，SQLite 幾乎是很合理的答案。<br>它不只是「可以存資料」，更重要的是它很適合這種本地查詢多、狀態切換多、又需要清楚資料邊界的 app。</p><p>同樣地，提醒功能也不需要先去依賴遠端排程服務，而是直接用 iOS Local Notifications。</p><p>這樣的好處很直接：</p><ul><li>所有核心功能都能離線成立</li><li>使用者不需要帳號</li><li>系統回應速度快</li><li>架構複雜度明顯下降</li></ul><p>但它也帶來一個反面要求：所有規則都要在裝置端被嚴謹執行。</p><p>例如 overdue refresh、trash cleanup、notification rescheduling、recurring generation，這些都不能推給後端處理。</p><p>換句話說，少了後端，不代表系統變簡單，而是責任整個回到本地端。</p><h3>2. 不把 Todo App 當成 CRUD，而是當成狀態機</h3><p>這是我在讀 SRS 時感受最強的一點。</p><p>如果只看功能列表，Todo App 好像就是：</p><ul><li>新增</li><li>編輯</li><li>刪除</li><li>完成</li></ul><p>但一旦用狀態來看，它其實更像一個狀態機：</p><ul><li>active</li><li>overdue</li><li>completed</li><li>trashed</li></ul><p>而且每次狀態轉換，都不是單純改一個欄位而已。</p><p>例如 complete task 背後其實包含：</p><ul><li>更新 task status</li><li>記錄 completed time</li><li>取消未來通知</li><li>如果是 recurring task，立即建立下一筆</li><li>觸發完成動畫</li></ul><p>再例如 move to trash 背後也不只是刪掉資料，而是：</p><ul><li>狀態改成 trashed</li><li>記錄 deletedAt</li><li>取消通知</li><li>從首頁、已完成頁與預設搜尋結果中排除</li></ul><p>當我用這個角度理解需求後，use case 的切法就變得很自然：</p><ul><li>CreateTaskUseCase</li><li>UpdateTaskUseCase</li><li>CompleteTaskUseCase</li><li>MoveTaskToTrashUseCase</li><li>RefreshTaskStatusUseCase</li><li>GenerateNextRecurringTaskUseCase</li></ul><p>這些名字看起來像工程細節，但它們其實是把產品規則變成系統邊界的過程。</p><h3>3. 先把 recurring task 當成獨立模組，不要只是加一個 flag</h3><p>如果只想做最小功能，重複任務很容易被做成一個簡單欄位：</p><ul><li>isRecurring = true</li></ul><p>但這樣其實不夠。</p><p>因為 recurring task 真正要解的不是「這筆任務是不是會重複」，而是：</p><ul><li>recurrence type 是什麼</li><li>recurrence interval 是多少</li><li>下一筆 due date 怎麼算</li><li>要不要複製 subtasks</li><li>要不要複製 reminders</li><li>生成後如何保留 parent-child 關係</li></ul><p>更麻煩的是，PRD 還點出一個很重要的邊界情境：</p><p>如果前一筆 recurring task 已經逾期但還沒完成，系統仍可能要繼續產生下一筆。</p><p>這一條一出來，這個 feature 就不再只是「完成後複製一筆」。 它變成一個和時間軸、任務關聯、查詢效能與 UI 清晰度都有關的模組設計問題。</p><p>所以我很認同 SRS 裡把 recurrence 單獨拉成一個 module。</p><h3>4. 讓匯出格式一開始就版本化</h3><p>這個設計點我很喜歡，因為它很工程，但又很貼近產品長期性。</p><p>這個專案雖然沒有後端，但文件很明確要求 JSON 匯出，而且未來要保留匯入相容性。</p><p>如果只是把資料直接輸出成一份 JSON，那看起來很快能做完，但未來 schema 一旦變更，就會遇到版本相容問題。</p><p>所以 SRS 要求 export payload 至少要有：</p><ul><li>schema_version</li><li>exported_at</li><li>export_type</li></ul><p>這個決定的價值在於，它讓匯出從一個「功能按鈕」，變成一個有明確格式責任的資料交換層。</p><p>這種設計很適合 local-first app，因為它讓系統即使沒有遠端 API，仍然有乾淨的資料輸出邊界。</p><h3>把需求拆成模組之後，整個系統開始有骨架</h3><p>當我把整份需求重新整理後，這個專案的主要模組就變得很清楚。</p><h3>Task Module</h3><p>這是整個系統的核心，負責任務 CRUD、狀態切換、清單查詢、詳情讀取與移入垃圾桶。</p><p>它看起來最普通，但其實承接了最多橫向規則。因為完成、逾期、刪除、首頁排序與搜尋結果，大多都會回到 task 狀態本身。</p><h3>SubTask Module</h3><p>子任務最容易被低估。</p><p>表面上只是 checklist，但實際上它直接影響 parent task 是否要自動完成。這種跨層連動如果沒有明確規則，很容易造成重複完成或狀態不一致。</p><h3>Reminder / Notification Module</h3><p>提醒不是附屬欄位，而是一個副作用系統。</p><p>它要處理的不只是「建立通知」，還包含：</p><ul><li>task 編輯後重排通知</li><li>task 完成後取消通知</li><li>task 刪除後取消通知</li><li>overdue reminder 的動態建立</li><li>daily summary reminder</li></ul><p>也因此，Notification Scheduler Layer 在這個系統裡是合理的，不是過度設計。</p><h3>Search / Filter / Sort Module</h3><p>搜尋頁最容易被當成 UI 功能，但在這個專案裡，它其實更像查詢引擎加上結果操作層。</p><p>因為搜尋結果不只是顯示資料，還要支援：</p><ul><li>直接完成</li><li>直接刪除</li><li>編輯</li><li>批次改分類</li><li>批次完成</li><li>批次移到垃圾桶</li></ul><p>這代表查詢條件、route state、排序策略與 mutation 後的重新整理，都要被一起設計。</p><h3>Export Module</h3><p>這一塊的核心價值，不是「匯出資料」，而是「把資料用一個未來還能持續讀懂的格式輸出去」。</p><p>一旦你把 export 視為 schema versioned payload，而不是單純檔案輸出，整個系統的長期性就會更清楚。</p><h3>實作順序也很重要：先穩資料與規則，再做體驗層</h3><p>我很喜歡 TASKS.md 的 milestone 安排，因為它反映出一個很成熟的工程順序：</p><ol><li>先建立 Expo Router、SQLite schema、migration、repository 與 use case 邊界</li><li>再做任務生命週期主線：create / edit / detail / complete / trash</li><li>再擴充分類、子任務、重複規則與通知</li><li>然後才接搜尋、匯出、onboarding、主題與產品完成度</li><li>最後進入穩定性、handoff、integration tests 與 UI/E2E tests</li></ol><p>這個順序背後的核心觀念其實很簡單：</p><p><strong>先把資料流和狀態轉換做穩，再做依賴這些邏輯的體驗功能。</strong></p><p>如果反過來，很容易在畫面和互動做得很完整之後，才發現底層規則還沒定義清楚，最後變成大量返工。</p><h3>這個專案裡我覺得最真實的 trade-off</h3><p>我覺得這個 Todo App 最值得寫成文章的地方，不是它用了什麼技術，而是它把一些常見 trade-off 放得很清楚。</p><h3>local-first 很乾淨，但規則要自己負責</h3><p>沒有 backend 的好處，是系統更純粹、反應更快、離線自然成立。</p><p>但這也代表：</p><ul><li>overdue refresh 不能偷懶</li><li>recurring generation 不能只做 happy path</li><li>notification reschedule 不能漏掉舊通知</li><li>trash cleanup 不能只是 UI 假象</li></ul><p>也就是說，你省下的是雲端複雜度，換來的是更完整的裝置端責任。</p><h3>看起來常見的功能，實際上邊界很多</h3><p>Recurring task、subtask auto-complete、trash 不可還原，這些都不是「多一個按鈕」的問題。</p><p>它們真正難的地方在於：</p><ul><li>狀態一致性</li><li>副作用順序</li><li>多資料表關聯</li><li>查詢結果與使用者預期的一致</li><li>測試如何覆蓋風險情境</li></ul><h3>文件導向開發比較慢，但擴張能力更好</h3><p>用 PRD、SRS、TASKS 這種方式推進，前期一定比直接開始切畫面慢。</p><p>但它的價值是，一旦功能從「簡單待辦」長成「有 recurring、notifications、search、export 的本機系統」，整個專案仍然有一條清楚的主線。</p><p>你知道：</p><ul><li>為什麼這個功能存在</li><li>它跟哪條需求對應</li><li>它應該放在哪一層</li><li>它目前是已完成、進行中，還是 roadmap</li></ul><p>這對長期維護來說，非常重要。</p><h3>到目前為止，這個系統走到哪裡了？</h3><p>從目前 repo 內的 milestone 與 review 文件來看，這個專案已經超過「只有規格沒有實作」的階段。</p><p>可以保守地這樣理解它的進度：</p><ul><li>milestone 1 到 7 的主要骨架已經建立</li><li>JSON export、onboarding、主題切換與基礎完成動畫已有進展</li><li>milestone 8 正在補穩定性、share handoff、測試與 polish</li></ul><p>但也有幾個地方仍明確處於未完成或持續補強中：</p><ul><li>integration tests</li><li>UI / E2E tests</li><li>recurring overdue generation 的完整驗證</li><li>export handoff 的完整體驗</li><li>onboarding 與 completion animation 的進一步 polish</li></ul><p>我刻意把這一段寫得很保守，因為我覺得一篇好的技術文章，不應該把 roadmap 包裝成已完成，而是要清楚區分：</p><ul><li>什麼是已經定義清楚的</li><li>什麼是正在實作的</li><li>什麼是下一步</li></ul><h3>我從這個專案學到的三件事</h3><ul><li>一個看似簡單的 Todo App，只要把 recurring、notifications、trash、search 和 export 做完整，本質上就已經是一個有狀態機、有模組邊界的系統設計題。</li><li>當 PRD 先把非目標講清楚時，技術設計反而更容易收斂，因為你知道哪些複雜度是這一版故意不做的。</li><li>文件導向開發真正有價值的地方，不是文件本身，而是它讓產品需求、技術設計與實作順序之間可以被持續追蹤。</li></ul><h3>結語</h3><p>如果只是把這個專案看成「做一個 Todo App」，它確實不是最特別的題目。</p><p>但如果把它看成一個練習：如何把需求、限制、使用者流程、狀態規則與技術選擇，整理成一個可以持續演進的本機系統，那它就很值得做。</p><p>對我來說，這個專案最重要的收穫不是某個單一畫面，而是這條方法論：</p><p>先把問題定義清楚，再把需求拆成模組、規則與資料結構，最後才開始實作。</p><h3>Resources</h3><ul><li>專案原始碼：<a href="https://github.com/I3OR2A/todo-list">https://github.com/I3OR2A/todo-list</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4088ed5325b4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[用發票 QR Code 自動更新庫存]]></title>
            <link>https://medium.com/@ioariroi/%E7%94%A8%E7%99%BC%E7%A5%A8-qr-code-%E8%87%AA%E5%8B%95%E6%9B%B4%E6%96%B0%E5%BA%AB%E5%AD%98-2d8561ce0b17?source=rss-f4d71b1c82ec------2</link>
            <guid isPermaLink="false">https://medium.com/p/2d8561ce0b17</guid>
            <category><![CDATA[qr-code]]></category>
            <category><![CDATA[mobile-development]]></category>
            <category><![CDATA[sqlite]]></category>
            <category><![CDATA[einvoice]]></category>
            <category><![CDATA[react-native]]></category>
            <dc:creator><![CDATA[Ioariroi]]></dc:creator>
            <pubDate>Wed, 04 Feb 2026 14:26:13 GMT</pubDate>
            <atom:updated>2026-02-05T14:56:48.872Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>做了一個 Expo + SQLite 的 MVP 模組來驗證可行性</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bXXOQlAgG5i52Lf6ac-TYg.png" /><figcaption>掃描電子發票更新家中清單</figcaption></figure><h3>為什麼要寫這篇文章</h3><p>我正在開發一個「家用庫存管理 App」。現階段最大的摩擦點是：</p><p>每次採買回來，使用者要 <strong>手動輸入品項與數量</strong> 才能更新庫存清單 — — 尤其遇到一次買很多東西的情境（全聯、家樂福、量販店），輸入體驗會直接勸退。</p><p>我想新增一個功能：</p><p><strong>讀取台灣紙本電子發票的左右 QR Code，解析當天購買的多個品項，並一鍵加入今天的庫存清單。</strong></p><p>但在把功能合併進主專案前，我先把它抽出來做成一個獨立的 <strong>MVP 模組</strong>，目標是快速回答三個問題：</p><ol><li>真的掃得到左右兩顆 QR 嗎？</li><li>解析出來的資料能穩定變成「商品清單」嗎？</li><li>資料能不能先落地保存，做成可展示的原型流程？</li></ol><p>這篇文章就是這個實驗模組的完整記錄。</p><h3>最小可用目標</h3><p>我把 MVP 範圍控制在「<strong>能掃、能解析、能回看</strong>」三件事：</p><ul><li>✅ 一鍵拍照掃描發票左右 QR code</li><li>✅ 自動判斷 LEFT/RIGHT（不需要使用者猜哪一顆是左、哪一顆是右）</li><li>✅ 解析商品清單（name / qty / unitPrice）</li><li>✅ SQLite 持久化保存（重開 App 不會消失）</li><li>✅ 清單頁 / 明細頁可回看</li></ul><h3>技術選型與架構概念</h3><h3>為什麼用 Expo + React Native Paper</h3><ul><li>我希望這個模組「可以快速跑在 iOS/Android」，並且未來能無痛合併回主 App</li><li>UI 用 <strong>React Native Paper</strong>，省下自己做元件的時間，並且天然支援主題</li></ul><h3>為什麼用 SQLite</h3><ul><li>這是個 MVP，但「能回看」非常重要：重開 App 還能看到掃描紀錄，才能更像產品</li><li>Expo 的 expo-sqlite 足夠支撐本機資料存取</li></ul><h3>為什麼不靠 onBarcodeScanned 直接拿兩顆 QR</h3><p>一開始我以為只要畫面同時有兩顆 QR，callback 就會一起回傳。</p><p>但實際上 onBarcodeScanned 一次通常只回傳「其中一顆」，結果會變成使用者要一直晃來晃去。</p><p>所以我改成更穩的策略：</p><blockquote><strong><em>一鍵拍照 → 對同一張照片做掃碼 → 一次拿到多顆 QR 結果</em></strong></blockquote><h3>實作流程（從相機到商品清單）</h3><h3>Step 1：拍照後掃描圖片（同圖多 QR）</h3><p>核心做法是 scanFromURLAsync(photo.uri, [&quot;qr&quot;])，它會回傳陣列結果。</p><pre>const photo = await takePictureAsync({ quality: 0.85 });<br>const results = await scanFromURLAsync(photo.uri, [&quot;qr&quot;]);</pre><p>這招的好處是：</p><p>只要左右 QR <strong>同框且清晰</strong>，成功率明顯比即時掃描高。</p><h3>Step 2：自動判斷 LEFT/RIGHT（避免使用者判斷）</h3><p>我用了兩層策略：</p><ol><li><strong>內容規則優先</strong>：右側 QR 常見會以 * 開頭（接續段）</li><li><strong>座標 fallback</strong>：如果兩顆都沒有 *，就用掃描結果的 bounds/cornerPoints 取 X 座標排序</li></ol><pre>function classifyPart(raw: string) {<br>  return raw.trim().startsWith(&quot;**&quot;) ? &quot;RIGHT&quot; : &quot;LEFT&quot;;<br>}</pre><h3>Step 3：Parser v0：把 payload 切成商品三元組</h3><p>我原本的 parser 直接 split(&quot;:&quot;) 後每三個當一組（name/qty/price）。</p><p>結果遇到一個坑：有些發票在商品清單前會出現 1:1:1 這類控制欄位，會把整個三元組切歪。</p><h3>真實案例（坑）</h3><p>左邊 QR 內容像這樣：</p><pre>...:**********:1:1:1:賽格威 Segway-Ninebot-0531:1:1000:</pre><p>如果直接三個一組，第一組會變成：(&quot;1&quot;, 1, 1)</p><p>真正的商品就會被切錯位，導致「解析不到商品清單」。</p><h3>解法：先找到「商品起點」</h3><p>我改成一個最小但有效的規則：</p><blockquote><em>找第一個「</em><strong><em>不是純數字</em></strong><em>」且後面兩個是數字的 token，才視為商品起點。</em></blockquote><pre>function findItemsStartIndex(parts: string[]) {<br>  for (let i = 0; i + 2 &lt; parts.length; i++) {<br>    const name = parts[i];<br>    const qty = parts[i + 1];<br>    const price = parts[i + 2];<br>    const nameOk = !!name &amp;&amp; !/^\\d+$/.test(name.trim());<br>    const qtyOk = /^-?\\d+(\\.\\d+)?$/.test(qty ?? &quot;&quot;);<br>    const priceOk = /^-?\\d+(\\.\\d+)?$/.test(price ?? &quot;&quot;);<br>    if (nameOk &amp;&amp; qtyOk &amp;&amp; priceOk) return i;<br>  }<br>  return -1;<br>}</pre><p>有了這個起點定位後，再從起點開始每 3 個切一組，就能正確拿到商品清單。</p><h3>Step 4：SQLite 持久化保存（發票主表 + 品項表）</h3><p>我用兩張表：</p><ul><li>invoices：主資訊 + raw left/right（方便 debug）</li><li>invoice_items：每個品項一列（name/qty/unit_price）</li></ul><pre>CREATE TABLE IF NOT EXISTS invoices (<br>  id TEXT PRIMARY KEY,<br>  total INTEGER,<br>  raw_left TEXT NOT NULL,<br>  raw_right TEXT,<br>  created_at INTEGER NOT NULL<br>);<br><br>CREATE TABLE IF NOT EXISTS invoice_items (<br>  id TEXT PRIMARY KEY,<br>  invoice_id TEXT NOT NULL,<br>  name TEXT NOT NULL,<br>  qty REAL NOT NULL,<br>  unit_price REAL NOT NULL,<br>  FOREIGN KEY(invoice_id) REFERENCES invoices(id)<br>);</pre><p>為了簡化 MVP，我採用 <strong>寫入前先刪除舊 items 再重寫</strong> 的方式（對同一張發票可重覆掃描覆蓋）。</p><h3>UI 與使用體驗</h3><p>我把流程做成三個畫面：</p><ol><li><strong>InvoicesList</strong>：列表（可回看歷史掃描）</li><li><strong>ScanInvoice</strong>：相機 + 一鍵拍照掃描</li><li><strong>InvoiceDetail</strong>：商品明細（DataTable）</li></ol><p>掃描成功後直接：</p><ul><li>parse</li><li>save to SQLite</li><li>navigation.replace(&quot;InvoiceDetail&quot;)</li></ul><p>使用者不需要再按「產生清單」或手動操作。</p><h3>驗證結果</h3><p>我用「真的拿實體紙本發票」做測試，驗證：</p><ul><li>拍照掃描一次是否能取得 2 顆 QR</li><li>LEFT/RIGHT 是否判斷正確</li><li>Parser 是否能成功解析出品項</li><li>重開 App 後是否仍能回看清單與明細</li></ul><blockquote><em>TODO: demo GIF</em></blockquote><blockquote><em>「拍照 → 自動跳轉明細 → DataTable 顯示品項」。</em></blockquote><h3>Lessons Learned</h3><h3>1) onBarcodeScanned 不是「同框就回兩顆」</h3><p>實務上你可能只會收到其中一顆結果。</p><p>拍照後掃描圖片的方式反而更穩、也更適合「一次要收齊兩顆」的需求。</p><h3>2) Parser 必須先找「商品起點」</h3><p>台灣電子發票 QR 的 payload 可能在品項前有控制欄位，不能直接從頭三個一組切。</p><h3>3) 把 raw left/right 存進 DB 很有價值</h3><p>當 parser 失敗時，你可以在明細頁直接顯示 raw，快速定位解析規則需要怎麼調整。</p><h3>結尾：為什麼我會用「模組先驗證」而不是直接合併主專案</h3><p>我把功能抽成模組先做 MVP，是因為：</p><ul><li>主專案的需求很多（庫存、提醒、分類、統計…）</li><li>這個「掃發票」屬於高不確定性功能（掃描成功率、格式差異、解析規則）</li><li>抽成模組可以更快迭代、更容易展示</li></ul><h3>Resources</h3><ul><li>專案原始碼：<a href="https://github.com/I3OR2A/einvoice-rn.git">https://github.com/I3OR2A/einvoice-rn.git</a></li><li>expo-camera：拍照 + 掃碼</li><li>expo-sqlite：本機持久化</li><li>React Native Paper：快速 UI 元件</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2d8561ce0b17" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[一次搞定版本釋出：用 GitHub Actions 自動打包 Chrome Extension 並附加到 Release（tag 驅動）]]></title>
            <link>https://medium.com/@ioariroi/%E4%B8%80%E6%AC%A1%E6%90%9E%E5%AE%9A%E7%89%88%E6%9C%AC%E9%87%8B%E5%87%BA-%E7%94%A8-github-actions-%E8%87%AA%E5%8B%95%E6%89%93%E5%8C%85-chrome-extension-%E4%B8%A6%E9%99%84%E5%8A%A0%E5%88%B0-release-tag-%E9%A9%85%E5%8B%95-af21bbe6fcd3?source=rss-f4d71b1c82ec------2</link>
            <guid isPermaLink="false">https://medium.com/p/af21bbe6fcd3</guid>
            <category><![CDATA[github-actions]]></category>
            <category><![CDATA[chrome-extension]]></category>
            <category><![CDATA[github]]></category>
            <category><![CDATA[shell-script]]></category>
            <dc:creator><![CDATA[Ioariroi]]></dc:creator>
            <pubDate>Sat, 31 Jan 2026 14:07:23 GMT</pubDate>
            <atom:updated>2026-01-31T14:07:23.828Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><em>目標讀者：正在做工具/插件/小專案、想把「打包 + 發佈」流程自動化的工程師<br>你會學到：如何用「推 tag」觸發 GitHub Actions，自動產出乾淨的 release zip，並上傳成 GitHub Release 附件（可直接套用到 Chrome Extension 專案）</em></blockquote><h3>前言：為什麼我需要「自動打包並附到 Release」</h3><p>當專案開始有人使用後，你會很快遇到這些問題：</p><ul><li>我到底打包的是哪個版本？手動壓縮很容易忘記同步更新</li><li>Release 上的附件檔名不一致、內容夾雜開發檔案（例如測試檔、草稿）</li><li>每次發版都要重複做「打包、上傳、填 Release Notes」，耗時又容易出錯</li></ul><p>解法很直接：把發版當成一個「可重現的流程」。我採用的做法是：</p><ol><li>使用 v1.0.0 這種 tag 當作「發版事件」</li><li>GitHub Actions 在 tag push 後自動打包</li><li>自動建立/更新 Release，並把 zip 當附件上傳</li></ol><h3>發版設計：tag 驅動的 Release Pipeline</h3><p>我建議把流程拆成兩層：</p><ul><li><strong>Build layer（可重現打包）</strong>：用一個 shell script 產出「乾淨的 dist」與「標準命名 zip」</li><li><strong>Release layer（交付與追溯）</strong>：用 GitHub Actions 監聽 tag，呼叫 build script，再上傳到 Release</li></ul><p>這樣做的好處是：</p><ul><li>你在本機也能跑同一套打包流程（Debug 很方便）</li><li>CI 只是把相同步驟自動化，不會變成「CI 裡才跑得動」</li></ul><h3>Step 1：建立可重現的打包腳本 build_release.sh</h3><p>核心原則只有一個：release zip 的根目錄必須直接包含 manifest.json</p><p>（Chrome Web Store 或未封裝載入都會依賴這個結構）</p><p>以下是一個精簡版概念（完整版本可用你專案中的 scripts/build_release.sh）：</p><ul><li>清空 dist/</li><li>複製必要檔案（manifest、background、content script、panel 等）</li><li>選擇性複製 assets/</li><li>在 dist/ 內壓成 zip → 丟到 release/</li></ul><p>你可以用這樣的命名規則避免混亂：</p><ul><li>shopee-shop-cover-helper-v1.0.0.zip</li></ul><h3>Step 2：建立 GitHub Actions Workflow（推 tag 自動發版）</h3><p>在專案新增檔案：.github/workflows/release.yml</p><pre>name: Release<br><br>on:<br>  push:<br>    tags:<br>      - &quot;v*.*.*&quot;   # 例如 v1.0.0<br><br>permissions:<br>  contents: write  # 允許建立 Release 與上傳附件<br><br>jobs:<br>  build-and-release:<br>    runs-on: ubuntu-latest<br><br>    steps:<br>      - name: Checkout<br>        uses: actions/checkout@v4<br><br>      - name: Prepare version<br>        id: ver<br>        run: |<br>          TAG=&quot;${GITHUB_REF_NAME}&quot;        # e.g. v1.0.0<br>          VERSION=&quot;${TAG#v}&quot;              # -&gt; 1.0.0<br>          echo &quot;tag=$TAG&quot; &gt;&gt; $GITHUB_OUTPUT<br>          echo &quot;version=$VERSION&quot; &gt;&gt; $GITHUB_OUTPUT<br><br>      - name: Make script executable<br>        run: chmod +x scripts/build_release.sh<br><br>      - name: Build release zip<br>        run: ./scripts/build_release.sh &quot;${{ steps.ver.outputs.version }}&quot;<br><br>      - name: Upload zip to GitHub Release<br>        uses: softprops/action-gh-release@v2<br>        with:<br>          tag_name: ${{ steps.ver.outputs.tag }}<br>          files: release/*.zip<br>          name: ${{ steps.ver.outputs.tag }}<br>          body: |<br>            ## CI / Release Automation<br><br>            This release adds a GitHub Actions workflow to automate packaging and publishing.<br><br>            ### What’s included<br>            - Tag-based release pipeline (triggers on `v*.*.*`)<br>            - Automatically builds a versioned extension ZIP via `scripts/build_release.sh`<br>            - Creates/updates the GitHub Release for the tag<br>            - Uploads the generated ZIP as a Release asset<br><br>            ### How to use<br>            1. Create a tag, e.g. `v1.0.0`<br>            2. Push the tag to GitHub<br>            3. The workflow will run and attach `release/*.zip` to the corresponding Release</pre><h3>Step 3：實際發版流程（你只需要做兩件事）</h3><ol><li>打 tag</li><li>push tag</li></ol><pre>git tag v1.0.0<br>git push origin v1.0.0</pre><p>接著你就可以在 GitHub 的 Releases 看到：</p><ul><li>v1.0.0 Release 已建立</li><li>附件包含 shopee-shop-cover-helper-v1.0.0.zip</li></ul><h3>常見問題與最佳實踐</h3><h3>1）同時 push 多個 tag，會不會把 zip 混在一起？</h3><p>不會。GitHub Actions 的 runner 每次執行都是乾淨環境。</p><p>每個 tag 觸發一次 workflow，每次只會產出該版本的 zip，並上傳到對應 tag 的 Release。</p><h3>2）如何避免把多餘檔案打進 zip？</h3><p>把「打包白名單」寫進 script：只複製擴充套件真正需要的檔案。</p><p>這比用 .gitignore 或「壓整包再排除」穩定很多。</p><h3>3）Release Notes 要自訂怎麼辦？</h3><p>把 generate_release_notes: true 改成自訂 body：</p><pre>with:<br>tag_name: ${{ steps.ver.outputs.tag }}<br>files: release/*.zip<br>name: ${{ steps.ver.outputs.tag }}<br>  body:|<br>    這裡貼你的 Release Notes（Markdown）</pre><h3>結論：把發版變成「可重現的工程流程」</h3><p>這套 tag 驅動的 CI 發版流程，解決的是「一致性」與「可追溯性」：</p><ul><li>任何人拿到 v1.0.0 的 zip 都能對應到同一份程式碼</li><li>發版不再靠手動步驟記憶，降低人為失誤</li><li>你只需要打 tag，剩下交給 CI</li></ul><h3>專案連結</h3><p>我把完整實作放在 GitHub（包含 build script 與 release workflow）。</p><p>請到這裡查看專案與最新 Release：</p><pre>&lt;https://github.com/I3OR2A/shopee-shop-cover-ext&gt;</pre><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=af21bbe6fcd3" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[從 0 到 1 發布你的程式：SemVer 版本號 + Tag + GitHub Release 實戰]]></title>
            <link>https://medium.com/@ioariroi/%E5%BE%9E-0-%E5%88%B0-1-%E7%99%BC%E5%B8%83%E4%BD%A0%E7%9A%84%E7%A8%8B%E5%BC%8F-semver-%E7%89%88%E6%9C%AC%E8%99%9F-tag-github-release-%E5%AF%A6%E6%88%B0-17b9488cf213?source=rss-f4d71b1c82ec------2</link>
            <guid isPermaLink="false">https://medium.com/p/17b9488cf213</guid>
            <category><![CDATA[ci-cd-pipeline]]></category>
            <category><![CDATA[semver]]></category>
            <category><![CDATA[git]]></category>
            <dc:creator><![CDATA[Ioariroi]]></dc:creator>
            <pubDate>Thu, 29 Jan 2026 15:31:53 GMT</pubDate>
            <atom:updated>2026-02-04T14:28:43.323Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>你已經把程式寫好了，但「<strong>怎麼發版</strong>」常常是最後一道坎：版本號怎麼訂？Tag 要怎麼壓？GitHub Release 要放什麼？</blockquote><p>這篇文章會帶你用 <strong>SemVer（語意化版本）</strong> 制定版本號，並用一套<strong>可複製的流程</strong>把程式推到 GitHub、壓 Tag、建立 Release，最後產出一份像樣的 Release Notes。看完你可以把任何一個完成的專案，做出可追蹤、可回溯、可交付的版本發布。</p><h3>前言：你寫完了，但你還沒「交付」</h3><p>很多人以為把程式 push 到 GitHub 就算完成，但在團隊或正式交付情境中，你會遇到這些問題：</p><ul><li>同事問：「你現在部署的是哪個版本？」你答不出來</li><li>你修了一個 bug，想回溯「當時的版本內容」卻找不到對應 commit</li><li>想提供下載（或產出建置檔）給使用者，但沒有「正式版本」的概念</li></ul><p>解法就是：<strong>版本號（Version）+ Tag（不可變標記）+ Release（可見的發佈物）</strong>。</p><h3>一、先講清楚三個名詞：Version / Tag / Release</h3><h3>1) Version（版本號）</h3><p>版本號是你對外宣告的「這一版是什麼」。推薦用 <strong>SemVer：MAJOR.MINOR.PATCH</strong>。</p><ul><li><strong>MAJOR</strong>：做了不相容的改動（Breaking Change）</li><li><strong>MINOR</strong>：新增功能，但相容舊版本</li><li><strong>PATCH</strong>：修 bug，不影響相容性</li></ul><p>例如：</p><ul><li>1.4.0：新增功能</li><li>1.4.1：修 bug</li><li>2.0.0：API 改了、舊的用法不相容</li></ul><h3>2) Tag（Git 標籤）</h3><p>Tag 是貼在某個 commit 上的「永久標記」。</p><p><strong>一旦壓了 Tag，就不要改它</strong>，因為它代表那個版本的<strong>精確程式狀態</strong>。</p><p>常見命名：v1.4.1（前面加 v 很普遍）</p><h3>3) GitHub Release</h3><p>Release 是 GitHub 上「對人類友善」的發佈頁面：</p><ul><li>顯示版本、日期、說明（Release Notes）</li><li>可附上檔案（build artifact、安裝檔、zip…）</li><li>可讓使用者快速找到最新版與歷史版本</li></ul><blockquote><em>總結一句：Tag 是給 Git 精準定位；Release 是給人看的發版入口。</em></blockquote><h3>二、制定版本號規則（SemVer 實用版）</h3><p>你可以用下面這張「判斷表」快速決定要升哪一段：</p><ul><li><strong>PATCH +1</strong>：修 bug、修字、log 調整、效能優化（不改行為）</li><li><strong>MINOR +1</strong>：新增功能、新增 API endpoint、新增參數但保留舊行為</li><li><strong>MAJOR +1</strong>：移除功能、改 API 行為、改資料格式導致舊版不能用</li></ul><h3>建議搭配「commit 分類」讓 Release Notes 好寫</h3><p>你可以不用一開始就導入複雜工具，先從這樣分類就夠用：</p><ul><li>feat: 新功能（通常 MINOR）</li><li>fix: 修 bug（通常 PATCH）</li><li>break: 不相容改動（通常 MAJOR）</li><li>chore: 雜項（不一定發版）</li></ul><h3>三、實戰流程：把你的程式推上 GitHub、壓 Tag、做 Release</h3><p>下面是最常用、最穩的流程（照做即可）。</p><h3>Step 0：確認你的 repo 是乾淨的</h3><pre>git status</pre><p>確定沒有漏加檔案、或有沒 commit 的變更。</p><h3>Step 1：推到 GitHub（如果你已經有就略過）</h3><pre>git remote -v git push -u origin main</pre><h3>Step 2：決定版本號（例：1.0.0）</h3><p>假設你這是第一個可交付版本，通常從 1.0.0 或 0.1.0 開始：</p><ul><li><strong>1.0.0</strong>：代表功能完整、願意對外承諾穩定性</li><li><strong>0.x</strong>：代表仍在快速變動期（API 可能常改）</li></ul><h3>Step 3：建立 Tag（建議用 annotated tag）</h3><pre>git tag -a v1.0.0 -m &quot;Release v1.0.0&quot;</pre><h3>Step 4：把 Tag 推到遠端</h3><pre>git push origin v1.0.0</pre><p>（如果你一次要推全部 tag）</p><pre>git push --tags</pre><h3>Step 5：在 GitHub 建立 Release</h3><p>到 GitHub repo → <strong>Releases</strong> → <strong>Draft a new release</strong></p><ul><li>Choose a tag：選 v1.0.0</li><li>Release title：v1.0.0</li><li>Description：貼上 Release Notes（下一節教你寫）</li><li>如果你有 build 檔（zip、exe、jar、docker compose）就拖上去</li></ul><p>按 <strong>Publish release</strong> 完成。</p><h3>四、Release Notes 怎麼寫才像「正式發版」</h3><p>你可以用這個模板（直接複製改內容）：</p><pre>## v1.0.0 - 2026-01-26<br><br>### Added<br>- 新增 XXX 功能（簡述使用情境）<br>- 支援 XXX 設定（例如 .env / config）<br>### Fixed<br>- 修正 XXX bug（造成什麼影響、如何修）<br>### Changed<br>- 調整 XXX 行為（是否相容，若不相容請寫 Migration）<br>### Known Issues<br>- 目前已知限制：XXX</pre><p>如果你是給偏維運讀者，建議加一段：</p><h3>Deployment Notes（部署注意事項）</h3><ul><li>需要的環境變數</li><li>DB migration 是否需要執行</li><li>重要設定預設值</li></ul><h3>五、常見踩坑（你很可能會遇到）</h3><h3>1) 壓錯 Tag 怎麼辦？</h3><p><strong>如果 Tag 還沒推到遠端：</strong></p><pre>git tag -d v1.0.0</pre><p><strong>如果已經推到遠端（不推薦這樣做，但必要時）：</strong></p><pre>git tag -d v1.0.0 git push origin :refs/tags/v1.0.0</pre><p>然後再重新建立正確 tag 再 push。</p><blockquote><em>團隊習慣上：公開出去的 tag 盡量不要改，寧願補一個 v1.0.1。</em></blockquote><h3>2) Tag 要貼在哪個 commit？</h3><p>通常貼在：</p><ul><li>main 上「通過測試 / 可部署」的那個 commit</li><li>或你準備交付的 commit（release commit）</li></ul><h3>3) 要不要用 GitHub 的 “Generate release notes”？</h3><p>可以用，但第一次我建議你先手寫一版（你會更理解版本的價值）。之後再讓 GitHub 自動產生，自己再整理。</p><h3>結語：把「寫完」變成「可交付」</h3><p>當你開始用 SemVer + Tag + Release，你的專案會瞬間變得「可被信任」：</p><ul><li>可追蹤：任何環境都能對應到明確版本</li><li>可回溯：出問題能快速定位到版本與差異</li><li>可交付：對外有正式入口與變更紀錄</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=17b9488cf213" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[在兩台 Windows 電腦間開發 React + Python：我如何用「專案描述環境」解決環境不同步的痛點]]></title>
            <link>https://medium.com/@ioariroi/%E5%9C%A8%E5%85%A9%E5%8F%B0-windows-%E9%9B%BB%E8%85%A6%E9%96%93%E9%96%8B%E7%99%BC-react-python-%E6%88%91%E5%A6%82%E4%BD%95%E7%94%A8-%E5%B0%88%E6%A1%88%E6%8F%8F%E8%BF%B0%E7%92%B0%E5%A2%83-%E8%A7%A3%E6%B1%BA%E7%92%B0%E5%A2%83%E4%B8%8D%E5%90%8C%E6%AD%A5%E7%9A%84%E7%97%9B%E9%BB%9E-8d6a724e9856?source=rss-f4d71b1c82ec------2</link>
            <guid isPermaLink="false">https://medium.com/p/8d6a724e9856</guid>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[react]]></category>
            <category><![CDATA[github]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[powershell]]></category>
            <dc:creator><![CDATA[Ioariroi]]></dc:creator>
            <pubDate>Wed, 28 Jan 2026 12:36:07 GMT</pubDate>
            <atom:updated>2026-02-04T14:29:10.515Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>不用 Docker，也能讓你換電腦就能立刻開始寫程式的實務做法</blockquote><h3>前言：每次換電腦，為什麼我都在裝環境？</h3><p>如果你跟我一樣：</p><ul><li>有 <strong>兩台以上的個人桌機或筆電</strong></li><li>在家與公司、或不同地點來回開發</li><li>使用 <strong>React + Python（FastAPI）</strong></li><li>原始碼都已經放在 GitHub，但……</li></ul><p>那你大概也遇過這種情況：</p><blockquote><em>clone 專案後，</em></blockquote><blockquote><em>發現少裝一個 npm 套件、Node 版本不對、Python 套件缺漏，</em></blockquote><blockquote><em>然後花 30 分鐘以上「修環境」，才終於可以開始寫程式。</em></blockquote><p>這不是能力問題，而是<strong>環境沒有被好好管理</strong>。</p><p>這篇文章，我會分享我實際採用、目前覺得<strong>最平衡的一個解法</strong>：</p><p>👉 <strong>不用 Docker，只靠專案本身就能描述開發環境</strong>，讓你在不同 Windows 電腦之間快速切換。</p><h3>問題本質：不是 Git 的問題，是「環境沒被版本化」</h3><p>我們先釐清一件事：</p><blockquote><em>GitHub 解決的是「程式碼同步」，</em></blockquote><blockquote><em>但</em><strong><em>不會幫你同步開發環境</em></strong><em>。</em></blockquote><p>真正造成痛苦的，通常有三種：</p><ol><li><strong>Node / Python 版本不同</strong></li><li><strong>套件是「手動裝的」，但沒有完整記錄</strong></li><li>新電腦沒有一個「標準初始化流程」</li></ol><p>解法的關鍵不是再記更多步驟，而是：</p><blockquote><em>讓專案自己告訴你：我需要什麼環境</em></blockquote><h3>核心思路：讓「專案」成為環境的唯一真相（Single Source of Truth）</h3><p>我採用的原則很簡單：</p><ul><li>❌ 不靠記憶</li><li>❌ 不靠手動檢查</li><li>❌ 不靠「這台之前可以跑」</li></ul><p>而是：</p><ul><li>✅ Node 版本寫在專案裡</li><li>✅ Python 套件由檔案定義</li><li>✅ 換電腦只做「固定三步」</li></ul><p>接下來我會用 <strong>React + Python（FastAPI）+ Windows</strong> 的實際情境說明。</p><h3>前端（React）：固定 Node 版本 + lock 檔</h3><h3>1️⃣ 固定 Node 版本（避免隱性地雷）</h3><p>我會在專案根目錄放一個 .nvmrc：</p><pre>18.20.4</pre><p>兩台 Windows 都安裝 <strong>nvm-windows</strong>，進專案後只要：</p><pre>nvm use 18.20.4</pre><p>這一步的價值非常高，因為：</p><ul><li>避免「這台可以跑，那台不行」</li><li>避免 npm / vite / react-scripts 的版本差異問題</li></ul><h3>2️⃣ 只信任 package-lock.json</h3><p>幾個原則我會嚴格遵守：</p><ul><li>package.json、package-lock.json <strong>一定 commit</strong></li><li><strong>不用 </strong><strong>npm install 某某套件 來修環境</strong></li><li>換電腦只做一件事：</li></ul><pre>npm install</pre><p>如果 npm install 不能跑，</p><p>那代表「環境描述有問題」，而不是「電腦有問題」。</p><h3>後端（Python）：虛擬環境 + requirements.txt</h3><h3>1️⃣ 每個專案一個虛擬環境</h3><p>在專案根目錄：</p><pre>python -m venv .venv</pre><p>.venv 加入 .gitignore，<strong>永遠不 commit</strong>。</p><h3>2️⃣ 套件完整記錄在 requirements.txt</h3><p>開發完成或套件有變動時：</p><pre>pip freeze &gt; requirements.txt</pre><p>這個檔案就是：</p><blockquote><em>Python 環境的合約（contract）</em></blockquote><h3>3️⃣ 換電腦時的完整流程</h3><pre>python -m venv .venv<br>.\\.venv\\Scripts\\activate<br>pip install -r requirements.txt</pre><p>沒有猜測、沒有補裝，全靠檔案。</p><h3>加分技巧：用一支 setup.ps1 解決 90% 切換成本</h3><p>為了讓整件事「真的可複製」，</p><p>我會在專案根目錄放一支 <strong>初始化腳本</strong>。</p><h3>setup.ps1 範例（Windows）</h3><pre>Write-Host &quot;== 使用指定 Node 版本 ==&quot;<br>nvm use 18.20.4<br><br>Write-Host &quot;== 安裝前端套件 ==&quot;<br>npm install<br>Write-Host &quot;== 建立 Python 虛擬環境 ==&quot;<br>if (!(Test-Path &quot;.\\.venv&quot;)) {<br>    python -m venv .venv<br>}<br>Write-Host &quot;== 安裝 Python 套件 ==&quot;<br>.\\.venv\\Scripts\\activate<br>pip install -r requirements.txt<br>deactivate<br>Write-Host &quot;環境初始化完成，可以開始開發了 🚀&quot;</pre><p>之後換任何一台電腦，流程只剩：</p><pre>git clone 專案<br>cd 專案<br>pwsh .\\setup.ps1</pre><h3>為什麼我暫時不選 Docker？</h3><p>我知道 Docker / Dev Container 是更完整的解法，</p><p>但在我目前的使用情境下：</p><ul><li>個人專案</li><li>本機效能與除錯體驗優先</li><li>希望「clone 後 5 分鐘內能開工」</li></ul><p>這套做法：</p><ul><li>✔ 成本低</li><li>✔ 學習曲線平緩</li><li>✔ 已經解決 80% 的實際痛點</li></ul><p>Docker 會是<strong>下一步</strong>，但不是一開始就必須。</p><h3>結論：環境穩定，是持續開發的前提</h3><p>我最大的體會是：</p><blockquote><em>當環境不再是阻力，你才會真的想打開專案。</em></blockquote><p>如果你也常在不同 Windows 電腦之間切換開發，我會建議你：</p><ol><li>從今天開始，讓專案「描述環境」</li><li>不再靠手動修補</li><li>把 setup 流程寫成腳本</li></ol><p>這不是為了完美，而是為了<strong>持續寫程式</strong>。</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8d6a724e9856" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>