Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 17 additions & 9 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,10 @@ jobs:

steps:
- name: Checkout
uses: actions/checkout@v4
uses: actions/checkout@v7

- name: Setup JDK 21
uses: actions/setup-java@v4
uses: actions/setup-java@v6
with:
distribution: corretto
java-version: '21'
Expand All @@ -33,7 +33,7 @@ jobs:
run: chmod +x gradlew

- name: Проверка Gradle Wrapper
uses: gradle/actions/wrapper-validation@v4
uses: gradle/actions/wrapper-validation@v6

- name: Build and test
run: ./gradlew build --no-daemon
Expand Down Expand Up @@ -75,7 +75,7 @@ jobs:

- name: Upload test reports
if: always()
uses: actions/upload-artifact@v4
uses: actions/upload-artifact@v7
with:
name: test-reports-${{ github.run_number }}
path: |
Expand All @@ -97,7 +97,7 @@ jobs:
run: java -jar validum-cli/build/libs/validum.jar version

- name: Upload fat jar
uses: actions/upload-artifact@v4
uses: actions/upload-artifact@v7
with:
name: validum-jar-${{ github.run_number }}
path: validum-cli/build/libs/validum.jar
Expand All @@ -110,17 +110,25 @@ jobs:
run: java -jar validum-cli/build/libs/validum.jar fetch-bik -o data/ED807.xml

- name: Демо-прогон (demo-check)
if: hashFiles('tools/demo-check.py') != ''
run: python3 tools/demo-check.py --jar validum-cli/build/libs/validum.jar --data data/ED807.xml --skip-excel

- name: Предрелизная проверка (release-check)
if: hashFiles('tools/release-check.py') != ''
run: python3 tools/release-check.py --jar validum-cli/build/libs/validum.jar

- name: Публичный аудит снимка
if: hashFiles('tools/public-audit.py') != ''
run: python3 tools/public-audit.py

- name: Смоук потребителя на JDK 17
if: hashFiles('tools/consumer-smoke.py') != ''
run: |
./gradlew :validum-core:publishToMavenLocal --no-daemon
python3 tools/consumer-smoke.py

- name: Смоук живого REST-сервиса
if: hashFiles('tools/rest-smoke.py') != ''
run: |
./gradlew :validum-api:bootJar --no-daemon
java -jar validum-cli/build/libs/validum.jar fetch-bik -o data/ED807.xml
Expand All @@ -133,10 +141,10 @@ jobs:

steps:
- name: Checkout
uses: actions/checkout@v4
uses: actions/checkout@v7

- name: Setup JDK 17
uses: actions/setup-java@v4
uses: actions/setup-java@v6
with:
distribution: corretto
java-version: '17'
Expand All @@ -158,10 +166,10 @@ jobs:

steps:
- name: Checkout
uses: actions/checkout@v4
uses: actions/checkout@v7

- name: Setup JDK 21
uses: actions/setup-java@v4
uses: actions/setup-java@v6
with:
distribution: corretto
java-version: '21'
Expand Down
6 changes: 3 additions & 3 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,19 +34,19 @@ jobs:

steps:
- name: Checkout
uses: actions/checkout@v4
uses: actions/checkout@v7
with:
fetch-depth: 0

- name: Setup JDK 21
uses: actions/setup-java@v4
uses: actions/setup-java@v6
with:
distribution: corretto
java-version: '21'
cache: gradle

- name: Проверка Gradle Wrapper
uses: gradle/actions/wrapper-validation@v4
uses: gradle/actions/wrapper-validation@v6

