术语表
本文档统一定义 YunStack-IoT 中的关键概念和术语，便于团队成员和新读者快速理解。
核心概念
| 术语 | 英文 | 定义 |
|---|---|---|
| 产品 | Product | 一类设备的抽象定义，包含设备型号、厂商信息、物模型 JSON |
| 设备 | Device | 产品的具体实例，每个设备有唯一 ID，关联到一个产品 |
| 物模型 | Thing Model | JSON 格式的设备能力描述，定义属性（Property）、事件（Event）、服务（Service） |
| 属性 | Property | 设备的状态数据，如温度、湿度、开关状态，可读/可写 |
| 事件 | Event | 设备主动上报的告警或通知，如过温告警、按键触发 |
| 服务 | Service | 设备可被调用的能力，如重启、校准，包含输入输出参数 |
| 设备影子 | Device Shadow | JSON 文档，记录设备的期望状态（Desired）和实际状态（Reported），用于状态同步 |
| 遥测数据 | Telemetry | 设备周期性上报的时序数据，如每分钟上报一次温度值，存储在 InfluxDB |
ID 体系
| 术语 | 英文 | 定义 |
|---|---|---|
| 物理 ID | Physical ID / DID | 设备固件层的唯一标识，由 WiFi MAC 地址生成（12 位十六进制大写） |
| 逻辑 ID | Logical ID / UUID | 平台分配的唯一标识，用于 API 调用和业务逻辑，物理 ID 对内，逻辑 ID 对外 |
| 产品 ID | Product ID / PID | 产品在平台的唯一标识，用于 MQTT Topic 和 API 路由 |
| ClientId | — | MQTT 连接时使用的设备标识，通常为设备物理 ID |
MQTT 相关
| 术语 | 定义 |
|---|---|
| Topic | MQTT 消息主题，设备按 sys/{pid}/{did}/thing/... 格式发布和订阅 |
| QoS | 服务质量等级：0（最多一次）、1（至少一次）、2（仅一次）。平台默认使用 QoS 1 |
| Webhook | EMQX 事件回调通知机制。当前架构中暂不使用，设备认证改为 EMQX 直连 PostgreSQL |
| Keep Alive | MQTT 心跳间隔，设备定期发送 PINGREQ 保持连接，超时判定离线 |
| set_reply | 设备收到控制指令后回复的确认消息，包含执行结果和最新状态 |
平台架构
| 术语 | 定义 |
|---|---|
| Web 管理后台 | 基于 Vue 3 + Element Plus 的 PC 端管理界面，用于产品/设备/用户管理 |
| 微信小程序 | 基于 UniApp + Wot Design 的移动端应用，用于设备查看和控制 |
| Dashboard | Web 后台首页，展示系统概览统计 |
| 配网 | 将新设备连接到 WiFi 并注册到平台的过程，支持 BLE/扫码方式 |
| 组织 | Organization |
| 房间 | Room |
状态说明
| 术语 | 定义 |
|---|---|
| 已完成 | 功能开发完毕，测试通过，可生产使用 |
| 基础完成 | 框架搭建完成，核心功能可运行，但缺少边界处理和细节打磨 |
| 计划中 | 已纳入版本规划，尚未开始开发 |
| 待排期 | 已识别需求，但未纳入具体版本 |