Sharifa — бэкенд исламского приложения: аудит, доработка и DevOps

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

Sharifa — исламское мобильное приложение (iOS/Android, Flutter), включающее цифровой Коран/мусхаф, азкары, дуа, хадисы, 99 имён Аллаха, гайды по намазу, видео-Коран, FAQ, групповую геймификацию (задания, рейтинг), счётчики салаватов и стрик чтения. Продукт живой и обслуживает реальный трафик (в App Store — версия 1.2.2, разработчик Comrades Devs LLC).

Бэкенд (sharifa_back, Laravel 11) к моменту подключения автора был уже зрелым, но запущенным с рискованной конфигурацией: единственный экземпляр в проде без staging, dev-настройки на боевом сервере, неработающая почта (блокер регистрации), сломанные платежи, ненастроенные cron/queue, открытый CORS и отсутствие rate-limit, а также серьёзные расхождения с техническим заданием «Sharifa Мусхаф v1.7» (отсутствовали синхронизация закладок/папок/заметок, постраничный Коран, удаление аккаунта и др.). Кроме того, исходный домен бэкенда оказался неконтролируемым и размещён на мультитенантном сервере — возникла задача планирования переезда. Цель работы: честно оценить состояние системы, устранить критические дефекты и закрыть приоритетные пробелы ТЗ, не нарушив работу боевого продукта.

Что я сделал

Подача честная: исходный бэкенд написан не мной — это легаси команды (≈4 года развития, мобильный клиент и Laravel-ядро других авторов). Моя роль — аудит → устранение долга → доработка → DevOps, при этом за период работы (06.2026) я стал автором с наибольшим числом коммитов в sharifa_back (62).

• Аудит (read-only). Снял слепок боевого кода и БД (49 таблиц, COUNT(*) по всем, полный DDL), окружения и runtime; провёл три итерации анализа ТЗ↔реализация (v1–v3.1) с многоагентной адверсариальной перепроверкой выводов. Отдельно — аудит сервера (доступы, сервисы, домены, нагрузка, риски). Каждое утверждение подкреплено файлом/строкой или числом; на сервере ничего не менялось.
• Устранение багов и безопасности. Отдельными ветками с тестами: устойчивость YooKassaService к пустым реквизитам (баг ронял route:cache/optimize), устранение утечек полей в Resources, чистка дублей языков, корректная валидация фильтров категорий (публичные 500 → 422), throttle и анти-спам на формах, hardening кастомной авторизации, устранение всех падений автотестов (5 первопричин).
• Новый функционал API. Синхронизация избранного с папками и заметками (CRUD, снапшот sync, per-folder заметки, live-резолв контента), удаление аккаунта (GDPR §11.3), эндпоинт постраничных шрифтов мусхафа (GET /api/v1/mushaf/fonts + artisan-команда генерации манифеста), удаление device-token, уведомления и обработка заявок «аль-Фатиха».
• DevOps и публикация контента. Runbook чистого развёртывания на новый сервер; безопасная публикация пакета из 604 шрифтов QCF v2 (целостность по sha256, версионирование, отдельный nginx-location, регресс-проверка соседнего проекта); план переезда прод через переключение Firebase Remote Config без релиза приложения.
• Интеграция и контракт. Полный анализ связи Flutter-клиента с бэкендом (38 эндпоинтов сверено, заголовок Mobile-locale, Bearer/Sanctum, источник base URL — Remote Config); подготовил Flutter-гайды и контракты эндпоинтов для мобильной команды; синхронизировал поведение с OpenAPI-контрактом.

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

Бэкенд построен на чистом слоёном Laravel 11: тонкие контроллеры + одноклассовые Action-объекты (одна операция = один класс), Form Requests для валидации, Resources для формы ответа, две параллельные системы фильтров и отдельный Sorter. Мультиязычность — через модели-спутники *Translation + глобальный LocaleScope, локаль из заголовка Mobile-locale; админы намеренно обходят скоуп. Авторизация — Sanctum (мобильное API) + Fortify (кастомная верификация по коду), роли через колонку role и AdminMiddleware. Свои доработки я встраивал строго в существующий паттерн домена (Action/Request/Resource), сохраняя консистентность.

