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

> 本文件承接 README.md 的全部历史更新记录（按时间倒序）。
> README 只保留最近更新的摘要表；**当前项目状态以 [docs/HANDOFF.md](docs/HANDOFF.md) 第 3 节为唯一权威来源**。
> 记录规范：新条目加在最上方，格式 `## YYYY-MM-DD — 主题`，里程碑明细另见 `docs/P1-P5交付总结与上手指南.md`。

---

## 2026-09-04 — 结果导出：Web 关键指标 + 全量 Excel/CSV

**结果导出能力完整交付**：
- 前端 PlanDetail 结果表扩充 30+ 中文指标标签；热任务自动加入 5 个热核心列；新增"导出 Excel"/"下载 CSV"按钮
- 新增 `GET /api/plans/{id}/export-xlsx` + `export-csv`：双行表头（类目分组+中文列名带单位），格式复用 torqrippswap scan_results.xlsx 的 write_summary_xlsx
- **全量无损导出**：执行器采集 Motor-CAD 电磁（319 字段）+ 热仿真（578 字段）全部导出字段（raw_flat 链路），SimulationResult 新增 raw_json 存档列，导出文件含全部 ~885 列
- 修复两个实测 bug：Motor-CAD 导出含 "INF" 导致 JSON 上报崩溃（任务卡死）；Node-to-Node 矩阵段误解析产生垃圾列
- 修复历史误标："下载 CSV"原指向方案 JSON 下载接口，从未返回结果 CSV
- 修复 Node Temperatures 段 4 列布局错位（表头 0[25]/数据为部件名），重映射为 部件名[°C]=温度，类目中文化"热仿真-节点温度"；已存数据用磁盘原始导出回填免重跑
- **表头全中文化**：新建 afmcore/export_field_zh.py 三层翻译（精确字典/模式规则/部件词典），461/461 英文字段覆盖；xlsx 新增"字段对照"sheet（中文表头↔Motor-CAD原始字段+单位，885 列全覆盖），供后续软件对接对表

**测试**：TEST-066/067/068，test_xlsx_export.py 66 项全过；真实任务端到端验证（897 字段入库、885 列导出、0 英文表头残留）。

## 2026-09-04 — Motor-CAD 热仿真能力 + 任务级三档开关

**热仿真首次打通并完整交付**：
- 稳态热仿真（电磁→热，134s/点）+ 磁热耦合（474s/点，更准更慢）实测对比
- 修复 P5-M6 遗留的错误 API（do_thermal_calculation→do_steady_state_analysis，export_results "Thermal"→"SteadyState"）
- 7 项热指标别名实测登记（绕组/磁钢/定子/轴承/温升/热阻）
- 环境温度固化（Ambient_Temperature 默认 25°C，MARS 模型 125°C 异常已修正）
- **任务级三档热仿真开关**：off（仅电磁）/ steady（电磁+稳态热，默认）/ coupled（磁热耦合），工程师按任务自主选择
- 前端 TaskManager 任务创建表单加三档单选（含各档耗时提示）

**git 远程推送**：配置 gogsgit.ez4l.com（store 凭据助手 + ~/.git-credentials），以后代码更新后推送免干预。已知限制：ls-remote/fetch（upload-pack 方向）超时，push 正常。

**测试**：TEST-060~062 实测通过（稳态热/磁热耦合/三档端到端），test_executor_m3 修复（claim 逻辑测试夹具缺陷）。

## 2026-09-01 — AI 协作方法论框架升级（Playbook V2）

**背景**：项目已沉淀完整工程纪律（AGENTS.md 硬约束 + TEST_RECORDS + 单一事实源 + 里程碑管理），但缺 playbook 的“接续/换机/上下文延续”机制。本次融合本项目框架与 ai-collab-dev-playbook.md（MARS 电机热仿真方法论）产出 V2 框架，并落地本项目。

**新增/修改**：
1. 新增 `ai-collab-dev-playbook-v2.md`：五支柱文件体系（README/AGENTS/HANDOFF/KNOWLEDGE_BASE/留痕双件套）+ 五步启动法 V2 + 全套模板（含里程碑管理/测试纪律/单一事实源），下个项目可直接复用
2. 新增 `docs/HANDOFF.md`：环境要求、恢复步骤、当前进度（P1~P5+P6-M1 完成）、阻塞点（5 个未验证变量/热求解/多工具 mock/Kriging 降级）、待办（P6-M2/M3）+ 接续提示词
3. 新增 `scripts/check_machine_paths.py`：只读环境体检（Python 版本/环境变量/Motor-CAD exe/Python 包/Git 状态/仓库资产/node），`--fix` 打印修复命令；含项目 venv 探测提示
4. `AGENTS.md` 接入新框架：补 HANDOFF/playbook-v2 引用、环境体检命令、会话日志强制、反模式自查表、接续与交接节
5. `docs/CONVERSATION_LOG.md`：头部补统一模板说明 + 追加本次会话记录

