From e0b6a3f7e6a4727305f59268d95bd51f5a226260 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A0=D0=B0=D0=B8=D1=81=20=D0=AE=D1=81=D1=83=D0=BF=D0=B0?= =?UTF-8?q?=D0=BB=D0=B8=D0=B5=D0=B2?= Date: Sat, 7 Mar 2026 14:15:58 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9E=D0=B1=D0=BD=D0=BE=D0=B2=D0=B8=D0=BB=20?= =?UTF-8?q?=D0=BE=D0=BF=D0=B8=D1=81=D0=B0=D0=BD=D0=B8=D0=B5=20=D0=B7=D0=B0?= =?UTF-8?q?=D0=B4=D0=B0=D1=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- spec/index.md | 2 +- spec/tasks/003_add_cdek_provider_adapter.md | 6 +++++- spec/tasks/004_add_redis_price_cache_repository.md | 5 ++++- spec/tasks/007_add_observability_correlation.md | 10 ++++++++-- spec/tasks/008_add_signoz_telegram_alerting.md | 10 +++++----- 5 files changed, 23 insertions(+), 10 deletions(-) diff --git a/spec/index.md b/spec/index.md index a2e10cf..51a92cf 100644 --- a/spec/index.md +++ b/spec/index.md @@ -1,7 +1,7 @@ # Spec Tasks Index > ⚠️ This file is generated. Do not edit manually. -> Generated at (UTC): `2026-03-07T11:09:24+00:00` +> Generated at (UTC): `2026-03-07T11:14:43+00:00` ## Tasks diff --git a/spec/tasks/003_add_cdek_provider_adapter.md b/spec/tasks/003_add_cdek_provider_adapter.md index 9b8f5ca..8fa36f3 100644 --- a/spec/tasks/003_add_cdek_provider_adapter.md +++ b/spec/tasks/003_add_cdek_provider_adapter.md @@ -9,12 +9,14 @@ created: 2026-03-07 Phase 1 в `spec/overview.md` требует поддержку provider CDEK с OAuth2 authentication и маппингом расчёта тарифа. ## Goal -Реализовать adapter interfaces и модули CDEK adapter: provider contract, OAuth2 token handling, HTTP client behavior и преобразование ответа в `DeliveryPrice`. +Реализовать adapter interfaces и модули CDEK adapter: provider contract, OAuth2 token handling, HTTP client behavior, преобразование ответа в `DeliveryPrice` и чтение параметров CDEK из секции `adapter` YAML-конфига. ## Constraints - Только Adapter layer; без business decisions и sorting logic. - Внешний IO должен оставаться внутри adapter modules. - Timeout для CDEK должен быть 10 секунд согласно specification. +- Параметры CDEK (`base_url`, OAuth2 credentials, retry policy, timeout, cache TTL) должны приходить из секции `adapter` в `.yaml` конфиге. +- Запрещён хардкод credentials и runtime-параметров адаптера. - Не изменять файлы в `spec/`. ## Acceptance criteria @@ -23,6 +25,7 @@ Phase 1 в `spec/overview.md` требует поддержку provider CDEK с - CDEK client выполняет tariff request с timeout и retry behavior. - CDEK mapper преобразует provider response в унифицированную schema `DeliveryPrice`. - Adapter наружу предоставляет только provider-facing API, необходимый Service. +- Адаптер использует значения из секции `adapter` YAML-конфига, включая `timeout_seconds=10` и `cache_ttl_seconds=900` по умолчанию. ## Definition of Done - [ ] Реализован base provider interface. @@ -33,6 +36,7 @@ Phase 1 в `spec/overview.md` требует поддержку provider CDEK с ## Tests - Добавить adapter unit tests для token lifecycle behavior. - Добавить adapter tests для response mapping и HTTP error handling. +- Добавить tests, проверяющие применение параметров CDEK из секции `adapter` YAML-конфига. - Для внешних HTTP взаимодействий использовать stubs/mocks. ## Commands diff --git a/spec/tasks/004_add_redis_price_cache_repository.md b/spec/tasks/004_add_redis_price_cache_repository.md index 1ea3e6a..0366344 100644 --- a/spec/tasks/004_add_redis_price_cache_repository.md +++ b/spec/tasks/004_add_redis_price_cache_repository.md @@ -9,12 +9,13 @@ created: 2026-03-07 Product requirements требуют кеширование ответов provider с configurable TTL, а архитектура закрепляет доступ к данным за слоем Repository. ## Goal -Реализовать `PriceCache` repository на Redis с операциями `get`, `set` и `invalidate`, включая поддержку TTL. +Реализовать `PriceCache` repository на Redis с операциями `get`, `set` и `invalidate`, включая поддержку TTL из секции `repository` YAML-конфига. ## Constraints - Только Repository layer: data access и persistence mapping. - В repository code не допускаются business decisions и workflow orchestration. - Генерация cache key не должна реализовываться в repository. +- Параметры Redis и TTL должны читаться из секции `repository` в `.yaml` конфиге. - Не изменять файлы в `spec/`. ## Acceptance criteria @@ -22,6 +23,7 @@ Product requirements требуют кеширование ответов provid - `PriceCache` предоставляет async методы `get`, `set`, `invalidate`. - `set` применяет TTL из configuration. - Serialization/deserialization cached payload выполняются детерминированно. +- Repository использует только параметры секции `repository` YAML-конфига для подключения к Redis и настройки TTL. ## Definition of Done - [ ] Реализован Redis-backed cache repository. @@ -31,6 +33,7 @@ Product requirements требуют кеширование ответов provid ## Tests - Добавить repository tests для cache hit/miss, set/get roundtrip, invalidate и TTL expiration. +- Добавить tests, проверяющие чтение TTL и Redis connection settings из секции `repository` YAML-конфига. - Использовать Redis test double или изолированный test Redis instance. ## Commands diff --git a/spec/tasks/007_add_observability_correlation.md b/spec/tasks/007_add_observability_correlation.md index 087083f..d37db0e 100644 --- a/spec/tasks/007_add_observability_correlation.md +++ b/spec/tasks/007_add_observability_correlation.md @@ -9,33 +9,39 @@ created: 2026-03-07 Проект требует связать traces, metrics и logs через request correlation (`request_id` и `trace_id`) и добавить manual spans вокруг ключевых операций. ## Goal -Реализовать observability wiring: middleware для `request_id`, propagation structured logging context, OpenTelemetry instrumentation для FastAPI/httpx и manual spans для операций service/provider/cache. +Реализовать observability wiring: middleware для `request_id`, propagation structured logging context с корреляцией по `trace_id`, OpenTelemetry instrumentation для FastAPI/httpx, manual spans для операций service/provider/cache и метрики из `spec/overview.md`. ## Constraints - Все observability concerns держать вне Business Logic. - При добавлении telemetry не вводить business decision-making. - Инструментировать только слои и операции, указанные в `spec/overview.md`. +- Конфигурация telemetry должна читаться из секции `observability` в `.yaml` конфиге. - Не изменять файлы в `spec/`. ## Acceptance criteria - Middleware назначает UUID `request_id` для каждого запроса. - `request_id` добавляется в structured logs через contextvars. +- Логи коррелируются с трассировкой через `trace_id`. - Включена OpenTelemetry instrumentation для FastAPI и httpx. - Есть manual spans для `AggregatorService.get_all_prices`, provider `get_price` и cache operations. - Span attributes включают `provider`, `from_city`, `to_city`, `weight_kg`, `cache_hit`, `tariffs_found` там, где применимо. +- Реализованы и экспортируются метрики: количество запросов, количество ошибок, latency (включая p50/p99), доступность провайдеров. ## Definition of Done - [ ] Реализован middleware корреляции запросов. - [ ] В logging context есть binding `request_id`. - [ ] Реализована автоматическая и manual tracing instrumentation. -- [ ] Observability tests проверяют создание spans и обязательные attributes. +- [ ] Реализованы метрики, соответствующие overview. +- [ ] Observability tests проверяют создание spans, обязательные attributes и метрики. ## Tests - Добавить middleware tests для генерации и propagation `request_id`. - Добавить telemetry tests с in-memory span exporter для проверки names/attributes. - Добавить logging tests, проверяющие наличие `request_id` в log context. +- Добавить tests для проверки экспорта метрик (request count, error count, latency, provider availability). ## Commands - `poetry run pytest tests/controllers/test_middleware_request_id.py -q` - `poetry run pytest tests/observability/test_tracing.py -q` - `poetry run pytest tests/observability/test_logging_context.py -q` +- `poetry run pytest tests/observability/test_metrics.py -q` diff --git a/spec/tasks/008_add_signoz_telegram_alerting.md b/spec/tasks/008_add_signoz_telegram_alerting.md index f380c84..98901f9 100644 --- a/spec/tasks/008_add_signoz_telegram_alerting.md +++ b/spec/tasks/008_add_signoz_telegram_alerting.md @@ -9,22 +9,22 @@ created: 2026-03-07 `spec/overview.md` требует anomaly alerting через цепочку `SigNoz Alert Rules -> Webhook -> Telegram Bot API` с вынесением token в configuration. ## Goal -Добавить configuration и infrastructure artifacts, необходимые для маршрутизации anomaly alerts из SigNoz в Telegram и для соответствия alert thresholds требованиям проекта. +Добавить configuration и infrastructure artifacts, необходимые для маршрутизации anomaly alerts из SigNoz в Telegram и для соответствия alert thresholds требованиям проекта через секцию `alerts` в `.yaml` конфиге. ## Constraints - Alert transport/configuration должны быть отделены от business logic. -- Telegram credentials должны приходить из configuration и не быть hardcoded. +- Telegram credentials должны приходить из секции `alerts` YAML-конфига и не быть hardcoded. - Thresholds должны соответствовать alert conditions из `spec/overview.md`. - Не изменять файлы в `spec/`. ## Acceptance criteria -- Configuration содержит отдельную секцию Alerts с Telegram settings. +- Configuration содержит отдельную секцию `alerts` в `.yaml` конфиге с Telegram settings. - Infrastructure artifact(s) описывают routing от SigNoz alert webhook к Telegram Bot API. - Представлены alert conditions для: - provider 5xx: 5 ошибок за 5 минут - provider p99 latency > 5000ms в течение 10 минут - provider unavailable более 5 минут -- Setup instructions содержат обязательные environment variables и шаги верификации. +- Setup instructions содержат пример секции `alerts` YAML-конфига и шаги верификации. ## Definition of Done - [ ] Реализована schema конфигурации Alerts. @@ -33,7 +33,7 @@ created: 2026-03-07 - [ ] Инструкции валидации исполнимы в local environment. ## Tests -- Добавить config tests для проверки загрузки alert settings и обязательных полей. +- Добавить config tests для проверки загрузки alert settings из секции `alerts` YAML-конфига и обязательных полей. - Добавить tests для alert payload transformation/transport logic, если он реализован в коде. ## Commands