Раис Юсупалиев
282 lines
15 KiB
Markdown
282 lines
15 KiB
Markdown
# spec/overview.md
|
||
|
||
Контекст, специфичный для проекта агрегатора служб доставки.
|
||
Глобальные правила определены в AGENTS.md.
|
||
|
||
---
|
||
|
||
## Проект
|
||
|
||
**Название:** Агрегатор служб доставки (бэкенд)
|
||
**Язык:** Python 3.14
|
||
**Назначение:** Агрегировать расчёты стоимости доставки от нескольких служб и отдавать единый ответ фронтенду через унифицированный API.
|
||
|
||
---
|
||
|
||
## Продуктовые требования
|
||
|
||
- Принимать запрос на расчёт стоимости доставки (идентификаторы городов отправления/назначения, вес, габариты)
|
||
- Поддерживать необязательный параметр `parcel_type` в запросе расчёта стоимости доставки для фильтрации тарифов по типу отправления
|
||
- Предоставлять отдельный 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
|
||
- Для европейских стран, сопоставленных с provider id `tomtom`, использовать TomTom Search API Fuzzy Search
|
||
- Конфигурация и wiring должны допускать отдельные address suggestion providers для других регионов
|
||
- Опрашивать всех зарегистрированных провайдеров параллельно
|
||
- Возвращать унифицированный список тарифов, отсортированных по цене
|
||
- Если провайдер вернул ошибку или не ответил вовремя — исключить его из результата, не падая целиком
|
||
- Кешировать ответы провайдеров для исключения повторных внешних запросов. Время кэширования вынести в конфиг
|
||
- Применять к цене, полученной от провайдера, конфигурируемый мультипликатор и округлять итоговую цену до целого значения
|
||
- Для расчёта стоимости использовать локальный справочник `cities_map` с provider-specific данными города; для CDEK брать `cdek.code` без обращения к API подсказок городов
|
||
|
||
---
|
||
|
||
## Провайдеры
|
||
|
||
### Фаза 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` без изменений в логике агрегации
|
||
|
||
---
|
||
|
||
## Компоненты
|
||
|
||
### 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/init-payment` — принимает `InitPaymentRequest`, возвращает `InitPaymentResponse`
|
||
- Парсинг и валидация входных данных через Pydantic
|
||
- Маппинг исключений сервиса в HTTP-ответы
|
||
- Каждый 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]`
|
||
- Распределяет запросы по всем зарегистрированным провайдерам через `asyncio.gather(..., return_exceptions=True)`
|
||
- Принимает от каждого провайдера список тарифов и объединяет их в единый список
|
||
- Фильтрует упавшие результаты
|
||
- Сортирует тарифы по цене
|
||
- `AggregatorService.suggest_addresses(request: AddressSuggestRequest) -> list[AddressSuggestion]`
|
||
- `AggregatorService.suggest_addresses()` выбирает address suggestion provider по `country_code` через injected config mapping и оркестрирует ровно один adapter call
|
||
- `AggregatorService.init_payment(request: InitPaymentRequest) -> InitPaymentResponse`
|
||
- `AggregatorService.init_payment()` оркестрирует инициализацию платежа через injected TBank adapter dependency
|
||
- Service не содержит бизнес-логики и provider HTTP-деталей
|
||
|
||
### Business Logic (`app/domain/`)
|
||
- Правила сортировки и фильтрации тарифов
|
||
- Правила фильтрации тарифов по `parcel_type`
|
||
- Логика сравнения цен
|
||
- Правила применения конфигурируемого мультипликатора к ценам провайдеров
|
||
- Округление цены после применения мультипликатора до целого значения по детерминированному правилу
|
||
- Нормализация входных данных (например, идентификаторов городов и правил округления веса)
|
||
- Чистые функции, без IO, без зависимостей от фреймворков
|
||
|
||
### Repository (`app/repositories/cache/`)
|
||
- `PriceCache` — хранилище ключ/значение на базе Redis
|
||
- Операции: `get(key)`, `set(key, value, ttl)`, `invalidate(key)`
|
||
- Без бизнес-решений; формирование ключа — ответственность Adapter
|
||
|
||
### Adapter (`app/adapters/delivery_providers`)
|
||
- `base.py` — абстрактный интерфейс `DeliveryProvider`:
|
||
```python
|
||
class DeliveryProvider(ABC):
|
||
name: str
|
||
async def get_prices(self, request: DeliveryCalculationRequest) -> list[DeliveryPrice]: ...
|
||
```
|
||
- `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 order contract; публичный `init-payment` flow не вызывает регистрацию заказа в CDEK
|
||
- Каждый адаптер владеет своей конфигурацией; наружу экспонирует только service-facing methods, необходимые соответствующему use-case
|
||
- Для расчёта тарифа CDEK adapter принимает city identifiers из `DeliveryCalculationRequest`, находит запись в `cities_map`, берёт `cdek.code` и передаёт его в CDEK 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`:
|
||
```python
|
||
class AddressSuggestionProvider(ABC):
|
||
name: str
|
||
async def suggest(self, request: AddressSuggestRequest) -> list[AddressSuggestion]: ...
|
||
```
|
||
- `dadata/client.py` — HTTP-клиент `dadata.ru` для address suggestions
|
||
- `yandex_geosuggest/client.py` — HTTP-клиент Yandex Geosuggest `GET https://suggest-maps.yandex.ru/v1/suggest`
|
||
- `tomtom/client.py` — HTTP-клиент TomTom Search API Fuzzy Search `GET https://api.tomtom.com/search/2/search/{query}.json`
|
||
- provider-specific модули address suggestion adapters инкапсулируют внешние API-контракты, auth, serialization и error handling
|
||
- В конфиге adapter layer хранится маппинг `country_code -> provider_id` для выбора address suggestion provider
|
||
- Address suggestion adapters возвращают только унифицированные internal models без утечки provider-specific payload в Service
|
||
- Для Yandex Geosuggest adapter возвращает `postal_code=None`, так как контракт Geosuggest не используется как источник почтового индекса
|
||
- Для TomTom Search adapter использует `request.city` и `request.query` для формирования search query, передаёт `countrySet=request.country_code`, `typeahead=true`, `idxSet=PAD,Addr,Str,EPP`, а `postal_code` берёт из `address.postalCode`, если оно присутствует
|
||
|
||
---
|
||
|
||
## Reference Data
|
||
|
||
- `cities_map` содержит city identifier и provider-specific данные города для price flow.
|
||
- Справочник может быть частично заполнен; отсутствие provider-specific данных для города должно обрабатываться детерминированно.
|
||
- Структура справочника должна допускать появление дополнительных провайдеров без изменения публичного API расчёта.
|
||
|
||
---
|
||
|
||
## Модели данных
|
||
|
||
### Входная: `DeliveryCalculationRequest`
|
||
```
|
||
entity: Enum(individual, legal)
|
||
from_city: int
|
||
to_city: int
|
||
weight_kg: float
|
||
length_cm: float
|
||
width_cm: float
|
||
height_cm: float
|
||
parcel_type: Literal[doc, parcel] | None
|
||
```
|
||
|
||
### Выходная: `DeliveryPrice`
|
||
```
|
||
provider: str
|
||
service_name: str
|
||
price: Decimal
|
||
currency: str
|
||
delivery_days_min: int
|
||
delivery_days_max: int
|
||
```
|
||
|
||
### Входная: `AddressSuggestRequest`
|
||
```
|
||
country_code: str
|
||
city: str
|
||
query: str
|
||
limit: int | None
|
||
```
|
||
|
||
### Выходная: `AddressSuggestion`
|
||
```
|
||
address: str
|
||
street: str | None
|
||
house: str | None
|
||
flat: str | None
|
||
postal_code: str | None
|
||
```
|
||
|
||
### Входная: `InitPaymentRequest`
|
||
```
|
||
order_uuid: str
|
||
price: int
|
||
type: Literal[2]
|
||
tariff_code: Literal[535]
|
||
comment: str | None
|
||
sender:
|
||
name: str
|
||
email: str
|
||
phone: {number: str}
|
||
recipient:
|
||
name: str
|
||
email: str
|
||
phone: {number: str}
|
||
from_location:
|
||
address: str
|
||
city: str
|
||
country_code: str
|
||
to_location:
|
||
address: str
|
||
city: str
|
||
country_code: str
|
||
services: list[{code: str, parameter: str}] | None
|
||
packages: list[{number: str, weight: int, length: int, width: int, height: int, comment: str | None}]
|
||
```
|
||
|
||
`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.
|
||
|
||
### Выходная: `InitPaymentResponse`
|
||
```
|
||
payment_url: str
|
||
```
|
||
|
||
---
|
||
|
||
## Технологический стек
|
||
|
||
| Задача | Инструмент |
|
||
|---|---|
|
||
| Web-фреймворк | FastAPI |
|
||
| HTTP-клиент | httpx (async) |
|
||
| Валидация | Pydantic v2 |
|
||
| Кеш | Redis |
|
||
| Конфигурация | pydantic-settings |
|
||
| Сервер | Uvicorn |
|
||
|
||
---
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
app/
|
||
├── controllers/
|
||
│ ├── http_client.py
|
||
│ └── v1/
|
||
│ └── delivery.py # Controller
|
||
├── services/
|
||
│ └── aggregator.py # Service
|
||
├── domain/
|
||
│ └── price.py # Business Logic
|
||
├── adapters/
|
||
│ ├── address_suggestions/
|
||
│ │ ├── base.py # Интерфейс Adapter
|
||
│ │ ├── dadata/
|
||
│ │ └── client.py
|
||
│ │ ├── yandex_geosuggest/
|
||
│ │ └── client.py
|
||
│ │ └── tomtom/
|
||
│ │ └── client.py
|
||
│ └── delivery_providers/
|
||
│ ├── base.py # Интерфейс Adapter
|
||
│ └── cdek/
|
||
│ ├── client.py
|
||
│ ├── auth.py
|
||
│ ├── mapper.py
|
||
│ └── order_mapper.py
|
||
│ └── tbank/
|
||
│ ├── base.py
|
||
│ └── client.py
|
||
├── repositories/
|
||
│ └── cache/
|
||
│ └── redis_cache.py # Repository
|
||
├── schemas/
|
||
│ ├── address.py
|
||
│ ├── request.py
|
||
│ ├── response.py
|
||
│ └── payment.py
|
||
└── config.py
|
||
```
|
||
|
||
---
|
||
|
||
## Инфраструктура
|
||
|
||
```yaml
|
||
# docker-compose сервисы
|
||
app # FastAPI-приложение
|
||
redis # Кеш тарифов
|
||
```
|