docs: зафиксировать HTMX-портал и границы с PHMS и VisitManager.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -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).
|
||||
|
||||
Такая структура хорошо переносится в другой проект с минимальными изменениями доменной модели.
|
||||
|
||||
@@ -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 (домен + границы систем)
|
||||
Reference in New Issue
Block a user