Initial commit

2026-07-03 16:37:12 +07:00
commit 63b8c1ea8b
1931 changed files with 640587 additions and 0 deletions
--- a/docs/MapEditor/README.md
+++ b/docs/MapEditor/README.md
@@ -0,0 +1,303 @@
+# MapEditor Documentation / Tài liệu MapEditor
+
+## 📋 Overview / Tổng quan
+
+**MapEditor** là shared library cung cấp công cụ web-based để tạo, chỉnh sửa và quản lý bản đồ nhà máy theo chuẩn VDMA LIF (Layout Interchange Format). Module này được sử dụng bởi **FleetManager** để định nghĩa không gian hoạt động của robot AMR.
+
+## 🎯 Problem & Solution / Vấn đề & Giải pháp
+
+### 🔴 Challenges / Thách thức
+
+**Trong môi trường nhà máy thực tế**:
+- Bản đồ nhà máy phức tạp với hàng trăm điểm (stations, nodes, edges)
+- Cần import/export data từ nhiều nguồn khác nhau (CAD tools, other fleet systems)
+- Operators không phải programmers, cần giao diện trực quan
+- Phải tuân thủ chuẩn VDMA LIF để tích hợp với hệ thống khác
+- Database cần normalized schema để query hiệu quả (không lưu JSON blob)
+- PathFinding để validate routes và generate VDA 5050 orders
+- Multi-map support cho nhiều tầng, nhiều khu vực
+
+### ✅ MapEditor Solution / Giải pháp MapEditor
+
+**Visual Editor**: Blazor WASM + SVG canvas
+- Vẽ và chỉnh sửa map objects trực quan (drag, drop, resize)
+- Pan, zoom, layer management
+- Real-time validation với visual feedback
+
+**VDMA LIF Standard**: Import/export JSON format
+- Tuân thủ VDMA 40499-1 và 40499-2 specifications
+- Interoperability với CAD tools và other fleet systems
+- Complete map data: stations, edges, zones, vehicle types
+
+**Normalized Database**: PostgreSQL với relational schema
+- Separate tables cho Maps, Stations, InteractionNodes, Edges, Actions
+- Foreign key constraints đảm bảo data integrity
+- Efficient queries (find all charging stations, edges by speed limit)
+- No JSON blob storage (except for complex nested data như trajectory)
+
+**PathFinding Integration**: A* algorithm
+- Validate route existence trước khi dispatch missions
+- Calculate shortest/fastest paths
+- Support bidirectional và unidirectional edges
+- Consider vehicle type compatibility
+
+**VDA 5050 Integration**: Generate Order messages
+- Convert map data (stations, edges) thành VDA 5050 nodes và edges
+- Include actions từ stations vào order
+- Apply vehicle type filtering
+
+### 🎪 Use Cases / Trường hợp Sử dụng
+
+**Initial Setup**:
+- Import VDMA LIF JSON từ AutoCAD hoặc design tool
+- Visual editing để adjust positions, thêm bớt elements
+- Define stations (pickup, dropoff, charging, parking)
+- Configure edges (paths, speed limits, directions)
+- Define zones (restricted areas, slow-speed zones)
+- Set up vehicle types (dimensions, envelopes)
+
+**Operations** (FleetManager):
+- Query database để tạo VDA 5050 Orders cho robots
+- PathFinding service validate routes trước khi dispatch
+- Operators view map trên dashboard với real-time robot positions
+- Export VDMA LIF để backup hoặc share với other systems
+
+**Maintenance**:
+- Update map khi factory layout thay đổi
+- Add/remove stations khi production changes
+- Adjust edge configurations (speed limits, orientations)
+- Manage multiple map versions (version control)
+
+## 🏗️ System Architecture / Kiến trúc Hệ thống
+
+### Component Overview / Tổng quan Thành phần
+
+```mermaid
+graph TB
+    subgraph Browser["🌐 Browser - Blazor WASM"]
+        UI[MapEditor UI<br/>Map list, toolbox<br/>Property inspector]
+        Canvas[SVG Canvas<br/>Visual rendering<br/>Interactive editing]
+        ImportExport[Import/Export UI<br/>File upload/download<br/>Format validation]
+    end
+
+    subgraph Server["🖥️ Server - ASP.NET Core API"]
+        MapAPI[Map Management API<br/>CRUD operations<br/>Validation endpoints]
+
+        Parser[VDMA LIF Parser<br/>JSON ↔ Domain Models<br/>Schema validation]
+
+        PathFinder[PathFinding Service<br/>A* algorithm<br/>Route validation<br/>Cost calculation]
+
+        VDA5050Gen[VDA 5050 Generator<br/>Map → Order nodes<br/>Map → Order edges<br/>Action mapping]
+
+        Validator[Map Validator<br/>Connectivity check<br/>Reference integrity<br/>Geometric validation]
+    end
+
+    subgraph Database["💾 PostgreSQL Database"]
+        direction TB
+        Maps[(Maps<br/>Layout metadata)]
+        Stations[(Stations<br/>Physical locations)]
+        INodes[(InteractionNodes<br/>Approach points)]
+        Edges[(Edges<br/>Navigation paths)]
+        Actions[(Actions<br/>Robot behaviors)]
+        Zones[(Zones<br/>Special areas)]
+        VTypes[(VehicleTypes<br/>Robot specs)]
+    end
+
+    UI --> Canvas
+    UI --> ImportExport
+    Canvas -->|REST API| MapAPI
+    ImportExport -->|Upload JSON| Parser
+
+    MapAPI <--> Parser
+    MapAPI <--> PathFinder
+    MapAPI <--> VDA5050Gen
+    MapAPI <--> Validator
+
+    MapAPI <--> Maps
+    MapAPI <--> Stations
+    MapAPI <--> INodes
+    MapAPI <--> Edges
+    MapAPI <--> Actions
+    MapAPI <--> Zones
+    MapAPI <--> VTypes
+
+    PathFinder --> Stations
+    PathFinder --> Edges
+
+    VDA5050Gen --> Stations
+    VDA5050Gen --> INodes
+    VDA5050Gen --> Edges
+    VDA5050Gen --> Actions
+
+    style Browser fill:#e6f3ff
+    style Server fill:#fff0e6
+    style Database fill:#e6ffe6
+```
+
+### Data Flow / Luồng Dữ liệu
+
+**Import Flow** (VDMA LIF JSON → Database):
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Parser
+    participant Validator
+    participant DB
+
+    User->>UI: Upload VDMA LIF JSON
+    UI->>Parser: Parse JSON
+    Parser->>Parser: Deserialize to models
+    Parser->>Validator: Validate structure
+
+    alt Invalid format
+        Validator-->>UI: Return errors
+        UI-->>User: Show validation errors
+    else Valid format
+        Validator->>DB: Begin transaction
+        Validator->>DB: Insert Map entity
+        Validator->>DB: Insert Stations
+        Validator->>DB: Insert InteractionNodes
+        Validator->>DB: Insert Edges
+        Validator->>DB: Insert Actions
+        Validator->>DB: Insert Zones
+        Validator->>DB: Insert VehicleTypes
+        Validator->>DB: Commit transaction
+        DB-->>UI: Return Map ID
+        UI-->>User: Show success, open editor
+    end
+```
+
+**Export Flow** (Database → VDMA LIF JSON):
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant MapAPI
+    participant DB
+    participant Parser
+
+    User->>UI: Click Export Map
+    UI->>MapAPI: GET /api/maps/{id}/export
+    MapAPI->>DB: Load Map + related entities
+    DB-->>MapAPI: Map, Stations, Nodes, Edges, etc.
+    MapAPI->>Parser: Convert to VDMA LIF models
+    Parser->>Parser: Build JSON structure
+    Parser->>Parser: Serialize with camelCase
+    Parser-->>UI: VDMA LIF JSON string
+    UI->>User: Download file
+```
+
+**Order Generation Flow** (Map → VDA 5050 Order):
+```mermaid
+sequenceDiagram
+    participant FleetMgr as FleetManager
+    participant PathFinder
+    participant Generator as VDA5050 Generator
+    participant DB
+
+    FleetMgr->>PathFinder: FindPath(startStation, endStation)
+    PathFinder->>DB: Load Stations & Edges
+    DB-->>PathFinder: Station list, Edge list
+    PathFinder->>PathFinder: Run A* algorithm
+    PathFinder-->>FleetMgr: Route (station IDs, edge IDs)
+
+    FleetMgr->>Generator: GenerateOrder(route, vehicleType)
+    Generator->>DB: Load InteractionNodes for stations
+    Generator->>DB: Load Actions for nodes
+    DB-->>Generator: Nodes + Actions
+    Generator->>Generator: Map to VDA 5050 format
+    Generator-->>FleetMgr: VDA 5050 Order message
+    FleetMgr->>FleetMgr: Send Order to robot via MQTT
+```
+
+## 📚 Cấu trúc Tài liệu / Documentation Structure
+
+Tài liệu MapEditor được tổ chức thành các module riêng biệt để dễ dàng tra cứu và bảo trì:
+
+```
+docs/MapEditor/
+├── README.md                    # File này - Tổng quan MapEditor
+├── VDMA_LIF_Standard.md         # Chuẩn VDMA LIF
+├── Database_Design.md            # Thiết kế Database
+├── SVG_Canvas.md                # Kiến trúc Canvas SVG
+├── PathFinding.md               # Kiến trúc PathFinding
+├── ImportExport.md              # Quy trình Import/Export
+├── VDA5050_Integration.md       # Tích hợp VDA 5050
+└── Design_Rationale.md          # Lý do Thiết kế
+```
+
+## 📐 [VDMA LIF Standard](VDMA_LIF_Standard.md) - Chuẩn VDMA LIF
+
+VDMA LIF (Layout Interchange Format) là chuẩn quốc tế để mô tả factory layout cho AGV/AMR systems.
+
+📖 **[Xem chi tiết →](VDMA_LIF_Standard.md)**
+
+## 🗄️ [Database Design](Database_Design.md) - Thiết kế Database
+
+MapEditor sử dụng normalized relational schema thay vì JSON blob để đảm bảo query flexibility và data integrity.
+
+📖 **[Xem chi tiết →](Database_Design.md)**
+
+## 🎨 [SVG Canvas Architecture](SVG_Canvas.md) - Kiến trúc Canvas SVG
+
+MapEditor sử dụng SVG canvas với Blazor WASM để render và edit maps với interactive features.
+
+📖 **[Xem chi tiết →](SVG_Canvas.md)**
+
+## 🔍 [PathFinding Architecture](PathFinding.md) - Kiến trúc Tìm đường
+
+MapEditor tích hợp A* algorithm để tính toán routes giữa các stations trên map.
+
+📖 **[Xem chi tiết →](PathFinding.md)**
+
+## 🔄 [Import/Export Workflow](ImportExport.md) - Quy trình Import/Export
+
+MapEditor hỗ trợ import và export VDMA LIF JSON format với validation và transaction safety.
+
+📖 **[Xem chi tiết →](ImportExport.md)**
+
+## 🔗 [VDA 5050 Integration](VDA5050_Integration.md) - Tích hợp VDA 5050
+
+MapEditor convert map data thành VDA 5050 Order messages để gửi đến robot.
+
+📖 **[Xem chi tiết →](VDA5050_Integration.md)**
+
+## 🎯 [Design Rationale](Design_Rationale.md) - Lý do Thiết kế
+
+Giải thích các quyết định thiết kế quan trọng: VDMA LIF, Blazor WASM + SVG, normalized database, PathFinding.
+
+📖 **[Xem chi tiết →](Design_Rationale.md)**
+
+## 📖 Related Documents / Tài liệu Liên quan
+
+- [Architecture Overview](../architecture/README.md) - System architecture overview
+- [FleetManager Documentation](../fleetmanager/README.md) - Usage context and integration
+- [VDA 5050 Implementation](../vda5050/README.md) - Order message generation
+- [Development Guide](../development/README.md) - Implementation guidelines
+- [ScriptEngine Documentation](../scriptengine/README.md) - Scripting integration
+
+## 🌐 External References / Tham khảo Ngoài
+
+**Standards**:
+- [VDMA 40499-1](https://www.vdma.org/) - Common Definitions for LIF
+- [VDMA 40499-2](https://www.vdma.org/) - Layout Interchange Format Specification
+- [VDA 5050](https://www.vda.de/) - Communication Interface for AMR Systems
+- [GitHub: VDMA LIF](https://github.com/continua-systems/vdma-lif) - Reference implementation
+
+**Algorithms**:
+- [A* Search Algorithm](https://en.wikipedia.org/wiki/A*_search_algorithm) - PathFinding
+- [NURBS](https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline) - Trajectory representation
+
+**Technologies**:
+- [Blazor WebAssembly](https://dotnet.microsoft.com/apps/aspnet/web-apps/blazor) - Client framework
+- [SVG Specification](https://www.w3.org/TR/SVG2/) - Vector graphics format
+- [PostgreSQL](https://www.postgresql.org/) - Database system
+- [Entity Framework Core](https://learn.microsoft.com/en-us/ef/core/) - ORM
+
+---
+
+**Status**: Architecture & Design Document (No Implementation Code)
+**Focus**: Concepts, Architecture, Design Rationale, Mermaid Diagrams
+**Last Updated**: 2025-11-13
+**Version**: 2.1 (Modular documentation structure)