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.

docs/PLUGIN_GUIDE.md

@@ -0,0 +1,78 @@
+# Hướng Dẫn Viết Plugin recovery_core
+
+Package hiện có 4 plugin mẫu dưới `plugins/`:
+- `clear_costmap_recovery` — nhóm B, one-shot, no output.
+- `rotate_recovery` — nhóm C, per-cycle velocity.
+- `back_up_recovery` — nhóm C, per-cycle velocity.
+- `regen_path_recovery` — nhóm A, path output.
+
+## Bước chung
+
+1. Kế thừa `recovery_core::RecoveryBehavior`.
+2. Override `initialize()` — đọc param riêng qua `robot::NodeHandle("~/" + name)`, cache
+   tf/global_path/costmap.
+3. Override method theo họ (xem dưới) + `status()`.
+4. Thêm factory `static Ptr create()` **không tham số** + `BOOST_DLL_ALIAS(...)`.
+
+## Override theo họ
+
+| Họ | Override | Trả về |
+|----|----------|--------|
+| A. path | `runBehavior()` | `RecoveryResult::PathOut(path, kSucceeded)` |
+| B. none | `runBehavior()` | `RecoveryResult::Succeeded()` / `Failed()` |
+| C. velocity | `computeCommand(dt)` | `RecoveryResult::Velocity(twist, kRunning|kSucceeded)` |
+
+## Export bằng Boost.DLL (bắt buộc cho plugin)
+
+```cpp
+#include <recovery_core/recovery_behavior.h>
+#include <boost/dll/alias.hpp>
+
+namespace recovery_plugins {
+class SpinRecovery : public recovery_core::RecoveryBehavior {
+ public:
+  static recovery_core::RecoveryBehavior::Ptr create() {
+    return std::make_shared<SpinRecovery>();
+  }
+  // override initialize()/computeCommand()/runBehavior()/status()...
+};
+}  // namespace recovery_plugins
+
+// alias = `type` dùng trong YAML recovery_behaviors.
+BOOST_DLL_ALIAS(recovery_plugins::SpinRecovery::create, spin_recovery)
+```
+
+## Nạp phía loader (adapter/caller — không nằm trong recovery_core)
+
+```cpp
+#include <boost/dll/import.hpp>
+auto loader = boost::dll::import_alias<recovery_core::RecoveryBehavior::Ptr()>(
+    path_so, /*symbol=*/type, boost::dll::load_mode::append_decorations);
+recovery_core::RecoveryBehavior::Ptr behavior = loader();
+behavior->initialize(name, tf, global_path, global_costmap, local_costmap);
+```
+
+Lưu ý: adapter/test phải giữ handle `.so` sống lâu hơn object plugin. Nếu library bị unload trong
+khi object plugin còn tồn tại, virtual call qua vtable của plugin có thể crash.
+
+## CMake cho plugin
+
+- `find_package(Boost REQUIRED COMPONENTS system filesystem)`
+- link `${Boost_LIBRARIES}`, `${CMAKE_DL_LIBS}`, `recovery_core`
+- `set_target_properties(<plugin> PROPERTIES POSITION_INDEPENDENT_CODE ON)`
+- build shared library, tên library + symbol khớp `type`; install `.so` nơi loader tìm.
+
+## Test plugin
+
+```bash
+catkin_make --pkg recovery_core
+./devel/lib/recovery_core/recovery_core_plugin_loader_test
+```
+
+Standalone:
+
+```bash
+cmake -S src/AMR_T800/pnkx_nav_core/src/Navigations/Libraries/recovery_core -B /tmp/recovery_core_phase3_build
+make -C /tmp/recovery_core_phase3_build -j4
+/tmp/recovery_core_phase3_build/test/recovery_core_plugin_loader_test
+```

docs/SAFETY.md

@@ -0,0 +1,30 @@
+# An Toàn — recovery_core
+
+> Cảnh báo an toàn khi dùng interface này. Đọc trước khi triển khai plugin họ vận tốc.
+
+## recovery_core KHÔNG đảm bảo
+
+- **Không collision-check tự động.** Interface không kiểm tra va chạm khi sinh vận tốc
+  (backup/spin) hay khi tạo path. Việc tránh va chạm là trách nhiệm của **plugin** (dùng
+  costmap được cấp qua `initialize`) hoặc của **caller**.
+- **Không quản lý vòng lặp thời gian thực.** Caller chịu trách nhiệm gọi `computeCommand(dt)`
+  đúng nhịp và publish command.
+- **Không đảm bảo frame/đơn vị.** Pose lấy từ costmap/tf phải đúng frame; đơn vị phải nhất quán
+  (m, rad, s, m/s, rad/s).
+- **Default per-cycle fail an toàn.** Behavior không override `computeCommand(dt)` sẽ nhận
+  `RecoveryResult::Failed()` thay vì velocity mặc định.
+
+## Nguyên tắc cho plugin
+
+- Guard `initialized_` và costmap/tf null trước khi thao tác; fail an toàn -> `RecoveryResult::Failed()`.
+- Guard `dt <= 0`, `NaN`, `Inf` trước khi tính velocity.
+- Với họ vận tốc: khi không chắc an toàn, trả **stop command** (Twist 0), không trả vận tốc mù.
+- Kiểm tra NaN/Inf của pose/vận tốc trước khi xuất command.
+- Tôn trọng giới hạn vận tốc/gia tốc của robot (đọc qua param).
+- `BackUpRecovery` có param `require_costmap` để bắt buộc có local costmap trước khi xuất
+  vận tốc lùi. Adapter production vẫn nên có safety gate/collision check riêng trước publish.
+
+## Trách nhiệm caller/adapter
+
+- Đảm bảo ngữ cảnh cho phép recovery (vd: đã dừng planner, vùng xung quanh đủ an toàn).
+- Áp timeout/giám sát ngoài để tránh recovery chạy vô hạn.