Архитектура в репозитории требований

1. Место архитектуры

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

Архитектура — отдельное измерение описания решения; два уровня требований сохраняются. Архитектурный REQ относится ко второму уровню. У него есть HLR-основание, источник принятого решения, затронутые элементы и способ проверки.

Например: HLR требует, чтобы сбой уведомлений не терял ответ. REQ описывает повторы и доступность ответа. Решение выбирает transactional outbox. Архитектура показывает участников и транзакционную границу. REQ-ARC фиксирует обязательство атомарно сохранить публикацию и задачу уведомления. Проверка с отказом перед/после commit подтверждает это обязательство.

Архитектурный выбор не следует автоматически из HLR: одной цели могут соответствовать несколько решений. Поэтому связь «обосновано требованием» отличается от «уточняет требование». Если выбор ухудшает внешнюю гарантию, меняется и исходная спецификация после согласования.

2. Структура и форма

Архитектура редактируется непосредственно в Markdown:

architecture/
  README.md       # маршрут чтения, вопросы и применимость представлений
  catalog.md      # единственные определения элементов/связей/владельцев
  technology-stack.md # входящие/выбранные технологии, версии и применимость
  context.md
  structure.md
  runtime.md
  data.md
  deployment.md
  quality.md
  concepts.md
docs/decisions.md
openspec/specs/architecture/spec.md

В небольшом проекте несколько вопросов можно рассмотреть в одном документе. Не требуется создавать все файлы ради полноты дерева. Технические решения — DEC-ARCH-* в общем Markdown-реестре; причины, альтернативы и последствия пишутся свободно. Существенные обязательства разработки — обычные REQ второго уровня.

Каталог с контрольными таблицами нужен, когда выбранные инварианты регулярно проверяются скриптами. В примере автоматизация касается ссылок, владельцев/доступов и связи нормативных ограничений с решениями/проверками. Она включается architecture_required=true в профиле. Стартовый шаблон этого не требует. Runtime, deployment и обоснование качеств проверяются агентом; для них не нужна пара JSON→generated MD.

Файл design.md изменения содержит дельту и ссылки на текущую архитектуру. После завершения он сохраняется в архиве; текущий проект читается из architecture/.

3. Шесть представлений

Каждое представление отвечает на свой вопрос. «Обязательное» означает, что вопрос рассмотрен; объём представления зависит от сложности и риска.

Контекст и состав нужны практически всегда. Владение данными обязательно при хранении/обмене данными. Взаимодействия выбираются для сложных, рискованных и повторяющихся механизмов. Развёртывание нужно для оценки эксплуатационных гарантий; неизвестная промышленная среда явно обозначается открытым вопросом (в примере Q-ARCH-001). Представление качеств нужно для архитектурно значимых NFR и сквозных гарантий.

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

Процесс деятельности заявителя и ведомства относится к требованиям/предметной модели. Runtime-представление распределяет шаги этого процесса между выбранными программными частями. Они могут ссылаться друг на друга, но не должны содержать два независимых описания бизнес-правил.

4. Правила против дублирования

Один факт — один канонический источник. Один элемент — один стабильный ID. Представление — проекция известных фактов и добавление собственного типа фактов.

Диаграммы могут повторять элемент, чтобы оставаться читаемыми. Это допустимое визуальное повторение: имя и определение берутся из общего каталога; агент проверяет согласованность изображений с этим источником. Опасно повторять независимо редактируемое определение элемента или гарантии.

Context показывает границу системы, structure — состав и выбранную детализацию. Runtime объясняет выбранные взаимодействия со ссылками на элементы/связи каталога. Deployment добавляет размещение экземпляров. Data объясняет границу доступа и ссылается на владельцев из каталога. Quality связывает требование, решение, механизм и проверку. Диаграммы и смысловое соответствие проверяет агент.

Обзор продукта содержит ссылку на контекстное представление вместо второй вручную поддерживаемой схемы. Новое изображение существующей схемы допустимо как производный файл, а не второй источник.

5. Какие взаимодействия выбрать для системы обратной связи

Минимальный набор:

1. Регистрация с повторной отправкой: идемпотентность и фиксация исходных данных.
2. Направление в несколько ведомств и переназначение: владелец состояния, версии и устаревшие ответы.
3. Публикация и уведомление: полнота комплекта, атомарная фиксация, внешний отказ и восстановление.
4. Построение аналитической проекции: источник фактов, временной срез и граница доступа.

В заполненном примере подробно показаны три структурно отличающихся механизма: регистрация, публикация с outbox и построение проекции. Fan-out/переназначение уже описаны предметной моделью и приёмочными сценариями; отдельная runtime-детализация добавляется при выборе существенного межсервисного или конкурентного механизма.

Не нужно рисовать runtime-схему для каждого SCN. Несколько SCN могут проверять один механизм, а один SCN — проходить через несколько механизмов. Их связи также многие-ко-многим.

