Initial commit

docs/ScriptEngine/Missions.md

@@ -0,0 +1,97 @@
+# Missions / Nhiệm vụ Dài hạn
+
+## 📋 Overview / Tổng quan
+
+Missions là long-running workflows với progress tracking, phù hợp cho các nhiệm vụ phức tạp có thể cancel và track progress.
+
+**Lưu ý quan trọng**: 
+- `Mission` = method trong script với `[Mission]` attribute (không có state machine)
+- `MissionInstance` = instance được tạo từ Mission method khi gọi `CreateMission()` (có state machine)
+- Xem chi tiết về state machine trong [StateMachine_Design.md](StateMachine_Design.md)
+
+## 🔧 Cách sử dụng / Usage
+
+```csharp
+[Mission(TotalScore = 10)]
+public async IAsyncEnumerable<MissionStatus> PickAndPlace(
+    string pickLocation,
+    string placeLocation,
+    [EnumeratorCancellation] CancellationToken ct)
+{
+    yield return new MissionStatus { Score = 1, Message = "Moving to pick" };
+    await MoveTo(pickLocation);
+
+    yield return new MissionStatus { Score = 3, Message = "Picking item" };
+    await PerformPick();
+
+    yield return new MissionStatus { Score = 5, Message = "Moving to place" };
+    await MoveTo(placeLocation);
+
+    yield return new MissionStatus { Score = 8, Message = "Placing item" };
+    await PerformPlace();
+
+    yield return new MissionStatus { Score = 10, Message = "Completed" };
+}
+```
+
+## ⚙️ Đặc điểm / Features
+
+- **IAsyncEnumerable<MissionStatus>**: Return type để track progress
+- **CancellationToken support**: Có thể cancel mission
+- **Progress tracking**: Score/TotalScore để track tiến độ
+- **Per-instance MissionGlobals**: Isolated execution cho mỗi mission instance
+- **Persist to database**: Mission history được lưu vào database
+
+## 🎛️ Mission Attributes / Thuộc tính Mission
+
+- `[Mission(TotalScore = number)]`: Định nghĩa total score cho progress tracking
+
+## 📊 Mission Status / Trạng thái Mission
+
+**ScriptMissionState Enum** (tương ứng với state machine trong [StateMachine_Design.md](StateMachine_Design.md)):
+- `Idle` (0) - MissionInstance chưa được start
+- `Running` (1) - MissionInstance đang thực thi
+- `Canceling` (2) - MissionInstance đang được cancel
+- `Pausing` (3) - MissionInstance đang được pause
+- `Paused` (4) - MissionInstance đã bị pause
+- `Resuming` (5) - MissionInstance đang được resume
+- `Canceled` (6) - MissionInstance đã bị cancel
+- `Completed` (7) - MissionInstance đã hoàn thành thành công
+- `Error` (8) - MissionInstance gặp lỗi
+
+**Lưu ý**: 
+- `Mission` là method trong script với `[Mission]` attribute (không có state machine)
+- `MissionInstance` là instance được tạo từ Mission method khi gọi `CreateMission()` (có state machine)
+- State machine quản lý state của **MissionInstance**, không phải Mission
+- Terminal states (`Completed`, `Canceled`, `Error`) là final states - khi về các state này, MissionInstance sẽ:
+  1. Lưu trạng thái, log và score vào database
+  2. Dispose MissionInstance
+
+## 🔄 Mission Management APIs / API Quản lý Mission
+
+```csharp
+// Create mission
+Guid missionId = CreateMission("DeliverPackage",
+    fromLocation: "A1",
+    toLocation: "B2");
+
+// Cancel mission
+CancelMission(missionId);
+```
+
+## 💾 Data Persistence / Lưu trữ Dữ liệu
+
+Missions được persist vào database với MissionInstances và MissionLogs tables.
+
+## 🔗 Related Documents / Tài liệu Liên quan
+
+- [ScriptEngine Overview](README.md) - Tổng quan ScriptEngine
+- [Variables](Variables.md) - Missions có thể đọc/ghi variables
+- [Tasks](Tasks.md) - Tasks có thể tạo/cancel missions
+- [Data Persistence](DataPersistence.md) - Chi tiết về database storage
+- [Built-in APIs](BuiltInAPIs.md) - Mission management APIs
+
+---
+
+**Last Updated**: 2025-11-13
+