本项目是一个运行在嵌入式设备上的 Web 前端配置界面，用于通过浏览器对设备进行可视化配置与管理。
前端采用 Vite + 原生 JavaScript / HTML / CSS 构建，最终以静态资源形式运行在设备本地，无需额外服务器或云端依赖。

用户只需在同一局域网内使用浏览器访问设备地址，即可完成设备参数配置、状态查看及相关交互操作。配套固件项目：https://github.com/Anonymity2002/HoloCubic_AIO

在原始项目中，Web 配置页面与固件代码 直接内嵌在固件工程中，前端资源通常以字符串形式随固件一同维护和编译。这种方式在项目早期较为直观，但随着功能和页面复杂度的提升，逐渐暴露出以下问题：

• 前端与固件代码混杂，维护成本高
• 前端迭代需要频繁重新编译、烧录固件
• 不利于独立调试、样式优化和功能扩展
• 难以复用或单独演进前端部分

基于以上原因，本项目将 原本嵌入在固件中的 Web 前端独立拆分，形成一个单独的前端工程，主要目标包括：

• 前端可作为普通 Web 项目独立进行开发与构建
• 构建产物以静态文件形式集成回固件文件系统
• 前后端职责更加清晰，整体结构更易维护
• 更有利于后续功能扩展与 UI 重构

此外，前端工程在使用方式上支持 开发模式 与 发布模式 两种运行形态，模式切换由固件代码控制：

• 开发模式

  • 前端由 Vite 开发服务器托管并运行在开发电脑上
  • 设备网页访问可跳转至本地开发服务器
  • 支持热更新（HMR），前端修改无需频繁重新构建和烧录固件
  • 即使在开发模式下，仍可通过网页正常配置和操作设备参数

• 发布模式

  • 前端构建后的静态文件被打包并存放于设备的 SPIFFS 文件系统中
  • 设备可直接本地访问网页，无需依赖外部开发环境
  • 适用于正式使用和分发场景

通过这种双模式设计，在保证设备功能完整可用的同时，大幅提升了前端开发效率，并降低了前后端联调与维护成本。

本项目主要用于为嵌入式设备提供本地化的 Web 配置与交互界面，核心功能包括：

• 设备基础参数配置与管理
• 设备运行状态与系统信息展示
• 即时生效的参数调整与交互操作
• 面向嵌入式场景的轻量化 UI 设计

具体功能以配套固件支持情况为准。

• 构建工具：Vite
• 前端语言：原生 JavaScript（ES Modules）
• 页面结构：HTML
• 样式实现：CSS

本项目未引入 Vue、React 等前端框架，主要基于以下考虑：

• 运行环境受限
  前端最终运行在嵌入式设备上，对内存占用、加载速度和资源体积更为敏感，避免引入大型运行时可有效降低整体资源消耗。
• 部署形式为静态文件
  项目以构建后静态资源形式集成至固件文件系统中，原生 JavaScript 已能满足页面交互与状态管理需求，引入框架带来的复杂度收益有限。

在进行本前端项目的开发与构建前，请确保开发环境满足以下要求：

• Node.js
  建议使用长期支持版本（LTS），用于依赖管理与构建流程。
• 包管理工具
  支持使用 npm 进行依赖安装与脚本执行。
• Vite（作为项目构建工具）
  本项目基于 Vite 进行开发与构建，Vite 作为项目依赖由包管理工具自动安装，无需额外全局配置。
• 网络环境
  开发电脑需与设备处于同一局域网内，以便在开发模式下进行页面访问与联调。

以上环境仅用于前端开发与调试，设备在发布模式下运行前端页面不依赖开发环境。但仍需要处于同一局域网才可进行参数配置。

本前端项目以 静态文件 形式部署，并由设备固件内置的 Web 服务直接提供访问。
根据使用场景不同，项目支持 发布模式 与 开发模式 两种部署方式。

发布模式用于设备的正式运行与分发场景，前端页面完全运行在设备本地。

部署流程如下：

1. 在前端项目目录中执行构建命令，生成静态资源文件：

   npm run build

2. 将构建产物拷贝至固件工程中对应的文件系统目录。

3. 将文件烧录至设备存储（SPIFFS）。

4. 设备启动后，由固件内置的 Web 服务直接提供本地 Web 页面访问能力。

开发模式用于前端开发与调试阶段，通过本地开发服务器运行前端页面，以提升开发效率。

部署与使用方式如下：

1. 在前端项目目录中启动 Vite 开发服务器：

   npm run dev -- --host

2. 开发服务器运行在开发电脑上，并允许局域网内的设备访问。

3. 固件在开发模式下会将设备 Web 页面访问重定向至本地开发服务器地址。

4. 前端页面支持热更新（HMR），修改后可即时生效，无需频繁重新构建前端或烧录固件。

在开发模式下，需确保固件侧配置的前端访问地址指向开发电脑的 IP，否则设备无法正确重定向至开发服务器。

前端页面基于现代 Web 标准实现，需在支持 ES Modules 的浏览器环境中运行。

已验证可正常使用的浏览器：

• Chrome
• Edge

不建议使用：

• Internet Explorer
• 过旧版本的移动端或桌面浏览器

项目未引入额外的兼容性垫片或降级方案，旨在保持代码结构简洁并降低资源占用。页面布局主要针对 平板设备（横屏） 与 手机设备（竖屏） 进行了适配。

由于项目为个人开发，测试设备和环境有限，未对所有型号的手机和平板进行全面验证；当前适配在作者自用设备上可正常使用，其他设备的显示与交互效果可能存在差异，敬请理解。

本项目前端部分基于原项目的固件 Web 配置页面演进而来，感谢源项目作者及其维护者所做的工作与贡献。

同时感谢以下开源项目与社区提供的工具与技术支持：

• ClimbSnail项目仓库：https://github.com/ClimbSnail/HoloCubic_AIO
• Vite 及相关前端工具链
• Web 标准与开源社区的长期积累

设备与 ESP32 处于同一局域网后，可通过手机或电脑浏览器访问设备的 IP 地址，或使用主机名 holocubic.local 打开配置页面。（mDNS 主机名 不区分大小写，文档中统一使用小写形式表示。）

在首次烧录固件且尚未完成 Wi-Fi 配置时，可将设备切换至 AP 模式。连接设备热点后，同样可以访问配置页面完成网络设置。

• 设备 IP 地址：192.168.4.2
• 设备主机名：holocubic
• AP 热点名称：HoloCubic_AIO