# 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](docs/HANDOFF.md) 第 3 节 |
| 更新日志 | [CHANGELOG.md](CHANGELOG.md)（全部历史更新，本文件只保留摘要） |
| 设计方案 | [PC轴向磁通电机自动化仿真系统设计方案介绍.md](PCB轴向磁通电机自动化仿真系统设计方案介绍.md)（V2.0，已同步实现现状） |
| 论文知识库 | [docs/PAPER_KNOWLEDGE_BASE.md](docs/PAPER_KNOWLEDGE_BASE.md)（无铁心PCB-AFPM 38篇论文精读整理，供软件工程师参考） |
| 上手指南 | [docs/P1-P5交付总结与上手指南.md](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](CHANGELOG.md)；里程碑明细见 [docs/P1-P5交付总结与上手指南.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](docs/CODE_REVIEW_RESPONSE.md)。

逐里程碑计划 vs 实际交付对照表：[docs/P1-P5交付总结与上手指南.md](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` 打印修复命令）。

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

```bash
# 安装依赖
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端方案生成）

```bash
# 后端
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/](axial_mag_pull-master/) | 单一目标微缩闭环验证、三判据校验、AFM轴向力数据口 |
| torqrippswap | [torqrippswap-master/](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](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 拓扑 | 🔳 规划中 |