Учебник: редакционная готовность и границы проверки

Оглавление · Программа

Версия подготовлена 6 октября 2026 года в отдельной ветке docs/textbook-structure. Цель этапа — превратить плоское руководство в последовательный учебник с концепциями, схемами и практикумами. Это запись о содержании и проверках исходников, а не о публикации документационного сайта. Разбор реализации сверён с main на коммите 6f85fd5: главы self-hosted observability перенесены в тематический раздел. Адреса /devops/ и /observability/ сохранены; концептуальная глава имеет адрес /observability-concepts/. Наличие конфигурации мониторинга не подтверждает её выпуск на VPS.

Покрытие программы

Часть	Материалы и итоговый результат
I. Начало	Терминал/Git/worktree, установка, архитектура, первый diff и коммит
II–III. JS/TS и данные	Значения, ссылки, функции, FP, async, ADT, Zod и автоматы
IV. React	Компоненты, события, формы, effects, Flux/Context, FRP, MobX и сравнение моделей
V. Интерфейс	HTML/DOM/CSS, доступность, адаптивность, Mantine, CSS Modules, UIKit/Storybook
VI. Next.js	CSR/SSR/SSG/ISR, гидратация, Suspense/streaming, уровни кеша и гонки
VII. API	HTTP, origin/auth/CORS/CSRF, REST/OpenAPI/pagination, GraphQL/tRPC/gRPC/Protobuf, повтор
VIII. Хранение	SQL/NoSQL/NewSQL, PG/JSONB, Redis, TypeORM, транзакции, OLAP/колонки, MapReduce, окна, ANN
IX. CMS и S3	Модели, import/draft/publish, media lifecycle, S3/presign/multipart и ограничения Garage
X. Инструменты	Workspace/AST/модули, типы, Oxlint/Oxfmt, тесты, debugger/profiler и расследование
XI. DevOps	Linux/SSH, DNS/TLS/proxy, контейнеры, readiness, PG/WAL, миграции, CI/digest, наблюдаемость и restore
Дополнительный маршрут	PHP/MySQL/MariaDB: отдельные изменения языка/БД/ORM, карта типов, сверка и cutover
Практикум	Восемь интеграционных сценариев с входом, действиями и критериями приёмки

Темы имеют написанные объяснения и задания, а не карточки с обещанием будущих глав. Глубина разная: PostgreSQL/Strapi/Next.js связаны с текущим проектом, дополнительные системы изучаются в изолированных лабораториях. Учебник не является полным справочником каждого продукта и не внедряет их все в приложение.

Что проверено при подготовке

Проверка различает текст, алгоритм, серверный контракт и живую систему.

Проверка	Свидетельство и граница
Навигация	Реестр глав, уникальные slugs, локальные ссылки и сохранение старых адресов проверяются Node tests
Статический сайт	Next.js docs export и check-export проверяют HTML, внутренние ссылки, MDX и русскую 404
Схемы	Mermaid разбирается в strict mode с временным happy-dom; это не проверка геометрии в браузере
JS/TS примеры	Нативные вычисления, reducer/автоматы, async, агрегации и временные примеры запускались Node 24
Состояние	MobX 7.0.6, reducer, учебный атом/сигнал дают одинаковые snapshots и прекращают подписки после cleanup
Кеш/streaming	Проверен управляемый порядок Promise, singleflight/generation, отказ и серверный React stream
API	HTTP/gRPC на loopback, GraphQL/tRPC внутри процесса: valid/invalid/missing/forbidden/version conflict
OpenAPI	Документ 3.1.1 валидирован swagger-parser 13.1.0; алгоритм keyset выполнен отдельно
SQL	PGlite 0.3.14 с PostgreSQL 17.5: JOIN/JSONB, FK/CHECK, планы, GROUP BY, журнал/rollback/replay/key conflict
TypeORM	Синтаксис, EntitySchema metadata/relations и SQL условного UPDATE проверены с 0.3.28 без подключения к БД
Диагностика	Числовые примеры, перцентили и создание CPU-профиля Node выполнены на учебных данных

