Простая аналитика расходов

🚀 Live Application (Render): https://amurcode.onrender.com

Локальный MVP для кейса БФТ и Минфина Амурской области. Приложение запускается одной командой, читает CSV из case/, держит данные в памяти и отдаёт Vue 3 UI без Vite, npm, PostgreSQL и отдельного ETL-сервиса.

Запуск

Установка зависимостей:

python -m pip install -r requirements.txt

Обычный локальный запуск:

python app.py 8000

Открыть в браузере:

http://127.0.0.1:8000

python app.py запускает FastAPI через uvicorn. Для прямого ASGI-запуска используйте:

uvicorn analytics.api:app --host 127.0.0.1 --port 8000

HOST и PORT можно задать переменными окружения. Legacy Handler сохранен для совместимости тестов и старого импорта app.

Простой режим

Первый экран построен вокруг задач, а не фильтров. Пользователь может нажать быстрый сценарий, ввести код или название в единую строку, получить короткий вывод на отчетную дату, посмотреть готовность данных, открыть карточку объекта со строками-источниками и скачать Excel-отчет.

Короткий вывод теперь строится как управленческая подсказка: система показывает, что требует внимания, и выводит главные риски. Риск не является юридическим выводом или автоматическим решением о нарушении; это приоритет для ручной проверки объекта.

После вывода появляется блок Что делать дальше: открыть главный риск, показать объекты без кассы/оплат/документов или скачать Excel. Пользователю не нужно помнить фильтры и формулировать следующий запрос вручную.

Демо за 60 секунд

Первый быстрый сценарий Демо за 60 секунд открывает проблемные СКК, вкладку Проблемы, главные риски и плашку с шагами показа. Рекомендуемый путь: посмотреть короткий вывод, открыть главный риск, показать источник цифр в карточке объекта и скачать Excel.

Контроль загрузки

Кнопка Контроль загрузки показывает управленческую сверку текущей выборки: сколько строк и источников попало в расчет, есть ли предупреждения качества, сколько объектов связано только по названию и сколько объектов видны только в одном источнике. Предупреждения считаются из накопленных проблем качества загрузки по исходным файлам и строкам; источник считается покрытым, если его записи попали в текущую выборку.

Тот же контроль доступен через GET /api/control?date=&template=&q=&code=&budget=&source= и добавлен в Excel отдельным листом Контроль загрузки.

Workflow проверки

Проверка проблемного объекта идет по короткому пути: открыть карточку объекта, посмотреть блок Почему такой риск, проверить документы и исходные строки, выбрать статус проверки, при необходимости назначить ответственного и добавить комментарий. Статусы сохраняются локально в data/reviews.json и не коммитятся.

Загрузка новых данных

В UI загрузка находится в Расширенные настройки -> Загрузить данные. Разрешенные источники: rcb, agreements, state_task_contracts, state_task_payments, buau. Разрешенные расширения: .csv и .xlsx, максимальный размер файла - 50 MB.

Файлы сохраняются локально в data/uploads/<source_type>/. Если имя уже занято, к имени добавляется timestamp suffix. Runtime-файлы data/reviews.json и data/uploads/ исключены из git.

Ошибки импорта возвращаются как JSON: invalid_extension, source_type_required, file_required, file_too_large.

Быстрый старт

Доступны готовые сценарии:

• Собрать отчет СКК.
• Собрать отчет КИК.
• Собрать отчет 2/3.
• Собрать отчет ОКВ.
• Демо за 60 секунд.
• Найти проблемные объекты.
• Проблемные СКК.
• Сравнить две даты.
• Найти объект.

UI использует /api/query?view=as_of&date=... и /api/compare. Старый периодический режим /api/query без view сохранен для совместимости.

Семантика дат

Основной режим MVP - состояние на дату. РЧБ и соглашения считаются месячными срезами с семантикой balance_as_of: выбирается последний срез не позже выбранной даты, а не сумма срезов за период. Контракты, платежи и БУАУ считаются событиями с накоплением до выбранной даты.

Отчетные даты берутся только из РЧБ и соглашений через GET /api/catalog/reporting-dates, чтобы пользователь не выбирал одиночную дату платежа как дату месячного среза.

Колонки РЧБ для лимитов, БО и кассы ищутся по смысловому префиксу, например Лимиты ПБС и Подтв. лимитов по БО, поэтому файлы 2025 и 2026 годов читаются одним правилом.

Экспорт

Основной рабочий экспорт:

• GET /api/export.xlsx?date=&template=&q=&code=&budget=&source=&post_filter=
• GET /api/export.xlsx?mode=compare&base=&target=&template=&q=&code=&budget=&source=
• GET /api/export.pdf?date=&template=&q=&code=&budget=&source=&post_filter=
• GET /api/export.pdf?mode=compare&base=&target=&template=&q=&code=&budget=&source=

