Thực thể & Quan hệ

VieLang IoT sử dụng mô hình thực thể (entity) linh hoạt để đại diện cho mọi đối tượng trong hệ thống IoT, từ thiết bị vật lý đến tổ chức kinh doanh.

Các loại thực thể

Tenant (Người thuê)

Tổ chức kinh doanh hoặc cá nhân sử dụng nền tảng. Mỗi tenant có:

Nhiều Tenant Admin quản lý
Nhiều Customer là khách hàng của họ
Toàn bộ thiết bị, tài sản, dashboard, rule chain riêng biệt

Customer (Khách hàng)

Tổ chức/cá nhân là khách hàng của Tenant. Customer có thể:

Xem dashboard được chia sẻ
Quản lý thiết bị được giao
Có nhiều User với quyền khác nhau

User (Người dùng)

Người sử dụng hệ thống với các vai trò:

SYS_ADMIN — Quản trị viên hệ thống
TENANT_ADMIN — Quản trị viên tenant
CUSTOMER_USER — Người dùng cuối

Device (Thiết bị)

Thực thể IoT cơ bản, thực hiện:

Gửi telemetry lên server
Nhận lệnh RPC từ server
Báo cáo trạng thái qua attributes
Trigger alarm khi vượt ngưỡng

Asset (Tài sản)

Thực thể trừu tượng đại diện cho:

Khu vực địa lý (nhà máy, tòa nhà, phòng)
Thiết bị nhóm (dây chuyền sản xuất)
Khái niệm kinh doanh (đơn hàng, dự án)

Asset không kết nối trực tiếp với phần cứng nhưng có thể liên kết với nhiều Device.

Entity View

Chia sẻ một phần dữ liệu của Device/Asset với Customer mà không lộ toàn bộ thông tin. Ví dụ: chỉ chia sẻ temperature mà không chia sẻ password, secret_key.

Alarm (Cảnh báo)

Xem Cảnh báo để biết chi tiết.

Dashboard

Xem Dashboard để biết chi tiết.

Rule Node / Rule Chain

Xem Rule Engine để biết chi tiết.

Profiles (Hồ sơ)

Tenant Profile

Cấu hình chung áp dụng cho nhiều tenant:

Giới hạn thiết bị, API calls
Quota lưu trữ dữ liệu
Tính năng được phép sử dụng

Device Profile

Cấu hình nhóm thiết bị cùng loại:

Default rule chain — Rule chain xử lý dữ liệu mặc định
Transport type — MQTT, HTTP, CoAP, LwM2M, SNMP
Alarm rules — Điều kiện tự động tạo alarm
Firmware — OTA update configuration

Asset Profile

Cấu hình cho nhóm tài sản cùng loại — tương tự Device Profile nhưng dành cho Asset.

Quan hệ (Relations)

Quan hệ là kết nối có hướng giữa hai thực thể, mô phỏng thế giới thực.

Cấu trúc quan hệ

Từ (From) → [RelationType] → Đến (To)

Ví dụ:

Building A  → [Contains] → Floor 1
Floor 1     → [Contains] → Room 101
Room 101    → [Contains] → Sensor-Temperature-01
Room 101    → [Contains] → Sensor-Humidity-01

Ví dụ thực tế: Nhà máy thông minh

Nhà máy HCM  → [Contains]  → Dây chuyền 1
Nhà máy HCM  → [Contains]  → Dây chuyền 2
Dây chuyền 1 → [Contains]  → Robot Hàn-01
Dây chuyền 1 → [Contains]  → Băng tải-01
Dây chuyền 1 → [ManagedBy] → Kỹ sư Nguyễn

Quản lý quan hệ qua API

Tạo quan hệ:

POST /api/relation
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "from": { "id": "ASSET_ID", "entityType": "ASSET" },
  "type": "Contains",
  "to":   { "id": "DEVICE_ID", "entityType": "DEVICE" }
}

Lấy danh sách thực thể liên quan:

GET /api/relations/info?fromId=ASSET_ID&fromType=ASSET&relationType=Contains
Authorization: Bearer {JWT}

Lấy tất cả relations của một thực thể:

GET /api/relations?fromId=ASSET_ID&fromType=ASSET
Authorization: Bearer {JWT}

Entity ID Format

Mỗi thực thể có ID dạng:

{
  "id": "784f394c-42b6-11ea-b77f-2e728ce88125",
  "entityType": "DEVICE"
}

entityType có thể là: TENANT, CUSTOMER, USER, DEVICE, ASSET, ALARM, DASHBOARD, RULE_CHAIN, ENTITY_VIEW.