master/tasks.md

План работ: web-python-skelet

Контекст

• Источник требований: AGENTS.md и ADR docs/001-docs/004
• Текущее состояние: в adapter/, domain/, usecase/, repository/, test/ пока только __init__.py
• Отсутствуют рабочие каталоги и файлы из целевой структуры: adapter/config/, adapter/otel/, adapter/di/, adapter/http/fastapi/, config/, main.py
• Ограничения: docs/ и tasks.md не добавлять в git; коммиты не делать; работать по одной задаче
• ADR пока покрывают архитектуру, новые ADR нужны только если по ходу работ изменится решение

Правила выполнения

• Каждую задачу выполнять отдельным заходом, без параллельной реализации
• Каждый субагент отдает diff, список измененных файлов и проверку, но не делает commit
• Если в задаче всплывает архитектурное изменение, остановиться и вынести вопрос на согласование

Очередь задач

T01. Базовый каркас домена и usecase

• Исполнитель: primary-agent (scaffolding)
• Статус: completed
• Зависимости: нет
• Commit required: no
• Scope: создать базовые файлы и контракты в domain/, usecase/, repository/
• Файлы: domain/error.py, domain/user.py, usecase/interface.py, usecase/user.py, repository/user.py
• Критерии приемки: зависимости направлены внутрь; в domain/ и usecase/ нет FastAPI/OTel; есть пример сущности, ошибок, портов и простого usecase

T02. Конфиг из YAML и env

