# hardware-lab

**Repository Path**: hoowaynew/hardware-lab

## Basic Information

- **Project Name**: hardware-lab
- **Description**: 硬件科普互动实验H5 - 电路仿真引擎驱动的可玩实验
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 硬件实验室 - 互动电路实验 H5

> 把电路仿真引擎变成每篇科普文章的"可玩文末实验"，读者看完文章直接上手操作，犯错即触发教学反馈。

🌐 **线上地址**: https://hardware-lab.pages.dev

## 快速开始

```bash
npm install
npm run dev      # 开发服务器 http://localhost:5180
npm run build    # 构建到 dist/
npm run preview  # 预览构建结果
```

## 35个实验 · 11大分类

| # | 实验 | 分类 | 难度 | 交互 | 错误触发 |
|---|------|------|------|------|----------|
| 1 | LED限流电阻计算器 | ⚡ 电源 | 🟢 入门 | 点击切换电阻值 | 选<65Ω → 烧毁+冒烟+教学弹窗 |
| 2 | GPIO八种模式配置器 | 📋 STM32 | 🟢 入门 | 8模式切换+电平控制 | 浮空输入→波形抖动 / 推挽接地→短路 |
| 3 | PWM占空比可视化调音台 | ⏱️ 定时 | 🟢 入门 | 频率/占空比滑块+负载切换 | 舵机非50Hz→不响应 / 100%占空比→不动 |
| 4 | 分压器计算器 | 📊 模拟 | 🟡 进阶 | R1/R2/Vin滑块 | Vout超出ADC量程 → 警告 |
| 5 | 电容充放电时间常数 | 📊 模拟 | 🟡 进阶 | R/C滑块+充放电切换 | τ过大→充不满 / τ过小→闪烁 |
| 6 | 三极管开关驱动 | 🔌 电路 | 🟡 进阶 | Ib滑块+负载切换 | Ib不足→不饱和 / Ib过大→烧基极 |
| 7 | RC低通滤波器 | 〰️ 信号 | 🟡 进阶 | R/C/频率滑块 | 截止频率不对 → 衰减不够 |
| 8 | I2C通信时序 | 🔗 通信 | 🟡 进阶 | 地址/数据/START/STOP | ACK检测 → NACK错误 |
| 9 | NTC热敏电阻测温 | 📡 传感器 | 🟡 进阶 | 温度/B值/ADC精度滑块 | 温度超限 → ADC溢出 |
| 10 | PCB走线阻抗控制 | 🎨 PCB | 🟡 进阶 | W/H/εr/T滑块 | 阻抗偏离50Ω → 信号反射 |
| 11 | WiFi信号链路预算 | 📡 无线 | 🟡 进阶 | 功率/距离/频率/墙数滑块 | RSSI低于灵敏度 → 链路中断 |
| 12 | SPI逻辑分析仪调试 | 🐛 调试 | 🔴 高级 | CPOL/CPHA选择+数据/频率 | 模式不匹配 → 数据错位 |
| 13 | DC-DC Buck降压转换器 | ⚡ 电源 | 🟡 进阶 | Vin/频率/L/负载/占空比滑块 | 纹波>30% / 占空比偏差过大 |
| 14 | 运放比较器+迟滞 | 📊 模拟 | 🟡 进阶 | V+/Vref/迟滞/输出类型 | 无迟滞→抖动 / 开漏无上拉 |
| 15 | 按键消抖对比 | ⏱️ 定时 | 🟢 入门 | 抖动时间/消抖模式/RC参数 | 无消抖→多次触发 / RC太小 |
| 16 | LDO线性稳压器 | ⚡ 电源 | 🟡 进阶 | Vin/Vout/Iload/热阻滑块 | 结温>125°C → 热关断 |
| 17 | 555定时器振荡器 | ⏱️ 定时 | 🟡 进阶 | Ra/Rb/C滑块 | 频率/占空比偏差过大 |
| 18 | ESD保护电路 | 🔌 电路 | 🟢 入门 | Vwm/Vc/信号电压滑块 | Vwm<信号电压 / 钳位比>3 |
| 19 | UART串口通信 | 🔗 通信 | 🟡 进阶 | 数据/波特率/校验/匹配 | 波特率不匹配 → 乱码 |
| 20 | 光敏电阻测光 | 📡 传感器 | 🟢 入门 | 光照/上拉/暗阻滑块 | ADC饱和/ADC过低 |
| 21 | LC带通滤波器 | 〰️ 信号 | 🔴 高级 | L/C/R/频率滑块 | 严重失谐 → 信号被抑制 |
| 22 | MOSFET低边开关 | 🔌 电路 | 🟡 进阶 | Vgs/Rds/负载滑块 | Vgs<Vth → 未导通；线性区发热 |
| 23 | 继电器驱动+续流 | ⚡ 电源 | 🟡 进阶 | 线圈R/Vcc/续流开关 | 无续流二极管断电 → 击穿三极管 |
| 24 | R-2R DAC | 📊 模拟 | 🔴 高级 | 数字输入/Vref/位数 | 接近满量程 → 精度降低 |
| 25 | ADC采样量化器 | 📋 STM32 | 🟡 进阶 | 分辨率/Vref/采样时间 | 输入超Vref → 饱和 / 位数低 → 精度差 |
| 26 | PCB地平面回流 | 🎨 PCB | 🟡 进阶 | 频率/走线长/地平面类型/开槽 | 开槽 → EMI超标 / 分割 → 跨岛 |
| 27 | 示波器探头补偿 | 🐛 调试 | 🟡 进阶 | 衰减比/补偿系数/方波频率 | 欠补偿 → 圆角 / 过补偿 → 尖峰 |
| 28 | BLE蓝牙链路预算 | 📡 无线 | 🟡 进阶 | 发射功率/距离/频率/障碍物 | RSSI低于灵敏度 → 连接断开 |
| 29 | RS-485差分总线 | 🔗 通信 | 🟡 进阶 | 波特率/线长/终端电阻/节点 | 无终端电阻 → 信号反射振铃 |
| 30 | Sallen-Key有源滤波 | 〰️ 信号 | 🔴 高级 | R/C/Q值/输入频率滑块 | Q值过高 → 谐振峰/自激 |
| 31 | DMA数据传输对比 | 📋 STM32 | 🟡 进阶 | 数据源/目标/数据量/位宽/突发/模式 | FIFO溢出 / CPU被搬运占满 |
| 32 | 超声波HC-SR04测距 | 📡 传感器 | 🟢 入门 | 距离/温度/障碍物/引脚模式/滤波 | 超量程 / 回波太弱 / 温度漂移 |
| 33 | 差分走线等长设计 | 🎨 PCB | 🔴 高级 | 线宽/线距/介质/失配/阻抗标准/频率 | 阻抗偏差 / 时序偏斜 / 间距过小 |
| 34 | LoRa扩频通信 | 📡 无线 | 🟡 进阶 | SF/BW/CR/功率/距离/负载 | 链路不足 / 空中时间过长 / SF/BW不当 |
| 35 | JTAG/SWD边界扫描 | 🐛 调试 | 🔴 高级 | 扫描模式/器件数/链长/TCK/信号质量/上拉 | 无上拉→TAP失控 / 信号差 / 链过长 |

