[volume-3] 도메인 & 객체 설계 및 아키텍처, 패키지 구성 - 김평숙

.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(./gradlew test:*)",
+      "Bash(./gradlew :apps:commerce-api:test:*)",
+      "Bash(./gradlew :apps:commerce-api:compileJava:*)"
+    ]
+  }
+}

.claude/skills/requirements-analysis/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: requirements-analysis 
+description:
+  제공된 요구사항을 분석하고, 개발자와의 질문/대답을 통해 애매한 요구사항을 명확히 하여 정리합니다.
+  모든 정리가 끝나면, 시퀀스 다이어그램, 클래스 다이어그램, ERD 등을 Mermaid 문법으로 작성한다.
+  요구사항이 제공되었을 때, 코드를 작성하기 전 이를 명확히 하는 데에 사용합니다.
+---
+요구사항을 분석할 때 반드시 다음 흐름을 따른다.
+### 1️⃣ 요구사항을 그대로 믿지 말고, 문제 상황으로 다시 설명한다.
+- 요구사항 문장을 정리하는 데서 끝내지 않는다.
+- "무엇을 만들까?"가 아니라 "지금 어떤 문제가 있고, 그걸 왜 해결하려는가?" 로 재해석한다.
+- 다음 관점을 분리해서 정리한다:
+    - 사용자 관점
+    - 비즈니스 관점
+    - 시스템 관점
+> 예시
+> "주문 실패 시 결제를 취소한다" → "결제 성공/실패와 주문 상태가 어긋나지 않도록 일관성을 유지하려는 문제"
+
+### 2️⃣ 애매한 요구사항을 숨기지 말고 드러낸다
+- 추측하거나 알아서 결정하지 않는다.
+- 요구사항에서 결정되지 않은 부분을 명시적으로 나열한다.
+  **다음 유형의 질문을 반드시 포함한다:**
+- 정책 질문: 기준 시점, 성공/실패 조건, 예외 처리 규칙
+- 경계 질문: 어디까지가 한 책임인가, 어디서 분리되는가
+- 확장 질문: 나중에 바뀔 가능성이 있는가
+
+### 3️⃣ 요구사항 명확화를 위한 질문을 개발자 답변이 쉬운 형태로 제시한다
+- 질문은 우선순위를 가진다 (중요한 것부터).
+- 선택지가 있는 경우, 옵션 + 영향도를 함께 제시한다.
+> 형식 예시:
+- 선택지 A: 하나의 트랜잭션으로 처리 → 구현 단순, 확장성 낮음
+- 선택지 B: 단계별 분리 → 구조 복잡, 확장/보상 처리 유리
+
+### 4️⃣ 합의된 내용을 바탕으로 개념 모델부터 잡는다
+- 바로 코드나 기술 얘기로 들어가지 않는다.
+- 먼저 다음을 정의한다:
+    - 액터 (사용자, 외부 시스템)
+    - 핵심 도메인
+    - 보조/외부 시스템
+- 이 단계는 “구현”이 아니라 설계 사고 정렬이 목적이다.
+
+### 5️⃣ 다이어그램은 항상 이유 → 다이어그램 → 해석 순서로 제시한다
+**다이어그램을 그리기 전에 반드시 설명한다**
+- 왜 이 다이어그램이 필요한지
+- 이 다이어그램으로 무엇을 검증하려는지
+
+**다이어그램은 Mermaid 문법으로 작성한다**
+사용 기준:
+- **시퀀스 다이어그램**
+    - 책임 분리
+    - 호출 순서
+    - 트랜잭션 경계 확인
+- **클래스 다이어그램**
+    - 도메인 책임
+    - 의존 방향
+    - 응집도 확인
+- **ERD**
+    - 영속성 구조
+    - 관계의 주인
+    - 정규화 여부
+
+### 6️⃣ 다이어그램을 던지고 끝내지 말고 읽는 법을 짚어준다
+- "이 구조에서 특히 봐야 할 포인트"를 2~3줄로 설명한다.
+- 설계 의도가 드러나도록 해석을 붙인다.
+
+### 7️⃣ 설계의 잠재 리스크를 반드시 언급한다
+- 현재 설계가 가질 수 있는 위험을 숨기지 않는다.
+    - 트랜잭션 비대화
+    - 도메인 간 결합도 증가
+    - 정책 변경 시 영향 범위 확대
+- 해결책은 정답처럼 말하지 않고 선택지로 제시한다.
+
+### 톤 & 스타일 가이드
+- 강의처럼 설명하지 말고 설계 리뷰 톤을 유지한다
+- 정답이라고 제시하기보다, 다른 선택지가 있다면 이를 제공하도록 한다.
+- 코드보다 의도, 책임, 경계를 더 중요하게 다룬다
+- 구현 전에 생각해야 할 것을 끌어내는 데 집중한다

