Wiki Rules

Правила работы с вики

Вики описывает сайт TravelAgency: как он устроен сейчас и что планируется. Репозиторий публичный, вики тоже: всё написанное видно всем.

Разделы

Раздел	Что сюда	Префикс имени файла
Главная	Короткий обзор сайта и ссылки на разделы	Home
Действующая документация	Только то, что уже работает в main: архитектура, API, сервисы, инфраструктура, как реализованы функции	Doc-
Будущие доработки	Видение, дорожная карта, ТЗ, концепции, идеи	Plan-
Служебное	Правила вики, политика секретов	без префикса

Простой пример. Описание нового фильтра каталога до разработки лежит на Plan- странице. Когда фильтр смержен в main, описание того, как он работает, появляется в Doc-Catalog и Doc-Public-API, а в плане остаётся пометка «сделано» со ссылкой.

Правило проверки: если утверждение на Doc- странице нельзя подтвердить кодом в main, его место на Plan- странице или нигде. Если факт не удалось проверить, рядом пишется «требует проверки» и ссылка на задачу; когда задача закрыта, пометка снимается.

Имена и заголовки

• Имя файла латиницей: Doc-Название-Через-Дефис.md, Plan-Название.md. Кириллица в имени файла ломает ссылки.
• Первая строка страницы: заголовок # … по-русски. Он и есть видимое название.
• Ссылки внутри вики: [текст](Имя-Файла) без .md; на раздел страницы: [текст](Имя-Файла#якорь).
• Архитектурные решения: Doc-ADR-NNN-Название, номер по порядку, не переиспользуется.

Боковая панель

• Каждая новая, переименованная или удалённая страница отражается в _Sidebar.md в том же коммите.
• Страница без ссылки в боковой панели считается ошибкой (кроме служебных _Sidebar, _Footer и страниц-заглушек переезда).

Переименование и удаление

• Вики не делает редиректов. При переименовании в том же коммите обновляются все ссылки на старое имя во всех файлах.
• Если на страницу ссылаются issue или внешние ресурсы, на старом имени остаётся страница из одной строки Страница перенесена: [Новое название](Новое-Имя).
• Перед пушем проверяется, что каждая ссылка ведёт на существующий файл.

Как писать

• Язык русский. Названия классов, полей, маршрутов и команд пишутся как в коде.
• Обезличенно: без имён людей, ролей и исполнителей, без упоминания конкретных компаний-заказчиков. Пишется, что делает система: «Gateway отвечает 404», а не «решили» или «сделал такой-то».
• Сначала простой пример (запрос и ответ, шаг пользователя), потом детали.
• Для сравнения можно ссылаться на Tourvisor и другие публичные сервисы.
• Длинное тире не используется: точка, двоеточие, запятая или скобки.
• Ссылки на задачи и PR (#81, PR #82) допустимы и полезны.
• Даты в формате 2026-10-17. Строка «Обновлено» не ставится: дату показывает история страницы.

Безопасность

Действует Секреты и чувствительные данные. Кратко: никаких паролей, токенов, ключей, строк подключения со значениями, содержимого .env и htpasswd, личных адресов почты и телефонов, учётных данных серверов. Имена переменных без значений и плейсхолдеры (CHANGE_ME, user@example.com) допустимы. Адрес dev-сервера и домен dev-стенда публиковать можно.

Перед каждым пушем в вики:

gitleaks dir --redact .
gitleaks git --redact .

Обе проверки должны пройти без находок. Если секрет попал в вики, сначала он ротируется, потом удаляется (см. Secrets-Policy).

Когда обновлять

• PR меняет поведение, API, контракты, настройки или инфраструктуру: соответствующая Doc- страница обновляется в момент мержа этого PR. В описании PR указывается, какая страница обновлена, или «вики не затронута».
• Функция из плана реализована: описание «как работает» пишется на Doc- странице, на Plan- странице пункт отмечается «сделано» со ссылкой на Doc- страницу и PR. Если план реализован целиком, Plan- страница сливается с действующей документацией по правилам переименования.
• План изменился или отменён: Plan- страница правится, отменённое помечается «отменено» с причиной или удаляется.
• Найдено расхождение Doc- страницы с кодом: правится вики, если код верный; иначе заводится issue.

Новое ТЗ

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