**验证**：check_machine_paths.py 本机运行通过（py_compile + 纯 ASCII + 体检输出正常，详见 TEST_RECORDS TEST-024）。

**技术决策**：check_machine_paths.py 采用“默认只读 + --fix 仅打印命令不自动执行”（避免脚本擅自改系统环境）；会话日志沿用现有 CONVERSATION_LOG（不新建 session_log，避免双日志漂移）。

**已知问题/后续**：新项目可直接复用 playbook-v2；PCB 项目对照框架第 8 节落地清单逐项对齐。
- **V2.1 迭代**（本次）：playbook 已通用化重构——主文不绑定任何项目，新增「版本更新记录」；MARS/PCB 降级为附录案例，可直接复制到任何新项目初始化。

---

## 2026-08-30（晚）— P5-M2 拓扑感知变量名映射与执行前校验

### 背景
Plan 23 的 80 个扫描点全部失败，根因是扫描变量使用了径向磁通电机（RFM）的变量名 `Stator_Lam_Outer_Dia` / `Stator_Lam_Inner_Dia`，而当前模型是轴向磁通电机（AFM/SSSR），Motor-CAD 中不存在这些变量。

### 修复内容
1. **新增拓扑感知变量名映射模块** `web/backend/app/services/topology_variable_map.py`
   - 定义 SSSR / AFIR / RFM 三种拓扑的已知变量集合（41 个 AFM 变量）
   - RFM→AFM 别名映射（`Stator_Lam_Outer_Dia` → `Stator_Outer_Diameter` 等）
   - 模板逻辑名→Motor-CAD 实际名映射（`Number_of_Slots` → `Slot_Number` 等）
   - 变量名校验 + 未知变量建议功能

2. **修复参数展开函数** `_expand_plan_to_parameters()`
   - 扫描变量现在经过模板 motorcad_var + 拓扑别名映射，不再直接用原始 name
   - fixed_params 中不在模板里的参数也经过拓扑别名解析

3. **新增执行前变量名校验** `start_simulation`
   - 启动仿真前校验所有参数名，未知变量直接返回 400 错误并给出建议名
   - 防止静默的 Motor-CAD "Could not find variable" 失败

4. **补充模板缺失的 motorcad_var**
   - 为 8 个几何/电气参数补充了 motorcad_var（`Stator_Outer_Diameter`、`CurrentDefinition` 等）
   - 仅剩 `Current_Density` 和 `Insulation_Class` 合理留空（非直接 Motor-CAD 变量）

5. **新增变量目录 API** `GET /api/plans/variable-catalog?topology=SSSR`
   - 返回指定拓扑的模板参数（含 motorcad_var）和已知变量集合
   - 前端用于填充扫描变量下拉列表

6. **前端优化** PlanDetail.vue
   - 扫描变量从后端 API 获取拓扑感知的变量目录
   - 下拉列表显示中文名 + 逻辑名 + Motor-CAD 实际变量名
   - 不再依赖本地硬编码模板

### 测试
- 单元测试 `scripts/test_topology_variable_map.py`：8/8 PASS
- 包含 plan 23 回归测试：验证 RFM 变量名被正确映射，80 个点全部已知

---

## 2026-08-30 — P6-M1：Web 前端 UI/UX 全面重构（专业仿真工具风格）

**背景**：P5 完成后功能完备，但前端存在信息过载（PlanDetail 1129 行长卷）、导航 14 项平铺无分组、参数三套命名口径、监控页功能重叠、stat-card 四处重复手写等问题。参考 SimScale / Ansys 等在线仿真工具的设计语言（工作流树式导航、三级可见性、高数据墨水比、卡片式分组、上下文操作就近放置），完成 B1（信息架构）+ B2（PlanDetail 分层）两批次改造。

**全局设计系统**：
- 新建 `src/style.css` 设计令牌（CSS 变量）：专业深蓝主色 `#2563eb`、中性灰阶、8px 网格间距、统一圆角/阴影/过渡
- 新建 3 个公共组件：`StatCard.vue`（统计卡片，消除 4 处重复手写）、`SectionCard.vue`（内容区块）、`PageHeader.vue`（页面头部）
- Element Plus 主题变量覆盖（按钮/卡片/表格/标签/Tabs 统一为设计令牌色）

**B1 信息架构重构**（`MainLayout.vue`）：
- 侧边栏由 7 项平铺改为 5 组工作流导航：工作台 / 执行 / 分析 / AI 智能 / 知识
- AI 高级功能（L0预筛选、多保真度校准、经验库AI增强）收进「高级功能」可折叠子组
- 面包屑升级为 项目→方案→任务 层级链（原仅两级）
- 顶栏新增全局任务状态条（运行中任务数，10s 轮询，点击跳转任务管理）
- 侧边栏支持折叠（240px ↔ 64px）
- 页面切换淡入过渡动画

