order sagas

2026-06-21 11:33:20 +02:00
parent 484f2364fb
commit 1a365de071
25 changed files with 4224 additions and 1 deletions
@@ -0,0 +1,98 @@
+syntax = "proto3";
+package order_messages;
+option go_package = "git.k6n.net/mats/go-cart-actor/proto/order;order_messages";
+
+// Order mutations. Each message is one immutable event in an order's history.
+// The grain's event log (actor.DiskStorage) is the source of truth; the current
+// OrderGrain state is a projection folded by replaying these in order. The
+// order state machine (pkg/order) guards which mutation is legal in which state.
+//
+// Timestamps are carried as unix-millis fields set by the caller so that replay
+// is deterministic (the registry does not pass the event timestamp to handlers).
+
+message OrderLine {
+  string reference = 1; // stable line reference (cart line id / sku)
+  string sku = 2;
+  string name = 3;
+  int32 quantity = 4;
+  int64 unit_price = 5; // inc-vat, minor units
+  int32 tax_rate = 6;   // percent
+  int64 total_amount = 7;
+  int64 total_tax = 8;
+}
+
+// PlaceOrder creates the order (only legal when the order does not yet exist).
+message PlaceOrder {
+  string order_reference = 1; // external reference (e.g. checkout/cart id)
+  string cart_id = 2;
+  string currency = 3;
+  string locale = 4;
+  string country = 5;
+  int64 total_amount = 6; // inc-vat, minor units
+  int64 total_tax = 7;
+  repeated OrderLine lines = 8;
+  string customer_email = 9;
+  string customer_name = 10;
+  bytes billing_address = 11;  // raw JSON, stored losslessly
+  bytes shipping_address = 12; // raw JSON, stored losslessly
+  int64 placed_at_ms = 13;
+}
+
+// AuthorizePayment records a successful authorization against a provider.
+message AuthorizePayment {
+  string provider = 1;
+  int64 amount = 2;
+  string reference = 3; // processor authorization reference
+  int64 at_ms = 4;
+}
+
+// CapturePayment records a (possibly partial) capture against an authorization.
+message CapturePayment {
+  string provider = 1;
+  int64 amount = 2;
+  string reference = 3; // processor capture reference
+  int64 at_ms = 4;
+}
+
+message FulfillmentLine {
+  string reference = 1;
+  int32 quantity = 2;
+}
+
+// CreateFulfillment ships some or all of the order's lines.
+message CreateFulfillment {
+  string id = 1;
+  string carrier = 2;
+  string tracking_number = 3;
+  string tracking_uri = 4;
+  repeated FulfillmentLine lines = 5;
+  int64 at_ms = 6;
+}
+
+// CompleteOrder marks a fully-fulfilled order complete.
+message CompleteOrder {
+  int64 at_ms = 1;
+}
+
+// CancelOrder cancels an order that has not yet been captured.
+message CancelOrder {
+  string reason = 1;
+  int64 at_ms = 2;
+}
+
+// RequestReturn opens an RMA against fulfilled lines (does not change status).
+message RequestReturn {
+  string id = 1;
+  string reason = 2;
+  repeated FulfillmentLine lines = 3;
+  int64 at_ms = 4;
+}
+
+// IssueRefund records a (possibly partial) refund against a captured payment.
+message IssueRefund {
+  string provider = 1;
+  int64 amount = 2;
+  string reference = 3; // processor refund reference
+  string return_id = 4; // optional linked RMA
+  int64 at_ms = 5;
+}