PetTrace

Информационная система для автоматизации процессов ветеринарной клиники: регистратура, приемы, лаборатория, склад, финансы, CRM, отчеты и аудит.

Содержание

• 1. Назначение и текущее покрытие
• 2. Быстрый старт (Docker)
• 3. Первый вход и базовая настройка
• 4. Роли и права доступа
  • 4.4 Пошаговые инструкции по ролям
• 5. Полное руководство пользователя (Web UI)
  • 5.16 Пошаговые инструкции по каждому модулю
• 6. Сквозные рабочие сценарии
• 7. Полное руководство по API
• 8. Автоматизация и фоновые процессы
• 9. Администрирование и эксплуатация
  • 9.1 Что именно попадает в БД при крупном демо-сидинге
• 10. Локальный запуск без Docker
• 11. Тесты и контроль качества
• 12. Основные бизнес-сущности
• 13. Диагностика проблем (Troubleshooting)
• 14. Архитектура проекта
• 15. Дальнейшее развитие

1. Назначение и текущее покрытие

Что уже реализовано

• Полноценный backend с RBAC, аудитом и workflow-переходами.
• Рабочий Web UI (server-rendered) для ежедневных задач:
  • вход в систему;
  • дашборд;
  • владельцы и питомцы;
  • табло записей/очереди;
  • карточка визита (осмотр, диагнозы, назначения, процедуры, события);
  • лабораторное табло (статусы заказов/образцов, утверждение результатов).
• Полный API-контур для всех доменов (включая clinical, inventory, billing, reports).

Что пока в основном через API/Admin

• Расширенный контур CRM-коммуникаций (массовые/сложные сценарии dispatch).
• Операции склада закупок (детальный операционный интерфейс по партиям и движениям).
• Отчеты расширенного уровня (экспортные и аналитические срезы).

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

• Python 3.12
• Django 5.x + Django REST Framework
• PostgreSQL 16
• Redis 7
• Celery (worker, beat, Flower)
• Gunicorn + WhiteNoise
• Docker Compose (Nginx профиль для prod)
• Ruff + Django test suite (59 автотестов)

Назначение компонентов стека (кто за что отвечает)