**B2 PlanDetail 分层重构**（`PlanDetail.vue`）：
- 单页长卷改为 4 Tab：概览 / 方案参数 / 仿真结果 / AI 闭环
- 概览 Tab：统计卡 + AI 设计思路 + 验收标准 + 结果摘要（前5行）+ 快捷操作卡片
- 方案参数 Tab：扫描变量（主）+ 边界条件 + 固定参数（默认只显示"已修改"项，其余按分类折叠）
- 仿真结果 Tab：完整结果表 + 导出
- AI 闭环 Tab：步骤指示器 + AI分析/生成迭代/提取经验 三步向导
- 运行中进度横幅（始终可见，含预计剩余时间）
- 预估耗时由硬编码 `points×3min` 改为 `points×2.5min`（贴近真实 90~150s/点）
- 固定参数"需确认"变量名高亮标签（README 已知的 5 个未验证变量）

**其他页面优化**：
- `ProjectList.vue`：PageHeader + StatCard + SectionCard + 搜索/拓扑筛选 + 创建弹窗边界条件双列布局
- `Dashboard.vue`：PageHeader + StatCard + ECharts 趋势/Pareto 图 + 结果表
- `TaskManager.vue`：PageHeader + 6 项状态统计卡 + 状态筛选 + 创建任务从方案下拉选择（JSON 降为高级折叠项）+ 详情抽屉优化

**验证**：`npm run build` 全绿（vue-tsc 0 错误，vite 11.62s 构建完成，2283 模块）。详见 TEST_RECORDS TEST-023。

**后续批次**：B3（参数目录单一事实源，前后端协同）、B4（流程引导+仿真前检查清单+耗时校准）待实施。

---

## 2026-08-30 — 文档卫生修复 + 前端分包优化（外部工程审核整改）

**背景**：外部系统专家审核发现 3 处文档污染与 1 处前端性能问题，本次全部修复。

1. **README.md 控制字符清理**：清除 2 个粘贴带入的控制字符（0x07/0x08），修复 `daptive→adaptive`、`atch_scheduler.py→batch_scheduler.py` 两处被吞字符的文本
2. **docs/TEST_RECORDS.md 修复**：清除 3 个控制字符（`fmcore→afmcore` 等）；重建"测试记录索引"表（TEST-004~022 原本 5 列错位、内容串行，现恢复为 22 条完整 5 列表格）
3. **前端 chunk 分包**：`vite.config.ts` 增加 `manualChunks`（vendor-vue / vendor-echarts / vendor-element 三包拆分），业务代码与第三方库解耦，改善缓存与首屏加载；重新 build 验证 EXIT=0（vue-tsc 0 错误）

**验证**：README / TEST_RECORDS / .gitignore 三文件控制字符清零；`npm run build` 全绿；业务 chunk 由 1MB 级降为 13~54kB（vendor 库独立成 3 包）。

---

## 2026-08-30 — P5-M6：多物理场 L2 接入（热网络+结构指标 + 报告模板化）

**背景**：P5 路线最后一批。metrics.py 仅 25 个电磁指标，报告为单一 metrics 表。P5-M6 扩加热网络+结构指标（自动生效），robust_motorcad 加热求解开关，报告按物理域分组。

**metrics.py 扩项**（单一事实源，extract_all_metrics 自动生效）：
- 热网络 6 项（domain=thermal）：winding_hotspot_temp_c / magnet_temp_c / stator_temp_c / bearing_temp_c / temp_rise_c / thermal_resistance_k_w
- 结构 4 项（domain=structural）：axial_force_n / radial_force_n / max_stress_mpa / deformation_mm
- 均 required=False，含英文+中文别名；总指标 25→35

**robust_motorcad 热求解**：`enable_thermal` 开关（__init__ + run_single_point），默认关；电磁求解后尽力而为 do_thermal_calculation + Thermal 导出合并，失败不中断电磁结果。需要模型热网络配置（环境依赖）。

**报告模板化**：report_generator Results Summary 按域分组（Electromagnetic / Thermal / Structural），每域子标题+表格，空域跳过；从 afmcore.metrics 取 domain/label/unit；JSON fallback 含 metrics_by_domain。

**验证**：test_metrics_extension.py 20/20 PASS（定义/提取/中文别名/必需校验/域分组/报告JSON/robust参数）；全量回归 21/21。真实热求解待模型配置+实际运行。详见 TEST_RECORDS TEST-022。

**P5 路线全部完成**（M1-M6）。

---

## 2026-08-30 — P5-M5：多工具适配器（Maxwell/JMAG mock + 执行器 tool 参数化）

**背景**：适配器层仅有 MotorCADAdapter，执行器硬编码 import motorcad。P5-M5 新增 MaxwellAdapter/JMAGAdapter（mock 实现，真实接入标注环境依赖），执行器根据 `tool` 动态选择适配器。

