docs: 新增 README.md — 项目说明、功能、使用流程、版本历史
This commit is contained in:
VALM-Labs
parent
2deb201844
commit
57cd353a78
238
README.md
Normal file
238
README.md
Normal file
@ -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 都是本地生成的。
|
||||
Loading…
x
Reference in New Issue
Block a user