pcb-afm-simulation-system

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

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

项目	内容
文档版本	V2.1（P6-M1 完成：前端 UI/UX 重构）
作者	Car.Lin
启动日期	2026-08-27
当前状态	P1~P5 全部完成；P6 前端体验优化进行中：P6-M1（UI/UX 全面重构）✅；P6-M2（参数目录单一事实源）🔳 待办；P6-M3（流程引导+检查清单+耗时校准）🔳 待办。进度权威来源：docs/HANDOFF.md 第 3 节
更新日志	CHANGELOG.md（全部历史更新，本文件只保留摘要）
设计方案	PC轴向磁通电机自动化仿真系统设计方案介绍.md（V2.0，已同步实现现状）
论文知识库	docs/PAPER_KNOWLEDGE_BASE.md（无铁心PCB-AFPM 38篇论文精读整理，供软件工程师参考）
上手指南	docs/P1-P5交付总结与上手指南.md（P1-P5 全盘核对 + 目录结构 + 快速开始 + 工程纪律 + 测试体系，新人必读）
远程仓库	https://gogsgit.ez4l.com/carlin/pcb-afm-simulation-system

---

项目目标

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

• 系统一（Web端）：输入边界条件 → 基于经验库+规则+AI生成仿真方案 → 人工确认 → 下发
• 系统二（本地EXE）：读取方案 → 驱动Motor-CAD自动仿真 → 输出结果 → 回传
• 共享核心层 src/afmcore/：指标/拓扑/适配器/策略/L0预筛选的单一事实源，双系统共用
• 核心闭环：边界条件 → 方案 → 仿真 → 结果 → 反馈调整 → 经验库积累

---

最近更新（摘要）

完整历史记录见 CHANGELOG.md；里程碑明细见 docs/P1-P5交付总结与上手指南.md。

日期	内容
2026-09-04	热仿真首次打通：Motor-CAD 稳态热仿真实测跑通（MARS：电磁 127.8s + 热 6.0s），修正 P5-M6 两个错误 API（do_thermal_calculation→do_steady_state_analysis、export_results("Thermal")→"SteadyState"），热指标别名实测登记（绕组 68°C/热点 74.6°C/磁钢 118°C/后轴承 88.5°C）；新增 scripts/run_thermal.py。⚠ MARS 模型环境温度 Ambient_Temperature=125 异常待修正
2026-09-03	仿真失败根因修复：MARS 几何变量名实测修正（RotorOuterDiameter/Stator_Lam_Dia/Stator_Bore/Back_Iron_Thickness/PhaseAdvance/材料名 N42UH）+ 生产链路 3 修复（拓扑预检变量集/执行器 dispatch 状态机/适配器导入路径），多点扫描全链路实测通过（3 点 Airgap，趋势符合电磁学）
2026-09-03	P6-M2/M3 落地：BC 字段目录单一事实源（bc_fields + /api/bc-fields + key 统一 normalize_bc）+ 仿真前检查清单 + 耗时校准（实测 solve_time_s）+ 任务自动展开
2026-09-03	AI 生成链路修复：Kimi max_tokens 撞顶修复 + topology/strategy 归一化兜底 + AI 生成摘要对话框 + 扫描变量归一化（注册表 8→13，AI 推荐变量不再被误裁）
2026-09-03	UI 评审修复闭环：统计卡字段名 Bug + Dashboard 结果加载 + BC 空值折叠 + 失败结果错误信息列 + 监控页合并 + 批量清理入口 + 扫描变量编辑持久化 + 列配置持久化
2026-09-02	AI 方案生成 422 修复（前端拓扑枚举 AFIR→SSSR 对齐单一事实源）+ Web 开发环境联调
2026-09-01	AI 协作方法论框架升级（playbook V2）+ 新增 scripts/check_machine_paths.py 环境体检 + docs/HANDOFF.md
2026-08-30	P6-M1 前端 UI/UX 全面重构（设计令牌 + 信息架构 + PlanDetail 分层）；文档卫生修复；前端 chunk 分包
2026-08-30	P5-M2 拓扑感知变量名映射与执行前校验（修复 plan 23 的 80 点全失败）+ variable-catalog API
2026-08-30	P5-M3~M6：adaptive 三视图 / Morris+IDW 策略 / Maxwell+JMAG 适配器（mock）/ 多物理场 L2 指标（25→35）
2026-08-30	P5-M1~M2：前端 build 类型错误清零（71→0）/ EXE 配置化 + 真实 Motor-CAD 端到端验证
2026-08-29	本地执行器真实仿真全链路打通（P2 关键里程碑）+ 方案详情页三栏重构
2026-08-29	平台化改造五批（afmcore/拓扑注册表/策略层/调度契约/执行桥）+ P3 闭环 + P4 收尾（Schema 统一/EXE 打包/部署）

---

已完成里程碑（概要）

