# Маршруты чтения Что читать под конкретную задачу и в каком порядке. Каждый маршрут собран так, чтобы после него задачу можно было выполнить целиком, не догадываясь о пропущенном. Общее для всех маршрутов: [PRINCIPLES](./development/architecture/PRINCIPLES.md) — почему всё устроено именно так. Одна страница, читается первой и объясняет решения в остальных документах. --- ## Собрать бэкенд | № | Документ | Что даёт | |---|---|---| | 1 | [PRINCIPLES](./development/architecture/PRINCIPLES.md) | принципы: контракт на границе, ничто не приколочено | | 2 | [BMAP](./development/architecture/BMAP.md) | корни репозитория, место бэка в продукте | | 3 | [BMBP](./development/architecture/BMBP.md) | слои, API-иерархия, конверт, данные, идемпотентность, транзакции | | 4 | [AUTH](./development/architecture/AUTH.md) | кто обращается и что ему можно: удостоверения, правила доступа | | 5 | [Стиль кода бэка](./development/process/backend-code-style.md) | именование, типизация, исключения, асинхронность, журнал | | 6 | [База данных](./development/operations/database.md) | схема на сервис, миграции, подключение и таймауты | | 7 | [Тестирование](./development/process/testing.md) | что покрывать на каждом слое | | 8 | [Git и репозитории](./development/process/git-and-repositories.md) | что попадает в историю, как ведём версии | Если бэков несколько и перед ними нужен единый вход — дальше [BMGP](./development/architecture/BMGP.md). Если сервисы общаются событиями — [Обмен сообщениями](./development/operations/message-queues.md). --- ## Собрать фронт | № | Документ | Что даёт | |---|---|---| | 1 | [PRINCIPLES](./development/architecture/PRINCIPLES.md) | принципы | | 2 | [BMAP](./development/architecture/BMAP.md) | место фронта в продукте, связь с бэком | | 3 | [BMFP](./development/architecture/BMFP.md) | слои, состояние, контракт, маршруты, стили, оптимизация загрузки | | 4 | [Правила дизайна](./development/design/DESIGN_RULES.md) + [Адаптивность](./development/design/RESPONSIVE.md) | как это должно выглядеть и вести себя на разных экранах | | 5 | [Стиль кода фронта](./development/process/frontend-code-style.md) | именование, вложенность стилей, приёмы разметки | | 6 | [Тестирование](./development/process/testing.md) | что покрывать на каждом слое | | 7 | [Git и репозитории](./development/process/git-and-repositories.md) | версии и история | Если во фронте есть вход и закрытые разделы — [AUTH](./development/architecture/AUTH.md): что хранится в браузере, когда продлевается сессия, почему право проверяется на сервере, а не кнопкой. Форма ответов бэка описана в [BMBP](./development/architecture/BMBP.md) — читается, если контракт ещё не задан. --- ## Собрать шлюз | № | Документ | Что даёт | |---|---|---| | 1 | [BMGP](./development/architecture/BMGP.md) | структура, маршруты, upstream, сквозные правила | | 2 | [BMBP](./development/architecture/BMBP.md), раздел про API-иерархию | какие ручки бэков существуют и чем отличаются | | 3 | [Сетевой контур](./development/operations/network-topology.md) | где шлюз стоит в цепочке и что публикует | --- ## Развернуть систему на сервере Порядок обязателен: каждый следующий документ опирается на состояние, оставленное предыдущим. | № | Документ | Что даёт | |---|---|---| | 1 | [Настройка сервера](./development/operations/server-setup.md) | пользователь, вход по ключу, межсетевой экран, часы, журналы | | 2 | [Docker](./development/operations/docker-install.md) | движок, правила публикации портов, ротация логов | | 3 | [Частная сеть](./development/operations/private-network.md) | обращение между машинами по частным адресам | | 4 | [Сетевой контур](./development/operations/network-topology.md) | как соединены слои, что наружу не смотрит | | 5 | [База данных](./development/operations/database.md) | хранилище, пользователи, схема на сервис, миграции | | 6 | [Секреты](./development/operations/secrets.md) | откуда части системы берут пароли и ключи | | 7 | [Запуск приложения](./development/operations/running-an-application.md) | compose продукта, проверки готовности, ограничения | | 8 | [HTTPS для домена](./development/operations/tls-certificates.md) | домен, сертификат, автопродление | | 9 | [Резервное копирование](./development/operations/backup-and-restore.md) | копии и проверка восстановлением — до первого выката | | 10 | [Релиз и выкат](./development/operations/release-and-deploy.md) | сборка, выкат без простоя, откат | | 11 | [Наблюдение](./development/operations/observability.md) + [Журналы](./development/operations/logs.md) | метрики, пороги, оповещения, сбор записей | Если сервисы общаются событиями, между шагами 7 и 8 добавляется [Обмен сообщениями](./development/operations/message-queues.md): брокер поднимается до потребителей, иначе темы рождаются с настройками по умолчанию. Копии настраиваются **до** первого выката с миграциями: выкат, меняющий схему, без свежей копии не имеет пути назад. --- ## Выпустить новую версию | № | Документ | Что даёт | |---|---|---| | 1 | [Git и репозитории](./development/process/git-and-repositories.md) | чистое зафиксированное состояние, метка версии | | 2 | [Тестирование](./development/process/testing.md) | прогон как условие выпуска | | 3 | [Релиз и выкат](./development/operations/release-and-deploy.md) | сборка артефакта, выкат, откат, миграции | | 4 | [Наблюдение](./development/operations/observability.md) | что смотреть сразу после выката | --- ## Выделить переиспользуемую единицу | № | Документ | Что даёт | |---|---|---| | 1 | [REUSE](./development/architecture/REUSE.md) | когда выделять, топология, подключение с закреплённой версией | | 2 | [BMFP](./development/architecture/BMFP.md), раздел про модули | как устроен фронт-модуль и его публичный контракт | | 3 | [Git и репозитории](./development/process/git-and-repositories.md) | версии: что означает каждая часть номера | | 4 | [Тестирование](./development/process/testing.md) | тесты принадлежат единице, а не потребителю | --- ## Разобраться, почему не работает | Симптом | Куда смотреть | |---|---| | сайт не открывается, ошибка сертификата | [HTTPS для домена](./development/operations/tls-certificates.md), раздел отказов | | `502` или `504` | [Сетевой контур](./development/operations/network-topology.md), проверка по слоям | | сервис доступен снаружи в обход шлюза | [Docker](./development/operations/docker-install.md), публикация портов | | после выката всё сломалось | [Релиз и выкат](./development/operations/release-and-deploy.md), откат | | данные потеряны | [Резервное копирование](./development/operations/backup-and-restore.md), восстановление | | непонятно, где искать причину | [Наблюдение](./development/operations/observability.md), разбор отказа | | нужны записи за прошлый час | [Журналы](./development/operations/logs.md), запросы к хранилищу | | действие выполнилось дважды | [BMBP](./development/architecture/BMBP.md), идемпотентность | | сообщения обрабатываются не по порядку | [Обмен сообщениями](./development/operations/message-queues.md), ключ и порядок | | вход перестал работать, разлогинивает | [AUTH](./development/architecture/AUTH.md), таблица отказов | | машины не видят друг друга по частным адресам | [Частная сеть](./development/operations/private-network.md), таблица отказов | | часть не поднимается или не выходит в готовность | [Запуск приложения](./development/operations/running-an-application.md), где искать причину | | ошибка подключения к базе, исчерпан пул | [База данных](./development/operations/database.md), таблица отказов | | секрет попал в репозиторий | [Секреты](./development/operations/secrets.md), раздел про утечку | | заперся снаружи, потерян доступ к серверу | [Настройка сервера](./development/operations/server-setup.md), откат | --- ## Внести изменение в существующий код | № | Документ | Что даёт | |---|---|---| | 1 | [Работа в кодовой базе](./development/process/rules.md) | с чем сверяться, как вносить правку, что делать при расхождении с архитектурой | | 2 | Спецификация нужного слоя: [BMFP](./development/architecture/BMFP.md), [BMBP](./development/architecture/BMBP.md) или [BMGP](./development/architecture/BMGP.md) | границы, за которые нельзя выходить ради краткости | | 3 | Стиль соответствующей стороны: [фронт](./development/process/frontend-code-style.md) или [бэк](./development/process/backend-code-style.md) | чтобы правка читалась как соседний код | | 4 | [Тестирование](./development/process/testing.md) | что прогнать перед сдачей | | 5 | [Git и репозитории](./development/process/git-and-repositories.md) | одно изменение — один коммит | --- ## Написать документ в библиотеку | № | Документ | Что даёт | |---|---|---| | 1 | [Документ библиотеки](./development/process/writing-a-library-document.md) | критерий готовности, обязательные части | | 2 | [Правила письма](./development/process/writing-rules.md) | язык: точность, нейтральность, чего избегать | Перед публикацией — `./tools/check-leaks.sh`.