test: add architecture and OpenAPI validation tooling

firstleg/docs/firstleg-internal-modularization-baseline.md

@@ -4,8 +4,9 @@
 
 本基线只分析 `firstleg` 同一部署单元，不拆微服务，不改变业务流程、数据库结构、OpenAPI 或跨服务契约。分析输入为：
 
-- `src/main/java`：429 个 Java 文件；948 条可解析的模块内类依赖；66 个物理包。
-- `src/test/java`：169 个 Java 文件。与主源码合并分析时共 598 个 Java 文件、1,635 条模块内类依赖、69 个物理包。
+- 首切片实施前 `src/main/java`：429 个 Java 文件；948 条可解析的模块内类依赖；66 个物理包。
+- 首切片实施前 `src/test/java`：169 个 Java 文件。与主源码合并分析时共 598 个 Java 文件、1,635 条模块内类依赖、69 个物理包。
+- 首切片实施后 `src/main/java`：430 个 Java 文件；949 条可解析的模块内类依赖；67 个物理包。增加项仅为只读 Out Port。
 
 可重复命令：
 
@@ -78,7 +79,7 @@ split-loading
 | 订舱报关拖车 | `oceanbooking/`、`customs/`，全局 `TruckAppointment*`、`WarehouseSupplier*`、出仓门禁贡献者 | 68 | 25/13 | `CustomsRepository` 直接读取入库与装柜 Mapper；订舱 Repository 直接读取全局货柜 Entity |
 | 出仓 | `outbound/dispatch/` 与全局 `OutboundDispatch*`、运输历史、海外卸柜回写 | 17 | 8/10 | 与装柜、订舱门禁双向；海外回写直接使用全局货柜 Mapper/Entity |
 | 船节点 | `portschedule/` 中 `CarrierScheduleQuery/Node/Adapter/Attempt/Exception*` | 22 | 8/1 | 查询服务直接读取订舱、船期、货柜 Entity；节点 Outbox 直接使用入库 Outbox Mapper/Entity |
-| 客户统计 | `customerstatistics/` | 4 | 1/0 | Java 依赖最低；唯一跨切片依赖为 Controller 调用 `FirstlegScopeGuard`。SQL 只读订舱、货柜和装柜表 |
+| 客户统计 | `customerstatistics/adapter`、`customerstatistics/application` | 5 | 1/0 | 已完成首切片；唯一跨切片依赖为 Web Adapter 调用 `FirstlegScopeGuard`。SQL 只读订舱、货柜和装柜表 |
 | 财务集成 | 全局 `InternalFinance*`、`FinanceFeeSource*`、`FinanceCostSnapshot*`、付款凭证/快照类 | 20 | 17/6 | 直接读取入库费、柜次费、装柜及共享 Outbox 的 Entity/Mapper；继续受财务总控冻结的业务口径约束 |
 
 共享技术层当前有 36 类，包含应用启动/配置、Scope Guard、单据号、部分跨服务 Client 及无法安全归属的全局模型。跨服务适配器按 `client` 包独立标识，不能因逻辑切片归属而被迁入应用核心。
@@ -104,7 +105,7 @@ split-loading
 
 选择 `customer-statistics`，不是因为预设，而是因为以下实际证据：
 
-1. 仅 4 个生产类，已集中在单一顶层包；没有业务切片对其产生 Java 类型入向依赖。
+1. 实施前仅 4 个生产类且已集中在单一顶层包；实施后为原 4 类加 1 个只读 Out Port，没有业务切片对其产生 Java 类型入向依赖。
 2. 唯一跨切片 Java 依赖为 Web Controller 对共享 `FirstlegScopeGuard` 的调用，不涉及 Entity 或 Mapper 泄漏。
 3. 不属于当前八节点 SCC，也没有跨服务 Feign/HTTP Client。
 4. 现有调用面稳定：一个平台 GET 接口、一个 Admin API 消费者、两个后端测试。
@@ -138,7 +139,7 @@ application -> application.model + common-core
 
 ## 7. 精确迁移清单、调用方与测试
 
-首切片实施时只迁移/新增以下文件：
+首切片已按以下清单迁移/新增：
 
 | 当前文件 | 目标/动作 |
 |---|---|