阶段	内容	状态
Phase 1	最小闭环：环境验证 + 扫描引擎 + 方案JSON/GUI + 经验库雏形（MARS-12S10P 气隙扫描验证，物理趋势符合预期）	✅
Phase 2	Web端方案系统（FastAPI + Vue3 + SQLite + 规则引擎 + 边界条件/方案编辑器）	✅
Phase 3	AI驱动智能仿真闭环（Kimi k3 + L0预筛选 + 可行性优先搜索 + 多保真度 + 自适应闭环，32 个 API 端点）	✅
Phase 4	Web AI集成 + 双系统任务闭环 + 批量调度 + 16项鲁棒性 MotorCAD 核心 + 报告生成 + Docker/EXE 部署	✅
P5	平台化增强 M1~M6（build清零 / EXE配置化 / adaptive三视图 / Morris+IDW / 多工具适配器 / 多物理场L2）	✅
P6-M1	前端 UI/UX 全面重构	✅
P6-M2	BC 参数目录单一事实源（bc_fields + normalize_bc 统一 key 口径）	✅
P6-M3	流程引导（仿真前检查清单）+ 耗时校准 + 任务自动展开	✅

Phase 3 核心能力：Kimi k3 大模型集成、L0 解析预筛选（14+ 约束检查）、可行性优先搜索（LHS+主动学习+信任域）、多保真度校准（L0→L4）、置信等级 A-D、六类收敛判据、批量自适应闭环。

Phase 4 核心能力：前端 10 个 AI 页面、双系统任务闭环（Web创建→执行器轮询→仿真→回传）、批量调度器（优先级/并行/依赖/断点续跑）、增强版 MotorCAD 核心（16 项鲁棒性措施）、Word/JSON 自动报告、Docker + Windows 一键部署。

代码评审修复（第三方评审 V1.0 + 二轮，20+ P0 项）：数据完整性 / 稳定性 / AI 逻辑 / 前端 / 部署安全 / 纪律六大类，详见 docs/CODE_REVIEW_RESPONSE.md。

逐里程碑计划 vs 实际交付对照表：docs/P1-P5交付总结与上手指南.md 第 2 节。

---

快速开始

环境要求

项	要求	验证
系统	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

换机/新会话第一步：python scripts/check_machine_paths.py（只读环境体检，缺项给修复建议；--fix 打印修复命令）。

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

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

# 方式一（推荐）：任务执行器 —— 连接 Web 端，认领并执行仿真任务
python scripts/run_task_executor.py --config executor_config.json
#   - enable_mock=true 时不启动 Motor-CAD，可离线验证全链路
#   - 多实例并行：python scripts/run_task_executor_parallel.py --instances 2
#   - 配置项（web_base_url / model_path / tool / instances 等）见 executor_config.json

# 方式二（调试）：独立脚本
python scripts/run_single.py                                # 单工况验证
python scripts/run_scan.py --plan simulation_plan.json      # 参数扫描
python scripts/run_gui.py                                   # 本地 PySide6 GUI

系统一（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 到后端

# 或 Docker 一键部署（P4-M5）
docker-compose up -d

Web端核心API（节选）

完整 API 以 Swagger（/docs）为准——P3 起 AI/搜索/自适应闭环共 32+ 端点，此处仅列常用入口。

方法	路径	用途
GET	/api/health	健康检查
GET/POST	/api/projects	项目列表/创建
GET	/api/scan-parameters	可扫描参数注册表
GET	/api/plans/variable-catalog?topology=SSSR	拓扑感知变量目录（模板参数 + Motor-CAD 实际变量名）
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	指标定义列表（35 项，单一事实源 src/afmcore/metrics.py：电磁25+热6+结构4）
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	项目概览统计
POST	/api/adaptive/loops/{loop_id}/submit-batch	自适应批次下发本地执行器

---

项目结构

