Checker Corporate

English README

RU

Что это

Checker Corporate — это демонстрационный Java-сервис для валидации ИНН юрлица и проверки его статуса через DaData API. Проект показывает практический подход к:

• валидации входных данных до сетевых вызовов;
• устойчивой обработке интеграционных ошибок;
• выделению доменной модели (CheckResult, CompanyStatus);
• предоставлению CLI и HTTP UI;
• автоматизации качества через GitHub Actions.

Что внутри

• com.krotname.checker.validation — проверка ИНН и контрольных сумм.
• com.krotname.checker.client — HTTP-клиент и парсер ответа DaData.
• com.krotname.checker.config — безопасная загрузка конфигурации.
• com.krotname.checker.ui — HTTP-сервер (/, /health, /api/check).
• src/main/resources/static/index.html — dashboard-style UI для ручной проверки и визуального демо.

Подробные материалы для ревью: architecture, quality gates, OpenAPI.

Запуск

1. Установить Java 21.
2. Подготовить токен:

cp src/main/resources/checker.example.properties src/main/resources/checker.properties
# token=<Ваш токен DADATA>

или:

set DADATA_TOKEN=your_token   # Windows
export DADATA_TOKEN=your_token # macOS/Linux

На Windows используйте mvnw.cmd вместо ./mvnw.

CLI

./mvnw -q -DskipTests package
java -jar target/checker-corporate-*.jar 9710083390

Веб UI

./mvnw -q -DskipTests package
java -jar target/checker-corporate-*.jar --server 8080

Откройте http://localhost:8080.

API

• GET /health — health-check для автоматизации.
• GET /api/check?inn=<ИНН> — статус компании. Оба endpoint соответствуют docs/openapi.yaml.

Пример ответа:

{
  "inn": "9710083390",
  "status": "ACTIVE",
  "dadataStatus": "ACTIVE",
  "message": "Организация активна."
}

Docker

./mvnw -q -DskipTests package
docker compose up --build

Откройте http://localhost:8080.

UI surface

• Встроенный dashboard с состоянием сервиса, быстрыми сценариями и структурированным выводом результата.
• JSON можно копировать прямо из браузерного UI.
• Встроенный health ping показывает готовность локального сервера без внешних инструментов.

Тестовая стратегия

• Unit: валидация ИНН, маппинг статусов DaData, конфигурация, доменные фабрики.
• Интеграционные: HTTP-клиент DaData с локальным тестовым сервером + маршруты API.
• UI: smoke-проверки /, /api/check, /health, включая ошибки валидации.
• Contract/через интеграционный слой: формат DadataResponseParser и поведение CheckerCorporate.check.

Классификация тестов:

• @Tag("unit") — изолированные и доменные проверки.
• @Tag("integration") — интеграции с HTTP-клиентом и HTTP API.
• @Tag("ui") — интеграционные проверки поведения пользовательского API.
• @Tag("contract") — проверки внешнего JSON/OpenAPI контракта.

Запуск выборочно по профилям:

./mvnw -q test                           # все тесты
./mvnw -q test -Punit-tests              # только unit
./mvnw -q test -Pintegration-tests       # только интеграционные (включая ui)
./mvnw -q test -Pui-tests                # только UI/API smoke
./mvnw -q test -Pcontract-tests          # только contract
./mvnw -q verify -Pmutation-tests        # mutation testing gate

Качество и автоматизация

• CI (.github/workflows/ci.yml) — ./mvnw verify.
• CI отдельно запускает unit, integration, ui и contract test jobs с публикацией Surefire reports.
• Docker image build + /health smoke test in CI.
• Docker image запускается под non-root пользователем app и содержит Java-based HEALTHCHECK.
• JaCoCo с минимальным порогом покрытия LINE >= 0.70.
• PIT mutation testing с минимальным порогом mutationThreshold >= 80.
• SpotBugs bug-pattern analysis с effort=Max, threshold=Low и fail-on-warning режимом.
• Checkstyle на этапе verify.
• Воспроизводимые Maven artifacts через фиксированный project.build.outputTimestamp.
• Source/Javadoc jars создаются на этапе package и прикладываются к CI/release artifacts.
• CodeQL и OpenSSF Scorecard.
• Dependabot, Release workflow.
• CycloneDX SBOM (target/bom.xml, target/bom.json) для supply-chain review.
• Dependency Review блокирует PR с новыми runtime-зависимостями высокой критичности.
• Release workflow выпускает artifact provenance и SBOM attestations для JAR.
• Release workflow публикует Docker image в ghcr.io/krotname/company-status-checker для tag-релизов.
• Community health files: SECURITY.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, issue/PR templates.

./mvnw -q test
./mvnw -q verify
./mvnw -q verify -Pmutation-tests