docs: reorganize project documentation
This commit is contained in:
@@ -0,0 +1,133 @@
|
||||
<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、接口资料和第三方内容分别受其自身许可或授权条件约束；本仓库当前未声明覆盖整个项目的统一开源许可证。
|
||||
Reference in New Issue
Block a user