Update migration guide

spec/migration.md

@@ -27,11 +27,20 @@
 
 ---
 
+## Принятые решения
+
+- **URL статей**: упрощаем до `/articles/slug/`, старые URL (`/articles/YYYY/MM/DD/slug/`) — 301-редиректы в nginx
+- **Пакет `@anwinged/predictor`**: чистый TypeScript, без привязки к фреймворку — миграция на Vue 3 затрагивает только обёртку
+- **Tailwind CSS**: используем; Tailwind 4 делает tree-shaking из коробки — в сборку попадают только используемые утилиты
+- **Текст на главной**: переносим как есть, автор обновит сам
+- **Галерея**: один альбом с фотографиями, хранение в `src/content/gallery/` (оптимизация через Astro Image)
+- **Локальная разработка**: всё через Docker (и dev, и build), npm на хосте не используем
+
 ## Целевое состояние
 
 ### Стек
 - **Генератор**: Astro
-- **Стилизация**: Tailwind CSS
+- **Стилизация**: Tailwind CSS 4
 - **Интерактивность**: Vue 3 (islands, для гадалки и будущих компонентов)
 - **Сборка**: Docker (один Node-контейнер), Taskfile
 - **Деплой**: Docker-образ nginx, Ansible (без изменений)
@@ -39,7 +48,7 @@
 ### Разделы сайта
 1. **Главная** — краткое описание, ссылки
 2. **Блог** — статьи и эссе по программированию
-3. **Галерея** — фотографии (новый раздел, реализуется позже)
+3. **Галерея** — один альбом с избранными фотографиями
 
 ---
 
@@ -53,9 +62,9 @@
 - Установить интеграции: `@astrojs/sitemap`, `@astrojs/rss`, `@astrojs/vue`, `@astrojs/tailwind`
 - Настроить TypeScript (strict или relaxed — на усмотрение)
 
-#### 1.2. Настроить Tailwind CSS
+#### 1.2. Настроить Tailwind CSS 4
-- Установить и настроить Tailwind
+- Установить и настроить Tailwind 4 (tree-shaking из коробки — в сборку попадает только используемый CSS)
-- Перенести дизайн-токены из SCSS-переменных в Tailwind-конфигурацию:
+- Перенести дизайн-токены из SCSS-переменных в Tailwind-конфигурацию (через `@theme` в CSS):
   - Шрифты: PT Serif (serif), Source Code Pro (mono)
   - Цвета: `#24292e` (текст), `#0366d6` (ссылки), `#e6e6e6` (линии)
   - Ширина контента: 740px
@@ -70,11 +79,11 @@
 #### 1.4. Обновить Taskfile
 - Убрать задачи: `composer`, `sculpin`, `shell-node`, `format-php`
 - Обновить задачи сборки:
-  - `build-dev`: `astro build` (dev-режим — через `astro dev`)
   - `build-prod`: `astro build`
+- Добавить задачу `dev`: запуск `astro dev` для локальной разработки (через Docker с проброшенными портами)
 - Обновить задачу `deploy`: путь к собранным файлам `dist/`
-- Добавить задачу `dev`: запуск `astro dev` для локальной разработки
 - Сохранить структуру Docker-команд через Taskfile
+- Все npm/astro-команды выполняются внутри Docker-контейнера
 
 ---
 
