dsh-desktop-kit 0.0.0-stage → 2.0.0

package/skills/seo/references/stack-recipes.md

@@ -0,0 +1,695 @@
+> Часть навыка seo. ≈10 100 токенов. Читать, когда: пишешь SEO в коде — Laravel/Blade, Bitrix/Aspro, React/Vite, статика; один источник SEO-данных, мета и JSON-LD в исходном HTML, сервер/деплой.
+
+# Стек-рецепты: Laravel/Blade, Bitrix/Aspro, React/Vite, статика
+
+> Готовые паттерны, чтобы SEO-по-умолчанию не превращалось в ручную работу. Всё написано так, чтобы
+> **мета и JSON-LD попадали в исходный HTML на сервере** (это главное требование любого стека).
+> Проверено 04.11.2026.
+
+## 0. Общие принципы (для любого стека)
+
+1. **Один источник SEO-данных.** Не разбрасывай title/description по шаблонам: собери объект `SeoData`
+   (title, description, canonical, robots, og, jsonld, breadcrumbs) и рендерь его в одном месте.
+2. **Значения по умолчанию** (сайт/организация/шаблон title) + переопределение на странице.
+3. **Экранирование.** Всё, что попадает в HTML-атрибуты, — через escape (`{{ }}` в Blade, `htmlspecialchars`
+   в PHP, `escapeHtml` в JS). JSON-LD — через `json_encode` с флагами, не склейкой строк.
+4. **Абсолютные URL** стройте от `url()`/`config('app.url')`/`Request::root()`, а не от `/path` вручную.
+5. **Проверка в CI:** страница 200, title/description/H1 есть, canonical есть, JSON-LD валиден, 0 critical
+   в `seo-audit.mjs`.
+6. **Не трогай SEO-данные без baseline** (какие title/URL были до). Смена URL — 301 (см. `technical-seo.md`).
+
+---
+
+## 1. Laravel + Blade
+
+### 1.1 Объект SEO-данных
+
+```php
+<?php
+// app/Support/Seo/SeoData.php
+namespace App\Support\Seo;
+
+final class SeoData
+{
+    public array $jsonLd = [];
+    public array $breadcrumbs = [];
+    public ?string $ogImage = null;
+
+    public function __construct(
+        public string $title,
+        public string $description,
+        public string $canonical,
+        public string $robots = 'index,follow',
+        public string $type = 'website',
+    ) {}
+
+    public function addJsonLd(array $node): self
+    {
+        $this->jsonLd[] = $node;
+
+        return $this;
+    }
+
+    public function breadcrumbs(array $items): self
+    {
+        $this->breadcrumbs = $items; // [['name' => 'Главная', 'url' => '/'], ...]
+
+        return $this;
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'title' => $this->title,
+            'description' => $this->description,
+            'canonical' => $this->canonical,
+            'robots' => $this->robots,
+            'type' => $this->type,
+            'ogImage' => $this->ogImage,
+            'jsonLd' => array_merge($this->jsonLd, $this->breadcrumbNode()),
+            'breadcrumbs' => $this->breadcrumbs,
+        ];
+    }
+
+    private function breadcrumbNode(): array
+    {
+        if (count($this->breadcrumbs) < 2) {
+            return [];
+        }
+
+        return [[
+            '@context' => 'https://schema.org',
+            '@type' => 'BreadcrumbList',
+            'itemListElement' => array_map(
+                fn (array $item, int $i) => array_filter([
+                    '@type' => 'ListItem',
+                    'position' => $i + 1,
+                    'name' => $item['name'],
+                    'item' => isset($item['url']) ? url($item['url']) : null,
+                ]),
+                $this->breadcrumbs,
+                array_keys($this->breadcrumbs),
+            ),
+        ]];
+    }
+}
+```
+
+### 1.2 Глобальные данные + хелпер
+
+```php
+<?php
+// app/Support/Seo/Seo.php
+namespace App\Support\Seo;
+
+class Seo
+{
+    public static function page(string $title, string $description, ?string $path = null): SeoData
+    {
+        $canonical = $path ? url($path) : url()->current();
+
+        return new SeoData(
+            title: $title,
+            description: $description,
+            canonical: $canonical,
+        );
+    }
+
+    public static function organization(): array
+    {
+        return [
+            '@context' => 'https://schema.org',
+            '@type' => ['MedicalOrganization', 'MedicalClinic'],
+            '@id' => url('/') . '#organization',
+            'name' => config('seo.org_name'),
+            'url' => url('/'),
+            'logo' => ['@type' => 'ImageObject', 'url' => asset('img/logo-512.png')],
+            'telephone' => config('seo.org_phone'),
+            'address' => [
+                '@type' => 'PostalAddress',
+                'streetAddress' => config('seo.addr_street'),
+                'addressLocality' => config('seo.addr_city'),
+                'postalCode' => config('seo.addr_zip'),
+                'addressCountry' => 'RU',
+            ],
+            'sameAs' => config('seo.same_as', []),
+        ];
+    }
+}
+```
+
+`config/seo.php` — единый конфиг: название, телефон, адрес, соцсети, `og:image` по умолчанию, `robots` для
+закрытых разделов. Значения — из `.env`/админки, **не хардкод** по шаблонам.
+
+### 1.3 Blade-компонент `<x-seo-meta>`
+
+```blade
+{{-- resources/views/components/seo/meta.blade.php --}}
+@props(['seo'])
+@php
+    $seo = is_array($seo) ? $seo : $seo->toArray();
+    $jsonLd = array_values(array_filter($seo['jsonLd'] ?? []));
+@endphp
+
+<title>{{ $seo['title'] }}</title>
+<meta name="description" content="{{ $seo['description'] }}">
+<meta name="robots" content="{{ $seo['robots'] ?? 'index,follow' }}">
+<link rel="canonical" href="{{ $seo['canonical'] }}">
+
+{{-- Open Graph --}}
+<meta property="og:type" content="{{ $seo['type'] ?? 'website' }}">
+<meta property="og:site_name" content="{{ config('seo.org_name') }}">
+<meta property="og:locale" content="ru_RU">
+<meta property="og:title" content="{{ $seo['title'] }}">
+<meta property="og:description" content="{{ $seo['description'] }}">
+<meta property="og:url" content="{{ $seo['canonical'] }}">
+<meta property="og:image" content="{{ $seo['ogImage'] ?? asset('img/og-default-1200x630.jpg') }}">
+<meta property="og:image:width" content="1200">
+<meta property="og:image:height" content="630">
+<meta name="twitter:card" content="summary_large_image">
+
+@if ($jsonLd)
+    @foreach ($jsonLd as $node)
+        <script type="application/ld+json">{!! json_encode($node, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_HEX_TAG | JSON_HEX_AMP) !!}</script>
+    @endforeach
+@endif
+```
+
+Флаги **обязательны**: `JSON_UNESCAPED_UNICODE` (кириллица читаемо), `JSON_UNESCAPED_SLASHES` (URL не
+`\/`), `JSON_HEX_TAG`/`JSON_HEX_AMP` (защита от XSS/разрыва тега).
+
+### 1.4 Layout
+
+```blade
+{{-- resources/views/layouts/app.blade.php --}}
+<!doctype html>
+<html lang="ru" prefix="og: https://ogp.me/ns#">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <x-seo.meta :seo="$seo ?? \App\Support\Seo\Seo::page(
+        config('seo.default_title'),
+        config('seo.default_description')
+    )" />
+    @stack('head')
+    @vite(['resources/css/app.css', 'resources/js/app.js'])
+</head>
+<body>
+    @include('partials.header')
+    <main id="main">
+        @yield('content')
+    </main>
+    @include('partials.footer')
+    @stack('scripts')
+</body>
+</html>
+```
+
+### 1.5 Контроллер страницы услуги
+
+```php
+public function show(Service $service): View
+{
+    $seo = Seo::page(
+        title: "{$service->title} в организация — цена от {$service->price_from} ₽",
+        description: Str::limit($service->short_description, 155),
+        path: "/uslugi/{$service->slug}/",
+    )
+        ->breadcrumbs([
+            ['name' => 'Главная', 'url' => '/'],
+            ['name' => 'Услуги', 'url' => '/uslugi/'],
+            ['name' => $service->category->title, 'url' => "/uslugi/{$service->category->slug}/"],
+            ['name' => $service->title],
+        ])
+        ->addJsonLd([
+            '@context' => 'https://schema.org',
+            '@type' => 'MedicalWebPage',
+            'url' => url("/uslugi/{$service->slug}/"),
+            'name' => $service->title,
+            'description' => $service->short_description,
+            'inLanguage' => 'ru-RU',
+            'datePublished' => $service->published_at?->toDateString(),
+            'dateModified' => $service->updated_at->toDateString(),
+            'lastReviewed' => $service->reviewed_at?->toDateString(),
+            'reviewedBy' => $service->reviewer ? [
+                '@type' => 'Physician',
+                'name' => $service->reviewer->full_name,
+                'jobTitle' => $service->reviewer->specialty,
+                'url' => route('doctors.show', $service->reviewer),
+            ] : null,
+        ]);
+
+    return view('services.show', compact('service', 'seo'));
+}
+```
+
+### 1.6 sitemap.xml и robots.txt (роуты, а не файлы)
+
+```php
+// routes/web.php
+Route::get('/sitemap.xml', SitemapController::class)->name('sitemap');
+Route::get('/robots.txt', RobotsController::class)->name('robots');
+```
+
+```php
+<?php
+namespace App\Http\Controllers;
+
+use Illuminate\Http\Response;
+
+class RobotsController extends Controller
+{
+    public function __invoke(): Response
+    {
+        $content = implode("\n", [
+            'User-agent: *',
+            'Disallow: /admin',
+            'Disallow: /login',
+            'Disallow: /search',
+            'Disallow: /*?sort=',
+            'Allow: /',
+            '',
+            'Sitemap: ' . url('/sitemap.xml'),
+        ]);
+
+        return response($content, 200, ['Content-Type' => 'text/plain; charset=UTF-8']);
+    }
+}
+```
+
+```php
+<?php
+namespace App\Http\Controllers;
+
+use App\Models\Service;
+use App\Models\Doctor;
+use App\Models\Post;
+
+class SitemapController extends Controller
+{
+    public function __invoke()
+    {
+        $urls = collect()
+            ->push(['loc' => url('/'), 'lastmod' => now()->toDateString(), 'priority' => '1.0'])
+            ->merge(Service::published()->get()->map(fn ($s) => [
+                'loc' => url("/uslugi/{$s->slug}/"),
+                'lastmod' => $s->updated_at->toDateString(),
+                'priority' => '0.8',
+            ]))
+            ->merge(Doctor::published()->get()->map(fn ($d) => [
+                'loc' => url("/vrachi/{$d->slug}/"),
+                'lastmod' => $d->updated_at->toDateString(),
+                'priority' => '0.7',
+            ]))
+            ->merge(Post::published()->get()->map(fn ($p) => [
+                'loc' => url("/blog/{$p->slug}/"),
+                'lastmod' => $p->updated_at->toDateString(),
+                'priority' => '0.6',
+            ]));
+
+        return response()
+            ->view('seo.sitemap', ['urls' => $urls])
+            ->header('Content-Type', 'application/xml; charset=UTF-8');
+    }
+}
+```
+
+```blade
+{{-- resources/views/seo/sitemap.blade.php --}}
+{!! '<'.'?xml version="1.0" encoding="UTF-8"?'.'>' !!}
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+@foreach ($urls as $u)
+  <url>
+    <loc>{{ $u['loc'] }}</loc>
+    <lastmod>{{ $u['lastmod'] }}</lastmod>
+    <priority>{{ $u['priority'] }}</priority>
+  </url>
+@endforeach
+</urlset>
+```
+
+> Осторожно с `{{ '<'.'?xml' }}`: Blade съедает `<?xml`. Альтернатива — `response()->view(...)->header(...)`
+> с шаблоном, где первая строка выводится через `{!! !!}` с экранированием, или отдавать sitemap строкой
+> из PHP (надёжнее). Кэшируй sitemap (`Cache::remember('sitemap', 3600, ...)`), но сбрасывай кэш при
+> публикации/обновлении сущности.
+
+### 1.7 301-редиректы (middleware)
+
+```php
+<?php
+// app/Http/Middleware/CanonicalHost.php — http→https, www→без www, слэш
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+
+class CanonicalHost
+{
+    public function handle(Request $request, Closure $next)
+    {
+        $host = $request->getHost();
+        $canonical = config('seo.canonical_host');
+        $needsRedirect = $host !== $canonical
+            || ! $request->isSecure()
+            || ($request->getPathInfo() !== '/' && str_ends_with($request->getPathInfo(), '/'));
+
+        if ($needsRedirect && ! app()->environment('local')) {
+            $path = rtrim($request->getPathInfo(), '/') ?: '/';
+            $query = $request->getQueryString();
+
+            return redirect()->to(
+                'https://' . $canonical . $path . ($query ? '?' . $query : ''),
+                301
+            );
+        }
+
+        return $next($request);
+    }
+}
+```
+
+Исторические редиректы (после смены URL) — таблицей в БД/конфиге + middleware `RedirectOldUrls`,
+**один прыжок**, без цепочек. Для массовых правил — `nginx`/`.htaccess` (быстрее).
+
+### 1.8 Прочее по Laravel
+
+- Роут-модель по `slug`, а не `id`; `Route::get('/uslugi/{service:slug}')`.
+- 404: `abort(404)` — Laravel отдаст 404 и страницу `errors/404.blade.php` (должна содержать навигацию).
+- `noindex` для страниц «спасибо»/личного кабинета: `Seo::page(...)->robots('noindex,follow')`.
+- Пагинация: `?page=` + canonical на текущую страницу (`url()->full()` без лишних параметров).
+- Кэш: `view:cache`, `route:cache`, `config:cache` на проде; после деплоя — `php artisan optimize` по политике проекта.
+- Slug: `Str::slug($title)` транслитерирует кириллицу (`МРТ головы` → `mrt-golovy`). Проверяй уникальность и
+  не меняй slug у проиндексированных страниц без 301.
+- Пакет `spatie/laravel-sitemap` — удобно, если не хочется свой контроллер; для маленького сайта проще свой.
+
+---
+
+## 2. 1С-Битрикс + Aspro «Медицинский центр 3.0»
+
+### 2.1 Где что лежит (и где нельзя править)
+
+| Что | Где | Правило |
+|---|---|---|
+| Шаблон Aspro | `/local/templates/aspro-allcorp3medc/` | **правим только здесь**, не в `/bitrix/templates/` (маркетплейс) |
+| `init.php` | `/local/php_interface/init.php` | свои события/редиректы/SEO-логика |
+| `urlrewrite.php` | `/urlrewrite.php` + `/local/` | правила ЧПУ и 301 |
+| `robots.txt`, `sitemap.xml` | генерируются модулем «Поисковая оптимизация» (seo) | настраивать в админке, не руками в корне |
+| Ядро | `/bitrix/modules/` | **не трогать** |
+| Кэш | `/bitrix/cache/`, `/bitrix/managed_cache/`, `/bitrix/stack_cache/` | чистить после правок |
+
+Проверка окружения: `/bitrix/admin/` (админка), «Настройки → Настройки продукта → Настройки модулей →
+Поисковая оптимизация» — SEO-шаблоны, robots, sitemap.
+
+### 2.2 SEO-шаблоны инфоблоков (главный инструмент)
+
+В настройках инфоблока (вкладка **SEO**) задаются шаблоны для списка и детальной страницы:
+`title`, `description`, `keywords`, `h1`, `canonical`, `robots`, `og:*`. Макросы (синтаксис Bitrix):
+
+```
+{=this.name}                 — название текущего элемента/раздела
+{=this.property.SEO_TITLE}   — значение свойства
+{=parent.name}               — название родительского раздела
+{=section.name}              — раздел
+{=iblock.name}               — инфоблок
+{=this.id} / {=this.code}
+```
+
+Пример шаблона title для услуг: `{=this.name} в организация — цена, запись | {=parent.name}`
+Пример description: `{=this.name}: показания, подготовка, стоимость и запись в {=parent.name}. Опытные врачи, современное оборудование.`
+
+Правила:
+- Не делай шаблон «{=this.name} — {=iblock.name}» для всего — дубли и отсутствие интента.
+- Проверь каждую группу: шаблон применяется к **всем** элементам инфоблока, включая «пустые» свойства
+  (получишь «в организация — цена, запись» без названия).
+- Уникальные title/description можно переопределять через свойства элемента (`SEO_TITLE`, `SEO_DESCRIPTION`)
+  и отдавать их в шаблоне компонента/`header.php`.
+- После правки SEO-шаблона — **очистить кэш** (админка «Очистить кэш» или `/bitrix/admin/cache.php`)
+  и проверить живой HTML (`view-source`), иначе увидишь старый title.
+
+### 2.3 Мета в шаблоне (`header.php`) и компонентах
+
+```php
+<?php
+// /local/templates/aspro-allcorp3medc/header.php — фрагмент <head>
+$APPLICATION->ShowHead();
+?>
+<title><?php $APPLICATION->ShowTitle(); ?></title>
+<?php
+$canonical = $APPLICATION->GetPageProperty('canonical');
+if (!$canonical) {
+    $canonical = 'https://' . $_SERVER['HTTP_HOST'] . strtok($_SERVER['REQUEST_URI'], '?');
+}
+$APPLICATION->AddHeadString('<link rel="canonical" href="' . htmlspecialcharsbx($canonical) . '">', true);
+?>
+```
+
+Ключевые API:
+- `$APPLICATION->SetTitle(...)` — `<h1>`/`<title>` (в Aspro часто используется для H1).
+- `$APPLICATION->SetPageProperty('title', ...)`, `'description'`, `'keywords'`.
+- `$APPLICATION->SetPageProperty('canonical', ...)` — если шаблон/компонент это поддерживает; иначе
+  `AddHeadString`.
+- `$APPLICATION->AddHeadString('<meta ...>')` — для og/twitter (с `$unique=true`, чтобы не дублировать).
+- Aspro-медицина: у компонентов (`bitrix:news.list`, `bitrix:news.detail`, `aspro:...`) есть параметры
+  `SET_TITLE`, `SET_STATUS_404`, `SHOW_404`, `MESSAGE_404` — **включай** `SET_STATUS_404=Y`,
+  иначе будет «мягкий 404» с кодом 200.
+
+### 2.4 Canonical, 404, `noindex` в Битриксе
+
+- **Canonical** — на детальных страницах ставь на «чистый» URL без `?utm_*`, `?sort=`, `?PAGEN_*` (если это
+  фильтры), через `SetPageProperty('canonical', ...)`/`AddHeadString`.
+- **Мягкие 404**: `$APPLICATION->SetStatus('404')` / `CHTTP::SetStatus('404 Not Found')` при пустом результате;
+  у компонентов — `SET_STATUS_404=Y`. Проверка: `curl -I https://site.ru/net-takoy-stranicy/` → 404.
+- **noindex** для служебных страниц: `$APPLICATION->SetPageProperty('robots', 'noindex, follow')`
+  или `<meta name="robots">` в шаблоне; для целых разделов — «SEO → Настройки robots» / правила в админке.
+- **ЧПУ**: «Настройки → Настройки продукта → Настройки модулей → Главный модуль → Обработка ЧПУ»;
+  правила — в `urlrewrite.php`; проверь, что `/uslugi/mrt/` отдаёт 200, а не редирект на `?SECTION_ID=`.
+- **301**: правила в `urlrewrite.php` (массив `$arUrlRewrite`) или `init.php`:
+
+```php
+<?php
+// /local/php_interface/init.php — пример точечных 301
+AddEventHandler('main', 'OnEpilog', function () {
+    $uri = strtok($_SERVER['REQUEST_URI'], '?');
+    $map = [
+        '/uslugi/mrt-golovy/' => '/uslugi/mrt/',
+        '/old-section/'       => '/napravleniya/',
+    ];
+    if (isset($map[$uri]) && http_response_code() !== 301) {
+        LocalRedirect($map[$uri], false, '301 Moved Permanently');
+    }
+});
+```
+
+`LocalRedirect($url, $skip_security_check = false, $status = '302 Found')` — ставь 301 явно.
+
+### 2.5 robots.txt и sitemap.xml
+
+- **robots.txt**: «Настройки → Настройки продукта → Настройки модулей → Поисковая оптимизация → robots.txt».
+  Автогенерация учитывает настройки, но проверяй результат на живом URL. Не закрывай `/bitrix/js`, `/bitrix/css`,
+  `/upload`; закрывай `/bitrix/` (кроме нужных подпапок), `/local/` (кроме шаблона), `/search/`, `/auth/`.
+- **sitemap.xml**: тот же модуль → «Файлы Sitemap» / настройки генерации; проверь, что в карту попадают только
+  активные элементы с 200, что `<lastmod>` реальный (дата изменения элемента), и что карта доступна
+  `https://example.org/sitemap.xml`. Обновление — по агенту/по расписанию; после массовых правок — перегенерировать.
+- **Яндекс**: отправить sitemap в Вебмастер; проверить «Анализ robots.txt».
+- **Композитный сайт** (если включён): для авторизованных отдаётся динамика — проверяй SEO-мета в `view-source`
+  под гостем, иначе рискуешь увидеть «персонализированный» HTML.
+
+### 2.6 Aspro-медицина: частные грабли
+
+- Шаблон медицины — много компонентов с `SET_TITLE`; если заголовок дублируется (`<h1>` из компонента + свой) —
+  ищи `SET_TITLE=Y` и отключай в одном месте.
+- Услуги/врачи часто в разных инфоблоках и с разными URL — проверь, что карточка врача **одна**, а не
+  дублируется в каждом отделении (canonical или один источник).
+- Формы записи/личный кабинет — `noindex`; страницы «спасибо» — `noindex`.
+- Фильтры/сортировки (цены, алфавит) — не должны плодить индексируемые дубли: canonical на базовый URL
+  или `noindex,follow`; для Яндекса — `Clean-param`.
+- Кэш: после правки шаблона/`init.php` чисти кэш сайта и **кэш компонентов**; для админа помогает `?clear_cache=Y`,
+  но не полагайся на него для проверки — используй `view-source` в приватном окне.
+- Обновления Aspro: правки делать в `local/`, чтобы обновление шаблона их не снесло; `custom.css`/`init.php` —
+  штатные точки расширения (см. скилл `bitrix-aspro`).
+
+---
+
+## 3. React / Vite
+
+### 3.1 Главное решение: не SPA для контента
+
+Для медицинского сайта/лендинга выбирай:
+1. **SSG** (Astro, Next.js `output: 'export'`, Eleventy) — лучший вариант: мета и JSON-LD в статике, CWV отличные.
+2. **SSR** (Next.js App Router, Remix, Laravel+Vite SSR) — если нужна динамика/личный кабинет.
+3. **SPA + prerender** — компромисс: на этапе сборки прогнать список маршрутов через headless-браузер и
+   сохранить HTML (`vite-plugin-ssr`/Vike, `puppeteer` prerender, `react-snap`). Требует поддержки списка URL.
+
+**Не оставляй** контентные страницы на чистом CSR: title/meta/H1/ссылки должны быть в HTML.
+
+### 3.2 Astro (рекомендуемый вариант для статики)
+
+```astro
+---
+// src/pages/uslugi/[slug].astro
+import Layout from '../../layouts/Layout.astro';
+const { service } = Astro.props;
+---
+<Layout
+  title={`${service.title} в организация — цена от ${service.priceFrom} ₽`}
+  description={service.description.slice(0, 155)}
+  canonical={`https://example.org/uslugi/${service.slug}/`}
+  jsonLd={[{
+    '@context': 'https://schema.org',
+    '@type': 'MedicalWebPage',
+    url: `https://example.org/uslugi/${service.slug}/`,
+    name: service.title,
+    inLanguage: 'ru-RU',
+    lastReviewed: service.reviewedAt,
+  }]}
+>
+  <h1>{service.title}</h1>
+  <!-- контент -->
+</Layout>
+```
+
+```astro
+---
+// src/layouts/Layout.astro
+const { title, description, canonical, jsonLd = [] } = Astro.props;
+---
+<!doctype html>
+<html lang="ru">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title}</title>
+    <meta name="description" content={description} />
+    <link rel="canonical" href={canonical} />
+    <meta property="og:type" content="website" />
+    <meta property="og:locale" content="ru_RU" />
+    <meta property="og:title" content={title} />
+    <meta property="og:description" content={description} />
+    <meta property="og:url" content={canonical} />
+    <meta property="og:image" content="https://example.org/img/og-default-1200x630.jpg" />
+    {jsonLd.map((node) => (
+      <script type="application/ld+json" set:html={JSON.stringify(node)} />
+    ))}
+  </head>
+  <body><slot /></body>
+</html>
+```
+
+### 3.3 Next.js (App Router)
+
+- `generateMetadata()` на каждую страницу → `title`, `description`, `alternates.canonical`, `openGraph`, `robots`.
+- JSON-LD — обычный `<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(node) }} />`.
+- `app/not-found.tsx` + `notFound()` — реальный 404 (не отдавай 200 на неизвестный маршрут).
+- `app/sitemap.ts` и `app/robots.ts` — генерируемые sitemap/robots.
+- `next/image` для CWV (width/height, priority для LCP).
+- `export const dynamic = 'force-static'` для контентных страниц.
+
+### 3.4 Клиентский React (если SPA неизбежна)
+
+- React 19 умеет рендерить `<title>`/`<meta>`/`<link>` и «поднимать» их в `<head>`, но **только если есть SSR**.
+  В чистом CSR это не работает для роботов — не рассчитывай.
+- `react-helmet-async` — только вместе с SSR/prerender.
+- Роутинг: History API + сервер должен отдавать **реальный HTML** на каждый маршрут (SSR/SSG) и **404** на
+  неизвестные пути.
+- CWV: `React.lazy`/динамические импорты, без тяжёлых библиотек в первом экране; шрифты — `font-display: swap`;
+  изображения — `width/height`, WebP/AVIF, lazy ниже фолда.
+- Проверка: `view-source` + `curl -A Googlebot` — в ответе должны быть мета/контент/ссылки.
+
+---
+
+## 4. Статический HTML
+
+```html
+<!doctype html>
+<html lang="ru">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Кардиология в организация, Москва — врачи, диагностика, запись</title>
+  <meta name="description" content="Кардиологическое отделение: ЭКГ, ЭхоКГ, холтер, консультации кардиолога. Запись онлайн и по телефону.">
+  <meta name="robots" content="index,follow">
+  <link rel="canonical" href="https://example.org/napravleniya/kardiologiya/">
+  <meta property="og:type" content="website">
+  <meta property="og:locale" content="ru_RU">
+  <meta property="og:title" content="Кардиология в организация, Москва — врачи, диагностика, запись">
+  <meta property="og:description" content="...">
+  <meta property="og:url" content="https://example.org/napravleniya/kardiologiya/">
+  <meta property="og:image" content="https://example.org/img/og-kardiologiya-1200x630.jpg">
+  <script type="application/ld+json">
+  {"@context":"https://schema.org","@type":"MedicalWebPage","url":"https://example.org/napravleniya/kardiologiya/","name":"Кардиология","inLanguage":"ru-RU","lastReviewed":"2026-10-20"}
+  </script>
+</head>
+<body>
+  <h1>Кардиология: врачи, диагностика и лечение</h1>
+  <!-- контент, ссылки, alt, width/height -->
+</body>
+</html>
+```
+
+Для статики:
+- **sitemap** генерируй скриптом из списка HTML-файлов (Node/PHP) — не пиши руками, забудешь страницу.
+- **robots.txt** — файл в корне + `Sitemap: https://.../sitemap.xml`.
+- Проверяй относительные пути: при открытии через `file://` ссылки работают, но в вебе нужны правильные корни.
+- Хостинг: настроить 404-страницу, HTTPS, gzip/brotli, кеш статики.
+
+---
+
+## 5. Сервер/деплой: минимум для SEO
+
+### nginx
+
+```nginx
+# http → https + www → без www + слэш
+server {
+    listen 80;
+    server_name example.ru www.example.ru;
+    return 301 https://example.ru$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name www.example.ru;
+    return 301 https://example.ru$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name example.ru;
+    root /var/www/example/public;
+    # ... fastcgi/php
+    error_page 404 /404.html;
+    add_header Cache-Control "public, max-age=3600" always; # для статики — долгий immutable
+}
+```
+
+### .htaccess (Apache/Битрикс)
+
+```apache
+RewriteEngine On
+RewriteCond %{HTTPS} !=on [OR]
+RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC]
+RewriteRule ^ https://example.ru%{REQUEST_URI} [R=301,L]
+```
+
+### Проверка после деплоя (5 минут)
+
+```bash
+curl -sI https://example.ru/uslugi/mrt/ | head -20        # 200, content-type, кеш
+curl -s  https://example.ru/uslugi/mrt/ | grep -E 'title|canonical|og:'
+curl -sI https://example.ru/net-takoy-stranicy/ | head -3 # 404
+curl -s  https://example.ru/robots.txt
+curl -s  https://example.ru/sitemap.xml | head -20
+```
+
+Плюс: Rich Results Test для 2–3 типов страниц, `seo-audit.mjs` по странице/URL, GSC «Проверка URL».
+
+---
+
+## 6. Первоисточники
+
+- Laravel: https://laravel.com/docs/blade · https://laravel.com/docs/routing
+- Bitrix (техдокументация): https://dev.1c-bitrix.ru · модуль «Поисковая оптимизация» (seo)
+- Aspro: документация шаблона «Медицинский центр 3.0» + скилл `bitrix-aspro` (локально)
+- Astro: https://docs.astro.build · Next.js: https://nextjs.org/docs
+- Google. Управление мета-тегами/JS: https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics
+- Google. URL-структура: https://developers.google.com/search/docs/crawling-indexing/url-structure