• Django + DRF: основной backend, бизнес-логика, Web UI, API, RBAC, валидации, workflow.
• PostgreSQL: основная транзакционная БД (владельцы, питомцы, визиты, лаборатория, склад, финансы, аудит).
• Redis:
  • кэш Django (REDIS_URL, обычно redis://redis:6379/0);
  • кэш отчетов и версионирование ключей отчетности;
  • брокер Celery (CELERY_BROKER_URL, обычно redis://redis:6379/1);
  • backend результатов Celery (CELERY_RESULT_BACKEND, обычно redis://redis:6379/2).
• Celery worker: выполнение фоновых задач (уведомления, SLA, dispatch, прогрев отчетов).
• Celery beat: запуск периодических задач по расписанию.
• Flower: мониторинг очередей и задач Celery (http://localhost:5555/).
• Gunicorn: WSGI-сервер приложения в контейнере web.
• WhiteNoise: отдача статических файлов Django без отдельного static-сервера в dev-сценарии.
• Nginx (profile prod): reverse proxy и отдача static/media в production-профиле.
• Docker Compose: оркестрация сервисов и зависимостей проекта.

Быстрая проверка инфраструктурных модулей

# Проверка PostgreSQL
docker compose exec postgres pg_isready -U pettrace -d pettrace

# Проверка Redis
docker compose exec redis redis-cli ping

# Проверка Celery worker
docker compose exec celery_worker celery -A config inspect ping

# Открыть Flower UI
open http://localhost:5555/

2. Быстрый старт (Docker)

Предварительные требования

• Docker Desktop (или Docker Engine + Compose).
• Свободные порты: 8000, 5432, 6379, 5555.

Шаги запуска

1. Создайте .env из примера:
   • Linux/macOS: cp .env.example .env
   • PowerShell: Copy-Item .env.example .env
2. Запустите стек:
   • docker compose up --build
3. Откройте сервисы:
   • Web console: http://localhost:8000/
   • API root: http://localhost:8000/api/
   • Admin: http://localhost:8000/admin/
   • Health: http://localhost:8000/health/
   • OpenAPI schema: http://localhost:8000/api/schema/
   • Swagger UI: http://localhost:8000/api/docs/swagger/
   • ReDoc: http://localhost:8000/api/docs/redoc/
   • Flower: http://localhost:5555/

Интерфейс пользователя и Django Admin русифицированы (подписи, статусы, справочники).

Что запускается автоматически в web

• python manage.py migrate --noinput
• python manage.py bootstrap_rbac
• python manage.py bootstrap_facilities
• python manage.py create_initial_superuser
• python manage.py collectstatic --noinput

Статика Web UI отдается через WhiteNoise.

3. Первый вход и базовая настройка

Данные первого superuser

Логин и пароль берутся из .env:

• SUPERUSER_EMAIL
• SUPERUSER_PASSWORD

Для текущей dev-конфигурации из примера:

• email: admin@pettrace.local
• password: admin123

Первые шаги после входа

1. Проверьте группы и права (/admin/auth/group/).
2. Создайте сотрудников в /admin/users/user/.
3. Назначьте пользователей в нужные группы:
   • registrar, veterinarian, assistant, lab_technician, inventory_manager, cashier.
4. Заполните базовые справочники:
   • филиалы и кабинеты;
   • типы оборудования и оборудование;
   • требования услуг (если используете ресурсное планирование по кабинетам/оборудованию).
5. При необходимости настройте персональный доступ сотрудника:
   • /admin/users/useraccessprofile/
   • или POST /api/user-access-profiles/.

4. Роли и права доступа

Группы по умолчанию:

• administrator
• registrar
• veterinarian
• assistant
• lab_technician
• inventory_manager
• cashier

Ресинхронизация RBAC:

python src/manage.py bootstrap_rbac

Развернуть базовую структуру филиалов/кабинетов:

python src/manage.py bootstrap_facilities

Ключевые доменные разрешения:

• visits.close_visit
• labs.approve_lab_result
• inventory.write_off_stock
• clinical.apply_clinical_protocol
• crm.dispatch_communication

Если пользователю не хватает прав, Web UI и API возвращают 403 Forbidden.

4.1 Детальная ролевая матрица

Роль	Основные UI-кабинеты	Ключевые действия	Что ограничено
administrator	Все разделы: дашборд, приемы, лаборатория, документы, стационар, MAR, финансы	Полный контроль данных, ролей, справочников, workflow и аудита	Ограничений нет (кроме бизнес-валидаций).
registrar	Дашборд, приемы/очередь, документы, стационар (операционные действия), финансы (просмотр)	Регистрация владельцев/животных, запись на прием, check-in, оформление документов, координация госпитализации	Нет клинического закрытия визита и утверждения лабораторных результатов.
veterinarian	Дашборд, приемы, лаборатория, документы, стационар, MAR, финансы	Полное ведение приема, назначения/процедуры, госпитализация (bed/vitals/plans), контроль MAR, работа с документами	Не выполняет админ-настройки пользователей/глобальных прав.
assistant	Дашборд, приемы, лаборатория, документы, стационар, MAR	Исполнение процедур и заборов, переходы лабораторных статусов, фиксация vitals и MAR	Нет прав закрытия визита close_visit, ограниченные финансовые операции.
lab_technician	Дашборд, лаборатория, документы	Прием/обработка образцов, внесение и утверждение результатов, лабораторные документы	Нет управления приемами/финансами/клиническим закрытием визита.
inventory_manager	Дашборд, MAR	Контроль списаний и остатков по факту выполнения, учет движений/партий через API/Admin	Нет клинических и финансовых действий в визите.
cashier	Дашборд, документы, финансы	Создание/ведение счетов, позиции, оплаты, скидки, корректировки платежей	Нет клинических изменений приема и лабораторных workflow-действий.

Примечание: фактическая доступность модулей зависит от группы пользователя и от персонального UserAccessProfile (филиалы/кабинеты/assigned scope).

Скоуп по ролям и кабинетам

Система применяет ограничения в 2 слоя:

1. Базовый ролевой скоуп (по группе пользователя) на типы кабинетов.
2. Персональный скоуп через UserAccessProfile:
   • home_branch
   • allowed_branches
   • allowed_cabinets
   • limit_to_assigned_cabinets

Ограничения применяются в API и Web UI для расписания, визитов, лаборатории, задач, финансов и справочников кабинетов.

4.2 Детально по каждой роли: что именно можно делать

Ниже приведен практический разбор роли в терминах ежедневных действий, а не только permission-кодов.

administrator

• Полный доступ ко всем разделам Web UI, Admin и API.
• Управление пользователями, группами, правами, ролью и скоупами (UserAccessProfile).
• Настройка справочников: филиалы, кабинеты, койки, оборудование, требования услуг.
• Контроль и коррекция данных в любом домене:
  • CRM/пациенты;
  • приемы/визиты/стационар;
  • лаборатория;
  • склад;
  • финансы;
  • документы;
  • отчеты и аудит.
• Эксплуатационные функции: bootstrap, сидинг, миграции, контроль фоновых задач, диагностика.

registrar

• Регистрация и ведение клиентской базы:
  • создание/редактирование владельцев;
  • создание/редактирование карточек животных;
  • согласия на обработку данных;
  • теги клиентов, напоминания и коммуникации.
• Полный фронт-офис записи:
  • создание записи на прием;
  • check-in;
  • перевод записи по рабочим статусам в рамках разрешенных переходов;
  • координация маршрута пациента между кабинетом, врачом и лабораторией.
• Визитный контур (операционно):
  • просмотр визита;
  • создание/редактирование визита без клинического закрытия.
• Документы:
  • создание/загрузка клинических вложений;
  • работа с шаблонами документов и просмотр сгенерированных форм.
• Что ограничено:
  • нет права visits.close_visit;
  • нет права утверждения лабораторных результатов labs.approve_lab_result;
  • нет полноценного кассового контура (инвойсы/оплаты только на чтение в UI).

veterinarian

• Полный клинический цикл по приему:
  • ведение осмотра и анамнеза;
  • постановка диагнозов;
  • назначения, процедуры, наблюдения;
  • перевод визита по статусам вплоть до закрытия (close_visit).
• Лаборатория:
  • создание и ведение заказов/тестов/образцов;
  • внесение результатов;
  • работа с повторными заборами.
• Клинический движок:
  • применение протоколов лечения (clinical.apply_clinical_protocol);
  • работа с противопоказаниями, алертами, чек-листами.
• Стационар и MAR:
  • госпитализация, койко-места, vitals, план процедур;
  • контроль введений препаратов и статусов MAR.
• Документы и задачи:
  • формирование клинических документов;
  • работа с задачами и уведомлениями.
• Что ограничено:
  • администрирование пользователей и глобальной RBAC-конфигурации.

assistant

• Исполнение процедурного контура:
  • сопровождение записи/приема в части исполнения;
  • изменение визита в рамках операционной работы без права закрытия.
• Лаборатория:
  • забор и обработка образцов;
  • перевод статусов заказа/образцов;
  • подготовка контейнеров, связка с пробирками.
• Стационар:
  • создание/ведение госпитализации;
  • заполнение vitals;
  • ведение госпитального плана процедур.
• MAR:
  • ведение введений (GIVEN, SKIPPED, CANCELED);
  • фиксация фактических параметров и отклонений;
  • списание препаратов/материалов по факту.
• Документы и задачи:
  • создание клинических вложений;
  • постановка и ведение задач.
• Что ограничено:
  • нет visits.close_visit;
  • нет кассового закрытия и подтверждения лабораторных результатов.

lab_technician

• Полный лабораторный pipeline:
  • обработка LabOrder/LabTest/Specimen;
  • перевод статусов на этапах обработки;
  • работа с событиями образца и маркировкой.
• Ведение результатов:
  • внесение LabResultValue;
  • утверждение результатов (approve_lab_result).
• Работа с лабораторными документами:
  • загрузка и обновление вложений;
  • использование шаблонов документов и просмотр генераций.
• Что ограничено:
  • нет кассового, складского и клинического закрытия визита;
  • не ведет фронт-офисную часть регистратора.

inventory_manager

• Складской контур:
  • номенклатура (InventoryItem);
  • партии (Batch);
  • движения (StockMovement);
  • корректировка связки пробирок и материалов;
  • право write_off_stock.
• Ресурсный контур клиники:
  • оборудование и типы оборудования;
  • контроль обеспеченности услуг ресурсами.
• Что ограничено:
  • не ведет клинический визит;
  • не выполняет лабораторное утверждение;
  • не ведет кассовые операции.
• Примечание:
  • значимая часть глубоких операций склада доступна через API/Admin (в UI в основном оперативный контроль через MAR/дашборд).

cashier

• Финансовый контур приема:
  • создание/редактирование инвойсов;
  • добавление/изменение позиций инвойса;
  • проведение и контроль статусов счета.
• Платежи:
  • регистрация оплат;
  • учет корректировок (refund/correction);
  • проверка полноты оплаты.
• Скидки и прайс:
  • работа с прайс-позициями;
  • правила скидок и промо-механики.
• Документный контур:
  • просмотр сгенерированных документов для закрытия расчетов.
• Что ограничено:
  • нет клинических прав на изменение медицинской части визита;
  • нет управления лабораторным workflow.

4.3 Ограничения и разделение ответственности

• Клиническое решение и закрытие визита: veterinarian (или administrator).
• Утверждение лабораторного результата: lab_technician (или administrator).
• Складское списание как отдельное полномочие: inventory_manager через write_off_stock.
• Финансовые корректировки и закрытие расчетов: cashier (или administrator).
• Фронт-офис и запись: registrar.
• Исполнительный медицинский контур: assistant.

4.4 Пошаговые инструкции по ролям

administrator: ежедневный регламент

1. Войти под админом и открыть GET /home/administrator/.
2. Проверить GET /dashboard/: визиты в работе, критические лабораторные результаты, неоплаченные счета.
3. Проверить пользователей и роли в /admin/users/user/ и /admin/auth/group/.
4. Проверить персональные скоупы в /admin/users/useraccessprofile/.
5. При изменениях модели доступа выполнить python src/manage.py bootstrap_rbac.
6. Проверить эксплуатационные задачи: Celery/Beat/Flower, отчеты, аудит.
7. Перед окончанием смены убедиться, что нет незакрытых инцидентов в задачах и уведомлениях.

registrar: инструкция по рабочей смене

1. Открыть GET /home/registrar/ и проверить очередь на сегодня.
2. В GET /owners/new/ создать владельца или найти существующего в GET /owners/.
3. В GET /pets/new/ создать питомца или выбрать существующего в GET /pets/.
4. В GET /appointments/new/ оформить запись: врач, кабинет, время, длительность.
5. При прибытии клиента сделать Check-in в GET /appointments/.
6. Передать пациента врачу, отслеживать статус записи и визита до завершения маршрута.
7. При необходимости оформить документы/вложения в GET /documents/.

veterinarian: инструкция по приему

1. Открыть GET /home/veterinarian/ и перейти к приему из GET /appointments/.
2. В карточке GET /visits/{id}/ заполнить жалобы, анамнез, осмотр.
3. Добавить диагнозы, наблюдения, назначения и процедуры.
4. При необходимости создать/обновить лабораторный заказ и клинические документы.
5. При госпитализации перевести пациента в GET /hospitalization/, назначить койку и план.
6. Контролировать исполнение назначений через GET /mar/.
7. Завершить/закрыть визит с учетом клинических и финансовых правил.

assistant: инструкция по исполнению назначений

1. Открыть GET /home/assistant/ и список активных задач.
2. В GET /appointments/ и GET /visits/{id}/ взять в работу назначения врача.
3. Выполнить заборы и процедурные действия, обновить статусы выполнения.
4. В GET /labs/ перевести образцы по этапам обработки.
5. В GET /hospitalization/ зафиксировать vitals и обновить план госпитальных процедур.
6. В GET /mar/ отметить факт введения препаратов (GIVEN/SKIPPED/CANCELED).
7. Проверить, что задачи закрыты или переданы на следующий этап без пропусков.

lab_technician: инструкция по лабораторному циклу

1. Открыть GET /home/lab_technician/ и лабораторное табло GET /labs/.
2. Принять заказ и образцы, перевести статусы LabOrder и Specimen по pipeline.
3. Проверить корректность маркировки/контейнеров и связки с пробирками.
4. Внести результаты анализов по тестам.
5. Для валидных результатов выполнить утверждение (approve), включая критические.
6. При проблемах инициировать повторный забор и уведомить врача через задачи/нотификации.
7. Завершить заказ до статуса DONE и убедиться, что SLA зафиксирован корректно.

inventory_manager: инструкция по складу

1. Проверить остатки и движения через API/Admin (/api/items/, /api/batches/, /api/movements/).
2. Обновить партии, сроки годности и минимальные остатки.
3. Проверить списания по лаборатории и MAR, сверить причины и источники операций.
4. Выполнить необходимые корректировки движений/партий.
5. Проверить связки расходников с лабораторными пробирками.
6. Подготовить оперативный отчет по дефицитам и рискам обеспечения услуг.

cashier: инструкция по закрытию финансового контура

1. Открыть GET /home/cashier/ и модуль GET /finance/.
2. Найти визит, убедиться, что счет создан, иначе создать новый.
3. Проверить и скорректировать позиции счета, применить скидку/правило при необходимости.
4. Сформировать и провести счет (FORMED/POSTED).
5. Зарегистрировать оплату (полную или частичную).
6. При возврате/исправлении провести корректировку платежа.
7. Убедиться, что итоговый статус счета и связанного визита корректен.

5. Полное руководство пользователя (Web UI)

Точки входа Web UI:

• GET /login/
• GET /home/, GET /home/{role}/
• GET /dashboard/
• GET /owners/, GET /owners/new/
• GET /pets/, GET /pets/new/
• GET /appointments/, GET /appointments/new/
• GET /visits/{id}/
• GET /labs/
• GET /cabinets/, GET /cabinets/{role}/
• GET /documents/
• GET /hospitalization/
• GET /mar/
• GET /finance/

5.1 Вход в систему

1. Откройте http://localhost:8000/login/.
2. Введите email и пароль сотрудника.
3. После входа откроется домашний ролевой экран.

5.2 Домашний экран по роли (/home/, /home/{role}/)

Что дает:

• отдельную стартовую страницу под каждую роль;
• role-specific KPI и списки задач;
• быстрые действия только по доступным разделам;
• переключение между ролями, если пользователь состоит в нескольких группах.

5.3 Дашборд (/dashboard/)

Показывает оперативные метрики:

• приемы за сегодня;
• живая очередь;
• визиты в работе;
• активные лабораторные заказы;
• просроченные задачи;
• последние визиты и лабораторные события.

5.4 Владельцы (/owners/)

Что можно делать:

• искать владельцев по имени, телефону, email;
• видеть статус black-list, скидку, предпочитаемый филиал;
• создавать владельца (/owners/new/).

Поля владельца:

• имя, фамилия, телефон, email;
• скидка;
• black-list;
• адрес и заметки;
• предпочитаемый филиал.

5.5 Животные (/pets/)

Что можно делать:

• искать по кличке, владельцу, microchip_id;
• создавать карточку животного (/pets/new/).

Поля животного:

• владелец;
• кличка, вид, порода, пол;
• дата рождения, вес;
• аллергии, вакцинации;
• microchip_id (15 цифр, если задан);
• страховой номер, статус.

5.6 Записи и очередь (/appointments/)

Создание записи (/appointments/new/)

1. Укажите владельца и питомца.
2. Выберите врача, услугу, филиал, кабинет.
3. Укажите время начала и длительность.
4. Сохраните запись.

Система автоматически:

• проверяет конфликт по кабинету;
• учитывает требования услуги к типу кабинета и оборудованию;
• выставляет end_at;
• подставляет комнату из кабинета.

Работа с очередью

Для каждой записи доступны действия (зависит от прав и статуса):

• Check-in
• Начать визит
• Завершить
• Сменить статус (только допустимые переходы)

Стандартные статусы записи:

• BOOKED
• CHECKED_IN
• IN_ROOM
• COMPLETED
• CANCELED
• NO_SHOW

5.7 Карточка визита (/visits/{id}/)

Доступно:

• изменение клинической части визита:
  • жалобы;
  • анамнез;
  • осмотр;
  • summary диагноза;
  • рекомендации;
• перевод статусов визита;
• добавление диагнозов;
• добавление назначений;
• добавление процедур;
• просмотр истории событий визита;
• просмотр связанных лабораторных заказов;
• просмотр клинических предупреждений (если есть право).

Стандартные статусы визита:

• SCHEDULED
• WAITING
• IN_PROGRESS
• COMPLETED
• CLOSED
• CANCELED

5.8 Лабораторное табло (/labs/)

Функции:

• фильтрация заказов по статусу;
• перевод статусов LabOrder;
• перевод статусов Specimen;
• просмотр неутвержденных результатов;
• утверждение результата (при праве approve_lab_result).

Типовой pipeline:

• LabOrder: PLANNED -> COLLECTED -> IN_TRANSPORT -> RECEIVED -> IN_PROCESS -> DONE
• Specimen: PLANNED -> COLLECTED -> IN_TRANSPORT -> RECEIVED -> IN_PROCESS -> DONE

5.9 Ролевые кабинеты (/cabinets/)

• Экран агрегирует доступные рабочие зоны по ролям пользователя.
• Для каждой роли отображаются доступные модули на основе текущих permissions.
• В карточке роли есть отдельная страница с функциональным описанием и быстрыми переходами.

5.10 Документы и медиа (/documents/)

Функции:

• загрузка вложений на уровень визита/пациента/лабораторного заказа;
• типизация (XRAY, ULTRASOUND, PHOTO, PDF_RESULT, ...);
• версионирование документа (замена файла с аудитом);
• генерация PDF по шаблонам (DocumentTemplate) с JSON payload.

5.11 Стационар (/hospitalization/)

Функции:

• создание госпитализации из визита;
• назначение/перемещение/освобождение койко-места (bed management);
• перевод статусов госпитализации;
• заполнение витальных показателей (vitals);
• планирование и обновление статусов госпитальных процедур.

5.12 MAR (/mar/)

Функции:

• создание плановых записей медикаментозного введения;
• отметка GIVEN, SKIPPED, CANCELED;
• фиксация фактической дозы/пути введения/отклонений;
• списание со склада по факту введения (при наличии связанного InventoryItem).

5.13 Финансы (/finance/)

Функции:

• создание счета по визиту;
• добавление и сторнирование позиций;
• формирование/проведение счета;
• применение скидок (правила/промокод);
• регистрация оплат и корректировок (refund/correction);
• автообновление статуса счета и авто-закрытие визита после полной оплаты (по настройке).

5.14 Что остается через API/Admin

• сложные CRM-сценарии массовых коммуникаций;
• расширенный складской контур закупок/поставок;
• специализированные отчеты и экспортные формы.

5.15 Полный каталог функционала по модулям

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

users / доступ

• аутентификация сотрудников (session auth);
• ролевой доступ через группы;
• персональный скоуп по филиалам/кабинетам (UserAccessProfile);
• MFA-профили и централизованное администрирование доступа;
• проверка прав на уровне API и Web UI.

facilities / ресурсы клиники

• филиалы, кабинеты, койки стационара;
• оборудование и типы оборудования;
• привязка требований к услугам (кабинет/оборудование);
• контроль доступности ресурсов при записи.

owners + pets + crm

• картотека владельцев и животных;
• согласия на обработку персональных данных;
• контактные и клинически значимые атрибуты пациента;
• теги клиентской базы, назначения тегов;
• коммуникации и напоминания (включая отложенный dispatch).

visits / приемы и клинический контур

• запись на прием;
• очередь и операционные статусы записи;
• запуск визита из записи;
• ведение клинической карточки визита;
• диагнозы, наблюдения, назначения, процедуры;
• журнал событий визита (VisitEvent);
• контроль допустимых переходов статусов с валидациями.

clinical

• справочники диагнозов и симптомов;
• клинические протоколы лечения;
• шаблоны медикаментов и процедур внутри протоколов;
• правила противопоказаний;
• клинические алерты;
• чек-листы процедур и выполнение чек-листов.

labs

• лабораторные заказы и тесты;
• образцы и их жизненный цикл;
• пробирки, маркировка, контейнерные метки;
• события обработки образца;
• результаты анализов с флагами (NORMAL/HIGH/CRITICAL);
• утверждение результатов;
• сценарии повторного забора;
• контроль SLA.

inventory

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

billing

• прайс-лист услуг/пакетов;
• инвойсы по визиту;
• строки счета (включая void/storno);
• скидки (правила, промо, owner-scope);
• оплаты разными методами;
• корректировки платежей: возвраты/исправления;
• расчет итогов счета и обновление финансовых статусов.

documents

• клинические вложения и версии файлов;
• политики хранения документов;
• шаблоны документов;
• генерация документов из шаблона с payload;
• контроль доступа к документам по скоупу визита/пациента.

tasks + notifications

• постановка операционных задач;
• приоритеты, дедлайны, жизненный цикл задач;
• связанные задачи по визиту/лаборатории;
• уведомления пользователям (in-app);
• автоматические триггеры уведомлений из workflow.

reports

• операционные отчеты по приемам;
• лабораторная аналитика по turnaround;
• аналитика расхода и использования материалов;
• финансовая аналитика;
• CSV-экспорт и кеширование отчетов;
• прогрев кеша и планировщик обновления.

audit

• журнал ключевых изменений и операций;
• фиксация API-мутаций и статусных переходов;
• трассировка actor/entity/action для контроля и разбора инцидентов.

5.16 Пошаговые инструкции по каждому модулю

users / доступ

1. Создать пользователя в Admin или через /api/users/.
2. Назначить группу(ы) роли.
3. Настроить UserAccessProfile (филиалы/кабинеты/лимиты).
4. Проверить вход пользователя в GET /login/ и доступ к GET /home/{role}/.

facilities / ресурсы клиники

1. Создать филиалы и кабинеты.
2. Добавить койки, типы оборудования и оборудование.
3. Настроить требования услуг к ресурсам.
4. Проверить создание записи на прием без конфликтов ресурса.

owners + pets + crm

1. Создать владельца с контактами и согласием.
2. Создать карточку животного с клинически значимыми полями.
3. Назначить теги клиента.
4. Запланировать коммуникацию/напоминание и проверить dispatch.

visits / приемы и клинический контур

1. Создать запись на прием.
2. Выполнить check-in, затем start-visit.
3. Вести визит: диагнозы, наблюдения, назначения, процедуры.
4. Переводить статусы только по допустимому workflow.
5. Завершить визит и передать его в финансовое закрытие.

clinical

1. Заполнить справочники диагнозов/симптомов.
2. Создать клинический протокол и шаблоны медикаментов/процедур.
3. Добавить правила противопоказаний.
4. Применить протокол к визиту и проверить алерты/чек-листы.

labs

1. Создать LabOrder по визиту.
2. Перевести Specimen и LabOrder по стадиям обработки.
3. Внести LabResultValue по параметрам.
4. Утвердить результат, проверить авто-нотификации для критических флагов.
5. Закрыть заказ в DONE.

hospitalization

1. Создать госпитализацию из визита.
2. Назначить койку и фиксировать перемещения.
3. Заполнять vitals по графику.
4. Вести план госпитальных процедур и статусы выполнения.
5. При выписке перевести госпитализацию в финальный статус.

mar

1. Создать план медикаментозных введений.
2. Фиксировать факт (GIVEN) и отклонения (SKIPPED/CANCELED).
3. Указывать дозы, путь введения и комментарии.
4. Проверять списания со склада, связанные с фактическим введением.

inventory

1. Создать номенклатуру и партии с количеством/сроками.
2. Проводить входящие и расходные движения.
3. Выполнять списания по факту лабораторных/клинических операций.
4. Контролировать min stock и формировать заявки на пополнение.

billing

1. Создать прайс-позиции.
2. Сформировать инвойс по визиту и добавить линии.
3. Применить скидку или правило, пересчитать итоги.
4. Провести счет и зарегистрировать платеж.
5. При необходимости оформить возврат/корректировку.

documents

1. Создать шаблоны документов.
2. Загрузить клинические вложения к визиту/пациенту/заказу.
3. Сгенерировать документ из шаблона и payload.
4. Проверить версионность и доступность документа по скоупу.

tasks + notifications

1. Создать задачу, указать приоритет, дедлайн и исполнителя.
2. Связать задачу с визитом или лабораторным заказом.
3. Контролировать статусы TODO/IN_PROGRESS/DONE.
4. Проверить доставку уведомлений и обработку просроченных задач.

reports

1. Выбрать отчет (labs, inventory, appointments, finance).
2. Указать период date_from/date_to.
3. Для актуализации использовать refresh=true.
4. Для выгрузки включить export=csv.
5. При включенном кеше проверить прогрев через warm_reports_cache.

audit

1. Выполнить тестовую бизнес-операцию (например статусный переход).
2. Открыть журнал аудита.
3. Проверить поля actor/entity/action и время события.
4. Использовать лог для разбора инцидентов и регуляторной отчетности.

6. Сквозные рабочие сценарии

6.1 Регистратор: первичный прием

1. Создать владельца.
2. Создать карточку животного.
3. Создать запись на прием.
4. На стойке регистрации выполнить Check-in.
5. Передать пациента врачу/ассистенту.

6.2 Врач: ведение визита

1. Открыть визит из табло приемов.
2. Заполнить жалобы/анамнез/осмотр.
3. Добавить диагнозы.
4. Добавить назначения и процедуры.
5. Завершить медицинскую часть и перевести статус визита.

6.3 Лаборант: обработка образцов

1. Открыть лабораторное табло.
2. Переводить статусы заказа и образцов по этапам.
3. Вносить/проверять результаты.
4. Утверждать результаты (при наличии права).

6.4 Кассир: закрытие счета

Рабочий путь:

1. Открыть /finance/.
2. Создать счет по визиту (если еще не создан).
3. Добавить позиции и применить скидку при необходимости.
4. Сформировать/провести счет.
5. Зарегистрировать оплату и, при необходимости, корректировку платежа.
6. При полной оплате визит автоматически закрывается (COMPLETED -> CLOSED, если включена политика).

6.5 Склад/закупки

Основной операционный контур сейчас через API/Admin:

• номенклатура;
• партии;
• движения;
• списания;
• контроль остатков.

7. Полное руководство по API

7.1 Аутентификация (Session auth)

Эндпоинты:

• POST /api/auth/login/
• POST /api/auth/logout/
• GET /api/auth/me/

Пример логина:

curl -X POST http://localhost:8000/api/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@pettrace.local","password":"admin123"}'

В ответе login возвращается csrf_token. Для mutating-запросов в session-режиме передавайте CSRF-токен и cookie сессии.

7.2 Основные группы эндпоинтов

Пользователи и доступ:

• /api/users/
• /api/groups/
• /api/user-access-profiles/
• /api/auth/*

Ресурсы клиники:

• /api/branches/
• /api/cabinets/
• /api/equipment-types/
• /api/equipment/
• /api/service-requirements/
• /api/service-requirement-equipment/

CRM и пациенты:

• /api/owners/
• /api/consents/
• /api/pets/
• /api/attachments/
• /api/crm/tags/
• /api/crm/tag-assignments/
• /api/crm/communications/
• /api/crm/reminders/

Приемы и визиты:

• /api/appointments/
• /api/encounters/
• /api/visit-events/
• /api/hospitalizations/
• /api/diagnoses/
• /api/observations/
• /api/prescriptions/
• /api/procedures/

Лаборатория:

• /api/orders/
• /api/tests/
• /api/specimens/
• /api/tubes/
• /api/specimen-tubes/
• /api/labels/
• /api/events/
• /api/results/

Клинические протоколы:

• /api/clinical/protocols/
• /api/clinical/protocol-medications/
• /api/clinical/protocol-procedures/
• /api/clinical/contraindications/
• /api/clinical/alerts/
• /api/clinical/checklists/

Склад:

• /api/items/
• /api/batches/
• /api/movements/

Финансы:

• /api/price-items/
• /api/invoices/
• /api/invoice-lines/
• /api/payments/

Задачи и уведомления:

• /api/tasks/
• /api/notifications/

Аудит и отчеты:

• /api/logs/
• /api/reports/*

7.3 Ключевые workflow-эндпоинты

Приемы:

• POST /api/appointments/{id}/check-in/
• POST /api/appointments/{id}/start-visit/
• POST /api/appointments/{id}/complete/
• POST /api/appointments/{id}/transition/

Визиты:

• POST /api/encounters/{id}/transition/
• POST /api/hospitalizations/{id}/transition/

Лаборатория:

• POST /api/orders/{id}/transition/
• POST /api/specimens/{id}/transition/
• POST /api/specimens/{id}/mark-collected/
• POST /api/results/{id}/approve/

Клинический контур:

• POST /api/clinical/protocols/{id}/apply/
• POST /api/clinical/dose-calc/
• POST /api/clinical/checklists/create-from-template/
• POST /api/clinical/checklists/{id}/complete-item/

CRM:

• POST /api/crm/communications/{id}/dispatch/
• POST /api/crm/communications/dispatch-due/

Отчеты:

• GET /api/reports/labs/turnaround/
• GET /api/reports/inventory/tube-usage/
• GET /api/reports/appointments/operations/
• GET /api/reports/finance/summary/

Параметры отчетов:

• date_from=YYYY-MM-DD
• date_to=YYYY-MM-DD
• export=csv
• refresh=true

8. Автоматизация и фоновые процессы

Лаборатория

• При создании LabOrder автоматически создается задача COLLECT_SPECIMEN.
• При переводе Specimen -> COLLECTED автоматически:
  • создается событие SpecimenEvent;
  • закрываются задачи забора при готовности;
  • создается задача LAB_RECEIVE;
  • выполняется списание пробирок со склада по FEFO через Tube.inventory_item.

Уведомления и клиническая безопасность

• При LabResultValue.flag=CRITICAL автоматически создается уведомление врачу.
• Противопоказания формируют ClinicalAlert.

Финансы

• При полной оплате инвойса визит закрывается автоматически (если это допустимо по статусам).

Периодические задачи Celery Beat

• SLA лаборатории;
• обработка просроченных задач;
• отправка pending notifications;
• dispatch отложенных CRM-коммуникаций;
• прогрев кеша отчетов (если включен).

9. Администрирование и эксплуатация

Полезные команды Makefile:

• make docker-up
• make docker-down
• make docker-logs
• make migrate
• make makemigrations
• make bootstrap-rbac
• make seed-demo
• make seed-demo-reset
• make warm-reports-cache

Скрипт do.py (команды как в демо-ноутбуке):

# показать все команды
python do.py --help

# полный сценарий подготовки демо
python do.py all

# отдельно этапы
python do.py up
python do.py bootstrap
python do.py seed-demo --bulk-cases 240 --days 120
python do.py demo-users
python do.py metrics
python do.py qa
python do.py down

Скрипт release.sh (финальный pre-release/prod прогон):

# показать параметры
./release.sh --help

# полный прогон перед отгрузкой (prod-профиль, build, миграции, проверки, smoke)
./release.sh

# прогон с демо-наполнением БД
./release.sh --with-demo-seed --bulk-cases 240 --days 120

# быстрый прогон без тестов/линта
./release.sh --skip-tests --skip-lint

Крупное демо-заполнение для презентации:

docker compose run --rm web python manage.py bootstrap_rbac
docker compose run --rm web python manage.py seed_demo_data --reset --bulk-cases 240 --days 120

Данные при развертке на сервере:

• Демо-данные не создаются автоматически, если явно не запускать seed_demo_data.
• Данные сохраняются между рестартами контейнеров благодаря named volume postgres_data.
• Данные будут потеряны только при удалении volume (например docker compose down -v) или очистке БД.

Демо-учетки после сидинга (seed_demo_data):

• Пароль для всех: pettrace123
• registrar@pettrace.local
• vet@pettrace.local
• assistant@pettrace.local
• lab@pettrace.local
• inventory@pettrace.local
• cashier@pettrace.local

9.1 Что именно попадает в БД при крупном демо-сидинге

Команда:

docker compose run --rm web python manage.py seed_demo_data --reset --bulk-cases 240 --days 120

Что создается:

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

Типовая картина данных после сидинга --bulk-cases 240:

• есть завершенные/закрытые и активные приемы одновременно;
• есть частично и полностью оплаченные визиты;
• есть лабораторные заказы в разных статусах, включая DONE;
• есть критические/аномальные результаты для сценариев мониторинга;
• есть складские движения с расходом материалов;
• есть задачи TODO и DONE для операционной аналитики.

Пример контрольных метрик, полученных на тестовом прогоне:

• owners: 241
• pets: 241
• visits_total: 241
• visits_closed: 96
• visits_completed: 48
• visits_in_progress: 49
• appointments_completed: 144
• lab_done: 48
• invoices_paid: 145
• payments_total: 193
• tasks_total: 241

Эти данные достаточно насыщены для демонстрации:

• работы ролевых кабинетов;
• end-to-end сценариев от регистрации до оплаты;
• отчетности и аналитических срезов;
• отказоустойчивости workflow (ошибки/запреты по ролям, статусы, валидации).

10. Локальный запуск без Docker

1. Установите зависимости:

pip install -r requirements/dev.txt

2. Настройте минимум:

• DATABASE_URL
• REDIS_URL
• CELERY_BROKER_URL
• CELERY_RESULT_BACKEND

3. Опциональные env-параметры отчетов и CRM dispatch:

• REPORTS_CACHE_TTL
• REPORTS_WARMUP_ENABLED
• REPORTS_WARMUP_DAYS
• REPORTS_WARMUP_INTERVAL_SECONDS
• CRM_DISPATCH_INTERVAL_SECONDS

4. Выполните:

python src/manage.py migrate
python src/manage.py bootstrap_rbac
python src/manage.py bootstrap_facilities
python src/manage.py runserver

11. Тесты и контроль качества

Тесты:

docker compose run --rm web python manage.py test --noinput

Линтер:

docker compose run --rm web ruff check .

System checks:

docker compose run --rm web python manage.py check

CI (GitHub Actions):

• workflow: .github/workflows/ci.yml
• запускается на push и pull_request
• выполняет ruff check src
• выполняет python src/manage.py test apps --noinput

12. Основные бизнес-сущности

• CRM: Owner, Pet, ConsentDocument
• Ресурсы клиники: Branch, Cabinet, EquipmentType, Equipment, ServiceRequirement
• CRM-операции: OwnerTag, OwnerTagAssignment, CommunicationLog, Reminder
• Прием: Visit, Diagnosis, Observation, Prescription, ProcedureOrder
• Стационар: Hospitalization
• Клинический движок: ClinicalProtocol, ProtocolMedicationTemplate, ProtocolProcedureTemplate, ContraindicationRule, ClinicalAlert, ProcedureChecklist*
• Лаборатория: LabOrder, LabTest, Specimen, Tube, ContainerLabel, SpecimenEvent, LabResultValue
• Склад: InventoryItem, Batch, StockMovement
• Финансы: PriceItem, Invoice, InvoiceLine, Payment
• Оркестрация: Task, Notification
• Запись/очередь: Appointment
• Аудит: AuditLog

13. Диагностика проблем (Troubleshooting)

Нет стилей в Web UI

1. Выполните полный билд:
   • docker compose build
2. Поднимите сервис:
   • docker compose up -d web
3. Проверьте статику:
   • http://localhost:8000/static/frontend/style.css должен вернуть 200
4. В браузере выполните hard refresh (Ctrl+F5).

Ошибка доступа 403

• Проверьте группу пользователя в Admin.
• Проверьте наличие нужного permission в группе.
• Проверьте UserAccessProfile (филиалы/кабинеты/режим limit_to_assigned_cabinets).
• При необходимости выполните bootstrap_rbac.

Не стартует web

• Проверьте docker compose logs web.
• Убедитесь, что postgres и redis в статусе healthy.

Проблемы с тестовой БД

Если test DB осталась после аварийного запуска:

• удалите контейнеры/volume тестовой БД или перезапустите postgres;
• затем повторите python manage.py test --noinput.

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

PetTrace/
  src/
    config/
      settings/ (base/local/production/test)
      urls.py
      celery.py
    apps/
      common/      # базовые абстракции, health check, demo seed
      users/       # custom user, RBAC bootstrap, role scope/access profile
      frontend/    # server-rendered web UI (dashboard, CRM, visits, labs)
      facilities/  # филиалы, кабинеты, оборудование, требования к услугам
      owners/      # владельцы, согласия
      pets/        # питомцы, microchip_id, qr_token
      crm/         # теги клиентов, коммуникации, напоминания
      visits/      # Encounter, диагнозы, назначения, процедуры
      clinical/    # протоколы лечения, противопоказания, предупреждения и чек-листы
      labs/        # LabOrder, Specimen, Tube, events, results
      inventory/   # номенклатура, партии, движения остатков
      billing/     # прайс, счета, оплаты
      tasks/       # внутренние задачи и уведомления
      audit/       # аудит действий и middleware
      reports/     # операционные и финансовые отчеты (KPI)
  docker/
    scripts/entrypoint.sh
    nginx/default.conf
  requirements/
  docker-compose.yml
  Dockerfile

15. Дальнейшее развитие

• Углубленный UI для склада/закупок и CRM-коммуникаций.
• Интеграции анализаторов (CSV/HL7/вендорные адаптеры).
• Печатные формы и PDF-шаблоны.
• SLA/KPI дашборды для операционного управления.
• Многофилиальность с объектной изоляцией данных.