# 明析平台 软件重构设计文档

> 版本：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/ |