• Субагент: feature-developer
• Статус: completed
• Зависимости: T01
• Commit required: no
• Scope: собрать typed-config слой в adapter/config/ и подготовить базовые yaml-файлы
• Файлы: adapter/config/*, config/app.yaml
• Критерии приемки: конфиг собирается в одну dataclass-структуру; секреты читаются из env; парсинг и валидация не протекают в inner layers

T03. Observability порты и OTel adapter

• Субагент: feature-developer
• Статус: completed
• Зависимости: T01, T02
• Commit required: no
• Scope: реализовать логгер, метрики, трейсинг и bootstrap OTel в adapter/otel/ через интерфейсы из usecase/interface.py
• Файлы: adapter/otel/*, config/otel-collector.yaml
• Критерии приемки: inner layers знают только интерфейсы; OTLP exporter настраивается из конфига; нет кастомного trace middleware

T04. Composition root и lifetime singleton-объектов

• Субагент: feature-developer
• Статус: completed
• Зависимости: T01, T02, T03
• Commit required: no
• Scope: собрать контейнер и startup wiring в adapter/di/
• Файлы: adapter/di/container.py, adapter/di/__init__.py
• Критерии приемки: repository/usecase создаются один раз на старте; контейнер хранит инстансы явно; нет пересоздания на HTTP-запрос

T05. FastAPI adapter как заменяемый web layer

• Субагент: feature-developer
• Статус: completed
• Зависимости: T04
• Commit required: no
• Scope: поднять HTTP adapter в adapter/http/fastapi/ с app factory, lifespan, dependencies, middleware и router /api/v1
• Файлы: adapter/http/fastapi/*, main.py
• Критерии приемки: FastAPI изолирован в adapter-слое; handlers тонкие; request logging и metrics middleware подключены; usecase/repository берутся из контейнера

T06. Локальный runtime и compose-окружение

• Субагент: feature-developer
• Статус: completed
• Зависимости: T02, T03, T05
• Commit required: no
• Scope: добавить контейнерный runtime для сервиса и compose-окружение с OTel и UI для просмотра логов, метрик и трейсов
• Файлы: Dockerfile, docker-compose.yml
• Ограничения: не трогать репозиторный config/app.yaml; docker должен прокидывать свой runtime-config внутрь контейнера; Dockerfile только с двумя стадиями build и run
• Критерии приемки: make compose-build и make compose-up опираются на существующие файлы; сервис поднимается в контейнере; OTel telemetry уходит в dockerized stack; есть UI для просмотра логов, метрик и трейсов; для локального docker-окружения достаточно только Dockerfile и docker-compose.yml

T07. Тесты на lifetimes, config и HTTP smoke

• Субагент: test-engineer
• Статус: pending
• Зависимости: T01, T02, T03, T04, T05, T06
• Commit required: no
• Scope: покрыть тестами ключевые архитектурные гарантии
• Файлы: test/*
• Критерии приемки: есть тест на singleton lifetime для repository/usecase; есть тест merge YAML+env; есть smoke-тест для /api/v1; тесты не тянут FastAPI/OTel в inner layers

T08. Архитектурный и boundary review

• Субагент: code-reviewer
• Статус: pending
• Зависимости: T07
• Commit required: no
• Scope: проверить импорты, соблюдение слоев, startup lifetimes и заменяемость web adapter
• Файлы: весь измененный код
• Критерии приемки: dependency direction не нарушен; FastAPI и OTel не протекают в domain/ и usecase/; замечания сформулированы как точечные правки или подтверждение готовности к review

T09. Конфигурируемый runtime observability

• Субагент: feature-developer
• Статус: completed
• Зависимости: T03, T04, T05
• Commit required: no
• Scope: сделать конфигурируемый runtime observability с настраиваемым sink и форматом логов, плюс отдельными флагами для метрик и трейсов
• Файлы: adapter/config/*, adapter/observability/*, adapter/otel/*, adapter/di/*, adapter/http/fastapi/*, config/app.yaml, при необходимости main.py
• Конфиг: logging.output=stdout|file|otel, logging.format=text|json, logging.file_path=..., metrics.enabled=true|false, tracing.enabled=true|false
• Решение: вынести выбор runtime в отдельный adapter-layer factory; domain/ и usecase/ не менять; для stdout и file поддержать оба формата text и json; logging.file_path использовать только при logging.output=file; при отключенных метриках и трейсах использовать Noop-реализации; OTel runtime поднимать только если нужен хотя бы для одного сигнала
• Критерии приемки: при logging.output=stdout логи идут в stdout в формате text или json по конфигу; при logging.output=file логи пишутся в файл по пути logging.file_path в формате text или json; при logging.output=otel логи уходят в collector; metrics.enabled=false отключает метрики и metrics middleware; tracing.enabled=false отключает FastAPI instrumentation и tracer runtime; DI продолжает отдавать единый runtime через контейнер; внутренние слои по-прежнему знают только порты

T10. ADR: раннее подключение OTel к FastAPI

• Исполнитель: primary-agent (docs)
• Статус: completed
• Зависимости: нет
• Commit required: no
• Scope: зафиксировать правило, что FastAPI OTel instrumentation выполняется до первой сборки middleware_stack
• Файлы: docs/005-fastapi-otel-early-instrumentation.md
• Критерии приемки: ADR занимает 10-20 строк; описаны context, decision, consequences; решение не переписывает историю прошлых ADR

T11. Перенос FastAPI OTel bootstrap в app factory

• Субагент: feature-developer
• Статус: completed
• Зависимости: T10
• Commit required: no
• Scope: перенести создание container, установку FastAPIInstrumentor.instrument_app(...) из lifespan в create_app, оставив в lifespan только shutdown
• Файлы: adapter/http/fastapi/app.py, adapter/http/fastapi/lifespan.py, при необходимости adapter/http/fastapi/dependencies.py
• Ограничения: не использовать ручной rebuild app.middleware_stack; не менять domain/ и usecase/; не добавлять бизнес-логику; сохранить singleton-lifetime container
• Критерии приемки: instrumentation происходит до первой сборки middleware stack; OpenTelemetryMiddleware попадает в runtime stack без workaround; shutdown закрывает instrumentation и runtime один раз; compose-конфиг продолжает работать

T12. Регрессионная проверка HTTP telemetry wiring

• Субагент: test-engineer
• Статус: pending
• Зависимости: T11
• Commit required: no
• Scope: добавить проверку, что раннее instrumentation wiring сохраняется и не требует ручного rebuild middleware stack
• Файлы: test/*
• Ограничения: без реального collector; проверять через ASGI/lifespan или локальные assertions по app runtime; не тянуть FastAPI и OTel в inner-layer тесты
• Критерии приемки: тест подтверждает, что при включенных metrics/tracing OpenTelemetryMiddleware присутствует в runtime stack; тест не зависит от внешнего OTel collector; существующие архитектурные границы не нарушены