docs(CLAUDE.md): актуализация онбординга — состояние на 2026-10, модули, стенды, инфраструктура, два чекаута

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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