# 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.