diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0bb1373 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,149 @@ +# 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://: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 + +## Как запускать + +**Локально (для разработки)**: +```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` — УЦ МБ, сертификаты + +## Что делать НЕ надо + +- Не пытайся ставить ИШ на РЕД ОС — он только под Astra (.deb пакет) +- Не предлагай переход на КриптоПро JCP — пользователь явно его отверг по цене +- Не пытайся выпускать новые сертификаты — у организации они уже есть, наша задача только импортировать +- Не убирай UI-баннер «РЕЖИМ ЭМУЛЯЦИИ» — он защищает от случайной отправки в прод +- Не используй прокси zetit для go-модулей или для запросов к nsd.ru — будет 403 + +--- + +**Спросить пользователя, если непонятно** — не стесняйся. Лучше задать вопрос чем сделать неверное предположение.