# PCB 轴向磁通电机自动化仿真系统 — P1-P5 交付总结与上手指南

> **文档版本**：V1.0（2026-08-30，P5 完成时点）
> **适用读者**：新加入项目的开发者、需要快速定位模块的维护者、接手后续 Phase 的工程师
> **前置阅读**：`AGENTS.md`（工程纪律）→ `docs/KNOWLEDGE_BASE.md`（环境事实与踩坑记录）→ 本文档

---

## 1. 项目概览

### 1.1 一句话定位

双系统解耦的 PCB 轴向磁通电机（AFPM）自动化仿真平台：
- **系统一（Web 端）**：FastAPI + Vue3，负责方案生成、AI 优化、经验库、可视化、报告
- **系统二（本地 EXE）**：PyInstaller 打包的本地执行器，驱动 Motor-CAD 真实仿真
- **共享核心层** `src/afmcore/`：metrics / topology / adapters / strategies / l0 / plan_schema，单一事实源，双系统共用

### 1.2 当前状态（2026-08-30）

| 维度 | 状态 |
|---|---|
| Phase 1（最小闭环） | ✅ 全部完成 |
| Phase 2（Web 端方案系统） | ✅ 全部完成 |
| Phase 3（AI 驱动智能仿真闭环） | ✅ 全部完成 |
| Phase 4（Web AI 集成 + 双系统闭环 + 批量调度 + 部署） | ✅ 全部完成 |
| Phase 5（平台化增强，M1-M6） | ✅ 全部完成 |
| Git HEAD | `af2275f` |
| 测试脚本 | 23 个 `scripts/test_*.py`，全量回归 22/22 PASS（test_api_client 需真实链路） |
| 指标定义 | 35 项（电磁 25 + 热 6 + 结构 4） |
| 仿真策略 | 5 种（full_factorial / lhs / adaptive / morris / surrogate_guided） |
| 工具适配器 | 3 种（motorcad 真实 / maxwell mock / jmag mock） |
| 前端构建 | vue-tsc 0 错误（P5-M1 清零） |
| EXE 打包 | `dist/PCB-AFM-Executor.exe`（P4-M3，PyInstaller onefile） |

---

## 2. P1-P5 里程碑全盘核对表

### 2.1 Phase 1 — 最小闭环

| 里程碑 | 计划内容 | 实际交付 | 状态 | Commit |
|---|---|---|---|---|
| P1-M1 | 环境验证 + 单工况仿真脚本 | Motor-CAD 前台可见、参数回读校验、连接/计算/导出/解析跑通 | ✅ | `75347b6` |
| P1-M2 | 参数扫描引擎 | 每点基线重载、逐点落盘、中英文字段别名；气隙扫描 3 点物理趋势符合预期 | ✅ | `a43d971` |
| P1-M3 | 方案 JSON 接口 + 本地 PySide6 GUI | 方案 Schema、GUI 加载/监控、方案回写 | ✅ | `cbd9402` |
| P1-M4 | 经验库雏形 + 反馈闭环 | SQLite 经验库、相似检索、反馈闭环 | ✅ | `f20bef9` |

**验证记录**：TEST-001（连接探测，发现 export_results API 兼容问题）→ TEST-002（修复后全流程，磁场计算 138.1s/点）→ TEST-003（指标解析 7→14 项）。

### 2.2 Phase 2 — Web 端方案系统

| 里程碑 | 计划内容 | 实际交付 | 状态 | Commit |
|---|---|---|---|---|
| P2-M1 | Web 基础框架 | FastAPI + Vue3 + SQLite + CRUD API + 双系统 API 客户端 | ✅ | `1ea7653` |
| P2-M2 | 边界条件输入 + 方案编辑器 | 规则引擎（参数注册表/范围推荐/方案生成） | ✅ | `a95c0db` |
| P2-M3 | 经验库 Web 端 + 分析仪表盘 | ECharts 趋势/Pareto/敏感性 | ✅ | `9885437` |
| P2-M4 | 双系统 API 联调 + 知识库管理 | 经验库 CRUD/导入、系统二客户端增强 | ✅ | `25ee19f` |
| P2-M5 | Phase 2 验收 | 自动化测试 + 前端人工验收 + 文档 | ✅ | `0df69f2` |
| P2-补丁 | 前端全面中文化 + Dashboard 修复 | — | ✅ | `2660df7` |

