# PCB轴向磁通电机自动化仿真系统 — 平台化升级设计方案 V2.0

| 项 | 内容 |
|---|---|
| 文档版本 | V2.0 |
| 作者 | Car.Lin / AI 协助 |
| 日期 | 2026-08-29 |
| 状态 | 评审稿 + 第一批已落地（2026-08-29：afmcore 共享核心层 + 指标单一事实源 + 适配器抽象） |
| 关联 | 原《设计方案介绍》V1.1 + 《P3-评审响应与更新计划》 |

---

## 1. 为什么要平台化

### 1.1 现状能力（已实现且扎实的部分）

- 双系统解耦（Web 方案端 + 本地执行端）REST 通信已跑通
- 方案生成三源融合（规则引擎 + Kimi k3 AI + 经验库检索）已落地
- 本地执行器真实驱动 Motor-CAD，全链路（Web 下发 → 本地认领 → 真实磁计算 → 回传）已实测通过
- 工程纪律（回读校验/基线重载/弹窗抑制/逐点落盘/纯 ASCII）执行到位
- 第三方评审 P0/P1 已修复，测试留痕规范

### 1.2 平台性短板（本次系统性深潜发现）

| # | 短板 | 现状 | 平台性影响 |
|---|---|---|---|
| S1 | **指标定义三处漂移** | `src/solver_core.py`(15项) / `scripts/robust_motorcad.py`(18项) / `web/.../metrics_constants.py`(25项) 三份不统一 | 新增指标要改三处，必然漂移 |
| S2 | **解析器两套实现** | solver_core 带字段归一化（全角括号/空白/大小写），robust_motorcad 是无归一化精确匹配 | robust_motorcad 解析不到 tavg_nm/ripple_pct（实测） |
| S3 | **求解核心两套重叠** | `MotorCADSolver`(src) 与 `RobustMotorCADSolver`(scripts) 职责重叠，无统一抽象 | 维护成本翻倍，行为易分叉 |
| S4 | **无工具适配器抽象** | 方案要求的 `SimulationAdapter` ABC 未落地，Motor-CAD 硬编码 | 无法插拔 Maxwell/JMAG |
| S5 | **拓扑是裸字符串** | topology 字段无配置化注册表 | 无法扩展 DRSS/SDSR 参数体系 |
| S6 | **方案 Schema 两套** | `src/plan_schema.py` 与 `web/backend/app/schemas/*` 并行 | 契约漂移风险 |
| S7 | **执行策略硬编码全因子** | feasibility_search 未接入执行器，自适应闭环未通 | P3 优化能力未真正生效 |
| S8 | **调度逻辑分裂** | Web 端 BatchScheduler（内存）与本地执行器（轮询）两套 | 平台化调度难扩展 |

### 1.3 平台化目标

把系统从"单工具、单拓扑、单策略"的专用工具，升级为：

> **可插拔工具、可配置拓扑、可扩展策略、契约统一、单一事实源**的电机仿真自动化平台。

新增一个工具/拓扑/策略时，只做"注册"和"实现适配器"，不改平台核心。

---

## 2. 目标架构

```
┌──────────────────────────────────────────────────────────────────┐
│                     共享核心层 src/afmcore/                       │
│  （单一事实源，纯 Python，无 GUI/无 Web 依赖，三方共同引用）         │
│                                                                    │
│  metrics.py      指标定义 + 归一化解析器（唯一权威）                 │
│  plan_schema.py  方案契约 V2（唯一权威）                            │
│  topology.py     拓扑注册表（SSSR/DRSS/SDSR 参数体系+模板+规则）      │
│  adapters/       仿真工具适配器（接口+注册表+实现）                  │
│  strategies/     执行策略（full_factorial / adaptive）              │
│  validation.py   结果校验规则集（可插拔判据）                        │
└───────────────┬────────────────────┬────────────────┬──────────────┘
                │                    │                │
        ┌───────▼───────┐   ┌───────▼───────┐   ┌─────▼──────────┐
        │  系统一 Web 端  │   │  系统二 本地端 │   │  GUI / 其他      │
        │  backend 引用   │   │  executor 引用 │   │  工具脚本引用     │
        │  src/afmcore  │   │  src/afmcore │   │  src/afmcore   │
        └────────────────┘   └───────────────┘   └────────────────┘
```

### 2.1 分层职责

| 层 | 职责 | 不许做 |
|---|---|---|
| 共享核心层 src/afmcore/ | 指标、契约、拓扑、适配器接口、策略接口、校验规则 | 不依赖 Motor-CAD/Web/GUI 具体实现 |
| 系统一（Web） | 方案生成、AI、分析、知识库、任务调度 | 不直接调 Motor-CAD |
| 系统二（本地） | 执行任务、驱动工具、落盘、回传 | 不依赖 AI（可离线） |
| GUI | 加载方案、监控、展示 | 不跑仿真（子线程例外） |

### 2.2 扩展点一览（平台性的落点）

| 扩展点 | 新增方式 | 不改动 |
|---|---|---|
| 新仿真工具（Maxwell/JMAG/Flux） | 实现 `SimulationAdapter` + 注册 `tool_name` | 执行器/任务层/解析层 |
| 新拓扑（DRSS/SDSR） | topology.py 注册参数体系 + 模型模板 + 默认规则 | 引擎核心 |
| 新执行策略（adaptive） | strategies/ 实现策略接口 | 任务下发层 |
| 新指标 | metrics.py 加一项（key/label/alias/direction） | 所有消费端自动生效 |
| 新校验判据 | validation.py 加一个可插拔 rule | 执行器/方案端 |
| 新物理场 | 适配器实现多物理场提取 + 指标扩展 | 架构 |