PCB轴向磁通电机自动化仿真系统/
├── README.md / CHANGELOG.md / AGENTS.md    # 说明 / 历史更新 / AI工作准则
├── executor_config.json            # 执行器侧车配置（web地址/模型/实例数/工具/mock开关）
├── deploy.ps1 / Dockerfile / docker-compose.yml / nginx.conf   # 部署
├── PCB轴向磁通电机自动化仿真系统设计方案介绍.md   # 设计方案 V2.0
├── ai-collab-dev-playbook-v2.md    # AI 协作方法论框架（可复用）
├── docs/
│   ├── HANDOFF.md                  # 接续指南（进度/阻塞/待办/接续提示词，新会话必读）
│   ├── KNOWLEDGE_BASE.md           # 核心知识库（环境事实/参数语义/坑/SOP）
│   ├── TEST_RECORDS.md             # 测试记录（TEST-001~024，含索引）
│   ├── CONVERSATION_LOG.md         # 会话与决策记录
│   ├── PAPER_KNOWLEDGE_BASE.md     # 无铁心PCB-AFPM论文知识库（38篇）
│   ├── PLATFORM_DESIGN_V2.md       # 平台化升级设计方案
│   ├── P1-P5交付总结与上手指南.md   # 里程碑核对 + 新人上手（必读）
│   ├── CODE_REVIEW_RESPONSE.md     # 代码评审修复记录
│   ├── 前端界面优化建议_V1.md       # B1~B4 前端优化批次（B3/B4 待办）
│   └── archive/                    # 已完结历史计划文档（P3/P4实施计划等）
├── src/                            # 系统二 + 共享核心
│   ├── afmcore/                    # 共享核心层（单一事实源）
│   │   ├── metrics.py              # 指标定义 35 项 + 归一化解析器（唯一权威）
│   │   ├── topology.py             # 拓扑注册表（SSSR 8组37项，DRSS/SDSR预留）
│   │   ├── adapters/               # 工具适配器（MotorCAD真实 + Maxwell/JMAG mock）
│   │   ├── strategies/             # 执行策略（full_factorial/lhs/adaptive/morris/surrogate_guided）
│   │   └── l0/                     # L0 解析预筛选（纯stdlib）
│   ├── solver_core.py              # 仿真核心（Motor-CAD连接/参数/求解/结果提取）
│   ├── scan_engine.py              # 参数扫描引擎
│   ├── plan_schema.py              # 方案JSON Schema（parse/validate单一权威）
│   ├── experience_db.py            # 经验库（SQLite）
│   ├── api_client.py               # Web端API客户端（系统二↔系统一通信）
│   ├── status_constants.py         # 状态常量（"OK"/"FAILED"统一）
│   └── gui/                        # PySide6 GUI
├── scripts/                        # 33个脚本
│   ├── run_task_executor.py        # 本地执行器主入口（读executor_config.json）
│   ├── run_task_executor_parallel.py   # 多实例并行
│   ├── run_single.py / run_scan.py / run_gui.py    # 调试入口
│   ├── check_machine_paths.py      # 环境体检（只读，--fix打印修复命令）
│   ├── build_executable.ps1        # EXE打包（PyInstaller）
│   └── test_*.py                   # 回归测试（23个，python scripts/test_*.py独立运行）
├── web/                            # 系统一（Web端）
│   ├── backend/app/
│   │   ├── main.py / config.py / database.py
│   │   ├── models/ / schemas/      # ORM模型 / Pydantic Schema
│   │   ├── routers/                # 14个路由（projects/plans/tasks/adaptive/ai/ai_plan/
│   │   │                           #   search/analysis/analytics/executor_monitor/
│   │   │                           #   experience/generation/monitor/reports）
│   │   └── services/               # 规则引擎/AI方案生成/自适应闭环/批量调度/
│   │                               #   报告生成/拓扑变量映射/固定参数模板等
│   └── frontend/src/               # Vue3 + Element Plus + ECharts
│       └── views/                  # 9个主视图 + ai/子目录（AI功能页）
├── models/                         # 基线模型（只读：MARS-12S10P_SSSR .mot 及配套网格/导出文件）
├── testcase/                       # 测试模型
├── dist/                           # 打包产物 PCB-AFM-Executor.exe（不入库）
├── output/                         # 仿真输出（不入库）
├── experience/                     # 经验库数据（SQLite）
├── 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（版本号/状态/路线图）+ CHANGELOG.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
11. 状态信息单一事实源：当前进度/阻塞/待办只维护 docs/HANDOFF.md 第 3 节，README 只放链接
12. 粘贴文本入文档后检查控制字符（0x07/0x08 等会吞字，历史已发生两次）

---

阶段路线图

阶段编号说明：P4 期间实施的「平台化改造四/五批」与 P4-M1~M5 合并交付（Schema 统一、EXE 打包均已在 P4 完成）；P5 为平台化增强 M1~M6；P6 为前端体验优化。逐里程碑明细见 docs/P1-P5交付总结与上手指南.md。

阶段	目标	状态
Phase 1（M1~M4）	最小闭环：环境验证 + 扫描引擎 + 方案JSON/GUI + 经验库雏形	✅ 完成
Phase 2（P2-M1~M5）	Web端方案系统（FastAPI + Vue3 + SQLite + 规则引擎）	✅ 完成
Phase 3	AI驱动智能仿真闭环（Kimi + 可行性优先搜索 + 自适应）	✅ 完成
Phase 4	Web AI集成 + 双系统闭环 + 批量调度 + Schema 统一 + EXE 打包 + 部署	✅ 完成
P5 平台化增强	M1 前端build清零 / M2 EXE配置化 / M3 adaptive三视图 / M4 Morris+IDW策略 / M5 多工具适配器 / M6 多物理场L2接入	✅ 全部完成
P6 前端体验优化	M1 UI/UX全面重构（设计令牌+信息架构+PlanDetail分层）	✅ 完成
P6-M2	B3 参数目录单一事实源（前后端协同）	🔳 待办
P6-M3	B4 流程引导 + 仿真前检查清单 + 耗时校准	🔳 待办
路线扩展	热求解真实验证 + Maxwell/JMAG 真实接入 + Kriging 升级 + DRSS/SDSR 拓扑	🔳 规划中