KremeCN
0144ea992c
## Summary - add a root README with project overview, setup, usage, architecture, security, and contribution guidance - replace stale planning and requirement notes with current 1.0 project overview - update architecture and hardware validation docs to match the implemented app - remove obsolete UI branch notes and the old Java/XML AsyncTask example - remove the superpowers documentation and move vendor ABSDK references into docs/vendor - preserve vendor Markdown and XLS content byte-for-byte ## Verification - Markdown relative links checked - vendor files verified as 100% Git renames - git diff --check passed - no application tests run; documentation-only change Reviewed-on: #15 Co-authored-by: KremeCN <3265494849@qq.com>
134 lines
4.7 KiB
Markdown
134 lines
4.7 KiB
Markdown
<p align="center">
|
||
<img src="android/app/src/main/res/drawable/ic_abox_logo_master.png" width="112" alt="ABox Manager logo">
|
||
</p>
|
||
|
||
<h1 align="center">ABox Manager</h1>
|
||
|
||
<p align="center">
|
||
面向 Android 手机和平板的 ABox 智能家居管理应用
|
||
</p>
|
||
|
||
## 项目介绍
|
||
|
||
ABox Manager 使用 ABSDK 连接局域网中的 ABox 网关，为智能插座、温湿度传感器和红外控制器提供统一的设备管理体验。应用同时包含不依赖账号、网络或真实硬件的本地体验模式，可用于浏览界面和验证主要操作流程。
|
||
|
||
当前正式版本为 **1.0.0**，由 **Flagship** 团队开发。
|
||
|
||
## 主要功能
|
||
|
||
- ABox 登录、自动登录、加密凭据与会话失效处理；
|
||
- 智能插座状态查询、开关控制和命令后状态确认；
|
||
- 温度与湿度读取，以及无数据、错误和离线状态展示；
|
||
- 预置红外码库下载，以及自定义遥控器按键学习；
|
||
- 遥控器布局、按钮、硬件槽位和顺序管理；
|
||
- 手动指令与基于时间、温度、湿度和设备状态的自动指令；
|
||
- 插座、红外、延迟和系统通知动作；
|
||
- 按 profile 隔离并持久化的活动记录；
|
||
- 浅色、深色、动态颜色、强调色与界面缩放；
|
||
- 英文和简体中文本地化；
|
||
- 独立且确定性的本地体验环境。
|
||
|
||
## 技术栈
|
||
|
||
- Kotlin 2.4
|
||
- Jetpack Compose 与 Material
|
||
- Navigation Compose
|
||
- Hilt
|
||
- Coroutines 与 StateFlow
|
||
- Room
|
||
- DataStore 与 Android Keystore
|
||
- WorkManager
|
||
- 多模块 Gradle 工程
|
||
|
||
核心模块：
|
||
|
||
```text
|
||
domain/ 领域模型、端口和用例
|
||
absdk-bridge/ ABSDK 0630 防腐层
|
||
runtime/simulation/ 本地体验模拟运行时
|
||
testing/fakes/ 测试专用 Fake
|
||
android/core/ 设计系统、偏好、设备目录和会话
|
||
android/feature/infrared/ 红外遥控器功能
|
||
android/feature/automation/ 情景、自动化和活动记录
|
||
android/app/ 应用组合根、导航和设备界面
|
||
```
|
||
|
||
完整依赖方向和数据边界见 [架构文档](docs/architecture.md)。
|
||
|
||
## 开发环境
|
||
|
||
- JDK 17
|
||
- Android SDK 37
|
||
- Android Studio，或能够运行 Gradle Wrapper 的 Android 开发环境
|
||
- Windows、macOS 或 Linux
|
||
|
||
项目最低支持 Android 8.0（API 26），目标 SDK 为 36。
|
||
|
||
克隆仓库后，确保 Android SDK 路径已由 Android Studio 写入本机 `local.properties`，然后构建调试 APK：
|
||
|
||
```powershell
|
||
.\gradlew.bat :android:app:assembleDebug
|
||
```
|
||
|
||
macOS 或 Linux：
|
||
|
||
```bash
|
||
./gradlew :android:app:assembleDebug
|
||
```
|
||
|
||
APK 输出位置：
|
||
|
||
```text
|
||
android/app/build/outputs/apk/debug/app-debug.apk
|
||
```
|
||
|
||
连接模拟器或 Android 设备后可以安装：
|
||
|
||
```bash
|
||
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
|
||
```
|
||
|
||
## 使用方式
|
||
|
||
### ABox
|
||
|
||
设备需要与 ABox 网关处于可用的局域网环境，并使用有效账号登录。ABSDK 通过设备名称匹配网关设备；App 中的设备名称必须与网关实际名称一致。
|
||
|
||
首次初始化 ABox profile 时，App 会按设备类型补充以下默认记录：
|
||
|
||
- `智能插座`
|
||
- `温湿度传感器`
|
||
- `红外控制器`
|
||
|
||
已有同类型设备不会被迁移、重命名或覆盖。
|
||
|
||
### 本地体验
|
||
|
||
本地体验无需账号和网络，使用独立模拟数据。它适合浏览产品和验证界面流程，但不能作为真实 ABox、网络或硬件验收结果。
|
||
|
||
## 文档
|
||
|
||
- [项目概览](docs/project-overview.md)
|
||
- [架构说明](docs/architecture.md)
|
||
- [ABSDK 0630 已确认事实与边界](docs/protocol/absdk-0630.md)
|
||
- [设备数据能力矩阵](docs/testing/device-data-capability-matrix.md)
|
||
- [红外硬件验证](docs/testing/infrared-hardware-validation.md)
|
||
- [正式版局域网硬件验收](docs/testing/release-lan-hardware-validation.md)
|
||
- [完整文档索引](docs/README.md)
|
||
|
||
## 安全边界
|
||
|
||
厂商 ABSDK JAR 使用明文 HTTP，并依赖外部局域网环境完成域名到网关的访问。真实 ABox 功能只能在已授权、受控的局域网中使用。
|
||
|
||
不得在日志、截图、问题报告或测试记录中提交密码、Token、完整网关地址、完整硬件标识、原始红外码值或未脱敏 SDK 响应。
|
||
|
||
## 贡献流程
|
||
|
||
`main` 是受保护分支。所有修改必须从最新 `main` 创建专用分支，通过 Pull Request 合并，不得直接在 `main` 上开发或推送。详细规则见 [AGENTS.md](AGENTS.md)。
|
||
|
||
## 第三方资料
|
||
|
||
内置的部分红外预置来源于 Flipper-IRDB，并按照 CC0 1.0 提供。来源、转换范围和归属信息见 [Flipper-IRDB attribution](docs/third-party/flipper-irdb.md)。
|
||
|
||
仓库中的厂商 SDK、接口资料和第三方内容分别受其自身许可或授权条件约束；本仓库当前未声明覆盖整个项目的统一开源许可证。
|