ilaandClaude Sonnet 4.6
37a4c13799
- 新增 mingxi-capture（PyQt5桌面程序）目录骨架 - 新增 mingxi-vision（FastAPI推理服务）目录骨架 - 新增 mingxi-backend（Django业务后端）目录骨架 - 新增 mingxi-frontend（Vue3管理后台）目录骨架 - 迁入 docs/（技术设计文档和PCB调研资料） - 补充 .gitignore（模型文件、Node.js依赖、运行时数据库） Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
758 lines
29 KiB
Markdown
758 lines
29 KiB
Markdown
# 明析平台 软件重构设计文档
|
||
|
||
> 版本：v2.0 · 日期：2026-05-24
|
||
> 项目：基于机器视觉的图像识别技术应用平台——明析
|
||
> 参赛：梅州市2026年新一代电子信息暨人工智能产业创新创业大赛 · 初创企业（创客）组
|
||
|
||
---
|
||
|
||
## 1. 重构背景
|
||
|
||
### 1.1 现有代码概况
|
||
|
||
当前仓库 `yolo_classification_system` 是一套**通用YOLO推理系统**，实现了：
|
||
|
||
| 模块 | 现状 |
|
||
|------|------|
|
||
| 后端 | Django 4 + DRF，JWT鉴权，支持图片/视频/摄像头三种推理模式 |
|
||
| 推理 | `inference.py` 封装 ultralytics YOLO，模型缓存，结果落库 |
|
||
| 数据模型 | `UserProfile`、`YoloResult`、`SceneNews`、`SystemLog`、`YoloStatsDaily` |
|
||
| 前端 | Vue 3 + Vite，开发/生产环境分离，API代理配置完整 |
|
||
| 演示模型 | 驾驶员疲劳检测（`driver-drowsiness-detection/best.pt`） |
|
||
|
||
### 1.2 重构目标
|
||
|
||
将通用系统改造为**PCB线路板缺陷检测专用平台（明析）**，在不改动客户现有硬件的前提下，通过算法叠加实现AI视觉质检能力升级。
|
||
|
||
---
|
||
|
||
## 2. 系统物理架构
|
||
|
||
### 2.1 两台机器部署
|
||
|
||
```
|
||
┌─────────────────────────────────┐ 局域网 ┌──────────────────────────────────────┐
|
||
│ 前置机（工业PC） │ ─────────────→ │ 推理服务器（Linux+GPU） │
|
||
│ │ │ │
|
||
│ 相机 ──USB3──→ mingxi-capture │ │ mingxi-vision :8001 (FastAPI) │
|
||
│ （PyQt5桌面程序） │ │ mingxi-backend :8000 (Django) │
|
||
│ Win7 SP1+ 工业机 │ │ mingxi-frontend :80 (Vue3) │
|
||
└─────────────────────────────────┘ └──────────────────────────────────────┘
|
||
```
|
||
|
||
| 角色 | 机器 | 操作系统 | 运行软件 |
|
||
|------|------|---------|---------|
|
||
| 前置机 | 工厂现有工业PC（USB3.0） | Windows 7 SP1 及以上 | mingxi-capture.exe |
|
||
| 推理服务器 | 团队配置（RTX 4060 或以上） | Linux | mingxi-vision + mingxi-backend + mingxi-frontend |
|
||
|
||
### 2.2 数据流
|
||
|
||
```
|
||
操作工（点击按钮）或 PLC触发信号
|
||
│
|
||
▼
|
||
mingxi-capture（前置机）
|
||
│
|
||
├─① 同步 POST 图像 ──────────────→ mingxi-vision（推理服务器:8001）
|
||
│ │ 推理完成
|
||
│ ←── 返回标注图+缺陷列表+结论 ──────┘
|
||
│
|
||
├─ 立即在桌面程序展示结果（操作工可见）
|
||
│ · 合格 / 不合格 结论
|
||
│ · 标注了缺陷位置的图像
|
||
│ · 每个缺陷的类型、等级、置信度
|
||
│
|
||
└─② 异步队列 POST 结果 ──────────→ mingxi-backend（:8000）
|
||
│ 存入 SQLite
|
||
若失败 → 本地SQLite重试队列 │
|
||
▼
|
||
管理员/组长/厂长
|
||
通过浏览器查看
|
||
（短轮询，1-2秒延迟）
|
||
```
|
||
|
||
### 2.3 端口分配
|
||
|
||
| 服务 | 端口 | 调用方 |
|
||
|------|------|-------|
|
||
| mingxi-vision | 8001 | mingxi-capture（同步推理） |
|
||
| mingxi-backend | 8000 | mingxi-capture（存档）、浏览器前端 |
|
||
| mingxi-frontend | 80 | 浏览器 |
|
||
|
||
---
|
||
|
||
## 3. 子项目拆分方案
|
||
|
||
### 3.1 项目总览
|
||
|
||
```
|
||
mingxi-capture/ Python 3.8 · PyQt5 · Windows桌面程序（前置机运行）
|
||
mingxi-vision/ Python 3.8 · FastAPI · PCB缺陷推理服务（推理服务器运行）
|
||
mingxi-backend/ Python 3.8 · Django 4 · 业务后端（推理服务器运行）
|
||
mingxi-frontend/ Vue 3.0 · 管理后台（推理服务器运行，浏览器访问）
|
||
```
|
||
|
||
### 3.2 代码迁移决策
|
||
|
||
| 现有文件/模块 | 处置方式 | 说明 |
|
||
|-------------|---------|------|
|
||
| `yolo8/models.py` → `UserProfile` | **直接复用** | JWT鉴权体系完整，扩展 role 字段 |
|
||
| `yolo8/models.py` → `SystemLog` | **直接复用** | 日志结构通用 |
|
||
| `yolo8/jwt_utils.py` | **直接复用** | token版本机制保留 |
|
||
| `yolo8/models.py` → `YoloResult` | **重构为** `DefectResult` | 增加PCB专用字段：缺陷等级、产线 |
|
||
| `yolo8/models.py` → `SceneNews` | **删除** | 与PCB业务无关 |
|
||
| `yolo8/models.py` → `YoloStatsDaily` | **重构为** `ProductionStat` | 改为产线维度统计 |
|
||
| `yolo8/inference.py` → `run_image_inference` | **迁移至** `mingxi-vision` | 推理服务核心，增加ONNX支持 |
|
||
| `yolo8/inference.py` → `run_camera_inference` | **删除** | 由 `mingxi-capture` 海康SDK替代 |
|
||
| `yolo8/inference.py` → `_copy_to_ascii_temp_input` | **删除** | 改为内存读图，彻底消除中文路径问题 |
|
||
| `yolo8/views.py` → 鉴权相关视图 | **直接复用** | `auth_*`、`user_*` 无需改动 |
|
||
| `yolo8/views.py` → `yolo_task_image` | **重构为** `detect_pcb` | 简化，接收capture推送 |
|
||
| `frontend/` | **重构** | 删除通用YOLO页面，改为管理后台 |
|
||
|
||
---
|
||
|
||
## 4. mingxi-capture（前置采集程序）
|
||
|
||
### 4.1 定位
|
||
|
||
运行在**前置机**（工厂工业PC）上的 Windows 原生桌面程序。操作工唯一的交互界面，负责连接相机、触发检测、展示结果，并将结果异步上报至后台。
|
||
|
||
### 4.2 技术栈
|
||
|
||
```
|
||
语言：Python 3.8
|
||
GUI：PyQt5（支持 Windows 7 SP1 及以上，系统托盘、对话框完整支持）
|
||
相机：MvImport（海康威视MVS Python SDK，随MVS安装包提供）
|
||
本地存储：SQLite（通过 Python 内置 sqlite3）
|
||
网络：requests（同步调用vision）+ threading（异步队列推送backend）
|
||
打包：PyInstaller → 单文件 .exe 或目录，客户解压即用
|
||
最低系统：Windows 7 SP1 x64
|
||
```
|
||
|
||
### 4.3 目录结构
|
||
|
||
```
|
||
mingxi-capture/
|
||
├── camera/
|
||
│ ├── hik_camera.py # 海康相机封装（MvImport，Phase 2接入）
|
||
│ └── mock_camera.py # 模拟模式（读本地图片文件夹，Demo/开发用）
|
||
├── ui/
|
||
│ ├── main_window.py # 主窗口：触发按钮 + 图像展示 + 缺陷列表
|
||
│ ├── config_dialog.py # 配置弹窗：服务器地址、端口、相机参数
|
||
│ └── tray_icon.py # 系统托盘图标：显示/隐藏主窗口、退出
|
||
├── core/
|
||
│ ├── capture_worker.py # 拍图+调推理（在QThread中执行，不阻塞UI）
|
||
│ ├── upload_queue.py # 异步上报队列（本地SQLite缓存+重试）
|
||
│ └── settings.py # 读写 config.ini 配置文件
|
||
├── assets/
|
||
│ └── tray_icon.png # 托盘图标
|
||
├── config.ini # 默认配置（首次运行生成）
|
||
├── queue.db # 本地重试队列（SQLite，运行时生成）
|
||
├── main.py # 程序入口
|
||
├── requirements.txt
|
||
└── mingxi-capture.spec # PyInstaller打包配置
|
||
```
|
||
|
||
### 4.4 主窗口功能
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ 明析采集程序 [最小化到托盘] [×] │
|
||
├─────────────┬───────────────────────────┤
|
||
│ │ ┌───────────────────────┐│
|
||
│ [手动检测] │ │ ││
|
||
│ │ │ 标注图显示区域 ││
|
||
│ 状态: 就绪 │ │ (检测后显示) ││
|
||
│ │ │ ││
|
||
│ 结论: │ └───────────────────────┘│
|
||
│ ██ 不合格 │ │
|
||
│ │ 缺陷列表: │
|
||
│ 共 3 处 │ 类型 等级 置信度 │
|
||
│ 最高: 致命 │ 断路 致命 0.94 │
|
||
│ │ 短路 致命 0.88 │
|
||
│ │ 毛刺 轻微 0.72 │
|
||
└─────────────┴───────────────────────────┘
|
||
```
|
||
|
||
### 4.5 配置弹窗（系统托盘右键→设置）
|
||
|
||
```
|
||
推理服务地址: [192.168.1.100] 端口: [8001]
|
||
后台服务地址: [192.168.1.100] 端口: [8000]
|
||
相机序列号: [自动检测 ▼]
|
||
模拟模式: [✓] 启用 图片目录: [C:\test_images\ 浏览]
|
||
置信度阈值: [0.45]
|
||
[保存] [取消]
|
||
```
|
||
|
||
配置持久化至 `config.ini`，程序启动时自动读取。
|
||
|
||
### 4.6 异步上报队列
|
||
|
||
```python
|
||
# core/upload_queue.py 逻辑
|
||
|
||
# 1. capture_worker 推理成功后，将结果插入本地 SQLite queue.db
|
||
# 2. 后台线程每 5 秒扫描一次 queue.db 中状态为 pending 的记录
|
||
# 3. 尝试 POST 到 mingxi-backend
|
||
# 成功 → 标记为 sent
|
||
# 失败 → retry_count + 1，超过 10 次标记为 failed（不再重试）
|
||
# 4. 队列表结构:
|
||
# id, image_base64, result_json, created_at, status, retry_count, last_error
|
||
```
|
||
|
||
### 4.7 mock_camera 模拟模式
|
||
|
||
Phase 1（路演）无真实相机时，从配置目录中按序读取 `.jpg`/`.png` 文件，接口与 `hik_camera.py` 完全一致，上层代码无感知切换。
|
||
|
||
### 4.8 打包部署
|
||
|
||
```bash
|
||
pyinstaller mingxi-capture.spec
|
||
# 输出：dist/mingxi-capture/（目录模式）或 dist/mingxi-capture.exe（单文件）
|
||
# 客户端：解压后双击 mingxi-capture.exe 即可运行
|
||
# 随安装包附带：海康 MVS Runtime DLL（如需相机功能）
|
||
```
|
||
|
||
### 4.9 触发模式（阶段支持）
|
||
|
||
| 触发方式 | Phase 1 | Phase 2 |
|
||
|---------|---------|---------|
|
||
| 手动点击按钮 | ✅ | ✅ |
|
||
| PLC/传感器信号（串口/数字IO） | — | ✅ |
|
||
| 定时自动（固定频率） | — | ✅ |
|
||
|
||
---
|
||
|
||
## 5. mingxi-vision（推理服务）
|
||
|
||
### 5.1 职责
|
||
|
||
- 接收图像（来自 `mingxi-capture`）
|
||
- 调用明析平台（YOLOv8/ONNX）执行PCB缺陷检测
|
||
- 返回缺陷列表（位置、类别、置信度、等级）+ 标注图（可选）
|
||
- 支持模型热重载（管理员通过后台切换模型时调用）
|
||
|
||
### 5.2 技术栈
|
||
|
||
```
|
||
语言：Python 3.8
|
||
框架：FastAPI + uvicorn（workers=1，单进程，GPU不跨进程共享）
|
||
推理：ultralytics YOLOv8（开发阶段）/ ONNX Runtime（生产部署）
|
||
并发：asyncio.Lock（推理串行化，防止GPU冲突）
|
||
GPU：CUDA 11.x + cuDNN
|
||
```
|
||
|
||
### 5.3 并发处理：推理锁
|
||
|
||
```python
|
||
# engine/loader.py
|
||
import asyncio
|
||
|
||
_inference_lock = asyncio.Lock()
|
||
_engine: Optional[BaseInferenceEngine] = None
|
||
|
||
def get_inference_lock() -> asyncio.Lock:
|
||
return _inference_lock
|
||
|
||
# api/detect.py
|
||
async def detect(image: UploadFile, conf: float = 0.45, ...):
|
||
raw = await image.read()
|
||
img = cv2.imdecode(np.frombuffer(raw, np.uint8), cv2.IMREAD_COLOR)
|
||
|
||
async with get_inference_lock(): # 请求自动排队，GPU串行执行
|
||
result = engine.detect(img, conf)
|
||
|
||
return build_response(result)
|
||
```
|
||
|
||
- 并发请求不会崩溃，自动排队等待
|
||
- RTX 4060，YOLOv8s，PCB图：约 20~40ms/张 → 25~50 fps
|
||
- Windows / Linux 行为完全一致（asyncio 事件循环原语，无OS依赖）
|
||
|
||
### 5.4 模型热重载接口
|
||
|
||
```
|
||
POST /api/model/reload
|
||
Body: { "model_path": "/opt/mingxi/models/pcb_v2.onnx" }
|
||
Response: { "status": "ok", "model_version": "pcb_v2", "warmup_ms": 312 }
|
||
```
|
||
|
||
热重载流程：
|
||
1. 管理员在浏览器上传新模型并点击"切换"
|
||
2. `mingxi-backend` 保存文件、更新数据库，调用此接口
|
||
3. `mingxi-vision` 获取推理锁（等待当前推理完成），卸载旧模型，加载新模型，执行 warmup
|
||
4. 释放锁，返回成功
|
||
|
||
### 5.5 目录结构
|
||
|
||
```
|
||
mingxi-vision/
|
||
├── api/
|
||
│ ├── detect.py # POST /api/detect
|
||
│ ├── model.py # POST /api/model/reload
|
||
│ └── health.py # GET /api/health, /api/health/gpu
|
||
├── engine/
|
||
│ ├── base.py # DefectBox, DetectResult, BaseInferenceEngine
|
||
│ ├── loader.py # 单例 + asyncio.Lock + init_engine()
|
||
│ ├── ultralytics_adapter.py
|
||
│ ├── onnx_adapter.py
|
||
│ ├── annotator.py # 标注图生成（按severity着色）
|
||
│ └── defect_classes.py # HRIPCB 6类 + 扩展4类
|
||
├── models/ # .pt 和 .onnx 文件（gitignored）
|
||
├── scripts/
|
||
│ ├── export_onnx.py # pt → onnx 导出脚本
|
||
│ └── benchmark.py
|
||
├── tests/
|
||
├── schema.py # Pydantic 响应模型
|
||
├── config.py # BaseSettings（读 .env）
|
||
├── main.py # FastAPI lifespan + app
|
||
└── requirements.txt
|
||
```
|
||
|
||
### 5.6 推理接口
|
||
|
||
```
|
||
POST /api/detect
|
||
Content-Type: multipart/form-data
|
||
Fields:
|
||
image: <图像文件>
|
||
conf: float (default: 0.45)
|
||
return_annotated: bool (default: false)
|
||
|
||
Response 200:
|
||
{
|
||
"task_id": "uuid",
|
||
"duration_ms": 38,
|
||
"verdict": "fail", // pass / fail
|
||
"defect_count": 2,
|
||
"max_severity": "fatal",
|
||
"avg_confidence": 0.89,
|
||
"defects": [
|
||
{
|
||
"class_id": 2,
|
||
"class_name": "open_circuit",
|
||
"class_name_zh": "断路",
|
||
"confidence": 0.94,
|
||
"severity": "fatal",
|
||
"box_xyxy": [120, 45, 198, 123]
|
||
}
|
||
],
|
||
"annotated_image_base64": "..." // 仅 return_annotated=true 时返回
|
||
}
|
||
```
|
||
|
||
### 5.7 缺陷类别与等级映射
|
||
|
||
```python
|
||
DEFECT_CLASSES = {
|
||
# HRIPCB 数据集原始6类
|
||
0: {"name": "missing_hole", "zh": "缺孔", "severity": "fatal"},
|
||
1: {"name": "mouse_bite", "zh": "鼠咬", "severity": "major"},
|
||
2: {"name": "open_circuit", "zh": "断路", "severity": "fatal"},
|
||
3: {"name": "short_circuit", "zh": "短路", "severity": "fatal"},
|
||
4: {"name": "spur", "zh": "毛刺", "severity": "minor"},
|
||
5: {"name": "spurious_copper", "zh": "余铜", "severity": "major"},
|
||
# 扩展类（Phase 2 标注后训练）
|
||
6: {"name": "oxidation", "zh": "氧化", "severity": "minor"},
|
||
7: {"name": "solder_ball", "zh": "锡珠", "severity": "rework"},
|
||
8: {"name": "scratch", "zh": "划痕", "severity": "minor"},
|
||
9: {"name": "label_error", "zh": "标签错贴","severity": "rework"},
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. mingxi-backend（业务后端）
|
||
|
||
### 6.1 职责
|
||
|
||
- 接收 `mingxi-capture` 推送的检测结果，持久化至 SQLite
|
||
- 提供 REST API 给浏览器管理后台
|
||
- 用户管理、三级权限控制
|
||
- 模型文件管理（上传、备份、切换、触发vision热重载）
|
||
- 系统参数配置
|
||
|
||
### 6.2 技术栈
|
||
|
||
```
|
||
语言：Python 3.8
|
||
框架：Django 4.0 + django-rest-framework
|
||
数据库：SQLite（内网单服务器部署，无高并发写入，SQLite足够）
|
||
认证：JWT（从现有系统直接复用）
|
||
```
|
||
|
||
> 初期不引入 Celery/Redis，保持部署简单。告警推送（Phase 2）再评估是否引入。
|
||
|
||
### 6.3 用户权限设计
|
||
|
||
| 角色 | 检测记录可见范围 | 其他权限 |
|
||
|------|---------------|---------|
|
||
| 操作工 | 仅自己触发的记录 | 无 |
|
||
| 组长 | 本组所有成员的记录 | 查看本组统计 |
|
||
| 管理员 | 全部记录 | 用户管理、系统配置、模型管理、查看所有统计 |
|
||
|
||
```python
|
||
# UserProfile 扩展
|
||
class UserProfile(models.Model):
|
||
user = models.OneToOneField(User)
|
||
role = models.CharField(choices=[
|
||
("operator", "操作工"),
|
||
("leader", "组长"),
|
||
("admin", "管理员"),
|
||
], default="operator")
|
||
group = models.ForeignKey("WorkGroup", null=True) # 操作工和组长属于某个工组
|
||
|
||
class WorkGroup(models.Model):
|
||
name = models.CharField(max_length=100)
|
||
leader = models.ForeignKey(UserProfile, null=True, related_name="led_group")
|
||
```
|
||
|
||
### 6.4 模型管理设计
|
||
|
||
```python
|
||
class ModelRegistry(models.Model):
|
||
"""模型版本注册表"""
|
||
name = models.CharField(max_length=100) # 文件名（含扩展名）
|
||
runtime = models.CharField(choices=["pt", "onnx"])
|
||
file_path = models.CharField(max_length=500) # 服务器本地路径
|
||
file_size = models.IntegerField() # 字节数
|
||
is_active = models.BooleanField(default=False) # 当前生效模型
|
||
uploaded_by = models.ForeignKey(UserProfile)
|
||
uploaded_at = models.DateTimeField(auto_now_add=True)
|
||
notes = models.TextField(blank=True)
|
||
```
|
||
|
||
**模型管理规则：**
|
||
- 同时只有一个 `is_active=True`
|
||
- 最多保留 10 个版本，超出时自动删除最早上传的非活跃版本及其文件
|
||
- 切换模型时：更新 `is_active` → 调用 `POST http://localhost:8001/api/model/reload`
|
||
|
||
### 6.5 管理员可配置参数
|
||
|
||
| 参数类别 | 具体参数 |
|
||
|---------|---------|
|
||
| 推理参数 | 置信度阈值、IOU阈值、图像输入尺寸 |
|
||
| 模型管理 | 上传模型、切换活跃模型、查看备份列表 |
|
||
| 产线配置 | 产线名称、前置机IP（仅记录，不主动通信） |
|
||
| 用户管理 | 新增/停用账号、分配角色、分配工组 |
|
||
| 告警规则 | Phase 2，预留接口 |
|
||
|
||
### 6.6 数据模型设计
|
||
|
||
```python
|
||
class DefectResult(models.Model):
|
||
"""单次检测记录"""
|
||
operator = models.ForeignKey(UserProfile, null=True)
|
||
line_id = models.CharField(max_length=50, blank=True)
|
||
source_image = models.ImageField(upload_to="originals/")
|
||
annotated_image = models.ImageField(upload_to="annotated/", null=True)
|
||
verdict = models.CharField(choices=["pass", "fail"])
|
||
defect_count = models.IntegerField(default=0)
|
||
max_severity = models.CharField(choices=["none","rework","minor","major","fatal"])
|
||
detections_json = models.TextField() # 完整缺陷列表JSON
|
||
avg_confidence = models.FloatField()
|
||
duration_ms = models.IntegerField()
|
||
model_version = models.CharField(max_length=100)
|
||
created_at = models.DateTimeField(auto_now_add=True)
|
||
|
||
|
||
class ProductionStat(models.Model):
|
||
"""每日产线统计（聚合）"""
|
||
stat_date = models.DateField()
|
||
line_id = models.CharField(max_length=50)
|
||
total_count = models.IntegerField(default=0)
|
||
pass_count = models.IntegerField(default=0)
|
||
fail_count = models.IntegerField(default=0)
|
||
defect_dist = models.TextField() # 各缺陷类型数量JSON
|
||
|
||
|
||
class SysConfig(models.Model):
|
||
"""系统参数键值存储"""
|
||
key = models.CharField(max_length=100, unique=True)
|
||
value = models.TextField()
|
||
updated_at = models.DateTimeField(auto_now=True)
|
||
```
|
||
|
||
### 6.7 API 接口设计
|
||
|
||
```
|
||
# 认证（直接复用现有代码）
|
||
POST /api/auth/login
|
||
POST /api/auth/refresh
|
||
POST /api/auth/logout
|
||
GET /api/user/me
|
||
|
||
# 检测结果（capture推送入口）
|
||
POST /api/detect/result/ # capture 上报推理结果
|
||
GET /api/detect/results/ # 列表（按角色自动过滤）
|
||
GET /api/detect/results/{id}/
|
||
|
||
# 统计
|
||
GET /api/stats/overview/ # 今日合格率、缺陷总数
|
||
GET /api/stats/trend/ # 近N天趋势
|
||
GET /api/stats/defect-dist/ # 缺陷类型分布
|
||
|
||
# 模型管理（管理员）
|
||
GET /api/admin/models/ # 模型列表（最多10条）
|
||
POST /api/admin/models/upload/ # 上传新模型
|
||
POST /api/admin/models/{id}/activate/ # 切换活跃模型（触发vision热重载）
|
||
DELETE /api/admin/models/{id}/ # 手动删除某个备份
|
||
|
||
# 系统配置（管理员）
|
||
GET /api/admin/config/
|
||
PATCH /api/admin/config/
|
||
|
||
# 用户管理（管理员）
|
||
GET /api/admin/users/
|
||
POST /api/admin/users/
|
||
PATCH /api/admin/users/{id}/
|
||
GET /api/admin/groups/
|
||
POST /api/admin/groups/
|
||
|
||
# 系统日志（直接复用）
|
||
GET /api/admin/logs/
|
||
```
|
||
|
||
---
|
||
|
||
## 7. mingxi-frontend（管理后台）
|
||
|
||
### 7.1 定位
|
||
|
||
**纯管理后台**，供组长、厂长、管理员通过浏览器使用。操作工不通过浏览器操作（操作工使用前置机桌面程序）。
|
||
|
||
### 7.2 技术栈
|
||
|
||
```
|
||
框架：Vue 3 + Vite + TypeScript（保持现有配置不变）
|
||
UI：Element Plus（复用现有）
|
||
图表：ECharts（统计报表）
|
||
实时：短轮询（每1秒请求一次最新记录，满足1-2秒延迟要求，无需WebSocket）
|
||
```
|
||
|
||
> 短轮询而非 WebSocket：部署简单，Django 无需 Channels，延迟满足要求。
|
||
|
||
### 7.3 页面规划
|
||
|
||
| 路由 | 页面 | 可见角色 | 现有/新增 |
|
||
|------|------|---------|---------|
|
||
| `/login` | 登录 | 全部 | 复用 |
|
||
| `/dashboard` | 实时监控看板 | 组长、管理员 | **新增** |
|
||
| `/history` | 检测历史记录 | 全部（按权限过滤） | **新增** |
|
||
| `/stats` | 统计报表 | 组长、管理员 | **新增** |
|
||
| `/admin/models` | 模型管理 | 管理员 | **新增** |
|
||
| `/admin/config` | 系统配置 | 管理员 | **新增** |
|
||
| `/admin/users` | 用户管理 | 管理员 | 复用改造 |
|
||
|
||
### 7.4 实时监控看板（/dashboard）
|
||
|
||
- 最新检测结果卡片（标注图缩略图 + 结论）
|
||
- 今日合格率仪表盘
|
||
- 缺陷类型分布饼图
|
||
- 近10条记录时间线
|
||
- 每1秒轮询 `/api/detect/results/?limit=1&ordering=-created_at`
|
||
|
||
### 7.5 需删除的现有页面
|
||
|
||
```
|
||
SceneNews 相关页面
|
||
通用YOLO视频/摄像头检测页面
|
||
驾驶员疲劳检测相关组件
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 系统间通信
|
||
|
||
### 8.1 完整通信图
|
||
|
||
```
|
||
前置机（Windows） 推理服务器（Linux）
|
||
┌──────────────────────┐ ┌──────────────────────┐
|
||
│ mingxi-capture │ │ mingxi-vision │
|
||
│ │──① POST─────→│ /api/detect │
|
||
│ QThread推理线程 │←─ 结果返回──│ asyncio.Lock串行 │
|
||
│ │ └──────────────────────┘
|
||
│ 主线程展示结果 │
|
||
│ │ ┌──────────────────────┐
|
||
│ upload_queue线程 │──② 异步────→│ mingxi-backend │
|
||
│ （失败则重试） │ │ /api/detect/result │
|
||
└──────────────────────┘ │ │
|
||
│ SQLite存档 │
|
||
└──────────┬───────────┘
|
||
│ REST API
|
||
┌──────────▼───────────┐
|
||
│ mingxi-frontend │
|
||
│ 浏览器短轮询 │
|
||
└──────────────────────┘
|
||
管理员/组长/厂长 浏览器访问
|
||
```
|
||
|
||
### 8.2 关键通信约定
|
||
|
||
| 通信路径 | 协议 | 格式 | 备注 |
|
||
|---------|------|------|------|
|
||
| capture → vision | HTTP POST | multipart/form-data（图像二进制） | 同步，等待结果 |
|
||
| vision → capture | HTTP Response | JSON（含 base64 标注图） | 一次请求一次响应 |
|
||
| capture → backend | HTTP POST | JSON（推理结果） | 异步，本地队列保障 |
|
||
| browser → backend | HTTP REST | JSON | 短轮询 + 增删改查 |
|
||
| backend → vision（热重载） | HTTP POST | JSON | 仅管理员切换模型时触发 |
|
||
|
||
### 8.3 前置机配置两个地址
|
||
|
||
前置机桌面程序配置界面中填写：
|
||
- **推理服务地址**：`http://192.168.x.x:8001`（vision）
|
||
- **后台服务地址**：`http://192.168.x.x:8000`（backend）
|
||
|
||
两个服务通常在同一台服务器上，填写相同IP、不同端口。
|
||
|
||
---
|
||
|
||
## 9. 硬件集成（相机配置）
|
||
|
||
### 9.1 推荐型号
|
||
|
||
| 阶段 | 型号 | 分辨率 | 接口 | 用途 |
|
||
|------|------|--------|------|------|
|
||
| Demo/POC | MV-CS060-10GM | 600万像素 | USB3.0 | 算法验证，接工业PC |
|
||
| 产线部署 | MV-CA060-10GM | 600万像素 | GigE | 稳定产线，线长100m |
|
||
| 大板检测 | MV-CA120-10GM | 1200万像素 | GigE | 视野≥200mm的PCB |
|
||
|
||
### 9.2 分辨率选型计算
|
||
|
||
```
|
||
视野：100mm × 75mm（单次拍摄区域）
|
||
最小缺陷：0.1mm（针孔、断路）
|
||
像素尺寸 ≤ 0.1mm ÷ 3 = 0.033mm/pixel
|
||
所需分辨率：100 ÷ 0.033 ≈ 3030 pixels（水平）
|
||
结论：600万像素（3072×2048）满足需求 ✓
|
||
```
|
||
|
||
### 9.3 配套清单（单工位 Demo 版）
|
||
|
||
| 器材 | 型号/规格 | 估价 |
|
||
|------|----------|------|
|
||
| 工业相机 | MV-CS060-10GM | 1800-2500元 |
|
||
| 镜头 | 16mm C口定焦（1/1.8"靶面） | 500-800元 |
|
||
| LED环形光源 | 同轴/低角度，直径120mm | 400-600元 |
|
||
| USB3.0线缆 | ≤3m，锁扣式 | 80-150元 |
|
||
| 简易支架光箱 | 铝型材，可调高度 | 200-400元 |
|
||
| **合计** | | **约 3000-4450元** |
|
||
|
||
---
|
||
|
||
## 10. 开发阶段划分
|
||
|
||
### Phase 1：Demo版（目标：2026年6月中旬决赛前）
|
||
|
||
**路演方式：** 预先准备好的PCB图片，模拟模式演示完整流程，约5分钟。
|
||
|
||
**核心展示：** 操作工点击→检测→标注图展示→管理后台历史记录。
|
||
|
||
```
|
||
P0（必须完成，路演核心）：
|
||
[ ] mingxi-vision：图片推理API + asyncio.Lock + 启动warmup
|
||
[ ] mingxi-capture：PyQt5桌面程序，Mock模式，结果展示界面
|
||
[ ] mingxi-backend：接收capture推送，DefectResult落库，基础REST API
|
||
[ ] mingxi-frontend：登录 + 检测历史列表 + 详情页
|
||
[ ] mingxi-backend：三级权限（操作工/组长/管理员）
|
||
|
||
P1（有时间做，加分项）：
|
||
[ ] mingxi-frontend：实时监控看板（短轮询）
|
||
[ ] mingxi-backend：模型管理（上传/备份/切换）
|
||
[ ] mingxi-frontend：统计报表页
|
||
[ ] mingxi-capture：系统托盘图标
|
||
```
|
||
|
||
### Phase 2：POC版（目标：2026年Q3，接入真实相机）
|
||
|
||
```
|
||
[ ] mingxi-capture：接入海康MVS SDK，对接 MV-CS060-10GM
|
||
[ ] mingxi-capture：PLC触发接口（串口/数字IO）
|
||
[ ] mingxi-vision：ONNX Runtime部署（export_onnx.py导出）
|
||
[ ] mingxi-vision：模型热重载接口完善
|
||
[ ] mingxi-backend：告警规则引擎（连续不良数、缺陷率阈值）
|
||
[ ] 完成1家PCB厂POC试用
|
||
```
|
||
|
||
### Phase 3：产线版（目标：2026年Q4，首单签约）
|
||
|
||
```
|
||
[ ] 多相机支持（多条产线并发采集）
|
||
[ ] 模型迁移学习（基于客户真实样本微调）
|
||
[ ] 告警推送（企业微信/短信）
|
||
[ ] MES/ERP对接接口
|
||
[ ] 边缘部署探索（Jetson Orin，脱离大型服务器）
|
||
[ ] 软件著作权申请
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 开发环境搭建
|
||
|
||
### 11.1 各项目启动命令
|
||
|
||
```bash
|
||
# mingxi-vision（推理服务器，Linux）
|
||
cd mingxi-vision
|
||
pip install -r requirements.txt
|
||
uvicorn main:app --host 0.0.0.0 --port 8001 --workers 1
|
||
|
||
# mingxi-backend（推理服务器，Linux）
|
||
cd mingxi-backend
|
||
pip install -r requirements.txt
|
||
python manage.py migrate
|
||
python manage.py runserver 0.0.0.0:8000
|
||
|
||
# mingxi-frontend（推理服务器，Linux）
|
||
cd mingxi-frontend
|
||
npm install
|
||
npm run build # 生产：dist/ 由 nginx 托管
|
||
npm run dev # 开发：localhost:5173
|
||
|
||
# mingxi-capture（前置机，Windows，开发阶段）
|
||
cd mingxi-capture
|
||
pip install -r requirements.txt
|
||
python main.py # 启动桌面程序，自动进入Mock模式（若配置了图片目录）
|
||
```
|
||
|
||
### 11.2 环境变量
|
||
|
||
```bash
|
||
# mingxi-vision/.env
|
||
MODEL_PATH=./models/pcb_defect_v1.pt
|
||
RUNTIME=ultralytics # 或 onnx
|
||
DEVICE=cuda # 或 cpu
|
||
CONF_THRESHOLD=0.45
|
||
|
||
# mingxi-backend/.env
|
||
SECRET_KEY=...
|
||
DATABASE_PATH=./db.sqlite3
|
||
VISION_SERVICE_URL=http://127.0.0.1:8001
|
||
CORS_ALLOWED_ORIGINS=http://localhost:5173
|
||
MODEL_STORAGE_DIR=/opt/mingxi/models
|
||
MODEL_MAX_BACKUPS=10
|
||
```
|
||
|
||
### 11.3 开发联调注意事项
|
||
|
||
- `mingxi-capture` 在 Windows 开发机上运行，配置 vision/backend 为开发机局域网IP
|
||
- `mingxi-vision` 和 `mingxi-backend` 建议在同一台机器（或WSL2）上启动
|
||
- SQLite 文件在 `mingxi-backend/` 目录下，无需额外数据库服务
|
||
|
||
---
|
||
|
||
## 12. 参考资料
|
||
|
||
| 资料 | 路径/来源 |
|
||
|------|---------|
|
||
| 创业技术书 | `梅州创新创业大赛/创业技术书v1.3.docx` |
|
||
| 明析vision架构详细设计 | `梅州创新创业大赛/mingxi-vision-架构设计.md` |
|
||
| 现有后端代码 | `yolo_classification_system/` |
|
||
| PCB缺陷检测调研 | `梅州创新创业大赛/pcb缺陷检测初步方案.md` |
|
||
| 海康MVS SDK | 随MVS安装包提供，路径：`C:\Program Files (x86)\MVS\Development\` |
|
||
| HRIPCB数据集 | 公开学术数据集，CC BY 4.0，6类缺陷，10,000+样本 |
|
||
| PyQt5文档 | https://doc.qt.io/qtforpython-5/ |
|
||
| PyInstaller文档 | https://pyinstaller.org/en/stable/ |
|