From eae07bdba8932f788b228cf29ec2877661b20734 Mon Sep 17 00:00:00 2001 From: Tsygankov Pavel Date: Sat, 14 Nov 2026 07:14:58 +0000 Subject: [PATCH 1/2] =?UTF-8?q?ci:=20=D0=B2=D0=BD=D1=83=D1=82=D1=80=D0=B5?= =?UTF-8?q?=D0=BD=D0=BD=D0=B8=D0=B5=20tools=20=D0=BD=D0=B5=20=D0=B2=D1=85?= =?UTF-8?q?=D0=BE=D0=B4=D1=8F=D1=82=20=D0=B2=20=D0=BF=D1=83=D0=B1=D0=BB?= =?UTF-8?q?=D0=B8=D1=87=D0=BD=D1=8B=D0=B9=20=D1=81=D0=BD=D0=B8=D0=BC=D0=BE?= =?UTF-8?q?=D0=BA=20=E2=80=94=20=D1=88=D0=B0=D0=B3=D0=B8=20=D0=BF=D0=BE?= =?UTF-8?q?=D0=B4=20hashFiles?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/ci.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a6bff7c..a8b84de 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -110,17 +110,21 @@ 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: Смоук потребителя на 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 From 205632662c57df35b38df400310b5b1d83f344bf Mon Sep 17 00:00:00 2001 From: Tsygankov Pavel Date: Sun, 15 Nov 2026 11:02:18 +0300 Subject: [PATCH 2/2] validum 0.5.0 --- .github/workflows/ci.yml | 22 +- .github/workflows/release.yml | 6 +- CHANGELOG.md | 34 +- README.md | 71 +- docs/CLI.md | 55 +- docs/COMPATIBILITY.md | 14 +- docs/DEMO-SCENARIO.md | 644 ------------------ docs/FEATURES.md | 10 +- docs/INTEGRATIONS.md | 2 +- docs/PROJECT.md | 14 +- docs/QUICKSTART.md | 31 +- docs/README.md | 218 ++---- docs/RELEASING.md | 79 --- docs/REST.md | 8 +- docs/ROADMAP-0.4.0.md | 213 ------ docs/ROADMAP.md | 271 -------- docs/SCENARIOS.md | 12 +- docs/TUTORIAL.md | 289 ++++++++ docs/recipes/README.md | 10 +- gradle.properties | 2 +- settings.gradle.kts | 2 +- .../GenerationControllerExportTest.java | 2 +- .../java/ru/validum/cli/DescribeCommand.java | 19 + .../java/ru/validum/cli/GenerateCommand.java | 9 + .../validum/cli/GenerateDocumentsCommand.java | 8 +- .../cli/GenerateIndividualCommand.java | 44 +- .../ru/validum/cli/GenerateIpCommand.java | 4 + .../cli/GenerateOrganizationCommand.java | 4 + .../java/ru/validum/cli/GenerateSpec.java | 5 +- .../java/ru/validum/cli/OutputFormat.java | 5 +- .../java/ru/validum/cli/OutputWriter.java | 12 + .../main/java/ru/validum/cli/SetRunner.java | 276 ++++++++ .../src/main/java/ru/validum/cli/SetSpec.java | 119 ++++ .../java/ru/validum/cli/CardsTableTest.java | 71 ++ .../java/ru/validum/cli/CliSmokeTest.java | 2 +- .../java/ru/validum/cli/GenerateSpecTest.java | 2 +- .../java/ru/validum/cli/NestedFormatTest.java | 56 ++ .../java/ru/validum/cli/SetRunnerTest.java | 127 ++++ .../java/ru/validum/cli/SetSummaryTest.java | 97 +++ .../java/ru/validum/cli/SetTeardownTest.java | 63 ++ .../java/ru/validum/core/card/MirCard.java | 47 ++ .../validum/core/card/MirCardGenerator.java | 94 +++ .../ru/validum/core/card/MirCardOutcome.java | 39 ++ .../java/ru/validum/core/export/CardsCsv.java | 37 + .../ru/validum/core/export/CsvExporter.java | 5 + .../export/IndividualProfileFlattener.java | 16 + .../ru/validum/core/export/NestedWriter.java | 211 ++++++ .../validum/core/export/ProfileFromCsv.java | 30 +- .../core/profile/IndividualProfile.java | 20 +- .../profile/IndividualProfileBuilder.java | 25 + .../profile/IndividualProfileGenerator.java | 15 +- .../java/ru/validum/core/report/Coverage.java | 25 +- .../java/ru/validum/core/sql/TeardownSql.java | 55 ++ .../core/card/MirCardGeneratorTest.java | 72 ++ .../core/export/CardsFlatOutputTest.java | 62 ++ .../validum/core/export/NestedWriterTest.java | 48 ++ .../core/export/ProfileFlattenersTest.java | 12 +- .../core/profile/EmployerLinkTest.java | 48 ++ .../validum/core/report/CardCoverageTest.java | 42 ++ .../ru/validum/core/sql/TeardownSqlTest.java | 50 ++ .../resources/golden/individual-preview.txt | 5 + .../src/test/resources/golden/individual.txt | 10 +- 62 files changed, 2375 insertions(+), 1525 deletions(-) delete mode 100644 docs/DEMO-SCENARIO.md delete mode 100644 docs/RELEASING.md delete mode 100644 docs/ROADMAP-0.4.0.md delete mode 100644 docs/ROADMAP.md create mode 100644 docs/TUTORIAL.md create mode 100644 validum-cli/src/main/java/ru/validum/cli/SetRunner.java create mode 100644 validum-cli/src/main/java/ru/validum/cli/SetSpec.java create mode 100644 validum-cli/src/test/java/ru/validum/cli/CardsTableTest.java create mode 100644 validum-cli/src/test/java/ru/validum/cli/NestedFormatTest.java create mode 100644 validum-cli/src/test/java/ru/validum/cli/SetRunnerTest.java create mode 100644 validum-cli/src/test/java/ru/validum/cli/SetSummaryTest.java create mode 100644 validum-cli/src/test/java/ru/validum/cli/SetTeardownTest.java create mode 100644 validum-core/src/main/java/ru/validum/core/card/MirCard.java create mode 100644 validum-core/src/main/java/ru/validum/core/card/MirCardGenerator.java create mode 100644 validum-core/src/main/java/ru/validum/core/card/MirCardOutcome.java create mode 100644 validum-core/src/main/java/ru/validum/core/export/CardsCsv.java create mode 100644 validum-core/src/main/java/ru/validum/core/export/NestedWriter.java create mode 100644 validum-core/src/main/java/ru/validum/core/sql/TeardownSql.java create mode 100644 validum-core/src/test/java/ru/validum/core/card/MirCardGeneratorTest.java create mode 100644 validum-core/src/test/java/ru/validum/core/export/CardsFlatOutputTest.java create mode 100644 validum-core/src/test/java/ru/validum/core/export/NestedWriterTest.java create mode 100644 validum-core/src/test/java/ru/validum/core/profile/EmployerLinkTest.java create mode 100644 validum-core/src/test/java/ru/validum/core/report/CardCoverageTest.java create mode 100644 validum-core/src/test/java/ru/validum/core/sql/TeardownSqlTest.java diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a8b84de..fa0a994 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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' @@ -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 @@ -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: | @@ -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 @@ -117,6 +117,10 @@ jobs: 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: | @@ -137,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' @@ -162,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' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0bf750d..c122c01 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 9da2e16..b6e568e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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` пишется вторая таблица `-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 @@ -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, которые не выпускались отдельным хотфиксом. @@ -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 diff --git a/README.md b/README.md index 7706e90..8675947 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/docs/CLI.md b/docs/CLI.md index 73243dd..1d7fd9c 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -52,7 +52,7 @@ POST /api/v1/generate/individual/batch } ``` -**P3.3:** в батч можно добавить `"bik": "044525225"` — все профили в пакете получат этот банк. +**P3.3:** в батч можно добавить `"bik": "044525225"` — все профили в батче получат этот банк. Ответ (по умолчанию `json`): `{ "count": 100, "seed": 42, "profiles": [...] }`. @@ -164,7 +164,7 @@ Fat JAR на Picocli. **Без Spring.** ~15 МБ со справочникам # → validum-cli/build/libs/validum.jar ``` -### Быстрый старт +### Справка и знакомство ```powershell java -jar validum.jar --help @@ -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 ``` @@ -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`). ### Где ищется файл diff --git a/docs/COMPATIBILITY.md b/docs/COMPATIBILITY.md index b9e4fc1..e2bfca9 100644 --- a/docs/COMPATIBILITY.md +++ b/docs/COMPATIBILITY.md @@ -64,7 +64,7 @@ golden-фикстурами: SHA-256 каноничного набора для Машинный `csv` не меняется между версиями. `csv-semicolon` — «дружелюбный» профиль: его заголовки и обёртки `="…"` могут уточняться (это не контракт для парсеров; парсить надо `csv`). -**Ошибки.** CLI: код 2 — ошибка ввода/конфигурации (сообщение в stderr, префикс «Ошибка:»). +**Ошибки.** CLI: exit 2 — ошибка ввода/конфигурации (сообщение в stderr, префикс «Ошибка:»). REST: 400 — невалидный ввод, 503 `bik_source_missing` — не найден справочник БИК, 500 — внутренняя ошибка. Код 2 не означает падение. @@ -73,15 +73,21 @@ REST: 400 — невалидный ввод, 503 `bik_source_missing` — не До 1.0 допускаются в минорных версиях, но с двумя условиями: строка в CHANGELOG и обновлённый этот файл. Планируются в 0.5.0: -- перемещение пакетов `ru.validum.core.export` → `format` / `mapping` / `cbr` (импорты у +- перемещение батчов `ru.validum.core.export` → `format` / `mapping` / `cbr` (импорты у потребителей `validum-core` придётся поправить); -- разбиение `DocumentsCsv` на три класса; -- вынос `Builder` из `IndividualProfileGenerator`. +- разбиение `DocumentsCsv` на три класса. + +Вынос `Builder` из `IndividualProfileGenerator` уже сделан в 0.4.0: тип называется +`IndividualProfileBuilder`, точка входа `IndividualProfileGenerator.builder()` не менялась. +Ломается только явное объявление типа `IndividualProfileGenerator.Builder` в коде потребителя. ## 4.1 Что менялось в минорных версиях | Версия | Тип изменения | Что добавилось | |---|---|---| +| 0.4.0 | аддитивное + внутреннее | шесть колонок адресного региона, `passportExpirationDate` («Действителен до»), читаемые эталоны `golden/*-preview.txt`, `--fields` и пресет `short`; реальные почтовые индексы из КЛАДР; билдер вынесен в `IndividualProfileBuilder` (см. раздел 4). Исправлены: `-o` с подкаталогами, `--age-distribution` без диапазона, `--spec` без `ageDistribution`, `--unique-pool` | +| 0.5.0 | аддитивное | связь `employerOgrn` («ОГРН работодателя»), карты «Мир» (`--cards`, колонки `cardPan/cardExpiry/cardOutcome/cardCount`, таблица `*-cards.csv`), формат `json-nested`, набор `type: "set"` и `*-teardown.sql` | +| 0.4.1 | исправление | `?fields=` с `format=json` теперь `400` вместо тихого игнорирования; внешние имена полей не менялись | | 0.3.1 | аддитивное | колонка `passportExpirationDate` («Действителен до») в плоской выдаче и `describe`; срок паспорта по рубежам 20/45; исправления `-o` с подкаталогами, `--age-distribution` без диапазона, `--spec` без `ageDistribution`, `--unique-pool` | Ломающих изменений в 0.3.1 нет: имена и типы существующих полей, сигнатуры и коды ошибок diff --git a/docs/DEMO-SCENARIO.md b/docs/DEMO-SCENARIO.md deleted file mode 100644 index 9657ca1..0000000 --- a/docs/DEMO-SCENARIO.md +++ /dev/null @@ -1,644 +0,0 @@ -# Демо-сценарий validum 0.4.0 — четыре видео + демо-репозиторий - -Полный пошаговый сценарий: воспроизводишь каждый блок руками и показываешь на видео. -Материал разбит на **четыре отдельных видео** по способу подключения — каждый показывает -«что уже можно получить прямо сейчас», не пересекаясь с другими: - -| № | Видео | Кому | Что доказывает | -|---|---|---|---| -| 1 | **CLI** — одна консоль | QA, аналитик, devops | весь продукт без единой строки кода | -| 2 | **Библиотека `validum-core`** | Java-разработчик | генерация внутри своих фикстур/тестов | -| 3 | **REST API** | интегратор, CI | self-host сервис в пайплайне | -| 4 | **Allure extension** | автоматизатор | данные приложены к каждому отчёту | - -## Как читать шаг - -Каждый шаг — три строки: -- **`команда`** или **`код`** — что ввести/написать; -- **Увидишь** — что появится на экране (по этому проверяешь, что всё снято с 0.3.0); -- **Скажи словами** — фраза для видео, объясняющая пользу. - ---- - -## Предпосылки (для всех четырёх видео) - -```powershell -# 1. JDK 17+ (REST-сервис и Allure — 21) -java -version - -# 2. Jar для Видео 1 -# собран релизом: validum-cli\build\libs\validum.jar -# или скачан: https://github.com/Validum-Tech/validum/releases/download/v0.4.0/validum-0.4.0.jar -$jar = ".\validum-cli\build\libs\validum.jar" - -# 3. Справочник ЦБ — обязателен, демо-набора в продукте нет -java -jar $jar fetch-bik -o data\ED807.xml -``` - -В кадре на каждом прогоне CLI должна светиться строка `# validum 0.4.0-SNAPSHOT · seed=…` — это -доказательство, что снято с реального релиза. - ---- - -# Видео 1. CLI — весь продукт одной консолью - -## 1.0 Заставка — 20 секунд - -**Без команд.** Кадр: `validum 0.4.0`, три строки на экране. - -- Скажи: «Validum — генератор тестовых данных, валидных по требованиям Банка России: - ИНН, СНИЛС, ОГРН, счета по 809-П, документы по возрасту, справочник БИК из ED807. - Ноль зависимостей в ядре, ноль генеративных моделей — только алгоритмы. - Четыре способа подключения: CLI, Java-библиотека, REST и Allure-расширение». -- Три цифры в кадре: **860 тестов**, **около 1,4 тыс. участников** в справочнике, - **12 типов счетов**. -- Скажи: «Версия 0.4.0 лежит в Maven Central, код — на GitHub, лицензия Apache-2.0». - -## 1.1 Окружение и справочник - -**`java -jar $jar version`** -- Увидишь: `validum 0.4.0`. -- Скажи: «CLI читает версию из манифеста jar, а не из хардкода». - -**`java -jar $jar participants -f data\ED807.xml`** -- Увидишь: таблица `БИК · PtType · Тип · Корсчёт · Наименование`, в конце — `Всего выведено: 1360` - (число зависит от выгрузки ЦБ — на другой выгрузке будет другое). -- Скажи: «Справочник ED807 — это не "демо-данные", а настоящий справочник участников - платёжной системы Банка России: около 1,4 тыс. участников, из них около 370 банков - с корсчетами — точные числа зависят от выгрузки». - -**`java -jar $jar scenarios`** -- Увидишь: 8 слагов — `adult-resident-with-account`, `adult-resident-without-account`, - `pensioner-male`, `pensioner-female`, `salary-client`, `non-resident-with-residence-permit`, - `serviceman`, `minor`. -- Скажи: «Готовые КУС-сценарии — не "случайные люди", а именно те кейсы, которые - проверяют в онбординге». - -## 1.2 Человек - -**`java -jar $jar generate individual --seed 42 -n 3 --format json-array -o out\people.json`** -- Увидишь: 3 профиля с ИНН, СНИЛС, паспортом, адресом из КЛАДР, банком и счётом. -- Скажи: «Каждый реквизит валиден по алгоритму: ИНН — контрольные разряды, СНИЛС — - контрольное число, счёт — ключ по письму ЦБ № 515. Это не случайные цифры». - -**`java -jar $jar generate individual --seed 7 -n 1000 --age-range 18-70 --format csv -o out\cohort.csv`** -- Увидишь: возраст размазан равномерно от 18 до 70. -- Скажи: «Раньше без параметров генерировалась тысяча 19-летних — это было синтетическим - шумом. Теперь можно задать диапазон». - -**`java -jar $jar generate individual --seed 7 -n 1000 --age-distribution realistic --format csv -o out\cohort-real.csv`** -- Увидишь: когорты 0–6, 7–13, 14–17, 18–24, 25–34 … 80+. -- Скажи: «Набор похож на реальную клиентскую базу — есть дети, взрослые, пенсионеры». - -**`java -jar $jar generate individual --seed 3 -n 5 --age-range 14-60 --documents auto --index --format csv-semicolon -o out\bios.csv`** -- Увидишь: в stderr таблица `№ · Идентификатор · ФИО · Возраст · Регион · Банк · Счёт`. -- Скажи: «`--index` — быстрый оглавление набора: каждому человеку присвоен стабильный - `personId`, по которому его потом можно найти в любом экспорте того же seed». - -## 1.3 Карточка человека - -**`java -jar $jar describe --file out\bios.csv --row 2`** -- Увидишь: блоки `[Кто] [Проверки] [Паспорт] [Дополнительные документы] [Адреса] [Банк и счёт] [Флаги]`; - проверки ИНН/СНИЛС/счёта — `✓`; паспорт с «кем выдан» из региона серии и кодом - подразделения `77X-XXX`; у 20-летнего — права и военный билет, у 15-летнего — только паспорт. -- Скажи: «Документы согласованы с датой рождения: паспорт не выдан в 3 года, права не в 16, - военный билет не у 40-летней женщины. А `describe` — это "прочитай этого человека": поймал - баг → приложил карточку клиента вместо гадания». - -## 1.4 Реальность - -### Боль, которую лечим (30 секунд — снять до команд) - -Кадр: обычный CSV (`--format csv`) открыт в русском Excel. Видно: -`5,86E+11` вместо ИНН, `1,07E+10` вместо СНИЛС, `053796` превратился в `53796`, -20-значный счёт обрезан до `4,08178E+19`, дата — `#######`. - -- Скажи: «Это не ошибка генератора — это Excel угадывает типы. Поэтому есть - второй CSV-профиль: `csv-semicolon`. Смотрим, что он делает иначе». - -**`java -jar $jar generate individual --seed 11 -n 2 --residency non-resident --country KZ --age 34 --format json-array -o out\kz.json`** -- Увидишь: `passportType: FOREIGN`, `passportCountry: KZ`, адрес «Казахстан, г. Алматы…», - `isResident: false`, `citizenship: KZ` — при этом банк и счёт российские. -- Скажи: «Трансграничный кейс: иностранец обслуживается в РФ. ДУЛ, адрес, резидентство — - всё согласовано, без ручной правки». - -**`java -jar $jar describe --file out\kz.json --row 1`** -- Увидишь: в `[Паспорт]` — `Тип: FOREIGN`, `Страна: KZ`; в `[Флаги]` — `Резидент: false`, - `Гражданство: KZ`; адрес «Казахстан, г. Алматы…»; банк и счёт — российские. -- Скажи: «То же самое глазами: не нужно вчитываться в JSON, чтобы увидеть страну паспорта - и адрес. Сравни с карточкой резидента из 1.3 — вот разница, которую обычно набивают руками». - -**`java -jar $jar generate individual --seed 5 -n 3 --format csv-semicolon -o out\excel.csv`** -- Увидишь (открой в Excel): ИНН, СНИЛС, счёт, корсчёт, индекс `053796` — текстом, - без `5,86E+11`, без потери разрядов; заголовки русские. -- Скажи: «Обычный CSV Excel ломает: ИНН превращает в экспоненту, у 20-значного счёта теряет - разряды. Формат `csv-semicolon` пишет кодовые поля как `="…"` — Excel показывает как текст». - -**`java -jar $jar coverage --file out\excel-saved.csv`** — тот же файл после «Сохранить» в Excel -```powershell -# Excel → открыть out\excel.csv → Сохранить как → out\excel-saved.csv (CSV, разделитель ;) -# Не сохранял — проверь исходный файл: coverage понимает и «;», и формулы ="…" -java -jar $jar coverage --file out\excel.csv -``` -- Увидишь: `inn`, `snils`, `account`, `bankBik` — `0` невалидных, индекс `053796` на месте. -- Скажи: «Excel пересохранил файл — и мы это проверили, а не поверили. Если бы Excel съел - разряды или ведущий ноль, `coverage` показал бы это в колонке "невалидных". Именно так - ловят порчу данных при обмене наборами между командами». - -**`generate --spec` требует файл — сначала пишем спецификацию, потом генерируем** -```powershell -$spec = @' -{ "type": "individual", "count": 50, "seed": 20261113, "asOf": "2026-11-13", - "format": "csv-semicolon", "ageRange": "25-54", "documents": "auto", "region": "77" } -'@ -# Set-Content -Encoding utf8 в PowerShell 5.1 пишет BOM и портит кириллицу; -# надёжный способ — явный UTF-8 без BOM: -[IO.File]::WriteAllText("out\set.json", $spec, (New-Object System.Text.UTF8Encoding($false))) -Get-Content out\set.json -Encoding utf8 | Select-Object -First 1 # проверить, что файл читается -``` -**`java -jar $jar generate --spec out\set.json -o out\clients.csv`** -```json -{ - "type": "individual", "count": 50, "seed": 20261113, "asOf": "2026-11-13", - "format": "csv-semicolon", "ageRange": "25-54", "documents": "auto", "region": "77" -} -``` -- Увидишь: тот же набор из одного файла. -- Скажи: «Данные — это код: набор воспроизводим в CI, ревьюится в PR, версионируется вместе - с тестами. Стенд больше не ломается от "у тебя не тот CSV"». - -**`$spec.Replace('"seed"', '"sed"') | Set-Content out\set-typo.json -Encoding utf8`** -**`java -jar $jar generate --spec out\set-typo.json`** -- Увидишь: `Ошибка: Неизвестные ключи: sed. Допустимые: …`, код возврата 2. -- Скажи: «Спецификация строгая: опечатка не молча игнорируется, как в YAML-конфигах, - а называется по имени. Набор нельзя "починить не туда"». - -## 1.5 Надёжность - -**`java -jar $jar generate individual --seed 1 -n 50 --unique --format csv -o out\unique.csv`** -- Увидишь: 50 строк, ИНН без повторов. -- Скажи: «Уникальность гарантируется, а не "надеемся на вероятность"». - -**`java -jar $jar generate individual --seed 1 -n 11 --unique --unique-pool 10`** -- Увидишь: `Ошибка: пул исчерпан: выдано 10 из 10 вариантов ИНН; увеличьте --unique-pool или уменьшите -n`, - код возврата 2. -- Скажи: «Пул ИНН — 10 миллиардов, но если ты просишь 11 из 10, продукт честно откажет - до генерации, а не после 40 минут работы. Так же он посчитает, что 700 000 уникальных - ИНН из пула 676 000 невозможны». - -**`java -jar $jar generate individual --seed 4 -n 10 --corrupt inn,snils --format csv-semicolon -o out\bad.csv`** -**`java -jar $jar coverage --file out\bad.csv`** - -> Каждая строка с командой — **отдельный** вызов. Если склеить две команды в одну строку, picocli ответит `Unmatched arguments from index …` — это не сбой продукта. -- Увидишь: `# испорчено: inn,snils` в stderr; в отчёте `inn: 10/10 невалидных`, - `snils: 10/10 невалидных`, остальное чисто. -- Скажи: «Управляемый негатив — ровно одна ошибка в нужном поле. Идеальный вход для теста - "наша система обязана отклонить такой файл"». - -**`java -jar $jar coverage --file out\cohort-real.csv`** -- Увидишь: таблица «поле / заполнено % (N/M) / различных / невалидных», `Согласованность: - нарушений нет`, распределения (пол, резидентство, регион, банк, семья, возраст). -- Скажи: «Качество набора проверяется машинно: документ/возраст, регион паспорта и прописки, - счёт/БИК. Если данные испорчены на входе — нарушение будет названо текстом». - -## 1.6 ИП и организации - -**`java -jar $jar generate ip --seed 8 -n 2 --region 77 --okved 62.01 --format json-array -o out\ip.json`** -- Увидишь: ОГРНИП, ИНН, ОКВЭД, счёт 40802. -- Скажи: «Тот же конвейер для ИП — валидный ОГРНИП и счёт, привязанный к БИК». - -**`java -jar $jar generate organization --seed 9 -n 2 --type LLC --region 77 --format json-array -o out\org.json`** -- Увидишь: ОГРН, ИНН, КПП, ОКПО, ОКВЭД, банк и расчётный счёт 40702. -- Скажи: «ОПФ — ООО, АО, ПАО, НКО, фонд, ГУП, МУП; реквизиты юридического лица согласованы». - -## 1.7 Валидация и дозаполнение - -**`java -jar $jar validate inn 7707083893`** → `валиден`; **`java -jar $jar validate inn 7707083892`** → `не валиден`. -- Скажи: «Та же валидация, что и при генерации, доступна как самостоятельная команда. - Типы: inn, snils, ogrn, ogrnip, account, kpp, okpo, bik». - -**`java -jar $jar fill individual -i out\people-partial.csv -o out\people-filled.csv`** -```powershell -# 1) готовим входной CSV и руками оставляем пробелы (Excel/блокнот: удалить СНИЛС и счёт у второй строки) -java -jar $jar generate individual --seed 5 -n 2 --format csv -o out\people-partial.csv -# 2) дозаполняем -java -jar $jar fill individual -i out\people-partial.csv -o out\people-filled.csv -``` -- Увидишь: пустые ячейки заполнены, непустые не тронуты. -- Скажи: «Дозаполнение: приходит CSV с пробелами — продукт достраивает только пустое». - -## 1.8 Обмен с ЦБ и засев БД - -**`java -jar $jar export ed807 -f data\ED807.xml -t 20 -l 5 -o out\ed807.xml`** -**`java -jar $jar export ed808 -b 044525225 -f data\ED807.xml -o out\ed808.xml`** -- Увидишь: XML по схемам ЦБ (`urn:cbr-ru:ed:v2.0`, кодировка windows-1251). -- Скажи: «Продукт понимает не только клиентов, но и расчётную инфраструктуру ЦБ». - -**`java -jar $jar generate individual --seed 9 -n 100 --format sql --dialect postgres --table clients -o out\seed.sql`** -- Увидишь: `CREATE TABLE` + `INSERT`, шапка `-- validum 0.4.0, seed=9`. -- Скажи: «Стенд "с нуля" одной командой: `psql -f seed.sql`». - -## 1.9 Воспроизводимость - -**`java -jar $jar generate individual --seed 1234 --as-of 2026-01-15 -n 3 --format csv -o out\a1.csv`** -**`java -jar $jar generate individual --seed 1234 --as-of 2026-01-15 -n 3 --format csv -o out\a2.csv`** -**`Get-FileHash out\a1.csv, out\a2.csv`** -- Увидишь: хеши совпадают. -- Скажи: «Один seed + фиксированная дата расчёта `asOf` = побитово один и тот же набор. - В тестах это закреплено SHA-256 golden-фикстурами». - ---- - -## 1.10 Цена ошибки — что было бы без validum - -**`java -jar $jar generate individual --seed 3 -n 1 --bik 044525225 --format csv -o out\one.csv`** -```powershell -$row = Import-Csv out\one.csv | Select-Object -First 1 -java -jar $jar validate inn $row.inn # валиден -java -jar $jar validate inn 7707083892 # не валиден (тот же ИНН, последняя цифра на 1) -``` -- Увидишь: первая команда — `{"valid":true,…}`, вторая — `{"valid":false,…}` и **код возврата 1**. -- Скажи: «Faker и его аналоги выдают правдоподобные номера. Валидатор на стенде падает не - на бизнес-логике, а на данных: ИНН не проходит контрольную сумму. Validum выдаёт только - то, что проходит. И эту проверку можно вставить в свой пайплайн — код возврата 1». - -**`java -jar $jar validate snils $row.snils`** — валиден. -> `$row` живёт только в текущем окне PowerShell: после перезапуска консоли сначала выполните -> `Import-Csv out\one.csv | Select-Object -First 1`. Пустая переменная превращается в пустую -> строку, и picocli ответит «Missing required parameter: ''» — это ваш PowerShell, а не продукт. -**`java -jar $jar validate account $row.account --bik $row.bankBik`** — валиден. -**`java -jar $jar validate account $row.account --bik 044030653`** — **не** валиден. -- Скажи: «Счёт валиден только вместе со своим банком: контрольный ключ по письму ЦБ № 515 - считается от БИК. Подменили БИК — счёт перестал проходить. Это ловит ошибку - «скопировали счёт из другого стенда»». - -**`java -jar $jar validate bik $row.bankBik`** — валиден. Для КПП нужен профиль юрлица: - -**`java -jar $jar generate organization --type SE --seed 4 -n 1 --format csv -o out\one-org.csv`** -```powershell -$org = Import-Csv out\one-org.csv | Select-Object -First 1 -java -jar $jar validate kpp $org.kpp -``` -- Скажи: «Семь типов реквизитов одной командой: `inn`, `snils`, `ogrn`, `ogrnip`, `account`, - `kpp`, `okpo`, `bik` — и у каждого свой набор правил: где формат, где контрольная сумма, - а у счёта ещё и БИК». - -## 1.11 Негатив по требованию - -**`java -jar $jar generate individual --seed 4 -n 2 --terrorist --blocked --format json-array -o out\aml.json`** -- Увидишь: `"terrorist": true`, `"blocked": true` у обоих профилей, остальные реквизиты — валидные. -- Скажи: «AML-сценарии: клиент из перечня и клиент с блокировкой. Данные остаются валидными — - ломается ровно тот флаг, который нужен тесту». - -**`java -jar $jar generate documents --type 22 -n 2 --format json-array -o out\passports.json`** -- Увидишь: серия, номер, кем выдан, дата выдачи, код подразделения — без профиля человека. -- Скажи: «Бывает, что нужны только документы: тестируем валидатор ДУЛ, а человека не генерируем». - -## 1.12 Документы отдельной таблицей - -**`java -jar $jar generate individual --seed 12 -n 3 --age 30 --documents auto --documents-mode split --format csv -o out\people-docs.csv`** -- Увидишь: два файла — `out\people-docs.csv` и рядом `out\people-docs-documents.csv` - (колонки `profileKey`, `spdulCode`, `title`, `series`, `number`, …). -- Скажи: «Документы — отдельная таблица, как в реальной модели данных. Связь — по идентификатору профиля». - -**`java -jar $jar fill individual -i out\people-docs.csv -o out\people-back.csv --documents-file out\people-docs-documents.csv`** -- Увидишь: колонка `documents` заполнена теми же документами, что были во второй таблице. -- Скажи: «И обратно: две таблицы склеиваются по ключу — так данные едут из АБС в тест и назад». - -## 1.13 Участники ЦБ по типам и офлайн-путь - -**`java -jar $jar participants -f data\ED807.xml --type 20`** -- Увидишь: только банки — в конце `Всего выведено: N` (в выгрузке 2026 года N ≈ 368, точное число - зависит от версии справочника — говори «около 370»). -- Скажи: «Справочник — это около 1,4 тыс. участников: банки, РКЦ, казначейство. Для генерации - нужны банки — фильтр по типу PtType=20, и их около 370». - -**`java -jar $jar fetch-bik --offline -o data\ED807.xml`** -- Увидишь: `Режим --offline: скачивание не выполняется` и ссылка на файл, код возврата 0. -- Скажи: «В банковском контуре cbr.ru закрыт: продукт не пытается лезть в сеть, а объясняет, - что положить в `data`». - -## 1.14 Адрес из КЛАДР и ОКВЭД - -**`java -jar $jar generate ip --seed 8 -n 1 --region 50 --okved 62.01 --format csv -o out\ip-okved.csv`** -```powershell -Import-Csv out\ip-okved.csv | Select-Object okved, okvedName, registrationCity, registrationStreet, registrationPostalCode -``` -- Увидишь: `62.01` и его расшифровка, город и улица из КЛАДР, индекс по региону. -- Скажи: «Адрес — не случайная строка: 1,99 млн улиц, 16 регионов, индекс и город согласованы. - ОКВЭД проверяется по справочнику ОК 029-2014 (3069 позиций): ни одного кода вне классификатора». - ---- - -# Видео 2. Библиотека `validum-core` (Java) - -## 2.1 Подключение - -```kotlin -// build.gradle.kts -implementation("io.github.validum-tech:validum-core:0.4.1") -``` -- Увидишь: jar скачивается из Maven Central, `repositories { mavenCentral() }` уже есть. -- Скажи: «`validum-core` — обычная библиотека из Central: без Spring, без сети, ноль - зависимостей. Единственный внешний артефакт — справочник ЦБ». - -## 2.2 Генерация одного человека - -```java -import ru.validum.core.bank.*; -import ru.validum.core.profile.*; -import java.nio.file.Path; - -BikSource bik = BikSources.resolve(Path.of("data/ED807.xml")); - -IndividualProfile p = IndividualProfileGenerator.builder() - .seed(42) - .ageRange(25, 54) - .documentsAuto() - .region(Region.MOSCOW) - .bikSource(bik) - .build() - .generate(); - -p.fullName(); p.gender(); p.age(); p.inn(); p.snils(); -p.passport().series(); p.passport().number(); -p.registrationAddress(); p.account(); -``` -- Увидишь: объект профиля, все поля доступны типизированно. -- Скажи: «Builder — весь набор опций генератора: seed, asOf, age/ageRange/ageDistribution, - gender, region, residency, country, bikSource/bik/bank, passportType, passportCountry, - documents/documentsAuto, corrupt, terrorist, blocked, familyStatus, categoryClient, - personalManager, email, secretWord». - -## 2.3 ИП и организации из того же seed - -```java -IndividualProfileGenerator base = IndividualProfileGenerator.builder().seed(42).bikSource(bik).build(); -IpProfile ip = IpProfileGenerator.generate(base, 42, "62.01"); -OrganizationProfile org = OrganizationProfileGenerator.builder().seed(42).region(Region.MOSCOW).build().generate(); -``` -- Скажи: «ИП строится от профиля-человека, организация — своим билдером; реквизиты - согласованы внутри каждой сущности». - -## 2.4 Участники и счета - -```java -ParticipantRegistry registry = BikRegistryLoader.loadRegistry(Path.of("data/ED807.xml")); -registry.size(); // ≈1,4 тыс. -registry.banks().size(); // ≈370 -registry.findByBik("044525225"); // Сбербанк - -AccountValidator.isValid("40817810600000000001", AccountType.CLAC, "044525225"); -AccountGenerator.generate(AccountType.CLAC, "044525225", new java.util.Random(1)); -``` -- Скажи: «12 типов счетов (BANA, CBRA, CRSA, TRSA, CLRA, EPGA, EPSA, GARA, TRUA, UTRA, - CLAC, CBDC), ключ по письму № 515 зависит от типа счёта и БИК». - -## 2.5 Экспорт ED807 / ED808 - -```java -String xml = Ed807Exporter.toXml(registry.all(), header, Ed807Exporter.Defaults.moscow()); -byte[] ed808 = Ed808Exporter.toBytes(registry, "044525225", header, defaults, seed); -``` -- Скажи: «Экспортёры ЦБ вызываются из кода — можно встроить выгрузку в свой конвейер». - -## 2.6 Готовые сценарии - -```java -IndividualProfile pensioner = IndividualScenarios.createPensionerFemale(1); -IndividualProfile minor = IndividualScenarios.createMinor(2); -// или по слагу: -IndividualProfile salary = ScenarioCatalog.bySlug("salary-client").get().withSeed(3); -``` -- Увидишь: 8 сценариев (взрослый с/без счёта, пенсионер м/ж, зарплатный, нерезидент с ВНЖ, - военнослужащий, несовершеннолетний). -- Скажи: «КУС-кейсы как методы — не нужно собирать профиль руками под каждый тест». - -## 2.7 Детерминизм и personId - -```java -String id1 = PersonIds.of(42); -PersonIds.isValid(id1); // true -IndividualProfile a = IndividualProfileGenerator.builder().seed(42).asOf(LocalDate.of(2026,1,15)).bikSource(bik).build().generate(); -IndividualProfile b = IndividualProfileGenerator.builder().seed(42).asOf(LocalDate.of(2026,1,15)).bikSource(bik).build().generate(); -a.equals(b); // true -``` -- Скажи: «`personId` — стабильный идентификатор от seed; два генератора с одним seed и - `asOf` дают идентичный профиль». - ---- - -## 2.8 Двенадцать типов счетов - -```java -AccountGenerator gen = new AccountGenerator(new Random(7)); -String bik = "044525225"; // ПАО Сбербанк - -String client = gen.generate("40817", AccountType.EPGA, bik); // 20 цифр, ключ по 515 -String corr = gen.generate("30101", AccountType.BANA, bik); // корсчёт банка -System.out.println(client + " " + AccountValidator.isValidAuto(client, bik)); // true -System.out.println(corr + " " + AccountValidator.isValid(corr, AccountType.BANA, bik)); // true -System.out.println(AccountValidator.isValidAuto(client, "044030653")); // false — не его банк -``` -- Увидишь: три `true`/`false` ровно как в комментариях; счета 20-значные. -- Скажи: «`AccountType` — 12 типов из классификатора УФЭБС: клиентский, расчётный, корсчёт, - транзитный, накопительный. Тип влияет на то, из какого БИК берётся условный номер подразделения, - поэтому счёт нельзя проверять «сам по себе» — только вместе с банком». - ---- - -# Видео 3. REST API - -Запуск: `java -jar validum-api-0.4.0.jar` (Spring Boot, порт 8080). Справочник берётся из -`data/ED807.xml` рядом или через переменную `validum.bik.file`. - -## 3.1 Генерация и заголовки воспроизводимости - -```bash -curl -s -D - "http://localhost:8080/api/v1/generate/individual?seed=42" -``` -- Увидишь: JSON профиля и заголовки **`X-Validum-Version: 0.4.0`** и **`X-Validum-Seed: 42`**. -- Скажи: «Пайплайн может записать в отчёт, каким seed и какой версией получены данные — - воспроизводимость не "на словах"». - -## 3.2 Пакеты и форматы - -```bash -curl -s -X POST "http://localhost:8080/api/v1/generate/individual/batch?count=5&format=csv-semicolon" -o batch.csv -curl -s -X POST "http://localhost:8080/api/v1/generate/ip/batch?count=3&format=json-array" -curl -s -X POST "http://localhost:8080/api/v1/generate/organization/batch?count=3&format=json-array" -``` -- Увидишь: `batch.csv` с русскими заголовками и `="…"`. -- Скажи: «Три сущности, батчи, форматы json / json-array / csv / csv-semicolon / sql». - -## 3.3 Дозаполнение - -```bash -curl -s -X POST "http://localhost:8080/api/v1/fill/individual" \ - -H "Content-Type: application/json" -d '{"fullName":"Иванов Иван","gender":"MALE"}' -``` -- Увидишь: пустые поля достроены, заданные не тронуты. - -## 3.4 Валидация - -```bash -curl -s -X POST "http://localhost:8080/api/v1/validate/inn" -H "Content-Type: application/json" -d '"7707083893"' -``` -- Увидишь: `{ "valid": true }`. Типы: inn, snils, ogrn, ogrnip, account, kpp, okpo, bik. - -## 3.5 Сценарии и экспорт - -```bash -curl -s "http://localhost:8080/api/v1/scenarios" -curl -s -X POST "http://localhost:8080/api/v1/scenarios/pensioner-female?seed=1" -curl -s "http://localhost:8080/api/v1/export/ed807" -curl -s "http://localhost:8080/api/v1/export/ed808?bik=044525225" -``` -- Скажи: «Сценарии и ЦБ-экспорт доступны и по HTTP — для сервисных интеграций». - -## 3.6 Ошибки честные: 400 - -```powershell -'{"seed":1,"gender":"WRONG","region":"MOSCOW"}' | Set-Content bad-body.json -Encoding utf8 -curl -s -w "`nHTTP %{http_code}`n" -X POST http://localhost:8080/api/v1/generate/individual ` - -H "Content-Type: application/json" -d "@bad-body.json" -``` -- Увидишь: **400** и тело с полем `message` — сервис отвечает по-человечески и не отдаёт 500. -- Скажи: «Ошибка входа — это 400 с объяснением. 500 в тестовом стенде означает, что сломались - мы, а не тест». - ---- - -## 3.7 Ошибка честная: 503 вместо пустого ответа - -Запусти сервис **без** `data\ED807.xml` и без `VALIDUM_BIK_FILE` (например, из пустого каталога): - -```powershell -java -jar validum-api\build\libs\validum-api-0.4.0.jar -# в соседнем окне, из каталога без data\ED807.xml -'{"seed":1,"gender":"MALE","region":"MOSCOW"}' | Set-Content body.json -Encoding utf8 -curl -s -w "`nHTTP %{http_code}`n" -X POST http://localhost:8080/api/v1/generate/individual ` - -H "Content-Type: application/json" -d "@body.json" -``` -- Увидишь: `HTTP 503` и тело `{"error":"bik_source_missing","message":"Не найден справочник БИК … скачать: validum fetch-bik"}`. -- Скажи: «Нет справочника — сервис не делает вид, что банк сгенерирован: он отвечает 503 и говорит, - чем это лечится. Пустой массив или случайный БИК сломали бы тест позже и молча». - ---- - -# Видео 4. Allure extension - -## 4.1 Подключение - -```kotlin -testImplementation("io.github.validum-tech:validum-allure:0.4.1") -testRuntimeOnly("io.qameta.allure:allure-junit5:2.35.3") // ваша версия Allure -``` -- Скажи: «Расширение **не навязывает** версию Allure — зависит от `allure-java-commons` - как `compileOnly`, поэтому работает и с 2.29, и с 2.35». - -## 4.2 Аннотации - -```java -import ru.validum.allure.ValidumGenerate; -import ru.validum.allure.ValidumSeed; - -class DepositTest { - @Test - @ValidumGenerate(seed = 42, age = 16, region = "MOSCOW", gender = "MALE") - void minorCannotOpenDeposit() { /* тело теста */ } - - @Test - @ValidumSeed(7) - void deterministicCase() { /* тело теста */ } -} -``` -- Увидишь: расширение генерирует профиль **до** теста и кладёт его в контекст. - -## 4.3 Что видно в Allure - -- Увидишь: рядом с шагом — attachment **«Validum Profile»** с полным JSON профиля. -- Скажи: «Данные не "где-то сгенерированы", а приложены к каждому отчёту — разбор падения - не требует догадок». - ---- - -# Демо-репозиторий `validum-demo` (публичный) - -**Зачем.** Сейчас у продукта нет живого примера «как подключить и что получается» — это -главный пробел для нового пользователя. Публичный репозиторий закрывает его и даёт: -`Used By` на Maven Central, площадку для статей, готовые команды для видео (линки в README), -один `git clone` вместо инструкции. - -**Что внутри — и как это ложится на видео:** - -``` -validum-demo/ -├── README.md ← 6 команд из Видео 1 + скриншоты + ссылки на видео -├── cli/ ← Видео 1 -│ ├── run.ps1 ← сценарий из Видео 1 целиком -│ └── specs/*.json ← наборы как код -├── core/ ← Видео 2 -│ ├── build.gradle.kts ← validum-core:0.4.1 -│ └── src/test/java/DemoCoreTest.java -├── api/ ← Видео 3 -│ ├── docker-compose.yml ← REST-сервис одной командой -│ └── requests.http ← curl'ы из Видео 3 (для IDEA HTTP Client) -├── allure/ ← Видео 4 -│ ├── build.gradle.kts ← validum-allure + allure-junit5 -│ └── src/test/java/DepositTest.java -├── out/ ← эталонные выводы (обновляются релизом) -│ ├── clients.csv / excel.png / unique-fail.txt -└── .github/workflows/demo.yml ← generate → coverage → публикация out/ -``` - -**Что можно показывать в репо:** -1. `git clone` → `cd cli` → `./run.ps1` → за минуту весь Видео 1. -2. `docker compose up` в `api/` → REST-сервис без локальной сборки. -3. `core/` и `allure/` — примеры `build.gradle.kts` для копипаста в свой проект. -4. CI: пушишь в репо → workflow генерирует набор, прогоняет `coverage` и публикует `out/` - как артефакт — наглядная демонстрация «данные как код». - -**Что НЕ класть в репо:** `data/ED807.xml` (тяжёлый, скачивается в CI через `fetch-bik`), -внутренние скрипты сборки релиза, ключи/секреты. - ---- - -## Проверить всё сразу (без съёмки) - -Сценарий можно прогнать машинно: те же команды, но с проверками (код возврата, поля, -отсутствие регрессий). Пишет отчёт и складывает stdout/stderr каждой команды. -Скрипт живёт в приватном репозитории (`tools/demo-check.py` + обёртка `tools/demo-check.ps1`), -в публичную сборку не входит. - -```powershell -.\gradlew :validum-cli:shadowJar -.\tools\demo-check.ps1 # всё, включая Excel-формат -.\tools\demo-check.ps1 -SkipExcel # без дружелюбного CSV -.\tools\demo-check.ps1 -SelfTest # проверить сам скрипт, java не нужна -``` - -Результат — `out\demo-check\report.md`: таблица «шаг → статус → что не так», рядом -`env.txt` (хеш jar, версия Java, размер справочника) и по папке на каждый шаг -(`stdout.txt`, `stderr.txt`, `command.txt`). Скрипт ничего не меняет в репозитории. - -## Чек-лист перед съёмкой - -- [ ] каждая команда прогнана **на 0.4.0**, в кадре строка `# validum 0.4.0-SNAPSHOT · seed=…`; -- [ ] `data/ED807.xml` свежий (не старше месяца); -- [ ] Excel-кадр: ИНН текстовый (слева, без `E+11`), счёт 20 цифр, индекс `053796`; -- [ ] в `describe` рядом виден регион серии = регион прописки; -- [ ] отказ `--unique` показан целиком, включая код возврата 2; -- [ ] **все файлы в `out\` перегенерированы после свежей сборки** (`shadowJar`), иначе в кадре - старый набор без новых колонок — например, без «Действителен до»; -- [ ] консоль в UTF-8 (`chcp 65001`), иначе кириллица в кадре будет кракозябрами. - -## Порядок съёмки - -1. **Видео 1 (CLI)** — самое длинное, оно «продаёт» продукт; остальные три — короткие, - по 2–3 минуты, со ссылкой «детали — в Видео 1». -2. **Видео 2 (core)** — для разработчиков, врезка «добавил одну зависимость → получил - валидный профиль». -3. **Видео 3 (API)** — для тех, кто хочет сервис, а не библиотеку. -4. **Видео 4 (Allure)** — для автоматизаторов: «данные в каждом отчёте». -5. После видео — **`validum-demo`**: README уже ссылается на все четыре ролика. diff --git a/docs/FEATURES.md b/docs/FEATURES.md index ec818a2..2d41a9f 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -28,7 +28,7 @@ - Поддерживает **каскадные дефолты**. - **Пакетную генерацию** — до 10 000 профилей. - **8 эндпоинтов валидации**. -- **Экспорт** — JSON, JSON-массив, CSV. +- **Экспорт** — JSON, JSON-массив, вложенный JSON, CSV (машинный и для Excel), SQL. - **CLI без Spring** — fat JAR на Picocli (P3.1). - **Allure Extension** для JUnit 5 (P3.2). - **Явный выбор банка** — `.bik` / `.bank` (P3.3). @@ -45,7 +45,7 @@ | **Каскадные дефолты** | Задаёшь `age=16` — система сама делает несовершеннолетнего | | **Три типа субъектов** | ФЛ, ИП, ЮЛ (7 ОПФ) | | **Четыре способа использовать** | REST API · CLI · Java-библиотека · Allure Extension | -| **Пакетная генерация** | 3 эндпоинта `/batch`, до 10 000 профилей | +| **Batch** | 3 endpoint'а `/batch`, до 10 000 профилей | | **Валидация** | **8 эндпоинтов** + 8 типов в CLI | | **Экспорт** | JSON, JSON Array, CSV с UTF-8 BOM. `CsvExporter` — в core | | **Явный банк (P3.3)** | `.bik` / `.bank` для ФЛ и ИП. Невалидный → 400 / exit 2 | @@ -58,7 +58,7 @@ ## ✅ Что уже работает -### Ядро `validum-core` — 651 тест +### Ядро `validum-core` — 679 тестов | Генератор / Валидатор | Что делает | |---|---| @@ -77,6 +77,8 @@ | `OrganizationProfileGenerator` | Профиль ЮЛ (7 ОПФ, P2.2) + ОКВЭД-2 | | `OkvedGenerator` / `OkvedRegistry` | ОКВЭД-2: 3069 позиций, код + наименование | | `CsvExporter` + 3 флаттенера | Плоский CSV (P3.1a). Общий для API, CLI, Allure | +| `MirCardGenerator` | Карты «Мир»: BIN 220000–220499, Луна, срок +2…+5 лет, 6 исходов операции | +| `IndividualProfile.employerOgrn` | Связь «человек → работодатель» (ОГРН организации) | | 7 валидаторов | ИНН, СНИЛС, ОГРН, ОГРНИП, КПП, ОКПО, БИК | ### API `validum-api` — 88 тестов @@ -87,7 +89,7 @@ - **Экспорт (P1.4):** `?format=json|json-array|csv`. - **P3.3:** `bik` в DTO, `GlobalExceptionHandler → 400` на `IllegalArgumentException`. -### CLI `validum-cli` — 100 тестов (P3.1b + P3.3) +### CLI `validum-cli` — 114 тестов (P3.1b + P3.3) Fat JAR на Picocli, **без Spring** (~15 МБ вместе со справочниками КЛАДР и ОКВЭД, старт ~300 мс). diff --git a/docs/INTEGRATIONS.md b/docs/INTEGRATIONS.md index 5202462..e1d2113 100644 --- a/docs/INTEGRATIONS.md +++ b/docs/INTEGRATIONS.md @@ -5,7 +5,7 @@ Java-библиотека и JUnit 5 + Allure: как подключить valid ## 🎭 Allure Extension (P3.2) ```kotlin -testImplementation("io.github.validum-tech:validum-allure:0.4.1") +testImplementation("io.github.validum-tech:validum-allure:0.5.0") ``` ```java diff --git a/docs/PROJECT.md b/docs/PROJECT.md index 2370ffc..f57c1f2 100644 --- a/docs/PROJECT.md +++ b/docs/PROJECT.md @@ -88,7 +88,7 @@ validum/ - REST API + Swagger UI + Actuator + Docker - Каскадные дефолты, флаги, ЮЛ/ИП - **P0.1–P0.3** — ФИО (3.8 млн), адреса (320 / 16), email/слова/менеджеры -- **P1.2–P1.4** — batch, validation, экспорт +- **P1.2–P1.4** — батчный, validation, экспорт - **P2.2–P2.3** — 7 ОПФ, ОКПО/ОГРНИП, расширенный КПП - **P3.1** — CLI + CSV в core - **P3.2** — Allure Extension @@ -100,7 +100,7 @@ validum/ ### 📅 Отложено / Backlog -- **P1.1** — первая публикация в Maven Central (код готов, нужны секреты — см. `docs/RELEASING.md`) +- **P1.1** — первая публикация в Maven Central (код готов, нужны секреты — см. `CONTRIBUTING.md`) - **P2.1** — Транзакции - **P3.4** — Mock API по OpenAPI (3–5 дней) - **P4.2–P4.4** — Иностранные паспорта, Web UI, ML-датасеты @@ -113,12 +113,12 @@ validum/ | Что | Где взять | |---|---| -| Fat jar `validum.jar` (+ `.sha256`) | [GitHub Releases](https://github.com/Validum-Tech/validum/releases) | +| Fat JAR `validum.jar` (+ `.sha256`) | [GitHub Releases](https://github.com/Validum-Tech/validum/releases) | | Java-библиотеки (`validum-core`, `validum-allure`, …) | Maven Central: `io.github.validum-tech:*:0.3.1` (с первого релиза в Central; подключать репозиторий не нужно) | | Контейнер API | `docker compose up` локально; Docker Hub — после 0.2 | | Исходники | `git clone` → `./gradlew build` | -Как выпускается версия (тег, секреты, Maven Central) — [`docs/RELEASING.md`](RELEASING.md). +Как выпускается версия (тег, CI, Maven Central) — [`CONTRIBUTING.md`](../CONTRIBUTING.md). Что мы гарантируем потребителю (JDK, зависимости, контракт вывода, ломающие изменения) — [`docs/COMPATIBILITY.md`](COMPATIBILITY.md). --- @@ -137,10 +137,10 @@ validum/ 1. Форк → ветка `feature/my-feature` 2. Тесты **до** реализации -3. `./gradlew build` — все 860 зелёные, покрытие не падает +3. `./gradlew build` — все 906 зелёные, покрытие не падает 4. PR — CI прогонит сборку на Linux и Windows -Подробности и чек-лист — [`CONTRIBUTING.md`](CONTRIBUTING.md). -Уязвимости — не в Issues, а на `security@validum.tech` ([`SECURITY.md`](SECURITY.md)). +Подробности и чек-лист — [`CONTRIBUTING.md`](../CONTRIBUTING.md). +Уязвимости — не в Issues, а на `security@validum.tech` ([`SECURITY.md`](../SECURITY.md)). --- diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index b1473b0..7dc054d 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -14,25 +14,14 @@ Validum создаёт **вымышленные** данные для тесто данных клиентов, — но ответственность за то, что вы генерируете и куда кладёте, остаётся на операторе. -## 🚀 Быстрый старт +## 🚀 Первый прогон -Три команды — от нуля до данных. Нужен только JDK 17+ (или Docker). +Первые команды и объяснение, что происходит, — в [туториале](TUTORIAL.md) +и в [README](../README.md#за-30-секунд). Здесь — установка, сборка и проверки. -```powershell -# 1. Справочник участников ЦБ (обязателен: 1380 участников, 370 банков) -java -jar validum.jar fetch-bik -o data/ED807.xml - -# 2. Профиль клиента с реквизитами, банком и счётом -java -jar validum.jar generate individual --seed 42 - -# 3. Тысяча клиентов в CSV / SQL / JSON -java -jar validum.jar generate individual --seed 42 -n 1000 --format csv -o clients.csv -java -jar validum.jar generate individual --seed 42 -n 1000 --format sql --dialect postgres -o seed.sql -``` - -Собрать jar: `./gradlew :validum-cli:shadowJar` → `validum-cli/build/libs/validum.jar`. -Пошаговые сценарии под конкретные задачи — в [`docs/recipes/`](recipes/README.md) -(фикстуры в JUnit, заливка в БД, нерезиденты, ДУЛ, ED807/ED808, детерминизм, Docker). +Собрать jar из исходников: `./gradlew :validum-cli:shadowJar` → +`validum-cli/build/libs/validum.jar`. Готовые сценарии под конкретные задачи — в +[`recipes/`](recipes/README.md). --- @@ -101,11 +90,11 @@ java -jar .\validum-cli\build\libs\validum.jar generate individual --seed 42 --f | Модуль | Тестов | |---|---| -| `validum-core` | **567** | -| `validum-api` | **80** | -| `validum-cli` | **55** | +| `validum-core` | **679** | +| `validum-api` | **92** | +| `validum-cli` | **114** | | `validum-allure` | **19** | -| **Итого** | **860** | +| **Итого** | **906** | Покрытие строк по jacoco (прогон 30.10.2026): `validum-core` — **89,2%** (2309/2588), `validum-api` — **92,2%** (404/438), `validum-cli` — считается тем же отчётом (HTML — `validum-cli/build/reports/jacoco/test/html/index.html`). Худшие пакеты: `validation` (75,9%), `common` (77,2%), `address` (77,8%); полностью покрыты `passport`, `snils`, `ogrn`, `random`. HTML-отчёт — `validum-core/build/reports/jacoco/test/html/index.html`. diff --git a/docs/README.md b/docs/README.md index e28109b..b10cef9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,192 +1,54 @@ -# 📚 Validum — документация +# Документация Validum -> Единая точка входа. Что читать — зависит от того, кто ты и зачем пришёл. +Один индекс на всю документацию: начните с того, что ближе к задаче. ---- +## С чего начать -## 🚀 Быстрый старт (5 минут) - -### Вариант 1: CLI (без Docker, без Spring) - -```powershell -.\gradlew :validum-cli:shadowJar -java -jar .\validum-cli\build\libs\validum.jar generate individual --seed 42 --format csv -o profile.csv -``` - -### Вариант 2: REST API - -```bash -docker compose up -d -# → http://localhost:8080/swagger-ui.html -curl -X POST http://localhost:8080/api/v1/generate/individual -d '{"seed":42}' -H "Content-Type: application/json" -``` - -### Вариант 3: Allure Extension (P3.2) - -```java -@ExtendWith(ValidumExtension.class) -class MyTest { - @Test - @ValidumSeed(42) - void test() { - // Профиль с seed=42 — в Allure-отчёте - } -} -``` - -Полная инструкция — в [README.md](../README.md) (лендинг) и [QUICKSTART.md](QUICKSTART.md). - ---- - -## 👤 Кто ты? - -### 🧪 QA-инженер — генерирую данные для тестов - -| Что нужно | Куда | -|---|---| -| Что умеет Validum | [FEATURES.md](FEATURES.md) | -| Готовые сценарии | [SCENARIOS.md](SCENARIOS.md) → раздел 2 | -| Комбинирование параметров | [SCENARIOS.md](SCENARIOS.md) → раздел 3 | -| Генерировать из скрипта | [CLI.md](CLI.md) | -| Attach профиля в Allure | [INTEGRATIONS.md](INTEGRATIONS.md) | -| **Явный банк (`.bik`)** | **[CLI.md](CLI.md#-явный-выбор-банка-p33)** | -| REST API | [REST.md](REST.md) | -| Проверка данных | [CLI.md](CLI.md#-валидация-validation-api) | -| Встроить в Java-тесты | [INTEGRATIONS.md](INTEGRATIONS.md) | - -### 🛠 Разработчик — понимаю, как устроено - -| Что нужно | Куда | -|---|---| -| Архитектура | [PROJECT.md](PROJECT.md) | -| Принципы проектирования | [SCENARIOS.md](SCENARIOS.md) → «Принципы проектирования» | -| Соглашения по коду | [PROJECT.md](PROJECT.md) | -| План | [ROADMAP.md](ROADMAP.md) | -| Данные (ФИО, адреса, email) | [SCENARIOS.md](SCENARIOS.md) → 5.5 | -| Экспортные колонки | [SCENARIOS.md](SCENARIOS.md) → 5.6 | -| Нормативные форматы (БИК, счёт, PtType) | [reference/cbr/README.md](reference/cbr/README.md) | - -### 🏗 Интегратор — встраиваю в свой процесс - -| Что нужно | Куда | +| Ситуация | Открыть | |---|---| -| REST API | [REST.md](REST.md) | -| CLI для скриптов | [CLI.md](CLI.md) | -| Allure Extension | [INTEGRATIONS.md](INTEGRATIONS.md) | -| Java-библиотека | [INTEGRATIONS.md](INTEGRATIONS.md) | -| Docker | [QUICKSTART.md](QUICKSTART.md) | -| Maven Central | [ROADMAP.md](ROADMAP.md) → P1.1 (отложено) | +| Первый раз в проекте | **[Туториал](TUTORIAL.md)** — 30–40 минут: установка, набор, проверка, спецификация | +| Нужна одна команда под задачу | [Рецепты](recipes/README.md) — «задача → команда → проверка» | +| Нужны все флаги команды | [CLI](CLI.md) | +| Нужен HTTP-доступ | [REST](REST.md) | +| Встраиваю в Java-тесты | [Интеграции](INTEGRATIONS.md) | -### 📊 Менеджер — статус и планы +## Документы -| Что нужно | Куда | +| Документ | О чём | |---|---| -| Статус (тесты, покрытие) | [QUICKSTART.md](QUICKSTART.md) | -| Что закрыто / что осталось | [ROADMAP.md](ROADMAP.md) | -| Метрики | [ROADMAP.md](ROADMAP.md) → «Метрики успеха» | - ---- - -## 📂 Структура документации - -``` -docs/ -├── README.md ← ты здесь (публичный) -├── SCENARIOS.md ← карта сценариев, каскады, поля профиля, CLI/Allure/.bik -├── ROADMAP.md ← бэклог, приоритеты, статус -├── recipes/README.md ← 14 рецептов «задача → команда → результат» -│ -├── reference/ ← нормативная база и форматы (публичная) -│ ├── cbr/ ← УФЭБС ЦБ РФ: форматы, коды, маски, счёт по 809-П -│ └── dul/ ← ДУЛ: форматы документов и источники (исследование) -│ -└── internal/ ← только для автора (в .gitignore / локально) - ├── HANDOFF.md ← контекст сессии - ├── PLAN-2026-11.md - └── competitor-analysis.md -``` - -| Файл | Аудитория | О чём | -|---|---|---| -| [SCENARIOS.md](SCENARIOS.md) | QA, разработчики | Типы клиентов, фасады, каскады, поля, контракт REST/CLI/Allure/Java, валидация, экспорт, `.bik` | -| [ROADMAP.md](ROADMAP.md) | Менеджеры, разработчики | Приоритеты P0–P4, статус итераций, метрики | -| [recipes/README.md](recipes/README.md) | QA, интеграторы | 14 готовых сценариев: фикстуры, CSV/SQL, нерезиденты, ДУЛ, ED807/ED808, детерминизм, Docker | -| [../CHANGELOG.md](../CHANGELOG.md) | Все | Что вошло в 0.1.0 | -| `internal/HANDOFF.md` | Только автор | Локальный контекст сессии (в `.gitignore`) | -| [../README.md](../README.md) | Все | Лендинг: что это, 30 секунд, цифры | -| [QUICKSTART.md](QUICKSTART.md) | Все | Установка, сборка, тесты, Docker | -| [CLI.md](CLI.md) | QA, интеграторы | Девять команд, пакеты, валидация, экспорт | -| [REST.md](REST.md) | Разработчики | Эндпоинты, форматы, ошибки | -| [INTEGRATIONS.md](INTEGRATIONS.md) | Java-разработчики | Библиотека и Allure | -| [FEATURES.md](FEATURES.md) | Все | Зачем нужен и что работает | -| [PROJECT.md](PROJECT.md) | Контрибьюторы | Архитектура, структура, релизы | -| [reference/cbr/README.md](reference/cbr/README.md) | Все | Нормативная база УФЭБС ЦБ РФ v2026.09.0: PtType, форматы счёта/БИК/ИНН, ED-сообщения | -| [reference/dul/research-dul-formats.md](reference/dul/research-dul-formats.md) | Все | ДУЛ: 15 видов документов, подтверждённые форматы и пробелы | - ---- - -## 🔍 Частые вопросы +| [TUTORIAL.md](TUTORIAL.md) | сквозной проход: справочник ЦБ → набор → проверка → спецификация → негатив | +| [QUICKSTART.md](QUICKSTART.md) | установка, сборка из исходников, тесты, Docker | +| [CLI.md](CLI.md) | десять команд, форматы, `--unique`, `--corrupt`, `--fields`, экспорт ED807/ED808 и SQL | +| [REST.md](REST.md) | пакетные эндпоинты, `fill`, `validate`, `scenarios`, `export`, коды ошибок | +| [INTEGRATIONS.md](INTEGRATIONS.md) | Java-библиотека (Maven Central) и расширение JUnit 5 + Allure | +| [SCENARIOS.md](SCENARIOS.md) | типы клиентов, фасады, каскады, поля профиля, контракт | +| [FEATURES.md](FEATURES.md) | зачем нужен, ключевые свойства, что работает | +| [COMPATIBILITY.md](COMPATIBILITY.md) | Java 17+, аддитивность полей, детерминизм, коды ошибок | +| [PROJECT.md](PROJECT.md) | архитектура, модули, структура репозитория, участие | +| [recipes/README.md](recipes/README.md) | готовые сценарии с проверками | +| [../CHANGELOG.md](../CHANGELOG.md) | что вошло в каждую версию | + +## Частые вопросы **Это облачный сервис?** -Нет. Self-hosted, работает внутри периметра. - -**Можно боевые данные?** -Нет, нарушение 152-ФЗ. Validum — синтетические. - -**Данные детерминированы?** -Да. `seed=42` всегда даёт одинаковый профиль. `seed=42, count=100` — первый как одиночный с seed=42, второй seed=43 и т.д. - -**Чем REST отличается от CLI?** -REST — для автотестов (JUnit + REST Assured), Swagger UI. CLI — для скриптов сетапа, CI. CLI не тянет Spring → ~15 МБ со справочниками, старт ~300 мс. - -**CLI JSON 1:1 с REST?** -Нет. CLI выдаёт **плоский JSON** (те же поля, что CSV). Осознанно. Нужен 1:1 REST — используй REST. - -**Что делает Allure Extension?** -Перехватывает тесты с `@ValidumSeed` / `@ValidumGenerate`, генерирует профиль, прикладывает плоский JSON в Allure. Best-effort: без Allure runtime — warning в stderr, тест не падает. Только ФЛ. - -**Как задать конкретный банк (P3.3)?** -- Java: `.bik("044525225")` или `.bank(Bank)` -- REST: `{ "bik": "044525225" }` -- CLI: `--bik 044525225` -- Приоритет: `bank` > `bik` > случайный. - -**Что если БИК не найден (P3.3)?** -`IllegalArgumentException` → REST 400 `{"error":"invalid_argument","message":"..."}`, CLI exit 2. **Не откатываемся** на случайный банк. - -**ЮЛ и `.bik`?** -`OrganizationProfile` получил `bank` и `account` (P2.4): БИК из справочника + расчётный счёт 40702, ключ по письму 515. CLI `generate organization --bank-bik …`. - -**Какие регионы?** -16: Москва, СПб, Московская, Краснодарский, Свердловская, Ленинградская, Новосибирская, Ростовская, Башкортостан, Татарстан, Челябинская, Самарская, Нижегородская, Красноярский, Приморский, Саратовская. По 20 адресов. - -**Как проверить, что данные валидны?** -REST: 8 эндпоинтов `/validate/*`. CLI: `validum validate ` (exit 0/1). Round-trip тесты (`ValidatorRoundTripTest`) гарантируют, что всё сгенерированное проходит валидацию. - -**Чем `/validate/ogrn` от `/validate/ogrnip`?** -`/validate/ogrn` автоопределяет: 13 — ЮЛ, 15 — ОГРНИП. `/validate/ogrnip` — **только** 15-значный, вернёт `false` для 13-значного (P2.3). - -**Что нового в КПП?** -Все 4 группы (регион, ИФНС, причина, порядковый) ≠ 0 (P2.3). - -**Где справочник банков?** -Топ-30 встроен. Полный ED807 (370): `validum fetch-bik -o data/ED807.xml`, или через `VALIDUM_BIK_FILE`, или `fetch-bik --offline` в банковском контуре. - -**`fetch-bik` за firewall?** -`--offline` — не скачивает, печатает инструкцию, exit 0. Без флага — понятное сообщение о причинах (сеть, прокси, `--offline`). - -**JUnit 4 / pytest?** -Нет. JUnit 5 (через Allure Extension — P3.2) и REST/CLI для любых языков. - -**Maven Central?** -Отложено до покупки `validum.tech` (верификация groupId). См. [ROADMAP.md](ROADMAP.md) → P1.1. +Нет. Self-hosted: работает внутри периметра, наружу ничего не уходит. ---- +**Можно генерировать боевые данные?** +Нет. Validum создаёт вымышленные данные, боевые персональные данные в тестовый контур попадать +не должны (152-ФЗ). Ответственность за то, что вы генерируете и куда кладёте, остаётся на операторе. -## 🗺 Что дальше +**Нужен справочник ЦБ?** +Для банковских сценариев — да: `fetch-bik -o data/ED807.xml`. Без него CLI отдаёт код `2`, +REST — `503 bik_source_missing`. Встроенного демо-справочника в продукте нет специально: один +источник правды вместо тихого отката. -Следующая итерация — **P4.1 (Импорт CSV — fill gaps)**. Полный бэклог — в [ROADMAP.md](ROADMAP.md). +**Почему прогон на следующий день даёт другой набор?** +`--seed` фиксирует значения, `--as-of` фиксирует дату расчёта (возраст, срок действия паспорта). +Без `--as-of` берётся сегодняшняя дата. ---- +**Есть Maven Central?** +Да: `io.github.validum-tech:validum-core` и `io.github.validum-tech:validum-allure` — см. +[QUICKSTART](QUICKSTART.md). -**Validum** — данные, которые проходят валидацию. **769 тестов. REST API + CLI + Java-библиотека + Allure. 8 валидаторов. 7 ОПФ. ДУЛ, КЛАДР, ОКВЭД, ED807/ED808.** +**JUnit 4 или pytest?** +JUnit 5 — через [Allure Extension](INTEGRATIONS.md); для остальных языков — REST или CLI. diff --git a/docs/RELEASING.md b/docs/RELEASING.md deleted file mode 100644 index ba87d59..0000000 --- a/docs/RELEASING.md +++ /dev/null @@ -1,79 +0,0 @@ -# Релиз Validum - -Как выпустить версию: от правки `CHANGELOG.md` до артефакта в Maven Central. - -## Что где публикуется - -| Куда | Что | Как | -|---|---|---| -| GitHub Release | `validum-<версия>.jar` + `.sha256` | автоматически по тегу `v*` | -| GitHub Packages | `validum-core`, `validum-api`, `validum-cli`, `validum-allure` (jar + sources + javadoc) | автоматически по тегу `v*` | -| Maven Central | те же четыре артефакта | ручной шаг, см. ниже | -| Docker Hub | `validum/validum-api` | пока вручную, автоматизация — после 0.2 | - -## Перед релизом - -1. **Проверить цифры.** Тесты, покрытие, число эндпоинтов и команд должны совпадать - в `README.md`, `docs/ROADMAP.md`, `CHANGELOG.md`. - Источник правды — `*/build/test-results/test/*.xml` и `*/build/reports/jacoco/test/*.csv`, не память. -2. **`CHANGELOG.md`** — секция `## [X.Y.Z] — ГГГГ-ММ-ДД`. Из неё берётся тело GitHub Release. -3. **Версия** — `version=X.Y.Z` в `gradle.properties` (единственное место). -4. **Сборка локально:** - - ```bash - ./gradlew build publishToMavenLocal - java -jar validum-cli/build/libs/validum.jar version - ``` - -5. **Дымовой прогон** на чистом окружении: `fetch-bik`, `generate individual`, `validate`, - `export ed807`, `--format sql`. - -## Тег и CI - -```bash -git tag -a v0.1.0 -m "Validum 0.1.0" -git push origin v0.1.0 -``` - -`release.yml` (Actions → Release) соберёт проект, прогонит тесты, опубликует -`validum-core` и `validum-allure` в **Maven Central** и создаст GitHub Release с jar и -контрольной суммой. - -**Секреты репозитория:** - -| Секрет | Обязателен | Зачем | -|---|---|---| -| `CENTRAL_USERNAME` | для Central | username из токена Central Portal | -| `CENTRAL_TOKEN` | для Central | пароль из токена Central Portal | -| `SIGNING_KEY` | для Central | armored PGP-ключ (`gpg --armor --export-secret-keys`) | -| `SIGNING_PASSWORD` | для Central | пароль ключа | - -Если секреты не заданы, шаг публикации в Central пропускается: сборка, тесты, релиз и jar -проходят как обычно, просто пакета в реестре не появится. Порядок получения ключей и токена — -внутренняя инструкция ведётся в `validum-dev` (внутри публичного репозитория её нет). - -## Maven Central - -Публикация автоматическая: `./gradlew publishToMavenCentral` (плагин `com.vanniktech.maven.publish`, -`SonatypeHost.CENTRAL_PORTAL`, авторелиз). Добавлять `validum-core` в свой проект можно без -подключения репозитория — Central есть по умолчанию: - -```kotlin -testImplementation("io.github.validum-tech:validum-core:0.2.0") -``` - -Что проверить после релиза: Central Portal → **Deployments** (статус `PUBLISHED`) и - (синхронизация — от -10 минут до пары часов). Локально без ключей: `./gradlew publishToMavenLocal`. - -## Версионирование - -- SemVer: `MAJOR` — несовместимый API, `MINOR` — новые возможности, `PATCH` — исправления. -- Пока не вышли из 0.x: ломающие изменения допустимы в `MINOR`, но обязаны быть в `CHANGELOG.md`. -- `-SNAPSHOT` в `main` после релиза не возвращаем: версия поднимается сразу, тег ставится на коммит. - -## Откат - -- Неверный тег: `git tag -d vX.Y.Z && git push --delete origin vX.Y.Z`, затем пересобрать. -- Ошибочный релиз в Central не удаляется. Выпускаем `PATCH` с исправлением и помечаем старую - версию в `CHANGELOG.md` как «не использовать». diff --git a/docs/REST.md b/docs/REST.md index fc508b1..c9329ee 100644 --- a/docs/REST.md +++ b/docs/REST.md @@ -1,6 +1,6 @@ # REST API -Spring Boot-сервис: batch-эндпоинты, fill, validate, scenarios, export. +Spring Boot-сервис: пакетные эндпоинты, fill, validate, scenarios, export. ## 🎯 Четыре способа использовать @@ -9,7 +9,7 @@ Spring Boot-сервис: batch-эндпоинты, fill, validate, scenarios, e | **REST API** | Автотесты (JUnit + REST Assured), Swagger UI | `docker compose up` → `POST /api/v1/generate/...` | | **CLI** | Скрипты сетапа, CI-пайплайны, «100 профилей в CSV» | `java -jar validum.jar generate individual --count 100 --format csv -o profiles.csv` | | **Allure Extension** | JUnit 5: attach профиля в Allure-отчёт | `@ValidumSeed(42)` / `@ValidumGenerate(...)` | -| **Java-библиотека** | Свой генератор поверх core | `io.github.validum-tech:validum-core:0.4.1` (Maven Central) | +| **Java-библиотека** | Свой генератор поверх core | `io.github.validum-tech:validum-core:0.5.0` (Maven Central) | --- @@ -188,7 +188,7 @@ java -jar validum.jar coverage --file clients.csv ``` ``` -# validum 0.4.1 coverage · file=clients.csv · rows=100 +# validum 0.5.0 coverage · file=clients.csv · rows=100 поле заполнено различных невалидных -------------------------------------------------- @@ -213,7 +213,7 @@ account 100% (100/100) 100 0 ### ✂️ Только нужные колонки -Полный профиль ФЛ — 64 колонки, и в большинстве сценариев столько не нужно. `--fields` оставляет +Полный профиль ФЛ — больше 60 колонок, и в большинстве сценариев столько не нужно. `--fields` оставляет только запрошенные, не меняя остального вывода: ```bash diff --git a/docs/ROADMAP-0.4.0.md b/docs/ROADMAP-0.4.0.md deleted file mode 100644 index 918eb9a..0000000 --- a/docs/ROADMAP-0.4.0.md +++ /dev/null @@ -1,213 +0,0 @@ -# Roadmap 0.4.0 - -Черновик списка задач на следующую версию. Основано на трёх источниках: аудит репозитория -(`sprints/2026-W48-refactoring/audit.md`), внутренний разбор конкурентов и замечания, -найденные при прогоне демо-сценария (`docs/DEMO-SCENARIO.md`). - -В 0.4.0 входит и набор дефектов 0.3.0, который не выпускался отдельным хотфиксом: -`-o out\sub\file.json`, `--age-distribution` без `--age-range`, NPE в `--spec`, -`--unique-pool`, срок паспорта по рубежам, дубль паспорта в документах, `fill` без стектрейса. -Они уже в `CHANGELOG.md` → `[Unreleased] — 0.4.0`. - -Принципы, которые не обсуждаются: - -- `validum-core` остаётся **zero-dependency** — новая зависимость в ядро не заезжает. -- Изменения только аддитивные; ломающие — не раньше 1.0 (и тогда с переходным периодом). -- Каждая задача — карточка на доске + прогон тестов; «сделано» = зелёные тесты и обновлённые - доки, а не «код написан». - - -## Состав 0.4.0 (решение 14.11.2026) - -Маленькое обновление: «данные правильные и читаемые» + доля техдолга. Всё остальное — в 0.5.0 и дальше. - -**Входит в 0.4.0:** - -| # | Задача | Цена | Почему | -|---|---|---|---| -| 0 | Фиксы 0.3.0 (уже в дереве) | готово | `-o`, `--age-distribution`, NPE в `--spec`, `--unique-pool`, паспорт по рубежам, `fill` | -| 1 | Регион адреса в плоской выдаче | 0,5 д | в CSV нет субъекта — не с чем сверять адрес | -| 2 | Формулировка `coverage` | 2 ч | «нарушений нет» при 10/10 битых ИНН вводит в заблуждение | -| 3 | `--fields` + пресет `short` | 1,5 д | 64 колонки — главный барьер при первом открытии CSV | -| 4 | `managers.txt`: одна заглушка вместо 50 | ✅ сделано | В выдаче «Менеджер клиента» вместо `ААА/ВВВ/…` | -| 5 | Рефакторинг: общие опции CLI через `@Mixin` | ✅ сделано | 7 опций жили в 4 копиях; теперь `CommonOptions` | -| 6 | Рефакторинг: `Builder` из `IndividualProfileGenerator` | ✅ сделано | `IndividualProfileBuilder` отдельным классом; голдены не изменились | -| 7 | Документация: README → `docs/*` | ✅ сделано | README 1165 → 71 строка; 6 файлов в `docs/` | -| 8 | Релиз 0.4.0 | 0,5 д | версии, CHANGELOG, витрина, Central | -| 9 | Предрелизная проверка (`release-check.py` + CI) | ✅ сделано | версии, jar, поверхность CLI/REST, поведение; гейт перед тегом | - -Итого ≈ 6 дней. - -**Отложено осознанно:** связанность набора (0.5.0), карты МИР (0.5.0), условная генерация (0.5.0), -проверки ОКВЭД/адресов в `coverage` (0.5.0), `--format xlsx` (до запроса от пользователей), -CLI-JSON через DTO (до 1.0), перемещение пакетов `core/export` (ломает импорты — до 1.0), -`/demo`, `samples/*`, видео и презентация (демо — только для внутреннего просмотра, публиковать -не планируем). - - ---- - -## P0 — то, что видит пользователь - -### 1. Регион в плоской выдаче адреса - -Сейчас в CSV есть `registrationCity`, `registrationStreet`, `registrationPostalCode`, -но **субъекта нет вообще** — в `describe` видно «Казахстан, г. Алматы…», а по CSV не понять регион. -Для сверки с ЕСИА/анкетами и для отчётов это заметный пробел. - -- Добавить `registrationRegion`, `postRegion`, `currentRegion` (и `regionType` следом) в - `IndividualProfileFlattener`/`IpProfileFlattener`, русские метки — в `CsvExporter`. -- Аддитивно: колонки в конце блока адреса, старые имена не трогаем. -- Обновить golden-фикстуры (осознанно, один раз). -- Оценка: **0,5 дня**. Критерий: `coverage`/`describe` видят регион, golden обновлён, 860+ зелёных. - -### 2. Формулировка в `coverage` - -На испорченном наборе отчёт печатает «Согласованность: нарушений нет», хотя ИНН 10 из 10 -невалидны. Формально верно (правила — про согласованность, не про валидность), но на демо и в -статье звучит как противоречие. - -- Переименовать блок в «Согласованность полей» и добавить сводку «валидность ключевых полей: - N из M невалидны». -- Оценка: **2 часа**. Критерий: `coverage bad.csv` показывает и согласованность, и валидность. - -### 3. Узкий профиль выдачи (`--fields`) - -64 колонки — это хорошо для засева БД и плохо для «покажите мне человека». -`--fields fullName,inn,age,region` + пресет `--fields short` (8–10 колонок). - -- Работает в CLI (`generate … --fields`), в спецификации (`"fields": [...]`) и в REST - (`?fields=`). -- Оценка: **1–2 дня**. Критерий: `--fields short` даёт понятную таблицу без потери ключей - (`personId`, `inn`), `coverage` продолжает работать. - -### 4. `--format xlsx` своим писателем - -Настоящий Excel, ноль зависимостей: XLSX — это ZIP с пятью XML (`[Content_Types].xml`, -`_rels`, `xl/workbook.xml`, `xl/worksheets/sheet1.xml`, `xl/styles.xml`). - -- Числа как числа, текстовые коды (`ИНН`, счёт, индекс) — как текст; ведущий ноль индекса - сохраняется. -- Только в CLI (`validum-cli`), ядро не тянет `java.util.zip`-обвязку в публичный API — либо - отдельный подпакет `ru.validum.core.export.xlsx` с явным javadoc «без зависимостей». -- Оценка: **2–3 дня**. Критерий: файл открывается в Excel/LibreOffice, `coverage --file *.xlsx` - не обязателен (или читаем через тот же писатель). - -### 5. CLI-JSON: флаги как boolean - -CLI собирает JSON из плоской карты строк, поэтому `"terrorist": "true"` — строка, а в REST — -настоящий boolean. Для машинной обработки это ловушка. - -- Вариант A (дешёвый): оставить как есть и задокументировать. -- Вариант B (правильный): `--format json` собирать через DTO (`IndividualProfileDto` уже есть в - api — вынести в `core` или продублировать в CLI), плоскую карту оставить для CSV/SQL. -- Оценка: **1–2 дня** (B). Критерий: в JSON флаги boolean, имена полей совпадают с REST. - ---- - -## P1 — рефакторинг (внутреннее, API не меняется) - -### 6. `core/export` → три пакета - -Сейчас в одном пакете кодеки (`CsvExporter`, `DocumentsCsv`), маппинг (`*Flattener`, -`ProfileFromCsv`, `CsvFiller`, `CsvImporter`) и доменные выгрузки ЦБ (`Ed807Exporter`, -`Ed808Exporter`). - -- `ru.validum.core.format` — CSV/JSON/SQL кодеки; -- `ru.validum.core.mapping` — flatten/unflatten/fill; -- `ru.validum.core.cbr` — ЭД 807/808. -- Оценка: **2–3 дня**. Критерий: `git grep` старых импортов пуст, тесты зелёные, публичные - классы сохранены как алиасы на один минор. - -### 7. `DocumentsCsv` (435 строк) → три класса - -Чтение, запись и склейка с профилем — по отдельности. Оценка: **1 день**. - -### 8. `IndividualProfileGenerator` (728 строк) → `Builder` + коллабораторы ✅ (Builder вынесен) - -Вынести `Builder`, настройку документов и адресов в отдельные классы; сам генератор оставить -сценарием. Оценка: **2 дня**. Критерий: золотые фикстуры не изменились (поведение то же). - -### 9. `@Mixin` для общих опций CLI - -`--seed`, `-n`, `-o`, `--format`, `--dialect`, `--table`, `--no-ddl`, `--region` дублируются -в 4 командах (24/18/15/9 опций). Общий `CommonOptions` + `@Mixin`. Оценка: **1 день**. -Критерий: `--help` не изменился по смыслу, тесты CLI зелёные. - -### 10. README (1135 строк) → `docs/*` - -`docs/quickstart.md`, `docs/cli.md`, `docs/api.md`, `docs/library.md`, `docs/data.md`; -README — витрина на 2–3 экрана со ссылками. Оценка: **1 день**. - -### 11. `managers.txt` — 50 заглушек `ННН` ✅ (одна заглушка «Менеджер клиента») - -Персональный менеджер выводится как «ННН». Выбрать: реальные правдоподобные ФИО (по регионам) -или убрать поле из выдачи по умолчанию. Оценка: **0,5 дня**. - ---- - -## P2 — возможности - -### 12. Связанность набора (перенесено из 0.3.0) - -`id` у профилей уже есть (`personId`), поэтому можно строить граф: `individual → accounts → -documents`, `organization → employees → individuals`, порядок вставки и `teardown.sql`. - -- Оценка: **6–8 дней**. Критерий: `generate --spec` с `"relations"` создаёт согласованный набор, - `fill`/`coverage` понимают связи, `teardown.sql` удаляет в обратном порядке. - -### 13. Карты МИР - -Тестовые PAN с ожидаемым исходом (как у ЮKassa), связка карта → банк → BIN. -Оценка: **3–4 дня**. - -### 14. Условная генерация - -`--where "region=77,gendern=MALE"` / `probe(seed=[...])` — набор под заданную выборку. -Оценка: **3–4 дня**. - -### 15. Расширить отчёт `coverage` - -Проверки ОКВЭД (код есть в классификаторе) и адресов (индекс ↔ регион), сейчас только -ИНН/СНИЛС/ОГРН/счёт. Оценка: **1 день**. - ---- - -## P3 — демонстрация и распространение - -### 16. Страница `/demo` на витрине - -12 шагов с реальными выводами (сейчас её нет — `/demo` отдаёт 404; материалы лежат в -`docs/DEMO-SCENARIO.md`). Оценка: **1–2 дня**. - -### 17. `samples/core-demo`, `samples/allure-demo` - -Компилируемые примеры: `Main.java` + `build.gradle.kts` с `validum-core:0.4.0`, тест с -`@ValidumGenerate` и Allure-отчётом. Нужны, чтобы примеры в документации действительно -собирались. Оценка: **1 день**. - -### 18. Репозиторий `validum-demo` - -Публичная площадка: `specs/*.json`, `out/`, CI «generate → coverage → публикация артефактов». -Даёт `Used By` на Central и живые примеры для статей. Оценка: **1 день**. - -### 19. Видео и презентация - -4 видео по `docs/DEMO-SCENARIO.md` (CLI, core, REST, Allure) + презентация. Вне кода. - ---- - -## Порядок - -1. **0.4.0-beta**: P0 (1–5) — «то, что видит пользователь». -2. **0.4.0**: P1 (6–11) — рефакторинг, потом P3-16/17 (демо и примеры). -3. **0.5.0**: P2 (12–15) — связанность, карты МИР, условная генерация. - -Оценки суммарно: P0 ≈ 5–8 дней, P1 ≈ 8–9 дней, P2 ≈ 13–17 дней, P3 ≈ 4–5 дней. - -## Что решить сейчас - -- xlsx: делать в 0.4.0 или отложить (P0-4)? Ломает «только CLI» или нет? -- CLI-JSON: вариант A (документировать строки) или B (DTO)? -- `managers.txt`: ФИО или убрать из выдачи? -- Связность (12): в 0.4.0 или отдельным 0.5.0? Она нужна клиентам больше, чем рефакторинг. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md deleted file mode 100644 index 1440777..0000000 --- a/docs/ROADMAP.md +++ /dev/null @@ -1,271 +0,0 @@ -# 🗺️ Validum — Roadmap и бэклог - -> **Дата:** 22 октября 2026 -> **Текущий статус:** MVP готов. **769 тестов**. P0.1–P0.3, P1.2–P1.4, P2.2, P2.3, P3.1–P3.3, P4.1 закрыты, ДУЛ (Неделя 3) — 11 видов, КУС-сценарии (9), экспорт ED807/ED808, Docker. Дальше — витрина и монетизация. -> **Как пользоваться:** идём строго по приоритетам. P0 блокирует публикацию. P1 закрывает MVP для QA. P2–P4 — рост. -> **Правило:** после каждой итерации — прогон тестов, обновление доков, коммит, зелёный CI. - ---- - -## 📊 Текущее состояние - -| Слой | Что готово | -|---|---| -| **Ядро** | **567 тест**, zero-dep Java 21, 18 пакетов | -| **API** | **60 тестов**, 16 бизнес-эндпоинтов + `GlobalExceptionHandler` | -| **CLI** | **78 тестов**, 10 команд + 8 типов валидации + `--bik`, fat JAR ~15 МБ (справочники КЛАДР и ОКВЭД внутри) | -| **Allure** | **19 тестов**, JUnit 5 Extension, attach профиля в отчёт | -| **Субъекты** | ФЛ (21 поле), ИП (композиция), ЮЛ (19 полей, **7 ОПФ**) | -| **Каскады** | `age → passport`, `region → addresses+KPP`, `category → package`, `orgType → okfs/budget` | -| **Батчи** | 3 эндпоинта `/batch`, до 10 000 профилей за раз | -| **Валидация** | **8 эндпоинтов** `/validate/*` + 8 типов в CLI | -| **Экспорт** | **CSV в core** (API, CLI, Allure). `?format=json|json-array|csv` | -| **Allure** | `@ValidumSeed` + `@ValidumGenerate`, flat JSON attachment | -| **Банк (P3.3)** | **`.bik(String)` / `.bank(Bank)`** для ФЛ и ИП. Невалидный БИК → 400 / exit 2 | -| **Негативные** | `corrupt(INN/SNILS)`, `passportWasExchanged=false`, `fioScript=LATIN` | -| **Флаги** | `terrorist`, `blocked` | -| **Справочник** | Топ-30 + полный ED807 (370 банков) | -| **Инфра** | Docker, GitHub Actions, GitHub Projects | - ---- - -## ⚠️ Узкие места (закрыты в P0) - -| Компонент | Было уникальных | Стало | Проблема при 100k профилей | -|---|---|---|---| -| **ФИО (кириллица)** | 14 000 | **~3 800 000** ✅ | Решено в P0.1 | -| **Адреса (на регион)** | **1** | **20** ✅ | Решено в P0.2 (всего 320) | -| **Email** | **1** | **298 доменов + ФИО** ✅ | Решено в P0.3 | -| **Секретное слово** | **1** | **298** ✅ | Решено в P0.3 | -| **Менеджер** | **1** | **50** ✅ | Решено в P0.3 | -| Регионы | 5 | **16** ✅ | Решено в P0.2 | -| ИНН | 5.2 млрд | 5.2 млрд | ✅ ок | -| СНИЛС | 900 млн | 900 млн | ✅ ок | -| Счёт | 9 млрд | 9 млрд | ✅ ок | - -**Вывод:** P0.1, P0.2 и P0.3 закрыли все острые проблемы массовой генерации. Продукт готов к использованию внешними QA-командами. - ---- - -# 🔴 P0 — Предрелизные блокеры (ЗАКРЫТЫ) - -## ✅ P0.1 — Расширение пула ФИО -- 5 списков в `src/main/resources/names/*.txt` (10 файлов). Ёмкость: **~3.8 млн** уникальных ФИО. - -## ✅ P0.2 — AddressPool -- `Region` расширен с 5 до **16 регионов**. Адреса — из реального справочника КЛАДР (`AddressBook`), а не из пула. -- `AddressBook` на реальных данных КЛАДР. Каскады `region → адрес`, `region → паспорт`, `region → КПП` для всех 16. - -## ✅ P0.3 — Email / SecretWord / Manager -- `Transliterator` по ГОСТ Р 52535.1-2006. -- `ContactGenerator.email(PersonName, EmailDomainMode)` — `petrov.si@test.ru`. -- 20 доменов (TEST/REALISTIC/MIXED). 298 слов, 50 менеджеров. -- Override для email, слова, менеджера. - ---- - -# 🔴 P1 — MVP для QA-инженера - -## 📅 P1.1 — Maven Central (отложено) - -**Статус:** отложено до покупки домена `validum.tech` (нужен для верификации `groupId` в Sonatype). - -**Что нужно будет сделать:** `maven-publish`, `signing`, GPG-ключ, Sonatype Central Portal, `./gradlew publish`, Sources JAR + Javadoc JAR. - -**Оценка:** 1 день. - -## ✅ P1.2 — Batch-генерация -- 3 эндпоинта: `POST /api/v1/generate/{individual,ip,organization}/batch`. -- Валидация `count` (1–10 000). Вне диапазона → 400. -- **Детерминизм:** первый профиль `seed`, второй `seed+1` и т.д. - -## ✅ P1.3 — Validation API -- 6 эндпоинтов: `POST /validate/{inn,snils,ogrn,account,kpp,bik}`. -- Автоопределение типа (ИНН ФЛ/ЮЛ, ОГРН ЮЛ/ОГРНИП). -- `BikValidator` возвращает название банка. - -## ✅ P1.4 — Экспорт (CSV / JSON Array) -- `CsvExporter` — плоский CSV, экранирование, UTF-8 BOM. -- `?format=json|json-array|csv` для батчей. -- **P3.1a:** `CsvExporter` переехал в core. - ---- - -# 🟠 P2 — Расширение домена - -## ✅ P2.2 — Расширение ОПФ ЮЛ -- `OrganizationType` — **7 типов**: `LLC`, `JSC`, `PJSC`, `NCO`, `FOUNDATION`, `SE`, `ME`. -- `IP` сознательно не добавлен (ИП = ФЛ + ОГРНИП). -- `okfs` / `budget` переехали в `OrganizationType`. - -## ✅ P2.3 — Валидаторы ОКПО / ОГРНИП + расширенный КПП -- `OkpoValidator` — 8 (ЮЛ) / 10 (ИП), автоопределение по длине. -- `OgrnipValidator` — 15 цифр, mod 13. Отдельный фасад. -- `KppValidator` расширен — все 4 группы (регион, ИФНС, причина, порядковый) ≠ 0. -- 2 новых эндпоинта: `/validate/okpo`, `/validate/ogrnip`. -- Round-trip тесты (`ValidatorRoundTripTest`). -- **Итог:** +28 core, +10 api. - -## 📅 P2.1 — Транзакции (отложено) - -**Статус:** отложено. Приоритет отдан CLI и Allure. Вернёмся, когда появится реальный запрос от QA. - -**Модель:** `Transaction { id, type, amount, currency, date, purpose, payerAccount, payeeAccount, payerBankBik, payeeBankBik, payerInn, payeeInn, status }`. - -**API:** `POST /api/v1/generate/transaction[/batch]`. - -**Оценка:** 2–3 дня. - ---- - -# 🟡 P3 — Killer features - -## ✅ P3.1 — CLI + CSV в core - -### P3.1a — Вынос CSV в core -- `core/export/CsvExporter` (generic `List> → CSV`, RFC 4180 + BOM). -- 3 флаттенера: `IndividualProfileFlattener`, `IpProfileFlattener`, `OrganizationProfileFlattener`. -- `validum-api/export/CsvExporter` удалён. `GenerationService` raw-методы. -- +18 core-тестов. Было 478 → стало 525. - -### P3.1b — CLI на Picocli -- Новый модуль `validum-cli`, зависимости — только `validum-core` + `picocli` + `jackson`. -- 7 корневых команд (generate, fill, validate, participants, scenarios, fetch-bik, version). - `--format json|json-array|csv`. `--output` (UTF-8) / stdout (UTF-8 форс). -- `fetch-bik --offline` — для банковских контуров. `validate` → exit 0/1. -- Fat JAR через GradleUp shadow 8.3.7 (~15 МБ со справочниками). +34 cli-теста. - -## ✅ P3.2 — Allure Extension (JUnit 5) - -**Зачем:** QA видят в Allure-отчёте, с какими данными упал/прошёл тест. - -**Что сделано:** -- Новый модуль `validum-allure`. Зависимости: `validum-core` + `allure-jupiter:2.35.3` + `junit-jupiter-api` + `jackson`. -- `@ValidumSeed(long)` / `@ValidumGenerate(seed, age, region, gender, categoryClient)`. -- `ValidumExtension implements BeforeEachCallback`. Плоский JSON attachment (`IndividualProfileFlattener`). -- **Best-effort attach** — не ломает тесты, если Allure runtime отсутствует. -- **Только ФЛ** (ИП/ЮЛ — P3.2b, если попросят). +19 allure-тестов. - -## ✅ P3.3 — `.bik(String)` / `.bank(Bank)` (ЗАКРЫТА) - -**Зачем:** банк выбирался случайно из справочника. QA хотят фиксировать «тест со Сбербанком». - -**Что сделано:** -1. **`.bik(String)`** в `IndividualProfileGenerator.Builder` — поиск в `BikSource`. Не найден → `IllegalArgumentException`. -2. **`.bank(Bank)`** — готовый объект (например, из `BikSources.resolve(...).findByBik(...)`). Приоритет > `.bik`. -3. **REST:** `bik` в `IndividualGenerationRequest`, `IpGenerationRequest`, `IndividualBatchRequest`, `IpBatchRequest` (`@Pattern("\\d{9}")`). -4. **`GenerationService`:** `bik` в raw-методах (одиночные и батчи). -5. **`GlobalExceptionHandler`:** `IllegalArgumentException → 400 {"error":"invalid_argument","message":"..."}`. -6. **CLI:** `--bik` в `generate individual` и `generate ip`. Невалидный БИК → exit 2. -7. **ЮЛ не трогаем** — у `OrganizationProfile` нет `Bank`. - -**Итог:** +10 core, +11 api, +9 cli. Было 544 → стало **574**. - -**Ключевые решения:** -- **Невалидный БИК — явное исключение, не откат на случайный.** REST 400, CLI exit 2. -- **Приоритет:** `bank` > `bik` > случайный. -- **ФЛ, ИП и ЮЛ с банком.** ЮЛ получил `bank` + `account` в P2.4. - ---- - -## ⏭️ P4.1 — Импорт CSV (fill gaps) (следующая) - -**Зачем:** QA хотят «взять существующий CSV, заполнить пустые ячейки валидными данными, сохранить». Это сценарий «у меня есть 50 профилей, но у 20 пустые ИНН — заполни». - -**Что делать:** -1. **`CsvImporter`** в `validum-core/export` — читает CSV (RFC 4180, BOM, экранирование), возвращает `List>`. -2. **`ProfileFromCsv`** — собирает `IndividualProfile` из плоских полей (обратный флаттенеру). -3. **`CsvFiller`** — берёт CSV-строки, для пустых ячеек генерирует значения через существующие генераторы. Непустые не трогает. -4. **REST:** `POST /api/v1/fill/individual/csv` (multipart) → CSV обратно. Или `POST /api/v1/fill/individual` (JSON). -5. **CLI:** `validum fill individual --input profiles.csv --output filled.csv`. -6. **Тесты:** парсинг, round-trip, fill empty-only. - -**DoD:** -- [ ] `CsvImporter` + `CsvFiller` в core. -- [ ] REST-эндпоинт `/fill/*` (JSON и CSV). -- [ ] CLI `validum fill individual`. -- [ ] Round-trip: `flatten(parse(csv)) == csv`. -- [ ] Тесты: 15–20. - -**Оценка:** 2–3 дня. - -**Что НЕ делаем:** не «дополняем битые» — только пустые. Валидацию битых оставляем на `/validate/*`. - ---- - -## 📅 P3.4 — Mock API по OpenAPI - -Генерация JSON-ответов по схеме. Конкурент Mockaroo. - -**Оценка:** 3–5 дней. - ---- - -# 🟢 P4 — На будущее - -| # | Фича | Оценка | -|---|---|---| -| P4.2 | Иностранные паспорта (5–7 стран) | 2 дня | -| P4.3 | Веб-UI для демо | 3–5 дней | -| P4.4 | ML-датасеты (связанные таблицы) | 5+ дней | -| P2.4 | ✅ Банк для ЮЛ (`.bik` / `.bank` в `OrganizationProfile`) | сделано 30.10 | -| P3.2b | Allure для ИП и ЮЛ | 0.5 дня (если попросят) | - ---- - -# ❌ Что НЕ делаем - -| Идея | Почему | -|---|---| -| LLM-генерация | Не гарантирует валидность | -| Собственный BIK-скрапер через Selenium | Хрупко | -| Публичный SaaS | Self-hosted модель | -| Плагин для JUnit 4 / pytest | JUnit 5 + REST/CLI | -| Интеграция с конкретной АБС | Пока только генерация | -| Универсальный экспорт под любую БД | Плоский CSV | -| Дублирование ИП в `OrganizationType` | ИП = ФЛ + ОГРНИП | -| 1:1 DTO в CLI и Allure | Плоский JSON = CSV | -| Interactive REPL в CLI | Скрипты | -| Config-файлы в CLI | Флагов достаточно | -| Fake `ExtensionContext` в тестах | Структурные тесты + реальный JUnit Platform | -| **Откат на случайный БИК при невалидном (P3.3)** | **Невалидный запрос должен явно провалиться** | - ---- - -# 📊 Метрики успеха - -| Метрика | Сейчас | После P4.1 | Цель через 3 мес | -|---|---|---|---| -| Тестов | **769** | 700+ | 750+ | -| Бизнес-эндпоинтов | **16** | 17–18 | 25+ | -| CLI-команд | **5** | 6 (fill) | 7+ | -| Allure аннотаций | **2** | 2 | 3+ | -| Сценариев | 6 | 6 | 15+ | -| Валидаторов | **8** | 8 | 10+ | -| ОПФ ЮЛ | **7** | 7 | 10+ | -| Скачиваний Maven Central | — | — | 500+/мес | -| Внешних потребителей | 0 | 0 | 5+ компаний | - ---- - -# 🎯 Порядок работы - -## Ближайшая последовательность - -1. **P4.1** — Импорт CSV (fill gaps) (2–3 дня) -2. Пауза / покупка домена → **P1.1** (Maven Central) - -**После P4.1** — полноценный MVP: REST + batch + validation (8 эндпоинтов) + экспорт + CLI + Allure + явный выбор банка + импорт CSV. - -## Правило завершения итерации - -1. Прогон `./gradlew test --rerun-tasks` -2. Все зелёные -3. Обновить счётчики в HANDOFF/SCENARIOS/README -4. Коммит + push -5. CI зелёный -6. Только потом — следующая - ---- - -**Validum** — данные, которые проходят валидацию. **769 тестов. REST API + CLI + Java-библиотека + Allure. P0.1–P0.3, P1.2–P1.4, P2.2, P2.3, P3.1–P3.3, P4.1 закрыты, ДУЛ (11 видов), 9 КУС-сценариев, ED807/ED808.** diff --git a/docs/SCENARIOS.md b/docs/SCENARIOS.md index 7b3d082..535c109 100644 --- a/docs/SCENARIOS.md +++ b/docs/SCENARIOS.md @@ -270,7 +270,7 @@ POST /api/v1/generate/organization **P3.3:** `bik` (`@Pattern("\\d{9}")`) — опциональное поле. Если задан — банк берётся из справочника. Не найден → 400 `{"error":"invalid_argument","message":"..."}`. -### 4.2 REST — Батчи (P1.2 + P3.3) +### 4.2 REST — Пакетные вызовы (P1.2 + P3.3) ``` POST /api/v1/generate/{individual,ip,organization}/batch @@ -278,7 +278,7 @@ POST /api/v1/generate/{individual,ip,organization}/batch → { count, seed, profiles: [ ... ] } ``` -**P3.3:** `bik` в `IndividualBatchRequest` и `IpBatchRequest` — применяется ко всем профилям в пакете. +**P3.3:** `bik` в `IndividualBatchRequest` и `IpBatchRequest` — применяется ко всем профилям в батче. ### 4.3 REST — Экспорт (P1.4 + P3.1a) @@ -557,7 +557,7 @@ validum validate → exit 0 / 1, JSON в stdout | P0.1 | ФИО (3.8 млн) | ✅ | | P0.2 | Адреса (КЛАДР, 16 регионов) | ✅ | | P0.3 | Email / SW / Manager | ✅ | -| P1.2 | Batch (3 эндпоинта) | ✅ | +| P1.2 | Пакетная генерация (3 эндпоинта) | ✅ | | P1.3 | Validation API (6 эндпоинтов) | ✅ | | P1.4 | Экспорт (CSV / JSON Array) | ✅ | | P2.2 | 7 ОПФ ЮЛ | ✅ | @@ -622,7 +622,7 @@ validum validate → exit 0 / 1, JSON в stdout | 26 | Почему отдельный `/validate/ogrnip`? | Не смешивать с ОГРН ЮЛ (P2.3) | | 27 | Почему ОКПО автоопределяет тип? | 8 → ЮЛ, 10 → ИП (P2.3) | | 28 | Что нового в КПП? | Все 4 группы ≠ 0 (P2.3) | -| 29 | Что нового в CLI? | 5 команд, 8 валидаторов, `--format`, exit 0/1 (P3.1b) | +| 29 | Что нового в CLI? | 10 команд, 8 валидаторов, `--format`, exit 0/1 (P3.1b) | | 30 | CLI JSON — 1:1 REST? | Нет, плоский (P3.1b) | | 31 | Как `fetch-bik` в банковском контуре? | `--offline` — инструкция, exit 0 (P3.1b) | | 32 | Где `CsvExporter`? | В core (P3.1a). Используется API, CLI, Allure | @@ -678,6 +678,6 @@ REST (`GET/POST /api/v1/scenarios`), CLI (`validum scenarios`, `generate`) и Ja --- -**Validum** — данные, которые проходят валидацию. **769 тестов. REST API + CLI + Java-библиотека + Allure.** -Каскады, батчи, валидация (8 типов), счета по 809-П (12 типов), ДУЛ (11 видов), 9 КУС-сценариев, +**Validum** — данные, которые проходят валидацию. **906 тестов. REST API + CLI + Java-библиотека + Allure.** +Каскады, пакетные вызовы, валидация (8 типов), счета по 809-П (12 типов), ДУЛ (11 видов), 9 КУС-сценариев, CSV в трёх режимах, экспорт ED807/ED808, Docker. **P0.1–P0.3, P1.2–P1.4, P2.2, P2.3, P3.1–P3.3, P4.1 закрыты.** diff --git a/docs/TUTORIAL.md b/docs/TUTORIAL.md new file mode 100644 index 0000000..f965454 --- /dev/null +++ b/docs/TUTORIAL.md @@ -0,0 +1,289 @@ +# Туториал: первый день с Validum + +Один проход сверху вниз — 30–40 минут. После него у вас есть набор данных, вы понимаете, +что в нём лежит, почему это правильно и как повторить прогон. + +Если нужен только «поставил и запустил» — [QUICKSTART](QUICKSTART.md). Если ищете готовый +сценарий под конкретную задачу — [рецепты](recipes/README.md). + +- [0. Что вы получите](#0-что-вы-получите) +- [1. Установка](#1-установка) +- [2. Справочник БИК](#2-справочник-бик) +- [3. Первые профили и детерминизм](#3-первые-профили-и-детерминизм) +- [4. CSV, который открывается в Excel](#4-csv-который-открывается-в-excel) +- [5. Только нужные колонки](#5-только-нужные-колонки) +- [6. Проверьте себя](#6-проверьте-себя) +- [7. Свой набор из файла](#7-свой-набор-из-файла) +- [8. Негативные данные](#8-негативные-данные) +- [Куда дальше](#куда-дальше) +- [Если что-то не работает](#если-что-то-не-работает) + +--- + +## 0. Что вы получите + +Validum генерирует **синтетические, но валидные** данные для российского финтеха: ИНН, СНИЛС, +ОГРН/ОГРНИП, КПП, ОКПО, БИК и корсчёт из справочника ЦБ, счёт по 809-П, паспорта, адреса из +КЛАДР, ОКВЭД-2. Контрольные суммы настоящие — их понимают те же валидаторы, что стоят у банка. + +Три свойства, из-за которых инструмент вообще нужен: + +1. **Валидность.** Данные проходят проверку, а не выглядят похожими. +2. **Воспроизводимость.** `--seed` + `--as-of` дают тот же набор на любой машине. +3. **Согласованность.** Серия паспорта, регион прописки, банк и счёт не противоречат друг другу. + +Данные **синтетические**: боевые персональные данные использовать нельзя (152-ФЗ), и Validum +для этого не предназначен. + +--- + +## 1. Установка + +Нужен Java 17+ (если нужен REST-сервис — Java 21). Скачайте `validum-<версия>.jar` из +[GitHub Releases](https://github.com/Validum-Tech/validum/releases) или соберите сами: + +```bash +./gradlew :validum-cli:shadowJar # → validum-cli/build/libs/validum.jar +``` + +Проверка, что всё на месте: + +```powershell +java -jar validum.jar version +# validum 0.4.1 +# Java: 21 +``` + +> Дальше в примерах используется `java -jar validum.jar` — замените на свой путь к jar. + +--- + +## 2. Справочник БИК + +Банковские сценарии (банк, счёт, корсчёт) работают только со справочником участников ЦБ — +встроенного демо-набора в продукте нет, чтобы не было «двух правд». + +```powershell +java -jar validum.jar fetch-bik -o data/ED807.xml +# Скачано: data/ED807.xml, <размер> байт +# Справочник: около 1,4 тыс. участников, из них около 370 действующих банков +``` + +Проверить, что справочник читается: + +```powershell +java -jar validum.jar participants -f data/ED807.xml --type 20 -l 5 +# таблица: БИК | PtType | Тип | Корсчёт | Наименование +``` + +Флаги: `-f` — путь к файлу (обязателен), `--type` — код типа участника (20 — действующие банки), +`-l` — сколько строк показать. + +> Если файла нет, банковские сценарии честно падают: CLI — код `2`, REST — `503 bik_source_missing`. +> Это не баг, а защита от тихого отката на «непонятно что». + +--- + +## 3. Первые профили и детерминизм + +```powershell +java -jar validum.jar generate individual --seed 42 -n 3 +``` + +Увидите в stderr строку меты и три профиля в JSON: + +``` +# validum 0.4.1 · seed=42 · asOf=2026-11-15 +``` + +Мета печатается всегда — она и есть ответ на вопрос «какие данные вы сгенерили». +Повторите команду с тем же `--seed` — получите тот же набор: + +```powershell +java -jar validum.jar generate individual --seed 42 -n 3 -o out/a.json +java -jar validum.jar generate individual --seed 42 -n 3 -o out/b.json +Get-FileHash out/a.json, out/b.json # одинаковые SHA-256 +``` + +Поменяйте `--as-of` — данные пересчитаются на другую дату (возраст, срок действия паспорта): + +```powershell +java -jar validum.jar generate individual --seed 42 -n 3 --as-of 2030-01-01 --format json-array +``` + +Что важно знать сразу: + +- `--seed` без `--as-of` — берётся сегодняшняя дата; прогон через месяц даст другой набор. +- Хотите «как было месяц назад» — задайте `--as-of` явно. + +--- + +## 4. CSV, который открывается в Excel + +Обычный CSV ломается в русском Excel: ИНН превращается в `5,86E+11`, счёт теряет точность, +индекс — ведущий ноль, дата — `#######`. + +```powershell +java -jar validum.jar generate individual --seed 7 -n 3 --format csv-semicolon -o out/clients.csv +``` + +Отличия `csv-semicolon` от обычного `csv`: + +- UTF-8 **с BOM** — Excel определяет кодировку сам; +- разделитель `;` — как в русской локали; +- русские заголовки («ФИО», «ИНН», «Счёт»); +- кодовые колонки пишутся текстом `="…"` — Excel не переформатирует ИНН, счёт, индекс и телефон. + +Машинный `csv` (без BOM, с `,`) оставлен как есть — для скриптов и конвейеров, ему Excel не нужен. + +--- + +## 5. Только нужные колонки + +В полном профиле больше 60 колонок — для теста это лишнее. Есть явный список и пресет: + +```powershell +java -jar validum.jar generate individual --seed 7 -n 3 --fields inn,fullName,account --format csv +# заголовок: fullName,inn,account (порядок — как в профиле, не как в списке) + +java -jar validum.jar generate individual --seed 7 -n 3 --fields short --format csv +# 15 основных колонок: идентификатор, ФИО, пол, дата рождения, возраст, ИНН, СНИЛС, +# паспорт, регион и город прописки, БИК, счёт, документы +``` + +Опечатка в имени колонки — не тихий пропуск, а отказ: + +```powershell +java -jar validum.jar generate individual --fields formName +# Ошибка: Неизвестные колонки: formName. В наборе есть, например: personId, fullName, inn, … +``` + +То же доступно в REST: `?fields=inn,fullName` или `?fields=short` — но только для CSV-форматов. + +--- + +## 6. Проверьте себя + +Две команды, которые заменяют «поверьте мне на слово». + +**`coverage`** — что в наборе есть и насколько оно валидно: + +```powershell +java -jar validum.jar coverage --file out/clients.csv +``` + +``` +поле заполнено различных невалидных +inn 100% (3/3) 3 0 +snils 100% (3/3) 3 0 +… +Валидность значений: проверено 5 полей, невалидных 0 из 15 значений +Согласованность набора: нарушений нет +``` + +**`describe`** — разбор одной записи человеческим языком: + +```powershell +java -jar validum.jar describe --file out/clients.csv --row 1 +``` + +Вы увидите ФИО, возраст, ИНН и СНИЛС с отметкой «валиден», паспорт с датой выдачи и сроком +действия, код подразделения, согласованный с регионом, адреса и счёт с БИК банка. + +Если сгенерировать данные с ошибкой (`--corrupt`, шаг 8) — `coverage` покажет ненулевые +«невалидные», а `describe` подчеркнёт проблему. Это и есть проверка, что вы смотрите на реальные +данные, а не на красивую картинку. + +--- + +## 7. Свой набор из файла + +Когда нужно повторять один и тот же набор в CI, удобнее держать его в файле спецификации: + +```powershell +$spec = @' +{ + "type": "individual", + "count": 100, + "seed": 42, + "asOf": "2026-01-01", + "format": "csv-semicolon", + "ageRange": "18-40", + "documents": "auto", + "fields": "short" +} +'@ +[IO.File]::WriteAllText("out/set.json", $spec, (New-Object System.Text.UTF8Encoding($false))) + +java -jar validum.jar generate --spec out/set.json -o out/set.csv +``` + +Ключи в файле — те же, что у флагов CLI (`--unique` → `"unique": true` и т.д.); неизвестный ключ +не игнорируется, а даёт ошибку со списком допустимых. + +Опечатка в имени ключа ловится сразу: + +```powershell +java -jar validum.jar generate --spec out/broken.json +# Ошибка: Неизвестные ключи: sed. Допустимо: type, count, seed, … +``` + +**Уникальность.** Если нужны неповторяющиеся значения: + +```powershell +java -jar validum.jar generate individual --seed 1 -n 1000 --unique --format csv +``` + +- `--unique` **требует** `--seed` — без него отказывается: иначе набор не воспроизводим. +- Ёмкость конечна: 1 000 000 ИНН не сгенерировать, если у пула меньше вариантов — инструмент + скажет, сколько всего вариантов, вместо тихих дублей. + +--- + +## 8. Негативные данные + +Тесты должны проверять не только успех. Порча — по одному полю за раз: + +```powershell +java -jar validum.jar generate individual --seed 3 -n 5 --corrupt inn,snils -o out/bad.csv --format csv +# в stderr: # испорчено: inn,snils +``` + +Доступно: `inn`, `snils`, `address` (пустой индекс и строка без улицы). Всё остальное в записи +остаётся валидным — чтобы тест не падал сразу по десяти причинам. + +Проверить, что порча доехала до файла: + +```powershell +java -jar validum.jar coverage --file out/bad.csv +# inn 100% (5/5) 5 5 ← все пять невалидны +# snils 100% (5/5) 5 5 +``` + +--- + +## Куда дальше + +| Задача | Документ | +|---|---| +| Все команды и флаги | [CLI](CLI.md) | +| HTTP-эндпоинты и коды ошибок | [REST](REST.md) | +| JUnit 5 + Allure, Java-библиотека | [INTEGRATIONS](INTEGRATIONS.md) | +| Готовые сценарии «под задачу» | [recipes](recipes/README.md) | +| Что считается совместимым изменением | [COMPATIBILITY](COMPATIBILITY.md) | +| Типы клиентов, каскады, поля профиля | [SCENARIOS](SCENARIOS.md) | +| Установка, Docker, сборка | [QUICKSTART](QUICKSTART.md) | + +--- + +## Если что-то не работает + +| Симптом | Причина и лечение | +|---|---| +| `Ошибка: файл не найден — …\data\ED807.xml` | Шаг 2 не выполнен: `fetch-bik -o data/ED807.xml` | +| В PowerShell вместо кириллицы `╨С╨Ш╨Ъ` | Консоль в cp866: `chcp 65001`, затем переменные `[Console]::OutputEncoding = [Text.Encoding]::UTF8` | +| `Ошибка: Неизвестный формат` | Форматы: `json`, `json-array`, `csv`, `csv-semicolon`, `sql` | +| `Ошибка: --unique требует --seed` | Добавьте `--seed` — без него набор невоспроизводим | +| `Хэш двух прогонов не совпал` | Не задан `--as-of`: при повторном прогоне в другой день берётся другая «сегодняшняя» дата | +| `java -jar` ругается на неизвестный флаг | Старый jar: пересоберите `./gradlew :validum-cli:shadowJar` и сверьте `version` | +| REST отвечает `503 bik_source_missing` | На сервере нет справочника: положите `data/ED807.xml` рядом с запуском API | diff --git a/docs/recipes/README.md b/docs/recipes/README.md index 5c66f4d..d6def40 100644 --- a/docs/recipes/README.md +++ b/docs/recipes/README.md @@ -7,7 +7,7 @@ ```powershell java -jar validum.jar fetch-bik -o data/ED807.xml -# → Справочник: 1380 участников, из них 370 действующих банков +# → Справочник: около 1,4 тыс. участников, из них около 370 действующих банков ``` Если файла нет, банковские сценарии честно падают: CLI — `exit 2`, REST — `503 bik_source_missing`. @@ -135,7 +135,7 @@ curl -X POST "http://localhost:8080/api/v1/scenarios/foreigner-with-visa?seed=42 curl -X POST "http://localhost:8080/api/v1/scenarios/serviceman?seed=42" ``` -**Что получилось.** Мужчина 20 лет, паспорт РФ + военный билет (код 07, серия — две заглавные буквы). +**Что получилось.** Мужчина 20 лет, паспорт РФ + военный билет (exit 07, серия — две заглавные буквы). Правила совместимости проверяет `DocumentRules`: билет только мужчине, призывной возраст 18–27. **Как проверить.** `gender=MALE`, `age=20`, `documents[1].spdulCode == "07"`. @@ -221,8 +221,8 @@ java -jar validum.jar export ed808 --bik 044525225 -o ed808.xml **Задача.** Нужны РКЦ, казначейство, конкурсные управляющие — не только банки (17 кодов `PtType`). ```powershell -java -jar validum.jar participants --file data/ED807.xml # все 1380 участников -java -jar validum.jar participants --file data/ED807.xml --type 20 # 370 банков +java -jar validum.jar participants --file data/ED807.xml # все участники (в выгрузке ЦБ 09.2026 — 1380) +java -jar validum.jar participants --file data/ED807.xml --type 20 # действующие банки (в выгрузке ЦБ 09.2026 — 370) java -jar validum.jar participants --file data/ED807.xml --type RKC # 13 расчётно-кассовых центров java -jar validum.jar participants --file data/ED807.xml --type 90 # 280 конкурсных управляющих java -jar validum.jar participants --file data/ED807.xml --type 52 # 141 территориальный орган ФК @@ -231,7 +231,7 @@ java -jar validum.jar participants --file data/ED807.xml --type 52 # 141 те **Что получилось.** Таблица БИК / PtType / тип / корсчёт / наименование. Код принимается числом (`52`) или именем (`TREASURY`). -**Как проверить.** Сумма по всем типам = 1380; `--type 20` = 370. +**Как проверить.** «Всего выведено» (строка суммы) должно совпасть с числом записей в файле; `--type 20` — только действующие банки. Числа зависят от выгрузки ЦБ: в официальной за 09.2026 — 1380 участников и 370 банков, в локальной `data/ED807.xml` — 1360 и 368. --- diff --git a/gradle.properties b/gradle.properties index b7b46c0..ca1ab11 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,6 +1,6 @@ # Версия проекта — единственное место, где она меняется. # Скрипт релиза сверяет её с тегом и с package.json витрины. -version=0.4.1 +version=0.5.0 # JVM org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8 diff --git a/settings.gradle.kts b/settings.gradle.kts index 7ab3017..b89b8a6 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -6,7 +6,7 @@ pluginManagement { } plugins { - id("org.gradle.toolchains.foojay-resolver-convention") version "0.9.0" + id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0" } dependencyResolutionManagement { diff --git a/validum-api/src/test/java/ru/validum/api/controller/GenerationControllerExportTest.java b/validum-api/src/test/java/ru/validum/api/controller/GenerationControllerExportTest.java index 2c3cfb5..a654b5b 100644 --- a/validum-api/src/test/java/ru/validum/api/controller/GenerationControllerExportTest.java +++ b/validum-api/src/test/java/ru/validum/api/controller/GenerationControllerExportTest.java @@ -60,7 +60,7 @@ void ipBatchCsv() throws Exception { .andExpect(status().isOk()) .andExpect(content().contentType(new MediaType("text", "csv", StandardCharsets.UTF_8))) .andExpect(content().string(startsWith("\uFEFF"))) - .andExpect(content().string(containsString("ogrnip,personId,fullName"))); + .andExpect(content().string(containsString("ogrnip,personId,employerOgrn,fullName"))); } @Test diff --git a/validum-cli/src/main/java/ru/validum/cli/DescribeCommand.java b/validum-cli/src/main/java/ru/validum/cli/DescribeCommand.java index 434f911..5a4a2d2 100644 --- a/validum-cli/src/main/java/ru/validum/cli/DescribeCommand.java +++ b/validum-cli/src/main/java/ru/validum/cli/DescribeCommand.java @@ -99,6 +99,7 @@ private void print(Map row) { line("Возраст", row.get("age")); line("Дата расчёта", row.get("asOf")); line("Семейное положение", row.get("familyStatus")); + line("Работодатель (ОГРН)", row.get("employerOgrn")); section("Проверки"); line("ИНН", row.get("inn"), check(InnValidator.isValid(row.get("inn")))); @@ -147,6 +148,8 @@ private void print(Map row) { line("БИК", bik); line("Корсчёт", row.get("bankCorrAccount")); line("Счёт", account); + line("Карта «Мир»", cardText(row), row.get("cardExpiry")); + line("Исход по карте", row.get("cardOutcome")); line("Пакет услуг", row.get("accountPackage")); line("Персональный менеджер", row.get("personalManager")); @@ -183,6 +186,22 @@ private static void line(String label, String value) { } /** «регион, индекс» — то, что видно в CSV отдельными колонками. */ + /** Номер карты с группировкой по четыре цифры; пустая строка, если карты нет. */ + private static String cardText(Map row) { + String pan = row.get("cardPan"); + if (pan == null || pan.isBlank()) { + return ""; + } + StringBuilder sb = new StringBuilder(); + for (int i = 0; i < pan.length(); i++) { + if (i > 0 && i % 4 == 0) { + sb.append(' '); + } + sb.append(pan.charAt(i)); + } + return sb.toString(); + } + private static String addressNote(Map row, String prefix) { String region = row.get(prefix + "Region"); String postal = row.get(prefix + "PostalCode"); diff --git a/validum-cli/src/main/java/ru/validum/cli/GenerateCommand.java b/validum-cli/src/main/java/ru/validum/cli/GenerateCommand.java index 1932745..dd8699f 100644 --- a/validum-cli/src/main/java/ru/validum/cli/GenerateCommand.java +++ b/validum-cli/src/main/java/ru/validum/cli/GenerateCommand.java @@ -43,6 +43,15 @@ public Integer call() throws Exception { return 2; } + if (SetRunner.isSet(spec)) { + try { + return new SetRunner(spec, output).run(); + } catch (IllegalArgumentException e) { + System.err.println("Ошибка в " + spec + ": " + e.getMessage()); + return 2; + } + } + GenerateSpec specification; try { specification = GenerateSpec.load(spec); diff --git a/validum-cli/src/main/java/ru/validum/cli/GenerateDocumentsCommand.java b/validum-cli/src/main/java/ru/validum/cli/GenerateDocumentsCommand.java index cf7e4be..82a8c46 100644 --- a/validum-cli/src/main/java/ru/validum/cli/GenerateDocumentsCommand.java +++ b/validum-cli/src/main/java/ru/validum/cli/GenerateDocumentsCommand.java @@ -80,9 +80,13 @@ public Integer call() throws Exception { } } + OutputFormat format = OutputFormat.fromString(common.format); + if (format == OutputFormat.JSON_NESTED) { + System.err.println("Ошибка: json-nested поддерживается только для generate individual"); + return 2; + } OutputMeta.print(System.err, baseSeed, asOfDate, common.seed == null); - OutputWriter.of( - common.output, OutputFormat.fromString(common.format), common.dialect, tableName(), !common.noDdl) + OutputWriter.of(common.output, format, common.dialect, tableName(), !common.noDdl) .write(rows, baseSeed); return 0; } diff --git a/validum-cli/src/main/java/ru/validum/cli/GenerateIndividualCommand.java b/validum-cli/src/main/java/ru/validum/cli/GenerateIndividualCommand.java index 3171d4d..4ef88ed 100644 --- a/validum-cli/src/main/java/ru/validum/cli/GenerateIndividualCommand.java +++ b/validum-cli/src/main/java/ru/validum/cli/GenerateIndividualCommand.java @@ -15,6 +15,7 @@ import ru.validum.core.export.FieldSelection; import ru.validum.core.bank.BikSource; import ru.validum.core.document.DocumentType; +import ru.validum.core.export.CardsCsv; import ru.validum.core.export.CsvExporter; import ru.validum.core.export.DocumentsCsv; import ru.validum.core.export.DocumentsFormat; @@ -85,6 +86,10 @@ public final class GenerateIndividualCommand implements Callable { description = "Как писать ДУЛ в CSV: inline | json | split (split пишет второй файл)") String documentsMode; + @Option(names = "--cards", defaultValue = "1", + description = "Сколько карт «Мир» выдать клиенту: 0 — без карты, 1 — в профиле, N>1 — таблица -cards.csv") + int cards; + @Option( names = "--corrupt", @@ -168,16 +173,33 @@ public Integer call() throws Exception { return 2; } + if (fmt == OutputFormat.JSON_NESTED && fields != null) { + System.err.println("Ошибка: --fields работает с плоскими форматами; для json-nested не нужен"); + return 2; + } List> rows = FieldSelection.keep( IndividualProfileFlattener.flattenAll(profiles, docFormat), fields); OutputMeta.print(System.err, baseSeed, asOfDate, common.seed == null); if (corrupt != null && corrupt.length > 0) { System.err.println("# испорчено: " + String.join(",", corrupt).toLowerCase(Locale.ROOT)); } - OutputWriter.of(common.output, fmt, common.dialect, tableName(), !common.noDdl).write(rows, baseSeed); + OutputWriter writer = OutputWriter.of( + common.output, fmt, common.dialect, tableName(), !common.noDdl); + if (fmt == OutputFormat.JSON_NESTED) { + writer.writeNested(profiles, baseSeed); + } else { + writer.write(rows, baseSeed); + } if (docFormat == DocumentsFormat.SPLIT) { writeDocumentsTable(profiles, common.output); } + if (cards > 1) { + if (common.output == null) { + System.err.println("Ошибка: --cards больше 1 требует -o: таблица карт пишется рядом с профилями"); + return 2; + } + writeCardsTable(profiles, common.output); + } if (index) { printIndex(profiles); } @@ -227,6 +249,7 @@ private IndividualProfileBuilder newBuilder(long profileSeed, BikSource bikSourc b.residency(parseResidency(residency, country)); if (bik != null) b.bik(bik); if (asOfDate != null) b.asOf(asOfDate); + b.cards(cards); applyDocuments(b); if (corrupt != null && corrupt.length > 0) { b.corrupt(parseCorrupt(corrupt)); @@ -327,6 +350,25 @@ private static List parseTypes(String[] values) { return types; } + private static void writeCardsTable(List profiles, Path output) + throws IOException { + List> rows = new ArrayList<>(); + for (IndividualProfile profile : profiles) { + rows.addAll(CardsCsv.toRows(profile.personId(), profile.cards())); + } + String csv = rows.isEmpty() + ? "\uFEFF" + String.join(",", CardsCsv.SPLIT_HEADER) + "\r\n" + : CsvExporter.toCsv(rows); + OutputFiles.write(cardsPath(output), CsvExporter.toBytes(csv)); + } + + private static Path cardsPath(Path output) { + String name = output.getFileName().toString(); + int dot = name.lastIndexOf('.'); + String target = dot > 0 ? name.substring(0, dot) + "-cards.csv" : name + "-cards.csv"; + return output.resolveSibling(target); + } + private static void writeDocumentsTable(List profiles, Path output) throws IOException { List> rows = new ArrayList<>(); diff --git a/validum-cli/src/main/java/ru/validum/cli/GenerateIpCommand.java b/validum-cli/src/main/java/ru/validum/cli/GenerateIpCommand.java index 0e05075..872e85f 100644 --- a/validum-cli/src/main/java/ru/validum/cli/GenerateIpCommand.java +++ b/validum-cli/src/main/java/ru/validum/cli/GenerateIpCommand.java @@ -121,6 +121,10 @@ public Integer call() throws Exception { List> rows = FieldSelection.keep(IpProfileFlattener.flattenAll(profiles), fields); OutputFormat fmt = OutputFormat.fromString(common.format); + if (fmt == OutputFormat.JSON_NESTED) { + System.err.println("Ошибка: json-nested поддерживается только для generate individual"); + return 2; + } OutputMeta.print(System.err, baseSeed, asOfDate, common.seed == null); OutputWriter.of(common.output, fmt, common.dialect, tableName(), !common.noDdl).write(rows, baseSeed); return 0; diff --git a/validum-cli/src/main/java/ru/validum/cli/GenerateOrganizationCommand.java b/validum-cli/src/main/java/ru/validum/cli/GenerateOrganizationCommand.java index efd9fd4..b4681dd 100644 --- a/validum-cli/src/main/java/ru/validum/cli/GenerateOrganizationCommand.java +++ b/validum-cli/src/main/java/ru/validum/cli/GenerateOrganizationCommand.java @@ -107,6 +107,10 @@ public Integer call() throws Exception { List> rows = FieldSelection.keep(OrganizationProfileFlattener.flattenAll(profiles), fields); OutputFormat fmt = OutputFormat.fromString(common.format); + if (fmt == OutputFormat.JSON_NESTED) { + System.err.println("Ошибка: json-nested поддерживается только для generate individual"); + return 2; + } OutputMeta.print(System.err, baseSeed, null, common.seed == null); OutputWriter.of(common.output, fmt, common.dialect, tableName(), !common.noDdl).write(rows, baseSeed); return 0; diff --git a/validum-cli/src/main/java/ru/validum/cli/GenerateSpec.java b/validum-cli/src/main/java/ru/validum/cli/GenerateSpec.java index 245ab9e..b9e5bc8 100644 --- a/validum-cli/src/main/java/ru/validum/cli/GenerateSpec.java +++ b/validum-cli/src/main/java/ru/validum/cli/GenerateSpec.java @@ -108,7 +108,7 @@ public static GenerateSpec load(Path file) { String type = normalizeType(text(merged, "type")); if (type == null) { throw new IllegalArgumentException( - "Обязательное поле \"type\": individual | ip | organization | documents"); + "Обязательное поле \"type\": individual | ip | organization | documents | set"); } Integer count = integer(merged, "count"); @@ -190,9 +190,10 @@ private static String normalizeType(String raw) { case "ip", "ип", "предприниматель" -> "ip"; case "organization", "ul", "юл", "organizationprofile", "org" -> "organization"; case "documents", "document", "документы", "doc" -> "documents"; + case "set", "набор", "наборы" -> "set"; default -> throw new IllegalArgumentException( "Неизвестный \"type\": \"" + raw - + "\". Допустимо: individual | ip | organization | documents"); + + "\". Допустимо: individual | ip | organization | documents | set"); }; } diff --git a/validum-cli/src/main/java/ru/validum/cli/OutputFormat.java b/validum-cli/src/main/java/ru/validum/cli/OutputFormat.java index e578ca6..a3ac3ee 100644 --- a/validum-cli/src/main/java/ru/validum/cli/OutputFormat.java +++ b/validum-cli/src/main/java/ru/validum/cli/OutputFormat.java @@ -7,6 +7,8 @@ public enum OutputFormat { CSV_SEMICOLON, JSON, JSON_ARRAY, + /** Вложенный JSON: структура профиля (passport, addresses, bank, cards) вместо плоской строки. */ + JSON_NESTED, SQL; public static OutputFormat fromString(String s) { @@ -18,9 +20,10 @@ public static OutputFormat fromString(String s) { case "json_array" -> JSON_ARRAY; case "csv" -> CSV; case "csv_semicolon", "csv_excel" -> CSV_SEMICOLON; + case "json_nested", "nested" -> JSON_NESTED; case "sql", "ddl" -> SQL; default -> throw new IllegalArgumentException( - "Неизвестный формат: '" + s + "'. Допустимо: json, json-array, csv, csv-semicolon, sql"); + "Неизвестный формат: '" + s + "'. Допустимо: json, json-array, csv, csv-semicolon, json-nested, sql"); }; } } diff --git a/validum-cli/src/main/java/ru/validum/cli/OutputWriter.java b/validum-cli/src/main/java/ru/validum/cli/OutputWriter.java index 9092ab5..9594daa 100644 --- a/validum-cli/src/main/java/ru/validum/cli/OutputWriter.java +++ b/validum-cli/src/main/java/ru/validum/cli/OutputWriter.java @@ -11,6 +11,7 @@ import java.util.List; import java.util.Map; import ru.validum.core.export.CsvExporter; +import ru.validum.core.export.NestedWriter; import ru.validum.core.sql.SqlDialect; import ru.validum.core.sql.SqlExporter; @@ -48,16 +49,27 @@ public static OutputWriter of( } public void write(List> rows, Long seed) throws IOException { + if (format == OutputFormat.JSON_NESTED) { + throw new IllegalStateException( + "json-nested собирается из профилей: используйте writeNested(...)"); + } String content = switch (format) { case JSON -> toJsonWrapper(rows, seed); case JSON_ARRAY -> JSON.writeValueAsString(rows); case CSV -> CsvExporter.toCsv(rows); case CSV_SEMICOLON -> CsvExporter.toCsv(rows, ';', true); case SQL -> sqlWithHeader(rows, seed); + case JSON_NESTED -> throw new IllegalStateException("json-nested пишется через writeNested"); }; writeContent(content); } + /** Вложенный JSON: структура профилей, а не плоских строк. */ + public void writeNested(List profiles, Long seed) + throws IOException { + writeContent(NestedWriter.toJson(profiles, seed)); + } + private String sqlWithHeader(List> rows, Long seed) { String script = SqlExporter.script(table, rows, dialect, withDdl); if (script.isEmpty()) { diff --git a/validum-cli/src/main/java/ru/validum/cli/SetRunner.java b/validum-cli/src/main/java/ru/validum/cli/SetRunner.java new file mode 100644 index 0000000..f562dfd --- /dev/null +++ b/validum-cli/src/main/java/ru/validum/cli/SetRunner.java @@ -0,0 +1,276 @@ +package ru.validum.cli; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import java.io.IOException; +import java.nio.file.Path; +import java.time.LocalDate; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import ru.validum.core.bank.BikSources; +import ru.validum.core.export.CsvExporter; +import ru.validum.core.export.IndividualProfileFlattener; +import ru.validum.core.export.IpProfileFlattener; +import ru.validum.core.export.OrganizationProfileFlattener; +import ru.validum.core.organization.IpProfile; +import ru.validum.core.organization.IpProfileGenerator; +import ru.validum.core.organization.OrganizationProfile; +import ru.validum.core.organization.OrganizationProfileGenerator; +import ru.validum.core.profile.IndividualProfile; +import ru.validum.core.profile.IndividualProfileBuilder; +import ru.validum.core.profile.IndividualProfileGenerator; +import ru.validum.core.sql.TeardownSql; + +/** + * Исполнение набора из спецификации {@code type=set}: организации → люди и ИП со ссылкой на + * работодателя, затем таблицы и связи. + * + *

