所有 Unit Test 都綠燈
≠
架構是正確的

應用程式跑得起來
≠
架構是健康的

noClasses()
    .that().resideInAPackage("..domain..")
    .should().dependOnClassesThat().resideInAnyPackage("org.springframework..")
    .because("Domain 層必須與框架解耦，才能在不啟動 Spring 的情況下被測試與重用");

Day 1    Controller → Service → Repository（設計如此）
Day 90   某次趕時間，Controller 直接叫了 Repository（「只有這一支，之後改」）
Day 180  新人看到前例，照抄（「原來這裡可以這樣寫」）
Day 400  43 個 Controller 裡有 19 個直接叫 Repository
Day 800  要換 ORM 時才發現，Repository 的介面被 Controller 綁死了

A → B → C → A

@ArchTest
static final ArchRule controller_must_not_expose_entities =
    noClasses()
        .that().resideInAPackage("..controller..")
        .should().dependOnClassesThat().areAnnotatedWith(jakarta.persistence.Entity.class)
        .because("REST 回應必須使用 DTO，Entity 外洩會讓資料庫 schema 變成對外 API 契約");

Unit Test Pass  ≠  Architecture Correct

Application Works  ≠  Architecture Healthy

import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.core.domain.JavaClasses;

// 匯入指定套件（最常用）
JavaClasses classes = new ClassFileImporter()
        .importPackages("com.company.order");

// 匯入整個 classpath（含第三方 jar，較慢）
JavaClasses all = new ClassFileImporter().importClasspath();

// 匯入指定路徑
JavaClasses fromPath = new ClassFileImporter()
        .importPath("target/classes");

import com.tngtech.archunit.core.importer.ImportOption;

JavaClasses productionClasses = new ClassFileImporter()
        .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
        .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_JARS)
        .importPackages("com.company.order");

// 排除所有由程式碼產生器產生的類別
ImportOption excludeGenerated = location ->
        !location.contains("/generated/");

JavaClasses classes = new ClassFileImporter()
        .withImportOption(excludeGenerated)
        .importPackages("com.company.order");

JavaClass orderService = classes.get("com.company.order.application.OrderService");

orderService.getSimpleName();          // "OrderService"
orderService.getPackageName();         // "com.company.order.application"
orderService.getModifiers();           // PUBLIC, FINAL ...
orderService.getMethods();             // Set<JavaMethod>
orderService.getFields();              // Set<JavaField>
orderService.getConstructors();        // Set<JavaConstructor>
orderService.getAnnotations();         // Set<JavaAnnotation<JavaClass>>
orderService.getDirectDependenciesFromSelf();  // 它依賴誰
orderService.getDirectDependenciesToSelf();    // 誰依賴它
orderService.isInterface();
orderService.isEnum();
orderService.isRecord();
orderService.isSealed();               // 【Official・1.5.0 新增】
orderService.getPermittedSubclasses(); // 【Official・1.5.0 新增】sealed 類別的許可子類

JavaPackage domainPackage = classes.getPackage("com.company.order.domain");
domainPackage.getClasses();
domainPackage.getSubPackages();
domainPackage.getClassDependenciesFromSelf();

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.*;

classes()        // 對類別下規則
noClasses()      // 「沒有任何類別應該……」
methods()        // 對方法下規則
noMethods()
fields()         // 對欄位下規則
noFields()
constructors()   // 對建構子下規則
noConstructors()
members()        // 對所有成員（方法 + 建構子 + 欄位）
noMembers()
codeUnits()      // 對所有可執行單位（方法 + 建構子）
noCodeUnits()

rule.check(classes);                         // 不符合就丟 AssertionError
rule.evaluate(classes);                      // 回傳 EvaluationResult，不丟例外
rule.as("自訂規則名稱");                      // 改寫規則描述
rule.because("原因");                        // 補上原因（會出現在失敗訊息）
rule.allowEmptyShould(true);                 // 允許「零個類別符合」

noClasses().that( <DescribedPredicate> ).should( <ArchCondition> )
             ↑ 選出要檢查哪些類別         ↑ 這些類別必須滿足什麼

import com.tngtech.archunit.base.DescribedPredicate;
import com.tngtech.archunit.core.domain.JavaClass;
import com.tngtech.archunit.lang.ArchCondition;
import com.tngtech.archunit.lang.ConditionEvents;
import com.tngtech.archunit.lang.SimpleConditionEvent;

// 自訂述詞：找出「有超過 5 個欄位」的類別
DescribedPredicate<JavaClass> haveMoreThanFiveFields =
    new DescribedPredicate<>("有超過 5 個欄位") {
        @Override
        public boolean test(JavaClass javaClass) {
            return javaClass.getFields().size() > 5;
        }
    };

// 自訂條件：類別必須為 final
ArchCondition<JavaClass> beFinal =
    new ArchCondition<>("為 final") {
        @Override
        public void check(JavaClass javaClass, ConditionEvents events) {
            boolean satisfied = javaClass.getModifiers()
                    .contains(com.tngtech.archunit.core.domain.JavaModifier.FINAL);
            String message = String.format("%s 不是 final（%s）",
                    javaClass.getName(), javaClass.getSourceCodeLocation());
            events.add(new SimpleConditionEvent(javaClass, satisfied, message));
        }
    };

ArchRule rule = classes().that(haveMoreThanFiveFields).should(beFinal);

EvaluationResult result = rule.evaluate(classes);

if (result.hasViolation()) {
    result.getFailureReport().getDetails()
          .forEach(System.out::println);
}

ArchRule rule = noClasses()
        .that().resideInAPackage("..domain..")
        .should().dependOnClassesThat().resideInAnyPackage("..infrastructure..")
        .because("Domain 是最內層，不得依賴外層實作");

rule.check(classes);

java.lang.AssertionError: Architecture Violation [Priority: MEDIUM] -
Rule 'no classes that reside in a package '..domain..' should depend on classes
that reside in any package ['..infrastructure..'], because Domain 是最內層，不得依賴外層實作'
was violated (2 times):
  Method <com.company.order.domain.Order.persist()> calls method
  <com.company.order.infrastructure.OrderDao.save(com.company.order.domain.Order)>
  in (Order.java:58)
  Field <com.company.order.domain.Order.dao> has type
  <com.company.order.infrastructure.OrderDao> in (Order.java:23)

import com.tngtech.archunit.lang.Priority;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.priority;

ArchRule criticalRule = priority(Priority.HIGH)
        .noClasses()
        .that().resideInAPackage("..domain..")
        .should().dependOnClassesThat().resideInAnyPackage("..infrastructure..");

Rule 'no classes that reside in a package '..domain..' should depend on classes
that reside in any package ['org.springframework..']' was violated (1 times):
  Class <com.company.order.domain.Order$$SpringCGLIB$$0> ...

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.0.0</version>
        <relativePath/>
    </parent>

    <groupId>com.company</groupId>
    <artifactId>order-service</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <properties>
        <!-- 編譯目標 Java 版本 -->
        <java.version>25</java.version>
        <maven.compiler.release>25</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

        <!-- 集中管理 ArchUnit 版本：升級時只改這一行 -->
        <archunit.version>1.5.0</archunit.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <!-- 測試：Spring Boot 的 starter-test 已含 JUnit Jupiter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- ArchUnit：JUnit 5 整合版本，一定要用 test scope -->
        <dependency>
            <groupId>com.tngtech.archunit</groupId>
            <artifactId>archunit-junit5</artifactId>
            <version>${archunit.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <!-- 確保架構測試一定會被執行（預設命名規則已涵蓋 *Test.java） -->
                    <includes>
                        <include>**/*Test.java</include>
                        <include>**/*Tests.java</include>
                        <include>**/architecture/**/*.java</include>
                    </includes>
                    <!-- 架構測試失敗必須讓 build 失敗（預設即為 false，此處明示意圖） -->
                    <testFailureIgnore>false</testFailureIgnore>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

<!-- parent pom.xml -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tngtech.archunit</groupId>
            <artifactId>archunit-junit5</artifactId>
            <version>1.5.0</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit-junit5</artifactId>
</dependency>

plugins {
    java
    id("org.springframework.boot") version "4.0.0"
    id("io.spring.dependency-management") version "1.1.7"
}

group = "com.company"
version = "1.0.0-SNAPSHOT"

java {
    toolchain {
        // 明確指定編譯與執行使用的 JDK，避免「本機 JDK 與 CI JDK 不同」的經典問題
        languageVersion = JavaLanguageVersion.of(25)
    }
}

repositories {
    mavenCentral()
}

val archunitVersion = "1.5.0"

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")

    testImplementation("org.springframework.boot:spring-boot-starter-test")

    // ArchUnit：JUnit 5 整合
    testImplementation("com.tngtech.archunit:archunit-junit5:$archunitVersion")
}

tasks.withType<Test> {
    useJUnitPlatform()
    testLogging {
        // 架構測試的失敗訊息很長，務必讓它完整輸出，否則在 CI 上看不到違規清單
        events("passed", "skipped", "failed")
        showStandardStreams = true
        exceptionFormat = org.gradle.api.tasks.testing.logging.TestExceptionFormat.FULL
    }
}

