ESP32_COMM/.trae/specs/split-tools-into-modules/spec.md

# tools 网页工程化拆分 Spec

## Why
`tools/` 目录下 4 个核心文件（`app.js` 2371 行、`ble_ota.js` 1658 行、`can.js` 1526 行、`style.css` 2146 行）体积过大，单文件承载多重职责，难以维护和导航。`index.html` 还内联了 ~250 行胶水脚本。需要按职责拆分为小文件工程，提升可维护性。

## What Changes
- 将 `style.css` 拆分为 5 个按职责划分的 CSS 文件（base / layout / components / can / responsive）
- 将 `app.js` 拆分为 8 个 ES Module（ota/session、progress、stages、file-handle、upload-esp32、upload-gd32、spi、console-mode）+ 公共模块
- 将 `ble_ota.js` 拆分为 8 个 ES Module（ble/constants、state、stages、gatt、file、transfer、verify、session）
- 将 `can.js` 拆分为 5 个 ES Module（can/dbc、messages、signals、send、feedback）
- 抽取 `index.html` 内联 `<script>` 到 `js/ota/console-mode.js`
- 抽取跨页面共享的工具函数到 `js/common/`（utils、toast、log、connection、polling）
- 三个 HTML 页面的 `<script>` 改为 `type="module"`，`<link>` 拆分为多文件引用
- 删除原始大文件，用薄入口文件（`js/app.js`、`js/ble_ota.js`、`js/can.js`）替代

## Impact
- Affected code: `tools/` 目录全部文件（`app.js`、`ble_ota.js`、`can.js`、`can_monitor.js`、`style.css`、`index.html`、`can.html`、`can_monitor.html`）
- 不影响 ESP32 固件代码（`main/` 目录不改动）
- `serve.bat` 无需修改（Python http.server 天然支持 ESM 的 MIME 类型）
- **BREAKING**：旧的单文件引用路径（`app.js?v=...`）将不存在，HTML 中所有 `<script src>` 和 `<link href>` 路径需更新

## 技术方案

### 模块组织：原生 ES Modules
- 使用 `<script type="module">` + `import`/`export`，零构建、零工具链依赖
- `serve.bat`（Python http.server）无需修改，浏览器原生解析 ESM
- 所有 `import` 路径必须带 `.js` 后缀（浏览器 ESM 规范要求）

### HTML 内联事件处理器兼容策略
当前 HTML 大量使用 `onclick="funcName()"` 内联处理器。ES Module 作用域非全局，采用以下策略：
1. **内部函数**：模块内使用，不暴露到全局
2. **HTML 引用函数**：在入口模块中显式挂载到 `window`（如 `window.setConsoleMode = setConsoleMode`）
3. 模块脚本默认 `defer`，DOM 解析完成后执行，用户点击前 `window` 上的函数已就绪

### CSS 拆分策略
- 多 `<link>` 标签并行加载（优于 `@import` 串行）
- 每个页面引入相同的 5 个 CSS 文件（base + layout + components + responsive 为全站共用，can 为 CAN 页面专用但 OTA 页面也引用了 CAN 入口卡片样式）

### 目标目录结构
```
tools/
├── index.html                  # 结构 only，<script type="module" src="js/app.js"> + js/ble_ota.js
├── can.html                    # <script type="module" src="js/can.js">
├── can_monitor.html            # <script type="module" src="js/can_monitor.js">
├── serve.bat                   # 不变
├── css/
│   ├── base.css                # :root 变量、reset、container、背景纹理
│   ├── layout.css              # header、main-layout、cards、forms、buttons、conn-indicator
│   ├── components.css          # upload-zone、file-info、progress、stage-flow、badges、metrics、log-panel、toast、heap
│   ├── can.css                 # CAN workspace + monitor 专用样式
│   └── responsive.css          # @media 响应式 + @keyframes 动画
└── js/
    ├── app.js                  # 薄入口：import ota/* + common/*，挂载 window 函数
    ├── ble_ota.js              # 薄入口：import ble/*，导出 window.bleOta
    ├── can.js                  # 薄入口：import can/*，初始化 CAN 工具
    ├── can_monitor.js          # CAN 监控入口（小文件，引用 common 模块）
    ├── common/
    │   ├── utils.js            # formatBytes / formatTime / formatUptime / escapeHtml / sanitizeHtml
    │   ├── toast.js            # showToast
    │   ├── log.js              # addLog + 环形缓冲 + 去重 + 自动滚动
    │   ├── connection.js       # testConnection + 连接状态指示器更新
    │   └── polling.js          # 状态/日志轮询调度 + Page Visibility 补偿
    ├── ota/
    │   ├── session.js          # OTA 会话状态机（OtaSessionState + 转换 + 复位）
    │   ├── progress.js         # 进度条 + 阶段节点 UI（setProgress / setActivePhase / markStageDone）
    │   ├── stages.js           # ESP32/GD32 阶段驱动（updateEsp32StagesFromPhase / GD32 阶段更新）
    │   ├── file-handle.js      # 文件选择 / FSAPI / SHA-256 / HEX→BIN 转换 / 文件信息 UI
    │   ├── upload-esp32.js     # ESP32 上传流程 + SHA 校验 + 完成升级
    │   ├── upload-gd32.js      # GD32 中继 OTA 触发 + relay 态跟踪
    │   ├── spi.js              # SPI 帧构建与发送
    │   └── console-mode.js     # 从 index.html 抽出的内联脚本（setConsoleMode / selectFlashTarget / 共享固件胶水）
    ├── ble/
    │   ├── constants.js        # UUIDS + BLE_OTA_* 协议常量 + TARGETS 配置
    │   ├── state.js            # state 对象 + 元素缓存（els）
    │   ├── stages.js           # BLE 阶段流管理（setBleStage / resetBleStages / setBleStageError）
    │   ├── gatt.js             # BLE 连接 / 断开 / 服务发现 / 通知使能
    │   ├── file.js             # 文件准备 + 分包 + notifyFileChange
    │   ├── transfer.js         # 数据写入循环 + ACK 窗口节流 + 重传
    │   ├── verify.js           # SHA-256 校验面板（showBleVerifyInfo / hideBleVerifyInfo）
    │   └── session.js          # waitForOtaResult + resolveOtaResult + abort 任务
    └── can/
        ├── dbc.js              # DBC 解析器（parseDbc / findSignal / buildSummary）
        ├── messages.js         # 报文列表渲染 + 过滤 + 节点过滤
        ├── signals.js          # 信号值编辑器 + 编解码 + 批量添加
        ├── send.js             # 帧构建 + 发送 + 错误码描述
        └── feedback.js         # 1Hz 反馈轮询 + ID 快照表
```

