krotname/CompanyStatusChecker

# Checker Corporate [](https://github.com/krotname/CompanyStatusChecker/actions/workflows/ci.yml?query=branch%3Amain+event%3Apush) [](https://github.com/krotname/CompanyStatusChecker/actions/workflows/mutation-testing.yml?query=branch%3Amain+event%3Apush) [](https://github.com/krotname/CompanyStatusChecker/actions/workflows/codeql.yml?query=branch%3Amain) [](docs/quality-gates.md) [](https://securityscorecards.dev/viewer/?uri=github.com/krotname/CompanyStatusChecker) [](https://www.bestpractices.dev/projects/13149) [](LICENSE) [](https://openjdk.org/projects/jdk/21/) [English README](README.en.md) ## RU ### 这是什么 `Checker Corporate` 是一个用于验证企业纳税人识别号 (TIN) 并通过 DaData API 检查其状态的 Java 演示服务。该项目展示了对以下方面的实际处理方法： - 在进行网络调用前验证输入数据； - 稳健地处理集成错误； - 提取领域模型（`CheckResult`、`CompanyStatus`）； - 提供 CLI 和 HTTP UI； - 通过 GitHub Actions 实现质量自动化。 ### 包含内容 - `com.krotname.checker.validation` — TIN 和校验和验证。 - `com.krotname.checker.client` — HTTP 客户端和 DaData 响应解析器。 - `com.krotname.checker.config` — 安全的配置加载。 - `com.krotname.checker.ui` — HTTP 服务器（`/`、`/health`、`/api/check`）。 - `src/main/resources/static/index.html` — 仪表盘式 UI，用于手动检查和可视化演示。 详细的审查材料：[架构](docs/architecture.md)，[质量门禁](docs/quality-gates.md)，[OpenAPI](docs/openapi.yaml)。 ### 运行 1. 安装 Java 21。 2. 准备 token： ``` cp src/main/resources/checker.example.properties src/main/resources/checker.properties # token=<您的 DADATA token> ``` 或者： ``` 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 ``` #### Web UI ``` ./mvnw -q -DskipTests package java -jar target/checker-corporate-*.jar --server 8080 ``` 打开 `http://localhost:8080`。 ### API - `GET /health` — 用于自动化的健康检查。 - `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 界面 - 内置仪表盘，提供服务状态、快速场景和结构化的结果输出。 - 可以直接从浏览器 UI 复制 JSON。 - 内置健康 ping 可显示本地服务器的就绪状态，无需借助外部工具。 ### 测试策略 - **Unit**：TIN 验证、DaData 状态映射、配置、领域工厂。 - **Integration**：带有本地测试服务器的 DaData HTTP 客户端 + API 路由。 - **UI**：对 `/`、`/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` 测试任务，并发布 Surefire 报告。 - 在 CI 中进行 Docker image build + `/health` 冒烟测试。 - Docker image 在非 root 用户 `app` 下运行，并包含基于 Java 的 `HEALTHCHECK`。 - `JaCoCo`，最低覆盖率阈值为 `LINE >= 0.70`。 - `PIT` mutation testing，最低阈值为 `mutationThreshold >= 80`。 - `SpotBugs` bug-pattern 分析，设置为 `effort=Max`、`threshold=Low` 以及 fail-on-warning 模式。 - 在 `verify` 阶段执行 `Checkstyle`。 - 通过固定的 `project.build.outputTimestamp` 实现可重现的 Maven artifacts。 - Source/Javadoc jars 在 `package` 阶段创建，并作为 CI/release artifacts 附带。 - `CodeQL` 和 `OpenSSF Scorecard`。 - `Dependabot`、`Release` 工作流。 - CycloneDX SBOM（`target/bom.xml`、`target/bom.json`）用于供应链审查。 - Dependency Review 会阻止包含新的高危 runtime 依赖的 PR。 - Release 工作流为 JAR 发布 artifact provenance 和 SBOM attestations。 - Release 工作流针对 tag 发布将 Docker image 发布到 `ghcr.io/krotname/company-status-checker`。 - 社区健康文件：`SECURITY.md`、`CODE_OF_CONDUCT.md`、`CONTRIBUTING.md`、issue/PR 模板。 ``` ./mvnw -q test ./mvnw -q verify ./mvnw -q verify -Pmutation-tests ```

标签：DaData, Docker, RESTful API, Web服务, 企业信息查询, 域名枚举, 安全防御评估, 提示词优化, 数据校验, 请求拦截