ACORE/PROJECT_ARCHITECTURE_FOR_HANDOFF.md

ACORE: описание проекта и связей

Этот документ можно передать как стартовую архитектурную справку для другого проекта. Он описывает текущую структуру ACORE и показывает, как организованы доменные связи.

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

ACORE — Django-проект для управления сетью аптек. Основные сценарии:

• учет сотрудников и их оргструктуры;
• учет аптек и геолокаций;
• справочники организаций, отделов, должностей, регионов;
• интеграции (Mattermost, Active Directory, почта, портал);
• отображение данных в админке и web-интерфейсе.

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

• Python + Django
• Django ORM
• Django Admin (кастомизированный)
• Веб-портал: server-rendered HTML + HTMX (shell templates/index.html, partials через core.utils.htmx.render_page)
• Много приложений в папке apps
• SQLite в текущей локальной среде

Подробнее про выбор фронтенда и границы с PHMS / VisitManager Client:
docs/htmx-portal-architecture.md.

3. Модульная структура

• acore: конфигурация проекта, URL и настройки
• core: базовые модели, справочники, общие view и утилиты
• apps/employees: сотрудники, права, сериализация и админка
• apps/locations: локации и аптеки
• apps/visit_manager: расписания и посещаемость
• apps/mattermost_connector: интеграция Mattermost
• apps/ad_connector: интеграция Active Directory
• apps/mail_connector, apps/mailparser, apps/portal_connector: интеграционные модули

4. Ключевые доменные сущности

4.1 База

• BaseModel (core.models.base):
  • uuid, created_at, updated_at
  • используется как абстрактная база для большинства сущностей

4.2 Справочники

• DirectoryType (core.models.directories): тип справочника
• Directory (core.models.directories): универсальный элемент справочника (иерархический)

Типичные значения DirectoryType:

• organization
• department
• post
• region, district, city, city_district

Directory используется как единая точка для:

• организаций;
• отделов;
• должностей;
• региональной структуры;
• других классификаторов.

4.3 Локации и аптеки

• Location (apps.locations.models.base): базовая географическая сущность
  • связь на Directory (location_region)
  • тип локации: pharmacy, warehouse, office
• Pharmacy (apps.locations.models.pharmacies): наследник Location (multi-table inheritance)
  • organization -> Directory (organization)
  • head_pharmacist -> Employee (AUTH_USER_MODEL)
  • уникальность: organization + pharmacy_number
• PharmacyPhone:
  • pharmacy -> Pharmacy (1:N)
• PharmacyHistory:
  • pharmacy -> Pharmacy (1:N)
  • changed_by -> Employee (AUTH_USER_MODEL)

4.4 Сотрудники

• Employee (apps.employees.models.base): кастомный пользователь
  • user_organization -> Directory (organization)
  • user_pharmacy -> Pharmacy
  • department -> Directory (department)
  • post -> Directory (post)
  • manager -> Employee (self FK, иерархия руководитель-подчиненный)
• PermissionGroup (apps.employees.models.permissions): профиль для auth.Group
• EmployeePermissionOverride:
  • employee -> Employee
  • permission -> auth.Permission

5. Связи между модулями

• core.Directory и core.DirectoryType являются центральным справочным слоем
• locations.Pharmacy использует Directory для организации и региона
• employees.Employee использует:
  • Directory для организации, отдела и должности
  • Pharmacy для привязки сотрудника к аптеке
• core.views строит страницы, агрегируя Employee, Pharmacy и Directory
• employees.admin и locations.admin подключают visit_manager для связанных inlines и мониторинга активности

6. Поток данных (упрощенно)

1. Справочники (DirectoryType/Directory) формируют допустимые значения.
2. Создаются Location и Pharmacy с привязкой к организации и региону.
3. Создаются Employee с привязкой к организации/аптеке/отделу/должности.
4. Интерфейс (core.views + templates) выводит агрегированные данные и фильтры.
5. Интеграторы (Mattermost/AD/почта/портал) синхронизируют внешние системы.

7. Маршрутизация и портальный UI

Главные URL находятся в acore/urls.py:

• административный интерфейс;
• страницы dashboard, employees, pharmacies и другие;
• подключение маршрутов приложения employees;
• JSON API посещаемости (apps.visit_manager.api) для edge-клиента.

Портал:

• полный ответ = index.html + вложенный pages/...;
• HTMX-запрос (HX-Request: true) = только фрагмент pages/...;
• секции и права — core.portal_sections / матрица доступа портала.

7.1 Границы внешних систем

• ACORE — основной веб-портал и source of truth (сотрудники, аптеки, справочники, IT/HR UI, выдача прав).
• PVMS — сервер учёта рабочего времени (при SoT — источник посещаемости); в портале анализ через /timetrack/ (access_timetrack), тонкие права can_view_attendance / can_manage_schedules синхронизируются в PVMS.
• VisitManager Client (отдельный репозиторий, Rust/egui) — kiosk/камера/сканер; не веб-фронт ACORE; регистрация визитов через API.
• PHMS (и родственные порталы) — внешний контур; связь через API/SSO/deep-link, без общего SPA и без HTML-скрейпинга.
• Сложный интерактив внутри ACORE (DnD, печать, canvas) — точечный JS рядом с partial, без обязательного React/Vue.

8. Что перенести в другой проект

Если создавать похожий проект, рекомендуется сохранить такой каркас:

1. Единая модель справочников (DirectoryType + Directory) для всех классификаторов.
2. Базовая абстрактная модель (BaseModel) с uuid и аудит-полями.
3. Разделение на доменные приложения:
   • people (сотрудники и права)
   • locations (локации и объекты)
   • integrations (внешние коннекторы)
4. Наследование для локаций:
   • общий Location
   • специализированные типы (Pharmacy, Warehouse и т.д.).
5. Явные внешние ключи на справочники вместо жестко зашитых enum-значений.

9. Краткий шаблон для нового проекта

Название проекта:

Цель:

• <Ключевая бизнес-цель>

Контексты:

• Справочники
• Локации/объекты
• Сотрудники
• Интеграции

Базовые модели:

• BaseModel
• DirectoryType
• Directory

Основные сущности:

• Location
• Employee

Ключевые связи:

• Employee -> Directory (organization/department/post)
• Employee ->
• -> Directory (region/organization)

Технические решения:

• Django apps по доменным контекстам
• Сервисный слой интеграций
• Единые правила валидации и аудита
• HTMX-портал (shell + partials), внешние клиенты — по API

10. Итог

Текущий ACORE построен вокруг четырех опор:

• универсальные справочники;
• доменные модели сотрудников и аптек;
• интеграционные коннекторы;
• HTMX как фронтенд основного портала (edge/PHMS — отдельные клиенты + API).

Такая структура хорошо переносится в другой проект с минимальными изменениями доменной модели.