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
@@ -1,7 +1,7 @@
 # Spec Tasks Index

 > ⚠️ This file is generated. Do not edit manually.
-> Generated at (UTC): `2026-03-15T21:04:41+00:00`
+> Generated at (UTC): `2026-03-18T18:41:29+00:00`

 ## Tasks

@@ -25,10 +25,11 @@
 | 015 | DONE | 2026-03-13 | Add minimal OpenTelemetry tracing | `spec/tasks/015_add_minimal_opentelemetry_tracing.md` |
 | 016 | DONE | 2026-03-14 | Add CDEK order registration adapter | `spec/tasks/016_add_cdek_order_registration_adapter.md` |
 | 017 | DONE | 2026-03-14 | Return all tariffs from CDEK price calculation | `spec/tasks/017_return_all_cdek_tariffs.md` |
-| 018 | TODO | 2026-03-14 | Add CDEK order creation endpoint | `spec/tasks/018_add_cdek_order_creation_endpoint.md` |
+| 018 | TODO | 2026-03-16 | Add optional parcel type filter to price request | `spec/tasks/018_add_optional_parcel_type_filter_to_price_request.md` |
+| 019 | TODO | 2026-03-14 | Add CDEK order creation endpoint | `spec/tasks/019_add_cdek_order_creation_endpoint.md` |

 ## Summary

- Total: **19**
- TODO: **1**
+- Total: **20**
+- TODO: **2**
 - DONE: **18**
@@ -16,6 +16,7 @@
 ## Продуктовые требования

 - Принимать запрос на расчёт стоимости доставки (откуда, куда, вес, габариты)
+- Поддерживать необязательный параметр `parcel_type` в запросе расчёта стоимости доставки для фильтрации тарифов по типу отправления
 - Принимать запрос на создание заказа CDEK по контракту из `http-client.http` для сценария "доставка, до двери"
 - Опрашивать всех зарегистрированных провайдеров параллельно
 - Возвращать унифицированный список тарифов, отсортированных по цене
@@ -59,6 +60,7 @@

 ### Business Logic (`app/domain/`)
 - Правила сортировки и фильтрации тарифов
+- Правила фильтрации тарифов по `parcel_type`
 - Логика сравнения цен
 - Правила применения конфигурируемого мультипликатора к ценам провайдеров
 - Округление цены после применения мультипликатора до целого значения по детерминированному правилу
@@ -98,6 +100,7 @@ weight_kg: float
 length_cm: float
 width_cm: float
 height_cm: float
+parcel_type: Literal[doc, parcel] | None
 ```

 ### Выходная: `DeliveryPrice`
@@ -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