Добавлен адаптер к tbank и формирование ссылки на оплату

spec/overview.md

@@ -17,8 +17,9 @@
 
 - Принимать запрос на расчёт стоимости доставки (идентификаторы городов отправления/назначения, вес, габариты)
 - Поддерживать необязательный параметр `parcel_type` в запросе расчёта стоимости доставки для фильтрации тарифов по типу отправления
-- Предоставлять отдельный endpoint подсказок адреса, чтобы frontend мог получить точное значение для `from_location.address` и `to_location.address` перед созданием заказа
-- Принимать запрос на создание заказа CDEK по контракту из `http-client.http` для сценария "доставка, до двери"
+- Предоставлять отдельный endpoint подсказок адреса, чтобы frontend мог получить точное значение для `from_location.address` и `to_location.address` перед инициализацией оплаты доставки
+- Принимать запрос на инициализацию оплаты доставки через TBank и возвращать ссылку на оплату без регистрации заказа в CDEK
+- Принимать сумму оплаты в поле `price` в копейках
 - Выбирать сервис подсказок адреса по `country_code` через маппинг стран в конфиге
 - Для `RU`, `BY` и `KZ`, сопоставленных с provider id `dadata`, использовать `dadata.ru`
 - Для `AM`, `AZ`, `KG`, `MD`, `TJ`, `TM` и `UZ`, сопоставленных с provider id `yandex_geosuggest`, использовать Yandex Geosuggest
@@ -38,8 +39,11 @@
 ### Фаза 1
 - **CDEK** — https://apidoc.cdek.ru/
     - Аутентификация: OAuth2 (client credentials)
-    - Операции: расчёт тарифа, регистрация заказа
+    - Операции: расчёт тарифа
     - Cache TTL: 15 минут
+- **TBank** — https://securepay.tinkoff.ru/v2/Init
+    - Аутентификация: `TerminalKey` и token на основе password
+    - Операции: инициализация платежа и получение payment URL
 
 ### Фаза 2+
 - Дополнительные провайдеры (Boxberry, DHL и др.) — подключаются через интерфейс `DeliveryProvider` без изменений в логике агрегации
@@ -51,10 +55,10 @@
 ### Controller (`app/controllers/v1/delivery.py`)
 - `POST /api/v1/delivery/price` — принимает `DeliveryCalculationRequest`, возвращает `list[DeliveryPrice]`
 - `POST /api/v1/delivery/suggest-address` — принимает `AddressSuggestRequest`, возвращает `list[AddressSuggestion]`
-- `POST /api/v1/delivery/order` — принимает `OrderCreateRequest`, возвращает `OrderCreateResponse`
+- `POST /api/v1/delivery/init-payment` — принимает `InitPaymentRequest`, возвращает `InitPaymentResponse`
 - Парсинг и валидация входных данных через Pydantic
 - Маппинг исключений сервиса в HTTP-ответы
-- Каждый endpoint вызывает ровно один метод Service: `AggregatorService.get_all_prices()`, `AggregatorService.suggest_addresses()` или `AggregatorService.create_order()`
+- Каждый endpoint вызывает ровно один метод Service: `AggregatorService.get_all_prices()`, `AggregatorService.suggest_addresses()` или `AggregatorService.init_payment()`
 
 ### Service (`app/services/aggregator.py`)
 - `AggregatorService.get_all_prices(request: DeliveryCalculationRequest) -> list[DeliveryPrice]`
@@ -64,8 +68,8 @@
 - Сортирует тарифы по цене
 - `AggregatorService.suggest_addresses(request: AddressSuggestRequest) -> list[AddressSuggestion]`
 - `AggregatorService.suggest_addresses()` выбирает address suggestion provider по `country_code` через injected config mapping и оркестрирует ровно один adapter call
-- `AggregatorService.create_order(request: OrderCreateRequest) -> OrderCreateResponse`
-- `AggregatorService.create_order()` оркестрирует регистрацию заказа в CDEK через injected adapter dependency
+- `AggregatorService.init_payment(request: InitPaymentRequest) -> InitPaymentResponse`
+- `AggregatorService.init_payment()` оркестрирует инициализацию платежа через injected TBank adapter dependency
 - Service не содержит бизнес-логики и provider HTTP-деталей
 
 ### Business Logic (`app/domain/`)
@@ -92,14 +96,18 @@
 - `cdek/client.py` — HTTP-клиент (httpx AsyncClient), аутентификация, ретраи, таймаут (10с)
 - `cdek/auth.py` — управление OAuth2-токеном
 - `cdek/mapper.py` — ответ CDEK → `list[DeliveryPrice]`
