云控一体机 - Web 版 (yunkong-web)

将微信小程序「云控一体机」(电动自行车控制器蓝牙配置应用) 重新开发为独立 HTML/TypeScript Web 项目。

技术栈

• 构建工具: Vite + HTTPS (Web Bluetooth 需要)
• 语言: TypeScript (严格模式)
• UI 框架: Lit (Web Components)
• 蓝牙: Web Bluetooth API
• 测试: Vitest

快速开始

cd yunkong-web
npm install
npm run dev      # 启动 HTTPS 开发服务器 (https://localhost:3000)
npm run build    # 生产构建到 dist/
npm test         # 运行协议层单元测试

⚠️ 浏览器要求: 仅 Chrome / Edge / Opera 支持 Web Bluetooth。必须在 HTTPS 或 localhost 环境下运行。

项目结构

src/
├── main.ts                 # 应用入口 (4-tab shell)
├── app.ts                  # 全局状态 (替代 App.globalData + watch)
├── config.ts               # 配置常量 (myconfig.js 等效)
├── core/                   # 核心基础设施
│   ├── reactive-store.ts   # 响应式状态管理
│   ├── router.ts           # hash 路由
│   ├── event-bus.ts        # 事件总线
├── ble/                    # BLE 适配器
│   ├── adapter.ts          # Web Bluetooth API 适配
│   ├── services.ts         # UUID 常量
│   ├── device-filter.ts    # 设备过滤
├── protocol/               # BLE 协议层 (核心)
│   ├── frame.ts            # 0x9595 帧构建/解析
│   ├── commands.ts         # 命令构建器
│   ├── params.ts           # 所有参数定义 (~1100 行)
│   ├── at-commands.ts      # AT 命令
│   ├── crc.ts              # FCS + CRC-16
│   ├── data-codecs.ts      # 数据编解码
├── features/               # 功能页面
│   ├── scan/               # BLE 扫描连接
│   ├── monitor/            # page1: FOC 监控
│   ├── learn/              # page2: 电机学习 + IO 配置
│   ├── params/             # page3: 高级参数
│   ├── settings/           # page4: 系统设置
│   ├── upgrade/            # 固件升级 (待实现)
│   └── fast-install/       # 快速安装 (待实现)
├── components/             # 通用 UI 组件
├── i18n/                   # 国际化 (中/英/越)
├── api/                    # HTTP 客户端
├── utils/                  # 工具函数
└── styles/                 # 样式 (主题: 亮/暗)

BLE 协议

帧格式: [0x95, 0x95, length, code, address?, ...data, fcs]

• 头部: 0x9595
• 长度: 总字节 - 3 (包含 code + addr + data + fcs)
• 响应码: 请求码 | 0x80
• 错误码: 请求码 | 0x40
• FCS: 所有字节 XOR

服务 UUID:

• 数据服务: FFE0 (写: FFE1, 通知: FFE2)
• 令牌服务: FFC0 (写: FFC1)

已实现功能 (核心)

• ✅ BLE 扫描 / 连接 / 断开
• ✅ 二进制协议帧构建 / 解析 (含 MTU 分片重组)
• ✅ FOC 实时监控 (速度/电压/电流/温度/故障码)
• ✅ 电机自学习 (启动/停止/进度查询)
• ✅ IO 端口配置 (7 种控制器型号, 30 针)
• ✅ 参数读写 (44+ 参数, 两轮/三轮)
• ✅ 显示协议选择 (36+ 品牌)
• ✅ 主题切换 (亮/暗)
• ✅ 语言切换 (中/英/越)
• ✅ 本地项目管理 (LocalStorage)
• ✅ 协议层单元测试 (25 项)

后续迭代 (需后端或额外工作)

• ⬜ 语音引导安装 (step.js 18 步骤) — 需音频托管
• ⬜ 快速安装 + OCR — 需 Tesseract.js 或后端
• ⬜ 固件升级 (upgrade.js 状态机) — 需固件文件托管
• ⬜ 显示协议升级状态机 — 需显示 bin 文件托管
• ⬜ 云端项目同步 — 需后端服务 (xcm.wx-iot.com CORS)
• ⬜ MAC 地址验证 — 需后端服务
• ⬜ 设备注册/管理 — 需后端服务

与原小程序的差异

1. BLE 扫描: Web Bluetooth 无被动扫描, 用户需手动选择设备 (无法自动连接最强信号)
2. 音频: 浏览器阻止自动播放, 语音引导需用户首次交互后才能播放
3. 存储: LocalStorage 替代云存储, 项目数据仅保存在本地
4. MTU: Web Bluetooth 不暴露 MTU, 使用保守 20 字节分块