6. Архитектурные обязательства для разработки

В нормативные REQ переводятся те принятые решения, нарушение которых создаёт существенный риск или ломает согласованную архитектуру: транзакционная граница, запрещённая зависимость, доступ к данным, обязательный интерфейс, граница изоляции, правило версионирования.

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

Для архитектурного REQ указать:

• основание HLR и связанные функциональные/качественные REQ;
• принятое решение DEC-ARCH-* в sources;
• точное обязательство и область применения;
• затронутые элементы каталога;
• исключения и способ их согласования;
• метод проверки реализации, данные и доказательства.

Примеры методов: тест с отказом перед/после commit; анализ зависимостей кода; контрактный тест; инспекция IAM/SQL-grants; проверка конфигурации среды; испытание восстановления. Проверка модели архитектуры подтверждает согласованность проекта, но не соответствие кода и не достижение NFR.

Если внутреннее требование модуля становится достаточно подробным для отдельного проекта, оно хранится в репозитории этого модуля с ссылкой на версию родительского архитектурного обязательства. В данном профиле HLR↔REQ остаётся основной связью; дополнительные источники и архитектурные allocations задают распределение по частям.

7. Связи и протяжка

HLR / REQ / внешние ограничения
        ↕ обоснование и обратная связь
Решения DEC-ARCH-* ↔ каталог и механизмы
        ↕ распределение и обязательства
Архитектурные REQ ↔ части системы
        ↕ конкретные проверки и случаи
Реализация / конфигурация / результаты

Это набор типизированных связей многие-ко-многим. У распределения есть accountable — основной ответственный элемент и supporting — участвующие элементы. Это ответственность проекта, не заявление о доказанном выполнении. Для сквозного обязательства accountable может быть системой или единицей исполнения; локальное обязательство закрепляется за модулем. Внешний участник не отвечает за выполнение внутреннего требования реализации.

Изменение NFR требует пересмотра механизмов, размещения и доказательств. Изменение части — её распределённых REQ, контрактов, владельцев данных и runtime-потоков. Изменение решения — нормативных обязательств, использующих его как источник. Архитектура и новые зависимости включаются в тот же MR.

В профиле v2 выбранные каталоговые ID используются для прямых зависимостей REQ↔элементы и элемент→связи. Runtime, размещение и механизмы агент пересматривает по авторской матрице влияния; полноценное влияние модели скриптом не вычисляется. Вопросы о непрямом влиянии и достаточности решений остаются предметом ревью.

8. Готовность архитектуры

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

Перед промышленным запуском: подтверждена целевая среда, границы отказа/доверия, ресурсы, восстановление и эксплуатационные процедуры; выполнены проверки соответствия реализации. Тестовая среда не заменяет промышленное представление.

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

9. Практики, использованные в предложении

• C4: набор диаграмм — контекст, состав и детализация по необходимости.
• C4: контейнерная диаграмма — единицы приложения/данных; параметры развёртывания вынесены отдельно. «Контейнер» C4 не означает обязательно Docker.
• C4: динамическая диаграмма — выбранные существенные взаимодействия вместо схемы каждого сценария.
• C4: развёртывание — экземпляры и среды.
• arc42: сквозные концепции — общие механизмы описываются централизованно, с явной применимостью.

Это профиль репозитория, использующий перечисленные идеи. Он не требует заполнения всех разделов arc42 или всех уровней C4.

Автоматизация по риску

Не следует формализовывать все представления только ради генерации диаграмм. Каталоговые проверки оправданы для выбранных запретов, частых изменений и высокой цены ошибки. Агентское ревью отвечает за транзакционные/асинхронные границы, конкурентные ветки, компромиссы и достаточность эксплуатационных решений. Матрица выбора всех артефактов: ARTIFACTS.md.

Технологический стек как входное условие

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

Базис хранится в architecture/technology-stack.md и является единственным источником разрешённых технологий и правил версий. Это дополнительный архитектурный артефакт, а не седьмое представление и не новый уровень требований. Состав связывает части с TECH-ID, deployment задаёт размещение, DEC объясняет применение/последствия, архитектурный REQ закрепляет обязательность и способ проверки. Спецификация ссылается на базис без копирования перечня версий.

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

При изменении базиса пересматриваются REQ, решения, состав, развёртывание, механизмы качеств и проверки. Проверка должна различать разрешённый состав, несогласованную замену и незакреплённую сборку. Markdown проверяет агент/архитектор; постоянную автоматизацию сравнения состава вводят, когда есть регулярный потребитель и значимый риск ошибки.

Архитектурное ограничение может опираться на рабочий DEC со статусом working, принятый к реализации и связанный с открытым вопросом. Каталоговые проверки принимают такой источник наравне с accepted; блокировки вопроса проверяются независимо. Область применения, риск и условие пересмотра рабочего решения остаются явными.