refactor: 按角色分层目录, HTML 不再平铺根目录

根目录原本平铺 7 个 HTML, 而 js/ 已按功能域分子目录, 两级结构不对称;
且自包含实验页与主功能页平级摆放, 看不出可随时删除。现按角色分三层:

  tabs.html  标签外壳留在根 = 工具入口
  pages/     index / can / can_monitor / motor  主功能页
  lab/       continuity_test / spi_test  自包含实验页(零外部依赖)
  scripts/   build_mem.bat

随迁修正(全部实跑验证):
- pages/ 下 4 页共 22 处 css/js 引用加 ../ 前缀; 页面互链同目录无需改
- js/motor/main.js 的 Worker URL 改用 import.meta.url 解析: 原文档相对
  路径 "js/motor/tick.worker.js" 在 pages/ 下会解析成 /pages/js/... 而
  404, 静默退化到 setTimeout 兜底、丢失后台不节流能力(已验证旧写法 404)
- tabs.html 的 TABS 登记新路径; pageToTab 改按文件名匹配, 旧版
  localStorage 存的裸文件名(can.html)自动迁移到 pages/can.html
- esp32_server.py: GET / 与 /index.html 302 到 /tabs.html(根下已无
  index.html); 注入脚本的 ⌂ 主页判定基准由 index.html 改为 tabs.html
- serve.bat 打印外壳与 OTA 页新地址; README 补目录结构与路径约定

验证: 39/39 静态资源 200, 7 页 200 且注入生效, 逐页解析引用 0 坏链,
路由 / 与 /index.html 302、未知页 404, node --check 与 py_compile 通过。
This commit is contained in:
cbb
2026-09-03 21:51:17 +08:00
parent d2c86c425a
commit 31b90f68b3
12 changed files with 89 additions and 50 deletions
+26 -9
View File
@@ -20,33 +20,50 @@
同款结构。pywebview 窗口没有地址栏与刷新按钮,因此服务器会向 HTML 响应注入
`_reload.html`(右下角 ⟳ 悬浮按钮 + F5/Ctrl+R 拦截)。
`build_mem.bat` 是从 Git Bash 调用 ESP-IDF 构建 `DCU/ESP32_COMM` 的辅助脚本
`build_mem.bat`(在 `scripts/`)是从 Git Bash 调用 ESP-IDF 构建 `DCU/ESP32_COMM` 的辅助脚本
(会先清掉 MSYS 环境变量绕过 IDF 的 MSys 检测)。
## 目录结构
```
tabs.html 标签外壳 = 工具入口(GET / 会 302 到这里)
pages/ 主功能页,各自引用 ../css 与 ../js
lab/ 自包含实验页,零外部依赖,删文件即可移除
css/ js/ 共享样式与 ES module
scripts/ 构建辅助脚本
esp32_server.py 本地页面服务 + 桌面窗口外壳
esp32_app.vbs esp32_web.vbs serve.bat 三个启动入口
```
## 页面
`tabs.html` 是单窗口多标签外壳,用 iframe 承载下列功能页,激活标签记忆在
`localStorage` 的 `dcu_tab`:
`localStorage` 的 `dcu_tab`(按文件名匹配,与目录层级无关):
| 页面 | 用途 | 主要脚本 |
|------|------|----------|
| `index.html` | OTA 中继控制台(ESP32 WiFi OTA / GD32 relay / BLE OTA) | `js/app.js`、`js/ota/*`、`js/ble_ota.js`、`js/ble/*` |
| `can.html` | CAN 通信(DBC 解析、消息编辑与批量发送) | `js/can.js`、`js/can/*` |
| `can_monitor.html` | CAN 接收监控 | `js/can_monitor.js` |
| `motor.html` | 电机控制台(CAN FD) | `js/motor/main.js`、`js/motor/tick.worker.js` |
| `continuity_test.html` | LAN9252 通断测试(自包含,含 WebGL 液态玻璃效果) | 内联 |
| `spi_test.html` | 【临时功能 SPI-SPEEDTEST】SPI 链路测速,完全自包含,删文件即可移除 | 内联 |
| `pages/index.html` | OTA 中继控制台(ESP32 WiFi OTA / GD32 relay / BLE OTA) | `js/app.js`、`js/ota/*`、`js/ble_ota.js`、`js/ble/*` |
| `pages/can.html` | CAN 通信(DBC 解析、消息编辑与批量发送) | `js/can.js`、`js/can/*` |
| `pages/can_monitor.html` | CAN 接收监控(独立页;也被 `can.html` 内嵌复用) | `js/can_monitor.js` |
| `pages/motor.html` | 电机控制台(CAN FD) | `js/motor/main.js`、`js/motor/tick.worker.js` |
| `lab/continuity_test.html` | LAN9252 通断测试(自包含,含 WebGL 液态玻璃效果) | 内联 |
| `lab/spi_test.html` | 【临时功能 SPI-SPEEDTEST】SPI 链路测速,完全自包含,删文件即可移除 | 内联 |
## 目录约定
- `css/` —— `base`(变量/基础)、`layout`、`components`、`can`、`motor`、`responsive`。
- `js/common/` —— 跨页公用:`base-url`(设备 IP)、`connection`、`polling`、`log`、`toast`、`utils`、`heap-low-history`。
- `js/ota/`、`js/ble/`、`js/can/`、`js/motor/` —— 按功能域拆分的 ES module。
- `js/ota/`、`js/ble/`、`js/can/`、`js/motor/` —— 按功能域拆分的 ES module,跨域引用只走 `js/common/`。
- 子系统配色:ESP32 = 青绿 · GD32 = 琥珀 · BLE = 蓝 · CAN = 绿 · 内存/调试 = 紫。
## 改动须知
- **改 CSS/JS 后必须 bump 引用处的 `?v=` 缓存版本**,否则浏览器会加载旧代码。
- `pages/` 与 `lab/` 下的页面引用共享资源要用 `../css/`、`../js/` 前缀;
**JS 模块内部引用其他资源(如 Worker)须用 `import.meta.url` 解析**,
不能写文档相对路径,否则页面换层级就会 404(见 `js/motor/main.js` 的 `TICK_WORKER_URL`)。
- 新增功能页放 `pages/`,并在 `tabs.html` 的 `TABS` 数组登记;
一次性/实验页放 `lab/` 并保持自包含。
- OTA 流程以设备端为真相来源:WiFi OTA 由设备回读分区算 SHA-256 后自动重启;
BLE OTA 由前端发 `0xF8 + 32B SHA-256`、设备端比较并通过 FINISH 事件报结果
(前端不做 SHA 预比较);GD32 relay 状态以 `/system/status` 为准。