صفحهٔ اصلی گشت‌و‌گذار راهنما
ثبت نام ورود
carlin
/
pcb-afm-simulation-system
1
0
انشعاب 0
پرونده‌ها مشکلات 0 درخواست واکشی 0 ویکی
شاخه: master
شاخه‌ها تگ‌ها
pcb-afm-simu...
/
docs
/
archive
/
P4_IMPLEMENTATION_PLAN.md

P4_IMPLEMENTATION_PLAN.md 9.3 KB
لینک دائمی تاريخچه خام

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. 验收清单（交付前逐项确认 ✅/❌）

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

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