599 lines
15 KiB
Markdown
599 lines
15 KiB
Markdown
# ABox Manager 项目计划
|
||
|
||
## 1. 文档目的
|
||
|
||
本文档是 ABox Manager 的项目执行蓝图，用于统一产品范围、技术方向、五人固定分工、模块依赖、实施阶段和验收原则。
|
||
|
||
本文档只记录已经确认的方向。尚未确认的 SDK 行为、协议细节和外部环境必须保留为待确认事项，不得将推测直接作为实现依据。
|
||
|
||
---
|
||
|
||
## 2. 项目现状
|
||
|
||
仓库目前主要包含：
|
||
|
||
- 产品需求概要；
|
||
- ABSDK 0630 接口文档；
|
||
- AsyncTask 登录示例；
|
||
- 清理归档后的 ABSDK Android Sample；
|
||
- Git 和 AI 工具协作规则。
|
||
|
||
当前还没有正式的 Android 应用工程、自有后端、自动化测试或 CI Runner。
|
||
|
||
重要参考资料：
|
||
|
||
```text
|
||
docs/requirement_spec.md
|
||
docs/ABSDK接口部分_0630.md
|
||
docs/examples/
|
||
samples/abox-sdk-sample/
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 产品目标
|
||
|
||
ABox Manager 是面向 Android 手机和平板的智能家居管理应用，首版覆盖以下核心能力：
|
||
|
||
1. 登录和会话管理；
|
||
2. 设备列表与页面导航；
|
||
3. 插座状态查询和开关控制；
|
||
4. 温湿度查询和展示；
|
||
5. 红外遥控器创建、学习和发送；
|
||
6. 基于插座和红外动作的情景模式；
|
||
7. 数据本地持久化；
|
||
8. 简体中文和英文界面；
|
||
9. 手机和平板响应式界面。
|
||
|
||
---
|
||
|
||
## 4. MVP 范围
|
||
|
||
### 4.1 登录
|
||
|
||
- 支持用户名和密码登录；
|
||
- 支持记住用户名；
|
||
- 支持按连接配置独立开启自动登录；
|
||
- 自动登录所需密码必须通过 Android Keystore 安全保存；
|
||
- ABSDK Token 由 SDK 自身管理；进程重启或 Token 失效后，通过保存的凭据重新登录；
|
||
- 退出登录时保留非敏感连接信息和用户名，清除密码与会话；
|
||
- 切换后端提供方前必须退出当前会话。
|
||
|
||
### 4.2 提供方模式
|
||
|
||
应用计划兼容三种相互独立的模式：
|
||
|
||
1. **ABox 后端**：使用现有 ABSDK 0630 连接 ABox 服务；
|
||
2. **自有兼容后端**：连接自行实现的 ABSDK 0630 协议兼容服务；
|
||
3. **本地体验**：不连接远端服务，通过本地模拟数据体验完整应用流程。
|
||
|
||
约束：
|
||
|
||
- 任一时刻只使用一个提供方；
|
||
- 不要求同时连接两个后端；
|
||
- ABox 与自有后端的账号、会话和数据不互相绑定；
|
||
- 每个连接配置拥有独立的设备、遥控器、情景和凭据空间；
|
||
- 本地体验不启动 HTTP 服务，也不调用 ABSDK。
|
||
|
||
### 4.3 设备目录
|
||
|
||
ABSDK 0630 当前没有已确认的设备列表接口，因此首版设备目录采用：
|
||
|
||
- 二维码批量导入；
|
||
- 用户手工添加、编辑和删除；
|
||
- 设备名称作为调用 ABSDK 的设备标识；
|
||
- 设备类型首版只包含插座、温湿度和红外。
|
||
|
||
不得假设存在尚未确认的新版 SDK 或设备发现接口。
|
||
|
||
### 4.4 插座
|
||
|
||
- 查询当前状态；
|
||
- 显示打开、关闭、加载、错误和离线状态；
|
||
- 控制打开和关闭；
|
||
- 控制完成后确认实际状态；
|
||
- 防止重复操作；
|
||
- 记录操作结果。
|
||
|
||
### 4.5 温湿度
|
||
|
||
- 查询温度；
|
||
- 查询湿度；
|
||
- 分别展示温度和湿度；
|
||
- 支持刷新；
|
||
- 显示加载、无数据、错误和离线状态；
|
||
- 温湿度设备是只读设备，不提供控制动作。
|
||
|
||
### 4.6 红外遥控器
|
||
|
||
- 创建、编辑和删除遥控器；
|
||
- 设置遥控器名称和视觉标识；
|
||
- 添加、重命名、排序和删除按键；
|
||
- 学习红外按键；
|
||
- 发送红外按键；
|
||
- 下载红外码；
|
||
- 持久化遥控器布局和按键；
|
||
- 为情景模式提供稳定的红外按键动作引用。
|
||
|
||
### 4.7 情景模式
|
||
|
||
- 创建、编辑和删除情景；
|
||
- 设置情景名称、图标和颜色；
|
||
- 添加插座开关动作；
|
||
- 添加红外按键动作；
|
||
- 调整动作顺序；
|
||
- 按顺序执行动作；
|
||
- 单个动作失败后继续执行后续动作；
|
||
- 最后逐项汇总执行结果；
|
||
- 防止同一情景被重复触发；
|
||
- 按提供方隔离情景数据。
|
||
|
||
首版不实现：
|
||
|
||
- 定时触发；
|
||
- 条件判断；
|
||
- 温湿度或其他传感器自动触发；
|
||
- 复杂规则引擎。
|
||
|
||
---
|
||
|
||
## 5. 技术方向
|
||
|
||
### 5.1 Android
|
||
|
||
正式 Android 应用采用：
|
||
|
||
- Kotlin；
|
||
- Jetpack Compose；
|
||
- Material 3；
|
||
- 单 Activity；
|
||
- Navigation Compose；
|
||
- ViewModel；
|
||
- StateFlow；
|
||
- Coroutines；
|
||
- Hilt；
|
||
- Room；
|
||
- DataStore；
|
||
- Android Keystore。
|
||
|
||
目标：
|
||
|
||
- applicationId 暂定 `de.kimico.abox.manager`；
|
||
- 最低 Android 版本暂按 API 26；
|
||
- 支持手机和平板；
|
||
- 支持深色和浅色主题；
|
||
- 支持简体中文和英文；
|
||
- 其他系统语言回退到英文；
|
||
- 满足基本无障碍要求；
|
||
- 建立独立的 ABox 视觉设计系统。
|
||
|
||
### 5.2 ABSDK 接入原则
|
||
|
||
- 正式业务代码不得直接散落调用 `ABSDK.getInstance()`；
|
||
- 必须通过统一适配层调用 SDK；
|
||
- SDK 同步阻塞调用必须在后台线程执行；
|
||
- `ABRet`、原始 `Map` 和字符串错误码不得泄漏到 UI 层；
|
||
- 适配层将 SDK 返回转换为类型化领域结果；
|
||
- SDK 的 Host、Token 和线程状态按全局共享状态处理；
|
||
- 切换提供方前必须结束当前会话；
|
||
- `docs/examples/` 和 `samples/abox-sdk-sample/` 只作为参考，不直接作为正式架构。
|
||
|
||
### 5.3 自有兼容后端
|
||
|
||
自有后端目标是兼容 ABSDK 0630 的必要服务端行为。
|
||
|
||
暂定方向：
|
||
|
||
- Kotlin 和 Ktor；
|
||
- 旧协议只存在于兼容适配边界；
|
||
- 内部使用类型化领域模型；
|
||
- 密码使用强哈希保存；
|
||
- 酒店与房间作为数据隔离边界；
|
||
- 管理操作通过内置 CLI 完成；
|
||
- 提供模拟设备驱动；
|
||
- 为未来真实设备驱动预留统一接口；
|
||
- SQLite 用于轻量部署；
|
||
- PostgreSQL 用于较大规模部署；
|
||
- Docker 作为标准交付方式。
|
||
|
||
具体协议、签名和连接方式必须先验证，不在本文档中提前固化。
|
||
|
||
---
|
||
|
||
## 6. 固定五人分工
|
||
|
||
项目总体分工固定为以下五个模块。后续新增工作必须归入这五个模块，不再以协议、服务端或基础架构为理由重划总体职责。
|
||
|
||
| 成员 | 固定模块 |
|
||
|---|---|
|
||
| KremeCN | 工程 SDK 登录 |
|
||
| alZerNest | 设备列表导航 |
|
||
| Aurum | 插座温湿度 |
|
||
| Moler | 红外遥控器 |
|
||
| tzh | 情景模式集成 |
|
||
|
||
### 6.1 KremeCN：工程 SDK 登录
|
||
|
||
负责项目公共基础、SDK 以及登录体系。
|
||
|
||
主要工作：
|
||
|
||
- 创建 Android 工程和公共构建配置；
|
||
- 建立 Compose、Navigation、Hilt、Room 和 DataStore 基础；
|
||
- 建立公共设计系统基础；
|
||
- 接入和封装 ABSDK 0630；
|
||
- 建立统一领域接口、错误模型和 Fake 实现；
|
||
- 实现 ABox、自有兼容后端和本地体验三个入口；
|
||
- 实现记住用户名、自动登录、Keystore 凭据保存和退出；
|
||
- 处理 Token 失效与重新登录；
|
||
- 研究 SDK 已确认行为和协议边界；
|
||
- 建立自有兼容后端基础、测试宿主、CLI 和 Docker 基础。
|
||
|
||
主要交付：
|
||
|
||
```text
|
||
工程基础
|
||
SDK 适配层
|
||
登录与提供方选择
|
||
公共领域接口与 Fake
|
||
兼容后端基础
|
||
```
|
||
|
||
### 6.2 alZerNest：设备列表导航
|
||
|
||
负责登录后的主界面、设备目录和页面导航。
|
||
|
||
主要工作：
|
||
|
||
- 设备模型和三种设备类型；
|
||
- 设备列表；
|
||
- 二维码导入设备目录；
|
||
- 手工添加、编辑和删除设备；
|
||
- 按提供方隔离设备数据；
|
||
- 手机单栏导航；
|
||
- 平板列表详情双栏布局；
|
||
- 点击设备进入正确详情页；
|
||
- 空列表、未知设备和离线状态；
|
||
- Room 设备目录持久化。
|
||
|
||
主要交付：
|
||
|
||
```text
|
||
设备目录
|
||
设备列表
|
||
主导航
|
||
手机和平板导航
|
||
```
|
||
|
||
### 6.3 Aurum：插座温湿度
|
||
|
||
负责插座和温湿度的完整功能。
|
||
|
||
主要工作：
|
||
|
||
- 插座状态查询和开关控制；
|
||
- 控制后的状态确认；
|
||
- 插座加载、错误、超时和离线状态；
|
||
- 温度和湿度查询、格式化和刷新；
|
||
- 温湿度加载、错误、无数据和离线状态；
|
||
- 操作日志接入；
|
||
- 对应 ViewModel、单元测试和 UI 测试。
|
||
|
||
主要交付：
|
||
|
||
```text
|
||
插座控制页面
|
||
温湿度页面
|
||
相关状态管理和测试
|
||
```
|
||
|
||
### 6.4 Moler：红外遥控器
|
||
|
||
负责全部红外相关能力。
|
||
|
||
主要工作：
|
||
|
||
- 遥控器列表；
|
||
- 遥控器创建、编辑和删除；
|
||
- 按键添加、重命名、排序和删除；
|
||
- 红外按键学习；
|
||
- 红外发送；
|
||
- 红外码下载；
|
||
- 红外失败和离线状态；
|
||
- Room 持久化；
|
||
- 为情景模式提供稳定的红外动作引用。
|
||
|
||
主要交付：
|
||
|
||
```text
|
||
红外遥控器
|
||
红外学习和发送
|
||
红外本地持久化
|
||
```
|
||
|
||
### 6.5 tzh：情景模式集成
|
||
|
||
负责情景模式和最终体验整合。
|
||
|
||
主要工作：
|
||
|
||
- 情景列表；
|
||
- 情景创建、编辑和删除；
|
||
- 插座动作和红外动作选择；
|
||
- 动作排序；
|
||
- 顺序执行和失败后继续；
|
||
- 执行结果逐项汇总；
|
||
- 情景 Room 持久化；
|
||
- 中英文资源整合；
|
||
- 空状态、错误状态和加载状态统一；
|
||
- 深浅色、无障碍和最终集成测试；
|
||
- 用户使用说明。
|
||
|
||
主要交付：
|
||
|
||
```text
|
||
情景编辑器
|
||
情景执行器
|
||
最终体验整合和验收
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 分工依赖关系
|
||
|
||
```text
|
||
KremeCN 工程 SDK 登录
|
||
├── alZerNest 设备列表导航
|
||
├── Aurum 插座温湿度
|
||
└── Moler 红外遥控器
|
||
│
|
||
└────────────┐
|
||
Aurum 插座温湿度 ───────┤
|
||
▼
|
||
tzh 情景模式集成
|
||
```
|
||
|
||
开发阶段必须通过 Fake 接口解除等待：
|
||
|
||
- KremeCN 优先提供领域接口和 Fake；
|
||
- alZerNest、Aurum、Moler、tzh 使用 Fake 并行开发；
|
||
- 真实 SDK 接口准备好后，各模块只替换数据源，不重写 UI；
|
||
- tzh 不等待全部硬件联调完成才开始情景页面。
|
||
|
||
---
|
||
|
||
## 8. 执行阶段
|
||
|
||
### 阶段 0：需求和接口基线
|
||
|
||
- 扩充产品需求；
|
||
- 区分已确认事实与待确认事项；
|
||
- 定义最小公共领域接口；
|
||
- 提供 Fake 登录、设备目录和设备操作；
|
||
- 五人共同评审接口。
|
||
|
||
退出条件：
|
||
|
||
- 五个模块都能在 Fake 上开始开发；
|
||
- 不确定的 SDK 协议没有被写死；
|
||
- 各模块数据所有权明确。
|
||
|
||
### 阶段 1：工程和 UI 骨架
|
||
|
||
KremeCN：
|
||
|
||
- 建立工程、设计系统、SDK 适配和登录骨架。
|
||
|
||
alZerNest：
|
||
|
||
- 建立设备列表和导航。
|
||
|
||
Aurum：
|
||
|
||
- 建立插座和温湿度页面状态。
|
||
|
||
Moler：
|
||
|
||
- 建立红外遥控器页面和数据结构。
|
||
|
||
tzh：
|
||
|
||
- 建立情景列表、编辑器和 Fake 动作执行。
|
||
|
||
退出条件：
|
||
|
||
- Android App 可以使用 Fake 完成主要页面导航；
|
||
- 服务端骨架可以独立启动；
|
||
- 所有人拥有可独立测试的模块。
|
||
|
||
### 阶段 2：完整功能实现
|
||
|
||
- 接入 Room、DataStore 和 Keystore；
|
||
- 完成登录和提供方隔离；
|
||
- 完成设备目录导入和维护；
|
||
- 完成插座、温湿度和红外；
|
||
- 完成情景模式；
|
||
- 完成自有兼容后端的已确认协议范围。
|
||
|
||
退出条件：
|
||
|
||
- 本地体验模式完整可用；
|
||
- 所有模块在 Fake 或模拟后端下通过测试；
|
||
- 提供方切换不会混用数据和凭据。
|
||
|
||
### 阶段 3：真实集成
|
||
|
||
- 连接真实 ABox 环境；
|
||
- 连接自有兼容后端；
|
||
- 使用真实插座、温湿度和红外设备；
|
||
- 验证 Token 失效、设备离线和错误码；
|
||
- 验证手机和平板布局。
|
||
|
||
退出条件：
|
||
|
||
- 三类真实硬件核心流程通过；
|
||
- ABox 与自有后端连接行为明确；
|
||
- 已知限制完整记录。
|
||
|
||
### 阶段 4：发布验收
|
||
|
||
- 中英文检查；
|
||
- 深浅色检查；
|
||
- 无障碍检查；
|
||
- 安全检查；
|
||
- 自动化测试和手工验收；
|
||
- 安装和部署文档；
|
||
- 发布包和回滚方案。
|
||
|
||
---
|
||
|
||
## 9. 分支与 PR 规则
|
||
|
||
总体模块固定，但具体工作应使用短期功能分支，不应为每个人保留一个持续到项目结束的巨大分支。
|
||
|
||
建议分支示例：
|
||
|
||
### KremeCN
|
||
|
||
```text
|
||
feat/project-foundation
|
||
feat/absdk-bridge
|
||
feat/provider-login
|
||
feat/compatible-server
|
||
```
|
||
|
||
### alZerNest
|
||
|
||
```text
|
||
feat/device-catalog
|
||
feat/device-navigation
|
||
feat/device-import
|
||
```
|
||
|
||
### Aurum
|
||
|
||
```text
|
||
feat/socket-control
|
||
feat/temperature-display
|
||
```
|
||
|
||
### Moler
|
||
|
||
```text
|
||
feat/infrared-remote
|
||
feat/infrared-learning
|
||
```
|
||
|
||
### tzh
|
||
|
||
```text
|
||
feat/scene-editor
|
||
feat/scene-execution
|
||
feat/app-integration
|
||
```
|
||
|
||
所有工作遵循 `AGENTS.md`：
|
||
|
||
- 从最新 `main` 创建工作分支；
|
||
- 修改和提交保留在工作分支；
|
||
- 完成后创建目标为 `main` 的 Pull Request；
|
||
- 不绕过分支保护、评审和必要检查。
|
||
|
||
---
|
||
|
||
## 10. 公共文件所有权
|
||
|
||
| 公共内容 | 主要维护者 |
|
||
|---|---|
|
||
| 根构建配置 | KremeCN |
|
||
| 公共领域接口 | KremeCN，其他成员共同评审 |
|
||
| 设计系统基础 | KremeCN |
|
||
| 主导航与设备导航 | alZerNest |
|
||
| 设备模型 | alZerNest 提出，KremeCN 合入公共层 |
|
||
| 插座与温湿度命令 | Aurum 提出，KremeCN 合入公共层 |
|
||
| 红外命令与按键引用 | Moler 提出，KremeCN 合入公共层 |
|
||
| 情景动作模型 | tzh 提出，KremeCN 合入公共层 |
|
||
| 中英文公共文案检查 | tzh |
|
||
|
||
公共接口变更必须：
|
||
|
||
1. 单独说明影响范围；
|
||
2. 更新对应 Fake；
|
||
3. 由受影响模块负责人评审；
|
||
4. 合并后再由功能分支更新基线。
|
||
|
||
---
|
||
|
||
## 11. 测试与验收
|
||
|
||
### 11.1 自动测试
|
||
|
||
- 领域模型和执行逻辑单元测试；
|
||
- SDK 返回和错误映射测试；
|
||
- ViewModel 状态测试；
|
||
- Room 持久化测试；
|
||
- Compose 核心页面测试；
|
||
- 情景顺序执行和失败继续测试；
|
||
- 自有兼容后端认证、存储和模拟驱动测试；
|
||
- Docker 和 CLI 验证。
|
||
|
||
### 11.2 手工验收
|
||
|
||
- 登录、自动登录和退出；
|
||
- 三种提供方入口；
|
||
- 数据和凭据隔离；
|
||
- 设备目录导入和维护；
|
||
- 插座状态和控制；
|
||
- 温湿度读取；
|
||
- 红外学习和发送；
|
||
- 情景创建和执行；
|
||
- Token 失效与设备离线；
|
||
- 手机和平板；
|
||
- 中文和英文；
|
||
- 深色和浅色。
|
||
|
||
### 11.3 CI
|
||
|
||
当前 Gitea 暂无 Runner。
|
||
|
||
在 Runner 就绪前：
|
||
|
||
- 提供统一的本地验证命令；
|
||
- 每个 PR 附带实际测试结果；
|
||
- 不得以未来 CI 会运行作为跳过验证的理由。
|
||
|
||
Runner 就绪后，再将相同命令配置为受保护 `main` 的必要检查。
|
||
|
||
---
|
||
|
||
## 12. 待确认事项
|
||
|
||
以下内容不能提前假定：
|
||
|
||
- ABSDK 0630 的完整初始化流程；
|
||
- `setHostInfo` 的正式业务含义；
|
||
- ABox 官方部署所需参数；
|
||
- 自有后端与原始 JAR 的最终连接方式；
|
||
- SDK 的完整签名算法和参数规则；
|
||
- SDK 线程安全与会话清理行为；
|
||
- 真实测试账号、设备名称和硬件环境；
|
||
- 自有后端连接真实设备所使用的网关协议；
|
||
- ABSDK 二进制的生产分发许可。
|
||
|
||
上述事项必须通过厂商资料、授权分析、实验或真实环境验证后，再更新本文档或对应技术文档。
|
||
|
||
---
|
||
|
||
## 13. 当前下一步
|
||
|
||
本计划落盘后，不立即开始全部功能开发。
|
||
|
||
正式开工前建议依次完成：
|
||
|
||
1. 五人确认固定分工；
|
||
2. 将 MVP 需求补充到 `docs/requirement_spec.md`；
|
||
3. 建立任务看板；
|
||
4. 明确第一轮短期分支和 PR；
|
||
5. 由 KremeCN 先提供最小公共接口和 Fake；
|
||
6. 五人进入第一轮并行开发。
|