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;
  string location = 9; // inventory location / store id for commit; empty = order country
  bool drop_ship = 10;
}

// 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;
}

// RequestExchange opens an RMA return and reserves/adds replacement lines.
message RequestExchange {
  string id = 1;
  string return_id = 2;
  string reason = 3;
  repeated FulfillmentLine return_lines = 4;
  repeated OrderLine new_lines = 5;
  int64 at_ms = 6;
}

// EditOrderDetails updates address/shipping price post-placement.
message EditOrderDetails {
  bytes shipping_address = 1;
  bytes billing_address = 2;
  int64 shipping_price = 3;
  int64 at_ms = 4;
}