**新增适配器**：
- `MaxwellAdapter`（tool=`maxwell`）：mock 实现，capability_domains=(electromagnetic, thermal)，确定性合成指标（含 winding_temp_c）
- `JMAGAdapter`（tool=`jmag`）：mock 实现，capability_domains=(electromagnetic,)，指标系数与 Maxwell 不同以区分工具
- 两者均实现 SimulationAdapter 协议（connect/disconnect/load_model/set_parameter/run_simulation/extract_metrics），set_parameter 含回读校验，mock=False 时 connect() 抛 RuntimeError 标注环境依赖

**执行器改造**：`MotorCADTaskExecutor._ensure_adapter()` 从硬编码 import 改为根据 `self.tool` 动态 import（motorcad/maxwell/jmag）；`executor_config.json` 的 `tool` 字段现在可切换工具。

**验证**：test_adapters.py 22/22 PASS（注册/全链路/工具区分/回读校验/边界/异常/执行器动态 import）；全量回归 20/20。真实 Maxwell/JMAG 接入待目标机环境（需 Ansys Maxwell + PyAEDT / JMAG + jmagpy）。详见 TEST_RECORDS TEST-021。

---

## 2026-08-30 — P5-M4：策略层高级管线（Morris 灵敏度 + IDW 代理 + 预算自适应）

**背景**：蓝图 §6 设计四阶段优化管线（Morris 筛选 → LHS 采样 → Kriging 代理 → NSGA-II），但当前策略层仅有 full_factorial/lhs/adaptive。P5-M4 新增 Morris 灵敏度筛选和代理模型引导策略，补齐蓝图前两阶段。

**依赖降级**：环境无 numpy/scipy/sklearn，项目纪律要求纯 stdlib。代理模型用 **IDW（反距离加权）** 替代 Kriging——预测 + 最近邻距离不确定性，支持 UCB explore-exploit 权衡。后续升级 Kriging 须引入 scipy 并在同接口下替换。

**新增策略**：
- `MorrisStrategy`（kind=`morris`）：纯 stdlib Morris OAT 灵敏度筛选，state() 返回 sensitivity_ranking（mu/mu_star/sigma）+ key_parameters
- `SurrogateGuidedStrategy`（kind=`surrogate_guided`）：初始 LHS → IDW 代理 + UCB 采集 + 预算自适应批次大小，state() 返回 phase/budget/surrogate 诊断（loo_rmse/mean_uncertainty）

**验证**：test_strategy_morris.py 15/15 + test_strategy_surrogate.py 17/17；Morris 线性函数灵敏度排名正确（a=2.0 > b=0.5）；SurrogateGuided bowl 函数收敛 best y=0.007（理想 0.0）；全量回归 19/19。详见 TEST_RECORDS TEST-020。

---

## 2026-08-30 — P5-M3：adaptive 可视化补全（批次状态 + L0 摘要 + 运行期轮询）

**背景**：P4-M4 上线收敛曲线后，adaptive 优化页面缺少批次级状态可见性（每批多少点成功/失败/不可行）、L0 预筛选结果展示（采样可行率/不可行原因），且运行期只能手动刷新。P5-M3 补齐三视图。

**后端**：`feasibility_search.py` `get_state_summary()` 增加 `batch_summary`（每批进度/状态分布/批内最优）、`l0_summary`（采样可行率/不可行原因 Top N）、`infeasible_points`、`failed_points`；`search.py` SearchStateResponse 同步增加字段（向后兼容）。

**前端**：`AdaptiveOptimize.vue` 增加①运行期 3s 自动轮询（非 searching 状态自动停止）②L0 预筛选摘要卡片（可行率进度条 + 不可行原因 tag）③批次状态总览卡片（每批进度条 + 状态分布 tag + 批内最优）。

**验证**：`test_search_state_summary.py` 8/8 PASS；vue-tsc && vite build 零类型错误；独立后端端到端 create/state 新字段正常。详见 TEST_RECORDS TEST-019。

---

## 2026-08-30 — P5-M2：EXE 配置化 config.json + mock 分支修复

**背景**：本地执行器 EXE 此前只能靠环境变量（MOTORCAD_MODEL / WEB_BASE_URL）配置，部署到目标机需改环境。P5-M2 引入 `executor_config.json` 侧车配置：web 地址 / 模型路径 / 日志 / 实例数全部可改，无需重新打包。

**改动**：
1. `scripts/executor_config.py`（新增）：配置加载器。优先级：`--config` > `$EXECUTOR_CONFIG` > `<EXE目录>/executor_config.json` > `<仓库根>/executor_config.json` > 内置默认；单字段仍可被环境变量覆盖；相对路径按 EXE 目录/仓库根解析；数值/枚举/类型校验。
2. `executor_config.json`（新增，仓库根模板）：web_base_url / model_path / poll_interval / instances / log_dir / log_level / tool / enable_mock。
3. `scripts/run_task_executor.py`：argparse 支持 `--config / --instances / --interval / --mock / --log-dir / --log-level`；logging 落盘；支持单入口多实例（instances>1）。
4. `scripts/run_task_executor_parallel.py`：复用共享配置加载（保留原 CLI 兼容）。
5. `scripts/task_executor.py`（修复 P4-M3 遗留）：`MotorCADTaskExecutor._run_simulation_point` 此前忽略 `enable_mock` 无条件走真实 adapter；现 `enable_mock=True` 时走基类 mock（结果带 `source="mock"`），不启动 Motor-CAD、不要求 model_path。

