OpenWash Web App 是 OpenWash 固件的网页端管理应用，核心任务是通过一套基于 HTTP/JSON 的OpenWash API，让浏览器与固件之间完成双向通信。本文是一份面向新手和普通用户的接口速查手册：不需要阅读大段代码，就能快速理解 Web 端与固件通信的架构、接口分类、典型请求流程和常见报错的解决办法。

📌 提示：当前仓库仍处于早期开发阶段（初始提交），文中的接口类别为 Web 端与固件通信的标准功能划分，具体路径与参数请以仓库后续发布的文档和源码为准。

一、OpenWash Web App 是什么？

简单理解：OpenWash 固件跑在设备里，OpenWash Web App 是你在浏览器里打开的"控制面板"。它本身不直接驱动硬件，而是通过 API 把用户的操作转发给固件，再把固件的状态反馈到页面上。

📎 相关文件：

• 项目说明：README.md
• 开源许可（GNU LGPL v3）：LICENSE

项目遵循LGPL-3.0许可，你可以在该协议下自由使用、修改和分发，这也是二次开发 OpenWash Web App 的基础。

二、通信架构一图看懂：Web 端如何与固件对话

整个通信链路只有三步，记住它，后面看任何接口都不会迷路：

1. 浏览器发起请求：页面上的按钮（如"启动""保存设置"）触发一次 HTTP 请求，目标是设备固件的 API 端点；
2. 固件处理并返回 JSON：固件解析请求体（JSON 格式），执行对应动作，返回统一结构的状态数据；
3. Web 端解析并刷新界面：前端读取返回的status与data字段，更新页面显示或提示用户。

✅ 这种"请求—响应"模型的最大好处是：任何标准工具（浏览器地址栏、curl、Postman）都可以直接调用同一套接口，调试门槛很低。

一次典型请求的流程

以一个"查询设备状态"的请求为例，通信过程如下：

GET /api/status HTTP/1.1 Host: <设备IP>

固件返回的响应通常是统一的 JSON 结构：

{ "status": "ok", "data": { "model": "OpenWash", "firmware": "x.y.z", "uptime": 3600 } }

• status：接口是否执行成功（ok/error）
• data：真正的业务数据或错误详情

三、核心接口速查表（按功能分类）

下表按功能类别整理 Web 端与固件通信的接口速查，方便你按需求定位：

💡 速记技巧：GET 只读、POST 执行动作、PUT 整体更新——看到方法名就能判断接口是"查"还是"改"。

四、常见通信报错速查：一次定位问题

Web 端连不上固件、页面转圈无响应，大多是下面几类问题：

🔍 排查顺序建议：先看网络连通性（能否 ping 通设备）→ 再看接口是否 404（版本是否匹配）→ 最后看响应体里的错误详情。

五、获取源码与关键文件定位

📥 克隆仓库：

git clone https://gitcode.com/gh_mirrors/op/openwash-web

克隆后建议按以下顺序阅读：

1. README.md —— 项目定位与基本介绍（OpenWash - Web App）
2. LICENSE —— LGPL-3.0 许可条款，二次开发前请确认合规要求
3. 后续新增的源码与文档目录 —— 接口定义、路由注册等通信细节将在 Web App 代码中持续完善

六、常见问题 FAQ

Q1：OpenWash API 必须用浏览器才能调用吗？不用。它是标准的 HTTP/JSON 接口，任何能发 HTTP 请求的工具（curl、Postman、脚本）都可以直接调用。

Q2：接口路径和参数在哪看最终定义？以仓库正式发布的源码与文档为准。当前仓库处于初始提交阶段，建议关注仓库后续更新。

Q3：我自己加的功能需要遵守什么许可？仓库采用 LGPL-3.0（见 LICENSE）。分发修改后的版本时需遵守 LGPL 的附加义务，例如保留许可声明、提供修改说明等。

Q4：Web 端和固件版本不匹配会怎样？可能表现为 404（新接口固件不支持）或字段缺失（旧接口结构变化）。保持 Web 端与固件版本配套升级是最稳妥的做法。

总结

• OpenWash Web App是 OpenWash 固件的网页控制台，通过HTTP + JSON API与固件通信；
• 接口按"状态查询 / 控制指令 / 参数配置 / 系统维护"四类理解，配合 GET/POST/PUT 方法即可快速定位；
• 遇到问题先查网络连通性，再看状态码与日志接口，绝大多数通信问题都能在这三步内定位；
• 项目基于LGPL-3.0开源，欢迎基于 README.md 与 LICENSE 进一步了解并参与贡献。