From 86aaef9a601854f542dc8a92524d6670e06cba36 Mon Sep 17 00:00:00 2001
From: WaterRain <109326062+CATMIAOZHI@users.noreply.github.com>
Date: Tue, 7 Jul 2026 00:27:31 +0000
Subject: [PATCH] docs: sync AGENTS.md and README.md for Room migration +
 refactors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AGENTS.md:
- Tech stack: DataStore → Room + DataStore
- UsageCache: DataStore JSON → Room DAO, auto-migration from old DataStore
- ChartSettingsStore: add StateFlow, remove runBlocking
- Data flow: insertAll persist/invalidateCache → Room DAO insert (IGNORE)
- RefreshBalanceUseCase: add retryOnTransientError note

README.md:
- Architecture diagram: UsageCache DataStore → Room
- Feature table: 内存缓存 → Room 数据库
- Dependency table: remove Jsoup, add Room
- Project structure: local/ updated with Room files
---
 AGENTS.md | 10 +++++-----
 README.md |  8 ++++----
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 57ca605..0d033d6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,7 @@ CommandCode Go 走 JSON API 抓取用量数据，Codex / ChatGPT Plus 通过 aut
 - MVVM + Repository + `RefreshBalanceUseCase`（单一 UseCase，按 ServiceType 分发）
 - Hilt + KSP（DI）
 - Retrofit 2 + OkHttp 4 + Kotlinx Serialization
-- DataStore（本地缓存）+ Android Keystore（凭据加密，AES-256 GCM）
+- Room（用量数据，indexed on workspaceId+timeCreated）+ DataStore（余额缓存/图表偏好）+ Android Keystore（凭据加密，AES-256 GCM）
 - `minSdk=31`（Android 12+）
 - `material3-window-size-class` — 平板自适应布局
 - WorkManager（计划中）
@@ -29,11 +29,11 @@ CommandCode Go 走 JSON API 抓取用量数据，Codex / ChatGPT Plus 通过 aut
 - ❌ OpenCode Zen / 小米 MiMo — 未实现
 
 **用量统计系统**：
-- ✅ `UsageCache`（DataStore，~3700 条记录）— 全量 JSON 序列化 + 内存缓存（`@Volatile cachedAll`），仅在写入后失效
+- ✅ `UsageCache`（Room，indexed on workspaceId+timeCreated）— DAO 查询替代全量 JSON 序列化；首次启动自动从旧 DataStore JSON 迁移
 - ✅ `SyncUsageUseCase`（OCGO）/ `SyncCommandCodeUsageUseCase`（CCGO） — 首次全量同步（cursor 翻页）、增量同步（逐页比对本地 ID 集合）
 - ✅ `UsageViewModel` — `loadStatsInternal()` 单次 `getRecords()`→ 内存聚合 Overview/ModelStats/DailyStats，所有重操作包在 `withContext(Dispatchers.Default)` 避免主线程卡顿
 - ✅ `UsageChartViewModel` — 图表粒度（5h/**12h(10min)**/24h/今天/昨天/7天/当月/自定义日/月/范围），模型多选，3 张 Canvas 图表；支持 **UTC+0/UTC+8 时区切换**（桶边界+标签双感知）；自定义日/月/范围保存 `LocalDate` 语义，切换 UTC 偏好时重新计算边界；**自动降级**（5h无数据→12h→7天→当月）
-- ✅ `ChartSettingsStore`（DataStore Preferences）— 持久化 UTC 偏好，下次进入自动恢复
+- ✅ `ChartSettingsStore`（DataStore Preferences + StateFlow）— 持久化 UTC 偏好，`useUtc8Flow` 异步读取（已移除 runBlocking）
 - ✅ `UsageDataViewModel` — 原始记录分页浏览（20条/页），支持时间+模型筛选，页码输入跳转
 - ✅ 全局刷新绑定 — Dashboard 下拉刷新 → `DashboardViewModel.refresh()` → `UsageViewModel.sync()`（增量）
 
