@szjy/iot-coms

一个基于 Vue 3 + Element Plus 的物联网（IoT）业务组件库与示例项目。提供设备/监测项/设备类型的列表与详情展示、设备数据查询与图表、告警列表/配置等常用场景组件与 API 封装，帮助前端快速搭建 IoT 管理与监控页面。

• 核心目标: 以组件化方式沉淀 IoT 业务能力，开箱即用，减少重复开发。
• 主要解决问题: 统一组件样式与交互、封装常用 IoT 数据接口、提供示例用法与二次封装能力。
• 典型场景: 项目设备台账、监测项管理、历史数据查询、设备运行态势看板、告警管理与配置。

目录结构说明

.
├─ index.ts                      # 组件库入口（默认导出 install、导出全部组件与 create 工厂）
├─ vite.config.mts               # Vite 打包与开发配置（库模式、类型声明生成等）
├─ tsconfig.json                 # TypeScript 配置
├─ packages/
│  ├─ components/                # 业务组件目录
│  │  ├─ components.ts           # 聚合导出各业务组件入口
│  │  ├─ installer.ts            # 全量注册安装器（自动注册所有导出的组件）
│  │  ├─ create.ts               # 选择性注册工厂（按需注册 + 前缀）
│  │  ├─ contants.ts             # 组件库常量（前缀、版本等）
│  │  ├─ IotDeviceList/          # 设备列表组件
│  │  ├─ IotDeviceDetail/        # 设备详情组件
│  │  ├─ IotDeviceData/          # 设备数据组件（含转换器）
│  │  ├─ IotDeviceTypeList/      # 设备类型列表组件
│  │  ├─ IotDeviceTypeDetail/    # 设备类型详情与动态表单配置
│  │  ├─ IotMonitorItemList/     # 监测项列表组件
│  │  ├─ IotMonitorItemDetail/   # 监测项详情组件
│  │  ├─ IotFeDeviceData/        # 前端渲染的设备数据与图表
│  │  ├─ IotFeAlarmList/         # 前端渲染的告警列表
│  │  ├─ IotAlarmList/           # 告警列表
│  │  └─ IotAlarmSettingList/    # 告警配置列表
│  ├─ api/                       # 业务 API 封装
│  │  ├─ device.ts               # 设备/监测项/设备类型/设备数据/告警相关 API
│  │  ├─ project.ts              # 项目列表 API
│  │  └─ ai.ts                   # AI 能力（流式接口封装，如 Kimi、SiliconFlow、Spark 等）
│  ├─ hooks/                     # 组合式 Hook
│  │  └─ device.ts               # useProjectList/useMonitoringItemList/useDeviceTypeList/useDeviceList
│  └─ common/                    # 公共能力
│     ├─ utils/
│     │  ├─ request.ts           # Axios 封装（Loading、Error、Token 注入）
│     │  ├─ object.ts            # omitEmptyValue 等工具
│     │  ├─ url.ts               # ensureFullURL 等
│     │  └─ ids.ts, loader.ts... # 其它工具
│     └─ ...
├─ examples/                     # 组件使用示例（基于 Vite）
│  ├─ main.ts                    # 示例入口（引入 Element Plus、按需注册组件、挂载全局方法）
│  ├─ App.vue                    # 示例 App 根组件
│  └─ components/                # Tabs 示例，演示各业务组件使用
└─ dist/                         # 构建输出（ES/UMD）与类型声明

