# DevicePlugin 阶段一任务分解文档

## 项目背景
根据 CEO 陈逸飞指示和架构师王思远设计文档 `docs/DEVICE_PLUGIN_DESIGN.md`，实施 DevicePlugin 统一设备管理插件的阶段一（基础框架）。

## 总体目标
建立 DevicePlugin 基础框架，支持 Linux ARM64 平台的 Display 和 SleepInhibit 两个核心能力，为后续功能扩展打下基础。

## 任务列表与执行顺序

### Task 1: Message enum 扩展
**负责人建议**: 张明远（内核工程师，精通 Rust 类型系统和消息传递）

**优先级**: P0（阻塞后续所有任务）

**输入文件**:
- `src/core/message.rs` — 现有 Message enum 定义
- `docs/DEVICE_PLUGIN_DESIGN.md` — DeviceCommand/DeviceResponse/DeviceEvent 设计

**任务描述**:
1. 在 `Message` enum 中添加三个新变体：
   - `DeviceCommand(DeviceCommand)` — 业务插件向 DevicePlugin 发送的命令
   - `DeviceResponse(DeviceResponse)` — DevicePlugin 返回的响应
   - `DeviceEvent(DeviceEvent)` — DevicePlugin 广播的事件
2. 在 `message.rs` 中定义以下新类型（参考设计文档第4节）：
   - `pub enum DeviceCommand` — 至少包含 GetDisplayInfo, SetBrightness, SetBacklight, WriteFramebuffer, SetSleepInhibit
   - `pub enum DeviceResponse` — 至少包含 DisplayInfo, Ok, Error
   - `pub enum DeviceEvent` — 至少包含 DisplayConnected, DisplayDisconnected
   - `pub enum DeviceCapability` — 至少包含 Display, Backlight, Framebuffer
   - `pub enum PixelFormat` — 至少包含 RGBA8888, RGB888
   - `pub enum SensorType` — 预留，至少包含 Temperature
   - `pub enum TouchAction` — 预留，至少包含 Down, Move, Up
3. 所有新类型必须派生 `Debug, Clone, Serialize, Deserialize`（跨 FFI 边界要求）
4. 为复杂变体添加文档注释说明用途

**输出文件**:
- `src/core/message.rs` — 更新后的消息定义

**验收标准**:
- [ ] `cargo check --workspace` 零 warning
- [ ] 所有新类型正确派生 serde traits
- [ ] DeviceCommand 至少包含 5 个变体（Display + SleepInhibit 相关）
- [ ] DeviceResponse 至少包含 3 个变体
- [ ] 文档注释清晰说明每个变体的用途

**预计工时**: 2 小时

---

### Task 2: DevicePlugin 骨架与 Backend trait
**负责人建议**: 王思远（架构师，精通系统架构和 trait 设计）

**优先级**: P0（依赖 Task 1）

**依赖**: Task 1 必须完成（Message enum 已扩展）

**输入文件**:
- `src/core/message.rs` — Task 1 完成后的消息定义
- `src/plugins/screen/mod.rs` — 现有插件实现参考
- `src/core/plugin.rs` — Plugin trait 定义
- `docs/DEVICE_PLUGIN_DESIGN.md` — DeviceBackend trait 设计（第3节）

**任务描述**:
1. 创建 `src/plugins/device/mod.rs`：
   - 定义 `pub struct DevicePlugin` 包含字段：
     - `ctx: Option<PluginContext>`
     - `backend: Box<dyn DeviceBackend>`
   - 实现 `Plugin` trait 的所有方法：
     - `id()` 返回 "device"
     - `info()` 返回插件信息
     - `init()` 初始化 backend
     - `start()` 启动 backend
     - `handle_message()` 匹配 `Message::DeviceCommand`，调用 `backend.handle_command()`，返回 `Message::DeviceResponse`
     - `stop()` 调用 `backend.shutdown()`
   - 实现 `DevicePlugin::new(backend: Box<dyn DeviceBackend>)` 构造函数