Каждая фича шла полным циклом spec → TDD-план → реализация → независимое ревью (артефакты в sharifa_back/docs/superpowers/specs|plans/), отдельной веткой feature/*/fix/* с интеграцией в integration/staging и проверкой бесконфликтной сборки. Шрифты мусхафа (~344 МБ) намеренно вынесены из git и раздаются статикой nginx с агрессивным кэшем; манифест-эндпоинт независим от раздачи файлов (до публикации отдаёт штатный 503/404). Все правки прода предусматривают бэкап конфига и откат за один шаг, а работа с боевой БД/сервером — только read-only и с явного согласия.

Результат

• Аудит зафиксировал реальную картину: 49 таблиц, 27 контроллеров, 40 моделей, ~120 Actions; 22 бэкенд-задачи ТЗ разнесены на 7 багов/нерабочего, 10 нового функционала и 5 доработок (источник: analysis-tz-vs-backend.md). Развенчаны и ложные тревоги (например, правило int — валидный алиас integer в Laravel 11).
• Внесено 19 содержательных изменений, 45 файлов, +2492/−195 строк; все ветки собираются без конфликтов (источник: client-report-sharifa-2026-06.html).
• Опубликовано 604 постраничных шрифта QCF мусхафа с проверкой целостности и версионированием (источник: runbook-mushaf-fonts-publish.md, HANDOFF_README.md).
• Автотесты стабилизированы (5 первопричин устранены; подтверждено сериями зелёных прогонов) — источник: client-report-sharifa-2026-06.html.
• Продукт остаётся живым в App Store (Comrades Devs LLC) — подтверждено публичной карточкой.
• Точная доля фич, уже выкаченных на боевой сервер на момент анализа, — не зафиксирована (уточнить): часть готовилась как автономный handoff (bundle/патчи) из-за отсутствия push-доступа на раннем этапе.

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

PHP 8.3 / Laravel 11 / MySQL 8 — существующий стек продукта; доработки следуют его конвенциям. Sanctum + Fortify — токены для мобильного API и кастомная верификация. Firebase Cloud Messaging (kreait/laravel-firebase) — пуши; YooKassa SDK — платежи/донаты; FFmpeg — аудио азкаров. Nginx + PHP-FPM + GitLab CI — раздача и деплой; supervisor + cron — недостающие на старом проде queue/scheduler. OpenAPI (Redocly/Spectral) — контракт API. Смежно проанализированы Vue 3 (админ-SPA) и Flutter (Riverpod, dio, Drift, auto_route, Freezed) — мобильный клиент; их разработка велась другими командами, моя роль здесь — анализ интеграции и контракты.

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

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

• Спроектировано безопасное рабочее пространство под команду: проектный CLAUDE.md, permissions deny/ask/allow (запрет мутаций прода и доступа к секретам), 4 hooks (guard Bash, php-lint+Pint, защита путей, secret-scan), read-only MCP (Laravel Boost с изоляцией локальной БД, GitLab read-only, OpenAPI-навигатор, context7), субагенты (laravel-code-reviewer, security-auditor, php-test-engineer, migration-guardian, api-contract-syncer), слэш-команды (/test, /pint, /scribe, /api-contract-diff, /safe-prod-inspect), skill add-crud-resource. Выбор обоснован веб-исследованием с верификацией по исходникам (docs/claude-workspace-research-2026-05-29.md, docs/prompts/setup-claude-code-workspace-sharifa.md).
• Аудит — многоагентный и адверсариальный: результаты перепроверялись отдельными агентами со свежими доказательствами, ложные выводы помечались и исправлялись (server-audit-verification.md, версии analysis-tz-vs-backend.v1.v3).
• Doc-driven + TDD цикл: для каждой фичи — спека и план в sharifa_back/docs/superpowers/specs|plans/, затем тесты и реализация с независимым ревью (видно по истории коммитов: docs → план → test → feat → merge).
• Переиспользуемые промпты как артефакты (docs/prompts/): analyze-tz-and-backend.md, deep-audit-sharifa-back.md, combined-audit-sharifa.md, client-report-html-sharifa.md, session-handoff-sharifa.md. Использованы skill deep-research и субагент claude-code-guide для актуализации знаний о Claude Code и экосистеме.

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

• Боевой прод без страховки. Единственный экземпляр без staging, dev-конфигурация и открытый APP_DEBUG — любые проверки только read-only, изменения с бэкапом и откатом; раздача шрифтов проектировалась так, чтобы не задеть соседний мультитенантный проект (регресс-проверка после каждого reload nginx).
• Расхождение «приложение живёт, домен отключён». Установлено, что фактический адрес бэкенда не захардкожен, а приходит из Firebase Remote Config (проект sharifa-cmd), без дефолтов в коде, — это объяснило поведение прода и задало безопасную стратегию переезда (переключение URL без релиза в сторах).
• Каскад блокеров из аудита. Неработающая почта → 0 авторизованных пользователей → мертвы все auth-фичи (трекинг, салаваты, группы); платежи сломаны на уровне кода + пустые креды. Зафиксирована причинно-следственная цепочка и приоритезирована «Фаза 0» разблокировки.
• Передача без push-доступа. На раннем этапе фича шрифтов оформлена как автономный git-bundle + 6 патчей с инструкцией fast-forward — чтобы команда с доступом могла принять её без потери истории.
• Две параллельные системы фильтров и нюансы локализации (админ обходит LocaleScope) требовали аккуратной сверки use-импортов перед каждой доработкой.