temporary storage 7/9/2026 19:41

docs/PLUGIN_GUIDE.md

@@ -9,18 +9,38 @@ Package hiện có 4 plugin mẫu dưới `plugins/`:
 ## 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(...)`.
+2. Override hook `onConfigure()` (tuỳ chọn) — đọc param riêng qua `robot::NodeHandle("~/" + name)`;
+   ngữ cảnh tf/global_path/costmap lấy qua `ctx()`.
+3. Override `onStart(goal)` + `onUpdate(dt)` theo họ (xem dưới). KHÔNG override
+   `configure/start/update/cancel` — base đã lo guard vòng đời/timeout/cancel/elapsed.
+4. Thêm factory `static RecoveryBehaviorPtr create()` **không tham số** + `BOOST_DLL_ALIAS(...)`.
+
+## Vòng đời (goal-driven)
+
+```
+configure(name, ctx)      // 1 lần: cache ctx, đọc config chung, gọi onConfigure()
+        │
+start(goal)               // mỗi lượt: chốt mục tiêu RUNTIME (angle/distance/pose), gọi onStart()
+        │
+loop update(dt)           // mỗi cycle tới khi status != kRunning; base tick elapsed + guard
+        │
+[cancel()]                // update() kế tiếp -> stop output + kCancelled
+```
+
+`RecoveryGoal` là điểm mấu chốt: cùng plugin, mỗi lượt caller đặt `goal.angle` (rad) hay
+`goal.distance` (m) khác nhau; field = 0 nghĩa là dùng default đã cấu hình. Override thêm truyền
+qua `goal.params` (vd `goal.params["angular_speed"] = 0.8`).
 
 ## 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)` |
+| A. path | `onUpdate()` (one-shot) | `RecoveryResult::PathOut(path, kSucceeded)` |
+| B. none | `onUpdate()` (one-shot) | `RecoveryResult::Succeeded()` / `Failed()` |
+| C. velocity | `onStart()` chốt goal + `onUpdate(dt)` mỗi cycle | `RecoveryResult::Velocity(twist, kRunning\|kSucceeded)` |
+
+Mọi kết quả nên gắn feedback qua `.withProgress(progress, remaining)` và `.withMessage(...)` để
+caller giám sát tiến độ (progress ∈ [0,1], remaining theo rad/m).
 
 ## Export bằng Boost.DLL (bắt buộc cho plugin)
 
@@ -31,10 +51,11 @@ Package hiện có 4 plugin mẫu dưới `plugins/`:
 namespace recovery_plugins {
 class SpinRecovery : public recovery_core::RecoveryBehavior {
  public:
-  static recovery_core::RecoveryBehavior::Ptr create() {
+  static recovery_core::RecoveryBehavior::RecoveryBehaviorPtr create() {
     return std::make_shared<SpinRecovery>();
   }
-  // override initialize()/computeCommand()/runBehavior()/status()...
+ protected:
+  // override onConfigure()/onStart(goal)/onUpdate(dt)...
 };
 }  // namespace recovery_plugins
 
@@ -46,10 +67,21 @@ BOOST_DLL_ALIAS(recovery_plugins::SpinRecovery::create, spin_recovery)
 
 ```cpp
 #include <boost/dll/import.hpp>
-auto loader = boost::dll::import_alias<recovery_core::RecoveryBehavior::Ptr()>(
+auto loader = boost::dll::import_alias<recovery_core::RecoveryBehavior::RecoveryBehaviorPtr()>(
     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);
+recovery_core::RecoveryBehavior::RecoveryBehaviorPtr behavior = loader();
+
+recovery_core::RecoveryContext ctx;
+ctx.tf = tf; ctx.global_path = global_path;
+ctx.global_costmap = global_costmap; ctx.local_costmap = local_costmap;
+behavior->configure(name, ctx);
+
+recovery_core::RecoveryGoal goal;
+goal.angle = 1.57;                    // "quay 90 độ ngay lượt này"
+recovery_core::RecoveryResult r = behavior->start(goal);
+while (r.status == recovery_core::RecoveryStatus::kRunning) {
+  r = behavior->update(dt);          // publish r.command; đọc r.progress/r.remaining/r.message
+}
 ```
 
 Lưu ý: adapter/test phải giữ handle `.so` sống lâu hơn object plugin. Nếu library bị unload trong