Excel содержит листы Выводы, Итоги, Объекты, Проблемы, Исходные строки, Контроль загрузки, Методика. Файл оформлен как отчет: заголовки, фильтры, закрепленные строки, подсветка рисков, денежные форматы, блоки внимания, главные риски, контроль загрузки и следующие действия. CSV-экспорт в UI сохранен как дополнительная таблица.

PDF-экспорт доступен кнопкой Скачать PDF и теми же фильтрами, что Excel. Excel остается детальной рабочей таблицей для проверки строк, а PDF - коротким оформленным отчетом для показа или пересылки.

Excel требует openpyxl, PDF требует reportlab. Если reportlab не установлен, /api/export.pdf вернет понятную JSON-ошибку pdf_dependency_missing; остальное приложение и Excel продолжают работать. Для корректной кириллицы в PDF лучше иметь системный TTF-шрифт Windows, например Arial, Calibri или Tahoma.

Assistant

Пользователь пишет обычный запрос в единую строку первого экрана. Система сама выбирает быстрый сценарий, rule-based разбор или LLM и применяет действие в UI.

Endpoint POST /api/assistant принимает обычный текст и возвращает intent, объяснение, действие для UI и follow-up кнопки. Без GROQ_API_KEY assistant работает по правилам. Если ключ задан, он может использовать Groq как enhancer, но суммы всё равно считает только backend.

Локальный Groq ключ

Создайте локальный .env из примера:

Copy-Item .env.example .env
notepad .env

.env локальный и не коммитится. GROQ_API_KEY используется только сервером, не возвращается в API и не нужен для обычных тестов. Без ключа помощник работает по правилам.

Опциональные переменные окружения:

GROQ_API_KEY=
GROQ_MODEL=llama-3.1-8b-instant
ASSISTANT_ENABLED=auto
RUN_LLM_TESTS=0

В Groq не отправляются raw records. Используются только запрос пользователя, список шаблонов, список метрик, доступные даты, короткий RAG-контекст из docs/rag и агрегированные выводы для /api/explain.

API

• GET /api/meta
• GET /api/query?view=as_of&date=&q=&code=&budget=&source=&template=&metrics=&post_filter=
• GET /api/query?q=&code=&budget=&source=&start=&end=&template=&metrics= legacy period mode
• GET /api/compare?base=&target=&q=&code=&budget=&source=&template=&metrics=
• GET /api/readiness?view=as_of&date=&template=&q=&code=&budget=
• GET /api/control?date=&template=&q=&code=&budget=&source=
• GET /api/reviews
• GET /api/review?object_key=
• POST /api/review
• GET /api/object?date=&template=&object_key=&budget=
• GET /api/export.xlsx?date=&template=&q=&code=&budget=&source=&post_filter=
• GET /api/export.pdf?date=&template=&q=&code=&budget=&source=&post_filter=
• GET /api/export.pdf?mode=compare&base=&target=&template=&q=&code=&budget=&source=
• GET /api/quality
• GET /api/trace?id=
• GET /api/catalog/dates
• GET /api/catalog/reporting-dates
• GET /api/catalog/sources
• GET /api/catalog/budgets
• GET /api/catalog/templates
• GET /api/catalog/metrics
• GET /api/catalog/objects?q=&template=
• GET /api/catalog/quick-actions
• POST /api/assistant
• POST /api/explain
• POST /api/import

/api/query добавляет к строкам risk_score, risk_level, risk_label, risk_explanation и общий блок attention_summary. /api/compare добавляет compare_insights с новыми проблемами, снижением риска, ростом риска и объектами, где план вырос без движения кассы.

Офлайн-демо

Vue runtime хранится локально в /static/vendor/vue.global.prod.js, поэтому первый экран не зависит от CDN. Данные, проверки и загруженные файлы остаются локальными.

Тесты

python -m unittest discover -s tests -v

Текущий baseline после hardening phases: 102 tests OK, 1 skipped.

В набор входят backend-тесты, безбраузерные проверки Vue-логики через Node VM и Playwright-тесты реальных кликов в Chromium. Для новой машины:

python -m pip install playwright
python -m playwright install chromium

Ограничения

• Данные хранятся in-memory.
• Денежные расчеты внутри backend выполняются через Decimal, внешний JSON по-прежнему отдает money fields как numbers.
• Trace показывает источник, файл и строку исходного CSV там, где она доступна.
• Векторная база не используется. Мини-RAG реализован чтением markdown из docs/rag.

Как проверить перед показом

1. Запустить python -m unittest discover -s tests -v.
2. Запустить python app.py 8000 и открыть http://127.0.0.1:8000/.
3. Нажать Демо за 60 секунд.
4. Убедиться, что открылась вкладка Проблемы, видны главные риски и открывается карточка объекта.
5. Проверить блок Почему такой риск, сохранить статус проверки и переоткрыть карточку.
6. Открыть Контроль загрузки.
7. Скачать PDF и Excel; в Excel должны быть листы Выводы, Итоги, Объекты, Проблемы, Исходные строки, Контроль загрузки, Методика.
8. Проверить, что в основных экранах не показаны machine fields: snapshot, trace, pipeline, problem_reasons, коды факторов риска.