MotorViz

MotorViz — 永磁同步电机（PMSM）控制学习工作站 项目需求开发提示词

用途：本文档提炼了 MotorVizPWA 项目的完整需求与设计规范。将此提示词提供给 AI 开发工具（如 Claude、GPT-Engineer 等），可快速重新搭建出同等功能的项目。

项目定位：面向电机控制工程师与学习者的离线可用交互式可视化教学工具。

作者：Xinyang.Hu |版本：V01 |日期：2026-06-03

一、项目概览

1.1 项目名称

MotorViz— 永磁同步电机（PMSM）控制学习工作站

1.2 一句话描述

一个纯前端、离线可用的 PWA（Progressive Web App），通过交互式 Canvas 可视化和结构化理论知识面板，帮助工程师理解和学习 PMSM 电机控制的完整技术栈：从坐标变换、FOC 矢量控制、SVPWM 调制，到 MTPA/弱磁、电流采样、谐波分析等。

1.3 核心价值

• 离线可用：通过 Service Worker 实现全资源缓存，首次加载后完全离线运行
• 零依赖：纯 HTML/CSS/JS，不依赖任何第三方框架或库
• 双语友好：中文界面，技术术语保留英文对照
• 交互式学习：Canvas 动画 + 参数调节 + 实时波形反馈
• 模块化架构：理论知识面板 + IFrame 嵌入的可视化模块分离设计

1.4 技术栈

1.5 文件结构

MotorVizPWA/ ├── desktop_learning.html # ★ 主应用入口（导航 + 知识面板 + IFrame 容器） ├── manifest.json # PWA 清单 ├── sw.js # Service Worker 离线缓存 ├── 启动_MotorViz_学习工作站.bat # Windows 一键启动脚本 └── viz/ # 10 个独立可视化模块 ├── foc_full_loop_animation.html ├── clarke_transform_animation.html ├── park_transform_animation.html ├── spwm_algorithms_visualization.html ├── pwm_spwm_svpwm_comparison.html ├── svpwm_calculation_flow.html ├── motor_drive_visualization.html ├── mtpa_flux_weakening_visualization.html ├── current_sampling_timing.html └── harmonic_sources.html

二、全局设计规范

2.1 视觉设计系统

颜色体系（CSS Variables）

