018 add parcel type

2026-03-16 01:14:46 +03:00
parent 54160a0e38
commit c4175121a0
10 changed files with 346 additions and 11 deletions
@@ -0,0 +1,49 @@
+---
+id: 018
+title: Add optional parcel type filter to price request
+status: DONE
+created: 2026-03-16
+---
+
+## Context
+Сейчас `POST /api/v1/delivery/price` возвращает все доступные тарифы без возможности отфильтровать их по типу отправления. Новый пользовательский сценарий требует опциональный параметр `parcel_type`, который должен фильтровать уже агрегированный список тарифов для всех провайдеров.
+
+## Goal
+Расширить контракт `DeliveryRequest` опциональным полем `parcel_type` и добавить детерминированную фильтрацию тарифов в price flow по правилам `doc` и `parcel` без изменения публичного path endpoint.
+
+## Constraints
+- `parcel_type` является необязательным полем запроса `POST /api/v1/delivery/price`.
+- Допустимые значения ограничены `doc` и `parcel`; другие значения должны отклоняться schema validation.
+- Правило фильтрации является pure business rule и должно жить в `app/domain/`; Controller только валидирует DTO, Service только оркестрирует и передаёт параметр в domain logic.
+- Фильтрация должна применяться к унифицированному списку тарифов для всех провайдеров и не должна требовать provider-specific branching или изменения provider transport contract.
+- Для `doc` включаются только тарифы, у которых `service_name` содержит `документ` или `document` без учёта регистра.
+- Для `parcel` возвращаются все остальные тарифы, не попавшие под правило `doc`.
+- Если `parcel_type` не передан, поведение endpoint остаётся прежним: возвращаются все тарифы.
+- Scope задачи не включает изменение order flow, добавление новых endpoint'ов, расширение набора значений `parcel_type` и иные изменения вне price flow.
+- Не изменять файлы в `spec/`.
+
+## Acceptance criteria
+- `DeliveryRequest` поддерживает опциональное поле `parcel_type`.
+- `POST /api/v1/delivery/price` принимает запросы без `parcel_type` и возвращает полный список тарифов без дополнительной фильтрации.
+- При `parcel_type=doc` ответ содержит только тарифы, у которых `service_name` содержит `документ` или `document` без учёта регистра.
+- При `parcel_type=parcel` ответ содержит только тарифы, у которых `service_name` не содержит `документ` и `document` без учёта регистра.
+- Невалидное значение `parcel_type` приводит к 422 response на уровне schema validation.
+- Фильтрация работает одинаково для тарифов, полученных из provider responses и из cache.
+
+## Definition of Done
+- [ ] Обновлён контракт price request с опциональным `parcel_type`.
+- [ ] Реализована pure domain logic для фильтрации тарифов по `parcel_type`.
+- [ ] Service wiring передаёт `parcel_type` в domain logic без добавления business rules в Service.
+- [ ] Controller/API tests покрывают сценарии `doc`, `parcel`, отсутствие параметра и невалидное значение.
+- [ ] Поведение одинаково для fresh provider results и cache hit.
+
+## Tests
+- Обновить `tests/domain/test_price.py` для проверки case-insensitive фильтрации по `документ` и `document`, а также поведения без `parcel_type`.
+- Обновить `tests/services/test_aggregator.py` для проверки делегирования `parcel_type` в domain logic и одинакового результата для fresh path и cache hit.
+- Обновить `tests/controllers/v1/test_delivery.py` для проверки optional request field, 422 на невалидное значение и response filtering для `doc` и `parcel`.
+
+## Commands
+- `poetry run pytest tests/domain/test_price.py -q`
+- `poetry run pytest tests/services/test_aggregator.py -q`
+- `poetry run pytest tests/controllers/v1/test_delivery.py -q`
+- `python3 spec/gen_spec_index.py --check`
@@ -1,5 +1,5 @@
 ---
-id: 018
+id: 019
 title: Add CDEK order creation endpoint
 status: TODO
 created: 2026-03-14