本地开发
以下命令均在参考工程 android/base 根目录执行。
1. 编译与安装 Debug
./gradlew :app:assembleDebug
./gradlew :app:installDebug
或在 Android Studio 选 app 配置，点 Run。
验证 Kotlin 编译（改动导航/装配时常用的最小命令）：
./gradlew :app:compileDebugKotlin
产物位置示例：
app/build/outputs/apk/debug/app-debug.apk
2. API 端点
默认
https://api-dev.alinode.com/
core:network 会规范化 BuildConfig.API_BASE_URL；必须以 / 结尾。
构建时覆盖（本地后端）
./gradlew :app:installDebug -PapiBaseUrl=http://10.0.2.2:8080/
| 场景 | base URL 示例 |
|---|---|
| 模拟器 → 宿主机 monolith | http://10.0.2.2:8080/ |
| 真机 → 电脑局域网 | http://192.168.1.10:8080/ |
| 正式联调云 | 保持默认或团队指定环境 |
运行时覆盖（Settings）
应用内 Settings 可持久化端点到 DataStore，并支持重置回 https://api-dev.alinode.com/。
调试结束后记得重置，避免「只有你这台机子连错环境」。
3. Admin Token
管理页走公共路径形态的 /internal/admin/*，请求头需要 X-Admin-Token。
在 Settings 中配置；诊断页只显示「是否已配置」，不展示 token 明文。
4. 常用 Gradle 任务
| 任务 | 用途 |
|---|---|
./gradlew :app:compileDebugKotlin | 最快编译反馈 |
./gradlew :app:assembleDebug | Debug APK |
./gradlew :app:assembleRelease | Release APK（见发布文档） |
./gradlew :app:testDebugUnitTest | App 单元测试 |
./gradlew :feature:devices:testDebugUnitTest | 单模块测试 |
./gradlew :app:lintDebug | Lint |
./gradlew test | 更广的单元测试 |
./gradlew :app:connectedDebugAndroidTest | 真机/模拟器 UI smoke |
原则：优先跑最窄任务。 全量 build 只在需要时使用。
当前工程没有 demoDebug / prodDebug 一类 flavor（除非你后来加了）。不要用 NIA 文档里过时的 flavor 任务名。
5. Instrumentation 测试注意
维护中的设备 UI smoke 在 :app：
./gradlew :app:connectedDebugAndroidTest
不要把根任务 ./gradlew connectedDebugAndroidTest 当发布门禁：库模块往往没有独立 androidTest，可能去装空测试 APK 并因 runner / 厂商安装策略失败——与 App UI 质量无关。
若出现 INSTALL_FAILED_USER_RESTRICTED：
- 打开开发者选项
- 开启 USB 调试、USB 安装（及「经 USB 安装」类开关）
- 排除厂商安全中心拦截
- 重插线确认授权后重跑
6. 日志与调试
- Debug：可有较高层诊断；OkHttp 网络日志多为
BASIC - 仍避免把 access/refresh/admin token、设备 secret 打到 logcat
- 使用 Android Studio Logcat 过滤包名 / tag
清除应用数据可重置 DataStore 会话与端点覆盖（等价卸载重装的一部分效果）。
7. 与后端联调检查表
- 后端
readyz/ 健康检查通过 - App 端点指向正确主机（模拟器用
10.0.2.2） - 能注册或登录测试账号
- 能创建/选择组织
- 设备列表可刷新；断网时缓存列表仍可见（有 Room 覆盖的屏）
- 401 后能刷新会话或回到登录图
8. 源码目录约定
Android 模块使用 AGP 管理的 src/*/java 放 Kotlin 源文件（参考工程约定）。
纯 JVM 模块可用 src/main/kotlin。不要随意改回旧兼容开关。
下一步：网络与数据层。