Skip to content

About

TerminologyService — сервис нормативно-справочной информации на Django.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

TerminologyService

Краткое описание

TerminologyService — сервис нормативно-справочной информации на Python и Django.
Сервис хранит справочники, их версии и элементы (пары «код — значение»), а также предоставляет REST API для получения справочных данных и проверки принадлежности элемента определённой версии.

  • API — предназначен для чтения данных.
  • Django Admin — предназначен для управления справочниками, версиями и элементами.

Оглавление


Возможности

  • Хранение справочников с уникальным кодом, наименованием и описанием.
  • Версионирование справочников с датой начала действия каждой версии.
  • Автоматический выбор текущей версии по дате.
  • Получение списка справочников с необязательной фильтрацией по дате.
  • Получение элементов текущей или явно указанной версии.
  • Проверка существования элемента по точной паре code и value.
  • Управление данными через русскоязычную Django Admin, в том числе редактирование версий и элементов на страницах связанных объектов.
  • Документация OpenAPI с интерфейсами Swagger UI и ReDoc.
  • Автоматические тесты моделей и API на pytest / pytest-django.

Архитектура проекта

Технологический стек

Компонент Технология
Язык Python 3.12+
Веб-фреймворк Django 5.2
REST API Django REST Framework 3.17
База данных SQLite
OpenAPI drf-spectacular, Swagger UI, ReDoc
Тестирование pytest, pytest-django
Окружение разработки Docker Compose, python-dotenv
Отладка django-debug-toolbar, debugpy

Версии и диапазоны зависимостей задаются в pyproject.toml.

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

├── config/
│   ├── settings/
│   │   ├── base.py                 # Общие настройки Django
│   │   ├── dev.py                  # Настройки разработки
│   │   └── test.py                 # Настройки тестирования 
│   ├── urls.py                     # URL Django Admin, API и документации
│   ├── db.sqlite3                  # Локальная БД (создаётся при миграциях)
│   ├── asgi.py
│   └── wsgi.py
├── terminology/
│   ├── api/
│   │   ├── urls.py                 # Маршруты REST API
│   │   ├── views.py                # Представления DRF
│   │   ├── serializers.py          # Валидация и сериализация
│   │   └── schema.py               # Описания операций OpenAPI
│   ├── migrations/                 # Миграции моделей
│   ├── tests/
│   │   ├── api/                    # Тесты API
│   │   ├── models/                 # Тесты моделей
│   │   └── conftest.py             # Общие фикстуры и фабрики
│   ├── admin.py                    # Настройки Django Admin
│   ├── models.py                   # Справочники, версии, элементы
│   └── selectors.py                # Запросы к данным
├── .env.example                    # Пример переменных окружения
├── Dockerfile
├── docker-compose.dev.yaml
├── docker-compose.debug.yaml
├── Makefile                         # Команды для разработки
├── manage.py
├── pyproject.toml                  # Зависимости и настройки pytest
└── README.md

Структура данных

Справочник — Refbook

  • id — идентификатор;
  • code — уникальный код (до 100 символов);
  • name — наименование (до 300 символов);
  • description — необязательное описание.

Версия справочника — RefbookVersion

  • id — идентификатор;
  • refbook — ссылка на справочник;
  • version — обозначение версии (до 50 символов);
  • date — необязательная дата начала действия.

Элемент версии — RefbookElement

  • id — идентификатор;
  • version — ссылка на версию;
  • code — код элемента (до 100 символов);
  • value — значение элемента (до 300 символов).

Ограничения целостности:

  • Код справочника уникален.
  • Пара (refbook, version) уникальна.
  • Для одного справочника нельзя создать две версии с одинаковой датой начала действия.
  • Пара (version, code) уникальна: код элемента не повторяется внутри одной версии, но может использоваться в других версиях.
  • При удалении справочника удаляются его версии и элементы; при удалении версии — принадлежащие ей элементы.

Текущая версия:

  • Текущей считается версия с максимальной датой начала действия, которая не превышает текущую дату (version.date <= today)
  • Версии с будущей датой и версии без даты начала действия не выбираются в качестве текущих.
  • Если подходящей версии нет, API элементов и проверки элемента без параметра version возвращает HTTP 404.

Запуск проекта

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

Для быстрого запуска необходимо установить Docker и Docker Compose.

Выполните следующие команды:

git clone https://github.com/NikPACodes/TerminologyService.git
cd TerminologyService
cp .env.example .env.dev
make dev-build
make dev-up-d
make docker-migrate
make docker-createsuperuser

После этого проект будет готов к локальной проверке по адресу http://127.0.0.1:8000/

1. Локальный запуск

Для локального запуска требуется Python 3.12+. Все команды выполняются из корневого каталога проекта.

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

Через Makefile:

make local-setup

Или вручную:

# Создание и активация виртуального окружения
python3.12 -m venv .venv
source .venv/bin/activate

# Установка проекта и зависимостей для разработки
pip install -e ".[dev]"

1.2. Настройка окружения

