Flask + Claude API за 10 дней: как мы автоматизировали акты выполненных работ для самозанятых

Как мы запустили ИИ-сервис для генерации актов за 10 дней: Flask + Claude API

TL;DR: сделали сервис для автоматической генерации актов выполненных работ с помощью Claude API. Расскажем про архитектуру, промпт-инжиниринг и подводные камни.

Предпосылки

Самозанятые и ИП вынуждены тратить 20–40 минут на оформление каждого акта выполненных работ. Существующие решения — либо тяжёлые бухгалтерские системы, либо ручные Word-шаблоны. Мобильного, быстрого инструмента не было.

Архитектура

Бэкенд: Flask + SQLAlchemy + PostgreSQL. Хостинг на Railway. Для генерации документов — Anthropic Claude API (модель claude-sonnet-4).

Ключевая часть — промпт. Мы передаём структурированные данные: исполнитель, заказчик, описание работ в свободной форме. Модель возвращает чистый HTML с таблицей работ, расчётом итога и блоком подписей.

Промпт-инжиниринг: самая сложная часть — научить модель правильно парсить неструктурированное описание («установил 3 розетки по 500, провёл кабель 20 метров по 80») и формировать аккуратную таблицу с единицами измерения.

Дополнительные возможности: распознавание реквизитов из загруженного договора (Claude Vision), голосовой ввод через Web Speech API, генерация PDF через ReportLab с поддержкой кириллицы, Word через python-docx, отправка на email через Resend API.

Подводные камни

Главная проблема — таймауты Gunicorn при длинных запросах к Claude API (30–90 секунд). Решили через увеличение воркер-таймаута до 300 секунд и настройку Anthropic SDK timeout.

Кириллица в PDF: WeasyPrint не заработал на Railway из-за отсутствия системных библиотек. Перешли на ReportLab с подключением шрифта Arial через TTFont.