PGlite — временный embedded runtime для части SQL, не production-зависимость и не замена PostgreSQL проекта. Он не подтверждает поведение пула, нескольких сетевых сессий, WAL crash recovery или физического restore. Лабораторные пакеты установлены вне репозитория; завершающие лаборатории не меняли workspace/Strapi lockfiles и стек.

Глубокое ревью 6 октября 2026

Независимое ревью нашло две ошибки исполняемой API-лаборатории: декодирование отдельных HTTP chunks повреждало кириллицу, а Protobuf int32 мог усечь большой ID до другой записи. Исправлены сбор байтов до декодирования и общий диапазон ID/версии с проверкой до сериализации. Добавлены проверки дробных/больших входов, неизменности записи и разрыва UTF-8 между chunks. Четыре adapters прошли приёмку.

Тесты реестра добавлены в PR job существующего deploy workflow: прежде они выполнялись только локально и при сборке docs-образа после слияния. Разрешены семь конфликтов с main (6f85fd5); эксплуатационные инструкции наблюдаемости сохранены. Повторное независимое ревью не нашло оставшихся P1/P2.

Локальные проверки после интеграции: 8 Node tests, typecheck, Oxlint, Oxfmt, Next.js docs export (90 HTML-страниц), strict Mermaid parse (83 схемы) и 635 ссылок на якоря. Реестр содержит 87 глав. GitHub PR у ветки пока отсутствует; CI итогового ref, браузер и VPS не проверены. Это не статус готовности к слиянию.

Согласование с SourceCraft

Перед публикацией ветка согласована с SourceCraft main (2a68a95). Главы о пилоте и PR-стендах перенесены в DevOps, их адреса /sourcecraft-pilot/ и /pr-environments/ сохранены. Реестр содержит 89 глав. Тесты реестра добавлены также в SourceCraft node-checks. Состав CI и стендов целевой ветки сохранён; исторические результаты выше относятся к соответствующим этапам подготовки.

Какие проверки выполняются отдельно

Следующие инструкции написаны, но не выдаются за результаты подготовки:

Настоящий браузер: layout, keyboard/screen reader, React observer integration, гидратация, CORS/cookies и видимая передача streaming через proxy.
PostgreSQL-сервер: две конкурентные psql sessions, соединения TypeORM, crash recovery, backup/restore и поведение конкретной конфигурации.
Внешние учебные сервисы: Redis, ClickHouse, pgvector/HNSW, распределённый SQL-кластер, PHP/MySQL/MariaDB и Garage multipart/presigned URL.
Генерация клиентов и их совместимость: OpenAPI/Protobuf codegen и потребители на других языках; один runtime schema check не покрывает эту границу.
GitHub CI, публикация документации, работающий VPS и редакторские данные: в этом этапе не запускались и не изменялись.

Каждая такая лаборатория указывает среду, наблюдение и приёмку. В отчёте читателя пишите фактический статус «выполнено / не запускалось / не прошло» и конкретную версию; наличие главы не меняет статус опыта. Production-образы проверяются штатным CI, публикация выполняется отдельным разрешённым этапом.

Редакционные правила дальнейших изменений

Сначала обновляйте объяснение изменённого контракта и его реальные команды. Типы, runtime-вход, права и ограничения БД рассматривайте отдельно.
Новую главу регистрируйте в apps/docs/src/lib/chapters.ts и связывайте с оглавлением/программой. Существующий slug сохраняйте при переносе файла.
Разделяйте работающий код Atmanki, временный исполняемый пример, упражнение и архитектурный вариант. Наличие схемы не означает наличие сервиса.
У диаграммы указывайте смысл стрелок и предел модели; для чисел — вход, единицы, алгоритм и допустимую погрешность. Не обещайте exactly-once по одному retry.
Проверяйте подходящие Node examples, документационные tests, typecheck, Oxlint/Oxfmt и целевой docs export после новых изменений.
Исторические отчёты оставляйте датированными: они не подтверждают нынешнюю публикацию, backup или состояние внешней системы.

Для следующего редакционного прохода используйте MDX там, где интерактивность помогает проверить переход или контрпример. Статический текст, таблица или Mermaid остаются достаточными для короткой объяснимой модели.