### 2.3 Phase 3 — AI 驱动智能仿真闭环

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

| 里程碑 | 计划内容 | 实际交付 | 状态 |
|---|---|---|---|
| P3-M1 | AI 服务层基础架构 | Kimi 客户端 + JSON Schema V2 + 多保真度框架（L0→L4） | ✅ |
| P3-M2 | L0 解析预筛选 + 可行性优先搜索 | 14+ 约束检查 + LHS 初始采样 + 主动学习批量选点 + 局部信任域精修 | ✅ |
| P3-M3 | AI 方案生成器 | 自然语言 → 结构化仿真方案 | ✅ |
| P3-M4 | AI 结果分析师 + 多保真度校准 | 置信等级 A~D + 六类收敛判据 | ✅ |
| P3-M5 | 经验库 AI 增强 + 批量自适应闭环 | 经验提取 + 闭环验收 | ✅ |
| P3-M6 | Web 端执行桥 + 路由整合 | AdaptiveLoop 补齐 submit_batch_to_executor() | ✅ `768a883` |

**P3 平台化（afmcore 第一批~第三批）**：
- 第一批：`metrics.py`（25 项指标+归一化解析器）+ `adapters/`（ABC + 注册表 + MotorCADAdapter）→ TEST-004
- 第二批：`topology.py`（SSSR 8 组 37 项参数）+ task_executor 切换 get_adapter → TEST-005
- 第三批：`strategies/`（full_factorial/lhs/adaptive）+ Task 模型扩展 + 调度契约统一 → TEST-006~011

**P3 遗留处理（P4 期初）**：并发原子认领（`fb3a505`）、断点恢复（`4dcc627`）、ASCII 纪律（`3caecd1`）、环境依赖测试（TEST-013）。

### 2.4 Phase 4 — Web AI 集成 + 双系统闭环 + 批量调度 + 部署

| 里程碑 | 计划内容 | 实际交付 | 状态 |
|---|---|---|---|
| P4-M1 | 前端 AI 功能集成 | 6 个 AI 页面 + API 封装 + 通用组件 | ✅ |
| P4-M2 | 双系统任务下发与回传 | Web 创建任务 → 执行器轮询领取 → 执行 → 上报 → 回传 → 存储展示 | ✅ |
| P4-M3 | 批量调度 + 实时监控 + 增强版 MotorCAD 核心 | 优先级队列(1-10) + 最大并行(2) + 依赖 + 断点续跑；16 项鲁棒性措施 | ✅ |
| P4-M4 | 高级可视化 + 自动报告 | Pareto/收敛/雷达/热力图 + Word/JSON 报告 | ✅ |
| P4-M5 | 部署打包 | Docker + docker-compose + nginx + Windows 部署脚本 | ✅ |

**P4 平台化批次（p4-m1..m5）**：

| 批次 | 内容 | 验证 | Commit |
|---|---|---|---|
| P4-M1 | 方案 Schema 单一权威（src/plan_schema.py） | test_p4_schema.py 7 组全过 | `223888a` |
| P4-M2 | 设计文档 V1.1→V2.0（附录 B 实现现状对照） | README 引用同步 | `9d09b3c` |
| P4-M3 | EXE 打包（PyInstaller onefile，12.6MB） | dist/PCB-AFM-Executor.exe 冒烟通过 | `5dd3559` |
| P4-M4 | 前端 adaptive 收敛曲线（points_history + echarts） | test_p4_m4_convergence.py 5 组；vue-tsc 0 错误 | `10a34a0` |
| P4-M5 | L0 上提共享核心（src/afmcore/l0/prescreening.py） | test_p4_m5_l0.py 8 组 | `18ea49e` |

**真实 Motor-CAD 实测**（MARS-12S10P，5000rpm）：效率 86.06%、总损耗 41.945W、磁场计算 138.1s/点（TEST-002/003/010）。

**第三方代码评审修复**（V1.4）：20+ P0 项，详见 `docs/CODE_REVIEW_RESPONSE.md`。