@@ -170,7 +171,7 @@ application -> application.model + common-core
 
 - `scripts/analyze-firstleg-dependencies.mjs`：生成 JSON/Markdown/DOT 和 Tarjan SCC。
 - `src/test/resources/architecture/firstleg-slice-dependencies.json`：冻结当前切片边；历史边可减少，不可增加。
-- `scripts/analyze-firstleg-dependencies.test.mjs`：验证基线无新增边，并锁定客户统计 4 类、唯一出向边、零入向边和不进入 SCC。
+- `scripts/analyze-firstleg-dependencies.test.mjs`：验证基线无新增边，并锁定客户统计目标 5 类/目录、唯一出向边、零入向边、不进入 SCC 和 application 依赖禁令。
 
 与其他架构专项的依赖：
 
@@ -182,8 +183,18 @@ application -> application.model + common-core
 ```powershell
 node --test firstleg/scripts/analyze-firstleg-dependencies.test.mjs
 node firstleg/scripts/analyze-firstleg-dependencies.mjs --source-set main --format markdown
+mvn -pl firstleg -am test-compile
 mvn -pl firstleg -am -Dtest=CustomerTransitStatisticsServiceTest,CustomerTransitStatisticsContractTest -Dsurefire.failIfNoSpecifiedTests=false test
 ```
 
-当前只新增只读脚本、合同和报告，没有 Java 签名变化；前两条命令是本轮直接门禁。第三条用于首切片实际迁移后的 Maven 行为验证。
+首切片已经发生 Java 包与依赖签名变化，三条命令均为直接门禁；另需执行 `mvn -pl firstleg -am test-compile` 覆盖全部测试源码调用点。
 
+## 11. 首切片实施结果
+
+- 四个旧包类已删除，没有转发兼容层；目标五层目录已由 Node 合同锁定。
+- `CustomerTransitStatisticsReader.SummaryProjection` 只包含 `customerId`、`containerCount`、`totalTeu`、`unknownContainerCount`、`asOf`，不暴露 MyBatis、Entity 或其他切片类型。
+- 依赖方向由 `application Service -> MyBatis Mapper` 改为 `application Service -> application Port <- persistence Mapper`。
+- 主源码由 429 类/948 条内部依赖/66 包变为 430 类/949 条内部依赖/67 包；36 条切片间边、88 条模型泄漏、31 条 Mapper 泄漏及全局 `mapper <-> repository` SCC 均未增加。客户统计仍只有 `adapter.in.web -> FirstlegScopeGuard` 一条跨切片边，且没有入向边。
+- 根 Mapper 扫描只把旧精确包替换为新精确包，没有扩大扫描范围或增加兼容 Bean。
+- 验证结果：Node 合同 3/3；`test-compile` 成功；客户统计加根扫描定向测试 7/7；`mvn -pl firstleg -am test` 共 854 个测试，0 失败、0 错误、3 跳过，构建成功。
+- 首次并发执行 `test-compile` 时，其他专项同时写入共享 `target/classes` 导致若干无关 class 文件瞬时缺失；源符号核对正常，独立重跑 `test-compile` 与完整测试均成功。

firstleg/pom.xml

@@ -23,6 +23,7 @@
         <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId></dependency>
         <dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><scope>runtime</scope></dependency>
         <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
+        <dependency><groupId>com.tngtech.archunit</groupId><artifactId>archunit</artifactId><scope>test</scope></dependency>
         <dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency>
     </dependencies>
     <build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>

firstleg/scripts/analyze-firstleg-dependencies.mjs