---

## 3. 第一批落地：共享核心层（本轮实施）

> 优先解决 S1/S2/S3/S4，这是平台性的地基，也是数据正确性的根因。

### 3.1 src/afmcore/metrics.py（单一事实源）

- 合并三处指标定义，形成唯一 `METRIC_DEFINITIONS`（key/label/aliases/direction/required/unit）
- 归一化解析器：全角括号→半角、去空白、小写，三段匹配（section 优先级→全 section 精确→前缀模糊）
- 提供 `parse_export()` / `extract_all_metrics()` / `pick_metric()` 统一入口
- 兼容导出：保留 `solver_core` / `robust_motorcad` / `metrics_constants` 的旧符号名（薄兼容层），避免一次性大改调用点

### 3.2 src/afmcore/adapters/（工具适配器）

```
base.py      SimulationAdapter(ABC): connect/load_model/set_parameter/run_simulation/extract/disconnect
registry.py  ADAPTER_REGISTRY: {tool_name: adapter_class}，get_adapter(tool)
motorcad.py  MotorCADAdapter: 包装 RobustMotorCADSolver，实现统一接口
```

- 执行器通过 `get_adapter("motorcad")` 获取，不再硬编码
- 未来 `get_adapter("maxwell")` 只需注册新类

### 3.3 消费端接入

| 消费端 | 接入方式 |
|---|---|
| `src/solver_core.py` | 改为 `from .afmcore.metrics import *`，保留旧名导出 |
| `scripts/robust_motorcad.py` | 删除自带 METRIC_DEFINITIONS/_parse_export，改用共享解析器（修复 tavg_nm/ripple） |
| `web/backend/app/metrics_constants.py` | 从共享层派生（或保留 key 常量，标注权威源在共享层） |

---

## 4. 后续批次（待本批验证后启动）

| 批次 | 内容 | 解决 |
|---|---|---|
| P2 | 拓扑注册表落地：topology.py 注册 SSSR 参数体系，DRSS/SDSR 预留 | S5 |
| P2 | 方案 Schema 统一：以 src/afmcore/plan_schema.py 为权威，web schemas 转薄兼容层 | S6 |
| P3 | 执行策略接入：strategies/adaptive 包装 feasibility_search，task_executor 支持 adaptive 模式 | S7 | ✅ 已落地（2026-08-29，M1-M6） |
| P3 | 调度统一：本地执行器支持多实例并行 + 与 BatchScheduler 对齐契约 | S8 | ✅ 已落地（2026-08-29，M4/M3） |
| P4 | 文档同步：原《设计方案介绍》升级 V2，消除与实现漂移 | — |
| P4 | 本地 EXE 打包：PyInstaller 打包执行器 + GUI | 系统二交付物 |

---

## 5. 风险与约束

| 风险 | 应对 |
|---|---|
| 重构破坏现有可用闭环 | 本批只做"共享层 + 接入"，不改行为语义；接入后跑指标解析单元验证 + 回归导入测试 |
| 三处接入遗漏 | 用 Grep 确认所有 METRIC_DEFINITIONS/_parse_export 引用点，逐一替换 |
| web 端部署路径引用 src | Dockerfile/requirements 增加 src 路径映射（本批先保证本地运行，部署调整列入 P4） |
| 纯 ASCII 纪律 | 新代码全 ASCII，中文用 \\uXXXX |

---

*本文档为设计决策稿，代码实现按 3.x 批次逐步落地并回填进度。*

## 6. 实施进度回填

| 批次 | 内容 | 状态 | 验证 |
|---|---|---|---|
| 第一批（2026-08-29） | src/afmcore/metrics.py（25项指标+归一化解析器）；adapters/（SimulationAdapter+注册表+MotorCADAdapter）；solver_core/robust_motorcad/metrics_constants 三端接入；修复 tavg_nm/ripple_pct 解析缺口 | ✅ 完成 | TEST-004：单元验证全 PASS、78文件编译0失败、三端+7本地+4Web 导入回归、纯ASCII |
| 第二批（2026-08-29） | 拓扑注册表 topology.py（SSSR 参数体系 8组37项注册，DRSS/SDSR 预留）+ plan_schema 拓扑校验 + task_executor 切换 get_adapter + _compute_metrics 缺口修复 | ✅ 完成 | TEST-005：36 项断言全 PASS、79文件编译 0 失败、三端导入回归、纯ASCII、回归测试脚本 test_platform_registry.py 固化 |
| 第三批 | 执行策略 strategies（full_factorial/lhs/adaptive）+ task 模型扩展 + AdaptiveOrchestrator + 执行器批次/多实例 + 调度契约统一 + Web 端执行桥（submit-batch） | ✅ 完成 | TEST-006~011，回归脚本 test_p3_*.py 全 PASS |
| 第四批 | 方案 Schema 统一（plan_schema 单一权威）+ 文档同步（原方案 V1.1 → V2）+ EXE 打包 | 🔲 规划中 | — |