# ABox Manager 项目概览

## 产品定位

ABox Manager 是面向 Android 手机和平板的 ABox 智能家居管理应用。正式版版本为 `1.0.0`，applicationId 为 `com.flagship.abox.manager`，最低支持 Android 8.0（API 26）。

应用提供两种彼此隔离的使用方式：

1. **ABox**：使用 ABSDK 连接当前局域网中的 ABox 网关；
2. **本地体验**：不使用账号、网络或 ABSDK，通过确定性模拟数据体验完整界面和主要流程。

不同提供方的会话、设备、遥控器、情景、自动化和活动记录互不混用。

## 正式版能力

### 会话与账户

- ABox 用户名和密码登录；
- 记住用户名与可选自动登录；
- Android Keystore 加密保存自动登录凭据；
- Token 失效后清理会话并返回登录流程；
- 从账户面板切换连接方式、进入主题和关于页面或退出当前会话。

### 设备中心

- 展示智能插座、温湿度传感器和红外控制器；
- ABox 首次初始化时按设备类型补充默认设备：`智能插座`、`温湿度传感器`、`红外控制器`；
- 设备名称是网关调用使用的匹配标识，用户可以在 App 中修改名称；
- 明确展示加载、在线、离线、无数据和错误状态；
- 插座命令完成后回读真实状态，无法确认时不得把期望状态冒充为设备终态。

### 红外遥控器

- 添加遥控器时先选择下载预置红外码库，或创建通过学习导入的自定义遥控器；
- 非自定义预置遥控器不提供学习入口；
- 支持电视、空调、风扇等预置类型和开源红外码库；
- 支持自定义电视遥控器和自定义面板遥控器；
- 自定义遥控器可添加、编辑、排序和删除按钮，并区分未学习、学习中、学习失败和可发送状态；
- 管理页面支持硬件槽位、遥控器排序、编辑和删除；
- ABox 首次初始化预置两个自定义遥控器，不预置非自定义遥控器。

### 情景、自动化与活动

- 手动指令和自动指令均可从界面手动执行，便于日常使用和测试；
- 动作支持插座开关、虚拟遥控器按钮、红外按键、延迟和系统通知；
- 自动指令触发器支持时间、温度、湿度和插座状态；
- 条件支持温度、湿度、插座状态和时间范围；
- 多个触发器中任一触发器产生新的匹配即可尝试执行，所有条件必须同时满足；
- 状态型触发器只在从“不匹配”进入“匹配”时触发，不会在每次轮询持续重复执行；
- 情景、自动化运行状态和活动记录通过 Room 按 profile 持久化；
- 活动记录区分用户、自动化和系统来源，以及成功、失败、取消和等待确认结果。

### 外观与本地化

- 使用 Kotlin、Jetpack Compose 和 Material；
- 支持系统、浅色和深色模式；
- 支持动态颜色、手动强调色、色彩风格、色彩规范和界面缩放；
- 预测性返回保持关闭且不在界面中提供开关；
- 提供英文和简体中文本地化，其他系统语言回退到英文。

## 数据与安全边界

- ABSDK 0630 没有设备发现接口，ABox 设备目录由 App 本地维护；
- 业务 UI 不接触 `ABRet`、原始 `Map` 或厂商错误文本；
- App 不伪造网关没有提供的电压、电流、功率、电量、历史趋势或诊断数据；
- 本地体验数据不能作为真实 ABox 或真实硬件验收证据；
- 厂商 JAR 使用明文 HTTP，只允许在已授权、受控的局域网环境中使用；
- 日志和文档不得保存密码、Token、完整网络标识、原始红外码值或未脱敏响应。

## 开发团队

开发团队名称为 **Flagship**。

| 成员 | 主要职责 |
|---|---|
| KremeCN | 项目架构与全模块开发 |
| alZerNest | 设备目录与导航 |
| Aurum | 插座与环境传感器 |
| Moler | 红外遥控器 |
| tzh | 情景与应用集成 |

职责用于说明主要所有权，不限制成员参与其他模块的设计、实现、修复和集成。

## 当前限制

- ABSDK 只支持文档和 JAR 已确认的设备能力；
- 网关设备通过名称匹配，重命名后必须与网关实际名称一致；
- 红外开源码库只导入能够可靠转换的 NEC 和 NECext 数据；
- 自动化依赖 Android 后台调度和周期性设备读取，系统省电策略可能影响触发时效；
- ABSDK 的初始化参数、完整线程安全保证和域名到局域网网关的映射机制仍未由厂商完整确认。