ScriptEngine Documentation / Tài liệu ScriptEngine
📋 Overview / Tổng quan
ScriptEngine là shared library cho phép viết và thực thi C# scripts trực tiếp trên web mà không cần rebuild ứng dụng. Module này được dùng bởi RobotApp và FleetManager để mở rộng chức năng linh hoạt.
🎯 Vấn đề Cần Giải quyết
Thách thức: Trong môi trường sản xuất thực tế:
- Mỗi robot có hành vi riêng (custom actions, sensor processing)
- Mỗi nhà máy có quy trình khác nhau (business logic)
- Cần tích hợp với thiết bị bên thứ 3 (conveyors, elevators, stations)
- Không thể rebuild/redeploy app mỗi lần thay đổi logic
Giải pháp ScriptEngine:
- ✅ Viết C# code trực tiếp trên web browser
- ✅ IntelliSense, diagnostics, refactoring (Monaco Editor + Roslyn)
- ✅ Multi-file support (organize code như C# project)
- ✅ Variables, Tasks (periodic), Missions (workflows)
- ✅ Extension APIs (mỗi app expose custom functions)
- ✅ Real-time updates qua SignalR
🎪 Use Cases / Trường hợp Sử dụng
RobotApp:
- Custom VDA 5050 actions (pick, drop, scan, charge)
- Robot-specific behaviors (sensor calibration, custom navigation)
- Hardware integration (custom actuators, sensors)
FleetManager:
- Mission planning algorithms (optimize routes, load balancing)
- External system integration (HTTP APIs, MQTT, OPC UA)
- Business logic (station management, elevator control, conveyor sync)
- Custom analytics and reporting
🏗️ Architecture / Kiến trúc
System Overview
graph TB
subgraph Browser["🌐 Browser - Blazor WASM"]
Editor[Monaco Editor<br/>C# Code Editing<br/>Multi-file workspace]
Roslyn[Roslyn Analysis<br/>IntelliSense<br/>Diagnostics<br/>Hover info]
UI[UI Components<br/>Hierarchy Tree<br/>Tasks/Missions/Variables]
end
subgraph Server["🖥️ Server - .NET Runtime"]
Compiler[Script Compiler<br/>Merge files<br/>Analyze code<br/>Extract metadata]
SM[State Machine<br/>Idle → Building<br/>→ Ready → Running]
TaskMgr[Task Manager<br/>Timer-based execution<br/>1 TaskRunner per task]
MissionMgr[Mission Manager<br/>Workflow execution<br/>CancellationToken support<br/>Progress tracking]
VarMgr[Variable Manager<br/>ConcurrentDictionary<br/>Shared state]
ExtAPI[Extension APIs<br/>App-specific functions<br/>IScriptResource]
end
Editor -->|SignalR<br/>Save, Build| Compiler
Roslyn -.->|Analysis results| Editor
Compiler -->|Build trigger| SM
SM -->|Ready state| TaskMgr
SM -->|Ready state| MissionMgr
TaskMgr <-->|Read/Write| VarMgr
MissionMgr <-->|Read/Write| VarMgr
TaskMgr --> ExtAPI
MissionMgr --> ExtAPI
TaskMgr -.->|Status updates| UI
MissionMgr -.->|Progress updates| UI
VarMgr -.->|Value changes| UI
style Browser fill:#e6f3ff
style Server fill:#fff0e6
State Machine / Máy Trạng thái
ScriptEngine sử dụng state machine để quản lý lifecycle của Engine, Tasks và MissionInstances.
📖 Xem chi tiết về State Machine Architecture →
Tóm tắt:
- Engine State Machine: Quản lý trạng thái của ScriptEngine (Initializing → Idle → Building → Ready → Starting → Running → Stopping)
- Task State Machine: Quản lý trạng thái của mỗi Task (Idle → Running → Pausing → Paused → Resuming → Stopping → Stopped → Error)
- MissionInstance State Machine: Quản lý trạng thái của mỗi MissionInstance (Idle → Running → Pausing → Paused → Resuming → Canceling → Completed/Canceled/Error)
📚 Cấu trúc Tài liệu / Documentation Structure
Tài liệu ScriptEngine được tổ chức thành các module riêng biệt để dễ dàng tra cứu và bảo trì:
docs/ScriptEngine/
├── README.md # File này - Tổng quan ScriptEngine
├── StateMachine_Design.md # Kiến trúc State Machine (Task, Mission, Engine)
├── ScriptFiles.md # Quản lý File Script
├── Variables.md # Biến Toàn cục
├── Tasks.md # Nhiệm vụ Định kỳ
├── Missions.md # Nhiệm vụ Dài hạn
├── Compilation.md # Quá trình Biên dịch
├── ExtensionAPIs.md # API Mở rộng
├── BuiltInAPIs.md # API Tích hợp Sẵn
├── DataPersistence.md # Lưu trữ Dữ liệu & Backup/Restore
└── Security.md # Bảo mật & Giới hạn
📝 Core Concepts / Khái niệm Cốt lõi
1. Script Files - File Script
Scripts được tổ chức như C# project với multi-file support, file locking, và backup/restore.
2. Variables - Biến Toàn cục
Shared state được chia sẻ giữa tất cả scripts với thread-safe storage.
3. Tasks - Nhiệm vụ Định kỳ
Periodic execution với timer, phù hợp cho monitoring và automation đơn giản.
4. Missions - Nhiệm vụ Dài hạn
Long-running workflows với progress tracking, cancellable, và persist to database.
🔄 Script Compilation Process - Quá trình Biên dịch
ScriptEngine compile C# scripts sử dụng Roslyn để extract metadata và generate executable runners.
🔌 Extension APIs - API Mở rộng
Apps implement IScriptResource interface để expose custom APIs cho scripts (RobotApp và FleetManager).
📚 Built-in APIs - API Tích hợp Sẵn
Các APIs có sẵn trong tất cả scripts: Logger, Mission Management, Task Control.
💾 Data Persistence - Lưu trữ Dữ liệu
Mission instances và logs được lưu vào database. Backup và restore scripts với ZIP format.
⚠️ Security & Limitations - Bảo mật & Giới hạn
MetadataReference restrictions và thread safety considerations.
🎯 Design Rationale / Lý do Thiết kế
Tại sao C# Scripting?
| Lý do | Giải thích |
|---|---|
| Familiar syntax | Developers đã biết C# |
| Type safety | Strong typing giảm runtime errors |
| IntelliSense | Code completion, diagnostics |
| Roslyn power | Full language analysis |
| Async/await | Natural asynchronous programming |
Tại sao Monaco Editor + Roslyn trên WASM?
| Lý do | Giải thích |
|---|---|
| Client-side analysis | No server round-trip for IntelliSense |
| Fast feedback | Instant diagnostics while typing |
| VS Code experience | Professional IDE in browser |
| Offline capable | Can work without constant server connection |
Tại sao Tasks & Missions?
| Concept | Use Case |
|---|---|
| Tasks | Periodic monitoring, simple automation |
| Missions | Complex workflows, progress tracking, cancellable |
📖 Related Documents / Tài liệu Liên quan
- Architecture Overview - System architecture
- RobotApp Documentation - RobotApp usage
- FleetManager Documentation - FleetManager usage
- AI Collaboration Guide - For developers
Status: Design Document Last Updated: 2025-11-13 Version: 1.1 (Modular documentation structure)