### 2.5 Phase 5 — 平台化增强（M1-M6，本轮全部完成）

| 里程碑 | Backlog | 计划内容 | 实际交付 | 状态 | Commit |
|---|---|---|---|---|---|
| P5-M1 | B1 | 前端全量 build 类型错误清零 | vue-tsc 0 错误，修复 12 处类型问题 | ✅ | `b394c39` |
| P5-M2 | B2 | 真实 EXE E2E 修复 | executor_config.json 可配置 + airgap_mm→Airgap 映射 + 排除 point_id 元数据 | ✅ | `3638699` + `974750e` |
| P5-M3 | B3 | Adaptive 三视图可视化 | batch status + L0 summary + auto-polling | ✅ | `b137690` |
| P5-M4 | B4 | 策略层高级管线 | Morris 灵敏度筛选 + IDW 代理 + UCB + 预算自适应批次 | ✅ | `94647f1` |
| P5-M5 | B6 | 多工具适配器 | MaxwellAdapter/JMAGAdapter mock + 执行器 tool 动态 import | ✅ | `05df4be` |
| P5-M6 | B5 | 多物理场 L2 接入 | metrics 扩 10 项（热6+结构4）+ robust 热求解开关 + 报告按域分组 | ✅ | `af2275f` |

**Backlog 覆盖核对**：B1✅ B2✅ B3✅ B4✅ B5✅ B6✅ — 全部 6 项 backlog 清零。

---

## 3. 目录结构速查

```
PCB轴向磁通电机自动化仿真系统/
├── AGENTS.md                          # 工程纪律（必读）
├── README.md                          # 项目说明（V2.0）
├── executor_config.json               # 本地执行器配置（tool/model_path/output_dir）
├── deploy.ps1                         # Windows 部署脚本
├── PCB轴向磁通电机自动化仿真系统设计方案介绍.md  # 完整设计方案 V2.0（含附录 B 实现对照）
│
├── docs/
│   ├── KNOWLEDGE_BASE.md              # 核心知识库（环境事实、参数语义、踩坑记录）
│   ├── HANDOFF.md                     # 接续指南（进度/阻塞/待办，新会话必读）
│   ├── TEST_RECORDS.md                # 测试记录（TEST-001~024）
│   ├── CONVERSATION_LOG.md            # 会话与决策记录
│   ├── PLATFORM_DESIGN_V2.md          # 平台设计 V2
│   ├── CODE_REVIEW_RESPONSE.md        # 第三方代码评审修复记录
│   ├── P1-P5交付总结与上手指南.md      # 本文档
│   └── archive/                       # 已完结历史计划文档（P3/P4实施计划等）
│
├── src/
│   ├── afmcore/                       # 共享核心层（单一事实源，双系统共用）
│   │   ├── metrics.py                 # 35 项指标定义 + 归一化解析器
│   │   ├── topology.py                # 拓扑注册表（SSSR 8 组 37 项参数）
│   │   ├── adapters/                  # 仿真工具适配器
│   │   │   ├── __init__.py            # SimulationAdapter ABC + 注册表
│   │   │   ├── motorcad.py            # Motor-CAD 适配器（真实，wrap RobustMotorCADSolver）
│   │   │   ├── maxwell.py             # Maxwell 适配器（mock，真实接入待环境）
│   │   │   └── jmag.py                # JMAG 适配器（mock，真实接入待环境）
│   │   ├── strategies/                # 仿真策略
│   │   │   ├── __init__.py            # 策略注册表 + get_strategy
│   │   │   ├── full_factorial.py      # 全因子
│   │   │   ├── lhs.py                 # 拉丁超立方
│   │   │   ├── adaptive.py            # 自适应（可行性优先 + 主动学习）
│   │   │   ├── morris.py              # Morris 灵敏度筛选
│   │   │   └── surrogate_guided.py    # IDW 代理 + UCB + 预算自适应
│   │   └── l0/
│   │       ├── __init__.py
│   │       └── prescreening.py        # L0 解析预筛选（14+ 约束，纯 stdlib）
│   ├── api_client.py                  # Web API 客户端（系统二调用系统一）
│   ├── experience_db.py               # 经验库（SQLite）
│   ├── plan_schema.py                 # 方案 Schema（parse/validate 单一权威入口）
│   ├── scan_engine.py                 # 扫描引擎（legacy）
│   └── solver_core.py                 # 求解核心（legacy）
│
├── scripts/
│   ├── robust_motorcad.py             # 鲁棒 Motor-CAD 求解器（16 项鲁棒性措施）
│   ├── task_executor.py               # 任务执行器（adapter 驱动，多实例，point_id 回填）
│   ├── executor_config.py             # 执行器配置加载
│   ├── run_gui.py                     # 启动本地 PySide6 GUI
│   ├── run_scan.py                    # 运行参数扫描
│   ├── run_single.py                  # 运行单工况
│   ├── run_task_executor.py           # 启动单实例任务执行器
│   ├── run_task_executor_parallel.py  # 启动多实例并行执行器
│   ├── build_executable.ps1           # PyInstaller EXE 打包脚本
│   ├── scan_airgap.json               # 气隙扫描示例方案
│   └── test_*.py                      # 23 个单元/集成测试脚本
│
├── web/
│   ├── backend/                        # FastAPI 后端
│   │   └── app/
│   │       ├── main.py                # FastAPI 入口
│   │       ├── routers/               # API 路由（plans/tasks/loops/experience/reports 等）
│   │       ├── services/              # 业务服务（task_contract/report_generator/adaptive 等）
│   │       └── models.py              # SQLAlchemy 模型
│   ├── frontend/                       # Vue3 前端
│   │   └── src/
│   │       ├── views/                 # 页面（6 个 AI 页面 + 方案/任务/监控/经验库）
│   │       ├── components/            # 通用组件
│   │       └── api/                   # API 封装
│   └── output/                         # Web 端输出（报告等）
│
├── models/                             # Motor-CAD 基线模型（.mot，只读）
├── output/                             # 运行输出（不入库）
└── dist/                               # EXE 打包输出（不入库）
```

