refactored notificatoin / tgsettle responsibility boundaries
This commit is contained in:
Stephan D
193
api/proto/payments/orchestration/v2/orchestration.proto
Normal file
193
api/proto/payments/orchestration/v2/orchestration.proto
Normal file
@@ -0,0 +1,193 @@
|
||||
syntax = "proto3";
|
||||
|
||||
package payments.orchestration.v2;
|
||||
|
||||
option go_package = "github.com/tech/sendico/pkg/proto/payments/orchestration/v2;orchestrationv2";
|
||||
|
||||
import "google/protobuf/timestamp.proto";
|
||||
import "api/proto/common/gateway/v1/gateway.proto";
|
||||
import "api/proto/common/pagination/v1/cursor.proto";
|
||||
import "api/proto/payments/shared/v1/shared.proto";
|
||||
import "api/proto/payments/quotation/v2/quotation.proto";
|
||||
import "api/proto/payments/quotation/v2/interface.proto";
|
||||
|
||||
// PaymentOrchestratorService executes quotation-backed payments and exposes
|
||||
// orchestration-focused read APIs.
|
||||
//
|
||||
// Notes:
|
||||
// - Execution input is quotation_ref (not an execution plan).
|
||||
// - Returned Payment contains immutable quote/intent snapshots, so reads remain
|
||||
// meaningful after quote storage TTL expiry.
|
||||
service PaymentOrchestratorService {
|
||||
// ExecutePayment creates/starts payment execution from an accepted quote.
|
||||
rpc ExecutePayment(ExecutePaymentRequest) returns (ExecutePaymentResponse);
|
||||
|
||||
// GetPayment returns one payment by reference.
|
||||
rpc GetPayment(GetPaymentRequest) returns (GetPaymentResponse);
|
||||
|
||||
// ListPayments returns payments filtered by orchestration lifecycle.
|
||||
rpc ListPayments(ListPaymentsRequest) returns (ListPaymentsResponse);
|
||||
}
|
||||
|
||||
// ExecutePaymentRequest starts orchestration for one accepted quote.
|
||||
message ExecutePaymentRequest {
|
||||
// Organization and trace context; idempotency should be supplied via
|
||||
// meta.trace.idempotency_key.
|
||||
payments.shared.v1.RequestMeta meta = 1;
|
||||
|
||||
// Required accepted quotation reference.
|
||||
string quotation_ref = 2;
|
||||
|
||||
// Optional caller-side correlation key.
|
||||
string client_payment_ref = 3;
|
||||
}
|
||||
|
||||
// ExecutePaymentResponse returns the created or deduplicated payment.
|
||||
message ExecutePaymentResponse {
|
||||
Payment payment = 1;
|
||||
}
|
||||
|
||||
// GetPaymentRequest fetches one payment by payment_ref.
|
||||
message GetPaymentRequest {
|
||||
payments.shared.v1.RequestMeta meta = 1;
|
||||
string payment_ref = 2;
|
||||
}
|
||||
|
||||
// GetPaymentResponse returns one orchestration payment aggregate.
|
||||
message GetPaymentResponse {
|
||||
Payment payment = 1;
|
||||
}
|
||||
|
||||
// ListPaymentsRequest lists payments within the caller organization scope.
|
||||
message ListPaymentsRequest {
|
||||
payments.shared.v1.RequestMeta meta = 1;
|
||||
|
||||
// Optional state filter. Empty means all states.
|
||||
repeated OrchestrationState states = 2;
|
||||
|
||||
// Optional filter by source quotation.
|
||||
string quotation_ref = 3;
|
||||
|
||||
// Optional creation-time range filter.
|
||||
// Semantics: created_from is inclusive, created_to is exclusive.
|
||||
google.protobuf.Timestamp created_from = 4;
|
||||
google.protobuf.Timestamp created_to = 5;
|
||||
|
||||
// Cursor pagination controls.
|
||||
common.pagination.v1.CursorPageRequest page = 6;
|
||||
}
|
||||
|
||||
// ListPaymentsResponse returns one cursor page of payments.
|
||||
message ListPaymentsResponse {
|
||||
repeated Payment payments = 1;
|
||||
common.pagination.v1.CursorPageResponse page = 2;
|
||||
}
|
||||
|
||||
// Payment is the orchestration runtime aggregate.
|
||||
// It is designed to be self-contained for post-factum analysis and support.
|
||||
message Payment {
|
||||
// Stable payment reference.
|
||||
string payment_ref = 1;
|
||||
|
||||
// Quote used to initiate the payment.
|
||||
string quotation_ref = 2;
|
||||
|
||||
// Immutable snapshot of the execution intent used to create this payment.
|
||||
payments.quotation.v2.QuoteIntent intent_snapshot = 3;
|
||||
|
||||
// Immutable quote snapshot used for execution pricing/route context.
|
||||
payments.quotation.v2.PaymentQuote quote_snapshot = 4;
|
||||
|
||||
string client_payment_ref = 5;
|
||||
|
||||
// Current orchestration runtime state.
|
||||
OrchestrationState state = 6;
|
||||
|
||||
// Monotonic aggregate version for optimistic concurrency control.
|
||||
uint64 version = 7;
|
||||
|
||||
// Step-level execution telemetry.
|
||||
repeated StepExecution step_executions = 8;
|
||||
|
||||
// Aggregate timestamps.
|
||||
google.protobuf.Timestamp created_at = 9;
|
||||
google.protobuf.Timestamp updated_at = 10;
|
||||
}
|
||||
|
||||
// Kept local on purpose: payments.shared.v1.PaymentState models product-level
|
||||
// payment lifecycle and does not cover orchestration runtime states.
|
||||
enum OrchestrationState {
|
||||
// Default zero value.
|
||||
ORCHESTRATION_STATE_UNSPECIFIED = 0;
|
||||
// Payment record created, execution not started yet.
|
||||
ORCHESTRATION_STATE_CREATED = 1;
|
||||
// Runtime is actively executing steps.
|
||||
ORCHESTRATION_STATE_EXECUTING = 2;
|
||||
// Runtime requires operator/system attention.
|
||||
ORCHESTRATION_STATE_NEEDS_ATTENTION = 3;
|
||||
// Execution finished successfully.
|
||||
ORCHESTRATION_STATE_SETTLED = 4;
|
||||
// Execution reached terminal failure.
|
||||
ORCHESTRATION_STATE_FAILED = 5;
|
||||
}
|
||||
|
||||
// StepExecution is telemetry for one orchestration step attempt stream.
|
||||
message StepExecution {
|
||||
// Stable step reference inside orchestration runtime.
|
||||
string step_ref = 1;
|
||||
// Logical step code/type label (planner/executor-defined).
|
||||
string step_code = 2;
|
||||
// Current state of this step.
|
||||
StepExecutionState state = 3;
|
||||
// Monotonic attempt number, starts at 1.
|
||||
uint32 attempt = 4;
|
||||
// Step timing.
|
||||
google.protobuf.Timestamp started_at = 5;
|
||||
google.protobuf.Timestamp completed_at = 6;
|
||||
// Failure details when state is FAILED/NEEDS_ATTENTION.
|
||||
Failure failure = 7;
|
||||
// External references produced by the step.
|
||||
repeated ExternalReference refs = 8;
|
||||
}
|
||||
|
||||
// Kept local on purpose: no shared enum exists for orchestration step runtime.
|
||||
enum StepExecutionState {
|
||||
// Default zero value.
|
||||
STEP_EXECUTION_STATE_UNSPECIFIED = 0;
|
||||
// Not started yet.
|
||||
STEP_EXECUTION_STATE_PENDING = 1;
|
||||
// Currently running.
|
||||
STEP_EXECUTION_STATE_RUNNING = 2;
|
||||
// Finished successfully.
|
||||
STEP_EXECUTION_STATE_COMPLETED = 3;
|
||||
// Finished with terminal error.
|
||||
STEP_EXECUTION_STATE_FAILED = 4;
|
||||
// Blocked and requires attention/intervention.
|
||||
STEP_EXECUTION_STATE_NEEDS_ATTENTION = 5;
|
||||
// Not executed because it became irrelevant/unreachable.
|
||||
STEP_EXECUTION_STATE_SKIPPED = 6;
|
||||
}
|
||||
|
||||
// Failure describes a normalized step failure.
|
||||
message Failure {
|
||||
// Broad, shared failure category.
|
||||
payments.shared.v1.PaymentFailureCode category = 1;
|
||||
// Machine-readable, executor-specific code.
|
||||
string code = 2;
|
||||
// Human-readable message.
|
||||
string message = 3;
|
||||
}
|
||||
|
||||
// ExternalReference links step execution to external systems/operations.
|
||||
message ExternalReference {
|
||||
// Rail where external side effect happened.
|
||||
common.gateway.v1.Rail rail = 1;
|
||||
// Gateway instance that owns the referenced operation/entity.
|
||||
// This is the discovery key for fetching details on demand.
|
||||
string gateway_instance_id = 2;
|
||||
// Reference classifier. Keep values stable and namespaced:
|
||||
// e.g. "ledger.journal", "ledger.hold", "chain.tx", "provider.payout".
|
||||
string kind = 3;
|
||||
// External operation/entity reference id in the owner system.
|
||||
string ref = 4;
|
||||
}
|
||||
Reference in New Issue
Block a user