项目概览
参考工程是一套 面向 IoT / 设备管理 SaaS 的原生 Android 客户端基础，而不是「只有一两个页面的 demo」。
它把登录与组织选择、设备与命令、遥测与告警、设置与诊断、离线缓存与鉴权刷新串在同一套模块图里。
核心设计
- 单 Activity + 多 feature 模块：导航与装配在
app，业务屏在feature/* - 离线优先（offline-first）：UI 观察 Room / Flow；写操作与刷新走 Repository
- 依赖单向：
app → feature → core；feature 互不依赖 - 实现强调边界清晰、可测、可发布
默认产品形态是 模块化单体 App（modular app）：
- 一个安装包承载完整产品路径
- feature 边界仍然清晰
- 不需要一上来拆「多 App / 动态特性交付」
一句话：先稳住模块与数据边界，真有独立交付压力再拆分。
设计原则
| 原则 | 含义 |
|---|---|
| Now-in-Android 风格 | Compose + M3 + Hilt + UDF + Repository |
| Boundary first | feature 不互相 import；UI 不碰 Room/Retrofit |
| Offline first | 有缓存表时以本地观察为主，再刷新远端 |
| Explicit first | 状态用不可变 UiState + StateFlow |
| Small changes first | 无明确理由不升级 AGP/Kotlin/Compose BOM |
技术硬约束（务必遵守）
| 用途 | 使用 | 不要用 |
|---|---|---|
| UI | Jetpack Compose + Material 3 | 在新屏上堆 XML View 为主路径 |
| 依赖注入 | Hilt 构造注入 | 在 Composable 里手动 new Repository |
| 数据入口 | Repository（core:data） | UI/ViewModel 直接调 DAO / Retrofit / DataStore |
| 列表分页 | Paging 3（合适时） | ViewModel 里手搓游标 + 无限叠加列表当默认 |
| JSON | kotlinx.serialization（新 DTO） | 无必要地混入反射型解析到 UI |
规则摘要：
- Composable 只渲染状态、上抛事件
- ViewModel 做状态编排，不写重业务细节
- 持久化与网络细节关在
core/database、core/network、core/datastore - 不要为了「再包一层」而造平行架构
技术栈快照
以参考仓库 gradle/libs.versions.toml 为准（版本会演进）：
| 类别 | 典型选型 |
|---|---|
| 语言 / 构建 | Kotlin、AGP、Version Catalog |
| UI | Compose BOM、Material 3、Navigation Compose |
| DI | Hilt + KSP |
| 异步 | Coroutines、Flow、StateFlow |
| 本地 | Room、DataStore Preferences |
| 网络 | OkHttp、Retrofit、kotlinx.serialization converter |
| 测试 | JUnit、Truth、Turbine、Compose UI Test |
当前能力范围（概览）
参考仓库已覆盖（随版本演进，以该仓库 README 为准），例如：
- 注册 / 登录 / 会话刷新、组织选择与切换
- 设备列表与详情、创建设备（一次性 secret）、启停与批量操作
- 命令下发与事件、车队视图相关能力
- 遥测查询、告警规则、自动化、通知路由
- 厂商集成、设置（含 API 端点覆盖）、诊断与 Admin 入口
- Room 缓存：看板、设备、组织、部分规则与系统版本等
默认 API 端点：
https://api-dev.alinode.com/
本地后端需显式覆盖（见 本地开发），避免误连生产/联调环境习惯被改坏。
本教程怎么对应仓库
| 本站文档 | 仓库中的对应物 |
|---|---|
| 架构与目录 | docs/ARCHITECTURE.md、settings.gradle.kts |
| 模块形态 | app/、feature/*、core/*、AGENTS.md |
| 本地运行 | ./gradlew :app:assembleDebug、-PapiBaseUrl |
| 网络与缓存 | core/network、core/database、core/data |
| 安全 | docs/SECURITY_NOTES.md |
| 发布 | docs/RELEASE_CHECKLIST.md、signing.properties.example |
下一步：环境准备。