Порядок записи повторяет порядок загрузки в БД: сначала организации (на них ссылаются люди), + * затем физические лица, затем ИП. Каждому участнику выдаётся свой seed + * ({@code seed + номер * 10007}), поэтому набор воспроизводится целиком. + */ +public final class SetRunner { + + private static final long SEED_STEP = 10_007L; + private static final ObjectMapper MAPPER = new ObjectMapper(); + + private final SetSpec spec; + private final Path output; + private final long seed; + private final LocalDate asOf; + + public SetRunner(Path specFile, Path outputOverride) { + this.spec = SetSpec.load(specFile); + Path declared = spec.output() == null ? null : Path.of(spec.output()); + this.output = outputOverride != null ? outputOverride : declared; + this.seed = spec.seed() == null ? 42L : spec.seed(); + this.asOf = spec.asOf() == null ? LocalDate.now() : LocalDate.parse(spec.asOf()); + } + + /** Быстрый признак набора: {@code "type": "set"} прямо в файле (без полного разбора). */ + public static boolean isSet(Path file) { + try { + JsonNode root = MAPPER.readTree(file.toFile()); + JsonNode type = root == null ? null : root.get("type"); + String raw = type == null ? null : type.asText(); + return raw != null + && ("set".equalsIgnoreCase(raw.trim()) + || "набор".equalsIgnoreCase(raw.trim()) + || "наборы".equalsIgnoreCase(raw.trim())); + } catch (Exception e) { + return false; + } + } + + /** Собрать и записать набор; возвращает код возврата CLI. */ + public int run() { + if (output == null) { + System.err.println("Ошибка: у набора должен быть \"output\" в спецификации или -o"); + return 2; + } + try { + write(); + return 0; + } catch (IOException e) { + System.err.println("Ошибка записи: " + e.getMessage()); + return 1; + } + } + + private void write() throws IOException { + List members = spec.members(); + Map> organizations = generateOrganizations(members); + Map> individuals = generateIndividuals(members, organizations); + Map> ips = generateIps(members, organizations); + + int written = 0; + for (SetSpec.Member member : members) { + List> rows = switch (member.kind()) { + case "organization" -> organizations.get(member.name()).stream() + .map(OrganizationProfileFlattener::flatten) + .toList(); + case "individual" -> individuals.get(member.name()).stream() + .map(p -> IndividualProfileFlattener.flatten(p)) + .toList(); + default -> ips.get(member.name()).stream().map(IpProfileFlattener::flatten).toList(); + }; + Path file = memberFile(member); + OutputFiles.write(file, CsvExporter.toBytes(CsvExporter.toCsv(rows))); + System.err.printf("# %-12s %-13s %d строк → %s%n", member.name(), member.kind(), + rows.size(), file); + written += rows.size(); + } + writeRelations(individuals, ips); + if (spec.teardownWanted()) { + writeTeardown(organizations, individuals, ips); + } + System.err.printf("# набор: %d строк в %d файлах, seed=%d, asOf=%s%n", + written, members.size() + (hasEmployerLinks() ? 1 : 0), seed, asOf); + } + + private Map> generateOrganizations(List members) { + Map> result = new LinkedHashMap<>(); + for (int index = 0; index < members.size(); index++) { + SetSpec.Member member = members.get(index); + if (!"organization".equals(member.kind())) { + continue; + } + List profiles = new ArrayList<>(); + for (int i = 0; i < member.count(); i++) { + profiles.add(OrganizationProfileGenerator.builder() + .seed(seed + index * SEED_STEP + i) + .bikSource(BikSources.defaultSource()) + .build() + .generate()); + } + result.put(member.name(), profiles); + } + return result; + } + + private Map> generateIndividuals( + List members, Map> organizations) { + Map> result = new LinkedHashMap<>(); + for (int index = 0; index < members.size(); index++) { + SetSpec.Member member = members.get(index); + if (!"individual".equals(member.kind())) { + continue; + } + List profiles = new ArrayList<>(); + for (int i = 0; i < member.count(); i++) { + IndividualProfileBuilder builder = IndividualProfileGenerator.builder() + .seed(seed + index * SEED_STEP + i) + .asOf(asOf) + .bikSource(BikSources.defaultSource()); + String employer = employerOgrn(member, organizations, i); + if (employer != null) { + builder.employer(employer); + } + profiles.add(builder.build().generate()); + } + result.put(member.name(), profiles); + } + return result; + } + + private Map> generateIps( + List members, Map> organizations) { + Map> result = new LinkedHashMap<>(); + for (int index = 0; index < members.size(); index++) { + SetSpec.Member member = members.get(index); + if (!"ip".equals(member.kind())) { + continue; + } + List profiles = new ArrayList<>(); + for (int i = 0; i < member.count(); i++) { + long profileSeed = seed + index * SEED_STEP + i; + IndividualProfileBuilder builder = IndividualProfileGenerator.builder() + .seed(profileSeed) + .asOf(asOf) + .bikSource(BikSources.defaultSource()); + String employer = employerOgrn(member, organizations, i); + if (employer != null) { + builder.employer(employer); + } + profiles.add(IpProfileGenerator.from(builder.build().generate(), profileSeed)); + } + result.put(member.name(), profiles); + } + return result; + } + + /** Работодатель по кругу: i-й человек получает i-ю организацию участника. */ + private String employerOgrn( + SetSpec.Member member, Map> organizations, int index) { + if (member.employer() == null) { + return null; + } + List pool = organizations.get(member.employer()); + return pool.get(index % pool.size()).ogrn(); + } + + private void writeRelations( + Map> individuals, Map> ips) + throws IOException { + List> rows = new ArrayList<>(); + for (List profiles : individuals.values()) { + for (IndividualProfile profile : profiles) { + if (profile.employerOgrn() != null) { + rows.add(link(profile.personId(), profile.employerOgrn())); + } + } + } + for (List profiles : ips.values()) { + for (IpProfile profile : profiles) { + if (profile.base().employerOgrn() != null) { + rows.add(link(profile.base().personId(), profile.base().employerOgrn())); + } + } + } + if (rows.isEmpty()) { + return; + } + OutputFiles.write(relationsFile(), CsvExporter.toBytes(CsvExporter.toCsv(rows))); + System.err.printf("# %-12s %-13s %d строк → %s%n", "relations", "link", rows.size(), + relationsFile()); + } + + /** Скрипт отката: организации удаляются последними, потому что на них ссылаются люди. */ + private void writeTeardown( + Map> organizations, + Map> individuals, + Map> ips) throws IOException { + List tables = new ArrayList<>(); + organizations.values().forEach(list -> tables.add(new TeardownSql.Table( + "validum_organization", "ogrn", list.stream().map(OrganizationProfile::ogrn).toList()))); + individuals.values().forEach(list -> tables.add(new TeardownSql.Table( + "validum_individual", "personId", list.stream().map(IndividualProfile::personId).toList()))); + ips.values().forEach(list -> tables.add(new TeardownSql.Table( + "validum_ip", "personId", list.stream().map(ip -> ip.base().personId()).toList()))); + + String sql = TeardownSql.build( + "validum " + ru.validum.core.Version.version() + ", набор, seed=" + seed, tables); + Path file = teardownFile(); + OutputFiles.write(file, sql.getBytes(java.nio.charset.StandardCharsets.UTF_8)); + System.err.printf("# %-12s %-13s %d таблиц → %s%n", "teardown", "delete", tables.size(), file); + } + + private Path teardownFile() { + String name = output.getFileName().toString(); + int dot = name.lastIndexOf('.'); + String stem = dot > 0 ? name.substring(0, dot) : name; + return output.resolveSibling(stem + "-teardown.sql"); + } + + private static Map link(String personId, String ogrn) { + Map row = new LinkedHashMap<>(); + row.put("personId", personId == null ? "" : personId); + row.put("employerOgrn", ogrn); + return row; + } + + private boolean hasEmployerLinks() { + return spec.members().stream().anyMatch(m -> m.employer() != null); + } + + private Path memberFile(SetSpec.Member member) { + String name = output.getFileName().toString(); + int dot = name.lastIndexOf('.'); + String stem = dot > 0 ? name.substring(0, dot) : name; + String suffix = switch (member.kind()) { + case "organization" -> "organizations"; + case "individual" -> "individuals"; + default -> "ip"; + }; + return output.resolveSibling(stem + "-" + suffix + ".csv"); + } + + private Path relationsFile() { + String name = output.getFileName().toString(); + int dot = name.lastIndexOf('.'); + String stem = dot > 0 ? name.substring(0, dot) : name; + return output.resolveSibling(stem + "-relations.csv"); + } +} diff --git a/validum-cli/src/main/java/ru/validum/cli/SetSpec.java b/validum-cli/src/main/java/ru/validum/cli/SetSpec.java new file mode 100644 index 0000000..a7bb3ab --- /dev/null +++ b/validum-cli/src/main/java/ru/validum/cli/SetSpec.java @@ -0,0 +1,119 @@ +package ru.validum.cli; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.HashSet; +import java.util.List; +import java.util.Locale; +import java.util.Set; + +/** + * Спецификация набора из нескольких сущностей: организации, физические лица и ИП в одном прогоне, + * со связью «человек → работодатель». + * + *

+ * {
+ *   "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"}
+ *   ]
+ * }
+ * 
+ */ +public record SetSpec(Long seed, String asOf, String output, Boolean teardown, List members) { + + /** Писать ли рядом с набором скрипт отката ({@code -teardown.sql}); по умолчанию — да. */ + public boolean teardownWanted() { + return teardown == null || teardown; + } + + /** Один участник набора. */ + public record Member(String name, String kind, int count, String employer) {} + + private static final ObjectMapper MAPPER = new ObjectMapper(); + + /** Разбор файла; любая проблема — {@link IllegalArgumentException} с понятным текстом. */ + public static SetSpec load(Path file) { + JsonNode root; + try { + root = MAPPER.readTree(file.toFile()); + } catch (Exception e) { + throw new IllegalArgumentException("не удалось прочитать " + file + ": " + e.getMessage()); + } + if (root == null || !root.isObject()) { + throw new IllegalArgumentException("ожидался JSON-объект"); + } + Long seed = root.hasNonNull("seed") ? root.get("seed").asLong() : null; + String asOf = text(root, "asOf"); + String output = text(root, "output"); + Boolean teardown = root.hasNonNull("teardown") ? root.get("teardown").asBoolean() : null; + + JsonNode rawMembers = root.get("members"); + if (rawMembers == null || !rawMembers.isArray() || rawMembers.isEmpty()) { + throw new IllegalArgumentException("нужен непустой массив \"members\""); + } + List members = new ArrayList<>(); + Set names = new HashSet<>(); + for (JsonNode raw : rawMembers) { + String name = text(raw, "name"); + if (name == null || name.isBlank()) { + throw new IllegalArgumentException("у каждого участника набора должно быть имя \"name\""); + } + if (!names.add(name)) { + throw new IllegalArgumentException("имя участника повторяется: " + name); + } + String kind = kind(text(raw, "kind")); + int count = raw.hasNonNull("count") ? raw.get("count").asInt() : 1; + if (count < 1) { + throw new IllegalArgumentException("count у «" + name + "» должен быть хотя бы 1"); + } + members.add(new Member(name, kind, count, text(raw, "employer"))); + } + + for (Member member : members) { + if (member.employer() == null) { + continue; + } + Member target = members.stream() + .filter(m -> m.name().equals(member.employer())) + .findFirst() + .orElseThrow(() -> new IllegalArgumentException( + "участник «" + member.name() + "» ссылается на несуществующего работодателя: " + + member.employer())); + if (!"organization".equals(target.kind())) { + throw new IllegalArgumentException( + "работодатель «" + target.name() + "» должен быть организацией, а он " + target.kind()); + } + } + return new SetSpec(seed, asOf, output, teardown, List.copyOf(members)); + } + + private static String kind(String raw) { + if (raw == null) { + throw new IllegalArgumentException("у участника набора нужен \"kind\""); + } + return switch (raw.toLowerCase(Locale.ROOT).trim()) { + case "organization", "org", "юл" -> "organization"; + case "individual", "person", "фл" -> "individual"; + case "ip", "ип" -> "ip"; + default -> throw new IllegalArgumentException( + "неизвестный kind «" + raw + "»: organization | individual | ip"); + }; + } + + private static String text(JsonNode node, String field) { + JsonNode value = node.get(field); + if (value == null || value.isNull()) { + return null; + } + String text = value.asText(); + return text == null || text.isBlank() ? null : text.trim(); + } +} diff --git a/validum-cli/src/test/java/ru/validum/cli/CardsTableTest.java b/validum-cli/src/test/java/ru/validum/cli/CardsTableTest.java new file mode 100644 index 0000000..0fd374d --- /dev/null +++ b/validum-cli/src/test/java/ru/validum/cli/CardsTableTest.java @@ -0,0 +1,71 @@ +package ru.validum.cli; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.io.PrintWriter; +import java.io.Writer; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import picocli.CommandLine; + +/** {@code --cards N>1} пишет вторую таблицу карт рядом с профилями. */ +@DisplayName("CLI: таблица карт «Мир»") +class CardsTableTest { + + @TempDir Path tmp; + + @Test + @DisplayName("--cards 3 -o people.csv → people-cards.csv с тремя строками на клиента") + void writesCardsTable() throws Exception { + Path out = tmp.resolve("people.csv"); + + int code = run("generate", "individual", "--seed", "4", "--count", "2", + "--cards", "3", "--format", "csv", "-o", out.toString()); + + assertThat(code).isZero(); + Path cards = tmp.resolve("people-cards.csv"); + assertThat(cards).exists(); + + List lines = Files.readAllLines(cards, StandardCharsets.UTF_8); + assertThat(lines.get(0)).isEqualTo("\uFEFFpersonId,pan,expiry,outcome"); + assertThat(lines).hasSize(1 + 6); + assertThat(lines.subList(1, lines.size())) + .allSatisfy(line -> assertThat(line).containsPattern("^pd-[0-9a-f]{16},220\\d{13},\\d{2}/\\d{2},")); + } + + @Test + @DisplayName("--cards 3 без -o → отказ с кодом 2") + void cardsWithoutOutputIsRefused() { + int code = run("generate", "individual", "--seed", "4", "--count", "1", "--cards", "3"); + assertThat(code).isEqualTo(2); + } + + @Test + @DisplayName("--cards 1 не создаёт вторую таблицу") + void singleCardHasNoTable() { + Path out = tmp.resolve("one.csv"); + + int code = run("generate", "individual", "--seed", "5", "--count", "1", + "--cards", "1", "--format", "csv", "-o", out.toString()); + + assertThat(code).isZero(); + assertThat(tmp.resolve("one-cards.csv")).doesNotExist(); + assertThat(out).exists(); + } + + private static int run(String... args) { + CommandLine cmd = ValidumCli.commandLine(); + cmd.setOut(quiet()); + cmd.setErr(quiet()); + return cmd.execute(args); + } + + private static PrintWriter quiet() { + return new PrintWriter(Writer.nullWriter()); + } +} diff --git a/validum-cli/src/test/java/ru/validum/cli/CliSmokeTest.java b/validum-cli/src/test/java/ru/validum/cli/CliSmokeTest.java index 7def355..d6a0820 100644 --- a/validum-cli/src/test/java/ru/validum/cli/CliSmokeTest.java +++ b/validum-cli/src/test/java/ru/validum/cli/CliSmokeTest.java @@ -188,7 +188,7 @@ void generateIp() throws Exception { .isZero(); String csv = Files.readString(out, StandardCharsets.UTF_8); - assertThat(csv).contains("ogrnip,personId,fullName"); + assertThat(csv).contains("ogrnip,personId,employerOgrn,fullName"); } @Test diff --git a/validum-cli/src/test/java/ru/validum/cli/GenerateSpecTest.java b/validum-cli/src/test/java/ru/validum/cli/GenerateSpecTest.java index 21dd275..3ac5bd4 100644 --- a/validum-cli/src/test/java/ru/validum/cli/GenerateSpecTest.java +++ b/validum-cli/src/test/java/ru/validum/cli/GenerateSpecTest.java @@ -79,7 +79,7 @@ void excelCsvFromSpec() throws Exception { assertThat(bytes[0] & 0xFF).isEqualTo(0xEF); assertThat(bytes[1] & 0xFF).isEqualTo(0xBB); assertThat(bytes[2] & 0xFF).isEqualTo(0xBF); - assertThat(Files.readString(out)).startsWith("\uFEFFИдентификатор;ФИО;"); + assertThat(Files.readString(out)).startsWith("\uFEFFИдентификатор;ОГРН работодателя;ФИО;"); } @Test diff --git a/validum-cli/src/test/java/ru/validum/cli/NestedFormatTest.java b/validum-cli/src/test/java/ru/validum/cli/NestedFormatTest.java new file mode 100644 index 0000000..08bb5af --- /dev/null +++ b/validum-cli/src/test/java/ru/validum/cli/NestedFormatTest.java @@ -0,0 +1,56 @@ +package ru.validum.cli; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.io.PrintWriter; +import java.io.Writer; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import picocli.CommandLine; + +/** {@code --format json-nested}: вложенная структура в файл и отказ для --fields. */ +@DisplayName("CLI: вложенный JSON") +class NestedFormatTest { + + @TempDir Path tmp; + + @Test + @DisplayName("json-nested пишет профили с группами") + void writesNested() throws Exception { + Path out = tmp.resolve("people-nested.json"); + + int code = run("generate", "individual", "--seed", "11", "--count", "2", + "--format", "json-nested", "-o", out.toString()); + + assertThat(code).isZero(); + String json = Files.readString(out, StandardCharsets.UTF_8); + assertThat(json).startsWith("{\"count\":2,\"seed\":11,\"profiles\":[{"); + assertThat(json).contains("\"cards\":[{"); + assertThat(json).contains("\"passport\":{"); + } + + @Test + @DisplayName("--fields с json-nested — отказ с кодом 2") + void fieldsRefused() { + Path out = tmp.resolve("x.json"); + int code = run("generate", "individual", "--seed", "11", "--count", "1", + "--format", "json-nested", "--fields", "inn,fullName", "-o", out.toString()); + assertThat(code).isEqualTo(2); + assertThat(out).doesNotExist(); + } + + private static int run(String... args) { + CommandLine cmd = ValidumCli.commandLine(); + cmd.setOut(quiet()); + cmd.setErr(quiet()); + return cmd.execute(args); + } + + private static PrintWriter quiet() { + return new PrintWriter(Writer.nullWriter()); + } +} diff --git a/validum-cli/src/test/java/ru/validum/cli/SetRunnerTest.java b/validum-cli/src/test/java/ru/validum/cli/SetRunnerTest.java new file mode 100644 index 0000000..0129ca7 --- /dev/null +++ b/validum-cli/src/test/java/ru/validum/cli/SetRunnerTest.java @@ -0,0 +1,127 @@ +package ru.validum.cli; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.stream.Collectors; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import picocli.CommandLine; +import ru.validum.core.export.CsvImporter; + +/** Набор из спецификации: организация + люди + ИП со связью «человек → работодатель». */ +class SetRunnerTest { + + @TempDir + Path tmp; + + /** Путь в JSON — с прямыми слэшами, иначе на Windows ломается экранирование. */ + private String jsonPath(String name) { + return tmp.resolve(name).toAbsolutePath().toString().replace("\\", "/"); + } + + private int run(Path spec) { + return new CommandLine(new ValidumCli()).execute("generate", "--spec", spec.toString()); + } + + + private static List> readRows(Path file) throws IOException { + String text = Files.readString(file, StandardCharsets.UTF_8); + char delimiter = CsvImporter.detectDelimiter(text.lines().findFirst().orElse("")); + return CsvImporter.parse(text, delimiter); + } + + @Test + @DisplayName("Один участник: файл на месте и столько строк, сколько просили") + void singleMember() throws Exception { + String spec = """ + {"type":"set","seed":11,"asOf":"2026-11-15","output":"%s", + "members":[{"name":"people","kind":"individual","count":2}]} + """.formatted(jsonPath("set.csv")); + Path file = tmp.resolve("set.json"); + Files.writeString(file, spec, StandardCharsets.UTF_8); + + assertThat(run(file)).isZero(); + + List> rows = + readRows(tmp.resolve("set-individuals.csv")); + assertThat(rows).hasSize(2); + } + + @Test + @DisplayName("Работодатель — ОГРН организации из набора, а не случайная строка") + void employerLinksAreReal() throws Exception { + String spec = """ + {"type":"set","seed":13,"asOf":"2026-11-15","output":"%s", + "members":[{"name":"orgs","kind":"organization","count":2}, + {"name":"people","kind":"individual","count":3,"employer":"orgs"}]} + """.formatted(jsonPath("linked.csv")); + Path file = tmp.resolve("linked.json"); + Files.writeString(file, spec, StandardCharsets.UTF_8); + + assertThat(run(file)).isZero(); + + List> organizations = + readRows(tmp.resolve("linked-organizations.csv")); + List> people = readRows(tmp.resolve("linked-individuals.csv")); + + Set orgs = organizations.stream() + .map(row -> row.get("ogrn")) + .collect(Collectors.toSet()); + assertThat(orgs).hasSize(2); + + List> relations = readRows(tmp.resolve("linked-relations.csv")); + assertThat(relations).hasSize(3); + assertThat(relations).allSatisfy(link -> { + assertThat(orgs).contains(link.get("employerOgrn")); + assertThat(link.get("personId")).isNotBlank(); + }); + } + + @Test + @DisplayName("ИП тоже получает работодателя — он живёт в base профиля") + void ipWithEmployerOgrn() throws Exception { + String spec = """ + {"type":"set","seed":21,"asOf":"2026-11-15","output":"%s", + "members":[{"name":"orgs","kind":"organization","count":1}, + {"name":"ips","kind":"ip","count":2,"employer":"orgs"}]} + """.formatted(jsonPath("ips.csv")); + Path file = tmp.resolve("ips.json"); + Files.writeString(file, spec, StandardCharsets.UTF_8); + + assertThat(run(file)).isZero(); + + List> ips = readRows(tmp.resolve("ips-ip.csv")); + assertThat(ips).hasSize(2); + assertThat(ips).allSatisfy(row -> assertThat(row.get("employerOgrn")).isNotBlank()); + } + + @Test + @DisplayName("Ссылка на несуществующего работодателя — понятная ошибка и код 2") + void invalidEmployerFails() throws Exception { + String spec = """ + {"type":"set","seed":1,"asOf":"2026-11-15","output":"%s", + "members":[{"name":"people","kind":"individual","count":1,"employer":"missing"}]} + """.formatted(jsonPath("broken.csv")); + Path file = tmp.resolve("broken.json"); + Files.writeString(file, spec, StandardCharsets.UTF_8); + + assertThat(run(file)).isEqualTo(2); + + String spec2 = """ + {"type":"set","seed":1,"asOf":"2026-11-15","output":"%s", + "members":[{"name":"people","kind":"individual","count":1}, + {"name":"self","kind":"individual","count":1,"employer":"people"}]} + """.formatted(jsonPath("broken2.csv")); + Files.writeString(file, spec2, StandardCharsets.UTF_8); + + assertThat(run(file)).isEqualTo(2); + } +} diff --git a/validum-cli/src/test/java/ru/validum/cli/SetSummaryTest.java b/validum-cli/src/test/java/ru/validum/cli/SetSummaryTest.java new file mode 100644 index 0000000..b8ba662 --- /dev/null +++ b/validum-cli/src/test/java/ru/validum/cli/SetSummaryTest.java @@ -0,0 +1,97 @@ +package ru.validum.cli; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.Map; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import picocli.CommandLine; +import ru.validum.core.export.CsvImporter; + +/** Сводка набора: все файлы созданы, порядок и детерминизм предсказуемы. */ +class SetSummaryTest { + + @TempDir + Path tmp; + + private Path write(String name, String json) throws Exception { + Path file = tmp.resolve(name); + Files.writeString(file, json, StandardCharsets.UTF_8); + return file; + } + + private String jsonPath(String name) { + return tmp.resolve(name).toAbsolutePath().toString().replace("\\", "/"); + } + + + private static List> readRows(Path file) throws IOException { + String text = Files.readString(file, StandardCharsets.UTF_8); + char delimiter = CsvImporter.detectDelimiter(text.lines().findFirst().orElse("")); + return CsvImporter.parse(text, delimiter); + } + + @Test + @DisplayName("Набор из четырёх участников даёт четыре файла и таблицу связей") + void summaryListsEveryTable() throws Exception { + String spec = """ + {"type":"set","seed":5,"asOf":"2026-11-15","output":"%s", + "members":[{"name":"orgs","kind":"organization","count":1}, + {"name":"people","kind":"individual","count":2,"employer":"orgs"}, + {"name":"ips","kind":"ip","count":1,"employer":"orgs"}]} + """.formatted(jsonPath("all.csv")); + Path file = write("all.json", spec); + + assertThat(new CommandLine(new ValidumCli()).execute("generate", "--spec", file.toString())) + .isZero(); + + assertThat(tmp.resolve("all-organizations.csv")).exists(); + assertThat(tmp.resolve("all-individuals.csv")).exists(); + assertThat(tmp.resolve("all-ip.csv")).exists(); + assertThat(tmp.resolve("all-relations.csv")).exists(); + } + + @Test + @DisplayName("Один seed — один и тот же набор байт в байт") + void sameSeedGivesSameBytes() throws Exception { + String specTemplate = """ + {"type":"set","seed":77,"asOf":"2026-11-15","output":"%s", + "members":[{"name":"orgs","kind":"organization","count":1}, + {"name":"people","kind":"individual","count":2,"employer":"orgs"}]} + """; + Path first = write("a.json", specTemplate.formatted(jsonPath("a.csv"))); + Path second = write("b.json", specTemplate.formatted(jsonPath("b.csv"))); + + assertThat(new CommandLine(new ValidumCli()).execute("generate", "--spec", first.toString())) + .isZero(); + assertThat(new CommandLine(new ValidumCli()).execute("generate", "--spec", second.toString())) + .isZero(); + + List a = Files.readAllLines(tmp.resolve("a-individuals.csv"), StandardCharsets.UTF_8); + List b = Files.readAllLines(tmp.resolve("b-individuals.csv"), StandardCharsets.UTF_8); + assertThat(a).isEqualTo(b); + } + + @Test + @DisplayName("Файл набора: каждый участник получает собственный seed, поэтому набор не пустой") + void everyMemberHasRows() throws Exception { + String spec = """ + {"type":"set","seed":3,"asOf":"2026-11-15","output":"%s", + "members":[{"name":"orgs","kind":"organization","count":1}, + {"name":"people","kind":"individual","count":1,"employer":"orgs"}]} + """.formatted(jsonPath("one.csv")); + Path file = write("one.json", spec); + assertThat(new CommandLine(new ValidumCli()).execute("generate", "--spec", file.toString())) + .isZero(); + + List> rows = readRows(tmp.resolve("one-individuals.csv")); + assertThat(rows).hasSize(1); + assertThat(rows.get(0).get("fullName")).isNotBlank(); + } +} diff --git a/validum-cli/src/test/java/ru/validum/cli/SetTeardownTest.java b/validum-cli/src/test/java/ru/validum/cli/SetTeardownTest.java new file mode 100644 index 0000000..768815b --- /dev/null +++ b/validum-cli/src/test/java/ru/validum/cli/SetTeardownTest.java @@ -0,0 +1,63 @@ +package ru.validum.cli; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import picocli.CommandLine; + +/** Скрипт отката набора: DELETE в обратном порядке, отключается ключом spec. */ +class SetTeardownTest { + + @TempDir + Path tmp; + + private String jsonPath(String name) { + return tmp.resolve(name).toAbsolutePath().toString().replace("\\", "/"); + } + + private Path spec(String name, String json) throws Exception { + Path file = tmp.resolve(name); + Files.writeString(file, json, StandardCharsets.UTF_8); + return file; + } + + @Test + @DisplayName("Набор пишет teardown.sql: сначала люди, потом организации") + void teardownIsWritten() throws Exception { + Path file = spec("t.json", """ + {"type":"set","seed":9,"asOf":"2026-11-15","output":"%s", + "members":[{"name":"orgs","kind":"organization","count":1}, + {"name":"people","kind":"individual","count":2,"employer":"orgs"}]} + """.formatted(jsonPath("t.csv"))); + + assertThat(new CommandLine(new ValidumCli()).execute("generate", "--spec", file.toString())) + .isZero(); + + Path sql = tmp.resolve("t-teardown.sql"); + assertThat(sql).exists(); + String text = Files.readString(sql, StandardCharsets.UTF_8); + assertThat(text).startsWith("-- validum "); + assertThat(text.indexOf("DELETE FROM validum_individual")) + .isLessThan(text.indexOf("DELETE FROM validum_organization")); + assertThat(text).doesNotContain("DROP", "TRUNCATE"); + } + + @Test + @DisplayName("\"teardown\": false — файла нет") + void teardownCanBeDisabled() throws Exception { + Path file = spec("off.json", """ + {"type":"set","seed":9,"asOf":"2026-11-15","teardown":false,"output":"%s", + "members":[{"name":"people","kind":"individual","count":1}]} + """.formatted(jsonPath("off.csv"))); + + assertThat(new CommandLine(new ValidumCli()).execute("generate", "--spec", file.toString())) + .isZero(); + + assertThat(tmp.resolve("off-teardown.sql")).doesNotExist(); + } +} diff --git a/validum-core/src/main/java/ru/validum/core/card/MirCard.java b/validum-core/src/main/java/ru/validum/core/card/MirCard.java new file mode 100644 index 0000000..1333dd2 --- /dev/null +++ b/validum-core/src/main/java/ru/validum/core/card/MirCard.java @@ -0,0 +1,47 @@ +package ru.validum.core.card; + +import java.time.LocalDate; + +/** + * Тестовая карта «Мир»: номер, срок действия и ожидаемый исход операции. + * + *

Номер проходит алгоритм Луна и попадает в реальный BIN-диапазон «Мира» + * (220000–220499), поэтому карта проходит формальную проверку платёжных систем. Это не боевая + * карта: владелец, CVV и ПИН ей не выдаются. + * + * @param pan 16 цифр, проходят Луна + * @param expiryMonth месяц истечения, 1–12 + * @param expiryYear год истечения (полный, например 2029) + * @param outcome ожидаемый исход операции + */ +public record MirCard(String pan, int expiryMonth, int expiryYear, MirCardOutcome outcome) { + + /** Срок действия в виде {@code ММ/ГГ} — так он печатается на карте. */ + public String expiry() { + return String.format("%02d/%02d", expiryMonth, expiryYear % 100); + } + + /** Просрочена ли карта на указанную дату. */ + public boolean expiredAt(LocalDate at) { + LocalDate end = LocalDate.of(expiryYear, expiryMonth, 1).plusMonths(1).minusDays(1); + return end.isBefore(at); + } + + /** Проверка контрольной цифры по алгоритму Луна. */ + public boolean luhnValid() { + int sum = 0; + boolean doubleDigit = false; + for (int i = pan.length() - 1; i >= 0; i--) { + int digit = pan.charAt(i) - '0'; + if (doubleDigit) { + digit *= 2; + if (digit > 9) { + digit -= 9; + } + } + sum += digit; + doubleDigit = !doubleDigit; + } + return sum % 10 == 0; + } +} diff --git a/validum-core/src/main/java/ru/validum/core/card/MirCardGenerator.java b/validum-core/src/main/java/ru/validum/core/card/MirCardGenerator.java new file mode 100644 index 0000000..2fb9452 --- /dev/null +++ b/validum-core/src/main/java/ru/validum/core/card/MirCardGenerator.java @@ -0,0 +1,94 @@ +package ru.validum.core.card; + +import java.time.LocalDate; +import java.util.ArrayList; +import java.util.List; +import java.util.Random; + +/** + * Генератор тестовых карт «Мир». + * + *

Номер: BIN из диапазона «Мира» (220000–220499), 9 случайных цифр и контрольная цифра Луна — + * итого 16. Срок действия — от двух до пяти лет вперёд от даты расчёта. Исход: в девяти случаях из + * десяти успешный, остальные — отказы, распределённые по типам. + */ +public final class MirCardGenerator { + + /** Минимальный BIN «Мира» (включительно). */ + public static final int BIN_MIN = 220_000; + + /** Максимальный BIN «Мира» (включительно). */ + public static final int BIN_MAX = 220_499; + + /** Сколько цифр номера занимает BIN. */ + private static final int BIN_DIGITS = 6; + + /** Полная длина номера карты «Мир». */ + private static final int PAN_LENGTH = 16; + + private static final long SUCCESS_WEIGHT = 90; + + private final Random random; + + public MirCardGenerator(Random random) { + this.random = random; + } + + /** Одна карта; срок действия считается от даты расчёта. */ + public MirCard next(LocalDate asOf) { + return new MirCard(pan(), 1 + random.nextInt(12), asOf.getYear() + 2 + random.nextInt(4), + outcome()); + } + + /** Несколько карт одного клиента. */ + public List next(LocalDate asOf, int count) { + List cards = new ArrayList<>(Math.max(0, count)); + for (int i = 0; i < count; i++) { + cards.add(next(asOf)); + } + return cards; + } + + /** Девять успешных из десяти; остальные — равномерно между отказами. */ + private MirCardOutcome outcome() { + if (random.nextInt(100) < SUCCESS_WEIGHT) { + return MirCardOutcome.SUCCESS; + } + MirCardOutcome[] declines = { + MirCardOutcome.INSUFFICIENT_FUNDS, + MirCardOutcome.LIMIT_EXCEEDED, + MirCardOutcome.CARD_EXPIRED, + MirCardOutcome.ISSUER_DECLINED, + MirCardOutcome.INVALID_CARD, + }; + return declines[random.nextInt(declines.length)]; + } + + /** 16 цифр: BIN + 9 случайных + контрольная цифра Луна. */ + private String pan() { + StringBuilder sb = new StringBuilder(PAN_LENGTH); + sb.append(BIN_MIN + random.nextInt(BIN_MAX - BIN_MIN + 1)); + while (sb.length() < PAN_LENGTH - 1) { + sb.append(random.nextInt(10)); + } + sb.append(luhnCheckDigit(sb.toString())); + return sb.toString(); + } + + private static char luhnCheckDigit(String partial) { + int sum = 0; + boolean doubleDigit = true; + for (int i = partial.length() - 1; i >= 0; i--) { + int digit = partial.charAt(i) - '0'; + if (doubleDigit) { + digit *= 2; + if (digit > 9) { + digit -= 9; + } + } + sum += digit; + doubleDigit = !doubleDigit; + } + return (char) ('0' + (10 - sum % 10) % 10); + } +} diff --git a/validum-core/src/main/java/ru/validum/core/card/MirCardOutcome.java b/validum-core/src/main/java/ru/validum/core/card/MirCardOutcome.java new file mode 100644 index 0000000..2a407f7 --- /dev/null +++ b/validum-core/src/main/java/ru/validum/core/card/MirCardOutcome.java @@ -0,0 +1,39 @@ +package ru.validum.core.card; + +/** + * Ожидаемый исход операции по карте «Мир» — то, что платёжный шлюз вернёт в тестовой среде. + * + *

Для большинства тестовых карт нужен успешный исход; карты с отказом позволяют проверить + * обработку ошибок в АБС и фронте без реального терминала. + */ +public enum MirCardOutcome { + + /** Операция разрешена. */ + SUCCESS("успех"), + + /** Недостаточно средств на счёте. */ + INSUFFICIENT_FUNDS("недостаточно средств"), + + /** Превышен лимит операции. */ + LIMIT_EXCEEDED("превышен лимит"), + + /** Срок действия карты истёк. */ + CARD_EXPIRED("карта просрочена"), + + /** Эмитент отклонил операцию. */ + ISSUER_DECLINED("отказ эмитента"), + + /** Карта недействительна (закрыта, заблокирована). */ + INVALID_CARD("карта недействительна"); + + private final String russianName; + + MirCardOutcome(String russianName) { + this.russianName = russianName; + } + + /** Человеческое название исхода для отчётов и `describe`. */ + public String russianName() { + return russianName; + } +} diff --git a/validum-core/src/main/java/ru/validum/core/export/CardsCsv.java b/validum-core/src/main/java/ru/validum/core/export/CardsCsv.java new file mode 100644 index 0000000..3f0169b --- /dev/null +++ b/validum-core/src/main/java/ru/validum/core/export/CardsCsv.java @@ -0,0 +1,37 @@ +package ru.validum.core.export; + +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import ru.validum.core.card.MirCard; + +/** + * Таблица карт «Мир» для режима {@code --cards N} (N больше единицы): одна строка — одна карта, + * связь с человеком через {@code personId}. + */ +public final class CardsCsv { + + /** Заголовок таблицы. */ + public static final List SPLIT_HEADER = + List.of("personId", "pan", "expiry", "outcome"); + + private CardsCsv() {} + + /** Строки таблицы для одного клиента. */ + public static List> toRows(String personId, List cards) { + List> rows = new ArrayList<>(); + if (cards == null) { + return rows; + } + for (MirCard card : cards) { + Map row = new LinkedHashMap<>(); + row.put("personId", personId == null ? "" : personId); + row.put("pan", card.pan()); + row.put("expiry", card.expiry()); + row.put("outcome", card.outcome().russianName()); + rows.add(row); + } + return rows; + } +} diff --git a/validum-core/src/main/java/ru/validum/core/export/CsvExporter.java b/validum-core/src/main/java/ru/validum/core/export/CsvExporter.java index 942b452..49e25fa 100644 --- a/validum-core/src/main/java/ru/validum/core/export/CsvExporter.java +++ b/validum-core/src/main/java/ru/validum/core/export/CsvExporter.java @@ -167,6 +167,7 @@ private static Map keyByRussian() { private static Map rusHeadersMap() { Map m = new LinkedHashMap<>(); m.put("personId", "Идентификатор"); + m.put("employerOgrn", "ОГРН работодателя"); m.put("fullName", "ФИО"); m.put("gender", "Пол"); m.put("birthDate", "Дата рождения"); @@ -227,6 +228,10 @@ private static Map rusHeadersMap() { m.put("bankCity", "Город банка"); m.put("bankRegion", "Регион банка"); m.put("account", "Счёт"); + m.put("cardPan", "Номер карты"); + m.put("cardExpiry", "Срок действия карты"); + m.put("cardOutcome", "Исход операции по карте"); + m.put("cardCount", "Карт у клиента"); m.put("documents", "Документы"); m.put("isResident", "Резидент"); m.put("citizenship", "Гражданство"); diff --git a/validum-core/src/main/java/ru/validum/core/export/IndividualProfileFlattener.java b/validum-core/src/main/java/ru/validum/core/export/IndividualProfileFlattener.java index b410fee..f89a933 100644 --- a/validum-core/src/main/java/ru/validum/core/export/IndividualProfileFlattener.java +++ b/validum-core/src/main/java/ru/validum/core/export/IndividualProfileFlattener.java @@ -3,6 +3,7 @@ import java.time.LocalDate; import java.util.LinkedHashMap; import java.util.List; +import ru.validum.core.card.MirCard; import java.util.Map; import ru.validum.core.address.Address; import ru.validum.core.bank.Bank; @@ -50,6 +51,7 @@ public static Map flatten(IndividualProfile p) { public static Map flatten(IndividualProfile p, DocumentsFormat format) { Map m = new LinkedHashMap<>(); m.put("personId", p.personId() == null ? "" : p.personId()); + m.put("employerOgrn", p.employerOgrn() == null ? "" : p.employerOgrn()); m.put("fullName", p.fullName()); m.put("gender", p.gender().name()); m.put("birthDate", formatDate(p.birthDate())); @@ -71,6 +73,7 @@ public static Map flatten(IndividualProfile p, DocumentsFormat f m.put("blocked", String.valueOf(p.blocked())); flattenBank(m, p.bank()); m.put("account", p.account()); + flattenCards(m, p.cards()); List documents = p.documents() == null ? List.of() : p.documents(); m.put(DocumentsCsv.COLUMN, switch (format) { case JSON -> DocumentsCsv.json(documents); @@ -108,6 +111,19 @@ private static void flattenAddress(Map m, String prefix, Address m.put(prefix + "Formatted", a.formatted()); } + /** + * Карты «Мир»: в плоской строке — первая карта и их количество. Подробности по каждой карте + * живут в отдельной таблице ({@link CardsCsv}), чтобы не плодить колонки {@code card1*, card2*}. + */ + private static void flattenCards(Map m, List cards) { + List list = cards == null ? List.of() : cards; + MirCard first = list.isEmpty() ? null : list.get(0); + m.put("cardPan", first == null ? "" : first.pan()); + m.put("cardExpiry", first == null ? "" : first.expiry()); + m.put("cardOutcome", first == null ? "" : first.outcome().russianName()); + m.put("cardCount", String.valueOf(list.size())); + } + private static void flattenContact(Map m, String prefix, Contact c) { if (c == null) return; m.put(prefix + "Type", c.type().name()); diff --git a/validum-core/src/main/java/ru/validum/core/export/NestedWriter.java b/validum-core/src/main/java/ru/validum/core/export/NestedWriter.java new file mode 100644 index 0000000..12b6ccf --- /dev/null +++ b/validum-core/src/main/java/ru/validum/core/export/NestedWriter.java @@ -0,0 +1,211 @@ +package ru.validum.core.export; + +import java.util.List; +import ru.validum.core.address.Address; +import ru.validum.core.card.MirCard; +import ru.validum.core.contact.Contact; +import ru.validum.core.document.IdentityDocument; +import ru.validum.core.passport.Passport; +import ru.validum.core.profile.IndividualProfile; + +/** + * Вложенный JSON профиля — та же структура, что отдаёт REST ({@code IndividualProfileDto}), но для + * файла: группы {@code passport}, {@code addresses}, {@code contacts}, {@code bank}, {@code cards}, + * {@code documents}. + * + *

Плоская выдача ({@code csv}/{@code json-array}) остаётся контрактом для колонок и SQL; вложенная + * нужна там, где данные читают глазами или отдают в другой сервис. Своя сериализация — потому что + * {@code validum-core} не тянет зависимостей. + */ +public final class NestedWriter { + + private NestedWriter() {} + + /** Полный JSON-объект: {@code {"count":N,"seed":S,"profiles":[…]}}. */ + public static String toJson(List profiles, Long seed) { + StringBuilder sb = new StringBuilder(256 * Math.max(1, profiles.size())); + sb.append('{'); + sb.append("\"count\":").append(profiles.size()); + if (seed != null) { + sb.append(",\"seed\":").append(seed); + } + sb.append(",\"profiles\":["); + for (int i = 0; i < profiles.size(); i++) { + if (i > 0) { + sb.append(','); + } + appendProfile(sb, profiles.get(i)); + } + sb.append("]}"); + return sb.toString(); + } + + private static void appendProfile(StringBuilder sb, IndividualProfile p) { + sb.append('{'); + field(sb, "personId", p.personId()).append(','); + field(sb, "employerOgrn", p.employerOgrn()).append(','); + field(sb, "fullName", p.fullName()).append(','); + field(sb, "gender", p.gender().name()).append(','); + field(sb, "birthDate", String.valueOf(p.birthDate())).append(','); + field(sb, "age", String.valueOf(p.age())).append(','); + field(sb, "familyStatus", p.familyStatus().russianName()).append(','); + field(sb, "inn", p.inn()).append(','); + field(sb, "snils", p.snils()).append(','); + + sb.append("\"passport\":"); + appendPassport(sb, p.passport()); + sb.append(','); + + sb.append("\"addresses\":{"); + sb.append("\"registration\":"); + appendAddress(sb, p.registrationAddress()); + sb.append(",\"post\":"); + appendAddress(sb, p.postAddress()); + sb.append(",\"current\":"); + appendAddress(sb, p.currentAddress()); + sb.append("},\"contacts\":{"); + sb.append("\"mobile\":"); + appendContact(sb, p.mobile()); + sb.append(",\"email\":"); + appendContact(sb, p.email()); + sb.append("},\"bank\":"); + appendBank(sb, p); + sb.append(','); + field(sb, "account", p.account()).append(','); + sb.append("\"cards\":["); + List cards = p.cards() == null ? List.of() : p.cards(); + for (int i = 0; i < cards.size(); i++) { + if (i > 0) { + sb.append(','); + } + appendCard(sb, cards.get(i)); + } + sb.append("],\"documents\":["); + List docs = p.documents() == null ? List.of() : p.documents(); + for (int i = 0; i < docs.size(); i++) { + if (i > 0) { + sb.append(','); + } + appendDocument(sb, docs.get(i)); + } + sb.append("],"); + field(sb, "secretWord", p.secretWord()).append(','); + field(sb, "categoryClient", p.categoryClient()).append(','); + field(sb, "accountPackage", p.accountPackage()).append(','); + field(sb, "personalManager", p.personalManager()).append(','); + field(sb, "terrorist", String.valueOf(p.terrorist())).append(','); + field(sb, "blocked", String.valueOf(p.blocked())).append(','); + field(sb, "isResident", String.valueOf(p.residency() != null && p.residency().isResident())) + .append(','); + field(sb, "citizenship", p.residency() == null ? null : p.residency().citizenship().isoCode()) + .append(','); + field(sb, "asOf", String.valueOf(p.asOf())).append('}'); + } + + private static void appendPassport(StringBuilder sb, Passport passport) { + if (passport == null) { + sb.append("null"); + return; + } + sb.append('{'); + field(sb, "series", passport.series()).append(','); + field(sb, "number", passport.number()).append(','); + field(sb, "issuedBy", passport.issuedBy()).append(','); + field(sb, "issueDate", String.valueOf(passport.issueDate())).append(','); + field(sb, "expirationDate", String.valueOf(passport.expirationDate())).append(','); + field(sb, "departmentCode", passport.departmentCode()).append(','); + field(sb, "status", passport.status()).append(','); + field(sb, "type", passport.type() == null ? null : passport.type().name()).append(','); + field(sb, "country", passport.country() == null ? null : passport.country().isoCode()) + .append('}'); + } + + private static void appendAddress(StringBuilder sb, Address a) { + if (a == null) { + sb.append("null"); + return; + } + sb.append('{'); + field(sb, "postalCode", a.postalCode()).append(','); + field(sb, "region", a.region()).append(','); + field(sb, "regionType", a.regionType()).append(','); + field(sb, "district", a.district()).append(','); + field(sb, "city", a.city()).append(','); + field(sb, "street", a.street()).append(','); + field(sb, "building", a.building()).append(','); + field(sb, "apartment", a.apartment()).append(','); + field(sb, "expectedAddress", a.expectedAddress()).append('}'); + } + + private static void appendContact(StringBuilder sb, Contact c) { + if (c == null) { + sb.append("null"); + return; + } + sb.append('{'); + field(sb, "value", c.value()).append(','); + field(sb, "type", c.type() == null ? null : c.type().name()).append('}'); + } + + private static void appendBank(StringBuilder sb, IndividualProfile p) { + if (p.bank() == null) { + sb.append("null"); + return; + } + sb.append('{'); + field(sb, "bik", p.bank().bik()).append(','); + field(sb, "name", p.bank().name()).append(','); + field(sb, "corrAccount", p.bank().corrAccount()).append(','); + field(sb, "city", p.bank().city()).append('}'); + } + + private static void appendCard(StringBuilder sb, MirCard card) { + sb.append('{'); + field(sb, "pan", card.pan()).append(','); + field(sb, "expiry", card.expiry()).append(','); + field(sb, "outcome", card.outcome().russianName()).append('}'); + } + + private static void appendDocument(StringBuilder sb, IdentityDocument d) { + sb.append('{'); + field(sb, "type", d.type() == null ? null : d.type().name()).append(','); + field(sb, "series", d.series()).append(','); + field(sb, "number", d.number()).append(','); + field(sb, "issuedBy", d.issuedBy()).append(','); + field(sb, "issueDate", String.valueOf(d.issueDate())).append(','); + field(sb, "expirationDate", String.valueOf(d.expirationDate())).append(','); + field(sb, "departmentCode", d.departmentCode()).append('}'); + } + + private static StringBuilder field(StringBuilder sb, String name, String value) { + sb.append('"').append(name).append("\":"); + if (value == null) { + sb.append("null"); + } else { + sb.append('"').append(escape(value)).append('"'); + } + return sb; + } + + private static String escape(String value) { + StringBuilder sb = new StringBuilder(value.length() + 8); + for (int i = 0; i < value.length(); i++) { + char c = value.charAt(i); + switch (c) { + case '"' -> sb.append("\\\""); + case '\\' -> sb.append("\\\\"); + case '\n' -> sb.append("\\n"); + case '\r' -> sb.append("\\r"); + case '\t' -> sb.append("\\t"); + default -> { + if (c < 0x20) { + sb.append(String.format("\\u%04x", (int) c)); + } else { + sb.append(c); + } + } + } + } + return sb.toString(); + } +} diff --git a/validum-core/src/main/java/ru/validum/core/export/ProfileFromCsv.java b/validum-core/src/main/java/ru/validum/core/export/ProfileFromCsv.java index 54a8ea0..c3097df 100644 --- a/validum-core/src/main/java/ru/validum/core/export/ProfileFromCsv.java +++ b/validum-core/src/main/java/ru/validum/core/export/ProfileFromCsv.java @@ -6,6 +6,8 @@ import java.util.Map; import ru.validum.core.address.Address; import ru.validum.core.bank.Bank; +import ru.validum.core.card.MirCard; +import ru.validum.core.card.MirCardOutcome; import ru.validum.core.common.Country; import ru.validum.core.contact.Contact; import ru.validum.core.contact.ContactType; @@ -65,7 +67,33 @@ public static IndividualProfile parse(Map row) { row.get("account"), DocumentsCsv.parse(row.get(DocumentsCsv.COLUMN)), asOf(row), - blankToNull(row.get("personId"))); + blankToNull(row.get("personId")), + blankToNull(row.get("employerOgrn")), + card(row)); + } + + /** Карта из плоской строки; пустой номер — карт нет. */ + private static List card(Map row) { + String pan = blankToNull(row.get("cardPan")); + if (pan == null) { + return List.of(); + } + String expiry = row.get("cardExpiry"); + int month = 1; + int year = 0; + if (expiry != null && expiry.matches("\\d{2}/\\d{2}")) { + month = Integer.parseInt(expiry.substring(0, 2)); + year = 2000 + Integer.parseInt(expiry.substring(3, 5)); + } + String outcome = row.get("cardOutcome"); + MirCardOutcome resolved = MirCardOutcome.SUCCESS; + for (MirCardOutcome candidate : MirCardOutcome.values()) { + if (candidate.russianName().equals(outcome)) { + resolved = candidate; + break; + } + } + return List.of(new MirCard(pan, month, year, resolved)); } private static String blankToNull(String value) { diff --git a/validum-core/src/main/java/ru/validum/core/profile/IndividualProfile.java b/validum-core/src/main/java/ru/validum/core/profile/IndividualProfile.java index a5336c5..7f0be5f 100644 --- a/validum-core/src/main/java/ru/validum/core/profile/IndividualProfile.java +++ b/validum-core/src/main/java/ru/validum/core/profile/IndividualProfile.java @@ -2,6 +2,7 @@ import java.time.LocalDate; import java.util.List; +import ru.validum.core.card.MirCard; import ru.validum.core.address.Address; import ru.validum.core.bank.Bank; import ru.validum.core.contact.Contact; @@ -88,7 +89,20 @@ public record IndividualProfile( * (см. {@link ru.validum.core.common.PersonIds}). Пусто у профилей, собранных без seed — * например, при импорте CSV без колонки {@code personId}. */ - String personId) { + String personId, + + /** + * ОГРН работодателя — юридического лица, где клиент работает. Пусто, если клиент не трудоустроен + * или работодатель не задан (например, при импорте CSV без этой колонки). Связь односторонняя: + * профиль ЮЛ про своих сотрудников ничего не знает, набор строится в CLI. + */ + String employerOgrn, + + /** + * Карты «Мир» клиента: {@code --cards N} в CLI, по умолчанию одна. Пустой список — карт нет + * (например, при импорте CSV без этой колонки или при {@code --cards 0}). + */ + List cards) { /** Полное ФИО одной строкой. */ public String fullName() { @@ -144,6 +158,8 @@ public IndividualProfile withName(PersonName newName) { account, documents, asOf, - personId); + personId, + employerOgrn, + cards); } } diff --git a/validum-core/src/main/java/ru/validum/core/profile/IndividualProfileBuilder.java b/validum-core/src/main/java/ru/validum/core/profile/IndividualProfileBuilder.java index d99e69e..0e33fdb 100644 --- a/validum-core/src/main/java/ru/validum/core/profile/IndividualProfileBuilder.java +++ b/validum-core/src/main/java/ru/validum/core/profile/IndividualProfileBuilder.java @@ -57,6 +57,8 @@ public final class IndividualProfileBuilder { List documentTypes = List.of(); boolean autoDocuments; LocalDate asOf; + String employerOgrn; + int cardCount = 1; IndividualProfileBuilder() {} @@ -82,6 +84,29 @@ public IndividualProfileBuilder asOf(LocalDate date) { return this; } + /** + * ОГРН работодателя (13 цифр) — юридического лица, где работает клиент. + * + *

Значение не проверяется: генератор не знает профиль ЮЛ, а набор в CLI связывает профили + * сам. Пустое значение — клиент без работодателя. + */ + public IndividualProfileBuilder employer(String ogrn) { + this.employerOgrn = ogrn; + return this; + } + + /** + * Сколько карт «Мир» выдать клиенту: 0 — без карт, 1 — одна карта в профиле (по умолчанию), + * больше — столько же строк в отдельной таблице карт. + */ + public IndividualProfileBuilder cards(int count) { + if (count < 0) { + throw new IllegalArgumentException("Число карт не может быть отрицательным: " + count); + } + this.cardCount = count; + return this; + } + public IndividualProfileBuilder bikSource(BikSource source) { this.bikSource = source; return this; diff --git a/validum-core/src/main/java/ru/validum/core/profile/IndividualProfileGenerator.java b/validum-core/src/main/java/ru/validum/core/profile/IndividualProfileGenerator.java index 02824e6..7ad46ce 100644 --- a/validum-core/src/main/java/ru/validum/core/profile/IndividualProfileGenerator.java +++ b/validum-core/src/main/java/ru/validum/core/profile/IndividualProfileGenerator.java @@ -24,6 +24,8 @@ import ru.validum.core.bank.Bank; import ru.validum.core.bank.BikGenerator; import ru.validum.core.bank.BikSource; +import ru.validum.core.card.MirCard; +import ru.validum.core.card.MirCardGenerator; import ru.validum.core.bank.BikSources; import ru.validum.core.common.Country; import ru.validum.core.common.PersonIds; @@ -118,6 +120,9 @@ public final class IndividualProfileGenerator implements DataGenerator { private final boolean autoDocuments; private final LocalDate asOf; private final Long seedValue; + private final String employerOgrn; + private final int cardCount; + private long cardCounter; private final NameGenerator nameGen; private final PassportGenerator passportGen; @@ -166,6 +171,8 @@ public final class IndividualProfileGenerator implements DataGenerator { this.autoDocuments = b.autoDocuments; this.asOf = b.asOf != null ? b.asOf : LocalDate.now(); this.seedValue = b.seedValue; + this.employerOgrn = b.employerOgrn; + this.cardCount = b.cardCount; this.nameGen = new NameGenerator(random); this.passportGen = new PassportGenerator(random); @@ -279,6 +286,10 @@ public IndividualProfile generate() { : null; List documents = generateDocuments(g, birthDate, a, asOf, regionCode); + // Свой поток для карт: генерация карты не должна сдвигать случайные числа остальных полей + // (иначе каждое новое поле меняет весь профиль и ломает эталоны и пулы). + long cardSeed = seedValue != null ? seedValue * 1_000_003L + cardCounter++ : ++cardCounter * 7_919L; + List cards = new MirCardGenerator(new Random(cardSeed)).next(asOf, cardCount); // personId детерминирован seed: тот же seed → тот же идентификатор в CLI и REST. String personId = seedValue == null ? null : PersonIds.of(seedValue); @@ -307,7 +318,9 @@ public IndividualProfile generate() { account, documents, asOf, - personId); + personId, + employerOgrn, + cards); } /** Возраст профиля: явное значение, иначе диапазон с распределением, иначе каскадный дефолт. */ diff --git a/validum-core/src/main/java/ru/validum/core/report/Coverage.java b/validum-core/src/main/java/ru/validum/core/report/Coverage.java index d4bb60b..ac7fe40 100644 --- a/validum-core/src/main/java/ru/validum/core/report/Coverage.java +++ b/validum-core/src/main/java/ru/validum/core/report/Coverage.java @@ -27,12 +27,13 @@ public final class Coverage { "fullName", "gender", "birthDate", "age", "inn", "snils", "passportSeries", "passportNumber", "passportIssuedAt", "passportIssuer", "organizationName", "organizationType", "ogrn", "ogrnip", "kpp", "okpo", - "bankBik", "account", "address", "okved", "asOf"); + "bankBik", "account", "cardPan", "address", "okved", "asOf"); /** Есть ли публичная проверка контрольной суммы у поля. */ public static boolean isChecked(String field) { return switch (field) { - case "inn", "snils", "ogrn", "ogrnip", "account", "kpp", "okpo", "bankBik" -> true; + case "inn", "snils", "ogrn", "ogrnip", "account", "kpp", "okpo", "bankBik", + "cardPan" -> true; default -> false; }; } @@ -56,10 +57,30 @@ public static Boolean valid(String field, String value, Map row) // BikValidator требует справочник; здесь проверяем только формат (9 цифр). case "bankBik" -> value.matches("\\d{9}"); case "account" -> AccountValidator.isValidAuto(value, bankOf(row)); + // Карта «Мир»: 16 цифр, BIN 220000–220499 и контрольная цифра по алгоритму Луна. + case "cardPan" -> value.matches("220\\d{13}") && luhnValid(value); default -> null; }; } + /** Алгоритм Луна — тот же, что в {@link ru.validum.core.card.MirCard#luhnValid()}. */ + private static boolean luhnValid(String pan) { + int sum = 0; + boolean doubleDigit = false; + for (int i = pan.length() - 1; i >= 0; i--) { + int digit = pan.charAt(i) - '0'; + if (doubleDigit) { + digit *= 2; + if (digit > 9) { + digit -= 9; + } + } + sum += digit; + doubleDigit = !doubleDigit; + } + return sum % 10 == 0; + } + private static String bankOf(Map row) { for (String key : List.of("bankBik", "bik")) { String value = row.get(key); diff --git a/validum-core/src/main/java/ru/validum/core/sql/TeardownSql.java b/validum-core/src/main/java/ru/validum/core/sql/TeardownSql.java new file mode 100644 index 0000000..c63d1a4 --- /dev/null +++ b/validum-core/src/main/java/ru/validum/core/sql/TeardownSql.java @@ -0,0 +1,55 @@ +package ru.validum.core.sql; + +import java.util.ArrayList; +import java.util.List; + +/** + * Сценарий отката: {@code DELETE} по уже вставленным строкам, в порядке, обратном загрузке. + * + *

Никакого DDL: таблицы создаются и удаляются снаружи, скрипт лишь убирает строки, которые + * создал прогон, — чтобы после проверки стенд остался в том же состоянии, что был до загрузки. + */ +public final class TeardownSql { + + /** Одна таблица: имя, колонка-ключ и значения ключей из этого прогона. */ + public record Table(String table, String keyColumn, List keys) { + + public Table { + keys = List.copyOf(keys); + } + } + + /** Сколько ключей попадает в один {@code DELETE … IN (…)}. */ + public static final int CHUNK = 200; + + private TeardownSql() {} + + /** Будущие строки: порядок как при загрузке (родители раньше детей). */ + public static String build(String header, List tables) { + StringBuilder sb = new StringBuilder(); + sb.append("-- ").append(header).append('\n'); + sb.append("-- Порядок удаления — обратный порядку загрузки.\n\n"); + for (int i = tables.size() - 1; i >= 0; i--) { + Table table = tables.get(i); + for (List chunk : chunks(table.keys())) { + sb.append("DELETE FROM ").append(table.table()) + .append(" WHERE ").append(table.keyColumn()).append(" IN (") + .append(String.join(", ", chunk.stream().map(TeardownSql::quote).toList())) + .append(");\n"); + } + } + return sb.toString(); + } + + private static List> chunks(List keys) { + List> result = new ArrayList<>(); + for (int start = 0; start < keys.size(); start += CHUNK) { + result.add(keys.subList(start, Math.min(start + CHUNK, keys.size()))); + } + return result; + } + + private static String quote(String value) { + return "'" + value.replace("'", "''") + "'"; + } +} diff --git a/validum-core/src/test/java/ru/validum/core/card/MirCardGeneratorTest.java b/validum-core/src/test/java/ru/validum/core/card/MirCardGeneratorTest.java new file mode 100644 index 0000000..fb6e5b2 --- /dev/null +++ b/validum-core/src/test/java/ru/validum/core/card/MirCardGeneratorTest.java @@ -0,0 +1,72 @@ +package ru.validum.core.card; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.time.LocalDate; +import java.util.ArrayList; +import java.util.EnumSet; +import java.util.List; +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +/** Карта «Мир»: BIN, Луна, срок действия и распределение исходов. */ +class MirCardGeneratorTest { + + private static final LocalDate AS_OF = LocalDate.of(2026, 1, 15); + + @Test + @DisplayName("Номер в BIN «Мира», 16 цифр и проходит Луна") + void pansAreValid() { + MirCardGenerator gen = new MirCardGenerator(new Random(42)); + + for (int i = 0; i < 1_000; i++) { + MirCard card = gen.next(AS_OF); + assertThat(card.pan()).hasSize(16).startsWith("220"); + int bin = Integer.parseInt(card.pan().substring(0, 6)); + assertThat(bin).isBetween(MirCardGenerator.BIN_MIN, MirCardGenerator.BIN_MAX); + assertThat(card.luhnValid()).as("Луна для %s", card.pan()).isTrue(); + } + } + + @Test + @DisplayName("Срок действия в будущем относительно даты расчёта") + void expiryIsInFuture() { + MirCardGenerator gen = new MirCardGenerator(new Random(7)); + + for (int i = 0; i < 200; i++) { + MirCard card = gen.next(AS_OF); + assertThat(card.expiryMonth()).isBetween(1, 12); + assertThat(card.expiryYear()).isBetween(AS_OF.getYear() + 2, AS_OF.getYear() + 5); + assertThat(card.expiredAt(AS_OF)).isFalse(); + assertThat(card.expiry()).matches("\\d{2}/\\d{2}"); + } + } + + @Test + @DisplayName("Исходы: успех доминирует, отказы тоже встречаются") + void outcomesAreMixed() { + MirCardGenerator gen = new MirCardGenerator(new Random(11)); + List cards = new ArrayList<>(); + for (int i = 0; i < 1_000; i++) { + cards.add(gen.next(AS_OF)); + } + + long success = cards.stream().filter(c -> c.outcome() == MirCardOutcome.SUCCESS).count(); + EnumSet seen = EnumSet.noneOf(MirCardOutcome.class); + cards.forEach(c -> seen.add(c.outcome())); + + assertThat(success).isBetween(800L, 960L); + assertThat(seen.size()).isGreaterThan(1); + assertThat(MirCardOutcome.INSUFFICIENT_FUNDS.russianName()).isEqualTo("недостаточно средств"); + } + + @Test + @DisplayName("Пачка карт одного клиента") + void generatesBatch() { + MirCardGenerator gen = new MirCardGenerator(new Random(3)); + List cards = gen.next(AS_OF, 3); + assertThat(cards).hasSize(3).allSatisfy(c -> assertThat(c.luhnValid()).isTrue()); + assertThat(gen.next(AS_OF, 0)).isEmpty(); + } +} diff --git a/validum-core/src/test/java/ru/validum/core/export/CardsFlatOutputTest.java b/validum-core/src/test/java/ru/validum/core/export/CardsFlatOutputTest.java new file mode 100644 index 0000000..fe7cc51 --- /dev/null +++ b/validum-core/src/test/java/ru/validum/core/export/CardsFlatOutputTest.java @@ -0,0 +1,62 @@ +package ru.validum.core.export; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.Map; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import ru.validum.core.TestProfiles; +import ru.validum.core.card.MirCard; +import ru.validum.core.profile.IndividualProfile; + +/** Карта в плоской выдаче: одна карта в профиле, ноль карт, круговая операция. */ +class CardsFlatOutputTest { + + @Test + @DisplayName("Одна карта по умолчанию: pan, срок, исход и счётчик") + void defaultCardIsInProfile() { + IndividualProfile profile = TestProfiles.individual(9_101); + Map row = IndividualProfileFlattener.flatten(profile); + + assertThat(profile.cards()).hasSize(1); + assertThat(row.get("cardPan")).isEqualTo(profile.cards().get(0).pan()); + assertThat(row.get("cardExpiry")).matches("\\d{2}/\\d{2}"); + assertThat(row.get("cardOutcome")).isNotEmpty(); + assertThat(row.get("cardCount")).isEqualTo("1"); + } + + @Test + @DisplayName("--cards 0: карт нет, колонки пустые, счётчик 0") + void noCards() { + IndividualProfile profile = TestProfiles.builder(9_102).cards(0).build().generate(); + Map row = IndividualProfileFlattener.flatten(profile); + + assertThat(profile.cards()).isEmpty(); + assertThat(row.get("cardPan")).isEmpty(); + assertThat(row.get("cardCount")).isEqualTo("0"); + } + + @Test + @DisplayName("Несколько карт: в строке первая, счётчик показывает количество") + void severalCards() { + IndividualProfile profile = TestProfiles.builder(9_103).cards(3).build().generate(); + Map row = IndividualProfileFlattener.flatten(profile); + + assertThat(profile.cards()).hasSize(3); + assertThat(row.get("cardPan")).isEqualTo(profile.cards().get(0).pan()); + assertThat(row.get("cardCount")).isEqualTo("3"); + } + + @Test + @DisplayName("Круговая операция flatten → parse сохраняет карту") + void roundTripKeepsCard() { + IndividualProfile profile = TestProfiles.individual(9_104); + MirCard card = profile.cards().get(0); + + IndividualProfile restored = ProfileFromCsv.parse(IndividualProfileFlattener.flatten(profile)); + + assertThat(restored.cards()).hasSize(1); + assertThat(restored.cards().get(0).pan()).isEqualTo(card.pan()); + assertThat(restored.cards().get(0).outcome()).isEqualTo(card.outcome()); + } +} diff --git a/validum-core/src/test/java/ru/validum/core/export/NestedWriterTest.java b/validum-core/src/test/java/ru/validum/core/export/NestedWriterTest.java new file mode 100644 index 0000000..2595135 --- /dev/null +++ b/validum-core/src/test/java/ru/validum/core/export/NestedWriterTest.java @@ -0,0 +1,48 @@ +package ru.validum.core.export; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.List; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import ru.validum.core.TestProfiles; +import ru.validum.core.profile.IndividualProfile; + +/** Вложенный JSON: структура профиля, а не плоская строка. */ +class NestedWriterTest { + + @Test + @DisplayName("Профиль разложен на passport / addresses / bank / cards / documents") + void nestedStructure() { + IndividualProfile profile = TestProfiles.individual(7_001); + + String json = NestedWriter.toJson(List.of(profile), 42L); + + assertThat(json).startsWith("{\"count\":1,\"seed\":42,\"profiles\":[{"); + assertThat(json).contains("\"passport\":{"); + assertThat(json).contains("\"addresses\":{\"registration\":{"); + assertThat(json).contains("\"contacts\":{"); + assertThat(json).contains("\"bank\":{\"bik\":"); + assertThat(json).contains("\"cards\":[{"); + assertThat(json).contains("\"pan\":\"220"); + assertThat(json).contains("\"expiry\":\""); + assertThat(json).contains("\"documents\":["); + assertThat(json).contains("\"isResident\":\"true\""); + assertThat(json).doesNotContain("\n"); + } + + @Test + @DisplayName("Без seed поле seed не выводится") + void withoutSeed() { + String json = NestedWriter.toJson(List.of(TestProfiles.individual(7_002)), null); + + assertThat(json).startsWith("{\"count\":1,\"profiles\":["); + assertThat(json).doesNotContain("\"seed\""); + } + + @Test + @DisplayName("Пустой список профилей — валидный объект") + void emptyList() { + assertThat(NestedWriter.toJson(List.of(), 5L)).isEqualTo("{\"count\":0,\"seed\":5,\"profiles\":[]}"); + } +} diff --git a/validum-core/src/test/java/ru/validum/core/export/ProfileFlattenersTest.java b/validum-core/src/test/java/ru/validum/core/export/ProfileFlattenersTest.java index 163781f..59072e7 100644 --- a/validum-core/src/test/java/ru/validum/core/export/ProfileFlattenersTest.java +++ b/validum-core/src/test/java/ru/validum/core/export/ProfileFlattenersTest.java @@ -87,8 +87,13 @@ void columnOrderIsStable() { List keys = List.copyOf(row.keySet()); assertThat(keys.get(0)).isEqualTo("personId"); - assertThat(keys.get(1)).isEqualTo("fullName"); - assertThat(keys.get(keys.size() - 5)).isEqualTo("account"); + assertThat(keys.get(1)).isEqualTo("employerOgrn"); + assertThat(keys.get(2)).isEqualTo("fullName"); + assertThat(keys.get(keys.size() - 9)).isEqualTo("account"); + assertThat(keys.get(keys.size() - 8)).isEqualTo("cardPan"); + assertThat(keys.get(keys.size() - 7)).isEqualTo("cardExpiry"); + assertThat(keys.get(keys.size() - 6)).isEqualTo("cardOutcome"); + assertThat(keys.get(keys.size() - 5)).isEqualTo("cardCount"); assertThat(keys.get(keys.size() - 4)).isEqualTo("documents"); assertThat(keys.get(keys.size() - 3)).isEqualTo("isResident"); assertThat(keys.get(keys.size() - 2)).isEqualTo("citizenship"); @@ -139,7 +144,8 @@ void startsWithOgrnipThenFl() { assertThat(keys.get(0)).isEqualTo("ogrnip"); assertThat(keys.get(1)).isEqualTo("personId"); - assertThat(keys.get(2)).isEqualTo("fullName"); + assertThat(keys.get(2)).isEqualTo("employerOgrn"); + assertThat(keys.get(3)).isEqualTo("fullName"); assertThat(row.get("ogrnip")).hasSize(15); assertThat(row.get("inn")).isEqualTo(base.inn()); } diff --git a/validum-core/src/test/java/ru/validum/core/profile/EmployerLinkTest.java b/validum-core/src/test/java/ru/validum/core/profile/EmployerLinkTest.java new file mode 100644 index 0000000..3499fc7 --- /dev/null +++ b/validum-core/src/test/java/ru/validum/core/profile/EmployerLinkTest.java @@ -0,0 +1,48 @@ +package ru.validum.core.profile; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.Map; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import ru.validum.core.TestProfiles; +import ru.validum.core.export.IndividualProfileFlattener; +import ru.validum.core.export.ProfileFromCsv; + +/** Связь «человек → работодатель»: ОГРН доезжает до плоской выдачи и переживает разбор CSV. */ +class EmployerLinkTest { + + private static final String OGRN = "1027700132195"; + + @Test + @DisplayName("ОГРН работодателя попадает в плоскую выдачу") + void employerAppearsInFlatOutput() { + IndividualProfile profile = TestProfiles.builder(8_001).employer(OGRN).build().generate(); + + Map row = IndividualProfileFlattener.flatten(profile); + + assertThat(row).containsEntry("employerOgrn", OGRN); + } + + @Test + @DisplayName("Без работодателя колонка пустая, а не отсутствует") + void withoutEmployerColumnIsEmpty() { + IndividualProfile profile = TestProfiles.individual(8_002); + + Map row = IndividualProfileFlattener.flatten(profile); + + assertThat(row).containsKey("employerOgrn"); + assertThat(row.get("employerOgrn")).isEmpty(); + } + + @Test + @DisplayName("Круговая операция flatten → parse сохраняет работодателя") + void roundTripKeepsEmployer() { + IndividualProfile profile = TestProfiles.builder(8_003).employer(OGRN).build().generate(); + + IndividualProfile restored = + ProfileFromCsv.parse(IndividualProfileFlattener.flatten(profile)); + + assertThat(restored.employerOgrn()).isEqualTo(OGRN); + } +} diff --git a/validum-core/src/test/java/ru/validum/core/report/CardCoverageTest.java b/validum-core/src/test/java/ru/validum/core/report/CardCoverageTest.java new file mode 100644 index 0000000..0781b49 --- /dev/null +++ b/validum-core/src/test/java/ru/validum/core/report/CardCoverageTest.java @@ -0,0 +1,42 @@ +package ru.validum.core.report; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.Map; +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import ru.validum.core.TestProfiles; +import ru.validum.core.card.MirCardGenerator; +import ru.validum.core.export.IndividualProfileFlattener; + +/** Проверка номера карты в отчёте покрытия. */ +class CardCoverageTest { + + @Test + @DisplayName("cardPan проверяется: Луна и BIN «Мира»") + void cardPanIsChecked() { + String pan = new MirCardGenerator(new Random(1)) + .next(java.time.LocalDate.of(2026, 1, 15)).pan(); + + assertThat(Coverage.isChecked("cardPan")).isTrue(); + assertThat(Coverage.valid("cardPan", pan, Map.of("cardPan", pan))).isTrue(); + + String broken = pan.substring(0, 15) + ((pan.charAt(15) - '0' + 1) % 10); + assertThat(Coverage.valid("cardPan", broken, Map.of("cardPan", broken))).isFalse(); + assertThat(Coverage.valid("cardPan", "4111111111111111", Map.of())) + .as("не «Мир»").isFalse(); + } + + @Test + @DisplayName("В наборе колонка cardPan заполнена у всех") + void statHasNoGaps() { + var profile = TestProfiles.individual(9_105); + var rows = java.util.List.of(IndividualProfileFlattener.flatten(profile)); + + Coverage.FieldStat stat = Coverage.stat("cardPan", rows); + + assertThat(stat.present()).isEqualTo(1); + assertThat(stat.invalid()).isZero(); + } +} diff --git a/validum-core/src/test/java/ru/validum/core/sql/TeardownSqlTest.java b/validum-core/src/test/java/ru/validum/core/sql/TeardownSqlTest.java new file mode 100644 index 0000000..348568c --- /dev/null +++ b/validum-core/src/test/java/ru/validum/core/sql/TeardownSqlTest.java @@ -0,0 +1,50 @@ +package ru.validum.core.sql; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.List; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +/** Откат: DELETE в обратном порядке, без DDL. */ +class TeardownSqlTest { + + @Test + @DisplayName("Таблицы удаляются в порядке, обратном загрузке: сначала дети, потом родители") + void reverseOrder() { + String sql = TeardownSql.build( + "validum 0.5.0 · набор · seed=42", + List.of( + new TeardownSql.Table("validum_organization", "ogrn", List.of("1027700132195")), + new TeardownSql.Table("validum_individual", "personId", List.of("pd-1", "pd-2")))); + + assertThat(sql).startsWith("-- validum 0.5.0"); + assertThat(sql.indexOf("DELETE FROM validum_individual")).isLessThan(sql.indexOf("DELETE FROM validum_organization")); + assertThat(sql).doesNotContain("CREATE", "DROP", "TRUNCATE"); + } + + @Test + @DisplayName("Значения экранируются, пустые таблицы пропускаются") + void quotesAndEmpty() { + String sql = TeardownSql.build( + "набор", + List.of( + new TeardownSql.Table("validum_individual", "personId", List.of("pd-o'brien")), + new TeardownSql.Table("validum_ip", "personId", List.of()))); + + assertThat(sql).contains("'pd-o''brien'"); + assertThat(sql).doesNotContain("validum_ip"); + } + + @Test + @DisplayName("Длинный список режется на пачки по 200 — одна строка на пачку") + void chunking() { + List keys = java.util.stream.IntStream.rangeClosed(1, 450) + .mapToObj(i -> "pd-" + i) + .toList(); + String sql = TeardownSql.build("набор", List.of(new TeardownSql.Table("validum_individual", "personId", keys))); + + assertThat(sql.lines().filter(line -> line.startsWith("DELETE FROM")).count()).isEqualTo(3); + assertThat(sql).contains("'pd-450'"); + } +} diff --git a/validum-core/src/test/resources/golden/individual-preview.txt b/validum-core/src/test/resources/golden/individual-preview.txt index 4b36199..f1cdfb7 100644 --- a/validum-core/src/test/resources/golden/individual-preview.txt +++ b/validum-core/src/test/resources/golden/individual-preview.txt @@ -9,6 +9,10 @@ bankName=ПАО Сбербанк bankRegion=45 birthDate=2006-12-16 blocked=false +cardCount=1 +cardExpiry=06/29 +cardOutcome=успех +cardPan=2203608975311946 categoryClient=КЛИЕНТ citizenship=RU currentApartment=24 @@ -24,6 +28,7 @@ emailDescription=Описание для email emailStatus=Действительный emailType=EMAIL emailValue=efimov.pp@test.tech +employerOgrn= familyStatus=Вдова/Вдовец fullName=Ефимов Платон Платонович gender=MALE diff --git a/validum-core/src/test/resources/golden/individual.txt b/validum-core/src/test/resources/golden/individual.txt index 877c596..7b97ed8 100644 --- a/validum-core/src/test/resources/golden/individual.txt +++ b/validum-core/src/test/resources/golden/individual.txt @@ -1,5 +1,5 @@ -0|7b4e1f1008358964c62d060e036e1088a8156ee8e83482b63403b3b81e9b0107 -1|b64a34455114b9b6ccd4f4df539eb72eb5f1645ed1cb3f70ce482902f1cc4c60 -42|06bf8df786ead738305f4b319cd1c25d4646e6580cc08d52e09cc51e49fb9f56 -1234|4049593308129595b9ffd7084809441283ade8c95cb05707fffe304dbb5205b0 -99999|97bcf3f9f157f2bb4ff0aa4d1d5e5a7d9547f563d000a10dc4c92745c0e7dab9 +0|5d136ed0a90747d67b04bcdba4aaa4e16a2c1eb7a05bbbb1be6ac585ba02856c +1|aba48c2a2b1cef9676c1f0cee99536136a5d22cbc4fcc4cce27a4de17ea16e16 +42|456b09c676d3a84e6906d3adc0b836f48d69ed4b52f7e4af015d56530f7568e9 +1234|bb9571043cc151e446aa59d4b2032e21e1a0e89abdc46f214438a6a8283e6ecc +99999|d28d8aa5a7e96cd527074a8fa3e1f2e1a136525ad0b628de6756c0e2a96552c3