GRADE — раздел «Полезные статьи» (блог) для grade.law

Контекст и задача

grade.law — сайт адвокатского бюро GRADE (Grabovskii & Deyneko) (Санкт-Петербург/Москва): налоговые споры, защита бизнеса, банкротство, сопровождение проверок ФНС и МВД. Сайт работает на MODX Revolution 2.8.1-pl (PHP 7.3.33, MySQL 8.0, MyISAM), весь контент живёт в БД, а не в файлах; системы сборки фронтенда нет.

Заказчику требовался новый экспертный раздел — «Полезные статьи» (по сути блог): двухколоночный каталог-аккордеон по категориям, шаблон отдельной статьи по двум макетам Figma и наполнение готовым контентом — 42 материала в 6 практиках, лежавшие в виде PDF-брифов. Дополнительная цель — закрыть SEO-пробел: у сайта не было per-page мета, canonical, OpenGraph и структурированных данных. Работа велась на 2026 год как независимый проект (не штатный).

Что я сделал

Прошёл полный цикл от исследования до запуска на проде:

• Аудит (read-only): разобрал кодовую базу и всю БД (77 таблиц, 71 ресурс, 9 шаблонов, 22 чанка, 44 сниппета, 27 TV, 10 плагинов), зафиксировал архитектуру, переиспользуемые элементы и риски. Прод при анализе не менялся, сняты точки отката (бэкапы).
• Веб-исследование стека под конкретные версии (актуальность на 16–17.06.2026): MODX 2.8.x/PHP 7.3, pdoTools 2.12.7, формы/изображения/фронтенд — три досье со ссылками и поправками.
• План реализации (13 разделов): IA, модель данных статьи, шаблоны/чанки, каталог-аккордеон, шаблон статьи, формы, SEO-пакет, миграция, кэш/безопасность, тестирование, деплой/откат, риски.
• Реализация раздела напрямую на проде (по решению заказчика, без стейджинга): новые TV (art_*, seo_*, og_image), 3 шаблона (каталог, категория, статья), 9 чанков (blog_*), дерево ресурсов (контейнер + 6 категорий + 42 статьи), изолированные blog.css/blog.js, интеграция пункта «ПОЛЕЗНЫЕ СТАТЬИ» в меню.
• Миграция контента: пайплайн «42 PDF → 42 ресурса-статьи» с категориями, авторами, ЧПУ-алиасами (транслит) и SEO-полями.
• SEO с нуля для раздела и QA (пройден заказчиком: формы, мобильная вёрстка, меню).

Честно про характер работ: это не сайт с нуля, а новый раздел-функционал, встроенный в существующий боевой сайт с переиспользованием его компонентов (карточки авторов, CTA-формы, галерея, линейка pdoTools). Поэтому engagement — mixed: аудит существующей системы + greenfield-разработка нового раздела + миграция контента + SEO.

Решение и подход

• Архитектура блога — на чистом pdoTools, без сторонних движков (Articles/Tickets/Collections под 2.8.1 несовместимы — подтверждено исследованием). Категории — контейнерами в дереве (Вариант A), что даёт чистые ЧПУ /poleznye-stati/<категория>/<статья>/ и сильную SEO-страницу под прямые заходы.
• Шаблон статьи построен на схеме существующего шаблона «Услуга» (id 5) + добавлены хлебные крошки (pdoCrumbs, 4 уровня), лид с буквицей, sticky-сайдбар (7 услуг + карточка автора + мини-CTA), тёмный CTA-баннер с формой.
• Каталог — серверный вывод категорий/статей (pdoResources) + JS-аккордеон с deep-link ?cat= и активной первой непустой категорией.
• Авторы — через listbox-TV на базе существующего механизма карточек user1…user8 (а не MIGX 3.0.0-alpha5: alpha-баг подтверждён исследованием). Это сознательный компромисс относительно плана (где предлагались авторы-ресурсы) — по решению заказчика.
• Сборка — идемпотентные PHP-скрипты через MODX API (_bootstrap.php + 01…11), запускаемые фиксированным /opt/php73/bin/php (дефолтный PHP 8.3 не поднимает MODX 2.8.1). Все элементы создаются скрытыми, затем включаются «точкой интеграции».
• Стили изолированы в blog.css — основной style.css (~80 КБ) не трогается; шрифты SF Pro Text, иконки grade-icon, Swiper переиспользованы.

Результат