@@ -123,19 +132,20 @@
   {
     title: z.string(),
     description: z.string().optional(),
-    date: z.date(),              // извлечь из имени файла или добавить в frontmatter
     keywords: z.array(z.string()).optional(),
     tags: z.array(z.string()).optional(),
     draft: z.boolean().default(false),
+    // date — парсится из имени файла (YYYY-MM-DD-slug.md), не хранится в frontmatter
   }
   ```
 
 #### 3.2. Перенести статьи
 Перенести 8 markdown-файлов из `source/_articles/` в `src/content/articles/`.
 
+Имена файлов сохраняют даты (формат `YYYY-MM-DD-slug.md`) для удобной навигации в файловой системе. Дата парсится из имени файла при сборке (в `content.config.ts` или в `getStaticPaths`), дублировать в frontmatter не нужно.
+
 Необходимые изменения в каждом файле:
 - Удалить Sculpin-специфичные поля frontmatter (`layout`, `styles`, `scripts`, `use`)
-- Добавить поле `date` (сейчас дата в имени файла, нужно продублировать в frontmatter)
 - Оставить `title`, `description`, `keywords`
 - Опционально: добавить `tags` для будущей фильтрации
 
@@ -155,7 +165,7 @@
 Шаги:
 - Переименовать файл в `.mdx`
 - Обновить Vue-компонент `PredictorDemo.vue` до Vue 3 (Composition API или Options API)
-  - `@anwinged/predictor` — проверить совместимость с Vue 3, при необходимости обновить
+  - `@anwinged/predictor` — чистый TS, совместимость с Vue 3 не затронута
   - Перенести scoped-стили компонента на Tailwind или оставить scoped CSS
 - В MDX-файле: импортировать компонент и использовать `<PredictorDemo client:visible />`
 - Удалить ручное подключение JS/CSS через frontmatter (`styles`, `scripts`)
@@ -184,10 +194,23 @@
 - Использовать `InternalLayout`
 - Текст "Страница не найдена" и ссылка на главную
 
-#### 4.5. Страница галереи `src/pages/gallery/index.astro` (заглушка)
+#### 4.5. Страница галереи `src/pages/gallery/index.astro`
 - Использовать `InternalLayout`
-- Placeholder-страница "Скоро здесь будут фотографии"
+- Content Collection `gallery` — фотографии с метаданными (title, описание, дата, порядок)
-- Полноценная реализация — отдельная задача в будущем
+- Структура хранения:
+  ```
+  src/content/gallery/
+  ├── photo-001.md        # frontmatter: title, image, order
+  ├── photo-002.md
+  └── ...
+  public/photos/
+  ├── photo-001.jpg       # оригиналы фотографий
+  ├── photo-002.jpg
+  └── ...
+  ```
+- Сетка превью с оптимизацией через Astro Image (WebP/AVIF, responsive sizes)
+- Просмотр полноразмерных фотографий: lightbox-библиотека (PhotoSwipe или GLightbox)
+- Один альбом, без категорий
 
 ---
 
@@ -267,16 +290,23 @@ tasks:
 
 ---
 
-## Сохранение URL-совместимости
+## URL-совместимость
 
-Текущие URL статей имеют формат: `/articles/YYYY/MM/DD/slug/`
+Новые URL: `/articles/slug/` (например, `/articles/predictor/`).
-(например, `/articles/2019/05/01/predictor/`).
 
-Нужно сохранить эти URL, чтобы не сломать внешние ссылки. Варианты:
+Редиректы в nginx для старых URL (301):
-1. **Настроить slug в Astro** — использовать `getStaticPaths()` с кастомными slug, повторяющими текущую структуру
+```
-2. **Редиректы в nginx** — если хочется упростить URL-структуру (например, `/articles/predictor/`), настроить 301-редиректы со старых URL
+/articles/2019/05/01/predictor/  →  /articles/predictor/
+/articles/2019/06/01/php-serialization/  →  /articles/php-serialization/
+/articles/2019/06/28/storytelling/  →  /articles/storytelling/
+/articles/2019/08/08/yandex-disk-image-hosting/  →  /articles/yandex-disk-image-hosting/
+/articles/2019/09/26/highload-videos/  →  /articles/highload-videos/
+/articles/2020/06/27/interesting-programming-blogs/  →  /articles/interesting-programming-blogs/
+/articles/2020/06/27/type-discriminant/  →  /articles/type-discriminant/
+/articles/2020/11/08/nullable-fields/  →  /articles/nullable-fields/
+```
 
-Рекомендация: упростить URL до `/articles/slug/` и настроить редиректы в nginx для старых URL.
+Также редирект `/atom.xml` → `/rss.xml` для совместимости RSS-подписок.
 
 ---