---

## 4. 核心层 afmcore 模块详解

### 4.1 metrics.py — 指标单一事实源

**职责**：定义全平台所有仿真输出指标，提供归一化解析器。

**关键设计**：
- `METRIC_DEFINITIONS`：35 项指标，每项含 `key/label/unit/direction/required/aliases/domain`
- `aliases`：英文 + 中文（`\uXXXX`），覆盖 Motor-CAD 导出的各种字段名变体
- `normalize_name()`：全角→半角、去所有空白（含全角空格 U+3000）、小写 — 修复历史 tavg/ripple 解析 bug
- `parse_export()`：分号分隔 CSV 解析器，多编码 fallback（utf-8-sig/utf-8/gbk/cp1252/latin-1）
- `pick_metric()`：E-Magnetics 段优先精确匹配 → 全段精确 → 前缀模糊（带 % 防护）
- `extract_all_metrics()`：遍历 METRIC_DEFINITIONS，**新增指标自动生效，无需改调用方**

**扩项方式**：在 `METRIC_DEFINITIONS` 列表中加一项（含 aliases），所有消费端（robust_motorcad / report_generator / Web 后端）自动生效。

### 4.2 adapters/ — 仿真工具适配器

**职责**：统一不同 FEA 工具（Motor-CAD / Maxwell / JMAG）的接口，执行器只依赖 `SimulationAdapter` ABC。

**接口契约**（`SimulationAdapter` 抽象基类）：
- `connect()` / `disconnect()`：生命周期
- `load_model(model_path)`：加载基线模型（只读）
- `set_parameter(name, value)`：写参数 + 回读校验（不一致抛 RuntimeError）
- `run_simulation(mode)`：运行求解
- `extract_metrics(output_dir, tag)`：导出原始结果 + 解析指标
- `run_point(...)`：高层便捷方法（默认编排 connect→load→set→run→extract→disconnect）

**注册表**：`register_adapter(tool_name, cls)` / `get_adapter(tool_name, **kwargs)` / `registered_tools()`

