fontvielle
5440ebe152
Файл автоматически читается Claude Code при старте сессии. Содержит: - что это за проект (M2M-переводы через MOEX МОСТ НРД) - текущее состояние + ссылку на REPORT.md - архитектуру обмена с НРД (bj-server → ИШ → ONYX) - структуру каталогов и описание DOC/ - неочевидные решения (КриптоПро CSP, не JCP; PKCS#11; mock-робот; Astra Linux для ИШ; globalRC в admin.go; noProxyClient в news.go) - команды для разработки и запуска - описание дев-стендов (10.10.10.22 РЕД ОС, 10.10.10.27 Astra) - правила (REPORT.md держать актуальным, UI на русском, без emoji если не просили) - что НЕ делать (РЕД ОС для ИШ, JCP вместо CSP, выпуск новых сертов) Это handoff для нового агента — на Astra Linux 10.10.10.27 или на любой другой ВМ — чтобы он не открывал контекст с нуля.
150 lines
11 KiB
Markdown
150 lines
11 KiB
Markdown
# 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://<ip>: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
|
||
|
||
---
|
||
|
||
**Спросить пользователя, если непонятно** — не стесняйся. Лучше задать вопрос чем сделать неверное предположение.
|