SciMesh/docs/worker-vibecoder-feedback.md

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

Это короткие правила по итогам ревью первой версии воркера. Перед новой задачей прочитай также 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, документацию и тесты в одном изменении.