**测试**：`scripts/test_executor_config.py`（20 用例：默认/文件合并/环境覆盖/优先级/边界/异常/空值）+ `scripts/test_executor_p5m2.py`（6 用例：mock 分支正常/多点/非法路径仍 mock/默认关闭/真实模式缺模型路径报错/空路径），全部 EXIT=0；全量回归 16/16 PASS。

**EXE 端到端验证（mock）**：重新打包 `dist/PCB-AFM-Executor.exe`（1.1.0）；独立后端（8010 + 临时 DB）→ EXE（`--config` 侧车，enable_mock=true）认领 3 点任务 → mock 求解 → 回传 Web → 任务 completed、3/3 成功、指标入库（tavg 34.56~42.05 N·m、eff 87.95~89.73%）。点级结果带 `source="mock"` 防混淆。

**真实 Motor-CAD 端到端**：✅ 本机已验证单点全链路（EXE → 真实 Motor-CAD → Web，duration 167.5s，tavg=0.52187 / eff=86.06% / losses=41.945W / back_emf=11.15V，与 TEST-010 完全一致，见 TEST-018）。过程中修复两个真实链路 bug：业务名 `airgap_mm→Airgap` 映射 + `point_id` 元数据键排除。真实短扫描/多实例可在目标机验证。

---

## 2026-08-30 — P5-M1：前端全量 build 类型错误清零（backlog B1）

**背景**：`npm run build`（vue-tsc && vite build）历史遗留 71 处类型错误（TS2339/TS2345/TS7006，6 个 .vue）。根因：`src/api/index.ts` 响应拦截器运行时已 unwrap 为 `.data`，但 TS 类型上 `api.get/post` 仍声明为 `Promise<AxiosResponse>`，导致调用处直接访问响应字段报 TS2339；PlanDetail 中 `task.status` 被误判为 HTTP 状态码 number 报 TS2345。

**改动**：
1. `web/frontend/src/api/index.ts`：axios 实例类型改写为 `UnwrappedApi` 接口（get/post/put/delete 返回 `Promise<T>`，默认 any），类型声明与运行时行为对齐；拦截器逻辑原样保留（实例改名 instance 后 cast）。
2. `web/frontend/src/views/PlanDetail.vue`：`@selection-change` 回调参数 `sel` 显式标注 `any[]`（消除 TS7006）。

**验证**：`npm run build` 全绿（vue-tsc 0 错误 + vite 2274 modules 构建成功，真实退出码 0）；后端 health 200 + `test_api_client.py` 真实链路 PASSED；前端 vite dev + API 代理 200；14 个 Python 回归脚本全绿。详见 docs/TEST_RECORDS.md TEST-016。

---

## 2026-08-29 — 方案详情页三栏职责重构（P2-M2 增强）

**背景**：边界条件栏与固定参数栏数量不平衡。根因：边界条件从模板全量渲染（27项），而固定参数只加载AI方案实际写入的少量参数；且边界条件栏混入了大量设计实现参数。

**改动内容**：

1. **边界条件栏瘦身**（27 → 14项）：只保留需求/约束型参数
   - 性能规格：功率/转速/转矩/电流/母线电压/效率/脉动/损耗
   - 几何约束：最大外径/轴向长度；热约束：最大温升
   - 需求描述：拓扑/防护等级/应用场景
   - 移出（归入固定参数）：气隙、内径、槽数、极对数、匝数、并联支路、电流密度、磁钢材料、硅钢片、剩磁、冷却方式、环境温度、绝缘等级

2. **固定参数栏扩容**（模板驱动，36项全量展示）
   - 后端 `app/services/fixed_params_template.py` 扩充为36个参数，按电机工程习惯分8类
   - `plan_generator.py` 固定参数改为**模板全量驱动**：AI不再需要输出固定参数，系统按边界条件推断全部参数值
   - 前端 `PlanDetail.vue` 加载方案时按模板自动补齐缺失固定参数
   - 每个固定参数加**来源标记**（AI/用户），用户修改后自动切换为用户
   - 移除"添加固定参数"按钮与弹窗（参数已全量展示，后续扩展往模板里加）

3. **AI方案思路中文简短化**
   - `plan_generator.py` 默认提示词改造：reasoning 用中文、约200字、只讲关键设计决策与核心参数
   - AI输出固定模板（plan_name/topology/scan_variables/search_strategy/acceptance_criteria/reasoning），固定参数由系统模板生成

