Android 每日飲食營養素紀錄器（Kotlin + Compose）。app 顯示名稱是「肥胖日記」， 專案代號維持 NutriLog —— package、repo、APK 檔名與簽章都綁在它身上。
Why NutriLog? 市面上的飲食紀錄 app 幾乎都要你先開帳號、再把三餐上傳到別人的伺服器。 這支不用：沒有後端、沒有帳號，紀錄全部躺在你自己的手機裡。
- 🔒 完全離線 — 唯一的對外連線是影像辨識與條碼查詢兩支公開 API，兩者都是你主動觸發才會發生。
- 🍱 四條輸入路徑 — 自己填數字、拍照或打一句話交給 Gemini 估、掃商品條碼查 Open Food Facts。
- 🔎 先搜自己吃過的，容錯 — 中文沒有空白可拆詞，改用單字＋相鄰兩字加權比對：「烤肉」找得到「煎烤豬肉排／五花肉」，而「咖啡」不會撈到咖哩飯。
- 🌐 需要的時候才上網查 —— 打了店名就按「AI 查」，它先去找該店公布的官方營養標示再算；平常按「AI 估」就好。要不要查是你按的，不是模型猜的。
- 🔢 五段雙速份數縮放 — 支援
±1與±0.1步進，自動縮放公克/毫升/份量文字與所有營養素，具備基準持久化無損還原。 - 📰 「紙與墨」出版物排版美學 — 內嵌 jf open 粉圓中文與 Neucha 手寫數字、自繪精準向量圖示、形狀即層級，無任何預設 Material 容器與色塊。
- 🔁 辨識失敗就地換一家 — 失敗時面板從底下升上來：選供應商、挑模型、按重試，不用跑一趟設定頁再回來。選完的值就是設定裡的值。
- ✅ AI 的數字一律要你點頭 — 模型給的是估算值，一定先經過確認畫面才入庫。
- ⌚ 手錶動得多就能多吃一點 — 連上健康連線之後，運動消耗會加進當天的目標（不是從吃掉的裡面扣），今日頁、週長條、月曆判斷超標時全部改用加上運動後的額度。預設只回補一半，因為手錶估的熱量普遍偏高。
- 🧮 依身型算目標 — 填身高體重與活動量，用 Mifflin-St Jeor 算出基礎代謝、每日消耗與建議的三大營養素。蛋白質跟著活動量走，久坐的人不會拿到運動員的數字。
- 💧 喝的也算數 — 今日頁營養素底下一排加減鍵（一次 50 ml）記白開水，而飲料的水量跟著那一筆紀錄走：AI 估飲料時會一併給出容量，喝完就自動進當天的飲水量。
- 🗒️ AI 週報／月報 — 每週每月的統計是本機算的、隨時看得到；要不要花一次 AI 呼叫請它寫成報告，由你按下去決定，不會自動送出。
- 🎨 換 app 圖示 — 設定 → 外觀可以從七款內建圖示裡挑一款，桌面上的圖示跟著換。
- 📅 看得出空白 — 月曆式歷史讓「哪幾天忘了記」一眼就有形狀，清單做不到這件事。
- 📤 CSV 匯出 — 唯一能把資料帶出手機的路徑，定位是完整備份，預設全部匯出。
- 🔑 權限只有一個 — Manifest 裡只有
INTERNET，相機在系統相機與 Play 服務中執行，連相機權限都不需要。
| 元件 | 細節 | |
|---|---|---|
| ⚙️ | 架構 |
|
| 🔩 | 程式品質 |
|
| 📄 | 文件 |
|
| 🔌 | 整合 |
|
| 🧩 | 模組化 |
|
| 🧪 | 測試 |
|
| ⚡️ | 效能 |
|
| 🛡️ | 安全 |
|
| 📦 | 相依 |
|
| 🚀 | 擴充性 |
|
└── NutriLog/
├── .github/
│ └── workflows/
│ └── release.yml
├── app/
│ ├── build.gradle.kts
│ ├── proguard-rules.pro
│ └── src/
│ ├── main/
│ │ ├── AndroidManifest.xml
│ │ ├── java/com/watson/nutrilog/
│ │ │ ├── MainActivity.kt
│ │ │ ├── data/
│ │ │ │ ├── ActivityEstimate.kt
│ │ │ │ ├── AppIconSwitcher.kt
│ │ │ │ ├── BackedUpProfile.kt
│ │ │ │ ├── BmrCalculator.kt
│ │ │ │ ├── CsvExport.kt
│ │ │ │ ├── CsvImport.kt
│ │ │ │ ├── DriveAuth.kt
│ │ │ │ ├── DriveBackup.kt
│ │ │ │ ├── HealthConnectSync.kt
│ │ │ │ ├── MonthlyAggregator.kt
│ │ │ │ ├── MonthlyReportStore.kt
│ │ │ │ ├── SettingsStore.kt
│ │ │ │ ├── WeeklyAggregator.kt
│ │ │ │ ├── WeeklyReportStore.kt
│ │ │ │ ├── db/
│ │ │ │ │ ├── CachedProduct.kt
│ │ │ │ │ ├── DailyHealthMetric.kt
│ │ │ │ │ ├── FoodEntry.kt
│ │ │ │ │ ├── FoodSuggestion.kt
│ │ │ │ │ ├── NutriDao.kt
│ │ │ │ │ └── NutriDatabase.kt
│ │ │ │ └── net/
│ │ │ │ ├── AiPrompts.kt
│ │ │ │ ├── DriveClient.kt
│ │ │ │ ├── GeminiClient.kt
│ │ │ │ ├── ImageCompressor.kt
│ │ │ │ ├── OpenFoodFactsClient.kt
│ │ │ │ ├── OpenRouterClient.kt
│ │ │ │ ├── SharedHttp.kt
│ │ │ │ └── TavilyClient.kt
│ │ │ ├── work/
│ │ │ │ └── BackupWorker.kt
│ │ │ └── ui/
│ │ │ ├── App.kt
│ │ │ ├── BarcodeScreen.kt
│ │ │ ├── BmrCalculatorDialog.kt
│ │ │ ├── Common.kt
│ │ │ ├── EditEntryScreen.kt
│ │ │ ├── ExerciseDetailSheet.kt
│ │ │ ├── HistoryScreen.kt
│ │ │ ├── NutriViewModel.kt
│ │ │ ├── PortionMultiplier.kt
│ │ │ ├── ReportScreen.kt
│ │ │ ├── ReviewScreen.kt
│ │ │ ├── SearchScreen.kt
│ │ │ ├── SettingsScreen.kt
│ │ │ ├── TextLookupScreen.kt
│ │ │ ├── TodayScreen.kt
│ │ │ └── theme/
│ │ │ └── Theme.kt
│ │ └── res/
│ │ ├── font/
│ │ │ ├── jf_open_huninn.ttf
│ │ │ └── neucha.ttf
│ │ ├── values/
│ │ │ ├── colors.xml
│ │ │ ├── strings.xml
│ │ │ └── themes.xml
│ │ └── values-night/
│ │ └── colors.xml
│ └── test/
│ └── java/com/watson/nutrilog/
│ ├── ActivityEstimateTest.kt
│ ├── CalorieTargetTest.kt
│ ├── WaterCsvTest.kt
│ ├── BackedUpProfileTest.kt
│ ├── BackupScheduleTest.kt
│ ├── BmrCalculatorTest.kt
│ ├── CsvRoundTripTest.kt
│ ├── DriveBackupPruneTest.kt
│ ├── FoodLibraryMatchTest.kt
│ └── NutrientScalingTest.kt
├── design/
│ ├── canvas.json
│ ├── Main.dc.html
│ └── v2/
├── gradle/
│ ├── libs.versions.toml
│ └── wrapper/
├── tools/
│ ├── emu.ps1
│ ├── setup-google-drive.sh
│ ├── setup-signing.sh
│ └── ui.ps1
├── build.gradle.kts
├── settings.gradle.kts
├── CLAUDE.md
└── README.mdNUTRILOG/
__root__
⦿ __root__
檔案 說明 app/build.gradle.kts 模組建置設定。版號由 CI 從 tag 傳入的 property 覆蓋，本機建置才用預設值。
- 簽章讀 `keystore.properties`，檔案不存在就退回 debug 簽章，讓別人 clone 下來照樣建得起來。gradle/libs.versions.toml 版本目錄，所有相依與外掛的版號單一來源。KSP 的版號前半段必須和 Kotlin 完全一致。 CLAUDE.md 這台機器的環境設定與專案慣例：建置指令、模擬器規則、配色與「紙與墨」版面語言、回歸清單。
com.watson.nutrilog
⦿ app/src/main/java/com/watson/nutrilog
檔案 說明 MainActivity.kt 唯一的 Activity。開啟 edge-to-edge、套上主題，並建立 activity-scoped 的 ViewModel 串接全域狀態。
data
⦿ app/src/main/java/com/watson/nutrilog/data
檔案 說明 ActivityEstimate.kt 把健康連線回報的東西換算成「今天動掉多少大卡」。
- 只認活動消耗與運動場次，要用哪一種看手錶配戴方式。
- 讀不到就回 NONE 並附原因，不生猜測值（總消耗扣基礎代謝、步數換算都已移除）。
- 純計算，有測試涵蓋。AppIconSwitcher.kt 換桌面圖示：把選到的 activity-alias 打開、其餘關掉。
- Android 不讓 app 在執行時把圖示換成任意圖片，只能切換事先放在 APK 裡的 alias。
- 先開新的再關舊的，中間不會有「完全沒有桌面入口」的空窗。
- 每次啟動對一次，系統那側被重設時會跟設定對回來。BackedUpProfile.kt 備份到 Drive 的身型與每日目標（CSV 裝不下的那一半）。
- 白名單而非整包設定：API 金鑰永遠不會被備份，有測試專門檢查。
- 還原時併進匯入的確認面板，不另外問一次。BmrCalculator.kt Mifflin-St Jeor 基礎代謝與每日目標、三大營養素、各餐配比。
- 蛋白質跟著活動量走（1.0–1.8 g/kg，減脂與增肌各 +0.2、封頂 2.0）。
- 碳水固定 55%、脂肪吃差額，脂肪守住 20% 下限。
- 算出來的只是建議，按「套用」才寫進設定。CsvExport.kt 把飲食紀錄轉成 CSV，是把資料帶出手機的路徑。
- 純函式、不碰 Android API。
- 檔頭有 UTF-8 BOM，避免 Excel 中文亂碼。
- 欄位名稱本身就是格式：`CsvImport` 靠名字對應欄位。CsvImport.kt 把匯出的 CSV 讀回資料庫，換手機或重裝之後接回原本的紀錄。
- 靠欄位名稱對應，舊版少兩欄的匯出檔也讀得回來。
- 依「日期＋名稱＋份量＋記錄時間」去重，同一份檔匯入兩次不會變兩份。
- 壞掉的資料列跳過並回報，不讓整份檔案失敗。DriveAuth.kt Drive 授權（Identity AuthorizationClient，非已淘汰的 GoogleSignIn）。
- 只索取drive.file：僅能存取本 app 自行建立的檔案，非受限範圍、免安全評估。
- app 內不含任何 client id：Android OAuth client 以套件名 + 簽章 SHA-1 辨識。DriveBackup.kt 備份與還原的流程編排：建立 Drive 主頁 NutriLog/資料夾、上傳當日 CSV、保留最近 30 天。
- 備份內容與本地匯出完全相同，可自行下載或改用本地匯入讀回。
- 保留規則為純函式並有測試涵蓋。HealthConnectSync.kt 健康連線的讀與寫。
- 讀每日運動消耗；寫入為選配，只在新增／編輯／刪除當下寫。
-diagnose()倒出原始讀值給設定頁的診斷區與 logcat。
- 以nutrilog_<紀錄 id>當 clientRecordId，改同一筆就是覆寫。
- 相依釘在 1.1.0-beta01（1.1.0 正式版要 compileSdk 36）。MonthlyAggregator.kt 整月統計與月報 prompt 組裝。
- 統計在本機算，跟 AI 報告分開，沒產生報告也看得到數字。MonthlyReportStore.kt 月報存取（ filesDir/monthly_reports/<yyyy-MM>.json）。
- 不進 Drive 備份：報告隨時可以重新產生。SettingsStore.kt 使用者設定與每日目標。用 DataStore Preferences 儲存單份無關聯之輕量偏好設定。 WeeklyAggregator.kt 整週統計與週報 prompt 組裝，並解析回應結尾的 json:targets區塊。
- 那個區塊就是「建議下週每日目標」，改 prompt 時名稱不能動。WeeklyReportStore.kt 週報存取（ filesDir/weekly_reports/<週日>.json）。
- 一週從星期日開始，和今日頁的週長條一致。
data.db
⦿ app/src/main/java/com/watson/nutrilog/data/db
檔案 說明 DailyHealthMetric.kt 每日運動消耗的本機快取（migration 2→3 新增）。
- 週長條與月曆一打開就要用，不能等健康連線慢慢回。FoodEntry.kt 一筆吃下去的飲食紀錄實體，包含份數倍率 `portionMultiplier`、延伸四項營養素與全天合計 `Totals`。日期以本地 YYYY-MM-DD 字串儲存。 NutriDao.kt Room DAO。合計走 SQL `GROUP BY` 計算，不把龐大明細撈進記憶體。常吃／最近以「名稱＋份量文字」分組聚合。 FoodSuggestion.kt 個人食物庫品項 —— 從既有紀錄聚合出來的品項模型，不額外建立實體表，提供快速一鍵帶入。 CachedProduct.kt 查過的條碼商品快取表（每 100g 營養素），節省 OFF 頻率限制並支援離線再次掃碼。 NutriDatabase.kt Room 資料庫單例與 Migrations。
data.net
⦿ app/src/main/java/com/watson/nutrilog/data/net
檔案 說明 GeminiClient.kt 照片與文字描述的營養估算。以 `responseSchema` 強制結構化 JSON 輸出，自動重試 5xx 與網路逾時。
- 四個進階營養素（糖／鈉／膳食纖維／飽和脂肪）列為 `required` 但仍可為 `null`：選填等於給模型一個整個略過的藉口。DriveClient.kt Google Drive REST v3，僅實作備份所需的四支端點（建資料夾、上傳／覆蓋、列檔、下載）。
- 以 OkHttp 手寫，不引官方 Drive client 函式庫（會拖進 google-api-client 與 guava）。
- 錯誤訊息帶上 Drive 回傳內容，權杖過期與配額不足才分得開。OpenFoodFactsClient.kt 條碼查詢客戶端。自動附帶規範之自訂 User-Agent，並把鈉公克轉換為毫克。 ImageCompressor.kt 將原始照片等比例縮放到長邊 1024 px 並壓為 base64 JPEG，大幅降低頻寬與延遲。 SharedHttp.kt 全 app 共用之 `OkHttpClient` 單例，維持高效連線池與執行緒管理。 OpenRouterClient.kt 文字辨識的另一家供應商（**只做文字**，拍照永遠走 Gemini）。
- 以**強制函式呼叫**（`tool_choice`）鎖住 JSON，而不是 `response_format` —— 想用的免費模型不支援後者。
- 錯誤碼比 Gemini 多一種：**402 是餘額不足**（免費模型也需要帳號裡有額度）。TavilyClient.kt 「AI 查」按下去時的網路搜尋。把清洗過的頁面正文接到 prompt 前面，**與供應商無關**，兩家都適用。
- 不需要 tool calling，也不多消耗模型的請求次數。
- 搜尋失敗一律回 `null`：它只是輔助，不該因為搜尋壞掉讓整條辨識失敗。AiPrompts.kt 兩家供應商**共用的 prompt**。同一段話兩邊各抄一份遲早會漂，而漂掉的症狀是「換一家之後回來的東西長得不一樣」。
ui
⦿ app/src/main/java/com/watson/nutrilog/ui
檔案 說明 NutriViewModel.kt 唯一的 ViewModel：管理全 App 狀態機、草稿狀態、辨識生命週期、搜尋與預設餐別。 App.kt 根 Composable。分派畫面與管理相機、相簿、SAF 與條碼掃描之 ActivityResultLauncher。 TodayScreen.kt 今日主畫面：一週長條、已吃熱量計數器、餐別分段進度條、三大營養素組成與兩級超標警示、固定四餐清單與五合一懸浮選單。 PortionMultiplier.kt 五段純數字雙速步進列（`±1` 與 `±0.1` 圓章按鍵），中間顯示倍率與襯線數字，支援基線對齊與無損還原。 EditEntryScreen.kt 共用飲食編輯表單：2×2 核心營養素網格、自繪圓章數字鍵盤（避免擋住儲存鈕）、份數縮放步進列、折疊進階營養素與熱量交叉檢驗。 ReportScreen.kt AI 週報／月報。
- 上半是本機算的統計（含與上週／上個月比），隨時看得到。
- 下半是報告本文；還沒產生時給一顆「產生週報」。
- 本文只認標題、條列、段落三種，模型多給的粗體與表格降成純文字。ReviewScreen.kt AI 辨識結果確認頁面：品項勾選、單品份數縮放、信心度指標與目標餐別預選。 SearchScreen.kt 搜尋與個人食物庫（90 天常吃／最近兩頁切換，即時多關鍵字全文搜尋，點擊直接進入編輯表單）。 TextLookupScreen.kt 常吃食物快捷與自然語言文字描述 AI 辨識合成頁面。 ExerciseDetailSheet.kt 今日頁「運動 +350 ›」點開的明細。
- 講清楚數字的來源（全日活動消耗與單場運動涵蓋範圍不同）。
- 列出吃了、動了、淨攝取，以及今天的目標是怎麼加出來的。HistoryScreen.kt 月曆式歷史視圖：熱量深淺與超標警示色塊、一眼辨識空白未記錄日，下方統計當月總覽。 BarcodeScreen.kt 條碼掃描與手動輸入條碼，支援自訂實際食用克數自動等比換算。 SettingsScreen.kt 外觀模式（系統/淺色/深色）、Gemini API Key 與模型攤開圈選（刻意不用下拉選單）、每日營養目標數字欄位、進階營養素開關與 CSV 備份匯出。 BmrCalculatorDialog.kt 「依身型計算」的面板：填身型與目標，看到建議的熱量與三大營養素。
- 蛋白質標出每公斤幾克，看得出這個數字高不高。
- 按「套用」才寫進每日目標。Common.kt 「紙與墨」設計系統元件：`Hairline`（1px）、`Rule`（2px）、`StampButton`、`PillButton`、`TextAction`、`RoundKey`、`BallotRow`、`SquareCheck`、`NutriTextField`、`dismissKeyboardOnTap`（點空白處收鍵盤）、`SwipeToReveal` / `UndoStamp`（左滑刪除與復原）與全自繪向量 `*Mark` 圖示。
ui.theme
⦿ app/src/main/java/com/watson/nutrilog/ui/theme
檔案 說明 Theme.kt 「紙與墨」出版物色票（淺色米紙 `#F7F3E9`、深色暖黑 `#17150F`）、三大營養素色階、兩級超標警示（橘 `#B8791F` / 紅 `#D8462A`），以及內嵌的 jf open 粉圓中文字型與 Neucha 數字字型。
work
⦿ app/src/main/java/com/watson/nutrilog/work
檔案 說明 BackupWorker.kt 每日一次的 Drive 備份排程（WorkManager）。
- 選用 WorkManager 而非 AlarmManager：Doze 與重新開機後仍可靠。
- 網路類失敗一律 retry；僅「需重新授權」回 failure，因背景無畫面可詢問使用者。
test
⦿ app/src/test/java/com/watson/nutrilog
檔案 說明 NutrientScalingTest.kt 單元測試：驗證份量文字縮放、DetectedFood 營養素等比計算、EntryDraft 基準導出與還原無損計算。 ActivityEstimateTest.kt 兩種配戴方式各自該採用哪一種資料、讀不到時不生猜測值。 BackedUpProfileTest.kt 備份的身型 JSON 是白名單，裡面不會出現 API 金鑰。 BmrCalculatorTest.kt 蛋白質跟著活動量走、封頂 2.0、碳水固定 55%、脂肪 20% 下限。
- 其中一條專釘「久坐與高活動量不能算出同一個數字」。CsvRoundTripTest.kt 單元測試：CSV 匯出→匯入來回逐欄一致、逗號／引號／換行跳脫、缺資料維持 null、舊版欄位相容、去重鍵與壞資料列跳過。 DriveBackupPruneTest.kt 單元測試：雲端備份的 30 天保留規則 —— 只刪自己產生的日期檔、跨月跨年排序正確、使用者自行放入的檔案一律不動。 FoodLibraryMatchTest.kt 單元測試：食物庫的模糊比對 —— 描述比庫裡更細仍找得到、名稱裡被拆開的詞仍找得到、只共用一個字不算命中、整串命中排在近似之前。
tools
⦿ tools
檔案 說明 emu.ps1 Windows 模擬器輔助腳本：啟動 AVD 並等待 `boot_completed`，建置與部署。 ui.ps1 UI 驗證工具：傾印畫面所有文字節點與座標，並以元件文字進行精準點擊測試。 setup-signing.sh 一次性正式發佈簽章金鑰設定精靈（產金鑰 → 驗指紋 → 設 GitHub Secrets）。
.github.workflows
⦿ .github/workflows
檔案 說明 release.yml 推 `v*` tag 自動觸發建置、覆寫版號、以正式簽章產出 APK 並發佈至 GitHub Release。
- 語言： Kotlin 2.0.21
- 建置工具： repo 內附的
./gradlew（Gradle 8.11.1，不必另外安裝） - JDK： 17
- Android SDK： compileSdk 35，最低支援 Android 8.0（minSdk 26）
只是想使用 app 的話不需要安裝上述環境 —— 直接至 Releases 下載最新 APK 安裝即可。
從原始碼編譯：
-
Clone 專案：
❯ git clone https://github.com/rowing195/NutriLog
-
進入目錄：
❯ cd NutriLog -
建置 Debug APK：
❯ ./gradlew assembleDebug
APK 產出於 app/build/outputs/apk/debug/app-debug.apk。
若本地無 keystore.properties，Gradle 將自動退回 debug 簽章以確保可順利編譯。
安裝至已連線的實機或模擬器：
❯ ./gradlew installDebugWindows 平台可使用隨附腳本：
& ".\tools\emu.ps1" start # 啟動模擬器並等待 boot_completed
& ".\tools\emu.ps1" deploy # 自動編譯並安裝執行自動化單元測試套件：
❯ ./gradlew test單元測試覆蓋：
- 份量字串縮放演算法（克、毫升、碗、份）
DetectedFood浮點營養素精確度與可空欄位保持EntryDraft基準值導出與無損還原（避免浮點進位累積漂移）
- 雲端備份的 30 天保留規則：只刪自己產生的日期檔、跨月跨年排序正確、使用者自行放入的檔案一律不動
- 描述打得比食物庫裡更細仍找得到（「手沖藝妓黑咖啡」→「手沖黑咖啡」）
- 換一種說法仍找得到（「美式黑咖啡」→「手沖黑咖啡」）
- 名稱裡被拆開的詞仍找得到（「烤肉」→「煎烤豬肉排／五花肉」）
- 只共用一個字不算命中（「咖啡」不會撈到「咖哩飯」）
- 整串命中一定排在近似命中之前，篩掉不相干的並依相符程度排序
- 每日備份對齊到凌晨 3 點的延遲計算（跨日、剛好 3 點、深夜與傍晚各一種）
- 這一項是純函式，因為它決定了「每一個日期檔是不是前一天結束時的完整狀態」
- 蛋白質的每公斤克數跟著活動量走（久坐 1.0 → 非常高 1.8），減脂與增肌各再加 0.2、封頂 2.0
- 同一個目標下，久坐與高活動量不能算出一樣的數字（舊版的固定倍率就是這樣壞的）
- 碳水固定佔 55%、脂肪吃差額；蛋白質高到塞不下時讓位的是碳水，脂肪守住 20% 下限
- 三大營養素加起來等於目標熱量
- 整天配戴：採用全日活動消耗，運動場次比它多時改用場次
- 只有運動時戴：只採用運動場次，全日活動消耗再大也不算（它只涵蓋戴著的那幾小時）
- 兩種都讀不到時是 0，而且說得出原因；步數照樣帶回來但不換算成大卡
- 備份的身型 JSON 是白名單：裡面不會出現任何 API key
- 還原後目標與身型逐欄一致，未知欄位不讓解析失敗
- 匯出→匯入來回逐欄一致（含份數倍率與記錄時間）
- 食物名稱裡的逗號、引號與換行照 RFC 4180 跳脫與還原
- 缺資料維持
null而不是變成 0 - 舊版（少「記錄時間」「份數倍率」兩欄）的匯出檔仍可匯入
- 去重鍵：同一筆重複匯入會撞在一起，但同名不同時間的兩筆不會
UI 部分使用 tools/ui.ps1 依元件文字進行模擬器自動化操作：
& ".\tools\ui.ps1" dump # 列出畫面所有文字節點與中心座標
& ".\tools\ui.ps1" tap "記一筆"
& ".\tools\ui.ps1" type "Chicken" # input text 只吃 ASCII，測試資料一律用英數- 一週長條與日紀錄聯動：上方為一週每日熱量達成率長條，滑動切換日期時自動維持同步，跨週時平滑換頁。
- 主數字顯示已吃熱量：主視覺直接顯示當日已攝取總熱量，目標與剩餘額度退居次要輔助行。
- 餐別分段熱量條：以早、午、晚、點心四色區段直觀呈現熱量攝取分佈結構。
- 三大營養素組成與兩級超標警示：
- 蛋白質、脂肪、碳水化合物轉換為熱量比例長條。
- 圖例整合兩級警示邏輯：超標 10% 以內顯示暖橘（
Warning），超過 10% 顯示朱紅（Over）。 - 下方進階營養素（糖／鈉／膳食纖維／飽和脂肪）一行到底，窄螢幕放不下時可以左右拖，高度永遠固定（見 issue #12）。
- 固定四餐區塊：早餐、午餐、晚餐、點心四格永遠列出，未記錄時提供直接補登入口，並自動預選該餐別。
- 五合一懸浮章印選單：右下角自繪墨印按鈕展開拍照、相簿、常吃/文字、條碼與手動五大入口。
- 左滑刪除與復原：紀錄列左滑時整張字卡跟著位移，放手後以彈簧回彈定位、刪除區留在原地，點擊後刪除，左下角滑出與「記一筆」同尺寸的深灰復原章，章體下沿墨線線性收縮呈現剩餘秒數，提供 5 秒復原視窗。復原以原 id 還原紀錄，備份與去重鍵均不受影響。
- 份數範圍為 0.1～99 份，辨識結果確認頁與手動編輯共用相同上限。
- 五段純數字雙速步進列：提供
−1、−0.1、+0.1、+1四顆自繪圓章按鍵，中間展示當前倍率與襯線數字。 - 基準值持久化與無損還原：
- 資料庫記錄
portionMultiplier。 - 編輯已放大紀錄時，系統以
deriveBase精確逆推原始 1.0x 基準，避免多次縮放產生的浮點數捨入漂移。
- 資料庫記錄
- 全自動字串與數值同步：
- 同步調整份量文字（例如
1 碗 (250g)縮放為1.5 碗 (375g)、700ml縮放為1050ml）。 - 熱量取整數、三大營養素保留一位小數、可空進階營養素正確保持
null。
- 同步調整份量文字（例如
| 方式 | 運作流程 |
|---|---|
| 輸入營養素 | 2×2 核心營養素網格，搭配自繪圓章數字鍵盤與份數步進列，完全避免系統鍵盤遮擋儲存鈕問題。 |
| 拍照辨識 | 拍照或自相簿選取 → 壓縮長邊至 1024 px → Gemini 結構化辨識 → 確認畫面逐項勾選與微調後入庫。 |
| 常吃／文字輸入 | 同一個輸入框服務兩條路：打字即時模糊篩選個人食物庫，找到直接點；篩不到時才把那句描述（如「無糖綠茶 700ml」）交給 Gemini 估算。 |
| 掃條碼 | 掃描條碼或手動輸入 → 優先讀取本機快取，無快取則查詢 Open Food Facts → 輸入食用公克數自動換算。 |
所有有輸入的畫面（上表三條打字路徑 ＋ 搜尋 ＋ 設定的每日目標）共通一件事：點輸入框與鍵盤以外的空白處即可收鍵盤，回到沒在打字的版面，已經打的字與數值都保留。編輯表單裡自繪的數字鍵盤同樣照這個方式收 —— 對使用者而言那與系統鍵盤是同一件事。
常吃頁與搜尋頁另有第二個入口：手指一開始捲清單，鍵盤就自己收起來。捲清單本身就表示使用者不在打字、正在看結果，而鍵盤佔掉半個畫面時剩下的清單只有兩三列。左右滑換分頁與點分頁標籤刻意不收（前者可能只是看一眼另一頁就要繼續打字，後者是畫面自己在捲）；編輯表單也不掛這條 —— 那裡捲動是為了把儲存鈕拉回畫面上，收掉數字鍵盤正好相反。
- 最上面一個搜尋框，打字即時篩常吃／最近兩頁，找到直接點那一列帶進編輯表單 —— 不必在清單裡慢慢翻，也不必跳去搜尋頁。
- 篩選是模糊比對（原理見〈設計決策〉）：「烤肉」找得到「煎烤豬肉排／五花肉」，而「咖啡」不會把咖哩飯撈上來。
- 找得到的排在前面，同分的維持原本「常吃」的次數順序與「最近」的日期順序。
- 底下那行會看情況講話：上面還篩得到東西時是「不是上面這些？」，真的一筆都沒有才說「沒有『⋯』？」—— 上面明明列著相近的卻說沒有，等於這個 app 沒在看自己的清單。
- 底下是成對的兩顆章：「AI 估」（憑模型印象，快）與「AI 查」（先上網找官方營養標示再算，慢一點）。兩個名字只差一個字，而那個字正好就是唯一真正的差別（見〈要不要查網路，由使用者按鈕決定〉）。
- 鍵盤一開，底下那區自動收到只剩兩顆章，把高度讓給清單；真的篩不到時標題會留著，因為那時候它是畫面上唯一還在講話的東西。兩顆章不跟著收 —— 收掉說明是省版面，收掉動作本身會讓人以為按鈕不見了。
- 離開搜尋框時是兩段動畫：先落地，再長出來。 等鍵盤真的退完、整區沉到定位，文字才從章的底邊往上長出來。兩件事一起做的話，畫面在同一段時間裡往兩個方向動，讀起來是彈一下而不是一個動作。等多久是問系統鍵盤的，不是寫死的秒數，所以各家輸入法快慢不一樣也都接得上。
連鎖店的品項網路上有官方營養標示，模型憑印象估的跟官方公布的差得不少。 所以常吃頁底下是兩顆章，打完描述自己選：
| 按哪一顆 | 發生什麼事 | 實測「麥當勞 大麥克」 |
|---|---|---|
| AI 估（主章） | 模型憑自己的知識估，快、不花搜尋額度 | 540 kcal（美國規格） |
| AI 查（次章，深灰） | 先上網找那個品項的營養標示，再把找到的表格交給模型讀 | 503 kcal（台灣麥當勞官方頁） |
- 要用第二顆章得先到 設定 → API 管理 選一個搜尋來源；沒選的話那顆是外框章、 按不下去，底下會講一句為什麼。
- 搜尋壞掉不會讓辨識失敗：查不到就讓模型照原本的方式估，錯誤留在 logcat。
- 搜尋結果放在使用者輸入前面並明講它是參考資料：它是外部來的、可能過期或根本在講別的品項 （實測結果裡混著部落格整理的表格，數字和官方差了將近 100 大卡）。
設定裡可以選文字描述要送去 Gemini 還是 OpenRouter。拍照不受它影響，永遠是 Gemini —— 拍照要吃得下圖片的模型，而這條路上想用的 OpenRouter 免費模型是純文字的。 做成一個總開關的話，選了 OpenRouter 之後拍照會神祕地失敗或偷偷跑去別家，兩種都比在設定頁講清楚差。
兩家共用同一份 prompt（AiPrompts），但傳輸格式、強制 JSON 的手法、錯誤訊息全都不一樣，
所以是兩個獨立的 client、沒有抽共同介面。
- 一格一天的月曆視圖，格子內顯示當日熱量，並以背景深淺及超標朱紅色直觀呈現。
- 「看得出空白」設計：未記錄天數一眼即可辨識，避免清單模式造成的漏記遮蔽。
- 左右滑就換月，拖的時候上方那個「2026 / 09」也跟著手指走，下一個月的月份從旁邊補進來 —— 和今日頁的週長條同一種手感。兩側箭頭留著，兩條路做同一件事。一次滑動就是一個月，不管滑多快。
- 下方即時由 SQLite
GROUP BY計算當月總記錄天數、平均熱量與超標天數。 - 不在本月時，畫面最底下會出現一顆空心章「回到本月」。它不在報頭裡： 它是一個動作而不是某一個月的內容，放到分頁器外面的底部，它出現時吃掉的是月曆底下那塊 本來就空的地方，格子一格都不會動。
- 點擊右上角放大鏡開啟。
- 未輸入關鍵字時：展示個人食物庫，支援左右滑動切換「90 天常吃」與「全部最近」。
- 輸入關鍵字時：切換為即時全文搜尋模式，支援多關鍵字空白分割比對（名稱 + 份量文字）。
- 點擊任一項目直接帶入編輯表單，兼顧便捷與可編輯性。
這裡的搜尋與常吃頁那一個搜的不是同一種東西：這頁搜的是逐筆紀錄（每一筆帶日期），回答的是「我哪天吃過這個」；常吃頁搜的是聚合後的品項，回答的是「拿一個品項來記一筆」——日期在那裡是雜訊，而且同一樣東西會重複出現二十次。兩頁共用同一個食物庫元件，但主要工作不同，所以沒有合併成一個要切換模式的畫面。
- 失敗時從底下升上來一張佔六成高的面板，上面留著失敗的原因 —— 那才是判斷「該換什麼」的依據。
- 供應商左右兩家（和設定頁同一種圈選），切換時底下的模型區跟著滑過去：Gemini 是固定型號的清單，OpenRouter 是自由填的模型路徑。
- 在這裡改的就是設定裡的那一組，不是另一份副本。拍照與文字各改各的 —— 拍照要看得懂圖片的模型，文字那邊常用的是純文字模型，混在一起會救了一邊弄壞另一邊。
- 選完按「重試」才會真的再送一次：每改一下就自動發一次請求會白白花掉額度。
- 今日頁營養素底下那一排：中間是當天的飲水量，兩側各一顆 ±50 ml。
- 飲料的水量跟著那一筆紀錄走。 編輯表單多一格「水量」，AI 辨識飲料時會自己填 （700 ml 的珍奶就是 700），確認畫面看得到那個數字才入庫。刪掉那筆飲料，水量跟著消失。
- 手動那一段是獨立的，存在自己的表裡，不會在紀錄清單長出一堆 0 大卡的白開水。 兩者相加才是當天的量，而總量不會被減成負的。
- 匯出的 CSV 兩種都帶得走：飲料的水量是每一列的欄位，手動的那一段以日期為單位 自己一列（食物名稱留空）—— 那天一筆食物都沒記也保得住。
- 於 設定 → Health 連線 打開「讀取運動消耗」後，今日頁「目標」底下多一行「運動 +350 ›」， 當天的額度跟著變多。點那一行看明細：數字從哪裡讀來、吃了多少、今天的目標怎麼算出來的。
- 加進目標，不是從吃掉的裡面扣。 你記的東西不該被改寫 —— 「吃了 1,800」就是 1,800，
變的是那天能吃多少。今日頁、餐別長條、週長條、月曆格子與月摘要的超標判斷全部走同一個
effectiveCalorieTarget()，不會出現「今日頁說還有 200、月曆卻把同一天標紅」。 - 打開它的時候，熱量目標的底會退到久坐基準，運動改由手錶量。活動係數的定義本來 就含運動（「輕度」＝每週運動 1–3 天），不退的話同一批熱量會算兩次。關掉就算回你 填的活動係數。蛋白質兩種情況都照你填的活動量算。
- 運動熱量預設只回補一半（設定 → 每日目標 →「運動熱量回補」，可改 25/50/75/全額）。 手錶估熱量普遍偏高，全額吃回去等於把高估的部分也吃掉。
- 手錶配戴方式決定哪一種資料算數：整天戴就用全日活動消耗，只有運動時戴就只算 運動場次（全日那個數字只涵蓋戴著的那幾小時，當一整天用會低估）。
- 只認活動消耗與運動場次這兩種資料。 讀不到就講原因，不會拿「總消耗扣基礎代謝」 或步數換算生一個猜的數字給你（理由見〈運動消耗加進目標〉）。
- 寫入飲食是選配、預設關閉，而且只在新增、編輯、刪除當下寫，不在背景整批同步。
每一筆用
nutrilog_<紀錄 id>當 clientRecordId，改同一筆就是覆寫，不會長出重複的紀錄。 - 每天的值快取在 Room 的
daily_health_metrics，週長條與月曆一打開就要用，不能等健康連線慢慢回。 - 數字和手錶的 app 對不上時，設定 → Health 連線最底下有「讀取診斷資訊」：列出今天從
健康連線讀到的原始值（活動大卡、總消耗、步數、運動場次、四個權限各有沒有）以及
App 採用了哪一個。同一份會寫進 logcat（
adb logcat -s HealthDiagnostics）。 「無資料」和「0」是分開的 —— 前者是對方沒寫進來，後者是那天真的沒動。
- 設定 → 每日目標 → 依身型計算：填性別、年齡、身高、體重、活動量與目標（減脂／維持／增肌）， 用 Mifflin-St Jeor 算出基礎代謝與每日消耗，並給出建議的熱量、三大營養素與各餐配比。
- 按「套用」才會寫進目標 —— 和 AI 辨識、週報推薦同一條規則：算出來的只是建議。
- 蛋白質跟著活動量走（久坐 1.0 → 非常高 1.8 g/kg，減脂與增肌各再加 0.2，封頂 2.0）， 結果會標出「蛋白質每公斤 N g」，這個數字高不高一眼看得出來。
- 身型本身會存下來：下次打開不必重填，週報也要用體重判斷蛋白質夠不夠。
- 入口在月曆月摘要底下那一列。返回鍵回月曆 —— 報表講的就是月曆上那段期間。
- 統計是本機算的，隨時都看得到：記錄天數、平均攝取、運動消耗、每日消耗、熱量收支 （換算成大約幾公斤），以及和上週（上個月）比的增減。
- 報告要花一次 AI 呼叫，按了才送出，不會自動產生。一筆紀錄都沒有的期間不給產生 —— 按下去只會換來一份在講「沒有資料」的報告。
- 週報結尾會附建議的下週每日目標，同樣是按「套用為每日目標」才寫進設定。
- 報告交給哪一家 AI 在 設定 → API 管理 → AI 報告 選，沿用那一家的金鑰與模型，不另外要金鑰。
- 報告存在 app 私有目錄，隨時可以重新產生，因此不進 Drive 備份（備份的是紀錄與設定）。
- 設定 → 外觀 → APP 圖示：八款可選 —— 糯糯（預設）、肥貓、菲比啾比、快樂牛馬、黑糯糯、紅糯糯、冰紅茶、牢大。 點一下就換，桌面上的圖示會先消失一下再出現，有些桌面要重新整理才看得到。
- 只能從內建的款式挑，不能用自己的照片。 Android 不讓 app 在執行時把自己的桌面 圖示換成任意圖片，理由見設計決策。
- 從 v1.18.1 以前的版本更新上來時，桌面上原本那顆圖示可能會失效，要從 app 抽屜 重新拉一次到桌面。app 抽屜裡的入口、飲食紀錄與設定都不受影響。
- 經由 Android 儲存存取框架（Storage Access Framework, SAF）將全量飲食紀錄匯出為標準 CSV，或把匯出過的 CSV 讀回來。
- 檔案開頭內嵌 UTF-8 BOM，確保 Excel 與 Google 試算表正確辨識繁體中文。
- 缺失營養素輸出為空白欄位而非 0，匯入時也維持
null，忠實保留原始資料型態。 - 匯入前先停在確認面板：會先算好「新增幾筆、日期範圍、略過幾筆重複、跳過幾列壞資料」再問要不要寫進去。
- 重複自動略過：以「日期＋名稱＋份量＋記錄時間」辨識同一筆，同一份檔案匯入兩次不會變成兩份，也能把兩支手機的紀錄合併起來。
- 匯出→匯入→再匯出實測為完全相同的檔案，換手機可以無損接回。
- 於設定頁連結 Google 帳號後，每天自動將紀錄備份至雲端硬碟主頁
NutriLog/資料夾，一天一個日期檔、僅保留最近 30 天。 - 背景排程採用 WorkManager（非 AlarmManager），可於 Doze 省電模式與重新開機後維持運作。排程對齊至每日凌晨 3 時，因此每個日期檔即為「前一日結束時的完整狀態」；實際執行時間會受 Doze 影響而順延至裝置下次喚醒，WorkManager 保證的是頻率而非準點。
- 每份備份皆為資料庫完整快照而非當日增量，最新一份永遠包含全部紀錄。
- 授權範圍僅
drive.file：只能存取本 app 自行建立的檔案，讀不到雲端硬碟上的其他資料。此範圍非 Google 定義之受限範圍，無需安全評估審查。 - 備份內容與本地匯出完全相同，可直接於 Drive 下載、以試算表開啟，或改用本地匯入讀回 —— 資料不會被鎖在 app 裡。
- 唯一的例外是身型與每日目標：它們是設定而不是紀錄，塞不進 CSV 的欄位，所以另外存一份
nutrilog-profile-<日期>.json。那是一份白名單（只有目標與身型欄位），API 金鑰永遠不會被備份，有測試專門守著。還原時併進同一個確認面板，不另外問一次。 - 「連結 Google Drive」會順便把雲端的紀錄接回來：換手機時自動比對雲端備份，走與本地匯入相同的確認面板（新增幾筆／略過幾筆重複），確認後才寫入資料庫。
- 此功能為選配。未連結時 app 不會存取網路，也不會排入任何背景工作。
- 首次使用需自行於 Google Cloud 建立 OAuth client，可執行
tools/setup-google-drive.sh精靈完成設定。
設定分兩層：先是一排項目，點進去才是內容。七段疊成一條長捲軸的話，找一個開關要捲很久； 選單每一列右邊直接寫著現在的值（深淺模式、熱量目標、健康連線讀寫狀態、key 設了沒、 Drive 連了沒），不用點進去就看得到自己設過什麼。 子頁的返回鍵回選單，不是回今日頁 —— 不然每改一項設定都要重新點兩次進來。
三把 key 都在 設定 → API 管理 底下，各自一頁：
| key | 用在哪 | 怎麼拿 |
|---|---|---|
| Gemini | 拍照辨識（必需）、文字辨識（預設） | Google AI Studio 免費申請 |
| OpenRouter | 文字辨識的另一家（選配） | openrouter.ai |
| Tavily | 「AI 查」的搜尋來源（選配） | tavily.com，免費層 1000 次/月 |
Key 僅安全儲存於本地 DataStore，不會打包進 APK 或上傳第三方伺服器。
同一頁還可以選模型（預設推薦 gemini-3.7-flash，亦可選用 gemini-3.5-flash-lite）、
文字辨識要走哪一家、「AI 查」要用誰查，以及週報／月報交給哪一家寫（沿用那一家已經
填好的金鑰與模型，不另外要一把）。只有 Gemini 那把是必需的：
沒有它拍照辨識就不能用，其餘三項不設也不影響 app 的其他功能。
這一節是「為什麼這樣設計」；「什麼東西壞過、怎麼追出來的」在 已關閉的 issues。
飲食紀錄具備日增長、關聯查詢（依日期範圍、餐別合計、分組統計）特性，採用具備索引的 Room SQLite 關聯式資料庫是最可靠做法。設定資料量極小且單一，採用 DataStore Preferences 即可滿足需求。
- 拍照：使用
ActivityResultContracts.TakePicture()委託系統相機 App 處理。 - 掃碼：使用 Google Play 服務之 Google Code Scanner，掃描視窗獨立於 Google Play 服務行程執行。
- 相簿：使用系統
PickVisualMedia照片選擇器。
本 App 本身無需宣告 CAMERA 或儲存權限，僅需 INTERNET 權限進行外部查詢。
- 色票：淺色米紙底色
#F7F3E9、深色暖黑#17150F、朱紅焦點#D8462A、琥珀警示#B8791F。 - 規線取代色塊：版面層次完全依靠 2px 墨線（
Rule）與 1px 細線（Hairline）劃分，堅決不用 Material 浮凸色塊卡片。 - 字型：純數字、日期、單位與按鍵採用內嵌 Neucha（
res/font/neucha.ttf）手寫體，並已正規化數字與標點的側邊留白（原版1/2/3/4/5/7側邊留白為 0，導致11、0.2等組合會黏在一起） —— 每天隨手記一筆的東西，數字長得像手寫的比像印刷品更貼近它在做的事；中文採用內嵌 jf open 粉圓（res/font/jf_open_huninn.ttf）—— 圓體的柔和調性搭配手寫數字，而粗細均勻、小字級撐得住；標題輔以拉開字距（letterSpacing）建立清晰層級。
常吃頁最上面只有一個輸入框，它同時是「篩自己的食物庫」與「把描述交給 AI」的入口。做成上下兩個框、或一個框配兩顆同級按鈕，都要使用者在打字之前先決定用哪一種搜尋，而選錯是安靜的：想篩清單卻送去 AI，等於白花一次 API 呼叫與數秒等待；想問 AI 卻打進篩選框，只會看到空清單、像是壞了。一個框則沒有東西要選 —— 打字時清單自己收斂，收斂到空的那一刻正好就是該問 AI 的時候。同理，鍵盤上的送出鍵只收鍵盤、不送 AI：那條要花錢也要等的路，一定要明確按下那顆章才走。
比對不能只用 contains。 中文沒有空白可以拆詞，而使用者為了讓 AI 估得準，打的往往比食物庫裡存的更細、或根本是另一種寫法。實際做法是單字與相鄰兩字（bigram）各算一份重疊比例，相鄰兩字加權 2 倍，門檻 0.3：
| 關鍵字 → 食物庫裡的 | 該不該中 | 只看相鄰兩字 | 只看單字 | 加權合分（現行） |
|---|---|---|---|---|
| 手沖藝妓黑咖啡 → 手沖黑咖啡 | 該中 | 0.50 ✅ | ✅ | 0.58 ✅ |
| 美式黑咖啡 → 手沖黑咖啡 | 該中 | 0.50 ✅ | ✅ | 0.54 ✅ |
| 烤肉 → 煎烤豬肉排／五花肉 | 該中 | 0.00 ❌ | ✅ | 0.50 ✅ |
| 咖啡 → 咖哩飯 | 不該中 | 0.00 ✅ | 1.00 ❌ | 0.25 ✅ |
兩種 n-gram 各自補對方的洞：只看相鄰兩字會漏掉在名稱裡被拆開的詞（「烤肉」在「煎烤豬肉排」裡是烤…肉，相鄰兩字一個都對不上），只看單字則會把「咖」對上咖哩、「肉」對上任何有肉的東西。加權相加之後兩件事同時成立，這也是 CJK 搜尋的標準形狀 —— 單字與相鄰兩字各建一份索引再加權合分。門檻 0.3 最好記的意義是「兩個字的關鍵字，兩個字都要出現」：只中一個是 0.25，剛好落在門檻外。整串命中另外給 2.0，因為近似分數的上限就是 1.0，撞在一起就無法保證「真的有這個」排在「長得有點像」前面。
它沒有語意。「拿鐵」與「牛奶咖啡」一個字都不共用，這裡就是配不起來，跨語言（latte／拿鐵）亦然。那正是底下那兩顆章存在的理由，不在這裡補同義詞表。規則由 FoodLibraryMatchTest 釘住 —— adb shell input text 只吃 ASCII，中文行為在模擬器上根本打不出來，只能靠單元測試驗。
不是設定裡的總開關，也不是讓模型自己判斷。理由很簡單：使用者在打字的當下就已經 知道自己要哪一種了 —— 他在食物前面加店名，就是想要官方資料；打「兩顆蛋」那種東西本來 就沒有官方標示可查，多等十秒只是浪費。這個判斷在使用者腦裡，不在模型那邊。
三條路都實際試過，兩條失敗：
| 試過的做法 | 結果 |
|---|---|
Gemini 搜尋 grounding（tools: [{google_search:{}}]） |
免費層的配額是 0，每一次文字辨識都變 429，整條路直接掛掉 |
| 讓模型自己下查詢（tool calling） | 不強制就不收斂（三輪查詢後仍未回傳結果）；強制之後它自己下的查詢反而撈到美規數字 |
| 自己先查、把正文接進 prompt（現行） | 拿到台灣官方頁的數字，而且模型仍然只收到一個普通請求 |
第二條的失敗是結構性的：多給一個工具就不能再強制 tool_choice，而那正是 OpenRouter
那條路鎖住 JSON 的唯一手段。這個題目的搜尋意圖是恆定的（永遠在問營養標示），
沒有需要模型推敲的餘地，放手讓它推敲反而弄丟穩定性。實驗留在 tool-calling-search
分支當紀錄，不合併。
搜尋來源選 Tavily 而不是 Brave：Brave 免費層回的是 SERP 片段，實測同一個查詢四筆裡 三筆在講麥克雞塊和薯條，唯一有數字的是 2018 年的新聞稿，而它的 AI 摘要要付費方案； Tavily 免費層回的就是清洗過的頁面正文。
糖、鈉、膳食纖維、飽和脂肪這四欄在 Gemini 那份是 required 但仍可為 null，
OpenRouter 那份維持選填。這是實測出來的，不是兩邊忘了同步。
選填等於給模型一個整個略過的藉口，改成必填之後 Gemini 那邊就填得出來了；
但同樣的改法在 OpenRouter 那個免費健康模型上，兩次都把鈉 1092.5 毫克換算成 1.092 公克
填進膳食纖維。逃不掉鍵之後它選了隨便找個欄位塞，而不是老實填 null —— 而
錯的數字比空白更糟：確認畫面只列出熱量與三大營養素，進階那四欄沒人看得到，
進去就是默默落地。詳細的追查過程見
issue #11。
這段算法最早是只看目標給一個固定倍率：維持一律 每公斤 1.7 g。問題有兩個。
一是那是運動員的數字。一般健康成人的建議是 0.8（RDA）到 1.2 g/kg，1.4–2.0 是給 有在認真訓練的人的區間，1.7 已經在那個區間的上緣。64 公斤、只想維持體重的人會算出 108 g —— 那得每天刻意安排才吃得到，實務上等於被推去喝高蛋白。
二是活動量那一欄形同白填：久坐和每週練五天的人，同一個目標下拿到一模一樣的數字。
現在每公斤幾克由活動量決定（久坐 1.0、輕度 1.2、中度 1.4、高 1.6、非常高 1.8），
減脂與增肌各再加 0.2、封頂 2.0，並且把這個數字顯示在結果裡。
BmrCalculatorTest 有一條專門釘「久坐與高活動量不能算出同一個數字」。
連帶的一件事：原本脂肪固定佔 25%、碳水吃剩下的差額，所以蛋白質一降，省下來的熱量 一克不剩全部跑到碳水（實測被推到 58.7%，建議範圍 50–65% 的上緣）。改成碳水固定 55%、 脂肪吃差額；蛋白質高到塞不下時讓位的是碳水，脂肪守住 20% 下限 —— 脂肪太低會影響 荷爾蒙與脂溶性維生素吸收。
同樣一件事有兩種寫法：把運動消耗從「今天吃了多少」裡扣掉，或是加到「今天可以吃多少」上。 前者比較好寫，但它改寫了使用者記的東西 —— 他明明吃了 1,800，畫面卻說 1,450。 紀錄是這支 app 唯一的事實來源，不能因為戴了手錶就變成另一個數字。
所以運動消耗只動目標那一側，而且全 app 只有一個 effectiveCalorieTarget()：
新增任何拿熱量去比目標的地方都得走它，否則就會出現今日頁與月曆對同一天有兩種說法。
健康連線裡拿得到的東西不只一種，早期的版本排了三段退路：活動消耗 → 總消耗扣掉基礎 代謝 → 步數換算。後兩段都已經移除，因為它們看起來像測量值，其實是估算值：
- 總消耗扣基礎代謝是拿兩個一千五百多的大數字相減，去換一個一百多的小數字。 三星寫進健康連線的總消耗含它自己算的靜態消耗，我們扣的是自己用 Mifflin 算的， 兩邊差幾個百分點，誤差就和答案同一個量級 —— 實測手錶記 153 大卡，這條路算出 39。 而且總消耗是從午夜累加上來的，要扣對就得引進「今天過了幾成」，於是同一天在不同 時刻讀會得到不同的數字。
- 步數換算是固定係數乘出來的猜測值，一旦和手錶實測混在同一個數字裡，使用者就 分不出哪天是量的、哪天是猜的。
現在只認「活動消耗」與「運動場次」這兩種本身就是活動量的資料，兩種都沒有就顯示
讀不到並講原因。步數照樣讀、照樣存進 daily_health_metrics 給報表用，只是不再
換算成大卡。
活動係數的定義本身就含運動 —— 這個 app 的選項寫的就是「輕度（每週運動 1–3 天）」。 所以「係數目標 ＋ 今天的運動」是同一批熱量算兩次：64 kg／159 cm 的人輕度係數是 2087， 再加一趟 45 分鐘的跑步（約 408）就變成 2495，對一個只想維持體重的人偏高得離譜。
所以打開「讀取運動消耗」之後，熱量的底會退到久坐基準（同一個人是 1821），運動由手錶 另外補。關掉就算回係數那個數字。兩者不並存。
補的時候預設只補一半。穿戴裝置估能量消耗是它最不準的一項——它沒有直接測氣體交換， 只能從動作與心率推，系統性回顧給的誤差從 9% 到 40% 以上都有，某些裝置的 MAPE 甚至破百。 營養師的普遍做法也是把活動量設低、運動熱量只回補 25–50%。同一個人跑 45 分鐘， 回補一半之後是 2025，而不是 2495。
最初的需求是「從相簿挑一張照片當圖示」，但 Android 沒有任何 API 讓 app 在執行時 換掉自己的桌面圖示：圖示是編譯進 APK 的資源，系統只認資源 ID。
唯一的官方作法是 activity-alias：manifest 裡事先放好幾個 alias、各自指定 icon，
執行時用 PackageManager.setComponentEnabledSetting 開一個、關其他。所以能選的就是
APK 裡事先放好的那幾款。
真正能用到相簿照片的另一條路是「釘一個帶自訂圖片的捷徑到桌面」（requestPinShortcut），
但那是多一顆圖示、原本那顆還在，所以沒有採用。（有些手機可以換任何 app 的圖示 ——
那是 Samsung One UI、Nova 這類桌面自己的功能，不是 app 給的。）
這個做法有一個代價：MainActivity 不能再帶 MAIN/LAUNCHER（兩邊都有，桌面就會出現兩顆），
所以從舊版更新上來時，之前釘在桌面的捷徑會失效 —— 它記的是 MainActivity 這個元件。
常吃頁離開搜尋框時同時有兩件事想發生：imePadding() 跟著鍵盤退場縮回去（整區往下沉），
以及剛剛收起來的說明文字要長回來。兩件事一起做的話畫面在同一段時間裡往兩個方向動，
讀起來就是彈一下；排成兩段之後是「先落地、再長出來」，那才讀得成一個動作。
第二段什麼時候開始，問 WindowInsets.ime 的 bottom 是不是 0，不自己數毫秒：
各家 IME 的退場長度不一樣（大約 200～300ms），寫死一個延遲在慢的機器上會提早搶拍、
在根本沒有鍵盤動畫的機器上則是乾等一段什麼都沒發生的空檔。
月曆報頭那個月份用的是借位：它兩側站著箭頭、做不成分頁器的一頁，所以改成讀分頁器的 即時位移自己位移，鄰月的字從旁邊補進來。純視覺，從頭到尾不碰分頁器自己的捲動狀態 —— 反過來做（拿即時值去驅動另一個分頁器的位置）正是今日頁那兩個換頁 bug 的共同根源。
不用 Material 成品容器就得自己承擔兩件事，兩者都曾經在深色模式下造成整段文字看不見。
LocalContentColor的預設值是純黑，只有 M3 的Surface會覆蓋它。本專案的畫面是Modifier.background()疊出來的，畫在Scaffold之外的覆蓋層（新增選單、Dialog）裡沒指定color的Text會一路吃到黑色 —— 淺色模式下黑字配米底剛好正確，所以只有深色模式會現形。現已於NutriLogTheme根部統一提供LocalContentColor = onSurface。- 遮罩用
scrim而非inverseSurface。inverseSurface的語意是「與目前主題相反的表面」，深色模式下它是亮色，拿來當遮罩會把背景刷亮、使面板成為畫面上最暗的一塊。scrim於兩套配色皆明確指定為Paper.Ink，永遠是壓暗。
完全替換所有 M3 預設外觀元件：
StampButton：墨色實心印章（主要確認動作）。成對的動作（匯出／匯入）維持相同形狀，靠退一階的深灰底色區分方向；次要動作用空心章，破壞性動作用空心朱紅章PillButton：圓角藥丸（就地確認、查詢）TextAction：純文字按鈕（次要切換）RoundKey：圓章按鍵（自製數字鍵盤、步進器）BallotRow/MealPicker：單選圓形圈選SquareCheck：複選方形打勾框NutriTextField：全封閉外框 + 3px 底部加重規線- 全自繪 24 格 1.6dp 圓端點
*Mark向量圖示，杜絕通用 Material 圖示造成的粗糙感。
GET https://world.openfoodfacts.org/api/v2/product/{barcode}.json
- 無需 API Key，請求需帶規範之 User-Agent。
- 每 IP 每分鐘限制 15 次，查詢結果自動寫入
cached_products本機快取。
POST https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
- API Key 走
x-goog-api-keyHTTP Header。 - 透過
responseSchema鎖定純 JSON 結構化輸出。 - 內建 5xx / 逾時自動指數退避重試 3 次。
- 不加搜尋 grounding（
tools: [{google_search:{}}]）：實測免費層的 grounding 配額是 0， 開了之後每一次文字辨識都變 429，而且那個 429 的 body 沒有QuotaFailure明細， 只能開關對照才分離得出來。
POST https://openrouter.ai/api/v1/chat/completions
- 文字辨識的另一家供應商，預設模型
inclusionai/ling-3.0-flash-sante:free。 - 用強制函式呼叫鎖 JSON（定義一個函式、參數就是那份 schema，再用
tool_choice強制呼叫）， 因為那個模型的supported_parameters裡沒有response_format。 回傳在choices[0].message.tool_calls[0].function.arguments，而那是字串包著的 JSON。 - 402 是餘額不足（免費模型也需要帳號裡有額度才跑得動），401 才是 key 的問題 —— Gemini 那邊沒有前者這種狀態。
- 換模型之前先查
openrouter.ai/api/v1/models，確認新模型的supported_parameters有tools。
POST https://api.tavily.com/search
- 「AI 查」按下去時才呼叫，免費層 1000 次/月。
- 不開
include_answer：那會回一段 AI 摘要，而摘要傾向給「約 500 至 550」這種跨地區區間； 自己的 prompt 讀官方表格比讀別人的摘要準。 max_results = 3、每筆正文截到 1500 字元；search_depth維持basic（理由見 issue #11）。- 失敗一律回
null不拋例外：它只是輔助，不該因為搜尋壞掉讓整條辨識失敗。
- 相依
androidx.health.connect:connect-client，釘在1.1.0-beta01：1.1.0 正式版要求 compileSdk 36 與 AGP ≥ 8.9.1，本專案是 35 / 8.7.3，升上去會在 AAR metadata 檢查失敗。 - 只讀全日活動消耗與運動場次，要用哪一種看手錶配戴方式；來源會顯示在明細面板上。
- 寫入使用
Metadata.manualEntry(clientRecordId, ...)，以nutrilog_<紀錄 id>作為 clientRecordId，同一筆紀錄重寫即為覆寫。 - 權限每次回到前景重查一次 —— 使用者隨時可以在系統設定收回，app 不會收到通知。
推動 v* 格式之 Git Tag 將自動觸發 GitHub Actions 進行正式 APK 編譯與 Release 建立：
git tag -a v1.10.0 -m "Release v1.10.0: 中文換成 jf open 粉圓"
git push origin v1.10.0版號由 Tag 動態注入，確保發佈檔名與內部版本號完全一致。
| 項目 | 規格值 |
|---|---|
| Kotlin / AGP / Gradle | 2.0.21 / 8.7.3 / 8.11.1 |
| minSdk / targetSdk / compileSdk | 26 / 35 / 35 |
| JDK | 17 |
| UI 框架 | Jetpack Compose (BOM 2024.10.01) + 自訂「紙與墨」元件庫 |
| 本地儲存 | Room 2.6.1 + DataStore Preferences 1.1.1 |
| 網路通訊 | OkHttp 4.12.0 + kotlinx-serialization 1.7.3 |
| 條碼辨識 | Google Play services Code Scanner 16.1.0 |
| 雲端備份 | Google Play services Auth 22.0.0（drive.file）+ WorkManager 2.10.0 |
| 健康連線 | androidx.health.connect connect-client 1.1.0-beta01 |
| 測試框架 | JUnit 4 + Kotlin Test |
| 內嵌字型 | jf open 粉圓 2.1（中文）+ Neucha（數字，已正規化側邊留白） |
| 發佈 APK 大小 | 約 14.1 MB（其中內嵌字型約 2.9 MB） |
| 應用權限 | android.permission.INTERNET |
- 🐛 回報問題：提交 Bug 或功能建議。
- 📓 看以前踩過的坑：已關閉的 issues 是當紀錄用的，不是待辦清單。每一篇都是「症狀 → 成因 → 修法」，包括猜錯的方向 —— 改到相關的地方之前先翻一下，有些看起來很合理的「簡化」前人已經試過並且壞過一次。
- 💡 提交 Pull Request：Fork 專案 → 建立分支 → 完成修改與驗證 → 提交 PR。
開發時請遵循 CLAUDE.md 規範：註解撰寫繁體中文說明決策原因、遵守無 M3 預設元件原則、修改 Room Entity 需提供 Migration 與版本升級。
NutriLog 採用 MIT License 授權。
- Open Food Facts —— 開放食品條碼資料庫。
- Google Gemini API —— 多模態影像與自然語言營養估算。
- Google Code Scanner —— 免相機權限之系統級條碼掃描模組。
- Neucha —— 手寫風格數字字型（OFL，Jovanny Lemonad）。
- jf open 粉圓 —— 台灣在地化圓體中文字型（OFL，justfont）。
- @waltwait —— 健康連線、身型計算與 AI 週報／月報的初版實作，以及「肥貓」這款圖示。