架构与目录

系统定位

该仓库是设备管理 / IoT SaaS 的 原生 Android 客户端内核：

默认路径：单 App、多 feature 模块、离线优先数据层
可选演进：在真实压力出现时再拆独立交付单元（业务边界已在 feature 内）

优先：可维护、可测、可发布，而不是最大化模块数量。

仓库布局（核心）

app/                      # MainActivity、应用图、主题、发布日志策略
core/
  model/                  # 领域模型（纯 Kotlin）
  common/                 # AppResult 等通用类型
  designsystem/           # Material 3 主题
  ui/                     # 共享 Compose 组件
  domain/                 # 领域侧扩展点（按仓库实际）
  data/                   # Repository、离线协调、mapper
  database/               # Room entity / DAO / Database
  datastore/              # 会话、Admin Token、端点、偏好
  network/                # Retrofit、DTO、拦截器、API
feature/
  auth/ devices/ commands/ telemetry/ ...
docs/                     # ARCHITECTURE、SECURITY、RELEASE…
gradle/libs.versions.toml
settings.gradle.kts

业务 feature 列表会随产品增长（alerts、automation、vendor、workforce…），以 settings.gradle.kts 为准。

依赖方向（硬边界）

:app
  → :feature:*
  → :core:*

:feature:*
  → :core:data, :core:ui, :core:designsystem, :core:model, …

:core:data
  → :core:database, :core:network, :core:datastore, :core:model, :core:common

:core:network / database / datastore
  → 不依赖 app、不依赖 feature

要点：

feature 之间不直接依赖
core 不依赖 feature；若 app 屏要嵌 feature UI，从 feature 暴露 Composable，由 app 组合
不要为了省事 implementation(project(":feature:other"))

运行时图（导航）

应用大致处于三种图之一：

状态	图
未登录	Auth
已登录但未选组织	Organization picker
已登录且已选组织	Main

Main 常见底部 Tab（以仓库实现为准）：

Dashboard（Home）
Devices
Commands
More（遥测、告警、自动化、通知、集成、设置、诊断、组织切换、退出等）

Admin 相关入口仅对具备管理员能力的用户可见。

状态流（UDF）

Repository (Flow / suspend)
    → ViewModel (StateFlow<UiState>)
        → Composable (collectAsStateWithLifecycle)
            → 用户事件回到 ViewModel

UI 不可变状态向下、事件向上
使用 collectAsStateWithLifecycle()，避免无效收集
业务逻辑优先落在 Repository / 合适的 domain，而不是 Composable

数据层直觉

默认 offline-first：

UI 观察 Room 支持的缓存（observe* → Flow）
进入屏或下拉时 Repository refresh* / 写操作走 Retrofit
网络 DTO → domain model → Room entity（mapper 分目录）
有缓存的屏以 Room 为当前展示真相源

Token、Admin Token、运行时 API 端点在 DataStore，不进 Room。

网络层直觉

Retrofit + OkHttp
JSON：kotlinx.serialization 单例 Json（ignoreUnknownKeys 等见实现）
拦截器职责拆分清晰：
- AuthInterceptor：Authorization: Bearer …
- AdminTokenInterceptor：仅 /internal/admin/* 加 X-Admin-Token
- TokenAuthenticator：401 单飞刷新
- DynamicBaseUrlInterceptor：Settings / 构建参数覆盖的端点

与 Go 后端的对应关系

Android	Go base（概念）
`feature/*`	用户可感知的产品切片（屏 + VM）
`core:data` repositories	application 用例的客户端侧编排
`core:network` DTO/API	HTTP 契约 / OpenAPI
`core:model`	跨层稳定模型（非 wire DTO）
DataStore session	服务端会话在客户端的投影

两端边界文档见 Go 仓库 OpenAPI 与 Android docs/API_COVERAGE.md。

下一步：模块怎么写。

系统定位​

仓库布局（核心）​

依赖方向（硬边界）​

运行时图（导航）​

状态流（UDF）​

数据层直觉​

网络层直觉​

与 Go 后端的对应关系​