docs: make documentation checks self-contained

2026-09-15 20:45:40 +03:00
parent c557af4ea5
commit 97069d6f6d
25 changed files with 125 additions and 112 deletions
@@ -8,6 +8,15 @@ Backend генерирует OpenAPI из собственного публич
 схемы находятся вне frontend. Это разделение принято в
 [ADR 002](../adr/002-nest-generated-openapi-contract.md) и
 [ADR 014](../adr/014-trusted-openapi-input.md).
+
+Backend командой `npm run openapi:generate` создаёт `openapi.json` без запуска
+сервера и не хранит результат в Git. Contract test сравнивает вывод генератора
+с Nest runtime schema настроенного приложения. Frontend хранит полученный
+artifact у себя и проверяет соответствие generated types этой копии. CI не
+скачивает соседние репозитории и не сравнивает их текущие revisions. Обновление
+входного artifact потребителя выполняется отдельно с review; совместимость
+развёрнутых версий не доказывается одним зелёным локальным CI.
+
 API имеет prefix `/api/v1`; Swagger публикуется для локальной разработки по
 environment policy, а не используется frontend в runtime.

@@ -36,7 +45,7 @@ message/stack. Типичный ответ:
 HTTP-ответа после всех стадий обработки запроса.

 **Известное расхождение:** согласованная
-[спецификация аутентификации](../../specs/openspec/specs/user-authentication/spec.md#requirement-стандартные-ответы-об-ошибках)
+[спецификация аутентификации](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/user-authentication/spec.md#requirement-стандартные-ответы-об-ошибках)
 требует `pointer` и `detail` для невалидных полей. В текущей конфигурации
 валидация формирует строковые сообщения, а фильтр ожидает структурированные
 ошибки полей; поэтому корректность деталей `errors` не подтверждена.
@@ -74,5 +83,5 @@ client request ID. Это позволяет сопоставить публич
 Выбор logger и граница ответственности описаны в
 [ADR 008](../adr/008-pino-backend-logging.md); согласованное поведение — в
 workspace-спецификации
-[Structured logging](../../specs/openspec/specs/backend-structured-logging/spec.md).
+[Structured logging](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/backend-structured-logging/spec.md).
 Сборщик, срок хранения журналов и alerting не определяются приложением.