同步移动端工程、设备控制改进与发布资料

核桃派软件源代码/README.md

@@ -4,6 +4,10 @@
 
 ## 路径与运行方式
 
+移动端控制器独立维护，入口见 `../移动端相关内容/README.md`；设备侧新增契约见 `../整体开发需求/03_移动端接入需求.md`。设备更新只评估并登记手机兼容影响，不自动迭代 App。BLE 与网页应复用公共业务层；不得让 App 依赖网页布局。当前蓝牙接入尚待实现，既有脚本仍执行原禁用策略，不能将需求文档当成设备已启用蓝牙。
+
+普通前端／BLE 入口改动不新增实屏视觉验收。确需视觉检查时先停止、解释原因、询问用户如何启动并等待指示，不自动开摄像头、DroidCam 或视觉程序，不主动切换实屏测试图案。软件统计和逻辑帧检查按正常自动测试执行。
+
 下列源码运行、编译和手工部署命令均在本文件所在的 `核桃派软件源代码/` 目录执行；发布命令另行标明从工作区根目录执行。Windows 本机测试使用根目录下 `测试相关资料/如何测试/本机测试环境/README.md` 的命令。
 
 - 程序：`/opt/matrix-screen-controller`
@@ -78,6 +82,8 @@ sudo sh scripts/update_walnutpi.sh
 
 ## 浏览器全量 OTA
 
+OTA 会记录更新前的候选内核、cpufreq 和性能模式状态。原本正常的设备若在更新中失去这些能力，应用更新按事务回滚；原本已回退到原内核的设备允许先更新应用。更新完成后，若已安装的候选 Image、两份 DTB、模块树、受管启动脚本和健康服务均与登记材料一致，独立任务仅安排一次候选重启；结果保存在持久根的 `kernel-recovery.json`，通过 `/api/ota/status.kernel_recovery` 查询。失败后不会在后续 OTA 自动重试。缺失或损坏候选材料时只提示需要专用内核修复包，普通 OTA 不携带大型内核归档。
+
 系统设置显示 `VERSION` 中的正式软件版本和 `FEATURE_UPDATED_AT` 中固定的北京时间，并允许上传完整 `.ota` 文件。页面不展示最近 OTA 结果，但上传、安装、断线恢复和失败反馈保持可见；失败后会自动打开可滚动、可复制的完整诊断日志，关闭后仍可重新查看或复制。设备只在 `/var/lib/matrix-screen-controller/ota/last-failure.log` 原子保留最近一份不超过 1 MiB 的脱敏失败日志，下一次成功更新会将其删除；`GET /api/ota/failure-log` 仅在最近结果失败且日志存在时返回 `text/plain`，并禁止缓存。设备不连接更新服务器，不使用增量、加密或签名；包内 SHA-256 只检查文件损坏。同版和旧版在停服前拒绝，新版失败自动恢复更新前程序与用户数据。
 
 从 1.0.3 首次升级到包含该能力的版本时，安装过程仍由 1.0.3 的旧 worker 控制，因此新日志页面只能在升级成功后使用。新版本测试入口兼容旧 worker 传入的隔离变量，并将 pytest、应用数据、运行数据和 Python 临时文件全部约束到 OTA 事务目录；它不会为安装日志功能而忽略测试失败或绕过原子回滚。