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

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

| 项目 | 内容 |
|---|---|
| 文档版本 | V1.2（Phase 3 验收完成） |
| 作者 | Car.Lin |
| 启动日期 | 2026-08-27 |
| 当前状态 | Phase 1/2/3 全部完成，AI驱动自适应仿真闭环就绪 |
| 设计方案 | [PCB轴向磁通电机自动化仿真系统设计方案介绍.md](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/搜索/方案生成/结果分析/自适应闭环全流程

---

## 快速开始

### 环境要求

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

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

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

```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 到后端
```

### 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/](axial_mag_pull-master/) | 单一目标微缩闭环验证、三判据校验、AFM轴向力数据口 |
| torqrippswap | [torqrippswap-master/](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 | 多物理场（热/结构）+ 多工具扩展 | 🔲 规划中 |
