# P4 实施计划 — 平台化第四批

> 状态：**已批准，实施中**
> 依据：`docs/PLATFORM_DESIGN_V2.md` §4 第四批 / `docs/P3_IMPLEMENTATION_PLAN.md` §8 遗留 / `README.md` P5 平台化表第四批
> 原则：沿用工程规范（禁止臆测 / 测试完备 / ASCII / 自查清单 / 文档同步 / commit 规范）

---

## 1. 目标

把平台化推进到"可交付、可扩展、文档不漂移"的收口状态：

1. **方案 Schema 单一权威**（核心）：消除 `src/plan_schema.py`（dataclass）与 `web/backend/app/schemas/schema_v2.py`（Pydantic）两套并行方案定义的漂移，让 `src/plan_schema.py` 成为唯一结构权威，web 端转为薄兼容层。
2. **文档同步 V1.1 → V2**：原《设计方案介绍》升级，消除与实现（P1~P3 平台化）的漂移。
3. **本地 EXE 打包**：PyInstaller 打包本地执行器，产出系统二交付物。
4. **前端 adaptive 视图**（P3 遗留）：批次可视化、收敛曲线，消除"前端仍是全因子展示"的语义错位。
5. **L0 预筛选上提共享核心层**（P3 遗留）：`L0PreScreeningEngine` 从 web 移到 `src/afmcore`，消除 web 依赖。

---

## 2. 现状（已探查确认，2026-08-29）

| 项 | 现状 | 问题 |
|---|---|---|
| 方案结构 | `src/plan_schema.py` 393 行 6 个 dataclass（ScanVariable/ScanCase/FixedParam/SearchStrategy/AcceptanceCriteria/SimulationPlan），已接入 afmcore.topology/strategies；**无顶层校验入口** | 与 web schema_v2.py 双份定义，语义漂移 |
| web 方案模型 | `web/backend/app/schemas/schema_v2.py` Pydantic V2（StrategyMode/FidelityLevel/SearchMethod/…策略子模型） | 独立于 src/plan_schema，AI 输出与存储格式不一致风险 |
| 数据流 | ai_plan 生成 unified v2 dict（fixed_params + variables with value lists）→ 存 SimulationPlan.plan_data → plans.py download 给本地 EXE | 格式转换点分散（plan_generator/rule_engine/plans.py），缺统一入口 |
| 文档 | 《PCB轴向磁通电机自动化仿真系统设计方案介绍》= V1.1 | 与 P1~P3 平台化实现漂移 |
| 打包 | 无 PyInstaller 产物（PyInstaller 6.22.2 已装） | 无系统二交付物 |
| 前端 | adaptive 闭环只有 API，UI 仍是全因子展示 | 语义错位 |
| L0 | `web/backend/app/services/l0_prescreening.py` | web 依赖，本地执行器/策略层无法复用 |

---

## 3. 批次表

| 批次 | 内容 | 验证 |
|---|---|---|
| P4-M1 | 方案 Schema 统一：`src/plan_schema.py` 补顶层校验/归一化入口（parse/validate）；web 端结构权威收敛到 src/plan_schema；schema_v2.py 转薄兼容层（字段语义对齐，不重复定义） | TEST-013：新 test_p4_schema.py（parse/validate 正常+异常+空值、web dict 归一化、schema_v2 兼容层 round-trip、回归现有 plan 用例） |
| P4-M2 | 文档同步 V1.1→V2：升级《设计方案介绍》，回填平台化架构/接口/算法选择/已知限制 | 文档评审 + 与实现对照清单 |
| P4-M3 | EXE 打包：PyInstaller 打包 `scripts/task_executor.py` + `robust_motorcad`（执行器，headless 模式优先）；spec/产物不入库 | TEST-014：构建脚本可复现，产物启动冒烟（--help / 心跳 mock） |
| P4-M4 | 前端 adaptive 视图：批次可视化（当前 batch/点状态）+ 收敛曲线（objective vs batch） | 前端组件单测 + 手工验收截图 |
| P4-M5 | L0 上提共享核心层：`L0PreScreeningEngine` 迁至 `src/afmcore/l0/`，web 改引用 | TEST-015：迁移后导入回归 + 功能等价单测 |

---

## 4. 实施细节

### P4-M1 方案 Schema 统一（核心）

**目标架构**：

```
src/plan_schema.py          # 唯一权威：dataclass 结构 + 顶层 parse/validate/归一化
web/.../schemas/schema_v2.py # 薄兼容层：Pydantic 仅做 HTTP 层类型包装，结构语义委托 src/plan_schema
web/.../services/plan_generator.py / rule_engine.py / routers/plans.py  # 统一走 src.plan_schema 入口
```

**步骤**：
1. `src/plan_schema.py` 新增顶层入口：
   - `parse_plan(data: dict) -> SimulationPlan`：dict → dataclass，缺省字段用默认值（容错 + 归一化）
   - `validate_plan(plan) -> ValidationReport`：结构合法 + 拓扑参数合法（调 afmcore.topology）+ 策略方法已注册（调 afmcore.strategies）+ 扫描变量范围/步长/values 一致性 + 固定参数类型
   - `plan_to_dict(plan) -> dict`：统一序列化（兼容现有 `to_dict`）
2. web 端收敛：
   - `plan_generator.py`：生成流程末尾统一调用 `parse_plan` 归一化 + 校验，失败返回结构化错误
   - `routers/plans.py`：POST /plans 创建时用 src.plan_schema 校验 plan_data（替代/补充 Pydantic 校验）
   - `rule_engine.py`：输出与 src.plan_schema 契约对齐（已声明兼容）