4. **Bug修复**：固定参数含字符串值（磁钢材料/硅钢片/冷却方式等）时一键启动仿真500错误
   - `plans.py` `_expand_plan_to_parameters`：数值转float、字符串保留原样

**涉及文件**：
- `web/backend/app/services/fixed_params_template.py`（扩充36参数+8类中文）
- `web/backend/app/services/plan_generator.py`（模板驱动+中文prompt）
- `web/backend/app/routers/plans.py`（字符串参数启动修复）
- `web/frontend/src/views/PlanDetail.vue`（三栏重构+来源标记+去添加按钮）

**已知问题**：
- 新增参数中 `Max_Speed/Winding_Connection/Current_Density/Magnet_Remanence/Insulation_Class` 的 Motor-CAD 变量名未验证，description 已标注"变量名需确认"，执行时可能标记FAILED，需在.mot中确认后修正

---

## 2026-08-29 二期 — 本地执行器真实仿真全链路打通（P2 关键里程碑）

**问题**：前端"一键启动仿真"后一直"仿真中"无进度，Motor-CAD 未打开。

**根因链**：本地执行器未运行 -> 认领逻辑矛盾（只拉pending但任务已dispatched）
-> 列表接口不含parameters -> 字符串参数float崩溃 -> 模板变量名非真实Motor-CAD变量
-> AFM_D_Rotor改外径破坏线性几何。

**修复**：
- 新增 `scripts/run_task_executor.py` 执行器启动入口（后台常驻，认领pending+dispatched任务）
- `scripts/task_executor.py`：`_hydrate_task` 拉取完整参数集；心跳注册（在线/进度）
- `scripts/robust_motorcad.py`：跳过非数值参数写入
- `fixed_params_template.py`：模板加 `motorcad_var`（真实Motor-CAD变量名，从.mot提取）；
  默认值对齐基线模型；AFM_D_Rotor 不写入（外径作约束）
- `plans.py` `_expand_plan_to_parameters`：模板为骨架合并用户修改，仅写真实变量名

**验证**：plan 21 扫描 Airgap 1->2mm 2点全部OK，Motor-CAD打开、进度推进、结果回传，
物理规律正确（气隙↑->反电动势↓）。

**涉及文件**：scripts/run_task_executor.py(新)、scripts/task_executor.py、scripts/robust_motorcad.py、
web/backend/app/services/fixed_params_template.py、web/backend/app/routers/plans.py

**已知问题**：字符串参数（材料/冷却/绝缘）暂不写入，用基线默认；几何改型需Motor-CAD内操作。

---

## 2026-08-29 三期 — 平台化改造第一批：共享核心层 + 适配器抽象

**背景**：按平台化升级设计方案（docs/PLATFORM_DESIGN_V2.md），消除"指标定义三处漂移"与"解析器两套实现"两大平台性短板，为多工具/多拓扑/多策略扩展铺路。

**改动内容**：
1. **新建共享核心层 `src/afmcore/`**（单一事实源）
   - `metrics.py`：25 项指标定义（key/label/unit/direction/required/aliases） + 归一化解析器
   - `adapters/`：SimulationAdapter 接口 + 注册表 + MotorCADAdapter 实现
2. **三个消费端接入共享层**：solver_core / robust_motorcad / metrics_constants 全部改为从 afmcore.metrics 导入
3. **修复 tavg_nm/ripple_pct 解析缺口（TEST-003 遗留）**：根因为 robust_motorcad 无归一化精确匹配，已统一为归一化匹配（全角括号→半角、去空白、小写）
4. **命名规避冲突**：共享包从 platform 改名 afmcore（避免与标准库同名）

**验证**：单元验证全部 PASS（含全角字符解析/中文别名/% 守卫/三端导入/78 文件编译/适配器协议），详见 docs/TEST_RECORDS.md TEST-004。

**进展路线（后续批次）**：P2 拓扑注册表 + task_executor 切换适配器；P3 执行策略接入（adaptive）；P4 方案 Schema 统一 + 文档同步 + EXE 打包。

---

## 2026-08-29 四期 — 平台化改造第二批：拓扑注册表 + 执行器切换适配器

**背景**：按平台化设计方案 P2，消除“拓扑是裸字符串”与“求解器硬编码”两个平台性短板。

**改动内容**：
1. **新建拓扑注册表 `src/afmcore/topology.py`**：SSSR 完整参数体系（8 组 37 项）注册，DRSS/SDSR 预留；提供拓扑验证/参数校验/UI 序列化
2. **`plan_schema.validate()` 集成拓扑校验**：未知拓扑拦截，新增拓扑只做注册
3. **`task_executor` 切换 `get_adapter()`**：从硬编码 RobustMotorCADSolver 改为统一适配器入口；修复结果嵌套导致的 _compute_metrics 聚合空的缺口