## 架构

```
engine/           仿真引擎核心
  topology.js     拓扑解析（DFS连通性+路径查找）
  simulator.js    行为规则引擎（元件行为+电流计算+standalone仿真器）
  error-detector.js  错误检测+教程索引匹配
  components/     元件行为定义
experiments/      实验配置（JSON驱动，无需写代码）
components/       Vue3 UI组件
  CircuitCanvas.vue     SVG电路画布
  ComponentShape.vue    元件形状渲染（15+种SVG图形）
  WaveformView.vue      波形示波器
  InteractionPanel.vue  交互控件（滑块/点击/选择）
  ErrorPopup.vue        错误教学弹窗
  SmokeAnimation.vue    烧毁冒烟动画
  PwmLoadView.vue       PWM负载可视化
  + 20个专用View组件（分压器/电容/三极管/RC/I2C/NTC/PCB/WiFi/LA/Buck/运放/消抖/LDO/555/ESD/UART/光敏/LC带通/MOSFET/继电器/R2R-DAC/ADC/地平面/探头/BLE/RS485/Sallen-Key/DMA/超声波/差分走线/LoRa/JTAG）
stores/           Pinia状态管理
  experiment.js   实验状态+仿真调度
  progress.js     进度持久化+成就系统（13个成就/35实验）
  favorites.js    收藏+最近浏览（localStorage）
data/             知识点+提示+挑战数据
  knowledge.js    35个实验核心公式/概念/提示
  hints.js        35个实验3级渐进提示
  challenges.js   35个实验挑战模式配置（目标/约束/计时/评分）
```

## 进度与成就系统

- 完成实验获得星数（无错误=⭐⭐⭐，有错误=⭐）
- localStorage 持久化保存进度
- 13个成就：纵火犯 → 亮灯人 → 初出茅庐 → 小有所成 → 渐入佳境 → 过半里程碑 → 硬件达人 → 完美主义 → 精益求精 → 匠人之心 → 零失误大师 → 试错专家 → 分类全才
- 首页实时显示进度条、星数、成就徽章
- 进度导出/导入（JSON备份恢复）

## 学习辅助功能