plugins {
    id 'java'
    id 'org.springframework.boot' version '4.0.0'
    id 'io.spring.dependency-management' version '1.1.7'
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

ext {
    archunitVersion = '1.5.0'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation "com.tngtech.archunit:archunit-junit5:${archunitVersion}"
}

test {
    useJUnitPlatform()
    testLogging {
        exceptionFormat = 'full'
    }
}

sourceSets {
    create("archTest") {
        compileClasspath += sourceSets.main.get().output + sourceSets.test.get().output
        runtimeClasspath += sourceSets.main.get().output + sourceSets.test.get().output
    }
}

val archTestImplementation: Configuration by configurations.getting {
    extendsFrom(configurations.testImplementation.get())
}

val archTest = tasks.register<Test>("archTest") {
    description = "執行架構測試"
    group = "verification"
    testClassesDirs = sourceSets["archTest"].output.classesDirs
    classpath = sourceSets["archTest"].runtimeClasspath
    useJUnitPlatform()
    shouldRunAfter(tasks.test)
}

tasks.check {
    dependsOn(archTest)
}

# Maven
mvn dependency:tree -Dincludes=com.tngtech.archunit

# Gradle
./gradlew dependencies --configuration testRuntimeClasspath | grep -i archunit

java.lang.IllegalArgumentException: Unsupported class file major version 72
    at com.tngtech.archunit.thirdparty.org.objectweb.asm.ClassReader.<init>(...)

步驟 1  查 ArchUnit 官方 Release Notes，確認目標 JDK 的 class file 版本已被支援
步驟 2  先升級 ArchUnit 到支援該版本的最新版
步驟 3  在 CI 上跑一次完整架構測試，確認沒有因 ArchUnit 升級而新增的違規
        （例如 1.5.0 開始計入 catch 的例外型別）
步驟 4  處理步驟 3 發現的新違規（修 code 或走 ADR 調整規則）
步驟 5  才升級 JDK
步驟 6  再跑一次完整架構測試

# ===== src/test/resources/archunit.properties =====

# --- 規則行為 ---
# 當規則的 that(...) 篩選結果為空時，是否讓規則失敗
# 預設 true：能及早發現「套件名稱打錯」「重構後規則失效」等問題，強烈建議保持 true
archRule.failOnEmptyShould=true

# --- 循環偵測（大型專案調校用）---
# 最多偵測幾個循環（預設 100）
cycles.maxNumberToDetect=100
# 每條邊最多記錄幾個依賴（預設 20），調小可縮短報告長度與記憶體用量
cycles.maxNumberOfDependenciesPerEdge=20

# --- JUnit 顯示 ---
# 把測試欄位名稱的底線顯示為空白，讓報表更好讀
junit.displayName.replaceUnderscoresBySpaces=true

com.company.order
├── adapter
│   ├── in
│   │   └── web            ← REST Controller
│   └── out
│       └── persistence    ← JPA Repository 實作
├── application            ← Use Case 實作
│   └── port
│       ├── in             ← 輸入埠（介面）
│       └── out            ← 輸出埠（介面）
├── domain                 ← 領域模型（最內層，不依賴任何框架）
└── configuration          ← Spring 設定

package com.company.order.architecture;

import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

@AnalyzeClasses(
        packages = "com.company.order",
        importOptions = ImportOption.DoNotIncludeTests.class
)
class DomainArchitectureTest {

    @ArchTest
    static final ArchRule domain_should_not_depend_on_outer_layers =
            noClasses()
                    .that().resideInAPackage("..domain..")
                    .should().dependOnClassesThat()
                    .resideInAnyPackage(
                            "..application..",
                            "..adapter..",
                            "..configuration.."
                    )
                    .because("Domain 是最內層，依賴方向必須由外向內；"
                           + "Domain 一旦依賴外層，就無法獨立測試與重用");
}

# Maven
mvn test -Dtest=DomainArchitectureTest

# Gradle
./gradlew test --tests '*DomainArchitectureTest'

// 寫法一：欄位（最常用）
@ArchTest
static final ArchRule my_rule = noClasses().that()...;

// 寫法二：方法（需要存取 JavaClasses 做自訂邏輯時使用）
@ArchTest
static void custom_check(JavaClasses classes) {
    // 可以寫任意 Java 邏輯，例如產生報表、條件式檢查
    noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage("..adapter..")
            .check(classes);
}

// 「沒有任何符合條件的類別，應該做某事」
noClasses().that().resideInAPackage("..domain..")
           .should().dependOnClassesThat().resideInAnyPackage("..adapter..");

// 「所有符合條件的類別，都應該做某事」
classes().that().resideInAPackage("..domain..")
         .should().onlyDependOnClassesThat().resideInAnyPackage("..domain..", "java..");

@ArchTest
static final ArchRule domain_should_only_depend_on_itself_and_jdk =
        classes()
                .that().resideInAPackage("..domain..")
                .should().onlyDependOnClassesThat()
                .resideInAnyPackage(
                        "..domain..",       // 自己
                        "java..",           // JDK
                        "javax.."           // 少數 JDK 擴充（視專案而定）
                )
                .because("Domain 必須是純粹的業務模型，"
                       + "不得依賴任何框架，才能在毫秒內被測試、並在未來替換技術棧時完整保留");

@ArchTest
static final ArchRule domain_purity = classes()
        .that().resideInAPackage("..domain..")
        .should().onlyDependOnClassesThat().resideInAnyPackage("..domain..", "java..")
        .as("[ARCH-001] Domain 層純淨性")
        .because("見 ADR-003");

// src/main/java/com/company/order/domain/Order.java
package com.company.order.domain;

import com.company.order.adapter.out.persistence.OrderJpaEntity;  // ← 違規！

public class Order {
    private final String orderId;

    public Order(String orderId) {
        this.orderId = orderId;
    }

    // Domain 不該知道 JPA Entity 的存在
    public OrderJpaEntity toEntity() {
        return new OrderJpaEntity(orderId);
    }
}

[ERROR] DomainArchitectureTest.domain_should_not_depend_on_outer_layers
java.lang.AssertionError: Architecture Violation [Priority: MEDIUM] -
Rule 'no classes that reside in a package '..domain..' should depend on classes
that reside in any package ['..application..', '..adapter..', '..configuration..'],
because Domain 是最內層，依賴方向必須由外向內；Domain 一旦依賴外層，就無法獨立測試與重用'
was violated (2 times):
  Method <com.company.order.domain.Order.toEntity()> has return type
  <com.company.order.adapter.out.persistence.OrderJpaEntity> in (Order.java:0)
  Method <com.company.order.domain.Order.toEntity()> calls constructor
  <com.company.order.adapter.out.persistence.OrderJpaEntity.<init>(java.lang.String)>
  in (Order.java:14)

// ❌ 把 adapter 從規則裡拿掉，讓測試變綠
.resideInAnyPackage("..application..", "..configuration..")  // 拿掉 ..adapter..

// src/main/java/com/company/order/domain/Order.java
package com.company.order.domain;

// 乾淨的 Domain，不 import 任何外層
public class Order {
    private final String orderId;

    public Order(String orderId) {
        this.orderId = orderId;
    }

    public String getOrderId() {
        return orderId;
    }
}

// src/main/java/com/company/order/adapter/out/persistence/OrderMapper.java
package com.company.order.adapter.out.persistence;

import com.company.order.domain.Order;
import org.springframework.stereotype.Component;

/**
 * 轉換責任放在 adapter 層：
 * adapter 知道 domain（允許，由外向內），domain 不知道 adapter（架構要求）。
 */
@Component
public class OrderMapper {

    public OrderJpaEntity toEntity(Order order) {
        return new OrderJpaEntity(order.getOrderId());
    }

    public Order toDomain(OrderJpaEntity entity) {
        return new Order(entity.getOrderId());
    }
}

package com.company.order.architecture;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.core.domain.JavaClass.Predicates.resideInAPackage;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.library.GeneralCodingRules.NO_CLASSES_SHOULD_ACCESS_STANDARD_STREAMS;
import static com.tngtech.archunit.library.GeneralCodingRules.NO_CLASSES_SHOULD_THROW_GENERIC_EXCEPTIONS;
import static com.tngtech.archunit.library.GeneralCodingRules.NO_CLASSES_SHOULD_USE_JAVA_UTIL_LOGGING;
import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;

@AnalyzeClasses(
        packagesOf = com.company.order.OrderApplication.class,
        importOptions = ImportOption.DoNotIncludeTests.class
)
class StarterArchitectureTest {

    /** ARCH-001：Domain 純淨性（白名單） */
    @ArchTest
    static final ArchRule ARCH_001_domain_purity = classes()
            .that().resideInAPackage("..domain..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage("..domain..", "java..")
            .as("[ARCH-001] Domain 層只能依賴自己與 JDK")
            .because("Domain 必須能在不啟動任何框架的情況下被測試與重用（ADR-003）");

    /** ARCH-002：Controller 不得直接存取 Repository */
    @ArchTest
    static final ArchRule ARCH_002_controller_not_touch_repository = noClasses()
            .that().resideInAPackage("..adapter.in.web..")
            .should().dependOnClassesThat().resideInAPackage("..adapter.out.persistence..")
            .as("[ARCH-002] Controller 不得直接依賴 Persistence")
            .because("交易邊界必須由 Application Service 管理（ADR-007）");

    /** ARCH-003：無循環依賴 */
    @ArchTest
    static final ArchRule ARCH_003_free_of_cycles = slices()
            .matching("com.company.order.(*)..")
            .should().beFreeOfCycles()
            .as("[ARCH-003] 頂層模組之間不得有循環依賴")
            .because("循環依賴會讓模組無法獨立測試、獨立部署、獨立理解");

    /** ARCH-004：不得使用 System.out / System.err */
    @ArchTest
    static final ArchRule ARCH_004_no_standard_streams =
            NO_CLASSES_SHOULD_ACCESS_STANDARD_STREAMS
                    .as("[ARCH-004] 不得使用 System.out / System.err")
                    .because("日誌必須經過統一的 logging framework，才能被集中蒐集與遮罩敏感資料");

    /** ARCH-005：不得拋出泛型例外 */
    @ArchTest
    static final ArchRule ARCH_005_no_generic_exceptions =
            NO_CLASSES_SHOULD_THROW_GENERIC_EXCEPTIONS
                    .as("[ARCH-005] 不得拋出 Exception / RuntimeException / Throwable")
                    .because("泛型例外讓呼叫端無法區分錯誤類型，也讓錯誤處理失去意義");

    /** ARCH-006：不得使用 java.util.logging */
    @ArchTest
    static final ArchRule ARCH_006_no_jul =
            NO_CLASSES_SHOULD_USE_JAVA_UTIL_LOGGING
                    .as("[ARCH-006] 不得使用 java.util.logging")
                    .because("專案統一使用 SLF4J + Logback，混用會造成日誌設定失效");
}

@Test
void domain_should_be_pure() {
    JavaClasses classes = new ClassFileImporter()
            .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
            .importPackages("com.company.order");

    noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage("..adapter..")
            .check(classes);
}

package com.company.order.architecture;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.junit.ArchTests;

/**
 * 架構測試總入口。
 * 所有規則集中由此執行，確保共用同一次類別匯入（效能最佳）。
 */
@AnalyzeClasses(
        packagesOf = com.company.order.OrderApplication.class,
        importOptions = ImportOption.DoNotIncludeTests.class
)
class ArchitectureTestSuite {

    @ArchTest
    static final ArchTests layerRules = ArchTests.in(LayerArchitectureRules.class);

    @ArchTest
    static final ArchTests dependencyRules = ArchTests.in(DependencyArchitectureRules.class);

    @ArchTest
    static final ArchTests namingRules = ArchTests.in(NamingArchitectureRules.class);

    @ArchTest
    static final ArchTests annotationRules = ArchTests.in(AnnotationArchitectureRules.class);

    @ArchTest
    static final ArchTests cycleRules = ArchTests.in(CycleArchitectureRules.class);

    @ArchTest
    static final ArchTests securityRules = ArchTests.in(SecurityBoundaryRules.class);
}

package com.company.order.architecture;

import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

/**
 * 分層架構規則集合。
 * 注意：這個類別「沒有」 @AnalyzeClasses，它由 ArchitectureTestSuite 引入並共用其匯入設定。
 */
class LayerArchitectureRules {

    @ArchTest
    static final ArchRule ARCH_010_web_not_touch_persistence = noClasses()
            .that().resideInAPackage("..adapter.in.web..")
            .should().dependOnClassesThat().resideInAPackage("..adapter.out.persistence..")
            .as("[ARCH-010] Web adapter 不得直接依賴 Persistence adapter")
            .because("Adapter 之間必須透過 Application 層溝通（ADR-007）");

    @ArchTest
    static final ArchRule ARCH_011_application_not_touch_adapter = noClasses()
            .that().resideInAPackage("..application..")
            .should().dependOnClassesThat().resideInAPackage("..adapter..")
            .as("[ARCH-011] Application 不得依賴 Adapter 實作")
            .because("Application 只能依賴 port 介面，才能在測試中替換實作（ADR-007）");
}

@ArchIgnore(reason = "等待 ADR-012 決議，預計 2026-10-31 前恢復")
@ArchTest
static final ArchRule temporarily_disabled_rule = ...;

package com.company.order.architecture;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 全專案統一的架構測試匯入設定。
 * 所有架構測試類別都應標註此註解，確保共用同一份 class cache。
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@AnalyzeClasses(
        packagesOf = com.company.order.OrderApplication.class,
        importOptions = {
                ImportOption.DoNotIncludeTests.class,
                ImportOption.DoNotIncludeJars.class,
                ExcludeGeneratedClasses.class
        }
)
public @interface ProductionCodeAnalysis {
}

package com.company.order.architecture;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.core.importer.Location;

/**
 * 排除程式碼產生器與框架代理產生的類別。
 *
 * 注意：排除之前務必確認這些類別不是在指出真正的架構問題
 * （例如 Spring CGLIB 代理出現在 domain 套件，代表 domain 被 @Transactional 污染）。
 */
public class ExcludeGeneratedClasses implements ImportOption {

    @Override
    public boolean includes(Location location) {
        return !location.contains("/generated/")
                && !location.contains("/generated-sources/")
                && !location.contains("MapperImpl")        // MapStruct 產生的實作
                && !location.contains("$$SpringCGLIB$$")   // Spring CGLIB 代理
                && !location.contains("_$$_jvst");         // Javassist / Hibernate 代理
    }
}

@ProductionCodeAnalysis
class ArchitectureTestSuite {
    @ArchTest
    static final ArchTests layerRules = ArchTests.in(LayerArchitectureRules.class);
    // ...
}

<!-- 步驟 1：換 artifact -->
<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit-junit6</artifactId>   <!-- 原本是 archunit-junit5 -->
    <version>1.5.0</version>
    <scope>test</scope>
</dependency>

// 步驟 2：換 import（套件名會不同，請依 IDE 提示調整）
// 步驟 3：確認專案 Java 版本 >= 17（JUnit 6 baseline）

src/test/java/com/company/order/
└── architecture/
    ├── ProductionCodeAnalysis.java          ← 統一匯入設定（meta-annotation）
    ├── ExcludeGeneratedClasses.java         ← 自訂 ImportOption
    ├── ArchitectureTestSuite.java           ← 總入口（唯一有 @AnalyzeClasses 的執行點）
    │
    ├── rules/
    │   ├── LayerArchitectureRules.java      ← 分層規則
    │   ├── DependencyArchitectureRules.java ← 依賴方向規則
    │   ├── NamingArchitectureRules.java     ← 命名規則
    │   ├── AnnotationArchitectureRules.java ← 標註規則
    │   ├── CycleArchitectureRules.java      ← 循環依賴規則
    │   ├── DomainPurityRules.java           ← Domain 純淨性規則
    │   ├── SecurityBoundaryRules.java       ← 安全邊界規則
    │   └── FrameworkBoundaryRules.java      ← 框架邊界規則（Spring/Jakarta）
    │
    └── freeze/
        └── LegacyFreezeRules.java           ← 使用 Freeze 的 Legacy 規則

src/test/resources/
├── archunit.properties                      ← ArchUnit 全域設定
└── archunit_store/                          ← Freeze 違規基準（要進版控！）
    └── stored.rules

❌ 錯誤做法：10 個模組，每個模組都跑一次「全專案循環檢查」
   → 匯入 10 次、循環演算法跑 10 次

✅ 正確做法：
   - 模組內規則（命名、註解、分層）→ 各模組自己跑
   - 跨模組規則（循環依賴、模組邊界）→ 只在聚合模組跑一次

Controller → Service → Repository

Presentation   ← 使用者介面、REST Controller
     ↓
Application    ← 應用服務、流程協調
     ↓
Domain         ← 業務邏輯
     ↓
Persistence    ← 資料存取

Framework / Infrastructure   ← 最外層
          ↓
     Interface Adapter
          ↓
      Application (Use Case)
          ↓
        Domain (Entity)      ← 最內層

Inbound Adapter  →  [ Port ]  →  Application Core
                                        ↓
                                    [ Port ]
                                        ↑
                               Outbound Adapter

package com.company.order.architecture.rules;

import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.library.Architectures.layeredArchitecture;

class TraditionalLayerRules {

    @ArchTest
    static final ArchRule ARCH_020_layer_dependencies_are_respected =
            layeredArchitecture()
                    .consideringAllDependencies()

                    // 步驟 1：定義有哪些層，以及每層對應哪些套件
                    .layer("Presentation").definedBy("..controller..", "..web..")
                    .layer("Application").definedBy("..service..", "..application..")
                    .layer("Domain").definedBy("..domain..")
                    .layer("Persistence").definedBy("..repository..", "..persistence..")

                    // 步驟 2：定義每層「可以被誰存取」
                    .whereLayer("Presentation").mayNotBeAccessedByAnyLayer()
                    .whereLayer("Application").mayOnlyBeAccessedByLayers("Presentation")
                    .whereLayer("Domain").mayOnlyBeAccessedByLayers("Presentation", "Application", "Persistence")
                    .whereLayer("Persistence").mayOnlyBeAccessedByLayers("Application")

                    .as("[ARCH-020] 傳統分層架構依賴規則")
                    .because("分層邊界確保每一層只承擔自己的責任，"
                           + "跨層存取會讓業務規則被繞過（ADR-002）");
}

// 假設 OrderController 依賴了 org.apache.commons.lang3.StringUtils
// （這個套件沒有被定義成任何一層）

.consideringOnlyDependenciesInLayers()
// → 忽略這個依賴，因為 commons-lang3 不屬於任何已定義的層

.consideringAllDependencies()
// → 會考慮這個依賴。若規則設定得夠嚴，可能會報違規

// 1. 可以被特定層存取
.whereLayer("Application").mayOnlyBeAccessedByLayers("Presentation")

// 2. 不可以被任何層存取（通常用在最外層）
.whereLayer("Presentation").mayNotBeAccessedByAnyLayer()

// 3. 只能存取特定層（從「主動方」的角度定義）
.whereLayer("Domain").mayOnlyAccessLayers("Domain")

.optionalLayer("Messaging").definedBy("..messaging..")

layeredArchitecture()
        .consideringOnlyDependenciesInLayers()
        .withOptionalLayers(true)          // 所有層都變成選用
        .layer("Presentation").definedBy("..web..")
        .layer("Application").definedBy("..application..")
        .layer("Domain").definedBy("..domain..")
        // ...

// 新增一個不在任何層定義中的套件，例如 com.myapp.util
// 然後從 util 去存取任何層——分層規則一條都管不到

layeredArchitecture()
        .consideringOnlyDependenciesInLayers()
        .layer("Presentation").definedBy("..web..")
        .layer("Application").definedBy("..application..")
        .layer("Domain").definedBy("..domain..")
        .layer("Infrastructure").definedBy("..infrastructure..")
        .ensureAllClassesAreContainedInArchitecture()
        .whereLayer("Presentation").mayNotBeAccessedByAnyLayer()
        // ...

// 依套件排除
.ensureAllClassesAreContainedInArchitectureIgnoring("..generated..", "com.myapp.MyApplication")

// 依 predicate 排除
.ensureAllClassesAreContainedInArchitectureIgnoring(
        JavaClass.Predicates.simpleNameEndingWith("Application"))

.ignoreDependency(LegacyBridge.class, OrderRepository.class)              // 指定類別
.ignoreDependency("com.myapp.LegacyBridge", "com.myapp.OrderRepository")  // 完整類別名
.ignoreDependency(originPredicate, targetPredicate)                       // predicate

class ManualLayerRules {

    @ArchTest
    static final ArchRule ARCH_021_presentation_not_accessed = noClasses()
            .that().resideOutsideOfPackage("..controller..")
            .should().dependOnClassesThat().resideInAPackage("..controller..")
            .as("[ARCH-021] 沒有任何層可以依賴 Presentation 層")
            .because("Presentation 是最外層，被依賴代表依賴方向反了");

    @ArchTest
    static final ArchRule ARCH_022_domain_not_depend_on_presentation = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage("..controller..", "..web..")
            .as("[ARCH-022] Domain 不得依賴 Presentation")
            .because("業務邏輯不應該知道請求是從 HTTP、批次還是訊息佇列來的");

    @ArchTest
    static final ArchRule ARCH_023_persistence_not_depend_on_application = noClasses()
            .that().resideInAPackage("..repository..")
            .should().dependOnClassesThat().resideInAnyPackage("..service..", "..controller..")
            .as("[ARCH-023] Persistence 不得依賴 Application 或 Presentation")
            .because("資料存取層被上層依賴是正常的，反過來則代表責任錯置");
}

@ArchTest
static final ArchRule ARCH_024_no_layer_skipping = noClasses()
        .that().resideInAPackage("..controller..")
        .should().dependOnClassesThat().resideInAnyPackage("..repository..", "..persistence..")
        .as("[ARCH-024] Controller 不得跳過 Service 直接存取 Repository")
        .because("跳層會繞過 Service 中的業務規則與交易邊界（ADR-002）");

@ArchTest
static final ArchRule ARCH_025_controllers_should_not_depend_on_each_other = noClasses()
        .that().resideInAPackage("..controller..")
        .should().dependOnClassesThat().resideInAPackage("..controller..")
        .as("[ARCH-025] Controller 之間不得互相依賴")
        .because("Controller 之間的共用邏輯應該下沉到 Application 層，"
               + "互相呼叫會造成難以追蹤的請求鏈");

@ArchTest
static final ArchRule ARCH_026_service_free_of_web_api = noClasses()
        .that().resideInAPackage("..service..")
        .should().dependOnClassesThat().resideInAnyPackage(
                "jakarta.servlet..",
                "org.springframework.web..",
                "org.springframework.http.."
        )
        .as("[ARCH-026] Service 層不得依賴 Web 技術")
        .because("Service 必須能被 REST、批次、排程、MQ 消費者共用；"
               + "依賴 HttpServletRequest 會讓它只能從 HTTP 呼叫");

// 他們的規則
.layer("Domain").definedBy("..domain..")
.layer("Persistence").definedBy("..repository..")
.whereLayer("Persistence").mayOnlyBeAccessedByLayers("Domain", "Application")
//                                                     ↑ 允許 Domain 依賴 Persistence

com.company.order
├── domain                          ← 最內層：純業務
│   ├── model
│   │   ├── Order.java
│   │   ├── OrderId.java
│   │   ├── OrderStatus.java
│   │   └── Money.java
│   ├── event
│   │   └── OrderPlacedEvent.java
│   ├── exception
│   │   └── OrderNotFoundException.java
│   └── service
│       └── OrderPricingService.java   ← Domain Service（純計算，無 IO）
│
├── application                     ← Use Case 層
│   ├── port
│   │   ├── in                      ← 輸入埠：外界能對系統做什麼
│   │   │   ├── PlaceOrderUseCase.java
│   │   │   └── QueryOrderUseCase.java
│   │   └── out                     ← 輸出埠：系統需要外界提供什麼
│   │       ├── LoadOrderPort.java
│   │       ├── SaveOrderPort.java
│   │       └── SendNotificationPort.java
│   └── service
│       ├── PlaceOrderService.java  ← 實作 PlaceOrderUseCase
│       └── QueryOrderService.java
│
├── adapter                         ← Interface Adapter 層
│   ├── in
│   │   └── web
│   │       ├── OrderController.java
│   │       ├── PlaceOrderRequest.java   ← Request DTO
│   │       └── OrderResponse.java       ← Response DTO
│   └── out
│       ├── persistence
│       │   ├── OrderJpaEntity.java
│       │   ├── OrderJpaRepository.java
│       │   ├── OrderPersistenceAdapter.java  ← 實作 Load/SavePort
│       │   └── OrderMapper.java
│       └── notification
│           └── EmailNotificationAdapter.java ← 實作 SendNotificationPort
│
└── configuration                   ← 最外層：框架組裝
    ├── OrderApplication.java
    ├── BeanConfiguration.java
    └── SecurityConfiguration.java

package com.company.order.architecture.rules;

import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.library.Architectures.layeredArchitecture;

/**
 * Clean Architecture 規則集。
 * 對應決策：ADR-003（Domain 純淨性）、ADR-007（依賴反轉）
 */
class CleanArchitectureRules {

    // ========== 第一組：整體分層（用官方 API） ==========

    @ArchTest
    static final ArchRule ARCH_030_clean_architecture_layers =
            layeredArchitecture()
                    .consideringAllDependencies()

                    .layer("Domain").definedBy("..domain..")
                    .layer("Application").definedBy("..application..")
                    .layer("Adapter").definedBy("..adapter..")
                    .layer("Configuration").definedBy("..configuration..")

                    // Domain 可以被所有層存取（它是最內層）
                    .whereLayer("Domain")
                    .mayOnlyBeAccessedByLayers("Application", "Adapter", "Configuration")

                    // Application 只能被 Adapter 與 Configuration 存取
                    .whereLayer("Application")
                    .mayOnlyBeAccessedByLayers("Adapter", "Configuration")

                    // Adapter 只能被 Configuration 存取（用於 Bean 組裝）
                    .whereLayer("Adapter")
                    .mayOnlyBeAccessedByLayers("Configuration")

                    // Configuration 是最外層，不得被任何層存取
                    .whereLayer("Configuration").mayNotBeAccessedByAnyLayer()

                    .as("[ARCH-030] Clean Architecture 分層依賴規則")
                    .because("依賴只能由外向內，這是 Clean Architecture 的核心約束（ADR-003）");

    // ========== 第二組：Domain 純淨性（白名單，最嚴格） ==========

    @ArchTest
    static final ArchRule ARCH_031_domain_purity = classes()
            .that().resideInAPackage("..domain..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage(
                    "..domain..",       // 自己
                    "java..",           // JDK 核心
                    "javax.."           // JDK 擴充（視專案調整）
            )
            .as("[ARCH-031] Domain 只能依賴自己與 JDK")
            .because("Domain 必須能在毫秒內被測試、能在更換技術棧時完整保留（ADR-003）");

    // ========== 第三組：具名的框架禁令（訊息更清楚） ==========

    @ArchTest
    static final ArchRule ARCH_032_domain_free_of_spring = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage("org.springframework..")
            .as("[ARCH-032] Domain 不得依賴 Spring")
            .because("Domain 必須能在沒有 Spring Context 的情況下被 new 出來並測試（ADR-003）");

    @ArchTest
    static final ArchRule ARCH_033_domain_free_of_jpa = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage(
                    "jakarta.persistence..",
                    "javax.persistence..",
                    "org.hibernate.."
            )
            .as("[ARCH-033] Domain 不得依賴 JPA / Hibernate")
            .because("Domain Model 與 Persistence Model 必須分離，"
                   + "否則資料庫 schema 會反向決定業務模型的設計（ADR-003）");

    @ArchTest
    static final ArchRule ARCH_034_domain_free_of_web = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage(
                    "jakarta.servlet..",
                    "org.springframework.web..",
                    "com.fasterxml.jackson.."
            )
            .as("[ARCH-034] Domain 不得依賴 Web 或序列化技術")
            .because("Domain 不該知道自己會被如何傳輸或序列化（ADR-003）");

    // ========== 第四組：依賴反轉 ==========

    @ArchTest
    static final ArchRule ARCH_035_application_not_depend_on_adapter = noClasses()
            .that().resideInAPackage("..application..")
            .should().dependOnClassesThat().resideInAPackage("..adapter..")
            .as("[ARCH-035] Application 不得依賴 Adapter 實作")
            .because("Application 只能依賴自己定義的 Port 介面，"
                   + "實作由 Configuration 在執行期注入（依賴反轉，ADR-007）");

    @ArchTest
    static final ArchRule ARCH_036_ports_must_be_interfaces = classes()
            .that().resideInAPackage("..application.port..")
            .should().beInterfaces()
            .as("[ARCH-036] Port 必須是介面")
            .because("Port 是抽象契約，具體類別會讓依賴反轉失效（ADR-007）");

    // ========== 第五組：Adapter 之間不得互相依賴 ==========

    @ArchTest
    static final ArchRule ARCH_037_adapters_are_isolated = noClasses()
            .that().resideInAPackage("..adapter.in..")
            .should().dependOnClassesThat().resideInAPackage("..adapter.out..")
            .as("[ARCH-037] Inbound Adapter 不得直接依賴 Outbound Adapter")
            .because("Adapter 之間必須透過 Application 層溝通，"
                   + "否則 Controller 會直接操作資料庫，繞過所有業務規則（ADR-007）");
}

import static com.tngtech.archunit.library.Architectures.onionArchitecture;

@ArchTest
static final ArchRule ARCH_038_onion_architecture =
        onionArchitecture()
                .domainModels("com.company.order.domain.model..")
                .domainServices("com.company.order.domain.service..")
                .applicationServices("com.company.order.application..")
                .adapter("web", "com.company.order.adapter.in.web..")
                .adapter("persistence", "com.company.order.adapter.out.persistence..")
                .adapter("notification", "com.company.order.adapter.out.notification..")
                .as("[ARCH-038] Onion Architecture 規則")
                .because("確保 Domain 獨立、Adapter 互不依賴（ADR-003）");

// src/main/java/com/company/order/domain/model/OrderId.java
package com.company.order.domain.model;

import java.util.Objects;
import java.util.UUID;

/**
 * 訂單識別碼。
 * 使用 record 確保不可變；沒有任何框架依賴。
 */
public record OrderId(String value) {

    public OrderId {
        Objects.requireNonNull(value, "OrderId 不可為 null");
        if (value.isBlank()) {
            throw new IllegalArgumentException("OrderId 不可為空白");
        }
    }

    public static OrderId generate() {
        return new OrderId(UUID.randomUUID().toString());
    }
}

// src/main/java/com/company/order/domain/model/Order.java
package com.company.order.domain.model;

import com.company.order.domain.exception.OrderStateException;

import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;

/**
 * 訂單聚合根。
 *
 * 架構約束（ARCH-031）：本類別只依賴 java.* 與同層的 domain 類別。
 * 驗證方式：可以在不啟動 Spring Context 的情況下 new 出來並測試。
 */
public class Order {

    private final OrderId id;
    private final String customerId;
    private final List<OrderLine> lines;
    private OrderStatus status;
    private final Instant createdAt;

    private Order(OrderId id, String customerId, List<OrderLine> lines, Instant createdAt) {
        this.id = Objects.requireNonNull(id);
        this.customerId = Objects.requireNonNull(customerId);
        this.lines = new ArrayList<>(Objects.requireNonNull(lines));
        this.status = OrderStatus.DRAFT;
        this.createdAt = Objects.requireNonNull(createdAt);
    }

    public static Order place(OrderId id, String customerId, List<OrderLine> lines, Instant now) {
        if (lines.isEmpty()) {
            throw new OrderStateException("訂單至少需要一個品項");
        }
        Order order = new Order(id, customerId, lines, now);
        order.status = OrderStatus.PLACED;
        return order;
    }

    /** 業務規則：只有 PLACED 狀態的訂單可以取消 */
    public void cancel() {
        if (status != OrderStatus.PLACED) {
            throw new OrderStateException(
                    "只有已成立的訂單可以取消，目前狀態：" + status);
        }
        this.status = OrderStatus.CANCELLED;
    }

    public Money totalAmount() {
        return lines.stream()
                .map(OrderLine::subtotal)
                .reduce(Money.zero(), Money::add);
    }

    public OrderId id() { return id; }
    public String customerId() { return customerId; }
    public OrderStatus status() { return status; }
    public Instant createdAt() { return createdAt; }
    public List<OrderLine> lines() { return List.copyOf(lines); }
}

// src/main/java/com/company/order/application/port/in/PlaceOrderUseCase.java
package com.company.order.application.port.in;

import com.company.order.domain.model.OrderId;

/**
 * 輸入埠：外界可以對本系統執行「下訂單」這個動作。
 * 架構約束（ARCH-036）：Port 必須是介面。
 */
public interface PlaceOrderUseCase {
    OrderId placeOrder(PlaceOrderCommand command);
}

// src/main/java/com/company/order/application/port/in/PlaceOrderCommand.java
package com.company.order.application.port.in;

import java.util.List;
import java.util.Objects;

/**
 * Command 物件：Application 層自己的輸入模型。
 * 注意它不是 Web 的 Request DTO——那個在 adapter.in.web。
 */
public record PlaceOrderCommand(String customerId, List<Item> items) {

    public PlaceOrderCommand {
        Objects.requireNonNull(customerId);
        Objects.requireNonNull(items);
        if (items.isEmpty()) {
            throw new IllegalArgumentException("訂單品項不可為空");
        }
    }

    public record Item(String productId, int quantity, long unitPriceInCents) {}
}

// src/main/java/com/company/order/application/port/out/SaveOrderPort.java
package com.company.order.application.port.out;

import com.company.order.domain.model.Order;

/**
 * 輸出埠：本系統需要外界提供「儲存訂單」的能力。
 *
 * 關鍵：這個介面定義在 application 層，實作在 adapter 層。
 * 這就是依賴反轉——介面屬於「使用者」，不屬於「實作者」。
 */
public interface SaveOrderPort {
    void save(Order order);
}

// src/main/java/com/company/order/application/service/PlaceOrderService.java
package com.company.order.application.service;

import com.company.order.application.port.in.PlaceOrderCommand;
import com.company.order.application.port.in.PlaceOrderUseCase;
import com.company.order.application.port.out.SaveOrderPort;
import com.company.order.application.port.out.SendNotificationPort;
import com.company.order.domain.model.Money;
import com.company.order.domain.model.Order;
import com.company.order.domain.model.OrderId;
import com.company.order.domain.model.OrderLine;

import java.time.Clock;
import java.util.List;

/**
 * Use Case 實作。
 *
 * 架構約束（ARCH-035）：本類別不得 import 任何 ..adapter.. 的東西。
 * 它只認識 Port 介面與 Domain。
 *
 * 注意：此類別「沒有」 @Service 註解——Bean 註冊集中在 configuration 層，
 * 讓 application 層完全不依賴 Spring（ADR-003）。
 */
public class PlaceOrderService implements PlaceOrderUseCase {

    private final SaveOrderPort saveOrderPort;
    private final SendNotificationPort notificationPort;
    private final Clock clock;

    public PlaceOrderService(SaveOrderPort saveOrderPort,
                             SendNotificationPort notificationPort,
                             Clock clock) {
        this.saveOrderPort = saveOrderPort;
        this.notificationPort = notificationPort;
        this.clock = clock;
    }

    @Override
    public OrderId placeOrder(PlaceOrderCommand command) {
        List<OrderLine> lines = command.items().stream()
                .map(item -> new OrderLine(
                        item.productId(),
                        item.quantity(),
                        Money.ofCents(item.unitPriceInCents())))
                .toList();

        Order order = Order.place(
                OrderId.generate(),
                command.customerId(),
                lines,
                clock.instant());

        saveOrderPort.save(order);
        notificationPort.notifyOrderPlaced(order.id(), order.customerId());

        return order.id();
    }
}

// src/main/java/com/company/order/adapter/out/persistence/OrderPersistenceAdapter.java
package com.company.order.adapter.out.persistence;

import com.company.order.application.port.out.LoadOrderPort;
import com.company.order.application.port.out.SaveOrderPort;
import com.company.order.domain.model.Order;
import com.company.order.domain.model.OrderId;
import org.springframework.stereotype.Component;

import java.util.Optional;

/**
 * Persistence Adapter：實作 application 定義的輸出埠。
 *
 * 依賴方向：adapter → application（Port 介面）、adapter → domain（模型）
 * 這是允許的，因為 adapter 在外層。
 */
@Component
public class OrderPersistenceAdapter implements SaveOrderPort, LoadOrderPort {

    private final OrderJpaRepository repository;
    private final OrderMapper mapper;

    public OrderPersistenceAdapter(OrderJpaRepository repository, OrderMapper mapper) {
        this.repository = repository;
        this.mapper = mapper;
    }

    @Override
    public void save(Order order) {
        repository.save(mapper.toEntity(order));
    }

    @Override
    public Optional<Order> load(OrderId orderId) {
        return repository.findById(orderId.value())
                .map(mapper::toDomain);
    }
}

// src/main/java/com/company/order/configuration/BeanConfiguration.java
package com.company.order.configuration;

import com.company.order.application.port.in.PlaceOrderUseCase;
import com.company.order.application.port.out.SaveOrderPort;
import com.company.order.application.port.out.SendNotificationPort;
import com.company.order.application.service.PlaceOrderService;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.time.Clock;

/**
 * 依賴組裝集中在最外層。
 * 這讓 application 層可以完全不知道 Spring 的存在（ADR-003）。
 */
@Configuration
public class BeanConfiguration {

    @Bean
    public Clock clock() {
        return Clock.systemUTC();
    }

    @Bean
    public PlaceOrderUseCase placeOrderUseCase(SaveOrderPort saveOrderPort,
                                               SendNotificationPort notificationPort,
                                               Clock clock) {
        return new PlaceOrderService(saveOrderPort, notificationPort, clock);
    }
}

package com.company.order.domain.model;

import org.junit.jupiter.api.Test;

import java.time.Instant;
import java.util.List;

import static org.junit.jupiter.api.Assertions.*;

/**
 * 注意：這個測試「沒有」 @SpringBootTest。
 * 如果 Domain 真的乾淨，它應該在幾毫秒內執行完畢。
 *
 * 如果你發現這個測試需要 Spring Context 才能跑，
 * 代表 Domain 已經被污染了——比任何 ArchUnit 規則更直接的證據。
 */
class OrderTest {

    @Test
    void 已成立的訂單可以被取消() {
        Order order = Order.place(
                OrderId.generate(),
                "CUST-001",
                List.of(new OrderLine("P-001", 2, Money.ofCents(15000))),
                Instant.parse("2026-09-16T10:00:00Z"));

        order.cancel();

        assertEquals(OrderStatus.CANCELLED, order.status());
    }

    @Test
    void 草稿訂單不可以被取消() {
        // ...
    }
}

application/
    service/PlaceOrderService.java
adapter/
    out/persistence/
        SaveOrderPort.java          ← 介面放在這裡！
        OrderPersistenceAdapter.java

noClasses().that().resideInAPackage("..application..")
        .should().dependOnClassesThat().resideInAPackage("..adapter..");

package com.company.order.architecture.rules;

import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

/**
 * Hexagonal Architecture（Ports and Adapters）規則集。
 * 對應決策：ADR-007
 */
class HexagonalArchitectureRules {

    // ========== Core 的純淨性 ==========

    @ArchTest
    static final ArchRule ARCH_040_domain_knows_nothing_outside = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage(
                    "..application..", "..adapter..", "..configuration..")
            .as("[ARCH-040] Domain 不得知道 Application、Adapter 或 Configuration 的存在")
            .because("Domain 是六邊形的最核心，必須對外部一無所知（ADR-007）");

    @ArchTest
    static final ArchRule ARCH_041_application_not_depend_on_adapters = noClasses()
            .that().resideInAPackage("..application..")
            .should().dependOnClassesThat().resideInAPackage("..adapter..")
            .as("[ARCH-041] Application Core 不得依賴任何 Adapter")
            .because("Core 只透過 Port 介面與外界互動，"
                   + "這讓同一組業務邏輯可以被 REST、批次、MQ 共用（ADR-007）");

    // ========== Port 的規範 ==========

    @ArchTest
    static final ArchRule ARCH_042_ports_are_interfaces = classes()
            .that().resideInAPackage("..application.port..")
            .should().beInterfaces()
            .as("[ARCH-042] 所有 Port 必須是介面")
            .because("Port 是抽象契約（ADR-007）");

    @ArchTest
    static final ArchRule ARCH_043_ports_are_public = classes()
            .that().resideInAPackage("..application.port..")
            .should().bePublic()
            .as("[ARCH-043] Port 必須是 public")
            .because("Port 需要被不同套件的 Adapter 實作與呼叫（ADR-007）");

    // ========== Adapter 的規範 ==========

    @ArchTest
    static final ArchRule ARCH_044_inbound_adapters_only_use_inbound_ports = classes()
            .that().resideInAPackage("..adapter.in..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage(
                    "..adapter.in..",              // 自己
                    "..application.port.in..",     // 只能用輸入埠
                    "..domain..",                  // 可以用領域模型（視決策而定）
                    "java..", "jakarta..",
                    "org.springframework..",
                    "com.fasterxml.jackson.."
            )
            .as("[ARCH-044] Inbound Adapter 只能依賴 Port In")
            .because("Controller 直接呼叫輸出埠會繞過業務邏輯（ADR-007）");

    @ArchTest
    static final ArchRule ARCH_045_outbound_adapters_implement_outbound_ports = classes()
            .that().resideInAPackage("..adapter.out..")
            .and().haveSimpleNameEndingWith("Adapter")
            .should().dependOnClassesThat().resideInAPackage("..application.port.out..")
            .as("[ARCH-045] Outbound Adapter 必須實作輸出埠")
            .because("沒有實作 Port 的 Adapter 代表它繞過了架構契約（ADR-007）");

    // ========== Adapter 之間的隔離（最重要） ==========

    @ArchTest
    static final ArchRule ARCH_046_adapters_do_not_know_each_other = noClasses()
            .that().resideInAPackage("..adapter.in..")
            .should().dependOnClassesThat().resideInAPackage("..adapter.out..")
            .as("[ARCH-046] Inbound Adapter 不得依賴 Outbound Adapter")
            .because("兩側 Adapter 必須完全隔離，"
                   + "否則 Controller 會直接操作資料庫，六邊形架構失去意義（ADR-007）");

    @ArchTest
    static final ArchRule ARCH_047_outbound_adapters_do_not_know_inbound = noClasses()
            .that().resideInAPackage("..adapter.out..")
            .should().dependOnClassesThat().resideInAPackage("..adapter.in..")
            .as("[ARCH-047] Outbound Adapter 不得依賴 Inbound Adapter")
            .because("Repository 依賴 Controller 是嚴重的責任錯置（ADR-007）");
}

public interface SaveOrderPort {
    void save(OrderJpaEntity entity);   // ❌ 洩漏了 JPA Entity！
}

@ArchTest
static final ArchRule ARCH_048_port_signatures_are_clean = noMethods()
        .that().areDeclaredInClassesThat().resideInAPackage("..application.port..")
        .should().haveRawParameterTypes(
                com.tngtech.archunit.base.DescribedPredicate.describe(
                        "任何位於 ..adapter.. 的型別",
                        types -> types.stream().anyMatch(
                                t -> t.getPackageName().contains(".adapter."))))
        .as("[ARCH-048] Port 的方法參數不得使用 Adapter 層型別")
        .because("Port 的簽章就是架構契約，"
               + "洩漏 JPA Entity 等於讓 Core 依賴了資料庫模型（ADR-007）");

@ArchTest
static final ArchRule ARCH_049_port_package_is_clean = classes()
        .that().resideInAPackage("..application.port..")
        .should().onlyDependOnClassesThat()
        .resideInAnyPackage(
                "..application.port..",
                "..domain..",
                "java.."
        )
        .as("[ARCH-049] Port 套件只能依賴 Domain 與 JDK")
        .because("Port 是 Core 的對外契約，必須用純粹的業務語彙表達（ADR-007）");

// ① Port 定義（application 層）
package com.company.order.application.port.out;

import com.company.order.domain.model.Order;
import com.company.order.domain.model.OrderId;

import java.util.Optional;

public interface LoadOrderPort {
    Optional<Order> load(OrderId orderId);   // 參數與回傳都是 Domain 型別
}

// ② Core 使用 Port（application 層）
package com.company.order.application.service;

import com.company.order.application.port.in.QueryOrderUseCase;
import com.company.order.application.port.out.LoadOrderPort;
import com.company.order.domain.exception.OrderNotFoundException;
import com.company.order.domain.model.Order;
import com.company.order.domain.model.OrderId;

public class QueryOrderService implements QueryOrderUseCase {

    private final LoadOrderPort loadOrderPort;

    public QueryOrderService(LoadOrderPort loadOrderPort) {
        this.loadOrderPort = loadOrderPort;
    }

    @Override
    public Order findById(OrderId orderId) {
        return loadOrderPort.load(orderId)
                .orElseThrow(() -> new OrderNotFoundException(orderId.value()));
    }
}

// ③ Adapter 實作 Port（adapter 層）
package com.company.order.adapter.out.persistence;

import com.company.order.application.port.out.LoadOrderPort;
import com.company.order.domain.model.Order;
import com.company.order.domain.model.OrderId;
import org.springframework.stereotype.Component;

import java.util.Optional;

@Component
public class OrderLoadAdapter implements LoadOrderPort {

    private final OrderJpaRepository repository;
    private final OrderMapper mapper;

    public OrderLoadAdapter(OrderJpaRepository repository, OrderMapper mapper) {
        this.repository = repository;
        this.mapper = mapper;
    }

    @Override
    public Optional<Order> load(OrderId orderId) {
        return repository.findById(orderId.value())
                .map(mapper::toDomain);   // JPA Entity → Domain Model 的轉換發生在這裡
    }
}

// ④ 測試時可以用純 Java 的假實作，完全不需要資料庫
package com.company.order.application.service;

import com.company.order.application.port.out.LoadOrderPort;
import com.company.order.domain.model.Order;
import com.company.order.domain.model.OrderId;

import java.util.HashMap;
import java.util.Map;
import java.util.Optional;

/**
 * 這個 fake 實作只有 10 行，不需要 Spring、不需要資料庫、不需要 Mockito。
 * 能寫出這種測試，就是 Hexagonal Architecture 真正的投資報酬。
 */
class InMemoryOrderRepository implements LoadOrderPort {

    private final Map<String, Order> store = new HashMap<>();

    void put(Order order) {
        store.put(order.id().value(), order);
    }

    @Override
    public Optional<Order> load(OrderId orderId) {
        return Optional.ofNullable(store.get(orderId.value()));
    }
}

// application/port/out/UnderwritingPort.java
public interface UnderwritingPort {
    UnderwritingResultDto evaluate(PolicyApplicationDto application);
}

com.company.product
├── controller          ← @RestController
├── service             ← @Service（介面 + 實作，或只有實作）
├── repository          ← @Repository / JpaRepository
├── entity              ← @Entity
├── dto                 ← Request / Response
├── mapper              ← Entity ↔ DTO 轉換
├── config              ← @Configuration
├── exception           ← 自訂例外與 @ControllerAdvice
└── util                ← 工具類別

package com.company.product.architecture.rules;

import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import org.springframework.stereotype.Controller;
import org.springframework.stereotype.Repository;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.RestController;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.library.Architectures.layeredArchitecture;

class SpringBootArchitectureRules {

    // ========== 整體分層 ==========

    @ArchTest
    static final ArchRule ARCH_050_spring_layers = layeredArchitecture()
            .consideringOnlyDependenciesInLayers()

            .layer("Controller").definedBy("..controller..")
            .layer("Service").definedBy("..service..")
            .layer("Repository").definedBy("..repository..")
            .layer("Entity").definedBy("..entity..")
            .layer("Dto").definedBy("..dto..")

            .whereLayer("Controller").mayNotBeAccessedByAnyLayer()
            .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")
            .whereLayer("Repository").mayOnlyBeAccessedByLayers("Service")

            .as("[ARCH-050] Spring Boot 分層依賴規則")
            .because("確保請求一律經過 Service 層的業務規則與交易邊界（ADR-002）");

    // ========== 核心禁令 ==========

    @ArchTest
    static final ArchRule ARCH_051_controller_not_touch_repository = noClasses()
            .that().resideInAPackage("..controller..")
            .should().dependOnClassesThat().resideInAPackage("..repository..")
            .as("[ARCH-051] Controller 不得直接依賴 Repository")
            .because("跳過 Service 會繞過業務規則、權限檢查與交易管理（ADR-002）");

    @ArchTest
    static final ArchRule ARCH_052_service_not_depend_on_controller = noClasses()
            .that().resideInAPackage("..service..")
            .should().dependOnClassesThat().resideInAPackage("..controller..")
            .as("[ARCH-052] Service 不得依賴 Controller")
            .because("依賴方向反轉會造成循環，也代表責任錯置（ADR-002）");

    @ArchTest
    static final ArchRule ARCH_053_repository_not_depend_on_upper_layers = noClasses()
            .that().resideInAPackage("..repository..")
            .should().dependOnClassesThat().resideInAnyPackage("..service..", "..controller..")
            .as("[ARCH-053] Repository 不得依賴 Service 或 Controller")
            .because("資料存取層必須是最底層，被上層依賴而非反向（ADR-002）");

    @ArchTest
    static final ArchRule ARCH_054_controller_not_expose_entity = noClasses()
            .that().resideInAPackage("..controller..")
            .should().dependOnClassesThat().resideInAPackage("..entity..")
            .as("[ARCH-054] Controller 不得直接使用 Entity")
            .because("Entity 外洩會讓資料庫 schema 變成對外 API 契約，"
                   + "改一個欄位就要改所有下游系統（ADR-005）");

    // ========== Spring 註解與套件的對應 ==========

    @ArchTest
    static final ArchRule ARCH_055_controllers_are_annotated = classes()
            .that().resideInAPackage("..controller..")
            .and().haveSimpleNameEndingWith("Controller")
            .should().beAnnotatedWith(RestController.class)
            .orShould().beAnnotatedWith(Controller.class)
            .as("[ARCH-055] Controller 套件的類別必須標註 @RestController 或 @Controller")
            .because("避免出現「命名像 Controller 但沒被 Spring 掃描」的殭屍類別");

    @ArchTest
    static final ArchRule ARCH_056_services_reside_in_service_package = classes()
            .that().areAnnotatedWith(Service.class)
            .should().resideInAPackage("..service..")
            .as("[ARCH-056] @Service 只能出現在 service 套件")
            .because("註解與套件必須一致，否則程式碼結構會誤導維護者與 AI Agent");

    @ArchTest
    static final ArchRule ARCH_057_repositories_reside_in_repository_package = classes()
            .that().areAnnotatedWith(Repository.class)
            .should().resideInAPackage("..repository..")
            .as("[ARCH-057] @Repository 只能出現在 repository 套件")
            .because("同上");

    // ========== 依賴注入方式 ==========

    @ArchTest
    static final ArchRule ARCH_058_no_field_injection = noFields()
            .should().beAnnotatedWith(org.springframework.beans.factory.annotation.Autowired.class)
            .as("[ARCH-058] 不得使用欄位注入（@Autowired on field）")
            .because("欄位注入讓類別無法用純 Java 建構、隱藏了必要依賴、"
                   + "也讓不可變性無法保證；請使用建構子注入");
}

// 1. 若 Domain 允許使用 JSpecify 的 null 註解，白名單要加上
@ArchTest
static final ArchRule domain_purity_spring_boot_4 = classes()
        .that().resideInAPackage("..domain..")
        .should().onlyDependOnClassesThat()
        .resideInAnyPackage(
                "..domain..",
                "java..",
                "org.jspecify.annotations.."   // ← Spring Boot 4 的 null safety 註解
        )
        .because("JSpecify 註解是編譯期契約，不引入執行期依賴，"
               + "經 ADR-011 核准可用於 Domain");

class SpringBootPracticalRules {

    /** 交易註解只應出現在 Service 層 */
    @ArchTest
    static final ArchRule ARCH_060_transactional_only_in_service = classes()
            .that().areAnnotatedWith(org.springframework.transaction.annotation.Transactional.class)
            .should().resideInAnyPackage("..service..", "..application..")
            .as("[ARCH-060] @Transactional 只能標註在 Service 層")
            .because("交易邊界必須集中管理；標在 Controller 會讓交易涵蓋 HTTP 處理時間，"
                   + "標在 Repository 會讓每次存取各自開交易，兩者都會造成問題（ADR-009）");

    /** Controller 必須回傳 DTO，不得回傳 Entity */
    @ArchTest
    static final ArchRule ARCH_061_controller_returns_dto = methods()
            .that().areDeclaredInClassesThat().resideInAPackage("..controller..")
            .and().arePublic()
            .should().notHaveRawReturnType(
                    com.tngtech.archunit.base.DescribedPredicate.describe(
                            "JPA Entity",
                            javaClass -> javaClass.isAnnotatedWith(jakarta.persistence.Entity.class)))
            .as("[ARCH-061] Controller 的公開方法不得直接回傳 Entity")
            .because("Entity 作為 API 回應會洩漏資料庫結構、"
                   + "造成延遲載入例外、也讓 schema 變更直接破壞 API 契約（ADR-005）");

    /** 設定類別只能在 config 套件 */
    @ArchTest
    static final ArchRule ARCH_062_configuration_in_config_package = classes()
            .that().areAnnotatedWith(org.springframework.context.annotation.Configuration.class)
            .should().resideInAPackage("..config..")
            .as("[ARCH-062] @Configuration 只能出現在 config 套件")
            .because("設定分散會讓「這個 Bean 從哪來」變得無法追蹤");

    /** 禁止在 Service 使用 Web 型別 */
    @ArchTest
    static final ArchRule ARCH_063_service_free_of_web_types = noClasses()
            .that().resideInAPackage("..service..")
            .should().dependOnClassesThat().resideInAnyPackage(
                    "jakarta.servlet..",
                    "org.springframework.web.context..",
                    "org.springframework.http..")
            .as("[ARCH-063] Service 不得依賴 Web 型別")
            .because("Service 必須能被批次、排程、MQ 消費者共用（ADR-002）");

    /** 禁止直接使用 RestTemplate（已被 RestClient / WebClient 取代） */
    @ArchTest
    static final ArchRule ARCH_064_no_rest_template = noClasses()
            .should().dependOnClassesThat()
            .haveFullyQualifiedName("org.springframework.web.client.RestTemplate")
            .as("[ARCH-064] 不得使用 RestTemplate")
            .because("專案統一使用 RestClient（同步）與 WebClient（非同步），"
                   + "混用會讓逾時、重試、追蹤等橫切設定無法統一（ADR-013）");
}

@RestController
public class ApplicationController {

    @PostMapping("/applications")
    @Transactional   // ← 問題在這裡
    public ApplicationResponse submit(@RequestBody SubmitRequest request) {
        var result = applicationService.submit(request);
        var receipt = receiptService.generate(result);      // 呼叫外部列印服務
        var notification = notificationService.send(result); // 呼叫外部簡訊 API
        return toResponse(result, receipt, notification);
    }
}

[ARCH-060] @Transactional 只能標註在 Service 層 was violated (1 times):
  Class <com.company.controller.ApplicationController> is annotated with @Transactional
  in (ApplicationController.java:24)
  because 交易邊界必須集中管理；標在 Controller 會讓交易涵蓋 HTTP 處理時間...

@RestController
public class ApplicationController {

    @PostMapping("/applications")
    public ApplicationResponse submit(@RequestBody SubmitRequest request) {
        // 交易只涵蓋資料庫操作
        var result = applicationService.submit(request);

        // 外部呼叫在交易之外
        var receipt = receiptService.generate(result);
        var notification = notificationService.send(result);

        return toResponse(result, receipt, notification);
    }
}

public class OrderController {
    private OrderRepository repository;      // ← depend（欄位型別），不是 access

    public void handle() {
        repository.findAll();                // ← 這才是 access（方法呼叫）
    }

    public OrderEntity get() { ... }         // ← depend（回傳型別），不是 access
}

// 類別：com.company.order.domain.Order
// 比對對象："com.company.order.domain"   ← 注意，不含 "Order"

.resideInAPackage("..domain..")   // ✅ 符合
.resideInAPackage("..Order..")    // ❌ 不符合——Order 是類別名，不是套件段

class PackageDependencyRules {

    /** 白名單：util 套件必須是純工具，不得依賴任何業務套件 */
    @ArchTest
    static final ArchRule ARCH_070_util_is_pure = classes()
            .that().resideInAPackage("..util..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage("..util..", "java..", "org.apache.commons..")
            .as("[ARCH-070] util 套件只能依賴 JDK 與通用函式庫")
            .because("工具類別一旦依賴業務套件，就無法被其他模組重用，"
                   + "也會製造出難以察覺的循環依賴");

    /** 黑名單：任何人不得依賴 internal 套件 */
    @ArchTest
    static final ArchRule ARCH_071_internal_is_private = noClasses()
            .that().resideOutsideOfPackage("..internal..")
            .should().dependOnClassesThat().resideInAPackage("..internal..")
            .as("[ARCH-071] internal 套件不得被外部使用")
            .because("internal 是模組的實作細節，不屬於公開 API，"
                   + "被外部依賴後就再也改不動了");

    /** 模組邊界：訂單模組與庫存模組只能透過各自的 api 套件溝通 */
    @ArchTest
    static final ArchRule ARCH_072_module_boundary = noClasses()
            .that().resideInAPackage("com.company.order..")
            .should().dependOnClassesThat()
            .resideInAPackage("com.company.inventory..")
            .andShould().dependOnClassesThat()
            .resideOutsideOfPackage("com.company.inventory.api..")
            .as("[ARCH-072] 訂單模組只能透過 inventory.api 存取庫存模組")
            .because("模組必須有明確的公開介面，才有可能在未來拆成獨立服務（ADR-015）");

    /** 禁用特定第三方函式庫 */
    @ArchTest
    static final ArchRule ARCH_073_no_deprecated_json_lib = noClasses()
            .should().dependOnClassesThat().resideInAnyPackage(
                    "org.json..",
                    "net.sf.json..",
                    "com.google.gson..")
            .as("[ARCH-073] 統一使用 Jackson 處理 JSON")
            .because("多套 JSON 函式庫並存會造成序列化行為不一致、"
                   + "也增加了三倍的 CVE 追蹤成本（ADR-016）");
}

// 語法層級的組合（最常用）
classes()
    .that().resideInAPackage("..service..")
    .and().areAnnotatedWith(Service.class)
    .and().arePublic()
    .should().haveSimpleNameEndingWith("Service");

// Predicate 層級的組合（更靈活）
import static com.tngtech.archunit.core.domain.JavaClass.Predicates.*;
import static com.tngtech.archunit.base.DescribedPredicate.*;

classes()
    .that(resideInAPackage("..service..").and(not(simpleNameEndingWith("Test"))))
    .should().bePublic();

resideInAPackage("..domain..")
resideInAnyPackage("..a..", "..b..")
resideOutsideOfPackage("..test..")
simpleName("Order")
simpleNameStartingWith("Abstract")
simpleNameEndingWith("Service")
simpleNameContaining("Order")
type(String.class)
assignableTo(Exception.class)
assignableFrom(Order.class)
implement(Serializable.class)
annotatedWith(Service.class)
metaAnnotatedWith(Component.class)   // 含間接標註（@Service 上有 @Component）
INTERFACES
ENUMS
RECORDS

classes().that().resideInAPackage("..domain")   // ❌ 少了尾端的 ..

com.company.order.domain          ← 只有 3 個類別（幾個 enum）
com.company.order.domain.model    ← 24 個類別（真正的業務模型）
com.company.order.domain.service  ← 8 個類別

類別層級：  A → B → C → A
套件層級：  order → payment → notification → order

import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;

@ArchTest
static final ArchRule ARCH_080_no_cycles_between_modules = slices()
        .matching("com.company.(*)..")
        .should().beFreeOfCycles()
        .as("[ARCH-080] 頂層模組之間不得有循環依賴")
        .because("循環依賴讓模組無法獨立測試、部署與理解（ADR-015）");

class CycleArchitectureRules {

    /** 第 1 層：頂層模組之間（最重要，Level 1 強制） */
    @ArchTest
    static final ArchRule ARCH_080_module_level = slices()
            .matching("com.company.(*)..")
            .should().beFreeOfCycles()
            .as("[ARCH-080] 業務模組之間不得循環")
            .because("模組是未來拆分服務的邊界，循環會讓拆分不可能（ADR-015）");

    /** 第 2 層：模組內的層次之間（Level 2） */
    @ArchTest
    static final ArchRule ARCH_081_layer_level = slices()
            .matching("com.company.order.(*)..")
            .should().beFreeOfCycles()
            .as("[ARCH-081] 訂單模組內的層次之間不得循環")
            .because("層次循環代表分層邊界已經模糊");

    /** 第 3 層：細緻套件（Level 3，通常對 Legacy 專案會爆量，建議搭配 Freeze） */
    @ArchTest
    static final ArchRule ARCH_082_package_level = slices()
            .matching("com.company.(**)")
            .should().beFreeOfCycles()
            .as("[ARCH-082] 所有套件之間不得循環")
            .because("細粒度的循環是結構腐化的早期訊號");
}

@ArchTest
static final ArchRule ARCH_083_services_are_isolated = slices()
        .matching("com.company.(*).service..")
        .should().notDependOnEachOther()
        .as("[ARCH-083] 各模組的 Service 不得互相直接依賴")
        .because("跨模組呼叫必須透過模組的公開 API，"
               + "直接呼叫別的模組的 Service 會讓模組邊界形同虛設（ADR-015）");

@ArchTest
static final ArchRule ARCH_084_cycles_with_exception = slices()
        .matching("com.company.(*)..")
        .should().beFreeOfCycles()
        .ignoreDependency(
                com.company.order.OrderFacade.class,
                com.company.payment.PaymentFacade.class)
        .as("[ARCH-084] 模組循環檢查（排除已核准的 Facade 互呼）")
        .because("ADR-018 核准訂單與付款 Facade 之間的雙向呼叫，"
               + "因為兩者屬於同一個交易一致性邊界");

# 最多偵測幾個循環後停止（預設 100）
# Legacy 專案可調小，避免報告過長、記憶體暴增
cycles.maxNumberToDetect=20

# 每條依賴邊最多記錄幾筆細節（預設 20）
# 調小可大幅縮短報告長度
cycles.maxNumberOfDependenciesPerEdge=5

階段 1  只開「頂層模組」的循環檢查（數量最少、價值最高）
階段 2  把既有循環用 Freeze 凍結，擋住新增
階段 3  每季挑 1～2 個循環拆解
階段 4  循環數降到可控後，再開「細粒度」檢查

order → inventory  （下單要扣庫存，合理）
inventory → member （庫存預留要查會員等級，可疑）
member → order     （會員等級計算要看歷史訂單，循環！）

修正前：member → order（同步查詢歷史訂單總額）

修正後：
  order 發布 OrderCompletedEvent
  member 訂閱事件，自行累計會員消費額
  member 不再需要依賴 order

order → inventory → member    （單向，無循環）
order --事件--> member         （非同步，不構成編譯期依賴）

@ArchTest
static final ArchRule ARCH_085_member_not_call_order = noClasses()
        .that().resideInAPackage("com.company.member..")
        .should().dependOnClassesThat().resideInAPackage("com.company.order..")
        .andShould().dependOnClassesThat()
        .resideOutsideOfPackage("com.company.order.event..")   // 事件類別是例外
        .as("[ARCH-085] 會員模組只能透過事件與訂單模組互動")
        .because("ADR-020：訂單→會員為單向事件流，會員不得同步查詢訂單");

class NamingArchitectureRules {

    // ===== 方向一：叫這個名字的，必須放在這裡 =====

    @ArchTest
    static final ArchRule ARCH_090_controllers_in_controller_package = classes()
            .that().haveSimpleNameEndingWith("Controller")
            .should().resideInAnyPackage("..controller..", "..adapter.in.web..")
            .as("[ARCH-090] Controller 必須位於 controller 或 web adapter 套件")
            .because("名稱與位置不一致會誤導維護者，也會讓依賴規則失效");

    // ===== 方向二：放在這裡的，必須叫這個名字 =====

    @ArchTest
    static final ArchRule ARCH_091_classes_in_controller_package_are_controllers = classes()
            .that().resideInAPackage("..controller..")
            .and().areNotNestedClasses()
            .should().haveSimpleNameEndingWith("Controller")
            .as("[ARCH-091] controller 套件內只能有 Controller")
            .because("套件是責任邊界，混入其他類型的類別會讓邊界模糊");
}

class FullNamingRules {

    @ArchTest
    static final ArchRule ARCH_092_service = classes()
            .that().haveSimpleNameEndingWith("Service")
            .should().resideInAnyPackage("..service..", "..application..")
            .because("Service 代表應用服務，必須位於應用層");

    @ArchTest
    static final ArchRule ARCH_093_repository = classes()
            .that().haveSimpleNameEndingWith("Repository")
            .should().resideInAnyPackage("..repository..", "..adapter.out.persistence..")
            .because("Repository 代表資料存取，必須位於持久化層");

    @ArchTest
    static final ArchRule ARCH_094_dto_suffix = classes()
            .that().resideInAPackage("..dto..")
            .should().haveSimpleNameEndingWith("Request")
            .orShould().haveSimpleNameEndingWith("Response")
            .orShould().haveSimpleNameEndingWith("Dto")
            .because("DTO 的用途（輸入／輸出）應該從名稱就看得出來");

    @ArchTest
    static final ArchRule ARCH_095_entity = classes()
            .that().areAnnotatedWith(jakarta.persistence.Entity.class)
            .should().resideInAnyPackage("..entity..", "..adapter.out.persistence..")
            .andShould().haveSimpleNameEndingWith("Entity")
            .because("Entity 是持久化模型，必須與 Domain Model 明確區分（ADR-005）");

    @ArchTest
    static final ArchRule ARCH_096_usecase = classes()
            .that().resideInAPackage("..application.port.in..")
            .should().haveSimpleNameEndingWith("UseCase")
            .orShould().haveSimpleNameEndingWith("Query")
            .orShould().haveSimpleNameEndingWith("Command")
            .because("輸入埠代表「系統能做什麼」，命名應該是動作而非名詞");

    @ArchTest
    static final ArchRule ARCH_097_port = classes()
            .that().resideInAPackage("..application.port.out..")
            .should().haveSimpleNameEndingWith("Port")
            .because("輸出埠代表「系統需要什麼」，統一以 Port 結尾便於辨識");

    @ArchTest
    static final ArchRule ARCH_098_adapter = classes()
            .that().resideInAPackage("..adapter.out..")
            .and().areNotInterfaces()
            .and().areNotNestedClasses()
            .should().haveSimpleNameEndingWith("Adapter")
            .orShould().haveSimpleNameEndingWith("Entity")
            .orShould().haveSimpleNameEndingWith("Repository")
            .orShould().haveSimpleNameEndingWith("Mapper")
            .because("Adapter 層的類別角色應該從名稱直接辨識");

    @ArchTest
    static final ArchRule ARCH_099_configuration = classes()
            .that().areAnnotatedWith(org.springframework.context.annotation.Configuration.class)
            .should().haveSimpleNameEndingWith("Configuration")
            .orShould().haveSimpleNameEndingWith("Config")
            .because("設定類別應可一眼辨識");

    /** 禁止無意義的命名 */
    @ArchTest
    static final ArchRule ARCH_100_no_meaningless_names = noClasses()
            .should().haveSimpleNameEndingWith("Manager")
            .orShould().haveSimpleNameEndingWith("Helper")
            .orShould().haveSimpleNameEndingWith("Util2")
            .orShould().haveSimpleNameContaining("Impl2")
            .as("[ARCH-100] 禁止使用無意義的類別名稱")
            .because("Manager / Helper 這類名稱無法說明責任，"
                   + "通常代表這個類別承擔了太多不相關的功能");
}

@ArchTest
static final ArchRule ARCH_101_repository_query_methods = methods()
        .that().areDeclaredInClassesThat().haveSimpleNameEndingWith("Repository")
        .and().arePublic()
        .should().haveNameMatching("^(find|save|delete|count|exists|update).*")
        .as("[ARCH-101] Repository 的公開方法必須使用標準動詞開頭")
        .because("統一的方法命名讓資料存取的意圖一目了然");

@ArchTest
static final ArchRule ARCH_102_constants_are_uppercase = fields()
        .that().areStatic().and().areFinal().and().arePublic()
        .should().haveNameMatching("^[A-Z][A-Z0-9_]*$")
        .as("[ARCH-102] public static final 常數必須全大寫")
        .because("常數與一般欄位的視覺區分");

// com.company.order.controller.OrderHelper.java
// 實際上包含了 800 行的業務邏輯與資料庫存取
public class OrderHelper { ... }

// com.company.product.controller.ProductHelper.java
public class ProductHelper { ... }   // 同樣塞滿業務邏輯

class AnnotationArchitectureRules {

    /** @Service 的位置 */
    @ArchTest
    static final ArchRule ARCH_110_service_annotation_location = classes()
            .that().areAnnotatedWith(org.springframework.stereotype.Service.class)
            .should().resideInAnyPackage("..service..", "..application..")
            .as("[ARCH-110] @Service 只能出現在應用層")
            .because("Spring Bean 的位置決定了它在架構中的角色（ADR-002）");

    /** @Repository 的位置 */
    @ArchTest
    static final ArchRule ARCH_111_repository_annotation_location = classes()
            .that().areAnnotatedWith(org.springframework.stereotype.Repository.class)
            .should().resideInAnyPackage("..repository..", "..adapter.out.persistence..")
            .because("同上");

    /** @Entity 的位置 —— 這條在 Clean Architecture 中特別重要 */
    @ArchTest
    static final ArchRule ARCH_112_entity_annotation_location = classes()
            .that().areAnnotatedWith(jakarta.persistence.Entity.class)
            .should().resideInAnyPackage("..entity..", "..adapter.out.persistence..")
            .as("[ARCH-112] @Entity 不得出現在 Domain 層")
            .because("Domain Model 與 Persistence Model 必須分離（ADR-005）");

    /** Domain 不得有任何 Spring 註解 */
    @ArchTest
    static final ArchRule ARCH_113_domain_free_of_spring_annotations = noClasses()
            .that().resideInAPackage("..domain..")
            .should().beMetaAnnotatedWith(org.springframework.stereotype.Component.class)
            .as("[ARCH-113] Domain 類別不得是 Spring Bean")
            .because("Domain 物件應該用 new 建立，而非由容器管理（ADR-003）");

    /** @Transactional 的位置 */
    @ArchTest
    static final ArchRule ARCH_114_transactional_location = classes()
            .that().areAnnotatedWith(
                    org.springframework.transaction.annotation.Transactional.class)
            .should().resideInAnyPackage("..service..", "..application..")
            .as("[ARCH-114] @Transactional 只能標註在應用層")
            .because("交易邊界集中管理；見第 10 章實務案例（ADR-009）");
}

// Spring 的 @Service 定義：
// @Component
// public @interface Service { ... }

classes().that().areAnnotatedWith(Component.class)
// → 只抓「直接標了 @Component」的類別
// → 抓不到標 @Service、@Repository、@Controller 的類別

classes().that().areMetaAnnotatedWith(Component.class)
// → 抓得到所有「間接是 @Component」的類別
// → 包含 @Service、@Repository、@Controller、@RestController、@Configuration

@ArchTest
static final ArchRule ARCH_115_no_readonly_false_in_query = methods()
        .that().areDeclaredInClassesThat().resideInAPackage("..query..")
        .and().areAnnotatedWith(
                org.springframework.transaction.annotation.Transactional.class)
        .should(new ArchCondition<JavaMethod>("使用 readOnly = true") {
            @Override
            public void check(JavaMethod method, ConditionEvents events) {
                var annotation = method.getAnnotationOfType(
                        org.springframework.transaction.annotation.Transactional.class);
                boolean satisfied = annotation.readOnly();
                events.add(new SimpleConditionEvent(method, satisfied,
                        String.format("%s 的 @Transactional 未設定 readOnly = true（%s）",
                                method.getFullName(), method.getSourceCodeLocation())));
            }
        })
        .as("[ARCH-115] 查詢方法的 @Transactional 必須設定 readOnly = true")
        .because("readOnly 讓資料庫可以使用唯讀最佳化，"
               + "也避免查詢方法意外寫入資料（效能 + 安全）");

class SecurityAnnotationRules {

    /** 所有 Controller 方法都必須有明確的授權宣告 */
    @ArchTest
    static final ArchRule ARCH_116_endpoints_have_authorization = methods()
            .that().areDeclaredInClassesThat().resideInAPackage("..controller..")
            .and().areAnnotatedWith(
                    org.springframework.web.bind.annotation.RequestMapping.class)
            .or().areAnnotatedWith(
                    org.springframework.web.bind.annotation.PostMapping.class)
            .should().beAnnotatedWith(
                    org.springframework.security.access.prepost.PreAuthorize.class)
            .as("[ARCH-116] 所有 API 端點必須有 @PreAuthorize")
            .because("預設拒絕原則：沒有明確授權宣告的端點視為設定疏漏（SEC-001）");

    /** 禁止 @PreAuthorize("permitAll()") 出現在非公開套件 */
    @ArchTest
    static final ArchRule ARCH_117_no_permit_all_in_internal = noClasses()
            .that().resideInAPackage("..internal..")
            .should().beAnnotatedWith(
                    org.springframework.security.access.prepost.PreAuthorize.class)
            .as("[ARCH-117] internal 套件不得有對外開放的端點")
            .because("internal 是實作細節，不應有任何對外端點（SEC-002）");

    /** 敏感欄位必須標註遮罩 */
    @ArchTest
    static final ArchRule ARCH_118_sensitive_fields_are_masked = fields()
            .that().haveNameMatching(".*(password|ssn|idNumber|creditCard|cvv).*")
            .should().beAnnotatedWith(com.company.security.Masked.class)
            .as("[ARCH-118] 敏感欄位必須標註 @Masked")
            .because("避免敏感資料進入日誌或 API 回應（SEC-003、個資法遵循）");
}

public record PolicyHolderResponse(
        String name,
        String idNumber,       // 身分證字號
        String phone,
        String address
) {}

[ARCH-118] 敏感欄位必須標註 @Masked was violated (1 times):
  Field <com.company.policy.dto.PolicyHolderResponse.idNumber> is not annotated
  with @Masked in (PolicyHolderResponse.java:4)
  because 避免敏感資料進入日誌或 API 回應（SEC-003、個資法遵循）

class VisibilityRules {

    /** Port 必須 public（它是跨套件契約） */
    @ArchTest
    static final ArchRule ARCH_120_ports_are_public = classes()
            .that().resideInAPackage("..application.port..")
            .should().bePublic()
            .because("Port 需要被不同套件的 Adapter 實作（ADR-007）");

    /** Adapter 實作不應該是 public（它是實作細節） */
    @ArchTest
    static final ArchRule ARCH_121_adapter_impl_not_public = classes()
            .that().resideInAPackage("..adapter.out..")
            .and().haveSimpleNameEndingWith("Adapter")
            .should().notBePublic()
            .as("[ARCH-121] Adapter 實作類別不應為 public")
            .because("Adapter 是實作細節，外界只應透過 Port 介面使用它；"
                   + "Spring 可以注入 package-private 的 Bean");

    /** internal 套件的類別不得為 public */
    @ArchTest
    static final ArchRule ARCH_122_internal_not_public = classes()
            .that().resideInAPackage("..internal..")
            .should().notBePublic()
            .as("[ARCH-122] internal 套件的類別不得為 public")
            .because("internal 代表模組私有實作，public 會讓它變成事實上的公開 API");

    /** 欄位必須 private */
    @ArchTest
    static final ArchRule ARCH_123_fields_are_private = fields()
            .that().areNotStatic()
            .should().bePrivate()
            .as("[ARCH-123] 實例欄位必須為 private")
            .because("封裝是物件導向的基礎；public 欄位讓不變條件無法保證");

    /** 常數必須 static final */
    @ArchTest
    static final ArchRule ARCH_124_public_fields_are_constants = fields()
            .that().arePublic()
            .should().beStatic().andShould().beFinal()
            .as("[ARCH-124] public 欄位必須是 static final 常數")
            .because("可變的 public 欄位讓物件狀態完全失控");

    /** Domain Model 的欄位必須 final（不可變） */
    @ArchTest
    static final ArchRule ARCH_125_domain_value_objects_are_immutable = fields()
            .that().areDeclaredInClassesThat().resideInAPackage("..domain.model..")
            .and().areDeclaredInClassesThat().haveSimpleNameNotEndingWith("Aggregate")
            .should().beFinal()
            .as("[ARCH-125] Domain 值物件的欄位必須為 final")
            .because("不可變的值物件天生執行緒安全，也避免了難以追蹤的狀態變更（ADR-004）");

    /** 工具類別必須 final 且有 private 建構子 */
    @ArchTest
    static final ArchRule ARCH_126_utility_classes_are_final = classes()
            .that().resideInAPackage("..util..")
            .and().haveSimpleNameEndingWith("Utils")
            .should().haveOnlyPrivateConstructors()
            .andShould().beFinal()
            .as("[ARCH-126] 工具類別必須 final 且僅有 private 建構子")
            .because("工具類別不應被實例化或繼承");
}

@ArchTest
static final ArchRule ARCH_127_module_api_boundary = classes()
        .that().resideInAPackage("com.company.order.internal..")
        .should().onlyBeAccessed().byAnyPackage("com.company.order..")
        .as("[ARCH-127] 訂單模組的 internal 只能被模組自己存取")
        .because("模組必須有明確的公開介面，才能在未來獨立演進或拆分（ADR-015）");

package com.company.common.audit.internal;

public class AuditContextHolder {   // ← 不小心寫了 public
    private static final ThreadLocal<AuditContext> HOLDER = new ThreadLocal<>();
    public static AuditContext get() { ... }
    public static void set(AuditContext ctx) { ... }
}

✅ 套件命名完全正確
com.company.order.domain
com.company.order.application
com.company.order.adapter

❌ 依賴方向全錯
domain      → application  （內層依賴外層）
domain      → adapter      （內層依賴最外層）
application → adapter      （依賴具體實作）

class DependencyDirectionRules {

    /** 核心：依賴只能由外向內 */
    @ArchTest
    static final ArchRule ARCH_130_dependency_flows_inward = layeredArchitecture()
            .consideringAllDependencies()
            .layer("UI").definedBy("..adapter.in..")
            .layer("Application").definedBy("..application..")
            .layer("Domain").definedBy("..domain..")
            .layer("Infrastructure").definedBy("..adapter.out..", "..configuration..")

            .whereLayer("UI").mayNotBeAccessedByAnyLayer()
            .whereLayer("Application").mayOnlyBeAccessedByLayers("UI", "Infrastructure")
            .whereLayer("Domain").mayOnlyBeAccessedByLayers("UI", "Application", "Infrastructure")
            .whereLayer("Infrastructure").mayOnlyBeAccessedByLayers("UI")

            .as("[ARCH-130] 依賴方向必須由外向內")
            .because("這是 Clean Architecture 的核心約束（ADR-003）");

    /** 用「主動視角」再確認一次 Domain 的方向 */
    @ArchTest
    static final ArchRule ARCH_131_domain_depends_on_nothing = classes()
            .that().resideInAPackage("..domain..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage("..domain..", "java..")
            .as("[ARCH-131] Domain 不得依賴任何外層")
            .because("Domain 是依賴圖的終點（ADR-003）");

    /** 檢查具體 vs 抽象的依賴方向（DIP 的另一半） */
    @ArchTest
    static final ArchRule ARCH_132_depend_on_abstractions = classes()
            .that().resideInAPackage("..application.service..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage("..application..", "..domain..", "java..")
            .as("[ARCH-132] Application Service 只能依賴抽象與 Domain")
            .because("依賴反轉原則：高層模組不應依賴低層模組，"
                   + "兩者都應依賴抽象（ADR-007）");
}

package com.company.order.architecture;

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 java.util.Map;
import java.util.TreeMap;

/**
 * 依賴方向觀測（不做斷言，只產出報表）。
 * 用途：架構稽核、Legacy 逆向工程、AI Agent 分析輸入。
 */
class DependencyDirectionReport {

    @Test
    void 產出跨層依賴統計() {
        JavaClasses classes = new ClassFileImporter()
                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
                .importPackages("com.company.order");

        Map<String, Integer> crossLayerCount = new TreeMap<>();

        classes.forEach(javaClass -> {
            String fromLayer = layerOf(javaClass.getPackageName());
            javaClass.getDirectDependenciesFromSelf().forEach(dependency -> {
                String toLayer = layerOf(dependency.getTargetClass().getPackageName());
                if (!fromLayer.equals(toLayer) && !toLayer.equals("external")) {
                    crossLayerCount.merge(fromLayer + " → " + toLayer, 1, Integer::sum);
                }
            });
        });

        System.out.println("=== 跨層依賴統計 ===");
        crossLayerCount.forEach((edge, count) ->
                System.out.printf("%-40s %5d%n", edge, count));
    }

    private static String layerOf(String packageName) {
        if (packageName.contains(".domain")) return "domain";
        if (packageName.contains(".application")) return "application";
        if (packageName.contains(".adapter.in")) return "adapter.in";
        if (packageName.contains(".adapter.out")) return "adapter.out";
        if (packageName.contains(".configuration")) return "configuration";
        return "external";
    }
}

=== 跨層依賴統計 ===
adapter.in → application                    48
adapter.in → domain                         31
adapter.out → application                   22
adapter.out → domain                        67
application → domain                       104
configuration → adapter.out                 15
domain → adapter.out                         3    ← ❌ 反向依賴！

package com.company.claim.domain.model;

import com.company.claim.adapter.out.persistence.ClaimEntity;
import com.company.claim.application.service.ClaimValidationService;
import org.springframework.stereotype.Component;
import jakarta.persistence.Entity;

第 1 週  只開 ARCH-131（Domain 白名單）→ 爆出 412 條違規
第 2 週  用 Freeze 凍結 412 條，CI 開始擋新增違規
第 3-8 週 每週處理 40～60 條，優先處理 @Entity 與 Spring 註解
第 9 週  Domain 違規歸零，Freeze 移除
第 10 週 開啟 ARCH-130（完整分層規則）

class SpringFrameworkBoundaryRules {

    @ArchTest
    static final ArchRule ARCH_140_domain_no_spring = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage("org.springframework..")
            .as("[ARCH-140] Domain 不得依賴 Spring Framework")
            .because("Domain 必須能在沒有 Spring Context 的情況下被建立與測試（ADR-003）");

    @ArchTest
    static final ArchRule ARCH_141_domain_no_jpa = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage(
                    "jakarta.persistence..", "javax.persistence..",
                    "org.hibernate..", "org.eclipse.persistence..")
            .as("[ARCH-141] Domain 不得依賴 JPA 或 ORM 實作")
            .because("Domain Model 與 Persistence Model 必須分離（ADR-005）");

    @ArchTest
    static final ArchRule ARCH_142_domain_no_web = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage(
                    "org.springframework.web..", "jakarta.servlet..",
                    "org.springframework.http..")
            .as("[ARCH-142] Domain 不得依賴 Web 技術")
            .because("Domain 不該知道請求從何而來（ADR-003）");

    @ArchTest
    static final ArchRule ARCH_143_domain_no_transaction = noClasses()
            .that().resideInAPackage("..domain..")
            .should().beAnnotatedWith(
                    org.springframework.transaction.annotation.Transactional.class)
            .as("[ARCH-143] Domain 不得使用 @Transactional")
            .because("交易是應用層的關注點；標在 Domain 會產生代理物件，"
                   + "導致 equals/hashCode 行為異常（ADR-009）");

    @ArchTest
    static final ArchRule ARCH_144_logging_via_facade_only = noClasses()
            .should().dependOnClassesThat().resideInAnyPackage(
                    "ch.qos.logback..",            // Logback 實作
                    "org.apache.logging.log4j.core..", // Log4j2 核心實作
                    "java.util.logging..")
            .as("[ARCH-144] 只能使用 SLF4J 門面，不得直接依賴日誌實作")
            .because("直接依賴實作會讓日誌框架無法替換，"
                   + "也可能造成多套日誌系統同時運作（ADR-016）");

    @ArchTest
    static final ArchRule ARCH_145_no_static_logger_leak = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage("org.slf4j..")
            .as("[ARCH-145] Domain 不應記錄日誌")
            .because("Domain 應該拋出有意義的例外，由應用層決定如何記錄；"
                   + "Domain 記錄日誌會讓同一件事在不同層被記錄多次（ADR-017）");
}

// 階段 1：只禁止最嚴重的（Web 與 Transaction）
.resideInAnyPackage("org.springframework.web..",
                    "org.springframework.transaction..")

// 階段 2：加上 Data 相關
.resideInAnyPackage("org.springframework.web..",
                    "org.springframework.transaction..",
                    "org.springframework.data..")

// 階段 3：禁止全部 Spring（最終目標）
.resideInAnyPackage("org.springframework..")

@Transactional   // ← 問題所在
public class Order {
    private final OrderId id;

    @Override
    public boolean equals(Object o) {
        if (!(o instanceof Order other)) return false;
        return id.equals(other.id);
    }
}

[ARCH-143] Domain 不得使用 @Transactional was violated (1 times):
  Class <com.company.order.domain.model.Order> is annotated with @Transactional
  in (Order.java:12)
  because 交易是應用層的關注點；標在 Domain 會產生代理物件，導致 equals/hashCode 行為異常

class JakartaBoundaryRules {

    @ArchTest
    static final ArchRule ARCH_150_servlet_only_in_web = classes()
            .that().dependOnClassesThat().resideInAPackage("jakarta.servlet..")
            .should().resideInAnyPackage("..adapter.in.web..", "..controller..", "..config..")
            .as("[ARCH-150] Servlet API 只能出現在 Web 層與設定")
            .because("Servlet 是 HTTP 傳輸細節，不應洩漏到業務層（ADR-008）");

    @ArchTest
    static final ArchRule ARCH_151_persistence_only_in_adapter = classes()
            .that().dependOnClassesThat().resideInAPackage("jakarta.persistence..")
            .should().resideInAnyPackage("..adapter.out.persistence..", "..entity..", "..config..")
            .as("[ARCH-151] JPA API 只能出現在持久化層")
            .because("JPA 是持久化技術細節（ADR-005）");

    @ArchTest
    static final ArchRule ARCH_152_transaction_not_in_adapter = noClasses()
            .that().resideInAPackage("..adapter..")
            .should().dependOnClassesThat().resideInAPackage("jakarta.transaction..")
            .as("[ARCH-152] Adapter 不得管理交易")
            .because("交易邊界必須由 Application 層統一控制（ADR-009）");
}

// 選項 A：Domain 使用 Bean Validation
public class Order {
    @NotNull
    @Size(min = 1)
    private List<OrderLine> lines;
}

// 選項 B：Domain 自己驗證
public class Order {
    private final List<OrderLine> lines;

    public Order(List<OrderLine> lines) {
        if (lines == null || lines.isEmpty()) {
            throw new OrderStateException("訂單至少需要一個品項");
        }
        this.lines = List.copyOf(lines);
    }
}

@ArchTest
static final ArchRule ARCH_153_validation_not_in_domain = noClasses()
        .that().resideInAPackage("..domain..")
        .should().dependOnClassesThat().resideInAPackage("jakarta.validation..")
        .as("[ARCH-153] Domain 不得使用 Bean Validation")
        .because("Domain 的不變條件必須在建構時強制執行，"
               + "Bean Validation 依賴呼叫者觸發，可能產生無效的 Domain 物件（ADR-010）");

@ArchTest
static final ArchRule ARCH_154_no_javax_ee = noClasses()
        .should().dependOnClassesThat().resideInAnyPackage(
                "javax.persistence..",
                "javax.servlet..",
                "javax.validation..",
                "javax.transaction..",
                "javax.annotation.."      // 注意：javax.annotation.Nullable 等仍在 JDK 中，需依實際情況調整
        )
        .as("[ARCH-154] 禁止使用已遷移至 jakarta 的 javax API")
        .because("Spring Boot 3+ 只支援 jakarta 命名空間，"
               + "混用會造成執行期找不到類別（ADR-019）");

# .github/workflows/common-platform-arch-check.yml（示意，完整版見第 33 章）
name: Common Platform Architecture Check
on:
  schedule:
    - cron: '0 2 * * 1'   # 每週一凌晨掃描所有共用元件
jobs:
  check-all-components:
    strategy:
      matrix:
        component: [common-audit, common-security, common-cache,
                    common-messaging, common-batch, common-web]
    # ...

class PersistenceBoundaryRules {

    @ArchTest
    static final ArchRule ARCH_160_domain_free_of_persistence = classes()
            .that().resideInAPackage("..domain..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage("..domain..", "java..")
            .as("[ARCH-160] Domain 不得依賴任何持久化技術")
            .because("Domain Model 的變更驅動力是業務需求，不是資料庫 schema（ADR-005）");

    @ArchTest
    static final ArchRule ARCH_161_entity_stays_in_persistence = classes()
            .that().areAnnotatedWith(jakarta.persistence.Entity.class)
            .should().resideInAPackage("..adapter.out.persistence..")
            .as("[ARCH-161] JPA Entity 只能存在於持久化 Adapter")
            .because("Entity 是資料庫的投影，不是業務模型（ADR-005）");

    @ArchTest
    static final ArchRule ARCH_162_entity_not_leak_upward = noClasses()
            .that().resideInAnyPackage("..application..", "..adapter.in..")
            .should().dependOnClassesThat()
            .areAnnotatedWith(jakarta.persistence.Entity.class)
            .as("[ARCH-162] Entity 不得洩漏到 Application 或 Web 層")
            .because("Entity 洩漏會導致延遲載入例外、N+1 查詢、"
                   + "以及資料庫欄位意外出現在 API 回應中（ADR-005、SEC-004）");

    @ArchTest
    static final ArchRule ARCH_163_repository_interface_returns_domain = methods()
            .that().areDeclaredInClassesThat().resideInAPackage("..application.port.out..")
            .should().notHaveRawReturnType(
                    com.tngtech.archunit.base.DescribedPredicate.describe(
                            "JPA Entity",
                            javaClass -> javaClass.isAnnotatedWith(
                                    jakarta.persistence.Entity.class)))
            .as("[ARCH-163] 輸出埠不得回傳 JPA Entity")
            .because("Port 是業務契約，回傳 Entity 等於把資料庫模型帶進 Core（ADR-007）");

    @ArchTest
    static final ArchRule ARCH_164_no_raw_sql_outside_persistence = noClasses()
            .that().resideOutsideOfPackage("..adapter.out.persistence..")
            .should().dependOnClassesThat().resideInAnyPackage(
                    "java.sql..", "javax.sql..",
                    "org.springframework.jdbc..")
            .as("[ARCH-164] SQL 與 JDBC 只能出現在持久化 Adapter")
            .because("SQL 散落各層會讓資料存取邏輯無法集中管理與稽核（ADR-005、SEC-005）");

    @ArchTest
    static final ArchRule ARCH_165_mapper_exists = classes()
            .that().resideInAPackage("..adapter.out.persistence..")
            .and().haveSimpleNameEndingWith("Mapper")
            .should().dependOnClassesThat().resideInAPackage("..domain..")
            .as("[ARCH-165] Persistence Mapper 必須認識 Domain")
            .because("Mapper 的職責就是在 Domain 與 Entity 之間轉換（ADR-005）");
}

SQL 散落 40 個類別  →  資安稽核要看 40 個地方，漏掉一個就出事
SQL 集中 1 個套件   →  資安稽核只看 1 個套件，可以做到 100% 覆蓋

@GetMapping("/products/{id}")
public Product getProduct(@PathVariable Long id) {
    return productRepository.findById(id).orElseThrow();
}

// DTO：只暴露該暴露的欄位
public record ProductResponse(
        Long id,
        String name,
        String description,
        long priceInCents,
        int reviewCount        // 只給數量，不給內容
) {}

@GetMapping("/products/{id}")
public ProductResponse getProduct(@PathVariable Long id) {
    Product product = queryProductUseCase.findById(new ProductId(id));
    return productResponseMapper.toResponse(product);
}

class RestApiBoundaryRules {

    @ArchTest
    static final ArchRule ARCH_170_controller_no_entity = noClasses()
            .that().resideInAPackage("..adapter.in.web..")
            .should().dependOnClassesThat()
            .areAnnotatedWith(jakarta.persistence.Entity.class)
            .as("[ARCH-170] Controller 不得使用 JPA Entity")
            .because("Entity 作為 API 模型會洩漏資料庫結構（ADR-005、SEC-004）");

    @ArchTest
    static final ArchRule ARCH_171_controller_returns_dto_or_wrapper = methods()
            .that().areDeclaredInClassesThat().resideInAPackage("..adapter.in.web..")
            .and().arePublic()
            .and().areAnnotatedWith(
                    org.springframework.web.bind.annotation.GetMapping.class)
            .should().haveRawReturnType(
                    com.tngtech.archunit.base.DescribedPredicate.describe(
                            "DTO 或 ResponseEntity",
                            javaClass -> javaClass.getPackageName().contains(".web")
                                      || javaClass.getName().equals(
                                             "org.springframework.http.ResponseEntity")))
            .as("[ARCH-171] Controller 的 GET 方法必須回傳 DTO 或 ResponseEntity")
            .because("回傳型別就是 API 契約，必須由 Web 層明確定義（ADR-005）");

    @ArchTest
    static final ArchRule ARCH_172_dto_are_records_or_immutable = classes()
            .that().resideInAPackage("..adapter.in.web..")
            .and().haveSimpleNameEndingWith("Response")
            .should().beRecords()
            .as("[ARCH-172] Response DTO 必須是 record")
            .because("不可變的回應物件避免了序列化過程中的意外變更（ADR-006）");

    @ArchTest
    static final ArchRule ARCH_173_request_dto_validated = classes()
            .that().resideInAPackage("..adapter.in.web..")
            .and().haveSimpleNameEndingWith("Request")
            .should().beRecords()
            .as("[ARCH-173] Request DTO 必須是 record")
            .because("同上（ADR-006）");

    @ArchTest
    static final ArchRule ARCH_174_no_domain_exception_leak = noMethods()
            .that().areDeclaredInClassesThat().resideInAPackage("..adapter.in.web..")
            .should().declareThrowableOfType(
                    com.company.order.domain.exception.DomainException.class)
            .as("[ARCH-174] Controller 不得向外拋出 Domain 例外")
            .because("Domain 例外必須被轉換為適當的 HTTP 狀態碼，"
                   + "直接拋出會讓內部錯誤訊息洩漏給呼叫端（SEC-006）");

    @ArchTest
    static final ArchRule ARCH_175_controllers_are_stateless = fields()
            .that().areDeclaredInClassesThat().resideInAPackage("..adapter.in.web..")
            .and().areNotStatic()
            .should().beFinal()
            .as("[ARCH-175] Controller 的欄位必須是 final")
            .because("Controller 是單例 Bean，可變欄位會造成執行緒安全問題（ADR-006）");
}

@ArchTest
static final ArchRule ARCH_176_versioned_api_packages = classes()
        .that().resideInAPackage("..adapter.in.web..")
        .and().haveSimpleNameEndingWith("Controller")
        .should().resideInAnyPackage("..web.v1..", "..web.v2..")
        .as("[ARCH-176] Controller 必須位於版本化套件")
        .because("API 版本必須從套件結構就明確可見，"
               + "才能支援多版本並存與逐步淘汰（ADR-014）");

@ArchTest
static final ArchRule ARCH_177_v1_and_v2_are_isolated = noClasses()
        .that().resideInAPackage("..web.v2..")
        .should().dependOnClassesThat().resideInAPackage("..web.v1..")
        .as("[ARCH-177] v2 不得依賴 v1")
        .because("版本之間必須完全獨立，否則無法單獨淘汰舊版（ADR-014）");

@GetMapping("/accounts/{id}")
public AccountResponse get(@PathVariable String id) {
    return mapper.toResponse(queryAccountUseCase.findById(id));
    // AccountNotFoundException 直接往上拋
}

throw new AccountNotFoundException(
    "帳號 " + accountId + " 不存在於 schema=prod_banking, table=account_master, "
    + "查詢條件 status IN ('ACTIVE','SUSPENDED')");

// 1. Domain 例外只帶業務識別碼，不帶技術細節
throw new AccountNotFoundException(accountId);

// 2. 統一的例外轉換
@RestControllerAdvice
public class ApiExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(ApiExceptionHandler.class);

    @ExceptionHandler(AccountNotFoundException.class)
    public ResponseEntity<ErrorResponse> handle(AccountNotFoundException ex) {
        // 技術細節寫入日誌（內部可見）
        log.warn("帳號查詢失敗: {}", ex.getAccountId(), ex);
        // 對外只給通用訊息
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                .body(new ErrorResponse("ACCOUNT_NOT_FOUND", "查無此帳號"));
    }
}

// ❌ 這不是架構規則，是程式碼風格
classes().that().resideInAPackage("..service..")
        .should().haveOnlyFinalFields()
        .andShould().haveSimpleNameEndingWith("ServiceImpl")
        .andShould().haveModifier(JavaModifier.FINAL)
        .andShould().bePublic();

// 規則 A
classes().that().resideInAPackage("..adapter..")
        .should().notBePublic();

// 規則 B（與 A 衝突）
classes().that().areAnnotatedWith(RestController.class)
        .should().bePublic();

// 若 RestController 在 adapter 套件，這兩條永遠有一條會失敗

// ❌ 過度限制：連合理的用法都擋掉
noClasses().should().dependOnClassesThat()
        .resideInAnyPackage("java.util..");   // 連 List、Map 都不能用？

步驟 1  匯出所有規則清單（規則描述 + 檔案位置 + git blame 作者）
步驟 2  統計每條規則過去 12 個月的觸發次數（從 CI 紀錄）
步驟 3  分類：
        A. 有 ADR + 有觸發     → 保留，補上 because
        B. 有 ADR + 無觸發     → 保留（可能是預防性規則）
        C. 無 ADR + 有觸發     → 補寫 ADR（它顯然有價值）
        D. 無 ADR + 無觸發     → 候選退役，找作者確認
步驟 4  D 類規則移到「觀察區」（不阻斷）三個月，無異議則移除
步驟 5  建立規則登錄表，每條規則都有 owner 與 ADR

Rule 'classes that reside in a package '..domain..' should only depend on
classes that reside in any package ['..domain..', 'java..']' was violated (10,847 times):
  ...（接下來是一萬多行）

package com.company.legacy.architecture;

import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import com.tngtech.archunit.core.importer.ImportOption;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.library.freeze.FreezingArchRule.freeze;

@AnalyzeClasses(
        packages = "com.company.legacy",
        importOptions = ImportOption.DoNotIncludeTests.class
)
class LegacyFreezeRules {

    /**
     * 目標架構規則（不是現況！）。
     * 現有的 10,847 條違規已被 Freeze 記錄為 baseline。
     *
     * 遞減目標：2026 Q4 前降至 8,000 條以下（見 ADR-022）
     * Owner：核心系統架構組
     */
    @ArchTest
    static final ArchRule ARCH_200_domain_purity_frozen = freeze(
            classes()
                    .that().resideInAPackage("..domain..")
                    .should().onlyDependOnClassesThat()
                    .resideInAnyPackage("..domain..", "java..")
                    .as("[ARCH-200] Domain 只能依賴自己與 JDK")
                    .because("目標架構：Domain 純淨化（ADR-022）。"
                           + "既有違規已 Freeze，新增違規一律擋下"));
}

# 違規儲存庫路徑（必須放在版控目錄內）
freeze.store.default.path=src/test/resources/archunit_store

# 第一次建立 baseline 時設為 true，建立完成後改回 false
freeze.store.default.allowStoreCreation=false

# 是否允許更新既有儲存庫（預設 true）
# 本機開發保持 true（讓修好的違規能被移除）
# CI 上必須設為 false（見 22.6）
freeze.store.default.allowStoreUpdate=true

# 是否重新凍結全部違規（預設 false）
# ⚠️ 極度危險，見 22.7
freeze.refreeze=false

# 方法 A：暫時修改 properties
# 把 allowStoreCreation 改成 true，跑一次測試，再改回 false

# 方法 B：用系統屬性（推薦，不用改檔案）
mvn test -Dtest=LegacyFreezeRules \
         -Darchunit.freeze.store.default.allowStoreCreation=true

# Gradle
./gradlew test --tests '*LegacyFreezeRules' \
         -Darchunit.freeze.store.default.allowStoreCreation=true

src/test/resources/archunit_store/
├── stored.rules                        ← 規則描述 → 檔名的對應表
└── 4a7f2c8e-...-9b3d.txt              ← 該規則的所有違規（每行一條）

git add src/test/resources/archunit_store/
git commit -m "chore: 建立 Legacy 架構違規 baseline（10,847 條）

依 ADR-022，先凍結既有違規以啟動架構治理機制。
新增違規將由 CI 擋下。
遞減目標：2026 Q4 前降至 8,000 條以下。"

// 故意在 domain 加一個違規
package com.company.legacy.domain;

import org.springframework.stereotype.Component;   // ← 新違規

@Component
public class TestViolation { }

Rule '[ARCH-200] Domain 只能依賴自己與 JDK' was violated (1 times):
  Class <com.company.legacy.domain.TestViolation> is annotated with @Component ...

# CI 專用的 archunit.properties 或用系統屬性覆寫
freeze.store.default.allowStoreUpdate=false

mvn verify -Darchunit.freeze.store.default.allowStoreUpdate=false

package com.company.legacy.architecture;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.EvaluationResult;
import org.junit.jupiter.api.Assertions;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;

class ArchitectureDebtRatchet {

    /**
     * 違規數量上限（棘輪）。
     *
     * 規則：這個數字只能往下調，不能往上調。
     * 每季由架構組檢視並下修。
     *
     * 歷史紀錄：
     *   2026-03-01  10,847（初始 baseline）
     *   2026-06-01   9,520
     *   2026-09-01   8,133  ← 目前
     *   2026-12-01   7,000（目標）
     */
    private static final int MAX_DOMAIN_VIOLATIONS = 8_133;

    @ArchTest
    static void domain_violations_must_not_increase(JavaClasses classes) {
        EvaluationResult result = classes()
                .that().resideInAPackage("..domain..")
                .should().onlyDependOnClassesThat()
                .resideInAnyPackage("..domain..", "java..")
                .evaluate(classes);

        int actual = result.getFailureReport().getDetails().size();

        Assertions.assertTrue(actual <= MAX_DOMAIN_VIOLATIONS, () -> String.format(
                "Domain 架構違規數量增加了！%n"
                + "目前：%d，上限：%d（超出 %d 條）%n"
                + "請修正新增的違規，或依 ADR 流程申請調整上限。",
                actual, MAX_DOMAIN_VIOLATIONS, actual - MAX_DOMAIN_VIOLATIONS));

        // 提示可以下修上限
        if (actual < MAX_DOMAIN_VIOLATIONS - 50) {
            System.out.printf(
                    "💡 違規數已降至 %d，建議將 MAX_DOMAIN_VIOLATIONS 下修至 %d%n",
                    actual, actual);
        }
    }
}

// AI 觀察到 domain 大量依賴 repository，於是產生：
.whereLayer("Repository").mayOnlyBeAccessedByLayers("Service", "Domain")
//                                                            ↑ 把問題合法化了

package com.company.legacy.architecture;

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 java.util.*;
import java.util.stream.Collectors;

/**
 * Legacy 系統架構盤點。
 * 不做任何斷言，只產出報表，作為架構決策與 AI 分析的輸入。
 */
class LegacyArchitectureDiscovery {

    private static final String ROOT = "com.company.legacy";

    private JavaClasses load() {
        return new ClassFileImporter()
                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_JARS)
                .importPackages(ROOT);
    }

    /** 報表 1：套件規模分布 —— 找出「巨型套件」 */
    @Test
    void 報表1_套件規模() {
        Map<String, Long> sizes = load().stream()
                .collect(Collectors.groupingBy(
                        JavaClass::getPackageName, TreeMap::new, Collectors.counting()));

        System.out.println("=== 套件規模（類別數 > 20 的套件） ===");
        sizes.entrySet().stream()
                .filter(e -> e.getValue() > 20)
                .sorted(Map.Entry.<String, Long>comparingByValue().reversed())
                .forEach(e -> System.out.printf("%-60s %5d%n", e.getKey(), e.getValue()));
    }

    /** 報表 2：命名慣例分布 —— 推論架構風格 */
    @Test
    void 報表2_命名慣例() {
        Map<String, Long> suffixes = load().stream()
                .map(JavaClass::getSimpleName)
                .map(LegacyArchitectureDiscovery::suffixOf)
                .collect(Collectors.groupingBy(s -> s, TreeMap::new, Collectors.counting()));

        System.out.println("=== 類別名稱後綴分布 ===");
        suffixes.entrySet().stream()
                .filter(e -> e.getValue() >= 5)
                .sorted(Map.Entry.<String, Long>comparingByValue().reversed())
                .forEach(e -> System.out.printf("%-25s %5d%n", e.getKey(), e.getValue()));
    }

    /** 報表 3：框架滲透度 —— 哪些套件被框架污染 */
    @Test
    void 報表3_框架滲透度() {
        Map<String, Set<String>> leakage = new TreeMap<>();

        load().forEach(javaClass -> {
            String pkg = topLevelModule(javaClass.getPackageName());
            javaClass.getDirectDependenciesFromSelf().forEach(dep -> {
                String target = dep.getTargetClass().getPackageName();
                if (target.startsWith("org.springframework")
                        || target.startsWith("jakarta.persistence")
                        || target.startsWith("jakarta.servlet")) {
                    leakage.computeIfAbsent(pkg, k -> new TreeSet<>())
                           .add(frameworkOf(target));
                }
            });
        });

        System.out.println("=== 框架滲透度（模組 → 使用的框架） ===");
        leakage.forEach((pkg, frameworks) ->
                System.out.printf("%-40s %s%n", pkg, frameworks));
    }

    /** 報表 4：跨模組依賴矩陣 —— 找出模組邊界與循環 */
    @Test
    void 報表4_跨模組依賴矩陣() {
        Map<String, Map<String, Integer>> matrix = new TreeMap<>();

        load().forEach(javaClass -> {
            String from = topLevelModule(javaClass.getPackageName());
            javaClass.getDirectDependenciesFromSelf().forEach(dep -> {
                String targetPkg = dep.getTargetClass().getPackageName();
                if (targetPkg.startsWith(ROOT)) {
                    String to = topLevelModule(targetPkg);
                    if (!from.equals(to)) {
                        matrix.computeIfAbsent(from, k -> new TreeMap<>())
                              .merge(to, 1, Integer::sum);
                    }
                }
            });
        });

        System.out.println("=== 跨模組依賴矩陣 ===");
        matrix.forEach((from, targets) -> targets.forEach((to, count) -> {
            boolean isCycle = matrix.getOrDefault(to, Map.of()).containsKey(from);
            System.out.printf("%-25s → %-25s %5d %s%n",
                    from, to, count, isCycle ? "⚠️ 雙向依賴" : "");
        }));
    }

    /** 報表 5：上帝類別 —— 依賴數異常高的類別 */
    @Test
    void 報表5_上帝類別() {
        System.out.println("=== 依賴數 > 30 的類別（重構優先目標） ===");
        load().stream()
                .map(c -> Map.entry(c.getName(), c.getDirectDependenciesFromSelf().size()))
                .filter(e -> e.getValue() > 30)
                .sorted(Map.Entry.<String, Integer>comparingByValue().reversed())
                .limit(30)
                .forEach(e -> System.out.printf("%-70s %4d%n", e.getKey(), e.getValue()));
    }

    // ===== 工具方法 =====

    private static String suffixOf(String simpleName) {
        for (String s : List.of("Controller", "Service", "ServiceImpl", "Repository",
                "Dao", "DaoImpl", "Entity", "Dto", "Vo", "Bo", "Po",
                "Manager", "Helper", "Util", "Utils", "Handler",
                "Factory", "Builder", "Mapper", "Converter", "Config")) {
            if (simpleName.endsWith(s)) return s;
        }
        return "(其他)";
    }

    private static String topLevelModule(String packageName) {
        if (!packageName.startsWith(ROOT)) return "(external)";
        String rest = packageName.substring(ROOT.length());
        if (rest.isEmpty()) return "(root)";
        String[] parts = rest.substring(1).split("\\.");
        return parts.length > 0 ? parts[0] : "(root)";
    }

    private static String frameworkOf(String packageName) {
        if (packageName.startsWith("org.springframework.web")) return "Spring Web";
        if (packageName.startsWith("org.springframework.data")) return "Spring Data";
        if (packageName.startsWith("org.springframework.transaction")) return "Spring Tx";
        if (packageName.startsWith("org.springframework")) return "Spring Core";
        if (packageName.startsWith("jakarta.persistence")) return "JPA";
        if (packageName.startsWith("jakarta.servlet")) return "Servlet";
        return packageName;
    }
}

# ADR-022：Legacy 核心系統目標架構

## 現況
- 傳統三層架構，Domain 層已被 Spring 與 JPA 大量污染
- 17 個頂層模組中有 9 組雙向依賴
- Domain 純淨性違規 14,203 條

## 決策
採用「漸進式 Clean Architecture」：
1. **不重寫**，在既有結構上逐步收緊
2. 目標架構：Domain 層零框架依賴
3. 分三年達成，每季設定遞減目標

## 不採用的方案
- ❌ 完整重寫：風險過高，業務不可能停 18 個月
- ❌ 維持現狀只擋新增：無法解決存量問題
- ❌ 把現況寫成規則：會讓技術債合法化

## 後果
- 需要建立 Freeze baseline 並進版控
- 需要每季投入約 15 人天處理違規
- 前 6 個月開發速度可能下降 5～10%

## 架構規則
本決策對應 ARCH-200 ~ ARCH-210 共 11 條規則。
Owner：核心系統架構組

@Test
void 違規分類報表() {
    JavaClasses classes = load();

    EvaluationResult result = classes()
            .that().resideInAPackage("..domain..")
            .should().onlyDependOnClassesThat().resideInAnyPackage("..domain..", "java..")
            .evaluate(classes);

    Map<String, Long> byCategory = result.getFailureReport().getDetails().stream()
            .collect(Collectors.groupingBy(
                    LegacyArchitectureDiscovery::categorize,
                    TreeMap::new, Collectors.counting()));

    System.out.println("=== 違規分類（決定修復優先順序） ===");
    byCategory.forEach((cat, count) -> System.out.printf("%-30s %6d%n", cat, count));
}

private static String categorize(String detail) {
    if (detail.contains("org.springframework.stereotype")) return "A-易修：Spring 註解";
    if (detail.contains("org.slf4j"))                      return "A-易修：日誌";
    if (detail.contains("jakarta.persistence"))            return "B-中等：JPA 註解";
    if (detail.contains("calls method"))                   return "C-困難：方法呼叫";
    if (detail.contains("extends"))                        return "D-最難：繼承關係";
    return "E-待分類";
}

=== 違規分類（決定修復優先順序） ===
A-易修：Spring 註解              4,218
A-易修：日誌                     1,903
B-中等：JPA 註解                 3,554
C-困難：方法呼叫                 3,891
D-最難：繼承關係                   512
E-待分類                           125

// AI 產生的規則
@ArchTest
static final ArchRule entity_location = classes()
        .that().areAnnotatedWith(Entity.class)
        .should().resideInAnyPackage("..domain..", "..entity..", "..model..", "..po..");
//                                      ↑ AI 觀察到 domain 裡有 Entity，於是把它列為合法位置

分析這個專案，但請嚴格區分兩件事：

1. 【現況描述】專案目前的實際結構是什麼
2. 【目標架構】專案應該是什麼結構

不要把 (1) 當成 (2)。

產生規則時，必須依據我提供的目標架構（見 ADR-022），
而不是依據你觀察到的現況。

如果現況與目標架構有落差，請：
- 明確列出落差清單與數量
- 產生「描述目標架構」的規則
- 建議用 FreezingArchRule 包裝，讓既有落差被凍結

絕對不要為了讓規則通過而調整規則的寬鬆度。

你的程式碼庫有 19 個 Controller 直接呼叫 Repository
              ↓
AI 讀到這些範例
              ↓
AI 產生的第 20 個 Controller 也會直接呼叫 Repository
              ↓
下一次 AI 讀到 20 個範例，模式更加強化

## 架構規則（AI Agent 必讀，優先於其他指引）

### 本專案的架構

本專案採用 Clean Architecture，套件結構與依賴方向如下：

```text
adapter.in.web     →  application.port.in   →  application.service  →  domain
adapter.out.*      →  application.port.out  （實作關係）
configuration      →  以上全部（僅用於 Bean 組裝）
```

**依賴方向只能由外向內。domain 是最內層，不依賴任何人。**

### 架構規則的位置

所有架構規則定義於：`src/test/java/com/company/order/architecture/`

**在撰寫或修改任何 main 原始碼之前，你必須先閱讀該目錄下的規則檔案。**

### 絕對禁止事項（違反即為嚴重錯誤）

1. ❌ **不得為了讓 ArchUnit 測試通過而修改、刪除或放寬任何架構規則。**
2. ❌ **不得新增 `@ArchIgnore`。**
3. ❌ **不得使用 `freeze.refreeze=true` 或修改 `src/test/resources/archunit_store/` 下的任何檔案。**
4. ❌ **不得新增 `.allowEmptyShould(true)` 來繞過空規則檢查。**
5. ❌ **不得新增 `ignoreDependency(...)` 排除項。**
6. ❌ **不得在 `domain` 套件 import 任何 `org.springframework.*`、`jakarta.persistence.*`、`jakarta.servlet.*`。**
7. ❌ **不得在 `controller` / `adapter.in.web` 套件使用 JPA Entity。**

### 必須執行的事項

1. ✅ 產生或修改 main 原始碼後，**必須執行**：
   ```bash
   mvn test -Dtest=ArchitectureTestSuite
   ```
2. ✅ 若測試失敗，必須先分析違規原因，再修正 **原始碼**（不是規則）。
3. ✅ 若你認為規則本身有問題，**停止動作並向使用者說明**，附上：
   - 違規的完整訊息
   - 你認為規則有問題的理由
   - 你建議的處理方式
   **然後等待使用者決定，不要自行修改。**

### 回報格式

完成工作後，請回報：

```text
架構測試結果：通過 / 失敗
執行指令：<實際執行的指令>
若失敗：
  - 違規規則編號與名稱
  - 違規數量
  - 你的分析（A 程式碼錯誤 / B 規則錯誤 / C 架構已變更 / D Legacy 違規 / E 誤判）
  - 你採取的行動
```

1. 在修改任何 main 原始碼之前，先閱讀 src/test/java/**/architecture/ 下的架構規則。

2. 撰寫程式碼時，主動遵守這些規則，而不是寫完再檢查。

3. 修改完成後，必須執行架構測試，並在回報中附上實際執行的指令與結果。

4. 若發現違規，必須先分析原因，將它歸類為：
   A. 程式碼錯誤（我寫錯了）
   B. 架構規則錯誤（規則本身有問題）
   C. 架構已經改變（規則過期了）
   D. Legacy 既有違規（不是我造成的）
   E. 誤判（規則抓到了不該抓的東西，如產生的程式碼）

5. 絕對不可以刪除、修改、放寬任何 ArchUnit 規則來讓測試通過。
   這包含：改 package pattern、加 ignoreDependency、加 @ArchIgnore、
   加 allowEmptyShould、修改 archunit.properties、修改 archunit_store/。

6. 只有分類為 A 時，才可以自行修正（修正的是原始碼）。
   分類為 B、C、D、E 時，必須停止並向使用者回報。

7. 若確認架構真的需要改變，必須先由人類更新架構決策（ADR），
   才能修改對應的 ArchUnit 規則。順序不可顛倒。

8. 修改架構規則的 PR，必須與程式碼修改分開提交，
   並在 commit message 中引用對應的 ADR 編號。

9. 完成後執行完整測試（架構測試 + 單元測試 + 整合測試），全部通過才算完成。

package com.company.order.architecture;

import org.junit.jupiter.api.Test;

import java.io.IOException;
import java.nio.file.*;
import java.util.List;
import java.util.stream.Stream;

import static org.junit.jupiter.api.Assertions.assertTrue;

/**
 * 反作弊檢查：確保架構規則本身沒有被繞過。
 *
 * 這條測試保護的是「規則」，而不是「程式碼」。
 * 它讓「偷偷放寬規則」這件事在 CI 上變得可見。
 */
class ArchitectureRuleIntegrityTest {

    private static final Path RULES_DIR =
            Paths.get("src/test/java/com/company/order/architecture");

    /** 禁止的繞過手法關鍵字 */
    private static final List<String> FORBIDDEN_PATTERNS = List.of(
            "@ArchIgnore",
            "allowEmptyShould(true)",
            "ignoreDependency("
    );

    @Test
    void 架構規則不得包含未經核可的繞過手法() throws IOException {
        try (Stream<Path> files = Files.walk(RULES_DIR)) {
            List<String> violations = files
                    .filter(p -> p.toString().endsWith(".java"))
                    .flatMap(ArchitectureRuleIntegrityTest::findForbiddenUsages)
                    .toList();

            assertTrue(violations.isEmpty(), () -> String.format(
                    "偵測到未經核可的架構規則繞過手法：%n%s%n%n"
                    + "若確有必要，請於同一行加上 // ADR-xxx 核可註記，"
                    + "並確認該 ADR 已通過架構組審核。",
                    String.join(System.lineSeparator(), violations)));
        }
    }

    private static Stream<String> findForbiddenUsages(Path file) {
        try {
            List<String> lines = Files.readAllLines(file);
            return java.util.stream.IntStream.range(0, lines.size())
                    .filter(i -> FORBIDDEN_PATTERNS.stream()
                            .anyMatch(p -> lines.get(i).contains(p)))
                    // 有 ADR 核可註記的放行
                    .filter(i -> !lines.get(i).matches(".*//\\s*ADR-\\d+.*"))
                    .mapToObj(i -> String.format("  %s:%d  %s",
                            file.getFileName(), i + 1, lines.get(i).trim()));
        } catch (IOException e) {
            throw new UncheckedIOException(e);
        }
    }
}

# .github/CODEOWNERS

# 架構規則的任何變更，必須由架構組審核
/src/test/java/**/architecture/          @company/architecture-team
/src/test/resources/archunit.properties  @company/architecture-team
/src/test/resources/archunit_store/      @company/architecture-team

# AI Agent 指引檔案同樣受保護
/CLAUDE.md                               @company/architecture-team
/.github/copilot-instructions.md         @company/architecture-team
/AGENTS.md                               @company/architecture-team

  @ArchTest
  static final ArchRule domain_purity = classes()
          .that().resideInAPackage("..domain..")
          .should().onlyDependOnClassesThat()
-         .resideInAnyPackage("..domain..", "java..");
+         .resideInAnyPackage("..domain..", "java..", "org.springframework.util..");

  @ArchTest
  static final ArchRule no_cycles = slices()
          .matching("com.company.(*)..")
          .should().beFreeOfCycles()
+         .ignoreDependency(OrderFacade.class, PaymentFacade.class);

+ @ArchIgnore(reason = "重構期間暫時停用")
  @ArchTest
  static final ArchRule controller_not_touch_repository = ...

# 任務：Java 專案架構分析

## 角色
你是一位資深軟體架構師，專長為 Java 企業系統的架構評估與逆向工程。

## 重要限制
**本次任務為「唯讀分析」。你不得修改任何檔案，不得建立任何檔案。**
若你認為需要修改，請在報告中「建議」，但不要執行。

## 分析範圍
專案根目錄：`<填入>`
主要套件：`<填入，例如 com.company.order>`

## 執行步驟

### 步驟 1：結構盤點
掃描 `src/main/java` 下的套件結構，產出：
- 完整的套件樹（深度至第 4 層）
- 每個套件的類別數量
- 類別名稱後綴的分布統計（Controller / Service / Repository / Entity / Dto ...）

### 步驟 2：依賴分析
分析類別之間的依賴關係，產出：
- 跨模組依賴矩陣（哪個模組依賴哪個模組，各幾次）
- 標示出所有「雙向依賴」
- 找出依賴數超過 30 的類別（候選上帝類別）

### 步驟 3：框架滲透度
統計每個套件對以下框架的依賴情況：
- `org.springframework.*`（細分 web / data / transaction / core）
- `jakarta.persistence.*`
- `jakarta.servlet.*`
- 其他第三方函式庫

### 步驟 4：架構風格推論
根據步驟 1～3 的結果，推論此專案採用的架構風格，並說明你的判斷依據。
可能的答案包含但不限於：傳統三層、Clean Architecture、Hexagonal、
Package by Feature、無明顯架構。

**如果證據不足以判斷，請明確說「無法確定」，不要猜測。**

### 步驟 5：問題識別
列出你觀察到的架構問題，每一項包含：
- 問題描述
- 證據（具體的類別名稱與依賴關係）
- 影響（會造成什麼實際損害）
- 嚴重程度（高 / 中 / 低）

## 輸出格式

請依序輸出以下八個區段：

1. **Architecture Map**：套件結構與職責推論
2. **Layer Map**：推論出的分層，以及每層包含哪些套件
3. **Dependency Map**：跨模組依賴矩陣（表格）
4. **Circular Dependency**：所有偵測到的循環依賴
5. **Architecture Violations**：依賴方向錯誤、框架洩漏等問題清單
6. **Candidate ArchUnit Rules**：建議的架構規則（**標示這些是「候選」，需人類確認**）
7. **Risk**：目前架構帶來的風險，以及風險實現時的後果
8. **Refactoring Recommendation**：改善建議，依投資報酬率排序

## 關鍵要求

- **嚴格區分「現況描述」與「建議目標」。** 在每個段落中明確標示哪些是觀察、哪些是建議。
- **不要把觀察到的現況當成「正確的架構」。** 例如若你發現 domain 依賴 repository，
  這是「觀察到的現況」，不是「這個專案的架構規範」。
- **所有結論都要附上證據**（具體的類別名稱、套件名稱、依賴關係）。
- **不確定的地方明確說不確定。**

# 任務：依據 ArchUnit 盤點報表進行架構分析

以下是用 ArchUnit 對專案實際執行後產出的結構化報表。
**這些數據是由工具精確產生的，請以它們為準，不要自行推測或補充數據。**

## 報表 1：套件規模
```text
<貼上報表輸出>
```

## 報表 2：命名慣例分布
```text
<貼上報表輸出>
```

## 報表 3：框架滲透度
```text
<貼上報表輸出>
```

## 報表 4：跨模組依賴矩陣
```text
<貼上報表輸出>
```

## 報表 5：上帝類別
```text
<貼上報表輸出>
```

## 你的任務

依據上述報表，產出架構分析報告（八個區段，格式同前）。

若某個結論需要報表以外的資訊才能確認，請明確指出
「需要進一步檢視 `<具體檔案>` 才能確認」，而不要直接下結論。

# 任務：依據目標架構產生 ArchUnit 規則

## 角色
你是一位熟悉 ArchUnit 的資深 Java 架構師。

## 環境資訊（請嚴格依此撰寫程式碼）
- ArchUnit 版本：**1.5.0**
- JUnit：JUnit 5（使用 `archunit-junit5`）
- Java：25
- Spring Boot：4.x
- 建置工具：Maven

## 目標架構（這是規則的唯一依據）

<在此貼上你的 ADR 內容，例如：>

本專案採用 Clean Architecture：
- `com.company.order.domain`：純業務模型，**只能依賴自己與 `java.*`**
- `com.company.order.application`：Use Case 與 Port 介面，可依賴 domain
- `com.company.order.adapter.in.web`：REST Controller，可依賴 application.port.in 與 domain
- `com.company.order.adapter.out.persistence`：JPA 實作，可依賴 application.port.out 與 domain
- `com.company.order.configuration`：Bean 組裝，可依賴全部

依賴方向：一律由外向內。Adapter 之間不得互相依賴。

## ⚠️ 最重要的要求

**規則必須描述「上述目標架構」，不得描述「專案目前的實際狀況」。**

如果你發現目前的程式碼不符合目標架構：
- **不要**放寬規則去配合現況
- **要**如實產生符合目標架構的規則
- **並**在報告中列出「預期會產生的違規類型與大致數量」
- **並**建議使用 `FreezingArchRule.freeze(...)` 包裝

## 產出要求

產生一個 Java 測試類別，包含 10～20 條規則，涵蓋：
1. 分層依賴方向
2. Domain 純淨性
3. Port 介面規範
4. Adapter 隔離
5. 循環依賴
6. 命名慣例
7. Spring / JPA 框架邊界

## 每條規則必須包含

| 項目 | 要求 |
|------|------|
| 規則編號 | 用 `.as("[ARCH-xxx] 中文規則名稱")` |
| 原因說明 | 用 `.because("...")`，必須說明「違反會造成什麼實際損害」，並引用 ADR 編號 |
| 程式碼 | 使用 ArchUnit 1.5.0 的正確 API |

## 除了程式碼，還要為每條規則提供以下說明表格

| 欄位 | 內容 |
|------|------|
| **Business Intent** | 這條規則保護的業務價值是什麼 |
| **Architecture Intent** | 這條規則保護的架構性質是什麼 |
| **Rule** | 規則的白話描述 |
| **Violation Example** | 一段會違反此規則的 Java 程式碼 |
| **Correct Example** | 修正後的 Java 程式碼 |
| **Why** | 為什麼這樣寫才對 |
| **Level** | 建議的強制等級（1 強制 / 2 強烈建議 / 3 風格） |
| **預期違規數** | 你預估目前程式碼會違反幾次（若無法估計請說明） |

## API 使用限制

- **只能使用 ArchUnit 1.5.0 實際存在的 API。**
- **不確定某個 API 是否存在時，請明說「我不確定 `xxx` 在 1.5.0 是否可用，請查證官方 User Guide」，不要猜測。**
- `layeredArchitecture()` 必須明確指定 `consideringAllDependencies()` 或
  `consideringOnlyDependenciesInLayers()`。
- `DescribedPredicate` 的抽象方法在 1.x 是 `test(T)`，不是舊版的 `apply(T)`。

## 禁止事項

- ❌ 不得使用 `@ArchIgnore`
- ❌ 不得使用 `allowEmptyShould(true)`
- ❌ 不得為了讓規則「看起來會通過」而放寬條件

□ 每條規則都有 .as() 編號與 .because() 原因
□ because 說明了「損害」而非重複規則本身
□ package pattern 的尾端有 `..`（檢查每一條！）
□ layeredArchitecture() 有指定 considering 模式
□ 沒有 @ArchIgnore、allowEmptyShould(true)、ignoreDependency
□ 規則描述的是目標架構，不是現況
□ 所有 API 都能在官方 User Guide 找到（逐一查證，不可信任 AI 的自述）
□ 程式碼可以編譯
□ 實際執行過一次，違規數量與 AI 的預估相符（差距過大代表 AI 沒理解專案）
□ 每條規則都能對應到一條 ADR

// AI 產生（錯誤）
classes().that().resideInAPackage("..domain..")
        .should().notDependOnAnyFrameworks();   // ❌ 這個方法不存在

// AI 產生（錯誤）
layeredArchitecture()
        .layer("Domain").definedBy("..domain..")
        .whereLayer("Domain").shouldNotAccessAnyLayer();   // ❌ 方法名稱錯誤

// 正確：用白名單表達「不依賴任何框架」
classes().that().resideInAPackage("..domain..")
        .should().onlyDependOnClassesThat().resideInAnyPackage("..domain..", "java..");

// 正確：方法名是 mayOnlyAccessLayers
layeredArchitecture()
        .consideringAllDependencies()
        .layer("Domain").definedBy("..domain..")
        .whereLayer("Domain").mayOnlyAccessLayers("Domain");

# 任務：分析並修復 ArchUnit 架構違規

## 角色
你是一位資深 Java 開發者，熟悉本專案的 Clean Architecture 架構。

## 情境
執行架構測試後出現失敗。請依照以下嚴格程序處理。

## 執行程序

### 步驟 1：取得完整失敗訊息
執行：
```bash
mvn test -Dtest=ArchitectureTestSuite
```
把完整的失敗輸出貼在你的回覆中（不要摘要，要完整）。

### 步驟 2：逐條分析

對每一條違規，判定它屬於以下哪一類：

- **A. 程式碼錯誤**：本次變更寫錯了
- **B. 架構規則錯誤**：規則本身有問題（如 package pattern 寫錯）
- **C. 架構已改變**：架構決策變了，規則過期
- **D. Legacy 既有違規**：不是本次變更造成的
- **E. 誤判**：來自產生的程式碼、框架代理或測試輔助類別

判定時請用 `git blame` 或 `git log` 確認該程式碼是否為本次變更所新增。

### 步驟 3：依分類處理

| 分類 | 你可以做的事 |
|------|--------------|
| **A** | ✅ 修正 **原始碼**，然後重跑測試 |
| **B** | 🛑 **停止**。說明你認為規則有什麼問題，等待人類決定 |
| **C** | 🛑 **停止**。說明架構改變的內容，請人類先更新 ADR |
| **D** | 🛑 **停止**。說明這是既有違規，請人類確認 Freeze 策略 |
| **E** | 🛑 **停止**。建議調整 `ImportOption`，但不要自行修改 |

### 步驟 4：修正（僅限分類 A）

修正時必須遵守：
- 修正的是 **原始碼的結構問題**，不是「讓測試通過」
- 不得把類別搬到其他套件來規避規則
- 修正後說明「這個修改為什麼解決了根本問題」

## 🚫 絕對禁止（違反即為嚴重錯誤）

1. 修改任何 `src/test/java/**/architecture/` 下的規則檔案
2. 新增 `@ArchIgnore`
3. 新增 `allowEmptyShould(true)`
4. 新增 `ignoreDependency(...)`
5. 放寬任何 package pattern 或白名單
6. 修改 `src/test/resources/archunit.properties`
7. 修改 `src/test/resources/archunit_store/` 下的任何檔案
8. 使用 `freeze.refreeze=true`
9. **把類別移到其他套件，只為了讓規則不再抓到它**

## 回報格式

```text
## 架構測試結果
執行指令：<實際指令>
失敗規則數：<n>
違規總數：<n>

## 逐條分析
### 違規 1
- 規則：[ARCH-xxx] <規則名稱>
- 位置：<檔案:行號>
- 分類：<A/B/C/D/E>
- 判定理由：<為什麼是這一類，附 git blame 證據>
- 處理：<已修正 / 停止並回報>

### 違規 2
...

## 已執行的修正
<若有，逐項說明修改內容與根本原因>

## 需要人類決定的項目
<若有，逐項說明>

## 最終測試結果
架構測試：通過 / 失敗
單元測試：通過 / 失敗
整合測試：通過 / 失敗
```

## 完成條件

只有當「架構測試 + 單元測試 + 整合測試」全部通過，
且沒有修改任何架構規則時，本次任務才算完成。

# 任務：批次修復機械性架構違規

## 背景
本專案為 Legacy 系統，Domain 層有 4,218 條「使用 Spring 註解」的架構違規。
這些違規的修正模式高度相似，適合批次處理。

## 目標
移除 `com.company.legacy.domain` 套件下所有類別的 Spring 註解依賴。

## 標準修正模式

### 模式 1：`@Component` / `@Service` 標在 Domain 類別上
```java
// 修正前
@Component
public class OrderCalculator { ... }

// 修正後：移除註解，改在 configuration 層註冊 Bean
public class OrderCalculator { ... }
```
同時在 `configuration/DomainBeanConfiguration.java` 加上：
```java
@Bean
public OrderCalculator orderCalculator() {
    return new OrderCalculator();
}
```

### 模式 2：使用 `org.springframework.util.StringUtils`
```java
// 修正前
if (StringUtils.hasText(value)) { ... }

// 修正後：改用 JDK
if (value != null && !value.isBlank()) { ... }
```

### 模式 3：使用 `org.springframework.util.CollectionUtils`
```java
// 修正前
if (CollectionUtils.isEmpty(list)) { ... }

// 修正後
if (list == null || list.isEmpty()) { ... }
```

## 執行要求

1. **一次只處理一個套件**（例如 `domain.order`），完成後回報，等待確認再繼續。
2. **每個檔案修改後，必須確認該檔案的既有單元測試仍然通過。**
3. **若遇到不屬於上述三種模式的違規，停止並回報**，不要自行發明修正方式。
4. **不得修改任何架構規則或 Freeze store。**
5. 修正完成後，執行：
   ```bash
   mvn test
   ```
   並回報：
   - 本次修正的檔案數
   - 剩餘違規數（與修正前對照）
   - 所有測試是否通過

## 特別注意

- `@Component` 移除後，**必須確認沒有其他地方用 `@Autowired` 注入它**，
  否則會在執行期出現 `NoSuchBeanDefinitionException`。
  請用全專案搜尋確認。
- 若某個 Domain 類別確實需要注入其他 Bean，**這代表它可能不該在 Domain 層**。
  這種情況請停止並回報，不要強行修正。

[ARCH-035] Application 不得依賴 Adapter 實作 was violated (1 times):
  Field <com.company.order.application.service.PlaceOrderService.eventPublisher>
  has type <org.springframework.context.ApplicationEventPublisher> in (PlaceOrderService.java:28)

升級 Spring Boot 3 → 4
  ↓
某個 API 被移除，編譯失敗
  ↓
開發者找到「最快能編譯」的替代方案
  ↓
那個方案讓 Application 層開始依賴 Spring 內部 API
  ↓
編譯通過、測試通過、上線
  ↓
架構債 +1，但沒有任何人發現

1.4.2：Domain 純淨性違規 1,203 條
1.5.0：Domain 純淨性違規 1,247 條（+44）

package com.company.order.architecture;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.lang.ArchRule;
import com.tngtech.archunit.lang.EvaluationResult;
import org.junit.jupiter.api.Test;

import java.nio.file.Files;
import java.nio.file.Path;
import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

/**
 * 產出架構基準線報告，供框架升級前後比對。
 * 執行：mvn test -Dtest=ArchitectureBaselineReport
 */
class ArchitectureBaselineReport {

    @Test
    void 產出架構基準線() throws Exception {
        JavaClasses classes = new ClassFileImporter()
                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
                .importPackages("com.company.order");

        Map<String, ArchRule> rules = Map.of(
                "ARCH-031 Domain 純淨性", CleanArchitectureRules.ARCH_031_domain_purity,
                "ARCH-035 Application 不依賴 Adapter",
                        CleanArchitectureRules.ARCH_035_application_not_depend_on_adapter
                // ... 其餘規則
        );

        List<String> lines = rules.entrySet().stream()
                .sorted(Map.Entry.comparingByKey())
                .map(entry -> {
                    EvaluationResult result = entry.getValue().evaluate(classes);
                    int count = result.getFailureReport().getDetails().size();
                    return String.format("%-45s %6d", entry.getKey(), count);
                })
                .collect(Collectors.toList());

        lines.add(0, "架構基準線報告  產生日期：" + LocalDate.now());
        lines.add(1, "ArchUnit 版本：1.5.0   Java：25   Spring Boot：4.0.0");
        lines.add(2, "=".repeat(55));

        Path output = Path.of("target/architecture-baseline.txt");
        Files.write(output, lines);
        lines.forEach(System.out::println);
    }
}

# 升級前
mvn test -Dtest=ArchitectureBaselineReport
cp target/architecture-baseline.txt baseline-before.txt

# 升級後
mvn test -Dtest=ArchitectureBaselineReport
diff baseline-before.txt target/architecture-baseline.txt

class UpgradeRegressionRules {

    /** 升級時最常見的偷懶：用反射繞過編譯錯誤 */
    @ArchTest
    static final ArchRule UPG_001_no_reflection_workaround = noClasses()
            .that().resideOutsideOfPackage("..util.reflect..")
            .should().dependOnClassesThat().resideInAPackage("java.lang.reflect..")
            .as("[UPG-001] 不得使用反射繞過 API 變更")
            .because("升級時用反射「讓它動起來」，會在下次升級時變成更難解的問題");

    /** 禁止使用已棄用的 Spring 內部 API */
    @ArchTest
    static final ArchRule UPG_002_no_spring_internal = noClasses()
            .should().dependOnClassesThat().resideInAnyPackage(
                    "org.springframework..support..",
                    "org.springframework..internal..")
            .as("[UPG-002] 不得依賴 Spring 內部 API")
            .because("internal / support 套件不在 Spring 的相容性承諾範圍內，"
                   + "下次升級一定會壞");

    /** 升級期間新增的 @SuppressWarnings 必須有說明 */
    @ArchTest
    static final ArchRule UPG_003_no_blanket_suppression = noClasses()
            .should().beAnnotatedWith(SuppressWarnings.class)
            .as("[UPG-003] 不得使用 @SuppressWarnings")
            .because("升級期間大量加上 SuppressWarnings，"
                   + "會讓真正的相容性警告被淹沒");
}

$ diff baseline-before.txt baseline-after.txt
< ARCH-031 Domain 純淨性                      1,203
---
> ARCH-031 Domain 純淨性                      1,350    ← +147，立刻可見

# 任務：Spring Boot 3.2 → 4.0 升級（架構安全版）

## 環境
- 目前：Spring Boot 3.2.x / Spring Framework 6.1.x / Java 21
- 目標：Spring Boot 4.0.x / Spring Framework 7.0.x / Java 25
- ArchUnit：1.5.0（已升級完成）

## 架構基準線（升級前）
```text
ARCH-031 Domain 純淨性                      1,203
ARCH-035 Application 不依賴 Adapter            89
ARCH-051 Controller 不得存取 Repository         0
ARCH-080 模組間無循環                            7
（升級後這些數字都不得增加）
```

## 執行原則

### 原則 1：一次一個模組
從 `com.company.order` 開始，完成並通過所有測試後再進行下一個模組。

### 原則 2：區分「機械性替換」與「架構決策」

**你可以自行處理的（機械性）：**
- 套件路徑變更（同一個類別搬到新套件）
- 方法改名（官方文件有明確對照）
- 已棄用 API 有官方指定的直接替代品

**你必須停止並詢問的（架構決策）：**
- API 被完全移除，沒有直接對應的替代品
- 替代方案位於不同的架構層
- 替代方案需要引入新的相依套件
- 需要改變類別的責任或位置

### 原則 3：每完成一個模組，必須執行

```bash
mvn -pl :order-module test
mvn test -Dtest=ArchitectureTestSuite
mvn test -Dtest=ArchitectureBaselineReport
```

並在回報中附上基準線比對結果。

## 🚫 禁止事項

1. ❌ 使用反射繞過 API 變更
2. ❌ 使用 `org.springframework..internal..` 或 `..support..` 套件的類別
3. ❌ 加上 `@SuppressWarnings` 來消除警告
4. ❌ 在升級過程中「順手整理」套件結構或搬移類別
5. ❌ 修改任何 ArchUnit 規則或 Freeze store
6. ❌ 讓任何一條規則的違規數增加

## 回報格式

```text
## 模組：<模組名稱>

### 已完成的變更
| 檔案 | 變更類型 | 說明 |
|------|----------|------|

### 架構基準線比對
| 規則 | 升級前 | 升級後 | 差異 |
|------|--------|--------|------|

### 需要人類決定的項目
<逐項說明：原 API、移除原因、可能的替代方案、各方案的架構影響>

### 測試結果
單元測試：<通過/失敗>
架構測試：<通過/失敗>
```

# 只跑架構測試（開發時最常用，通常幾秒）
mvn test -Dtest=ArchitectureTestSuite

# 跑所有測試（含架構測試）
mvn test

# 完整驗證（含 integration test 與其他 verify 階段的檢查）
mvn verify

# CI 上的完整指令（含 Freeze 唯讀設定）
mvn -B clean verify \
    -Darchunit.freeze.store.default.allowStoreUpdate=false

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <!-- 絕對不可設為 true -->
        <testFailureIgnore>false</testFailureIgnore>
        <!-- 架構測試的失敗訊息很長，確保完整輸出 -->
        <trimStackTrace>false</trimStackTrace>
    </configuration>
</plugin>

架構違規 → 測試失敗 → Build 失敗 → PR 無法合併

<profiles>
    <profile>
        <id>arch-test</id>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-surefire-plugin</artifactId>
                    <configuration>
                        <includes>
                            <include>**/architecture/**/*Test.java</include>
                            <include>**/architecture/**/*Suite.java</include>
                        </includes>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

# 只跑架構測試，幾秒完成
mvn test -Parch-test

parent/
├── pom.xml                      ← dependencyManagement 集中管理 ArchUnit 版本
├── common/
│   └── pom.xml                  ← 模組內規則
├── order-module/
│   └── pom.xml                  ← 模組內規則
├── payment-module/
│   └── pom.xml                  ← 模組內規則
└── architecture-test/           ← ⭐ 專門的架構測試模組
    └── pom.xml                  ← 跨模組規則（循環依賴、模組邊界）

<project>
    <parent>
        <groupId>com.company</groupId>
        <artifactId>parent</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>architecture-test</artifactId>

    <dependencies>
        <!-- 依賴所有需要一起檢查的模組 -->
        <dependency>
            <groupId>com.company</groupId>
            <artifactId>order-module</artifactId>
            <version>${project.version}</version>
        </dependency>
        <dependency>
            <groupId>com.company</groupId>
            <artifactId>payment-module</artifactId>
            <version>${project.version}</version>
        </dependency>

        <dependency>
            <groupId>com.tngtech.archunit</groupId>
            <artifactId>archunit-junit5</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

# 跑所有測試
./gradlew test

# 完整驗證（test + 其他 verification task）
./gradlew check

# 只跑架構測試（需先設定獨立 source set，見第 4 章）
./gradlew archTest

# 只跑特定測試類別
./gradlew test --tests '*ArchitectureTestSuite'

# CI 完整指令
./gradlew clean check \
    -Darchunit.freeze.store.default.allowStoreUpdate=false \
    --no-daemon

// build.gradle.kts

tasks.withType<Test> {
    useJUnitPlatform()

    // 架構測試失敗必須讓 build 失敗（這是預設值，明示意圖）
    ignoreFailures = false

    testLogging {
        events("failed")
        exceptionFormat = org.gradle.api.tasks.testing.logging.TestExceptionFormat.FULL
        showExceptions = true
        showCauses = true
        showStackTraces = true
        // 架構違規訊息很長，確保不被截斷
        maxGranularity = 3
    }
}

// 把架構測試綁進 check task
val archTest = tasks.register<Test>("archTest") {
    description = "執行架構測試（Architecture Quality Gate）"
    group = "verification"
    testClassesDirs = sourceSets["archTest"].output.classesDirs
    classpath = sourceSets["archTest"].runtimeClasspath
    useJUnitPlatform()

    // CI 上強制 Freeze store 唯讀
    systemProperty("archunit.freeze.store.default.allowStoreUpdate",
            providers.environmentVariable("CI").isPresent.not().toString())
}

tasks.named("check") {
    dependsOn(archTest)
}

tasks.named<Test>("archTest") {
    // 明確宣告：這些檔案變更時必須重跑測試
    inputs.files(
        fileTree("src/test/resources") {
            include("archunit.properties")
            include("archunit_store/**")
        }
    ).withPropertyName("archunitConfig")
     .withPathSensitivity(PathSensitivity.RELATIVE)
}

# .github/workflows/architecture-verification.yml
name: Architecture Verification

on:
  pull_request:
    branches: [ main, develop ]
  push:
    branches: [ main ]

# 同一個 PR 的新 commit 會取消舊的執行，節省 runner 資源
concurrency:
  group: arch-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  architecture-test:
    name: 架構測試（Quality Gate）
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          # Freeze 比對與 git blame 需要完整歷史
          fetch-depth: 0

      - name: Set up JDK 25
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '25'
          cache: 'maven'

      - name: 顯示環境資訊
        run: |
          java -version
          mvn -version
          echo "ArchUnit 版本："
          mvn help:evaluate -Dexpression=archunit.version -q -DforceStdout

      # ⭐ 關鍵步驟：先跑架構測試（快速失敗）
      - name: 執行架構測試
        id: arch
        run: |
          mvn -B clean test-compile
          mvn -B surefire:test -Dtest='ArchitectureTestSuite' \
              -Darchunit.freeze.store.default.allowStoreUpdate=false

      # 無論成功失敗都上傳報告
      - name: 上傳架構測試報告
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: architecture-test-report
          path: |
            target/surefire-reports/
            target/architecture-baseline.txt
          retention-days: 30

      # 失敗時把違規摘要寫進 PR 的 Job Summary
      - name: 產生違規摘要
        if: failure()
        run: |
          {
            echo "## ❌ 架構驗證失敗"
            echo ""
            echo "### 違規清單"
            echo '```text'
            grep -A 40 "Architecture Violation" target/surefire-reports/*.txt \
              | head -200 || echo "（無法讀取詳細訊息，請下載完整報告）"
            echo '```'
            echo ""
            echo "### 處理指引"
            echo "1. **請勿修改架構規則讓測試通過**"
            echo "2. 請參考 [架構教學手冊](.github/教學/AI開發/ArchUnit%20企業級軟體架構測試與%20AI%20Agent%20開發教學手冊.md)"
            echo "3. 若你認為規則本身有問題，請聯繫 @company/architecture-team"
          } >> "$GITHUB_STEP_SUMMARY"

  # 架構測試通過後才跑其他測試（節省資源）
  unit-and-integration-test:
    name: 單元與整合測試
    needs: architecture-test
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '25'
          cache: 'maven'
      - name: 完整驗證
        run: |
          mvn -B clean verify \
              -Darchunit.freeze.store.default.allowStoreUpdate=false
      - if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-reports
          path: target/surefire-reports/

  # 保護架構規則不被偷偷修改
  architecture-rule-guard:
    name: 架構規則變更守衛
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 檢查是否修改了架構規則
        run: |
          CHANGED=$(git diff --name-only \
            origin/${{ github.base_ref }}...HEAD \
            -- 'src/test/java/**/architecture/**' \
               'src/test/resources/archunit.properties' \
               'src/test/resources/archunit_store/**' \
               'CLAUDE.md' '.github/copilot-instructions.md' 'AGENTS.md')

          if [ -n "$CHANGED" ]; then
            {
              echo "## ⚠️ 本 PR 修改了架構規則或 AI 指引"
              echo ""
              echo "### 變更的檔案"
              echo '```text'
              echo "$CHANGED"
              echo '```'
              echo ""
              echo "### 審核要求"
              echo "- [ ] 本變更有對應的 ADR 編號"
              echo "- [ ] 已取得 Architecture Owner 核可"
              echo "- [ ] 變更理由不是「為了讓測試通過」"
              echo ""
              echo "**本 PR 需要 @company/architecture-team 審核。**"
            } >> "$GITHUB_STEP_SUMMARY"

            # 確認 commit message 或 PR 標題含 ADR 編號
            if ! git log --format=%B origin/${{ github.base_ref }}...HEAD \
                 | grep -qE 'ADR-[0-9]+'; then
              echo "::error::修改架構規則但未引用 ADR 編號。請在 commit message 中註明 ADR-xxx。"
              exit 1
            fi
          else
            echo "✅ 本 PR 未修改架構規則" >> "$GITHUB_STEP_SUMMARY"
          fi

Settings → Branches → Branch protection rules → main

☑ Require a pull request before merging
☑ Require status checks to pass before merging
   必選的檢查：
   ☑ 架構測試（Quality Gate）
   ☑ 架構規則變更守衛
   ☑ 單元與整合測試
☑ Require review from Code Owners
☑ Do not allow bypassing the above settings

# .gitlab-ci.yml

stages:
  - build
  - architecture
  - test
  - quality
  - deploy

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository -Xmx2g"
  MAVEN_CLI_OPTS: "-B -ntp --errors --fail-at-end"
  # CI 上 Freeze store 一律唯讀
  ARCHUNIT_OPTS: "-Darchunit.freeze.store.default.allowStoreUpdate=false"

cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - .m2/repository

default:
  image: maven:3.9-eclipse-temurin-25
  interruptible: true

# ===== 階段 1：編譯 =====
build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS clean test-compile
  artifacts:
    paths:
      - target/classes/
      - target/test-classes/
    expire_in: 1 hour

# ===== 階段 2：架構驗證（Quality Gate）=====
architecture-test:
  stage: architecture
  needs: ["build"]
  script:
    - echo "=== 環境資訊 ==="
    - java -version
    - mvn help:evaluate -Dexpression=archunit.version -q -DforceStdout
    - echo ""
    - echo "=== 執行架構測試 ==="
    - mvn $MAVEN_CLI_OPTS $ARCHUNIT_OPTS surefire:test -Dtest='ArchitectureTestSuite'
  artifacts:
    when: always
    reports:
      junit:
        - target/surefire-reports/TEST-*.xml
    paths:
      - target/surefire-reports/
    expire_in: 30 days
  # 架構測試失敗必須阻斷 pipeline
  allow_failure: false

# 架構基準線報告（僅在 main 分支產出，供長期追蹤）
architecture-baseline:
  stage: architecture
  needs: ["build"]
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  script:
    - mvn $MAVEN_CLI_OPTS surefire:test -Dtest='ArchitectureBaselineReport'
  artifacts:
    paths:
      - target/architecture-baseline.txt
    expire_in: 365 days

# ===== 階段 3：測試 =====
unit-test:
  stage: test
  needs: ["architecture-test"]
  script:
    - mvn $MAVEN_CLI_OPTS $ARCHUNIT_OPTS verify
  artifacts:
    when: always
    reports:
      junit:
        - target/surefire-reports/TEST-*.xml
        - target/failsafe-reports/TEST-*.xml

# ===== 階段 4：架構規則變更守衛 =====
architecture-rule-guard:
  stage: quality
  needs: []
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - |
      git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
      CHANGED=$(git diff --name-only \
        "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD" \
        -- 'src/test/java/**/architecture/**' \
           'src/test/resources/archunit.properties' \
           'src/test/resources/archunit_store/**')

      if [ -n "$CHANGED" ]; then
        echo "⚠️ 本 MR 修改了架構規則："
        echo "$CHANGED"
        echo ""
        if ! git log --format=%B \
             "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD" \
             | grep -qE 'ADR-[0-9]+'; then
          echo "❌ 錯誤：修改架構規則但未引用 ADR 編號"
          echo "請在 commit message 中註明對應的 ADR-xxx"
          exit 1
        fi
        echo "✅ 已引用 ADR，但仍需 Architecture Owner 審核"
      else
        echo "✅ 本 MR 未修改架構規則"
      fi

# CODEOWNERS

[Architecture] @architecture-team
src/test/java/**/architecture/**
src/test/resources/archunit.properties
src/test/resources/archunit_store/**
CLAUDE.md
AGENTS.md

src/
├── main/java/com/company/order/
│   ├── domain/
│   ├── application/
│   ├── adapter/
│   └── configuration/
│
└── test/
    ├── java/com/company/order/
    │   ├── domain/                          ← 領域單元測試（不啟動 Spring）
    │   ├── application/                     ← Use Case 測試
    │   ├── adapter/                         ← Adapter 測試
    │   │
    │   └── architecture/                    ⭐ 架構測試
    │       ├── ProductionCodeAnalysis.java  ← 統一匯入設定（meta-annotation）
    │       ├── ExcludeGeneratedClasses.java ← 自訂 ImportOption
    │       ├── ArchitectureTestSuite.java   ← 總入口（唯一的 @AnalyzeClasses）
    │       ├── ArchitectureRuleIntegrityTest.java  ← 反作弊檢查（第 25 章）
    │       ├── ArchitectureBaselineReport.java     ← 基準線報告（第 29 章）
    │       ├── LegacyArchitectureDiscovery.java    ← 盤點報表（第 23 章）
    │       │
    │       ├── rules/
    │       │   ├── LayerArchitectureRules.java
    │       │   ├── DependencyArchitectureRules.java
    │       │   ├── NamingArchitectureRules.java
    │       │   ├── AnnotationArchitectureRules.java
    │       │   ├── CycleArchitectureRules.java
    │       │   ├── DomainPurityRules.java
    │       │   ├── VisibilityRules.java
    │       │   ├── FrameworkBoundaryRules.java
    │       │   ├── PersistenceBoundaryRules.java
    │       │   ├── RestApiBoundaryRules.java
    │       │   └── SecurityBoundaryRules.java
    │       │
    │       └── freeze/
    │           └── LegacyFreezeRules.java
    │
    └── resources/
        ├── archunit.properties
        └── archunit_store/                  ← ⚠️ 必須進版控
            ├── stored.rules
            └── <uuid>.txt

project/
├── pom.xml                              ← dependencyManagement
│
├── order-module/
│   └── src/test/java/.../architecture/
│       └── OrderModuleArchitectureTest.java   ← 只檢查本模組內部
│
├── payment-module/
│   └── src/test/java/.../architecture/
│       └── PaymentModuleArchitectureTest.java
│
└── architecture-test/                   ⭐ 跨模組架構測試模組
    ├── pom.xml                          ← 依賴所有業務模組
    └── src/test/
        ├── java/com/company/architecture/
        │   ├── CrossModuleCycleTest.java       ← 模組間循環
        │   ├── ModuleBoundaryTest.java         ← 模組邊界
        │   └── EnterpriseStandardTest.java     ← 公司共通規則（第 45 章）
        └── resources/
            ├── archunit.properties
            └── archunit_store/

/**
 * 分層架構規則集。
 *
 * <p>對應決策：ADR-003（Clean Architecture）、ADR-007（依賴反轉）
 * <p>Owner：架構組（architecture-team@company.com）
 * <p>規則編號範圍：ARCH-030 ~ ARCH-049
 * <p>上次檢視：2026-09-01
 *
 * <p><b>修改本檔案前請注意：</b>任何規則的新增、修改或刪除，
 * 都必須有對應的 ADR，並經 Architecture Owner 核可。
 * 詳見《ArchUnit 企業級教學手冊》第 36 章。
 */
class LayerArchitectureRules {
    // ...
}