**验证**：新增可重复运行回归测试 `scripts/test_platform_registry.py`（36 项断言全 PASS）；79 个 .py 编译 0 失败；三端导入回归通过。详见 TEST_RECORDS.md TEST-005。

---

## 2026-08-29 五期 — P3 平台化改造（第一批：策略抽象层 + 自适应编排器）

**背景**：按 P3 实施计划（docs/archive/P3_IMPLEMENTATION_PLAN.md），把 Web 端已验收的 adaptive 搜索能力接到本地执行器，打通「方案 -> 批次任务 -> 本地执行 -> 回填搜索 -> 续批/收敛」闭环。

**M1 执行策略抽象层（src/afmcore/strategies/）**：
- 新增 SimulationStrategy ABC + STRATEGY_REGISTRY，执行器改为向策略要批次，不再硬编码全因子
- full_factorial（笛卡尔积，自包含）/ lhs（纯 Python 拉丁超立方）/ adaptive（backend 注入桥接，共享层不依赖 web）三种策略注册可用
- plan_schema 的 SearchStrategy.method 归一化（legacy active_learning/constrained -> adaptive）并经策略注册表校验

**M2 任务模型扩展 + 自适应编排器**：
- Task 模型新增 task_type / loop_id / batch_id / point_ids / dynamic 字段（旧库自动迁移 ADD COLUMN）
- 新建 strategy_orchestrator.py：AdaptiveOrchestrator（start_loop / advance_loop / get_loop_status），桥 FeasibilityFirstSearch <-> 任务系统 <-> 本地执行器，loop 状态落盘 output/adaptive_loops/
- 修复现存 bug：task_manager.report_results 未定义 plan_id（应取 task.plan_id）

**验证**：闭环回归脚本 scripts/test_p3_orchestrator.py（fake 执行器，temp DB 隔离），exit 0；详细记录见 docs/TEST_RECORDS.md TEST-006。

**技术决策**：orchestrator 采用 pull 驱动（advance_loop 由调用方/路由/调度器触发），与既有执行器轮询哲学一致；L0 可行性预筛依赖参数名对齐（airgap_mm/current_a），真实 AI plan 生成即对齐。

**已知问题/后续**：路由/定时器接入与真实 Motor-CAD 烟雾测试放 M5；adaptive 前端视图放 P4。

---

## 2026-08-29 六期 — P3 平台化改造（第二批：执行器批次化 + 多实例）

**背景**：P3-M3，让本地执行器原生支持 adaptive_batch 任务与多实例并行，配合 M2 编排器形成批次闭环。

**改动（scripts/task_executor.py）**：
- point_id 回传：逐点结果顶层带 point_id（OK/FAILED 均保留），编排器可精确回填搜索
- 认领原子化：dispatch 失败（被其他实例认领）即跳过该任务，多实例不重复仿真
- executor_id 唯一化 + 修复 report_results 本地模式 on_complete 参数个数不一致 bug

**新增**：scripts/run_task_executor_parallel.py（--instances N 并行启动，--mock 供测试）

**验证**：scripts/test_executor_m3.py（PASS），P2 回归 36/36 不破坏；见 docs/TEST_RECORDS.md TEST-007。

**技术决策**：多实例并行复用 Web 端 dispatch 的幂等语义（pending->dispatched 原子迁移）防重复，执行器侧无需额外锁。

---

## 2026-08-29 七期 — P3 平台化改造（第三批：调度契约统一）

**背景**：P3-M4，统一两套调度状态词汇（TaskManager 的 pending/dispatched 与 BatchScheduler 的 queued），并让调度器任务字段与 Task ORM 对齐。

**改动**：
- 新建 web/backend/app/services/task_contract.py（无依赖契约层）：规范状态常量 + STATUS_ALIASES 归一（queued->pending、canceled->cancelled、completed_with_errors->completed）+ normalize_status/is_terminal/merge_adaptive_fields
- batch_scheduler.py：add_task 支持 task_type/loop_id/batch_id/point_ids/dynamic 透传，_summary 输出新字段（状态词 queued 向后兼容）

**验证**：scripts/test_p3_m4_contract.py（PASS），M2 闭环回归不破坏；见 docs/TEST_RECORDS.md TEST-008。

**技术决策**：用契约层声明统一词汇/字段而非重构两个既有服务，消除漂移同时保持向后兼容；状态归一采用「别名映射 + 未知词透传」（能报错而非静默）。

---

## 2026-08-29 九期 — P3 平台化改造（第四批：HTTP 全链路闭环验证）

> 注：历史记录中无“八期”编号，沿用原始记录。

**背景**：P3-M5，验证「orchestrator -> 任务系统 -> 本地执行器(HTTP) -> 仿真 -> point_id 回填 -> 续批 -> 收敛」全链路真实闭环。

