43 KiB
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. Зависимости, настройки, общие типы
-
1.1 Зависимости:
aio-pika>=10.2.1,<11в основной группе,pillow>=13,<14из dev-группы в основную,uv lock.Проверка:
uv lock --check; вuv.lockaio-pika 10.2.1, aiormq 7.2.4, pamqp 4.0.1, Pillow 13.0.0;uv tree --no-devсодержит обе. -
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— ошибка проверки настроек называет поле. - классы
-
1.3 Секреты и порты по решению 13:
.env.example: блок брокера (RABBITMQ_DEFAULT_USER,RABBITMQ_DEFAULT_PASSпустой,RABBITMQ_HOST,RABBITMQ_PORT,RABBITMQ_OUT_PORT, мостыBROKER__*), ключиS3_WORKER_*, шапка с сопоставлением имён skeletonBROKER_URL_FILE,WORKER_CONCURRENCY,JOB_MAX_ATTEMPTS,JOB_TIMEOUT_SECONDS,STAGING_RETENTION_SECONDS;Makefile:ENV_SECRETS,ENV_FILLED.
Проверка: подстановки рецепта
env_setupдважды в поток, а не в файл: новые секреты непустые и различаются, сравнение по хэшу, значения не печатаются.make env_setupна рабочем каталоге печатает только имена дописанных переменных, повтор ничего не дописывает. -
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. Схема
-
2.1 Модели по решению 1: новые колонки и CHECK
Attachment,AttachmentJob,AttachmentVariantвsrc/infra/db/models/attachment.py.Проверка:
make lint; совпадение со схемой — задача 2.2. -
2.2 Ревизия поверх
5c3e1f0a9b7dруками по решению 1 иmigrations.md: первой строкойSET LOCAL lock_timeout = '2s', колонки, замена CHECK статуса и новый CHECKerror_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
-
3.1 DTO по
dto.md:AttachmentFullDTO—staging_key,error_code,variantsкортежем по умолчанию;AttachmentInListDTO.staging_key;AttachmentJobDTO,AttachmentVariantDTO;__init__.py.Проверка:
make lint. -
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. -
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. -
3.4
src/core/repos/attachment_variant.py: вставкаON CONFLICT DO NOTHINGпо ключу эффекта, варианты вложения, один вариант по имени.Проверка:
make lint; поведение — группы 6–7 и 10. -
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. Брокер: сервис и клиент
-
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.
-
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без печати).
- публикация с подтверждением, очередь
-
4.3 Глобал API по решению 5:
src/infra/broker/instance.py,src/api/dependencies.py, закрытие в lifespansrc/main.py, поля брокера в «Started API».Проверка:
make lint; процесс API стартует и отвечает/health/readyпри остановленном брокере; в «Started API» адрес, очередь и срок, пароля нет.
5. Thumbnail
-
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
-
6.1
AttachmentServiceпо решению 3: издатель в конструкторе и зависимости;_storeпишет в staging;_mark_ready→ перевод вqueuedс заданием и той же компенсацией; публикация, отметкаpublished_at, транзакция отмены; места загрузки держатся до ответа; записи журнала по решению 18,filenameв них нет.Проверка:
make lint; один PNG против консольного API и брокера стенда — 202, строкаqueued, объект только в staging, одно сообщение; сбои — тесты группы 10. -
6.2 Чтение по решению 9:
pending— 404, остальные — 200, варианты только уready;open_content(variant=…): статус неready—AttachmentNotReadyбез обращения к S3, нет варианта — 404, нет объекта варианта или другой размер — 500 с записьюerror; ветки оригинала иlost_atпрежние.Проверка:
make lint; поведение — тесты группы 10. -
6.3
MessageServiceпо решению 9: неизвестное, чужое иpending— 404 до ключа;failed— после захвата ключа: новый ключ — откат иAttachmentFailed, занятый — прежняя ветка повтора.Проверка:
make lint; поведение — тесты группы 10, в том числе «Повтор после failed вложения». -
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
-
7.1 Сообщение задания: pydantic-модель
src/schemas/jobs/attachment.py(решение 7), сборка тела из строки задания и номера попытки. Правилоdto.mdдополняется в задаче 13.1.Проверка: тело по
contracts/jobs.schema.json(jsonschemadev-группы); лишнее поле, чужаяschema_version,attempt0, неверныйtraceparent— ошибка разбора;traceparentиtracestateпо схеме проходят. -
7.2
AttachmentProcessingServiceвsrc/core/services/attachment_processing.pyпо решениям 2 и 7: разбор, таблица claim, обработка под сроком, фиксацияreadyс вариантом одной транзакцией, временные и постоянные ошибки, недоступный PostgreSQL, исходACKилиREQUEUE; порядок блокировок — задание, затем вложение; журнал по дельтеservice-logging.Проверка:
make lint; поведение — тесты группы 10. -
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. Уборщик и сверка
-
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. -
8.2 Сверка по решению 11: разбор ключа варианта в
_list_objects,idвариантов в выборке страницы, ветка варианта в_classify_object(строка есть — пропуск, нет — объект без метаданных, свежий — свежий); находка зависшей загрузки называет ключ staging;is_own_keyпо-прежнему смотритobject_key.Проверка:
make lint; на стенде обе стратегии без--applyне называют объекты вариантов; поведение — тесты группы 10.
9. Стенд
-
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 и уборщика. -
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. -
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. -
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,RestartCount0;haproxy -cзакреплённым образом. -
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— тег прогона. -
9.6 Рабочий стенд на рабочем дереве:
make run_docker.Проверка:
docker compose ps— две реплики, уборщик, worker, брокер и S3 в рабочем состоянии, bootstrap с кодом 0;make test—PASS: lab5;- журнал worker: «Started worker» со всеми значениями, затем запись о готовом вложении;
filenamesmoke в журнале нет; 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. Тесты
-
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 не работает»). -
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 — прежние сценарии зелёные, красное только из шапки. -
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сверены с метаданными варианта. -
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. -
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 напечатаны, стенд удалён. -
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. -
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». -
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— остаётся и печатается. -
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; итог называет число сценариев проверок отказов с новыми. -
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после откатов совпадает с кодом до них. - ack до фиксации результата →
11. bench/
-
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без секретов. -
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
-
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. -
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. Правила и карта кода
-
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. - новое
-
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. Регресс на рабочем дереве
-
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, сверка без расхождений по нему. -
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проверить чтением.
-
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. -
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. -
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.