小龙虾
33b41fd50a
添加了完整的前端架构约定文档 (frontend_architecture.md)， 包含以下主要内容： - 架构总览：Web资源本地托管方式和零构建方案 - 页面薄入口范式：HTML结构与ES Modules入口约定 - JS分层架构：common/ota/ble/can/motor等目录结构说明 - 缓存戳约定：版本管理强制要求 - 公共层API契约：baseUrl/toast/polling等接口规范 - motor页特殊性：独立主题和轮询链路处理 - 红线区域：不可动代码范围说明 - 回归清单：各页面功能验证checklist 同时移除了build相关的临时文件
5.3 KiB
5.3 KiB
前端架构约定与回归清单（tools/ Web 界面）
2026-07 网页框架化重构产物。本文档固化 tools/ 目录的模块化约定， 所有新增页面/模块必须遵循；同时提供改动后的回归验证清单。
1. 架构总览
- 托管方式：Web 资源不嵌入固件，由
tools/serve.bat（python -m http.server 8080）本地托管； 浏览器跨源调用 ESP32 REST API（路由表见main/server/wifi_ota.cppkHttpRoutes）。 改动 web 文件无需重编译固件。 - 零构建：原生 ES Modules，无打包器/无 CDN 依赖；页面必须经 http 访问（ES module 有 file:// CORS 限制）。
页面薄入口范式
每个页面 = HTML（纯结构，无内联 script/style/事件）+ 单个 type="module" 入口：
| 页面 | 入口 | 说明 |
|---|---|---|
| index.html | js/app.js + js/ota/console-mode.js + js/ble_ota.js | OTA 控制台（WiFi/BLE 双通道，三入口历史原因保留） |
| motor.html | js/motor/main.js | 电机控制台（独立 seed 主题，见 §4） |
| can.html | js/can.js | CAN 工具 |
| can_monitor.html | js/can_monitor.js | CAN 接收监控 |
JS 分层
js/
├── common/ 跨页面公共层：base-url(IP存取) / toast / log / polling / connection / utils
├── ota/ OTA 状态机与上传流程（高风险区，见 §5）
├── ble/ BLE OTA 传输时序（高风险区，见 §5）
├── can/ CAN 子系统（dbc 为基础层，导出共享 state/el）
├── motor/ 电机控制台
└── *.js 页面入口（薄装配层）
2. 缓存戳约定（强制）
- JS 间 import 一律不带
?v=——同一模块带不同 query 会被浏览器实例化两次， 导致模块级单例（state/toast 去抖等）分裂。 - 版本戳只出现在 HTML 的
<script>/<link>标签上；改动任何 JS/CSS 后， 必须更新对应页面入口标签的?v=（格式?v=YYYYMMDD<字母>），否则浏览器可能混载新旧模块。
3. 公共层 API 契约
common/base-url.js：设备 IP 唯一存取点（localStoragedcu_esp_ip，OTA/CAN/电机页共用）。 页面特有回退（CAN 页el.toolIp、OTA 页#espIp输入框）由各自入口在此基础上包装， 不得绕过它直接读写 localStorage。common/toast.js：单例 toast（#toast/#toastIco/#toastMsg+ components.css 样式）， 内置 5s 去重。适用于 index/can/can_monitor；motor 页因独立主题使用自有堆叠式 toast（§4）。common/polling.js：递归 setTimeout 轮询 + in-flight 守卫 + Page Visibility 补偿。 依赖 app.js 先挂载 window.OtaSessionState 等（见文件头注释的 window.* 清单），加载顺序不可变。- index.html 按钮事件：统一
data-action/data-arg属性 + app.js 末尾的事件委托， 禁止新增内联 onclick；window.* 函数挂载保留（polling/ota 模块间仍经 window 总线）。
4. motor 页特殊性
- 独立视觉主题（seed tokens，
css/motor.css），不引入 base.css/components.css （两者与 motor.css 存在.btn/.toast/.toolbar等同名类，混用会破坏视觉）。 - 自有堆叠式 toast（
#toastContainer，多条并存），与 common/toast.js 的单例 DOM 契约不同， 不做统一。 - 三条轮询链路（/motor/state、/can/feedback、/system/status）必须互不阻塞 （服务端约束，见 wifi_ota.cpp 注释）。
5. 红线（不可动区域）
js/ble/*：Web Bluetooth 包发送时序、重试退避、FINISH 中止——大量真机实测调优。js/ota/{session,stages,progress,upload-esp32,upload-gd32}.js：OTA 状态机与 window.* 状态总线（activePhase/otaSessionState/currentOtaTarget 等）。- index.html 视觉：shimmer / logoPulse 动画（css/responsive.css，仅 transform/opacity）不得削弱。
- 性能规范：高频更新走增量渲染 + write-before-compare + rAF 批量；CSS 动画仅 transform/opacity。
6. 回归清单
验证方式：tools/serve.bat 启动 → 浏览器打开 http://localhost:8080/<页面> → 真机 IP 连接。
index.html（OTA 控制台）
- WiFi/BLE 模式切换、GD32/ESP32 目标切换（顶部按钮）
- 固件选择：点击/拖拽上传区、清除按钮、SHA-256 显示、FSAPI 热重载
- ESP32 上传 → 阶段流程条驱动 → 重启 → 版本核对
- GD32 OTA relay → 进度/阶段 → 完成 toast
- 日志面板：过滤、自动滚动、清空；JSON 状态面板；任务排序
- 断线/重连：连接胶囊状态、"测试"按钮、重启 ESP32 按钮
- 视觉：shimmer/logoPulse 动画正常，无掉帧
- BLE 模式：连接、一键刷写、中止、清除文件、拖拽选文件
motor.html（电机控制台）
- 三条轮询链路存活（节点列表 1Hz 刷新、状态栏 RX/TX、健康检查）
- 控制指令发送、周期重发、模式切换、PID 配置
- 版本查询、NodeID 设置、电机 OTA relay
- 输入持久化（刷新后回填）、波形显示、console 无报错
window.phaseDebug调试句柄可用
can.html / can_monitor.html
- DBC 导入/解析/合并、报文列表/信号编辑、发送（单发/批量/手动）
- 发送历史、会话持久化、接收监控（独立页 + 抽屉）
- toast 仅弹一次（无双实例重复弹）