Перейти к содержанию

Корпоративные архитектурные и инфраструктурные стандарты

Этот репозиторий содержит единый версионируемый набор корпоративных требований к архитектуре приложений, доставке, развёртыванию и эксплуатации. Требования оформляются как однозначные и проверяемые контракты прежде всего для ИИ-агентов, а также для разработчиков, архитекторов и platform-команд.

Основной контекст применения — сервис-ориентированные и микросервисные системы, включающие frontend, backend, нативные приложения iOS и Android, фоновые процессы, хранилища данных и интеграции. Требования применимы и к другим архитектурным стилям в той части, где это явно указано.

Источник правды

Корпоративный self-hosted GitLab — единственный источник правды для кода, требований и истории решений.

Действующим считается содержимое защищённой ветки репозитория в GitLab. Для воспроизводимой разработки и аудита проект должен фиксировать точную версию стандартов: релизный Git-тег и соответствующий commit SHA. Ссылка только на ветку main недостаточна, потому что её содержимое меняется.

Локальные копии, документационные сайты, артефакты CI, поисковые индексы, чаты и ответы ИИ являются производными источниками. При расхождении приоритет имеет зафиксированное содержимое GitLab.

Все изменения стандартов и проектных решений проходят через GitLab merge request. Значимые обсуждения и согласования должны оставаться воспроизводимыми в GitLab, а не только во внешней переписке.

Правила подготовки изменений находятся в CONTRIBUTING.md. Содержимое репозитория распространяется по условиям MIT License.

Что регулирует репозиторий

Здесь размещаются повторно применимые требования к:

  • границам и взаимодействию сервисов;
  • frontend- и backend-компонентам;
  • нативным приложениям iOS и Android;
  • API, событиям и интеграционным контрактам;
  • владению данными и согласованности;
  • безопасности и управлению секретами;
  • обработке ошибок и устойчивости;
  • наблюдаемости;
  • тестированию и поставке изменений;
  • эксплуатации сервисов;
  • Kubernetes и Docker Compose runtime;
  • delivery, GitOps и конфигурации целей;
  • платформенным сервисам, backup и восстановлению;
  • работе ИИ-агентов с проектами.

Здесь не размещаются бизнес-требования, исходный код, схема данных, API-контракты и архитектура конкретной системы. Они должны находиться в соответствующем проекте в GitLab.

Нормативные слои

Архитектурный слой в docs/architecture/ определяет наблюдаемое поведение приложения, контракты данных и интеграций, release-инварианты и пользовательские SLI/SLO. Инфраструктурный слой в docs/infrastructure/ определяет реализацию этих контрактов в deployment, runtime и платформе.

Governance-слой в docs/governance/ содержит правила авторинга и общие контракты manifest и границ; только DOC-CLR относится к сопровождению самого репозитория и не включается в применимость прикладного проекта.

Зависимость направлена только от инфраструктуры к архитектуре. Ссылка architecture:<ID> разрешается в том же зафиксированном commit объединённого репозитория; отдельный межрепозиторный lock не используется. Изменение обоих слоёв поставляется одним merge request и одним release. Точные правила определены в границах слоёв.

Технологические profiles в profiles/technologies/ являются ненормативными индексами: они связывают документы обоих слоёв, но не создают третьего источника требований. PostgreSQL, Valkey и object storage используют общие архитектурные контракты состояния, TLS, backup и SLO; отдельный технологический архитектурный документ нужен только для дополнительной наблюдаемой гарантии приложения.

Действующие документы

Архитектура компонентов:

Backend:

Frontend (профили CSR, SSR, SSG и edge):

Mobile (нативный профиль — SwiftUI для iOS и Jetpack Compose для Android):

Общие требования для backend, frontend и mobile:

Применение стандартов:

catalog/requirements.json является производным результатом scripts/standards.py catalog, но хранится в Git намеренно: consumer может получить полный машинный каталог из зафиксированного checkout без генерации и сетевого доступа. Проверка репозитория сравнивает committed-файл с повторно сгенерированным представлением и отклоняет stale-версию.

Разработка и проверка:

Публикуемые компоненты:

Ненормативные справочные материалы:

Разработка стандартов:

Запуск проектов:

Развёртывание:

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

Интеграции:

Данные:

