# 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`.

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

```bash
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 нужен только при наличии КриптоПро):

```bash
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
```

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

```bash
# 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` — УЦ МБ, сертификаты