temporary storage 7/9/2026 19:41

docs/ARCHITECTURE.md

@@ -8,34 +8,41 @@ về output** (path/vận tốc), đồng thời vẫn dùng global path/costmap
 
 ## 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.
+- `RecoveryBehavior` (interface, template-method): API non-virtual `configure`/`start`/`update`/
+  `cancel`; plugin chỉ triển khai hook `onConfigure`/`onStart(goal)`/`onUpdate(dt)`.
+- `RecoveryContext`: gói con trỏ ngữ cảnh (tf/costmap/global_path) truyền một lần qua `configure`.
+- `RecoveryGoal`: mục tiêu RUNTIME mỗi lượt (angle/distance/target_pose/params).
+- `RecoveryResult` / `RecoveryStatus` / `RecoveryOutputType`: hợp đồng output hợp nhất 3 họ +
+  rich feedback (`progress`/`remaining`/`elapsed`/`message`), thêm trạng thái `kCancelled`.
 - 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.
+  - `ClearCostmapRecovery`: clear layer costmap theo tên, one-shot no-output.
+  - `RotateRecovery`: quay tới `goal.angle` (rad); sinh `Twist.angular.z` mỗi cycle.
+  - `BackUpRecovery`: lùi tới `goal.distance` (m); sinh `Twist.linear.x < 0` mỗi cycle.
   - `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
+configure(name, ctx)          // 1 lần: cache ctx, đọc config chung, onConfigure()
         │
-        ├── one-shot (họ A/B):  runBehavior() ──────────────► RecoveryResult{status, path|none}
+start(goal)                   // mỗi lượt: chốt mục tiêu runtime, onStart()
         │
-        └── per-cycle (họ C):   loop { computeCommand(dt) } ─► RecoveryResult{status, velocity}
-                                (caller publish command mỗi cycle tới khi status != kRunning)
+        ├── one-shot (họ A/B):  update(dt) 1 lần ─────────► RecoveryResult{status, path|none, msg}
+        │
+        └── per-cycle (họ C):   loop { update(dt) } ──────► RecoveryResult{status, velocity,
+                                (tới khi status != kRunning)             progress, remaining}
 ```
 
 ## 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.
+- Template-method: base xử lý guard vòng đời (configure→start→update), `dt<=0`, `timeout`, đo
+  `elapsed`, và `cancel` một chỗ; plugin không lặp lại các guard này.
+- Mục tiêu là RUNTIME qua `RecoveryGoal` (không cố định trong config): cùng plugin phục vụ nhiều
+  yêu cầu góc/khoảng khác nhau. Field = 0 → dùng default plugin đọc ở `onConfigure()`.
+- `onUpdate(dt)` lấy pose robot từ costmap/tf bên trong; không truyền pose qua tham số.
+- Sau `cancel()`, base tự trả stop output (Twist 0) + `kCancelled`.
+- Param chung duy nhất còn lại là `timeout` (s, 0 = không giới hạn), base đọc trong `configure()`
+  từ `~/<name>/timeout`; giá trị `NaN/Inf/<0` bị thay bằng 0. Param RIÊNG của plugin đọc trong
+  `onConfigure()`.
 - 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.