@@ -73,7 +73,7 @@ function classifySlice(fqcn) {
 function classifyKind(fqcn) {
   const packageName = fqcn.slice(0, fqcn.lastIndexOf('.'));
   if (packageName.includes('.client')) return 'cross-service-adapter';
-  if (/\.(controller|repository|mapper|config|security)(?:\.|$)/.test(packageName)) return 'technical-adapter';
+  if (/\.(adapter|controller|repository|mapper|config|security)(?:\.|$)/.test(packageName)) return 'technical-adapter';
   if (/\.(entity|dto)(?:\.|$)/.test(packageName)) return 'data-model';
   return 'business-application';
 }
@@ -218,7 +218,8 @@ function buildReport(sourceSet) {
       crossSliceMapperLeaks: mapperLeaks.length,
     },
     sliceDefinitions: Object.fromEntries(sliceRules.map(([name, expression]) => [name, expression.source]).concat([['shared-technical', 'fallback']])),
-    classes: sources.map(({ source, imports, ...entry }) => entry),
+    classes: sources.map(({ source, ...entry }) => entry),
+    classDependencies: dependencies,
     packageEdges,
     sliceEdges,
     packageSccs,
@@ -265,8 +266,43 @@ function checkContract(report, contractPath) {
   const allowed = new Set(contract.allowedSliceEdges ?? []);
   const actual = report.sliceEdges.map(edge => `${edge.source}->${edge.target}`);
   const additions = actual.filter(edge => !allowed.has(edge));
-  if (additions.length > 0) {
-    process.stderr.write(`New slice dependencies are not allowed by ${contractPath}:\n${additions.map(edge => `- ${edge}`).join('\n')}\n`);
+  const violations = additions.map(edge => `new slice dependency: ${edge}`);
+  const classesByName = new Map(report.classes.map(entry => [entry.fqcn, entry]));
+  for (const [fqcn, expectedFile] of Object.entries(contract.requiredClassLocations ?? {})) {
+    const actualClass = classesByName.get(fqcn);
+    if (!actualClass) violations.push(`required class missing: ${fqcn}`);
+    else if (actualClass.file !== expectedFile) violations.push(`class location changed: ${fqcn} (${actualClass.file})`);
+  }
+  const applicationRule = contract.applicationDependencyRule;
+  if (applicationRule) {
+    const applicationClasses = report.classes.filter(entry => entry.packageName.startsWith(applicationRule.packagePrefix));
+    for (const entry of applicationClasses) {
+      for (const imported of entry.imports) {
+        if ((applicationRule.forbiddenImportPrefixes ?? []).some(prefix => imported.startsWith(prefix))) {
+          violations.push(`forbidden application import: ${entry.fqcn} -> ${imported}`);
+        }
+      }
+    }
+    for (const edge of report.classDependencies) {
+      if (edge.source.startsWith(applicationRule.packagePrefix)
+          && edge.target.startsWith(internalPrefix)
+          && !edge.target.startsWith(applicationRule.allowedInternalPrefix)) {
+        violations.push(`forbidden application dependency: ${edge.source} -> ${edge.target}`);
+      }
+    }
+  }
+  for (const [slice, rule] of Object.entries(contract.sliceSpecificRules ?? {})) {
+    const outgoing = report.sliceEdges.filter(edge => edge.source === slice).map(edge => edge.target).sort();
+    const incoming = report.sliceEdges.filter(edge => edge.target === slice).map(edge => edge.source).sort();
+    if (JSON.stringify(outgoing) !== JSON.stringify([...(rule.allowedOutgoing ?? [])].sort())) {
+      violations.push(`${slice} outgoing dependencies changed: ${outgoing.join(', ')}`);
+    }
+    if (JSON.stringify(incoming) !== JSON.stringify([...(rule.allowedIncoming ?? [])].sort())) {
+      violations.push(`${slice} incoming dependencies changed: ${incoming.join(', ')}`);
+    }
+  }
+  if (violations.length > 0) {
+    process.stderr.write(`Firstleg dependency contract violations in ${contractPath}:\n${violations.map(item => `- ${item}`).join('\n')}\n`);
     process.exitCode = 1;
   }
 }
@@ -281,4 +317,3 @@ const rendered = options.format === 'json'
     : renderDot(report);
 if (options.output) fs.writeFileSync(path.resolve(process.cwd(), options.output), rendered, 'utf8');
 else process.stdout.write(rendered);
-

firstleg/scripts/analyze-firstleg-dependencies.test.mjs

@@ -25,10 +25,11 @@ test('customer statistics remains an independently packaged low-coupling slice',
   const report = analyze();
   const classes = report.classes.filter(entry => entry.slice === 'customer-statistics');
   assert.deepEqual(classes.map(entry => entry.fqcn).sort(), [
-    'com.baiyue.firstleg.customerstatistics.controller.PlatformCustomerTransitStatisticsController',
-    'com.baiyue.firstleg.customerstatistics.dto.CustomerTransitStatisticsDtos',
-    'com.baiyue.firstleg.customerstatistics.mapper.CustomerTransitStatisticsMapper',
-    'com.baiyue.firstleg.customerstatistics.service.CustomerTransitStatisticsService',
+    'com.baiyue.firstleg.customerstatistics.adapter.in.web.PlatformCustomerTransitStatisticsController',
+    'com.baiyue.firstleg.customerstatistics.adapter.out.persistence.CustomerTransitStatisticsMapper',
+    'com.baiyue.firstleg.customerstatistics.application.CustomerTransitStatisticsService',
+    'com.baiyue.firstleg.customerstatistics.application.model.CustomerTransitStatisticsDtos',
+    'com.baiyue.firstleg.customerstatistics.application.port.out.CustomerTransitStatisticsReader',
   ]);
   const outgoing = report.sliceEdges.filter(edge => edge.source === 'customer-statistics');
   const incoming = report.sliceEdges.filter(edge => edge.target === 'customer-statistics');
@@ -37,3 +38,17 @@ test('customer statistics remains an independently packaged low-coupling slice',
   assert.equal(report.sliceSccs.some(component => component.includes('customer-statistics')), false);
 });
 
+test('customer statistics application layer only depends inward', () => {
+  const report = analyze();
+  const prefix = 'com.baiyue.firstleg.customerstatistics.application';
+  const applicationClasses = report.classes.filter(entry => entry.packageName.startsWith(prefix));
+  assert.equal(applicationClasses.length, 3);
+  for (const entry of applicationClasses) {
+    assert.equal(entry.imports.some(imported => imported.startsWith('org.springframework.web')), false);
+    assert.equal(entry.imports.some(imported => imported.startsWith('org.apache.ibatis')), false);
+    assert.equal(entry.imports.some(imported => imported.startsWith('com.baomidou.mybatisplus')), false);
+  }
+  const outwardDependencies = report.classDependencies.filter(edge => edge.source.startsWith(prefix)
+    && edge.target.startsWith('com.baiyue.firstleg.') && !edge.target.startsWith(prefix));
+  assert.deepEqual(outwardDependencies, []);
+});

firstleg/src/test/java/com/baiyue/firstleg/customerstatistics/CustomerStatisticsArchitectureTest.java

@@ -0,0 +1,80 @@
+package com.baiyue.firstleg.customerstatistics;
+
+import com.baiyue.firstleg.customerstatistics.application.port.out.CustomerTransitStatisticsReader;
+import com.baiyue.firstleg.service.FirstlegScopeGuard;
+import com.tngtech.archunit.base.DescribedPredicate;
+import com.tngtech.archunit.core.domain.JavaClass;
+import com.tngtech.archunit.core.domain.JavaClasses;
+import com.tngtech.archunit.core.importer.ClassFileImporter;
+import com.tngtech.archunit.core.importer.ImportOption;
+import org.junit.jupiter.api.Test;
+
+import static com.tngtech.archunit.core.domain.JavaClass.Predicates.resideInAPackage;
+import static com.tngtech.archunit.core.domain.JavaClass.Predicates.resideOutsideOfPackage;
+import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
+import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
+
+class CustomerStatisticsArchitectureTest {
+    private static final String FIRSTLEG = "com.baiyue.firstleg..";
+    private static final String CUSTOMER_STATISTICS = "com.baiyue.firstleg.customerstatistics..";
+    private static final String APPLICATION = "com.baiyue.firstleg.customerstatistics.application..";
+    private static final String OUTPUT_PORT = "com.baiyue.firstleg.customerstatistics.application.port.out..";
+    private static final String PERSISTENCE = "com.baiyue.firstleg.customerstatistics.adapter.out.persistence..";
+    private static final String WEB = "com.baiyue.firstleg.customerstatistics.adapter.in.web..";
+
+    private static final JavaClasses PRODUCTION_CLASSES = new ClassFileImporter()
+        .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
+        .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_JARS)
+        .importPackages("com.baiyue.firstleg");
+
+    @Test
+    void applicationModelAndPortsStayFreeOfWebAndPersistenceFrameworks() {
+        noClasses().that().resideInAPackage(APPLICATION)
+            .should().dependOnClassesThat().resideInAnyPackage(
+                "org.springframework.web..",
+                "org.apache.ibatis..",
+                "com.baomidou.mybatisplus..")
+            .check(PRODUCTION_CLASSES);
+    }
+
+    @Test
+    void applicationOnlyDependsOnItsOwnSliceWithinFirstleg() {
+        classes().that().resideInAPackage(APPLICATION)
+            .should().onlyDependOnClassesThat(
+                resideOutsideOfPackage(FIRSTLEG).or(resideInAPackage(APPLICATION)))
+            .check(PRODUCTION_CLASSES);
+    }
+
+    @Test
+    void persistenceAdapterCollaboratesThroughTheApplicationOutputPort() {
+        classes().that().resideInAPackage(PERSISTENCE)
+            .should().onlyDependOnClassesThat(
+                resideOutsideOfPackage(CUSTOMER_STATISTICS).or(resideInAPackage(OUTPUT_PORT)))
+            .andShould().beAssignableTo(CustomerTransitStatisticsReader.class)
+            .check(PRODUCTION_CLASSES);
+    }
+
+    @Test
+    void webAdapterOnlyUsesApplicationAndScopeGuardWithinFirstleg() {
+        DescribedPredicate<JavaClass> scopeGuard = new DescribedPredicate<>("FirstlegScopeGuard") {
+            @Override
+            public boolean test(JavaClass javaClass) {
+                return javaClass.getName().equals(FirstlegScopeGuard.class.getName());
+            }
+        };
+        classes().that().resideInAPackage(WEB)
+            .should().onlyDependOnClassesThat(
+                resideOutsideOfPackage(FIRSTLEG)
+                    .or(resideInAPackage(APPLICATION))
+                    .or(resideInAPackage(WEB))
+                    .or(scopeGuard))
+            .check(PRODUCTION_CLASSES);
+    }
+
+    @Test
+    void otherFirstlegProductionPackagesDoNotDependOnCustomerStatistics() {
+        noClasses().that().resideOutsideOfPackage(CUSTOMER_STATISTICS)
+            .should().dependOnClassesThat().resideInAPackage(CUSTOMER_STATISTICS)
+            .check(PRODUCTION_CLASSES);
+    }
+}

firstleg/src/test/resources/architecture/firstleg-slice-dependencies.json

@@ -39,6 +39,22 @@
     "split-loading->outbound",
     "split-loading->shared-technical"
   ],
