cat-shark d71bfe2139 fix: 补齐设置保存/登录的中间层在途守卫,并去重同文案提示
- 真机双击验证发现:设置页「保存」两次点击都会真的写一遍(DataStore 写太快,UI 标记在第二次点击前就已复位),会看到两条一样的提示
- AppContainer 增加 authInFlight / baseUrlSaving 在途标记,重复调用直接忽略
- snackbar 增加同文案 1.5 秒去重,连点不再堆两条相同提示
2026-11-08 22:44:28 +08:00

lpt-android

LPT 的 Android 客户端:学习会话 + 系统级悬浮窗。不含复习模块。

它解决什么

LPT 的学习计时原本只能在电脑浏览器里进行;而真实的学习场景经常是「手机/平板上看视频课,同时想记录学习时间」。浏览器做不到跨应用常驻,所以需要一个悬浮窗:

  • 浮窗常驻在其他 App 之上,学习计时不因切走而中断。
  • 不抢输入法焦点、不挡住下层 App 的触摸(FLAG_NOT_FOCUSABLE | FLAG_NOT_TOUCH_MODAL)。
  • 12 秒无操作自动收成贴边小胶囊,点一下恢复;常态 80% 不透明,收起后约 60%。
  • 可在浮窗里直接记一条知识碎片(拉起轻量输入弹窗)。

浮窗的职责被刻意压到最小:只展示倒计时、记碎片、暂停/继续。其余动作(结束会话、写报告、改预期、看历史)都在 App 页面内完成。

功能范围

模块 内容
登录 POST /login 拿 token,DataStore 持久化,OkHttp 拦截器注入 satoken 请求头;服务端返回 401 时自动退出登录并在登录页说明原因
权限引导 悬浮窗权限 / 通知权限 / 电池优化白名单 / MIUI 自启动与后台弹出
任务列表 GET /tasks,每个任务带「报告」入口;有进行中的会话时顶部带「回到会话」入口
操作反馈 保存预期、保存 API 地址、开始/暂停/结束、记碎片等动作都有 snackbar 提示(成功短、失败长);所有发请求的按钮在途时禁用,防连点重复提交
学习会话 开始/继续、暂停、结束、误操作结束(零数据)、学习预期(必填)、知识碎片、结束报告三段
会话冲突出口 开始新任务前先查其他任务上的未结束会话;有冲突时只给「前往继续 / 取消」,结束与误操作结束必须回到那个会话的页面里自己做
悬浮窗 前台服务(specialUse)托管,跨应用常驻;只做三件事:展示倒计时 / 记一条碎片 / 暂停继续
学习报告 结束会话时取 AI(不可用则规则降级)三段草稿作为编辑起点;任务页可查看历史报告与本次碎片
设置 API 地址可切(默认 dev)

