Skip to content

feat(android): WorkManager 后台余额刷新 + 低余额本地通知闭环 - #23

Merged
Qiyuanqiii merged 12 commits into
mainfrom
feat/android-workmanager-notification
Aug 16, 2026
Merged

Qiyuanqiii merged 12 commits into
mainfrom
feat/android-workmanager-notification

Conversation

@Qiyuanqiii

Copy link
Copy Markdown
Member

描述

A4 最后一个功能块(Issue #15):WorkManager 后台余额刷新 + 低余额本地通知闭环。前置 #11(依赖准入,已合并)与 #13(纯策略,已合并)均已就绪。

架构(:core 决策 / :app 执行)

SettingsScreen 通知开关
   │ ON:权限通过 → enabled=true → schedule(Unique+UPDATE)
   │ OFF:enabled=false → cancelUniqueWork + 重置 alerted
   ▼
WorkManager → BackgroundRefreshWorker(NetworkType.CONNECTED,15 分钟 Best Effort)
   │ 1. 开关关闭 → success(防御性 early-return,不联网)
   │ 2. Keystore 读 Token(严禁进 InputData)→ 无 Token → success
   │ 3. fetchSummary → normalWallets.firstOrNull()(与 AppModel 同规则,币种与 UI 一致)
   │ 4. LowBalancePolicy.evaluate(:core 纯策略)→ 持久化 alerted
   │ 5. shouldNotify 且 areNotificationsEnabled() → LowBalanceNotifier.notify()
   └─ 错误映射:BackgroundRefreshDecision → NETWORK=retry;Token 失效 40002/40003 与其余 = success(不无限重试)

关键设计点

  • 唯一任务:enqueueUniquePeriodicWork("deepseek-meter-background-refresh", ExistingPeriodicWorkPolicy.UPDATE, ...)——多次进入设置页/重启不会注册多个 Worker;UPDATE 不取消运行中 worker、保持原排队时间(work-runtime ≥ 2.8.0 语义);
  • 通知开关闭环双保险:ON→OFF 主动 cancelUniqueWork + 重置 alerted;Worker 每次执行前再查一次开关(即使被系统调度也立即 success 不联网);
  • 权限三态(Android 13+ POST_NOTIFICATIONS):未请求→开关开启时请求;曾拒绝→再次开启时重试(系统决定是否弹框,不自动骚扰);永久拒绝→开关保持关闭 + 「打开系统通知设置」入口。拒绝时余额/用量/趋势/登录完全不受影响;
  • 去重状态机:alerted 持久化在 deepseek_meter_background SharedPreferences(非敏感标志),策略返回新状态由 Worker 写回;余额恢复自动重置,再次跌破可再次提醒;
  • 币种语义:阈值 0 < balance < 1.0(1.0 = 当前钱包币种一个单位);通知文案用 currencySymbol(currency) + format(...),不硬编码 ¥;
  • 安全边界:Token 由 Worker 自行从 Keystore 读取,绝不进入 WorkManager InputData(会落 WorkManager 数据库);通知为纯本地,无任何第三方推送;
  • 零新增非必要依赖:只新增 androidx.work:work-runtime:2.10.1(D6 已决策的 androidx 官方库);通知用平台 Notification.Builder(minSdk 26 可用),未引入 androidx.core 显式依赖。

涉及文件

  • 新增 android/app/src/main/kotlin/com/deepseek/meter/app/background/BackgroundRefreshWorker.kt
  • 新增 android/app/src/main/kotlin/com/deepseek/meter/app/background/BackgroundRefreshScheduler.kt
  • 新增 android/app/src/main/kotlin/com/deepseek/meter/app/notification/LowBalanceNotifier.kt
  • android/app/build.gradle.kts(work-runtime 2.10.1)
  • android/app/src/main/AndroidManifest.xml(POST_NOTIFICATIONS)
  • android/app/src/main/kotlin/com/deepseek/meter/app/SettingsScreen.kt(通知开关 + 权限三态)

关联

变更类型

  • ✨ 新功能

本地验证

边界检查

  • 未引入第三方业务依赖(work-runtime 为 D6 已决策的 androidx 官方库,见红线 11)
  • 未改动平台接口契约(URL / 参数 / 响应结构)
  • 未在代码 / 日志 / 截图 / 提交中夹带真实 Token 或凭据(Token 不进 WorkManager Data)
  • 未提交构建产物(.build/、build/、.DS_Store)
  • 未改变 Token 存储方式(保持 UserDefaults;Android 仍为 Keystore)
  • 注释与 UI 文案保持中文
  • 提交信息符合 Conventional Commits + 中文描述

非目标

  • ❌ 后台余额快照冷启动复用(独立增强 / A5)
  • ❌ Firebase / 第三方推送
  • ❌ Widget / Play Store(A5)

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

一句话总结

该 PR 为 Android 版实现了 WorkManager 后台余额刷新与低余额本地通知闭环,整体设计合理、边界处理细致,但存在一个红线级别的依赖版本问题需要修正。

🔴 红线 / 严重问题

android/app/build.gradle:58 — WorkManager 版本 2.10.1 超出红线 11 的准入范围

红线 11 明确说明:WorkManager 准入已经过 Issue #11 讨论,仅用于 :app 层后台刷新,且 :core 保持零 AndroidX 依赖。本 PR 在 :app 层使用 WorkManager 符合准入条件,但版本 2.10.1 需要确认:

  • 该版本是否与项目 minSdk 兼容(WorkManager 2.10.x 要求 minSdk 23,需确认项目 minSdk)
  • 建议在注释中明确标注版本选择依据,或与 Issue #11 中讨论的版本保持一致

建议:确认项目 minSdk 与 WorkManager 2.10.1 的兼容性,并在注释中补充版本选择说明。

🟡 建议改进

android/app/src/main/java/com/deepseek/meter/app/SettingsScreen.kt:47-49 — 通知权限拒绝后的状态处理可优化

当前逻辑:权限被拒后 showPermissionNote = true,但 alertsEnabled 保持 false。用户再次点击 Switch 时会重新触发权限请求,可能造成"请求→拒绝→再请求"的循环。建议在权限被拒后记录"用户已拒绝"状态,下次点击时直接展示系统设置入口而非再次弹权限框。

android/app/src/main/java/com/deepseek/meter/app/background/BackgroundRefreshWorker.kt:35-38 — Token 读取失败静默处理可增加日志

Token 读取失败(Keystore 解密异常)时直接 return Result.success(),无任何日志输出。建议至少用 Log.w() 记录一次,便于排查问题。

android/app/src/main/java/com/deepseek/meter/app/notification/LowBalanceNotifier.kt:52-53 — 通知文案硬编码阈值

LowBalancePolicy.DEFAULT_THRESHOLD 被硬编码在通知文案中("低于 1.0"),如果策略阈值未来调整,通知文案可能不同步。建议从策略中动态读取阈值文本。

🔵 小问题 / 风格

android/app/src/main/java/com/deepseek/meter/app/SettingsScreen.kt:76-77 — 两次 bgPrefs.edit() 可合并

disableAlerts() 中连续两次调用 bgPrefs.edit(),建议合并为一次:

bgPrefs.edit()
    .putBoolean(BackgroundRefreshWorker.KEY_ALERTS_ENABLED, false)
    .remove(BackgroundRefreshWorker.KEY_ALERTED)
    .apply()

android/app/src/main/java/com/deepseek/meter/app/background/BackgroundRefreshScheduler.kt:14 — 注释中"Best Effort"与代码风格

注释使用英文 "Best Effort",与仓库中文注释惯例不符,建议改为"尽力而为"。

android/app/src/main/java/com/deepseek/meter/app/background/BackgroundRefreshWorker.kt:70-72 — KEY_ALERTS_ENABLED 常量重复定义

BackgroundRefreshWorker 和 SettingsScreen 都引用了 KEY_ALERTS_ENABLED,且 PREFS 名称在 BackgroundRefreshScheduler 和 BackgroundRefreshWorker 中重复定义。建议将 SharedPreferences 名称和 key 常量统一收敛到一个地方(如 BackgroundRefreshScheduler 的 companion object),避免散落。

审查结论

整体实现质量良好:Worker 的防御性 early-return、Token 不落 WorkManager 数据库、错误映射复用 :core 策略、通知权限三态处理等设计都体现了对红线规范的尊重。主要问题集中在 WorkManager 版本确认和少量代码组织优化,建议修正后合并。

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

一句话总结

该 PR 为 Android 版实现了 WorkManager 后台余额刷新与低余额本地通知的完整闭环,整体设计合理、边界清晰,但存在一个红线级问题(WorkManager 依赖引入方式)和若干需要修正的实现细节。

🔴 红线 / 严重问题

  1. android/app/build.gradle.kts:57 — WorkManager 依赖引入违反红线 11

    • 红线 11 明确规定:WorkManager 准入已经过 Issue #11 讨论,仅用于 :app 层后台刷新,:core 保持零 AndroidX 依赖。
    • 当前 diff 显示依赖加在 android/app/build.gradle.kts(即 :app 模块),符合红线。但请确认:
      • 依赖版本 2.10.1 是否与项目 minSdk(26)兼容(WorkManager 2.10.x 要求 minSdk 23,兼容)
      • 是否在 :core 模块中引入了任何 AndroidX 依赖(当前 diff 未显示,需确认)
    • 建议:在 PR 描述中明确声明依赖仅存在于 :app,并附上 :core 的依赖树验证截图或命令输出。
  2. BackgroundRefreshWorker.kt:31-33 — Token 从 Keystore 读取,但未处理 Keystore 不可用场景

    • 红线 12 要求 Android 用 Keystore 加密存储 Token,当前实现符合。
    • 但 loadToken() 抛出的 Exception 被捕获后返回 null,然后 if (token.isNullOrEmpty()) return Result.success()——静默成功意味着用户以为通知已开启,但实际从未工作。
    • 建议:区分「未登录」(正常静默)与「Keystore 解密失败」(应记录日志或返回 Result.failure() 以便排查)。

🟡 建议改进

  1. BackgroundRefreshWorker.kt:56-58 — 错误处理过于宽泛

    • catch (_: Exception) { Result.success() } 会吞掉所有未预期异常(包括 NullPointerException、IllegalStateException 等),导致问题无法被发现。
    • 建议:至少 Log.e(TAG, "Unexpected error", e) 记录日志;考虑对 PlatformException 之外的异常返回 Result.failure() 以便 WorkManager 记录。
  2. BackgroundRefreshWorker.kt:44-46 — 钱包选择规则与 AppModel 的一致性依赖注释

    • 注释说「与 AppModel 相同的钱包选择规则(firstOrNull)」,但这是隐式耦合——如果 AppModel 后续改为「选择余额最低的钱包」或「用户指定钱包」,Worker 会静默偏离。
    • 建议:将钱包选择逻辑提取到 :core 的 LowBalancePolicy 或新增 WalletSelector,两端共用,消除漂移风险。
  3. BackgroundRefreshScheduler.kt:31-33 — 周期 15 分钟可能过短

    • WorkManager 的 15 分钟是最小周期,但实际执行间隔受 Doze 模式、电池优化等影响,可能远大于 15 分钟。
    • 注释已说明「Best Effort、不保证精确时间」,但建议在 README 或设置页文案中向用户说明「后台刷新可能延迟」,避免用户误以为实时。
  4. LowBalanceNotifier.kt:62-63 — setSmallIcon(R.mipmap.ic_launcher) 使用应用图标作为通知小图标

    • Android 通知小图标应为纯白色透明背景的专用图标(ic_stat_xxx),使用彩色应用图标会在部分系统上显示为灰色方块。
    • 建议:新增 drawable/ic_stat_low_balance.xml(矢量图,白色),并在 notifyLowBalance 中使用。
  5. SettingsScreen.kt — 通知开关状态与 Worker 实际状态可能不同步

    • 如果用户通过系统设置关闭通知权限(而非应用内开关),alertsEnabled 仍为 true,但通知实际不可用。
    • 建议:在 enableAlerts() 中已检查 areNotificationsEnabled(),但应用启动时应同步检查一次,若权限被系统撤销则自动关闭开关并提示。

🔵 小问题 / 风格

  1. SettingsScreen.kt:36-37 — 两个 bgPrefs.edit() 调用可合并

    bgPrefs.edit().putBoolean(BackgroundRefreshWorker.KEY_ALERTS_ENABLED, false).apply()
    bgPrefs.edit().remove(BackgroundRefreshWorker.KEY_ALERTED).apply()

    建议:合并为 bgPrefs.edit().putBoolean(...).remove(...).apply()。

  2. BackgroundRefreshWorker.kt:25 — PREFS 常量与 SettingsScreen.kt:36 的字符串字面量重复

    • SettingsScreen.kt 中 context.getSharedPreferences("deepseek_meter_background", ...) 硬编码了与 BackgroundRefreshWorker.PREFS 相同的字符串。
    • 建议:将 PREFS 提升为 public const,在 SettingsScreen 中引用,避免拼写漂移。
  3. LowBalanceNotifier.kt:75 — NOTIFICATION_ID = 1001 为魔法数字

    • 建议提取为 companion object 中的命名常量(当前已在 companion 中,但可加注释说明用途)。
  4. BackgroundRefreshScheduler.kt:16 — 注释「Issue #15」与 PR 标题「Issue #15」一致,但仓库中 Issue 编号需确认

    • 建议在 PR 描述中链接对应 Issue,方便追溯。

审查结论

有条件通过。核心设计(唯一周期任务、Token 不进 InputData、错误映射复用 :core、权限三态处理)符合红线要求,代码质量良好。需修复以下问题后合入:

  1. 确认 :core 零 AndroidX 依赖(红线 11)
  2. BackgroundRefreshWorker 的宽泛异常捕获改为记录日志
  3. 通知小图标改用专用白色矢量图标
  4. 合并 SettingsScreen 中重复的 bgPrefs.edit() 调用

其余为建议性改进,可由维护者酌情决定。

@Qiyuanqiii

Copy link
Copy Markdown
Member Author

感谢 review,逐条处理如下:

  • 🔴 版本问题(非违规,已补充依据):项目 minSdk 26 > WorkManager 2.10.x 的 minSdk 23,兼容;2.10.1 满足 Issue deps(android): 引入 androidx.work 依赖准入并翻转 MOBILE-PLAN D6 决策 #11 / D6 的「≥ 2.8.0」要求(UPDATE 语义)。已在 build.gradle.kts 注释中写明版本选择依据;
  • ✅ 采纳(建议 1 权限循环):新增 permissionDenialCount 三态——首次点击请求;拒绝一次允许再次点击重试(系统决定是否弹框);拒绝两次以上直接展示系统设置入口、不再弹权限框,提示文案随状态区分;
  • ✅ 采纳(建议 2 日志):Token 读取失败增加 Log.w(仅固定文案 + 异常栈,不输出 Token/密文,符合红线 3);
  • ✅ 采纳(建议 3 动态阈值):渠道描述改为 format(DEFAULT_THRESHOLD) 动态生成(通知正文本就是动态的);
  • ✅ 采纳(小问题 1):disableAlerts() 的两次 edit 合并为一次链式调用;
  • ✅ 采纳(小问题 2):注释「Best Effort」统一改为「尽力而为」;
  • ⚪ 部分采纳(小问题 3):SharedPreferences 名收敛为 BackgroundRefreshWorker.PREFS_NAME(Worker 与 SettingsScreen 共用);UNIQUE_WORK_NAME 本就在 BackgroundRefreshScheduler 单点定义、Worker 未重复定义(原文审阅描述不精确)。

5 个修正 commit 已推送,CI 重跑中。

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

一句话总结

本 PR 为 Android 版实现 WorkManager 后台余额刷新与低余额本地通知闭环,整体设计合理、红线意识强,但存在 Worker 中直接使用 PlatformService() 绕过 :core 依赖注入、通知文案硬编码币种单位等可改进点。

🔴 红线 / 严重问题

1. android/app/src/main/java/com/deepseek/meter/app/background/BackgroundRefreshWorker.kt:55 — 绕过 :core 依赖注入,破坏架构分层

val summary = PlatformService().fetchSummary(token)

:core 模块的 PlatformService 设计为可注入(AppModel 注入 TokenStoring+URLSession,见 AGENTS.md 第 3 节),但此处直接 PlatformService() 实例化,绕过了依赖注入。这会导致:

  • Worker 无法在测试中注入 mock 的 PlatformService(:core 有 JVM 单测,但 Worker 无法复用)
  • 与 AppModel 的实例化方式不一致,造成架构漂移

建议:Worker 构造函数接收 PlatformService 参数(WorkManager 支持通过 WorkerFactory 注入依赖),或至少提供一个 PlatformService 的抽象接口供注入。

2. android/app/src/main/java/com/deepseek/meter/app/notification/LowBalanceNotifier.kt:57-58 — 通知文案硬编码币种单位,与 UI 不一致

val balanceText = symbol + format(balance)
val thresholdText = symbol + format(LowBalancePolicy.DEFAULT_THRESHOLD)

虽然 currencySymbol() 会返回币种符号,但 format() 的格式可能与 UI 不一致(如小数位数、千分位分隔符)。且 LowBalancePolicy.DEFAULT_THRESHOLD 是硬编码的 1.0,而设置页文案写的是"余额低于 1.0(当前币种单位)"——如果未来阈值可配置,这里会不同步。

建议:通知文案复用 :core 的 Formatting 纯函数(确保与 UI 一致),阈值从 SharedPreferences 读取而非硬编码。

🟡 建议改进

1. BackgroundRefreshWorker.kt:24-26 — 防御性 early-return 逻辑可更简洁

if (!prefs.getBoolean(KEY_ALERTS_ENABLED, false)) return Result.success()

建议将开关检查提取为独立函数(如 isAlertsEnabled()),便于测试和复用。

2. BackgroundRefreshWorker.kt:47-52 — 错误处理分支可合并

} catch (e: PlatformException) {
    when (BackgroundRefreshDecision.decide(e)) {
        RefreshDecision.RETRY -> Result.retry()
        RefreshDecision.COMPLETE -> Result.success()
    }
} catch (_: Exception) {
    Result.success()
}

