Bridge-and-Join-s/CLAUDE.md

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

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

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

Bridge-and-Join-s — система M2M-переводов ценных бумаг между депозитариями через сервис MOEX МОСТ (НКО АО НРД). Целевая интеграция — сервис M2M НРД на TEST3, далее PROD.

Объём: 100-1000 сделок в день — сознательно облегчили архитектуру под этот объём.

Один бинарник bj-server (cmd/bj-server) вместо изначально планировавшихся микросервисов. Внутри — пакеты:

• internal/m2m — XSD-модели всех сообщений (M2MTransferRequest/Decision/Response)
• internal/m2mcore — стейт-машина заявок, репозиторий (memory + pgx)
• internal/lkgateway — REST API, веб-админка, lk-emulator, мастер настройки
• internal/nsdadapter — два режима: mock (внутренний робот-эмулятор) и igw (REST-клиент Интеграционного шлюза НРД)
• internal/cryptocli — PKCS#11 клиент к СКЗИ (КриптоПро CSP / Рутокен / Валидата)
• internal/nsdxml — XML кодек с CP-1251

Веб-админка: http://<ip>:8080/admin/ — главное место общения с системой. Разделы: Дашборд / Мастер настройки / Настройка / Заявки / Статус / Новости / Инструкции. Всё на русском.

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

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

• ✅ Все компоненты на нашей стороне написаны и оттестированы (~75% общая готовность)
• ✅ REST-клиент ИШ НРД готов (internal/nsdadapter/igw/ + тесты)
• ✅ Эмулятор робота MOEX МОСТ (4 сценария) работает
• ✅ Установщик одной командой deploy/astra/install.sh готов для Astra/Debian/Ubuntu
• ⏳ Заблокировано на внешнем: дистрибутив Валидата CSP (запрос в soed@nsd.ru), сертификат УЦ МБ (ca.moex.com), регистрация в TEST3
• ⚠️ Окно техработ TEST3 закрыто (18-22.05.2026 — сейчас 18.05, активно)

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

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/lk-emulator/	эмулятор ЛК ESIA для разработки
internal/	вся бизнес-логика, поделена на пакеты
migrations/	SQL миграции: fansy-store/ (входные данные от Fansy) и m2m-core/ (журнал сделок)
deploy/astra/	установщик одной командой + healthcheck
deploy/systemd/	systemd unit (используется install.sh)
deploy/docker-compose/	docker-compose для PostgreSQL в podman
DOC/	вся документация НРД (PDF — около 15 файлов, см. ниже)
dist/ish/	дистрибутив ИШ НРД (~120 МБ .deb, не в git)
docs/	наша внутренняя документация (контракты Fansy и т.п.)
REPORT.md	отчёт для руководства — держим в актуальном виде

Документация НРД в DOC/

• Инструккия M2M.pdf — главный документ по M2M-обмену (схемы, протоколы)
• instr-ish-rest-api.pdf — REST API ИШ (на нём основан internal/nsdadapter/igw)
• ruk_install_ish_2025_11_10.pdf — Руководство по установке ИШ (нужны Astra Linux + Валидата CSP)
• ruk_pol_ish.pdf — Руководство пользователя ИШ
• QA_ish.pdf, test-case_ish.pdf — FAQ и тест-кейсы
• instruktsiya-po-testirovaniyu-s-robotom.pdf — робот-автотест на TEST3 (код MC0012500000, 4 сценария)
• servis-most-m2m.pdf — обзор сервиса MOEX МОСТ
• Ссылки для доступа в тестовые контуры.pdf — URL'ы GUEST/TEST3/PROD контуров НРД

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

• КриптоПро CSP, а не JCP — экономия ~50 000 ₽ лицензии. Используется для подписи действий оператора в админке через Рутокен. Для отправки в НРД подпись делает ИШ (своей Валидатой) — наш bj-server для этого не нужен
• PKCS#11 как единый интерфейс к разным СКЗИ — пакет internal/cryptocli через github.com/miekg/pkcs11
• Один бинарник вместо микросервисов — для нашего объёма проще, никаких микросервисных издержек
• Mock-робот внутри bj-server — позволяет тестить логику без живого НРД. Активируется кодом MC0012500000 в ReceiverCode + DocumentSeries 1111/2001/2002/3333
• Astra Linux для ИШ — единственная поддерживаемая ОС от НРД (РЕД ОС не пойдёт). Дев — Astra CE (бесплатная), прод — Astra SE (платная)
• globalRC в admin.go — глобальная переменная RC для шаблонов; компромисс между чистотой и шумностью передачи *RuntimeConfig через все хендлеры
• doc-watcher с явным noProxyClient в news.go — игнорирует ENV-прокси, потому что zetit блокирует nsd.ru

Как запускать

Локально (для разработки):

go build -o ./bin/bj-server ./cmd/bj-server
LD_LIBRARY_PATH=/opt/cprocsp/lib/amd64 ./bin/bj-server   # путь нужен только если есть КриптоПро

Production-стиль через systemd (после deploy/astra/install.sh):

systemctl status bj-server
journalctl -u bj-server -f

Установить с нуля на свежей Astra/Debian/Ubuntu — одна команда:

curl -sSL https://git.zetit.ru/zuevav/Bridge-and-Join-s/raw/main/deploy/astra/install.sh | sudo bash

Окружение разработки

• Дев-стенд №1: РЕД ОС 8 на 10.10.10.22 — историческая ВМ, КриптоПро CSP установлен, есть PostgreSQL в podman, bj-server и lk-emulator работают
• Дев-стенд №2: Astra Linux SE 1.7 на 10.10.10.27 — будущий основной стенд (потому что Astra нужна для ИШ). Поднята 14.05.2026, базовая dev-среда настроена (Node 20, claude-code, tmux, прокси claude-fna)
• Прокси zetit fna.zetit.ru:3128 — только для Claude Code (alias claude-fna). Всё остальное (go modules, apt, nsd.ru) идёт напрямую
• Git remote: https://git.zetit.ru/zuevav/Bridge-and-Join-s.git (Gitea на zetit)

Команды и подсказки агенту

После любого значимого изменения — обновляй REPORT.md в том же коммите. Это правило (см. feedback_report_md_keep_updated.md в памяти). REPORT.md — «живая» отчётность для руководства, пользователь должен в любой момент открыть и показать.

Прокси при go build — выключай ENV-прокси, у нас всё ходит мимо zetit:

env -u HTTPS_PROXY -u HTTP_PROXY -u https_proxy -u http_proxy go build ...

bj-server в фоне — нужен setsid иначе умирает с shell:

LD_LIBRARY_PATH=/opt/cprocsp/lib/amd64 setsid ./bin/bj-server > /tmp/bj.log 2>&1 < /dev/null & disown

Cwd важно — после cd DOC/ или подобного go build от ./cmd/bj-server упадёт. Всегда возвращайся в /home/fontvielle/Bridge-and-Join-s (или /opt/bj/src на Astra).

Все UI-надписи — на русском (требование заказчика). Исключения только для программных терминов (PostgreSQL, REST, JSON, и т.п.).

Не создавай PDF-документы и md-отчёты без явного запроса. REPORT.md — единственный, его поддерживаем актуальным.

Релизные коммиты — заголовок в Conventional Commits (feat(igw): ..., fix(admin): ...), русский body. См. предыдущие коммиты git log --oneline.

Контакты НРД (если что-то нужно по проекту)

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

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

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

---

Спросить пользователя, если непонятно — не стесняйся. Лучше задать вопрос чем сделать неверное предположение.