function-optimization-followup.md

第二次全專案函式層級檢查（2026-10-03）

本輪延續前次函式檢查，納入新增的 GitHub 更新流程，檢查自有程式碼的重複工作、暫時配置與資源生命週期。介面、操作、功能、認證、排序及錯誤處理維持原有行為。

範圍

以 Go parser 與 TypeScript AST 盤點正式程式碼，按模組檢查函式的呼叫方式與資源成本。調整後共有：

• Go：28 個含函式的檔案，356 個具名函式／方法、60 個匿名函式，包含平台分支。
• 前端 src：26 個含函式的檔案，810 個具有實作的函式／回呼。
• 獨立安裝視窗 JavaScript：6 個函式／回呼。
• JavaScript／TypeScript 建置工具：35 個函式／回呼；版本控制內的 shell 腳本另有 5 個具名輔助函式。

這是盤點數量，不是修改或逐一量測的數量。型別宣告、自動產生的 Wails 綁定、第三方套件、測試與基準不列入正式函式統計。入口、組態與清理流程也納入檢查。

模組	檢查結果與處置
main.go、操作登錄、一般檔案與平台輔助函式	保留啟停、取消、FD 與來源識別的生命週期
app.go、文字解碼、檔名排序、有界讀取	掃描先以檔名判斷副檔名；只為支援的內容或目錄組合完整路徑。保留文字、排序及讀取限制
download.go	已在記憶體內的 HLS 清單直接逐行解析，省去 Scanner 工作區與行字串複製
update.go、internal/updater	增加精簡進度快照；串流下載、驗證、取消、獨立安裝、啟動收據及失敗回復流程維持既有行為
media.go、圖片／PDF HTTP	保留來源失效判定、串流、Range、取消及有界診斷輸出
檔案操作、ZIP／TAR、縮圖解碼及磁碟快取	保留容量、並行預算、使用中淘汰、CRC 與檔案識別檢查
useDownloads、downloads、useAppUpdates、appUpdates	相同輪詢結果沿用既有 React state 身分；輪詢只在標籤改變時取得發行說明
structuredData、結構化文件檢視	排序前保存數值鍵，排序索引而非每次解析欄位；已排序數值欄位走快速路徑
App、圖庫樹／檢視、工作區、篩選、掃描佇列	保留分支共用、弱鍵快取、分塊 FIFO、選取順序與失效判定
播放器、字幕、圖片傳輸、縮圖、虛擬網格與版面工具	保留既有工作區重用、預取限制、離屏取消、事件清理與可視列掛載
建置、版本資料、相依套件與檢查腳本	保留版本格式、macOS 12 arm64 目標、可重跑檢查及既有依賴

函式調整與行為約束

掃描與 HLS

ScanDirectory 不再為不支援的檔案先組合完整路徑。目錄、特殊檔名、大小寫副檔名、檔案連結與目錄連結的處理順序不變；支援內容的 stat、取消與穩定排序保持原樣。

parseHLSPlaylist 以 strings.SplitSeq 借用原內容中的每一行，不配置分行陣列或 Scanner 緩衝。保留原有 32 MiB 單行限制、CRLF／空行／最後一行處理、位元組範圍、初始化區段、變體順序及加密串流拒絕行為。網路中繼資料總量與下載分段限制仍由既有流程檢查。產生的 URL 經原有解析器組合為獨立結果。

原版函式保存在測試用 playlist_reference_test.go、scan_reference_test.go，供相同輸入的輸出、錯誤及基準對照。

更新與下載輪詢

GetUpdateProgress 只回傳階段、目前版本、發行標籤、位元組數與錯誤。完整 GetUpdateState 仍保留全部發行資訊；前端發現不同標籤時才取得詳細資料，同一次更新重用既有發行說明。手動重新檢查仍能更新相同標籤的說明文字。

reconcileDownloads 與 reconcileAppUpdateState 比較所有目前定義的狀態欄位。資料沒有變化時沿用既有 state，避免由相同輪詢結果引發主畫面重複渲染；進度、順序、刪除、錯誤及發行資訊改變時仍發布新狀態。維持原有輪詢間隔、單一請求、取消、過期回應與卸載保護。

這些函式不建立持久快取，僅保留畫面目前使用的快照。Wails 綁定與前端型別已一併更新。

表格排序

selectDelimitedRows 先檢查完全由有限數值組成、且已符合指定方向的欄位；符合時直接取出可見列。其他情況以 Float64Array 暫存數值鍵，再排序整數索引。混合內容仍使用原本「雙方都是非空有限數值才做數值比較，否則使用語系自然排序」的規則。

