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

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

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

ACORE — Django-проект для управления сетью аптек.
Основные сценарии:
- учет сотрудников и их оргструктуры;
- учет аптек и геолокаций;
- справочники организаций, отделов, должностей, регионов;
- интеграции (Mattermost, Active Directory, почта, портал);
- отображение данных в админке и web-интерфейсе.

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

- Python + Django
- Django ORM
- Django Admin (кастомизированный)
- Много приложений в папке apps
- SQLite в текущей локальной среде

## 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. Маршрутизация

Главные URL находятся в acore/urls.py:
- административный интерфейс;
- страницы dashboard, employees, pharmacies и другие;
- подключение маршрутов приложения employees.

## 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 по доменным контекстам
- Сервисный слой интеграций
- Единые правила валидации и аудита

## 10. Итог

Текущий ACORE построен вокруг трех опор:
- универсальные справочники;
- доменные модели сотрудников и аптек;
- интеграционные коннекторы.

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