Как писать страницы этой базы

Правила, которые делают базу читаемой и не дают ей расползтись. Их соблюдают и люди, и ИИ-агенты, которым поручают написать страницу.

Что мы объясняем

Смысл, а не содержимое файлов. Страница отвечает на вопрос разработчика, а не индексирует код. Имена классов, пути к файлам, номера строк и перечни эндпоинтов не нужны: код меняется быстрее документации, а найти его умеет поиск. Назвать эндпоинт можно, если без него абзац теряет смысл.

Читателя, который пришёл вчера. Если термин встречается впервые — либо объясните его в одном предложении, либо сошлитесь на словарь.

Прозой, законченными предложениями. Не телеграфный стиль, не обрывки, не стрелочные цепочки. Таблицы — для коротких перечислимых фактов, объяснения выносим в текст вокруг них.

Как избежать расползания

Одна вещь описана в одном месте. Флоу отвечает «что за чем во времени», механика — «как устроена подсистема», карточка сервиса — «кто за это отвечает». Если пишете про 3DS внутри флоу больше абзаца, значит это должно быть в механике, а во флоу — ссылка.

Новый флоу пишется как отличие от базового. Подробно расписан только платёж картой server-to-server. Любая другая страница флоу начинается с раздела «чем отличается» и не повторяет общую часть.

Не дублируйте другие источники, ссылайтесь. Инфраструктура, сети и логи — в superpos-prod-architecture. Интеграции с конкретными провайдерами — в репозитории драйверов. Публичное описание API для мерчантов — в документации merchant API.

Страницы флоу

На каждой странице флоу обязателен раздел «Как это выглядит целиком» с sequence-диаграммой. Образец — платёж картой server-to-server: диаграмма стоит после таблицы участников и до пошагового разбора, чтобы читатель сначала увидел путь целиком, а потом разбирался в шагах.

Правила простые. Участники диаграммы называются так же, как сервисы в тексте и в карточках, — иначе читатель не свяжет одно с другим. Рисуется основной путь: успешный сценарий плюс те развилки, без которых флоу непонятен, например возврат плательщика с 3DS. Обработка ошибок, таймауты и повторы на диаграмму не выносятся — они расползутся в нечитаемую паутину, их место в тексте и в разделе «Где ломается чаще всего».

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

Подписи к стрелкам короткие — что передаётся, а не пересказ шага. Всё остальное скажет текст под диаграммой.

Страницы сервисов

Карточка сервиса отвечает на вопрос «кто за это отвечает»: что сервис делает, чего он сознательно не делает, что получает на вход и куда ходит сам, где хранит данные и в каких флоу участвует. Устройство подсистем — в механиках, последовательность шагов — во флоу, здесь только зона ответственности.

Заканчивается карточка разделом «Где искать» с тремя обязательными ссылками. Это и есть главное, за чем на неё вернутся во второй раз.

Репозиторий с кодом. Обычные сервисы — https://github.com/smartpayments-dev/<repo>, сервисы PCI-контура — https://github.com/smartcore-pci-software/<repo>. Имя репозитория берите из git remote, а не из имени папки: в PCI-организации оно бывает другим — шлюз для карточных данных лежит там как api-gateway-kotlin.

Карточка в инфраструктуре. Ссылка на файл сервиса в описании прод-контура: https://github.com/smartpayments-dev/superpos-prod-architecture/blob/main/services/<имя>/service.yaml. Там сети, группы безопасности, балансировщики и логи — в базе знаний мы это не пересказываем. Имя каталога тоже проверяйте: драйверы там называются drivers-service, антифрод — antifraud-service.

Публичная документация. Документация merchant API — ссылайтесь на конкретный раздел, который обслуживает сервис, а не на корень: https://api-docs.smartcore.pro/#create-direct-payment, #create-payment-form, #callback, #refund, #transaction-statuses. Если сервис внутренний и наружу не смотрит, так и напишите — строка «публичной документации нет» отвечает на вопрос не хуже ссылки.

Всё остальное в «Где искать» — по желанию: правила работы с кодом из репозитория, скиллы, конвенции. Три ссылки выше — обязательный минимум.

Чего в базе не бывает

• Упоминаний KZ P2P — этого продукта здесь нет ни в каком виде.
• Описания локального запуска системы: разработчик получает окружение, которое разворачивается через админку окружений.
• Привязки к срокам вида «в первый день», «за неделю» — важен порядок изучения, а не график.
• Секретов, ключей, реальных идентификаторов мерчантов и карт.
• Эмодзи и вводных оборотов вроде «в этой статье мы рассмотрим».

Факты, в которых легко ошибиться

• Ядро одно; альтернативных реализаций платёжного флоу в базе не существует.
• Шлюзы ходят в ядро по HTTP.
• Входящие уведомления банков приходят в ядро; сервис колбеков занимается только исходящими уведомлениями мерчанту.
• Токен карты обратим для внутренних сервисов — это не анонимизация.
• Чарджбэк не транзакция, а признак на платеже.

Если факт не проверен

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