PRD（做什麼） → SDD（如何設計） → TSD（如何實作）
     ↑                ↑                ↑
   產品經理          架構師           開發工程師

[使用 UML 類別圖或 Mermaid 呈現]

範例：

┌─────────────────────────────────────┐
│         <<interface>>               │
│         UserService                 │
├─────────────────────────────────────┤
│ + findById(id: Long): UserDTO       │
│ + create(req: CreateUserReq): UserDTO│
│ + update(id: Long, req): UserDTO    │
│ + delete(id: Long): void            │
│ + search(criteria): Page<UserDTO>   │
└──────────────┬──────────────────────┘
               │ implements
┌──────────────▼──────────────────────┐
│         UserServiceImpl             │
├─────────────────────────────────────┤
│ - userRepository: UserRepository    │
│ - passwordEncoder: PasswordEncoder  │
│ - eventPublisher: EventPublisher    │
├─────────────────────────────────────┤
│ + findById(id: Long): UserDTO       │
│ + create(req: CreateUserReq): UserDTO│
│ - validateEmail(email: String): void│
│ - publishEvent(event: DomainEvent)  │
└─────────────────────────────────────┘

/**
 * @param userRepository 使用者資料存取物件
 * @param passwordEncoder 密碼編碼器
 * @param eventPublisher 領域事件發布器
 */
public UserServiceImpl(
    UserRepository userRepository,
    PasswordEncoder passwordEncoder,
    ApplicationEventPublisher eventPublisher
)

1. 驗證請求參數（Bean Validation）
2. 檢查 Email 是否已存在
   └─ 已存在 → 拋出 DuplicateEmailException
3. 檢查 Username 是否已存在
   └─ 已存在 → 拋出 DuplicateUsernameException
4. 密碼雜湊處理（bcrypt, cost=12）
5. 建立 User Entity 並設定預設值
   ├─ status = "PENDING_VERIFICATION"
   ├─ createdAt = now()
   └─ createdBy = currentUser
6. 儲存至資料庫
7. 發布 UserCreatedEvent 領域事件
8. 轉換為 UserDTO 並回傳

@Transactional
public UserDTO create(CreateUserRequest request) {
    // Step 1: 參數驗證（由框架 @Valid 處理）

    // Step 2-3: 唯一性檢查
    if (userRepository.existsByEmail(request.getEmail())) {
        throw new DuplicateEmailException(request.getEmail());
    }
    if (userRepository.existsByUsername(request.getUsername())) {
        throw new DuplicateUsernameException(request.getUsername());
    }

    // Step 4: 密碼雜湊
    String encodedPassword = passwordEncoder.encode(request.getPassword());

    // Step 5: 建立實體
    User user = User.builder()
        .username(request.getUsername())
        .email(request.getEmail())
        .passwordHash(encodedPassword)
        .displayName(request.getDisplayName())
        .status(UserStatus.PENDING_VERIFICATION)
        .createdAt(Instant.now())
        .createdBy(SecurityUtils.getCurrentUser())
        .build();

    // Step 6: 儲存
    User saved = userRepository.save(user);

    // Step 7: 發布事件
    eventPublisher.publishEvent(new UserCreatedEvent(saved));

    // Step 8: 轉換回傳
    return UserMapper.INSTANCE.toDTO(saved);
}

function validatePasswordStrength(password, userContext):
    issues = []
    score = 0

    // 必要規則
    if length(password) < 8:
        issues.add("密碼長度不足 8 碼")
        return { valid: false, score: 0, issues }

    if isCommonPassword(password):
        issues.add("密碼過於常見")
        return { valid: false, score: 0, issues }

    if containsUserInfo(password, userContext):
        issues.add("密碼不可包含個人資訊")
        return { valid: false, score: 0, issues }

    // 評分規則
    if length(password) >= 12: score += 1
    if hasUpperCase(password): score += 1 else issues.add("建議包含大寫字母")
    if hasLowerCase(password): score += 1 else issues.add("建議包含小寫字母")
    if hasDigit(password): score += 1 else issues.add("建議包含數字")
    if hasSpecialChar(password): score += 1 else issues.add("建議包含特殊字元")

    return { valid: score >= 3, score, issues }

@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true, length = 50)
    private String username;

    @Column(nullable = false, unique = true, length = 254)
    private String email;

    @Column(name = "password_hash", nullable = false, length = 256)
    private String passwordHash;

    @Column(name = "display_name", length = 100)
    private String displayName;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false, length = 30)
    private UserStatus status;

    @Column(name = "last_login_at")
    private Instant lastLoginAt;

    @Column(name = "failed_login_count", nullable = false)
    private int failedLoginCount = 0;

    @Column(name = "locked_until")
    private Instant lockedUntil;

    // 稽核欄位
    @Column(name = "created_at", nullable = false, updatable = false)
    private Instant createdAt;

    @Column(name = "created_by", nullable = false, updatable = false, length = 50)
    private String createdBy;

    @Column(name = "updated_at")
    private Instant updatedAt;

    @Column(name = "updated_by", length = 50)
    private String updatedBy;
}

public enum UserStatus {
    PENDING_VERIFICATION,  // 待驗證
    ACTIVE,               // 啟用
    SUSPENDED,            // 停權
    LOCKED,               // 鎖定（登入失敗過多）
    DEACTIVATED           // 停用
}

