From bb103e9f989c138ac5ed5d340ad9714e1b01963c Mon Sep 17 00:00:00 2001 From: fontvielle Date: Mon, 12 Oct 2026 19:18:54 +0300 Subject: [PATCH] =?UTF-8?q?docs(CLAUDE.md):=20=D0=B0=D0=BA=D1=82=D1=83?= =?UTF-8?q?=D0=B0=D0=BB=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D1=8F=20=D0=BE=D0=BD?= =?UTF-8?q?=D0=B1=D0=BE=D1=80=D0=B4=D0=B8=D0=BD=D0=B3=D0=B0=20=E2=80=94=20?= =?UTF-8?q?=D1=81=D0=BE=D1=81=D1=82=D0=BE=D1=8F=D0=BD=D0=B8=D0=B5=20=D0=BD?= =?UTF-8?q?=D0=B0=202026-10,=20=D0=BC=D0=BE=D0=B4=D1=83=D0=BB=D0=B8,=20?= =?UTF-8?q?=D1=81=D1=82=D0=B5=D0=BD=D0=B4=D1=8B,=20=D0=B8=D0=BD=D1=84?= =?UTF-8?q?=D1=80=D0=B0=D1=81=D1=82=D1=80=D1=83=D0=BA=D1=82=D1=83=D1=80?= =?UTF-8?q?=D0=B0,=20=D0=B4=D0=B2=D0=B0=20=D1=87=D0=B5=D0=BA=D0=B0=D1=83?= =?UTF-8?q?=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 245 +++++++++++++++++++++++++++++------------------------- 1 file changed, 134 insertions(+), 111 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0bb1373..d4876e3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,149 +1,172 @@ # Bridge-and-Join-s — гайд для агента Claude Code -Этот файл читается автоматически при старте `claude` в репозитории. Здесь — сжатый контекст проекта чтобы агент не вычислял всё заново. +Этот файл читается автоматически при старте `claude` в репозитории. Здесь — сжатый +контекст проекта, чтобы агент не вычислял всё заново. **Держим его в актуальном +состоянии** — это точка входа для любого нового агента. ## Что это за проект -**Bridge-and-Join-s** — система M2M-переводов ценных бумаг между депозитариями через сервис **MOEX МОСТ** (НКО АО НРД). Целевая интеграция — сервис M2M НРД на TEST3, далее PROD. +Bridge-and-Join-s (bj) — шлюз для переводов ценных бумаг физлица «самому себе» (M2M) +между депозитариями через сервис НРД **MOEX МОСТ**. Регулируемая операция +(ФЗ № 124-ФЗ от 23.05.2025, Указание Банка России № 7317-У, в силе с 01.09.2026): +депозитарий зачисляет бумаги клиенту в другом депозитарии без встречного поручения. -**Объём**: 100-1000 сделок в день — сознательно облегчили архитектуру под этот объём. +Роль bj — **протокольное плечо НРД/MOEX МОСТ**: собрать `M2MTransferRequest`, +отправить через Интеграционный шлюз НРД (ИШ сам подписывает ГОСТ-ЭП), принять +`M2MTransferDecision`/`M2MTransferResponse`, вернуть исход в вызвавшую систему. +Переводятся только российские бумаги (ISIN `RU…`) с торгового счёта депо. -**Один бинарник** `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 +Продукт поставляется клиентам как установщик «одной командой»; лицензии и обновления +раздаёт отдельный сервер лицензий (репозиторий `lic_Bridge-and-Join-s`, см. ниже). -**Веб-админка**: `http://:8080/admin/` — главное место общения с системой. Разделы: Дашборд / Мастер настройки / Настройка / Заявки / Статус / Новости / Инструкции. Всё на русском. +### Пакеты (`internal/`) -## Текущее состояние (актуально на 2026-05-18) +- `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 для разработки -См. **`REPORT.md` в корне репо** — там полный статус с процентами. Кратко: +### Модули (`modules/`) — отдельные бинарники, обновляются независимо -- ✅ Все компоненты на нашей стороне написаны и оттестированы (~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, активно) +- `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 + сертификат УЦ МБ +ИШ / igate (ставится на Astra Linux рядом) + │ ИШ САМ: подписывает, упаковывает, отправляет (Валидата CSP + серт УЦ МБ) ▼ Web-сервис ONYX (НРД, https://gost.nsd.ru/onyxt3/WslService) ``` -Подробная схема и FAQ — в `/admin/help/architecture` (когда сервис запущен) и в `DOC/ruk_install_ish_2025_11_10.pdf`. +Подробная схема и FAQ — в `/admin/help/architecture` (когда сервис запущен) и в +`DOC/ruk_install_ish_2025_11_10.pdf`. ## Где что лежит | Каталог | Что | |---|---| -| `cmd/bj-server/` | главный бинарник | +| `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/` | вся бизнес-логика, поделена на пакеты | -| `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 и т.п.) | +| `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` | назначение, роли пользователей, профили (Финансы / автомат / полуавтомат) | -## Документация НРД в 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 контуров НРД +> Пароли/ключи здесь НЕ храним — получить у владельца проекта (вне репозитория). + +| Стенд | Адрес | Роль | +|---|---|---| +| **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 — экономия ~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 - -## Как запускать - -**Локально (для разработки)**: -```bash -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`): -```bash -systemctl status bj-server -journalctl -u bj-server -f -``` - -**Установить с нуля на свежей Astra/Debian/Ubuntu** — одна команда: -```bash -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: -```bash -env -u HTTPS_PROXY -u HTTP_PROXY -u https_proxy -u http_proxy go build ... -``` - -**bj-server в фоне** — нужен `setsid` иначе умирает с shell: -```bash -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` — УЦ МБ, сертификаты +- **КриптоПро 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-баннер «РЕЖИМ ЭМУЛЯЦИИ» — он защищает от случайной отправки в прод -- Не используй прокси zetit для go-модулей или для запросов к nsd.ru — будет 403 +- Не ставить ИШ на РЕД ОС — он только под 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` — УЦ МБ, сертификаты