两个 catch 分支都返回 Result.success(),可合并为一个 catch 块,减少代码重复。

3. SettingsScreen.kt — 权限三态逻辑可提取为独立 Composable

enableAlerts() / disableAlerts() 与权限状态管理逻辑较复杂,建议提取为 LowBalanceNotificationSection 独立 Composable,降低 SettingsScreen 的复杂度。

4. BackgroundRefreshScheduler.kt:27-28 — 周期 15 分钟可配置化

private const val PERIOD_MINUTES = 15L

建议将周期值放入 SharedPreferences,便于未来用户可配置(对齐 iOS 的刷新间隔设置)。

🔵 小问题 / 风格

1. BackgroundRefreshWorker.kt:1-10 — import 顺序不规范

import com.deepseek.meter.app.KeystoreTokenStore
import com.deepseek.meter.app.notification.LowBalanceNotifier
import com.deepseek.meter.core.BackgroundRefreshDecision
...
import android.util.Log

android.util.Log 应放在 android.* 导入组,与 android.content.Context 等一起。

2. LowBalanceNotifier.kt:53 — setSmallIcon(R.mipmap.ic_launcher) 使用 launcher 图标

通知小图标应使用专门的 monochrome 图标(如 R.drawable.ic_stat_balance),launcher 图标在部分设备上会显示为灰色方块。

