Методики сложных компонентов

Этот раздел хранит не пользовательскую документацию API, а объяснение причин: почему сложный компонент устроен именно так, какие внешние правила он моделирует, какие компромиссы уже были проверены и что нельзя менять без повторной проверки.

Обязательное правило. Если изменение затрагивает формулу, источник данных, публичный контракт, безопасность/приватность, существенное состояние интерфейса, доступность или исторически выбранный UX-паттерн сложного компонента, его методика проверяется и обновляется в том же PR. Код отвечает на вопрос «как», методика — «почему» и «что сломается, если изменить».

Публичная страница нужна не каждой методике. Для внутренних механизмов основная документация хранится рядом с кодом в astro/docs/components/, а исходник содержит короткий MAINTENANCE CONTRACT со ссылкой на неё. Публичная методика остаётся там, где сама модель полезна читателю или её важно открыть прямо из компонента.

Когда компонент считается сложным

Отдельная методика нужна, если выполняется хотя бы один из критериев:

• компонент содержит расчётную или предметную модель, особенно юридическую, налоговую, финансовую или медицинскую;
• имеет заметное клиентское состояние и несколько связанных сценариев взаимодействия;
• преобразует данные из внешнего API, базы или другого управляемого источника;
• затрагивает платежи, приватность, безопасность или передачу данных третьей стороне;
• является глобальным override Astro/Starlight и влияет сразу на большую часть сайта;
• имеет неочевидные UX-решения, появившиеся после нескольких итераций и пользовательской проверки;
• его публичный интерфейс используется многими статьями и тихая несовместимость может массово повредить контент.

Что должна содержать методика

1. Назначение и границы: что компонент делает и чего намеренно не делает.
2. Архитектура: какие файлы и слои отвечают за расчёт, данные, UI и интеграцию.
3. Предметные правила: формулы, пороги, источники данных, приоритеты и допущения.
4. Публичный контракт: props, ключи серий, форматы данных и обратная совместимость, если они существенны.
5. Почему интерфейс такой: решения, которые легко принять за случайные и «упростить» обратно.
6. История решений: значимые PR/коммиты и причина каждого поворота, а не механический changelog.
7. Контрольные сценарии: минимальный набор проверок после изменения.
8. Источники истины и ограничения проверки: где перепроверять внешние факты и что не было протестировано.

Реестр

Компонент / семейство	Почему сложный	Статус
TaxCalculator и внутренние слои	Налоговые формулы, несколько режимов, график, контекстные поля, правовые пороги	Публичная методика есть
UplatnicaGenerator	Платёжный payload, QR, реквизиты, передача данных внешнему QR-сервису	Внутренняя методика есть: docs/components/uplatnica.md
ContentInclude	Build-time transclusion, поиск секций, сноски, совместимость исторических slug	Внутренняя методика есть: docs/components/content-include.md
SmartTable / StructTable / SupabaseTable / SanityTable	Renderer, несколько источников данных, schema adapters, фильтрация и стабильные preset ID	Общая методика есть: docs/components/tables.md
Header / TwoColumnContent / ThemeSwitch / MascotSiteTitle	Глобальные Starlight overrides, sidebar/ToC state, языки, theme provider и responsive layout	Общая методика есть: docs/components/layout.md
PWARegistration + PWA config	Service worker, install/update prompt, offline-состояние, manifest и совместимость сборки	Методика есть: docs/PWA.md
StickerGallery, EditorialFooter, Countdown, embeds, Mermaid и другие небольшие custom widgets	Тонкие, но проектные контракты: metadata compatibility, privacy defaults, date semantics, security	Обзорная методика есть: docs/components/other-components.md
MDX autoimport, custom sidebar, footnotes, OG renderer, Rocket Loader protection	Глобальная build/runtime инфраструктура вне одного компонента	Внутренняя методика есть: docs/components/infrastructure.md

Внутренний индекс всех документов и правило эскалации находятся в astro/docs/components/README.md. Если новый компонент становится сложным, его нужно добавить туда и сюда в том же PR, не дожидаясь отдельного аудита.

Комментарии в исходниках

Для сложных компонентов используется короткий MAINTENANCE CONTRACT прямо в исходнике. Он не копирует длинную статью, а фиксирует самые опасные инварианты и ведёт к полной методике. Для тонких компонентов достаточно такого комментария и обзорного документа; сотни строк объяснений внутри .astro только мешали бы читать реализацию.

Связь с пользовательской документацией

Методика не должна дублировать энциклопедию. Если сложный компонент реализует предметную модель, понятную читателю — например налоговый расчёт — соответствующее объяснение должно существовать и в публичном контенте. Методика хранит технические причины, допущения и историю; энциклопедия объясняет сам предмет пользователю.

Проверка перед merge

1. Проверить текущий исходник и связанные конфиги, а не только методику.
2. Сверить методику с фактическим поведением после изменения.
3. Обновить контрольные сценарии, если появился новый edge case.
4. Если изменился пользовательский смысл — обновить соответствующую статью в Antiokh/rslive_content.
5. Не утверждать, что build или browser-проверка прошли, если они реально не выполнялись.