feat(dispatch): 預約行程＋常用地點——修掉停機後會把積壓的過期預約全部派車

[thothawei]

W. 兩張新表（migration 000025／000026）＋9 支端點＋一支到點轉單的背景排程器。
App 端對應 fleet-app #95。

為什麼預約是獨立一張表，不是 rides 加一個狀態

rides 的查詢散布在派單池（status='requested'）、乘客 active、歷史、報表、admin 訂單列表。
多塞一個「還不該被派單」的狀態進去，得逐一稽核每支查詢有沒有排除它——
漏一支就是「司機看到一張三天後才要出發的單」。獨立表對既有路徑是純新增、零風險。

到點轉單

每 30 秒掃一次，把約定時間前 15 分鐘內的 pending 轉成真訂單。
轉單走的是與手動叫車完全同一支 RideService.CreateByCustomer——派單、審計、車種驗證、
「同時只能有一張進行中訂單」全部自動沿用。另寫一份的話兩條路徑遲早長歪，
而且是預約那條先歪（沒人在旁邊看著）。

機制	防的是什麼
認領帶 attempt_count 樂觀鎖	多副本同時掃到同一筆 → 建出兩張要付錢的訂單
暫時性失敗維持 pending（上限 10 次）	乘客當下還在別的行程上，那是「等下一輪」不是「永久失敗」
永久性失敗立刻判死	座標／車種無效重試幾次都一樣，佔著額度只會讓乘客到約定時間才發現沒車
過期 30 分鐘作廢	停機後重啟會把積壓的過期預約全部派車（見下）

修掉的 bug：停機後會把積壓的過期預約全部派車

FindDue 原本只有上界沒有下界。部署／當機／DB 不可用停了一段時間，重啟時
昨天早上的預約會今天下午開一台車到乘客家樓下，而且他還得付那趟錢。
修法是超過約定時間 30 分鐘就標 failed 並寫原因——標 failed 而不是留在 pending，
是因為留著它會永遠掛在乘客的「即將到來」，而那台車永遠不會來。
先寫 TestDispatcherSkipsLongExpiredSchedules 取證看到它真的被轉單，才動手修。

常用地點

home／work 每人各限一筆（部分唯一索引），服務層是 upsert 語意——
「設定住家」該把住家換成新地址，不是回一句「你已經有住家了」。
已達地點數上限時，覆蓋住家仍然成功（覆蓋不增加筆數，擋掉會變成連住家都不能改的死結）。

取消已轉單的回 409＋現況

那張真訂單已經在派單池裡，司機可能正在開過來——App 要據此把畫面切成「已為你派車」
並引導去取消訂單，而不是「取消失敗，請稍後再試」（同一個病在 V 那章的 admin 端抓過一次）。

驗收

• go build／go vet 乾淨。
• internal/service 完整套件 172 支全過、0 失敗（ok ... 2911.952s，真 PostGIS 容器，
  本機跑了 48 分鐘），其中 17 支是這批新增的；internal/handler 完整套件也綠（136s）。
  ⚠️ CI 那支 build-and-unit-test 只花 1 分鐘，是因為 CI 環境跳過 testcontainers——
  它綠不代表整合測試綠，所以上面那份本機數字才是這批的證據。
• 另加 scheduled_ride_route_shape_test.go——新路由與既有 /customer/rides/:id 同層混用
  靜態段與參數段，gin 的路由衝突是註冊當下 panic：服務起不來但單元測試照樣全綠。
• 反向驗證三次，其中兩次推翻了自己的假設：拔掉 FindDue 的時間條件會紅；
  拔掉樂觀鎖 TestDispatcherIsIdempotent 仍然綠（它守的是循序重跑，沒走到認領那行）；
  補的併發測試第一版也是假的（兩個 goroutine 沒真重疊，拔掉樂觀鎖連跑三次都綠），
  改成餵兩份 attempt_count=0 的相同快照直接進 dispatchOne 才造得出真重疊。
• 真環境實跑：塞一筆 5 分鐘後到點的預約，前兩輪被「已有進行中的訂單」擋下並維持 pending，
  結掉擋路訂單後第三輪轉單成功（ride_id=39，起訖點與預約一致、已進派單池）。
  那張訂單也確認顯示在乘客 App 的「車已在路上」區（跨端閉環）。
• scripts/seed_demo_data.sh 兩條分支（帶／不帶 PSQL_DSN）都實跑過。

🤖 Generated with Claude Code