Files
lpt-android/README.md
T
cat-shark 267570dcab fix: 修复加载动画变形、补动作反馈,并收紧冲突弹窗
- CircularProgressIndicator 误用 Modifier.height() 会拿到非方形画布,圆环被压扁且旋转中心偏;四处统一改为 Modifier.size()
- 保存预期 / 保存 API 地址 / 开始暂停结束 / 记碎片都有 snackbar 反馈(成功短、失败长),不再只靠页面底部静态文案
- API 地址改为先校验再写入(不合法保留旧地址并提示),登录页同样校验;启动时遇到坏地址退回默认,不再抛异常
- 冲突弹窗只保留「前往继续 / 取消」:结束与误操作结束必须回到会话页面里用户自己做,列表页不再提供放弃/结束入口
2026-11-08 22:21:45 +08:00

134 lines
8.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`,附件每次覆盖)——本地不需要配签名环境。
## 构建与安装
```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()`。进程被系统拉起时(`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`。
## 目录结构
```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 页面(含 ReportsScreen)+ FragmentInputActivity
└── util/Format.kt
```
## 已知限制
- 浮窗依赖悬浮窗权限;进程被杀后靠 `START_STICKY` + 启动时对账恢复。实测 **MIUI(Android 12)不会重启被杀的进程**:进程没了浮窗就没了,需要用户打开一次 App 才恢复(打开后的对账是可靠的)。
- 国内 OEM 的省电策略可能杀掉前台服务,需要用户手动白名单。
- 报告第四部分「按归属分组的碎片」由复习模块实时聚合,本客户端按仓库边界不访问复习端点,报告页只列本次会话产生的碎片。
- 没有自动化测试;`.gitea/workflows/build.yml` 只构建不跑测试。
- 学习录音(系统混音采集)未做,属于二期。