ShowenV2/docs/M1.2_TEST_PLAN.md

M1.2 集成测试计划

1. 目标与范围

• 目标：完成 ShowenV2 在 M1.2 阶段的端到端集成测试、旧功能对齐验证、边界条件验证、错误处理验证与回归基线建立。
• 范围覆盖：device、screen、wifi、video、ble、http 六个内置插件，动态插件系统，Flutter App 通过 HTTP/WebSocket/BLE 的交互链路。
• 重点链路：插件注册与启动、消息路由、配置热重载、视频控制、WiFi 配网、BLE 配网、文件管理、动态插件生命周期。
• 验收对齐：覆盖 docs/MILESTONES.md 中 M1.2 的全部任务项，并为 M1.3 性能优化提供可重复的基准输入。

2. 当前实现观察与 M1.2 风险

• src/main.rs 按 device -> screen -> wifi -> video -> ble -> http 注册静态插件，再扫描 plugin_store/ 挂载动态插件。
• src/core/service_manager.rs 负责依赖排序、init -> self_test -> start 生命周期、消息路由、动态插件错误阈值、自动回退、启停与热替换。
• src/plugins/http/routes.rs 已暴露播放、配置、视频、文件、WiFi、BLE、插件管理、App 下载等 API。
• 风险 1：HTTP 插件管理 API 通过 Message::Custom 向 Manager 发命令，但 ServiceManager::handle_manager_message() 当前未处理 plugin_enable、plugin_disable、plugin_rollback、plugin_switch、plugin_install、plugin_check_updates。
• 风险 2：/api/plugins 依赖 plugin_states 自定义消息更新状态，但当前源码中未看到 Manager 侧生产该消息，插件列表接口可能返回空状态。
• 风险 3：WifiProvisioned、DeviceEvent、部分 Custom 消息在当前主链路中无明确生产者/消费者，测试时应区分“未实现”与“回归缺陷”。
• 风险 4：BLE、WiFi、显示、OpenCV、动态插件 .so 装载均依赖 ARM64 实机环境，CI 只能承担部分替身测试。

3. 测试策略

3.1 分层策略

• 单元测试：验证纯逻辑、解析、状态转换、命令拼装、路径校验、manifest 校验、消息序列化。
• 集成测试：验证 ServiceManager 与插件间消息流、配置重载、插件生命周期、HTTP 路由到消息总线的桥接。
• 端到端测试：以真实进程启动 showen_v2，通过 HTTP/WebSocket/BLE/文件系统操作驱动系统，校验插件协同与用户可见结果。

3.2 层级分工