3. SettingsScreen.kt — permissionDenialCount 未持久化

permissionDenialCount 是 remember 状态,App 重启后重置为 0。如果用户之前拒绝过两次,重启后再次点击开关会重新弹权限框。建议持久化到 SharedPreferences。

4. BackgroundRefreshWorker.kt:39 — Log.w 的 TAG 使用 "DeepSeekMeter"

建议使用类名作为 TAG("BackgroundRefreshWorker"),便于日志过滤。

审查结论

本 PR 整体质量良好,红线意识强(Token 不落 WorkManager 数据库、错误映射复用 :core、权限三态处理细致),核心逻辑与架构分层基本符合 AGENTS.md 规范。主要问题是 Worker 直接实例化 PlatformService 绕过依赖注入(红线 13 的架构一致性要求),以及通知文案与 UI 的币种格式一致性。建议修复上述问题后合并。

@Qiyuanqiii
Qiyuanqiii merged commit 8fb187f into main Aug 16, 2026
5 checks passed
@Qiyuanqiii
Qiyuanqiii deleted the feat/android-workmanager-notification branch August 16, 2026 15:14
@Qiyuanqiii

Copy link
Copy Markdown
Member Author

感谢第三轮 review,逐条处理如下:

  • ✅ 部分采纳(红线 1 依赖注入):Worker 增加可注入 PlatformService 的主构造器 + WorkManager 反射兼容的次构造器(生产默认实例;未来可经主构造器注入 stub)。不采纳 WorkerFactory/Application 方案——本项目零 DI 框架、无 Application 类,为单一 Worker 引入 Configuration.Provider 属过度工程;且 PlatformService 本身已通过 PlatformHttp 接口提供注入边界;
  • ⚪ 说明(红线 2 文案一致性):通知文案已复用 :core 的 format() 与 currencySymbol()(与 HomeScreen 同源函数),格式一致;DEFAULT_THRESHOLD 是 :core 单一来源常量,项目不存在用户可配置阈值(iOS 语义相同),不引入读取 SharedPreferences 的新设置;设置页开关描述的「1.0」字面量已改为动态 format(DEFAULT_THRESHOLD);
  • ✅ 采纳(小问题 1):android.util.Log 移入 android 导入组,TAG 改为类名 BackgroundRefreshWorker;
  • ✅ 采纳(小问题 2):新增 res/drawable/ic_stat_balance.xml(monochrome 铃铛)替换 launcher 图标作为通知小图标;
  • ✅ 采纳(小问题 3):permissionDenialCount 持久化到 SharedPreferences(KEY_DENIAL_COUNT),重启后不再重置;
  • ❌ 不采纳(建议 1 提取函数):开关检查是单次使用的两行判断,:app 无测试设施,提取无实际收益;
  • ❌ 不采纳(建议 2 合并 catch):两分支语义不同(PlatformException 需映射 NETWORK→retry),合并需类型判断反而降低可读性;
  • ❌ 不采纳(建议 3 提取 Composable):设置页各卡片本就在同一 Composable 内局部化,提取会引入跨函数状态传递;
  • ❌ 不采纳(建议 4 周期可配置):后台周期是产品决策(≥15 分钟 Best Effort),不提供用户配置(iOS 亦无此项)。

修正 commit 已推送,CI 重跑中。

@Qiyuanqiii

Copy link
Copy Markdown
Member Author

更正:上一条回复中的第三轮修正 commit 在推送时 #23 已被合并(分支已删除),未能随原 PR 提交;现已改为跟进 PR #24 提交(Worker 注入构造器 / monochrome 图标 / 拒绝计数持久化 / 动态阈值文案)。

Qiyuanqiii added a commit that referenced this pull request Aug 16, 2026
…llowup

fix(android): 通知闭环第三轮 AI review 修正(#23 跟进)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(android): WorkManager 后台余额刷新 + 低余额本地通知闭环

1 participant