From 33b41fd50aa60d2cdf792899fe5db7e8dd99e3ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E9=BE=99=E8=99=BE?= Date: Mon, 27 Jul 2026 01:50:48 +0800 Subject: [PATCH] =?UTF-8?q?docs(frontend):=20=E6=B7=BB=E5=8A=A0=E5=89=8D?= =?UTF-8?q?=E7=AB=AF=E6=9E=B6=E6=9E=84=E7=BA=A6=E5=AE=9A=E4=B8=8E=E5=9B=9E?= =?UTF-8?q?=E5=BD=92=E6=B8=85=E5=8D=95=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加了完整的前端架构约定文档 (frontend_architecture.md)， 包含以下主要内容： - 架构总览：Web资源本地托管方式和零构建方案 - 页面薄入口范式：HTML结构与ES Modules入口约定 - JS分层架构：common/ota/ble/can/motor等目录结构说明 - 缓存戳约定：版本管理强制要求 - 公共层API契约：baseUrl/toast/polling等接口规范 - motor页特殊性：独立主题和轮询链路处理 - 红线区域：不可动代码范围说明 - 回归清单：各页面功能验证checklist 同时移除了build相关的临时文件 --- docs/frontend_architecture.md | 96 + ...es__idf_main.dirmonitordebug_log.cpp.obj.d | 180 - ...df_main.dirmonitorhealth_monitor.cpp.obj.d | 180 - ...ort.dir____maintransportprotocol.cpp.obj.d | 165 - tools/can.html | 2 +- tools/can_monitor.html | 2 +- tools/css/motor.css | 670 ++++ tools/index.html | 40 +- tools/js/app.js | 49 + tools/js/can.js | 19 +- tools/js/can/dbc.js | 16 +- tools/js/can/messages.js | 8 +- tools/js/can/persist.js | 2 +- tools/js/can/send.js | 12 +- tools/js/can/signals.js | 6 +- tools/js/can_monitor.js | 2 +- tools/js/common/base-url.js | 34 + tools/js/motor/main.js | 2650 +++++++++++++ tools/motor.html | 3349 +---------------- 19 files changed, 3555 insertions(+), 3927 deletions(-) create mode 100644 docs/frontend_architecture.md delete mode 100644 esp-idfmainCMakeFiles__idf_main.dirmonitordebug_log.cpp.obj.d delete mode 100644 esp-idfmainCMakeFiles__idf_main.dirmonitorhealth_monitor.cpp.obj.d delete mode 100644 esp-idftransportCMakeFiles__idf_transport.dir____maintransportprotocol.cpp.obj.d create mode 100644 tools/css/motor.css create mode 100644 tools/js/common/base-url.js create mode 100644 tools/js/motor/main.js diff --git a/docs/frontend_architecture.md b/docs/frontend_architecture.md new file mode 100644 index 0000000..fa1cc9b --- /dev/null +++ b/docs/frontend_architecture.md @@ -0,0 +1,96 @@ +# 前端架构约定与回归清单（tools/ Web 界面） + +> 2026-07 网页框架化重构产物。本文档固化 tools/ 目录的模块化约定， +> 所有新增页面/模块必须遵循；同时提供改动后的回归验证清单。 + +## 1. 架构总览 + +- **托管方式**：Web 资源不嵌入固件，由 `tools/serve.bat`（`python -m http.server 8080`）本地托管； + 浏览器跨源调用 ESP32 REST API（路由表见 `main/server/wifi_ota.cpp` kHttpRoutes）。 + 改动 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 的 ` + diff --git a/tools/can_monitor.html b/tools/can_monitor.html index af048df..44b15d2 100644 --- a/tools/can_monitor.html +++ b/tools/can_monitor.html @@ -182,6 +182,6 @@ 操作成功 - + \ No newline at end of file diff --git a/tools/css/motor.css b/tools/css/motor.css new file mode 100644 index 0000000..44c9f52 --- /dev/null +++ b/tools/css/motor.css @@ -0,0 +1,670 @@ +/* motor.css - 电机控制台页面样式 + * 由 motor.html 内联 + @@ -847,7 +179,7 @@ label { display: block; }
硬件版本
--
Bootloader
--
-

请求/回报共用 0x000-00FF（同 ID）· DLC 24 · YYYY.MM.DD ×3 (soft/hard/boot) · GD32 解析后 0xC6 同步

+

请求/回报共用 0x000-00FF（同 ID）· DLC 24 · major.minor.patch.build ×3 (soft/hard/boot，DBC v0.71) · GD32 解析后 0xC6 同步

@@ -1011,2681 +343,6 @@ label { display: block; }
- + \ No newline at end of file