@@ -147,7 +147,7 @@ export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-arm64
 
 ```
 DashboardViewModel.refresh()
-  → RefreshBalanceUseCase(service)
+  → RefreshBalanceUseCase(service) （retryOnTransientError: Network/5xx 指数退避重试 2 次）
     → DeepSeekRepository.fetchBalance()    / OpenCodeGoRepository.fetchBalance()
     → CommandCodeGoRepository.fetchBalance() / CodexRepository.fetchBalance()
     → OllamaRepository.fetchBalance()
@@ -157,7 +157,7 @@ DashboardViewModel.refresh()
 Dashboard 下拉刷新 → usageSyncTrigger++ → UsageViewModel.sync()
   → OCGO: SyncUsageUseCase.fullSync() / incrementalSync()
     → OpenCodeUsageRepository.fetchPage(cursor) 逐页抓取
-    → UsageCache.insertAll() → persist() → invalidateCache()
+    → UsageCache.insertAll() → Room DAO insert（IGNORE 策略，去重）
   → CCGO: SyncCommandCodeUsageUseCase.fullSync() / incrementalSync()
     → CommandCodeUsageRepository.fetchPage(cursor) 逐页抓取
   → UsageViewModel.loadStats() → getRecords() → 内存聚合
diff --git a/README.md b/README.md
index 8186ae8..1c483e4 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,7 @@ Android AI 余额与用量查询 APP —— 统一查看 DeepSeek、OpenCode Go
 | 🔄 **自动同步** | 首页下拉自动同步用量；无缓存时启动自动全量同步；CCGO 详情页支持手动清除并重新同步 |
 | 🌙 **深色模式** | 全局自适应 — App 内文字/图标/背景自动切换，小组件独立适配暗色布局 |
 | ➕ **一键添桌面** | APP 内点 + 直接添加小组件，不用去系统列表翻 |
-| ⚡ **内存缓存** | DataStore 全量 JSON 仅反序列化一次，后续操作零 IO |
+| ⚡ **Room 数据库** | 用量记录存 Room（indexed on workspaceId+timeCreated），DAO 查询替代全量 JSON 序列化；首次启动自动从旧 DataStore 迁移 |
 | 🎀 **雨晴粉主题** | Material Design 3 · 草莓粉 #FF85A2 · 樱粉 #FFD1DC |
 
 ---
@@ -83,7 +83,7 @@ Android AI 余额与用量查询 APP —— 统一查看 DeepSeek、OpenCode Go
 │  ┌────────────────────▼─────────────────────────┐ │
 │  │         本地存储                              │ │
 │  │  BalanceCache（DataStore）                    │ │
-│  │  UsageCache（DataStore + @Volatile 内存缓存） │ │
+│  │  UsageCache（Room，indexed on workspaceId+timeCreated） │ │
 │  │  CredentialRepository（Keystore AES-256 GCM） │ │
 │  └──────────────────────────────────────────────┘ │
 └──────────────────────────────────────────────────┘
@@ -98,7 +98,7 @@ Rainytoken/
 ├── app/src/main/java/com/rainy/token/
 │   ├── data/
 │   │   ├── cache/          # BalanceCache（DataStore）
-│   │   ├── local/          # UsageCache（DataStore + 内存缓存）、UsageRecord、ChartBucket
+│   │   ├── local/          # UsageCache（Room）、UsageRecordEntity、UsageDao、UsageDatabase、ChartBucket
 │   │   ├── remote/         # DeepSeekApi（Retrofit）+ OpenCodeGo 抓取 + UsageRepository
 │   │   └── repository/     # DeepSeek / OpenCodeGo / CommandCode / Codex / Ollama / Credential Repository
 │   ├── domain/
@@ -161,7 +161,7 @@ chmod +x ./setup_android_env.sh
 | `com.squareup.retrofit2:retrofit` | DeepSeek REST API |
 | `com.squareup.okhttp3:okhttp` | OpenCode Go 网页抓取 |
 | `org.jetbrains.kotlinx:kotlinx-serialization-json` | JSON 序列化 |
-| `org.jsoup:jsoup` | HTML 解析（已引入但实际未使用，HTML 解析全用正则） |
+| `androidx.room:room-runtime` | 用量数据本地数据库（Room） |
 | `androidx.datastore:datastore-preferences` | 本地缓存 |
 | `com.google.dagger:hilt-android` | 依赖注入 |
 | `com.google.devtools.ksp:symbol-processing-api` | KSP 注解处理 |