面向 Windows 的轻量级库存台账与点料工具：本机 PySide6 图形界面、CSV 持久化、可选 ESP32-S3 通过局域网 HTTP 推送计数，以及可选 串口 读行写入数量。固件侧使用 ESP-IDF（idf.py）管理。
- 项目简介
- 仓库结构
- 功能概览
- 环境要求
- 快速开始（桌面端）
- ESP32 固件
- 点料 HTTP 接口
- CSV 与数据
- 打包为 Windows exe
- 防火墙与安全
- 已知限制
- 许可协议与转载署名
- 免责声明
ESP32-MM 是一套「PC 台账 + 可选硬件计数」的小型方案：
| 组成部分 | 说明 |
|---|---|
桌面端 (desktop/) |
Python 3.10+，PySide6 主窗口；读写 CSV；内嵌 FastAPI + Uvicorn 接收点料；可选串口解析数字写入数量。 |
固件 (firmware/esp32_counter/) |
ESP32-S3：WiFi、NVS 配网、GPIO0 向 PC 的 HTTP 接口 POST（ESP-IDF）。 |
适用于个人或小团队 非商业 场景下的物料数量登记、盘点辅助与简易计数推送，不替代专业 WMS/ERP。
ESP32-MM/
├── README.md # 本说明
├── LICENSE # 开源许可（非商用 + 署名等）
├── data/
│ └── inventory_template.csv # CSV 表头模板（可参考）
├── desktop/ # Windows 桌面程序（Python）
│ ├── pyproject.toml
│ ├── requirements.txt
│ ├── src/warehouse_app/ # 应用源码（主窗体、HTTP、串口、自绘控件等）
│ ├── scripts/ # 构建、图标、演示数据脚本
│ └── warehouse_manager.spec # PyInstaller 配置
└── firmware/
└── esp32_counter/ # ESP32-S3 ESP-IDF 工程
- 库存 CSV：加载/保存 UTF-8（带 BOM 便于 Excel）；导入导出。
- 表格：勾选列（本地状态，不写回 CSV）、行编辑、删除选中/已勾选行。
- 筛选与搜索：分类、封装筛选；模糊搜索（rapidfuzz）。
- 点料 / 表单：数量、分类、名称、封装、数值/单位、库位、备注；右侧「快捷选用」从表中抽取常用值填入。
- HTTP 点料：
POST /api/push-count，JSON 内可带presets预填分类/名称/封装等（由界面逻辑消费）。 - 串口采样：可选读行、解析数字一键写入数量（依赖
pyserial）。 - 主题：浅色 QSS + 自绘下拉等控件（与系统主题解耦程度因平台略有差异）。
| 组件 | 要求 |
|---|---|
| 操作系统 | Windows 10/11（开发与运行以 Windows 为主） |
| Python | 3.10+（桌面端） |
| 可选 | ESP-IDF 5.x（固件 idf.py build flash）；管理员权限仅在为 exe 放行防火墙等场景可能需要 |
git clone <本仓库 URL>
cd ESP32-MM\desktoppip install -r requirements.txt
pip install -e .在 desktop 目录下：
cd src
python -m warehouse_app若已通过 pip install -e .，也可在任意目录执行：
warehouse-manager- 默认库存文件：
%USERPROFILE%\Documents\WarehouseManager\inventory.csv（UTF-8 BOM，便于 Excel 打开）。 - 可在界面侧栏修改路径并「重新加载 / 保存」。
- 安装 ESP-IDF 5.x 并执行环境导出（如
export.ps1）。 - 编译并烧录：
cd firmware\esp32_counter
idf.py set-target esp32s3
idf.py build flash monitor- 首次配网：若 NVS 中无 WiFi/PC 配置，开发板开启热点
ESP32-Counter-Config，连接后在浏览器打开http://192.168.4.1，填写 WiFi、电脑在局域网中的 IP、端口（与 PC 软件侧栏「端口」一致，默认8765），保存后重启。 - 按键：GPIO0（内部上拉，按键接 GND）在 WiFi 已连接时向 PC POST 一次点料数据。
详见 firmware/esp32_counter/README.md。
- 监听：
0.0.0.0:<端口>（界面「点料接收 (HTTP)」中配置，默认 8765）。 - 健康检查：
GET /health→{"status":"ok"} - 点料：
POST /api/push-count- Body 为 JSON，字段示例：
count（整数）、device_id、presets（内含apply_*与对应字符串字段）等，详见desktop/src/warehouse_app/http_api.py中PushCountBody/PresetsPayload。
- Body 为 JSON，字段示例：
局域网内 ESP32 或自写脚本将请求发往 http://<PC局域网IP>:<端口>/api/push-count。
表头（顺序固定）：
id,category,name,package,value,value_unit,quantity,location,notes,updated_at
仓库内可参考：data/inventory_template.csv。
在 desktop 目录：
.\scripts\build_exe.ps1输出目录一般为 desktop\dist\WarehouseManager\，运行其中的 WarehouseManager.exe。
打包后若需 HTTP 点料，请在 Windows 防火墙 中为该 exe 放行 专用网络 入站（端口与软件内设置一致）。
- 点料服务绑定
0.0.0.0，意味着 同网段设备 在防火墙放行后均可访问；请勿在不可信网络暴露。 - 本仓库 不包含 身份认证、HTTPS、审计日志等企业级安全能力；生产或公网环境请自行评估风险。
| 类别 | 说明 |
|---|---|
| 适用范围 | 单机 CSV、内嵌 HTTP，适合轻量场景；大数据量、多用户并发写入未做专项优化。 |
| 平台 | 开发与说明以 Windows 为主；其他系统未做完整验证。 |
| 依赖许可 | 界面使用 Qt/PySide6 等第三方库，分发时需遵守其许可证（与 本仓库 CC BY-NC-SA 无关）。 |
| 数据与备份 | 无内置自动备份与版本历史；重要数据请自行定期备份 CSV。 |
| ESP32 | 配网、路由、防火墙与硬件接线由使用者自行负责。 |
本仓库中的 源代码、资源与文档（第三方依赖除外）在 Creative Commons 体系下采用：
- 非商业（NC）：不得将本作品或其主要部分用于 商业目的（包括但不限于收费分发、嵌入商业产品对外提供服务而收费等）。若需商业授权，须另行取得权利人的书面许可。
- 署名（BY）：转载、再分发、公开展示或基于本仓库发布衍生作品时，须 显著保留 原作者及项目信息，建议至少包含：
- 项目名称：ESP32-MM（或仓库显示名）；
- 来源链接（本 Git 仓库 URL）；
- 本许可证 或指向
LICENSE/ CC BY-NC-SA 4.0 法律文本的链接； - 若修改了源码，应 在相应源文件或 README 中说明 修改范围，并不得移除原有版权与许可声明。
- 相同方式共享（SA）：若你基于本仓库修改并再发布，衍生作品须以 CC BY-NC-SA 4.0（或法律允许的同等条件）授权。
完整法律文本见仓库根目录 LICENSE，亦可查阅：
https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode
若你仅引用少量代码片段做学习交流，仍建议注明出处与许可证，以避免争议。
本软件按「现状」提供，不作任何明示或暗示的保证。因使用或无法使用本软件导致的任何直接或间接损失，作者与贡献者 不承担 法律责任。使用前请自行评估数据、网络与硬件安全。