CLAUDE.md

@@ -0,0 +1,166 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Tech Stack & Versions
+
+| Category | Technology | Version |
+|----------|------------|---------|
+| Language | Java | 21 |
+| Framework | Spring Boot | 3.4.4 |
+| Dependency Management | Spring Dependency Management | 1.1.7 |
+| Cloud | Spring Cloud | 2024.0.1 |
+| Build Tool | Gradle (Kotlin DSL) | 8.13+ |
+| API Documentation | SpringDoc OpenAPI | 2.7.0 |
+| ORM | Spring Data JPA + QueryDSL | (managed by Spring Boot) |
+| Database | MySQL | 8.0 |
+| Cache | Redis (Master-Replica) | - |
+| Messaging | Kafka | 3.5.1 |
+| Monitoring | Micrometer + Prometheus | (managed by Spring Boot) |
+| Logging | Logback + Slack Appender | 1.6.1 |
+| Testing | JUnit 5, Mockito 5.14.0, SpringMockk 4.0.2, Instancio 5.0.2 | - |
+| Containers | TestContainers | (managed by Spring Boot) |
+
+## Build & Run Commands
+
+```bash
+# Build all modules
+./gradlew build
+
+# Run tests (profile: test, timezone: Asia/Seoul)
+./gradlew test
+
+# Run specific app
+./gradlew :apps:commerce-api:bootRun
+./gradlew :apps:commerce-batch:bootRun --args='--job.name=jobName'
+./gradlew :apps:commerce-streamer:bootRun
+
+# Build specific module
+./gradlew :apps:commerce-api:build
+
+# Run single test class
+./gradlew test --tests "com.loopers.ExampleServiceIntegrationTest"
+
+# Run single test method
+./gradlew test --tests "com.loopers.ExampleServiceIntegrationTest.testMethodName"
+
+# Test with coverage report
+./gradlew test jacocoTestReport
+```
+
+**Java version**: 21 (configured via Gradle toolchain)
+
+## Local Infrastructure
+
+```bash
+# Start MySQL, Redis (master+replica), Kafka
+docker-compose -f docker/infra-compose.yml up
+
+# Start Prometheus + Grafana monitoring
+docker-compose -f docker/monitoring-compose.yml up
+```
+
+- MySQL: localhost:3307 (root/root, application/application)
+- Redis Master: localhost:6379, Replica: localhost:6380
+- Kafka: localhost:19092, Kafka UI: localhost:9099
+- Grafana: localhost:3000 (admin/admin)
+
+## Architecture
+
+### Multi-Module Structure
+
+```
+loopers-java-spring-template/
+├── apps/                          # Executable Spring Boot applications
+│   ├── commerce-api              # REST API (web, actuator, springdoc-openapi)
+│   ├── commerce-batch            # Batch jobs (spring-batch)
+│   └── commerce-streamer         # Event streaming (web, kafka)
+├── modules/                       # Reusable infrastructure configurations
+│   ├── jpa                       # JPA, QueryDSL, MySQL connector
+│   ├── redis                     # Spring Data Redis (master-replica)
+│   └── kafka                     # Spring Kafka
+└── supports/                      # Cross-cutting add-on modules
+    ├── jackson                   # Jackson serialization (Kotlin module, JSR310)
+    ├── logging                   # Logback, Slack appender
+    └── monitoring                # Micrometer, Prometheus registry
+```
+
+### Module Dependencies
+
+| App | modules | supports |
+|-----|---------|----------|
+| commerce-api | jpa, redis | jackson, logging, monitoring |
+| commerce-batch | jpa, redis | jackson, logging, monitoring |
+| commerce-streamer | jpa, redis, kafka | jackson, logging, monitoring |
+
+### Layer Architecture (commerce-api)
+```
+interfaces/api/     → Controllers, DTOs, OpenAPI specs
+application/        → Facades (use case orchestration)
+domain/             → Entities, Services, Repository interfaces
+infrastructure/     → Repository implementations, adapters
+```
+
+### Key Patterns
+- **Controllers**: Implement `*ApiSpec` interfaces for OpenAPI documentation
+- **Facades**: Orchestrate domain services, convert domain models to DTOs
+- **Services**: `@Component` with `@Transactional`, contain business logic
+- **Repositories**: Interface in `domain/`, implementation in `infrastructure/`
+- **Entities**: Extend `BaseEntity` (provides id, createdAt, updatedAt, deletedAt)
+- **Response wrapper**: All APIs return `ApiResponse<T>`
+- **Error handling**: `CoreException` with `ErrorType` enum, caught by `ApiControllerAdvice`
+
+### Soft Delete
+Entities use `deletedAt` field via `BaseEntity`:
+```java
+entity.delete();   // marks as deleted
+entity.restore();  // restores
+```
+
+## Configuration
+
+- Profile-based: local, test, dev, qa, prd
+- Config imports in application.yml: jpa.yml, redis.yml, logging.yml, monitoring.yml
+- Management endpoints on port 8081 (/health, /prometheus)
+
+## Testing
+
+- Framework: JUnit 5 + AssertJ + Mockito + SpringMockk + Instancio
+- `DatabaseCleanUp` utility truncates tables between tests (from jpa test fixtures)
+- `RedisCleanUp` available from redis test fixtures
+- TestContainers support for MySQL, Redis, Kafka
+
+## 개발 규칙
+
+### 진행 Workflow - 증강 코딩
+- **대원칙**: 방향성 및 주요 의사 결정은 개발자에게 제안만 할 수 있으며, 최종 승인된 사항을 기반으로 작업 수행
+- **중간 결과 보고**: AI가 반복적인 동작을 하거나, 요청하지 않은 기능을 구현, 테스트 삭제를 임의로 진행할 경우 개발자가 개입
+- **설계 주도권 유지**: AI가 임의판단을 하지 않고, 방향성에 대한 제안 등을 진행할 수 있으나 개발자의 승인을 받은 후 수행
+
+### 개발 Workflow - TDD (Red → Green → Refactor)
+- 모든 테스트는 3A 원칙으로 작성 (Arrange - Act - Assert)
+
+| Phase | 설명 |
+|-------|------|
+| **Red** | 요구사항을 만족하는 실패하는 테스트 케이스 먼저 작성 |
+| **Green** | Red Phase의 테스트가 모두 통과할 수 있는 최소한의 코드 작성 (오버엔지니어링 금지) |
+| **Refactor** | 불필요한 private 함수 지양, 객체지향적 코드 작성, unused import 제거, 성능 최적화. 모든 테스트 통과 필수 |
+
+### 주의사항
+
+**Never Do:**
+- 실제 동작하지 않는 코드, 불필요한 Mock 데이터를 이용한 구현 금지
+- null-safety 하지 않은 코드 작성 금지 (Java의 경우 Optional 활용)
+- println 코드 남기지 말 것
+
+**Recommendation:**
+- 실제 API를 호출해 확인하는 E2E 테스트 코드 작성
+- 재사용 가능한 객체 설계
+- 성능 최적화에 대한 대안 및 제안
+- 개발 완료된 API는 `http/*.http` 파일에 분류해 작성
+
+**Priority:**
+1. 실제 동작하는 해결책만 고려
+2. null-safety, thread-safety 고려
+3. 테스트 가능한 구조로 설계
+4. 기존 코드 패턴 분석 후 일관성 유지