• 依赖关系与调用逻辑:
  • index.ts 默认导出 install(app)，内部调用 packages/components/installer.ts 全量注册所有组件。
  • 也可通过 create(options) 选择性注册组件并自定义前缀，适用于「按需注册」。
  • 业务组件通过 packages/api/* 调用后端 API，底层统一走 packages/common/utils/request.ts。
  • 组合式 Hook（packages/hooks/device.ts）封装了列表类接口的获取与选项映射，便于表单下拉等使用。

环境与依赖配置

• Node.js: 建议 >= 18（Vite 5 要求 Node 18+）
• 包管理器: pnpm / npm / yarn 均可（仓库含 pnpm-lock.yaml 与 package-lock.json）
• 浏览器: 现代浏览器（ES2020+）；移动端需根据业务进行适配
• 核心依赖:
  • Vue 3 (^3.4.21)
  • Element Plus (2.7.1)
  • Axios (^1.4.0)
  • ECharts (^5.5.0)
  • Moment (^2.29.4)
  • @form-create/element-ui (^3.1.26)
• 开发依赖:
  • TypeScript (^5.2.2)
  • Vite (^5.1.6) + @vitejs/plugin-vue、@vitejs/plugin-vue-jsx
  • vite-plugin-dts（类型声明生成）
  • unplugin-icons、unplugin-vue-components

安装步骤

# 任选其一
pnpm install
# 或
npm install
# 或
yarn install

环境变量

• VITE_BASE_URL: Axios 默认基础地址（也可在 API 调用时显式传入 baseUrl 覆盖）。
• 其它 Token/网关地址建议由业务应用以参数形式传入组件或 API。

推荐开发工具

• VS Code + Volar（Vue 语言服务）
• TypeScript Vue Plugin (Volar)
• ESLint/Prettier（建议在业务仓库配置）

项目运行指南

开发模式（示例站点）

# 启动 examples 开发站点
pnpm dev
# 或
npm run dev

• 默认地址: http://localhost:8811
• Dev Server 配置: vite.config.mts（host、port、open）

构建库

# 严格类型检查 + dev 模式（关闭极致压缩，便于调试）
pnpm run build:dev

# 标准生产构建（ES + UMD + d.ts）
pnpm run build

• 产物输出到 dist/
• 外部化依赖: vue、element-plus、axios、moment、@form-create/element-ui

预览

pnpm run preview

发布相关

# 自动提交并打 tag（遵循 conventional commits）
pnpm run release

# 同步到 cnpm（内网/镜像场景）
pnpm run sync

功能模块与使用示例

组件注册方式

• 全量注册（适合直接作为 UI 库使用）

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import IotComs from '@szjy/iot-coms'

createApp(App).use(ElementPlus).use(IotComs).mount('#app')

• 按需注册（推荐在大型项目中使用）

import { create } from '@szjy/iot-coms'
import { SzIotDeviceList, SzIotDeviceData } from '@szjy/iot-coms'

const szIotKits = create({
  components: [SzIotDeviceList, SzIotDeviceData],
  // componentPrefix: 'Sz'  // 可自定义前缀，默认来自库常量
})

app.use(szIotKits)

常用组件示例

• 设备列表 SzIotDeviceList

<script setup lang="ts">
// 可通过 props 传入过滤条件、baseUrl、token 等
</script>
<template>
  <SzIotDeviceList />
</template>

• 设备数据与图表 SzIotDeviceData

<template>
  <SzIotDeviceData />
</template>

• 告警列表 SzIotAlarmList / 告警配置 SzIotAlarmSettingList

<template>
  <SzIotAlarmList />
  <SzIotAlarmSettingList />
</template>

组件一览表

| 组件名 | 目录 | 简要说明 | 典型场景 | 主要依赖 API | | --- | --- | --- | --- | --- | | SzIotDeviceList | packages/components/IotDeviceList/ | 设备列表、筛选、分页与操作入口 | 设备台账、设备检索 | GET /deviceInfo、DELETE /deviceInfo/{id}、GET /deviceInfo/{id}、POST /deviceInfo、PUT /deviceInfo/{id} | | SzIotDeviceDetail | packages/components/IotDeviceDetail/ | 设备详情信息展示，支持列到规则转换 | 详情页、抽屉/对话框详情 | GET /deviceInfo/{id} | | SzIotDeviceData | packages/components/IotDeviceData/ | 设备历史数据查询、图表与统计 | 历史趋势、对比分析 | POST /device/data/getHistoryDataPage、POST /device/data/getHistoryData、POST /device/data/getDeviceStats、POST /device/data/listDevice | | SzIotDeviceTypeList | packages/components/IotDeviceTypeList/ | 设备类型列表与筛选 | 设备型号管理 | GET /deviceType、DELETE /deviceType/{id} | | SzIotDeviceTypeDetail | packages/components/IotDeviceTypeDetail/ | 设备类型详情与动态表单配置 | 类型配置、UI 配置可视化 | GET /deviceType/{id}、POST /deviceType、PUT /deviceType/{id} | | SzIotMonitorItemList | packages/components/IotMonitorItemList/ | 监测项列表与筛选 | 监测指标管理 | GET /monitoringItem、DELETE /monitoringItem/{id} | | SzIotMonitorItemDetail | packages/components/IotMonitorItemDetail/ | 监测项详情信息展示 | 指标详情、编辑面板 | GET /monitoringItem/{id}、POST /monitoringItem、PUT /monitoringItem/{id} | | SzIotFeDeviceData | packages/components/IotFeDeviceData/ | 前端渲染的设备数据与图表能力 | 轻量数据可视化、嵌入式看板 | 依赖设备数据 API（同设备数据模块） | | SzIotFeAlarmList | packages/components/IotFeAlarmList/ | 前端渲染的告警列表展示 | 告警看板、首页总览 | POST /alarm/list、POST /data/alarm/getAlarmDataPage | | SzIotAlarmList | packages/components/IotAlarmList/ | 告警记录列表与筛选 | 告警中心、问题追踪 | POST /alarm/list、POST /data/alarm/getAlarmDataPage | | SzIotAlarmSettingList | packages/components/IotAlarmSettingList/ | 告警阈值/规则配置与管理 | 告警策略配置 | POST /alarm/settings/list、DELETE /alarm/settings/delete?id={id}、POST /alarm/settings/create、POST /alarm/settings/update |

Hook 示例（组合式 API）

import { useProjectList, useMonitoringItemList, useDeviceTypeList, useDeviceList } from '@szjy/iot-coms/packages/hooks/device'

const { projectList, projectListOpts } = useProjectList({ skipRequest: false }, baseUrl, token)
const { monitoringItemList, monitoringItemListOpts } = useMonitoringItemList({}, baseUrl, token)
const { deviceTypeList, deviceTypeListOpts } = useDeviceTypeList({ includeConfig: true }, baseUrl, token)
const { deviceList, deviceListOpts } = useDeviceList({ showExtDeviceId: true }, baseUrl, token)

核心数据流（Mermaid）

flowchart LR
  UI[组件层: Iot*] --> Hook[Hooks: use*List]
  Hook --> API[API 层: packages/api/*]
  API --> AX[Axios 封装: request.ts]
  AX --> BE[(后端服务)]
  BE --> AX
  AX --> API
  API --> Hook
  Hook --> UI

API 接口文档

以下仅列出主要接口，更多可参考 packages/api/*.ts。

设备管理（device.ts）

• 获取设备列表

  • GET /deviceInfo
  • 查询参数: page, size, 其它过滤项
  • Headers: Authorization: Bearer <token>（可选）
  • 响应: { code, msg, data: { rows: any[], total?: number } }

• 删除设备

  • DELETE /deviceInfo/{id}

• 根据 ID 获取设备

  • GET /deviceInfo/{id}

• 新增设备

  • POST /deviceInfo，Body: JSON

• 更新设备

  • PUT /deviceInfo/{id}，Body: JSON

监测项管理（device.ts）

• 列表 GET /monitoringItem
• 删除 DELETE /monitoringItem/{id}
• 详情 GET /monitoringItem/{id}
• 新增 POST /monitoringItem
• 更新 PUT /monitoringItem/{id}

设备类型管理（device.ts）

• 列表 GET /deviceType
• 删除 DELETE /deviceType/{id}
• 详情 GET /deviceType/{id}
• 新增 POST /deviceType
• 更新 PUT /deviceType/{id}

设备数据（device.ts）

• 历史分页 POST /device/data/getHistoryDataPage
• 历史数据 POST /device/data/getHistoryData
• 设备列表 POST /device/data/listDevice
• 统计汇总 POST /device/data/getDeviceStats

告警（device.ts）

• 告警列表 POST /alarm/list
• 告警数据分页 POST /data/alarm/getAlarmDataPage
• 告警配置列表 POST /alarm/settings/list
• 删除配置 DELETE /alarm/settings/delete?id={id}
• 新增配置 POST /alarm/settings/create
• 更新配置 POST /alarm/settings/update

项目列表（project.ts）

• 列表 GET /project

AI 能力（ai.ts，流式 SSE/Fetch）

• createOllama3Stylized(text) → POST http://localhost:11434/api/chat
• createSparkStylized(text, token) → POST {origin}/spark/v1/chat/completions
• createSiliconFlowStylized(text, token) → POST {origin}/siliconflow/v1/chat/completions
• createKimiMoonshotStylized(text, token) → POST {origin}/moonshot/v1/chat/completions
• createDashScopeStylized(text, token) → POST {origin}/dashscope/compatible-mode/v1/chat/completions
• createSZJYStylized(text, token, identifier, baseUrl) → POST {baseUrl}/support/{identifier}/a

注: 实际响应结构与鉴权头由网关/后端服务决定。本库对 200/非 200 统一通过 request.ts 做提示与错误抛出。

项目维护规范

• 代码风格
  • TypeScript 严格模式（见 tsconfig.json）
  • 建议在业务仓库启用 ESLint + Prettier（如 @typescript-eslint, eslint-plugin-vue）
• 分支策略
  • main/release 稳定分支，feat/* 功能分支，fix/* 修复分支
• 提交信息
  • 建议采用 Conventional Commits：feat: ... fix: ... docs: ... refactor: ...
  • 使用 pnpm run release 自动生成版本与 tag
• CI/CD
  • 构建命令：pnpm run build
  • 可在 CI 中缓存 node_modules 与 pnpm/npm 缓存
• 代码评审
  • 提交 PR 前请本地通过构建与类型检查（vue-tsc --noEmit）

常见问题与故障排查（FAQ）

• 构建提示外部依赖未找到

  • 可能原因: UMD/ES 外部依赖未在宿主项目提供（如 vue、element-plus）。
  • 解决: 在宿主项目安装并在运行时提供这些依赖。

• 接口请求无响应或 401

  • 可能原因: VITE_BASE_URL 未配置、Token 未传入、跨域限制。
  • 解决: 在 .env 设置 VITE_BASE_URL，或在 API/组件调用时显式传入 baseUrl、token；检查网关 CORS 与代理。

• Loading 一直不消失

  • 可能原因: 手动抛错未进入响应拦截器的 hideLoading；或接口返回结构非预期。
  • 解决: 确保通过 request.ts 发起请求；排查 res.code 与后端约定，非 200 会弹错误并 reject。

• Element Plus 样式异常

  • 可能原因: 未引入基础样式。
  • 解决: 在宿主入口引入 element-plus/dist/index.css。

• 类型报错（vue-tsc）

  • 可能原因: TS 版本/类型定义不一致。
  • 解决: 使用与本库一致的 TS 版本（^5.2.2），并开启 Volar。

• 图表不显示或异常

  • 可能原因: 宿主未安装 echarts 或容器尺寸为 0。
  • 解决: 安装依赖，确保容器可见且有尺寸，或在可见时重新渲染。

参考资料与延伸阅读

• Vite 官方文档（库模式）: https://vitejs.dev/guide/build.html#library-mode
• Vue 3 官方文档（组合式 API）: https://vuejs.org/guide/introduction.html
• Element Plus 组件库: https://element-plus.org/
• Axios 官方文档: https://axios-http.com/
• ECharts 官方文档: https://echarts.apache.org/
• Conventional Commits: https://www.conventionalcommits.org/
• Volar（Vue Language Tools）: https://marketplace.visualstudio.com/items?itemName=Vue.volar