**改动**：
- strategy_orchestrator.py：AI 分析按 KIMI_API_KEY 门控（无 key 时保持 quantitative，不空打 AI 日志）
- 新增 scripts/test_p3_closed_loop.py：真实 FastAPI（temp DB）+ orchestrator + mock 执行器全链路闭环回归，exit 0

**验证**：闭环 n_results=8 budget_exhausted；P2 36 项 + M2/M3/M4 全量回归 PASS；91 个 .py 编译 0 失败；详见 docs/TEST_RECORDS.md TEST-009。

**技术决策**：AI 分析为可选项——无 key 环境自动降级为纯定量结果，配置 key 后自动启用；避免每次批次空调 AI 的日志噪音与延迟。

**真实 Motor-CAD 烟雾**：已通过（TEST-010）——连接/基线加载/求解 1 点/解析 21 项指标全 OK，back_emf=11.15V 与历史 TR-01 一致；同时发现并修复 MotorCADAdapter.run_point 忽略 model_path 的真实 bug。

### P3 平台化改造（第五批：Web 端执行桥 + 路由整合）

**背景**：P3-M6。Web 端已有 AdaptiveLoop 闭环（AI 方案 -> L0 -> FeasibilityFirstSearch -> 选批 -> report-results 回填 -> AI 分析 -> 经验库 -> 收敛），但「本地执行器执行」环节缺失；平台层已具备任务系统 + 执行器（批次 Task、point_id 回填）。本批打通两套体系。

**改动**：
- adaptive_loop.py：新增 submit_batch_to_executor() —— 把当前 pending 批次包装为 adaptive_batch Task（复用 task_manager 原语），交由本地执行器认领执行
- routers/adaptive.py：新增 POST /api/adaptive/loops/{loop_id}/submit-batch 端点
- 撤销误建的 adaptive_orchestrator 路由（与既有 adaptive.py 路径冲突），main.py 还原
- 新增 scripts/test_p3_adaptive_execution.py：Web 端 AdaptiveLoop + 执行桥全闭环集成回归（temp DB + fake executor + 无 AI）

**验证**：M6 集成测试 PASS（fake plan -> 初始 3 点 -> submit-batch -> 3 批 -> budget_exhausted，8 点/8 预算；Task 落库含 loop_id/batch_id/point_ids/dynamic；幂等性 OK；HTTP 端点 404/200 正常）；P2 36 项 + M2/M3/M4/M5/M6 全量回归 PASS；详见 docs/TEST_RECORDS.md TEST-011。

**技术决策**：采用「Web 智能层 + 平台执行层」整合而非新建第二套循环路由——给 AdaptiveLoop 补执行桥（只加方法/端点，不改既有流程），复用已验证的任务系统/执行器，避免两套 /api/adaptive 循环并存。

### P3 收尾遗留处理 + P4 平台化第四批（十期）

**背景**：用户要求"先处理遗留问题 → 写 P4 详细计划 → 直接做 P4"。P4 按 `docs/archive/P4_IMPLEMENTATION_PLAN.md` 五件套实施，全部完成。

**P3 遗留处理（4 commit）**：
- 并发原子认领：`task_manager.dispatch_task` 改 SQLAlchemy 条件 UPDATE（8 线程竞争恰 1 win）
- 断点恢复：`FeasibilityFirstSearch.import_state()` + `AdaptiveLoop.export/restore` + `/loops/{id}/export`、`/loops/import` 端点
- ASCII 纪律：plans.py + fixed_params_template.py 中文串转 `\uXXXX`（运行解码正确）
- 环境依赖测试：`test_api_client.py` 真实链路；未动用户常驻服务

**P4 实施（M1~M5，5 commit）**：
- **M1 Schema 单一权威**：`src/plan_schema.py` 增 parse/validate 入口 + 别名容错 + require_model_path 分级；web 端 main.py 注入 repo root，plans/ai_plan 接入校验（400/422）
- **M2 文档 V1.1→V2.0**：设计方案追加"附录 B 实现现状对照"（蓝图 vs 实现逐项映射）
- **M3 EXE 打包**：`scripts/build_executable.ps1` + PyInstaller onefile → `dist/PCB-AFM-Executor.exe`（12.6MB，--version/--self-test 通过）
- **M4 前端收敛曲线**：search state 增 points_history（逐评估点数据）+ AdaptiveOptimize.vue echarts 收敛曲线
- **M5 L0 上提共享核心**：`L0PreScreeningEngine` 迁 `src/afmcore/l0/prescreening.py`（唯一实现，纯 stdlib），web 薄 re-export 兼容 6 处调用点

**验证**：新增 test_p4_schema / test_p4_m4_convergence / test_p4_m5_l0 全过；P2 36 + M6 + closed_loop + checkpoint + concurrency 全量回归绿；全量 py_compile 0 失败；ASCII 0 违规；vue-tsc 对 AdaptiveOptimize.vue 0 错误（全量 build 仍有既有类型错误属 backlog）。详见 docs/TEST_RECORDS.md TEST-013~015。