### 拆分原则
1. **保持功能完全不变**：纯结构重构，不修改任何业务逻辑、算法、阈值
2. **按现有注释分节对齐**：`app.js` 已有 17 个 `// ==== SECTION ====` 注释，按此天然边界拆分
3. **共享函数提取到 common/**：`formatBytes`、`showToast`、`addLog`、`testConnection` 等在多个文件中重复的函数统一提取
4. **循环依赖处理**：模块间若存在循环引用，通过回调注册或共享 state 模块解耦
5. **全局状态最小化**：原 `window.*` 全局变量保留必要的（`window.connectionMode`、`window.flashTarget`、`window.bleOta`），内部状态用模块级变量

## ADDED Requirements

### Requirement: ES Module 工程结构
系统 SHALL 将 `tools/` 目录组织为原生 ES Module 工程，所有 JS 文件使用 `import`/`export` 语法，HTML 通过 `<script type="module">` 加载。

#### Scenario: 浏览器加载页面
- **WHEN** 用户通过 `http://localhost:8080/index.html` 访问 OTA 控制台
- **THEN** 浏览器原生解析 ESM import 链，无构建步骤，所有模块按依赖顺序加载执行

#### Scenario: Python http.server 提供 ESM 文件
- **WHON** `serve.bat` 启动 Python http.server
- **THEN** `.js` 文件以 `application/javascript` MIME 类型返回，`type="module"` 脚本正常加载

### Requirement: CSS 按职责拆分
系统 SHALL 将 `style.css` 拆分为 5 个独立 CSS 文件，每个文件负责一个明确的样式职责域。

#### Scenario: 页面引用 CSS
- **WHEN** 任意 HTML 页面加载
- **THEN** 通过 5 个 `<link>` 标签并行加载 base + layout + components + can + responsive，视觉效果与原单文件 `style.css` 完全一致

## MODIFIED Requirements

### Requirement: HTML 脚本引用方式
三个 HTML 页面 SHALL 使用 `<script type="module">` 引用入口 JS 文件，不再使用普通 `<script src>`。`index.html` SHALL 移除所有内联 `<script>` 块，改为模块导入。

#### Scenario: index.html 加载脚本
- **WHEN** `index.html` 解析到末尾
- **THEN** 按顺序加载 `js/app.js`（WiFi OTA 入口）和 `js/ble_ota.js`（BLE 入口），两者均为 `type="module"`，原内联胶水代码由 `js/ota/console-mode.js` 模块提供

### Requirement: HTML 内联事件处理器兼容
系统 SHALL 保留现有 HTML 中的 `onclick="funcName()"` 内联处理器，并在入口模块中将这些函数显式挂载到 `window` 对象。

#### Scenario: 用户点击内联 onclick 按钮
- **WHEN** 用户点击 `onclick="setConsoleMode('wifi')"` 按钮
- **THEN** `window.setConsoleMode` 函数已被 `js/ota/console-mode.js` 模块挂载，正常执行模式切换逻辑

## REMOVED Requirements

### Requirement: 原始大文件
**Reason**: `app.js`（2371 行）、`ble_ota.js`（1658 行）、`can.js`（1526 行）、`style.css`（2146 行）单文件过大，已拆分为模块化小文件
**Migration**: 原文件删除，功能由 `js/` 和 `css/` 子目录下的模块文件承接，HTML 引用路径已更新