mingxi_platform/CLAUDE.md

CLAUDE.md

适用于 mingxi_platform 仓库的 Claude Code 协作规则。

---

会话启动

每次新 session 开始时，按顺序执行：

1. 读取 docs/明析平台-软件重构设计文档.md — 了解整体架构和当前阶段
2. 执行 git log --oneline -10 — 查看最近提交，了解上次做到哪里
3. 确认当前处于哪个 Phase（Demo / POC / 产线），再开始任务

用户说"继续开发"或"继续上次的"时，完成以上步骤后直接接续，不重新介绍项目背景。

---

项目定位

明析平台——基于机器视觉的PCB线路板缺陷检测系统。

• 参赛背景：梅州市2026年新一代电子信息暨人工智能产业创新创业大赛·初创企业（创客）组
• 当前阶段：Phase 1 Demo（目标：2026年6月决赛前完成可路演版本）
• 团队规模：5人，AI辅助开发，所有改动优先保证可读、可理解、可接手
• 核心链路：前置相机 → mingxi-capture → mingxi-vision → mingxi-backend → 浏览器管理后台

两台机器部署：

• 前置机（Windows 7 SP1+工业PC）：运行 mingxi-capture.exe
• 推理服务器（Linux + GPU）：运行 mingxi-vision、mingxi-backend、mingxi-frontend

---

目录职责

目录	说明
mingxi-capture/	PyQt5 Windows桌面程序：相机采集、手动触发、结果展示、异步上报
mingxi-vision/	FastAPI推理服务：YOLOv8/ONNX推理、asyncio.Lock串行、模型热重载
mingxi-backend/	Django业务后端：三级权限、SQLite落库、模型管理、REST API
mingxi-frontend/	Vue3管理后台：纯管理端（组长/厂长/管理员），短轮询实时监控
docs/	所有技术文档，与代码同等重要
docs/明析平台-软件重构设计文档.md	系统整体架构，每次架构变更必须同步更新
docs/mingxi-vision-架构设计.md	vision子项目详细设计
references/	参考视频和脚本，不进核心开发流程

---

修改原则

• 先读现有实现和相关文档，再动手；优先最小化改动范围。
• 已有实现可复用时，不新增平行实现。
• 先定位根因，再修复问题，不做只遮盖现象的补丁。
• 非任务要求，不改数据库字段名、API响应字段名、接口路径。
• 涉及推理引擎（engine/）、数据库迁移（migrations/）、模型管理时，必须保守处理。

---

文档同步要求

代码和文档必须同步提交，不允许代码改了文档没跟上。

发生什么	必须更新
架构或接口发生变化	docs/明析平台-软件重构设计文档.md
mingxi-vision 内部设计变化	docs/mingxi-vision-架构设计.md
做了重要技术决策	docs/decisions/ 新增 ADR 文件
阶段目标或优先级变化	docs/明析平台-软件重构设计文档.md 第10节

ADR 文件命名：docs/decisions/00N-简短描述.md，包含：背景、决策、原因、影响。

---

技术约定

通用

• Python 版本：所有 Python 子项目统一使用 Python 3.8，不使用 3.9+ 特性
• 注释语言：中文注释，只写 WHY，不写 WHAT

mingxi-capture

• GUI 框架：PyQt5（不用 PyQt6，需兼容 Windows 7 SP1）
• 推理调用：同步 HTTP，在 QThread 中执行，禁止在主线程发网络请求
• 上报队列：异步线程 + 本地 SQLite，失败重试不超过 10 次
• 打包：PyInstaller，目标平台 Windows x64

mingxi-vision

• 框架：FastAPI，启动参数 --workers 1（GPU 不支持多进程共享）
• Pydantic：使用 v1（pydantic==1.10.x），不使用 v2 语法
• 推理并发：必须通过 asyncio.Lock 串行化，不允许并发进入 engine.detect()
• 模型加载：启动时加载并 warmup，禁止懒加载（避免路演首次延迟）
• 图像读取：使用内存读取（np.frombuffer + cv2.imdecode），禁止写临时文件

mingxi-backend

• 框架：Django 4.1，数据库 SQLite（内网单服务器，无需 MySQL）
• 认证：JWT，从 yolo_classification_system 复用，不重写
• 权限过滤：operator 只见自己的记录，leader 见本组，admin 见全部
• 模型备份上限：10个，超出自动删除最早的非活跃版本及文件

mingxi-frontend

• 框架：Vue 3 + Vite + TypeScript
• 实时更新：短轮询（每1秒），不引入 WebSocket（部署复杂度不值得）
• 定位：纯管理后台，操作工不使用浏览器

---

安全要求

• 严禁将 .env、config.ini、queue.db、模型文件（.pt/.onnx）提交到 git
• 模型文件单独管理（共享盘或对象存储），git 只存代码和文档
• config.ini 含服务器地址，已在 .gitignore 中，永远不提交
• 如需提供配置示例，创建 config.ini.example（含占位值，不含真实地址）

---

验证要求

改动完成后做最小必要验证：

• 推理链路改动：用测试图片确认 /api/detect 返回结构正确，verdict / defects 字段完整
• 数据库改动：运行 python manage.py migrate，确认无报错，查询结果符合预期
• 权限改动：分别用三种角色的 token 验证返回数据范围正确
• capture UI 改动：在 Windows 环境确认界面渲染、按钮响应、结果展示正常
• 如无法本地验证，必须说明原因和风险

---

提交规范

格式：<type>(<scope>): <简短描述>

type	用途
feat	新功能
fix	修复问题
docs	文档变更
refactor	重构（不改功能）
chore	构建/配置/依赖
test	测试相关

scope 对应子项目或文档：

feat(vision): 实现 asyncio.Lock 推理串行化
feat(capture): 完成 MockCamera 模拟模式
feat(backend): 新增模型管理上传接口
feat(frontend): 完成检测历史列表页
fix(vision): 修复 ONNX 后处理坐标还原错误
docs: 更新软件重构设计文档至 v2.0
chore(capture): 更新 PyInstaller 打包配置

---

提交前检查

• 未改动无关文件
• 未引入不必要重构
• 未硬编码服务器地址、密码、密钥等敏感信息
• 未提交 .env、config.ini、.pt/.onnx 模型文件
• 未留下临时代码、调试 print、未说明的 TODO
• 接口字段变更已同步更新 docs/明析平台-软件重构设计文档.md
• 重要架构决策已补 docs/decisions/ ADR 文件