2. 创建 `src/plugins/device/backend.rs`：
   - 定义 `pub trait DeviceBackend: Send` 包含方法（参考设计文档）：
     - `fn name(&self) -> &str;`
     - `fn init(&mut self, config: &serde_json::Value) -> Result<()>;`
     - `fn handle_command(&mut self, cmd: DeviceCommand) -> Result<DeviceResponse>;`
     - `fn capabilities(&self) -> Vec<DeviceCapability>;`
     - `fn shutdown(&mut self) -> Result<()>;`
   - 添加完整的文档注释说明每个方法的职责
3. 在 `src/plugins/device/mod.rs` 中添加 `pub mod backend;` 和 `pub use backend::DeviceBackend;`
4. 在 `src/plugins/mod.rs` 中添加 `pub mod device;`

**输出文件**:
- `src/plugins/device/mod.rs` — DevicePlugin 实现
- `src/plugins/device/backend.rs` — DeviceBackend trait 定义
- `src/plugins/mod.rs` — 模块导出更新

**验收标准**:
- [ ] `cargo check --workspace` 零 warning
- [ ] DevicePlugin 正确实现 Plugin trait 所有方法
- [ ] DeviceBackend trait 方法签名与设计文档一致
- [ ] handle_message 正确处理 DeviceCommand 并返回 DeviceResponse
- [ ] 文档注释完整，说明插件职责和 trait 用途

**预计工时**: 3 小时

---

### Task 3: Linux ARM64 Backend 实现
**负责人建议**: 赵雨薇（屏幕工程师，精通 Linux 显示系统和电源管理）

**优先级**: P0（依赖 Task 2）

**依赖**: Task 2 必须完成（DeviceBackend trait 已定义）

**输入文件**:
- `src/plugins/device/backend.rs` — Task 2 完成后的 trait 定义
- `src/plugins/screen/mod.rs` — 现有 ScreenPlugin 实现（参考 systemd-inhibit 用法）
- `docs/DEVICE_PLUGIN_DESIGN.md` — 后端实现要求

**任务描述**:
1. 创建 `src/plugins/device/linux_arm64.rs`：
   - 定义 `pub struct LinuxArm64Backend` 包含字段：
     - `wake_lock_child: Option<Child>` — systemd-inhibit 子进程
     - `display_info: Option<DisplayInfo>` — 缓存的显示信息
     - `backlight_enabled: bool` — 背光状态
   - 实现 `DeviceBackend` trait：
     - `name()` 返回 "linux-arm64"
     - `init()` 读取 framebuffer 信息（/sys/class/graphics/fb0/virtual_size），初始化 display_info
     - `capabilities()` 返回 `vec![DeviceCapability::Display, DeviceCapability::Backlight, DeviceCapability::Framebuffer]`
     - `handle_command()` 实现以下命令：
       - `GetDisplayInfo` → 返回 `DisplayInfo { width, height, format }`
       - `SetSleepInhibit(true)` → 启动 systemd-inhibit（参考 ScreenPlugin::start_wake_lock）
       - `SetSleepInhibit(false)` → 停止 systemd-inhibit（参考 ScreenPlugin::stop_wake_lock）
       - `SetBacklight(bool)` → 写入 `/sys/class/backlight/*/brightness`（0 或最大值）
       - 其他命令返回 `DeviceResponse::Error("Not implemented".to_string())`
     - `shutdown()` 清理 wake_lock_child
   - 实现 `LinuxArm64Backend::new() -> Self` 构造函数
   - 添加 `#[cfg(target_os = "linux")]` 条件编译
2. 在 `src/plugins/device/mod.rs` 中：
   - 添加 `#[cfg(target_os = "linux")] pub mod linux_arm64;`
   - 添加 `#[cfg(target_os = "linux")] pub use linux_arm64::LinuxArm64Backend;`
   - 添加便捷构造函数 `pub fn new_default() -> Self`，自动选择当前平台后端

**输出文件**:
- `src/plugins/device/linux_arm64.rs` — Linux ARM64 后端实现
- `src/plugins/device/mod.rs` — 更新模块导出和便捷构造函数

