bot-rates/SUMMARY.md

開發過程摘要

記錄這個專案的演進脈絡、遇到的問題、以及為什麼做出這些選擇。

需求演進

階段	需求	產出
1	抓台銀 USD / JPY / EUR 即期賣出	Python CLI (bot_rates.py)
2	要給別人用、Windows、GUI、雙擊即跑、不要裝東西	Python tkinter + PyInstaller 方案
3	太麻煩，改用 Rust，使用者無 Windows 機器	Rust + eframe + 交叉編譯
4	也給我一份 macOS 能跑的	BotRates.app bundle
5	壓縮 exe 方便傳送	bot_rates.zip（5.4 MB → 2.7 MB）
6	加上金額輸入 / 即時換算	三欄布局：幣別 / 輸入 / TWD
7	換算結果要能直接複製	「複製」按鈕 + 可選取文字

階段 1：Python CLI

直接用 urllib 抓台銀 CSV，起初用 csv.DictReader，但踩到一個坑——CSV 有重複欄名（買入、賣出區段都用 匯率 / 現金 / 即期），DictReader 只會保留最後一個同名欄位，所以找不到「本行即期賣出」。

解法：改用位置索引，即期賣出 在 col 13。

階段 2：Python GUI（最終未採用）

計畫：tkinter + ttk 美化 + PyInstaller --onefile --windowed 打包成 exe。寫了 bot_rates_gui.py 和 build.bat。

問題：使用者手上沒有 Windows 機器，PyInstaller 必須在目標 OS 上執行，無法從 macOS 直接產出 Windows exe。只能給使用者 build.bat 要他在 Windows 上自己打包——違背「不要裝東西」的初衷。

階段 3：改用 Rust

Rust 可以從 macOS 乾淨地交叉編譯到 Windows，單一靜態執行檔，零 runtime 依賴，剛好解決 Python 方案的痛點。

技術選型

選擇	理由
eframe / egui	Immediate mode GUI，使用 OpenGL（Windows 內建），不需要 GTK / Qt 這類系統依賴。交叉編譯幾乎沒坑。
ureq + rustls	reqwest 預設用 native-tls 會綁 OpenSSL 或 Windows SChannel，交叉編譯會有系統 library 問題。ureq 搭 rustls 是純 Rust，無系統依賴。
x86_64-pc-windows-gnu	用 mingw-w64 當 linker，比 -msvc 少了需要 Windows SDK 的麻煩。brew install mingw-w64 就好。

踩過的坑

LLVM 在 release 編譯時 SIGSEGV

error: rustc interrupted by SIGSEGV, printing backtrace
llvm::DeadArgumentEliminationPass::run

第一次 release 編譯時，Cargo.toml 用了 opt-level = "z" + lto = true，LLVM 的 DeadArgumentElimination pass 在處理 eframe 依賴時堆疊用光。

解法：

1. 把 opt-level 從 "z" 改成 3、lto 從 true 改成 "thin"（降低 pass 壓力）
2. 加上 RUST_MIN_STACK=16777216（把執行緒堆疊從預設 2MB 拉到 16MB）

兩個同時做下去就過了。

CJK 字型

egui 預設字型不含中文字，幣別名稱會顯示成「豆腐」。

解法：不 bundle 字型（會讓 exe 大 5-15MB），改在執行期讀取作業系統字型。

• Windows：C:\Windows\Fonts\msjh.ttc（微軟正黑體）
• macOS：/System/Library/Fonts/PingFang.ttc

fallback 鏈有多個候選（msjhl / msyh / simhei），找到第一個能讀的就用。

階段 4：macOS .app bundle

cargo build --release 只產出裸執行檔，從 Finder 雙擊會跳 terminal 然後才開 GUI，體驗差。

解法：手動組 .app bundle——其實就是特定目錄結構加一個 Info.plist：

BotRates.app/
├── Contents/
│   ├── Info.plist           # 告訴 Finder 這是 app
│   └── MacOS/BotRates       # 實際執行檔

寫 plist 時標示 CFBundlePackageType = APPL 和 CFBundleExecutable = BotRates 即可。另外跑 xattr -cr 清掉 quarantine 屬性避免 Gatekeeper 擋下。

階段 5：壓縮

bot_rates.exe 5.4 MB，zip -9 後 2.7 MB（壓縮率 50%）。PE 檔因為有大量重複的 LLVM / rustc 樣板程式碼壓縮效果很好。

階段 6：金額換算

重新設計每一列為三欄 horizontal layout：

[幣別+匯率 寬110]  [輸入 寬120]  [ → ]  [TWD 靠右]

狀態放在 App.amounts: HashMap<String, String>（幣別 → 輸入字串）。為什麼存字串而不是 f64？因為使用者輸入過程中可能有中間態（例如 "100."、空字串、"1,000"），存字串才能保留原樣。

輸入解析用 parse_amount，忽略逗號和空白再 parse。

TWD 顯示用 format_twd，手刻千分位 separator（沒引入 num-format crate 以減少 binary size）。

階段 7：複製功能

兩種複製方式並存：

1. 按鈕複製（主要 UX）：按「複製」→ ui.output_mut(|o| o.copied_text = raw)，複製純數字 3162.00（不含 NT$、不含逗號）。原因：這樣貼到 Excel 會被識別成數字而不是文字。
2. 選取複製：egui::Label::new(...).selectable(true)，使用者可以用滑鼠拉選 TWD 文字後 Cmd/Ctrl+C。

按下按鈕後短暫顯示「已複製」（1.2 秒），用 Option<(String, Instant)> 追蹤狀態 + ctx.request_repaint_after 觸發回復重繪。

最終成果

項目	數值
Windows exe 大小	5.4 MB（zip 後 2.7 MB）
macOS 執行檔大小	5.2 MB
執行期依賴	無（兩平台皆零依賴）
首次冷啟動	< 1 秒
抓匯率耗時	網路 + 解析 < 500ms
總原始碼行數	~310 行 Rust

如果要擴充

• 加更多幣別：改 TARGETS 即可，其他地方都自動處理。
• 換成即期買入 / 現金匯率：改 fetch_rates 裡的 col index（3 買入 / 13 賣出 / 2 現金買入 / 12 現金賣出）。
• 雙向換算（TWD → 外幣）：在每列加第二個輸入框，狀態多存一組字串；注意避免無限循環更新。
• 歷史紀錄 / 圖表：台銀有 flcsv/1/month 等端點可以抓歷史，但就不是「即期」而是均價了。