Initial commit

2026-07-03 16:37:12 +07:00
commit 63b8c1ea8b
1931 changed files with 640587 additions and 0 deletions
--- a/docs/MapEditor/Database_Design.md
+++ b/docs/MapEditor/Database_Design.md
@@ -0,0 +1,152 @@
+# Database Design / Thiết kế Database
+
+## 📋 Overview / Tổng quan
+
+MapEditor sử dụng normalized relational schema để lưu trữ map data thay vì JSON blob.
+
+## 🎯 Design Philosophy / Triết lý Thiết kế
+
+### ❌ Anti-pattern (Not Used)
+
+```
+Maps table:
+  - id
+  - name
+  - vdma_lif_json TEXT  <-- Store entire JSON blob
+```
+
+**Problems với JSON blob approach**:
+- Cannot query specific elements
+- No foreign key constraints
+- Poor performance for complex queries
+- Cannot index nested data
+
+### ✅ Our Approach - Normalized Relational Schema
+
+**Benefits**:
+- Query any element directly
+- Foreign keys ensure data integrity
+- Efficient indexes
+- Easy to join với robot positions, orders, analytics
+
+## 📊 Entity Relationship Diagram
+
+```mermaid
+erDiagram
+    Maps ||--o{ Stations : contains
+    Maps ||--o{ Edges : contains
+    Maps ||--o{ Zones : contains
+    Maps ||--o{ VehicleTypes : defines
+
+    Stations ||--o{ InteractionNodes : has
+    Stations ||--o{ Edges : "start from"
+    Stations ||--o{ Edges : "end at"
+
+    InteractionNodes ||--o{ Actions : contains
+
+    Maps {
+        uuid id PK
+        string layoutId UK "VDMA LIF layoutId"
+        string layoutName
+        string layoutVersion
+        int layoutLevel "Floor number"
+        float referenceX "Origin X"
+        float referenceY "Origin Y"
+    }
+
+    Stations {
+        uuid id PK
+        uuid mapId FK
+        string stationId UK "VDMA LIF stationId"
+        string stationType
+        float positionX
+        float positionY
+        float positionTheta
+    }
+
+    InteractionNodes {
+        uuid id PK
+        uuid stationId FK
+        string interactionNodeId UK
+        float positionX
+        float positionY
+        float positionTheta
+        string vehicleTypeIds "JSON array"
+    }
+
+    Actions {
+        uuid id PK
+        uuid interactionNodeId FK
+        string actionType
+        string blockingType
+        string actionParameters "JSON"
+    }
+
+    Edges {
+        uuid id PK
+        uuid mapId FK
+        string edgeId UK
+        string startStationId FK
+        string endStationId FK
+        string trajectory "JSON NURBS"
+        float maxSpeed
+        boolean bidirectional
+    }
+
+    Zones {
+        uuid id PK
+        uuid mapId FK
+        string zoneId UK
+        string zoneType
+        string geometry "JSON polygon"
+    }
+
+    VehicleTypes {
+        uuid id PK
+        uuid mapId FK
+        string vehicleTypeId UK
+        float vehicleLength
+        float vehicleWidth
+    }
+```
+
+## 🔑 Key Design Decisions
+
+**1. Dual ID System**:
+- `id` (UUID): Database primary key
+- `{entity}Id` (String): VDMA LIF identifier, business key
+
+**2. Position Decomposition**:
+- Store as separate columns: `positionX`, `positionY`, `positionTheta`
+- Enable spatial queries và indexing
+
+**3. Trajectory as JSON**:
+- Store NURBS trajectory as JSON string
+- Complex structure, rarely queried independently
+
+**4. Vehicle Type IDs as JSON Array**:
+- Store vehicleTypeIds as JSON array
+- Typically small arrays, loaded together with edge/node
+
+**5. Actions Hierarchy**:
+- Actions belong to InteractionNodes (not Stations directly)
+- Follows VDMA LIF structure exactly
+
+## 📈 Indexes for Performance
+
+**Critical Indexes**:
+- Maps: layoutId (unique)
+- Stations: mapId, stationId, stationType, (positionX, positionY)
+- Edges: mapId, edgeId, startStationId, endStationId
+- InteractionNodes: stationId, interactionNodeId
+
+## 🔗 Related Documents / Tài liệu Liên quan
+
+- [MapEditor Overview](README.md) - Tổng quan MapEditor
+- [VDMA LIF Standard](VDMA_LIF_Standard.md) - Chuẩn VDMA LIF
+- [PathFinding](PathFinding.md) - Sử dụng database để pathfinding
+
+---
+
+**Last Updated**: 2025-11-13
+