Создайте файл .env.dev на основе примера:

cp .env.example .env.dev

Укажите необходимые переменные окружения:

DJANGO_SETTINGS_MODULE=config.settings.dev
DJANGO_SECRET_KEY=replace-with-your-development-secret-key
DJANGO_ALLOWED_HOSTS=127.0.0.1,localhost

DJANGO_SECRET_KEY необходимо заменить собственным значением. Приведённый ключ предназначен только для примера.

1.3. Инициализация и запуск приложения

Через Makefile:

# Применение миграций
make local-migrate

# Создание суперпользователя Django
make local-createsuperuser

# Запуск сервера
make local-run

Или вручную (в активированном виртуальном окружении):

python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

После запуска приложение будет доступно по адресу: http://127.0.0.1:8000/

Корневой URL не содержит отдельной главной страницы.
Для работы с приложением используйте REST API, административную панель Django и интерактивную документацию Swagger UI / ReDoc.

2. Запуск через Docker Compose

Для запуска приложения в Docker необходимо установить Docker и Docker Compose. Все команды выполняются из корневого каталога проекта.

2.1. Настройка окружения

Создайте файл .env.dev на основе примера:

cp .env.example .env.dev

Укажите необходимые переменные окружения:

DJANGO_SETTINGS_MODULE=config.settings.dev
DJANGO_SECRET_KEY=replace-with-your-development-secret-key
DJANGO_ALLOWED_HOSTS=127.0.0.1,localhost

DJANGO_SECRET_KEY необходимо заменить собственным значением. Приведённый ключ предназначен только для примера.

2.2. Сборка и запуск контейнера

Через Makefile:

# Сборка Docker-образа
make dev-build

# Запуск контейнера в фоновом режиме
make dev-up-d

Или вручную:

docker compose -f docker-compose.dev.yaml up --build -d

2.3. Инициализация базы данных

После первого запуска необходимо применить миграции и создать суперпользователя Django.

Через Makefile:

# Применение миграций
make docker-migrate

# Создание суперпользователя
make docker-createsuperuser

Или вручную:

docker compose -f docker-compose.dev.yaml exec app python manage.py migrate
docker compose -f docker-compose.dev.yaml exec app python manage.py createsuperuser

После запуска приложение будет доступно по адресу: http://127.0.0.1:8000/

Режим отладки в Docker

Для отладки приложения предусмотрена дополнительная конфигурация docker-compose.debug.yaml, использующая debugpy.

Перед запуском режима отладки остановите обычный dev-контейнер, если он уже запущен:

make dev-down

Через Makefile:

# Сборка Docker-образа
make debug-build

# Запуск контейнера в режиме отладки
make debug-up

Или вручную:

docker compose \
    -f docker-compose.dev.yaml \
    -f docker-compose.debug.yaml \
    up --build

Отладчик ожидает подключения IDE по адресу 127.0.0.1:5678.

Для подключения настройте в IDE конфигурацию Python Debug Server / Attach to Process с параметрами:

  • Host: 127.0.0.1
  • Port: 5678
  • Путь в контейнере: /app

В режиме отладки используется параметр --wait-for-client, поэтому Django-сервер начнёт работу только после подключения отладчика.


REST API

Базовый адрес локального API: http://127.0.0.1:8000.

  • Публичные методы работают без авторизации и возвращают JSON.
  • API предназначен только для чтения.
Метод Путь Назначение
GET /refbooks/ Получить список справочников
GET /refbooks/?date=YYYY-MM-DD Получить справочники, имеющие версии с датой начала действия не позднее указанной
GET /refbooks/{id}/ Получить справочник с описанием
GET /refbooks/{id}/elements Получить элементы текущей версии
GET /refbooks/{id}/elements?version=v1.0 Получить элементы конкретной версии
GET /refbooks/{id}/check_element?code=...&value=... Проверить элемент в текущей версии
GET /refbooks/{id}/check_element?code=...&value=...&version=v1.0 Проверить элемент в указанной версии

1. Получение справочников

curl "http://127.0.0.1:8000/refbooks/"

С фильтрацией по дате:

curl "http://127.0.0.1:8000/refbooks/?date=2026-10-01"

Пример ответа 200 OK:

{
  "refbooks": [
    {
      "id": 1,
      "code": "ICD-10",
      "name": "Международная классификация болезней"
    }
  ]
}
  • Если справочников, удовлетворяющих фильтру, нет, то возвращается {"refbooks": []}.
  • Если параметр date не указан, возвращаются все справочники, в том числе не имеющие версий.
  • Параметр date является опциональным.

2. Получение одного справочника

curl "http://127.0.0.1:8000/refbooks/1/"

Пример ответа 200 OK:

{
  "id": 1,
  "code": "ICD-10",
  "name": "Международная классификация болезней",
  "description": "Справочник кодов заболеваний"
}
  • Для этого метода также поддерживается необязательный параметр date.
  • Если справочник не найден или не имеет версии с датой начала действия не позднее указанной, возвращается статус 404.