**验收标准**:
- [ ] `cargo check --workspace` 零 warning
- [ ] LinuxArm64Backend 正确实现 DeviceBackend trait
- [ ] GetDisplayInfo 能正确读取 framebuffer 信息
- [ ] SetSleepInhibit 能启动/停止 systemd-inhibit 子进程
- [ ] SetBacklight 能控制背光（至少支持开/关）
- [ ] shutdown 正确清理子进程资源
- [ ] 非 Linux 平台编译不报错（条件编译正确）

**预计工时**: 4 小时

---

### Task 4: 集成测试与文档
**负责人建议**: 李思琪（视频引擎工程师，熟悉状态机和测试，有 Message 序列化经验）

**优先级**: P1（依赖 Task 3）

**依赖**: Task 3 必须完成（Backend 实现完成）

**输入文件**:
- `src/plugins/device/` — Task 1-3 完成后的所有文件
- `src/plugins/screen/mod.rs` — 参考现有插件测试模式
- `docs/DEVICE_PLUGIN_DESIGN.md` — 验收标准（第8节）

**任务描述**:
1. 创建 `src/plugins/device/tests.rs`：
   - 编写至少 5 个单元测试：
     - `test_device_command_serialization` — 测试 DeviceCommand 序列化/反序列化
     - `test_device_response_serialization` — 测试 DeviceResponse 序列化/反序列化
     - `test_backend_capabilities` — 测试 backend.capabilities() 返回正确能力列表
     - `test_get_display_info` — 测试 GetDisplayInfo 命令（mock backend）
     - `test_set_sleep_inhibit` — 测试 SetSleepInhibit 命令（mock backend）
   - 实现一个 `MockBackend` 用于测试（不依赖真实硬件）
2. 在 `src/plugins/device/mod.rs` 中添加 `#[cfg(test)] mod tests;`
3. 更新 `docs/DEVICE_PLUGIN_DESIGN.md`：
   - 在第8节验收标准中勾选已完成项
   - 添加"使用示例"章节，展示如何创建和使用 DevicePlugin
4. 创建 `src/plugins/device/README.md`：
   - 说明 DevicePlugin 的职责和架构
   - 列出支持的平台和能力
   - 提供代码示例（如何发送 DeviceCommand）
   - 说明如何添加新的 Backend 实现

**输出文件**:
- `src/plugins/device/tests.rs` — 单元测试
- `src/plugins/device/README.md` — 插件文档
- `docs/DEVICE_PLUGIN_DESIGN.md` — 更新验收标准

**验收标准**:
- [ ] `cargo check --workspace --all-targets` 零 warning
- [ ] `cargo test --workspace` 全部通过
- [ ] 至少 5 个测试用例，覆盖核心功能
- [ ] MockBackend 实现完整，可用于测试
- [ ] README.md 包含清晰的使用示例和架构说明
- [ ] 设计文档验收标准已更新

**预计工时**: 3 小时

---

### Task 5: ScreenPlugin 功能迁移验证（可选）
**负责人建议**: 赵雨薇（ScreenPlugin 原作者，熟悉现有实现）

**优先级**: P2（依赖 Task 4，可延后到阶段二）

**依赖**: Task 4 必须完成（测试通过）

**输入文件**:
- `src/plugins/screen/mod.rs` — 现有 ScreenPlugin 实现
- `src/plugins/device/` — 新的 DevicePlugin 实现

**任务描述**:
1. 在 `src/plugins/screen/mod.rs` 中添加注释标记待迁移功能：
   - `start_wake_lock()` → 改为发送 `Message::DeviceCommand(DeviceCommand::SetSleepInhibit(true))`
   - `stop_wake_lock()` → 改为发送 `Message::DeviceCommand(DeviceCommand::SetSleepInhibit(false))`
2. 创建 `docs/SCREEN_PLUGIN_MIGRATION.md` 迁移计划文档：
   - 列出需要迁移的功能清单
   - 说明迁移步骤和兼容性策略
   - 标记阶段二执行的具体任务
3. 验证 DevicePlugin 和 ScreenPlugin 可以共存（不冲突）

**输出文件**:
- `src/plugins/screen/mod.rs` — 添加迁移注释
- `docs/SCREEN_PLUGIN_MIGRATION.md` — 迁移计划文档