• Раздел «Полезные статьи» запущен на проде и работает — подтверждено: https://grade.law/poleznye-stati/ отдаёт каталог с 6 категориями и 41+ статьями; пункт «Полезные статьи» присутствует в меню (WebFetch, проверено).
• 42 статьи перенесены из PDF и опубликованы; распределение по практикам — ФНС 12 / МВД 10 / налог.оптимизация 8 / банкротство 6 / арбитраж 3 / защита 3 (docs/handoff.md).
• SEO-пробел закрыт для раздела: уникальные мета, canonical, OG/Twitter, JSON-LD Article+Person+BreadcrumbList, категорийные OG-обложки.
• QA пройден заказчиком (формы, мобильная вёрстка, меню); индексация включена; новых ошибок от блога в логах прода не зафиксировано (docs/progress.md).
• Бизнес-эффекты (трафик/заявки из поиска) на момент сдачи не зафиксированы (уточнить у автора) — раздел только запущен.

Стек и обоснование

• MODX Revolution 2.8.1 + pdoTools 2.12.7 / Fenom — платформа существующего сайта; решения принимались строго под эти версии (не под MODX 3 / pdoTools 3).
• PHP 7.3.33 — версия прода (зафиксирована через ISPmanager); под неё писались код и скрипты; обновление вне scope (зафиксировано как риск).
• MySQL 8.0 / MyISAM — существующая конфигурация; учтены особенности (sql_mode, коллации, отсутствие транзакций).
• Python (PyMuPDF, Pillow) — для извлечения структуры из PDF и генерации OG-обложек: разбор уровней по размеру шрифта и списков по координатам маркеров оказался надёжнее «плоского» pdftotext.
• JS (jQuery + Swiper) — стек сайта; аккордеон и галерея сделаны без новых зависимостей.
• Формы — переиспользован существующий паттерн form-handler.js → assets/php/submit.php (Telegram + SMTP) со скрытым formId, чтобы не плодить вторую механику.

Роль ИИ в проекте

Проект выполнен в формате AI-augmented разработки на Claude Code (Opus 4.8, max effort):

• Doc-driven development: проект ведётся через CLAUDE.md (карта репозитория и правил) и рабочие документы docs/progress.md / docs/handoff.md, которые обновлялись по ходу длинной сессии для устойчивости к суммаризации контекста.
• Структурированный промпт-инжиниринг: этап исследования/плана задан развёрнутым ТЗ docs/prompts/blog-poleznye-stati-research-and-plan.md (фазы, гард-рейлы, матрица версий, антипаттерны).
• Параллельные субагенты: 3 фоновых research-агента (платформа/безопасность/БД; блог/pdoTools/SEO; формы/изображения/фронтенд) → сведение в docs/research/*.
• Цикл research → audit → plan → implement → migrate → QA с проверкой фактов о версиях/API на первоисточниках, а не по памяти.
• Интеграция инструментов: Figma REST API (разбор макетов 8:2 и 8:83 в дизайн-токены), генерация кода миграции и идемпотентных MODX-скриптов, итеративные правки шаблона по ревью заказчика. Артефакты ИИ-процесса: CLAUDE.md, docs/prompts/*, docs/research/*, docs/analysis/*, docs/plan/*, scripts/modx-build/*.

Инженерные вызовы

• Работа напрямую на боевом сайте без стейджинга — компенсирована множественными бэкапами/точками отката, созданием всех элементов «скрытыми» и единой «точкой интеграции».
• Контент только в БД (MODX) — потребовал сборки через MODX API-скрипты, а не правки файлов; отдельная ловушка с правами кэша (скрипты от root создают кэш root:root → Apache ломается; решение — chown кэша после каждого build).
• Неоднородные PDF — единый парсер структуры (PyMuPDF) с распознаванием заголовков по размеру шрифта и склейкой 2-строчных пунктов списков; баг склейки выявлен и исправлен, 42 статьи перемигрированы.
• Legacy-ограничения и риски: MODX 2.8.1 с незакрываемым без обновления RCE (CVE-2022-26149), EOL PHP 7.3, alpha-MIGX, отсутствие сборки фронта — обойдены конфигурацией/изоляцией; критичное вынесено заказчику.
• Безопасность секретов: в проде обнаружены захардкоженные секреты (Telegram-токен/chat_id, SMTP-пароль в submit.php, пароль БД в конфиге). Их значения не извлекались и не выносились в артефакты — зафиксирован только факт и рекомендация ротации/выноса (выполняет разработчик заказчика).