From 57cd353a781ad8127c3020b8b16af4a1814314bf Mon Sep 17 00:00:00 2001 From: VALM-Labs <135186421+VALM-Labs@users.noreply.github.com> Date: Wed, 20 May 2026 16:14:09 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20README.md=20?= =?UTF-8?q?=E2=80=94=20=E9=A1=B9=E7=9B=AE=E8=AF=B4=E6=98=8E=E3=80=81?= =?UTF-8?q?=E5=8A=9F=E8=83=BD=E3=80=81=E4=BD=BF=E7=94=A8=E6=B5=81=E7=A8=8B?= =?UTF-8?q?=E3=80=81=E7=89=88=E6=9C=AC=E5=8E=86=E5=8F=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 238 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..95e1ae1 --- /dev/null +++ b/README.md @@ -0,0 +1,238 @@ +# 产品-硬件入库测试工具 + +ESP32-S3 类产品的产线入库测试夹具。Python + tkinter 编写，打包为单文件 `.exe`，仓库人员双击即用，不需要装 Python。 + +**版本**：v2.1.0 + +--- + +## 一、项目背景 + +产线测试场景：成箱的硬件设备（ESP32-S3 模组）需要逐台测试合格后入库。每台设备通过 USB 接电脑后，会通过串口输出诊断日志（MAC、按键事件、音频测试等），测试员根据日志和人工耳听判断每台设备是否合格，合格的设备分配唯一 SN 入库，不合格的不入库（拿去维修）。 + +为减少人工记录误差、自动统计不良率、防止 SN 重复分配，做了这套工具。 + +--- + +## 二、核心功能 + +### 1. 多产品支持 + +- 一个工具能测多种产品（ESP32-S3-Airhub、其他型号 …） +- 每个产品独立的配置：测试项、MAC 提取正则、SN 起始/位数/步长 +- 顶部下拉切换产品，支持新建 / 复制 / 重命名 / 删除 / 导入导出 JSON +- 配置存放在 `profiles/<产品名>.json` + +### 2. 测试项五种类型 + +| 类型 | 用途 | 操作 | +|---|---|---| +| 自动-关键词命中 | 日志里出现指定字符串就 PASS | 串口自动识别 | +| 自动-抓取数值 | 从日志抓数字/字符串当值 | 串口自动识别并填入 | +| 人工-勾选 ✓/✗ | 测试员目测/耳听判断 | 点 ✓ / ✗ | +| 人工-多选下拉 | 多状态选项（红灯/绿灯/不亮） | 选状态 + 人工 ✓/✗ | +| 人工-填写文本 | 测试员手填一段文字 | 输入框 + ✓填入 | + +测试项可在 UI 内任意增删改，每行末尾 ✏ 按钮快速编辑，无需手改 JSON。 + +### 3. MAC 双源校验 + +设备插入时同时显示两个 MAC： +- **USB SN**（端口栏下小灰字）：从 USB 端口的 serial_number 字段读取 +- **串口 MAC**：从串口日志正则匹配 + +两者实时比对，✅ 一致 / ❌ 不一致，防止设备弄混。 + +### 4. SN 智能分配（核心逻辑） + +**SN 只属于已入库的 PASS 设备**，FAIL 设备不占用 SN。 + +- 主 CSV 里 FAIL 行的 SN 列**为空** +- 新设备进来时，扫描 CSV 中所有 PASS 行的 SN 数字，自动分配**最小未占用**的编号 +- 设备 FAIL → SN 不占用 → spinbox 不动 +- 设备 PASS → SN 占用 → spinbox 自动 +1 +- 维修后回来 = 当作新设备处理（之前 FAIL 没绑定，重新分配） + +举例 — 已测 SN1(PASS)、X(FAIL)、SN2(PASS)： +- spinbox 显示 **3**（最小未被 PASS 占用） +- 下一台 PASS → 占 SN3 +- 下一台 FAIL → spinbox 不动还是 3 + +### 5. MAC 重复检测 + +| 情况 | 行为 | +|---|---| +| 同会话同 MAC 反复出现（设备一直插着） | 忽略，不打扰 | +| CSV 中已有 **PASS 行**匹配此 MAC | 弹窗"该 MAC 已入库为 SN=XX，是否覆盖" | +| CSV 中只有 **FAIL 行**匹配 / 全新 MAC | 不弹窗，当新设备 | + +### 6. 批次管理 + +- **批次号**和**数量**用户自定义（如 "2026-05-A" 数量 600） +- 每个批次独立 CSV 文件：`reports/<产品>_<日期>_批次<批次号>.csv` +- 切换批次 = 切换 CSV，统计自动刷新 +- 批次测满自动提示生成汇总 + +### 7. 统计-汇总面板 + +实时显示： +- 累计 / 未测台数 +- 合格台数 / 合格率 +- 不合格台数 / 不良率 +- 不良率公式：`不合格 / 累计 × 100%`（未测不计入分母，0 台时显示 —） + +### 8. 统计汇总报告导出 + +底部"📊 导出统计汇总"按钮，弹窗让用户选格式： + +- **`.xlsx`**（推荐）：三个 sheet + - `测试汇总`：产品/日期/测试员（按明细自动汇总）/批次号/数量/合格/不合格/合格率/不良率 + - `PASS 明细`：已入库设备列表 + - `FAIL 明细`：失败设备，SN/MAC 列红字加粗 + - 所有单元格居中对齐 + 自动列宽 +- **`.csv`**：纯文本（汇总 + 明细同 sheet） + +### 9. 其他 + +- 串口下拉 + 波特率下拉（readonly，不能手输错） +- 端口下方小灰字显示设备描述 + USB SN（仿 VOFA+ 风格） +- 串口日志时间戳绿色显示，跟设备打印分离 +- 已连接状态深绿色加粗显眼 +- 字号 5 档可调（小/中/大/特大/超大）保存到 settings +- 测试项 / 串口日志区域中间可拖动调整宽度 +- 串口日志支持"断开时自动清空"开关 +- 保存一台后自动断开串口，避免同设备 MAC 重复触发检测 + +--- + +## 三、文件结构 + +``` +hardware-test-jig/ +├── HardwareTestJig.exe # 打包后单文件可执行（仓库用） +├── 使用说明.txt # 仓库人员看的简单说明 +├── test_jig.py # 主程序源码 +├── start.bat # 开发调试用启动脚本 +├── settings.json # 全局设置（串口、波特率、字号、批次号、批次大小） +├── profiles/ # 产品配置目录 +│ └── ESP32-S3-Airhub.json +├── reports/ # 每日测试报告输出 +│ └── <产品>_<日期>_批次<批次号>.csv +└── README.md # 本文档 +``` + +--- + +## 四、使用流程（仓库人员视角） + +1. 双击 `HardwareTestJig.exe` 启动 +2. 顶部下拉选产品（如 ESP32-S3-Airhub） +3. 选串口 + 波特率 → 点"连接" +4. 设置批次号（如 "2026-05-A"）、数量（如 600） +5. 拿一台设备上电 → 串口日志自动滚动，MAC 自动识别 +6. 测试员按提示操作：故事按键、BOOT 按键、喊唤醒词、听喇叭语音… +7. 自动项（按键、音频）日志命中自动 ✅，人工项点 ✓ / ✗ +8. 所有项判定完成后 → 点 **"💾 保存本台数据"** +9. 自动断开串口 → 测试员拔下设备、装下一台、重新点"连接" +10. 批次测完后 → 点 **"📊 导出统计汇总"** 生成 xlsx 报告（自动按 PASS / FAIL 分 sheet） + +--- + +## 五、关键概念图解 + +### SN 分配示例 + +``` +批次大小 600，spinbox 起始 1： + +第 1 台 PASS → 分配 SN1 (PASS 占用 = {1}, 下一个 = 2) +第 2 台 FAIL → SN 留空 (PASS 占用 = {1}, 下一个 = 2) +第 3 台 PASS → 分配 SN2 (PASS 占用 = {1,2}, 下一个 = 3) +第 4 台 FAIL → SN 留空 (PASS 占用 = {1,2}, 下一个 = 3) +第 5 台 PASS → 分配 SN3 (PASS 占用 = {1,2,3}, 下一个 = 4) +... + +合格 = 3 台, 不合格 = 2 台, 累计 = 5, 合格率 60%, 不良率 40% +``` + +### MAC 检测决策树 + +``` +新 MAC 进入 + │ + ├─ 同会话内是否已问过此 MAC？ + │ 是 → 跳过，不打扰 + │ 否 ↓ + │ + ├─ 主 CSV 中是否有此 MAC 的 PASS 行？ + │ 是 → 弹窗"该 MAC 已入库为 SN=XX，是否覆盖重测？" + │ 否 ↓ + │ + └─ 当新设备处理，自动重算 SN spinbox = 最小可用编号 +``` + +--- + +## 六、开发与打包 + +### 环境 +- Python 3.11.7（Anaconda） +- 依赖：pyserial 3.5、openpyxl 3.0.10、tkinter（标准库） + +### 直接运行源码 +```cmd +python test_jig.py +``` +（或双击 `start.bat`） + +### 打包成 exe +```cmd +python -m PyInstaller --onefile --windowed --name "HardwareTestJig" --clean --noconfirm ^ + --hidden-import=openpyxl ^ + --exclude-module=numpy --exclude-module=scipy --exclude-module=pandas ^ + --exclude-module=matplotlib --exclude-module=PIL --exclude-module=lxml ^ + test_jig.py +``` + +完整的排除清单（避免 Anaconda 把不相关库一起打包导致 exe 暴涨）： +``` +numpy scipy pandas matplotlib PIL Pillow lxml tornado notebook IPython +ipykernel jupyter jupyter_client jupyter_core sphinx sympy statsmodels +seaborn bokeh cv2 tables numba llvmlite torch tensorflow sklearn +``` + +打包结果：约 13 MB 单文件 exe。 + +--- + +## 七、版本说明 + +### v2.1.0（当前） + +**核心改动**（相对 v2.0.0）： +- **SN 不再被 FAIL 占用**：FAIL 行 SN 列留空，PASS 才占编号 +- **SN 自动分配**：扫主 CSV PASS 行找最小未占用编号，spinbox 自动跟新 +- **MAC 检测重构**：只对 PASS 过的 MAC 弹窗，FAIL 过的 MAC 当新设备静默处理 +- **xlsx 导出三 sheet**：测试汇总 / PASS 明细 / FAIL 明细，FAIL 行 SN/MAC 红字加粗 +- 优化：滚轮只在测试项区域生效，统计-汇总 UI 字体字号统一 + +### v2.0.0 + +- 多产品 Profile 切换 / 增删 / 导入导出 +- 5 种测试项类型 + UI 内可编辑 +- SN 自增（前缀+位数+步长） +- MAC 双源验证（USB serial_number + 串口日志） +- 报告按产品+日期分文件 +- 测试统计面板 + 批次完成提示 + +--- + +## 八、隐私说明 + +仓库公开/分发时只包含： +- 源码 `test_jig.py` +- 默认 profile `profiles/ESP32-S3-Airhub.json` +- 空的 `settings.json`（无任何个人信息） +- `.gitignore` 排除了所有运行时生成的报告、日志、build artifacts + +不会泄露任何测试员姓名、邮箱、实际测试数据。每个产线的 `reports/`、自定义 profile、settings 都是本地生成的。