-- `cdek/order_mapper.py` — request/response mapping для регистрации заказа CDEK
+- `cdek/order_mapper.py` — request/response mapping для CDEK order contract; публичный `init-payment` flow не вызывает регистрацию заказа в CDEK
 - Каждый адаптер владеет своей конфигурацией; наружу экспонирует только service-facing methods, необходимые соответствующему use-case
 - Для расчёта тарифа CDEK adapter принимает city identifiers из `DeliveryCalculationRequest`, находит запись в `cities_map`, берёт `cdek.code` и передаёт его в CDEK API
 
-Для сценария создания заказа CDEK adapter принимает валидированную order model, отправляет контракт `Регистрация заказа (тип "доставка", до двери)` из `http-client.http` и возвращает внутреннюю response model без утечки HTTP-деталей в Service.
-Во внутреннем order flow `sender` и `recipient` содержат ровно одно поле `phone`, а CDEK adapter сериализует его в provider payload `phones` с одним элементом.
-Поле `services` в order flow является необязательным; при отсутствии значения adapter не отправляет `services` в CDEK payload.
-Поле `packages[*].weight` во входном order request задаётся в килограммах, а CDEK adapter конвертирует его в граммы перед отправкой в provider API.
+Для CDEK order contract mapper принимает `InitPaymentRequest`, сериализует `sender.phone` и `recipient.phone` в provider payload `phones` с одним элементом, не отправляет `services` при отсутствии значения, конвертирует `packages[*].weight` из килограммов в граммы и возвращает `entity.uuid` строкой.
+
+### Adapter (`app/adapters/tbank`)
+- `base.py` — исключения TBank payment adapter
+- `client.py` — `TBankAdapter`
+- `TBankAdapter.create_payment_link(order_uuid: str, amount_kopecks: int) -> str` инициализирует платёж TBank и возвращает payment URL
+- TBank adapter инкапсулирует HTTP-взаимодействие с TBank Init API, auth token, retries, timeout, serialization и error handling
+- TBank adapter владеет собственной секцией конфигурации `tbank_payment` с полями `init_url`, `auth.terminal_key`, `auth.password`, `timeout_seconds`, `retry_attempts`, `retry_backoff_seconds`
 
 ### Adapter (`app/adapters/address_suggestions`)
 - `base.py` — абстрактный интерфейс `AddressSuggestionProvider`:
@@ -168,8 +176,10 @@ flat: str | None
 postal_code: str | None
 ```
 
-### Входная: `OrderCreateRequest`
+### Входная: `InitPaymentRequest`
 ```
+order_uuid: str
+price: int
 type: Literal[2]
 tariff_code: Literal[535]
 comment: str | None
@@ -193,14 +203,14 @@ services: list[{code: str, parameter: str}] | None
 packages: list[{number: str, weight: int, length: int, width: int, height: int, comment: str | None}]
 ```
 
-`from_location.address` и `to_location.address` должны содержать точные значения адреса, выбранные клиентом; order flow не выполняет address suggestion lookup.
-`sender.phone` и `recipient.phone` представляют единственный телефон для соответствующей стороны заказа; передача нескольких телефонов во входном API не поддерживается.
-`packages[*].weight` в `OrderCreateRequest` задаётся в килограммах, а в payload CDEK должен передаваться в граммах.
+`price` задаётся в копейках, является обязательным целым числом и должен быть больше 0.
+`from_location.address` и `to_location.address` должны содержать точные значения адреса, выбранные клиентом; payment flow не выполняет address suggestion lookup.
+`sender.phone` и `recipient.phone` представляют единственный телефон для соответствующей стороны; передача нескольких телефонов во входном API не поддерживается.
+`packages[*].weight` в `InitPaymentRequest` задаётся в килограммах; CDEK order mapper конвертирует его в граммы для provider payload.
 
-### Выходная: `OrderCreateResponse`
+### Выходная: `InitPaymentResponse`
 ```
-provider: str
-order_uuid: str
+payment_url: str
 ```
 
 ---
@@ -246,6 +256,9 @@ app/
 │           ├── auth.py
 │           ├── mapper.py
 │           └── order_mapper.py
+│   └── tbank/
+│       ├── base.py
+│       └── client.py
 ├── repositories/
 │   └── cache/
 │       └── redis_cache.py             # Repository
@@ -253,7 +266,7 @@ app/
 │   ├── address.py
 │   ├── request.py
 │   ├── response.py
-│   └── order.py
+│   └── payment.py
 └── config.py
 ```