# Tasks Как строить — `design.md` (дальше «решение N»), что должно получиться — дельты в `specs/`. Перед первым файлом слоя прочитать его правило: `api-contract.md`, `api-layer.md`, `auth.md` (`dependencies.py`, `errors.py`), `service-layer.md`, `repo-layer.md`, `dto.md`, `migrations.md`, `logging.md`, `settings.md`, `student-tests.md`, `bench.md`, `balancer.md` (драйвер и `stop-one.sh`). Evidence снимается с закоммиченного кода, коммит — только после подтверждения пользователя (`bench.md`, «Измеренное состояние — commit»). Ответы пользователя 2026-10-20 (`PLAN.md`, `### attachments` → «Вопросы»): - п. 1 — структурная проверка изображения; - п. 2 — ответ преподавателя 2026-10-20 (AGENTS.md, «Согласования с преподавателем»; design, решение 8): «пустой текст» — и `""`, и текст из одних пробелов; с хотя бы одним вложением он допустим (201, текст как прислан), без вложений — 400. Валидатор `CreateMessage`, сценарий `messages` «Пробелы с вложением» и его тест — под это; - п. 3 — `filename` отклоняется только по списку контракта: `/`, `\` и управляющие символы категории Cc, остальное принимается. Ожидаемо красное по ходу работы, остальное разбирается по AGENTS.md: - до задачи 5.5 (sync дельт) тесты с маркерами новых сценариев падают на сверке: «marker points to unknown scenario»; - до задачи 9.2 `test_exclusion_evidence_exists`: нет файлов исключений. Это четыре файла перехода из AGENTS.md («Переход в следующую лабу») и `evidence/attachments/failover.md`, `storage.md`. ## 1. Основа: константы, enum, DTO, исключения, проверка изображения - [x] 1.1 Типы домена по решениям 2, 4 и 10: - константы в `src/utils/constants.py`: лимиты, длины `filename`, запрещённые символы `filename` (`/`, `\`, категория Cc), `MESSAGE_ATTACHMENTS_MAX`, префикс и суффикс ключа объекта; - `src/schemas/enums/attachment.py` (`AttachmentStatus`, `ImageType`); - `src/schemas/dataclasses/attachment.py` (`AttachmentFullDTO`, `AttachmentContentDTO`), поле `attachment_ids: tuple[UUID, ...] = ()` в `MessageFullDTO`; - `src/core/exceptions/attachment.py` (`AttachmentNotFound`, `PayloadTooLarge`, `UnsupportedMediaType`, `UploadInterrupted`, `AttachmentContentMissing`); - реэкспорт в `__init__.py` пакетов по алфавиту. Проверка: `make lint`; `uv run python -c "from src.core import exceptions; from src.schemas import dataclasses, enums; print(…)"` без ошибок. - [x] 1.2 `src/utils/image.py` по решению 2: `inspect_image(data, *, max_pixels)` → `ImageInfo` (тип, ширина, высота), исключения `UnsupportedImage`, `DamagedImage`, `TooManyPixels`. Только stdlib; фильтры строк — срезом с шагом строки, конец скана JPEG — регулярным выражением. Проверка — разовый скрипт в scratchpad (`uv run --no-project --with pillow python -I`), который импортирует модуль по пути. Повторить пробу из design, Context: - 17 вариантов приняты; - повреждённые из списка — `DamagedImage`, хвосты приняты; - подмена размеров SOF — `TooManyPixels`; - «бомба» 100 × 100 / 200 MiB — `DamagedImage` быстрее 10 мс; - PNG 1 × 40 млн и 40 млн RGBA — не дольше 0,5 с, пик `tracemalloc` до 5 MiB; - корпус из 12 000 случайных PNG и JPEG системы: ни одного файла, который загружает Pillow, а модуль отклоняет, кроме лимита пикселей. Итоги — строкой в design, «Уточнения apply». ## 2. Схема БД - [x] 2.1 Модели по решению 3: `src/infra/db/models/attachment.py` (`Attachment`, `MessageAttachment` с ограничениями и индексом по `attachment_id`), новое условие `text_length` в `Message`, экспорт в `models/__init__.py`. Проверка: `make revision` даёт ревизию с двумя таблицами и индексом. Ослабление CHECK autogenerate не видит (`migrations.md`). - [x] 2.2 Ревизия руками по решению 3: - первая строка `SET LOCAL lock_timeout = '2s'`; - CHECK литералами, а не константами `src`; - `DROP CONSTRAINT ck_messages_text_length` и `ADD CONSTRAINT … CHECK (char_length(text) <= 4000) NOT VALID`; - `downgrade` зеркально, строгое ограничение тоже `NOT VALID`. Проверка: - `uv run alembic upgrade head --sql` содержит `NOT VALID`; - `make upgrade` на рабочей базе, повторный `upgrade head` — без изменений; - на временной базе (`createdb` в контейнере `postgres`, `DATABASE__NAME` в окружении): `upgrade` с нуля → `downgrade -1` → `upgrade`, затем `DROP DATABASE`; - psql в транзакции с откатом: - строка с каждым нарушением CHECK отклонена: размер, SHA-256, тип, статус, `filename` с `/`, `\`, U+0001, U+007F, U+0085 и из 256 символов; - допустимая строка принята, в том числе с `filename`, где есть U+202E, U+2028 и U+00AD: CHECK не строже API; - владелец не участник — отказ FK; - удаление вложения со связью — отказ FK; - повтор вложения в сообщении и позиция 10 — отказ; - `\d attachments`, `\d message_attachments` — по таблице решения 3. ## 3. Repo и сервисы - [x] 3.1 Repo по решениям 3, 4 и 8: - `src/core/repos/attachment.py`: `insert_attachment`, `mark_ready` (`UPDATE … WHERE status = 'pending' RETURNING`), `get_attachment`, `get_attachments`; - `src/core/repos/attachment_object.py`: `original_key`, `put_original`, `open_original` поверх `ObjectStorage`; - `src/core/repos/message.py`: `MESSAGE_COLUMNS` с подзапросом `ARRAY(...)`, вставка сообщения явными колонками, `insert_message_attachments` одной вставкой. В каждой функции одно выражение. Проверка: `make lint`. Поведение — через HTTP в группах 4–5; план истории — задача 7.2. - [x] 3.2 `src/core/services/attachment.py` — `AttachmentService(db_scope, cache, storage)` по решениям 1, 5, 6, 7, 11: `upload`, `get_attachment`, `open_content`. Проверка, загрузка, SHA-256 и размеры — одним `anyio.to_thread.run_sync`. Каждый шаг с БД — свой `async with self.db_scope()`, без вложенных. Журнал без `filename`. Проверка: `make lint`, дальше задача 4.3. - [x] 3.3 `MessageService.send_message(..., attachment_ids)` по решениям 8 и 9: - проверка вложений до захвата ключа; - связи после вставки сообщения, один commit; - `message_request_hash(text, attachment_ids)`: пустой список хэш не меняет, id — `str(UUID)`; - `attachments_count` в записи журнала. Проверка: разовый вызов `message_request_hash` — хэш `{"text": "x"}` равен хэшу версии `e1161f7` (`git show e1161f7:src/core/services/ message.py`), список в верхнем и нижнем регистре даёт один хэш, другой порядок — другой. ## 4. Слой API - [x] 4.1 `src/api/dependencies.py` по решению 5: - `db_session_scope()`; - `get_db_session` — обёртка над ним; - `get_current_user_brief` и `CurrentUserBrief`; - `get_attachment_service` и `AttachmentServiceDep` (глобал `object_storage`). `src/api/errors.py` — строки таблицы решения 10. Проверка: `make lint`; `make student_test` через LB — те же итоги, что до правки (красное — только схема `Message`, сверка и исключения). JSON-ручки не изменились. - [x] 4.2 Схемы и ручки по решениям 6, 7, 8, 10: - `src/api/schemas/attachment.py`: `DisplayFilename` (отказ на `/`, `\`, символы категории Cc и строку из одних пробелов, решение 10), `Attachment`; - `src/api/schemas/message.py`: `CreateMessage` с `attachment_ids` и валидатором, `Message` с `attachment_ids`; - `src/api/routers/v1/attachment.py`: загрузка с `openapi_extra`, метаданные, `content` со `StreamingResponse`, обёртка над `request.stream()` с `UploadInterrupted`; - подключение в `routers/v1/__init__.py`, параметр `attachment_ids` в ручке сообщения. Проверка: `/openapi.json` запущенного сервера содержит три пути контракта, тело загрузки `image/png` / `image/jpeg` и параметр `variant` с перечислением `original`. - [x] 4.3 Проверка на живом сервере. Консоль — `driver.py start`, стенд — `make rolling_update`: одна миграция, затем замена по одной. - `make test` против обоих: `PASS: lab4 public API scenario`. - Руками через `driver.py req` и curl: - 413 по `Content-Length` и частями; - 415 на текст и подмену MIME; - 400 на `filename` с `/` и с U+0085, 201 на `filename` с U+202E — имя в ответе то же; - 404 постороннему на загрузку, метаданные и байты; - 503 на загрузку и скачивание при `make stop_s3`, метаданные 200; - после `make start_s3` — 201 и 200; - журнал (`make logs` без `-f`) не содержит переданных `filename`. - Разовый скрипт в scratchpad (решение 5): загрузка 10 MiB частями за ~12 с и скачивание 10 MiB с чтением за ~12 с через LB — 201 и 200 без «Database is unavailable» в журнале. ## 5. Тесты - [x] 5.1 `uv add --dev pillow`. `student-tests/images.py` — генераторы по решению 12. Проверка: - `uv lock --check`; - `docker run --rm mtusi-messenger:lab4 python -c "import PIL"` завершается ошибкой: в образе Pillow нет; - `uv run python -c` с импортом `images` даёт PNG ровно 10 485 760 байт, и `inspect_image` его принимает. - [x] 5.2 `student-tests/api_client.py` и `contract.py` по решению 12: - загрузка, метаданные, байты, `send_message(..., attachment_ids)`; - коды 413 и 415, `owner_id`, элементы `attachment_ids`, `updated_at`; - `assert_content`. Проверка: прежние тесты проходят на коде группы 4. - [x] 5.3 `student-tests/test_attachments.py` — сценарии спека `attachments`, кроме проверок отказов и исключений, с маркерами `spec`. В «Опасном имени» — только символы контракта, в «Символах форматирования в имени» — 201 и то же имя в ответе и метаданных. «Скачивание через другую реплику» — с фикстурой `replicas`. В `test_rubric.py` — пять сценариев рубрики «4» лабы 4. Новые сценарии дельт `messages`, `idempotency`, `api-conventions`, `data-storage` — в их модулях. Проверка: `make student_test` через LB и `make test_isolated` — новые тесты проходят; на рабочем стенде через LB `replicas`-тест выполняется, в `test_isolated` пропущен с причиной. - [x] 5.4 Проверки отказов по дельте `student-tests`: - `test_failures.py`: «Запись в S3 не удалась», «Отклонённая загрузка ничего не оставляет», «S3 остановлен», «S3 завис» в `with outage(...)`; - `fault_hook.py`: действия `count-attachments` и `count-objects`, docstring; - `run_failures.py`: bucket и имя базы в окружении hook. Проверка: `make failure_checks FAULT_ARGS='-k attachment or object_storage'`, затем полный `make failure_checks` — код 0, стенд отказов удалён, у рабочего стенда прежний `StartedAt`. - [x] 5.5 Сверка покрытия: - `attachments` в `CAPABILITIES` (`spec_coverage.py`); - исключения «Принявшая реплика остановлена», «Байты не в БД и не на диске API», «Рестарт стенда» с причиной и командой по решению 12; - синхронизация всех дельт change в основные спеки (`/opsx:sync`), как `health` в `s3-storage`. Проверка: `make student_test` — сверка без «no test and no exclusion» и «unknown scenario». Красное — только `test_exclusion_evidence_exists` по списку в шапке. ## 6. Драйвер скилла `run-mtusi-messenger` - [x] 6.1 Команды `upload` и `download` по решению 13. Проверка против `driver.py start` и стенда (`--port 8080`): загрузка `tests/fixtures/sample.png`, скачивание вторым участником — SHA-256 `99ea7533…` совпадает; 404 постороннему; `ruff format --check` и `make lint` проходят. - [x] 6.2 `attachment-failover [--mode stop|kill]` по решению 13. Проверка на стенде: оба режима — код 0, скачивание от реплики с другим `X-Instance-Id`, SHA-256 совпал, после команды снова `API_REPLICAS` реплик `UP` (`make lb_stats`). Отрицательная проверка: без балансировщика (`--port` консольного процесса) — код 2 и понятное сообщение. - [x] 6.3 `attachment-storage` по решению 13. Проверка: - на стенде код 0; - отрицательная: `s3.anonymous.set -access Read` через `docker compose exec s3 weed shell` — код 1 с названной проверкой; `docker compose up -d s3-bootstrap` закрывает доступ, и снова код 0. - [x] 6.4 `flow` с вложением по решению 13, раздел о вложениях в `SKILL.md`: команды, gotchas — `urllib` напрямую к реплике и ранний 413; S3 нужен только путям вложений. Проверка: `driver.py all` — код 0, `FAILED: none`. ## 7. Стенд `bench/` - [x] 7.1 `rollout_from = "e1161f7"` в профилях `rollout` и `rollout_quick` (комментарий профиля — тоже) и проверка commit до стенда по решению 14 и дельте `load-benchmark`. Правило в `bench.md`, удаление записи из `KNOWN_ISSUES.md`. Проверка: - `uv run python bench/run.py --profile rollout_quick --from 0000000` — ненулевой код до запуска стенда, в сообщении commit и `--from`; - `make bench_rollout_quick` — код 0, в `meta.json` метки `from_commit` `e1161f7`; - ревизия до замены — `e656d6bbe1a4`, после — новая. - [ ] 7.2 Регресс прежних профилей: `make bench_quick`, `make bench_failover_quick`, `make bench_restore_quick` — код 0. В `explain-10k.txt` пробной метки узел истории — прежний индекс `messages`, а `SubPlan` идёт по `pk_message_attachments` (решение 8). Пробные метки `quick-*` в git не идут. ## 8. Документы и проверка кода - [x] 8.1 Правила: - `api-contract.md` — раздел лабы 4: ручки, коды 413 и 415 в таблице, порядок проверок загрузки, `filename` (только символы контракта, категория Cc), `UuidIn` для id вложений, ранний ответ и `urllib`, пустой текст (в том числе из пробелов) с вложением — 201 по согласованию с преподавателем; - `api-layer.md` — роутер с двумя префиксами, `CurrentUserBrief`, тело без параметра, `StreamingResponse`, `UploadInterrupted`; - `service-layer.md` — `AttachmentService` с `db_scope`, порядок записи, проверка вложений сообщения, хэш; - `repo-layer.md` — repo вложений, repo объекта S3, подзапрос `ARRAY`; - `dto.md` — новые DTO и enum; - `migrations.md` — таблицы вложений, ослабление CHECK `NOT VALID`, почему не `autocommit_block`; - `logging.md` — записи `attachment_service`, `filename` не пишется; - `student-tests.md` — `test_attachments.py`, `images.py`, Pillow в dev, отказы S3 и действия hook, новые исключения; - `settings.md` — `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` — константы; - `bench.md` — `rollout_from`. Ещё AGENTS.md (карта кода, команды драйвера, «Переход в следующую лабу» — `rollout_from`, таблица важных файлов) и `PLAN.md`, `### attachments` («Решения» из apply). Проверка: `grep -rn "c50b721" AGENTS.md .claude bench KNOWN_ISSUES.md` пуст. - [x] 8.2 `make lint`, `make check`, `openspec validate attachments --strict`, `graphify update .`. После sync дельт имя `attachments` — и change, и спек: `openspec validate attachments --type change --strict`. ## 9. Коммит, evidence, отчёт - [x] 9.1 Финальная проверка на стенде `mtusi-lab4` после `make rolling_update`: - `make test` — `PASS: lab4`; - `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` — PASS, между прогонами `make replicas`; - `make student_test` и `make test_isolated` — красное только по шапке; - `make failure_checks` — код 0. Затем показать изменения, предложить сообщение коммита и после подтверждения закоммитить. - [ ] 9.2 Evidence исключений с закоммиченного кода, без токенов, паролей и секретов S3, в каждом файле дата, commit и стенд: - четыре файла перехода по AGENTS.md («Переход в следующую лабу»). `evidence/replicas/test-persistence.md` — `make test-persistence` с `LAB=4`, `StartedAt` до и после, вложение после hook; - `evidence/attachments/failover.md` — `attachment-failover`, оба режима; - `evidence/attachments/storage.md` — `attachment-storage`. Проверка: `make student_test` — `test_exclusion_evidence_exists` зелёный; `grep` по значениям секретов из `.env` в `evidence/` пуст. Коммит — после подтверждения. - [ ] 9.3 Evidence проверок по таблице решения 15: - `evidence/tests/` — зелёные `make test_isolated`, `make student_test` через LB, `make failure_checks`; - `evidence/attachments/smoke.md`, `slow-transfer.md`; - `evidence/failover/test-failover.md` — `make test-failover` с `LAB=4` для каждой реплики, `STOP_ONE_LOG`, `docker compose ps` до и после, между прогонами `make replicas`. Проверка: в каждом файле команда, итог, дата, commit; секретов нет. - [ ] 9.4 Желательно: `make bench_rollout ROLLOUT_LABEL=attachments` после проверки хоста (`bench.md`, «Результаты»), рабочий стенд на время замера остановлен. Проверка: код 0, в `summary.md` ревизии до и после, сверка записей сошлась; метка закоммичена. - [ ] 9.5 `REPORT.md` по решению 15: - раздел о вложениях; - соответствие `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS`; - ответы на четыре вопроса защиты; - строки уровней «3» и «4» с командой, наблюдением и файлом; - ограничения; - согласование с преподавателем 2026-10-20: текст из одних пробелов с вложением — 201, без вложений — 400 (design, решение 8; AGENTS.md, «Согласования с преподавателем»). Строку этапа 2 в `PLAN.md` — по факту. Проверка: у каждой новой строки таблицы доказательств есть команда, наблюдение и файл; `make lint`, `make check`, `openspec validate attachments --strict`. Коммит — после подтверждения.