diff --git a/proto/customer.thrift b/proto/customer.thrift index ee66aea1..827623a3 100644 --- a/proto/customer.thrift +++ b/proto/customer.thrift @@ -113,6 +113,19 @@ struct TerminalAffinityParams { * она снимается, а вместо неё создаётся новая с очередным bind_seq. */ 4: optional domain.RoutingAffinityTtl ttl + /** + * Платёж, по итогам которого создаётся привязка. + * + * Служит ключом идемпотентности: повторная привязка по тому же платежу + * ничего не меняет и возвращает существующую запись. Без него повтор шага + * машины неотличим от нового успешного платежа, и привязка, истёкшая между + * попытками, была бы снята и создана заново с новым порядковым номером, + * то есть переехала бы в конец истории. + * + * Этот же платёж запоминается за Customer, поэтому отдельный вызов + * AddPayment для него не нужен. + */ + 5: required PaymentRef payment } /** @@ -409,6 +422,9 @@ service CustomerManagement { /** * Добавить платёж к Customer. + * + * Для платежей, по которым создаётся привязка к терминалу, вызывать не нужно: + * BindTerminalAffinity запоминает платёж сам. */ void AddPayment( 1: CustomerID customer_id, @@ -470,8 +486,15 @@ service CustomerManagement { throws (1: CustomerNotFound not_found) /** - * Привязать Customer к терминалу. - * Идемпотентно: повторный вызов не меняет bind_seq, только last_used_at. + * Привязать Customer к терминалу по итогам успешного платежа. + * + * Идемпотентно по платежу: повторный вызов с тем же PaymentRef возвращает + * существующую привязку, не меняя ни её порядковый номер, ни срок. Вызов по + * новому платежу обновляет last_used_at, а если привязка к этому терминалу + * истекла по ttl — снимает её и создаёт заново в конце истории. + * + * Платёж запоминается за Customer в том же вызове, поэтому отдельно звать + * AddPayment для него не требуется. */ TerminalAffinity BindTerminalAffinity(1: TerminalAffinityParams params) throws ( diff --git a/proto/payment_processing.thrift b/proto/payment_processing.thrift index 12a3c130..dddfa819 100644 --- a/proto/payment_processing.thrift +++ b/proto/payment_processing.thrift @@ -915,6 +915,10 @@ struct RouteDecisionContext { * (domain.RoutingAffinity): при успешном платеже привязка будет создана. */ 2: optional bool terminal_affinity + /** + * Время жизни привязки, взятое с выбранного кандидата + */ + 3: optional domain.RoutingAffinityTtl affinity_ttl } // Exceptions