ЧекАпп — монорепозиторий

Это скелет проекта для сервиса анализа чеков.

Структура

• app/backend — Laravel 12 API (Sanctum; PostgreSQL по умолчанию, Redis — позже)
• app/frontend — Ionic Vue app (Vite + Vue 3) + Capacitor (Android)
• app/ocr-service — Python-сервис с PaddleOCR
• infra/docker — Docker Compose, конфиги nginx, MinIO и т.д.
• storage — файлы чеков и датасеты (не коммитить в git)
• docs — документация (архитектура, roadmap, заметки)
• .github/workflows — CI/CD пайплайны

Дальше ты наполняешь эти директории реальным кодом (Laravel, Vue + Ionic, Python).

Документация (docs/)

• docs/README.md — навигация по документации и правила обновлений
• docs/tasks/ — задачи и текущие сессии (в работе)
• docs/INSTRUCTIONS.md — правила работы и ограничения для Codex
• docs/VISION.md — зачем продукт и критерии успеха
• docs/ROADMAP.md — план Now / Next / Later
• docs/ARCHITECTURE.md — компоненты и взаимодействия
• docs/DOMAIN.md — словарь домена
• docs/DECISIONS.md — список ключевых решений
• docs/adr/ — ADR (документы с решениями)
• docs/IDEAS.md — банк идей и гипотез
• docs/CODING_GUIDELINES.md — инженерные правила и стиль
• docs/CONTRIBUTING.md — как вносить изменения
• docs/PROMPT_START.md — стартовый промпт для новой сессии
• docs/deprecated-architecture.md — устаревшая архитектура (история)

Требования и установка (Ubuntu Server)

Минимум для запуска через Docker:

• Ubuntu Server 22.04/24.04 LTS
• Docker Engine + Docker Compose plugin
• just (task runner)
• git, curl, unzip, ca-certificates

Быстрая установка минимального набора:

sudo apt update
sudo apt install -y git curl unzip ca-certificates docker.io docker-compose-plugin just
sudo usermod -aG docker $USER

Если запускаешь без Docker (локально на сервере), дополнительно нужно:

• PHP 8.2+ и расширения: mbstring, xml, curl, zip, pgsql, sqlite3, bcmath, intl
• Composer 2.x
• PostgreSQL 14+ и Redis 6+ (или их контейнеры)
• Node.js 18+ и npm (для фронтенда)

OCR-сервис по умолчанию запускается в Docker и не требует Python на хосте.

Запуск (рекомендации)

Инфраструктура через Docker

Поднимает PostgreSQL/Redis/MinIO/nginx/OCR:

just up

Полезные порты (Docker Compose): 20000 (frontend placeholder), 20001 (PostgreSQL), 20003 (Redis), 20004 (MinIO S3), 20005 (MinIO console), 20006 (nginx), 20007 (OCR).

Backend (Laravel) локально

Минимальный запуск с PostgreSQL (по умолчанию в .env.example):

cd app/backend
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan serve --host=0.0.0.0 --port=8000

Альтернатива: just backend-dev.

Если нужен быстрый локальный запуск без Postgres, можно временно переключиться на SQLite: DB_CONNECTION=sqlite и DB_DATABASE=database/database.sqlite.

Для фоновых задач (OCR job-заглушка) нужен воркер очереди:

cd app/backend
php artisan queue:listen --tries=1

Для получения Bearer-токена нужен пользователь в БД (можно создать через tinker):

cd app/backend
php artisan tinker
>>> \App\Models\User::factory()->create(['email' => 'demo@example.com', 'password' => bcrypt('secret')]);

Далее получить токен:

curl -X POST http://localhost:8000/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@example.com","password":"secret","device_name":"local"}'

Загрузка чека (multipart) и проверка статуса:

curl -X POST http://localhost:8000/api/receipt-imports \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/receipt.jpg"

curl -X GET http://localhost:8000/api/receipt-imports/<id> \
  -H "Authorization: Bearer <token>"

Postman

Коллекция запросов лежит в docs/postman/checkapp.postman_collection.json. Базовый адрес в коллекции по умолчанию: http://localhost:20006 (Docker Compose + nginx). Для локального backend замени переменную baseUrl на http://localhost:8000.

Frontend (Ionic Vue) локально

cd app/frontend
npm install
npm run dev

Альтернатива: just frontend-dev (нужен @ionic/cli, можно через npx ionic serve).

Адреса:

• UI dev-сервер: http://localhost:8100
• Hot reload (Vite HMR): ws://localhost:8100
• API (локальный backend через php artisan serve): http://localhost:8000/api
• API (Docker Compose + nginx): http://localhost:20006/api

Frontend build через just

just build-frontend

Билд сохраняется в app/frontend/dist. При запущенном nginx из Docker Compose: http://localhost:20006.

OCR (ручной запуск)

just ocr-run sample.png

Файл должен лежать в storage/receipts.

OCR-сервис

• Зависимости и PaddleOCR упакованы в app/ocr-service/Dockerfile. При запуске just up Docker Compose соберет образ ocr-service, так что Python-виртуальное окружение на хосте не требуется.
• Хранилище чеков примонтировано в контейнер в /data/receipts, поэтому любая загруженная картинка становится доступна для обработки.
• Для ручного теста можно выполнить docker compose -f infra/docker/docker-compose.yml run --rm ocr-service python main.py --image /data/receipts/sample.png (подставь нужный путь к файлу).