AY 手机维修检测设备（ROC-RK3308B-CC Plus）-嵌入式 Linux 手持设备 / 工业检测终端 UI 与本地服务联调

1、立项背景和目标
项目面向手机维修场景，在 Firefly ROC-RK3308B 手持板上提供本地操作界面，完成电池排线信息读取、底层修复、排线固件 OTA、WiFi/系统设置等检测业务。目标是：新板从零可部署、UI 可操作、与本地后端通过本机 HTTP 联通，形成「屏幕操作 → 本地服务 → 串口/云端」闭环。底层 Python 服务非本人从零开发，本人从拿到新板开始负责系统部署、UI 落地与端到端联调。

2、软件功能与核心模块
LVGL 人机界面：主菜单多业务入口（设置、电池修复、点阵/原彩/听筒/相机等）；设置页含 WiFi、系统升级入口、服务器/语言/亮度等。
rk_client 通信层：板端 C 通过 curl/HTTP 调用本机 127.0.0.1:8080 后端。
电池与排线：FPC 信息读取、底层修复任务与进度、排线固件列表查询与升级进度展示。
设置子系统：WiFi 扫描连接、亮度 PWM、语言/服务器持久化、界面主题与二级/三级菜单样式统一。
本地后端（联调对象）：FastAPI 提供健康检查、Apple/串口/FPC/云端固件列表等 API。

3、业务流程与功能路径
新板部署 → 启动 rk-backend 与 lvgl-ui → 主界面进入业务页 → UI 发 HTTP → 后端驱动串口/排线/云端 → 轮询进度并刷新界面。排线 OTA 路径：插 FPC → POST /fpc/firmware/list 取 sdk_key 与云端 packages → 用户选择后 upgrade → 轮询 progress。电池修复：选容量模式 → 创建任务 → 轮询 → 重启确认。设置路径：二级菜单 → 三级选择面板保存配置并即时预览（如亮度）。

1、整体架构与技术栈
整体为双进程本机架构：板端 LVGL + C（lvgl_board / rk_client） 负责显示与按键导航；本地 Python FastAPI（AY-RK3308） 负责串口协议、Apple 设备、云端 HTTP、FPC OTA。通信仅用本机 HTTP（8080），systemd 管理服务。UI 侧含页面管理、设置桥接、电池页与固件选择弹窗；后端含 controller/service/module/api 分层。部署路径 /opt/rk-backend、/usr/bin/lvgl_ui。本人不主写底层协议与云端封装，负责 UI 实现、接口对接、部署脚本使用与问题定位。

2、本人负责模块与结果（尽量量化）
从新板零环境完成 backend/UI 部署与冷启动联调（含低内存 pip、venv、双服务顺序）。
落地并完善设置模块：WiFi L3/L4、亮度/语言/服务器选择与持久化；统一二级/三级选中主题。
完成电池页排线固件选择与升级相关 UI，对接 /fpc/firmware/list、upgrade/progress；用终端 curl 验证电池/相机 FPC：读 key、云端空包与有包差异。
联调结论可复现：电池 sdk_key 可读、云端 packages=[]；相机 FPC 云端有包，证明链路通、差别在云端 catalog。
文档与命令沉淀：健康检查、list、进度查询等板端操作路径。

3、难点、坑与解决
新板资源紧：pip 装重依赖 OOM → 分批安装、swap、保留 venv 只换业务代码。
FPC list 与 UI 竞态：自动刷新与 list 抢串口导致偶发空 key → 取消读、等待空闲、弹窗期暂停刷新；字体缺字导致提示乱码 → 改短文案。
OTA target 易混：相机模块用 main，误用 camera 导致失败 → 用实测对照文档纠正。
「有声卡无声音」：软件链（aplay、LINEOUT、spk-ctl 播放时拉高）已通，判定硬件喇叭/功放问题，避免误改 boot。
云端空列表易误判为设备坏：对比相机有包/电池无包，定位为 sdk_key 对应 catalog 为空。