• 单元：优先放在 src/core/*、src/plugins/* 内部测试，补齐未覆盖的解析和错误分支。
• 集成：新增 tests/m1_2_*.rs，使用临时目录、测试配置、fake backend、fake dynamic plugin store 驱动系统。
• E2E：以 ARM64 实机为主，CI 仅跑“无硬件替身版”流程；WebSocket/HTTP 使用 curl、websocat、Flutter 测试桩执行。

3.3 覆盖原则

• 所有非 - 消息交互单元至少有 1 条自动化验证。
• 所有用户入口 API 至少有 1 条成功场景和 1 条失败场景。
• 所有动态插件生命周期动作至少覆盖：加载、必需能力自测失败、错误阈值禁用、自动回退、热替换恢复。
• Flutter 侧至少覆盖：首次连接、实时状态、WiFi 配网、配置读取/保存、APK 下载入口。

4. src 模块视图

• src/main.rs：程序入口、配置加载、静态/动态插件注册、主循环。
• src/core/：消息模型、插件 trait、ServiceManager、PluginLoader、VersionManager。
• src/plugins/device/：统一设备能力入口，响应 DeviceCommand 并广播 DeviceResponse。
• src/plugins/screen/：DevicePlugin thin wrapper，负责防息屏与光标隐藏。
• src/plugins/wifi/：nmcli 驱动的 WiFi 扫描/连接/AP 管理。
• src/plugins/video/：OpenCV 播放器、状态机、状态广播。
• src/plugins/ble/：BlueZ GATT 配网服务，接收 WiFi 结果并向核心转发 WiFi 指令。
• src/plugins/http/：REST/WebSocket/Web UI/App 下载与文件管理桥接层。

5. 插件 × Message 覆盖矩阵

说明：Rx=直接处理，Tx=直接发送/广播，Bridge=对外桥接或间接映射，Gap=已有入口但当前实现未闭环，-=无直接关系。

插件/系统	PlayerCommand	PlayerStatus	Trigger	StateChanged	ScreenLockRequest	CursorVisibility	WifiCommand	WifiResult	WifiProvisioned	ConfigReloaded	ConfigReloadRequest	Shutdown	PluginReady	DeviceCommand	DeviceResponse	DeviceEvent	Custom
DevicePlugin	-	-	-	-	-	-	-	-	-	-	-	Rx	Rx	Rx	Tx	-	-
ScreenPlugin	-	-	-	-	Rx/Tx	Rx/Tx	-	-	-	-	-	Rx	-	Tx	-	-	-
WifiPlugin	-	-	-	-	-	-	Rx	Tx	-	-	-	-	-	-	-	-	-
VideoPlugin	Rx	Tx	Rx	Tx	Tx	-	-	-	-	Rx	-	Rx	Tx	-	-	-	-
BlePlugin	-	-	-	-	-	-	Tx(经 GATT)	Rx	-	-	-	Rx	Tx	-	-	-	-
HttpPlugin	Bridge	Rx/Bridge	Bridge	Rx/Bridge	-	-	Bridge	Rx/Bridge	-	Rx/Bridge	Tx/Bridge	Rx	Rx(ble)	-	-	-	Rx(plugin_states)
动态插件系统	视插件而定	视插件而定	视插件而定	视插件而定	视插件而定	视插件而定	视插件而定	视插件而定	视插件而定	视插件而定	-	Rx	视插件而定	视插件而定	视插件而定	视插件而定	Rx/Tx
Flutter App	Bridge	Bridge	Bridge	Bridge	-	-	Bridge	Bridge	Bridge(BLE 配网结果)	Bridge	Bridge	-	Bridge(状态映射)	-	-	-	Bridge(插件管理入口)

5.1 重点补测项

• DeviceResponse：补足 DevicePlugin 与 ScreenPlugin/业务插件的联动验证，确认 thin wrapper 没有只发不收的问题。
• PluginReady：验证 video、http、ble 的 ready 事件被 Manager 广播后，HTTP/Flutter 状态同步是否准确。
• Custom：动态插件自定义消息已有基础；HTTP 插件管理类 Custom 当前缺少 Manager 闭环，应作为 M1.2 对齐缺陷优先验证。

6. HTTP API 覆盖范围

6.1 播放与状态

• GET /api/status
• POST /api/play
• POST /api/pause
• POST /api/next
• POST /api/previous
• POST /api/goto/:index
• GET /api/playlist
• POST /api/scene/:name
• POST /api/trigger/:name
• POST /api/trigger/:name/:value

6.2 配置管理

• GET /api/config
• GET /api/config/display
• POST /api/config
• GET /api/config/available
• POST /api/config/switch

6.3 视频/文件/App

• GET /api/videos
• POST /api/videos/upload
• DELETE /api/videos/:filename
• GET /api/app/info
• GET /download/:filename
• GET /api/files/:dir
• POST /api/files/:dir/upload
• GET /api/files/:dir/download
• POST /api/files/:dir/delete
• POST /api/files/move
• POST /api/files/:dir/mkdir

6.4 WiFi / BLE / WebSocket / 插件管理

• GET|POST /api/wifi/scan
• GET /api/wifi/status
• POST /api/wifi/connect
• POST /api/wifi/ap/start
• POST /api/wifi/ap/stop
• POST /api/wifi/hotspot/start
• POST /api/wifi/hotspot/stop
• POST /api/ble/start
• POST /api/ble/stop
• GET /api/ble/status
• GET /ws
• GET /api/plugins
• GET /api/plugins/:id
• POST /api/plugins/:id/enable
• POST /api/plugins/:id/disable
• POST /api/plugins/:id/rollback
• POST /api/plugins/:id/switch
• POST /api/plugins/install
• POST /api/plugins/check-updates

7. 端到端场景清单

每个场景均要求记录：日志、HTTP 响应、WebSocket 事件、关键文件变化、插件状态快照。

场景 1：系统冷启动与插件注册

• 前置条件：ARM64 实机；有效配置文件；plugin_store/ 为空或仅含稳定动态插件。
• 操作步骤：启动主程序；观察启动日志；调用 GET /api/status；建立 /ws 连接。
• 预期结果：6 个内置插件按依赖顺序启动；若动态插件存在则完成自测；/api/status 可返回；WebSocket 首包包含 status_update、config_update、ble_update。

场景 2：播放控制主链路

• 前置条件：播放列表至少 2 个有效视频；HTTP 服务启用。
• 操作步骤：依次调用 /api/play、/api/pause、/api/play、/api/next、/api/previous。
• 预期结果：VideoPlugin 正确切换状态；WebSocket 推送 status_update；暂停时触发 ScreenPlugin 释放防息屏，恢复播放时重新加锁。

场景 3：按索引跳转视频

• 前置条件：播放列表长度 >= 3。
• 操作步骤：调用 POST /api/goto/2，随后调用 GET /api/status。
• 预期结果：当前索引变为 2；当前视频与目标条目一致；无越界异常。

场景 4：状态机触发器切换场景

• 前置条件：配置内存在多个 state/trigger 规则。
• 操作步骤：调用 POST /api/trigger/voice/name 或 WebSocket {"cmd":"trigger","name":"voice","value":"name"}。
• 预期结果：VideoPlugin 接收 Trigger；若状态变化则广播 StateChanged；HTTP/WebSocket 观察到 state_update。

场景 5：配置热重载

• 前置条件：当前配置文件合法，可修改显示或播放参数。
• 操作步骤：POST /api/config 提交合法 JSON；观察日志与 /ws；再次调用 /api/config。
• 预期结果：配置文件落盘；Manager 处理 ConfigReloadRequest 并广播 ConfigReloaded；VideoPlugin 与 HttpPlugin 更新内部状态；新配置立即可见。

场景 6：切换配置文件

• 前置条件：configs/ 下至少 2 个合法配置文件。
• 操作步骤：调用 GET /api/config/available，选择另一个配置后调用 POST /api/config/switch。
• 预期结果：目标配置通过校验后覆盖当前活动配置；系统广播配置重载；active 配置更新。

场景 7：视频文件上传与删除

• 前置条件：视频目录可写；准备 1 个小视频文件。
• 操作步骤：调用 /api/videos/upload 上传；调用 /api/videos 检查列表；随后调用 DELETE /api/videos/:filename。
• 预期结果：上传成功且文件可见；删除后列表消失；不会因文件名注入逃逸目录。

场景 8：文件管理器跨目录操作

• 前置条件：videos/、configs/、plugin_store/ 可访问；创建测试子目录。
• 操作步骤：调用 /api/files/:dir 浏览、mkdir 新建目录、upload 上传、move 移动、download 下载、delete 删除。
• 预期结果：仅允许受管目录；子路径校验生效；跨文件系统移动可回退到 copy+delete；非法路径返回拒绝。

场景 9：WiFi 扫描与状态查询

• 前置条件：实机具备 WiFi 网卡与 nmcli；附近存在可扫描网络。
• 操作步骤：调用 GET /api/wifi/scan；随后调用 GET /api/wifi/status。
• 预期结果：WiFiPlugin 返回去重后的网络列表；状态接口返回连接状态、SSID、IP；WebSocket 有 wifi_update。

场景 10：WiFi 连接成功

• 前置条件：准备可连接的测试 WiFi；账号密码正确。
• 操作步骤：调用 POST /api/wifi/connect；等待 1~10 秒后查询 /api/wifi/status。
• 预期结果：连接命令进入 WifiPlugin；返回成功消息；状态转为 connected；IP 地址可读。

场景 11：AP 热点启停

• 前置条件：设备支持热点模式。
• 操作步骤：调用 POST /api/wifi/ap/start；确认热点启动；随后调用 POST /api/wifi/ap/stop。
• 预期结果：热点名称和密码按请求生效；停止成功；兼容别名 /api/wifi/hotspot/*。

场景 12：BLE 配网成功链路

• 前置条件：BLE 在配置中启用；手机或测试脚本可写 GATT 特征；目标 WiFi 可用。
• 操作步骤：启动程序；通过 BLE 写入 SSID、密码、connect 命令；观察 BLE 状态特征、日志、WiFi 状态。
• 预期结果：BLE 将凭据转发为 WifiCommand::Connect；WifiPlugin 返回结果后 BLE 状态特征更新；HttpPlugin 反映 ble_update 与 wifi_update。

场景 13：WebSocket 实时控制链路

• 前置条件：WebSocket 已连接。
• 操作步骤：发送 play、pause、goto、trigger、connect、ap_start 命令 JSON。
• 预期结果：合法命令被解析为内部消息并入队；响应 {"ok":true}；状态更新推送到客户端。

场景 14：动态插件挂载与自测通过

• 前置条件：plugin_store/registry.json 指向一个合法动态插件版本；manifest 声明 capability 且自测通过。
• 操作步骤：启动程序；查看日志与插件状态接口。
• 预期结果：动态插件被加载、init、self_test、start；必需能力通过；插件状态显示 enabled。

场景 15：动态插件必需能力失败并自动回退

• 前置条件：准备 active 版本失败、stable 版本可回退的动态插件仓库；错误策略为 auto_rollback。
• 操作步骤：启动程序或发送触发失败的消息直至达到错误阈值。
• 预期结果：当前版本被禁用并触发回退；若稳定版本可重载则恢复运行；否则 needs_rollback=true 并记录日志。

场景 16：动态插件热替换恢复旧版本

• 前置条件：已加载动态插件；准备一个启动失败的新版本。
• 操作步骤：通过测试钩子或后续管理命令触发热替换。
• 预期结果：旧插件先 stop；新插件 init/start 失败后恢复旧插件；资源无双开窗口。

场景 17：Flutter App 首次连接与实时状态

• 前置条件：Flutter App 安装完成；手机与设备网络可达。
• 操作步骤：Flutter App 输入设备地址并连接；进入主控页；触发播放/暂停；保持 WebSocket 连接。
• 预期结果：App 能读取 /api/status、/api/playlist、/api/ble/status；能接收 status_update、state_update、wifi_update；UI 与设备状态一致。

场景 18：Flutter App 配网与 APK 下载入口

• 前置条件：HTTP 服务与下载目录启用；存在 downloads/showen-app.apk。
• 操作步骤：Flutter 通过 BLE 或 HTTP 执行配网；访问 App 下载信息接口；点击下载 APK。
• 预期结果：/api/app/info 返回正确版本、大小、下载地址；APK 下载成功；Flutter 侧配网链路完成且错误可回显。

8. 边界条件清单

• 1. 空 playlist 启动：/api/status、/api/videos、WebSocket 快照均不崩溃。
• 2. goto 越界：返回 400，不改变当前播放状态。
• 3. 上传 100MB 边界：恰好上限通过，超过上限返回 413。
• 4. 文件名包含 ..、/、\\：上传、下载、删除、配置切换均拒绝。
• 5. WiFi SSID/密码包含空格、引号、反斜杠、冒号：命令参数保真。
• 6. BLE 写入空 SSID 或空命令：状态特征返回错误，不向核心发送无效命令。
• 7. 动态插件 manifest id/version 与目录不匹配：加载应失败且不污染注册表。
• 8. 动态插件 required capability 缺失于自测结果：视为失败并按策略处理。
• 9. ConfigReloadRequest 指向损坏 JSON：Manager 记录失败，保留旧配置。
• 10. WebSocket 收到非法 JSON 或缺少 cmd：返回结构化错误字符串，不影响连接。
• 11. remote_control.enabled=false：HTTP 插件不启动监听，但系统其他插件正常工作。
• 12. 关闭中的广播消息：Shutdown 广播后所有启用插件按逆序停止。

9. 错误处理场景清单

• 1. HTTP 发送到关闭的消息通道：播放/WiFi/插件管理 API 返回 500。
• 2. WiFi 10 秒无响应：/api/wifi/* 返回 504。
• 3. WiFi 返回非 JSON：HTTP 层返回 502。
• 4. WiFi 返回 {ok:false}：HTTP 层透传为 500 业务错误。
• 5. 配置更新请求体非 UTF-8：返回 400。
• 6. 配置切换目标文件不存在：返回 404。
• 7. 文件下载缺少 path 参数：返回 400。
• 8. 文件移动目标已存在：返回 409。
• 9. 静态插件 init/start 失败：启动整体失败并退出。
• 10. 动态插件 init/start 失败：仅该插件禁用，其他插件继续运行。
• 11. 动态插件错误阈值达到上限：disable_and_log 时禁用；auto_rollback 时回退。
• 12. 热替换新插件启动失败：恢复旧插件；若恢复失败则明确标记 disabled。
• 13. BLE worker 崩溃：3 秒重试；停止信号下应及时退出。
• 14. /api/plugins* 命令当前无 Manager 闭环：应在 M1.2 先作为已知功能对齐缺陷立项验证并修复。

10. 性能基准定义

M1.2 不做深度优化，但必须建立可重复基准，供 M1.3 追踪。

• 启动时间：从进程启动到 http 与 video 均发出 PluginReady，目标 <= 3s（无动态插件时）。
• HTTP 控制延迟：POST /api/play 到首个 status_update，P95 <= 200ms。
• WebSocket 状态推送延迟：内部消息到客户端收到事件，P95 <= 150ms。
• 配置热重载耗时：POST /api/config 到 config_update 推送完成，P95 <= 500ms。
• WiFi 状态查询：单次 /api/wifi/status 完成时间 P95 <= 3s，超时阈值 10s。
• 视频上传：100MB 文件上传不出现进程 OOM，峰值 RSS 不超过基线版本 120%。
• 长稳冒烟：连续 4 小时播放 + WebSocket 连接 + 周期性 WiFi 状态查询，无崩溃、无句柄泄漏迹象。
• 动态插件回退：达到错误阈值到完成禁用/回退标记，P95 <= 1s（不含磁盘 I/O 抖动）。

11. 测试环境要求

11.1 ARM64 实机

• Linux ARM64。
• 安装 nmcli、BlueZ、OpenCV 运行时、websocat、curl。
• 具备显示输出、WiFi 网卡、BLE 适配器。
• 可访问测试路由器，并可创建 AP 热点。
• 支持动态插件 .so 装载与回退仓库读写。

11.2 CI 环境

• 运行 Rust 单元/集成测试。
• 使用 fake backend/fake plugin store 替代硬件。
• 执行 HTTP 路由级测试、消息序列化测试、ServiceManager 生命周期测试。
• 不承担真实 OpenCV 显示、真实 WiFi/BLE、真实动态 .so 装载回归。

11.3 Flutter 联调环境

• Android 真机优先，至少 1 台；若支持则补 1 台 iOS 设备做网络连通冒烟。
• Flutter App 使用与服务端同版本 API 模型。
• 同时验证 HTTP 轮询回退与 WebSocket 实时模式。

12. 自动化落地建议

• 新增 tests/m1_2_service_manager.rs：启动顺序、关闭顺序、广播、配置重载、动态插件错误策略。
• 新增 tests/m1_2_http.rs：播放/配置/文件/WiFi/BLE/插件管理 API 路由级验证。
• 新增 tests/m1_2_dynamic_plugin.rs：registry、manifest、热替换、回退、必需能力失败。
• 新增 scripts/e2e/：实机冒烟脚本，串联 curl + websocat + 日志断言。
• 新增 clients/flutter/integration_test/：设备发现、状态同步、WiFi 配网、配置保存。

13. 预估工作量与排期建议

13.1 工作量

• 测试基建与 fake fixture：2 人日。
• HTTP/ServiceManager 集成测试补齐：3 人日。
• 动态插件系统回退/热替换测试：2 人日。
• ARM64 实机 WiFi/BLE/视频链路验证：3 人日。
• Flutter 联调与回归：2 人日。
• 缺陷修复回归缓冲：2~4 人日。
• 合计：12~16 人日。

13.2 两周建议排期

• 第 1-2 天：补齐测试基建，冻结 M1.2 测试配置与样本数据。
• 第 3-5 天：完成 ServiceManager、HTTP、文件管理、配置热重载自动化测试。
• 第 6-7 天：完成动态插件系统自动化测试，并确认插件管理 API 闭环缺陷。
• 第 8-10 天：ARM64 实机执行视频/WiFi/BLE/Flutter E2E，集中提单。
• 第 11-12 天：修复缺陷并回归，补齐性能基线数据。
• 第 13-14 天：做旧版本功能对齐复盘、输出测试报告与遗留风险清单。

14. M1.2 完成判定

• 六个内置插件均有成功链路与失败链路验证证据。
• 动态插件系统完成加载、自测、禁用、回退、热替换验证。
• Flutter App 完成 HTTP/WebSocket/BLE 三条交互链路联调。
• 所有关键用户场景、边界条件、错误处理场景均有执行记录。
• 已知阻断性问题清零，或被明确降级并获负责人确认。