temporary storage

docs/ARCHITECTURE.md

@@ -0,0 +1,41 @@
+# Kiến Trúc recovery_core
+
+## Vị trí trong stack
+
+`recovery_core` nằm ở tầng `Navigations/Libraries`, cạnh `robot_clear_costmap_recovery`. Nó
+giữ vai trò interface tương tự `robot_nav_core::RecoveryBehavior` cho các recovery cần **trả
+về output** (path/vận tốc), đồng thời vẫn dùng global path/costmap/tf như bản gốc.
+
+## Các thành phần
+
+- `RecoveryBehavior` (interface): `initialize` (mirror nav_core) + `runBehavior` (one-shot) +
+  `computeCommand` (per-cycle) + `status`.
+- `RecoveryResult` / `RecoveryStatus` / `RecoveryOutputType`: hợp đồng output hợp nhất 3 họ.
+- `RecoveryConfig`: param chung (control_frequency, timeout) + validate + đọc từ NodeHandle.
+- Plugin mẫu:
+  - `ClearCostmapRecovery`: clear layer costmap theo tên, trả no-output status.
+  - `RotateRecovery`: sinh `Twist.angular.z` theo chu kỳ tới khi đủ góc.
+  - `BackUpRecovery`: sinh `Twist.linear.x < 0` theo chu kỳ tới khi đủ khoảng lùi.
+  - `RegenPathRecovery`: trả lại `robot_nav_msgs::Path` từ `global_path` hiện tại.
+
+## Luồng runtime
+
+```
+initialize(name, tf, global_path, global, local)   // 1 lần, đọc param qua NodeHandle
+        │
+        ├── one-shot (họ A/B):  runBehavior() ──────────────► RecoveryResult{status, path|none}
+        │
+        └── per-cycle (họ C):   loop { computeCommand(dt) } ─► RecoveryResult{status, velocity}
+                                (caller publish command mỗi cycle tới khi status != kRunning)
+```
+
+## Ghi chú thiết kế
+
+- `computeCommand(dt)` lấy pose robot từ costmap/tf bên trong (nhất quán mirror nav_core),
+  không truyền pose qua tham số.
+- Default `RecoveryBehavior::computeCommand(dt)` trả `RecoveryResult::Failed()` để họ A/B không
+  vô tình sinh command mù.
+- `RecoveryConfig::validate()` từ chối `NaN/Inf`, `control_frequency <= 0`, `timeout < 0`.
+- `RecoveryConfig::fromNodeHandle()` đọc param chung và thay giá trị invalid bằng default an toàn.
+- Interface KHÔNG include Boost.DLL; export/import là việc của plugin/loader.
+- Plugin mẫu có dùng Boost.DLL alias, nhưng core contract vẫn không biết loader/adaptor.