190 lines
9.5 KiB
Markdown
190 lines
9.5 KiB
Markdown
# 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](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. Краткий шаблон для нового проекта
|
|
|
|
Название проекта: <ProjectName>
|
|
|
|
Цель:
|
|
- <Ключевая бизнес-цель>
|
|
|
|
Контексты:
|
|
- Справочники
|
|
- Локации/объекты
|
|
- Сотрудники
|
|
- Интеграции
|
|
|
|
Базовые модели:
|
|
- BaseModel
|
|
- DirectoryType
|
|
- Directory
|
|
|
|
Основные сущности:
|
|
- Location
|
|
- <DomainObject1>
|
|
- Employee
|
|
|
|
Ключевые связи:
|
|
- Employee -> Directory (organization/department/post)
|
|
- Employee -> <DomainObject1>
|
|
- <DomainObject1> -> Directory (region/organization)
|
|
|
|
Технические решения:
|
|
- Django apps по доменным контекстам
|
|
- Сервисный слой интеграций
|
|
- Единые правила валидации и аудита
|
|
- HTMX-портал (shell + partials), внешние клиенты — по API
|
|
|
|
## 10. Итог
|
|
|
|
Текущий ACORE построен вокруг четырех опор:
|
|
- универсальные справочники;
|
|
- доменные модели сотрудников и аптек;
|
|
- интеграционные коннекторы;
|
|
- HTMX как фронтенд основного портала (edge/PHMS — отдельные клиенты + API).
|
|
|
|
Такая структура хорошо переносится в другой проект с минимальными изменениями доменной модели.
|