From 6b97d87d8e57a8e365372ceafbadbb0c7bed2438 Mon Sep 17 00:00:00 2001 From: Andrey Epifancev Date: Sat, 3 Oct 2026 18:36:17 +0400 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20dev/README.md:=20=D0=B7=D0=B0=D0=BF=D1=83=D1=81=D0=BA?= =?UTF-8?q?=20=D0=B8=D0=BD=D1=84=D1=80=D0=B0=D1=81=D1=82=D1=80=D1=83=D0=BA?= =?UTF-8?q?=D1=82=D1=83=D1=80=D1=8B,=20=D0=BF=D0=B5=D1=80=D0=B5=D0=BC?= =?UTF-8?q?=D0=B5=D0=BD=D0=BD=D1=8B=D0=B5,=20=D1=81=D0=B1=D1=80=D0=BE?= =?UTF-8?q?=D1=81,=20=D0=B7=D0=B0=D0=BF=D1=83=D1=81=D0=BA=20=D0=B8=D0=B7?= =?UTF-8?q?=20venv?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Черновик: профиль services, запуск из venv и интеграционные тесты помечены как планируемые и дописываются в задачах 5.x. Co-Authored-By: Claude Fable 5.1 --- dev/README.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 dev/README.md diff --git a/dev/README.md b/dev/README.md new file mode 100644 index 0000000..16f7b4f --- /dev/null +++ b/dev/README.md @@ -0,0 +1,160 @@ +# Окружение разработки АРМ КА (`docs/dev/`) + +Локальная инфраструктура workspace одной командой: PostgreSQL 16, NATS 2.10 без JetStream и MinIO с бакетом `arm-ka`. + +**Статус (фаза 1):** в compose сейчас только инфраструктура (`postgres`, `nats`, `minio`, `minio-init`). Профиль +`services` (контейнеры `arm-core`, `tabular-parser`, `scan-gateway`, `scan-emulator`) **планируется** — добавляется позже +(задача 5.3), здесь не описан. До этого сервисы запускаются из venv против этой инфраструктуры (см. ниже). + +## Предварительные требования + +- Docker и compose v2 (проверено на docker 28 / compose 2.34). +- `uv` и Python 3.11 — для запуска сервисов из venv (версия Python — как на платформе). +- Свободные порты хоста: 5432 (PostgreSQL), 4222 и 8222 (NATS и его мониторинг), 9000 и 9001 (MinIO API и консоль). + Занятые порты меняются в `.env` (см. «Типичные проблемы»). + +## Запуск инфраструктуры + +Команды — из каталога `docs/dev/`: + +```bash +cp .env.example .env # .env в git не попадает +docker compose up -d # вернётся сразу; healthy — примерно через 6 с +``` + +Ожидание готовности (для скриптов и `Makefile`): + +```bash +docker compose up -d && docker compose up -d --wait postgres nats minio +``` + +Голый `docker compose up -d --wait` **возвращает код 1**: одноразовый `minio-init` (создаёт бакет и завершается с +кодом 0) compose 2.34 считает сбоем (`container arm-ka-minio-init-1 exited (0)`). Поэтому `--wait` нужно давать со +списком долгоживущих сервисов — как выше. + +Проверка: + +```bash +docker compose ps # postgres, nats, minio — Up (healthy); minio-init — Exited (0) +docker compose exec postgres psql -U armka -d armka -c 'select version()' +curl -s localhost:8222/healthz # {"status":"ok"} +curl -s localhost:8222/varz | grep -A1 jetstream # "jetstream": {} — JetStream не включён +docker compose run --rm --entrypoint sh minio-init -c 'mc alias set local http://minio:9000 minioadmin minioadmin >/dev/null && mc ls local' + # [...] 0B arm-ka/ +``` + +Консоль MinIO — (по умолчанию `minioadmin` / `minioadmin`); S3 API — `localhost:9000`. +Схема БД (`dkb`) создаётся миграциями `arm-core`, не compose. + +## Переменные `.env` + +Файл читают `docker compose` (из этого каталога) и, вторым блоком, сервисы при запуске из venv. Значения по умолчанию — +только для dev. + +Блок compose: + +| Переменная | По умолчанию | Для чего | +|---|---|---| +| `POSTGRES_DB` | `armka` | имя БД | +| `POSTGRES_USER` | `armka` | пользователь БД | +| `POSTGRES_PASSWORD` | `armka` | пароль БД | +| `POSTGRES_PORT` | `5432` | порт PostgreSQL на хосте | +| `NATS_PORT` | `4222` | клиентский порт NATS на хосте | +| `NATS_MONITOR_PORT` | `8222` | порт мониторинга NATS (`/varz`, `/healthz`) | +| `MINIO_ROOT_USER` | `minioadmin` | администратор MinIO | +| `MINIO_ROOT_PASSWORD` | `minioadmin` | пароль администратора MinIO | +| `MINIO_API_PORT` | `9000` | порт S3 API на хосте | +| `MINIO_CONSOLE_PORT` | `9001` | порт консоли MinIO на хосте | +| `MINIO_BUCKET` | `arm-ka` | единственный бакет, создаётся `minio-init` | + +Блок сервисов (запуск из venv против compose по `localhost`, формат шаблона команды): + +| Переменная | По умолчанию | Для чего | +|---|---|---| +| `DEBUG` | `true` | dev-режим: пакеты `raisa_*` импортируются условно | +| `OPENBAO__DATABASE__DATABASE_URL` | `postgresql+asyncpg://armka:armka@localhost:5432/armka` | подключение к PostgreSQL (asyncpg) | +| `OPENBAO__MINIO__MINIO_URL` | `localhost:9000` | адрес MinIO без схемы (`host:port`, так ждёт `miniopy-async`) | +| `OPENBAO__MINIO__MINIO_ADMIN_LOGIN` | `minioadmin` | логин MinIO | +| `OPENBAO__MINIO__MINIO_ADMIN_PASSWORD` | `minioadmin` | пароль MinIO | +| `OPENBAO__MINIO__MINIO_BUCKET` | `arm-ka` | бакет | +| `OPENBAO__NATS__NATS_URL` | `nats://localhost:4222` | адрес NATS | +| `OPENBAO__NATS__NATS_SEED` | пусто | nkey seed; пусто — подключение без nkeys | +| `OPENBAO__NATS__NATS_JWT` | пусто | JWT NATS; пусто — подключение без nkeys | + +Два блока описывают одни и те же ресурсы: **при смене порта, пароля, пользователя или бакета меняйте обе части.** + +## Сброс окружения + +```bash +docker compose down # останавливает контейнеры; тома postgres-data и minio-data сохраняются +docker compose down -v # полный сброс: удаляет тома postgres-data и minio-data (БД и бакет — с нуля) +``` + +Имя проекта compose фиксировано (`name: arm-ka`), поэтому тома общие для любого worktree (`.wt/<срез>/docs/dev`): +сброс из одного worktree затрагивает все. + +## Запуск сервисов из venv без Nexus (черновик) + +> Черновик: будет дописан и проверен вручную в задаче 5.4 (сквозная проверка). `make venv` и `make test-integration` +> в `tabular-parser` и `scan-gateway` будут доступны после задач этих сервисов; сейчас они есть в `arm-core`. + +Пакеты `raisa_*` из Nexus банка вне банка недоступны (D-10). Поэтому `make venv` ставит `requirements.txt` без строк +`raisa_*` (фильтр `grep -v '^raisa_'`), код импортирует `raisa_*` условно (при `DEBUG=true`), а npm-пакеты `raisa-*` +в `web/package.json` вынесены в `optionalDependencies`. + +Шаги для сервиса (пути — относительно каталога его репозитория; в workspace `docs/` лежит рядом, `../docs/dev/`): + +```bash +# 1. поднять инфраструктуру (из docs/dev/, см. выше) +# 2. из корня репозитория сервиса: +cp ../docs/dev/.env.example api/.env +make venv # api/.venv: Python 3.11 + зависимости без raisa_* +cd api && .venv/bin/python run_server.py # сервис подключается к PostgreSQL/NATS/MinIO по localhost +# 3. в другом терминале: +curl -s localhost:<порт сервиса>/healthcheck +``` + +Порт сервиса задаётся его настройками; в профиле `services` по spec это 8000 (`arm-core`), 8001 (`tabular-parser`), +8002 (`scan-gateway`). В ответе `/healthcheck` ожидаются `version` и `nats = ok`. + +## Интеграционные тесты сервисов против compose (черновик) + +> Черновик: уточняется после задач 3.x и 5.x. + +Цели `Makefile` одинаковы во всех сервисных репозиториях (spec `quality-checks`): + +- `make test-integration` — `pytest -m integration` против инфраструктуры из этого compose; +- `make check` — быстрые проверки без Docker (ruff, mypy, `pytest -m "not integration"`, идентичность контракта); +- `make check-full` — `make check` + интеграционные тесты; для `arm-core` — ещё «`alembic upgrade head` → + `downgrade base` → `upgrade head`» и `scripts/check_dbml_vs_orm.py`. Выполняется перед созданием PR. + +Интеграционные тесты **требуют поднятой инфраструктуры**: сначала `docker compose up -d && docker compose up -d --wait +postgres nats minio`, затем `make test-integration` (или `make check-full`) в репозитории сервиса. Для `scan-gateway` +дополнительно нужен эмулятор ИС Сканирование (появится вместе с профилем `services`). Общее описание проверок — +`docs/dev/checks.md` (будет добавлено). + +## Проверка контракта + +Из корня репозитория `docs`: `python scripts/validate_contracts.py` — валидирует примеры в +[`contracts/examples/`](../contracts/examples/) тремя схемами из [`contracts/`](../contracts/) (3 схемы, 8 примеров; +нужен `jsonschema`). + +## Примечания + +- **Образы MinIO неофициальные.** Официальные `minio/minio` и `minio/mc` недоступны (Docker Hub — denied, на quay.io нет + нужных тегов), поэтому в compose стоят `alpine/minio:RELEASE.2025-10-15T17-29-55Z` и + `bitnamilegacy/minio-client:2025.7.21`, а сервис `minio` запущен с `user: "0:0"` (иначе образ не пишет в свежий том) — + только для dev. Решения R-5/R-6: [`design.md`](../openspec/changes/slice-0-skeleton/design.md), раздел + «Decisions made without discussion», решения №16–17. Замена на официальные образы — две строки `image:` в + `docker-compose.yml` (и удаление `user: "0:0"`). +- **Безопасность.** Порты публикуются на `0.0.0.0` с паролями по умолчанию: это dev-окружение, не запускайте его в + недоверенной сети. + +## Типичные проблемы + +- **Порт занят** (`address already in use`): измените `*_PORT` в `.env` и одновременно соответствующий порт в + `OPENBAO__*` (`DATABASE_URL`, `MINIO_URL`, `NATS_URL`); перезапустите `docker compose up -d`. +- **`minio-init` завис или завершился с ошибкой:** `docker compose logs minio-init`; чаще всего `minio` не стал healthy — + `docker compose logs minio`. Повторный `docker compose up -d` идемпотентен. +- **Остаточные тома от прошлых запусков** (старый пароль БД, бакет не тот): `docker compose down -v` и запуск заново. +- **`up -d --wait` возвращает код 1:** см. раздел «Запуск инфраструктуры» — указывайте сервисы явно.