BQP/docs/MapEditor/README.md

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

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):

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):

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):

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 - 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 →

🗄️ Database Design - 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 →

🎨 SVG Canvas Architecture - 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 →

🔍 PathFinding Architecture - 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 →

🔄 Import/Export Workflow - 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 →

🔗 VDA 5050 Integration - Tích hợp VDA 5050

MapEditor convert map data thành VDA 5050 Order messages để gửi đến robot.

📖 Xem chi tiết →

🎯 Design Rationale - 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 →

📖 Related Documents / Tài liệu Liên quan

• Architecture Overview - System architecture overview
• FleetManager Documentation - Usage context and integration
• VDA 5050 Implementation - Order message generation
• Development Guide - Implementation guidelines
• ScriptEngine Documentation - Scripting integration

🌐 External References / Tham khảo Ngoài

Standards:

• VDMA 40499-1 - Common Definitions for LIF
• VDMA 40499-2 - Layout Interchange Format Specification
• VDA 5050 - Communication Interface for AMR Systems
• GitHub: VDMA LIF - Reference implementation

Algorithms:

• A* Search Algorithm - PathFinding
• NURBS - Trajectory representation

Technologies:

• Blazor WebAssembly - Client framework
• SVG Specification - Vector graphics format
• PostgreSQL - Database system
• Entity Framework 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)