45 lines
2.3 KiB
Markdown
45 lines
2.3 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 页面;不直接调 Retrofit,只调 `SessionController` / `AppContainer` |
|
||
|
||
## 必须遵守的约定
|
||
|
||
- **会话状态只在 `SessionController` 里改**。UI 和 Service 都不得自行维护会话副本,否则会与服务端口径分叉。
|
||
- **计时不得用 tick 累加**。显示值一律走 `State.effectiveSeconds(nowMs)`,基准取服务端 `effectiveTime`,锚点取 `SystemClock.elapsedRealtime()`。
|
||
- **悬浮窗窗口标志不要随手改**:`FLAG_NOT_FOCUSABLE | FLAG_NOT_TOUCH_MODAL | FLAG_LAYOUT_NO_LIMITS` 三者缺一都会出问题(抢焦点 / 挡住下层 / 半隐藏被夹回屏幕内)。
|
||
- **不要在浮窗里做文本输入**。App 不在前台时系统不允许后台窗口弹键盘;需要输入时拉起 Activity。
|
||
- **对接后端先看部署环境的 OpenAPI**(`GET {baseUrl}/v3/api-docs`),不要假设源码与部署一致——两者已经分叉过一次。
|
||
|
||
## 后端
|
||
|
||
- dev:`https://lpt-dev.cat-shark.xyz/api`
|
||
- 认证:Sa-Token,token 放请求头 `satoken`(不用 Cookie)
|
||
- 只使用学习会话相关端点,**不碰 `review/*`**
|
||
|
||
## 提交规范
|
||
|
||
同 meta 仓库:简短中文,格式 `类型: 简述`,例如 `feat: 新增悬浮窗碎片录入`。
|