public record CreateUserRequest(
    @NotBlank @Size(min = 3, max = 50)
    @Pattern(regexp = "^[a-zA-Z0-9_]+$")
    String username,

    @NotBlank @Email @Size(max = 254)
    String email,

    @NotBlank @Size(min = 8, max = 128)
    String password,

    @Size(max = 100)
    String displayName
) {}

public record UserDTO(
    Long id,
    String username,
    String email,
    String displayName,
    String status,
    Instant lastLoginAt,
    Instant createdAt
) {}

RuntimeException
└── BaseBusinessException (abstract)
    ├── ResourceNotFoundException
    │   ├── UserNotFoundException
    │   └── OrderNotFoundException
    ├── DuplicateResourceException
    │   ├── DuplicateEmailException
    │   └── DuplicateUsernameException
    ├── ValidationException
    │   └── PasswordPolicyException
    ├── AuthenticationException
    │   ├── InvalidCredentialsException
    │   └── AccountLockedException
    └── ExternalServiceException
        ├── SSOServiceException
        └── NotificationServiceException

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ApiResponse> handleNotFound(ResourceNotFoundException ex) {
        // HTTP 404, 錯誤碼依例外類型
    }

    @ExceptionHandler(DuplicateResourceException.class)
    public ResponseEntity<ApiResponse> handleDuplicate(DuplicateResourceException ex) {
        // HTTP 409, 錯誤碼依例外類型
    }

    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<ApiResponse> handleValidation(ConstraintViolationException ex) {
        // HTTP 400, 錯誤碼 E3001, 逐欄位列出驗證錯誤
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiResponse> handleUnexpected(Exception ex) {
        // HTTP 500, 錯誤碼 E9001, 記錄完整堆疊
        // 不向客戶端暴露內部細節
    }
}

{
  "success": false,
  "code": "E2001",
  "message": "使用者可理解的錯誤訊息",
  "errors": [
    {
      "field": "email",
      "code": "DUPLICATE",
      "message": "此 Email 已被使用"
    }
  ],
  "timestamp": "2026-05-19T10:30:00Z",
  "traceId": "abc123-def456",
  "path": "/api/v1/users"
}

                    ┌──────────┐
                   │  E2E Test │     ← 少量，關鍵流程
                  │  (Cypress)  │
                 ├──────────────┤
                │Integration Test│   ← 中量，API + DB
               │  (TestContainers) │
              ├────────────────────┤
             │     Unit Test        │ ← 大量，業務邏輯
            │   (JUnit 5 + Mockito)  │
           └──────────────────────────┘
                  測試金字塔

@ExtendWith(MockitoExtension.class)
class UserServiceImplTest {

    @Mock
    private UserRepository userRepository;

    @Mock
    private PasswordEncoder passwordEncoder;

    @Mock
    private ApplicationEventPublisher eventPublisher;

    @InjectMocks
    private UserServiceImpl userService;

    @Test
    @DisplayName("UT-001: 正常建立使用者 - 應回傳 UserDTO")
    void test_create_success() {
        // Given
        var request = new CreateUserRequest(
            "john_doe", "john@example.com", "P@ssw0rd123", "John"
        );
        when(userRepository.existsByEmail(anyString())).thenReturn(false);
        when(userRepository.existsByUsername(anyString())).thenReturn(false);
        when(passwordEncoder.encode(anyString())).thenReturn("hashed");
        when(userRepository.save(any(User.class))).thenAnswer(invocation -> {
            User user = invocation.getArgument(0);
            user.setId(1L);
            return user;
        });

        // When
        UserDTO result = userService.create(request);

        // Then
        assertNotNull(result);
        assertEquals("john_doe", result.username());
        assertEquals("PENDING_VERIFICATION", result.status());
        verify(eventPublisher).publishEvent(any(UserCreatedEvent.class));
    }

    @Test
    @DisplayName("UT-002: Email 已存在 - 應拋出 DuplicateEmailException")
    void test_create_duplicateEmail() {
        // Given
        var request = new CreateUserRequest(
            "john_doe", "existing@example.com", "P@ssw0rd123", "John"
        );
        when(userRepository.existsByEmail("existing@example.com")).thenReturn(true);

        // When & Then
        assertThrows(DuplicateEmailException.class, () -> userService.create(request));
        verify(userRepository, never()).save(any());
    }
}

# 本地建置
./gradlew clean build

# 執行測試
./gradlew test

# 產生測試覆蓋率報告
./gradlew jacocoTestReport

# 建立 Docker Image
docker build -t project-name:latest .

# 靜態分析
./gradlew sonar

# 多階段建置
FROM eclipse-temurin:21-jdk-alpine AS builder
WORKDIR /app
COPY . .
RUN ./gradlew clean build -x test

FROM eclipse-temurin:21-jre-alpine
RUN addgroup -S app && adduser -S app -G app
USER app
WORKDIR /app
COPY --from=builder /app/build/libs/*.jar app.jar
EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=3s \
  CMD wget -q --spider http://localhost:8080/actuator/health || exit 1
ENTRYPOINT ["java", "-jar", "app.jar"]