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

src/Order/Events/OrderCompleted.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+
+/**
+ * The one terminal signal every notification/reporting concern that only
+ * cares about "this order is fully done" should listen to, regardless of
+ * which path actually got it there — dispatched by all four:
+ * Modules\Core\Order\Listeners\CompleteOrderOnPickedUp (store-pickup),
+ * Modules\Core\Order\Commands\CloseExpiredReturnWindows (carrier,
+ * automatic 14-day return-window expiry), or Modules\Core\Shipping\
+ * Extensions\OrderViewExtension's "Mark Completed" action (manual
+ * universal fallback, either branch).
+ */
+class OrderCompleted
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+    ) {}
+}

src/Order/Events/OrderDispatched.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+use Modules\Core\Shipping\Models\ShipmentInfo;
+
+/**
+ * Dispatched by either of the two paths that move a carrier order's
+ * `status` to 'dispatched' — Modules\Core\Order\Listeners\
+ * AdvanceFulfillmentOnCarrierCheckpoint (automatic, reacting to a real
+ * carrier checkpoint) or Modules\Core\Order\Services\
+ * OrderFulfillmentService::createShipmentAndDispatch() (staff-driven, via
+ * the single "Update Status" action). $shipmentInfo is nullable
+ * specifically because of that second path — populated with the
+ * triggering checkpoint when it's real, null when staff drove it
+ * manually. Mirrors OrderDelivered's {order, shipmentInfo} shape, just
+ * with the nullability this one event additionally needs.
+ */
+class OrderDispatched
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+        public readonly ?ShipmentInfo $shipmentInfo = null,
+    ) {}
+}

src/Order/Events/OrderPaidChanged.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+
+/**
+ * Dispatched by Modules\Core\Order\Services\OrderStatusWriter::markPaid()
+ * whenever Order::paid flips to true — entirely independent of the
+ * `status` column (see OrderStatusFlow's own docblock for why payment
+ * timing, especially for cash-on-delivery, cannot be modeled as a step in
+ * that sequence). Order::status changes are instead picked up generically
+ * by Modules\Core\Order\Events\OrderStatusUpdated (dispatched by
+ * OrderObserver whenever `status` changes, regardless of writer).
+ */
+class OrderPaidChanged
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+        public readonly string $causeClass,
+    ) {}
+}

src/Order/Events/OrderPickedUp.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+
+/**
+ * Dispatched by Modules\Core\Order\Services\OrderFulfillmentService::
+ * markPickedUp(), the staff-driven "Update Status" action's handling of
+ * the 'picked_up' target — the customer has collected a store-pickup
+ * order in person. Store-pickup only; a carrier order's equivalent
+ * "arrived" moment is OrderDelivered. Modules\Core\Order\Listeners\
+ * CompleteOrderOnPickedUp reacts to this by moving `status` straight to
+ * 'completed' — no return-window step for store-pickup, per the business
+ * design.
+ */
+class OrderPickedUp
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+    ) {}
+}

src/Order/Events/OrderReadyForDispatch.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+
+/**
+ * Dispatched by Modules\Core\Shipping\Extensions\OrderViewExtension's
+ * "Mark Ready" action, carrier branch (Order::isStorePickupOrder() ===
+ * false) — staff has packed/staged the order for carrier handoff.
+ * Staff-internal: nothing customer-facing happens at this moment, so no
+ * notification listens to this event (compare OrderReadyForPickup, which
+ * does trigger a customer email).
+ */
+class OrderReadyForDispatch
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+    ) {}
+}

src/Order/Events/OrderReadyForPickup.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+
+/**
+ * Dispatched by Modules\Core\Shipping\Extensions\OrderViewExtension's
+ * "Mark Ready" action, store-pickup branch (Order::isStorePickupOrder()
+ * === true) — staff has packed/staged the order for the customer to
+ * collect in store. Drives Modules\Core\Order\Notifications\
+ * OrderPickupReadyNotification ("come collect your order").
+ */
+class OrderReadyForPickup
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+    ) {}
+}

src/Order/Events/OrderStatusChanged.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+
+/**
+ * Dispatched by Modules\Core\Order\Services\OrderStatusWriter::write()
+ * alongside the generic Modules\Core\Order\Events\OrderStatusUpdated
+ * (which Modules\Core\Order\Observers\OrderObserver dispatches for ANY
+ * `status` write, regardless of cause, and which
+ * OrderStatusUpdatedNotification already listens to). This event exists
+ * only because the audit trail (Modules\Core\Order\Listeners\
+ * RecordStatusTransition) needs $causeClass, which OrderStatusUpdated
+ * does not carry — OrderStatusWriter is the only writer of `status` this
+ * package has left, so it's the only place that needs to know its own
+ * cause.
+ */
+class OrderStatusChanged
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+        public readonly ?string $previousStatus,
+        public readonly string $newStatus,
+        public readonly string $causeClass,
+    ) {}
+}