Tech Debt

技術債

已知的捷徑、風險與待改善項目,依影響程度排序。每項含「為何是債」與「償還方式」。

高影響

1. Access email 閘門尚未建立(認證走備援路徑)

• 現況:設計上的最終認證是 Cloudflare Access email 登入,但閘門沒建,實際只靠 OWNER_TOKEN bearer token。
• 為何是債:token 存在使用者 localStorage、需手動貼入、輪替不便;Access 的 JWT 路徑程式都寫好了卻閒置。
• 償還:建立 Access 應用(步驟見 Plan),完成後 token 降為備援。

2. 資料管線依賴單一機器且全手動

• 現況:原始資料(~1.3 GB)只在一台機器的 ~/ash-image-bank/data;re-scrape → build_feed.py → upload_r2.sh → build_embeddings.py → 部署,每步手動。
• 為何是債:單點故障(機器遺失 = 資料管線斷),且步驟間順序錯誤(如忘了重跑 embeddings)會造成推薦指向不存在的影像。
• 償還:先把原始資料備份到 R2 私有 bucket 或外接儲存;中期把管線整合為單一腳本(見 Roadmap)。

3. feed.json / R2 / Vectorize 三方一致性沒有自動檢查

• 現況:「feed key == R2 key」的不變量靠人工遵守;Vectorize 索引與 feed 的同步也靠記憶。
• 為何是債:任何一方單獨更新就出現 404 影像或幽靈推薦,而且要到線上才發現。
• 償還:寫一支驗證腳本(抽樣 HEAD R2 物件、比對 Vectorize 條目數),納入部署流程最後一步。

中影響

4. 缺乏自動化測試

• 現況:前端與 Pages Functions 均無測試;驗證靠手動 smoke test(見 Maintenance)。
• 償還:至少為 pages-lib/gate.ts(認證邏輯、constant-time 比對)與 build_feed.py 的 keys_for() 補單元測試——這兩處錯了最痛。

5. Allow-list 與各種識別碼寫死在程式裡

• 現況:owner email 寫死在 frontend/pages-lib/gate.ts;KV namespace id 等寫死在 frontend/wrangler.toml。
• 償還:email 移到環境變數/Pages 設定;多使用者化時一併處理(見 Roadmap)。

6. localStorage 與 KV 的合併語意只有 union

• 現況:登入時 POST /api/merge 把本機歷史 union 進 KV,沒有刪除同步——在 A 裝置 unlike 過的影像,若 B 裝置的 localStorage 還留著,會被重新加回。
• 償還:小規模下可接受;若要修,需為事件加時間戳做 last-write-wins。

低影響 / 觀察中

7. mock-data 與 smoke test 產物殘留

• 現況:mock-data/ 留在 repo 作 schema 鏡像;本機 smoke test 產物已 gitignore(commit f860593)。
• 償還:保留即可,但 README 已註明「不是真實資料」,避免誤用。

8. 與上游 WikiTok 的分歧

• 現況:upstream remote 還指向 IsaacGemal/wikitok,但程式已大幅改寫,上游更新幾乎不可能乾淨合併。
• 償還:決定是否正式脫鉤(移除 upstream remote),避免誤合併;有用的上游修正改用 cherry-pick。

9. KV 而非 D1

• 現況:互動狀態以單一 KV value(u:<email> → {liked, disliked, read})存放,是刻意的 YAGNI 決策。
• 為何列入:不是現在的債,但若未來要做事件層級分析或多使用者查詢,KV 的整包讀寫會成為瓶頸,屆時遷 D1。