- name: Make gradlew executable
run: chmod +x gradlew
Expand Down
34 changes: 27 additions & 7 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,30 @@

Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/), версии — [SemVer](https://semver.org/lang/ru/).

## [Unreleased] — 0.5.0
## [Unreleased] — 0.6.0

Ничего не запланировано — состав следующей версии определится после 0.4.0.
## [0.5.0] — 2026-11-15

Связанный набор и карты «Мир».

### Added
- **Связь «человек → работодатель»:** колонка `employerOgrn` («ОГРН работодателя») в плоской выдаче,
`builder.employer(ogrn)`, строка в `describe`; круговая операция `flatten → parse` сохраняет связь.
- **Карты «Мир»:** `--cards N` (по умолчанию 1) и классы `MirCard`/`MirCardGenerator`/`MirCardOutcome`;
BIN `220000–220499`, 16 цифр с проверкой Луна, срок +2…+5 лет от `asOf`, 90 % успешных операций;
колонки `cardPan`, `cardExpiry`, `cardOutcome`, `cardCount`, строки в `describe`; при `--cards > 1`
и `-o` пишется вторая таблица `<output>-cards.csv`; `coverage` проверяет BIN и Луна.
- **`--format json-nested`:** вложенный JSON (профиль как в REST-DTO: `passport`, `addresses`,
`contacts`, `bank`, `cards`, `documents`) вместо плоской строки; только для `generate individual`.
- **Набор из нескольких сущностей:** `type: "set"` в спецификации — организации, ФЛ и ИП за один
прогон со связью по ОГРН; файлы `*-organizations.csv`, `*-individuals.csv`, `*-ip.csv`,
`*-relations.csv`; каждому участнику — свой seed (`seed + номер × 10007`).
- **Скрипт отката `*-teardown.sql`:** `DELETE` по строкам этого прогона в порядке, обратном загрузке
(люди → организации), пачками по 200 ключей, без DDL; отключается полем `"teardown": false` в спецификации.

### Changed
- Поток `Random` для карт отдельный от потока реквизитов: новые поля больше не сдвигают эталоны
и пулы секретных слов.

## [0.4.1] — 2026-11-14

Expand All @@ -20,9 +41,7 @@

## [0.4.0] — 2026-11-14

Планируется: `--format xlsx` без зависимостей, разложение `core/export` по слоям,
`@Mixin`-опции CLI, README → `docs/*`.
Полный список — [`docs/ROADMAP-0.4.0.md`](docs/ROADMAP-0.4.0.md).
Полный список — раздел `### Added` этого релиза ниже.

Версия также закрывает дефекты 0.3.0, которые не выпускались отдельным хотфиксом.

Expand Down Expand Up @@ -313,9 +332,10 @@
| Исходники | `git clone` → `./gradlew build` |

Требования: JDK 21. Справочник `data/ED807.xml` обязателен — `validum fetch-bik -o data/ED807.xml`.
Порядок выпуска версии — `docs/RELEASING.md`.
Порядок выпуска версии — `CONTRIBUTING.md`.

[Unreleased]: https://github.com/Validum-Tech/validum/compare/v0.4.1...HEAD
[Unreleased]: https://github.com/Validum-Tech/validum/compare/v0.5.0...HEAD
[0.5.0]: https://github.com/Validum-Tech/validum/compare/v0.4.1...v0.5.0
[0.4.1]: https://github.com/Validum-Tech/validum/compare/v0.4.0...v0.4.1
[0.4.0]: https://github.com/Validum-Tech/validum/compare/v0.3.0...v0.4.0
[0.3.0]: https://github.com/Validum-Tech/validum/compare/v0.2.0...v0.3.0
Expand Down
71 changes: 32 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,68 +4,61 @@

[![CI](https://github.com/Validum-Tech/validum/actions/workflows/ci.yml/badge.svg)](https://github.com/Validum-Tech/validum/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Java](https://img.shields.io/badge/Java-21_LTS-orange.svg)](https://adoptium.net/)
[![Spring Boot](https://img.shields.io/badge/Spring_Boot-3.5-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Gradle](https://img.shields.io/badge/Gradle-8.14-blue.svg)](https://gradle.org/)
[![Tests](https://img.shields.io/badge/tests-860_passing-success.svg)](#-тесты)
[![Coverage](https://img.shields.io/badge/coverage-core_91%25_%7C_api_92%25-yellowgreen.svg)](#-тесты)
[![Banks](https://img.shields.io/badge/CBR_banks-370-blueviolet.svg)](#-полный-справочник-цб-рф)
[![Zero-deps](https://img.shields.io/badge/core-zero--dependency-lightgrey.svg)](#-архитектура)
[![CLI](https://img.shields.io/badge/CLI-picocli-informational.svg)](#-cli-p31)
[![Allure](https://img.shields.io/badge/Allure-JUnit_5_Extension-yellow.svg)](#-allure-extension-p32)
[![Java](https://img.shields.io/badge/Java-17%2B-orange.svg)](https://adoptium.net/)
[![Tests](https://img.shields.io/badge/tests-906_passing-success.svg)](docs/QUICKSTART.md)
[![Maven Central](https://img.shields.io/badge/Maven_Central-0.5.0-informational.svg)](https://central.sonatype.com/artifact/io.github.validum-tech/validum-core)
[![core](https://img.shields.io/badge/core-zero--dependency-lightgrey.svg)](docs/PROJECT.md)

---

Validum — самодостаточная платформа генерации **валидных** тестовых данных для российского финтеха:
ИНН, СНИЛС, ОГРН/ОГРНИП, КПП, ОКПО, БИК и корсчета из справочника ЦБ, счета по 809-П, паспорта,
адреса из КЛАДР, ОКВЭД-2 — всё с настоящими контрольными суммами, детерминированно по `seed` и с
шагом `asOf`.

16 REST-эндпоинтов и 10 команд CLI; всё, что генерится, проверяется теми же валидаторами,
что используют банки, а справочник участников берётся из выгрузки ЦБ.
ИНН, СНИЛС, ОГРН/ОГРНИП, КПП, ОКПО, БИК и корсчёт из справочника ЦБ, счета по 809-П, паспорта,
адреса из КЛАДР, ОКВЭД-2 — с настоящими контрольными суммами, детерминированно по `seed` и с
шагом `asOf`. Core без зависимостей; CLI и REST — тонкие обёртки над ним.

## За 30 секунд

```bash
# 1. Справочник участников ЦБ (обязателен: около 1,4 тыс. участников, около 370 банков)
# 1. Справочник участников ЦБ (обязателен для банковских сценариев)
java -jar validum.jar fetch-bik -o data/ED807.xml

# 2. Профиль клиента с реквизитами, банком и счётом
java -jar validum.jar generate individual --seed 42

# 3. Тысяча клиентов в CSV для Excel
# 3. Тысяча клиентов в CSV, который открывается в Excel
java -jar validum.jar generate individual --seed 42 -n 1000 --format csv-semicolon -o out/clients.csv
```

Jar ещё не собран? `./gradlew :validum-cli:shadowJar` — подробности в [QUICKSTART](docs/QUICKSTART.md).

## Документация

| Раздел | Что внутри |
Начать стоит с **[туториала](docs/TUTORIAL.md)** — один проход «от установки до проверенного
набора» на 30–40 минут. Остальное — по мере необходимости.

| Документ | Когда открывать |
|---|---|
| [Быстрый старт](docs/QUICKSTART.md) | установка, первый прогон, сборка из исходников, тесты, Docker |
| [Возможности](docs/FEATURES.md) | зачем нужен, ключевые свойства, что уже работает |
| [CLI](docs/CLI.md) | десять команд, пакетная выдача, валидация, экспорт, уникальность, `--corrupt`, справочник ЦБ |
| [REST API](docs/REST.md) | batch-эндпоинты, `fill`, `validate`, `scenarios`, `export`, коды ошибок |
| [Интеграции](docs/INTEGRATIONS.md) | Java-библиотека и JUnit 5 + Allure |
| [Совместимость](docs/COMPATIBILITY.md) | контракт потребителя: Java 17+, аддитивность полей, детерминизм |
| [Рецепты](docs/recipes/README.md) | 14 готовых сценариев под конкретные задачи |
| [Проект](docs/PROJECT.md) | архитектура, структура репозитория, релизы, участие |
| [Демо-сценарий](docs/DEMO-SCENARIO.md) | пошаговый прогон для видео и презентаций (внутреннее) |
| [Туториал](docs/TUTORIAL.md) | первый раз в проекте |
| [QUICKSTART](docs/QUICKSTART.md) | установка, сборка, тесты, Docker |
| [CLI](docs/CLI.md) | все команды и флаги |
| [REST](docs/REST.md) | HTTP-эндпоинты, форматы, коды ошибок |
| [Интеграции](docs/INTEGRATIONS.md) | Java-библиотека, JUnit 5 + Allure |
| [Совместимость](docs/COMPATIBILITY.md) | Java 17+, аддитивность полей, детерминизм |
| [Рецепты](docs/recipes/README.md) | готовая команда под конкретную задачу |
| [Возможности](docs/FEATURES.md) | зачем нужен и что работает |
| [Сценарии](docs/SCENARIOS.md) | типы клиентов, каскады, поля профиля |
| [Проект](docs/PROJECT.md) | архитектура, модули, как участвовать |
| [История версий](CHANGELOG.md) | что менялось и когда |
| [Лицензия](LICENSE) | Apache-2.0 |

## Цифры

| Метрика | Значение |
|---|---|
| Тесты | 872 исполнения: 660 core + 100 CLI + 91 API + 21 Allure, 0 падений |
| Модули | 4: `validum-core` (без зависимостей), `validum-cli`, `validum-api`, `validum-allure` |
| Команды CLI | 9 (`generate`, `fill`, `validate`, `fetch-bik`, `participants`, `scenarios`, `export`, `coverage`, `describe`) |
| REST | 16 эндпоинтов |
| Справочник ЦБ | 1 360 участников, 368 банков, 1 297 счетов |
| Адреса | 90 субъектов, 98 730 населённых пунктов, 1 993 702 улицы, индексы из `DOMA.DBF` |
| Тесты | 906: 679 core + 114 CLI + 92 API + 21 Allure, 0 падений |
| Модули | `core` (без зависимостей), `cli`, `api`, `allure` |
| Поверхность | 10 команд CLI, 19 REST-эндпоинтов |
| Справочник ЦБ | около 1,4 тыс. участников, около 370 действующих банков (зависит от выгрузки) |
| Адреса | 90 субъектов, 98,7 тыс. населённых пунктов, ~2 млн улиц, индексы из `DOMA.DBF` |
| ОКВЭД-2 | 3 069 позиций |

## Лицензия и контакты

Apache License 2.0 — [LICENSE](LICENSE). Вопросы и предложения: issue в репозитории
или `dev@validum.tech`. Сайт: [validum.tech](https://validum.tech).
Apache License 2.0 — [LICENSE](LICENSE). Вопросы и предложения — issue в репозитории;
почта `dev@validum.tech`, сайт [validum.tech](https://validum.tech).
55 changes: 50 additions & 5 deletions docs/CLI.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ POST /api/v1/generate/individual/batch
}
```

**P3.3:** в батч можно добавить `"bik": "044525225"` — все профили в пакете получат этот банк.
**P3.3:** в батч можно добавить `"bik": "044525225"` — все профили в батче получат этот банк.

Ответ (по умолчанию `json`): `{ "count": 100, "seed": 42, "profiles": [...] }`.

Expand Down Expand Up @@ -164,7 +164,7 @@ Fat JAR на Picocli. **Без Spring.** ~15 МБ со справочникам
# → validum-cli/build/libs/validum.jar
```

### Быстрый старт
### Справка и знакомство

```powershell
java -jar validum.jar --help
Expand All @@ -186,13 +186,58 @@ java -jar validum.jar generate ip --seed 1 --count 10 --region MOSCOW --format j

# 5 ЮЛ типа ГУП
java -jar validum.jar generate organization --seed 42 --count 5 --type SE --region MOSCOW --format csv -o gup.csv

# Карты «Мир»: у каждого клиента по две, вторая таблица — рядом
java -jar validum.jar generate individual --seed 42 --count 3 --cards 2 --format csv -o out/clients.csv
# → out/clients.csv и out/clients-cards.csv

# Вложенный JSON: профиль как в REST, а не плоская строка
java -jar validum.jar generate individual --seed 42 --format json-nested -o out/clients.json
```

### Набор из нескольких сущностей (`type: "set"`)

Один прогон создаёт организации, людей и ИП **со связью «человек → работодатель»** — то, что нужно,
чтобы засеять несколько связанных таблиц. Ссылка проставляется по ОГРН организации.

```powershell
java -jar validum.jar generate --spec out/demo-set.json
```

```json
{
"type": "set",
"seed": 42,
"asOf": "2026-11-15",
"output": "out/demo-set.csv",
"members": [
{"name": "orgs", "kind": "organization", "count": 2},
{"name": "people", "kind": "individual", "count": 10, "employer": "orgs"},
{"name": "ip", "kind": "ip", "count": 2, "employer": "orgs"}
]
}
```

Что получится рядом с `out/demo-set.csv`:

| Файл | Содержимое |
|---|---|
| `demo-set-organizations.csv` | профили ЮЛ — загружать первыми |
| `demo-set-individuals.csv` | ФЛ с заполненным `employerOgrn` |
| `demo-set-ip.csv` | ИП (их `base` — тот же человек с `employerOgrn`) |
| `demo-set-relations.csv` | связи `personId → employerOgrn` (две колонки) |
| `demo-set-teardown.sql` | откат: `DELETE` по созданным строкам в обратном порядке (дети → родители), без DDL |

Правила: `kind` — `organization | individual | ip`; `employer` указывает на `name` участника-организации;
работодатель выдаётся по кругу (`i-й человек → i-я организация`); каждому участнику достаётся свой seed
(`seed + номер × 10007`), поэтому набор воспроизводим целиком; `count` — сколько записей у участника.
Скрипт отката пишется всегда; отключается полем `"teardown": false`.

### Валидация (exit 0/1)

```powershell
java -jar validum.jar validate inn 500100732259 # → exit 0
java -jar validum.jar validate inn 500100732258 # → exit 1
java -jar validum.jar validate inn 500100732259 # → код 0
java -jar validum.jar validate inn 500100732258 # → код 1
java -jar validum.jar validate ogrnip 304500116000157
```

Expand Down Expand Up @@ -355,7 +400,7 @@ Expand-Archive -Path data\newbik.zip -DestinationPath data\
Rename-Item data\*.xml data\ED807.xml
```

**Парсер:** WINDOWS-1251, namespace `urn:cbr-ru:ed:v2.0`, фильтры `PtType="20"`, `PSAC`, `CRSA`, `ACAC`. Из ~1380 участников — **370 банков** (все участники — `participants --file`).
**Парсер:** WINDOWS-1251, namespace `urn:cbr-ru:ed:v2.0`, фильтры `PtType="20"`, `PSAC`, `CRSA`, `ACAC`. Из ~1,4 тыс. участников — **около 370 действующих банков** (все участники — `participants --file`).

### Где ищется файл

Expand Down
Loading
Loading