不做:复习(review/*)、思维导图、回忆对比、学习录音。

技术栈

  • Kotlin + Jetpack Compose(Material 3),单 module
  • 网络:Retrofit + OkHttp + kotlinx.serialization
  • 本地:DataStore Preferences(token / baseUrl / username)
  • 悬浮窗:经典 View + WindowManager + TYPE_APPLICATION_OVERLAY(不用 Compose-in-overlay,避开 lifecycle owner 问题)
  • 无 Hilt / Room / Navigation-Compose,手写依赖容器,减少构建面

版本组合(已验证可构建)

组件 版本
AGP 8.13.2
Gradle 8.14.6
Kotlin 2.3.21
Compose BOM 2026.03.01(compose 1.10.6)
compileSdk / targetSdk 36 / 36
minSdk 26
JDK 17

⚠️ Compose BOM ≥ 2026.04(compose 1.11+)要求 AGP 9.1+ 与 compileSdk 37,配 AGP 8.13.2 会报 requires Android Gradle plugin 9.1.0 or higher。要么整体升 AGP 9,要么锁在 2026.03.01。

分支与环境

分支 环境 默认 API 地址 用途
dev 开发 https://lpt-dev.cat-shark.xyz/api 日常开发与验证
master 生产 https://lpt.cat-shark.xyz/api 给真实使用打的生产包

两个分支只差 ApiClient.DEFAULT_BASE_URL 一行;安装后仍可在「设置」页临时改地址(调试用)。

打包走 Gitea Actions 的 lpt-android Build(手动触发,选 dev 或 prod):先校验「分支 ↔ 默认地址」是否匹配,再在容器里构建,最后把 APK 传到该环境的滚动 Release(android-dev / android-prod,附件每次覆盖)——本地不需要配签名环境。

构建与安装

export JAVA_HOME=$HOME/opt/jdk
export ANDROID_HOME=$HOME/opt/android-sdk
export PATH=$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$HOME/opt/gradle-8.14.6/bin:$PATH

gradle :app:assembleDebug

国内直连 Google Maven 很慢,settings.gradle.kts 已配置阿里云镜像。

MIUI / 红米注意

  1. adb install 会被拦(INSTALL_FAILED_USER_RESTRICTED):需在开发者选项里开「USB 调试(安全设置)/ 通过 USB 安装」,手机端手动确认一次;或改用
    adb push app/build/outputs/apk/debug/app-debug.apk /data/local/tmp/lpt.apk
    adb shell pm install -r -t /data/local/tmp/lpt.apk
    
  2. 重装会重置悬浮窗权限(appops 变 ignore),且装完立刻 appops set 会被 MIUI 异步覆盖。正确做法是装完等几秒再设:
    adb shell appops set com.catshark.lpt SYSTEM_ALERT_WINDOW allow
    adb shell appops get com.catshark.lpt SYSTEM_ALERT_WINDOW   # 应为 allow
    
  3. MIUI 还会限制后台启动与后台弹窗,需手动放行「自启动」和「其他权限 → 后台弹出界面」,省电策略设「无限制」——App 的「权限」页有入口。

关键实现决定

  • 计时口径:显示值 = 服务端 effectiveTime(基准)+ 以 SystemClock.elapsedRealtime() 为锚点的增量。不用 tick 累加,因此进程被杀、Doze、锁屏都不会让时间失真;恢复时用服务端 lastStartTime 重新对锚。
  • 窗口必须带 FLAG_LAYOUT_NO_LIMITS:否则 WindowManager 会把越界位置夹回屏幕内,半隐藏会失效(实测 mAttrs x=-651 但 mFrame 仍是 [0,...])。
  • 浮窗内不做文本输入:App 不在前台时,系统不允许后台窗口弹软键盘——实测浮窗的 EditText 能拿到输入连接(mServedView=EditText),但 IME 窗口 mViewVisibility=0x8(GONE)。因此「记碎片」改为拉起 FragmentInputActivity(带 SYSTEM_ALERT_WINDOW 的 App 有后台启动 Activity 豁免),并给它独立 taskAffinity,保存后回到用户原本在用的 App。
  • 服务自恢复:App 启动时 GET /study-sessions/active 对账,恢复未结束的会话;只要状态里有活跃会话就拉起前台服务,权限是后来才授予的也会每秒兜底重试 overlay.show()。进程被系统拉起时(START_STICKY)服务自己会补一次对账,只有「对过账且确实没有会话」才停服务,否则会先自杀而没人再拉起来。
  • 浮窗职责固定为三件事:展示倒计时、记一条碎片、暂停/继续。结束、写报告、改预期、看历史都必须在 App 页面内完成(详见 AGENTS.md)。

后端契约兼容(重要)

dev 部署的后端比本地源码旧,两者契约不同。客户端对二者都兼容(多发字段两边都会忽略):

接口 部署版(旧) 本地源码(新) 客户端做法
POST /report-fragments {sessionNum, content} {contextNum, content} 两个字段都发
POST .../study-sessions/ended {content}(单段,必填) {sessionSummary, expectationVerdict, freeSummary} 发 content(三段拼接)+ 三段字段
报告草稿 GET .../report-draft(同步 AI) POST /ai/tasks(REPORT_DRAFT 异步任务) 走新契约:提交后轮询 GET /ai/tasks/{taskNum},失败不阻塞手写
DELETE /report-fragments/{id} 不存在 存在 未使用

排查这类问题的可靠手段:直接拉部署环境的 OpenAPI —— GET {baseUrl}/v3/api-docs。

目录结构

app/src/main/java/com/catshark/lpt/
├── LptApp.kt                 Application + 手写依赖容器
├── MainActivity.kt           导航(任务列表 / 会话 / 报告 / 权限 / 设置)+ 会话冲突出口弹窗
├── data/                     Models / LptApi / ApiClient / TokenStore / LptRepository
├── session/SessionController.kt   会话状态机(Application 级单例,StateFlow)
├── service/
│   ├── StudySessionService.kt     前台服务 + 通知 + 调度浮窗与输入弹窗
│   └── OverlayView.kt             悬浮窗(只做倒计时 / 记碎片 / 暂停继续)
├── ui/                       Compose 页面(含 ReportsScreen)+ FragmentInputActivity
└── util/Format.kt

已知限制

  • 浮窗依赖悬浮窗权限;进程被杀后靠 START_STICKY + 启动时对账恢复。实测 MIUI(Android 12)不会重启被杀的进程:进程没了浮窗就没了,需要用户打开一次 App 才恢复(打开后的对账是可靠的)。
  • 国内 OEM 的省电策略可能杀掉前台服务,需要用户手动白名单。
  • 报告第四部分「按归属分组的碎片」由复习模块实时聚合,本客户端按仓库边界不访问复习端点,报告页只列本次会话产生的碎片。
  • 没有自动化测试;.gitea/workflows/build.yml 只构建不跑测试。
  • 学习录音(系统混音采集)未做,属于二期。
S
Description
No description provided
Readme
309 KiB
2026-11-08 23:09:03 +08:00
Languages
Kotlin 98.4%
Dockerfile 1.6%