+  "requiredClassLocations": {
+    "com.baiyue.firstleg.customerstatistics.adapter.in.web.PlatformCustomerTransitStatisticsController": "src/main/java/com/baiyue/firstleg/customerstatistics/adapter/in/web/PlatformCustomerTransitStatisticsController.java",
+    "com.baiyue.firstleg.customerstatistics.adapter.out.persistence.CustomerTransitStatisticsMapper": "src/main/java/com/baiyue/firstleg/customerstatistics/adapter/out/persistence/CustomerTransitStatisticsMapper.java",
+    "com.baiyue.firstleg.customerstatistics.application.CustomerTransitStatisticsService": "src/main/java/com/baiyue/firstleg/customerstatistics/application/CustomerTransitStatisticsService.java",
+    "com.baiyue.firstleg.customerstatistics.application.model.CustomerTransitStatisticsDtos": "src/main/java/com/baiyue/firstleg/customerstatistics/application/model/CustomerTransitStatisticsDtos.java",
+    "com.baiyue.firstleg.customerstatistics.application.port.out.CustomerTransitStatisticsReader": "src/main/java/com/baiyue/firstleg/customerstatistics/application/port/out/CustomerTransitStatisticsReader.java"
+  },
+  "applicationDependencyRule": {
+    "packagePrefix": "com.baiyue.firstleg.customerstatistics.application",
+    "allowedInternalPrefix": "com.baiyue.firstleg.customerstatistics.application",
+    "forbiddenImportPrefixes": [
+      "org.springframework.web",
+      "org.apache.ibatis",
+      "com.baomidou.mybatisplus"
+    ]
+  },
   "sliceSpecificRules": {
     "customer-statistics": {
       "allowedOutgoing": ["shared-technical"],