**验收标准**:
- [ ] 迁移计划文档完整，列出所有待迁移功能
- [ ] ScreenPlugin 和 DevicePlugin 同时注册不报错
- [ ] `cargo check` 和 `cargo test` 通过

**预计工时**: 2 小时

---

## 任务依赖关系图

```
Task 1 (Message enum)
   ↓
Task 2 (DevicePlugin 骨架 + Backend trait)
   ↓
Task 3 (Linux ARM64 Backend)
   ↓
Task 4 (测试与文档)
   ↓
Task 5 (ScreenPlugin 迁移验证，可选)
```

## 团队成员能力评估

| 成员     | 角色           | 相关经验                                      | 适合任务 |
|----------|----------------|-----------------------------------------------|----------|
| 张明远   | 内核工程师     | Rust 类型系统★★★★★，消息传递★★★★★            | Task 1   |
| 王思远   | 架构师         | 系统架构★★★★★，trait 设计★★★★★               | Task 2   |
| 赵雨薇   | 屏幕工程师     | Linux 显示系统★★★★★，电源管理经验丰富         | Task 3, 5|
| 李思琪   | 视频引擎工程师 | 状态机★★★★★，Message 序列化经验，测试经验     | Task 4   |
| 王浩然   | 网络工程师     | 异步编程★★★★★，但本阶段无网络需求             | 备用     |

## 关键风险与应对

### 风险 1: Message enum 改动影响现有插件
**影响**: 中
**应对**: Task 1 完成后立即运行 `cargo check --workspace` 验证所有插件编译通过

### 风险 2: systemd-inhibit 在某些 Linux 发行版不可用
**影响**: 低
**应对**: Task 3 中添加错误处理，systemd-inhibit 失败时记录警告但不阻塞插件启动

### 风险 3: framebuffer 路径在不同设备上可能不同
**影响**: 中
**应对**: Task 3 中实现路径探测逻辑，尝试 /dev/fb0, /sys/class/graphics/fb0 等多个路径

### 风险 4: 任务串行导致总工时较长
**影响**: 中
**应对**: Task 1-3 必须串行，但 Task 4 可以在 Task 3 完成 80% 时提前开始准备 MockBackend

## 时间估算

| 任务   | 预计工时 | 依赖关系 | 可并行 |
|--------|----------|----------|--------|
| Task 1 | 2h       | 无       | 否     |
| Task 2 | 3h       | Task 1   | 否     |
| Task 3 | 4h       | Task 2   | 否     |
| Task 4 | 3h       | Task 3   | 否     |
| Task 5 | 2h       | Task 4   | 可选   |

**总计**: 12-14 小时（1.5-2 个工作日，假设单人串行）

**优化方案**: 
- Task 1 完成后，Task 2 和 Task 3 的负责人可以同时开始准备（阅读文档、设计实现）
- Task 4 可以在 Task 3 完成 80% 时开始编写 MockBackend

## 验收总清单

阶段一完成的标志：

- [ ] `cargo check --workspace --all-targets` 零 warning
- [ ] `cargo test --workspace` 全部通过
- [ ] DevicePlugin 通过 Plugin trait 正确注册和启动
- [ ] Linux ARM64 后端支持 Display + SleepInhibit 两个能力
- [ ] 至少 5 个单元测试覆盖核心功能
- [ ] 文档完整（README.md + 设计文档更新）
- [ ] Message enum 扩展不影响现有插件编译

## 汇报要求

每个任务完成后，负责人需要：
1. 运行 `export PATH="/home/showen/.rustup/toolchains/stable-aarch64-unknown-linux-gnu/bin:$PATH" && cargo check --workspace --all-targets` 验证编译
2. 运行 `export PATH="/home/showen/.rustup/toolchains/stable-aarch64-unknown-linux-gnu/bin:$PATH" && cargo test --workspace` 验证测试
3. 更新自己的 soul 文件，记录本次任务经验
4. 在 `.showen/TEAM_CHAT.md` 中汇报任务完成情况

全部任务完成后，PM 刘建国向 CEO 汇报到 `.showen/inbox/ceo.md`。

---

**文档创建时间**: 2026-03-13  
**文档创建人**: PM 刘建国  
**文档版本**: v1.0