**现有适配器**：
| tool | 实现 | 状态 | capability_domains |
|---|---|---|---|
| motorcad | MotorCADAdapter，wrap RobustMotorCADSolver | ✅ 真实可用 | electromagnetic |
| maxwell | MaxwellAdapter，内存参数+确定性合成指标 | ⚠️ mock（真实接入需 Ansys Maxwell + PyAEDT） | electromagnetic, thermal |
| jmag | JMAGAdapter，同上 | ⚠️ mock（真实接入需 JMAG Designer + jmagpy） | electromagnetic |

**执行器集成**：`MotorCADTaskExecutor._ensure_adapter()` 根据 `self.tool` 动态 import 对应适配器模块并注册。

### 4.3 strategies/ — 仿真策略

**职责**：参数空间探索策略，统一 `SimulationStrategy` 接口（select_next / report / next_batch_ready / is_converged / state）。

**现有策略**：
| kind | 类 | 适用场景 | state() 关键输出 |
|---|---|---|---|
| full_factorial | FullFactorialStrategy | 小空间全遍历 | progress |
| lhs | LHSStrategy | 大空间初始采样 | progress |
| adaptive | AdaptiveStrategy | 可行性优先 + 主动学习 + 信任域精修 | best_point / convergence |
| morris | MorrisStrategy | 灵敏度筛选（OAT 初等效应） | sensitivity_ranking / key_parameters |
| surrogate_guided | SurrogateGuidedStrategy | IDW 代理 + UCB + 预算自适应 | phase / surrogate 诊断 |

**注册表**：`get_strategy(kind, **kwargs)` / `registered_strategies()`

### 4.4 l0/prescreening.py — L0 解析预筛选

**职责**：14+ 约束检查（几何/电气/热/制造），在昂贵 FEA 之前快速排除不可行方案。

**关键特性**：纯 stdlib 实现（无 numpy/scipy），可在 EXE 中无依赖运行。

### 4.5 topology.py — 拓扑注册表

**职责**：SSSR（单定子单转子）8 组 37 项参数体系，DRSS/SDSR 预留。参数语义、范围、默认值的单一事实源。

### 4.6 plan_schema.py — 方案契约 V2

**职责**：仿真方案的 JSON Schema 定义 + parse/validate 入口。Web 端和本地执行器共用，确保方案格式一致。

---

## 5. 快速开始

### 5.1 环境准备

**必需**：
- Python 3.10+（推荐 3.11）
- Windows 10/11（Motor-CAD 仅 Windows）
- Git

**Motor-CAD 仿真（可选，跑真实求解需要）**：
- Ansys Motor-CAD v261（安装路径 `D:\Program Files\ANSYS Inc\v261\motorcad\MotorCAD.exe`）
- 环境变量：`MOTORCAD_ACTIVEX`、`ANSYSLMD_LICENSE_FILE`（非登录 shell 可能不继承，脚本内有回退）
- pymotorcad（`pip install ansys-motorcad-core`）

**Web 端（可选）**：
- Node.js 18+（前端构建）
- FastAPI + uvicorn（后端，`pip install -r web/backend/requirements.txt`）

**安装依赖**：
```powershell
cd C:\Users\admin\Desktop\PCB轴向磁通电机自动化仿真系统
pip install -r requirements.txt  # 如果存在
# 核心依赖：ansys-motorcad-core, pyside6（GUI）, fastapi, uvicorn, sqlalchemy, python-docx
```

### 5.2 跑测试（验证环境）

```powershell
# 全量回归（排除需要真实链路的 test_api_client.py）
Get-ChildItem scripts\test_*.py | ForEach-Object {
    if ($_.Name -ne "test_api_client.py") {
        python $_.FullName
    }
}
# 预期：22/22 PASS
```

**单个测试**：
```powershell
python scripts\test_metrics_extension.py   # 指标扩展
python scripts\test_adapters.py             # 适配器
python scripts\test_strategy_morris.py      # Morris 策略
```

### 5.3 启动本地 GUI（系统二，方案编辑 + 监控）

```powershell
python scripts\run_gui.py
```

GUI 功能：加载方案 JSON、编辑参数、启动扫描、实时监控进度、查看结果。

### 5.4 启动任务执行器（系统二，从 Web 端领取任务）

```powershell
# 单实例
python scripts\run_task_executor.py

# 多实例并行（2 个）
python scripts\run_task_executor_parallel.py --instances 2
```

