admin/SNT-Site-reDisign

SHA256

0 Fork 0

Files

T

admin 812f5ece4b Добавить architecture.md

2026-10-23 18:07:41 +00:00

17 KiB

Raw Permalink Blame History

Техническая документация проекта: Портал СНТ «Архангельское-1» (new.snt-a.ru)

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

Веб-портал СНТ СН «Архангельское-1» — официальный информационный ресурс товарищества (Московская область, Наро-Фоминский г.о., д. Архангельское).

Портал решает задачи миграции с устаревшей CMS Joomla на современную связку MODX Revolution 3.x + Leaflet.js + SVG, снижая нагрузку на сервер, устраняя зависимость от сторонних плагинов и обеспечивая моментальную загрузку на мобильных устройствах дачников.

Ключевые архитектурные принципы

Строгая типографика и корпоративный стиль: Единая гарнитура Century Schoolbook (woff2, woff, ttf), принудительно наследуемая всеми таблицами, карточками документов и интерактивной картой.
Векторная картография без растровой перегрузки: Вместо тяжелых тайлов карта поселка отрисована в легковесном SVG, встроенном прямо в DOM-дерево страницы через L.svgOverlay.
Модульность MODX: Шаблоны строятся из переиспользуемых чанков (pdoTools), списки выводятся через pdoResources, а структура каталога документов масштабируется стандартным деревом ресурсов.

2. Реальная архитектура MODX Revolution

2.1. Дерево ресурсов (Web Context)

Дерево ресурсов строго типизировано, служебные и системные разделы вынесены в технологический контейнер.

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. Файловая структура сервера

/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 выполните дамп базы данных:

mysqldump -u ПОЛЬЗОВАТЕЛЬ_БД -p ИМЯ_БД --default-character-set=utf8mb4 > backup_snt_db_$(date +%F).sql

Этот файл содержит все тексты страниц, структуру дерева, настройки чанков и сниппетов.

Шаг 2. Бэкап файлов проекта через SSH / Терминал

В корне сайта выполните команду для упаковки критических каталогов (исключая временный кэш):

tar -czvf snt_files_backup_$(date +%F).tar.gz \
  assets/ \
  core/config/ \
  index.php \
  .htaccess \
  config.core.php

Если требуется сохранить вообще все файлы портала вместе с ядром MODX:

tar --exclude='core/cache/*' -czvf full_site_backup_$(date +%F).tar.gz .

Шаг 3. Экспорт чанков и шаблонов в Git (нативные файлы)

Поскольку MODX по умолчанию хранит код чанков и шаблонов в базе данных, для удобного контроля версий в Git рекомендуется экспортировать их в виде физических файлов:

Создайте в каталоге assets/ папку assets/templates_backup/ (или свяжите элементы с файлами через опцию MODX «Статичный элемент»).
Сохраните код используемых элементов в файлы:

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. Актуальный бэклог дальнейшей разработки

Реестр должников (Ресурс ID 26): Формирование таблицы долгов с активными ссылками на участки главной карты.
Разработка личного кабинета садовода: перед тем чтобы выкладывать ПДН данные нужно разработать личный кабинет.
Динамический JSON-датасет участков: Вынос массива должников из скрипта snt-map.js в базу данных с выводом расширенной информации (сотки, ФИО владельца для закрытой зоны, кадастровый номер).
Генератор платежного QR-кода: Внедрение на страницу «Реквизиты» (ID 2) и «Членские взносы» (ID 25) генератора QR-кодов стандарта ГОСТ (СБП/Сбербанк) с автоподстановкой номера участка.
Раздел «Услуги и сервис» (ID 18): Наполнение графиков вывоза ТБО, чистки снега трактором и регламента прямого договора с ПАО «Россети Московский регион».

17 KiB Raw Permalink Blame History Unescape Escape