Flagship/abox-mgr
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
66334cf18ef705c76a553d1a2e2039a8b35f098c
abox-mgr/docs/project_plan.md
T

15 KiB
Raw Blame History

ABox Manager 项目计划

1. 文档目的

本文档是 ABox Manager 的项目执行蓝图，用于统一产品范围、技术方向、五人固定分工、模块依赖、实施阶段和验收原则。

本文档只记录已经确认的方向。尚未确认的 SDK 行为、协议细节和外部环境必须保留为待确认事项，不得将推测直接作为实现依据。

2. 项目现状

仓库目前主要包含：

  • 产品需求概要；
  • ABSDK 0630 接口文档；
  • AsyncTask 登录示例；
  • 清理归档后的 ABSDK Android Sample；
  • Git 和 AI 工具协作规则。

当前还没有正式的 Android 应用工程、自有后端、自动化测试或 CI Runner。

重要参考资料：

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 基础。

主要交付：

工程基础
SDK 适配层
登录与提供方选择
公共领域接口与 Fake
兼容后端基础

6.2 alZerNest：设备列表导航

负责登录后的主界面、设备目录和页面导航。

主要工作：

  • 设备模型和三种设备类型；
  • 设备列表；
  • 二维码导入设备目录；
  • 手工添加、编辑和删除设备；
  • 按提供方隔离设备数据；
  • 手机单栏导航；
  • 平板列表详情双栏布局；
  • 点击设备进入正确详情页；
  • 空列表、未知设备和离线状态；
  • Room 设备目录持久化。

主要交付：

设备目录
设备列表
主导航
手机和平板导航

6.3 Aurum：插座温湿度

负责插座和温湿度的完整功能。

主要工作：

  • 插座状态查询和开关控制；
  • 控制后的状态确认；
  • 插座加载、错误、超时和离线状态；
  • 温度和湿度查询、格式化和刷新；
  • 温湿度加载、错误、无数据和离线状态；
  • 操作日志接入；
  • 对应 ViewModel、单元测试和 UI 测试。

主要交付：

插座控制页面
温湿度页面
相关状态管理和测试

6.4 Moler：红外遥控器

负责全部红外相关能力。

主要工作：

  • 遥控器列表；
  • 遥控器创建、编辑和删除；
  • 按键添加、重命名、排序和删除；
  • 红外按键学习；
  • 红外发送；
  • 红外码下载；
  • 红外失败和离线状态；
  • Room 持久化；
  • 为情景模式提供稳定的红外动作引用。

主要交付：

红外遥控器
红外学习和发送
红外本地持久化

6.5 tzh：情景模式集成

负责情景模式和最终体验整合。

主要工作：

  • 情景列表；
  • 情景创建、编辑和删除；
  • 插座动作和红外动作选择；
  • 动作排序；
  • 顺序执行和失败后继续；
  • 执行结果逐项汇总；
  • 情景 Room 持久化；
  • 中英文资源整合；
  • 空状态、错误状态和加载状态统一；
  • 深浅色、无障碍和最终集成测试；
  • 用户使用说明。

主要交付：

情景编辑器
情景执行器
最终体验整合和验收

7. 分工依赖关系

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

feat/project-foundation
feat/absdk-bridge
feat/provider-login
feat/compatible-server

alZerNest

feat/device-catalog
feat/device-navigation
feat/device-import

Aurum

feat/socket-control
feat/temperature-display

Moler

feat/infrared-remote
feat/infrared-learning

tzh

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. 五人进入第一轮并行开发。
Reference in New Issue View Git Blame Copy Permalink