保留原有穩定同值順序、Unicode、空白／缺少欄位、科學記號、正負零、無限大文字、篩選與 1,000 列預覽限制，不修改輸入陣列。排序需處理全部匹配資料；無排序的查詢仍在第一筆被省略的匹配列停止。

數值鍵工作區為每列 8 bytes，4,999 列為 39,992 bytes，僅存在於本次函式呼叫；已排序數值欄位不建立此工作區。

受控基準

Apple M4、darwin/arm64、Go 1.26.6、Node 24.14.0。Go 為三次 -benchtime=300ms 結果的中位數；前端先暖機 60 次，再取七組、每組 50 次的中位數。原版與新版使用相同輸入。

情境	調整前	調整後
2,000 個不支援檔案的目錄掃描	2.118 ms	1.355 ms
同上，配置量／次數	690,179 B／6,052 次	274,176 B／4,052 次
64 段 HLS 清單解析	40.3 µs	25.3 µs
同上，配置量／次數	96,664 B／395 次	28,512 B／263 次
10,000 段 HLS 清單解析	5.745 ms	4.477 ms
同上，配置量／次數	5.697 MB／60,023 次	5.231 MB／40,019 次
含 136 KiB 發行說明的單次更新狀態 JSON	147,669 bytes	141 bytes
同上，序列化時間／配置量	164.8 µs／156,302 B	0.335 µs／240 B
4,999 列含空白數值的表格排序	4.535 ms	0.724 ms
4,999 列自然文字排序	8.762 ms	7.122 ms
4,999 列混合內容排序	6.494 ms	5.259 ms
4,999 列已排序數值欄位	0.0938 ms	0.0324 ms

前端單次呼叫的暫時 heap 增量，中位數如下：

情境	調整前 heap	調整後 heap	調整後額外 ArrayBuffer
含空白數值排序	5.44 MB	1.91 MB	39,992 B
自然文字排序	1.90 MB	0.33 MB	39,992 B
混合內容排序	1.34 MB	0.47 MB	39,992 B
已排序數值欄位	89,336 B	8,392 B	0 B

這些資料只表示指定函式及輸入的結果。Go B/op 是配置總量；Node heap 與 ArrayBuffer 增量受引擎、暖機及 GC 影響，都不是原生 App 的常駐記憶體。掃描基準包含本機暫存目錄的暖檔案系統讀取；HLS 不含網路；更新狀態基準使用合成的長說明，不含 Wails 傳輸時間、下載、簽章驗證或安裝。未量測原生 WebView 長時間 RSS。

驗證與重跑

• 前端 161 項測試通過，涵蓋排序結果／順序／記錄身分、輪詢完整欄位、進度、說明保留、手動重查、取消與過期回應。
• Go 205 項一般測試及 3 個 fuzz 種子套件通過，使用 race detector；已啟用正式簽署 App 的更新驗證 fixture。
• TypeScript、Vite production build、Go vet、Wails production 原生編譯及 macOS 12 arm64 目標檢查通過。
• 前端 10 個 JSX／CSS 原始檔與本輪修改前逐位元組一致。
• HLS 原版對照涵蓋 64 KiB 工作區邊界、32 MiB 單行邊界、有無最末換行及解析錯誤。
• 額外執行 15 秒 HLS 對照 fuzz，698,887 次輸入皆通過。

npm --prefix frontend test
GOTOOLCHAIN=go1.26.6 go test -race ./...
GOTOOLCHAIN=go1.26.6 go test ./internal/app -run '^$' -fuzz '^FuzzPlaylistParserParity$' -fuzztime=15s -parallel=4
GOTOOLCHAIN=go1.26.6 go test ./internal/app -run '^$' -bench 'BenchmarkFunction(Playlist|DirectoryScan|UpdateProgress)$' -benchmem -benchtime=300ms -count=3
cd frontend
node --expose-gc benchmarks/function-review.mts

正式簽署 fixture 驗證需將 FASTFILEVIEWER_UPDATE_TEST_APP 指向可用的正式 App；未設定時只有該項測試會跳過。前端資產需先建置，供 Go 入口嵌入。

此報告記錄最佳化完成時的來源範圍與量測；後續整合的新功能、發行版本及安裝包驗證見發行說明。既有快取上限、檔案操作及更新交易的安全檢查仍受回歸測試覆蓋。