fontvielle
173 lines
12 KiB
Markdown
173 lines
12 KiB
Markdown
# 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` — УЦ МБ, сертификаты
|