109 lines
10 KiB
Markdown
109 lines
10 KiB
Markdown
# Android项目全局上下文文档
|
||
## 1. 项目概况
|
||
语言：Kotlin、少量 Java 本地库代码
|
||
架构：Jetpack Compose 单 Activity UI，未形成标准 MVVM；当前主要通过 Composable 局部状态、StateFlow 全局 Manager、SharedPreferences 持久化驱动界面
|
||
技术栈：AndroidX、Jetpack Compose、Material3、Haze 毛玻璃、OkHttp、Gson、ZXing、Google Play Services Location、LeakCanary、Android Instrumentation Test
|
||
Gradle/SDK版本：Android Gradle Plugin 8.9.1，Kotlin 2.1.0，Compose BOM 2024.10.00，compileSdk 36，targetSdk 36，minSdk 33，Java/Kotlin JVM 1.8
|
||
项目作用：智能家居控制面板应用，提供登录、房间管理、设备控制展示、场景、自动化、设置、背景壁纸、多语言、天气展示，并预留 CAN/MQTT 设备柜通信能力
|
||
模块：settings.gradle.kts 当前仅 include :app；仓库内存在 blurview Android Library 源码和 test/BlurView-master 示例/测试目录，但未接入当前主工程构建
|
||
|
||
## 2. 包结构与模块职责
|
||
com.example.smarthome：应用入口层
|
||
包含 SmartHomeApp、MainActivity、MainActivityCompose、MainActivityHaze、MainActivityAlternative。生产入口是 MainActivity，负责初始化语言/用户管理器、隐藏系统栏、挂载 activity_main.xml 中的 ComposeView 并渲染 AppRoot。
|
||
|
||
com.example.smarthome.data：数据、状态和服务层
|
||
UserManager 管理登录状态、用户信息、手机号验证码模拟登录和用户资料持久化。
|
||
LanguageManager 管理多语言枚举、翻译字典、语言持久化和切换语言后的应用重启。
|
||
BackgroundManager 管理背景壁纸列表、当前背景 StateFlow 和持久化。
|
||
WeatherService 使用定位、HTTP 天气接口、缓存和模拟兜底获取天气。
|
||
DeviceManager 聚合 MQTT 与 CAN 服务，向 UI 暴露设备控制统一入口。
|
||
MqttService.kt 定义 MQTT 常量、实体、接口和模拟实现。
|
||
CanService.kt 定义 CAN 常量、命令、实体、接口和模拟实现。
|
||
|
||
com.example.smarthome.ui：Compose UI 层
|
||
MainScaffold 是主界面核心，承载控制台、房间内容、设备卡片、空调/灯光/图表、顶部栏、导航相关组件。
|
||
LoginScreen、PhoneLoginScreen 提供微信扫码模拟登录和手机号验证码登录。
|
||
SettingsScreen 提供设置、语言、背景、房间管理、退出登录。
|
||
RoomDialog 提供添加/编辑/删除房间弹窗。
|
||
SceneScreen 管理场景开关。
|
||
AutomationScreen 管理自动化列表增删改状态。
|
||
SecurityScreen 管理安防状态展示与本地开关。
|
||
StatisticsScreen 展示静态能耗统计。
|
||
SmartHomeScreen、HomeScreen、Neumorph*、LiquidIndicator 是备用/实验性界面或通用视觉组件。
|
||
Previews 提供多尺寸 Compose 预览。
|
||
|
||
com.example.smarthome.ui.theme：主题层
|
||
SmartHomeTheme 使用 Material3 darkColorScheme，当前为固定深色主题。
|
||
|
||
eightbitlab.com.blurview：本地 BlurView 库源码
|
||
包含 BlurView、BlurController、PreDrawBlurController、RenderScriptBlur、RenderNodeBlurController 等传统 View 毛玻璃实现；当前未被 :app 依赖。
|
||
|
||
## 3. 分层与数据流
|
||
启动流程：MainActivity.onCreate -> LanguageManager.init(context) -> UserManager.init(context) -> 隐藏状态栏/导航栏 -> ComposeView.setContent -> SmartHomeTheme -> AppRoot。
|
||
|
||
登录数据流：AppRoot collect UserManager.isLoggedIn。未登录显示 LoginScreen；微信模拟登录调用 UserManager.login，手机号登录调用 UserManager.sendVerifyCode、verifyCode、loginWithPhone；登录成功后 UserManager.isLoggedIn 变为 true，自动切换到 MainContent。
|
||
|
||
主界面数据流：MainContent 从 smart_home_prefs.rooms 加载房间列表，使用 Compose remember/mutableStateOf 保存 selectedRoom、selectedNavItem、rooms，通过回调传给 MainScaffold。房间增删改由 saveRooms 写入 SharedPreferences 后更新 Compose 状态。
|
||
|
||
导航数据流：MainScaffold 根据 selectedNavItem 分发页面：0 控制台、1 场景、2 自动化、3 设置。SecurityScreen、StatisticsScreen 和部分导航组件已存在，但当前主 switch 未接入对应页面。
|
||
|
||
控制台数据流：DashboardContent -> RoomSelector -> RoomContent。总览房间显示环境、安全健康、模式、灯光、所有设备；具体房间显示空调卡、状态图、灯光行、设备网格。多数设备/图表数据为 UI 局部状态或静态模拟数据。
|
||
|
||
设置数据流：SettingsContent -> SettingsContentList。语言通过 LanguageManager.currentLanguage collect，切换语言写入 language_prefs 并重启应用；背景通过 BackgroundManager.selectedBackground collect，切换背景写入 background_prefs；退出登录调用 UserManager.logout。
|
||
|
||
场景/自动化/安防数据流：SceneScreen 使用 SharedPreferences("scenes") 保存场景激活状态；AutomationScreen 使用 SharedPreferences("automations").automation_list 和 Gson 保存自动化列表；SecurityScreen 使用 smart_home_prefs.security_armed 保存安防开关。
|
||
|
||
设备通信数据流：UI 可通过 rememberDeviceManager() 获取 DeviceManager。DeviceManager.initialize 打开 CAN 串口，并在 MQTT 参数完整时初始化/连接 MQTT；业务方法调用 ICanService 发送开门、上电、LED、查询等命令；CAN 回调进入 handleCanResponse，必要时触发后续 CAN 查询或 MQTT 上报。当前 CAN/MQTT 均是模拟实现，真实客户端代码以 TODO 注释保留。
|
||
|
||
线程规则：Compose 状态更新主要在主线程组合环境内完成；网络天气请求在 WeatherService.getWeather 中通过 withContext(Dispatchers.IO) 执行；DeviceManager 使用 CoroutineScope(SupervisorJob() + Dispatchers.IO) 初始化 CAN/MQTT；CAN/MQTT 的 MutableStateFlow 可跨线程更新，但新增真实硬件/网络回调时需注意线程切换和生命周期释放。
|
||
|
||
## 4. 核心基类
|
||
当前项目没有自定义 BaseActivity、BaseFragment、BaseViewModel、Repository 基类。
|
||
Activity 基类使用系统/AndroidX 类：MainActivity、MainActivityCompose、MainActivityHaze 继承 ComponentActivity；MainActivityAlternative 继承 AppCompatActivity。
|
||
全局状态封装以 singleton object/class manager 为主：UserManager、LanguageManager、BackgroundManager、WeatherService、DeviceManager、MqttServiceImpl、CanServiceImpl。
|
||
|
||
## 5. 现有通用封装
|
||
网络：WeatherService 使用 OkHttp 访问 7timer、wttr.in、ip-api；LoginScreen 使用 HttpURLConnection 预留微信扫码登录接口；MqttServiceImpl 预留真实 MQTT 客户端接入点但当前只模拟连接和发布日志。
|
||
本地存储：广泛使用 SharedPreferences，包括 user_prefs、users_database、language_prefs、background_prefs、smart_home_prefs、scenes、automations、mqtt_prefs。
|
||
状态封装：使用 MutableStateFlow/StateFlow 暴露登录、用户、语言、背景、MQTT 连接、CAN 连接、最后 CAN 响应、当前设备操作等状态。
|
||
工具方法：tr(key) 多语言快捷函数；rememberSelectedBackground()、rememberDeviceManager()、rememberMqttConnectionState()、rememberCanConnectionState() Compose 便捷函数；Context.getMqttService()、Context.getCanService() 扩展；generateQRCode 使用 ZXing 生成二维码；Context.findActivity() 用于从 Context 查找 Activity。
|
||
UI 通用组件：BackgroundSelector、LanguageSelectDialog、EditRoomsDialog、AddRoomDialog、CustomSwitch、GradientButton、CustomSlider、LightSlider、BlurGlassCard、FloatingBottomNav、SideNavRail、NeumorphButton、LiquidIndicator 等。
|
||
|
||
## 6. 开发约束
|
||
- 最小改动，禁止随意重构稳定代码
|
||
- 遵守分层架构，不跨层调用
|
||
- 优先复用现有代码，不重复造轮子
|
||
- 沿用项目现有第三方方案
|
||
- 当前没有标准 ViewModel/Repository 层；新增功能应优先沿用现有 Manager + StateFlow + Compose 状态方式，除非明确要求架构升级
|
||
- 修改房间、登录、语言、背景等功能时，应复用现有 SharedPreferences key 和 Manager，不要引入新的重复存储
|
||
- 修改设备通信时，应通过 DeviceManager、IMqttService、ICanService 接口扩展，不要让 UI 直接拼 CAN 帧或 MQTT topic
|
||
- 修改 UI 时优先复用 MainScaffold.kt、SettingsScreen.kt、RoomDialog.kt 中已有组件和视觉风格
|
||
- 注意 SecurityScreen、StatisticsScreen 当前未接入生产导航 switch，接入前需确认导航索引设计
|
||
- 注意 UiAdaptationTest 引用了当前源码中不存在的 ControlPanel，测试维护前需先确认目标组件
|
||
|
||
## 7. 核心实体与全局常量
|
||
核心实体：
|
||
UserManager.UserInfo：用户 ID、手机号、昵称、头像、注册/登录时间、性别、生日、邮箱、地址。
|
||
BackgroundOption：背景 id、名称、资源、缩略图、描述、是否深色。
|
||
WeatherInfo：温度、天气、湿度、空气质量、AQI、城市。
|
||
DoorInfo：格口/柜子/设备状态、接口、电压、SN、PVD、PRO、MFG、电量、维修状态。
|
||
DeviceEvent：借还/丢失等设备事件上报字段。
|
||
CanMessage、CanResponse：CAN 命令和响应数据。
|
||
Scene：场景 id、名称、描述、图标、渐变、激活状态。
|
||
Automation：自动化 id、名称、触发条件、动作、启用状态。
|
||
SecurityEvent：安全事件标题、时间、类型、描述。
|
||
Device：UI 设备卡片名称、副标题、图标、开关状态。
|
||
ScanStatusResult、ScanStatus：扫码登录状态。
|
||
|
||
全局常量：
|
||
LoginConfig：BASE_URL、GET_QR_CODE、CHECK_STATUS、POLL_INTERVAL、QR_EXPIRE_TIME、USE_MOCK。
|
||
MqttConstants：MQTT host、API host、端口、发布/订阅 topic 前后缀、QoS。
|
||
CanConstants：默认串口 /dev/ttyS4、波特率 115200、CAN 帧头/长度/帧尾、门开关状态。
|
||
CanCommands：LON、LOF、LST、PON、POF、RON、GON、AOF、PVD、MFG、PRO、DSN、CON、1VER、1LEN、1MD5、1MDE。
|
||
OperationType：借、还、维修、批量出入柜、格口上断电、灯光、设备信息、固件版本、开门、异常检测等操作码。
|
||
LanguageManager.Language：中文、英文、韩文、日文、俄文。
|
||
Mode：HOME、AWAY、FUN、MOVIE。
|
||
|
||
## 8. 协作约定
|
||
生成本文档后，后续我只提供待修改局部代码，不再发送完整工程。所有修改基于这份上下文；信息不足、架构冲突请主动提问，不要自行猜测。回复仅输出改动代码+简短说明。
|