# Памятка для доработки SciMesh Worker

Это короткие правила по итогам ревью первой версии воркера. Перед новой
задачей прочитай также [PLAN.md](../PLAN.md) и документ задачи, который тебе
дали.

## Что делать

- Считай воркер клиентом. Очередью, статусами задач и PostgreSQL управляет
  только coordinator.
- Сначала скачай и проверь входной файл по SHA-256, затем запусти расчёт.
- Сохраняй файлы только в своей папке `task_id/attempt`.
- После расчёта сначала загрузи результат через coordinator, затем отправляй
  результат задачи.
- В `result` передавай URI, который вернул coordinator, плюс SHA-256 и тип
  файла.
- При ошибке вызывай `/tasks/{id}/failure`; при успехе —
  `/tasks/{id}/result`.
- Для heartbeat используй новое `lease_expires_at`, возвращённое coordinator.
- Во все запросы, связанные с задачей, передавай `worker_id` и `attempt`.
- Пиши тесты не только на успех: проверь ошибку runner, неверный checksum,
  ошибку загрузки, потерю lease и пустой результат.
- Если поменял API, меняй одновременно Python-код, Go coordinator,
  документацию и тесты.

## Чего не делать

- Не отправляй в coordinator пути вида `worker://...` или `file://...`.
  Coordinator не видит локальные файлы воркера.
- Не используй `/result` для сообщения об ошибке.
- Не считай, что проверок Python достаточно: coordinator обязан сам проверить
  владельца lease, attempt, срок lease и допустимость смены статуса.
- Не повторяй любой HTTP-запрос вслепую. Повторные запросы должны быть
  безопасны: одинаковый `(task_id, attempt, worker_id)` не должен создавать
  дубликаты.
- Не передавай bearer token на другой домен при редиректе и не пиши токены,
  traceback или полные локальные пути в логи.
- Не помечай задачу завершённой, если артефакт не загружен надёжно.
- Не меняй контракт API «по ощущениям». Сначала зафиксируй JSON, статусы и
  переходы состояний в документации.

## Мини-чеклист перед коммитом

- [ ] Результат загружен в storage coordinator до `POST /result`.
- [ ] Ошибка уходит в `POST /failure`, а не в `POST /result`.
- [ ] Heartbeat возвращает новый срок lease, и код его сохраняет.
- [ ] В запросах есть верные `worker_id` и `attempt`.
- [ ] Нет `worker://`, `file://`, токенов и секретов в результатах или логах.
- [ ] Добавлены тесты на новый сценарий и на ошибку.
- [ ] `pytest` и проверка форматирования проходят.

## Короткий контекст для нейронки

> SciMesh Worker — клиент coordinator, а не владелец очереди. Загружай
> результат через coordinator до завершения задачи. Успех отправляй в
> `/result`, ошибку — в `/failure`. Проверяй checksum, lease и attempt.
> Меняя протокол, обновляй Python, Go, документацию и тесты в одном изменении.