# recovery_core

Interface (base class) cho các hành vi **recovery** của navigation stack ROS-like T800.

## Phạm vi

- Là **package định nghĩa interface**, mô phỏng `robot_nav_core::RecoveryBehavior` nhưng mở
  rộng thêm `global_path`: `initialize(name, tf, global_path, global_costmap, local_costmap)`;
  đồng thời **tổng quát hoá output** để bao 3 họ recovery.
- **Không chạy roscpp/ROS master thật**; dùng bình thường lớp ROS-like `robot_*`
  (`robot_costmap_2d`, `tf3`, `robot_cpp`, `robot_time`, `robot_geometry_msgs`,
  `robot_nav_msgs`).
- Core interface không publish trực tiếp. Package hiện có thêm các plugin mẫu build thành
  `.so` riêng và nạp qua **Boost.DLL** để kiểm chứng contract end-to-end.

## Vòng đời hướng-goal

```cpp
behavior->configure(name, ctx);          // 1 lần: ctx = {tf, global_path, global/local costmap}
RecoveryGoal goal; goal.angle = 1.57;    // mục tiêu RUNTIME: "quay 90 độ ngay lượt này"
RecoveryResult r = behavior->start(goal);
while (r.status == RecoveryStatus::kRunning)
  r = behavior->update();                // publish r.command; đọc r.progress / r.remaining / r.message
```

API công khai `configure/start/update/cancel` là non-virtual (base lo guard vòng đời/cancel);
plugin chỉ override hook `onConfigure()/onStart(goal)/onUpdate()`.

## Ba họ recovery

| Họ | Ví dụ | Output | Hook chính |
|----|-------|--------|-----------|
| A | regen path (đường thoát) | `robot_nav_msgs::Path` | `onUpdate()` one-shot |
| B | clear costmap | không có (chỉ status) | `onUpdate()` one-shot |
| C | rotation / backup | `robot_geometry_msgs::Twist` mỗi cycle | `onStart(goal)` + `onUpdate()` |

Cả 3 chia sẻ một `RecoveryResult` hợp nhất mang cờ `output_type` + rich feedback
(`progress`/`remaining`/`elapsed`/`message`).

## Cấu trúc

```
include/recovery_core/   recovery_types.h, recovery_behavior.h
src/                     phần chung của contract (types + base lifecycle)
plugins/                 clear_costmap, rotate, backup, regen_path plugin mẫu
test/                    contract test + Boost.DLL loader test
examples/                minimal_recovery.cpp
docs/                    ARCHITECTURE.md, PLUGIN_GUIDE.md, SAFETY.md
```

## Build

Hỗ trợ **catkin** và **standalone CMake** (như `robot_clear_costmap_recovery`).

```bash
# catkin (trong workspace)
catkin_make --pkg recovery_core

# standalone
mkdir build && cd build && cmake .. && make
```

## Trạng thái

- [x] Phase 1 — khung package (interface + stub, build lib rỗng).
- [x] Phase 2 — triển khai phần chung (types/config/validate + default computeCommand).
- [x] Phase 3 — plugin mẫu cho 3 họ + export/import Boost.DLL.

Xem [PLAN.md](PLAN.md) để biết chi tiết từng phase.