执行器通过 Web API 轮询领取任务，调用适配器（默认 motorcad）执行仿真，结果上报回 Web 端。

**配置**：编辑 `executor_config.json`：
```json
{
  "web_base_url": "http://127.0.0.1:8000",
  "model_path": "models/base.mot",
  "tool": "motorcad",
  "output_dir": "output",
  "enable_mock": false,
  "poll_interval_seconds": 5
}
```

`tool` 可选：`motorcad`（真实）/ `maxwell`（mock）/ `jmag`（mock）。

### 5.5 启动 EXE（打包后的执行器）

```powershell
dist\PCB-AFM-Executor.exe --config executor_config.json
dist\PCB-AFM-Executor.exe --version
dist\PCB-AFM-Executor.exe --self-test
```

### 5.6 启动 Web 端（系统一）

```powershell
# 后端
cd web\backend
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 前端（另开终端）
cd web\frontend
npm install
npm run dev  # 开发模式，http://localhost:5173
npm run build  # 生产构建（vue-tsc 类型检查，P5-M1 后 0 错误）
```

### 5.7 运行单工况仿真（命令行）

```powershell
python scripts\run_single.py --model models\base.mot --params airgap_mm=1.0,magnet_thickness_mm=5.0
```

### 5.8 运行参数扫描（命令行）

```powershell
python scripts\run_scan.py --config scripts\scan_airgap.json
```

---

## 6. 关键工程约束（硬性纪律，违者返工）

> 完整规则见 `AGENTS.md`，以下为最常踩的 7 条。

### 6.1 源码纯 ASCII
所有 `.py` 和 `.ps1` 文件**只含 ASCII 字符**。中文说明写 Markdown，中文字段名用 `\uXXXX` 转义。
```powershell
# 检查命令
rg -n "[^\x00-\x7F]" --glob '*.py' --glob '*.ps1' .
```

### 6.2 运行前 Git 必须干净
实际启动 Motor-CAD 求解前必须满足：Git 仓库存在且 HEAD 有效、所有已跟踪文件无未提交修改。GUI 内置 Git preflight，不满足时拒绝启动扫描。

### 6.3 Motor-CAD 实例管理
- 使用 `open_new_instance=True` 创建独立实例（**不要**连接已有实例）
- 启动后必须 `set_visible(True)`（/SCRIPTING 模式默认隐藏）
- 每个扫描点开始前 `load_from_file(基线模型)`，结束后也重载基线

### 6.4 参数必须回读校验
不能只调用 `set_variable`。必须：
```python
mc.set_variable(variable, value)
applied = float(mc.get_variable(variable))
if not math.isclose(applied, value, rel_tol=1e-8, abs_tol=1e-7):
    raise RuntimeError(...)
```
回读不一致时将该点标记为 FAILED，保存错误并继续下一点。

### 6.5 结果逐点落盘
每个点完成后立即写 CSV 并 flush，**不能**等整批完成后一次性保存。失败点记录错误并继续。运行目录结构：`output/<timestamp>_<scan_name>/` 含 manifest.json + scan_results.csv + program_log.log + raw/。

### 6.6 原始模型只读
原始 `.mot` 文件不修改。所有操作在 Motor-CAD 内存中进行，或另存时间戳副本。`models/` 目录下的模型文件视为只读。

### 6.7 生成物不入库
`output/`、`runs/`、`build/`、`dist/`、`*.log`、`*.spec`、`__pycache__/` 不入库。关键数值转录进入库的文档（TEST_RECORDS.md / RESULTS.md / 报告）。

---

## 7. 测试体系

### 7.1 测试脚本清单（23 个）

