go-learn/docs/plans/plan-phase-5.md

План фазы 5: этап 5 — игровой интерфейс (apps/web, Astro)

Обновлено: 2026-08-05 | Статус: завершён (гейты зелёные, astro build собирает dist)

Итоговые пометки (факт против плана)

• Astro запинен 5.18.2, а не 7.1.6: astro 6/7 жёстко требуют Node

  =22.12.0 (bin/astro.mjs, проверено по tarball), в окружении Node 20. 5.18.2 — последняя линия с engines ^20.3.0. Конфиг и объём — по плану (output: 'static', без интеграций).

• Зона расширена на 3 корневых конфига игноров: eslint.config.js, .prettierignore, .gitignore — по одной записи **/.astro/ (генерируемый astro каталог ломал lint/format).
• AiClient дополнен readonly fallback (предусмотрено текстом контракта); loadSettings/saveSettings — необязательным параметром StorageLike.
• Воркер собран Vite (chunk ai-worker-*.js в dist). Смоук dist в браузере: доска рендерится, ход игрока + ответ бота работают.

Критические долги (реестр — в начале, III.5)

• Нет.

Ключевые решения (не пере-решать)

• Astro 7.1.6 (версия сверена npm view 2026-08-05), output: 'static', без UI-фреймворков — vanilla TS + DOM (спека: «без тяжёлых UI-фреймворков»).
• Строки UI — один ресурсный файл src/ui/strings.ts с первого дня (спека).
• Отмена хода бота — terminate + пересоздание воркера (решение по известной проблеме cancel в реальном Worker, отчёт сессии 4).
• Режим подсказки: topMoves последнего MCTS-ответа как разметка + оценка; дельта = изменение winRate лучшего хода между запросами (упрощение — оценка с точки зрения стороны, чей ход анализировался; зафиксировано).
• Схема localStorage и AiClient — контракты в docs/INTERFACES.md (зафиксированы 2026-08-05 до кода).
• Страницы: / — заглушка-визитка со ссылкой на партию; /play — игра. Курс — этап 6, полировка (a11y, .htaccess) — этап 7.

Объём этапа 5

1. apps/web (Astro): package.json @go-learn/web 0.1.0, astro.config.mjs (static), tsconfig (extends базового, lib DOM), workspaces += "apps/*".
2. Страница /play: доска (packages/board render + reduceInput + setupCanvas + attachPointerInput), панель: выбор доски 9/13/19, уровня 1–6, цвета (чёрные/белые/случайно), коми (auto/число), кнопки «Пас», «Сдаться», «Отменить ход», «Новая партия»; счётчики пленников; статус-строка (чей ход, причина отказа из MoveError, итог партии).
3. Подсчёт по окончании (два паса): scorePosition + отметка мёртвых (suggestDeadGroups + ручной toggle по клику) → итог.
4. SGF: «Скачать SGF» (serializeSgf, blob-скачивание), «Загрузка SGF» — режим просмотра (parseSgf, навигация назад/вперёд без игры).
5. Подсказки ур. 4+ (переключатель, hintsEnabled): топ-3 хода маркерами с оценкой; дельта winRate.
6. 19×19 при ур. 4–6 — честное предупреждение (спека этапа 4).
7. Тёмная минималистичная тема (согласована с палитрой packages/board), адаптивность desktop+мобильные.
8. lib/storage.ts (по контракту), lib/ai-client.ts (по контракту), lib/game-store.ts (чистый, без DOM: GameTree + действия), ui/strings.ts.
9. Воркер: entry ai-worker.ts (строка подключения — комментарий в packages/ai/src/worker.ts), сборка воркера средствами Astro/Vite.

Тесты (гейт приёмки этапа)

• storage: roundtrip save→load; битый JSON/checksum/неизвестная version → дефолты + recovered; миграция-путь задокументирован.
• game-store (чистый): новая партия, ход игрока через pending→confirm, отказ с reason при нелегальном, пас×2 → фаза подсчёта, toggle мёртвой группы, итог, resign → result, отмена хода, viewer: загрузка SGF, навигация prev/next.
• ai-client: фейк-worker (инжекция) — маршрутизация ур. 1–3 в синхронный движок, ур. 4–6 в воркер; cancel → AiCancelledError; фолбэк при отказе воркера.
• Матрица «чего НЕ покрывает ни один тест»: реальный кадр канвы в браузере, pointer на тачах, реальный Worker, astro build — смоук этапа 7 + ручная проверка владельцем.
• vitest.config: include += apps/*/src.

Критерий выхода

Все тесты зелёные + npm run gates зелёный + astro build собирает dist. Критерий v1 №4 («чистый клон собирается») проверяется сборкой в этой фазе; №2 (партия против ур.5) и №5 (мобильный Safari) — ручная приёмка владельцем после фазы 5–7.