diff --git a/PROJECT_ARCHITECTURE_FOR_HANDOFF.md b/PROJECT_ARCHITECTURE_FOR_HANDOFF.md index e6382f6..3c08508 100644 --- a/PROJECT_ARCHITECTURE_FOR_HANDOFF.md +++ b/PROJECT_ARCHITECTURE_FOR_HANDOFF.md @@ -18,9 +18,13 @@ ACORE — Django-проект для управления сетью аптек. - 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 и настройки @@ -104,12 +108,26 @@ Directory используется как единая точка для: 4. Интерфейс (core.views + templates) выводит агрегированные данные и фильтры. 5. Интеграторы (Mattermost/AD/почта/портал) синхронизируют внешние системы. -## 7. Маршрутизация +## 7. Маршрутизация и портальный UI Главные URL находятся в acore/urls.py: - административный интерфейс; - страницы dashboard, employees, pharmacies и другие; -- подключение маршрутов приложения employees. +- подключение маршрутов приложения 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. Что перенести в другой проект @@ -158,12 +176,14 @@ Directory используется как единая точка для: - Django apps по доменным контекстам - Сервисный слой интеграций - Единые правила валидации и аудита +- HTMX-портал (shell + partials), внешние клиенты — по API ## 10. Итог -Текущий ACORE построен вокруг трех опор: +Текущий ACORE построен вокруг четырех опор: - универсальные справочники; - доменные модели сотрудников и аптек; -- интеграционные коннекторы. +- интеграционные коннекторы; +- HTMX как фронтенд основного портала (edge/PHMS — отдельные клиенты + API). Такая структура хорошо переносится в другой проект с минимальными изменениями доменной модели. diff --git a/docs/htmx-portal-architecture.md b/docs/htmx-portal-architecture.md new file mode 100644 index 0000000..04f5d28 --- /dev/null +++ b/docs/htmx-portal-architecture.md @@ -0,0 +1,126 @@ +# HTMX для ACORE как основного портала + +Архитектурное решение: **HTMX — основной фронтенд веб-портала ACORE**. +Связь с PHMS, PVMS и VisitManager решается на уровне API/SSO и отдельных клиентов, а не заменой HTMX на SPA. + +## Вердикт + +ACORE — серверный Django-портал (shell + частичные HTML-ответы). +VisitManager Client — edge/kiosk (Rust/egui). +**PVMS — сервер учёта рабочего времени** (SoT посещаемости при `PVMS_ATTENDANCE_SOT`). +PHMS — внешний контур. Между ними нужна интеграция данных и доступа, а не единый SPA. + +```text +[ACORE web HTMX] + /timetrack/ (анализ) --PvmsClient--> [PVMS] + роли + visit_permissions --push_to_pvms-> [PVMS] + графики WorkSchedule --sync--------> [PVMS] + | + +-- API / SSO --> PHMS + | +[VisitManager Client] -- register visit --> ACORE API и/или PVMS +``` +## Почему HTMX подходит ACORE + +- Уже встроен: `templates/index.html` (htmx 2.x), навигация `hx-get` → `#main-content`, `core.utils.htmx.render_page`. +- Порталные сценарии (HR, IT, дислокация, новости, учёт, справочники) — server-rendered CRUD: формы, таблицы, фильтры, права по секциям (`core.portal_sections`). +- Один бэкенд владеет HTML и бизнес-логикой → проще auth, CSRF, матрица доступов, меньше дублирования DTO. +- Скорость разработки модулей выше, чем при отдельном SPA-слое. + +## Где HTMX не заменяет другие клиенты + +| Поверхность | Стек | Почему не HTMX | +|---|---|---| +| VisitManager Client (камера, EAN/QR, kiosk) | Rust + egui | Локальная камера, низкая задержка, offline/local storage | +| Тяжёлые редакторы внутри портала | точечный JS (DnD шаблона этикеток и т.п.) | HTMX отдаёт shell/partials; интерактив — локальный JS | +| PHMS / UI PVMS (если отдельный) | свой продукт | Связь через API/SSO/deep-link, не общий frontend | +| PVMS (движок учёта) | отдельный сервер | SoT смен/логов; ACORE читает отчёты и пушит identity/графики | + +## Границы систем + +1. **ACORE = hub UI + source of truth** для оргструктуры, сотрудников, аптек, **выдачи прав**. + Пользователь живёт в портале; модули открываются HTMX-частичками в одном shell. + +2. **PVMS = сервер учёта РВ**. + Хранит/считает посещаемость; при SoT ACORE не пишет локальный `AttendanceLog`. + Менеджеры **не обязаны** работать в UI PVMS: анализ и (по возможности) правила графика — в ACORE `/timetrack/` и связанных формах, данные через `PvmsClient` / sync. + +3. **VisitManager Client = edge device**. + Камера/сканер/kiosk; регистрация визита в API ACORE или PVMS. UI остаётся egui. + +4. **PHMS = внешний контур**. + API/SSO/deep-link; фронт PHMS не тащить в HTMX. + +5. **Точечный JS внутри ACORE** — canvas/DnD/печать. Не раздувать в SPA. + +## Доступ сотрудникам: анализ посещений и правила графика + +Два слоя прав (уже в коде): + +| Слой | Где | Зачем | +|---|---|---| +| Раздел портала | `core.access_timetrack` → `/timetrack/` | Видит ли сотрудник вкладку учёта в ACORE | +| Права PVMS (visit) | `can_view_attendance`, `can_manage_schedules`, `can_register_others` на `core.PvmsAccess` | Что разрешено в контуре посещаемости; уходят в PVMS как `visit_permissions` | + +Дефолты по ролям (`apps/portal_connector/pvms_permissions.py`): + +- **Заведующий / Администратор сети** — просмотр отчётов + управление графиками (+ регистрация чужих). +- **Ревизор / Офисный сотрудник** — только `can_view_attendance`. +- **Фармацевт / склад** — без visit can_* (только своя отметка на kiosk). + +Рекомендуемый UX (HTMX, без отдельного SPA): + +1. Сотруднику с `access_timetrack` + `can_view_attendance` — сводка в `/timetrack/` (уже тянет PVMS при `PVMS_SYNC_ENABLED`). +2. С `can_manage_schedules` — редактирование шаблонов/паттернов/`WorkSchedule` в ACORE (или deep-link в PVMS, если сложный UI ещё только там); sync ACORE → PVMS. +3. Права назначаются в карточке роли ACORE (поле «PVMS / посещаемость»), не вручную в PVMS. +4. Не открывать весь UI PVMS всем «аналитикам»: достаточно портальной страницы + точечных прав. +## Когда пересматривать HTMX + +Только при требованиях уровня: + +- полноценный offline PWA-портал; +- сложный real-time collaborative UI в браузере; +- отдельная UI-команда/репозиторий с собственным релизным циклом. + +Пока доминируют Django-страницы и права секций — HTMX остаётся оптимальным. + +## Практические правила + +### Новые разделы портала + +1. Django view возвращает страницу через `render_page(request, '....html', context)`. +2. Шаблон кладётся в `templates/pages/`. +3. Пункт навигации в shell (`templates/index.html` / секции в `core.portal_sections`) с `hx-get`, `hx-target="#main-content"`, `hx-push-url`, `hx-indicator="#loader"`. +4. Права секции — через матрицу портала, не обходом во view. + +### Интеграции наружу (PHMS и др.) + +- Стабильные API endpoints + явная auth (token/SSO), не HTML-скрейпинг. +- Портал может показывать deep-link или ACORE-страницу-сводку; чужой HTML не подменять через HTMX без контракта. + +### PVMS + +- Сервер учёта; ACORE — точка входа для людей (анализ, выдача прав, при необходимости графики). +- Отчёты: `PvmsClient.timetrack` → раздел `/timetrack/` (нужен `access_timetrack`). +- Identity/права/графики: `push_to_pvms` / builders (`visit_permissions`, schedules). +- UI PVMS — только для админов/интеграции или deep-link при недостающем экране в портале. + +### VisitManager Client + +- Не является веб-фронтом ACORE. +- Контракт: JSON API регистрации визита (ACORE `apps.visit_manager.api` и/или PVMS при SoT). +- Камера, сканирование штрихкодов и kiosk UX остаются на клиенте. +### Сложный UI внутри страницы + +- Маленький JS-модуль в `static/` рядом с partial. +- HTMX обновляет контейнер; модуль инициализируется после swap (`htmx:afterSwap` / явный init в partial), без React/Vue-слоя по умолчанию. + +## Ключевые файлы + +- `templates/index.html` — shell портала, подключение HTMX +- `core/utils/htmx.py` — `render_page` / `is_htmx_request` +- `core/portal_sections.py` — секции и permission codenames +- `apps/visit_manager/api/` — JSON API для edge-клиента +- `apps/portal_connector/pvms_permissions.py` — visit can_* и маппинг ролей +- `apps/portal_connector/pvms_client.py` — отчёты/API к PVMS +- `PROJECT_ARCHITECTURE_FOR_HANDOFF.md` — общий handoff (домен + границы систем)