pcb-afm-simulation-system

PCB轴向磁通电机自动化仿真系统

双系统解耦的轴向磁通电机自动化仿真平台：Web端方案生成 + 本地EXE仿真执行

项目	内容
文档版本	V1.4（代码评审修复）
作者	Car.Lin
启动日期	2026-08-27
当前状态	Phase 1/2/3/4 全部完成，第三方代码评审 P0 问题已修复
设计方案	PCB轴向磁通电机自动化仿真系统设计方案介绍.md
远程仓库	https://gogsgit.ez4l.com/carlin/pcb-afm-simulation-system

---

项目目标

构建一个通用的、可扩展的、双系统解耦的轴向磁通电机自动化仿真平台：

• 系统一（Web端）：输入边界条件 → 基于经验库+规则+AI生成仿真方案 → 人工确认 → 下发
• 系统二（本地EXE）：读取方案 → 驱动Motor-CAD自动仿真 → 输出结果 → 回传
• 核心闭环：边界条件 → 方案 → 仿真 → 结果 → 反馈调整 → 经验库积累

---

已完成里程碑

Phase 1（最小闭环）— 全部完成

里程碑	内容	状态	Commit
M1	环境验证 + 单工况仿真脚本	✅ 完成	75347b6
M2	参数扫描引擎（单参数/多参数）	✅ 完成	a43d971
M3	方案JSON接口 + 本地PySide6 GUI	✅ 完成	cbd9402
M4	经验库雏形 + 反馈闭环	✅ 完成	f20bef9

Phase 1 验证结果（MARS-12S10P SSSR，气隙扫描3点）：

• 平均转矩 0.4677~0.5663 Nm，转矩脉动 1.75~5.45%，效率 84.93~86.35%
• 物理趋势全部符合预期（转矩/脉动随气隙增大而减小，效率略升）

Phase 2（Web端方案系统）— 全部完成

里程碑	内容	状态	Commit
P2-M1	Web端基础框架（FastAPI + Vue3 + SQLite + CRUD API）	✅ 完成	1ea7653
P2-M2	边界条件输入 + 方案编辑器（规则引擎生成方案）	✅ 完成	a95c0db
P2-M3	经验库Web端增强 + 结果分析仪表盘（ECharts）	✅ 完成	9885437
P2-M4	双系统API联调 + 知识库管理（经验库CRUD/导入/系统二客户端增强）	✅ 完成	25ee19f
P2-M5	Phase 2 验收（自动化测试+前端人工验收+文档完善）	✅ 完成	0df69f2
P2-补丁	前端全面中文化 + Dashboard图表对齐修复	✅ 完成	2660df7

Phase 3（AI驱动智能仿真闭环）— 全部完成

基于第三方专家评审意见，将仿真策略从"固定批量DoE"升级为"多保真度+可行性优先+批量自适应闭环"，引入Kimi k3大模型。

里程碑	内容	状态	Commit
P3-M1	AI服务层基础架构（Kimi客户端+JSON Schema V2+多保真度框架）	✅ 完成	0df69f2
P3-M2	L0解析预筛选 + 可行性优先搜索框架（LHS+主动学习+信任域）	✅ 完成	7dab664
P3-M3	AI方案生成器（自然语言→结构化仿真方案）	✅ 完成	c12a8e6
P3-M4	AI结果分析师 + 多保真度校准 + 置信等级（A-D）+ 六类收敛判据	✅ 完成	29f6cbd
P3-M5	经验库AI增强 + 批量自适应闭环 + 整体验收	✅ 完成	2d71424

Phase 3 核心能力：

• Kimi k3 大模型集成：API端点 https://api.kimi.com/coding/v1，模型 k3
• L0 解析预筛选：14+约束检查（几何/电气/热/制造），排除明显不可行区域
• 可行性优先搜索：LHS初始采样 + 主动学习批量选点 + 局部信任域精修
• 多保真度校准：L0(解析)→L1(磁路)→L2(2D FEA)→L3(3D FEA)→L4(瞬态热耦合)，偏差修正
• 置信等级评估：A-D四级，基于保真度(40%)+样本密度(25%)+收敛性(25%)-异常惩罚(10%)
• 六类收敛判据：目标稳定性/最优位置/代理误差/约束满足/样本密度/物理一致性
• 自适应闭环：自然语言→AI方案→L0筛选→主动搜索→仿真→AI分析→经验提取→下一批
• 32个P3 API端点：覆盖AI/搜索/方案生成/结果分析/自适应闭环全流程

