- SessionController 新增在途标记 expectationSaving / fragmentAdding,入口早退 + 按钮禁用(文案改「保存中…」「记录中…」) - 记碎片改为「成功才清空输入、失败保留」;浮窗拉起的碎片输入页同样防连点,且写入成功才关弹窗 - 设置页保存 API 地址期间禁用按钮;登录按钮补显式重入保护 - 任务列表开始会话在途时禁用卡片(文案改「开始中…」),不再能连点重复开始
72 lines
6.0 KiB
Markdown
72 lines
6.0 KiB
Markdown
# lpt-android 代理协作规范
|
||
|
||
> LPT 的 Android 客户端:学习会话 + 系统级悬浮窗,不含复习。
|
||
|
||
## 规则与技能位置
|
||
|
||
- 通用规则(跨仓库):meta 仓库 `.agents/roles/`(提交规范见其中的 `commit-convention.md`)。
|
||
- 本仓库暂无专属 `roles/` 与 `skills/`;出现 Android 专属约定时再建。
|
||
|
||
## 技术栈
|
||
|
||
- Kotlin 2.3.21 + Jetpack Compose(Material 3)
|
||
- AGP 8.13.2 / Gradle 8.14.6 / JDK 17 / compileSdk 36 / minSdk 26
|
||
- Retrofit + OkHttp + kotlinx.serialization;DataStore Preferences
|
||
- 悬浮窗用经典 View + `WindowManager`,**不用 Compose-in-overlay**
|
||
|
||
> Compose BOM 锁 `2026.03.01`。升到 ≥ 2026.04 会要求 AGP 9.1+ / compileSdk 37,见 README。
|
||
|
||
## 目录职责
|
||
|
||
| 目录 | 职责 |
|
||
|------|------|
|
||
| `data/` | 网络与本地存储;`LptApi` 是唯一接口定义处,`LptRepository` 负责 `code != 200 → ApiException` |
|
||
| `session/` | `SessionController` 是会话状态机唯一入口;UI 与服务都只读它的 `StateFlow` |
|
||
| `service/` | 前台服务与悬浮窗;不承载业务逻辑,只渲染状态并转发动作 |
|
||
| `ui/` | Compose 页面(含 `ReportsScreen`);不直接调 Retrofit,只调 `SessionController` / `AppContainer` |
|
||
|
||
## 必须遵守的约定
|
||
|
||
- **会话状态只在 `SessionController` 里改**。UI 和 Service 都不得自行维护会话副本,否则会与服务端口径分叉。
|
||
- **悬浮窗只做三件事:展示倒计时、记一条碎片、暂停/继续**。结束会话、写报告、改预期、看历史一律在 App 页面内完成;不要往浮窗里加按钮或面板(它常驻在其他 App 之上,每多一个控件都是常态干扰)。
|
||
- **开始新任务前必须先处理未结束会话**。`startOrContinue` 先查 `GET /study-sessions/active?excludeTaskNum=`,有冲突就只设置 `State.conflict`(UI 只给「前往继续 / 取消」);不得绕过这一步直接开始,也不得在列表页代替用户结束或放弃那个会话——结束与误操作结束必须在会话页里由用户自己做。
|
||
- **写操作必须有可见反馈**。保存预期、保存 API 地址、开始/暂停/结束、记碎片等动作都要给 snackbar 提示(失败文案要写清楚为什么);不要只靠页面底部一行静态文案。
|
||
- **发请求的按钮必须防连点**。在中间层(`SessionController` / `AppContainer`)加“在途”标记并在入口早退,同时把按钮 `enabled` 绑到该标记(文案可改「保存中…」);涉及写入的动作要“成功才清输入、失败保留输入”,不能让一次连点变成两条碎片。
|
||
- **学习预期不可为空**。`State.expectationRequired` 为真时用不可关闭的弹窗挡住(只能填预期或误操作结束)。
|
||
- **前台服务停之前要确认“确实没有会话”**。对账是异步的,`State.resolved` 为 false 时看到的空状态是“还不知道”,不能据此 `stopSelf()`。
|
||
- **计时不得用 tick 累加**。显示值一律走 `State.effectiveSeconds(nowMs)`,基准取服务端 `effectiveTime`,锚点取 `SystemClock.elapsedRealtime()`。
|
||
- **悬浮窗窗口标志不要随手改**:`FLAG_NOT_FOCUSABLE | FLAG_NOT_TOUCH_MODAL | FLAG_LAYOUT_NO_LIMITS` 三者缺一都会出问题(抢焦点 / 挡住下层 / 半隐藏被夹回屏幕内)。
|
||
- **不要在浮窗里做文本输入**。App 不在前台时系统不允许后台窗口弹键盘;需要输入时拉起 Activity。
|
||
- **`CircularProgressIndicator` 必须用 `Modifier.size(...)`,不要用 `Modifier.height(...)`**。它不是按容器自适应缩放的:只给高度会得到非方形画布,旋转中心会偏、圆环会被压扁。
|
||
- **对接后端先看部署环境的 OpenAPI**(`GET {baseUrl}/v3/api-docs`),不要假设源码与部署一致——两者已经分叉过一次。
|
||
|
||
## 后端
|
||
|
||
- dev:`https://lpt-dev.cat-shark.xyz/api`
|
||
- 认证:Sa-Token,token 放请求头 `satoken`(不用 Cookie)
|
||
- 只使用学习会话相关端点(含报告与 `POST /ai/tasks` 的 `REPORT_DRAFT`),**不碰复习端点**(`review` 前缀)
|
||
|
||
## 分支与发布
|
||
|
||
与 `lpt-be` / `lpt-fe` / `lpt-ai` 同规则:**一个分支对一个环境**(本仓库没有服务端部署,环境差异落在“默认 API 地址”上)。
|
||
|
||
| 分支 | 环境 | 默认 API 地址 |
|
||
|------|------|----------------|
|
||
| `dev` | 开发 | `https://lpt-dev.cat-shark.xyz/api` |
|
||
| `master` | 生产 | `https://lpt.cat-shark.xyz/api` |
|
||
|
||
- 两个分支的代码**只允许差 `ApiClient.DEFAULT_BASE_URL` 这一行**(其余全部一致)。改这一行时必须确认自己在哪个分支上,改完只提本分支。
|
||
- 不要跨分支合并:`dev` 的功能要上生产时,只把常规代码改动同步过去,并保持 master 的默认地址不变。
|
||
- 构建在 Gitea 手动触发 `.gitea/workflows/build.yml`(dev/prod 二选一),不需要签本地环境:
|
||
1. 校验「分支 ↔ 环境」(从 dev 发 prod 直接被拒);
|
||
2. 校验代码里的 `DEFAULT_BASE_URL` 是否与本环境一致,不一致直接失败;
|
||
3. 容器内构建 APK(`ci/Dockerfile` 固定 JDK 17 / cmdline-tools / android-36),产物上传到该环境的**滚动 Release** 并在日志打印 sha256。
|
||
- APK 不入 Git(`.gitignore` 已忽略 `*.apk`),分发走 Release 附件:
|
||
`https://git.cat-shark.xyz/cat-shark/lpt-android/releases/tag/android-dev`(生产为 `android-prod`),每次构建覆盖同名附件。
|
||
- **本仓库的流水线不使用任何 `uses:` action**,也不得依赖 `python3` / `jq`(runner 上都没有,历史报错:`Cannot find: node in PATH`、`python3: command not found`)。
|
||
归档改用 Gitea 的 Release API + `curl`,只用 `grep`/`sed`/`cut` 解析 JSON,凭据用 Gitea 为每个 job 自动注入的 `secrets.GITEA_TOKEN`(权限由 workflow 的 `permissions: contents: write` 声明)。新增步骤前先确认工具在 runner 上存在(脚本开头有 `command -v` 预检)。
|
||
|
||
## 提交规范
|
||
|
||
同 meta 仓库:简短中文,格式 `类型: 简述`,例如 `feat: 新增悬浮窗碎片录入`。
|