Files
mtusi2026lab5/openspec/changes/async-attachments/tasks.md
T
ricoromaandClaude Opus 5.5 ff1a83b6ff feat: process attachments asynchronously with RabbitMQ and a worker
Upload answers 202 after staging, a queued job in PostgreSQL and a broker
confirm; a separate worker publishes the original and a thumbnail with
bounded retries. Adds the job and variant tables, the broker service, the
worker S3 user, cleanup and reconcile support for staging and variants,
the failure stand with broker and worker, bench and driver updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 06:48:20 +03:00

463 lines
43 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Tasks
Как строить — `design.md` (дальше «решение N»), что должно получиться — дельты в
`specs/`. Перед первым файлом слоя прочитать его правило: `service-layer.md`,
`repo-layer.md`, `dto.md`, `infra.md`, `api-layer.md`, `api-contract.md`,
`migrations.md`, `logging.md`, `settings.md`, `run-modes.md`, `docker.md`,
`balancer.md`, `student-tests.md`, `bench.md`.
**Граница коммита.** Группы 1–14 — код, тесты, инструменты и правила: проверяются на
рабочем дереве, агент apply не коммитит и в `evidence/` не пишет. Группа 15 — снятие
evidence и `REPORT.md`: её запускает основная сессия после коммита групп 1–14, на
закоммиченном коде (`bench.md`, «Измеренное состояние — commit»).
**Шага оператора нет.** `make env_setup` сам дописывает секреты брокера и ключи worker в
существующий `.env`, значения не печатает. Руками `.env` не читать и не править.
**Ожидаемо красное**, остальное разбирается по AGENTS.md:
- `make test` и сценарии вложений — до конца группы 9: API ещё не на 202 или worker нет;
- между задачами 10.1 и 10.9 — сверка покрытия: «marker points to unknown scenario»; sync
раньше тестов дал бы обратное, «no test and no exclusion»;
- `test_exclusion_evidence_exists` — до группы 15, а по файлам старых исключений — до
последнего шага всего прогона (`QUESTIONS.md`, «Перенос из лабы 4»). В группах 1–14 это не
регрессия, но падать он должен только по `missing_evidence`.
Решения по ходу работы — design, «Уточнения apply»; вопросы и решения без пользователя —
`QUESTIONS.md`, `## async-attachments`; дефект, найденный попутно, — `KNOWN_ISSUES.md`.
## 1. Зависимости, настройки, общие типы
- [x] 1.1 Зависимости: `aio-pika>=10.2.1,<11` в основной группе, `pillow>=13,<14` из dev-группы
в основную, `uv lock`.
Проверка: `uv lock --check`; в `uv.lock` aio-pika 10.2.1, aiormq 7.2.4, pamqp 4.0.1, Pillow
13.0.0; `uv tree --no-dev` содержит обе.
- [x] 1.2 Настройки по решению 13 и дельте `service-configuration`:
- классы `Broker` и `Worker` в `src/config/settings.py`, пароль — `SecretStr`, как у `[s3]`;
- `graceful_shutdown_seconds` не больше 9, сроки больше нуля, `concurrency` и `max_attempts`
не меньше 1;
- строки с комментариями единиц в `config_example.toml`.
Проверка: `uv run python -c "from src.config import settings; print(settings.worker)"` —
значения по умолчанию; `BROKER__PUBLISH_TIMEOUT_SECONDS=0` и `=abc`, `WORKER__CONCURRENCY=0`,
`WORKER__MAX_ATTEMPTS=abc`, `WORKER__GRACEFUL_SHUTDOWN_SECONDS=10` — ошибка проверки настроек
называет поле.
- [x] 1.3 Секреты и порты по решению 13:
- `.env.example`: блок брокера (`RABBITMQ_DEFAULT_USER`, `RABBITMQ_DEFAULT_PASS` пустой,
`RABBITMQ_HOST`, `RABBITMQ_PORT`, `RABBITMQ_OUT_PORT`, мосты `BROKER__*`), ключи
`S3_WORKER_*`, шапка с сопоставлением имён skeleton `BROKER_URL_FILE`, `WORKER_CONCURRENCY`,
`JOB_MAX_ATTEMPTS`, `JOB_TIMEOUT_SECONDS`, `STAGING_RETENTION_SECONDS`;
- `Makefile`: `ENV_SECRETS`, `ENV_FILLED`.
Проверка: подстановки рецепта `env_setup` дважды в поток, а не в файл: новые секреты непустые
и различаются, сравнение по хэшу, значения не печатаются. `make env_setup` на рабочем каталоге
печатает только имена дописанных переменных, повтор ничего не дописывает.
- [x] 1.4 Общие типы:
- `src/schemas/enums/attachment.py`: `AttachmentStatus` — ещё `queued`, `processing`, `failed`;
новые `AttachmentJobState`, `AttachmentVariantName`, `AttachmentErrorCode`,
`AttachmentJobReason`;
- `src/utils/constants.py`: `ATTACHMENT_PIPELINE_VERSION`, `ATTACHMENT_JOB_TYPE`,
`ATTACHMENT_JOB_SCHEMA_VERSION`, `ATTACHMENT_STAGING_PREFIX`, `THUMBNAIL_MAX_SIDE`,
`THUMBNAIL_JPEG_QUALITY`, имя очереди;
- `src/core/exceptions`: `AttachmentNotReady` и `AttachmentFailed` (409 в `DOMAIN_ERRORS`),
`BrokerUnavailable(ServiceUnavailable)`.
Проверка: `make lint`; `uv run python -c "import src.api.errors"`.
## 2. Схема
- [x] 2.1 Модели по решению 1: новые колонки и CHECK `Attachment`, `AttachmentJob`,
`AttachmentVariant` в `src/infra/db/models/attachment.py`.
Проверка: `make lint`; совпадение со схемой — задача 2.2.
- [x] 2.2 Ревизия поверх `5c3e1f0a9b7d` руками по решению 1 и `migrations.md`: первой строкой
`SET LOCAL lock_timeout = '2s'`, колонки, замена CHECK статуса и новый CHECK `error_code` с
`NOT VALID`, две таблицы, `downgrade`.
Проверка на временной базе (`createdb` в контейнере `postgres`, `DATABASE__NAME` в окружении,
после — `DROP DATABASE`):
- `upgrade` с нуля, `uv run alembic check` пуст, повтор ничего не меняет, `downgrade -1`,
`upgrade`;
- на базе со строками `pending` и `ready`: `status` прежний, `pg_constraint.convalidated` у
обоих CHECK — false;
- второе задание той же версии, второй вариант того же имени, `error_code` у не `failed`,
`failed` без кода — нарушение ограничения; удаление вложения с заданием — нарушение внешнего
ключа;
- транзакция держит `attachments` дольше 2 с: миграция падает без изменений, повтор проходит.
## 3. DTO и repo
- [x] 3.1 DTO по `dto.md`: `AttachmentFullDTO` — `staging_key`, `error_code`, `variants` кортежем
по умолчанию; `AttachmentInListDTO.staging_key`; `AttachmentJobDTO`, `AttachmentVariantDTO`;
`__init__.py`.
Проверка: `make lint`.
- [x] 3.2 `src/core/repos/attachment.py` по решениям 1–3 и `repo-layer.md`, одно выражение на
функцию, `updated_at` через `greatest`:
- `_ATTACHMENT_COLUMNS`, `_STALE_COLUMNS`, вставка со `staging_key`;
- `mark_ready` заменяется на `mark_queued` с теми же условиями (`pending`, `updated_at =
created_at`);
- новые: возврат в `pending`, перевод в `processing` и обратно в `queued`, условная фиксация
`ready` и `failed` с кодом.
Проверка: `make lint`; поведение — группы 6–8 и 10.
- [x] 3.3 `src/core/repos/attachment_job.py` по решениям 1, 3, 7: вставка, чтение с `FOR UPDATE`,
чтение по вложению, начало попытки, возврат в `queued` с условием своей попытки, завершение,
отметка `published_at`, условное удаление (`state = 'queued' AND attempt = 0`).
Проверка: `make lint`; поведение — группы 6–7 и 10.
- [x] 3.4 `src/core/repos/attachment_variant.py`: вставка `ON CONFLICT DO NOTHING` по ключу эффекта,
варианты вложения, один вариант по имени.
Проверка: `make lint`; поведение — группы 6–7 и 10.
- [x] 3.5 `src/core/repos/attachment_object.py` по решению 1: `staging_key`, `variant_key`,
`parse_variant_key`; запись и чтение остаются по ключу.
Проверка: разовый вызов `parse_variant_key`: свой `id` и `v1-thumbnail` — `id`, верхний регистр,
версия 0, неизвестное имя, `original`, чужой префикс — `None`; `make lint`.
## 4. Брокер: сервис и клиент
- [x] 4.1 Сервис `rabbitmq` по решению 4 и `docker.md`:
- `docker-compose.yml`: образ с тегом и digest из решения 4, `hostname`, volume, порт, алиас,
healthcheck, лимиты, `stop_grace_period`, якорь `x-broker-env`;
- `infra/rabbitmq/rabbitmq.conf`, монтирование read-only длинной записью;
- цели `start_broker`, `stop_broker`.
Проверка на рабочем стенде:
- `docker buildx imagetools inspect rabbitmq:4.3.7` — тот же digest;
- `make start_broker` — `healthy`; `rabbitmqctl -q status --formatter json` — предел памяти
400 МиБ; `docker port` — только AMQP на `127.0.0.1`;
- `docker compose stop rabbitmq` — код 0 раньше срока;
- `docker compose up -d --force-recreate rabbitmq` — `healthy`, имя узла `rabbit@rabbitmq` прежнее; очередь с
сообщениями после пересоздания — тест `test_broker_recreated`.
- [x] 4.2 Клиент по решению 5: `src/infra/broker/client.py` (`JobPublisher`, `JobConsumer`, имя
очереди из namespace, сброс соединения после любой ошибки), `aio_pika` и `aiormq` на `WARNING` в
`src/infra/logger.py`, записи журнала по решению 18.
Проверка — разовый скрипт в scratchpad против брокера стенда:
- публикация с подтверждением, очередь `durable`, сообщение persistent;
- нет маршрута при удалённой очереди и `docker compose stop rabbitmq` — `BrokerUnavailable`
быстрее срока; `docker pause` — не позже срока с запасом;
- после возврата брокера следующая публикация проходит на том же объекте издателя;
- потребитель получает сообщение, `prefetch_count` соблюдён, обрыв завершает его итератор;
- значения пароля в выводе нет (сравнение с `.env` без печати).
- [x] 4.3 Глобал API по решению 5: `src/infra/broker/instance.py`, `src/api/dependencies.py`,
закрытие в lifespan `src/main.py`, поля брокера в «Started API».
Проверка: `make lint`; процесс API стартует и отвечает `/health/ready` при остановленном
брокере; в «Started API» адрес, очередь и срок, пароля нет.
## 5. Thumbnail
- [x] 5.1 `src/utils/thumbnail.py` по решению 8.
Проверка — разовый скрипт в scratchpad с генераторами `student-tests/images.py`:
- 320 × 200 → 256 × 160, 100 × 50 и 256 × 256 без изменений, 1000 × 601 → 256 × 153, 601 × 1000 →
153 × 256, 5000 × 10 → 256 × 1, 10 × 5000 → 1 × 256;
- orientation 1–8: размеры и пиксели как у `ImageOps.exif_transpose`;
- alpha, палитра с tRNS, LA — белый на месте прозрачности;
- все `png_variants()` и `jpeg_variants()` — настоящий JPEG; точность SOF 12 — `InvalidImage`;
- пик RSS PNG RGBA 8000 × 5000 в контейнере образа с лимитом 1 ГБ — не больше ~350 МиБ.
`grep -rn "PIL" src` — только этот модуль; его импортирует только сервис обработки.
## 6. API
- [x] 6.1 `AttachmentService` по решению 3: издатель в конструкторе и зависимости; `_store` пишет в
staging; `_mark_ready` → перевод в `queued` с заданием и той же компенсацией; публикация, отметка
`published_at`, транзакция отмены; места загрузки держатся до ответа; записи журнала по решению 18,
`filename` в них нет.
Проверка: `make lint`; один PNG против консольного API и брокера стенда — 202, строка `queued`,
объект только в staging, одно сообщение; сбои — тесты группы 10.
- [x] 6.2 Чтение по решению 9: `pending` — 404, остальные — 200, варианты только у `ready`;
`open_content(variant=…)`: статус не `ready` — `AttachmentNotReady` без обращения к S3, нет варианта
— 404, нет объекта варианта или другой размер — 500 с записью `error`; ветки оригинала и `lost_at`
прежние.
Проверка: `make lint`; поведение — тесты группы 10.
- [x] 6.3 `MessageService` по решению 9: неизвестное, чужое и `pending` — 404 до ключа; `failed` —
после захвата ключа: новый ключ — откат и `AttachmentFailed`, занятый — прежняя ветка повтора.
Проверка: `make lint`; поведение — тесты группы 10, в том числе «Повтор после failed вложения».
- [x] 6.4 HTTP по решению 9: `status_code=202`, `variant` как `Literal` четырёх значений, модель
`Attachment` с `status`, `variants`, `error_code`, модель варианта, `DOMAIN_ERRORS`, версия `1.5.0`
в `create_app`.
Проверка: `/openapi.json` запущенного API против `contracts/openapi.json`: поля и обязательность
`Attachment` и `Variant`, перечисления, код успеха загрузки, `info.version`.
## 7. Worker
- [x] 7.1 Сообщение задания: pydantic-модель `src/schemas/jobs/attachment.py` (решение 7), сборка тела
из строки задания и номера попытки. Правило `dto.md` дополняется в задаче 13.1.
Проверка: тело по `contracts/jobs.schema.json` (`jsonschema` dev-группы); лишнее поле, чужая
`schema_version`, `attempt` 0, неверный `traceparent` — ошибка разбора; `traceparent` и `tracestate`
по схеме проходят.
- [x] 7.2 `AttachmentProcessingService` в `src/core/services/attachment_processing.py` по решениям 2 и 7:
разбор, таблица claim, обработка под сроком, фиксация `ready` с вариантом одной транзакцией, временные и
постоянные ошибки, недоступный PostgreSQL, исход `ACK` или `REQUEUE`; порядок блокировок — задание, затем
вложение; журнал по дельте `service-logging`.
Проверка: `make lint`; поведение — тесты группы 10.
- [x] 7.3 Процесс `src/worker/` по решению 6: `__main__.py` (`early_stop.install("worker")`, «Invalid
worker settings», код 2, `os._exit`), `main.py` (сигналы, свои engine, S3 и клиенты брокера, цикл
переподключения, ограниченная конкуренция, контекст `request_id`, остановка в срок, «Started worker» и
«Stopped worker»).
Проверка без стенда: `WORKER__CONCURRENCY=0 uv run python -m src.worker` — код 2, запись называет поле
без значений; `make lint`. На стенде — задача 9.6.
## 8. Уборщик и сверка
- [x] 8.1 Уборщик по решению 11: `staging_key` в выборках; `remove_stale_pending` удаляет `staging_key or
object_key`, запись журнала называет удалённый ключ.
Проверка: `make lint`; разовый `python -m src.cleaner --once` на стенде после 9.6 — код 0; поведение —
тесты группы 10. Профиль `reconcile` со строками прежнего вида — задача 11.2.
- [x] 8.2 Сверка по решению 11: разбор ключа варианта в `_list_objects`, `id` вариантов в выборке страницы,
ветка варианта в `_classify_object` (строка есть — пропуск, нет — объект без метаданных, свежий — свежий);
находка зависшей загрузки называет ключ staging; `is_own_key` по-прежнему смотрит `object_key`.
Проверка: `make lint`; на стенде обе стратегии без `--apply` не называют объекты вариантов; поведение —
тесты группы 10.
## 9. Стенд
- [x] 9.1 `docker-compose.yml` по решениям 6 и 10: сервис `worker`, `x-broker-env` и `depends_on` брокера у
`api`, ключи `S3_WORKER_*` у `s3-bootstrap`.
Проверка: `docker compose --env-file .env config --quiet`; `docker compose config` — секреты по сервисам
по дельте `container-run`: пароль брокера только у `rabbitmq`, `api`, `worker`, ключи worker только у
`s3-bootstrap` и `worker`, у `worker` нет пароля Valkey и ключей API и уборщика.
- [x] 9.2 `infra/s3/bootstrap.sh` по решению 12: `apply_user worker worker-objects`, политика, ожидание ключа,
проверки `apply` и `check`, отказ на удаление и список; `driver.py s3-check` — строки ключа worker.
Проверка на временном проекте compose (`-p` своё имя, `--env-file` — файл в scratchpad, порты свободные; без
`down -v`: созданные volumes перечислить в отчёте и оставить основной сессии): первый запуск — «user worker
created»; повтор дважды — «exists», код 0; новый секрет — ключ пересоздан, прежний отклонён; все запреты
сценария «Запрещённые операции worker» — 403.
- [x] 9.3 `Makefile`: `run_worker` (рецепт с `@`, ключи worker в окружение процесса), `run_dev` и `test_isolated`
зависят от `start_broker`, текст `wipe_data` называет volume брокера, комментарии стенда.
Проверка: `make run_worker` не печатает значения ключей; `make run_dev` и `make run_worker` — загрузка становится
`ready`, «Started worker» называет адрес `127.0.0.1:$RABBITMQ_OUT_PORT`.
- [x] 9.4 `scripts/restart.sh` по решению 14 (брокер в `restart` и `up --wait --no-recreate`), шапка; комментарии
`scripts/rolling-update.sh` и `infra/haproxy/haproxy.cfg` — 29 с и 76 с.
Проверка: `scripts/restart.sh` на стенде — код 0 не дольше 90 с, у брокера и реплик те же ID и новый `StartedAt`,
у worker и уборщика прежний `StartedAt`, `RestartCount` 0; `haproxy -c` закреплённым образом.
- [x] 9.5 CI по решению 14: `.github/ci/compose.yml` (`rabbitmq`, `worker`), `.github/ci/stand-env.sh`
(`CI_RABBITMQ_CONF`); шаги workflow не меняются.
Проверка: `COMPOSE_FILE=docker-compose.yml:.github/ci/compose.yml`, `CI_IMAGE_TAG` и `. .github/ci/stand-env.sh`,
`docker compose config --quiet` — без ошибок; в `docker compose config` у `rabbitmq` и `worker` нет `ports` и bind
mount, у `rabbitmq` есть volume данных, а образ `worker` — тег прогона.
- [x] 9.6 Рабочий стенд на рабочем дереве: `make run_docker`.
Проверка:
- `docker compose ps` — две реплики, уборщик, worker, брокер и S3 в рабочем состоянии, bootstrap с кодом 0;
- `make test` — `PASS: lab5`;
- журнал worker: «Started worker» со всеми значениями, затем запись о готовом вложении; `filename` smoke в журнале
нет;
- `docker compose stop worker` — быстрее 10 с, код 0, «Stopped worker»; `docker compose up -d --no-deps worker` и сразу
`stop` — код 0 и «Stopped worker before startup»;
- `/proc/1/cmdline` контейнера worker — `python -m src.worker`, проверки здоровья нет; в `/proc/1/maps` реплики API нет
`_imaging`;
- `make s3_check` — код 0, строки ключа worker на месте.
## 10. Тесты
- [x] 10.1 Клиент и генераторы по решению 15: `api_client.py` (`upload` — 202 и снимок `queued`, `wait_attachment`,
`upload_ready`, скачивание варианта), `contract.py` (код 202, схема `Variant`, `assert_content` для варианта),
`images.py` (JPEG с точностью 12 и с EXIF orientation, половины цветов, PNG с прозрачной половиной и палитрой с tRNS,
большой PNG RGBA).
Проверка: `make lint`; `wait_attachment` при остановленном worker падает и называет `queued` (сценарий «Worker не
работает»).
- [x] 10.2 Прежние сценарии вложений во всех модулях обычного набора (`test_attachments.py`, `test_messages.py`,
`test_idempotency.py`, `test_rubric.py`, `test_data_storage.py`, `test_api_conventions.py`, `test_load_balancing.py` и другие, где
есть загрузка): 202 и ожидание `ready` там, где нужны байты или итог; метаданные сравниваются по полям оригинала и отдельно по полям состояния; проверки не ослабляются и не
пропускаются (спек `student-tests`, «Готовность вложения в тестах»).
Проверка: `make student_test` через LB — прежние сценарии зелёные, красное только из шапки.
- [x] 10.3 Новый модуль `test_attachment_processing.py` и новые тесты обычного набора по таблице «Покрытие сценариев» design:
`test_attachment_becomes_ready`, `test_thumbnail_*`, `test_download_thumbnail`, `test_missing_variant`,
`test_variant_outsider`, `test_message_with_failed_attachment`, `test_accepted_attachment_visible_on_other_replica`;
маркеры `spec` дословно по сценариям дельт.
Проверка: `uv run pytest student-tests/test_attachment_processing.py` с `BASE_URL` стенда; thumbnail скачан и его настоящие
размеры, `sha256` и `size_bytes` сверены с метаданными варианта.
- [x] 10.4 Hook `student-tests/fault_hook.py` по решению 15 и дельте `student-tests`: действия брокера и worker, `worker-state`,
`queue-state`, `peek-job`, `publish-job`, `delete-queue`, `job`, `staging-ids`, `variant-object-count`; `put-object` и
`delete-object` под префиксами вложений и staging; режимы `fail-attachments` на `queued` и `→ ready`; docstring. Ключи S3 и
пароль брокера hook не получает и не печатает.
Проверка: разбор `fs.tree` на образце (`original` и `v1-thumbnail` в одном каталоге, staging отдельно); hook отказывается работать
с проектом рабочего стенда; поведение действий — тесты 10.6 и 10.7.
- [x] 10.5 Стенд отказов по решению 15: `failures.compose.yml` (`rabbitmq` без порта, `worker` с короткими сроками, `restart: "no"`),
`run_failures.py` (брокер в `up --wait`, worker после bootstrap, `FAULT_WORKER_*`, журнал worker при падении, строка `start worker`,
уборка), docstring.
Проверка: `make failure_checks FAULT_ARGS='-k health'` — код 0, строка worker в выводе, стенд и volumes удалены; `-k no_such_test`
— ненулевой код, журналы API, уборщика и worker напечатаны, стенд удалён.
- [x] 10.6 Прежние проверки отказов `test_failures.py` по решению 15 и дельтам `attachments` и `storage-consistency`:
- `upload_ready` и множества `id` там, где нужен готовый объект;
- `test_ready_failure_compensated` → `test_queued_failure_compensated`, `test_ready_commit_outcome_unknown` →
`test_queued_commit_outcome_unknown`; `test_killed_between_put_and_ready`, `test_upload_outlives_grace`,
`test_cleaner_failure_after_object_delete` — на `queued` и `staging-ids`;
- тесты сверки: зависшая загрузка — объект в staging, готовые вложения — с объектами вариантов.
Проверка: `make failure_checks FAULT_ARGS='-k "attachment or object_storage or cleaner or reconcile or upload"'` — код 0.
- [x] 10.7 Новые проверки отказов по таблице «Покрытие сценариев» design: сценарии `attachment-processing`, `message-broker`,
`messages`, `idempotency`, `health`, `attachments`, `storage-consistency`, а также `test_worker_stop_during_processing` (спек
`graceful-shutdown` в докстринге). Отказы — в `with outage(...)`, worker запускается в `finally`, триггеры снимаются в `finally`.
Сообщение проверяется по `contracts/jobs.schema.json`.
Проверка: полный `make failure_checks` — код 0, сводка журнала PostgreSQL без признаков аварии, стенд удалён, у контейнеров рабочего
стенда прежний `StartedAt`; время прогона — в design, «Уточнения apply».
- [x] 10.8 `make test_isolated` по решению 15: `run_isolated.py` — контейнер `<проект>-test-worker` с той же подменой базы, журналы
обоих контейнеров, удаление очереди в начале и в конце, `KEEP_TEST_DB` печатает очередь; проверка имени очереди — как у префикса,
иначе код 2.
Проверка: `make test_isolated` при работающем стенде — код 0; после него нет контейнеров, базы, объектов и очереди временной базы, а
сообщения и счётчики рабочей очереди и `StartedAt` рабочего стенда прежние; прерывание Ctrl+C — уборка выполнена; `KEEP_TEST_DB=1` —
остаётся и печатается.
- [x] 10.9 Сверка покрытия:
- `attachment-processing` и `message-broker` в `CAPABILITIES`, записи `EXCLUDED` с причинами и способом проверки по design (`message-broker`
«Сервис брокера запущен», «Предел памяти брокера», «Остановка брокера», «Очереди разных баз разделены», `data-storage` «Ограничения обработки
в схеме»);
- sync всех 18 дельт в основные спеки (`/opsx:sync`): сверка читает только `openspec/specs/`.
Проверка: `openspec validate --specs`; `make student_test` — сверка без «no test and no exclusion» и «unknown scenario», красное только
`missing_evidence`; итог называет число сценариев проверок отказов с новыми.
- [x] 10.10 Тесты ловят нарушение: временные регрессии, каждая откатывается и не попадает в рабочее дерево:
- ack до фиксации результата → `test_worker_killed_during_processing` красный;
- публикация без подтверждения → `test_upload_with_broker_stopped` или `test_upload_with_broker_paused` красный;
- очередь не `durable` → `test_broker_restart_keeps_job` красный;
- `Image.thumbnail` вместо своего расчёта → `test_thumbnail_rounding` красный;
- `failed` до захвата ключа → `test_replay_after_attachment_failed` красный;
- сверка без ветки варианта → `test_reconcile_variant_objects` красный.
Проверка: итог по каждой регрессии — в design, «Уточнения apply»; `git diff` после откатов совпадает с кодом до них.
## 11. `bench/`
- [x] 11.1 Стенд по решению 16: `bench.compose.yml` (`rabbitmq`, `worker`, лимиты), `bench.env`, `compose_env` (пароль брокера, ключи worker), поля
`Profile`, `SECRET_ENV_MARKS` покрывает новые имена, старт брокера в профиле загрузок, новый volume брокера на прогон, остатки и уборка.
Проверка: `uv run python bench/uploads.py --selftest`; `make bench_quick` — код 0, брокер и worker не запущены, `stand.app_env` без секретов.
- [x] 11.2 Профиль загрузок по решению 16: `k6/uploads.js`, `uploads.py` (`s201` — код успеха варианта, столбец `success_code` в конце, раздел паспорта),
`run.py`, тексты сводки.
Проверка: `make bench_uploads_quick` — код 0, успешные загрузки — 202, пик памяти реплики и 429 — в тех же границах, что у прежних сценариев спека;
`make bench_reconcile_quick` — код 0, зависшие строки прежнего вида убраны: сверка моделей сошлась. Метки `quick-*` в git не идут.
## 12. Драйвер скилла `run-mtusi-messenger`
- [x] 12.1 Прежние команды по решению 17: `start` поднимает брокер и worker, `upload`, `download`, `flow`, `attachment-failover`, `attachment-storage`,
`upload-consistency`, `reconcile-*`, `s3-idle` — 202 и ожидание `ready`; заглушка реплики `lb-upload-timeouts` — 202; `attachment-storage` — ещё пробы
ограничений обработки в откатываемой транзакции.
Проверка: каждая из этих команд на рабочем стенде — код 0; `driver.py lb-upload-timeouts` — пять случаев с 202.
- [x] 12.2 Новые команды по решению 17: `defense-scenario`, `broker-check [--require-test-queue]`, `worker-process`; раздел в `SKILL.md`: шаги, что
проверяется, коды выхода, gotchas.
Проверка:
- `defense-scenario` на рабочем стенде — код 0, вывод с шагами, кодами, `id` и `StartedAt` до и после, токенов и секретов нет;
- прерывание сигналом посреди сценария — worker запущен, код ненулевой;
- `broker-check`, `worker-process` — код 0; отрицательная: `broker-check --require-test-queue` без прогона на временной базе — код 1;
- `ruff format --check` драйвера.
## 13. Правила и карта кода
- [x] 13.1 Правила по решениям:
- новое `.claude/rules/worker.md` с `paths` (`src/worker/**`, сервис обработки, `thumbnail.py`), строка в `AGENTS.md`, «Где лежат инструкции»;
- `api-contract.md` — 202, 409, 404, `attachment_ids`; `api-layer.md` — параметр `variant`;
- `service-layer.md`, `repo-layer.md`, `dto.md` (модель сообщения), `infra.md` (`broker/`), `migrations.md`, `logging.md`, `settings.md`,
`run-modes.md`, `docker.md`, `balancer.md` (29 с и 76 с, порядок обновления), `student-tests.md` (hook, модуль, ожидание `ready`, время прогона),
`bench.md`.
Проверка: `grep -rn "201 Attachment\|mark_ready\|Pillow — только dev" .claude AGENTS.md` — только верные упоминания; `make lint`.
- [x] 13.2 `AGENTS.md`: текущий статус, правила лабы 5, таблица важных файлов и команд, карта кода (`src/worker/`, `src/infra/broker/`, сервис обработки,
`thumbnail.py`, `infra/rabbitmq/`, новые модули и файлы тестов), время `make failure_checks`. `KNOWN_ISSUES.md` — разрыв COMMIT и publish до
`pipeline-reliability`, смесь версий при замене. `QUESTIONS.md` — решения, принятые в apply.
Проверка: каждый новый файл `git status` назван в карте кода или таблице; `make lint`, `make check`.
## 14. Регресс на рабочем дереве
- [x] 14.1 Смесь версий и откат по Migration Plan design на рабочем стенде: `docker compose stop worker cleaner`, `make rolling_update COMMIT=cc33a03 MIGRATE=0`,
затем вперёд: `make rolling_update`, `docker compose up -d --no-deps cleaner worker`. Первое обновление с прежней версии под нагрузкой показывает
`make bench_rollout_quick` (задача 14.3).
Проверка: на прежнем образе сообщения и история — 200, загрузка — 201 `ready`, чтение вложения в новом статусе — 500 (названное ограничение); после возврата на
текущий код `lb_stats` без ручных состояний, новые вложения становятся `ready`, вложение прежнего образа — 200, `variants` пуст, `variant=thumbnail` — 404, сверка без
расхождений по нему.
- [x] 14.2 Рабочий стенд:
- `make test` — `PASS: lab5`, `make validate`, `make check`;
- `make student_test` через LB — красное только `missing_evidence`;
- `make run_dev` с `make run_worker` и `EXPECT_REPLICAS=1 make student_test` — те же итоги, кроме тестов реплик;
- `make test_isolated`, полный `make failure_checks`;
- `make test-persistence ACTION_SCRIPT=scripts/restart.sh`;
- `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` дважды (`stop`, `STOP_MODE=kill`) с `make replicas` между ними;
- `make s3_check`, `make reconcile` — код 0;
- `driver.py --port <LB> defense-scenario`;
- `make wipe_data` не выполнять: текст запроса и `docker compose config --volumes` проверить чтением.
- [x] 14.3 Регресс `bench/`: `make bench_quick`, `make bench_failover_quick`, `make bench_rollout_quick` (обе фазы образов, новая миграция под нагрузкой без
ошибок), `make bench_restore_quick`, `make bench_uploads_quick`, `make bench_reconcile_quick` — код 0.
- [x] 14.4 Сборка из чистого дерева: команда `git ls-files -z -co --exclude-standard | tar …` из `docker.md`; в образе импорт Pillow и aio-pika, версии как в
`uv.lock`, `uv` и компиляторов нет. `make lint`, `openspec validate async-attachments --strict`, `openspec validate --specs`.
- [x] 14.5 Отчёт apply для основной сессии: `git status`, `git diff --stat`, предложенное сообщение коммита, созданные пробами volumes, что осталось красным и
почему. Агент останавливается здесь: коммит и группу 15 выполняет основная сессия.
## 15. Evidence и отчёт (после коммита, основная сессия)
Снимать на закоммиченном коде: рабочий стенд собран из `HEAD` (`make run_docker`), рабочее дерево чистое, в шапке каждого файла команда, дата, commit и стенд. Без
токенов, паролей, ключей и секретов.
- [ ] 15.1 Коммит кода групп 1–14 на ветке `feat/async-attachments`, стенд на этом commit: `make run_docker`, `make replicas`.
Проверка: `git status` чист; `docker compose ps` — как в задаче 9.6; `make test` — `PASS: lab5`.
- [ ] 15.2 Проверки и исключения сверки:
- `evidence/attachments/defense.md` — `driver.py --port <LB> defense-scenario`;
- `evidence/broker/stand.md` — `driver.py --port <LB> broker-check`;
- `evidence/broker/isolated.md` — `make test_isolated KEEP_TEST_DB=1`, `broker-check --require-test-queue`, затем `make test_isolated`;
- `evidence/attachments/storage.md` — `driver.py --port <LB> attachment-storage`, с пробами ограничений обработки;
- `evidence/attachments/failover.md` — `driver.py --port <LB> attachment-failover`;
- `evidence/attachments/consistency.md` — `driver.py --port <LB> upload-consistency`;
- `evidence/replicas/test-persistence.md` — `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, контейнеры и `StartedAt` до и после.
Проверка: `test_exclusion_evidence_exists` называет только файлы старых исключений последнего шага прогона; в `broker/isolated.md` очередь есть после первого прогона и
нет после второго.
- [ ] 15.3 Процесс, ключи, журнал, схема:
- `evidence/worker/process.md` — `driver.py --port <LB> worker-process`: PID 1, лимиты, остановка, неверные `WORKER__*`, рестарт хранилищ, значения по умолчанию и
подмена окружением;
- `evidence/worker/logs.md` — журнал готового и `failed` вложения одного `request_id`, запись `error` сообщения не по схеме, `filename` и секретов нет;
- `evidence/s3/worker-key.md` — `make s3_check` и строки ключа worker;
- `evidence/migrations/async-attachments.md` — проба задачи 2.2, откат на образ `cc33a03` и возврат задачи 14.1;
- `evidence/uploads/lb-timeouts.md` — `driver.py lb-upload-timeouts`.
Проверка: `grep` значений секретов из `.env` по `evidence/` пуст (значения не печатаются).
- [ ] 15.4 Прогоны наборов на этом commit: `evidence/tests/student-test-lb.md` (`make student_test` через LB), `evidence/tests/test-isolated.md`,
`evidence/tests/failure-checks.md` (полный `make failure_checks`, число проверок и время), метка `make bench_rollout ROLLOUT_LABEL=async-attachments`.
Проверка: числа в файлах совпадают с выводом команд; красное только `missing_evidence` по файлам последнего шага прогона.
- [ ] 15.5 `REPORT.md`:
- архитектура стенда с брокером и worker, таблица ролей и сумма лимитов, расчёт соединений PostgreSQL;
- запуск из чистого clone двумя способами, `make run_worker`;
- сопоставление имён skeleton `BROKER_URL_FILE`, `WORKER_CONCURRENCY`, `JOB_MAX_ATTEMPTS`, `JOB_TIMEOUT_SECONDS`, `STAGING_RETENTION_SECONDS`;
- таблица критериев уровня 3 с командой, наблюдением и файлом;
- критичные и некритичные зависимости `/health/ready` с причинами, поведение при отказе брокера;
- разрыв COMMIT и publish и окна отказа (решение 3), что закрывает `pipeline-reliability`;
- ограничения из спеков: зависший worker и срок подтверждения брокера, постоянная пауза повтора, staging после `ready` и у `failed`, staging и конечный префикс на одном сервере
S3, объект staging при заморозке API, смесь версий при замене и новые статусы, прерванное остановкой задание, сверка не проверяет объекты вариантов и staging, искажения данных
скана JPEG, цепочка LB 76 с с формулой;
- ответы на вопросы защиты `README.md`, порядок сценария защиты и ссылка на `evidence/attachments/defense.md`;
- вопросы преподавателю из `QUESTIONS.md`, `## async-attachments`, в разделе «Открытые вопросы преподавателю».
Проверка: у каждой новой строки таблицы доказательств есть команда, наблюдение и файл; `make lint`, `make check`, `openspec validate async-attachments --strict`.
- [ ] 15.6 Коммит evidence и `REPORT.md` основной сессией. Проверка: `git status` чист; `git log -2` — commit кода назван в шапках файлов evidence.