Bridge-and-Join-s/CLAUDE.md

Bridge-and-Join-s — гайд для агента Claude Code

Этот файл читается автоматически при старте claude в репозитории. Здесь — сжатый контекст проекта, чтобы агент не вычислял всё заново. Держим его в актуальном состоянии — это точка входа для любого нового агента.

Что это за проект

Bridge-and-Join-s (bj) — шлюз для переводов ценных бумаг физлица «самому себе» (M2M) между депозитариями через сервис НРД MOEX МОСТ. Регулируемая операция (ФЗ № 124-ФЗ от 23.05.2025, Указание Банка России № 7317-У, в силе с 01.09.2026): депозитарий зачисляет бумаги клиенту в другом депозитарии без встречного поручения.

Роль bj — протокольное плечо НРД/MOEX МОСТ: собрать M2MTransferRequest, отправить через Интеграционный шлюз НРД (ИШ сам подписывает ГОСТ-ЭП), принять M2MTransferDecision/M2MTransferResponse, вернуть исход в вызвавшую систему. Переводятся только российские бумаги (ISIN RU…) с торгового счёта депо.

Продукт поставляется клиентам как установщик «одной командой»; лицензии и обновления раздаёт отдельный сервер лицензий (репозиторий lic_Bridge-and-Join-s, см. ниже).

Пакеты (internal/)

• m2m — XSD-модели сообщений (M2MTransferRequest/Decision/Response/Handbook/…)
• m2mcore — стейт-машина заявок, репозиторий (memory + pgx)
• lkgateway — REST API, веб-админка, мастер настройки, dev-страница «Эмуляторы»
• nsdadapter — два режима: mock (внутренний робот-эмулятор НРД) и igw (REST-клиент ИШ)
• cryptocli — PKCS#11 клиент к СКЗИ (КриптоПро CSP / Рутокен / Валидата)
• nsdxml — XML-кодек с CP-1251
• fansystore — чтение портфелей из учётной системы (Fansy/DEPO)
• license, hwid — лицензионный токен (Ed25519) и отпечаток сервера
• release — модель компонентов релиза и манифест (components.go — источник правды)
• notify, lkemulator — уведомления и эмулятор ЛК ESIA для разработки

Модули (modules/) — отдельные бинарники, обновляются независимо

• lk → bj-lk — личный кабинет клиента (для брокеров без платформы Финансы)
• npr → bj-npr — риск-монитор «НПР / УДС» по данным QUIK
• quikexport → bj-quikexport — экспорт биржевой информации (ARQA quikexport)
• modkit — общий каркас модулей

Текущее состояние (актуально на 2026-10-12)

Полный статус с процентами — в REPORT.md в корне. Кратко:

• Активная ветка разработки — feature/keywizard-m2m-live (не main; main сильно отстаёт). Последний выпуск — 2026.10.08.2.
• Готово и работает: ядро M2M (контракты/FSM/журнал — 100%), веб-админка и мастер настройки, REST-клиент ИШ, эмулятор робота НРД, установщик одной командой, модули ЛК / НПР / QUIK-экспорт, сервер лицензий и портал, dev-страница «Эмуляторы» (имитация НРД и МНП QUIK в режиме разработки).
• Заблокировано на внешнем: СКЗИ «Валидата CSP» для Linux, сертификат УЦ МБ, реальное подключение к роботу TEST3 НРД (REST-клиент готов, ждём сам ИШ + серт).

Архитектура обмена с НРД (кратко)

bj-server (наше Go-приложение)
   │  REST: POST /api/package/{channel}/file (ZIP в base64)
   ▼
ИШ / igate (ставится на Astra Linux рядом)
   │  ИШ САМ: подписывает, упаковывает, отправляет (Валидата CSP + серт УЦ МБ)
   ▼