Phase 4（Web端AI集成 + 双系统闭环 + 批量调度 + 部署）— 全部完成

将P3的AI能力前端化，打通Web端与本地仿真执行的双系统闭环，实现批量调度、实时监控、高级可视化和部署打包。

里程碑	内容	状态	Commit
P4-M1	前端AI功能集成（6个AI页面 + API封装 + 通用组件）	✅ 完成	0da99ed
P4-M2	双系统任务下发与回传（后端任务管理 + 本地执行器 + 前端任务页）	✅ 完成	25ae70f
P4-M3	批量调度 + 实时监控 + 增强版MotorCAD核心（16项鲁棒性措施）	✅ 完成	315383c
P4-M4	高级可视化（4种ECharts图表） + 自动报告生成（Word/JSON）	✅ 完成	fb5a72e
P4-M5	部署打包（Docker + docker-compose + nginx + Windows部署脚本） + 验收测试	✅ 完成	35b3f2a
P4-补丁1	修复export_results API兼容性（pymotorcad 0.8.8需要solution_type参数）	✅ 完成	f3b492a
P4-补丁2	扩展指标别名（12→20个指标） + 测试脚本弹窗抑制	✅ 完成	6a8bc80

Phase 4 核心能力：

• 前端AI页面（10个新增页面）：AI方案生成/L0预筛选/自适应优化/AI结果分析/多保真度校准/经验库增强/任务管理/实时监控/高级可视化
• 双系统闭环：Web创建任务 → 本地执行器轮询 → 领取任务 → 执行仿真 → 上报进度 → 回传结果 → Web存储展示
• 批量调度器：优先级队列(1-10) + 最大并行(默认2) + 任务依赖 + 断点续跑 + 实时统计
• 实时监控仪表盘：6项统计卡片 + 运行中/排队/历史任务面板 + 5秒自动刷新
• 高级可视化：Pareto前沿散点图 + 收敛轨迹折线图 + 多方案雷达图 + 参数敏感性热力图
• 增强版MotorCAD核心（16项鲁棒性措施）：
  • 连接安全：open_new_instance=True + set_visible(True) + BlackBox无头模式
  • 错误处理：MotorCADError优先捕获 + 单点超时重试 + 实例崩溃自动重连
  • 批量安全：MessageDisplayState=2弹窗抑制 + try/finally恢复 + 参数写入回读校验 + 每点基线重载
  • 数据完整：分号CSV解析 + 中英文字段别名 + 逐点双写(CSV+JSON) + flush+fsync
  • 五层自检：连接/权限/许可/模型/脚本层启动前自检
  • 变量名版本映射：可配置映射表，不硬编码
• 自动报告生成：Word报告（封面/参数/结果/AI分析/建议） + JSON fallback
• 部署方案：Dockerfile + docker-compose + nginx反向代理 + Windows一键部署脚本
• Motor-CAD实测验证（MARS-12S10P，5000rpm）：连接→计算→导出→解析全流程成功，效率86.06%，总损耗41.945W，磁场计算138.1s/点

代码评审修复（V1.4）

第三方代码评审报告 V1.0（2026-08-28）后，修复了 20+ 项 P0 问题：

类别	修复项
数据完整性	A1 指标清单单一事实源（metrics_constants.py）；A2 mock假数据静默上报改为failed；A3/A4/A5 task_executor复用RobustMotorCADSolver；A7 GUI plan回写；A8 204空响应处理
稳定性	B1 BatchScheduler死锁（Lock→RLock）；B2 closeEvent防QThread崩溃；B3 输入校验防全局崩溃；B4 finally disconnect防进程泄漏；B5 失败点落盘；B7 本地任务防重复执行
AI逻辑	C1 转矩方向显式映射表；C2 六类收敛判据全部接入；C3 L0最低覆盖判定；C4 信任域锚点按方向选max/min；C5 信任域中心随最优点迁移
前端	D1 6个AI页面994处\uXXXX还原中文；D2 axios响应拦截器统一.data；D3 ECharts动态导入修复；D4 热力图改为真实参数聚合
部署/安全	E1 .dockerignore防密钥泄露；E2 空值环境变量不覆盖.env；E3 SQLite持久化卷；F2 级联删除+PRAGMA foreign_keys；F3 web后端.py纯ASCII合规
纪律	F4 Git preflight改为硬拒绝；F5 GET download只读，状态迁移改POST

