TerminologyService — сервис нормативно-справочной информации на Python и Django.
Сервис хранит справочники, их версии и элементы (пары «код — значение»),
а также предоставляет REST API для получения справочных данных
и проверки принадлежности элемента определённой версии.
API— предназначен для чтения данных.Django Admin— предназначен для управления справочниками, версиями и элементами.
- TerminologyService
- Хранение справочников с уникальным кодом, наименованием и описанием.
- Версионирование справочников с датой начала действия каждой версии.
- Автоматический выбор текущей версии по дате.
- Получение списка справочников с необязательной фильтрацией по дате.
- Получение элементов текущей или явно указанной версии.
- Проверка существования элемента по точной паре
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возвращает HTTP404.
Для быстрого запуска необходимо установить
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/
Для локального запуска требуется
Python 3.12+. Все команды выполняются из корневого каталога проекта.
Через Makefile:
make local-setupИли вручную:
# Создание и активация виртуального окружения
python3.12 -m venv .venv
source .venv/bin/activate
# Установка проекта и зависимостей для разработки
pip install -e ".[dev]"Создайте файл .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необходимо заменить собственным значением. Приведённый ключ предназначен только для примера.
Через 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.
Для запуска приложения в Docker необходимо установить
DockerиDocker Compose. Все команды выполняются из корневого каталога проекта.
Создайте файл .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необходимо заменить собственным значением. Приведённый ключ предназначен только для примера.
Через Makefile:
# Сборка Docker-образа
make dev-build
# Запуск контейнера в фоновом режиме
make dev-up-dИли вручную:
docker compose -f docker-compose.dev.yaml up --build -dПосле первого запуска необходимо применить миграции и создать суперпользователя 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-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-сервер начнёт работу только после подключения отладчика.
Базовый адрес локального 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 |
Проверить элемент в указанной версии |
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является опциональным.
curl "http://127.0.0.1:8000/refbooks/1/"Пример ответа 200 OK:
{
"id": 1,
"code": "ICD-10",
"name": "Международная классификация болезней",
"description": "Справочник кодов заболеваний"
}- Для этого метода также поддерживается необязательный параметр
date. - Если справочник не найден или не имеет версии с датой начала действия не позднее указанной, возвращается статус
404.
Элементы текущей версии:
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.
Для проверки нужны обязательные параметры 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.
После запуска сервиса доступны:
- Swagger UI: http://127.0.0.1:8000/docs/swagger/
- ReDoc: http://127.0.0.1:8000/docs/redoc/
- OpenAPI Schema: http://127.0.0.1:8000/docs/schema/
Документация описывает параметры, структуры ответов, коды ошибок и примеры запросов.
Для автоматизированного тестирования используются pytest и pytest-django.
Тесты выполняются с настройками config.settings.test на отдельной тестовой базе SQLite,
не затрагивая данные основного приложения.
Перед запуском убедитесь, что установлены зависимости для разработки и активировано виртуальное окружение.
Через Makefile:
make local-testsИли вручную:
pytest -vДля запуска отдельных групп тестов можно указать соответствующий каталог:
# Тесты моделей
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 |
Проверка существования элемента |
Тесты можно выполнять непосредственно в запущенном Docker-контейнере.
Через Makefile (рекомендуется):
make docker-testsИли вручную:
docker compose -f docker-compose.dev.yaml exec app pytest -vАвтоматические тесты охватывают:
- Создание и удаление моделей, каскадное удаление связанных объектов.
- Проверку ограничений уникальности на уровне базы данных.
- Получение и фильтрацию справочников по дате.
- Выбор текущей и явно указанной версии справочника.
- Получение элементов и проверку соответствия кода значению.
- Формат JSON-ответов и обработку ошибок API.
Отдельный файл
.env.testне требуется: тестовые настройки предусматривают резервныйSECRET_KEY.
Этот репозиторий содержит упрощённую демонстрационную версию проекта.
Исходный код доступен исключительно для ознакомления, изучения и оценки. Копирование, изменение, распространение и использование в других проектах без письменного разрешения правообладателя запрещены, за исключением случаев, предусмотренных законодательством и условиями GitHub.
Все права защищены.
Подробные условия приведены в файле LICENSE.