Как участвовать в mock-services

Оглавление

• Как участвовать в mock-services
• Чем можно помочь
• Правила для кода
• Как добавить нового провайдера (адаптер)
• Гайды интеграции: шаблон
• Процесс
• Обновление базового образа (security patches)
• Лицензия вкладов

Спасибо за интерес! Проект — моки банков и облачных касс по их официальным протоколам. Цель — дать интегратору рабочий, честный и объясняющий ошибки стенд до договора с провайдером.

Если вы ИИ-агент (Arena Agent Mode, Claude Code и т.п.), начните с AGENTS.md: там обязательные прогоны, требования к шапкам, правилу «env в пяти местах» и к описанию PR. Планирование доработок и статусы задач — внутренний бриф проекта[^brief], подготовка к глубокому аудиту — внутренний пакет подготовки к аудиту[^audit-prep]. Документы лежат в закрытом репозитории команды mock-services-docs и в публичной документации не дублируются.

Чем можно помочь

Тип вклада	Как
Дефект мока	Issue с шаблоном «дефект мока»: что сделали, что ожидали, что получили, версия/коммит, curl-воспроизведение
Расхождение с протоколом провайдера	Issue с шаблоном «расхождение с протоколом»: ссылка на официальный раздел доки (или скриншот с датой), поле, ожидаемое поведение
Новый провайдер	Issue-предложение: название, публичная документация API, есть ли у вас доступ к тестовому контуру
Код	PR по правилам ниже
Документация	PR в docs/integration/*; конспекты провайдеров — в приватном mock-services-docs (доступ у мейнтейнеров)

Правила для кода

1. Zero dependencies. Ядро и адаптеры работают на одном Node (>= 18) без npm-пакетов. Новые зависимости обсуждаются отдельно и почти всегда отклоняются.
2. Фиделити важнее удобства. Если провайдер отклоняет запрос — мок тоже отклоняет, с тем же (или документированным) кодом. «Удобные» отступления допустимы только за флагом конфигурации и с пометкой в README.
3. Ошибка = DX. Любой отказ: код + человекочитаемое объяснение + поле + подсказка + ссылка на официальный раздел доки (core.createErrorCatalog). Голые 400/500 без объяснения не принимаются.
4. Тесты обязательны. npm test должен быть зелёным; на новый сценарий — новый пункт в selftest соответствующего сервиса; на дефект — регресс-тест.
5. Тесты не должны быть флаки. Не опирайтесь на sleep, если можно дождаться события/состояния; используйте свободные порты (:0).
6. Секреты и реальные данные запрещены. Только фейковые креды и тестовые карты; персональные данные покупателей в примерах не использовать.
7. Стиль: 2 пробела, одинарные кавычки, 'use strict';, модули CommonJS; комментарии — по делу, на русском с английскими терминами (как в репозитории).

Как добавить нового провайдера (адаптер)

1. Создайте services/<provider>-mock/server.js на packages/core (образец — services/tbank-mock, services/kassa-mock).

2. Опишите в адаптере только протокол: маршруты, поля, коды ошибок, машину состояний, тестовые реквизиты. Инфраструктура — из ядра.

3. Заведите конспект провайдера в приватном репозитории mock-services-docs (каталог <provider>/ — как у существующих адаптеров, например конспект Т-Банка): таблица «эндпоинт → официальный раздел доки → дата сверки → статус сверки». Пример заголовка конспекта:

   # MyBank · Payment API — сверка с моком
   
   | Эндпоинт мока | Официальный раздел доки | Дата сверки | Статус |
   |---|---|---|---|
   | `POST /v2/Init` | https://developer.mybank.example/api/init | 2026-10-11 | сверено |

   Относительные ссылки между доками проверяются автоматически (npm run check:links входит в npm test) — битые ссылки CI не пропустит.

4. Напишите services/<provider>-mock/selftest.js со всеми сценариями контракта (успех, отказ, таймаут, дубли, отмена/возврат — по специфике провайдера).

5. Добавьте инструкцию «интеграция за 10 минут» в docs/integration/<provider>.md по шаблону ниже (минимальный набор разделов проверяет npm run check:site) и запись в таблицу README.

6. Внесите новый документ в навигацию сайта — _sidebar.md (и, если он описывает провайдера, в таблицу карты документации). Полноту навигации, слаги ссылок и самодостаточность сайта проверяет npm run check:site — он также входит в npm test.

Гайды интеграции: шаблон

Гайд docs/integration/<provider>.md — «интеграция за 10 минут»: от запуска стенда до первого успешного платежа или чека. Шаблон один для всех адаптеров, чтобы гайды не расходились по структуре:

№	Раздел	Что внутри
—	Шапка	провайдер, ссылка на официальную документацию и дата сверки, предупреждения «не drop-in»
1	Запустить	docker compose up <service> / npm run start:<service>, порт, синтетические креды стенда
2	Базовый флоу	curl-цепочка Init/getToken → форма/PaymentURL → серверная сверка статуса
3	Что мок проверяет за вас	валидация, подпись/checksum, суммы, статусные переходы, ошибки с field/hint/doc
4	Негативные сценарии	X-Mock-Scenario, тестовые карты, конвенции fail-/hang-
5	Вебхуки	формат и подпись (или явное «подписи нет»), ACK, retry, SSRF-политика
6	Песочницы и часы	/mock/time, X-Mock-Sandbox, /mock/*, /admin
7	Известные отличия от боевого провайдера	список пометок [VERIFY]/[FORK] и ссылка на README сервиса, где они собраны
8	Ссылки	контракт (services/<provider>-mock/README.md), OpenAPI, protocols/<provider>.json, ядро

Разделы нумеруются ## N. подряд, без пропусков и дублей; разделы 4–7 допустимо объединять, если провайдер их не различает (например, read-only адаптер без вебхуков), но разделы 3 и 8 обязательны.

Обязательный минимум проверяет npm run check:site (входит в npm test): нумерация разделов 1..N, раздел «Что мок проверяет за вас» (или «Известные отличия …»), раздел «Ссылки» и ссылка на README сервиса. Все гайды в docs/integration/ описывают протокол провайдера и следуют шаблону без исключений.

Процесс

1. Fork → ветка с говорящим именем (fix/kassa-receipt-datetime).
2. npm test локально.
3. PR: что изменилось, зачем, как проверяли, ссылки на доку/issue.
4. Реагируйте на ревью; CI (Node 18/20/22 + docker smoke) должен быть зелёным.

Обновление базового образа (security patches)

Базовый образ и релизный образ закреплены дайджестами (F-37), чтобы повторная сборка одной версии репозитория не получала другой base image. Обновляют пины только отдельным PR с обоснованием (CVE/плановое обновление):

1. Новый дайджест node:22-alpine: docker buildx imagetools inspect node:22-alpine --format '{{json .Manifest.Digest}}' (или строка «Digest» на hub.docker.com/_/node для тега 22-alpine).
2. Обновите FROM node:22-alpine@sha256:… в Dockerfile и запишите в PR дату и причину обновления.
3. Прогоните оба контура проверок: npm test и node scripts/docker-smoke.js (tbank-mock и kassa-mock обязаны стать healthy, persist/restore — работать при --read-only).
4. После публикации GHCR-образа обновите дайджест релиза в docker-compose.include.yml (MOCK_IMAGE_DIGEST, строка «Digest» на странице пакета ghcr.io/rucorp/mock-services) — это deployment artifact потребителей.

Лицензия вкладов

Отправляя PR, вы соглашаетесь на распространение вклада под Apache-2.0 (см. LICENSE) и подтверждаете, что имеете право его предоставить.

[^brief]: docs/briefs/CLAUDE-2026-10-12-agent-brief.md — бриф доработок, статусы задач и волны. [^audit-prep]: docs/audit/AUDIT-PREP-2026-10-12.md — пакет подготовки к глубокому аудиту, карта покрытия.