Разработка

Предусловия

Установите uv и Node.js 22+, затем:

uv sync
cp -r .deploy.example .deploy   # .deploy/ — gitignored, отредактируйте при необходимости

Credentials читаются из ~/.config/gspread/service_account.json. Ещё нет ключа сервисного аккаунта? Смотрите Настройка Google Sheets.

Запуск сервера

inv dev   # запускает на http://127.0.0.1:8000 с uvicorn --reload

Миграции применяются автоматически при первом старте. БД создаётся в data/dinary.db.

Полезные флаги

Флаг	Эффект
`--reset`	Удалить `data/dinary.db`, пересоздать схему, пересеять каталог. Для чистого старта или после изменения `seed_config.py` — не для проверки корректности применения миграций к существующим данным.
`--rebuild`	Пересобрать PWA из `webapp/` перед запуском.
`--sheet-logging`	Включить логгинг в Google Sheets (по умолчанию выключен, чтобы тестовые расходы не попали в прод-таблицу).
`--port N`	Порт (по умолчанию 8000).

Разработка PWA

PWA — приложение на Vue 3 + Pinia в директории webapp/, собираемое Vite в _static/ (gitignored). FastAPI раздаёт собранные ассеты с того же origin, что и API.

После любых изменений в webapp/:

inv dev --rebuild              # пересобрать + перезапустить в одну команду
# или по отдельности:
inv build-static               # полная сборка (npm ci + vite build)
inv build-static --skip-install  # быстрее: без npm ci после первой сборки

Для горячей замены модулей (HMR) при итерации по Vue запустите Vite dev-сервер во втором терминале. Он проксирует вызовы /api на FastAPI порт 8000:

npm --prefix webapp run dev   # http://127.0.0.1:5173

Note

vite dev не регистрирует service worker. Тестируйте офлайн-режим и PWA-поведение на реальной сборке _static/ (запустите inv build-static, затем откройте FastAPI на порту 8000).

Работа с продакшн-данными

Для запуска локально с копией прод-данных:

inv restore-primary   # скачать живой снапшот с VM1 в data/dinary.db
inv dev               # не используйте --reset — это сотрёт снапшот

Тесты и качество кода

inv test   # Python + JavaScript тесты
inv pre    # pre-commit проверки (ruff, pyrefly, yaml, …)

Спецификации проекта

Внутренние проектные документы находятся в specs/ (на сайт документации не публикуются):

Директория	Содержимое
`specs/architecture/`	Архитектура системы, модель данных, проектные решения, сравнение подходов
`specs/reference/`	Доменный справочник: API каталога, валюты, обменные курсы, LLM-провайдеры, получение чеков, интеграция с Google Sheets, SQL-инструмент
`specs/ui/`	Визуальный язык PWA, каталог компонентов, спеки экранов, паттерны взаимодействия
`specs/plans/`	Планы реализации (активные) и записи о выполненных планах (`*-done.md`)

Если specs/ и код расходятся, код побеждает — спецификации описывают намерения, а не истину.