第十部分：MVP 实现说明

10.1 交付目标

本次不是只输出界面原型，而是提供一个可以直接运行和自动验证的纵向 MVP。它以同一份领域数据连接管理后台、后端和微信小程序，覆盖首期最关键的设备交付闭环。

工程路径：物联网项目文档/iot-platform-mvp。

10.2 技术选择

端	技术	选择理由
后端	Node.js 20+ 内置 HTTP/crypto/fs	零第三方依赖，可在当前环境直接运行和审查
持久化	原子替换 JSON 文件	便于 MVP 演示、测试隔离和回滚；明确不是生产数据库
管理后台	原生 HTML/CSS/JavaScript SPA	无构建步骤，服务启动即可访问；响应式桌面/移动布局
小程序	原生微信小程序 WXML/WXSS/JS	可直接导入微信开发者工具，保留平台 API 对接方式
测试	Node.js assert + 真实 HTTP 端到端请求	不使用 Mock 路由，验证认证、持久化和响应契约

10.3 已实现能力

后端

PBKDF2 密码哈希、HMAC 签名令牌、过期校验。
admin/operator/user 三种角色及接口级授权。
产品查询/创建、设备查询/注册/修改、用户查询。
设备凭据校验、遥测接收、属性合并、在线态刷新。
小程序登录适配、设备绑定、归属过滤、设备详情。
管理端/用户端指令下发、在线成功与离线等待状态。
告警列表/处置、关键动作审计、健康检查。
JSON 写入使用临时文件加同卷重命名，避免半写文件。

管理后台

登录页、响应式侧栏和角色感知菜单。
运营统计、近七日趋势、最近告警。
产品、设备、用户、指令、告警和审计页面。
新建产品、注册设备、下发指令、处理告警等实际 API 操作。
本地令牌会话、401 自动退出、错误消息和加载态。

用户小程序

微信登录入口及本地 demo 登录。
本人设备汇总、在线/离线状态、下拉刷新。
扫码或手工输入绑定码。
设备属性和基础信息查看、开关控制。
个人中心和退出登录。

10.4 启动与验证

cd E:\_1\notes\项目规划\物联网项目文档\iot-platform-mvp
npm test
npm start

管理后台：http://127.0.0.1:3000/admin/
健康检查：http://127.0.0.1:3000/api/health
管理员：admin / admin123
运维人员：operator / operator123
演示绑定码：IOT-GW-0002

默认数据首次运行写入 backend/data/db.json。需要恢复演示数据时，停止服务后删除该文件并重新启动；正式数据请先备份。测试使用独立临时文件，不污染运行数据。

10.5 配置

环境变量	默认值	说明
`PORT`	`3000`	HTTP 监听端口
`TOKEN_SECRET`	内置开发值	令牌签名密钥；生产必须使用长随机值并托管
`DATA_FILE`	`backend/data/db.json`	JSON 数据文件绝对或相对路径

小程序 API 地址在 mini-program/config.js。开发者工具可使用 127.0.0.1；手机真机需要开发机局域网地址，生产必须使用已备案且加入小程序合法域名的 HTTPS 地址。

10.6 代码结构

iot-platform-mvp/
├─ backend/
│  ├─ server.js          路由、授权、静态资源和领域用例
│  └─ lib/
│     ├─ auth.js         密码与令牌
│     └─ store.js        种子数据与原子持久化
├─ admin-web/
│  ├─ index.html         应用骨架
│  ├─ styles.css         设计系统与响应式样式
│  └─ app.js             页面渲染与 API 交互
├─ mini-program/         微信小程序入口、页面和请求封装
├─ tests/verify.js       端到端验证
└─ scripts/static-check.js

10.7 已知技术债与生产门禁

存储：JSON 仅支持单进程；生产迁移 PostgreSQL/TimescaleDB 并引入数据库迁移工具。
消息：当前没有连接真实 EMQX；生产实现 Topic ACL、Kafka 消费、设备 ACK、超时重试和幂等。
认证：微信登录仅保留适配入口；生产服务端调用 code2Session，校验 AppID/密钥，并处理手机号授权和账号合并。
密钥：MVP 为联调保存设备明文密钥；生产创建时一次展示，服务端使用 KMS/哈希，提供轮换和吊销。
令牌：生产使用轮换密钥、refresh token、设备/会话撤销和更短后台令牌周期。
前端工程化：规模扩大后迁移 Vue/React + TypeScript、组件库、路由、端到端浏览器测试和构建产物完整性。
可观测性：增加结构化日志、requestId、指标、链路追踪、Broker 指标和 SLO 告警。
多租户：开放客户前所有主表加入 tenant_id，建立行级隔离测试、租户级限流和凭据 scope。

10.8 完成定义

本 MVP 的“完成”指：工程零依赖安装即可启动；确定性测试验证关键权限与业务路径；后台能执行实际数据操作；小程序页面和请求链路完整；需求、接口、部署、用户和迭代文档互相引用。它不等同于生产环境已经满足规模、安全和可靠性目标。

📒 笔记文档