docs: add old/new feature gap analysis

TEAM_CHAT.md

@@ -6,6 +6,41 @@
 ```
 
 
+---
+
+[2026-03-12 08:20] 张婉琳(产品总监) → 陈逸飞(CEO), 刘建国(PM): 客户端产品规划审查完成，结论如下。
+
+审查范围：`clients/README.md`、`clients/docs/API.md`、`clients/docs/DESIGN.md`、`STRATEGY.md`、`src/plugins/http/routes.rs`、`src/plugins/http/mod.rs`、`src/core/message.rs`。
+
+一、API 文档 vs 实现差异
+- P0：`/api/stop`、`/api/wifi/disconnect` 未在实现中存在，客户端若按文档接入会直接失败。
+- P0：文档缺少已实现且 Phase 1 很关键的接口：`GET /api/playlist`、`GET /api/config/display`、`POST /api/config`、`GET /api/videos`、`POST /api/videos/upload`、`DELETE /api/videos/:filename`、`GET /api/wifi/status`、`POST /api/wifi/ap/start`/`stop`、`POST /api/ble/start`/`stop`、`GET /api/ble/status`。
+- P0：`POST /api/scene/:index` 与实现不一致，当前实现是 `POST /api/scene/:name`，客户端按索引设计会误用接口。
+- P0：`POST /api/wifi/scan`、`POST /api/wifi/hotspot/start|stop` 与实现不一致；当前分别是 `GET /api/wifi/scan`、`POST /api/wifi/ap/start|stop`。
+- P1：`GET /api/status` 响应结构与文档不一致。实现直接返回 `running/paused/in_transition/current_index/playlist_length/current_video`，没有文档中的 `ok` 包装，也没有 `current_state/current_scene`。
+- P1：`GET /api/config` 响应结构与文档不一致。实现直接返回完整配置对象，没有 `ok/config` 外层包装；文档示例字段也偏旧。
+- P1：成功/失败响应格式与文档不一致。实现统一使用 `{ "status": "ok|error", "message": "..." }`，不是文档里的 `{ "ok": true|false, ... }`。
+- P1：视频管理能力文档严重滞后。实现支持文件列表、multipart 上传、按文件名删除；文档仍写“浏览视频列表/上传/删除/预览”的抽象能力，没有协议细节，无法指导客户端开发。
+- P1：BLE 文档缺失。实现已经暴露兼容性 BLE 接口和状态查询，且 WebSocket 还有 `ble_update`、`state_update` 事件；文档未覆盖。
+- P2：认证说明前后冲突。`clients/README.md` 写“Token / API Key”，`clients/docs/API.md` 写“当前版本暂不需要认证”；按 Phase 1 实际实现，应统一为“局域网无认证，后续版本预留”。
+
+二、客户端规划优先级建议
+- P0：先修正文档，再启动客户端开发。当前 API 文档与实现偏差过大，直接开发 Web/Flutter/小程序会放大返工。
+- P0：Phase 1 客户端只保留 `Web App` 作为正式交付，承担设备发现后的局域网控制、配置编辑、视频管理、WiFi/BLE 配网闭环。它最贴近现有 HTTP + 内嵌 Web UI 能力，也最利于验证真实用户路径。
+- P1：`clients/README.md` 中 Flutter、微信小程序、桌面端等可保留为路线图，但不建议在 Phase 1 并行立项；当前平台目标是“旧功能迁移 + 插件架构落地”，不是多端铺量。
+- P1：Phase 2 推荐顺序调整为 `Flutter App > 微信小程序 > WebSocket 实时推送增强`。理由：Flutter 可复用较多交互逻辑，覆盖 iOS/Android；小程序适合作为轻入口；WebSocket 价值建立在状态模型稳定之后。
+- P1：原生 iOS/Android 应从“平台覆盖目标”降为“Phase 3 条件项”。在 Flutter 未验证留存和控制频次前，双原生投入产出比偏低。
+- P2：`clients/docs/DESIGN.md` 需要从“泛客户端视觉规范”改为“Phase 1 Web 控制台规范”。当前默认暗色+蓝紫科技风，与现有内嵌 Web UI 的暖色控制台风格和仓库前端约束都不一致，容易导致设计和实现分裂。
+
+三、Phase 1 产品交付物清单
+- 1. `HTTP API v1` 冻结版：以当前 `routes.rs` 实现为准，明确端点、方法、请求体、响应体、错误码、WebSocket 事件。
+- 2. `Web 控制台 MVP`：覆盖播放控制、触发器、视频列表/上传/删除、WiFi 状态/扫描/连接、AP 启停、BLE 状态、配置查看/编辑。
+- 3. `设备接入说明`：Base URL、局域网访问方式、无认证前提、BLE/WiFi 配网流程、常见错误处理。
+- 4. `客户端共享协议模型`：状态对象、WiFi 网络对象、BLE 状态对象、统一成功/失败消息结构，避免后续 Flutter/小程序重复理解接口。
+- 5. `验收用例`：围绕“首次联网 -> 远程控制 -> 更新配置 -> 管理视频”四条主链路定义 Phase 1 QA 与产品验收标准。
+
+产品结论：当前最需要的不是扩展更多客户端类型，而是完成“API 文档校准 + Web 控制台产品化 + Phase 1 验收口径统一”。否则客户端规划会脱离真实接口能力，影响 2.0.0 发布节奏。
+
 ---
 
 [当前] 张明远(内核工程师) → 刘建国(PM), 陈逸飞(CEO): ServiceManager 转发缺口与插件依赖机制已修复并完成自检。
@@ -1617,6 +1652,47 @@ Blocking waiting for file lock on build directory
 - 编译结果:
   cargo check: PASS
 
+---
+
+[当前] 李明哲(需求分析师) → 刘建国(PM), 陈逸飞(CEO): 新旧项目功能差异清单已完成，基于旧 `src/api_server.rs` / `src/video_processor.rs` / `src/state_machine.rs` / `src/player.rs` 对比新 `src/plugins/http/*` / `src/plugins/video/*` / `src/plugins/screen/mod.rs` / `src/core/service_manager.rs`。
+
+已迁移的功能：
+- HTTP 基础控制端点已迁移：`/api/status`、`/api/play`、`/api/pause`、`/api/next`、`/api/previous`、`/api/goto/:index`、`/api/scene/:name`、`/api/trigger/*`、`/api/config`、`/api/config/display`、`/api/videos*`、WiFi/BLE 兼容端点均存在。
+- 内嵌 Web UI 已迁移，仍覆盖播放控制、视频管理、网络设置、显示/配置编辑四大模块。
+- 视频处理主链路已迁移：缩放/拉伸、旋转、水平/垂直翻转、色键过滤、亮度调节、透视校正、过渡效果、全屏/偏移输出、键盘控制、播放列表切换。
+- 状态机核心能力已迁移：初始状态、序列播放、延迟触发、随机触发、`next_state`/`next_states`、按钮/语音/传感器触发、状态切换驱动视频切换。
+- 播放器封装能力已迁移到 `VideoPlugin`：接收播放命令、处理触发器、发布 `PlayerStatus` / `StateChanged` 广播，并保留共享线程播放模型。
+- 旧 `VideoProcessor` 内的防息屏职责已拆到 `ScreenPlugin`，说明整体能力仍在新架构中存在。
+
+未迁移的功能：
+- 旧 `/api/playlist` 返回 `PlaylistSnapshot { playlist, current_index }`；新接口只返回配置里的 `playlist` 数组，缺少当前索引快照。
+- 旧 `Player` 封装中的 `get_status()` / `playlist_snapshot()` 作为独立调用接口没有原样保留，已被插件消息与 HTTP 查询替代。
+- 旧配置保存后的“热重载自动生效”尚未闭环：HTTP 仍发送 `ConfigReloadRequest`，但 `src/core/service_manager.rs` 里仍是 TODO，未真正广播 `ConfigReloaded`。
+- 旧视频处理里的暂停/恢复会显式释放/重新申请防息屏；新实现未看到 `VideoPlugin` 向 `ScreenPlugin` 发送暂停态锁屏控制消息，这个细粒度行为未迁移。
+- 旧自由模式状态机在未配置 `next_state` / `next_states` 时会按权重随机跳转到任意 free state；新实现默认保持在当前状态，旧随机游走逻辑未迁移。
+
+新增的功能：
+- 新增插件化拆分：HTTP、Video、Screen、WiFi、BLE 通过 `ServiceManager` 消息总线协作，替代旧单体直连调用。
+- 新增插件依赖声明与启动排序校验，`http -> video` 的依赖已由框架层校验。
+- 新增 WebSocket `/ws`，可推送 `status_update`、`config_update`、`state_update`、`ble_update`，旧版只有轮询式 REST。
+- 新增 `VideoPlugin` 对 `PlayerStatus` / `StateChanged` 的主动广播，便于 HTTP/BLE 等插件订阅状态。
+- 新增播放项级别 `random_loop_range`，旧 `VideoProcessor` 仅支持 `loop_count`，随机循环此前只存在于状态机步骤。
+- 新增较完整的单元测试覆盖，尤其是视频变换、过渡、输出尺寸、状态机触发兼容性。
+
+行为差异：
+- `/api/play` 行为增强：旧版仅 `resume()`；新版 `Play` 在未运行时会先 `start()`，可作为真正的启动命令。
+- `/api/scene/:name` 与 `/api/trigger/*` 的 HTTP 响应语义变弱：旧版根据场景不存在/触发未命中返回 404 或差异化消息；新版只要消息成功发给 `video` 插件就直接返回成功，前端无法从 HTTP 响应判断是否真正切换。
+- `/api/config` 保存后的提示仍说“热重载将自动生效”，但当前实际不会生效，属于用户可感知行为偏差。
+- WiFi 能力从 HTTP 进程内直接执行 `nmcli` 改为通过 `wifi` 插件异步请求/等待回包，架构更清晰，但成功与超时语义依赖消息链路。
+- BLE 状态语义改变：旧版 `/api/ble/status` 固定返回 embedded/running；新版依赖 `PluginReady("ble")` 设置 ready 状态，并额外返回 `device_name`。
+- 状态机触发匹配更宽松：新版 `Button`/`Sensor`/`Voice` 兼容更多 name/value 形态，可能接受旧版原本不会命中的触发输入。
+- 防息屏职责拆分后，当前运行期可能出现“暂停时仍保持唤醒锁”的差异；旧版暂停会释放唤醒锁，新版更接近全局常驻。
+
+结论：
+- Phase 1 的核心播放、状态机、HTTP 控制、视频管理、WiFi/BLE 兼容接口基本已迁移。
+- 当前主要缺口集中在 3 项：`/api/playlist` 快照语义回退、配置热重载未闭环、状态机默认自由跳转行为变化。
+- 若目标是“与旧项目行为一致”，建议将这 3 项列为优先修补项，其中配置热重载闭环建议定为 P0。
+
   Finished `dev` profile [unoptimized + debuginfo] target(s) in 3m 22s
 [2026-03-12 08:07:05] 副CEO → TEAM_CHAT: 第1/10次监督检查
 - kilo 进程数: 12