Система учета и обработки корреспонденции

Модульный монолит для учета входящих и исходящих писем предприятия: контрагенты, контакты, черновики и официальная регистрация, журналы, вложения, назначения, комментарии, история, mock AI Gateway, фирменные бланки, детерминированное формирование DOCX, XLSX-отчёты и асинхронная PDF-конвертация.

Состав

• backend/ — FastAPI, Pydantic v2, SQLAlchemy 2.0, Alembic, Dramatiq.
• frontend/ — Next.js App Router, TypeScript, Tailwind CSS.
• docker-compose.yml — PostgreSQL, Redis, MinIO, backend, worker, frontend.
• docs/ — архитектура, модель данных, граница AI, разработка.

Быстрый запуск

1. Создайте .env из .env.example и обязательно замените JWT_SECRET. При желании задайте BOOTSTRAP_ADMIN_USERNAME и BOOTSTRAP_ADMIN_FULL_NAME; пароль оставьте пустым для безопасного интерактивного ввода или генерации.

cp .env.example .env

2. Запустите инфраструктуру:

docker compose up --build -d
docker compose ps

3. Примените миграции, создайте встроенные роли и первого администратора:

docker compose run --rm backend alembic upgrade head
docker compose run --rm backend python -m app.cli seed
docker compose run --rm backend python -m app.cli.bootstrap_admin

Bootstrap выполняется только при отсутствии пользователей. Повторный запуск идемпотентен и не меняет существующего администратора. Если пароль был сгенерирован в неинтерактивном запуске, он показывается один раз; при первом входе система потребует его заменить. Пользователи создаются только администратором на странице «Пользователи», публичной регистрации нет.

Основные URL: frontend http://localhost:3000, backend OpenAPI http://localhost:8000/docs, MinIO console http://localhost:9001.

Проверки

docker compose config
docker compose run --rm backend ruff check app tests
docker compose run --rm backend mypy app
docker compose run --rm backend pytest
docker compose run --rm frontend npm run lint
docker compose run --rm frontend npm run type-check
docker compose run --rm frontend npm run build
AUTH_SMOKE_ADMIN_PASSWORD=<secret-from-protected-env> python scripts/smoke_vertical_flow.py
AUTH_SMOKE_ADMIN_PASSWORD=<secret-from-protected-env> python scripts/smoke_attachment_flow.py
AUTH_SMOKE_ADMIN_PASSWORD=<secret-from-protected-env> python scripts/smoke_document_flow.py
AUTH_SMOKE_ADMIN_PASSWORD=<secret-from-protected-env> python scripts/auth_smoke.py

Логи:

docker compose logs --no-color --tail=200 postgres
docker compose logs --no-color --tail=200 redis
docker compose logs --no-color --tail=200 minio
docker compose logs --no-color --tail=200 backend
docker compose logs --no-color --tail=200 worker
docker compose logs --no-color --tail=200 frontend

Ограничения первой версии

AI работает только через MockAIProvider и не участвует в заполнении реквизитов. Реальные LLM/ML-модели не загружаются. DOCX формируется библиотекой python-docx из закрытого шаблона MinIO. PDF асинхронно создаётся headless LibreOffice только в отдельном worker-образе. OCR, антивирусная проверка, email-интеграции, электронная подпись и сложное согласование не реализованы.

Worker-задачи вложений запускаются через Dramatiq и помечают scan_status / text_extraction_status как skipped, чтобы не утверждать, что выполнены реальный антивирус или OCR.

Подробности:

• регистрация и журналы;
• бланки, DOCX и версионирование;
• XLSX и PDF.
• безопасность локальных учётных записей;
• установка и аварийное восстановление.

Очистка локальных данных:

docker compose down -v