Files
cat-shark c894025d83 feat: 同步 dev 的会话冲突、报告闭环与真机修复到生产包
内容与 dev 完全一致,只有 ApiClient.DEFAULT_BASE_URL 指向生产环境(流水线第一步会逐字校验这一行)。

包含:会话冲突出口(只留前往继续/取消)、学习预期必填、服务端收敛提示、报告草稿与报告查看、
悬浮窗只做计时/记碎片/暂停继续、前台服务自恢复竞态修复、加载动画变形修复、动作反馈与防连点。
2026-11-08 22:57:25 +08:00

6.0 KiB
Raw Permalink Blame History

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: 新增悬浮窗碎片录入。