| 测试文件 | 覆盖范围 | 类型 |
|---|---|---|
| test_robust_solver.py | RobustMotorCADSolver 核心（回读校验/基线重载/逐点落盘） | 单元 |
| test_platform_registry.py | afmcore 注册表（adapters/strategies） | 单元 |
| test_p3_unit_edge.py | P3 边界/异常场景 | 单元 |
| test_p3_m4_contract.py | P3-M4 任务契约 | 单元 |
| test_p3_orchestrator.py | P3 编排器 | 单元 |
| test_p3_adaptive_execution.py | P3 自适应执行 | 集成 |
| test_p3_closed_loop.py | P3 闭环（mock） | 集成 |
| test_p3_checkpoint.py | 断点恢复 | 单元 |
| test_p3_concurrency.py | 并发原子认领 | 集成 |
| test_p4_schema.py | 方案 Schema 校验 | 单元 |
| test_p4_acceptance.py | P4 验收 | 集成 |
| test_p4_m4_convergence.py | P4-M4 收敛曲线 | 单元 |
| test_p4_m5_l0.py | P4-M5 L0 上提 | 单元 |
| test_executor_config.py | 执行器配置 | 单元 |
| test_executor_m3.py | 执行器 M3 功能 | 单元 |
| test_executor_p5m2.py | P5-M2 EXE E2E 修复 | 单元 |
| test_search_state_summary.py | 搜索状态摘要 | 单元 |
| test_strategy_morris.py | Morris 策略（P5-M4） | 单元 |
| test_strategy_surrogate.py | SurrogateGuided 策略（P5-M4） | 单元 |
| test_adapters.py | 多工具适配器（P5-M5） | 单元 |
| test_metrics_extension.py | 指标扩展 + 报告域分组（P5-M6） | 单元 |
| test_api_client.py | Web API 真实链路（需启动后端） | 集成 |

### 7.2 运行方式

```powershell
# 全量（排除 test_api_client，需真实后端）
Get-ChildItem scripts\test_*.py | Where-Object { $_.Name -ne "test_api_client.py" } |
    ForEach-Object { python $_.FullName }

# 单个
python scripts\test_<name>.py
# exit 0 = PASS，非 0 = FAIL
```

### 7.3 测试记录

所有真实 Motor-CAD 仿真、API 测试、集成测试记录在 `docs/TEST_RECORDS.md`（TEST-001~022），含测试日期、环境、目的、步骤、结果、关键数据、发现的问题、修复措施。

---

## 8. 已知限制与后续方向

### 8.1 当前限制（如实标注）

| 限制 | 说明 | 升级路径 |
|---|---|---|
| Maxwell/JMAG 为 mock | 当前环境无 Ansys Maxwell / JMAG 安装，适配器为 mock 实现（确定性合成指标） | 目标机安装对应软件 + Python API（PyAEDT / jmagpy），在同接口下替换为真实实现 |
| Kriging 代理未实现 | 环境无 numpy/scipy，P5-M4 用 IDW（反距离加权）替代 Kriging | 引入 scipy 后替换为 Kriging，策略接口不变 |
| 真实热求解未运行 | P5-M6 增加了 enable_thermal 开关和代码路径，但需要模型配置热网络 + 实际启动 Motor-CAD 验证 | 配置热网络后运行 enable_thermal=True 的扫描，验证热指标提取 |
| 结构指标需外部 FEA | axial_force / stress / deformation 等结构指标需要 Motor-CAD 结构模块或第三方 FEA（如 Ansys Mechanical） | 接入结构求解器，或从 Maxwell 3D 结果中提取力后做后处理 |
| NSGA-II 多目标优化未实现 | P5 规划中提及，未在 M1-M6 范围内 | 后续 Phase 实现多目标优化策略 |
| 前端工具选择下拉框 | executor_config.json 已支持 tool 字段，但 Web 端任务创建页尚未加工具选择 UI | 前端加 tool 下拉框，传入 task 创建 API |
| 原有 winding_temp_c 无 domain | 该指标默认归入 electromagnetic 域 | 可加 domain=thermal 字段，归入热域 |

### 8.2 后续方向建议

1. **Phase 6 — 真实多工具接入**：在目标机安装 Maxwell/JMAG，将 mock 适配器替换为真实实现
2. **多物理场真实耦合**：电磁→热→结构的单向/双向耦合，L2 多保真度层落地
3. **多目标优化**：NSGA-II / MOEA-D，支持转矩密度×效率×成本的 Pareto 前沿
4. **Kriging 代理升级**：引入 scipy，替换 IDW，提升代理精度
5. **经验库自动积累**：仿真结果自动提取关键参数→指标映射，增量更新经验库
6. **Web 端工具选择 UI**：任务创建页加 tool 下拉框
7. **热求解真实验证**：配置热网络后运行 enable_thermal 扫描

