# 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 为 `com.flagship.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. 五人进入第一轮并行开发。