3. `schema_v2.py` 薄化：保留枚举与 API 模型（HTTP 入参校验），字段与 src.plan_schema 语义对齐；删除重复的结构推导逻辑（如有）
4. 回归：现有 plan 创建/下载/执行用例全部保持通过

**涉及文件**：`src/plan_schema.py`、`web/backend/app/schemas/schema_v2.py`、`web/backend/app/services/plan_generator.py`、`web/backend/app/routers/plans.py`、`web/backend/app/services/rule_engine.py`（如涉及）、`scripts/test_p4_schema.py`（新）

### P4-M2 文档同步 V1.1 → V2

1. 读 V1.1《设计方案介绍》全文，建立与实现对照清单（架构/接口/算法选择/模块清单）
2. 升级为 V2：
   - 架构图：补 `src/afmcore` 共享核心层、双系统解耦（Web 智能层 + 本地执行层）
   - 接口：补 `/api/adaptive/*`、`/api/executor/*`、task_contract 状态机、plan_schema 单一权威
   - 算法：补执行策略（full_factorial/lhs/adaptive）、L0 预筛选、断点恢复
   - 已知限制：EXE 打包状态、前端 adaptive 视图状态、许可证依赖
3. README 链接指向 V2

**涉及文件**：`PCB轴向磁通电机自动化仿真系统设计方案介绍.md`（V1.1 → V2）、`README.md`

### P4-M3 EXE 打包

1. 确认打包目标：本地执行器 headless 模式（`scripts/task_executor.py` + `scripts/robust_motorcad` + `src/afmcore`）
2. 编写 `scripts/build_executable.ps1`（构建脚本，ASCII）：
   - PyInstaller `--onefile`（或 `--onedir`，视依赖）打包执行器入口 `scripts/run_task_executor.py`
   - hidden-imports：pymotorcad 相关、src/afmcore 包
3. 产物验证：`dist/` 下 EXE 启动冒烟（`--help` / 短任务 mock 心跳）
4. 规范：`build/`、`dist/`、`*.spec` 不入库（AGENTS.md 生成物纪律）

**涉及文件**：`scripts/build_executable.ps1`（新）、`scripts/run_task_executor.py`（入口确认）

### P4-M4 前端 adaptive 视图（P3 遗留）

1. 前端现状：adaptive 闭环 API 已通（`/api/adaptive/loops/*`），UI 仍全因子展示
2. 新增：循环状态面板（当前 phase、批次号、已用/总预算、收敛状态）+ 批次点状态可视化 + 收敛曲线（objective vs batch）
3. 数据源：`GET /api/adaptive/loops/{id}/status` 现有响应

**涉及文件**：web 前端 Vue 组件（LoopMonitor.vue 或并入现有页面）、API 层确认

### P4-M5 L0 上提共享核心层（P3 遗留）

1. `L0PreScreeningEngine`（`web/backend/app/services/l0_prescreening.py`）迁至 `src/afmcore/l0/prescreening.py`
2. web 端 `l0_prescreening.py` 改引用 src（薄 re-export，保持现有 import 兼容）
3. 依赖检查：L0 不得依赖 web 专属模块（如 db/HTTP），若依赖则一并解耦
4. 回归：feasibility_search（已 import L0）+ web 端调用点

**涉及文件**：`src/afmcore/l0/prescreening.py`（新）、`web/backend/app/services/l0_prescreening.py`（薄化）、引用点

---

## 5. 风险与约束

| 风险 | 应对 |
|---|---|
| Schema 统一破坏现有闭环 | M1 先加 parse/validate 入口（纯新增），再逐步收敛调用点；每步跑现有 plan 用例回归 |
| EXE 打包依赖复杂（pymotorcad COM/license） | 打包 headless 执行器优先；真实 Motor-CAD 连接不做打包内自检（依赖 license server），标注环境依赖 |
| L0 上提引入循环依赖 | 先做依赖扫描（grep L0 的 import），确认无 web 专属依赖再迁移 |
| 前端 adaptive 视图工作量不确定 | 先做最小可视图（状态面板 + 收敛曲线），批次点可视化列后续 |
| ASCII 纪律 | 新 .py/.ps1 全 ASCII，中文进 .md |
| 文档 V2 篇幅大 | 对照清单驱动，逐节回填，不重写原文 |

---

## 6. 验收清单（交付前逐项确认 ✅/❌）

- [x] M1：src.plan_schema parse/validate 单测覆盖正常/异常/空值；web 创建/更新/ai 生成校验接入（test_p4_schema.py 7 组）
- [x] M2：V2 文档与实现对照清单完成（附录 B），README 引用更新
- [x] M3：build_executable.ps1 可复现构建，EXE 冒烟通过（--version/--self-test）
- [x] M4：前端 adaptive 收敛曲线上线（AdaptiveOptimize.vue + points_history 数据源）
- [x] M5：L0 迁移 src/afmcore/l0/prescreening.py，web 薄 re-export，6 处调用点兼容回归全绿
- [x] TEST_RECORDS.md 记录 TEST-013~015
- [x] README 十期记录回填
- [x] 全量回归（P2 36 / M4 / M5 / M6 / closed_loop / checkpoint / concurrency）+ ASCII 0 + py_compile 0
- [x] commit 规范 type(scope): description（M1~M5 共 5 commit + 遗留 4 commit + 文档 1 commit）

---

*本文档为 P4 实施计划，实施进度按批次回填。P4 五件套（M1~M5）已于 2026-08-29 全部完成。*