Web-сервис ONYX (НРД, https://gost.nsd.ru/onyxt3/WslService)

Подробная схема и FAQ — в /admin/help/architecture (когда сервис запущен) и в DOC/ruk_install_ish_2025_11_10.pdf.

Где что лежит

Каталог	Что
cmd/bj-server/	главный бинарник (ядро)
cmd/bj-lk/, cmd/bj-npr/, cmd/bj-quikexport/	модули-бинарники
cmd/bj-installer/, cmd/bj-component-install/	установщик и root-установщик обновлений
cmd/bj-release/	сборка и публикация релиза (манифест, подпись)
cmd/lk-emulator/	эмулятор ЛК ESIA для разработки
internal/, modules/	бизнес-логика (см. выше)
services/crypto-service/	Java-сервис подписи/проверки (служба bj-crypto)
migrations/	SQL: fansy-store/ (вход от Fansy) и m2m-core/ (журнал сделок)
deploy/	установщик, systemd-юниты, healthcheck
DOC/	документация НРД (PDF, ~15 файлов)
docs/	внутренние контракты (Fansy, ЛК ESIA — OpenAPI)
REPORT.md	отчёт для руководства — держим в актуальном виде
PRODUCT.md	назначение, роли пользователей, профили (Финансы / автомат / полуавтомат)

Стенды и инфраструктура

Пароли/ключи здесь НЕ храним — получить у владельца проекта (вне репозитория).

Стенд	Адрес	Роль
astramost	195.239.71.22:22451 (внутр. 10.10.10.28), Astra Linux, юзер fontvielle	Основной стенд: живой код в /opt/bj/src, сборка, релизы, все службы bj. sudo без пароля. Доступ по SSH ограничен по IP.
Тестовый	10.10.10.29 (из сети стенда)	Отдельный тестовый стенд, что-то проверяли. SSH-пароль/ключ — отдельные, уточнять у владельца.
Сервер лицензий (ПРОД)	46.173.19.220 = lic.zetit.ru	bj-license-server за nginx (127.0.0.1:8091). Деплой — lic_Bridge-and-Join-s/deploy/deploy.sh (root по SSH-ключу с astramost).

Службы на astramost (все под systemd): bj-server, bj-lk, bj-npr, bj-quikexport, bj-crypto, bj-keymedia, igate (ИШ), postgresql@11-main. Бинарники — в /opt/bj/.

Git

• Продукт: ssh://git@git.zetit.ru:32774/zuevav/Bridge-and-Join-s.git (ветка feature/keywizard-m2m-live).
• Сервер лицензий: ssh://git@git.zetit.ru:32774/zuevav/lic_Bridge-and-Join-s.git (ветка master), чекаут на astramost в ~/lic_Bridge-and-Join-s. Это внутренняя инфраструктура, клиентам не поставляется.
• Push с astramost настроен (ключ ~/.ssh/id_ed25519, хост git.zetit.ru в ~/.ssh/config).

⚠️ Два чекаута продукта на astramost — не перепутать

• /opt/bj/src — живой код, здесь работаем (ветка feature/keywizard-m2m-live).
• ~/Bridge-and-Join-s — старая копия от мая 2026, НЕ трогать для разработки (помечена своим README). Единственное ценное в ней — несколько незакоммиченных заметок в DOC/*.txt.

Как собирать и выкатывать

cd /opt/bj/src
# сборка без прокси (go-модули идут напрямую, не через zetit-прокси)
env -u HTTPS_PROXY -u HTTP_PROXY -u https_proxy -u http_proxy go build -o ./bin/bj-server ./cmd/bj-server
go test ./...

Запуск вручную (путь к libs нужен только при наличии КриптоПро):

LD_LIBRARY_PATH=/opt/cprocsp/lib/amd64 setsid ./bin/bj-server > /tmp/bj.log 2>&1 < /dev/null & disown
systemctl status bj-server ; journalctl -u bj-server -f

Релиз (подпись закрытым ключом — только на доверенной машине, на сервер не попадает):

# cmd/bj-release собирает манифест и подписывает; логи выкладок — ~/rel-*.log
# релиз раздаётся сервером лицензий: https://lic.zetit.ru/updates/v1/<канал>/manifest.json

Деплой сервера лицензий — cd ~/lic_Bridge-and-Join-s && ./deploy/deploy.sh (по умолчанию HOST=root@46.173.19.220).

Решения, которые мы приняли (не очевидные)

• КриптоПро CSP, а не JCP — экономия лицензии. Для отправки в НРД подпись делает ИШ (своей Валидатой), bj-server для этого не нужен.
• PKCS#11 как единый интерфейс к разным СКЗИ — internal/cryptocli через github.com/miekg/pkcs11.
• Модули как отдельные бинарники (bj-lk/npr/quikexport) с независимым обновлением; выдаются только если входят в лицензию (internal/release/components.go).
• Mock-робот внутри bj-server — тест логики без живого НРД. Код MC0012500000 в ReceiverCode + DocumentSeries 1111/2001/2002/3333.
• Astra Linux для ИШ — единственная поддерживаемая НРД ОС (РЕД ОС не пойдёт).
• Отпечаток сервера (hwid) привязывает лицензию к машине; перенос — только через деактивацию на сервере лицензий.
• doc-watcher с явным noProxyClient — игнорирует ENV-прокси (zetit блокирует nsd.ru).

Что делать НЕ надо

• Не ставить ИШ на РЕД ОС — он только под Astra (.deb).
• Не предлагать переход на КриптоПро JCP — отвергнут по цене.
• Не выпускать новые сертификаты — у организации они есть, наша задача только импортировать.
• Не убирать UI-баннер «РЕЖИМ ЭМУЛЯЦИИ» — защита от случайной отправки в прод.
• Не гонять go-модули и запросы к nsd.ru через прокси zetit — будет 403.
• Не путать /opt/bj/src (живой) и ~/Bridge-and-Join-s (старый).
• Закрытый ключ релиза (~/keys/release-signing.priv) на сервер не выкладывать.

Контакты НРД

• M2MOST@nsd.ru — форматы M2M · soed@nsd.ru — дистрибутивы (Валидата, ИШ) · pki@moex.com — УЦ МБ, сертификаты