:root{--bg:#0d1117;/* 主背景 - 深黑蓝 */--sidebar-bg:#161b22;/* 侧边栏/卡片背景 */--border:#30363d;/* 边框 */--text:#c9d1d9;/* 主文字 */--text-secondary:#8b949e;/* 次要文字 */--accent:#58a6ff;/* 主强调 - 蓝色 */--accent2:#3fb950;/* 成功/正向 - 绿色 */--accent3:#d29922;/* 警告/公式 - 琥珀色 */--accent4:#f78166;/* 错误/高亮 - 红色 */--heading:#e6edf3;/* 标题 */--card-bg:#1c2128;/* 信息卡片背景 */--code-bg:#0d1117;/* 代码块背景 */}

要求：整个项目统一使用上述暗色主题（GitHub Dark 风格），所有子模块必须遵循相同颜色系统。

字体

• 主字体：-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans SC', sans-serif
• 等宽/代码/公式：'Courier New', Consolas, monospace

圆角规范

• 大容器/面板：border-radius: 8px或12px
• 小按钮/Chip：border-radius: 16px（Chip）、6px（普通按钮）
• 代码块：border-radius: 6px
• 公式框：border-radius: 6px

间距规范

• 内容内边距：8px ~ 20px
• 元素间距：8px ~ 12px

2.2 交互设计规范

• 所有可视化模块运行时可暂停/恢复（Pause/Play）
• 支持滑块（range input）调节关键参数
• 键盘快捷键：数字键 1-7 切换知识标签页，B 键切换侧边栏
• 过渡动画：transition: all 0.2s

2.3 响应式设计

• 大屏（>1100px）：侧边栏 380px + 主面板自适应
• 中屏（750-1100px）：侧边栏压缩，子模块面板切换为垂直布局
• 小屏（<750px）：单列布局
• 可视化模块内部使用 CSS Grid 自适应

三、主应用（desktop_learning.html）详细需求

3.1 整体布局

┌────────────── Sidebar (380px) ──────────────┬──────────────── Main Panel ─────────────────┐ │ Logo + 标题 │ Viz Bar: 10个可视化Chip按钮 │ │ ┌─────────────────────────────────────┐ │ ┌─────────────────────────────────────┐ │ │ │ Tab: PMSM | FOC | SVPWM | 高级 | │ │ │ │ │ │ │ 工程 | 采样 | 谐波 │ │ │ IFrame Container │ │ │ │──────────────────────────────────── │ │ │ (嵌入 viz/ 下对应HTML) │ │ │ │ │ │ │ │ │ │ │ 知识内容面板（可滚动） │ │ │ │ │ │ │ · 文字讲解 │ │ │ │ │ │ │ · 对比表格 │ │ │ │ │ │ │ · 公式块 │ │ └─────────────────────────────────────┘ │ │ │ · 要点提示 │ │ Status Bar: 在线状态 | 当前模块 | 侧边栏切换 │ │ └─────────────────────────────────────┘ └───────────────────────────────────────────────┘ │ Footer: 作者 Xinyang.Hu | V01 | 2026-06-03 └──────────────────────────────────────────────────────────────────────────────────────────────┘

3.2 侧边栏（Sidebar）

功能区域（从上到下）：

1. Header：Logo “⚡ MotorViz” + 副标题 “永磁同步电机（PMSM）控制学习工作站”
2. Module Tabs：7 个标签页按钮
3. Content Panel：对应标签页的知识内容（可滚动）
4. Footer：作者、版本号、更新日期

7 个知识标签页及内容：

Tab 1: 🏗️ PMSM基础 (id=“pmsm”)

需包含以下内容块（使用 info-card / formula-box / key-point / note-box / comparison-table 组件）：

1. 电机基础概念

   • 电机定义（电能→机械能）
   • 四种电机对比表（有刷直流/BLDC/PMSM/异步电机IM），对比维度：效率、控制复杂度、应用领域
   • PMSM 高亮标注为最优选择
   • Key Point：「同步」= 转子转速始终等于定子旋转磁场转速，PMSM 无滑差

2. PMSM物理结构

   • 基本构成列表：定子（硅钢片+三相分布式绕组）、转子（钕铁硼永磁体+铁芯）、传感器（旋变/编码器）
   • SPM vs IPM 对比表：结构、特点（Ld≈Lq vs Lq>Ld）、车用选择
   • Key Point：电动汽车几乎全用 IPM，磁阻转矩额外贡献 20-40%，弱磁范围更宽

3. 坐标变换

   • 为什么需要坐标变换：三相abc下非线性、强耦合、时变 → 坐标变换后的直流量 → PI控制直接可用
   • Flow Steps：abc 三相 → Clarke → αβ 两相静止 → Park → dq 两相旋转
   • Note：d轴=励磁方向（与永磁体N极对齐），q轴=转矩方向（超前d轴90°），dq系下 PMSM 像直流电机

4. 核心方程

   • Formula Box 展示 dq电压方程 和 电磁转矩方程（标注永磁转矩 + 磁阻转矩分量）
   • Note：基频公式 fe = pn·n/60，举例说明

Tab 2: 🎯 FOC控制 (id=“foc”)

1. FOC定义：把PMSM当直流电机控制，d轴↔励磁，q轴↔电枢
2. FOC分级架构Flow Steps：速度指令ω* → 速度环PI → iq* → MTPA/弱磁 → id*,iq* → 电流环PI → ud*,uq* → 反Park → SVPWM → 6路PWM→电机
3. 环路层级：电流环（内环200~1000Hz）→ 速度环（外环，带宽=电流环1/5~1/10）
4. 调参顺序Note：①电流环PI → ②前馈解耦 → ③速度环PI → ④MTPA/弱磁 → ⑤高级控制
5. 电流环PI设计：零极点对消法整定公式（Kp=L·ωbw, Ki=Rs·ωbw），带宽经验值表格（开关频率 8/10/16kHz 对应推荐 ωbw 和 Hz）
6. MTPA策略：
   • SPM（Ld≈Lq）：id=0 即最优
   • IPM（Lq>Ld）：需 id<0 产生磁阻转矩，查表(LUT)实现
   • 可提升效率 5-10%
7. 弱磁控制：
   • 为什么弱磁：转速升高→反电势升高→电压饱和，需负id抵消永磁反电势
   • 三个工作区：恒转矩区（MTPA）→ 恒功率区（弱磁I）→ 深度弱磁（MTPV）

Tab 3: 🔢 SVPWM (id=“svpwm”)

1. SVPWM vs SPWM 对比表：调制方式、直流电压利用率（0.5·Vdc vs Vdc/√3）、利用率提升+15.47%、谐波特性
2. Key Point：SVPWM 比 SPWM 直流电压利用率高约 15.5%，是 PMSM 驱动标准调制方式
3. 8个基本电压矢量：6个非零矢量（V₁~V₆，间隔60°）+ 2个零矢量（V₀, V₇），Flow Steps 展示
4. Note：任意 Vref 由相邻两基本矢量+零矢量合成（整体合成，非分相调制）
5. 两种工程实现方式对比表：基于偏移电压（简单，代码量小）vs 基于扇区判断（直观，可精确控制）

Tab 4: 🚀 高级控制 (id=“advanced”)

1. 为什么需要超越FOC：经典PI-FOC在参数变化、负载扰动、高速弱磁下受限
2. 滑模控制(SMC)：滑模面设计思想、优势（参数不敏感、抗扰动）、劣势（抖振）、应用（SMO无传感器控制）
3. 模型预测控制(MPC)：用模型预测未来状态选最优电压矢量、优势（多目标优化、无PI调参）、劣势（计算量大）、典型FCS-MPC
4. SiC/GaN 宽禁带器件：SiC MOSFET（1200V+、800V电驱首选）、GaN HEMT（MHz级、48V微混/OBC）、核心收益（提高fs→减小无源器件→提升功率密度）

Tab 5: 📡 电流采样 (id=“sampling”)

1. 采样基础：FOC电流环依赖准确相电流反馈，ADC必须与PWM硬件同步（定时器触发，非软件轮询）
2. PWM与ADC联动机制：中心对齐PWM + 三角载波（Up-Down Counting），CNT从0→ARR→0，采样点选在CNT=0或ARR（PWM全开/全关时电流纹波最小）
3. 单电阻采样（1-Shunt）：
   • 原理：1个电阻串在DC母线负极，不同时刻采样间接重构三相电流
   • 采样时序说明
   • 优缺点表格：成本最低、PCB简单、无增益失配 / 需两次ADC/周期、有不可测区域、需PWM移相
   • Key Point：不可测区域（两相占空比差<3~5μs时无法区分）
4. 双电阻采样（2-Shunt）：
   • 原理：2个电阻串在A、B两相下桥臂，CNT=0同时触发采集ia、ib，ic由KCL计算
   • 优缺点表格：每周期1次采样、无不可测区域 / 需增益匹配校准
   • Key Point：工业最常用——成本可控、精度足够、算法简单
5. 三电阻采样（3-Shunt）：
   • 原理：3个电阻串在三相下桥臂，直接获取ia、ib、ic
   • 优缺点表格：精度最高、有KCL校验冗余 / 成本最高、需3路运放匹配
6. 三种方案总结对比表：分流电阻数、运放数、ADC通道、采样次数、不可测区域、算法复杂度、成本、典型应用
7. 硬件触发链路Flow Steps：TIM1.CNT=0 → TRGO → ADC1/2注入组 → 采样保持 → SAR转换 → EOC中断 → FOC算法
   • Note：STM32中纯硬件触发，无软件延迟

Tab 6: 〰️ 谐波分析 (id=“harmonic”)

1. 五大类谐波来源总述
2. ①逆变器PWM开关谐波：开关频率fc及其边带（fc±2f₁、fc±4f₁、2fc±f₁），举例计算
3. ②死区效应与逆变器非线性：
   • 死区2~5μs导致输出电压畸变
   • 仅含奇次谐波：5、7、11、13次（6k±1）
   • IGBT/MOSFET导通压降和开关延时
   • Formula Box：死区误差电压 ΔV ≈ (tdead/Ts)·Vdc
4. ③电机本体谐波：齿谐波（Z/p±1次）、绕组分布、磁路饱和（3/5/7次）、转子磁极形状
5. ④直流母线电压纹波：母线电容ESR/ESL→电压纹波→6f₁和2fc耦合到输出
6. ⑤采样与测量噪声：ADC量化噪声（12位~0.02%FSR）、运放噪声/偏置漂移、时钟抖动、EMI
7. THD定义Formula Box：THD = √(ΣIn²) / I₁
   • Key Point：车用电驱通常 THD<5%，谐波超标→转矩脉动→NVH问题

Tab 7: 💻 工程实践 (id=“practice”)

1. FOC代码骨架：完整 C 代码块展示 FOC 主循环（10步：传感器读取→Clarke→Park→速度环PI→MTPA→电流环PI→前馈解耦→反Park→SVPWM→PWM更新），包含语法高亮（关键字红色、函数紫色、数字蓝色、注释灰色）
2. 工程检查清单：电流采样偏移校准、死区补偿、积分抗饱和、过调制处理、温度对Rs/ψf补偿、旋变解码与角度误差补偿、故障保护（过流/过压/过温/失步）

3.3 主面板（Main Panel）

Viz Bar（可视化选择栏）

• 10 个 Chip 按钮，每个带颜色圆点标识
• Chip 激活态：蓝色边框 + 蓝色半透明背景
• 按钮与对应 viz 文件映射：

  按钮文字	颜色	文件
  FOC完整环路	#58a6ff	foc_full_loop_animation.html
  Clarke变换	#3fb950	clarke_transform_animation.html
  Park变换	#d29922	park_transform_animation.html
  SPWM算法	#f78166	spwm_algorithms_visualization.html
  PWM·SPWM·SVPWM对比	#a371f7	pwm_spwm_svpwm_comparison.html
  SVPWM计算流	#56b6c2	svpwm_calculation_flow.html
  电机驱动	#e06c75	motor_drive_visualization.html
  MTPA弱磁	#c678dd	mtpa_flux_weakening_visualization.html
  电流采样时序	#ff6b6b	current_sampling_timing.html
  谐波来源分析	#e5c07b	harmonic_sources.html

IFrame Container

• 初始占位符：大图标 ⚡ + “选择一个可视化模块开始”
• 加载 viz 文件时：src="viz/{filename}"
• sandbox 属性：allow-scripts allow-same-origin allow-forms allow-modals allow-popups
• allow 属性：accelerometer; gyroscope

Status Bar

• 左侧：绿色状态指示灯 + “离线可用 · 本地运行”
• 中间：当前选中可视化模块名称
• 右侧：☰ 侧边栏 切换按钮

3.4 交互逻辑（JavaScript）

1. Tab 切换：点击标签按钮→切换 active 类→显示对应 panel→自动切换推荐可视化
   • Tab-Viz 映射：pmsm/foc/practice→foc_full_loop, svpwm→svpwm_calculation_flow, advanced→mtpa_flux_weakening, sampling→current_sampling_timing, harmonic→harmonic_sources
2. Viz 选择：点击 Chip→高亮当前 Chip→IFrame 加载 viz URL→更新状态栏标签
3. 侧边栏切换：点击按钮/按B键→切换sidebar-collapsed类→侧边栏宽度变为0
4. 键盘快捷键：数字 1-7 = 切换标签页，B = 切换侧边栏（焦点在 input/textarea 时不触发）
5. 初始加载：默认加载 FOC 完整环路可视化

四、10 个可视化模块需求

通用规范（所有模块必须遵循）

• 独立 HTML 文件，可脱离主应用单独运行
• 使用相同的暗色主题（CSS Variables）
• 使用 Canvas 2D API 绘制动画
• 使用requestAnimationFrame实现动画循环
• 支持暂停/恢复（Pause/Play 按钮或状态切换）
• 响应式：Canvas 随窗口 resize 自适应
• 字体支持中文，同时保留英文术语
• 左侧/上方为 Canvas 可视化区域，右侧/下方为控制面板

模块 1：FOC 完整环路动画 (foc_full_loop_animation.html)

• 大小：~53KB，最复杂的模块
• 标题：FOC 矢量控制·完整链路：扭矩请求 → Id=0/MTPA → 弱磁 → 电流环 → SVPWM → 电机
• 信号流图（顶部）：Tₑ*扭矩请求 → Id=0/MTPA → PI电流环 → SVPWM → 电机 → 测量反馈 → 闭环
• 四象限 Layout（2×2 Grid）：
  1. 左上：扭矩→Id=0/MTPA→id,q*参考（dq电流平面），显示 MTPA轨迹(绿)、Id=0轨迹(紫)、电流极限圆(蓝)、电压极限椭圆(橙)、恒转矩线(粉)、当前工作点(红)
  2. 右上：PI电流环响应（id追踪波形和iq追踪波形，含参考值和反馈值曲线）
  3. 左下：SVPWM调制波形（三相调制波、三角载波、输出PWM波形）
  4. 右下：电机三相电流 ia,ib,ic 波形
• 右侧控制面板：
  • 速度参考滑块（0-6000rpm）
  • 扭矩参考滑块
  • 模式按钮：Id=0 / MTPA / 弱磁
  • 暂停/恢复按钮
  • 实时数据显示：转速、id/iq参考值、id/iq实际值、调制比

模块 2：Clarke 变换动画 (clarke_transform_animation.html)

• 大小：~27KB
• 标题：Clarke 变换 (abc → αβ) 交互式可视化
• 三栏 Layout：
  • 左：abc 三相坐标系（3D 投影显示三相正弦波形 + 空间矢量旋转）
  • 中：变换动画过渡区（展示从abc→αβ的变换过程）
  • 右：αβ 两相静止坐标系（α轴水平、β轴垂直，显示合成矢量旋转轨迹和 α/β 分量波形）
• 底部控制：角度滑块、频率滑块、自动旋转开关
• 数学公式展示：Clarke 变换矩阵（等幅值变换和等功率变换两种形式）

模块 3：Park 变换动画 (park_transform_animation.html)

• 大小：~30KB
• 标题：Park 变换 (αβ → dq) 交互式可视化
• 三栏 Layout：
  • 左：αβ 坐标系（静止，矢量旋转）
  • 中：旋转动画过渡（展示 dq 轴如何随转子旋转）
  • 右：dq 旋转坐标系（与转子同步旋转，矢量为直流量）
• 底部控制：转子角度滑块、速度滑块、自动旋转开关
• 关键可视化：dq 分量在旋转坐标系中显示为恒定值（非正弦），证明坐标变换的有效性
• 数学公式展示：Park 变换矩阵及逆变换矩阵

模块 4：SPWM 算法可视化 (spwm_algorithms_visualization.html)

• 大小：~47KB
• 标题：SPWM 算法 — 5种注入方式对比
• Layout：上大图（多波形对比）+ 下控制面板
• 5种 SPWM 方式：
  1. 经典 SPWM（正弦调制波 vs 三角载波）
  2. 三次谐波注入（THI）
  3. 零序分量注入（ZSS）
  4. 双调制波（DMPWM）
  5. 不连续PWM（DPWM）
• Canvas 内容：三相调制波、三角载波、PWM 输出脉冲
• 控制：调制比滑块、基频滑块、方式选择按钮、表格对比每种方式的电压利用率和开关损耗

模块 5：PWM/SPWM/SVPWM 对比 (pwm_spwm_svpwm_comparison.html)

• 大小：~39KB
• 标题：PWM · SPWM · SVPWM 对比可视化
• Layout：三行对比（每种调制方式一行），每行显示调制波和输出波形
• 对比内容：
  • 直流电压利用率（SPWM=0.5, SVPWM=0.577）
  • 调制波形状差异
  • 谐波含量对比
• 交互：可调节调制比，实时看三种方式的波形变化

模块 6：SVPWM 计算流程 (svpwm_calculation_flow.html)

• 大小：~42KB
• 标题：SVPWM 空间矢量调制计算流程
• 内容：
  • 左：扇区图（6个扇区，V₁~V₆ 矢量方向标注）
  • 右：当前扇区放大视图，显示 Vref 合成（T₁·Vₓ + T₂·Vᵧ 的平行四边形法则）
  • 下方：PWM 占空比波形（三相上管占空比 Ta/Tb/Tc）
• 计算步骤可视化：
  1. 判断扇区
  2. 计算 X, Y, Z 中间变量
  3. 计算 T₁, T₂（相邻矢量作用时间）
  4. 饱和处理（T₁+T₂ > Ts 时等比例缩放）
  5. 计算三相 CMP 值
• 两种实现方式切换：偏移电压法 vs 扇区判断法
• 交互：Vref 幅值和角度滑块

模块 7：电机驱动可视化 (motor_drive_visualization.html)

• 大小：~52KB
• 标题：电机驱动系统可视化
• Layout：
  • 左大：电机横截面动画（定子、转子旋转、磁链方向、dq轴标注）
  • 右上：三相电流波形
  • 右下：转矩/转速曲线
• 动画元素：
  • 定子铁芯固定（含槽）
  • 转子永磁体旋转
  • 旋转磁场矢量（同步旋转）
  • d轴（与N极对齐）和q轴实时显示
• 交互：速度控制、负载转矩调节

模块 8：MTPA/弱磁可视化 (mtpa_flux_weakening_visualization.html)

• 大小：~50KB
• 标题：MTPA & 弱磁控制策略可视化（dq平面）
• 核心可视化：完整的 dq 电流平面图
  • 电流极限圆（以原点为圆心，Imax 为半径）
  • 电压极限椭圆族（随转速升高向原点收缩）
  • MTPA 轨迹曲线（从原点出发，在电流极限圆内）
  • 弱磁区域标注（恒转矩区→恒功率区→MTPV区）
  • 当前工作点移动动画
• 右侧面板：
  • 速度/扭矩滑块
  • 实时数据显示：id、iq、电压裕量、调制比
  • 模式切换：MTPA / 弱磁I / MTPV
• 关键交互：拖动速度滑块，观察工作点如何沿 MTPA 轨迹移动，到达电压极限后进入弱磁区

模块 9：电流采样时序 (current_sampling_timing.html)

• 大小：~27KB
• 标题：电流采样时序 — 电机控制入门
• 核心可视化：
  • 上半部分：中心对齐 PWM 波形（三角载波 + 三相上管 PWM）
  • 标注采样触发点（CNT=0 或 CNT=ARR 位置）
  • 下半部分：对应的三相电流波形，标注采样时刻
• 三种模式切换：单电阻 / 双电阻 / 三电阻
• 每种模式展示：
  • 单电阻：展示两次 ADC 采样时刻、不可测区域高亮
  • 双电阻：CNT=0 同步采样 ia 和 ib
  • 三电阻：CNT=0 同时采样 ia, ib, ic
• 交互控制：
  • 采样模式选择按钮
  • 占空比调节滑块
  • 死区时间滑块（显示死区影响）
  • PWM 频率滑块

模块 10：谐波来源分析 (harmonic_sources.html)

• 大小：~28KB
• 标题：三相电流谐波来源 — 时域/频域交互式分析
• Layout：左侧大 Canvas（时域波形+频域柱状图并排）+ 右侧控制面板
• Canvas 内容：
  • 上半：三相电流时域波形（含谐波畸变效果）
  • 下半：FFT 频谱柱状图（频率轴标注，谐波次数标注 1,5,7,11,13…）
• 五大谐波来源可独立开关：
  1. PWM 开关谐波（fc±2f₁ 边带）
  2. 死区效应（奇次谐波 5/7/11/13）
  3. 电机本体谐波（齿谐波、饱和谐波）
  4. 母线纹波
  5. 测量噪声
• 每条谐波源有独立滑块调节幅度（0-100%）
• 实时计算并显示 THD 值，颜色指示（绿<5%、黄5-10%、红>10%）
• 对比模式：可同时显示 Clean（纯正弦）和 Distorted（谐波叠加）波形

五、PWA 离线功能

5.1 Service Worker (sw.js)

• 策略：Cache-First with Network Fallback（优先缓存，缓存未命中则网络请求并缓存）
• 缓存名称：motorviz-v1.1（版本化以便更新）
• 安装事件（install）：
  • 预缓存所有核心资源（index.html, manifest.json, icon-192.png, icon-512.png, 所有 viz/*.html）
  • 使用skipWaiting()立即激活
• 激活事件（activate）：
  • 清理旧版本缓存
  • clients.claim()控制所有客户端
• Fetch 事件：
  • 仅处理 GET 请求
  • 跳过 chrome-extension 和非 http(s) 请求
  • 缓存命中→返回缓存 + 后台更新缓存（stale-while-revalidate 变体）
  • 缓存未命中→网络请求→缓存后返回
  • 完全离线时导航请求返回缓存的 index.html
• 错误处理：部分资源缓存失败不阻塞 install，单个请求失败不崩溃

5.2 Web App Manifest (manifest.json)

{"name":"电机控制原理可视化","short_name":"MotorViz","description":"电机控制原理交互式可视化工具集 — FOC、SVPWM、MTPA、坐标变换等","start_url":"index.html","display":"standalone","orientation":"any","background_color":"#1a1d23","theme_color":"#1a1d23","categories":["education","engineering","utilities"],"lang":"zh-CN"}

• 需要图标文件 icon-192.png 和 icon-512.png

5.3 启动脚本（启动_MotorViz_学习工作站.bat）

• 设置控制台代码页为 UTF-8（chcp 65001）
• 显示启动欢迎信息
• 使用start ""在默认浏览器打开desktop_learning.html
• 自动退出命令行窗口

六、CSS 组件库

项目中复用的 UI 组件样式定义（所有模块可复用）：

组件清单

七、开发优先级与实施建议

Phase 1：基础框架（优先）

1. 创建desktop_learning.html主框架（侧边栏 + IFrame 容器 + 样式系统）
2. 创建manifest.json和sw.js
3. 创建启动脚本
4. 实现 7 个知识标签页的全部文本内容
5. 实现 Tab 切换和 Viz Chip 选择交互逻辑

Phase 2：核心可视化模块

6. foc_full_loop_animation.html— 最核心，展示完整 FOC 链路
7. clarke_transform_animation.html— 坐标变换基础
8. park_transform_animation.html— 坐标变换基础
9. svpwm_calculation_flow.html— 调制核心

Phase 3：高级模块

10. mtpa_flux_weakening_visualization.html— 高级控制策略
11. motor_drive_visualization.html— 系统级可视化
12. spwm_algorithms_visualization.html— SPWM 深化
13. pwm_spwm_svpwm_comparison.html— 对比教学

Phase 4：工程实践模块

14. current_sampling_timing.html— 采样时序
15. harmonic_sources.html— 谐波分析

八、关键技术要点提示

Canvas 动画实现模式

// 每个模块的标准动画循环结构：letanimationId;letpaused=false;lettime=0;functionanimate(timestamp){if(!paused){update(timestamp);// 更新状态}draw();// 始终重绘（响应 resize）animationId=requestAnimationFrame(animate);}functionupdate(timestamp){// 根据时间步进更新：角度、电流、电压等constdt=Math.min((timestamp-lastTime)/1000,0.05);// 防止大跳帧lastTime=timestamp;// 更新逻辑...}functiondraw(){constctx=canvas.getContext('2d');constW=canvas.width;constH=canvas.height;ctx.clearRect(0,0,W,H);// 绘制逻辑...}// Canvas resizefunctionresizeCanvas(){constrect=canvasWrap.getBoundingClientRect();canvas.width=rect.width*devicePixelRatio;canvas.height=rect.height*devicePixelRatio;canvas.style.width=rect.width+'px';canvas.style.height=rect.height+'px';ctx.scale(devicePixelRatio,devicePixelRatio);}

FOC/电机控制核心公式参考

Clarke 变换（等幅值）： iα = ia iβ = (ia + 2*ib) / √3 Park 变换： id = cos(θ)·iα + sin(θ)·iβ iq = -sin(θ)·iα + cos(θ)·iβ 反Park 变换： uα = cos(θ)·ud - sin(θ)·uq uβ = sin(θ)·ud + cos(θ)·uq dq 电压方程： ud = Rs·id + Ld·did/dt - ωe·Lq·iq uq = Rs·iq + Lq·diq/dt + ωe(Ld·id + ψf) 电磁转矩： Te = (3/2)·pn·[ψf·iq + (Ld-Lq)·id·iq] 基频：fe = pn·n/60 电流环PI（零极点对消）： Kp = L·ωbw Ki = Rs·ωbw SVPWM 直流电压利用率：Vdc/√3 ≈ 0.577·Vdc SPWM 直流电压利用率：0.5·Vdc SVPWM 提升：~15.47%

九、注意事项

1. 所有文件必须是纯静态的（HTML/CSS/JS），不需要任何服务端运行环境
2. IFrame 的 sandbox 属性必须保留，确保安全隔离
3. Canvas 的 devicePixelRatio 适配：务必乘以 devicePixelRatio 以在 Retina/HiDPI 屏幕上清晰显示
4. Service Worker 注册在 index.html 最底部通过脚本完成
5. 图标文件icon-192.png 和 icon-512.png 需单独生成（可用 SVG 转 PNG 工具生成简单的电机图标）
6. 所有子模块文件路径相对于主 HTML 为viz/目录
7. 代码中的电机参数（Rs, Ld, Lq, ψf, pn 等）需要采用合理的默认值，并标注典型范围

本文档完整描述了 MotorViz 项目的需求、架构、设计规范和实现细节。将此提示词提供给 AI 开发工具，可重建完整的电机控制学习工作站。