diff --git a/architecture.md b/architecture.md new file mode 100644 index 0000000..79bb5a3 --- /dev/null +++ b/architecture.md @@ -0,0 +1,210 @@ + +# Техническая документация проекта: Портал СНТ «Архангельское-1» (new.snt-a.ru) + +## 1. Назначение и концепция проекта + +Веб-портал СНТ СН «Архангельское-1» — официальный информационный ресурс товарищества (Московская область, Наро-Фоминский г.о., д. Архангельское). + +Портал решает задачи миграции с устаревшей CMS Joomla на современную связку **MODX Revolution 3.x + Leaflet.js + SVG**, снижая нагрузку на сервер, устраняя зависимость от сторонних плагинов и обеспечивая моментальную загрузку на мобильных устройствах дачников. + +### Ключевые архитектурные принципы + +1. **Строгая типографика и корпоративный стиль:** Единая гарнитура **Century Schoolbook** (`woff2`, `woff`, `ttf`), принудительно наследуемая всеми таблицами, карточками документов и интерактивной картой. +2. **Векторная картография без растровой перегрузки:** Вместо тяжелых тайлов карта поселка отрисована в легковесном SVG, встроенном прямо в DOM-дерево страницы через `L.svgOverlay`. +3. **Модульность MODX:** Шаблоны строятся из переиспользуемых чанков (`pdoTools`), списки выводятся через `pdoResources`, а структура каталога документов масштабируется стандартным деревом ресурсов. + +--- + +## 2. Реальная архитектура MODX Revolution + +### 2.1. Дерево ресурсов (Web Context) + +Дерево ресурсов строго типизировано, служебные и системные разделы вынесены в технологический контейнер. + +```text +Website +├── Главная (1) # Шаблон главной страницы [ID 2] +├── Реквизиты (2) # Шаблон второстепенной страницы [ID 1] +├── Контакты (3) # Шаблон второстепенной страницы [ID 1] +├── Объявления (4) # Контейнер новостей и уведомлений +│ └── Межевание участков (27) +├── Чат садоводов (8) # Информационная ссылка на внешний чат +├── Документы (13) # Общий реестр официальных документов +│ ├── Устав СНТ (14) +│ │ └── Устав СНТ СН от 2019 г. (28) # Карточка PDF-документа +│ ├── Протоколы общих собраний (15) +│ ├── Сметы и отчеты ревизионной комиссии (16) +│ └── Законодательные акты и постановления (17) +├── Услуги и сервис (18) # Раздел хозяйственной деятельности СНТ +│ ├── Услуги (19) +│ │ ├── Уборка снега (22) +│ │ └── Уборка ТБО (23) +│ ├── Сервис (21) +│ │ ├── Интернет (20) +│ │ └── Электричество (24) +│ └── Членские взносы (25) +├── Технологические ресурсы (12) # Системный служебный контейнер +│ ├── Политика конфиденциальности (5) # Страница требований 152-ФЗ +│ ├── Раздел находится в разработке (9) +│ ├── Ошибка 404 — Страница не найдена (10) +│ └── Ошибка 403 — Доступ ограничен (11) +└── Наши должники (26) # Реестр участков с задолженностями + +``` + +### 2.2. Шаблоны (Templates) + +* **Шаблон второстепенной страницы (1):** Для контентных разделов, положений, устава, реквизитов и контактов. Подключает `style.css` и `article.css`. +* **Шаблон главной страницы (2):** Рабочее пространство: срочная строка оповещений (`alert-strip`), интерактивная SVG-карта, панель быстрых действий (`sidebar.quick-actions`), карточки услуг и легенда. +* **Шаблон Статей и новостей (3):** Вывод публикаций с метаданными даты, автора и прикрепленными файлами. + +### 2.3. Дополнительные поля (Template Variables — TV) + +* `doc_file` (4): Тип «Файл». Привязка PDF-файлов к карточкам документов (Устав, протоколы). +* `footer_banners` (1): Настройка партнерских баннеров и ссылок в подвале сайта. +* `is_alert` (3): Тип «Переключатель» (флаг 1/0). При включении на ресурсе раздела «Объявления» новость автоматически транслируется в желтую полосу экстренного оповещения на главной странице. + +### 2.4. Чанки (Chunks) + +* `header` (1): Мета-теги, фавиконы, подключение шрифтов, CSS и библиотек. +* `footer` (3): Контакты правления, копирайт, ссылки на политику персональных данных. +* `sidebar` (2): Базовый сайдбар для типовых внутренних страниц. +* `sidebar.quick-actions` (8): Блок быстрых кнопок главной страницы (Оплата взносов, заявка электрику, реквизиты). +* `cards.bottom` (7): Сетка 4 ключевых сервисных блоков нижнего яруса главной («Услуги и сервис», «Объявления», «Чат садоводов», «Документы»). +* `tpl.digest.row` (4): Шаблон строки вызова срочного объявления вверху сайта через `pdoResources`. +* `tpl.announcements.row` (5): Оформление анонсов в ленте объявлений. +* `tpl.docs.category` (6), `tpl.docs.row` (11): Шаблоны списков и карточек документов со встроенными модальными окнами для просмотра PDF. +* `tpl.services.group` (10), `tpl.services.row` (9): Разметка вывода каталога услуг товарищества. + +### 2.5. Сниппеты (Snippets) + +* `pdoTools` (10) и `MIGX` (21): Системные пакеты вывода коллекций и структурированных данных. +* `docInfo` (32): Кастомный сниппет автоматического определения веса и расширения прикрепленных PDF-файлов (например, выводит бейдж `PDF, 2.4 МБ`). + +--- + +## 3. Файловая структура сервера + +```text +/public_html/ (Корень сайта) +├── assets/ +│ ├── components/ # Ассеты сторонних модулей (pdoTools, MIGX) +│ ├── css/ +│ │ ├── style.css # Базовый каркас, переменные палитры, шапка, подвал +│ │ ├── article.css # Стили текстовых публикаций, реквизитов, таблиц +│ │ ├── mapstyle.css # Изолированные стили карты Leaflet, попапов и поиска +│ │ ├── century-schoolbook.ttf # Корпоративный шрифт (TrueType) +│ │ ├── century-schoolbook.woff # Корпоративный шрифт (Web Open Font Format) +│ │ └── century-schoolbook.woff2 # Оптимизированный шрифт для современных браузеров +│ ├── files/ +│ │ └── ustav/ +│ │ └── sntsn-arxangelskoe-1.pdf # Скан действующего Устава товарищества +│ ├── images/ +│ │ ├── marker-icon.png # Стандартные маркеры Leaflet +│ │ ├── marker-icon-2x.png +│ │ ├── marker-shadow.png +│ │ └── snt-map.svg # Векторная схема СНТ с номерами участков +│ ├── js/ +│ │ └── snt-map.js # Ядро интерактивной карты +│ └── lib/ +│ └── leaflet/ # Локальный дистрибутив Leaflet.js +│ ├── leaflet.css +│ └── leaflet.js +├── core/ # Ядро MODX Revolution +├── manager/ # Панель управления MODX +├── connectors/ # Системные коннекторы процессоров +├── .htaccess # Правила ЧПУ, сжатия GZIP и защиты каталогов +├── config.core.php # Конфигурация путей ядра +└── index.php # Главный входной контроллер + +``` + +--- + +## 4. Разработанный функционал и решенные технические проблемы + +### 4.1. Внедрение корпоративного шрифта Century Schoolbook + +* Шрифты размещены локально, что гарантирует независимость от внешних CDN (Google Fonts и др.). +* Настроено принудительное применение гарнитуры в таблицах реквизитов и статьях через наследование в `article.css`. +* Решена проблема внутренних переопределений Inkscape: селектор `#map-viewport svg text, #map-viewport svg text tspan` с флагом `!important` подавляет жестко зашитые инлайновые стили старых редакторов (`font-family: Campania`). + +### 4.2. Страница «Контакты» и интеграция с навигацией + +* Карточки председателя и ответственного по 152-ФЗ с номерами телефонов и адресами электронной почты. +* Автоматизированная форма прокладки маршрута: садовод вводит отправную точку, и маршрут рассчитывается в Яндекс.Картах до шлагбаума СНТ (`55.326193, 35.965999`). +* Для смартфонов внедрен прямой запуск через системный протокол `yandexnavi://build_route_on_map`, мгновенно открывающий установленное приложение навигатора. + +### 4.3. Интерактивная векторная карта поселка (`snt-map.js`) + +* **Отказ от тяжелых решений:** Вместо растровых плиток карта выводится через `L.svgOverlay` в плоской системе `L.CRS.Simple`. +* **Устранение математического сдвига координат (Баг `0:0`):** Устранено несовпадение между жесткими габаритами полотна и реальным `viewBox` (1890.5×1059.0). Вычисление координат теперь выполняется динамически через `map.containerPointToLatLng()` от фактического положения на экране (`getBoundingClientRect()`), что нивелирует любые трансформационные матрицы Inkscape (`matrix(...)`). +* **Поиск участка:** Поле ввода находит номер участка в SVG, центрирует карту методом `setView` и подсвечивает его классом `.is-active`. +* **Интерактивные статусы и всплывающие окна:** +* Номера участков с долгами подсвечиваются бордовым цветом `.snt-plot--debt`. +* При клике открывается кастомизированный попап в корпоративном стиле со статусом оплаты взносов. + + + +--- + +## 5. Инструкция по созданию полного бэкапа проекта для передачи прав + +Для фиксации контрольной точки и безопасной передачи проекта новому разработчику или председателю правления необходимо создать резервную копию трех составляющих: базы данных, программных файлов и снимка элементов MODX. + +### Шаг 1. Бэкап базы данных MySQL + +В панели хостинга (phpMyAdmin) или по SSH выполните дамп базы данных: + +```bash +mysqldump -u ПОЛЬЗОВАТЕЛЬ_БД -p ИМЯ_БД --default-character-set=utf8mb4 > backup_snt_db_$(date +%F).sql + +``` + +*Этот файл содержит все тексты страниц, структуру дерева, настройки чанков и сниппетов.* + +### Шаг 2. Бэкап файлов проекта через SSH / Терминал + +В корне сайта выполните команду для упаковки критических каталогов (исключая временный кэш): + +```bash +tar -czvf snt_files_backup_$(date +%F).tar.gz \ + assets/ \ + core/config/ \ + index.php \ + .htaccess \ + config.core.php + +``` + +*Если требуется сохранить вообще все файлы портала вместе с ядром MODX:* + +```bash +tar --exclude='core/cache/*' -czvf full_site_backup_$(date +%F).tar.gz . + +``` + +### Шаг 3. Экспорт чанков и шаблонов в Git (нативные файлы) + +Поскольку MODX по умолчанию хранит код чанков и шаблонов в базе данных, для удобного контроля версий в Git рекомендуется экспортировать их в виде физических файлов: + +1. Создайте в каталоге `assets/` папку `assets/templates_backup/` (или свяжите элементы с файлами через опцию MODX *«Статичный элемент»*). +2. Сохраните код используемых элементов в файлы: +* `header.chunk.html` $\leftarrow$ чанк `header` (1) +* `footer.chunk.html` $\leftarrow$ чанк `footer` (3) +* `sidebar_quick_actions.chunk.html` $\leftarrow$ чанк `sidebar.quick-actions` (8) +* `cards_bottom.chunk.html` $\leftarrow$ чанк `cards.bottom` (7) +* `home.template.html` $\leftarrow$ «Шаблон главной страницы» (2) +* `subpage.template.html` $\leftarrow$ «Шаблон второстепенной страницы» (1) + + + +--- + +## 6. Актуальный бэклог дальнейшей разработки + +1. **Реестр должников (Ресурс ID 26):** Формирование таблицы долгов с активными ссылками на участки главной карты. +2. **Разработка личного кабинета садовода:** перед тем чтобы выкладывать ПДН данные нужно разработать личный кабинет. +3. **Динамический JSON-датасет участков:** Вынос массива должников из скрипта `snt-map.js` в базу данных с выводом расширенной информации (сотки, ФИО владельца для закрытой зоны, кадастровый номер). +4. **Генератор платежного QR-кода:** Внедрение на страницу «Реквизиты» (ID 2) и «Членские взносы» (ID 25) генератора QR-кодов стандарта ГОСТ (СБП/Сбербанк) с автоподстановкой номера участка. +5. **Раздел «Услуги и сервис» (ID 18):** Наполнение графиков вывоза ТБО, чистки снега трактором и регламента прямого договора с ПАО «Россети Московский регион». \ No newline at end of file