Эксплуатация:

Инфраструктурный слой:

Как применять стандарты

Быстрый старт

Для нового или существующего проекта:

  1. получите checkout release-тега стандартов и зафиксируйте его полный commit SHA;
  2. установите минимальные зависимости CLI из requirements-cli.lock;
  3. создайте .standards/standards.yaml командой init --from-checkout;
  4. выполните единую проверку check;
  5. получите индекс применимых требований через context --depth index, прочитайте относящиеся к задаче нормы и добавьте проверку проекта в CI.

Развёртывание сайта через Docker Compose

Корневой docker-compose.yml запускает опубликованный образ документации с read-only filesystem, healthcheck, ограничениями ресурсов и процессов, сброшенными Linux capabilities и ротацией локальных логов. Конфигурация рассчитана на single-host production по INF-CMP: владелец host, мониторинг, backup конфигурации и recovery runbook обеспечиваются отдельно.

Скопируйте .env.example в .env и замените STANDARDS_IMAGE на immutable-ссылку registry/repository@sha256:<digest> из успешного publish pipeline. Затем выполните:

docker compose config --quiet
docker compose pull
docker compose up --detach --wait

По умолчанию сайт слушает только 127.0.0.1:8080. Production TLS и внешний доступ должны предоставляться управляемым reverse proxy на host. Публикация на другом адресе требует явного изменения STANDARDS_BIND_ADDRESS и соответствующих firewall-правил. Остановка без удаления данных:

docker compose down

Пошаговые команды, пример manifest, интерпретация результата и сценарий обновления версии приведены в практическом руководстве.

Проект должен явно определить:

  1. версию стандартов: Git-тег и commit SHA;
  2. фактические компоненты, возможности и их роли;
  3. локальные архитектурные решения;
  4. согласованные отклонения от стандартов.

Эти данные должны храниться в .standards/standards.yaml по требованиям manifest применимости. Структура проверяется по JSON Schema. Применимые документы вычисляются по каталогу применимости.

Применимость и соразмерность

Требование применяется только при одновременном выполнении его области и условий применения. Само наличие документа в репозитории не делает все его требования обязательными для каждого проекта. Например, требования к GraphQL, webhook, mobile offline-режиму или публичному SDK не применяются к проекту, в котором соответствующей возможности нет.

Проект должен объявлять только фактически используемые компоненты, возможности и роли; каталог вычисляет из них минимальный перечень документов. Неприменимость требования не является исключением и не требует ADR. Добавление возможности «на будущее» не требуется.

Способ проверки из требования задаёт допустимые способы подтвердить результат, но не обязывает выполнять каждый перечисленный пункт для каждого изменения. Достаточно минимального набора проверок, который непосредственно подтверждает изменённое свойство. Отдельный отчёт, таблица, матрица или ручное согласование требуются только тогда, когда это прямо установлено формулировкой требования.

Практическая проверка

Для потребительских команд init, validate, verify-version, explain, audit, check и context достаточно Python 3.10+, Git и минимального lock-файла:

python3 -m venv .venv
.venv/bin/python -m pip install \
  --only-binary=:all: \
  --require-hashes \
  -r requirements-cli.lock

Из checkout зафиксированной версии стандартов команда python3 scripts/standards.py validate MANIFEST --project-root PROJECT_ROOT проверяет manifest, ссылки и вычисленную применимость. Подкоманда explain показывает документы и причины их подключения, а audit обнаруживает поддерживаемые формальные признаки возможностей, не объявленных в manifest.

verify-version локально подтверждает, что чистый checkout стандартов, release-тег и commit_sha manifest обозначают одно содержимое. check последовательно выполняет validate, verify-version и audit; код 2 означает обнаруженный необъявленный признак архитектуры.

context --depth index выдаёт компактный машинно-читаемый индекс ID, уровней, областей применения, причин подключения и согласованных исключений. context --depth full дополнительно включает точный текст применимых нормативных документов. Повторяемый параметр --requirement ID ограничивает результат выбранными применимыми требованиями. Команда включает только метаданные исключения, но не основной текст ADR, контракты или код прикладного проекта: агент получает их отдельно после проверки класса данных.

