abox-mgr/docs/project_plan.md

ABox Manager 项目计划

1. 文档目的

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

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

---

2. 项目现状

仓库目前主要包含：

• 产品需求概要；
• ABSDK 0630 接口文档与协议观测记录；
• 正式 Android 应用工程（含提供方登录与本地体验运行时）；
• ABSDK 防腐层、领域接口、模拟运行时和测试 Fake；
• 清理归档后的 ABSDK Android Sample；
• Git 和 AI 工具协作规则。

当前还没有设备目录、插座温湿度、红外和情景模式的正式实现，也没有 CI Runner。

重要参考资料：

docs/requirement_spec.md
docs/protocol/absdk-0630.md
docs/architecture.md
docs/examples/
samples/abox-sdk-sample/

---

3. 产品目标

ABox Manager 是面向 Android 手机和平板的智能家居管理应用，首版覆盖以下核心能力：

1. 登录和会话管理；
2. 设备列表与页面导航；
3. 插座状态查询和开关控制；
4. 温湿度查询和展示；
5. 红外遥控器创建、学习和发送；
6. 基于插座和红外动作的情景模式；
7. 数据本地持久化；
8. 简体中文和英文界面；
9. 手机和平板响应式界面。

---

4. MVP 范围

4.1 ABox 登录

以下登录要求只适用于 ABox 提供方；本地体验不需要凭据，也不显示登录页面。

• 支持用户名和密码登录；
• 支持记住用户名；
• 支持独立开启自动登录；
• 自动登录所需密码必须通过 Android Keystore 安全保存；
• ABSDK Token 由 SDK 自身管理；进程重启或 Token 失效后，通过保存的凭据重新登录；
• 退出登录时保留用户名，清除密码与会话。

4.2 提供方模式

应用提供两种入口，认证前必须选择其一：

1. ABox：通过 ABSDK 0630 连接当前局域网中的智能家居网关；
2. 本地体验：不访问网络或 ABSDK，通过本地模拟数据直接进入完整应用流程。

首版不提供自有兼容后端入口，也不再规划兼容服务端。

约束：

• 任一时刻只启用一个提供方；
• 切换提供方前必须退出当前会话；
• 每个提供方的会话、设备、遥控器、情景和凭据空间互不混用；
• 本地体验不启动 HTTP 服务，也不调用 ABSDK。

4.3 设备目录

ABSDK 0630 当前没有已确认的设备列表接口，也不提供设备目录。首版设备目录按提供方区分：

• ABox：由设备目录模块负责的本地持久化目录（二维码批量导入，用户手工添加、编辑和删除）；
• 本地体验：由模拟运行时内置的模拟设备目录。

共同约束：

• 设备名称作为调用 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 模拟运行时

本地体验由生产模块 :runtime:simulation 提供确定性模拟实现：

• 不依赖网络、ABSDK 或 Android API；
• 内置固定的模拟设备目录和设备状态；
• 与 ABox 共用同一套领域端口，UI 不感知差异。

测试专用的脚本化 Fake 保留在 :testing:fakes，不进入生产依赖。

---

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 已确认行为和协议边界。

主要交付：

工程基础
SDK 适配层（AbsdkBridge）
本地体验模拟运行时
登录与提供方选择
公共领域接口与测试 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

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 核心页面测试；
• 情景顺序执行和失败继续测试。

11.2 手工验收

• ABox 登录、自动登录和退出；
• 本地体验直接进入应用；
• 两种提供方入口；
• 数据和凭据隔离；
• 设备目录导入和维护；
• 插座状态和控制；
• 温湿度读取；
• 红外学习和发送；
• 情景创建和执行；
• Token 失效与设备离线；
• 手机和平板；
• 中文和英文；
• 深色和浅色。

11.3 CI

当前 Gitea 暂无 Runner。

在 Runner 就绪前：

• 提供统一的本地验证命令；
• 每个 PR 附带实际测试结果；
• 不得以未来 CI 会运行作为跳过验证的理由。

Runner 就绪后，再将相同命令配置为受保护 main 的必要检查。

---

12. 待确认事项

以下内容不能提前假定：

• ABSDK 0630 的完整初始化流程；
• setHostInfo 的正式业务含义；
• ABox 官方部署所需参数；
• SDK 的完整签名算法和参数规则；
• SDK 线程安全与会话清理行为；
• 真实测试账号、设备名称和硬件环境；
• 授权凭据下完整的 ABox 登录与设备操作冒烟验证；
• JAR 硬编码域名与局域网网关地址之间的映射机制（详见 docs/protocol/absdk-0630.md）；
• ABSDK 二进制的生产分发许可。

上述事项必须通过厂商资料、授权分析、实验或真实环境验证后，再更新本文档或对应技术文档。

---

13. 当前下一步

本计划落盘后，不立即开始全部功能开发。

正式开工前建议依次完成：

1. 五人确认固定分工；
2. 将 MVP 需求补充到 docs/requirement_spec.md；
3. 建立任务看板；
4. 明确第一轮短期分支和 PR；
5. 由 KremeCN 先提供最小公共接口和 Fake；
6. 五人进入第一轮并行开发。