127 lines
7.2 KiB
Markdown
127 lines
7.2 KiB
Markdown
# lpt-android
|
||
|
||
> LPT 的 Android 客户端:**学习会话 + 系统级悬浮窗**。不含复习模块。
|
||
|
||
## 它解决什么
|
||
|
||
LPT 的学习计时原本只能在电脑浏览器里进行;而真实的学习场景经常是「手机/平板上看视频课,同时想记录学习时间」。浏览器做不到跨应用常驻,所以需要一个悬浮窗:
|
||
|
||
- 浮窗常驻在其他 App 之上,学习计时不因切走而中断。
|
||
- 不抢输入法焦点、不挡住下层 App 的触摸(`FLAG_NOT_FOCUSABLE | FLAG_NOT_TOUCH_MODAL`)。
|
||
- 12 秒无操作自动收成贴边小胶囊,点一下恢复;常态 80% 不透明,收起后 60%。
|
||
- 可在浮窗里直接记一条知识碎片(拉起轻量输入弹窗)。
|
||
|
||
## 功能范围
|
||
|
||
| 模块 | 内容 |
|
||
|------|------|
|
||
| 登录 | `POST /login` 拿 token,DataStore 持久化,OkHttp 拦截器注入 `satoken` 请求头 |
|
||
| 权限引导 | 悬浮窗权限 / 通知权限 / 电池优化白名单 / MIUI 自启动与后台弹出 |
|
||
| 任务列表 | `GET /tasks` |
|
||
| 学习会话 | 开始/继续、暂停、结束、误操作结束(零数据)、学习预期、知识碎片、结束报告三段 |
|
||
| 悬浮窗 | 前台服务(`specialUse`)托管,跨应用常驻;暂停/继续/结束/记碎片/半隐藏 |
|
||
| 设置 | 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`,附件每次覆盖)——本地不需要配签名环境。
|
||
|
||
## 构建与安装
|
||
|
||
```bash
|
||
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 安装」,手机端手动确认一次;或改用
|
||
```bash
|
||
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 异步覆盖。正确做法是装完等几秒再设:
|
||
```bash
|
||
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()`。
|
||
|
||
## 后端契约兼容(重要)
|
||
|
||
**dev 部署的后端比本地源码旧**,两者契约不同。客户端对二者都兼容(多发字段两边都会忽略):
|
||
|
||
| 接口 | 部署版(旧) | 本地源码(新) | 客户端做法 |
|
||
|------|--------------|----------------|-----------|
|
||
| `POST /report-fragments` | `{sessionNum, content}` | `{contextNum, content}` | 两个字段都发 |
|
||
| `POST .../study-sessions/ended` | `{content}`(单段,必填) | `{sessionSummary, expectationVerdict, freeSummary}` | 发 `content`(三段拼接)+ 三段字段 |
|
||
| 报告草稿 | `GET .../report-draft`(同步 AI) | `POST /ai/tasks`(异步) | 暂未接入,报告由用户手写 |
|
||
| `DELETE /report-fragments/{id}` | 不存在 | 存在 | 未使用 |
|
||
|
||
排查这类问题的可靠手段:直接拉部署环境的 OpenAPI —— `GET {baseUrl}/v3/api-docs`。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
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 页面 + FragmentInputActivity
|
||
└── util/Format.kt
|
||
```
|
||
|
||
## 已知限制
|
||
|
||
- 浮窗依赖悬浮窗权限,被系统回收后需要 App 进程还活着才能自动恢复(`START_STICKY` + 启动时对账)。
|
||
- 国内 OEM 的省电策略可能杀掉前台服务,需要用户手动白名单。
|
||
- 报告草稿的 AI 生成未接入(旧后端同步接口慢、新后端是异步任务,两者差异大),报告目前由用户手写。
|
||
- 学习录音(系统混音采集)未做,属于二期。
|