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。

重要参考资料：

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

主要交付：

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

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

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