Feature: Order Updates, Events, Order Flows, Shipment And COD support

src/Order/Observers/OrderObserver.php

@@ -5,18 +5,32 @@ namespace Modules\Core\Order\Observers;
 use Lunar\Models\Order;
 use Modules\Core\Order\Events\OrderStatusUpdated;
 
+/**
+ * Generically dispatches OrderStatusUpdated for ANY write to `status`,
+ * regardless of what wrote it (Modules\Core\Order\Services\
+ * OrderStatusWriter, artisan tinker, a future API) — the general-purpose
+ * hook notifications listen to. OrderStatusWriter separately dispatches
+ * its own OrderStatusChanged (carrying $causeClass, which this event does
+ * not) for the audit trail — see Modules\Core\Order\Listeners\
+ * RecordStatusTransition.
+ *
+ * Does NOT try to generically watch Order::paid — an earlier design had
+ * this observer thread a "what caused this" value through a runtime
+ * $order->statusTransitionCause property, abandoned because
+ * Lunar\Models\Order's $guarded = [] means Eloquent tries to persist any
+ * property set that way as a real column. OrderStatusWriter::markPaid()
+ * dispatches OrderPaidChanged directly instead.
+ */
 class OrderObserver
 {
     public function updated(Order $order): void
     {
-        if (! $order->wasChanged('status')) {
-            return;
+        if ($order->wasChanged('status')) {
+            OrderStatusUpdated::dispatch(
+                $order,
+                $order->getOriginal('status'),
+                $order->status,
+            );
         }
-
-        OrderStatusUpdated::dispatch(
-            $order,
-            $order->getOriginal('status'),
-            $order->status,
-        );
     }
 }