SHA256
210 lines
17 KiB
Markdown
210 lines
17 KiB
Markdown
|
||
# Техническая документация проекта: Портал СНТ «Архангельское-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):** Наполнение графиков вывоза ТБО, чистки снега трактором и регламента прямого договора с ПАО «Россети Московский регион». |