3. Получение элементов версии

Элементы текущей версии:

curl "http://127.0.0.1:8000/refbooks/1/elements"

Элементы конкретной версии:

curl "http://127.0.0.1:8000/refbooks/1/elements?version=v1.0"

Пример ответа 200 OK:

{
  "elements": [
    {
      "code": "S09",
      "value": "Другие и неуточненные травмы головы"
    },
    {
      "code": "G93",
      "value": "Другие поражения головного мозга"
    }
  ]
}
  • Для существующей версии без элементов возвращается {"elements": []}.
  • При отсутствии справочника, заданной версии или текущей версии, возвращается статус 404.

4. Проверка элемента

Для проверки нужны обязательные параметры code и value.
Параметр version необязателен: без него проверяется текущая версия.

curl -G "http://127.0.0.1:8000/refbooks/1/check_element" \
  --data-urlencode "code=S09" \
  --data-urlencode "value=Другие и неуточненные травмы головы" \
  --data-urlencode "version=v1.0"

Если элемент найден (200 OK):

{"check": true}

Если элемент не найден (200 OK):

{"check": false}
  • Проверяется точное совпадение кода и значения в одной версии.
  • Пробелы по краям value учитываются.
  • Пробелы по краям code удаляются при обработке параметра.
  • При отсутствии обязательных параметров, возвращается 400
  • При отсутствии справочника или версии, возвращается 404.

Статусы ответов

HTTP Значение
200 OK Запрос выполнен; результат может быть пустым или check: false
400 Bad Request Некорректные параметры запроса
404 Not Found Не найден справочник или версия, включая отсутствие текущей версии
405 Method Not Allowed Неподдерживаемый HTTP-метод
Приведённые JSON-ответы являются примерами: после первого запуска база может быть пустой.

Добавить реальные справочники можно через административную панель.


Панель администратора

Адрес: http://127.0.0.1:8000/admin/

Используйте учётную запись, созданную командой python manage.py createsuperuser.

В Django Admin доступны:

  • создание, редактирование и удаление справочников;
  • редактирование версий непосредственно на странице справочника;
  • отображение текущей версии и даты начала действия в перечне справочников;
  • создание и редактирование версий с выбором справочника и даты;
  • редактирование элементов непосредственно на странице версии;
  • отдельное управление элементами справочников.

Интерфейс настроен на русский язык.

Для сокращения числа запросов к БД в административной панели используются Subquery и select_related.


Документация API

После запуска сервиса доступны:

Документация описывает параметры, структуры ответов, коды ошибок и примеры запросов.


Тестирование

Для автоматизированного тестирования используются pytest и pytest-django.

Тесты выполняются с настройками config.settings.test на отдельной тестовой базе SQLite, не затрагивая данные основного приложения.

1. Локальный запуск тестов

Перед запуском убедитесь, что установлены зависимости для разработки и активировано виртуальное окружение.

Через Makefile:

make local-tests

Или вручную:

pytest -v

2. Выборочный запуск тестов

Для запуска отдельных групп тестов можно указать соответствующий каталог:

# Тесты моделей
pytest terminology/tests/models/ -v

# Тесты REST API
pytest terminology/tests/api/ -v

Также поддерживается фильтрация по зарегистрированным маркерам:

# Базовые проверки
pytest -m smoke -v

# Тесты моделей
pytest -m models -v

# Все тесты API
pytest -m api -v

Перечень доступных маркеров:

HTTP Значение
smoke Базовая проверка работоспособности
models Тестирование моделей Django
refbook Тестирование модели Refbook
version Тестирование модели RefbookVersion
element Тестирование модели RefbookElement
api Тестирование REST API
api_refbooks Получение и фильтрация справочников
api_elements Получение элементов справочника
api_check Проверка существования элемента

3. Запуск тестов в Docker

Тесты можно выполнять непосредственно в запущенном Docker-контейнере.

Через Makefile (рекомендуется):

make docker-tests

Или вручную:

docker compose -f docker-compose.dev.yaml exec app pytest -v

4. Проверяемые сценарии

Автоматические тесты охватывают:

  • Создание и удаление моделей, каскадное удаление связанных объектов.
  • Проверку ограничений уникальности на уровне базы данных.
  • Получение и фильтрацию справочников по дате.
  • Выбор текущей и явно указанной версии справочника.
  • Получение элементов и проверку соответствия кода значению.
  • Формат JSON-ответов и обработку ошибок API.

Отдельный файл .env.test не требуется: тестовые настройки предусматривают резервный SECRET_KEY.


Лицензия

Этот репозиторий содержит упрощённую демонстрационную версию проекта.

Исходный код доступен исключительно для ознакомления, изучения и оценки. Копирование, изменение, распространение и использование в других проектах без письменного разрешения правообладателя запрещены, за исключением случаев, предусмотренных законодательством и условиями GitHub.

Все права защищены.

Подробные условия приведены в файле LICENSE.

About

TerminologyService — сервис нормативно-справочной информации на Django.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages