166 lines
6.6 KiB
Markdown
166 lines
6.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
适用于 `mingxi_platform` 仓库的 Claude Code 协作规则。
|
||
|
||
---
|
||
|
||
## 会话启动
|
||
|
||
每次新 session 开始时，按顺序执行：
|
||
|
||
1. 读取 `docs/PROGRESS.md` — 查看当前焦点和各任务状态
|
||
2. 执行 `git log --oneline -10` — 查看最近提交，了解上次做到哪里
|
||
3. 确认当前处于哪个 Phase（Demo / POC / 产线），再开始任务
|
||
|
||
> 需要了解架构细节时，读 `docs/明析平台-软件重构设计文档.md`。
|
||
|
||
> 用户说"继续开发"或"继续上次的"时，完成以上步骤后直接接续，不重新介绍项目背景。
|
||
|
||
---
|
||
|
||
## 项目定位
|
||
|
||
**明析平台**——基于机器视觉的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/PROGRESS.md` 状态标签 + 当前焦点 |
|
||
| 架构或接口发生变化 | `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 文件
|