Потребительские команды не обращаются в GitLab и не заменяют проверки прикладного поведения. Полная локальная проверка самого репозитория требует Python 3.14 и requirements-docs.lock и выполняется scripts/check-docs.sh; воспроизводимая сборка сайта вместе с этой проверкой — docker build --target build .. На Linux x86-64 и ARM64 скрипт использует проверенный vendored mado v0.3.1, если mado отсутствует в PATH. На других операционных системах mado должен быть установлен отдельно. Процедура обновления mado фиксирует проверку upstream assets, SHA-256 и обеих архитектур. Производное дерево источников MkDocs создаётся импортируемым модулем scripts/stage_docs.py; README остаётся источником его главной страницы.

Для SHOULD и SHOULD NOT достаточно зафиксировать причину отклонения в merge request или ADR проекта. ADR обязателен только когда его прямо требует конкретная норма или отклонение затрагивает security-границу, публичный контракт, целостность данных либо возможность восстановления.

Приоритет требований

Если источники не противоречат друг другу, они применяются совместно. При конфликте используется следующий порядок:

  1. применимое законодательство и обязательные корпоративные политики;
  2. зафиксированная версия этого стандарта с явно согласованными исключениями;
  3. утверждённые требования, контракты и ADR проекта;
  4. текст задачи;
  5. предположения участника или ИИ-агента.

ADR может оформить осознанное исключение из стандарта, но не может незаметно изменить его. Для исключения должны быть указаны нарушаемое требование, причины, риски, компенсирующие меры, владелец, срок действия и условия пересмотра.

Если выполнить требования одновременно невозможно, участник или ИИ-агент должен остановить затронутую часть работы, зафиксировать противоречие и запросить решение. Самостоятельно выбирать удобное толкование нельзя.

Контракт для ИИ-агента, применяющего стандарты

При использовании ИИ-агента проект объявляет возможность ai-assisted-development. Нормативные обязанности проекта, агента и человека, принимающего существенный риск, определены требованиями AI-DEV-001–AI-DEV-008 и AI-DEV-010–AI-DEV-011.

Инструкции для агентов, изменяющих сам репозиторий стандартов, находятся в AGENTS.md и не заменяют точку входа прикладного проекта.

Ненормативные контрольные вопросы

Этот список помогает начать архитектурный review, но не вводит обязанностей. Обязательства определяются только применимыми требованиями с ID.

  • Ясно ли назначение компонента и оправдано ли его отдельное создание?
  • Определены ли источник данных, модель согласованности, миграция и восстановление?
  • Зафиксированы ли контракты, тайм-ауты, повторы, идемпотентность и поведение при частичном отказе?
  • Проведены ли границы доверия, защита секретов и проверка доступа?
  • Ограничены ли ресурсы и предусмотрены ли запуск, завершение, проверка состояния и безопасная поставка?
  • Связаны ли логи, трассы, метрики и ошибки общими идентификаторами без утечки защищаемых данных?
  • Позволяют ли проверки связать исходный commit с выпущенным артефактом и подтвердить изменённый риск?

Как писать нормативные требования

Нормативные документы используют ключевые слова:

Уровень Значение
MUST / MUST NOT обязательное требование / запрет
SHOULD / SHOULD NOT правило, отклонение от которого требует обоснования
MAY допустимый вариант

Слова «желательно», «обычно» и «по возможности» не используются вместо уровня обязательности.

Каждое нормативное требование должно содержать:

  • стабильный уникальный ID, не зависящий от номера раздела;
  • однозначный заголовок и формулировку;
  • уровень обязательности;
  • область и условия применения;
  • обоснование;
  • способ объективной проверки;
  • исключения или явное указание, что они определяются через ADR.

Опубликованный ID нельзя повторно использовать для другого требования. Изменение смысла, обязательности или области применения считается нормативным изменением и должно быть явно отражено в истории версий.

Развитие стандартов

Нормативные изменения явно перечисляются в ненормативной истории изменений.

Версии release-тегов интерпретируются по Semantic Versioning:

  • PATCH — редакционное исправление без изменения смысла;
  • MINOR — обратно совместимое дополнение;
  • MAJOR — новое обязательство или несовместимое изменение.

Обязательный рабочий процесс ИИ-агента, изменяющего этот репозиторий, включая готовность изменения к merge, commit, тегирование main и push, определён только в AGENTS.md.