加班有據開發筆記（一）：為什麼我先寫規格，而不是先寫程式

我開始做一個新產品：「加班有據」，一個給台灣排班制老闆與勞工用的加班費計算工具。這是第一篇開發筆記，記錄它為什麼存在，以及我為什麼把最多時間花在一個完全看不到畫面的地方。

1. 問題從一個很樸素的觀察開始

勞基法第 24 條（加班費）是全台勞檢違規的第一名。不是因為老闆都很壞，很多時候是真的算不對：排班制的門市、餐飲、早餐店，例假跟休息日不是固定的週六日，還有變形工時、國定假日、補班日，每個月的組合都不一樣。

而勞動部的官方試算一次只能算一週，要週一到週日逐日手填，不能跨週累計、不能整月彙總，也不支援變形工時。市面上沒有一個工具是「整月 × 排班 × 變形工時 × 工資認定」一次算清的。這個缺口夠具體，我決定做。

做這種工具，最可怕的不是沒人用，是有人用了、算錯了、拿去跟老闆吵，結果輸了。所以我替它定了一條鐵則：任何金額都不能在沒有法源依據的狀態下出現。

每一筆加班費旁邊都掛一個「法源籤」，點開就是條文與計算式；遇到法律沒講清楚的灰色地帶（例如某項獎金算不算工資），不替使用者選邊，直接輸出保守值與完整值兩個數字。這也成了產品名的由來——加班「有據」。

我先寫了一份規格文件：費率表、工資認定的雙軌規則、每一天是平日／休息日／國定假日／例假的判定邏輯、補休換算、違法檢核，每一條都標上法源層級——法條、函釋、實務、灰色。然後依這份規格寫了 16 個 golden tests：一組已知輸入對應一組已知答案。

引擎本身是純函數，不碰任何執行環境，同一顆可以跑在瀏覽器、Node 和 Cloudflare Workers 上。寫完之後，我做了一件最土的事：打開勞動部的試算系統，手動把同樣的案例填一遍，四個案例逐一對帳，零差異。那一刻我才覺得這個產品可以往下做。

基本工資每年調、國定假日逐年不同、2025 年 5 月 28 日之後假日制度還改了一次。算 2024 年的帳就要用 2024 年的規則，這件事很容易被忽略，因為「今年的數字」寫死最快。

所以行事曆跟基本工資全部建成逐年的資料表，含補班日、彈性放假。這是產品上線以後每年都要維護的東西，我一開始就把它當成常態而不是例外。

說實話，前幾天心裡有點急：一週過去，沒有任何能給人看的畫面。但我很清楚，這個產品的價值不在畫面，在於使用者把它印出來、放到談判桌上的時候，每一個數字都站得住。

介面可以晚一點好看，數字不能晚一點正確。下一篇會寫使用者端的東西：打卡資料怎麼進來，以及我為什麼不讓 AI 幫忙「判斷」。