staffgen

Генератор тестовых данных для кадрового учёта научно-исследовательской организации.

Проект создавался как песочница для практики чистой архитектуры, тестирования и agent-driven разработки. В процессе вырос в готовый инструмент, который можно адаптировать под любой проект, которому нужна тестовая БД с реалистичными данными.

Возможности

• Генерация сотрудников со всей сопутствующей историей (поощрения, аттестации, контракты, квалификации, учёные звания, выслуга лет, обучение, состав семьи)
• Справочники: отделы, отделения, должности, штатное расписание, учёные звания
• RBAC: роли, разрешения, пользователи системы с паролями (bcrypt)
• Idempotent-сидинг: повторный запуск не дублирует данные
• 19 таблиц, связанных через внешние ключи (1:1, 1:N, M:N)

Технологии

Компонент	Назначение
SQLite	База данных (файловая, без сервера)
SQLAlchemy 2	ORM с аннотированными типами (Mapped[…])
Pydantic v2	Валидация данных и схемы (TypeAdapter, BaseModel)
Alembic	Миграции схемы БД
Mimesis	Генерация реалистичных ФИО, адресов, паспортных данных
pytest	Тестирование (unit + создание/чтение моделей)

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

# 1. Установка зависимостей
uv sync

# 2. Настройка (опционально)
cp .env.example .env
# Править: секретные ключи, количество сотрудников, пути

# 3. Применить миграции и заполнить БД
uv run python main.py

После выполнения в db_file/my_db.sqlite — 39 сотрудников с полной историей, 5 пользователей с ролями, справочники.

Как адаптировать под свой проект

1. Поменять модели — models/*.py. Добавить/убрать поля и таблицы.
2. Изменить генераторы — generators/*.py. Настроить формат данных под свой домен.
3. Поменять справочники — json_data/*.json. Загрузить свои отделы, должности и т.д.
4. Настроить количество — APP_EMPLOYEES_COUNT в .env.
5. Перегенерировать миграцию:

   rm db_file/my_db.sqlite
   rm alembic/versions/*.py
   uv run alembic revision --autogenerate -m "initial"
   uv run alembic upgrade head
   uv run python main.py

Архитектура построена так, что генераторы не зависят от конкретной БД — они работают с плоскими dict'ами. Модели, схемы и сидеры — с ORM. Это позволяет менять любой слой независимо.

Команды

Команда	Описание
uv run python main.py	Заполнить БД тестовыми данными
uv run pytest -v	Запустить тесты
uv run pytest --cov	Тесты с покрытием
uv run alembic check	Проверить синхронизацию моделей и БД
uv run ruff check .	Линтинг
uv run ruff format .	Форматирование

Структура проекта

creating_fake_data/
├── main.py               # точка входа: миграция + 4 шага сидинга
├── generators/            # генераторы случайных данных
│   ├── base.py            #   базовый класс + утилиты
│   ├── personal_data.py   #   ФИО, паспорт, ИНН, СНИЛС, адреса
│   ├── career.py          #   promotion, certification, contracts…
│   └── service.py         #   выслуга лет (length of service)
├── models/                # SQLAlchemy ORM-модели (22 модели)
├── schemas/               # Pydantic схемы
├── seeders/               # наполнение БД (basic_data, roles, users, employees)
├── db_service/            # менеджер сессий (портабельный)
├── settings/              # конфигурация через pydantic-settings
├── logging_service/       # кастомный логгер (Singleton)
├── tests/                 # pytest: unit-тесты генераторов + модели
├── alembic/               # миграции схемы БД
└── json_data/             # справочники в JSON

ER-диаграмма

Схема данных и связи таблиц — в ERD.md.