10a. Markdown-документы

Описание (Глава 10) — это флавор-markdown, прикреплённый к объявлению. Файл .md — это тот же флавор-markdown, стоящий сам по себе: нативный архитектурный документ, а не непрозрачное вложение. Он рендерится тем же диалектом: перекрёстные ссылки [[…]], ссылки на аспекты, ссылки на разделы, геттеры чужих значений и обратные ссылки, которые вы уже знаете из описаний, — поверх того же резолвера из core. Документ дизайна, рунбук, гайд по онбордингу, ADR — напишите его в .md, положите в рабочее пространство, и он связывается прямо с моделью.

# Payments Platform

The [[Payments]] service authorizes and captures card payments. It runs in
[[@@security-zone:pci]] and publishes events consumed by [[Orders]] and
[[Notifications]]. On-call rotation is owned by [[#pay001]]@@team.

See [[Payments#compliance]] for the PCI scope.

Каждая [[…]] здесь — живая ссылка в каноническую модель: [[Payments]] разрешается в модуль, [[@@security-zone:pci]] — в оверлей аспекта, [[#pay001]]@@team читает аспект team с узла, на который ссылается, а [[Payments#compliance]] прыгает к разделу.

Жёсткое ограничение: .md не может создавать модель

Правило. Markdown-документ ссылается на существующую модель и рендерит её; он никогда её не определяет. Файлы .arch остаются единственным источником истины.

Это та черта, что не даёт документации тихо стать вторым, противоречивым источником архитектуры. .md может указывать на [[Payments]], встраивать сниппет, цитировать аспект — но он не может вызвать модуль Payments к существованию, задать на нём поле или провести ребро. Если этого нет в файле .arch, оно не каноническое. Markdown — это линза на модель, никогда не сама модель.

Два способа участия документа

Двунаправленное связывание. Документ ссылается на элементы модели через [[…]], а элемент .arch (или его описание) может сослаться обратно наружу на документ — и на #раздел внутри него:

service Payments {
    docs.design: "platform-overview.md"
    "Full design rationale in [[platform-overview]]; PCI details in
    [[platform-overview#compliance]]."
}

Индекс обратных ссылок («упоминается в», ниже) охватывает обе поверхности, так что вы можете перемещаться .arch → .md и .md → .arch с любой стороны.

Встроенные самодостаточные сниппеты. Огороженный блок ```arch держит одноразовую черновую диаграмму — собственную независимую, самодостаточную модель, которая не является частью канонической модели рабочего пространства:

Here's the shape we're proposing:

```arch
service Gateway {
    > Payments
    > Orders
}
```

Этот сниппет рендерится живьём — настоящая диаграмма, а не скриншот, — но не определяет ничего канонического, так что жёсткое ограничение по-прежнему держится. Он идеален для RFC или документа дизайна, где вы хотите набросать идею, не трогая реальное рабочее пространство. (Встраивание живой проекции реальной модели в документ пока недоступно — оно зависит от зрелости проекций. Самодостаточный сниппет, будучи независимым от канонической модели, — это поддерживаемая встроенная форма.)

Диалект флавор-markdown

Файлы .md используют ровно тот диалект из Главы 10 — то же подмножество CommonMark плюс расширения archlang [[…]]:

Форма	Ссылается на
[[#id]] / [[Name]]	объявление (по стабильному идентификатору или имени)
[[@@key]] / [[@@key:value]]	плоскость аспекта или конкретное место на ней
[[Doc#section]]	заголовок # внутри документа .md
[[ref]]@@aspectPath	значение аспекта, прочитанное с того узла, на который ссылаются

Одна форма ведёт себя в документе иначе, чем в описании:

Правило. Интерполяция голым @@aspectPath — только для описаний. У отдельного .md нет владеющего узла, поэтому голый @@ в документе — это ошибка. Чтобы прочитать аспект внутри документа, используйте явную форму [[ref]]@@aspectPath, которая поставляет собственный контекст, — это единственная интерполяция, доступная в .md.

Так что описание на Payments может написать @@team, но platform-overview.md должен написать [[Payments]]@@team. Скомпонованная форма (перекрёстная ссылка плюс геттер значения) — это один механизм, построенный из двух уже имеющихся у вас кусочков, а не новый синтаксис, — и работает он везде, включая обратно в описаниях.

Обратные ссылки («упоминается в»)

Каждый элемент ведёт автоматический обратный индекс всех ссылок [[…]], указывающих на него, — и в описаниях, и в документах .md. Откройте Payments, и инструменты покажут все места, где о нём говорится, — документ дизайна, рунбук, описание другого сервиса, — так что вы переходите от объявления ко всему его разговору без grep.

Область разрешения

Голые имена документа ([[Payments]]) разрешаются относительно пакета/пространства, как и любая ссылка. Область берётся из фронтматтера .md, когда он есть, с откатом на расположение файла в дереве рабочего пространства. Ссылки по стабильному идентификатору ([[#id]]) разрешаются независимо от области.

Итоги

• Файлы .md — первоклассная поверхность архпространства, рендерятся тем же флавор-markdown, что и описания.
• Документ ссылается на модель и рендерит её — он никогда не создаёт каноническую модель; .arch остаётся источником истины.
• Он участвует двумя способами: двунаправленное связывание [[…]] (.arch ↔ .md, включая #раздел) и встроенные самодостаточные сниппеты ```arch (одноразовые, неканонические, рендерятся живьём).
• Голый @@aspectPath — только для описаний; в документе используйте явный геттер [[ref]]@@aspectPath.
• Обратные ссылки охватывают обе поверхности, так что «упоминается в» достаёт и описания, и документы.

Что дальше

Глава 11: Стандартная библиотека → — от базовых типов к service, command, event и остальной лексике стандартной библиотеки.