- **知识点面板**：每个实验可折叠展示核心公式/原理概念/实用提示
- **渐进提示系统**：3级提示（思路点拨→公式提示→答案揭晓），卡住时逐步求助
- **挑战模式**：每个实验都有目标导向+约束条件+计时+评分的挑战关卡
- **难度筛选**：首页按入门/进阶/高级筛选实验
- **统计仪表盘**：分类完成率/完美通关/错误分布可视化
- **首次访问引导**：新用户3步交互引导浮层
- **收藏与最近浏览**：星标常玩实验，快速回访最近6个实验

## 嵌入公众号文章

在文章 HTML 末尾添加 iframe：

```html
<iframe src="https://hardware-lab.pages.dev/?embed=true"
        style="width:100%;height:500px;border:none;border-radius:8px;"
        scrolling="no">
</iframe>
```

也可指定单个实验嵌入：

```html
<iframe src="https://hardware-lab.pages.dev/?embed=true&exp=led-resistor"
        style="width:100%;height:500px;border:none;border-radius:8px;"
        scrolling="no">
</iframe>
```

## 新增实验

只需在 `src/experiments/` 下新建 JSON 文件，无需写代码：

```json
{
  "id": "新实验ID",
  "title": "实验标题",
  "category": "分类ID",
  "canvas": { "components": [...], "wires": [...] },
  "interactions": [...],
  "error_triggers": [...]
}
```

然后在 `src/App.vue` 的 `allExperiments` 数组中注册即可。

## 技术栈

Vue 3 + Vite + Pinia + SVG，纯前端无后端依赖。

## 主题与音效

- **暗色/亮色双主题**：CSS变量驱动，顶部一键切换(☀️/🌙)，自动检测系统偏好
- **Web Audio音效**：程序化生成无需音频文件——点击/切换/滑块/烧毁/短路/成功琶音/成就解锁
- 音效可随时开关(🔊/🔇)，默认开启

## PWA离线支持

已配置 PWA manifest + service worker，支持添加到主屏幕、离线访问。

## 部署

Cloudflare Pages 自动部署，GitHub Actions CI/CD。

## 版本历史

- **v2.1** — 教学完整性修复：errorTutorialMap从23→85条目，100%覆盖全部66个可触发错误类型(此前57个错误弹窗无教学内容)；补全I2C/RS485/DMA/LoRa/JTAG/超声波/差分对等13个v1.8实验错误的教学映射
- **v2.0** — 难度增强+移动端适配：为14个单错误实验各补充1个错误触发器(含教学映射)；新增4档响应式断点(1024/768/600/375px)
- **v1.9** — 质量修复+成就扩展：修复副标题实验计数/hints键名不匹配/挑战缺失3个实验；补全35个实验statusText全覆盖；成就系统从8个扩展至13个里程碑（新增渐入佳境/过半里程碑/匠人之心/试错专家/分类全才）
- **v1.8** — 补充5个薄弱分类实验(DMA数据传输/超声波HC-SR04/差分走线等长/LoRa扩频/JTAG边界扫描)，共35个实验覆盖11分类；修复`_getParam()`运行时bug
- **v1.7** — 新增BLE蓝牙链路/RS-485总线/Sallen-Key有源滤波3个实验，共30个实验覆盖11分类
- **v1.6** — 新增ADC采样量化/PCB地平面回流/示波器探头补偿3个实验，共27个实验覆盖11分类
- **v1.5** — 新增MOSFET低边开关/继电器驱动续流/R-2R DAC 3个实验，共24个实验覆盖11分类
- **v1.4** — 新增UART串口/光敏电阻/LC带通滤波3个实验，共21个实验覆盖11分类
- **v1.3** — 新增LDO稳压器/555定时器/ESD保护3个实验，共18个实验
- **v1.2** — 分享卡片(Canvas生成分享图)+学习路径(15步结构化路线)+实验笔记(localStorage自动保存)
- **v1.1** — 新增3个实验(Buck降压/运放比较器/按键消抖)+挑战模式+难度筛选+移动端优化
- **v1.0** — 统计仪表盘+随机实验+进度导出导入+首次访问引导
- **v0.9** — 渐进提示系统+收藏+最近浏览+键盘快捷键
- **v0.8** — 知识点面板+实验搜索+分享深链接+进度重置
- **v0.7** — 暗色/亮色主题切换 + Web Audio音效系统 + PWA离线支持
- **v0.5** — 补齐PCB/WiFi/调试3个分类，11/11分类全部激活，12个实验
- **v0.4** — 新增RC滤波器/I2C时序/NTC测温，9个实验8分类
- **v0.3** — 修复电源引脚偏移/连线格式/PWM波形3个Bug
- **v0.2** — 新增分压器/电容充放电/三极管开关，首页11分类卡片网格
- **v0.1** — 仿真引擎核心 + 3个旗舰实验，Cloudflare Pages部署