---

## 9. 提交历史速查（P1-P5 关键 commit）

| Commit | 内容 | Phase |
|---|---|---|
| `75347b6` | P1-M1 环境验证 + 单工况仿真 | P1 |
| `a43d971` | P1-M2 参数扫描引擎 | P1 |
| `cbd9402` | P1-M3 方案 JSON + PySide6 GUI | P1 |
| `f20bef9` | P1-M4 经验库雏形 | P1 |
| `1ea7653` | P2-M1 Web 基础框架 | P2 |
| `2cae9b6` | afmcore 共享核心层 + metrics 单一事实源 + adapter 抽象 | P3 |
| `27ccde6` | 拓扑注册表 + adapter 驱动执行器 | P3 |
| `2e9adfa` | 执行策略抽象层 | P3 |
| `fa74834` | Adaptive 编排器 | P3 |
| `768a883` | Web AdaptiveLoop → 本地执行器桥 | P3-M6 |
| `fb3a505` | 并发原子认领（dispatch_task 条件 UPDATE） | P3 遗留 |
| `4dcc627` | 断点恢复（search/loop export-import） | P3 遗留 |
| `223888a` | P4-M1 方案 Schema 单一权威 | P4 |
| `5dd3559` | P4-M3 EXE 打包（PyInstaller） | P4 |
| `10a34a0` | P4-M4 前端 adaptive 收敛曲线 | P4 |
| `18ea49e` | P4-M5 L0 上提共享核心 | P4 |
| `e6563fc` | P1-P4 回顾 + P5 规划（交接文档） | P5 起点 |
| `b394c39` | P5-M1 前端类型错误清零（vue-tsc 0 错误） | P5 |
| `3638699` | P5-M2 EXE 可配置（executor_config.json） | P5 |
| `974750e` | P5-M2 真实 EXE E2E 修复（airgap_mm→Airgap + 排除 point_id） | P5 |
| `b137690` | P5-M3 Adaptive 三视图可视化 | P5 |
| `94647f1` | P5-M4 Morris + IDW 代理 + 预算自适应 | P5 |
| `05df4be` | P5-M5 Maxwell/JMAG mock 适配器 + tool 动态 import | P5 |
| `af2275f` | P5-M6 多物理场 L2（热/结构指标 + 热求解开关 + 报告域分组） | P5 收官 |

---

## 10. 新人上手 Checklist

按顺序完成以下步骤，即可独立维护和开发：

- [ ] **读 AGENTS.md**：理解工程纪律（ASCII / Git preflight / 回读校验 / 逐点落盘）
- [ ] **读 docs/KNOWLEDGE_BASE.md**：理解环境事实、参数语义、已踩的坑
- [ ] **读本文档 §3-§4**：理解目录结构和 afmcore 核心层
- [ ] **跑通测试**：`python scripts\test_robust_solver.py` → 全量回归 22/22
- [ ] **跑通 mock 执行器**：`executor_config.json` 设 `enable_mock=true`，启动执行器，从 Web 端创建 mock 任务
- [ ] **理解 metrics 扩项**：在 `METRIC_DEFINITIONS` 加一项，验证 `extract_all_metrics` 自动生效
- [ ] **理解适配器模式**：读 `adapters/__init__.py` + `motorcad.py`，尝试用 `get_adapter("maxwell")` 跑 mock 链路
- [ ] **理解策略模式**：读 `strategies/__init__.py`，用 `get_strategy("morris")` 跑灵敏度筛选
- [ ] **读设计方案附录 B**：`PCB轴向磁通电机自动化仿真系统设计方案介绍.md` 附录 B，理解蓝图 vs 实现的对照
- [ ] **（可选）跑真实 Motor-CAD**：确认环境变量 + license，用 `run_single.py` 跑单工况，对照 TEST-002 结果

---

> **文档维护**：每次 Phase / Milestone 完成后，更新 `README.md` + `docs/TEST_RECORDS.md`，并在本文档对应章节追加里程碑记录。本文档最后更新：2026-08-30（P5 完成时点，HEAD `af2275f`）。