详见 docs/CODE_REVIEW_RESPONSE.md。

第二轮修复（P1 + 风险项）：

类别	修复项
状态统一	3.4-34 新建 status_constants.py，全仓库仿真点状态统一为 "OK"/"FAILED"
Session	3.4-25 task_manager.py 7处 next(get_db()) 改为 with SessionLocal()
API安全	E4 可选API Key中间件 + max_tokens上限(8192)
求解稳定	3.1-1 solver_core 单点超时(600s) + 连续失败3次自动重连
数据安全	plan_id加随机后缀防碰撞；分页limit上限200；经验库去重
验证	75个Python文件语法通过，纯ASCII合规，关键模块导入正常

---

快速开始

环境要求

项	要求	验证
系统	Windows 10/11	—
Motor-CAD	2026R1 (v261)	echo %MOTORCAD_ACTIVEX%
Python	≥ 3.10	python --version
PyMotorCAD	pip install ansys-motorcad-core	python -c "import ansys.motorcad.core"
Node.js	≥ 18（Web端前端）	node --version
许可证	FlexNet ANSYSLMD_LICENSE_FILE=1055@localhost	ANSYS License Management Center

系统二（本地仿真执行端）

# 安装依赖
pip install ansys-motorcad-core pyside6 pandas

# 单工况验证
python scripts/run_single.py

# 参数扫描
python scripts/run_scan.py --plan simulation_plan.json

# 启动本地GUI
python scripts/run_gui.py

系统一（Web端方案生成）

# 后端
cd web/backend
pip install -r requirements.txt
python run.py
# 后端运行在 http://127.0.0.1:8000，API文档 http://127.0.0.1:8000/docs

# 前端（另开终端）
cd web/frontend
npm install
npm run dev
# 前端运行在 http://localhost:5173，自动代理 /api 到后端

Web端核心API

方法	路径	用途
GET	/api/health	健康检查
GET/POST	/api/projects	项目列表/创建
GET	/api/scan-parameters	可扫描参数注册表
POST	/api/generate-plan	规则引擎生成方案
POST	/api/projects/{id}/generate-plan	为项目生成方案
GET	/api/plans/{id}/download	下载方案（系统二兼容格式）
POST	/api/plans/{id}/upload-results	上传仿真结果CSV
GET	/api/analytics/metrics	指标定义列表（11项）
GET	/api/analytics/experience/stats	经验库统计（总数/拓扑分布/指标范围）
POST	/api/analytics/experience/similar	相似案例检索（参数距离匹配）
GET	/api/analytics/plans/{id}/trend	参数-指标趋势数据（散点图）
GET	/api/analytics/plans/{id}/pareto	Pareto前沿（效率vs损耗）
GET	/api/analytics/plans/{id}/sensitivity	参数敏感性排名（Pearson相关）
GET	/api/analytics/projects/{id}/overview	项目概览统计

---

项目结构

