Перейти к основному содержимому

ADR 0213 — Результат работает на машине пользователя через compose от Infra

Статус​

Accepted. 2026-10-11 (AT-517; решения владельца от 11.10: "pelo compose da Infra", без опубликованного порта в broker). Правила в RN-851..855. Ссылается, не редактируя, на ADR 0130, ADR 0190 и ADR 0199.

Контекст​

В конце выполнения у пользователя был смёрженный код и ни одного объявленного способа увидеть его работающим. Что было измерено:

  • docker-compose.yml, который Infra открывала в PR, был "для разработки": поднимал окружение, а не ПРИЛОЖЕНИЕ, и prompt Infra Lead говорил, что контейнер проекта им не поднимается.
  • Образ, решённый в artifact.project_image, не доходил до Infra, когда она писала compose, поэтому FROM Dockerfile модуля был догадкой.
  • Порт приложения по умолчанию (3000) конфликтует с портом Brabo на той же машине.
  • В контейнере проекта нет Docker (сдерживание ADR 0130), поэтому ничто внутри Brabo не может выполнить docker compose up, чтобы доказать compose.
  • Маршруты результата уже документируются dev в README (RN-850), а QA уже поднимает процессы в фоне и завершает группу (RN-817), но ничто не связывало URL с тем, что открывает пользователь.

Решение​

  1. Путь — compose от Infra, запускаемый пользователем в поставленном репозитории. Broker НЕ публикует порт: сдерживание ADR 0130 остаётся нетронутым.
  2. Compose поднимает ПРИЛОЖЕНИЕ (RN-851): build Dockerfile модуля с FROM, равным образу из artifact.project_image, порт хоста ${APP_PORT:-8080}:<porta interna> (8080 свободен рядом с портами Brabo: 3000, 4000, 5173, 5432, 7474, 7687, 8088, 11434), том для постоянных данных и env_file с закоммиченным .env.example — никогда .env.
  3. Infra пишет раздел README "Rodar na sua máquina" в своей PR. Dev продолжает с "Rotas HTTP" (RN-850) и добавляет URL Swagger или страницы, когда их создаёт.
  4. propose_infra_pr получает ОБЯЗАТЕЛЬНОЕ поле run, проверяемое в engine и в api:
    • command: непустая строка, до 300 символов (напр.: cp .env.example .env && docker compose up --build);
    • urls: от 1 до 5 элементов { label, url, kind }, label до 60 символов, kind ∈ api_docs | web, url, начинающийся с http://localhost: или http://127.0.0.1:;
    • envExample: boolean — когда true, .env.example находится среди files PR.
  5. api выдаёт artifact.run_instructions (RN-852) при успешном выполнении open_infra_pr: версионируемый, без таблицы, действующий заменяет — конструкция artifact.project_image, — payload { command, urls, envExample, prUrl }, читаемый через GET /projects/:projectId/infra-artifacts (или отдельный GET, если тот не подойдёт).
  6. Dev открывает то, что можно открыть (RN-853), не привязываясь к стеку: HTTP-модуль отдаёт /openapi.json (OpenAPI 3) и /docs (UI Swagger); при сети none или без пакета /docs — это HTML-страница, загружающая swagger-ui из CDN, — скачивает браузер пользователя, а не контейнер. Web-модуль отдаёт начальную страницу. Клаузула входит, только когда задача касается entrypoint или маршрутов.
  7. QA доказывает ВНУТРИ контейнера (RN-854): поднимает приложение командой из README в фоне, обращается к localhost:<porta interna>/openapi.json и /docs (curl, wget или node -e fetch) и завершает группу процессов (RN-817). Реальный docker compose up — НАБЛЮДЕНИЕ ("provado só na máquina do usuário"), никогда пункт плана.
  8. Visão geral получает карточку "Rodar na sua máquina" (RN-855): команда с кнопкой копирования и кликабельные URL, с текстом "declarado pela Infra, não verificado na sua máquina" (RN-468) — никогда зелёный.

Последствия​

  • Стоимость в токенах: payload run, раздел README и клаузула dev и QA — дополнительный текст в уже существовавших ходах; ни одного нового хода.
  • Объявленный пробел: реальный docker compose up никогда не выполняется внутри Brabo. То, что доказывает QA, — приложение, отвечающее внутри контейнера; порт хоста, том и сборка через compose доказываются только на машине пользователя, и экран это говорит.
  • Что НЕ меняется: сдерживание ADR 0130 и broker (без опубликованного порта, без сокета в контейнере, сеть internal), автоматический подъём ADR 0190 и ресурсы, выводимые из module_map ADR 0199. Свидетельство того, что точка входа поднимается (RN-813), и HTTP-маршрут в README (RN-846) продолжают действовать; этот ADR добавляет URL, который открывается, а не заменяет доказательство.

Рассмотренные альтернативы​

  • Порт, опубликованный broker, чтобы пользователь открывал приложение из контейнера проекта. Отвергнуто решением владельца: это открыло бы первый порт контейнера проекта на хост и изменило бы сдерживание ADR 0130.
  • Экран читает README или compose из репозитория, чтобы собрать карточку. Отвергнуто: это был бы разбор прозы и YAML на клиенте, без контракта; проверенный payload run и версионируемый артефакт дают те же данные в фиксированной форме.