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

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

| 项目 | 内容 |
|---|---|
| 文档版本 | V1.4（代码评审修复） |
| 作者 | Car.Lin |
| 启动日期 | 2026-08-27 |
| 当前状态 | Phase 1/2/3/4 全部完成，第三方代码评审 P0 问题已修复 |
| 设计方案 | [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/搜索/方案生成/结果分析/自适应闭环全流程

### 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](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 |

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

```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 | 多物理场（热/结构）+ 多工具扩展 | 🔲 规划中 |