PCB轴向磁通电机自动化仿真系统/
├── README.md                          # 本文件
├── AGENTS.md                          # AI工具工作说明（必读）
├── .gitignore
├── PCB轴向磁通电机自动化仿真系统设计方案介绍.md  # 完整设计方案V1.1
├── docs/
│   ├── KNOWLEDGE_BASE.md              # 核心知识库（方法/参数语义/坑/SOP）
│   └── CONVERSATION_LOG.md            # 对话与决策记录（带时间戳）
├── src/
│   ├── solver_core.py                 # 仿真核心（Motor-CAD连接/参数/求解/结果提取）
│   ├── scan_engine.py                 # 参数扫描引擎
│   ├── plan_schema.py                 # 方案JSON Schema定义
│   ├── experience_db.py               # 经验库（SQLite）
│   ├── api_client.py                  # Web端API客户端（系统二↔系统一通信）
│   └── gui/
│       └── main.py                    # PySide6 GUI主程序
├── scripts/
│   ├── run_single.py                  # 单工况快速验证
│   ├── run_scan.py                    # 命令行扫描入口
│   ├── run_gui.py                     # 本地GUI启动
│   └── test_api_client.py             # API客户端测试
├── web/                                # 系统一（Web端）
│   ├── backend/                        # FastAPI后端
│   │   ├── app/
│   │   │   ├── main.py                # FastAPI入口
│   │   │   ├── config.py              # 配置
│   │   │   ├── database.py            # SQLAlchemy数据库
│   │   │   ├── models/                # ORM模型（Project/Plan/Result/Experience）
│   │   │   ├── schemas/               # Pydantic Schema
│   │   │   ├── routers/               # API路由（projects/plans/experience/generation/analytics）
│   │   │   └── services/
│   │   │       ├── rule_engine.py     # 规则引擎（参数注册表/范围推荐/方案生成）
│   │   │       └── analytics.py       # 分析服务（统计/趋势/Pareto/敏感性/相似检索）
│   │   ├── requirements.txt
│   │   └── run.py
│   └── frontend/                       # Vue3前端
│       ├── src/
│       │   ├── api/index.ts           # API调用层
│       │   ├── router/index.ts        # 路由配置
│       │   ├── layouts/MainLayout.vue # 主布局
│       │   └── views/                 # 页面（项目列表/详情/方案详情/经验库/仪表盘）
│       ├── package.json
│       └── vite.config.ts
├── models/
│   └── MARS-12S10P_SSSR_D76-C150_V5.0-0819.mot  # 调试模型（只读）
├── output/                            # 仿真输出（不入库）
├── experience/                        # 经验库数据
├── axial_mag_pull-master/            # 参考案例1：轴向磁拉力仿真
├── torqrippswap-master/              # 参考案例2：转矩脉动参数扫描+GUI
└── 书籍与论文/                         # 理论参考资料

---

参考案例

本项目基于两个已验证的参考案例构建：

案例	路径	核心价值
axial_mag_pull	axial_mag_pull-master/	单一目标微缩闭环验证、三判据校验、AFM轴向力数据口
torqrippswap	torqrippswap-master/	参数扫描引擎、PyQt5 GUI+EXE打包、工程化规范

理论参考

轴向磁通电机基础理论知识参见 书籍与论文/ 目录：

• 《轴向磁通永磁无刷电机（原书第2版）》Jacek F. Gieras — 国际权威，主要参考
• 《轴向磁场无刷同步电机理论与设计》邓秋玲 — 国内工程实践，补充参考

当方案生成、参数初值估算、物理约束规则等需要理论支撑时，优先查阅上述书籍。

---

项目纪律（硬性）

1. 每次运行仿真前 git commit（脚本改动先入库再跑）
2. 每阶段完成后更新 README.md（版本号/状态/路线图）
3. 结果与报告带时间戳+简要说明并提交；报告版本化不覆盖
4. Motor-CAD前台运行，跑完保持打开供人工检查
5. 生成物不入库（output/、*.log、build/、dist/、node_modules/）
6. 原始.mot只读，一切修改在时间戳副本上进行
7. 参数写入后必须回读校验，不一致标记FAILED
8. 每个扫描点重新加载基线模型，防止参数污染
9. 对话与决策带时间戳记入 docs/CONVERSATION_LOG.md
10. 所有 .py / .ps1 源码纯 ASCII，中文用 Unicode 转义或放 Markdown

---

阶段路线图

阶段	目标	状态
Phase 1 M1	环境验证 + 单工况仿真脚本	✅ 完成
Phase 1 M2	参数扫描引擎（单参数/多参数）	✅ 完成
Phase 1 M3	方案JSON接口 + 本地GUI	✅ 完成
Phase 1 M4	经验库雏形 + 反馈闭环	✅ 完成
Phase 2 P2-M1	Web端基础框架（FastAPI + Vue3 + SQLite）	✅ 完成
Phase 2 P2-M2	边界条件输入 + 方案编辑器（规则引擎）	✅ 完成
Phase 2 P2-M3	经验库Web端 + 结果分析仪表盘	🔲 待开始
Phase 2 P2-M4	双系统API联调 + 知识库管理	🔲 待开始
Phase 2 P2-M5	Phase 2 验收	🔲 待开始
Phase 3	算法增强（Morris/LHS/Kriging/NSGA-II）+ DRSS拓扑	🔲 规划中
Phase 4	多物理场（热/结构）+ 多工具扩展	🔲 规划中