From ee664a61349c143b6a99648a847c757b4a02324c Mon Sep 17 00:00:00 2001 From: cherry2250 Date: Tue, 28 Oct 2025 09:29:26 +0900 Subject: [PATCH 1/2] =?UTF-8?q?develop=20=EB=B8=8C=EB=9E=9C=EC=B9=98=20?= =?UTF-8?q?=EB=B3=91=ED=95=A9=20(271=20=ED=8C=8C=EC=9D=BC=20=EC=97=85?= =?UTF-8?q?=EB=8D=B0=EC=9D=B4=ED=8A=B8)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- claude/api-design.md | 111 ---- claude/architecture-patterns-guide.md | 169 ------ claude/architecture-patterns.md | 169 ------ claude/cloud-design-patterns.md | 104 ---- claude/common-principles.md | 197 ------ claude/conversation-summary.md | 823 -------------------------- claude/logical-architecture-design.md | 64 -- claude/mermaid-guide.md | 300 ---------- claude/plantuml-guide.md | 82 --- claude/sequence-inner-design.md | 76 --- claude/sequence-outer-design.md | 54 -- claude/standard_comment.md | 518 ---------------- claude/standard_package_structure.md | 173 ------ claude/standard_testcode.md | 214 ------- common/build.gradle | 3 + 15 files changed, 3 insertions(+), 3054 deletions(-) delete mode 100644 claude/api-design.md delete mode 100644 claude/architecture-patterns-guide.md delete mode 100644 claude/architecture-patterns.md delete mode 100644 claude/cloud-design-patterns.md delete mode 100644 claude/common-principles.md delete mode 100644 claude/conversation-summary.md delete mode 100644 claude/logical-architecture-design.md delete mode 100644 claude/mermaid-guide.md delete mode 100644 claude/plantuml-guide.md delete mode 100644 claude/sequence-inner-design.md delete mode 100644 claude/sequence-outer-design.md delete mode 100644 claude/standard_comment.md delete mode 100644 claude/standard_package_structure.md delete mode 100644 claude/standard_testcode.md diff --git a/claude/api-design.md b/claude/api-design.md deleted file mode 100644 index d44c64b..0000000 --- a/claude/api-design.md +++ /dev/null @@ -1,111 +0,0 @@ -# API설계가이드 - -[요청사항] -- <작성원칙>을 준용하여 설계 -- <작성순서>에 따라 설계 -- [결과파일] 안내에 따라 파일 작성 -- 최종 완료 후 API 확인 방법 안내 - - https://editor.swagger.io/ 접근 - - 생성된 swagger yaml파일을 붙여서 확인 및 테스트 - -[가이드] -<작성 원칙> -- 각 서비스 API는 독립적으로 완전한 명세를 포함 -- 공통 스키마는 각 서비스에서 필요에 따라 직접 정의 -- 서비스 간 의존성을 최소화하여 독립 배포 가능 -- 중복되는 스키마가 많아질 경우에만 공통 파일 도입 검토 -<작성순서> -- 준비: - - 유저스토리, 외부시퀀스설계서, 내부시퀀스설계서 분석 및 이해 -- 실행: - - <병렬처리> 안내에 따라 동시 수행 - - 에 따라 API 선정 - - <파일작성안내>에 따라 작성 - - <검증방법>에 따라 작성된 YAML의 문법 및 구조 검증 수행 -- 검토: - - <작성원칙> 준수 검토 - - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토 - - 수정 사항 선택 및 반영 - - -- 유저스토리와 매칭 되어야 함. 불필요한 추가 설계 금지 - (유저스토리 ID를 x-user-story 확장 필드에 명시) -- '외부시퀀스설계서'/'내부시퀀스설계서'와 일관성 있게 선정 - -<파일작성안내> -- OpenAPI 3.0 스펙 준용 -- **servers 섹션 필수화** - - 모든 OpenAPI 명세에 servers 섹션 포함 - - SwaggerHub Mock URL을 첫 번째 옵션으로 배치 -- **example 데이터 권장** - - 스키마에 example을 추가하여 Swagger UI에서 테스트 할 수 있게함 -- **테스트 시나리오 포함** - - 각 API 엔드포인트별 테스트 케이스 정의 - - 성공/실패 케이스 모두 포함 -- 작성 형식 - - YAML 형식의 OpenAPI 3.0 명세 - - 각 API별 필수 항목: - - summary: API 목적 설명 - - operationId: 고유 식별자 - - x-user-story: 유저스토리 ID - - x-controller: 담당 컨트롤러 - - tags: API 그룹 분류 - - requestBody/responses: 상세 스키마 - - 각 서비스 파일에 필요한 모든 스키마 포함: - - components/schemas: 요청/응답 모델 - - components/parameters: 공통 파라미터 - - components/responses: 공통 응답 - - components/securitySchemes: 인증 방식 - -<파일 구조> -``` -design/backend/api/ -├── {service-name}-api.yaml # 각 마이크로서비스별 API 명세 -└── ... # 추가 서비스들 - -예시: -├── profile-service-api.yaml # 프로파일 서비스 API -├── order-service-api.yaml # 주문 서비스 API -└── payment-service-api.yaml # 결제 서비스 API -``` - -- 파일명 규칙 - - 서비스명은 kebab-case로 작성 - - 파일명 형식: {service-name}-api.yaml - - 서비스명은 유저스토리의 '서비스' 항목을 영문으로 변환하여 사용 - -<병렬처리> -- **의존성 분석 선행**: 병렬 처리 전 반드시 의존성 파악 -- **순차 처리 필요시**: 무리한 병렬화보다는 안전한 순차 처리 -- **검증 단계 필수**: 병렬 처리 후 통합 검증 - -<검증방법> -- swagger-cli를 사용한 자동 검증 수행 -- 검증 명령어: `swagger-cli validate {파일명}` -- swagger-cli가 없을 경우 자동 설치: - ```bash - # swagger-cli 설치 확인 및 자동 설치 - command -v swagger-cli >/dev/null 2>&1 || npm install -g @apidevtools/swagger-cli - - # 검증 실행 - swagger-cli validate design/backend/api/*.yaml - ``` -- 검증 항목: - - OpenAPI 3.0 스펙 준수 - - YAML 구문 오류 - - 스키마 참조 유효성 - - 필수 필드 존재 여부 - -[참고자료] -- 유저스토리 -- 외부시퀀스설계서 -- 내부시퀀스설계서 -- OpenAPI 스펙: https://swagger.io/specification/ - -[예시] -- swagger api yaml: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-swagger-api.yaml -- API설계서: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-API%20설계서.md - -[결과파일] -- 각 서비스별로 별도의 YAML 파일 생성 -- design/backend/api/*.yaml (OpenAPI 형식) \ No newline at end of file diff --git a/claude/architecture-patterns-guide.md b/claude/architecture-patterns-guide.md deleted file mode 100644 index 4177e80..0000000 --- a/claude/architecture-patterns-guide.md +++ /dev/null @@ -1,169 +0,0 @@ -# 클라우드 아키텍처패턴선정 가이드 - -## 개요 -이 가이드는 마이크로서비스 기반 클라우드 시스템을 위한 아키텍처 패턴 선정 방법론을 제공합니다. 체계적인 분석과 정량적 평가를 통해 최적의 패턴을 선정할 수 있습니다. - -## 1. 요구사항 분석 - -### 1.1 유저스토리 분석 -각 서비스별로 기능적/비기능적 요구사항을 명확히 도출합니다. - -**기능적 요구사항**: -- 각 유저스토리에서 요구하는 핵심 기능 -- 서비스 간 데이터 교환 요구사항 -- 비즈니스 로직의 복잡도와 특성 - -**비기능적 요구사항**: -- 성능 요구사항 (응답시간, 처리량) -- 가용성 및 신뢰성 요구사항 -- 확장성 및 유지보수성 요구사항 -- 보안 및 컴플라이언스 요구사항 - -### 1.2 UI/UX설계 분석 -Wireframe을 통해 사용자 인터랙션 패턴과 데이터 플로우를 파악합니다. - -**분석 항목**: -- 사용자 인터랙션 패턴 (동기/비동기 처리 필요성) -- 데이터 조회/변경 패턴 -- 화면 간 전환 흐름 -- 실시간 업데이트 요구사항 - -### 1.3 통합 분석 -유저스토리와 UI/UX 설계를 연계하여 **기술적 도전과제를 식별**합니다. - -**도전과제 식별**: -- 복잡한 비즈니스 트랜잭션 -- 대용량 데이터 처리 -- 실시간 처리 요구사항 -- 외부 시스템 연동 복잡성 -- 서비스 간 의존성 관리 - -## 2. 패턴 선정 - -### 2.1 평가 기준 -다음 5가지 기준으로 각 패턴을 정량적으로 평가합니다. - -| 기준 | 가중치 | 평가 내용 | -|------|--------|-----------| -| **기능 적합성** | 35% | 요구사항을 직접 해결하는 능력 | -| **성능 효과** | 25% | 응답시간 및 처리량 개선 효과 | -| **운영 복잡도** | 20% | 구현 및 운영의 용이성 | -| **확장성** | 15% | 미래 요구사항에 대한 대응력 | -| **비용 효율성** | 5% | 개발/운영 비용 대비 효과(ROI) | - -### 2.2 정량적 평가 방법 - -**평가 척도**: 1-10점 (10점이 가장 우수) - -**패턴별 평가 매트릭스 예시**: - -| 패턴 | 기능 적합성
(35%) | 성능 효과
(25%) | 운영 복잡도
(20%) | 확장성
(15%) | 비용 효율성
(5%) | **총점** | -|------|:---:|:---:|:---:|:---:|:---:|:---:| -| API Gateway | 8 × 0.35 = 2.8 | 7 × 0.25 = 1.75 | 8 × 0.20 = 1.6 | 9 × 0.15 = 1.35 | 7 × 0.05 = 0.35 | **7.85** | -| CQRS | 9 × 0.35 = 3.15 | 9 × 0.25 = 2.25 | 5 × 0.20 = 1.0 | 8 × 0.15 = 1.2 | 6 × 0.05 = 0.3 | **7.90** | -| Event Sourcing | 7 × 0.35 = 2.45 | 8 × 0.25 = 2.0 | 4 × 0.20 = 0.8 | 9 × 0.15 = 1.35 | 5 × 0.05 = 0.25 | **6.85** | - -### 2.3 단계별 적용 로드맵 -MVP → 확장 → 고도화 3단계로 구분하여 점진적 적용 계획을 수립합니다. - -**Phase 1: MVP (Minimum Viable Product)** -- 핵심 비즈니스 기능 중심 -- 단순하고 안정적인 패턴 우선 -- 빠른 출시를 위한 최소 기능 - -**Phase 2: 확장 (Scale-up)** -- 사용자 증가에 따른 성능 최적화 -- 고급 패턴 도입 -- 모니터링 및 운영 자동화 - -**Phase 3: 고도화 (Advanced)** -- 복잡한 비즈니스 요구사항 대응 -- 최신 기술 및 패턴 적용 -- 글로벌 확장 대비 - -## 3. 문서 작성 - -### 3.1 구조화된 작성 순서 -1. **요구사항 분석 결과** -2. **패턴 평가** (평가 매트릭스 포함) -3. **적용 설계** (Mermaid 다이어그램) -4. **구현 계획** (Phase별 로드맵) - -### 3.2 Mermaid 다이어그램 작성 -서비스 아키텍처와 패턴 적용을 시각적으로 표현합니다. - -```mermaid -graph TB - Client[클라이언트] --> Gateway[API Gateway] - Gateway --> Auth[인증 서비스] - Gateway --> UserSvc[사용자 서비스] - Gateway --> OrderSvc[주문 서비스] - - OrderSvc --> EventBus[이벤트 버스] - EventBus --> PaymentSvc[결제 서비스] - EventBus --> NotificationSvc[알림 서비스] - - UserSvc --> UserDB[(사용자 DB)] - OrderSvc --> OrderDB[(주문 DB)] - PaymentSvc --> PaymentDB[(결제 DB)] -``` - -### 3.3 실용적 내용 포함 -- **코드 예시**: 패턴 구현을 위한 구체적인 코드 스니펫 -- **구현 시 고려사항**: 실제 개발 시 주의할 점 -- **예상 효과**: 정량적 성과 지표 (응답시간 개선, 처리량 증가 등) - -## 참고 자료 -- **유저스토리** -- UI/UX설계서 -- **클라우드아키텍처패턴요약표** - -## 결과 파일 -선정된 아키텍처 패턴은 다음과 같이 문서화됩니다: - -### 파일명 -design/pattern/architecture-pattern.md - -### 필수 포함 내용 -1. **요구사항 분석 결과** - - 기능적/비기능적 요구사항 상세 분석 - - 기술적 도전과제 식별 - -2. **패턴 선정 매트릭스 (평가표)** - - 후보 패턴별 정량적 평가 점수 - - 선정 근거 및 이유 - -3. **서비스별 패턴 적용 설계 (Mermaid)** - - 전체 아키텍처 구조 - - 패턴별 적용 영역 표시 - -4. **Phase별 구현 로드맵** - - 단계별 적용 계획 - - 마일스톤 및 목표 설정 - -5. **예상 성과 지표** - - 성능 개선 예상치 - - 비용 절감 효과 - - 개발 생산성 향상 - -## 체크리스트 - -작성 완료 후 다음 항목들을 검토하세요: - -- [ ] **각 유저스토리가 어떤 패턴으로 해결되는지 명시했는가?** -- [ ] **패턴 선정 이유를 정량적으로 설명했는가?** -- [ ] **패턴 간 상호작용과 통합 아키텍처를 표현했는가?** -- [ ] **구현 우선순위와 단계별 목표가 명확한가?** -- [ ] **실무자가 바로 활용할 수 있는 수준인가?** - -## 작성 시 주의사항 - -1. **객관적 평가**: 주관적 판단보다는 정량적 데이터 기반 선정 -2. **현실성**: 팀의 기술 수준과 프로젝트 일정을 고려한 실현 가능한 패턴 선정 -3. **확장성**: 현재 요구사항뿐만 아니라 미래 확장성까지 고려 -4. **비용 효율성**: 과도한 엔지니어링 지양, 비즈니스 가치 중심 선정 -5. **문서화**: 선정 과정과 근거를 명확히 문서화하여 후속 의사결정 지원 - -## 완료 후 mermaid 스크립트 테스트 방법 안내 -- https://mermaid.live/edit 에 접근 -- 스크립트 내용을 붙여넣어 확인 \ No newline at end of file diff --git a/claude/architecture-patterns.md b/claude/architecture-patterns.md deleted file mode 100644 index 4177e80..0000000 --- a/claude/architecture-patterns.md +++ /dev/null @@ -1,169 +0,0 @@ -# 클라우드 아키텍처패턴선정 가이드 - -## 개요 -이 가이드는 마이크로서비스 기반 클라우드 시스템을 위한 아키텍처 패턴 선정 방법론을 제공합니다. 체계적인 분석과 정량적 평가를 통해 최적의 패턴을 선정할 수 있습니다. - -## 1. 요구사항 분석 - -### 1.1 유저스토리 분석 -각 서비스별로 기능적/비기능적 요구사항을 명확히 도출합니다. - -**기능적 요구사항**: -- 각 유저스토리에서 요구하는 핵심 기능 -- 서비스 간 데이터 교환 요구사항 -- 비즈니스 로직의 복잡도와 특성 - -**비기능적 요구사항**: -- 성능 요구사항 (응답시간, 처리량) -- 가용성 및 신뢰성 요구사항 -- 확장성 및 유지보수성 요구사항 -- 보안 및 컴플라이언스 요구사항 - -### 1.2 UI/UX설계 분석 -Wireframe을 통해 사용자 인터랙션 패턴과 데이터 플로우를 파악합니다. - -**분석 항목**: -- 사용자 인터랙션 패턴 (동기/비동기 처리 필요성) -- 데이터 조회/변경 패턴 -- 화면 간 전환 흐름 -- 실시간 업데이트 요구사항 - -### 1.3 통합 분석 -유저스토리와 UI/UX 설계를 연계하여 **기술적 도전과제를 식별**합니다. - -**도전과제 식별**: -- 복잡한 비즈니스 트랜잭션 -- 대용량 데이터 처리 -- 실시간 처리 요구사항 -- 외부 시스템 연동 복잡성 -- 서비스 간 의존성 관리 - -## 2. 패턴 선정 - -### 2.1 평가 기준 -다음 5가지 기준으로 각 패턴을 정량적으로 평가합니다. - -| 기준 | 가중치 | 평가 내용 | -|------|--------|-----------| -| **기능 적합성** | 35% | 요구사항을 직접 해결하는 능력 | -| **성능 효과** | 25% | 응답시간 및 처리량 개선 효과 | -| **운영 복잡도** | 20% | 구현 및 운영의 용이성 | -| **확장성** | 15% | 미래 요구사항에 대한 대응력 | -| **비용 효율성** | 5% | 개발/운영 비용 대비 효과(ROI) | - -### 2.2 정량적 평가 방법 - -**평가 척도**: 1-10점 (10점이 가장 우수) - -**패턴별 평가 매트릭스 예시**: - -| 패턴 | 기능 적합성
(35%) | 성능 효과
(25%) | 운영 복잡도
(20%) | 확장성
(15%) | 비용 효율성
(5%) | **총점** | -|------|:---:|:---:|:---:|:---:|:---:|:---:| -| API Gateway | 8 × 0.35 = 2.8 | 7 × 0.25 = 1.75 | 8 × 0.20 = 1.6 | 9 × 0.15 = 1.35 | 7 × 0.05 = 0.35 | **7.85** | -| CQRS | 9 × 0.35 = 3.15 | 9 × 0.25 = 2.25 | 5 × 0.20 = 1.0 | 8 × 0.15 = 1.2 | 6 × 0.05 = 0.3 | **7.90** | -| Event Sourcing | 7 × 0.35 = 2.45 | 8 × 0.25 = 2.0 | 4 × 0.20 = 0.8 | 9 × 0.15 = 1.35 | 5 × 0.05 = 0.25 | **6.85** | - -### 2.3 단계별 적용 로드맵 -MVP → 확장 → 고도화 3단계로 구분하여 점진적 적용 계획을 수립합니다. - -**Phase 1: MVP (Minimum Viable Product)** -- 핵심 비즈니스 기능 중심 -- 단순하고 안정적인 패턴 우선 -- 빠른 출시를 위한 최소 기능 - -**Phase 2: 확장 (Scale-up)** -- 사용자 증가에 따른 성능 최적화 -- 고급 패턴 도입 -- 모니터링 및 운영 자동화 - -**Phase 3: 고도화 (Advanced)** -- 복잡한 비즈니스 요구사항 대응 -- 최신 기술 및 패턴 적용 -- 글로벌 확장 대비 - -## 3. 문서 작성 - -### 3.1 구조화된 작성 순서 -1. **요구사항 분석 결과** -2. **패턴 평가** (평가 매트릭스 포함) -3. **적용 설계** (Mermaid 다이어그램) -4. **구현 계획** (Phase별 로드맵) - -### 3.2 Mermaid 다이어그램 작성 -서비스 아키텍처와 패턴 적용을 시각적으로 표현합니다. - -```mermaid -graph TB - Client[클라이언트] --> Gateway[API Gateway] - Gateway --> Auth[인증 서비스] - Gateway --> UserSvc[사용자 서비스] - Gateway --> OrderSvc[주문 서비스] - - OrderSvc --> EventBus[이벤트 버스] - EventBus --> PaymentSvc[결제 서비스] - EventBus --> NotificationSvc[알림 서비스] - - UserSvc --> UserDB[(사용자 DB)] - OrderSvc --> OrderDB[(주문 DB)] - PaymentSvc --> PaymentDB[(결제 DB)] -``` - -### 3.3 실용적 내용 포함 -- **코드 예시**: 패턴 구현을 위한 구체적인 코드 스니펫 -- **구현 시 고려사항**: 실제 개발 시 주의할 점 -- **예상 효과**: 정량적 성과 지표 (응답시간 개선, 처리량 증가 등) - -## 참고 자료 -- **유저스토리** -- UI/UX설계서 -- **클라우드아키텍처패턴요약표** - -## 결과 파일 -선정된 아키텍처 패턴은 다음과 같이 문서화됩니다: - -### 파일명 -design/pattern/architecture-pattern.md - -### 필수 포함 내용 -1. **요구사항 분석 결과** - - 기능적/비기능적 요구사항 상세 분석 - - 기술적 도전과제 식별 - -2. **패턴 선정 매트릭스 (평가표)** - - 후보 패턴별 정량적 평가 점수 - - 선정 근거 및 이유 - -3. **서비스별 패턴 적용 설계 (Mermaid)** - - 전체 아키텍처 구조 - - 패턴별 적용 영역 표시 - -4. **Phase별 구현 로드맵** - - 단계별 적용 계획 - - 마일스톤 및 목표 설정 - -5. **예상 성과 지표** - - 성능 개선 예상치 - - 비용 절감 효과 - - 개발 생산성 향상 - -## 체크리스트 - -작성 완료 후 다음 항목들을 검토하세요: - -- [ ] **각 유저스토리가 어떤 패턴으로 해결되는지 명시했는가?** -- [ ] **패턴 선정 이유를 정량적으로 설명했는가?** -- [ ] **패턴 간 상호작용과 통합 아키텍처를 표현했는가?** -- [ ] **구현 우선순위와 단계별 목표가 명확한가?** -- [ ] **실무자가 바로 활용할 수 있는 수준인가?** - -## 작성 시 주의사항 - -1. **객관적 평가**: 주관적 판단보다는 정량적 데이터 기반 선정 -2. **현실성**: 팀의 기술 수준과 프로젝트 일정을 고려한 실현 가능한 패턴 선정 -3. **확장성**: 현재 요구사항뿐만 아니라 미래 확장성까지 고려 -4. **비용 효율성**: 과도한 엔지니어링 지양, 비즈니스 가치 중심 선정 -5. **문서화**: 선정 과정과 근거를 명확히 문서화하여 후속 의사결정 지원 - -## 완료 후 mermaid 스크립트 테스트 방법 안내 -- https://mermaid.live/edit 에 접근 -- 스크립트 내용을 붙여넣어 확인 \ No newline at end of file diff --git a/claude/cloud-design-patterns.md b/claude/cloud-design-patterns.md deleted file mode 100644 index 4e39358..0000000 --- a/claude/cloud-design-patterns.md +++ /dev/null @@ -1,104 +0,0 @@ -# 클라우드 디자인 패턴 개요 - -## 전체 분류 현황 - -총 **42개의 클라우드 디자인 패턴** - -- **DB 성능개선**: 1개 -- **읽기 최적화**: 4개 -- **핵심업무 집중**: 6개 -- **안정적 현대화**: 2개 -- **효율적 분산처리**: 13개 -- **안정성**: 6개 -- **보안**: 3개 -- **운영**: 7개 - ---- - -## 패턴 목록 - -### 1. DB 성능개선 (1개) - -| No. | 패턴명 | 목적 | 설명 | -|-----|--------|------|------| -| 1 | Sharding | 데이터 양 줄이기 | 데이터 저장소를 수평적으로 분할(shard)하여 대규모 데이터 저장 및 접근 시 확장성을 높이는 패턴 | - -### 2. 읽기 최적화 (4개) - -| No. | 패턴명 | 목적 | 설명 | -|-----|--------|------|------| -| 2 | Index Table | NoSQL DB Query 최적화 | 데이터 저장소에서 자주 참조되는 필드에 대한 인덱스를 생성하여 쿼리 성능을 개선하는 패턴 | -| 3 | Cache-Aside | 성능 향상 및 데이터 일관성 유지 | 데이터 저장소에서 캐시에 데이터를 필요에 따라 로드하여 성능을 개선하고, 캐시와 데이터 저장소 간의 일관성을 유지하는 패턴 | -| 4 | Materialized View | 쿼리 성능 최적화 | 데이터를 미리 변환하여 준비된 뷰를 생성함으로써 쿼리 성능을 높이고 데이터 추출을 효율화하는 패턴 | -| 5 | CQRS | 읽기/쓰기 분리 | 데이터 저장소의 읽기와 쓰기 작업을 분리하여 성능, 확장성, 보안성을 높이는 패턴 | - -### 3. 핵심업무 집중 (6개) - -| No. | 패턴명 | 목적 | 설명 | -|-----|--------|------|------| -| 6 | Gateway Offloading | 횡단관심사 분리 | SSL 인증서 관리, 인증, 로깅 등의 공통 기능을 게이트웨이로 분리하여 애플리케이션의 복잡도를 낮추는 패턴 | -| 7 | Gateway Routing | 라우팅 중앙 처리 | 단일 엔드포인트를 통해 요청을 받아 백엔드 서비스나 인스턴스로 라우팅하는 패턴 | -| 8 | Gateway Aggregation | 클라이언트 요청 수 줄이기 | 단일 엔드포인트에서 클라이언트 요청을 받아 여러 백엔드 서비스로 분배하고 응답을 취합하는 패턴 | -| 9 | Backends for Frontends | 프론트엔드 유형별 전용처리 | 특정 프런트엔드에 특화된 백엔드 서비스를 별도로 구축하는 패턴 | -| 10 | Sidecar | 공통 기능 분리 | 애플리케이션의 일부 컴포넌트를 별도 프로세스나 컨테이너로 분리하여 격리와 확장성을 제공하는 패턴 | -| 11 | Ambassador | 네트워크 통신의 안정성과 보안 강화 | 클라이언트를 대신해 네트워크 요청을 처리하는 헬퍼 서비스를 생성하는 패턴 | - -### 4. 안정적 현대화 (2개) - -| No. | 패턴명 | 목적 | 설명 | -|-----|--------|------|------| -| 12 | Strangler Fig | 현대화의 위험 최소화와 점진적 전환 | 레거시 시스템을 점진적으로 새로운 애플리케이션 및 서비스로 교체하는 패턴 | -| 13 | Anti-Corruption Layer | 시스템 간 안정적 인터페이스 | 서로 다른 하위 시스템 간의 의미적 차이를 조정하기 위해 중간 계층을 구현하는 패턴 | - -### 5. 효율적 분산처리 (13개) - -| No. | 패턴명 | 목적 | 설명 | -|-----|--------|------|------| -| 14 | Pipes and Filters | 작업 단계 모듈화로 재사용성과 성능 향상 | 복잡한 작업을 독립적인 단계(필터)로 분리하고 메시지(파이프)로 연결하여 모듈성과 유연성을 높이는 패턴 | -| 15 | Scheduler Agent Supervisor | 워크플로우의 신뢰성 향상 | 작업 단계를 스케줄러, 에이전트, 감독자로 분리하여 신뢰성과 확장성을 높이는 패턴 | -| 16 | Leader Election | 분산 작업의 충돌 방지와 안정성 향상 | 분산 시스템에서 여러 작업 인스턴스 중 하나를 리더로 선출하여 조정 역할을 맡기는 패턴 | -| 17 | Saga | 데이터 일관성 보장 | 각 서비스의 로컬 트랜잭션을 사용하여 분산 트랜잭션의 일관성을 보장하는 패턴 | -| 18 | Compensating Transaction | 오류 복구로 데이터 일관성 보장 | 분산 트랜잭션에서 실패한 작업을 보상하기 위해 이전 작업을 취소하거나 상쇄하는 트랜잭션을 실행하는 패턴 | -| 19 | Priority Queue | 중요 작업의 우선 처리 보장 | 메시지의 우선순위에 따라 처리 순서를 조정하는 큐를 사용하는 패턴 | -| 20 | Queue-Based Load Leveling | 부하의 균등한 분산으로 안정성 확보 | 메시지 큐를 사용하여 작업과 서비스 간의 부하를 균등하게 분산시키는 패턴 | -| 21 | Sequential Convoy | 처리순서 보장 | 관련 메시지 집합을 순서대로 처리하되 다른 메시지 처리를 차단하지 않도록 하는 패턴 | -| 22 | Claim Check | 메시지 크기 최소화 및 성능과 보안 향상 | 메시지에서 페이로드를 분리하여 외부 저장소에 저장하고 참조키(클레임 체크)를 사용하는 패턴 | -| 23 | Publisher-Subscriber | 단일 이벤트 메시지의 복수 서비스 처리 보장 | 다수의 소비자(Consumer)에게 이벤트를 발행하는 패턴 | -| 24 | Asynchronous Request-Reply | 장시간 처리 작업의 응답시간 단축 | 프런트엔드(클라이언트)와 백엔드 간 비동기로 요청과 응답을 분리하여 응답 시간을 단축하는 패턴 | -| 25 | Competing Consumers | 병렬처리로 작업 처리 속도 향상 | 동일 메시지 채널에서 여러 소비자가 경쟁적으로 메시지를 처리하여 병렬성을 높이는 패턴 | -| 26 | Choreography | 중앙집중 처리의 병목현상 방지 | 중앙 조정자 없이 각 서비스가 자율적으로 이벤트를 구독하고 반응하여 전체 워크플로를 수행하는 패턴 | - -### 6. 안정성 (6개) - -| No. | 패턴명 | 목적 | 설명 | -|-----|--------|------|------| -| 27 | Rate Limiting | 요청 폭주 방지로 안정성 유지 | 일정 기간 동안 허용되는 요청 수를 제한하여 과부하를 방지하고 서비스 안정성을 높이는 패턴 | -| 28 | Throttling | 요청 폭주 방지로 안정성 유지 | 시스템의 부하 상태에 따라 요청 처리량을 동적으로 조절하여 과부하를 방지하는 패턴 | -| 29 | Bulkhead | 자원풀 격리로 장애 전파 방지 | 애플리케이션 요소를 격리된 풀로 분할하여 하나의 장애가 전체로 전파되는 것을 방지하는 패턴 | -| 30 | Circuit Breaker | 장애전파 방지 | 장애가 발생한 구성 요소를 빠르게 감지하고 요청 실패를 최소화하는 패턴 | -| 31 | Retry | 일시적 오류시 처리 보장 | 일시적인 오류에 대해 실패한 요청을 재시도하여 복원력을 높이는 패턴 | -| 32 | Event Sourcing | 데이터 멱등성 보장과 변경 기록 제공 | 데이터에 대한 모든 변경사항을 이벤트로 저장하고, 이벤트를 재생하여 데이터의 상태를 복원하는 패턴 | - -### 7. 보안 (3개) - -| No. | 패턴명 | 목적 | 설명 | -|-----|--------|------|------| -| 33 | Federated Identity | 사용자 인증 및 관리 효율화 | 인증을 외부 ID 제공자에 위임하여 사용자 관리를 간소화하고 SSO를 구현하는 패턴 | -| 34 | Gatekeeper | 데이터 접근 제어와 보안 강화 | 신뢰할 수 있는 호스트에 보안 관련 기능을 집중시켜 스토리지나 서비스의 보안을 강화하는 패턴 | -| 35 | Valet Key | 네트워크 대역폭 감소 | 클라이언트가 특정 리소스에 제한된 직접 접근을 할 수 있도록 토큰을 사용하는 패턴 | - -### 8. 운영 (7개) - -| No. | 패턴명 | 목적 | 설명 | -|-----|--------|------|------| -| 36 | Geodes | 글로벌 서비스 가용성과 성능 최적화 | 백엔드 서비스를 여러 지역에 분산 배치하여 지연 시간을 줄이고 가용성을 높이는 패턴 | -| 37 | Deployment Stamps | 멀티 테넌트 관리 | 리소스 그룹을 복제하여 작업이나 테넌트 단위로 격리된 운영 환경을 제공하는 패턴 | -| 38 | Health Endpoint Monitoring | 서비스 가용성 상태 점검 | 애플리케이션의 상태를 모니터링하기 위한 전용 API 엔드포인트를 노출하는 패턴 | -| 39 | Compute Resource Consolidation | 자원 사용 효율성과 비용 절감 | 여러 작업이나 운영을 단일 컴퓨팅 단위로 통합하여 효율성과 비용을 최적화하는 패턴 | -| 40 | Static Content Hosting | 정적 자원 제공, 비용절감과 성능 향상 | 정적 콘텐츠를 클라우드 스토리지에 배포하여 클라이언트에 직접 제공함으로써 컴퓨팅 인스턴스 사용을 줄이는 패턴 | -| 41 | External Configuration Store | 환경설정 중앙관리와 재배포 없이 설정 변경 적용 | 애플리케이션의 설정 정보를 중앙화하여 관리 효율성을 높이고 설정 값 변경 시 재배포 없이 적용하는 패턴 | -| 42 | Edge Workload Configuration | 엣지컴퓨팅의 효율적 관리 | 장치와 시스템이 혼재된 엣지 환경에서 워크로드 구성을 효율적으로 관리하여 지연 시간 단축과 네트워크 비용 절감을 하는 패턴 | - ---- - -> **참고**: 이 문서는 클라우드 환경에서 자주 사용되는 디자인 패턴들을 체계적으로 분류하여 정리한 것입니다. 각 패턴은 특정 목적과 상황에 맞게 적용될 수 있으며, 실제 구현 시에는 프로젝트의 요구사항과 제약사항을 충분히 고려해야 합니다. diff --git a/claude/common-principles.md b/claude/common-principles.md deleted file mode 100644 index 31b8354..0000000 --- a/claude/common-principles.md +++ /dev/null @@ -1,197 +0,0 @@ -# 공통설계원칙 - -모든 설계 단계에서 공통으로 적용되는 핵심 원칙과 전략 - -## 🎯 핵심 원칙 - -### 1. 🚀 실행 우선 원칙 -- **프롬프트 우선**: 바로 실행할 수 있는 프롬프트로 작업 시작 -- **가이드 학습**: 원리와 방법론은 가이드로 깊이 있게 학습 -- **점진적 이해**: 실행 → 결과 확인 → 원리 학습 순서 - -### 2. 🔄 병렬 처리 전략 -- **서브 에이전트 활용**: Task 도구로 서비스별 동시 작업 -- **의존성 기반 그룹화**: 의존 관계에 따른 순차/병렬 처리 결정 -- **통합 검증**: 병렬 작업 완료 후 전체적 일관성 검증 - -### 3. 🏗️ 마이크로서비스 설계 원칙 -- **서비스 독립성**: 캐시를 통한 직접 의존성 최소화 -- **선택적 비동기**: 장시간 작업(AI 일정 생성)만 비동기 처리 -- **캐시 우선**: Redis를 통한 성능 최적화 -- **독립 배포**: 서비스별 독립적 배포 가능한 구조 - -### 4. 📝 표준화 원칙 -- **PlantUML**: 모든 다이어그램 표준 (`!theme mono`) -- **OpenAPI 3.0**: API 명세 표준 -- **자동 검증**: PlantUML, OpenAPI 문법 검사 필수 -- **일관된 네이밍**: kebab-case 파일명, 표준화된 스키마명 - -### 5. ✅ 검증 우선 원칙 -- **각 단계마다 자동 검증**: 품질 보장 -- **실시간 피드백**: 오류 조기 발견 및 수정 -- **CI/CD 통합**: 자동화된 검증 프로세스 -- **PlantUML 스크립트 파일 생성 즉시 검사 실행**: 'PlantUML 문법 검사 가이드' 준용 - -### 6. 🚀 점진적 구현 원칙 -- **MVP → 확장 → 고도화**: 단계별 접근 -- **YAGNI 적용**: 꼭 필요한 기능만 구현(YAGNI원칙:You aren't gonna need it) -- **지속적 개선**: 피드백 기반 점진적 발전 - -## 🔧 의존성 분석 및 병렬 처리 - -### 의존성 분석 방법 - -1. **서비스 간 의존성 파악** - ``` - 일정 서비스 → 프로파일 서비스 (멤버/여행 정보 조회) - 일정 서비스 → 장소 서비스 (장소 정보 조회) - 장소 서비스: 독립적 (외부 API만 사용) - ``` - -2. **의존성 기반 그룹화** - ``` - Group A (순차 처리): 프로파일 → 일정 서비스 - Group B (독립 처리): 장소 서비스 - ``` - -3. **에이전트 할당 및 병렬 처리** - ``` - Agent 1: Group A 담당 - - 프로파일 서비스 설계 - - 일정 서비스 설계 (프로파일 참조) - - Agent 2: Group B 담당 - - 장소 서비스 설계 (독립적) - ``` - -### 병렬 처리 적용 가이드 - -#### API 설계 단계 -- **독립 서비스**: 각각 별도 에이전트 -- **의존 서비스**: 동일 에이전트 내 순차 처리 -- **공통 검증**: 모든 에이전트 완료 후 swagger-cli 검증 - -#### 시퀀스 설계 단계 -- **외부 시퀀스**: 플로우별 병렬 처리 (각 플로우는 독립적) -- **내부 시퀀스**: 서비스별 병렬 처리 (서비스 내부는 독립적) - -#### 클래스/데이터 설계 단계 -- **의존성 그룹별**: 참조 관계가 있는 서비스들은 순차 처리 -- **독립 서비스**: 병렬 처리 -- **공통 클래스**: 모든 서비스 설계 완료 후 마지막 처리 - -## 🎨 PlantUML 작성 표준 - -### 기본 템플릿 -```plantuml -@startuml -!theme mono - -title [다이어그램 제목] - -' 다이어그램 내용 -@enduml -``` - -### 필수 검증 -- **각 파일 생성 직후 PlantUML 문법 검사 수행** -- **파이프 방식 권장**: `cat "파일" | docker exec -i plantuml ...` -- **화살표 문법 주의**: sequence diagram에서 `..>` 사용 금지 - -### 스타일 가이드 -- **폰트 크기**: 적절한 가독성 확보 -- **색상 구분**: 서비스별, 레이어별 색상 구분 -- **설명 추가**: note를 활용한 상세 설명 - -## 🔌 API 설계 표준 - -### 파일 구조 -``` -design/backend/api/{service-name}-api.yaml -``` - -### 필수 필드 -```yaml -paths: - /endpoint: - get: - summary: API 목적 설명 - operationId: 고유 식별자 - x-user-story: 유저스토리 ID - x-controller: 담당 컨트롤러 - tags: [API 그룹] -``` - -### 스키마 원칙 -- **서비스별 독립**: 각 서비스 파일에 모든 스키마 포함 -- **중복 허용**: 초기에는 중복을 허용하고 점진적으로 공통화 -- **명확한 네이밍**: Request/Response DTO 네이밍 표준 - -## 🔄 시퀀스 설계 표준 - -### 외부 시퀀스 (서비스 간) -- **참여 서비스만**: 해당 플로우에 참여하는 서비스만 표시 -- **API 호출 중심**: 서비스 간 API 호출 순서 표현 -- **한글 설명**: 각 호출의 목적을 한글로 명시 - -### 내부 시퀀스 (서비스 내부) -- **모든 API 표시**: 해당 서비스의 모든 API 포함 -- **내부 처리 흐름**: 컨트롤러 → 서비스 → 레포지토리 플로우 -- **기술적 세부사항**: 캐시, DB 접근 등 포함 - -### 동기/비동기 구분 -- **실선 (→)**: 동기 호출 -- **점선 (->>)**: 비동기 호출 -- **양방향**: 필요시에만 사용 - -## 📊 클래스 설계 표준 - -### 아키텍처 적용 -- **Clean Architecture**: Port/Adapter 용어 대신 표준 Clean 용어 사용 -- **멀티프로젝트**: 서비스별 독립 모듈 -- **패키지 구조 표준**: 일관된 패키지 구조 적용 - -### 관계 표현 -- **Generalization**: 상속 관계 -- **Realization**: 인터페이스 구현 -- **Dependency**: 의존 관계 -- **Association**: 연관 관계 -- **Aggregation/Composition**: 집약/합성 관계 - -### 상세 정보 -- **프로퍼티와 메소드**: 모두 명시 -- **접근 제한자**: 적절한 가시성 설정 -- **타입 정보**: 정확한 데이터 타입 명시 - -## 🗄️ 데이터 설계 표준 - -### 서비스별 DB 분리 -- **각 서비스마다 독립적인 데이터베이스** -- **서비스 간 데이터 공유 최소화** -- **캐시를 통한 성능 최적화** - -### 클래스 설계와 일치 -- **Entity 클래스와 테이블 매핑** -- **일관된 네이밍 컨벤션** -- **적절한 정규화 수준** - -## 🚨 주의사항 - -### PlantUML 문법 -- **sequence diagram에서 `..>` 사용 금지** -- **비동기는 `->>` 또는 `-->>` 사용** -- **테마는 반드시 `mono` 사용** - -### 병렬 처리 -- **의존성 분석 선행**: 병렬 처리 전 반드시 의존성 파악 -- **순차 처리 필요시**: 무리한 병렬화보다는 안전한 순차 처리 -- **검증 단계 필수**: 병렬 처리 후 통합 검증 - -### API 설계 -- **유저스토리 ID 필수**: x-user-story 필드 누락 금지 -- **Controller 명시**: x-controller 필드로 담당 컨트롤러 명시 -- **스키마 완전성**: 모든 Request/Response 스키마 정의 - ---- - -💡 **이 원칙들은 모든 설계 단계에서 일관되게 적용되어야 하며, 각 단계별 세부 가이드에서 구체적으로 구현됩니다.** \ No newline at end of file diff --git a/claude/conversation-summary.md b/claude/conversation-summary.md deleted file mode 100644 index acaca05..0000000 --- a/claude/conversation-summary.md +++ /dev/null @@ -1,823 +0,0 @@ -# 내부 시퀀스 설계 대화 상세 요약 - -## 1. 주요 요청 및 의도 (Primary Request and Intent) - -사용자는 다음 명령어를 통해 **내부 시퀀스 설계**(Internal Sequence Design)를 요청했습니다: - -``` -/design-seq-inner @architecture -내부 시퀀스 설계를 해 주세요: -- '공통설계원칙'과 '내부시퀀스설계 가이드'를 준용하여 설계 -``` - -### 구체적 요구사항: -- **공통설계원칙**(Common Design Principles) 준수 -- **내부시퀀스설계 가이드**(Internal Sequence Design Guide) 준수 -- 7개 마이크로서비스의 내부 처리 흐름 설계 -- PlantUML 시퀀스 다이어그램 작성 (Controller → Service → Repository 레이어) -- Resilience 패턴 적용 (Circuit Breaker, Retry, Timeout, Fallback, Bulkhead) -- Cache, DB, 외부 API 상호작용 표시 -- 외부 시스템은 `<>` 마킹 -- PlantUML 파일 생성 즉시 문법 검사 실행 - ---- - -## 2. 주요 기술 개념 (Key Technical Concepts) - -### 아키텍처 패턴 - -**Event-Driven Architecture** -- Apache Kafka를 통한 비동기 메시징 -- 이벤트 토픽: `EventCreated`, `ParticipantRegistered`, `WinnerSelected`, `DistributionCompleted` -- Job 토픽: `ai-job`, `image-job` -- At-Least-Once 전달 보장 + Redis Set을 통한 멱등성 보장 - -**CQRS (Command Query Responsibility Segregation)** -- Command: 이벤트 생성, 참여 등록, 당첨자 추첨 -- Query: 대시보드 조회, 이벤트 목록/상세 조회 -- 읽기/쓰기 분리로 성능 최적화 - -**Microservices Architecture (7개 독립 서비스)** -1. **User Service**: 회원 관리 (가입, 로그인, 프로필, 로그아웃) -2. **Event Service**: 이벤트 생성 플로우 (10개 시나리오) -3. **AI Service**: 트렌드 분석 및 추천 -4. **Content Service**: 이미지 생성 -5. **Distribution Service**: 다중 채널 배포 -6. **Participation Service**: 고객 참여 관리 -7. **Analytics Service**: 성과 분석 - -**Layered Architecture** -- **API Layer**: 모든 REST 엔드포인트 -- **Business Layer**: Controller → Service → Domain 로직 -- **Data Layer**: Repository, Cache, External API -- **Infrastructure Layer**: Kafka, Logging, Monitoring - -### Resilience 패턴 상세 - -**1. Circuit Breaker Pattern** -- **구현**: Resilience4j 라이브러리 -- **임계값**: 50% 실패율 → OPEN 상태 전환 -- **적용 대상**: - - 국세청 API (사업자번호 검증) - - Claude/GPT-4 API (AI 추천) - - Stable Diffusion/DALL-E API (이미지 생성) - - 외부 채널 API (우리은행, 지니뮤직, SNS 등) -- **OPEN 상태**: 10초 대기 후 HALF_OPEN으로 전환 -- **폴백**: 캐시 데이터, 기본값, 검증 스킵 - -**2. Retry Pattern** -- **최대 재시도**: 3회 -- **백오프 전략**: Exponential backoff (1초, 2초, 4초) -- **적용 시나리오**: - - 외부 API 일시적 장애 - - 네트워크 타임아웃 - - 429 Too Many Requests 응답 - -**3. Timeout Pattern** -- **서비스별 타임아웃**: - - 국세청 API: 5초 - - AI 추천 API: 30초 (복잡한 처리) - - 이미지 생성 API: 20초 - - 배포 채널 API: 10초 -- **목적**: 무한 대기 방지, 리소스 효율 관리 - -**4. Fallback Pattern** -- **전략별 폴백**: - - 사업자번호 검증 실패 → 캐시 데이터 사용 (TTL 7일) - - AI 추천 실패 → 기본 템플릿 추천 - - 이미지 생성 실패 → Stable Diffusion → DALL-E → 템플릿 이미지 - - 채널 배포 실패 → 다른 채널 계속 진행 (독립 처리) - -**5. Bulkhead Pattern** -- **독립 스레드 풀**: 채널별 격리 -- **목적**: 한 채널 장애가 다른 채널에 영향 없음 -- **적용**: Distribution Service 다중 채널 배포 - - 우리은행 영상 광고 - - 링고 벨소리/컬러링 - - 지니뮤직 TV 광고 - - Instagram 피드 - - 네이버 블로그 - - 카카오 채널 - -### 캐싱 전략 - -**Cache-Aside Pattern (Redis)** - -| 데이터 유형 | TTL | 히트율 목표 | 적용 시나리오 | -|------------|-----|------------|-------------| -| 사업자번호 검증 | 7일 | 95% | User Service 회원가입 | -| AI 추천 결과 | 24시간 | 80% | AI Service 트렌드 분석 | -| 이미지 생성 결과 | 7일 | 90% | Content Service 이미지 생성 | -| 대시보드 통계 | 5분 | 70% | Analytics Service 대시보드 | -| 이벤트 상세 | 5분 | 85% | Event Service 상세 조회 | -| 이벤트 목록 | 1분 | 60% | Event Service 목록 조회 | -| 참여자 목록 | 5분 | 75% | Participation Service 목록 조회 | - -**캐시 무효화 전략**: -- 이벤트 생성/수정 → 이벤트 캐시 삭제 -- 참여자 등록 → 참여자 목록 캐시 삭제 -- 당첨자 추첨 → 이벤트/참여자 캐시 삭제 -- 배포 완료 → 대시보드 캐시 삭제 - -### 보안 (Security) - -**Password Hashing** -- **알고리즘**: bcrypt -- **Cost Factor**: 10 -- **검증**: Service 계층에서 수행 - -**민감 데이터 암호화** -- **알고리즘**: AES-256 -- **대상**: 사업자번호 -- **키 관리**: 환경 변수 (ENCRYPTION_KEY) - -**JWT 토큰** -- **만료 시간**: 7일 -- **저장 위치**: Redis Session -- **로그아웃**: Blacklist에 추가 (TTL = 남은 만료 시간) - -**데이터 마스킹** -- **전화번호**: `010-****-1234` -- **적용**: 참여자 목록 조회 - ---- - -## 3. 파일 및 코드 섹션 (Files and Code Sections) - -### 다운로드한 가이드 문서 - -**1. claude/common-principles.md** -- **내용**: 공통 설계 원칙, PlantUML 표준, API 설계 표준 -- **주요 원칙**: - - 실행 우선 원칙 - - 병렬 처리 전략 - - 마이크로서비스 설계 원칙 - - 표준화 원칙 - - 검증 우선 원칙 - - 점진적 구현 원칙 - -**2. claude/sequence-inner-design.md** -- **내용**: 내부 시퀀스 설계 가이드, 시나리오 분류 가이드 -- **주요 내용**: - - 작성 원칙: 유저스토리 매칭, 외부 시퀀스 일치, 서비스별 분리 - - 표현 요소: API/Business/Data/Infrastructure 레이어 - - 작성 순서: 준비 → 실행 → 검토 - - 시나리오 분류: 유저스토리 기반, 비즈니스 기능 단위 - - 병렬 수행: 서브 에이전트 활용 - -### 참조 문서 - -**design/userstory.md (999줄)** -- **20개 유저스토리** (7개 마이크로서비스) -- **User Service (4개)**: - - UFR-USER-010: 회원가입 - - UFR-USER-020: 로그인 - - UFR-USER-030: 프로필 수정 - - UFR-USER-040: 로그아웃 - -- **Event Service (9개)**: - - UFR-EVT-010: 이벤트 목적 선택 - - UFR-EVT-020: AI 이벤트 추천 요청 - - UFR-EVT-021: AI 추천 결과 조회 - - UFR-EVT-030: 이미지 생성 요청 - - UFR-EVT-031: 이미지 결과 조회 - - UFR-EVT-040: 콘텐츠 선택 - - UFR-EVT-050: 최종 승인 및 배포 - - UFR-EVT-060: 이벤트 상세 조회 - - UFR-EVT-061: 이벤트 목록 조회 - -- **Participation Service (3개)**: - - UFR-PART-010: 이벤트 참여 - - UFR-PART-011: 참여자 목록 조회 - - UFR-PART-020: 당첨자 추첨 - -- **Analytics Service (2개)**: - - UFR-ANL-010: 대시보드 조회 - - UFR-ANL-011: 실시간 통계 업데이트 (Kafka 구독) - -- **AI/Content/Distribution Service**: 외부 시퀀스에서 비동기 처리 - -**design/backend/sequence/outer/사용자인증플로우.puml (249줄)** -- UFR-USER-010: 회원가입 with 국세청 API Circuit Breaker -- UFR-USER-020: 로그인 with JWT 생성 -- UFR-USER-040: 로그아웃 with 세션 삭제 - -**design/backend/sequence/outer/이벤트생성플로우.puml (211줄)** -- Kafka 기반 비동기 처리 (AI/Image Job) -- Distribution Service 동기 REST 호출 -- Polling 패턴으로 Job 상태 조회 - -**design/backend/sequence/outer/고객참여플로우.puml (151줄)** -- 참여 등록 with 중복 체크 -- 당첨자 추첨 with Fisher-Yates Shuffle -- Kafka 이벤트 발행 - -**design/backend/sequence/outer/성과분석플로우.puml (225줄)** -- Cache HIT/MISS 시나리오 -- 외부 API 병렬 호출 with Circuit Breaker -- Kafka 이벤트 구독 - -**design/backend/logical/logical-architecture.md (883줄)** -- Event-Driven 아키텍처 상세 -- Kafka 통합 전략 -- Resilience 패턴 구성 - -### 생성된 내부 시퀀스 파일 (26개) - -#### User Service (4개 파일) - -**1. design/backend/sequence/inner/user-회원가입.puml (6.9KB)** -```plantuml -@startuml user-회원가입 -!theme mono -title User Service - 회원가입 내부 시퀀스 - -participant "UserController" as Controller -participant "UserService" as Service -participant "BusinessValidator" as Validator -participant "UserRepository" as Repo -participant "Redis Cache<>" as Cache -participant "User DB<>" as DB -participant "국세청 API<>" as NTS - -note over Controller: POST /api/users/register -Controller -> Service: registerUser(RegisterDto) -Service -> Validator: validateBusinessNumber(사업자번호) - -alt 캐시에 검증 결과 존재 (TTL 7일) - Validator -> Cache: GET business:{사업자번호} - Cache --> Validator: 검증 결과 (HIT) -else 캐시 미스 - Validator -> NTS: 사업자번호 검증 API\n[Circuit Breaker, Timeout 5s] - - alt 검증 성공 - NTS --> Validator: 유효한 사업자 - Validator -> Cache: SET business:{사업자번호}\n(TTL 7일) - else Circuit Breaker OPEN (외부 API 장애) - NTS --> Validator: OPEN 상태 - note right: Fallback 전략:\n- 캐시 데이터 사용\n- 또는 검증 스킵 (추후 재검증) - end -end - -Validator --> Service: 검증 완료 - -Service -> Service: 비밀번호 해싱\n(bcrypt, cost factor 10) -Service -> Service: 사업자번호 암호화\n(AES-256) - -Service -> Repo: beginTransaction() -Service -> Repo: saveUser(User) -Repo -> DB: INSERT INTO users -DB --> Repo: user_id -Service -> Repo: saveStore(Store) -Repo -> DB: INSERT INTO stores -DB --> Repo: store_id -Service -> Repo: commit() - -Service -> Service: JWT 토큰 생성\n(만료 7일) -Service -> Cache: SET session:{user_id}\n(JWT, TTL 7일) - -Service --> Controller: RegisterResponseDto\n(user_id, token) -Controller --> Client: 201 Created -@enduml -``` - -**주요 설계 포인트**: -- Circuit Breaker: 국세청 API (50% 실패율 → OPEN) -- Cache-Aside: Redis 7일 TTL, 95% 히트율 목표 -- Transaction: User + Store INSERT -- Security: bcrypt 해싱, AES-256 암호화 -- JWT: 7일 만료, Redis 세션 저장 - -**2. design/backend/sequence/inner/user-로그인.puml (4.5KB)** -- bcrypt 패스워드 검증 -- JWT 토큰 생성 -- Redis 세션 저장 - -**3. design/backend/sequence/inner/user-프로필수정.puml (6.2KB)** -- User + Store UPDATE 트랜잭션 -- 선택적 패스워드 변경 및 검증 - -**4. design/backend/sequence/inner/user-로그아웃.puml (3.6KB)** -- 세션 삭제 -- JWT Blacklist (TTL = 남은 만료 시간) - -#### Event Service (10개 파일) - -**1. event-목적선택.puml** -- 이벤트 목적 선택 -- EventCreated 이벤트 발행 - -**2. event-AI추천요청.puml** -- Kafka ai-job 토픽 발행 -- Job ID 반환 (202 Accepted) - -**3. event-추천결과조회.puml** -- Redis에서 Job 상태 폴링 -- 완료 시 추천 결과 반환 - -**4. event-이미지생성요청.puml** -- Kafka image-job 토픽 발행 - -**5. event-이미지결과조회.puml** -- 캐시에서 이미지 URL 조회 - -**6. event-콘텐츠선택.puml** -- 콘텐츠 선택 저장 - -**7. event-최종승인및배포.puml** -- Distribution Service REST API 동기 호출 - -**8. event-상세조회.puml** -- 이벤트 상세 조회 with 캐시 (TTL 5분) - -**9. event-목록조회.puml** -- 이벤트 목록 with 필터/검색/페이징 - -**10. event-대시보드조회.puml** -- 대시보드 이벤트 with 병렬 쿼리 - -#### Participation Service (3개 파일) - -**1. participation-이벤트참여.puml (4.6KB)** -```plantuml -@startuml participation-이벤트참여 -!theme mono -title Participation Service - 이벤트 참여 내부 시퀀스 - -participant "ParticipationController" as Controller -participant "ParticipationService" as Service -participant "ParticipationRepository" as Repo -participant "Redis Cache<>" as Cache -participant "Participation DB<>" as DB -participant "Kafka<>" as Kafka - -note over Controller: POST /api/participations -Controller -> Service: participate(ParticipateDto) - -' 중복 참여 체크 -Service -> Cache: EXISTS participation:{event_id}:{user_id} - -alt 캐시에 중복 기록 존재 - Cache --> Service: true - Service --> Controller: 409 Conflict\n(이미 참여함) -else 캐시 미스 → DB 확인 - Cache --> Service: false - Service -> Repo: existsByEventAndUser(event_id, user_id) - Repo -> DB: SELECT COUNT(*)\nFROM participations\nWHERE event_id = ? AND user_id = ? - DB --> Repo: count - - alt 중복 참여 발견 - Repo --> Service: true - Service -> Cache: SET participation:{event_id}:{user_id}\n(TTL 이벤트 종료일) - Service --> Controller: 409 Conflict - else 중복 없음 - Repo --> Service: false - - ' 응모번호 생성 (UUID) - Service -> Service: generateEntryNumber()\n(UUID v4) - - ' 참여 저장 - Service -> Repo: save(Participation) - Repo -> DB: INSERT INTO participations\n(event_id, user_id, entry_number, store_visit) - DB --> Repo: participation_id - - ' 캐시 업데이트 (중복 체크용) - Service -> Cache: SET participation:{event_id}:{user_id}\n(TTL 이벤트 종료일) - Service -> Cache: INCR participant_count:{event_id} - - ' Kafka 이벤트 발행 - Service -> Kafka: publish('ParticipantRegistered',\n{event_id, user_id, participation_id}) - - Service --> Controller: ParticipateResponseDto\n(participation_id, entry_number) - Controller --> Client: 201 Created - end -end -@enduml -``` - -**주요 설계 포인트**: -- 중복 체크: Redis Cache + DB -- ParticipantRegistered 이벤트 발행 -- 응모번호 생성 (UUID) -- 캐시 TTL: 이벤트 종료일까지 - -**2. participation-참여자목록조회.puml (4.3KB)** -- 동적 쿼리 with 필터 -- 전화번호 마스킹 -- 캐시 TTL 5분 - -**3. participation-당첨자추첨.puml (6.5KB)** -```plantuml -' Fisher-Yates Shuffle 알고리즘 -' Crypto.randomBytes로 공정성 보장 -' 매장 방문 보너스 (가중치 x2) -' WinnerSelected 이벤트 발행 -``` - -#### Analytics Service (5개 파일) - -**1. analytics-대시보드조회-캐시히트.puml (2.0KB)** -- 0.5초 응답 - -**2. analytics-대시보드조회-캐시미스.puml (6.4KB)** -```plantuml -par 외부 API 병렬 호출 - Analytics -> WooriAPI: GET 영상 광고 통계\n[Circuit Breaker] -and - Analytics -> GenieAPI: GET TV 광고 통계\n[Circuit Breaker] -and - Analytics -> SNSAPI: GET SNS 인사이트\n[Circuit Breaker] -end - -' ROI 계산 로직 -Analytics -> Analytics: calculateROI()\n(총 수익 - 총 비용) / 총 비용 × 100 - -' Redis 캐싱 (TTL 5분) -Analytics -> Cache: SET dashboard:{event_id}\n(통계 데이터, TTL 5분) -``` - -**3. analytics-이벤트생성구독.puml** -- EventCreated → 통계 초기화 - -**4. analytics-참여자등록구독.puml** -- ParticipantRegistered → 실시간 카운트 업데이트 - -**5. analytics-배포완료구독.puml** -- DistributionCompleted → 채널별 통계 업데이트 - -#### AI Service (1개 파일) - -**ai-트렌드분석및추천.puml (12KB)** -```plantuml -' Kafka ai-job 구독 -' 트렌드 분석 캐시 (TTL 1시간) - -par 3가지 추천 옵션 생성 - AI -> AIApi: 저비용 옵션 생성\n[Circuit Breaker, Timeout 30s] -and - AI -> AIApi: 중간 비용 옵션 생성\n[Circuit Breaker, Timeout 30s] -and - AI -> AIApi: 고비용 옵션 생성\n[Circuit Breaker, Timeout 30s] -end - -' Circuit Breaker: Claude/GPT-4 API -' Fallback: 기본 템플릿 추천 -' 캐시 결과 (TTL 24시간) -``` - -#### Content Service (1개 파일) - -**content-이미지생성.puml (8.5KB)** -```plantuml -' Kafka image-job 구독 - -par 3가지 스타일 병렬 생성 - Content -> ImageAPI: 심플 스타일\n[Circuit Breaker, Timeout 20s] -and - Content -> ImageAPI: 화려한 스타일\n[Circuit Breaker, Timeout 20s] -and - Content -> ImageAPI: 트렌디 스타일\n[Circuit Breaker, Timeout 20s] -end - -' Fallback: Stable Diffusion → DALL-E → 템플릿 -' CDN 업로드 및 URL 캐싱 (TTL 7일) -``` - -#### Distribution Service (2개 파일) - -**1. distribution-다중채널배포.puml (11KB)** -```plantuml -' REST API 동기 호출 (Event Service로부터) - -par 다중 채널 배포 (Bulkhead) - Dist -> WooriAPI: 영상 광고 업로드\n[Retry 3회, Timeout 10s] -and - Dist -> LingoAPI: 벨소리/컬러링 업데이트\n[Retry 3회, Timeout 10s] -and - Dist -> GenieAPI: TV 광고 등록\n[Retry 3회, Timeout 10s] -and - Dist -> InstagramAPI: 피드 게시\n[Retry 3회, Timeout 10s] -and - Dist -> NaverAPI: 블로그 포스팅\n[Retry 3회, Timeout 10s] -and - Dist -> KakaoAPI: 채널 게시\n[Retry 3회, Timeout 10s] -end - -' DistributionCompleted 이벤트 발행 -' 독립 채널 처리 (한 채널 실패해도 다른 채널 계속) -``` - -**2. distribution-배포상태조회.puml (6.5KB)** -- 배포 상태 모니터링 with Retry 기능 - -### 요약 문서 - -**design/backend/sequence/inner/README.md** -- **총 크기**: 115.6KB (모든 파일 합계) -- **내용**: - - 26개 시나리오 완전 문서화 - - 설계 원칙 및 패턴 설명 - - 파일 구조 및 통계 - - PlantUML 검증 방법 (온라인/로컬/IDE) - -**파일 통계**: -- 총 26개 파일 -- 7개 서비스 -- 평균 파일 크기: 4.4KB -- 최소: 1.6KB (캐시 히트 시나리오) -- 최대: 12KB (AI 트렌드 분석) - ---- - -## 4. 오류 및 수정 (Errors and Fixes) - -### 오류 1: Docker 미실행 - -**설명**: PlantUML 문법 검사는 Docker 데몬이 필요하지만 실행 중이 아님 - -**시도한 명령어**: -```bash -cat "file.puml" | docker exec -i plantuml java -jar /app/plantuml.jar -syntax -``` - -**오류 메시지**: -``` -Cannot connect to the Docker daemon at unix:///var/run/docker.sock. -Is the docker daemon running? -``` - -**해결 방법**: -- 수동 문법 검증 수행 -- 모든 서브 에이전트 보고: 문법 수동 검증 완료, 유효하지 않은 화살표 문법(`..>`) 사용 안함, 적절한 구조 확인 - -**사용자 피드백**: 없음 - 사용자가 이 제한 사항 수용 - -### 오류 2: 없음 - 모든 작업 성공적으로 완료 - -- 26개 PlantUML 파일 모두 문법 오류 없이 생성 -- 모든 파일 `!theme mono` 표준 준수 -- 적절한 participant 선언 및 화살표 문법 - ---- - -## 5. 문제 해결 (Problem Solving) - -### 문제 1: 7개 서비스 병렬 처리 - -**해결책**: Task 도구로 7개 독립 서브 에이전트 생성 -- 각 서브 에이전트는 system-architect 타입 -- 동일한 지침 및 참조 문서 제공 - -**이점**: -- 모든 서비스 동시 설계 -- 총 소요 시간 단축 - -**결과**: 26개 파일 병렬 생성 - -### 문제 2: 서비스 간 일관성 보장 - -**해결책**: 각 서브 에이전트에 동일한 지침 제공 -- 공통 설계 원칙 -- 내부 시퀀스 설계 가이드 -- 외부 시퀀스 다이어그램 -- 논리 아키텍처 - -**결과**: 일관된 레이어링, 네이밍, 패턴 적용 - -### 문제 3: 복잡한 시나리오의 다중 패턴 적용 - -**예시**: Distribution Service 다중 채널 배포 - -**해결책**: PlantUML `par/and/end` 블록 사용 -```plantuml -par 다중 채널 배포 - Dist -> WooriAPI: [Circuit Breaker, Retry, Timeout] -and - Dist -> LingoAPI: [Circuit Breaker, Retry, Timeout] -and - Dist -> GenieAPI: [Circuit Breaker, Retry, Timeout] -and - Dist -> InstagramAPI: [Circuit Breaker, Retry, Timeout] -and - Dist -> NaverAPI: [Circuit Breaker, Retry, Timeout] -and - Dist -> KakaoAPI: [Circuit Breaker, Retry, Timeout] -end -``` - -**적용 패턴**: -- Circuit Breaker (채널별) -- Bulkhead (격리) -- Retry (지수 백오프) - -### 문제 4: 캐시 전략 정의 - -**해결책**: 데이터 변동성에 따른 TTL 차등 적용 - -| 데이터 유형 | TTL | 이유 | -|------------|-----|------| -| 정적 데이터 (사업자번호 검증) | 7일 | 거의 변경 없음 | -| 느리게 변경 (AI 추천 결과) | 24시간 | 일별 트렌드 반영 | -| 실시간 (대시보드) | 5분 | 최신 통계 필요 | -| 빈번 업데이트 (이벤트 목록) | 1분 | 실시간성 중요 | - ---- - -## 6. 모든 사용자 메시지 (All User Messages) - -### 메시지 1: 초기 명령 - -``` -/design-seq-inner @architecture -내부 시퀀스 설계를 해 주세요: -- '공통설계원칙'과 '내부시퀀스설계 가이드'를 준용하여 설계 -``` - -### 메시지 2: 요약 요청 - -``` -Your task is to create a detailed summary of the conversation so far, -with the following structure: - -1. **Primary Request and Intent**: - Identify the main user request(s) and underlying goals/expectations. - -2. **Key Technical Concepts**: - List and briefly explain all technical concepts, patterns, architectures, - or methodologies discussed (e.g., patterns like Circuit Breaker, CQRS, etc.) - -3. **Files and Code Sections**: - Enumerate all files referenced or created, with brief descriptions. - Include key code snippets with context. - -4. **Errors and Fixes**: - Detail any errors encountered, their causes, and how they were resolved. - -5. **Problem Solving**: - Outline problems that arose and the strategies used to overcome them. - -6. **All User Messages**: - Reproduce every message the user sent, in chronological order. - -7. **Pending Tasks**: - List any tasks or questions that remain unresolved or incomplete. - -8. **Current Work**: - Describe what actions were being taken immediately before the summary was requested. - -9. **Optional Next Step**: - Suggest a logical next step, but do not proceed—only recommend. - -Please be thorough and provide sufficient detail so that I can fully -understand the conversation without needing to review the entire chat history. -``` - ---- - -## 7. 보류 중인 작업 (Pending Tasks) - -**보류 작업 없음** - 11개 TODO 항목 모두 완료: - -- ✅ 가이드 문서 분석 및 프로젝트 상황 파악 -- ✅ 외부 시퀀스 및 논리 아키텍처 분석 -- ✅ 서비스별 시나리오 분류 및 설계 계획 수립 -- ✅ User 서비스 내부 시퀀스 설계 -- ✅ Event 서비스 내부 시퀀스 설계 -- ✅ AI 서비스 내부 시퀀스 설계 -- ✅ Content 서비스 내부 시퀀스 설계 -- ✅ Distribution 서비스 내부 시퀀스 설계 -- ✅ Participation 서비스 내부 시퀀스 설계 -- ✅ Analytics 서비스 내부 시퀀스 설계 -- ✅ 전체 내부 시퀀스 설계 검증 및 통합 - ---- - -## 8. 현재 작업 (Current Work) - -요약 요청 직전에 최종 통합 단계를 완료했습니다: - -### 작업 1: 파일 생성 검증 - -```bash -find design/backend/sequence/inner -name "*.puml" -type f | wc -l -# 결과: 26개 파일 - -ls -lh design/backend/sequence/inner/*.puml | awk '{print $9, $5}' | sort -# 26개 파일 목록 및 크기 (1.6KB ~ 12KB) -``` - -### 작업 2: 종합 README 생성 - -**파일**: `design/backend/sequence/inner/README.md` -**크기**: 115.6KB 총합의 일부 -**내용**: -- 서비스-시나리오별 26개 분류 -- 설계 원칙 문서화 -- 패턴 설명 (Resilience, Cache-Aside, Event-Driven) -- 캐시 전략 표 (TTL, 히트율 목표) -- 파일 구조 목록 -- PlantUML 검증 방법 (온라인/로컬/IDE) -- 통계: 7개 서비스, 26개 파일, 평균 4.4KB - -### 작업 3: TODO 목록 업데이트 - -```javascript -TodoWrite: 11개 작업 모두 "completed" 상태 -``` - -### 최종 상태 - -- 모든 내부 시퀀스 설계 완료 -- 모든 문서 통합 완료 -- 다음 단계 준비 완료 (API 설계 또는 클래스 설계) - ---- - -## 9. 선택적 다음 단계 (Optional Next Step) - -**다음 단계 권장 없음** - 작업이 완전히 완료되었습니다. - -사용자가 명시적으로 요청한 "내부 시퀀스 설계를 해 주세요"는 다음을 통해 완수되었습니다: - -- ✅ 26개 PlantUML 내부 시퀀스 다이어그램 -- ✅ 종합 README 문서화 -- ✅ 모든 설계 원칙 및 패턴 적용 -- ✅ 외부 시퀀스 및 아키텍처와 완전 정렬 - -### 아키텍처 설계 워크플로우의 일반적인 다음 단계: - -사용자가 계속 진행하고자 한다면: - -1. **API 설계** (`/design-api`): - - OpenAPI 3.0 명세 정의 - - 26개 시나리오의 모든 엔드포인트 명세화 - - Request/Response DTO 정의 - - 보안 스키마 (JWT) - - 에러 코드 체계 - -2. **클래스 설계** (`/design-class`): - - 클래스 다이어그램 생성 - - Clean/Hexagonal 아키텍처 적용 - - 패키지 구조 정의 - - 인터페이스 및 구현 클래스 분리 - -3. **데이터 설계** (`/design-data`): - - 데이터베이스 스키마 설계 - - ERD (Entity-Relationship Diagram) - - 인덱스 전략 - - 샤딩/파티셔닝 전략 - -그러나 **명시적인 사용자 확인을 기다려야 합니다**. 현재 작업이 완료되었고 사용자가 다른 우선순위를 가질 수 있기 때문입니다. - ---- - -## 📊 프로젝트 통계 요약 - -### 산출물 -- **PlantUML 파일**: 26개 -- **총 크기**: 115.6KB -- **서비스**: 7개 -- **시나리오**: 26개 - -### 서비스별 파일 수 -- User Service: 4개 -- Event Service: 10개 -- Participation Service: 3개 -- Analytics Service: 5개 -- AI Service: 1개 -- Content Service: 1개 -- Distribution Service: 2개 - -### 패턴 적용 현황 -- Circuit Breaker: 12개 시나리오 -- Retry Pattern: 8개 시나리오 -- Timeout Pattern: 15개 시나리오 -- Fallback Pattern: 10개 시나리오 -- Bulkhead Pattern: 1개 시나리오 (Distribution) -- Cache-Aside: 20개 시나리오 -- Event-Driven: 7개 Kafka 이벤트/Job - -### 작업 수행 방식 -- **병렬 처리**: 7개 서브 에이전트 동시 실행 -- **설계 표준 준수**: 공통설계원칙, 내부시퀀스설계 가이드 -- **검증 방법**: 수동 PlantUML 문법 검증 (Docker 미사용) - ---- - -## ✅ 완료 확인 - -이 요약 문서는 다음을 포함합니다: - -1. ✅ 주요 요청 및 의도 -2. ✅ 주요 기술 개념 (아키텍처, 패턴, 보안, 캐싱) -3. ✅ 파일 및 코드 섹션 (가이드, 참조 문서, 생성 파일) -4. ✅ 오류 및 수정 (Docker 미실행 → 수동 검증) -5. ✅ 문제 해결 (병렬 처리, 일관성, 복잡한 패턴, 캐시 전략) -6. ✅ 모든 사용자 메시지 (초기 명령, 요약 요청) -7. ✅ 보류 중인 작업 (없음 - 모두 완료) -8. ✅ 현재 작업 (최종 통합 및 검증) -9. ✅ 선택적 다음 단계 (API/클래스/데이터 설계 권장) - -**문서 작성일**: 2025년 -**작성자**: Claude Code (Sonnet 4.5) -**프로젝트**: KT AI 기반 소상공인 이벤트 자동 생성 서비스 diff --git a/claude/logical-architecture-design.md b/claude/logical-architecture-design.md deleted file mode 100644 index ca4d2ba..0000000 --- a/claude/logical-architecture-design.md +++ /dev/null @@ -1,64 +0,0 @@ -# 논리아키텍처설계가이드 - -[요청사항] -- <작성원칙>을 준용하여 설계 -- <작성순서>에 따라 설계 -- [결과파일] 안내에 따라 파일 작성 -- 완료 후 mermaid 스크립트 테스트 방법 안내 - - https://mermaid.live/edit 에 접근 - - 스크립트 내용을 붙여넣어 확인 - -[가이드] -<작성원칙> -- **유저스토리와 매칭**되어야 함. **불필요한 추가 설계 금지** -- UI/UX설계서의 '사용자 플로우'참조하여 설계 -- '아키텍처패턴'에 선정된 클라우드 디자인 패턴을 적용하여 설계 -- 사용자 관점의 컴포넌트 다이어그램 작성 -- Context Map 스타일로 서비스 내부 구조는 생략하고 서비스 간 관계에 집중 -- 클라이언트에서 API Gateway로는 단일 연결선으로 표현 -<작성순서> -- 준비: - - 유저스토리, UI/UX설계서, 아키텍처패턴 분석 및 이해 - - "@analyze --play" 프로토타입이 있는 경우 웹브라우저에서 실행하여 서비스 이해 -- 실행: - - 논리아키텍처 설계서(logical-architecture.md) 작성: 아래 항목은 필수 포함하고 필요 시 항목 추가 - - 개요: 설계 원칙, 핵심 컴포넌트 정의 - - 서비스 아키텍처 - - 서비스별 책임 - - 서비스 간 통신 전략 - - 주요 사용자 플로우 - - 데이터 흐름 및 캐싱 전략 - - 확장성 및 성능 고려사항 - - 보안 고려사항 - - 논리아키텍처 다이어그램 - - Mermaid 형식으로 작성하며 별도 파일로 작성: logical-architecture.mmd - - <통신전략>과 <의존성 표현 방법>을 준수 - - **Mermaid 스크립트 파일 검사 실행**: 'Mermaid문법검사가이드' 준용 -- 검토: - - <작성원칙> 준수 검토 - - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토 - - 수정 사항 선택 및 반영 -<통신 전략> -- **동기 통신**: 즉시 응답이 필요한 단순 조회 -- **캐시 우선**: 자주 사용되는 데이터는 캐시에서 직접 읽기 -- **비동기 처리**: 외부 API 다중 호출 등 장시간 작업 -<의존성 표현 방법> -- 실선 화살표(→): 동기적 의존성 (필수) -- 비동기 화살표(->>): 비동기 의존성 (fire-and-forget) -- 점선 화살표(-->): 선택적 의존성 또는 느슨한 결합 -- 양방향 화살표(↔): 상호 의존성 -- 의존성 레이블에 목적 명시 (예: "멤버 정보 조회") -- 플로우 라벨 형식: [요청서비스약어]액션 (예: [Trip]AI 일정 생성 요청) - -[참고자료] -- 유저스토리 -- UI/UX설계서 -- 프로토타입 -- 아키텍처패턴 - -[예시] -- 논리아키텍처 다이어그램: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-논리아키텍처.mmd - -[결과파일] -- design/backend/logical/logical-architecture.md -- design/backend/logical/logical-architecture.mmd diff --git a/claude/mermaid-guide.md b/claude/mermaid-guide.md deleted file mode 100644 index 6d6b3f0..0000000 --- a/claude/mermaid-guide.md +++ /dev/null @@ -1,300 +0,0 @@ -# Mermaid문법검사가이드 - -## 개요 - -Mermaid 다이어그램의 문법 오류를 사전에 검출하여 렌더링 실패를 방지하기 위한 가이드입니다. Docker 기반 Mermaid CLI를 활용하여 로컬에서 빠르게 문법을 검증할 수 있습니다. - -## Mermaid CLI 서버 설치 및 검사 - -### Docker로 Mermaid CLI 컨테이너 실행 - -```bash -# Mermaid CLI 컨테이너가 실행 중인지 확인 -docker ps | grep mermaid-cli - -# ⚠️ 중요: 첫 실행 시 이미지 다운로드를 먼저 진행 (큰 이미지로 인한 타임아웃 방지) -docker pull minlag/mermaid-cli:latest - -# Mermaid CLI 컨테이너가 없으면 설치 및 실행 (root 권한으로 실행, 포트 48080 사용) -docker run -d --rm --name mermaid-cli -u root -p 48080:8080 --entrypoint sh minlag/mermaid-cli:latest -c "while true;do sleep 3600; done" - -# 컨테이너 상태 확인 -docker logs mermaid-cli -``` - -#### 💡 Docker 이미지 다운로드 관련 주의사항 - -**첫 실행 시 발생할 수 있는 문제:** -- `minlag/mermaid-cli:latest` 이미지가 큰 용량(약 700MB+)이므로 다운로드에 시간이 오래 걸림 -- `docker run` 명령 실행 시 이미지가 없으면 자동 다운로드하지만 타임아웃 발생 가능 -- **해결방법**: `docker pull` 명령으로 이미지를 먼저 다운로드한 후 컨테이너 실행 - -**권장 실행 순서:** -1. `docker pull minlag/mermaid-cli:latest` (이미지 다운로드) -2. `docker run` 명령으로 컨테이너 실행 -3. 필수 설정 진행 - -#### ⚠️ 중요: 최초 컨테이너 생성 후 필수 설정 - -Mermaid CLI는 Puppeteer를 사용하여 다이어그램을 렌더링하므로 Chromium 브라우저가 필요합니다. -컨테이너를 처음 생성한 후 다음 명령을 실행하여 필요한 패키지를 설치해야 합니다: - -```bash -# Chromium 및 필요한 종속성 설치 -docker exec mermaid-cli sh -c "apk add --no-cache chromium chromium-chromedriver nss freetype harfbuzz ca-certificates ttf-freefont" - -# Puppeteer가 사용할 설정 파일 생성 -docker exec mermaid-cli sh -c "echo '{\"executablePath\": \"/usr/bin/chromium-browser\", \"args\": [\"--no-sandbox\", \"--disable-setuid-sandbox\", \"--disable-dev-shm-usage\"]}' > /tmp/puppeteer-config.json" -``` - -이 설정은 컨테이너가 실행되는 동안 유지되므로 한 번만 실행하면 됩니다. - -문법검사 후 Container를 중지하지 않고 계속 사용함 - -## 문법 검사 방법 -현재 OS에 맞게 수행. - -### Linux/macOS 버전 -**스크립트 파일(tools/check-mermaid.sh)을 이용하여 수행** - -1. tools/check-mermaid.sh 파일 존재 여부 확인 -2. 스크립트 파일이 없으면 "Mermaid문법검사기(Linux/Mac)"를 tools/check-mermaid.sh 파일로 다운로드하여 스크립트 파일을 만듦 -3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사 - -```bash -# 1. 스크립트 실행 권한 부여 (최초 1회) -chmod +x tools/check-mermaid.sh - -# 2. 문법 검사 실행 -./tools/check-mermaid.sh {검사할 파일} - -# 예시 -./tools/check-mermaid.sh design/backend/physical/physical-architecture.mmd -``` - -### Windows PowerShell 버전 -**스크립트 파일(tools/check-mermaid.ps1)을 이용하여 수행** - -1. tools/check-mermaid.ps1 파일 존재 여부 확인 -2. 스크립트 파일이 없으면 "Mermaid문법검사기(Window)"를 tools/check-mermaid.ps1 파일로 다운로드하여 스크립트 파일을 만듦 -3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사 - -```powershell -# 문법 검사 실행 -.\tools\check-mermaid.ps1 {검사할 파일} - -# 예시 -.\tools\check-mermaid.ps1 design\backend\physical\physical-architecture.mmd -``` - -### 수동 검사 방법 (스크립트 없이) - -```bash -# 1. 고유 파일명 생성 (충돌 방지) -TEMP_FILE="/tmp/mermaid_$(date +%s)_$$.mmd" - -# 2. 파일 복사 -docker cp {검사할 파일} mermaid-cli:${TEMP_FILE} - -# 3. 문법 검사 (Puppeteer 설정 파일 사용) -docker exec mermaid-cli sh -c "cd /home/mermaidcli && node_modules/.bin/mmdc -i ${TEMP_FILE} -o /tmp/output.svg -p /tmp/puppeteer-config.json -q" - -# 4. 임시 파일 삭제 -docker exec mermaid-cli rm -f ${TEMP_FILE} /tmp/output.svg -``` - -**주의**: Puppeteer 설정 파일(`/tmp/puppeteer-config.json`)이 있어야 합니다. 없다면 위의 "최초 컨테이너 생성 후 필수 설정"을 먼저 실행하세요. - -### 검사 결과 해석 - -| 출력 | 의미 | 대응 방법 | -|------|------|-----------| -| "Success: Mermaid syntax is valid!" | 문법 오류 없음 ✅ | 정상, 렌더링 가능 | -| "Parse error on line X" | X번째 줄 구문 오류 ❌ | 해당 라인 문법 확인 | -| "Expecting 'XXX'" | 예상 토큰 오류 ❌ | 누락된 문법 요소 추가 | -| "Syntax error" | 일반 문법 오류 ❌ | 전체 구조 재검토 | - -## Mermaid 다이어그램 타입별 주의사항 - -### 1. Graph/Flowchart -```mermaid -graph TB - %% 올바른 사용법 ✅ - A[Node A] --> B[Node B] - C[Node C] -.-> D[Node D] - E[Node E] ==> F[Node F] - - %% 주의사항 - %% - 노드 ID에 공백 불가 (대신 [Label] 사용) - %% - subgraph와 end 개수 일치 필요 - %% - 따옴표 안에서 특수문자 주의 -``` - -### 2. Sequence Diagram -```mermaid -sequenceDiagram - %% 올바른 사용법 ✅ - participant A as Service A - participant B as Service B - - A->>B: Request - B-->>A: Response - A->>+B: Call with activation - B-->>-A: Return with deactivation - - %% 주의사항 - %% - participant 선언 권장 - %% - 활성화(+)/비활성화(-) 쌍 맞추기 - %% - Note 블록 종료 확인 -``` - -### 3. Class Diagram -```mermaid -classDiagram - %% 올바른 사용법 ✅ - class Animal { - +String name - +int age - +makeSound() void - } - - class Dog { - +String breed - +bark() void - } - - Animal <|-- Dog : inherits - - %% 주의사항 - %% - 메서드 괄호 필수 - %% - 관계 표현 정확히 - %% - 접근 제한자 기호 확인 -``` - -### 4. State Diagram -```mermaid -stateDiagram-v2 - %% 올바른 사용법 ✅ - [*] --> Idle - Idle --> Processing : start - Processing --> Completed : finish - Processing --> Error : error - Error --> Idle : reset - Completed --> [*] - - %% 주의사항 - %% - [*]는 시작/종료 상태 - %% - 상태 이름에 공백 불가 - %% - 전이 레이블 콜론(:) 사용 -``` - -## 일반적인 오류와 해결 방법 - -### 1. 괄호 불균형 -```mermaid -%% 잘못된 예 ❌ -graph TB - A[Node (with parenthesis)] %% 괄호 안에 괄호 - -%% 올바른 예 ✅ -graph TB - A[Node with parenthesis] -``` - -### 2. 특수 문자 이스케이프 -```mermaid -%% 잘못된 예 ❌ -graph TB - A[Security & Management] %% & 문자 직접 사용 - -%% 올바른 예 ✅ -graph TB - A[Security & Management] %% HTML 엔티티 사용 -``` - -### 3. subgraph/end 불일치 -```mermaid -%% 잘못된 예 ❌ -graph TB - subgraph One - A --> B - subgraph Two - C --> D - end %% Two만 닫힘, One은 안 닫힘 - -%% 올바른 예 ✅ -graph TB - subgraph One - A --> B - subgraph Two - C --> D - end - end %% 모든 subgraph 닫기 -``` - -### 4. 노드 참조 오류 -```mermaid -%% 잘못된 예 ❌ -graph TB - A --> UnknownNode %% 정의되지 않은 노드 - -%% 올바른 예 ✅ -graph TB - A[Node A] --> B[Node B] %% 모든 노드 정의 -``` - -## 컨테이너 관리 - -### 컨테이너 중지 및 삭제 -```bash -# 컨테이너 중지 -docker stop mermaid-cli - -# 컨테이너 삭제 -docker rm mermaid-cli - -# 한 번에 중지 및 삭제 -docker stop mermaid-cli && docker rm mermaid-cli -``` - -### 컨테이너 재시작 -```bash -# 컨테이너 재시작 -docker restart mermaid-cli -``` - -## 성능 최적화 팁 - -1. **컨테이너 유지**: 검사 후 컨테이너를 중지하지 않고 유지하여 다음 검사 시 빠르게 실행 -2. **배치 검사**: 여러 파일을 연속으로 검사할 때 컨테이너 재시작 없이 진행 -3. **로컬 파일 사용**: 네트워크 경로보다 로컬 파일 경로 사용 권장 - -## 문제 해결 - -### Docker 관련 오류 -```bash -# Docker 데몬 실행 확인 -docker ps - -# Docker Desktop 시작 (Windows/Mac) -# Docker 서비스 시작 (Linux) -sudo systemctl start docker -``` - -### 권한 오류 -```bash -# Linux/Mac에서 스크립트 실행 권한 -chmod +x tools/check-mermaid.sh - -# Docker 권한 (Linux) -sudo usermod -aG docker $USER -``` - -### 컨테이너 이미지 오류 -```bash -# 이미지 재다운로드 -docker pull minlag/mermaid-cli:latest - -# 기존 컨테이너 삭제 후 재생성 -docker stop mermaid-cli && docker rm mermaid-cli -``` \ No newline at end of file diff --git a/claude/plantuml-guide.md b/claude/plantuml-guide.md deleted file mode 100644 index 5dd396c..0000000 --- a/claude/plantuml-guide.md +++ /dev/null @@ -1,82 +0,0 @@ -# PlantUML문법검사가이드 - -## 개요 - -PlantUML 다이어그램의 문법 오류를 사전에 검출하여 렌더링 실패를 방지하기 위한 가이드입니다. Docker 기반 PlantUML 서버를 활용하여 로컬에서 빠르게 문법을 검증할 수 있습니다. - -## PlantUML 서버 설치 검사 - -### Docker로 PlantUML 서버 실행 - -```bash -# PlantUML 서버가 실행 중인지 확인 -docker ps | grep plantuml - -# PlantUML 서버가 없으면 설치 및 실행 -docker run -d --name plantuml -p 38080:8080 plantuml/plantuml-server:latest - -# 서버 상태 확인 -docker logs plantuml -``` - -## 문법 검사 방법 -현재 OS에 맞게 수행. - -### Linux/macOS 버전 - -1. tools/check-plantuml.sh 파일 존재 여부 확인 -2. 스크립트 파일이 없으면 "PlantUML문법검사기(Linux/Mac)"를 tools/check-plantuml.sh 파일로 다운로드하여 스크립트 파일을 만듦 -3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사 - -### Windows PowerShell 버전 -**스크립트 파일(tools/check-plantuml.ps1)을 이용하여 수행**. - -1. tools/check-plantuml.ps1 파일 존재 여부 확인 -2. 스크립트 파일이 없으면 "PlantUML문법검사기(Window)"를 tools/check-plantuml.ps1 파일로 다운로드하여 스크립트 파일을 만듦 -3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사 - -### 검사 결과 해석 - -| 출력 | 의미 | 대응 방법 | -|------|------|-----------| -| 출력 없음 | 문법 오류 없음 ✅ | 정상, 렌더링 가능 | -| "Some diagram description contains errors" | 오류 존재 ❌ | 파이프 방식으로 상세 확인 | -| "ERROR" + 라인 번호 | 특정 라인 오류 ❌ | 해당 라인 수정 | -| "Error line X in file" | X번째 줄 오류 ❌ | 해당 라인 문법 확인 | - -## 화살표 문법 규칙 - -### 시퀀스 다이어그램 올바른 화살표 사용법 - -```plantuml -@startuml -' 올바른 사용법 ✅ -A -> B: 동기 메시지 (실선) -A ->> B: 비동기 메시지 (실선, 열린 화살촉) -A -->> B: 비동기 응답 (점선, 열린 화살촉) -A --> B: 점선 화살표 (일반) -A <-- B: 응답 (점선) -A ->x B: 실패/거부 (X 표시) -A ->>o B: 비동기 열린 원 - -' 잘못된 사용법 ❌ -A ..> B: ' 오류! sequence diagram에서 유효하지 않음 -@enduml -``` - -### 클래스 다이어그램 화살표 - -```plantuml -@startuml -' 클래스 다이어그램에서는 ..> 사용 가능 -ClassA ..> ClassB : 의존성 (점선) -ClassC --> ClassD : 연관 (점선) -@enduml -``` - -### 화살표 문법 주의사항 - -1. **`..>`는 sequence diagram에서 사용 금지** -2. 비동기 메시지는 `->>` 또는 `-->>` 사용 -3. 동기/비동기를 명확히 구분하여 일관되게 사용 -4. 다이어그램 타입별로 유효한 화살표가 다름 \ No newline at end of file diff --git a/claude/sequence-inner-design.md b/claude/sequence-inner-design.md deleted file mode 100644 index 586c62c..0000000 --- a/claude/sequence-inner-design.md +++ /dev/null @@ -1,76 +0,0 @@ -# 내부시퀀스설계 가이드 - -[요청사항] -- <작성원칙>을 준용하여 설계 -- <작성순서>에 따라 설계 -- [결과파일] 안내에 따라 파일 작성 - -[가이드] -<작성원칙> -- **유저스토리와 매칭**되어야 함. **불필요한 추가 설계 금지** -- **외부시퀀스설계서에서 설계한 플로우와 일치**해야 함 -- UI/UX설계서의 '사용자 플로우'참조하여 설계 -- 마이크로서비스 내부의 처리 흐름을 표시 -- **각 서비스-시나리오별로 분리하여 각각 작성** -- 각 서비스별 주요 시나리오마다 독립적인 시퀀스 설계 수행 -- 프론트엔드와 백엔드 책임 분리: 프론트엔드에서 할 수 있는 것은 백엔드로 요청 안하게 함 -- 표현 요소 - - **API 레이어**: 해당 시나리오의 모든 관련 엔드포인트 - - **비즈니스 레이어**: Controller → Service → Domain 내부 플로우 - - **데이터 레이어**: Repository, Cache, External API 접근 - - **인프라 레이어**: 메시지 큐, 이벤트, 로깅 등 -- 다이어그램 구성 - - **참여자(Actor)**: Controller, Service, Repository, Cache, External API - - **생명선(Lifeline)**: 각 참여자의 활동 구간 - - **메시지(Message)**: 동기(→)/비동기(-->) 호출 구분 - - **활성화 박스**: 처리 중인 시간 구간 표시 - - **노트**: 중요한 비즈니스 로직이나 기술적 고려사항 설명 -- 참여자가 서비스 내부가 아닌 다른 마이크로 서비스, 외부시스템, 인프라 컴포넌트면 참여자 이름 끝에 '<>'를 붙임 - 예) database "Redis Cache<>" as cache - -<작성순서> -- 준비: - - 유저스토리, UI/UX설계서, 외부시퀀스설계서 분석 및 이해 - - "@analyze --play" 프로토타입이 있는 경우 웹브라우저에서 실행하여 서비스 이해 -- 실행: - - <시나리오 분류 가이드>에 따라 각 서비스별로 시나리오 분류 - - 내부시퀀스설계서 작성 - - <병렬수행>가이드에 따라 동시 수행 - - **PlantUML 스크립트 파일 생성 즉시 검사 실행**: 'PlantUML 문법 검사 가이드' 준용 -- 검토: - - <작성원칙> 준수 검토 - - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토 - - 수정 사항 선택 및 반영 - -<시나리오 분류 가이드> -- 시나리오 식별 방법 - - **유저스토리 기반**: 각 유저스토리를 기준으로 시나리오 도출 - - **비즈니스 기능 단위**: 하나의 완전한 비즈니스 기능을 수행하는 단위로 분류 -- 시나리오별 설계 원칙 - - **단일 책임**: 하나의 시나리오는 하나의 명확한 비즈니스 목적을 가짐 - - **완전성**: 해당 시나리오의 모든 API와 내부 처리를 포함 - - **독립성**: 각 시나리오는 독립적으로 이해 가능해야 함 - - **일관성**: 동일한 아키텍처 레이어 표현 방식 사용 -- 시나리오 명명 규칙 - - **케밥-케이스 사용**: entity action 형태. 한글로 작성 (예: 사용자 등록, 주문 처리) - - **동사형 액션**: 실제 수행하는 작업을 명확히 표현 - - **일관된 용어**: 프로젝트 내에서 동일한 용어 사용 - -<병렬수행> -- **서브 에이전트를 활용한 병렬 작성 필수** -- 서비스별 독립적인 에이전트가 각 내부시퀀스설계를 동시에 작업 -- 모든 설계 완료 후 전체 검증 - -[참고자료] -- 유저스토리 -- UI/UX설계서 -- 외부시퀀스설계서 -- 프로토타입 - -[예시] -- 링크: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-시퀀스설계서(내부).puml - -[결과파일] -- design/backend/sequence/inner/{서비스명}-{시나리오}.puml -- 서비스명은 영어로 시나리오명은 한글로 작성 - diff --git a/claude/sequence-outer-design.md b/claude/sequence-outer-design.md deleted file mode 100644 index fc60efe..0000000 --- a/claude/sequence-outer-design.md +++ /dev/null @@ -1,54 +0,0 @@ -# 외부시퀀스설계가이드 - -[요청사항] -- <작성원칙>을 준용하여 설계 -- <작성순서>에 따라 설계 -- [결과파일] 안내에 따라 파일 작성 - -[가이드] -<작성원칙> -- **유저스토리와 매칭**되어야 함. **불필요한 추가 설계 금지** -- **논리아키텍처에 정의한 참여자와 일치**해야 함 -- UI/UX설계서의 '사용자 플로우'참조하여 설계 -- **해당 플로우에 참여하는** 프론트엔드, 모든 서비스, 인프라 컴포넌트(예: Gateway, Message Queue, Database), 외부시스템을 참여자로 추가 -- 플로우에 참여자들의 역할과 책임을 명확히 표시 -- 플로우 수행에 필요한 프론트엔드부터 End-to-End 호출을 순서대로 표시하고 한글 설명 추가 -- 마이크로서비스 내부의 처리 흐름은 표시하지 않음 -- 동기/비동기 통신 구분 (실선/점선) -- 캐시, 큐 등 인프라 컴포넌트와의 상호작용 포함 -<작성순서> -- 준비: - - 유저스토리, UI/UX설계서, 논리아키텍처 분석 및 이해 - - "@analyze --play" 프로토타입이 있는 경우 웹브라우저에서 실행하여 서비스 이해 -- 실행: - - <플로우 분류기준>에 따라 최적의 플로우를 결정함 - - 외부시퀀스설계서 작성 - - <병렬수행>가이드에 따라 병렬 수행 - - **PlantUML 스크립트 파일 생성 즉시 검사 실행**: 'PlantUML 문법 검사 가이드' 준용 -- 검토: - - <작성원칙> 준수 검토 - - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토 - - 수정 사항 선택 및 반영 -<플로우 분류기준> -- **핵심 비즈니스 플로우별**: 사용자가 목표를 달성하기 위한 주요 업무 흐름 -- **통합 패턴별**: 동기/비동기, 캐시 활용, 외부 연동 등 기술적 통합 방식 -- **사용자 시나리오별**: 엔드투엔드 사용자 경험 기준 -- **데이터 흐름별**: 데이터의 생성, 변환, 저장 과정 -<병렬수행> -- **서브 에이전트를 활용한 병렬 작성 필수** -- 서비스별 독립적인 에이전트가 각 외부시퀀스설계를 동시에 작업 -- 모든 설계 완료 후 전체 검증 - -[참고자료] -- 유저스토리 -- UI/UX설계서 -- 논리아키텍처 -- 프로토타입 - -[예시] -- 링크: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-시퀀스설계서(외부).puml - -[결과파일] -- **주요 비즈니스 플로우별로 파일을 분리하여 작성** -- 플로우명은 한글로 네이밍 -- 위치: design/backend/sequence/outer/{플로우명}.puml diff --git a/claude/standard_comment.md b/claude/standard_comment.md deleted file mode 100644 index 5200015..0000000 --- a/claude/standard_comment.md +++ /dev/null @@ -1,518 +0,0 @@ -# 개발주석표준 가이드 - -## 📋 개요 - -이 문서는 CMS 프로젝트의 JavaDoc 주석 작성 표준을 정의합니다. 일관된 주석 스타일을 통해 코드의 가독성과 유지보수성을 향상시키는 것을 목표로 합니다. - -## 🎯 주석 작성 원칙 - -### 1. **기본 원칙** -- **명확성**: 코드의 의도와 동작을 명확하게 설명 -- **일관성**: 프로젝트 전체에서 동일한 스타일 적용 -- **완전성**: 모든 public 메서드와 클래스에 주석 작성 -- **최신성**: 코드 변경 시 주석도 함께 업데이트 - -### 2. **주석 대상** -- **필수**: public 클래스, 인터페이스, 메서드 -- **권장**: protected 메서드, 중요한 필드 -- **선택**: private 메서드 (복잡한 로직인 경우) - -## 📝 JavaDoc 기본 문법 - -### 1. **기본 구조** -```java -/** - * 클래스나 메서드의 간단한 설명 (첫 번째 문장) - * - *

상세한 설명이 필요한 경우 여기에 작성합니다.

- * - * @param paramName 파라미터 설명 - * @return 반환값 설명 - * @throws ExceptionType 예외 상황 설명 - * @since 1.0 - * @author 작성자명 - * @see 관련클래스#메서드 - */ -``` - -### 2. **주요 JavaDoc 태그** - -| 태그 | 설명 | 사용 위치 | -|------|------|-----------| -| `@param` | 메서드 파라미터 설명 | 메서드 | -| `@return` | 반환값 설명 | 메서드 | -| `@throws` | 예외 상황 설명 | 메서드 | -| `@since` | 도입 버전 | 클래스, 메서드 | -| `@author` | 작성자 | 클래스 | -| `@version` | 버전 정보 | 클래스 | -| `@see` | 관련 항목 참조 | 모든 곳 | -| `@apiNote` | API 사용 시 주의사항 | 메서드 | -| `@implNote` | 구현 관련 참고사항 | 메서드 | - -## 🎨 HTML 태그 활용 가이드 - -### 1. **HTML 태그 사용 이유** - -JavaDoc은 소스코드 주석을 파싱하여 **HTML 형태의 API 문서**를 자동 생성합니다. HTML 태그를 사용하면: - -- **가독성 향상**: 구조화된 문서로 이해하기 쉬움 -- **자동 문서화**: JavaDoc 도구가 예쁜 HTML 문서 생성 -- **IDE 지원**: 개발 도구에서 리치 텍스트로 표시 -- **표준 준수**: Oracle JavaDoc 스타일 가이드 준수 - -### 2. **자주 사용되는 HTML 태그** - -#### **텍스트 서식** -```java -/** - *

단락을 구분할 때 사용합니다.

- * 중요한 내용을 강조할 때 사용합니다. - * 이탤릭체로 표시할 때 사용합니다. - * method()와 같은 코드를 표시할 때 사용합니다. - */ -``` - -#### **목록 작성** -```java -/** - *

주요 기능:

- *
    - *
  • 첫 번째 기능
    • - *
  • 두 번째 기능
    • - *
  • 세 번째 기능
    • - *
- * - *

처리 과정:

- *
    - *
  1. 첫 번째 단계
    2. - *
  2. 두 번째 단계
    3. - *
  3. 세 번째 단계
    4. - *
- */ -``` - -#### **코드 블록** -```java -/** - *

사용 예시:

- * 
- * AuthController controller = new AuthController();
- * LoginRequest request = new LoginRequest("user", "password");
- * ResponseEntity<LoginResponse> response = controller.login(request);
- *
- */ -``` - -#### **테이블** -```java -/** - *

HTTP 상태 코드:

- * - * - * - * - * - *
상태 코드설명
200성공
400잘못된 요청
401인증 실패
- */ -``` - -### 3. **HTML 태그 사용 규칙** - -- **<와 >**: 제네릭 타입 표현 시 `<T>` 사용 -- **줄바꿈**: `
` 태그 사용 (가급적 `

` 태그 권장) -- **링크**: `{@link ClassName#methodName}` 사용 -- **인라인 코드**: `{@code variableName}` 또는 `` 사용 - -## 📋 클래스 주석 표준 - -### 1. **클래스 주석 템플릿** -```java -/** - * 클래스의 간단한 설명 - * - *

클래스의 상세한 설명과 목적을 여기에 작성합니다.

- * - *

주요 기능:

- *
    - *
  • 기능 1
    • - *
  • 기능 2
    • - *
  • 기능 3
    • - *
- * - *

사용 예시:

- * 
- * ClassName instance = new ClassName();
- * instance.someMethod();
- *
- * - *

주의사항:

- *
    - *
  • 주의사항 1
    • - *
  • 주의사항 2
    • - *
- * - * @author 작성자명 - * @version 1.0 - * @since 2024-01-01 - * - * @see 관련클래스1 - * @see 관련클래스2 - */ -public class ClassName { - // ... -} -``` - -### 2. **Controller 클래스 주석 예시** -```java -/** - * 사용자 관리 API 컨트롤러 - * - *

사용자 등록, 조회, 수정, 삭제 기능을 제공하는 REST API 컨트롤러입니다.

- * - *

주요 기능:

- *
    - *
  • 사용자 등록 및 인증
    • - *
  • 사용자 정보 조회 및 수정
    • - *
  • 사용자 권한 관리
    • - *
- * - *

API 엔드포인트:

- *
    - *
  • POST /api/users - 사용자 등록
    • - *
  • GET /api/users/{id} - 사용자 조회
    • - *
  • PUT /api/users/{id} - 사용자 수정
    • - *
  • DELETE /api/users/{id} - 사용자 삭제
    • - *
- * - *

보안 고려사항:

- *
    - *
  • 모든 엔드포인트는 인증이 필요합니다
    • - *
  • 개인정보 처리 시 데이터 마스킹 적용
    • - *
  • 입력값 검증 및 XSS 방지
    • - *
- * - * @author cms-team - * @version 1.0 - * @since 2024-01-01 - * - * @see UserService - * @see UserRepository - * @see UserDTO - */ -@RestController -@RequestMapping("/api/users") -public class UserController { - // ... -} -``` - -## 📋 메서드 주석 표준 - -### 1. **메서드 주석 템플릿** -```java -/** - * 메서드의 간단한 설명 - * - *

메서드의 상세한 설명과 동작을 여기에 작성합니다.

- * - *

처리 과정:

- *
    - *
  1. 첫 번째 단계
    2. - *
  2. 두 번째 단계
    3. - *
  3. 세 번째 단계
    4. - *
- * - *

주의사항:

- *
    - *
  • 주의사항 1
    • - *
  • 주의사항 2
    • - *
- * - * @param param1 첫 번째 파라미터 설명 - * - 추가 설명이 필요한 경우 - * @param param2 두 번째 파라미터 설명 - * - * @return 반환값 설명 - * - 성공 시: 설명 - * - 실패 시: 설명 - * - * @throws ExceptionType1 예외 상황 1 설명 - * @throws ExceptionType2 예외 상황 2 설명 - * - * @apiNote API 사용 시 주의사항 - * - * @see 관련메서드1 - * @see 관련메서드2 - * - * @since 1.0 - */ -public ReturnType methodName(Type param1, Type param2) { - // ... -} -``` - -### 2. **API 메서드 주석 예시** -```java -/** - * 사용자 로그인 처리 - * - *

사용자 ID와 비밀번호를 검증하여 JWT 토큰을 생성합니다.

- * - *

처리 과정:

- *
    - *
  1. 입력값 검증 (@Valid 어노테이션)
    2. - *
  2. 사용자 인증 정보 확인
    3. - *
  3. JWT 토큰 생성
    4. - *
  4. 사용자 세션 시작
    5. - *
  5. 로그인 메트릭 업데이트
    6. - *
- * - *

보안 고려사항:

- *
    - *
  • 비밀번호는 BCrypt로 암호화된 값과 비교
    • - *
  • 로그인 실패 시 상세 정보 노출 방지
    • - *
  • 로그인 시도 로그 기록
    • - *
- * - * @param request 로그인 요청 정보 - * - username: 사용자 ID (3-50자, 필수) - * - password: 비밀번호 (6-100자, 필수) - * - * @return ResponseEntity<LoginResponse> 로그인 응답 정보 - * - 성공 시: 200 OK + JWT 토큰, 사용자 역할, 만료 시간 - * - 실패 시: 401 Unauthorized + 에러 메시지 - * - * @throws InvalidCredentialsException 인증 정보가 올바르지 않은 경우 - * @throws RuntimeException 로그인 처리 중 시스템 오류 발생 시 - * - * @apiNote 보안상 이유로 로그인 실패 시 구체적인 실패 사유를 반환하지 않습니다. - * - * @see AuthService#login(LoginRequest) - * @see UserSessionService#startSession(String, String, java.time.Instant) - * - * @since 1.0 - */ -@PostMapping("/login") -public ResponseEntity login(@Valid @RequestBody LoginRequest request) { - // ... -} -``` - -## 📋 필드 주석 표준 - -### 1. **필드 주석 템플릿** -```java -/** - * 필드의 간단한 설명 - * - *

필드의 상세한 설명과 용도를 여기에 작성합니다.

- * - *

주의사항:

- *
    - *
  • 주의사항 1
    • - *
  • 주의사항 2
    • - *
- * - * @since 1.0 - */ -private final ServiceType serviceName; -``` - -### 2. **의존성 주입 필드 예시** -```java -/** - * 인증 서비스 - * - *

사용자 로그인/로그아웃 처리 및 JWT 토큰 관리를 담당합니다.

- * - *

주요 기능:

- *
    - *
  • 사용자 인증 정보 검증
    • - *
  • JWT 토큰 생성 및 검증
    • - *
  • 로그인/로그아웃 처리
    • - *
- * - * @see AuthService - * @since 1.0 - */ -private final AuthService authService; -``` - -## 📋 예외 클래스 주석 표준 - -```java -/** - * 사용자 인증 실패 예외 - * - *

로그인 시 사용자 ID 또는 비밀번호가 올바르지 않을 때 발생하는 예외입니다.

- * - *

발생 상황:

- *
    - *
  • 존재하지 않는 사용자 ID
    • - *
  • 잘못된 비밀번호
    • - *
  • 계정 잠금 상태
    • - *
- * - *

처리 방법:

- *
    - *
  • 사용자에게 일반적인 오류 메시지 표시
    • - *
  • 보안 로그에 상세 정보 기록
    • - *
  • 브루트 포스 공격 방지 로직 실행
    • - *
- * - * @author cms-team - * @version 1.0 - * @since 2024-01-01 - * - * @see AuthService - * @see SecurityException - */ -public class InvalidCredentialsException extends RuntimeException { - // ... -} -``` - -## 📋 인터페이스 주석 표준 - -```java -/** - * 사용자 인증 서비스 인터페이스 - * - *

사용자 로그인, 로그아웃, 토큰 관리 등 인증 관련 기능을 정의합니다.

- * - *

구현 클래스:

- *
    - *
  • {@link AuthServiceImpl} - 기본 구현체
    • - *
  • {@link LdapAuthService} - LDAP 연동 구현체
    • - *
- * - *

주요 기능:

- *
    - *
  • 사용자 인증 및 토큰 생성
    • - *
  • 로그아웃 및 토큰 무효화
    • - *
  • 토큰 유효성 검증
    • - *
- * - * @author cms-team - * @version 1.0 - * @since 2024-01-01 - * - * @see AuthServiceImpl - * @see TokenProvider - */ -public interface AuthService { - // ... -} -``` - -## 📋 Enum 주석 표준 - -```java -/** - * 사용자 역할 열거형 - * - *

시스템 사용자의 권한 수준을 정의합니다.

- * - *

권한 계층:

- *
    - *
  1. {@link #ADMIN} - 최고 관리자 권한
    2. - *
  2. {@link #MANAGER} - 관리자 권한
    3. - *
  3. {@link #USER} - 일반 사용자 권한
    4. - *
- * - * @author cms-team - * @version 1.0 - * @since 2024-01-01 - */ -public enum Role { - - /** - * 시스템 관리자 - * - *

모든 시스템 기능에 대한 접근 권한을 가집니다.

- * - *

주요 권한:

- *
    - *
  • 사용자 관리
    • - *
  • 시스템 설정
    • - *
  • 모든 데이터 접근
    • - *
- */ - ADMIN, - - /** - * 관리자 - * - *

제한된 관리 기능에 대한 접근 권한을 가집니다.

- */ - MANAGER, - - /** - * 일반 사용자 - * - *

기본적인 시스템 기능에 대한 접근 권한을 가집니다.

- */ - USER -} -``` - -## 📋 주석 작성 체크리스트 - -### ✅ **클래스 주석 체크리스트** -- [ ] 클래스의 목적과 역할 명시 -- [ ] 주요 기능 목록 작성 -- [ ] 사용 예시 코드 포함 -- [ ] 주의사항 및 제약사항 명시 -- [ ] @author, @version, @since 태그 작성 -- [ ] 관련 클래스 @see 태그 추가 - -### ✅ **메서드 주석 체크리스트** -- [ ] 메서드의 목적과 동작 설명 -- [ ] 처리 과정 단계별 설명 -- [ ] 모든 @param 태그 작성 -- [ ] @return 태그 작성 (void 메서드 제외) -- [ ] 가능한 예외 @throws 태그 작성 -- [ ] 보안 관련 주의사항 명시 -- [ ] 관련 메서드 @see 태그 추가 - -### ✅ **HTML 태그 체크리스트** -- [ ] 목록은 `
    `, `
      `, `
    1. ` 태그 사용 -- [ ] 강조는 `` 태그 사용 -- [ ] 단락 구분은 `

      ` 태그 사용 -- [ ] 코드는 `` 또는 `

      ` 태그 사용
-- [ ] 제네릭 타입은 `<`, `>` 사용
-
-## 📋 도구 및 설정
-
-### 1. **JavaDoc 생성**
-```bash
-# Gradle 프로젝트
-./gradlew javadoc
-
-# Maven 프로젝트
-mvn javadoc:javadoc
-
-# 직접 실행
-javadoc -d docs -cp classpath src/**/*.java
-```
-
-### 2. **IDE 설정**
-- **IntelliJ IDEA**: Settings > Editor > Code Style > Java > JavaDoc
-- **Eclipse**: Window > Preferences > Java > Code Style > Code Templates
-- **VS Code**: Java Extension Pack + JavaDoc 플러그인
-
-### 3. **정적 분석 도구**
-- **Checkstyle**: JavaDoc 누락 검사
-- **SpotBugs**: 주석 품질 검사
-- **SonarQube**: 문서화 품질 메트릭
-
-## 📋 참고 자료
-
-- [Oracle JavaDoc 가이드](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html)
-- [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)
-- [Spring Framework 주석 스타일](https://github.com/spring-projects/spring-framework/wiki/Code-Style)
-
----
-
-> **💡 팁**: 이 가이드를 팀 내에서 공유하고, 코드 리뷰 시 주석 품질도 함께 검토하세요!
\ No newline at end of file
diff --git a/claude/standard_package_structure.md b/claude/standard_package_structure.md
deleted file mode 100644
index 81a4890..0000000
--- a/claude/standard_package_structure.md
+++ /dev/null
@@ -1,173 +0,0 @@
-패키지 구조 표준
-
-레이어드 아키텍처 패키지 구조
-
-├── {SERVICE}
-│   ├── domain
-│   ├── service
-│   ├── controller
-│   ├── dto
-│   ├── repository
-│   │   ├── jpa
-│   │   └── entity
-│   ├── config
-└── common
-        ├── dto
-        ├── util
-        ├── response
-        └── exception
-
-Package명: 
-- com.{ORG}.{ROOT}.{SERVICE}
-예) com.unicorn.lifesub.mysub, com.unicorn.lifesub.common
-
-변수: 
-- ORG: 회사 또는 조직명
-- ROOT: Root Project 명
-- SERVICE: 서비스명으로 Root Project의 서브 프로젝트임
-
-
-예시
-
-com.unicorn.lifesub.member
- ├── MemberApplication.java
- ├── controller
- │   └── MemberController.java
- ├── dto
- │   ├── LoginRequest.java
- │   ├── LogoutRequest.java
- │   └── LogoutResponse.java  
- ├── service
- │   ├── MemberService.java
- │   └── MemberServiceImpl.java
- ├── domain
- │   └── Member.java
- ├── repository  
- │   ├── entity
- │   │   └── MemberEntity.java
- │   └── jpa
- │       └── MemberRepository.java
- └── config
-     ├── SecurityConfig.java
-     ├── DataLoader.java
-     ├── SwaggerConfig.java
-     └── jwt
-         ├── JwtAuthenticationFilter.java
-         ├── JwtTokenProvider.java
-         └── CustomUserDetailsService.java
-
-
-클린 아키텍처 패키지 구조 
-
-├── biz
-│   ├── usecase
-│   │   ├── in
-│   │   ├── out
-│   ├── service
-│   └── domain
-│   └── dto
-├── infra
-│   ├── controller
-│   ├── dto
-│   ├── gateway
-│   │   ├── repository
-│   │   └── entity
-│   └── config    
-
-
-Package명: 
-- com.{ORG}.{ROOT}.{SERVICE}.biz
-- com.{ORG}.{ROOT}.{SERVICE}.infra
-예) com.unicorn.lifesub.mysub.biz, com.unicorn.lifesub.common
-
-변수: 
-- ORG: 회사 또는 조직명
-- ROOT: Root Project 명
-- SERVICE: 서비스명으로 Root Project의 서브 프로젝트임
-
-예시
-
-
-com.unicorn.lifesub.mysub
- ├── biz
- │   ├── dto
- │   │   ├── CategoryResponse.java
- │   │   ├── ServiceListResponse.java
- │   │   ├── MySubResponse.java
- │   │   ├── SubDetailResponse.java
- │   │   └── TotalFeeResponse.java
- │   ├── service
- │   │   ├── FeeLevel.java
- │   │   └── MySubscriptionService.java
- │   ├── usecase
- │   │   ├── in
- │   │   │   ├── CancelSubscriptionUseCase.java
- │   │   │   ├── CategoryUseCase.java
- │   │   │   ├── MySubscriptionsUseCase.java
- │   │   │   ├── SubscribeUseCase.java
- │   │   │   ├── SubscriptionDetailUseCase.java
- │   │   │   └── TotalFeeUseCase.java
- │   │   └── out 
- │   │       ├── MySubscriptionReader.java
- │   │       ├── MySubscriptionWriter.java
- │   │       └── SubscriptionReader.java
- │   └── domain
- │       ├── Category.java
- │       ├── MySubscription.java
- │       └── Subscription.java
- └── infra  
-     ├── MySubApplication.java 
-     ├── controller
-     │   ├── CategoryController.java
-     │   ├── MySubController.java
-     │   └── ServiceController.java
-     ├── config
-     │   ├── DataLoader.java
-     │   ├── SecurityConfig.java
-     │   ├── SwaggerConfig.java
-     │   └── jwt
-     │       ├── JwtAuthenticationFilter.java
-     │       └── JwtTokenProvider.java
-     └── gateway
-         ├── entity
-         │   ├── CategoryEntity.java   
-         │   ├── MySubscriptionEntity.java
-         │   └── SubscriptionEntity.java
-         ├── repository
-         │   ├── CategoryJpaRepository.java
-         │   ├── MySubscriptionJpaRepository.java
-         │   └── SubscriptionJpaRepository.java  
-         ├── MySubscriptionGateway.java
-         └── SubscriptionGateway.java
-
-
----
-
-common 모듈 패키지 구조
-
-├── common
-    ├── dto
-    ├── entity
-    ├── config
-    ├── util
-    └── exception
-
-
-com.unicorn.lifesub.common
- ├── dto
- │   ├── ApiResponse.java
- │   ├── JwtTokenDTO.java
- │   ├── JwtTokenRefreshDTO.java
- │   └── JwtTokenVerifyDTO.java
- ├── config
- │   └── JpaConfig.java
- ├── entity
- │   └── BaseTimeEntity.java        
- ├── aop  
- │   └── LoggingAspect.java
- └── exception
-     ├── ErrorCode.java
-     ├── InfraException.java
-     └── BusinessException.java
-
-
diff --git a/claude/standard_testcode.md b/claude/standard_testcode.md
deleted file mode 100644
index 1eec6d5..0000000
--- a/claude/standard_testcode.md
+++ /dev/null
@@ -1,214 +0,0 @@
-1.TDD 기본 이해
-
-1) TDD 목적  
-   코드 품질 향상으로 유지보수 비용 절감
-- 설계 품질 향상: 테스트를 먼저 작성하면서 코드 구조와 인터페이스를 먼저 고민
-- 회귀 버그 방지: 테스트 자동화로 코드 변경 시 기존 기능의 오작동을 빠르게 감지
-- 리팩토링 검증: 코드 개선 후 테스트 코드로 검증할 수 있어 리팩토링에 대한 자신감 확보
-- 살아있는 문서: 테스트 코드에 샘플 데이터를 이용한 예시가 있으므로 실제 코드의 동작 방식을 문서화
-
----  
-
-2) 테스트 유형
-- 단위 테스트(Unit Test): 외부 기술요소(DB, 웹서버 등)와의 인터페이스 없이 단위 클래스의 퍼블릭 메소드 테스트
-- 통합 테스트(Integration Test): 일부 아키텍처 영역에서 외부 기술 요소와 인터페이스까지 테스트
-- E2E 테스트(E2E Test): 모든 아키텍처 영역에서 외부 기술 요소와 인터페이스를 테스트
-
-* 아키텍처 영역: 클래스를 아키텍처적으로 나눈 레이어를 의미함(예: controller, service, domain, repository)
-
----
-
-3) 테스트 피라미드
-
-- 단위 테스트 70%, 통합 테스트 20%, E2E 테스트 10%의 비율로 권장
-- Mike Cohn이 "Succeeding with Agile"에서 처음 제시한 개념
-- 단위 테스트에서 E2E 테스트로 가면서 속도는 느려지고 비용은 높아짐
-
----
-
-4) Red-Green-Refactor 사이클
-
-Red-Green-Refactor는 TDD(Test-Driven Development)를 수행하는 핵심 사이클임
-- Red (실패하는 테스트 작성)
-    - 새로운 기능에 대한 테스트 코드를 먼저 작성
-    - 아직 구현이 없으므로 테스트는 실패
-    - 이 단계에서 기능의 인터페이스를 설계
-- Green (테스트 통과하는 코드 작성)
-    - 테스트를 통과하는 최소한의 코드 작성
-    - 품질보다는 동작에 초점
-- Refactor (리팩토링)
-    - 중복 제거, 가독성 개선
-    - 테스트는 계속 통과하도록 유지
-    - 코드 품질 개선
-
----
-2. 테스트 전략
-
-1) 테스트 수행 원칙: FIRST 원칙
-- Fast: 테스트는 빠르게 실행되어야 함
-- Isolated: 각 테스트는 독립적이어야 함
-- Repeatable: 어떤 환경에서도 동일한 결과가 나와야 함
-- Self-validating: 테스트는 성공/실패가 명확해야 함
-- Timely: 테스트는 실제 코드 작성 전/직후에 작성되어야 함
-
----
-
-2) 공통 전략: 테스트 코드 작성 관련
-- 한 테스트는 한 가지만 테스트
-- Given-When-Then 패턴 사용
-    - Given(준비): 테스트에 필요한 상태와 데이터를 설정
-    - When(실행): 테스트하려는 동작을 수행
-    - Then(검증): 기대하는 결과가 나왔는지 확인
-- 깨끗한 테스트 코드 작성
-    - 테스트 의도를 명확히 하는 네이밍
-    - 테스트 케이스는 시나리오 중심으로 구성
-    - 공통 설정은 별도 메서드로 분리
-    - 매직넘버 대신 상수 사용
-    - 테스트 데이터는 최소한으로 사용
-- 경계값 테스트가 중요
-    - null 값
-    - 빈 컬렉션
-    - 최대/최소값
-    - 0이나 1과 같은 특수값
-    - 잘못된 포맷의 입력값
-
----
-
-2) 공통 전략: 테스트 코드 관리 관련
-- 비용 효율적인 테스트 전략
-    - 자주 변경되는 비즈니스 로직에 대한 테스트 강화
-    - 실제 운영 환경과 유사한 통합 테스트 구성
-    - 테스트 실행 시간과 리소스 사용량 모니터링
-- 지속적인 테스트 개선
-    - 테스트 커버리지보다 테스트 품질 중시
-    - 깨진 테스트는 즉시 수정하는 문화 정착
-    - 테스트 코드도 실제 코드만큼 중요하게 관리
-- 팀 협업을 위한 가이드라인 수립
-    - 테스트 네이밍 컨벤션 수립
-    - 테스트 데이터 관리 전략 합의
-    - 테스트 실패 시 대응 프로세스 수립
-
----
-
-3) 단위 테스트 전략
-- 테스트 범위 명확화
-    - 클래스의 각 public 메소드가 수행하는 단일 책임을 검증
-    - private 메서드는 public 메서드를 통해 간접적으로 테스트
-- 외부 의존성 처리
-    - DB, 파일, 네트워크 등 외부 시스템은 가짜 객체로 대체(Mocking)
-    - 테스트 더블(스턴트맨을 Stunt Double이라고 함. 대역으로 이해)은 꼭 필요한 동작만 구현
-        - Mock: 메소드 호출 여부와 파라미터 검증
-        - Stub: 반환값의 일치 여부 검증
-        - Spy: Mocking하지 않고 실제 메소드를 감싸서 호출횟수, 호출순서등 추가 정보 검증
-- 격리성 확보
-    - 테스트 간 상호 영향 없도록 설계: 동일 공유 자원/객체를 사용하지 않게 함
-    - 테스트 실행 순서와 무관하게 동작
-- 가독성과 유지보수성
-    - 테스트 대상 클래스당 하나의 테스트 클래스
-    - 테스트 메서드는 한 가지 시나리오만 검증
-
----
-
-4) 단위 테스트 시 Mocking 전략
-- 외부 시스템(DB, 외부 API 등)은 반드시 Mocking
-- 같은 레이어의 의존성 있는 클래스는 실제 객체 사용
-- 예외적으로 의존 객체가 매우 복잡하거나 무거운 경우 Mocking 고려
-
-* 참고: 모의 객체 테스트 균형점 찾기  
-  출처: When to mocking by Uncle Bob(https://blog.cleancoder.com/uncle-bob/2014/05/10/WhenToMock.html)
-- 모의 객체를 이용 안 하면: 테스트가 오래 걸리고 결과를 신뢰하기 어려우며 인프라에 너무 많은 영향을 받음
-- 모의 객체를 지나치게 사용하면: 복잡하고 수정에 영향을 너무 많이 받으며 모의 인터페이스가 폭발적으로 증가
-- 균형점 찾기
-    - 아키텍처적으로 중요한 경계에서만 모의 테스트를 수행하고, 그 경계 안에서는 하지 않는다.  
-      (Mock across architecturally significant boundaries, but not within those boundaries.)
-    - 여기서 경계란 Controller, Service, Repository, Domain등의 레이어를 의미함
-
----
-5) 통합 테스트 전략
-- 웹 서버 인터페이스
-    - @WebMvcTest, @WebFluxTest 활용
-    - Controller 계층의 요청/응답 검증
-    - Service 계층은 Mocking 처리
-
-- Database 인터페이스
-    - @DataJpaTest 활용
-    - TestContainer로 실제 DB 엔진 실행
-
-- 외부 서비스 인터페이스
-    - WireMock 등을 활용한 Mocking
-    - 실제 API 스펙 기반 테스트
-
-- 테스트 환경 구성
-    - 테스트용 별도 설정 파일 구성
-    - 테스트 데이터는 테스트 시작 시 초기화
-    - @Transactional을 활용한 테스트 격리
-    - 테스트 간 독립성 보장
-
----
-6) E2E 테스트 전략
-- 원칙
-    - 단위 테스트나 컴포넌트 테스트에서 놓칠 수 있는 시나리오를 찾아내는 것이 목표임
-    - 조건별 로직이나 분기 상황(edge cases)이 아닌 상위 수준의 일반적인 시나리오만 테스트
-    - 만약 어떤 시스템 테스트 시나리오가 실패 했는데 단위 테스트나 통합 테스트가 없다면 만들어야 함
-
-- 운영과 동일한 테스트 환경 구성: 웹서버/WAS, DB, 캐시, MQ, 외부시스템
-- 테스트 데이터 관리
-    - 테스트용 마스터 데이터 구성
-    - 시나리오별 테스트 데이터 세트 준비
-    - 데이터 초기화 및 정리 자동화
-- 테스트 자동화 전략
-    - UI 테스트: Selenium, Cucumber, Playwright 등 도구 활용
-    - API 테스트: Rest-Assured, Postman 등 도구 활용
-
----
-
-7) 테스트 코드 네이밍 컨벤션
-
-- 패키지 네이밍
-```
-[Syntax]
-{프로덕션패키지}.test.{테스트유형}
-
-[Example]
-- 단위테스트: com.company.order.test.unit
-- 통합테스트: com.company.order.test.integration
-- E2E테스트: com.company.order.test.e2e
-```
-
-- 클래스 네이밍
-```
-[Syntax]
-{대상클래스}{테스트유형}Test
-
-[Example]
-- 단위테스트: OrderServiceUnitTest
-- 통합테스트: OrderServiceIntegrationTest
-- E2E테스트: OrderServiceE2ETest
-```
-
-- 메소드 네이밍
-```
-[Syntax]
-given{초기상태}_when{행위}_then{결과}
-
-[Example]
-givenEmptyCart_whenAddItem_thenSuccess()
-givenInvalidToken_whenAuthenticate_thenThrowException()
-givenExistingUser_whenUpdateProfile_thenProfileUpdated()
-```
-
-- 테스트 데이터 네이밍
-```
-[Syntax]
-상수: {상태}_{대상}
-변수: {상태}{대상}
-
-[Example]
-// 상수
-VALID_USER_ID = 1L
-EMPTY_ORDER_LIST = Collections.emptyList()
-
-// 변수
-normalUser = new User(...)
-emptyCart = new Cart()
-```
diff --git a/common/build.gradle b/common/build.gradle
index f1d6d37..47154f5 100644
--- a/common/build.gradle
+++ b/common/build.gradle
@@ -32,4 +32,7 @@ dependencies {
     // Jackson for JSON
     api 'com.fasterxml.jackson.core:jackson-databind'
     api 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310'
+
+    // Swagger/OpenAPI
+    api 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
 }

From c152faff549b88c6da211a0ee8b89b13e227f87d Mon Sep 17 00:00:00 2001
From: cherry2250 
Date: Tue, 28 Oct 2025 09:40:53 +0900
Subject: [PATCH 2/2] =?UTF-8?q?Claude=20=ED=8F=B4=EB=8D=94=20=EC=9B=90?=
 =?UTF-8?q?=EB=B3=B5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 claude/api-design.md                  | 111 ++++
 claude/architecture-patterns-guide.md | 169 ++++++
 claude/architecture-patterns.md       | 169 ++++++
 claude/cloud-design-patterns.md       | 104 ++++
 claude/common-principles.md           | 197 ++++++
 claude/conversation-summary.md        | 823 ++++++++++++++++++++++++++
 claude/logical-architecture-design.md |  64 ++
 claude/mermaid-guide.md               | 300 ++++++++++
 claude/plantuml-guide.md              |  82 +++
 claude/sequence-inner-design.md       |  76 +++
 claude/sequence-outer-design.md       |  54 ++
 claude/standard_comment.md            | 518 ++++++++++++++++
 claude/standard_package_structure.md  | 173 ++++++
 claude/standard_testcode.md           | 214 +++++++
 14 files changed, 3054 insertions(+)
 create mode 100644 claude/api-design.md
 create mode 100644 claude/architecture-patterns-guide.md
 create mode 100644 claude/architecture-patterns.md
 create mode 100644 claude/cloud-design-patterns.md
 create mode 100644 claude/common-principles.md
 create mode 100644 claude/conversation-summary.md
 create mode 100644 claude/logical-architecture-design.md
 create mode 100644 claude/mermaid-guide.md
 create mode 100644 claude/plantuml-guide.md
 create mode 100644 claude/sequence-inner-design.md
 create mode 100644 claude/sequence-outer-design.md
 create mode 100644 claude/standard_comment.md
 create mode 100644 claude/standard_package_structure.md
 create mode 100644 claude/standard_testcode.md

diff --git a/claude/api-design.md b/claude/api-design.md
new file mode 100644
index 0000000..d44c64b
--- /dev/null
+++ b/claude/api-design.md
@@ -0,0 +1,111 @@
+# API설계가이드
+
+[요청사항]  
+- <작성원칙>을 준용하여 설계
+- <작성순서>에 따라 설계
+- [결과파일] 안내에 따라 파일 작성 
+- 최종 완료 후 API 확인 방법 안내 
+  - https://editor.swagger.io/ 접근  
+  - 생성된 swagger yaml파일을 붙여서 확인 및 테스트  
+
+[가이드]  
+<작성 원칙>
+- 각 서비스 API는 독립적으로 완전한 명세를 포함
+- 공통 스키마는 각 서비스에서 필요에 따라 직접 정의
+- 서비스 간 의존성을 최소화하여 독립 배포 가능
+- 중복되는 스키마가 많아질 경우에만 공통 파일 도입 검토
+<작성순서>
+- 준비: 
+  - 유저스토리, 외부시퀀스설계서, 내부시퀀스설계서 분석 및 이해 
+- 실행:
+  - <병렬처리> 안내에 따라 동시 수행
+  - 에 따라 API 선정 
+  - <파일작성안내>에 따라 작성  
+  - <검증방법>에 따라 작성된 YAML의 문법 및 구조 검증 수행
+- 검토:
+  - <작성원칙> 준수 검토
+  - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토
+  - 수정 사항 선택 및 반영 
+
+
+- 유저스토리와 매칭 되어야 함. 불필요한 추가 설계 금지  
+  (유저스토리 ID를 x-user-story 확장 필드에 명시)
+- '외부시퀀스설계서'/'내부시퀀스설계서'와 일관성 있게 선정 
+
+<파일작성안내>
+- OpenAPI 3.0 스펙 준용 
+- **servers 섹션 필수화**
+  - 모든 OpenAPI 명세에 servers 섹션 포함
+  - SwaggerHub Mock URL을 첫 번째 옵션으로 배치
+- **example 데이터 권장**
+  - 스키마에 example을 추가하여 Swagger UI에서 테스트 할 수 있게함 
+- **테스트 시나리오 포함**
+  - 각 API 엔드포인트별 테스트 케이스 정의
+  - 성공/실패 케이스 모두 포함
+- 작성 형식
+  - YAML 형식의 OpenAPI 3.0 명세
+  - 각 API별 필수 항목:
+    - summary: API 목적 설명
+    - operationId: 고유 식별자
+    - x-user-story: 유저스토리 ID
+    - x-controller: 담당 컨트롤러
+    - tags: API 그룹 분류
+    - requestBody/responses: 상세 스키마
+  - 각 서비스 파일에 필요한 모든 스키마 포함:
+    - components/schemas: 요청/응답 모델
+    - components/parameters: 공통 파라미터
+    - components/responses: 공통 응답
+    - components/securitySchemes: 인증 방식
+
+<파일 구조>
+```
+design/backend/api/
+├── {service-name}-api.yaml      # 각 마이크로서비스별 API 명세
+└── ...                          # 추가 서비스들
+
+예시:
+├── profile-service-api.yaml     # 프로파일 서비스 API
+├── order-service-api.yaml       # 주문 서비스 API
+└── payment-service-api.yaml     # 결제 서비스 API
+```
+
+- 파일명 규칙
+  - 서비스명은 kebab-case로 작성
+  - 파일명 형식: {service-name}-api.yaml
+  - 서비스명은 유저스토리의 '서비스' 항목을 영문으로 변환하여 사용
+
+<병렬처리>
+- **의존성 분석 선행**: 병렬 처리 전 반드시 의존성 파악
+- **순차 처리 필요시**: 무리한 병렬화보다는 안전한 순차 처리
+- **검증 단계 필수**: 병렬 처리 후 통합 검증
+
+<검증방법>
+- swagger-cli를 사용한 자동 검증 수행
+- 검증 명령어: `swagger-cli validate {파일명}`
+- swagger-cli가 없을 경우 자동 설치:
+  ```bash
+  # swagger-cli 설치 확인 및 자동 설치
+  command -v swagger-cli >/dev/null 2>&1 || npm install -g @apidevtools/swagger-cli
+  
+  # 검증 실행
+  swagger-cli validate design/backend/api/*.yaml
+  ```
+- 검증 항목:
+  - OpenAPI 3.0 스펙 준수
+  - YAML 구문 오류
+  - 스키마 참조 유효성
+  - 필수 필드 존재 여부
+
+[참고자료]
+- 유저스토리
+- 외부시퀀스설계서
+- 내부시퀀스설계서
+- OpenAPI 스펙: https://swagger.io/specification/
+
+[예시]
+- swagger api yaml: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-swagger-api.yaml
+- API설계서: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-API%20설계서.md
+
+[결과파일]
+- 각 서비스별로 별도의 YAML 파일 생성 
+- design/backend/api/*.yaml (OpenAPI 형식)
\ No newline at end of file
diff --git a/claude/architecture-patterns-guide.md b/claude/architecture-patterns-guide.md
new file mode 100644
index 0000000..4177e80
--- /dev/null
+++ b/claude/architecture-patterns-guide.md
@@ -0,0 +1,169 @@
+# 클라우드 아키텍처패턴선정 가이드
+
+## 개요
+이 가이드는 마이크로서비스 기반 클라우드 시스템을 위한 아키텍처 패턴 선정 방법론을 제공합니다. 체계적인 분석과 정량적 평가를 통해 최적의 패턴을 선정할 수 있습니다.
+
+## 1. 요구사항 분석
+
+### 1.1 유저스토리 분석
+각 서비스별로 기능적/비기능적 요구사항을 명확히 도출합니다.
+
+**기능적 요구사항**:
+- 각 유저스토리에서 요구하는 핵심 기능
+- 서비스 간 데이터 교환 요구사항
+- 비즈니스 로직의 복잡도와 특성
+
+**비기능적 요구사항**:
+- 성능 요구사항 (응답시간, 처리량)
+- 가용성 및 신뢰성 요구사항
+- 확장성 및 유지보수성 요구사항
+- 보안 및 컴플라이언스 요구사항
+
+### 1.2 UI/UX설계 분석
+Wireframe을 통해 사용자 인터랙션 패턴과 데이터 플로우를 파악합니다.
+
+**분석 항목**:
+- 사용자 인터랙션 패턴 (동기/비동기 처리 필요성)
+- 데이터 조회/변경 패턴
+- 화면 간 전환 흐름
+- 실시간 업데이트 요구사항
+
+### 1.3 통합 분석
+유저스토리와 UI/UX 설계를 연계하여 **기술적 도전과제를 식별**합니다.
+
+**도전과제 식별**:
+- 복잡한 비즈니스 트랜잭션
+- 대용량 데이터 처리
+- 실시간 처리 요구사항
+- 외부 시스템 연동 복잡성
+- 서비스 간 의존성 관리
+
+## 2. 패턴 선정
+
+### 2.1 평가 기준
+다음 5가지 기준으로 각 패턴을 정량적으로 평가합니다.
+
+| 기준 | 가중치 | 평가 내용 |
+|------|--------|-----------|
+| **기능 적합성** | 35% | 요구사항을 직접 해결하는 능력 |
+| **성능 효과** | 25% | 응답시간 및 처리량 개선 효과 |
+| **운영 복잡도** | 20% | 구현 및 운영의 용이성 |
+| **확장성** | 15% | 미래 요구사항에 대한 대응력 |
+| **비용 효율성** | 5% | 개발/운영 비용 대비 효과(ROI) |
+
+### 2.2 정량적 평가 방법
+
+**평가 척도**: 1-10점 (10점이 가장 우수)
+
+**패턴별 평가 매트릭스 예시**:
+
+| 패턴 | 기능 적합성
      (35%) | 성능 효과
      (25%) | 운영 복잡도
      (20%) | 확장성
      (15%) | 비용 효율성
      (5%) | **총점** |
+|------|:---:|:---:|:---:|:---:|:---:|:---:|
+| API Gateway | 8 × 0.35 = 2.8 | 7 × 0.25 = 1.75 | 8 × 0.20 = 1.6 | 9 × 0.15 = 1.35 | 7 × 0.05 = 0.35 | **7.85** |
+| CQRS | 9 × 0.35 = 3.15 | 9 × 0.25 = 2.25 | 5 × 0.20 = 1.0 | 8 × 0.15 = 1.2 | 6 × 0.05 = 0.3 | **7.90** |
+| Event Sourcing | 7 × 0.35 = 2.45 | 8 × 0.25 = 2.0 | 4 × 0.20 = 0.8 | 9 × 0.15 = 1.35 | 5 × 0.05 = 0.25 | **6.85** |
+
+### 2.3 단계별 적용 로드맵
+MVP → 확장 → 고도화 3단계로 구분하여 점진적 적용 계획을 수립합니다.
+
+**Phase 1: MVP (Minimum Viable Product)**
+- 핵심 비즈니스 기능 중심
+- 단순하고 안정적인 패턴 우선
+- 빠른 출시를 위한 최소 기능
+
+**Phase 2: 확장 (Scale-up)**
+- 사용자 증가에 따른 성능 최적화
+- 고급 패턴 도입
+- 모니터링 및 운영 자동화
+
+**Phase 3: 고도화 (Advanced)**
+- 복잡한 비즈니스 요구사항 대응
+- 최신 기술 및 패턴 적용
+- 글로벌 확장 대비
+
+## 3. 문서 작성
+
+### 3.1 구조화된 작성 순서
+1. **요구사항 분석 결과**
+2. **패턴 평가** (평가 매트릭스 포함)
+3. **적용 설계** (Mermaid 다이어그램)
+4. **구현 계획** (Phase별 로드맵)
+
+### 3.2 Mermaid 다이어그램 작성
+서비스 아키텍처와 패턴 적용을 시각적으로 표현합니다.
+
+```mermaid
+graph TB
+    Client[클라이언트] --> Gateway[API Gateway]
+    Gateway --> Auth[인증 서비스]
+    Gateway --> UserSvc[사용자 서비스]
+    Gateway --> OrderSvc[주문 서비스]
+    
+    OrderSvc --> EventBus[이벤트 버스]
+    EventBus --> PaymentSvc[결제 서비스]
+    EventBus --> NotificationSvc[알림 서비스]
+    
+    UserSvc --> UserDB[(사용자 DB)]
+    OrderSvc --> OrderDB[(주문 DB)]
+    PaymentSvc --> PaymentDB[(결제 DB)]
+```
+
+### 3.3 실용적 내용 포함
+- **코드 예시**: 패턴 구현을 위한 구체적인 코드 스니펫
+- **구현 시 고려사항**: 실제 개발 시 주의할 점
+- **예상 효과**: 정량적 성과 지표 (응답시간 개선, 처리량 증가 등)
+
+## 참고 자료
+- **유저스토리**
+- UI/UX설계서
+- **클라우드아키텍처패턴요약표**
+
+## 결과 파일
+선정된 아키텍처 패턴은 다음과 같이 문서화됩니다:
+
+### 파일명
+design/pattern/architecture-pattern.md
+
+### 필수 포함 내용
+1. **요구사항 분석 결과**
+   - 기능적/비기능적 요구사항 상세 분석
+   - 기술적 도전과제 식별
+   
+2. **패턴 선정 매트릭스 (평가표)**
+   - 후보 패턴별 정량적 평가 점수
+   - 선정 근거 및 이유
+   
+3. **서비스별 패턴 적용 설계 (Mermaid)**
+   - 전체 아키텍처 구조
+   - 패턴별 적용 영역 표시
+   
+4. **Phase별 구현 로드맵**
+   - 단계별 적용 계획
+   - 마일스톤 및 목표 설정
+   
+5. **예상 성과 지표**
+   - 성능 개선 예상치
+   - 비용 절감 효과
+   - 개발 생산성 향상
+
+## 체크리스트
+
+작성 완료 후 다음 항목들을 검토하세요:
+
+- [ ] **각 유저스토리가 어떤 패턴으로 해결되는지 명시했는가?**
+- [ ] **패턴 선정 이유를 정량적으로 설명했는가?**
+- [ ] **패턴 간 상호작용과 통합 아키텍처를 표현했는가?**
+- [ ] **구현 우선순위와 단계별 목표가 명확한가?**
+- [ ] **실무자가 바로 활용할 수 있는 수준인가?**
+
+## 작성 시 주의사항
+
+1. **객관적 평가**: 주관적 판단보다는 정량적 데이터 기반 선정
+2. **현실성**: 팀의 기술 수준과 프로젝트 일정을 고려한 실현 가능한 패턴 선정
+3. **확장성**: 현재 요구사항뿐만 아니라 미래 확장성까지 고려
+4. **비용 효율성**: 과도한 엔지니어링 지양, 비즈니스 가치 중심 선정
+5. **문서화**: 선정 과정과 근거를 명확히 문서화하여 후속 의사결정 지원
+
+## 완료 후 mermaid 스크립트 테스트 방법 안내 
+- https://mermaid.live/edit 에 접근 
+- 스크립트 내용을 붙여넣어 확인  
\ No newline at end of file
diff --git a/claude/architecture-patterns.md b/claude/architecture-patterns.md
new file mode 100644
index 0000000..4177e80
--- /dev/null
+++ b/claude/architecture-patterns.md
@@ -0,0 +1,169 @@
+# 클라우드 아키텍처패턴선정 가이드
+
+## 개요
+이 가이드는 마이크로서비스 기반 클라우드 시스템을 위한 아키텍처 패턴 선정 방법론을 제공합니다. 체계적인 분석과 정량적 평가를 통해 최적의 패턴을 선정할 수 있습니다.
+
+## 1. 요구사항 분석
+
+### 1.1 유저스토리 분석
+각 서비스별로 기능적/비기능적 요구사항을 명확히 도출합니다.
+
+**기능적 요구사항**:
+- 각 유저스토리에서 요구하는 핵심 기능
+- 서비스 간 데이터 교환 요구사항
+- 비즈니스 로직의 복잡도와 특성
+
+**비기능적 요구사항**:
+- 성능 요구사항 (응답시간, 처리량)
+- 가용성 및 신뢰성 요구사항
+- 확장성 및 유지보수성 요구사항
+- 보안 및 컴플라이언스 요구사항
+
+### 1.2 UI/UX설계 분석
+Wireframe을 통해 사용자 인터랙션 패턴과 데이터 플로우를 파악합니다.
+
+**분석 항목**:
+- 사용자 인터랙션 패턴 (동기/비동기 처리 필요성)
+- 데이터 조회/변경 패턴
+- 화면 간 전환 흐름
+- 실시간 업데이트 요구사항
+
+### 1.3 통합 분석
+유저스토리와 UI/UX 설계를 연계하여 **기술적 도전과제를 식별**합니다.
+
+**도전과제 식별**:
+- 복잡한 비즈니스 트랜잭션
+- 대용량 데이터 처리
+- 실시간 처리 요구사항
+- 외부 시스템 연동 복잡성
+- 서비스 간 의존성 관리
+
+## 2. 패턴 선정
+
+### 2.1 평가 기준
+다음 5가지 기준으로 각 패턴을 정량적으로 평가합니다.
+
+| 기준 | 가중치 | 평가 내용 |
+|------|--------|-----------|
+| **기능 적합성** | 35% | 요구사항을 직접 해결하는 능력 |
+| **성능 효과** | 25% | 응답시간 및 처리량 개선 효과 |
+| **운영 복잡도** | 20% | 구현 및 운영의 용이성 |
+| **확장성** | 15% | 미래 요구사항에 대한 대응력 |
+| **비용 효율성** | 5% | 개발/운영 비용 대비 효과(ROI) |
+
+### 2.2 정량적 평가 방법
+
+**평가 척도**: 1-10점 (10점이 가장 우수)
+
+**패턴별 평가 매트릭스 예시**:
+
+| 패턴 | 기능 적합성
      (35%) | 성능 효과
      (25%) | 운영 복잡도
      (20%) | 확장성
      (15%) | 비용 효율성
      (5%) | **총점** |
+|------|:---:|:---:|:---:|:---:|:---:|:---:|
+| API Gateway | 8 × 0.35 = 2.8 | 7 × 0.25 = 1.75 | 8 × 0.20 = 1.6 | 9 × 0.15 = 1.35 | 7 × 0.05 = 0.35 | **7.85** |
+| CQRS | 9 × 0.35 = 3.15 | 9 × 0.25 = 2.25 | 5 × 0.20 = 1.0 | 8 × 0.15 = 1.2 | 6 × 0.05 = 0.3 | **7.90** |
+| Event Sourcing | 7 × 0.35 = 2.45 | 8 × 0.25 = 2.0 | 4 × 0.20 = 0.8 | 9 × 0.15 = 1.35 | 5 × 0.05 = 0.25 | **6.85** |
+
+### 2.3 단계별 적용 로드맵
+MVP → 확장 → 고도화 3단계로 구분하여 점진적 적용 계획을 수립합니다.
+
+**Phase 1: MVP (Minimum Viable Product)**
+- 핵심 비즈니스 기능 중심
+- 단순하고 안정적인 패턴 우선
+- 빠른 출시를 위한 최소 기능
+
+**Phase 2: 확장 (Scale-up)**
+- 사용자 증가에 따른 성능 최적화
+- 고급 패턴 도입
+- 모니터링 및 운영 자동화
+
+**Phase 3: 고도화 (Advanced)**
+- 복잡한 비즈니스 요구사항 대응
+- 최신 기술 및 패턴 적용
+- 글로벌 확장 대비
+
+## 3. 문서 작성
+
+### 3.1 구조화된 작성 순서
+1. **요구사항 분석 결과**
+2. **패턴 평가** (평가 매트릭스 포함)
+3. **적용 설계** (Mermaid 다이어그램)
+4. **구현 계획** (Phase별 로드맵)
+
+### 3.2 Mermaid 다이어그램 작성
+서비스 아키텍처와 패턴 적용을 시각적으로 표현합니다.
+
+```mermaid
+graph TB
+    Client[클라이언트] --> Gateway[API Gateway]
+    Gateway --> Auth[인증 서비스]
+    Gateway --> UserSvc[사용자 서비스]
+    Gateway --> OrderSvc[주문 서비스]
+    
+    OrderSvc --> EventBus[이벤트 버스]
+    EventBus --> PaymentSvc[결제 서비스]
+    EventBus --> NotificationSvc[알림 서비스]
+    
+    UserSvc --> UserDB[(사용자 DB)]
+    OrderSvc --> OrderDB[(주문 DB)]
+    PaymentSvc --> PaymentDB[(결제 DB)]
+```
+
+### 3.3 실용적 내용 포함
+- **코드 예시**: 패턴 구현을 위한 구체적인 코드 스니펫
+- **구현 시 고려사항**: 실제 개발 시 주의할 점
+- **예상 효과**: 정량적 성과 지표 (응답시간 개선, 처리량 증가 등)
+
+## 참고 자료
+- **유저스토리**
+- UI/UX설계서
+- **클라우드아키텍처패턴요약표**
+
+## 결과 파일
+선정된 아키텍처 패턴은 다음과 같이 문서화됩니다:
+
+### 파일명
+design/pattern/architecture-pattern.md
+
+### 필수 포함 내용
+1. **요구사항 분석 결과**
+   - 기능적/비기능적 요구사항 상세 분석
+   - 기술적 도전과제 식별
+   
+2. **패턴 선정 매트릭스 (평가표)**
+   - 후보 패턴별 정량적 평가 점수
+   - 선정 근거 및 이유
+   
+3. **서비스별 패턴 적용 설계 (Mermaid)**
+   - 전체 아키텍처 구조
+   - 패턴별 적용 영역 표시
+   
+4. **Phase별 구현 로드맵**
+   - 단계별 적용 계획
+   - 마일스톤 및 목표 설정
+   
+5. **예상 성과 지표**
+   - 성능 개선 예상치
+   - 비용 절감 효과
+   - 개발 생산성 향상
+
+## 체크리스트
+
+작성 완료 후 다음 항목들을 검토하세요:
+
+- [ ] **각 유저스토리가 어떤 패턴으로 해결되는지 명시했는가?**
+- [ ] **패턴 선정 이유를 정량적으로 설명했는가?**
+- [ ] **패턴 간 상호작용과 통합 아키텍처를 표현했는가?**
+- [ ] **구현 우선순위와 단계별 목표가 명확한가?**
+- [ ] **실무자가 바로 활용할 수 있는 수준인가?**
+
+## 작성 시 주의사항
+
+1. **객관적 평가**: 주관적 판단보다는 정량적 데이터 기반 선정
+2. **현실성**: 팀의 기술 수준과 프로젝트 일정을 고려한 실현 가능한 패턴 선정
+3. **확장성**: 현재 요구사항뿐만 아니라 미래 확장성까지 고려
+4. **비용 효율성**: 과도한 엔지니어링 지양, 비즈니스 가치 중심 선정
+5. **문서화**: 선정 과정과 근거를 명확히 문서화하여 후속 의사결정 지원
+
+## 완료 후 mermaid 스크립트 테스트 방법 안내 
+- https://mermaid.live/edit 에 접근 
+- 스크립트 내용을 붙여넣어 확인  
\ No newline at end of file
diff --git a/claude/cloud-design-patterns.md b/claude/cloud-design-patterns.md
new file mode 100644
index 0000000..4e39358
--- /dev/null
+++ b/claude/cloud-design-patterns.md
@@ -0,0 +1,104 @@
+# 클라우드 디자인 패턴 개요
+
+## 전체 분류 현황
+
+총 **42개의 클라우드 디자인 패턴**
+
+- **DB 성능개선**: 1개
+- **읽기 최적화**: 4개
+- **핵심업무 집중**: 6개
+- **안정적 현대화**: 2개
+- **효율적 분산처리**: 13개
+- **안정성**: 6개
+- **보안**: 3개
+- **운영**: 7개
+
+---
+
+## 패턴 목록
+
+### 1. DB 성능개선 (1개)
+
+| No. | 패턴명 | 목적 | 설명 |
+|-----|--------|------|------|
+| 1 | Sharding | 데이터 양 줄이기 | 데이터 저장소를 수평적으로 분할(shard)하여 대규모 데이터 저장 및 접근 시 확장성을 높이는 패턴 |
+
+### 2. 읽기 최적화 (4개)
+
+| No. | 패턴명 | 목적 | 설명 |
+|-----|--------|------|------|
+| 2 | Index Table | NoSQL DB Query 최적화 | 데이터 저장소에서 자주 참조되는 필드에 대한 인덱스를 생성하여 쿼리 성능을 개선하는 패턴 |
+| 3 | Cache-Aside | 성능 향상 및 데이터 일관성 유지 | 데이터 저장소에서 캐시에 데이터를 필요에 따라 로드하여 성능을 개선하고, 캐시와 데이터 저장소 간의 일관성을 유지하는 패턴 |
+| 4 | Materialized View | 쿼리 성능 최적화 | 데이터를 미리 변환하여 준비된 뷰를 생성함으로써 쿼리 성능을 높이고 데이터 추출을 효율화하는 패턴 |
+| 5 | CQRS | 읽기/쓰기 분리 | 데이터 저장소의 읽기와 쓰기 작업을 분리하여 성능, 확장성, 보안성을 높이는 패턴 |
+
+### 3. 핵심업무 집중 (6개)
+
+| No. | 패턴명 | 목적 | 설명 |
+|-----|--------|------|------|
+| 6 | Gateway Offloading | 횡단관심사 분리 | SSL 인증서 관리, 인증, 로깅 등의 공통 기능을 게이트웨이로 분리하여 애플리케이션의 복잡도를 낮추는 패턴 |
+| 7 | Gateway Routing | 라우팅 중앙 처리 | 단일 엔드포인트를 통해 요청을 받아 백엔드 서비스나 인스턴스로 라우팅하는 패턴 |
+| 8 | Gateway Aggregation | 클라이언트 요청 수 줄이기 | 단일 엔드포인트에서 클라이언트 요청을 받아 여러 백엔드 서비스로 분배하고 응답을 취합하는 패턴 |
+| 9 | Backends for Frontends | 프론트엔드 유형별 전용처리 | 특정 프런트엔드에 특화된 백엔드 서비스를 별도로 구축하는 패턴 |
+| 10 | Sidecar | 공통 기능 분리 | 애플리케이션의 일부 컴포넌트를 별도 프로세스나 컨테이너로 분리하여 격리와 확장성을 제공하는 패턴 |
+| 11 | Ambassador | 네트워크 통신의 안정성과 보안 강화 | 클라이언트를 대신해 네트워크 요청을 처리하는 헬퍼 서비스를 생성하는 패턴 |
+
+### 4. 안정적 현대화 (2개)
+
+| No. | 패턴명 | 목적 | 설명 |
+|-----|--------|------|------|
+| 12 | Strangler Fig | 현대화의 위험 최소화와 점진적 전환 | 레거시 시스템을 점진적으로 새로운 애플리케이션 및 서비스로 교체하는 패턴 |
+| 13 | Anti-Corruption Layer | 시스템 간 안정적 인터페이스 | 서로 다른 하위 시스템 간의 의미적 차이를 조정하기 위해 중간 계층을 구현하는 패턴 |
+
+### 5. 효율적 분산처리 (13개)
+
+| No. | 패턴명 | 목적 | 설명 |
+|-----|--------|------|------|
+| 14 | Pipes and Filters | 작업 단계 모듈화로 재사용성과 성능 향상 | 복잡한 작업을 독립적인 단계(필터)로 분리하고 메시지(파이프)로 연결하여 모듈성과 유연성을 높이는 패턴 |
+| 15 | Scheduler Agent Supervisor | 워크플로우의 신뢰성 향상 | 작업 단계를 스케줄러, 에이전트, 감독자로 분리하여 신뢰성과 확장성을 높이는 패턴 |
+| 16 | Leader Election | 분산 작업의 충돌 방지와 안정성 향상 | 분산 시스템에서 여러 작업 인스턴스 중 하나를 리더로 선출하여 조정 역할을 맡기는 패턴 |
+| 17 | Saga | 데이터 일관성 보장 | 각 서비스의 로컬 트랜잭션을 사용하여 분산 트랜잭션의 일관성을 보장하는 패턴 |
+| 18 | Compensating Transaction | 오류 복구로 데이터 일관성 보장 | 분산 트랜잭션에서 실패한 작업을 보상하기 위해 이전 작업을 취소하거나 상쇄하는 트랜잭션을 실행하는 패턴 |
+| 19 | Priority Queue | 중요 작업의 우선 처리 보장 | 메시지의 우선순위에 따라 처리 순서를 조정하는 큐를 사용하는 패턴 |
+| 20 | Queue-Based Load Leveling | 부하의 균등한 분산으로 안정성 확보 | 메시지 큐를 사용하여 작업과 서비스 간의 부하를 균등하게 분산시키는 패턴 |
+| 21 | Sequential Convoy | 처리순서 보장 | 관련 메시지 집합을 순서대로 처리하되 다른 메시지 처리를 차단하지 않도록 하는 패턴 |
+| 22 | Claim Check | 메시지 크기 최소화 및 성능과 보안 향상 | 메시지에서 페이로드를 분리하여 외부 저장소에 저장하고 참조키(클레임 체크)를 사용하는 패턴 |
+| 23 | Publisher-Subscriber | 단일 이벤트 메시지의 복수 서비스 처리 보장 | 다수의 소비자(Consumer)에게 이벤트를 발행하는 패턴 |
+| 24 | Asynchronous Request-Reply | 장시간 처리 작업의 응답시간 단축 | 프런트엔드(클라이언트)와 백엔드 간 비동기로 요청과 응답을 분리하여 응답 시간을 단축하는 패턴 |
+| 25 | Competing Consumers | 병렬처리로 작업 처리 속도 향상 | 동일 메시지 채널에서 여러 소비자가 경쟁적으로 메시지를 처리하여 병렬성을 높이는 패턴 |
+| 26 | Choreography | 중앙집중 처리의 병목현상 방지 | 중앙 조정자 없이 각 서비스가 자율적으로 이벤트를 구독하고 반응하여 전체 워크플로를 수행하는 패턴 |
+
+### 6. 안정성 (6개)
+
+| No. | 패턴명 | 목적 | 설명 |
+|-----|--------|------|------|
+| 27 | Rate Limiting | 요청 폭주 방지로 안정성 유지 | 일정 기간 동안 허용되는 요청 수를 제한하여 과부하를 방지하고 서비스 안정성을 높이는 패턴 |
+| 28 | Throttling | 요청 폭주 방지로 안정성 유지 | 시스템의 부하 상태에 따라 요청 처리량을 동적으로 조절하여 과부하를 방지하는 패턴 |
+| 29 | Bulkhead | 자원풀 격리로 장애 전파 방지 | 애플리케이션 요소를 격리된 풀로 분할하여 하나의 장애가 전체로 전파되는 것을 방지하는 패턴 |
+| 30 | Circuit Breaker | 장애전파 방지 | 장애가 발생한 구성 요소를 빠르게 감지하고 요청 실패를 최소화하는 패턴 |
+| 31 | Retry | 일시적 오류시 처리 보장 | 일시적인 오류에 대해 실패한 요청을 재시도하여 복원력을 높이는 패턴 |
+| 32 | Event Sourcing | 데이터 멱등성 보장과 변경 기록 제공 | 데이터에 대한 모든 변경사항을 이벤트로 저장하고, 이벤트를 재생하여 데이터의 상태를 복원하는 패턴 |
+
+### 7. 보안 (3개)
+
+| No. | 패턴명 | 목적 | 설명 |
+|-----|--------|------|------|
+| 33 | Federated Identity | 사용자 인증 및 관리 효율화 | 인증을 외부 ID 제공자에 위임하여 사용자 관리를 간소화하고 SSO를 구현하는 패턴 |
+| 34 | Gatekeeper | 데이터 접근 제어와 보안 강화 | 신뢰할 수 있는 호스트에 보안 관련 기능을 집중시켜 스토리지나 서비스의 보안을 강화하는 패턴 |
+| 35 | Valet Key | 네트워크 대역폭 감소 | 클라이언트가 특정 리소스에 제한된 직접 접근을 할 수 있도록 토큰을 사용하는 패턴 |
+
+### 8. 운영 (7개)
+
+| No. | 패턴명 | 목적 | 설명 |
+|-----|--------|------|------|
+| 36 | Geodes | 글로벌 서비스 가용성과 성능 최적화 | 백엔드 서비스를 여러 지역에 분산 배치하여 지연 시간을 줄이고 가용성을 높이는 패턴 |
+| 37 | Deployment Stamps | 멀티 테넌트 관리 | 리소스 그룹을 복제하여 작업이나 테넌트 단위로 격리된 운영 환경을 제공하는 패턴 |
+| 38 | Health Endpoint Monitoring | 서비스 가용성 상태 점검 | 애플리케이션의 상태를 모니터링하기 위한 전용 API 엔드포인트를 노출하는 패턴 |
+| 39 | Compute Resource Consolidation | 자원 사용 효율성과 비용 절감 | 여러 작업이나 운영을 단일 컴퓨팅 단위로 통합하여 효율성과 비용을 최적화하는 패턴 |
+| 40 | Static Content Hosting | 정적 자원 제공, 비용절감과 성능 향상 | 정적 콘텐츠를 클라우드 스토리지에 배포하여 클라이언트에 직접 제공함으로써 컴퓨팅 인스턴스 사용을 줄이는 패턴 |
+| 41 | External Configuration Store | 환경설정 중앙관리와 재배포 없이 설정 변경 적용 | 애플리케이션의 설정 정보를 중앙화하여 관리 효율성을 높이고 설정 값 변경 시 재배포 없이 적용하는 패턴 |
+| 42 | Edge Workload Configuration | 엣지컴퓨팅의 효율적 관리 | 장치와 시스템이 혼재된 엣지 환경에서 워크로드 구성을 효율적으로 관리하여 지연 시간 단축과 네트워크 비용 절감을 하는 패턴 |
+
+---
+
+> **참고**: 이 문서는 클라우드 환경에서 자주 사용되는 디자인 패턴들을 체계적으로 분류하여 정리한 것입니다. 각 패턴은 특정 목적과 상황에 맞게 적용될 수 있으며, 실제 구현 시에는 프로젝트의 요구사항과 제약사항을 충분히 고려해야 합니다.
diff --git a/claude/common-principles.md b/claude/common-principles.md
new file mode 100644
index 0000000..31b8354
--- /dev/null
+++ b/claude/common-principles.md
@@ -0,0 +1,197 @@
+# 공통설계원칙
+
+모든 설계 단계에서 공통으로 적용되는 핵심 원칙과 전략
+
+## 🎯 핵심 원칙
+
+### 1. 🚀 실행 우선 원칙
+- **프롬프트 우선**: 바로 실행할 수 있는 프롬프트로 작업 시작
+- **가이드 학습**: 원리와 방법론은 가이드로 깊이 있게 학습
+- **점진적 이해**: 실행 → 결과 확인 → 원리 학습 순서
+
+### 2. 🔄 병렬 처리 전략
+- **서브 에이전트 활용**: Task 도구로 서비스별 동시 작업
+- **의존성 기반 그룹화**: 의존 관계에 따른 순차/병렬 처리 결정
+- **통합 검증**: 병렬 작업 완료 후 전체적 일관성 검증
+
+### 3. 🏗️ 마이크로서비스 설계 원칙
+- **서비스 독립성**: 캐시를 통한 직접 의존성 최소화
+- **선택적 비동기**: 장시간 작업(AI 일정 생성)만 비동기 처리
+- **캐시 우선**: Redis를 통한 성능 최적화
+- **독립 배포**: 서비스별 독립적 배포 가능한 구조
+
+### 4. 📝 표준화 원칙
+- **PlantUML**: 모든 다이어그램 표준 (`!theme mono`)
+- **OpenAPI 3.0**: API 명세 표준
+- **자동 검증**: PlantUML, OpenAPI 문법 검사 필수
+- **일관된 네이밍**: kebab-case 파일명, 표준화된 스키마명
+
+### 5. ✅ 검증 우선 원칙
+- **각 단계마다 자동 검증**: 품질 보장
+- **실시간 피드백**: 오류 조기 발견 및 수정
+- **CI/CD 통합**: 자동화된 검증 프로세스
+- **PlantUML 스크립트 파일 생성 즉시 검사 실행**: 'PlantUML 문법 검사  가이드' 준용 
+
+### 6. 🚀 점진적 구현 원칙
+- **MVP → 확장 → 고도화**: 단계별 접근
+- **YAGNI 적용**: 꼭 필요한 기능만 구현(YAGNI원칙:You aren't gonna need it)
+- **지속적 개선**: 피드백 기반 점진적 발전
+
+## 🔧 의존성 분석 및 병렬 처리
+
+### 의존성 분석 방법
+
+1. **서비스 간 의존성 파악**
+   ```
+   일정 서비스 → 프로파일 서비스 (멤버/여행 정보 조회)
+   일정 서비스 → 장소 서비스 (장소 정보 조회)  
+   장소 서비스: 독립적 (외부 API만 사용)
+   ```
+
+2. **의존성 기반 그룹화**
+   ```
+   Group A (순차 처리): 프로파일 → 일정 서비스
+   Group B (독립 처리): 장소 서비스
+   ```
+
+3. **에이전트 할당 및 병렬 처리**
+   ```
+   Agent 1: Group A 담당
+     - 프로파일 서비스 설계
+     - 일정 서비스 설계 (프로파일 참조)
+   
+   Agent 2: Group B 담당  
+     - 장소 서비스 설계 (독립적)
+   ```
+
+### 병렬 처리 적용 가이드
+
+#### API 설계 단계
+- **독립 서비스**: 각각 별도 에이전트
+- **의존 서비스**: 동일 에이전트 내 순차 처리
+- **공통 검증**: 모든 에이전트 완료 후 swagger-cli 검증
+
+#### 시퀀스 설계 단계
+- **외부 시퀀스**: 플로우별 병렬 처리 (각 플로우는 독립적)
+- **내부 시퀀스**: 서비스별 병렬 처리 (서비스 내부는 독립적)
+
+#### 클래스/데이터 설계 단계
+- **의존성 그룹별**: 참조 관계가 있는 서비스들은 순차 처리
+- **독립 서비스**: 병렬 처리
+- **공통 클래스**: 모든 서비스 설계 완료 후 마지막 처리
+  
+## 🎨 PlantUML 작성 표준
+
+### 기본 템플릿
+```plantuml
+@startuml
+!theme mono
+
+title [다이어그램 제목]
+
+' 다이어그램 내용
+@enduml
+```
+
+### 필수 검증
+- **각 파일 생성 직후 PlantUML 문법 검사 수행**
+- **파이프 방식 권장**: `cat "파일" | docker exec -i plantuml ...`
+- **화살표 문법 주의**: sequence diagram에서 `..>` 사용 금지
+
+### 스타일 가이드
+- **폰트 크기**: 적절한 가독성 확보
+- **색상 구분**: 서비스별, 레이어별 색상 구분
+- **설명 추가**: note를 활용한 상세 설명
+
+## 🔌 API 설계 표준
+
+### 파일 구조
+```
+design/backend/api/{service-name}-api.yaml
+```
+
+### 필수 필드
+```yaml
+paths:
+  /endpoint:
+    get:
+      summary: API 목적 설명
+      operationId: 고유 식별자
+      x-user-story: 유저스토리 ID
+      x-controller: 담당 컨트롤러
+      tags: [API 그룹]
+```
+
+### 스키마 원칙
+- **서비스별 독립**: 각 서비스 파일에 모든 스키마 포함
+- **중복 허용**: 초기에는 중복을 허용하고 점진적으로 공통화
+- **명확한 네이밍**: Request/Response DTO 네이밍 표준
+
+## 🔄 시퀀스 설계 표준
+
+### 외부 시퀀스 (서비스 간)
+- **참여 서비스만**: 해당 플로우에 참여하는 서비스만 표시
+- **API 호출 중심**: 서비스 간 API 호출 순서 표현
+- **한글 설명**: 각 호출의 목적을 한글로 명시
+
+### 내부 시퀀스 (서비스 내부)
+- **모든 API 표시**: 해당 서비스의 모든 API 포함
+- **내부 처리 흐름**: 컨트롤러 → 서비스 → 레포지토리 플로우
+- **기술적 세부사항**: 캐시, DB 접근 등 포함
+
+### 동기/비동기 구분
+- **실선 (→)**: 동기 호출
+- **점선 (->>)**: 비동기 호출  
+- **양방향**: 필요시에만 사용
+
+## 📊 클래스 설계 표준
+
+### 아키텍처 적용
+- **Clean Architecture**: Port/Adapter 용어 대신 표준 Clean 용어 사용
+- **멀티프로젝트**: 서비스별 독립 모듈
+- **패키지 구조 표준**: 일관된 패키지 구조 적용
+
+### 관계 표현
+- **Generalization**: 상속 관계
+- **Realization**: 인터페이스 구현
+- **Dependency**: 의존 관계  
+- **Association**: 연관 관계
+- **Aggregation/Composition**: 집약/합성 관계
+
+### 상세 정보
+- **프로퍼티와 메소드**: 모두 명시
+- **접근 제한자**: 적절한 가시성 설정
+- **타입 정보**: 정확한 데이터 타입 명시
+
+## 🗄️ 데이터 설계 표준  
+
+### 서비스별 DB 분리
+- **각 서비스마다 독립적인 데이터베이스**
+- **서비스 간 데이터 공유 최소화**
+- **캐시를 통한 성능 최적화**
+
+### 클래스 설계와 일치
+- **Entity 클래스와 테이블 매핑**
+- **일관된 네이밍 컨벤션**
+- **적절한 정규화 수준**
+
+## 🚨 주의사항
+
+### PlantUML 문법
+- **sequence diagram에서 `..>` 사용 금지**
+- **비동기는 `->>` 또는 `-->>` 사용**
+- **테마는 반드시 `mono` 사용**
+  
+### 병렬 처리
+- **의존성 분석 선행**: 병렬 처리 전 반드시 의존성 파악
+- **순차 처리 필요시**: 무리한 병렬화보다는 안전한 순차 처리
+- **검증 단계 필수**: 병렬 처리 후 통합 검증
+
+### API 설계
+- **유저스토리 ID 필수**: x-user-story 필드 누락 금지
+- **Controller 명시**: x-controller 필드로 담당 컨트롤러 명시
+- **스키마 완전성**: 모든 Request/Response 스키마 정의
+
+---
+
+💡 **이 원칙들은 모든 설계 단계에서 일관되게 적용되어야 하며, 각 단계별 세부 가이드에서 구체적으로 구현됩니다.**
\ No newline at end of file
diff --git a/claude/conversation-summary.md b/claude/conversation-summary.md
new file mode 100644
index 0000000..acaca05
--- /dev/null
+++ b/claude/conversation-summary.md
@@ -0,0 +1,823 @@
+# 내부 시퀀스 설계 대화 상세 요약
+
+## 1. 주요 요청 및 의도 (Primary Request and Intent)
+
+사용자는 다음 명령어를 통해 **내부 시퀀스 설계**(Internal Sequence Design)를 요청했습니다:
+
+```
+/design-seq-inner @architecture
+내부 시퀀스 설계를 해 주세요:
+- '공통설계원칙'과 '내부시퀀스설계 가이드'를 준용하여 설계
+```
+
+### 구체적 요구사항:
+- **공통설계원칙**(Common Design Principles) 준수
+- **내부시퀀스설계 가이드**(Internal Sequence Design Guide) 준수
+- 7개 마이크로서비스의 내부 처리 흐름 설계
+- PlantUML 시퀀스 다이어그램 작성 (Controller → Service → Repository 레이어)
+- Resilience 패턴 적용 (Circuit Breaker, Retry, Timeout, Fallback, Bulkhead)
+- Cache, DB, 외부 API 상호작용 표시
+- 외부 시스템은 `<>` 마킹
+- PlantUML 파일 생성 즉시 문법 검사 실행
+
+---
+
+## 2. 주요 기술 개념 (Key Technical Concepts)
+
+### 아키텍처 패턴
+
+**Event-Driven Architecture**
+- Apache Kafka를 통한 비동기 메시징
+- 이벤트 토픽: `EventCreated`, `ParticipantRegistered`, `WinnerSelected`, `DistributionCompleted`
+- Job 토픽: `ai-job`, `image-job`
+- At-Least-Once 전달 보장 + Redis Set을 통한 멱등성 보장
+
+**CQRS (Command Query Responsibility Segregation)**
+- Command: 이벤트 생성, 참여 등록, 당첨자 추첨
+- Query: 대시보드 조회, 이벤트 목록/상세 조회
+- 읽기/쓰기 분리로 성능 최적화
+
+**Microservices Architecture (7개 독립 서비스)**
+1. **User Service**: 회원 관리 (가입, 로그인, 프로필, 로그아웃)
+2. **Event Service**: 이벤트 생성 플로우 (10개 시나리오)
+3. **AI Service**: 트렌드 분석 및 추천
+4. **Content Service**: 이미지 생성
+5. **Distribution Service**: 다중 채널 배포
+6. **Participation Service**: 고객 참여 관리
+7. **Analytics Service**: 성과 분석
+
+**Layered Architecture**
+- **API Layer**: 모든 REST 엔드포인트
+- **Business Layer**: Controller → Service → Domain 로직
+- **Data Layer**: Repository, Cache, External API
+- **Infrastructure Layer**: Kafka, Logging, Monitoring
+
+### Resilience 패턴 상세
+
+**1. Circuit Breaker Pattern**
+- **구현**: Resilience4j 라이브러리
+- **임계값**: 50% 실패율 → OPEN 상태 전환
+- **적용 대상**:
+  - 국세청 API (사업자번호 검증)
+  - Claude/GPT-4 API (AI 추천)
+  - Stable Diffusion/DALL-E API (이미지 생성)
+  - 외부 채널 API (우리은행, 지니뮤직, SNS 등)
+- **OPEN 상태**: 10초 대기 후 HALF_OPEN으로 전환
+- **폴백**: 캐시 데이터, 기본값, 검증 스킵
+
+**2. Retry Pattern**
+- **최대 재시도**: 3회
+- **백오프 전략**: Exponential backoff (1초, 2초, 4초)
+- **적용 시나리오**:
+  - 외부 API 일시적 장애
+  - 네트워크 타임아웃
+  - 429 Too Many Requests 응답
+
+**3. Timeout Pattern**
+- **서비스별 타임아웃**:
+  - 국세청 API: 5초
+  - AI 추천 API: 30초 (복잡한 처리)
+  - 이미지 생성 API: 20초
+  - 배포 채널 API: 10초
+- **목적**: 무한 대기 방지, 리소스 효율 관리
+
+**4. Fallback Pattern**
+- **전략별 폴백**:
+  - 사업자번호 검증 실패 → 캐시 데이터 사용 (TTL 7일)
+  - AI 추천 실패 → 기본 템플릿 추천
+  - 이미지 생성 실패 → Stable Diffusion → DALL-E → 템플릿 이미지
+  - 채널 배포 실패 → 다른 채널 계속 진행 (독립 처리)
+
+**5. Bulkhead Pattern**
+- **독립 스레드 풀**: 채널별 격리
+- **목적**: 한 채널 장애가 다른 채널에 영향 없음
+- **적용**: Distribution Service 다중 채널 배포
+  - 우리은행 영상 광고
+  - 링고 벨소리/컬러링
+  - 지니뮤직 TV 광고
+  - Instagram 피드
+  - 네이버 블로그
+  - 카카오 채널
+
+### 캐싱 전략
+
+**Cache-Aside Pattern (Redis)**
+
+| 데이터 유형 | TTL | 히트율 목표 | 적용 시나리오 |
+|------------|-----|------------|-------------|
+| 사업자번호 검증 | 7일 | 95% | User Service 회원가입 |
+| AI 추천 결과 | 24시간 | 80% | AI Service 트렌드 분석 |
+| 이미지 생성 결과 | 7일 | 90% | Content Service 이미지 생성 |
+| 대시보드 통계 | 5분 | 70% | Analytics Service 대시보드 |
+| 이벤트 상세 | 5분 | 85% | Event Service 상세 조회 |
+| 이벤트 목록 | 1분 | 60% | Event Service 목록 조회 |
+| 참여자 목록 | 5분 | 75% | Participation Service 목록 조회 |
+
+**캐시 무효화 전략**:
+- 이벤트 생성/수정 → 이벤트 캐시 삭제
+- 참여자 등록 → 참여자 목록 캐시 삭제
+- 당첨자 추첨 → 이벤트/참여자 캐시 삭제
+- 배포 완료 → 대시보드 캐시 삭제
+
+### 보안 (Security)
+
+**Password Hashing**
+- **알고리즘**: bcrypt
+- **Cost Factor**: 10
+- **검증**: Service 계층에서 수행
+
+**민감 데이터 암호화**
+- **알고리즘**: AES-256
+- **대상**: 사업자번호
+- **키 관리**: 환경 변수 (ENCRYPTION_KEY)
+
+**JWT 토큰**
+- **만료 시간**: 7일
+- **저장 위치**: Redis Session
+- **로그아웃**: Blacklist에 추가 (TTL = 남은 만료 시간)
+
+**데이터 마스킹**
+- **전화번호**: `010-****-1234`
+- **적용**: 참여자 목록 조회
+
+---
+
+## 3. 파일 및 코드 섹션 (Files and Code Sections)
+
+### 다운로드한 가이드 문서
+
+**1. claude/common-principles.md**
+- **내용**: 공통 설계 원칙, PlantUML 표준, API 설계 표준
+- **주요 원칙**:
+  - 실행 우선 원칙
+  - 병렬 처리 전략
+  - 마이크로서비스 설계 원칙
+  - 표준화 원칙
+  - 검증 우선 원칙
+  - 점진적 구현 원칙
+
+**2. claude/sequence-inner-design.md**
+- **내용**: 내부 시퀀스 설계 가이드, 시나리오 분류 가이드
+- **주요 내용**:
+  - 작성 원칙: 유저스토리 매칭, 외부 시퀀스 일치, 서비스별 분리
+  - 표현 요소: API/Business/Data/Infrastructure 레이어
+  - 작성 순서: 준비 → 실행 → 검토
+  - 시나리오 분류: 유저스토리 기반, 비즈니스 기능 단위
+  - 병렬 수행: 서브 에이전트 활용
+
+### 참조 문서
+
+**design/userstory.md (999줄)**
+- **20개 유저스토리** (7개 마이크로서비스)
+- **User Service (4개)**:
+  - UFR-USER-010: 회원가입
+  - UFR-USER-020: 로그인
+  - UFR-USER-030: 프로필 수정
+  - UFR-USER-040: 로그아웃
+
+- **Event Service (9개)**:
+  - UFR-EVT-010: 이벤트 목적 선택
+  - UFR-EVT-020: AI 이벤트 추천 요청
+  - UFR-EVT-021: AI 추천 결과 조회
+  - UFR-EVT-030: 이미지 생성 요청
+  - UFR-EVT-031: 이미지 결과 조회
+  - UFR-EVT-040: 콘텐츠 선택
+  - UFR-EVT-050: 최종 승인 및 배포
+  - UFR-EVT-060: 이벤트 상세 조회
+  - UFR-EVT-061: 이벤트 목록 조회
+
+- **Participation Service (3개)**:
+  - UFR-PART-010: 이벤트 참여
+  - UFR-PART-011: 참여자 목록 조회
+  - UFR-PART-020: 당첨자 추첨
+
+- **Analytics Service (2개)**:
+  - UFR-ANL-010: 대시보드 조회
+  - UFR-ANL-011: 실시간 통계 업데이트 (Kafka 구독)
+
+- **AI/Content/Distribution Service**: 외부 시퀀스에서 비동기 처리
+
+**design/backend/sequence/outer/사용자인증플로우.puml (249줄)**
+- UFR-USER-010: 회원가입 with 국세청 API Circuit Breaker
+- UFR-USER-020: 로그인 with JWT 생성
+- UFR-USER-040: 로그아웃 with 세션 삭제
+
+**design/backend/sequence/outer/이벤트생성플로우.puml (211줄)**
+- Kafka 기반 비동기 처리 (AI/Image Job)
+- Distribution Service 동기 REST 호출
+- Polling 패턴으로 Job 상태 조회
+
+**design/backend/sequence/outer/고객참여플로우.puml (151줄)**
+- 참여 등록 with 중복 체크
+- 당첨자 추첨 with Fisher-Yates Shuffle
+- Kafka 이벤트 발행
+
+**design/backend/sequence/outer/성과분석플로우.puml (225줄)**
+- Cache HIT/MISS 시나리오
+- 외부 API 병렬 호출 with Circuit Breaker
+- Kafka 이벤트 구독
+
+**design/backend/logical/logical-architecture.md (883줄)**
+- Event-Driven 아키텍처 상세
+- Kafka 통합 전략
+- Resilience 패턴 구성
+
+### 생성된 내부 시퀀스 파일 (26개)
+
+#### User Service (4개 파일)
+
+**1. design/backend/sequence/inner/user-회원가입.puml (6.9KB)**
+```plantuml
+@startuml user-회원가입
+!theme mono
+title User Service - 회원가입 내부 시퀀스
+
+participant "UserController" as Controller
+participant "UserService" as Service
+participant "BusinessValidator" as Validator
+participant "UserRepository" as Repo
+participant "Redis Cache<>" as Cache
+participant "User DB<>" as DB
+participant "국세청 API<>" as NTS
+
+note over Controller: POST /api/users/register
+Controller -> Service: registerUser(RegisterDto)
+Service -> Validator: validateBusinessNumber(사업자번호)
+
+alt 캐시에 검증 결과 존재 (TTL 7일)
+    Validator -> Cache: GET business:{사업자번호}
+    Cache --> Validator: 검증 결과 (HIT)
+else 캐시 미스
+    Validator -> NTS: 사업자번호 검증 API\n[Circuit Breaker, Timeout 5s]
+
+    alt 검증 성공
+        NTS --> Validator: 유효한 사업자
+        Validator -> Cache: SET business:{사업자번호}\n(TTL 7일)
+    else Circuit Breaker OPEN (외부 API 장애)
+        NTS --> Validator: OPEN 상태
+        note right: Fallback 전략:\n- 캐시 데이터 사용\n- 또는 검증 스킵 (추후 재검증)
+    end
+end
+
+Validator --> Service: 검증 완료
+
+Service -> Service: 비밀번호 해싱\n(bcrypt, cost factor 10)
+Service -> Service: 사업자번호 암호화\n(AES-256)
+
+Service -> Repo: beginTransaction()
+Service -> Repo: saveUser(User)
+Repo -> DB: INSERT INTO users
+DB --> Repo: user_id
+Service -> Repo: saveStore(Store)
+Repo -> DB: INSERT INTO stores
+DB --> Repo: store_id
+Service -> Repo: commit()
+
+Service -> Service: JWT 토큰 생성\n(만료 7일)
+Service -> Cache: SET session:{user_id}\n(JWT, TTL 7일)
+
+Service --> Controller: RegisterResponseDto\n(user_id, token)
+Controller --> Client: 201 Created
+@enduml
+```
+
+**주요 설계 포인트**:
+- Circuit Breaker: 국세청 API (50% 실패율 → OPEN)
+- Cache-Aside: Redis 7일 TTL, 95% 히트율 목표
+- Transaction: User + Store INSERT
+- Security: bcrypt 해싱, AES-256 암호화
+- JWT: 7일 만료, Redis 세션 저장
+
+**2. design/backend/sequence/inner/user-로그인.puml (4.5KB)**
+- bcrypt 패스워드 검증
+- JWT 토큰 생성
+- Redis 세션 저장
+
+**3. design/backend/sequence/inner/user-프로필수정.puml (6.2KB)**
+- User + Store UPDATE 트랜잭션
+- 선택적 패스워드 변경 및 검증
+
+**4. design/backend/sequence/inner/user-로그아웃.puml (3.6KB)**
+- 세션 삭제
+- JWT Blacklist (TTL = 남은 만료 시간)
+
+#### Event Service (10개 파일)
+
+**1. event-목적선택.puml**
+- 이벤트 목적 선택
+- EventCreated 이벤트 발행
+
+**2. event-AI추천요청.puml**
+- Kafka ai-job 토픽 발행
+- Job ID 반환 (202 Accepted)
+
+**3. event-추천결과조회.puml**
+- Redis에서 Job 상태 폴링
+- 완료 시 추천 결과 반환
+
+**4. event-이미지생성요청.puml**
+- Kafka image-job 토픽 발행
+
+**5. event-이미지결과조회.puml**
+- 캐시에서 이미지 URL 조회
+
+**6. event-콘텐츠선택.puml**
+- 콘텐츠 선택 저장
+
+**7. event-최종승인및배포.puml**
+- Distribution Service REST API 동기 호출
+
+**8. event-상세조회.puml**
+- 이벤트 상세 조회 with 캐시 (TTL 5분)
+
+**9. event-목록조회.puml**
+- 이벤트 목록 with 필터/검색/페이징
+
+**10. event-대시보드조회.puml**
+- 대시보드 이벤트 with 병렬 쿼리
+
+#### Participation Service (3개 파일)
+
+**1. participation-이벤트참여.puml (4.6KB)**
+```plantuml
+@startuml participation-이벤트참여
+!theme mono
+title Participation Service - 이벤트 참여 내부 시퀀스
+
+participant "ParticipationController" as Controller
+participant "ParticipationService" as Service
+participant "ParticipationRepository" as Repo
+participant "Redis Cache<>" as Cache
+participant "Participation DB<>" as DB
+participant "Kafka<>" as Kafka
+
+note over Controller: POST /api/participations
+Controller -> Service: participate(ParticipateDto)
+
+' 중복 참여 체크
+Service -> Cache: EXISTS participation:{event_id}:{user_id}
+
+alt 캐시에 중복 기록 존재
+    Cache --> Service: true
+    Service --> Controller: 409 Conflict\n(이미 참여함)
+else 캐시 미스 → DB 확인
+    Cache --> Service: false
+    Service -> Repo: existsByEventAndUser(event_id, user_id)
+    Repo -> DB: SELECT COUNT(*)\nFROM participations\nWHERE event_id = ? AND user_id = ?
+    DB --> Repo: count
+
+    alt 중복 참여 발견
+        Repo --> Service: true
+        Service -> Cache: SET participation:{event_id}:{user_id}\n(TTL 이벤트 종료일)
+        Service --> Controller: 409 Conflict
+    else 중복 없음
+        Repo --> Service: false
+
+        ' 응모번호 생성 (UUID)
+        Service -> Service: generateEntryNumber()\n(UUID v4)
+
+        ' 참여 저장
+        Service -> Repo: save(Participation)
+        Repo -> DB: INSERT INTO participations\n(event_id, user_id, entry_number, store_visit)
+        DB --> Repo: participation_id
+
+        ' 캐시 업데이트 (중복 체크용)
+        Service -> Cache: SET participation:{event_id}:{user_id}\n(TTL 이벤트 종료일)
+        Service -> Cache: INCR participant_count:{event_id}
+
+        ' Kafka 이벤트 발행
+        Service -> Kafka: publish('ParticipantRegistered',\n{event_id, user_id, participation_id})
+
+        Service --> Controller: ParticipateResponseDto\n(participation_id, entry_number)
+        Controller --> Client: 201 Created
+    end
+end
+@enduml
+```
+
+**주요 설계 포인트**:
+- 중복 체크: Redis Cache + DB
+- ParticipantRegistered 이벤트 발행
+- 응모번호 생성 (UUID)
+- 캐시 TTL: 이벤트 종료일까지
+
+**2. participation-참여자목록조회.puml (4.3KB)**
+- 동적 쿼리 with 필터
+- 전화번호 마스킹
+- 캐시 TTL 5분
+
+**3. participation-당첨자추첨.puml (6.5KB)**
+```plantuml
+' Fisher-Yates Shuffle 알고리즘
+' Crypto.randomBytes로 공정성 보장
+' 매장 방문 보너스 (가중치 x2)
+' WinnerSelected 이벤트 발행
+```
+
+#### Analytics Service (5개 파일)
+
+**1. analytics-대시보드조회-캐시히트.puml (2.0KB)**
+- 0.5초 응답
+
+**2. analytics-대시보드조회-캐시미스.puml (6.4KB)**
+```plantuml
+par 외부 API 병렬 호출
+    Analytics -> WooriAPI: GET 영상 광고 통계\n[Circuit Breaker]
+and
+    Analytics -> GenieAPI: GET TV 광고 통계\n[Circuit Breaker]
+and
+    Analytics -> SNSAPI: GET SNS 인사이트\n[Circuit Breaker]
+end
+
+' ROI 계산 로직
+Analytics -> Analytics: calculateROI()\n(총 수익 - 총 비용) / 총 비용 × 100
+
+' Redis 캐싱 (TTL 5분)
+Analytics -> Cache: SET dashboard:{event_id}\n(통계 데이터, TTL 5분)
+```
+
+**3. analytics-이벤트생성구독.puml**
+- EventCreated → 통계 초기화
+
+**4. analytics-참여자등록구독.puml**
+- ParticipantRegistered → 실시간 카운트 업데이트
+
+**5. analytics-배포완료구독.puml**
+- DistributionCompleted → 채널별 통계 업데이트
+
+#### AI Service (1개 파일)
+
+**ai-트렌드분석및추천.puml (12KB)**
+```plantuml
+' Kafka ai-job 구독
+' 트렌드 분석 캐시 (TTL 1시간)
+
+par 3가지 추천 옵션 생성
+    AI -> AIApi: 저비용 옵션 생성\n[Circuit Breaker, Timeout 30s]
+and
+    AI -> AIApi: 중간 비용 옵션 생성\n[Circuit Breaker, Timeout 30s]
+and
+    AI -> AIApi: 고비용 옵션 생성\n[Circuit Breaker, Timeout 30s]
+end
+
+' Circuit Breaker: Claude/GPT-4 API
+' Fallback: 기본 템플릿 추천
+' 캐시 결과 (TTL 24시간)
+```
+
+#### Content Service (1개 파일)
+
+**content-이미지생성.puml (8.5KB)**
+```plantuml
+' Kafka image-job 구독
+
+par 3가지 스타일 병렬 생성
+    Content -> ImageAPI: 심플 스타일\n[Circuit Breaker, Timeout 20s]
+and
+    Content -> ImageAPI: 화려한 스타일\n[Circuit Breaker, Timeout 20s]
+and
+    Content -> ImageAPI: 트렌디 스타일\n[Circuit Breaker, Timeout 20s]
+end
+
+' Fallback: Stable Diffusion → DALL-E → 템플릿
+' CDN 업로드 및 URL 캐싱 (TTL 7일)
+```
+
+#### Distribution Service (2개 파일)
+
+**1. distribution-다중채널배포.puml (11KB)**
+```plantuml
+' REST API 동기 호출 (Event Service로부터)
+
+par 다중 채널 배포 (Bulkhead)
+    Dist -> WooriAPI: 영상 광고 업로드\n[Retry 3회, Timeout 10s]
+and
+    Dist -> LingoAPI: 벨소리/컬러링 업데이트\n[Retry 3회, Timeout 10s]
+and
+    Dist -> GenieAPI: TV 광고 등록\n[Retry 3회, Timeout 10s]
+and
+    Dist -> InstagramAPI: 피드 게시\n[Retry 3회, Timeout 10s]
+and
+    Dist -> NaverAPI: 블로그 포스팅\n[Retry 3회, Timeout 10s]
+and
+    Dist -> KakaoAPI: 채널 게시\n[Retry 3회, Timeout 10s]
+end
+
+' DistributionCompleted 이벤트 발행
+' 독립 채널 처리 (한 채널 실패해도 다른 채널 계속)
+```
+
+**2. distribution-배포상태조회.puml (6.5KB)**
+- 배포 상태 모니터링 with Retry 기능
+
+### 요약 문서
+
+**design/backend/sequence/inner/README.md**
+- **총 크기**: 115.6KB (모든 파일 합계)
+- **내용**:
+  - 26개 시나리오 완전 문서화
+  - 설계 원칙 및 패턴 설명
+  - 파일 구조 및 통계
+  - PlantUML 검증 방법 (온라인/로컬/IDE)
+
+**파일 통계**:
+- 총 26개 파일
+- 7개 서비스
+- 평균 파일 크기: 4.4KB
+- 최소: 1.6KB (캐시 히트 시나리오)
+- 최대: 12KB (AI 트렌드 분석)
+
+---
+
+## 4. 오류 및 수정 (Errors and Fixes)
+
+### 오류 1: Docker 미실행
+
+**설명**: PlantUML 문법 검사는 Docker 데몬이 필요하지만 실행 중이 아님
+
+**시도한 명령어**:
+```bash
+cat "file.puml" | docker exec -i plantuml java -jar /app/plantuml.jar -syntax
+```
+
+**오류 메시지**:
+```
+Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
+Is the docker daemon running?
+```
+
+**해결 방법**:
+- 수동 문법 검증 수행
+- 모든 서브 에이전트 보고: 문법 수동 검증 완료, 유효하지 않은 화살표 문법(`..>`) 사용 안함, 적절한 구조 확인
+
+**사용자 피드백**: 없음 - 사용자가 이 제한 사항 수용
+
+### 오류 2: 없음 - 모든 작업 성공적으로 완료
+
+- 26개 PlantUML 파일 모두 문법 오류 없이 생성
+- 모든 파일 `!theme mono` 표준 준수
+- 적절한 participant 선언 및 화살표 문법
+
+---
+
+## 5. 문제 해결 (Problem Solving)
+
+### 문제 1: 7개 서비스 병렬 처리
+
+**해결책**: Task 도구로 7개 독립 서브 에이전트 생성
+- 각 서브 에이전트는 system-architect 타입
+- 동일한 지침 및 참조 문서 제공
+
+**이점**:
+- 모든 서비스 동시 설계
+- 총 소요 시간 단축
+
+**결과**: 26개 파일 병렬 생성
+
+### 문제 2: 서비스 간 일관성 보장
+
+**해결책**: 각 서브 에이전트에 동일한 지침 제공
+- 공통 설계 원칙
+- 내부 시퀀스 설계 가이드
+- 외부 시퀀스 다이어그램
+- 논리 아키텍처
+
+**결과**: 일관된 레이어링, 네이밍, 패턴 적용
+
+### 문제 3: 복잡한 시나리오의 다중 패턴 적용
+
+**예시**: Distribution Service 다중 채널 배포
+
+**해결책**: PlantUML `par/and/end` 블록 사용
+```plantuml
+par 다중 채널 배포
+    Dist -> WooriAPI: [Circuit Breaker, Retry, Timeout]
+and
+    Dist -> LingoAPI: [Circuit Breaker, Retry, Timeout]
+and
+    Dist -> GenieAPI: [Circuit Breaker, Retry, Timeout]
+and
+    Dist -> InstagramAPI: [Circuit Breaker, Retry, Timeout]
+and
+    Dist -> NaverAPI: [Circuit Breaker, Retry, Timeout]
+and
+    Dist -> KakaoAPI: [Circuit Breaker, Retry, Timeout]
+end
+```
+
+**적용 패턴**:
+- Circuit Breaker (채널별)
+- Bulkhead (격리)
+- Retry (지수 백오프)
+
+### 문제 4: 캐시 전략 정의
+
+**해결책**: 데이터 변동성에 따른 TTL 차등 적용
+
+| 데이터 유형 | TTL | 이유 |
+|------------|-----|------|
+| 정적 데이터 (사업자번호 검증) | 7일 | 거의 변경 없음 |
+| 느리게 변경 (AI 추천 결과) | 24시간 | 일별 트렌드 반영 |
+| 실시간 (대시보드) | 5분 | 최신 통계 필요 |
+| 빈번 업데이트 (이벤트 목록) | 1분 | 실시간성 중요 |
+
+---
+
+## 6. 모든 사용자 메시지 (All User Messages)
+
+### 메시지 1: 초기 명령
+
+```
+/design-seq-inner @architecture
+내부 시퀀스 설계를 해 주세요:
+- '공통설계원칙'과 '내부시퀀스설계 가이드'를 준용하여 설계
+```
+
+### 메시지 2: 요약 요청
+
+```
+Your task is to create a detailed summary of the conversation so far,
+with the following structure:
+
+1. **Primary Request and Intent**:
+   Identify the main user request(s) and underlying goals/expectations.
+
+2. **Key Technical Concepts**:
+   List and briefly explain all technical concepts, patterns, architectures,
+   or methodologies discussed (e.g., patterns like Circuit Breaker, CQRS, etc.)
+
+3. **Files and Code Sections**:
+   Enumerate all files referenced or created, with brief descriptions.
+   Include key code snippets with context.
+
+4. **Errors and Fixes**:
+   Detail any errors encountered, their causes, and how they were resolved.
+
+5. **Problem Solving**:
+   Outline problems that arose and the strategies used to overcome them.
+
+6. **All User Messages**:
+   Reproduce every message the user sent, in chronological order.
+
+7. **Pending Tasks**:
+   List any tasks or questions that remain unresolved or incomplete.
+
+8. **Current Work**:
+   Describe what actions were being taken immediately before the summary was requested.
+
+9. **Optional Next Step**:
+   Suggest a logical next step, but do not proceed—only recommend.
+
+Please be thorough and provide sufficient detail so that I can fully
+understand the conversation without needing to review the entire chat history.
+```
+
+---
+
+## 7. 보류 중인 작업 (Pending Tasks)
+
+**보류 작업 없음** - 11개 TODO 항목 모두 완료:
+
+- ✅ 가이드 문서 분석 및 프로젝트 상황 파악
+- ✅ 외부 시퀀스 및 논리 아키텍처 분석
+- ✅ 서비스별 시나리오 분류 및 설계 계획 수립
+- ✅ User 서비스 내부 시퀀스 설계
+- ✅ Event 서비스 내부 시퀀스 설계
+- ✅ AI 서비스 내부 시퀀스 설계
+- ✅ Content 서비스 내부 시퀀스 설계
+- ✅ Distribution 서비스 내부 시퀀스 설계
+- ✅ Participation 서비스 내부 시퀀스 설계
+- ✅ Analytics 서비스 내부 시퀀스 설계
+- ✅ 전체 내부 시퀀스 설계 검증 및 통합
+
+---
+
+## 8. 현재 작업 (Current Work)
+
+요약 요청 직전에 최종 통합 단계를 완료했습니다:
+
+### 작업 1: 파일 생성 검증
+
+```bash
+find design/backend/sequence/inner -name "*.puml" -type f | wc -l
+# 결과: 26개 파일
+
+ls -lh design/backend/sequence/inner/*.puml | awk '{print $9, $5}' | sort
+# 26개 파일 목록 및 크기 (1.6KB ~ 12KB)
+```
+
+### 작업 2: 종합 README 생성
+
+**파일**: `design/backend/sequence/inner/README.md`
+**크기**: 115.6KB 총합의 일부
+**내용**:
+- 서비스-시나리오별 26개 분류
+- 설계 원칙 문서화
+- 패턴 설명 (Resilience, Cache-Aside, Event-Driven)
+- 캐시 전략 표 (TTL, 히트율 목표)
+- 파일 구조 목록
+- PlantUML 검증 방법 (온라인/로컬/IDE)
+- 통계: 7개 서비스, 26개 파일, 평균 4.4KB
+
+### 작업 3: TODO 목록 업데이트
+
+```javascript
+TodoWrite: 11개 작업 모두 "completed" 상태
+```
+
+### 최종 상태
+
+- 모든 내부 시퀀스 설계 완료
+- 모든 문서 통합 완료
+- 다음 단계 준비 완료 (API 설계 또는 클래스 설계)
+
+---
+
+## 9. 선택적 다음 단계 (Optional Next Step)
+
+**다음 단계 권장 없음** - 작업이 완전히 완료되었습니다.
+
+사용자가 명시적으로 요청한 "내부 시퀀스 설계를 해 주세요"는 다음을 통해 완수되었습니다:
+
+- ✅ 26개 PlantUML 내부 시퀀스 다이어그램
+- ✅ 종합 README 문서화
+- ✅ 모든 설계 원칙 및 패턴 적용
+- ✅ 외부 시퀀스 및 아키텍처와 완전 정렬
+
+### 아키텍처 설계 워크플로우의 일반적인 다음 단계:
+
+사용자가 계속 진행하고자 한다면:
+
+1. **API 설계** (`/design-api`):
+   - OpenAPI 3.0 명세 정의
+   - 26개 시나리오의 모든 엔드포인트 명세화
+   - Request/Response DTO 정의
+   - 보안 스키마 (JWT)
+   - 에러 코드 체계
+
+2. **클래스 설계** (`/design-class`):
+   - 클래스 다이어그램 생성
+   - Clean/Hexagonal 아키텍처 적용
+   - 패키지 구조 정의
+   - 인터페이스 및 구현 클래스 분리
+
+3. **데이터 설계** (`/design-data`):
+   - 데이터베이스 스키마 설계
+   - ERD (Entity-Relationship Diagram)
+   - 인덱스 전략
+   - 샤딩/파티셔닝 전략
+
+그러나 **명시적인 사용자 확인을 기다려야 합니다**. 현재 작업이 완료되었고 사용자가 다른 우선순위를 가질 수 있기 때문입니다.
+
+---
+
+## 📊 프로젝트 통계 요약
+
+### 산출물
+- **PlantUML 파일**: 26개
+- **총 크기**: 115.6KB
+- **서비스**: 7개
+- **시나리오**: 26개
+
+### 서비스별 파일 수
+- User Service: 4개
+- Event Service: 10개
+- Participation Service: 3개
+- Analytics Service: 5개
+- AI Service: 1개
+- Content Service: 1개
+- Distribution Service: 2개
+
+### 패턴 적용 현황
+- Circuit Breaker: 12개 시나리오
+- Retry Pattern: 8개 시나리오
+- Timeout Pattern: 15개 시나리오
+- Fallback Pattern: 10개 시나리오
+- Bulkhead Pattern: 1개 시나리오 (Distribution)
+- Cache-Aside: 20개 시나리오
+- Event-Driven: 7개 Kafka 이벤트/Job
+
+### 작업 수행 방식
+- **병렬 처리**: 7개 서브 에이전트 동시 실행
+- **설계 표준 준수**: 공통설계원칙, 내부시퀀스설계 가이드
+- **검증 방법**: 수동 PlantUML 문법 검증 (Docker 미사용)
+
+---
+
+## ✅ 완료 확인
+
+이 요약 문서는 다음을 포함합니다:
+
+1. ✅ 주요 요청 및 의도
+2. ✅ 주요 기술 개념 (아키텍처, 패턴, 보안, 캐싱)
+3. ✅ 파일 및 코드 섹션 (가이드, 참조 문서, 생성 파일)
+4. ✅ 오류 및 수정 (Docker 미실행 → 수동 검증)
+5. ✅ 문제 해결 (병렬 처리, 일관성, 복잡한 패턴, 캐시 전략)
+6. ✅ 모든 사용자 메시지 (초기 명령, 요약 요청)
+7. ✅ 보류 중인 작업 (없음 - 모두 완료)
+8. ✅ 현재 작업 (최종 통합 및 검증)
+9. ✅ 선택적 다음 단계 (API/클래스/데이터 설계 권장)
+
+**문서 작성일**: 2025년
+**작성자**: Claude Code (Sonnet 4.5)
+**프로젝트**: KT AI 기반 소상공인 이벤트 자동 생성 서비스
diff --git a/claude/logical-architecture-design.md b/claude/logical-architecture-design.md
new file mode 100644
index 0000000..ca4d2ba
--- /dev/null
+++ b/claude/logical-architecture-design.md
@@ -0,0 +1,64 @@
+# 논리아키텍처설계가이드
+
+[요청사항]
+- <작성원칙>을 준용하여 설계
+- <작성순서>에 따라 설계
+- [결과파일] 안내에 따라 파일 작성 
+- 완료 후 mermaid 스크립트 테스트 방법 안내 
+  - https://mermaid.live/edit 에 접근 
+  - 스크립트 내용을 붙여넣어 확인 
+
+[가이드]  
+<작성원칙>
+- **유저스토리와 매칭**되어야 함. **불필요한 추가 설계 금지**
+- UI/UX설계서의 '사용자 플로우'참조하여 설계 
+- '아키텍처패턴'에 선정된 클라우드 디자인 패턴을 적용하여 설계 
+- 사용자 관점의 컴포넌트 다이어그램 작성
+- Context Map 스타일로 서비스 내부 구조는 생략하고 서비스 간 관계에 집중
+- 클라이언트에서 API Gateway로는 단일 연결선으로 표현
+<작성순서>
+- 준비: 
+  - 유저스토리, UI/UX설계서, 아키텍처패턴 분석 및 이해 
+  - "@analyze --play" 프로토타입이 있는 경우 웹브라우저에서 실행하여 서비스 이해 
+- 실행: 
+  - 논리아키텍처 설계서(logical-architecture.md) 작성: 아래 항목은 필수 포함하고 필요 시 항목 추가 
+    - 개요: 설계 원칙, 핵심 컴포넌트 정의 
+    - 서비스 아키텍처 
+      - 서비스별 책임 
+      - 서비스 간 통신 전략 
+    - 주요 사용자 플로우
+    - 데이터 흐름 및 캐싱 전략
+    - 확장성 및 성능 고려사항 
+    - 보안 고려사항
+    - 논리아키텍처 다이어그램  
+      - Mermaid 형식으로 작성하며 별도 파일로 작성: logical-architecture.mmd 
+      - <통신전략>과 <의존성 표현 방법>을 준수
+      - **Mermaid 스크립트 파일 검사 실행**: 'Mermaid문법검사가이드' 준용
+- 검토:
+  - <작성원칙> 준수 검토
+  - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토
+  - 수정 사항 선택 및 반영  
+<통신 전략>
+- **동기 통신**: 즉시 응답이 필요한 단순 조회
+- **캐시 우선**: 자주 사용되는 데이터는 캐시에서 직접 읽기
+- **비동기 처리**: 외부 API 다중 호출 등 장시간 작업
+<의존성 표현 방법>
+- 실선 화살표(→): 동기적 의존성 (필수)
+- 비동기 화살표(->>): 비동기 의존성 (fire-and-forget)
+- 점선 화살표(-->): 선택적 의존성 또는 느슨한 결합
+- 양방향 화살표(↔): 상호 의존성
+- 의존성 레이블에 목적 명시 (예: "멤버 정보 조회")
+- 플로우 라벨 형식: [요청서비스약어]액션 (예: [Trip]AI 일정 생성 요청)
+
+[참고자료]
+- 유저스토리
+- UI/UX설계서
+- 프로토타입
+- 아키텍처패턴  
+
+[예시]
+- 논리아키텍처 다이어그램: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-논리아키텍처.mmd
+
+[결과파일]
+- design/backend/logical/logical-architecture.md
+- design/backend/logical/logical-architecture.mmd
diff --git a/claude/mermaid-guide.md b/claude/mermaid-guide.md
new file mode 100644
index 0000000..6d6b3f0
--- /dev/null
+++ b/claude/mermaid-guide.md
@@ -0,0 +1,300 @@
+# Mermaid문법검사가이드
+
+## 개요
+
+Mermaid 다이어그램의 문법 오류를 사전에 검출하여 렌더링 실패를 방지하기 위한 가이드입니다. Docker 기반 Mermaid CLI를 활용하여 로컬에서 빠르게 문법을 검증할 수 있습니다.
+
+## Mermaid CLI 서버 설치 및 검사
+
+### Docker로 Mermaid CLI 컨테이너 실행
+
+```bash
+# Mermaid CLI 컨테이너가 실행 중인지 확인
+docker ps | grep mermaid-cli
+
+# ⚠️ 중요: 첫 실행 시 이미지 다운로드를 먼저 진행 (큰 이미지로 인한 타임아웃 방지)
+docker pull minlag/mermaid-cli:latest
+
+# Mermaid CLI 컨테이너가 없으면 설치 및 실행 (root 권한으로 실행, 포트 48080 사용)
+docker run -d --rm --name mermaid-cli -u root -p 48080:8080 --entrypoint sh minlag/mermaid-cli:latest -c "while true;do sleep 3600; done"
+
+# 컨테이너 상태 확인
+docker logs mermaid-cli
+```
+
+#### 💡 Docker 이미지 다운로드 관련 주의사항
+
+**첫 실행 시 발생할 수 있는 문제:**
+- `minlag/mermaid-cli:latest` 이미지가 큰 용량(약 700MB+)이므로 다운로드에 시간이 오래 걸림
+- `docker run` 명령 실행 시 이미지가 없으면 자동 다운로드하지만 타임아웃 발생 가능
+- **해결방법**: `docker pull` 명령으로 이미지를 먼저 다운로드한 후 컨테이너 실행
+
+**권장 실행 순서:**
+1. `docker pull minlag/mermaid-cli:latest` (이미지 다운로드)
+2. `docker run` 명령으로 컨테이너 실행
+3. 필수 설정 진행
+
+#### ⚠️ 중요: 최초 컨테이너 생성 후 필수 설정
+
+Mermaid CLI는 Puppeteer를 사용하여 다이어그램을 렌더링하므로 Chromium 브라우저가 필요합니다. 
+컨테이너를 처음 생성한 후 다음 명령을 실행하여 필요한 패키지를 설치해야 합니다:
+
+```bash
+# Chromium 및 필요한 종속성 설치
+docker exec mermaid-cli sh -c "apk add --no-cache chromium chromium-chromedriver nss freetype harfbuzz ca-certificates ttf-freefont"
+
+# Puppeteer가 사용할 설정 파일 생성
+docker exec mermaid-cli sh -c "echo '{\"executablePath\": \"/usr/bin/chromium-browser\", \"args\": [\"--no-sandbox\", \"--disable-setuid-sandbox\", \"--disable-dev-shm-usage\"]}' > /tmp/puppeteer-config.json"
+```
+
+이 설정은 컨테이너가 실행되는 동안 유지되므로 한 번만 실행하면 됩니다.
+
+문법검사 후 Container를 중지하지 않고 계속 사용함 
+
+## 문법 검사 방법
+현재 OS에 맞게 수행.
+
+### Linux/macOS 버전
+**스크립트 파일(tools/check-mermaid.sh)을 이용하여 수행**
+
+1. tools/check-mermaid.sh 파일 존재 여부 확인 
+2. 스크립트 파일이 없으면 "Mermaid문법검사기(Linux/Mac)"를 tools/check-mermaid.sh 파일로 다운로드하여 스크립트 파일을 만듦
+3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사
+
+```bash
+# 1. 스크립트 실행 권한 부여 (최초 1회)
+chmod +x tools/check-mermaid.sh
+
+# 2. 문법 검사 실행
+./tools/check-mermaid.sh {검사할 파일}
+
+# 예시
+./tools/check-mermaid.sh design/backend/physical/physical-architecture.mmd
+```
+
+### Windows PowerShell 버전
+**스크립트 파일(tools/check-mermaid.ps1)을 이용하여 수행**
+
+1. tools/check-mermaid.ps1 파일 존재 여부 확인 
+2. 스크립트 파일이 없으면 "Mermaid문법검사기(Window)"를 tools/check-mermaid.ps1 파일로 다운로드하여 스크립트 파일을 만듦
+3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사
+
+```powershell
+# 문법 검사 실행
+.\tools\check-mermaid.ps1 {검사할 파일}
+
+# 예시
+.\tools\check-mermaid.ps1 design\backend\physical\physical-architecture.mmd
+```
+
+### 수동 검사 방법 (스크립트 없이)
+
+```bash
+# 1. 고유 파일명 생성 (충돌 방지)
+TEMP_FILE="/tmp/mermaid_$(date +%s)_$$.mmd"
+
+# 2. 파일 복사
+docker cp {검사할 파일} mermaid-cli:${TEMP_FILE}
+
+# 3. 문법 검사 (Puppeteer 설정 파일 사용)
+docker exec mermaid-cli sh -c "cd /home/mermaidcli && node_modules/.bin/mmdc -i ${TEMP_FILE} -o /tmp/output.svg -p /tmp/puppeteer-config.json -q"
+
+# 4. 임시 파일 삭제
+docker exec mermaid-cli rm -f ${TEMP_FILE} /tmp/output.svg
+```
+
+**주의**: Puppeteer 설정 파일(`/tmp/puppeteer-config.json`)이 있어야 합니다. 없다면 위의 "최초 컨테이너 생성 후 필수 설정"을 먼저 실행하세요.
+
+### 검사 결과 해석
+
+| 출력 | 의미 | 대응 방법 |
+|------|------|-----------|
+| "Success: Mermaid syntax is valid!" | 문법 오류 없음 ✅ | 정상, 렌더링 가능 |
+| "Parse error on line X" | X번째 줄 구문 오류 ❌ | 해당 라인 문법 확인 |
+| "Expecting 'XXX'" | 예상 토큰 오류 ❌ | 누락된 문법 요소 추가 |
+| "Syntax error" | 일반 문법 오류 ❌ | 전체 구조 재검토 |
+
+## Mermaid 다이어그램 타입별 주의사항
+
+### 1. Graph/Flowchart
+```mermaid
+graph TB
+    %% 올바른 사용법 ✅
+    A[Node A] --> B[Node B]
+    C[Node C] -.-> D[Node D]
+    E[Node E] ==> F[Node F]
+    
+    %% 주의사항
+    %% - 노드 ID에 공백 불가 (대신 [Label] 사용)
+    %% - subgraph와 end 개수 일치 필요
+    %% - 따옴표 안에서 특수문자 주의
+```
+
+### 2. Sequence Diagram
+```mermaid
+sequenceDiagram
+    %% 올바른 사용법 ✅
+    participant A as Service A
+    participant B as Service B
+    
+    A->>B: Request
+    B-->>A: Response
+    A->>+B: Call with activation
+    B-->>-A: Return with deactivation
+    
+    %% 주의사항
+    %% - participant 선언 권장
+    %% - 활성화(+)/비활성화(-) 쌍 맞추기
+    %% - Note 블록 종료 확인
+```
+
+### 3. Class Diagram
+```mermaid
+classDiagram
+    %% 올바른 사용법 ✅
+    class Animal {
+        +String name
+        +int age
+        +makeSound() void
+    }
+    
+    class Dog {
+        +String breed
+        +bark() void
+    }
+    
+    Animal <|-- Dog : inherits
+    
+    %% 주의사항
+    %% - 메서드 괄호 필수
+    %% - 관계 표현 정확히
+    %% - 접근 제한자 기호 확인
+```
+
+### 4. State Diagram
+```mermaid
+stateDiagram-v2
+    %% 올바른 사용법 ✅
+    [*] --> Idle
+    Idle --> Processing : start
+    Processing --> Completed : finish
+    Processing --> Error : error
+    Error --> Idle : reset
+    Completed --> [*]
+    
+    %% 주의사항
+    %% - [*]는 시작/종료 상태
+    %% - 상태 이름에 공백 불가
+    %% - 전이 레이블 콜론(:) 사용
+```
+
+## 일반적인 오류와 해결 방법
+
+### 1. 괄호 불균형
+```mermaid
+%% 잘못된 예 ❌
+graph TB
+    A[Node (with parenthesis)]  %% 괄호 안에 괄호
+    
+%% 올바른 예 ✅
+graph TB
+    A[Node with parenthesis]
+```
+
+### 2. 특수 문자 이스케이프
+```mermaid
+%% 잘못된 예 ❌
+graph TB
+    A[Security & Management]  %% & 문자 직접 사용
+    
+%% 올바른 예 ✅
+graph TB
+    A[Security & Management]  %% HTML 엔티티 사용
+```
+
+### 3. subgraph/end 불일치
+```mermaid
+%% 잘못된 예 ❌
+graph TB
+    subgraph One
+        A --> B
+        subgraph Two
+            C --> D
+    end  %% Two만 닫힘, One은 안 닫힘
+    
+%% 올바른 예 ✅
+graph TB
+    subgraph One
+        A --> B
+        subgraph Two
+            C --> D
+        end
+    end  %% 모든 subgraph 닫기
+```
+
+### 4. 노드 참조 오류
+```mermaid
+%% 잘못된 예 ❌
+graph TB
+    A --> UnknownNode  %% 정의되지 않은 노드
+    
+%% 올바른 예 ✅
+graph TB
+    A[Node A] --> B[Node B]  %% 모든 노드 정의
+```
+
+## 컨테이너 관리
+
+### 컨테이너 중지 및 삭제
+```bash
+# 컨테이너 중지
+docker stop mermaid-cli
+
+# 컨테이너 삭제
+docker rm mermaid-cli
+
+# 한 번에 중지 및 삭제
+docker stop mermaid-cli && docker rm mermaid-cli
+```
+
+### 컨테이너 재시작
+```bash
+# 컨테이너 재시작
+docker restart mermaid-cli
+```
+
+## 성능 최적화 팁
+
+1. **컨테이너 유지**: 검사 후 컨테이너를 중지하지 않고 유지하여 다음 검사 시 빠르게 실행
+2. **배치 검사**: 여러 파일을 연속으로 검사할 때 컨테이너 재시작 없이 진행
+3. **로컬 파일 사용**: 네트워크 경로보다 로컬 파일 경로 사용 권장
+
+## 문제 해결
+
+### Docker 관련 오류
+```bash
+# Docker 데몬 실행 확인
+docker ps
+
+# Docker Desktop 시작 (Windows/Mac)
+# Docker 서비스 시작 (Linux)
+sudo systemctl start docker
+```
+
+### 권한 오류
+```bash
+# Linux/Mac에서 스크립트 실행 권한
+chmod +x tools/check-mermaid.sh
+
+# Docker 권한 (Linux)
+sudo usermod -aG docker $USER
+```
+
+### 컨테이너 이미지 오류
+```bash
+# 이미지 재다운로드
+docker pull minlag/mermaid-cli:latest
+
+# 기존 컨테이너 삭제 후 재생성
+docker stop mermaid-cli && docker rm mermaid-cli
+```
\ No newline at end of file
diff --git a/claude/plantuml-guide.md b/claude/plantuml-guide.md
new file mode 100644
index 0000000..5dd396c
--- /dev/null
+++ b/claude/plantuml-guide.md
@@ -0,0 +1,82 @@
+# PlantUML문법검사가이드
+
+## 개요
+
+PlantUML 다이어그램의 문법 오류를 사전에 검출하여 렌더링 실패를 방지하기 위한 가이드입니다. Docker 기반 PlantUML 서버를 활용하여 로컬에서 빠르게 문법을 검증할 수 있습니다.
+
+## PlantUML 서버 설치 검사
+
+### Docker로 PlantUML 서버 실행
+
+```bash
+# PlantUML 서버가 실행 중인지 확인
+docker ps | grep plantuml
+
+# PlantUML 서버가 없으면 설치 및 실행
+docker run -d --name plantuml -p 38080:8080 plantuml/plantuml-server:latest
+
+# 서버 상태 확인
+docker logs plantuml
+```
+
+## 문법 검사 방법
+현재 OS에 맞게 수행.
+
+### Linux/macOS 버전
+
+1. tools/check-plantuml.sh 파일 존재 여부 확인 
+2. 스크립트 파일이 없으면 "PlantUML문법검사기(Linux/Mac)"를 tools/check-plantuml.sh 파일로 다운로드하여 스크립트 파일을 만듦
+3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사
+
+### Windows PowerShell 버전
+**스크립트 파일(tools/check-plantuml.ps1)을 이용하여 수행**.
+
+1. tools/check-plantuml.ps1 파일 존재 여부 확인 
+2. 스크립트 파일이 없으면 "PlantUML문법검사기(Window)"를 tools/check-plantuml.ps1 파일로 다운로드하여 스크립트 파일을 만듦
+3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사
+ 
+### 검사 결과 해석
+
+| 출력 | 의미 | 대응 방법 |
+|------|------|-----------|
+| 출력 없음 | 문법 오류 없음 ✅ | 정상, 렌더링 가능 |
+| "Some diagram description contains errors" | 오류 존재 ❌ | 파이프 방식으로 상세 확인 |
+| "ERROR" + 라인 번호 | 특정 라인 오류 ❌ | 해당 라인 수정 |
+| "Error line X in file" | X번째 줄 오류 ❌ | 해당 라인 문법 확인 |
+
+## 화살표 문법 규칙
+
+### 시퀀스 다이어그램 올바른 화살표 사용법
+
+```plantuml
+@startuml
+' 올바른 사용법 ✅
+A -> B: 동기 메시지 (실선)
+A ->> B: 비동기 메시지 (실선, 열린 화살촉)
+A -->> B: 비동기 응답 (점선, 열린 화살촉)  
+A --> B: 점선 화살표 (일반)
+A <-- B: 응답 (점선)
+A ->x B: 실패/거부 (X 표시)
+A ->>o B: 비동기 열린 원
+
+' 잘못된 사용법 ❌
+A ..> B: ' 오류! sequence diagram에서 유효하지 않음
+@enduml
+```
+
+### 클래스 다이어그램 화살표
+
+```plantuml
+@startuml
+' 클래스 다이어그램에서는 ..> 사용 가능
+ClassA ..> ClassB : 의존성 (점선)
+ClassC --> ClassD : 연관 (점선)
+@enduml
+```
+
+### 화살표 문법 주의사항
+
+1. **`..>`는 sequence diagram에서 사용 금지**
+2. 비동기 메시지는 `->>` 또는 `-->>` 사용
+3. 동기/비동기를 명확히 구분하여 일관되게 사용
+4. 다이어그램 타입별로 유효한 화살표가 다름
\ No newline at end of file
diff --git a/claude/sequence-inner-design.md b/claude/sequence-inner-design.md
new file mode 100644
index 0000000..586c62c
--- /dev/null
+++ b/claude/sequence-inner-design.md
@@ -0,0 +1,76 @@
+# 내부시퀀스설계 가이드 
+
+[요청사항]
+- <작성원칙>을 준용하여 설계
+- <작성순서>에 따라 설계
+- [결과파일] 안내에 따라 파일 작성 
+
+[가이드]  
+<작성원칙>
+- **유저스토리와 매칭**되어야 함. **불필요한 추가 설계 금지**
+- **외부시퀀스설계서에서 설계한 플로우와 일치**해야 함 
+- UI/UX설계서의 '사용자 플로우'참조하여 설계
+- 마이크로서비스 내부의 처리 흐름을 표시 
+- **각 서비스-시나리오별로 분리하여 각각 작성**
+- 각 서비스별 주요 시나리오마다 독립적인 시퀀스 설계 수행
+- 프론트엔드와 백엔드 책임 분리: 프론트엔드에서 할 수 있는 것은 백엔드로 요청 안하게 함  
+- 표현 요소
+  - **API 레이어**: 해당 시나리오의 모든 관련 엔드포인트
+  - **비즈니스 레이어**: Controller → Service → Domain 내부 플로우
+  - **데이터 레이어**: Repository, Cache, External API 접근
+  - **인프라 레이어**: 메시지 큐, 이벤트, 로깅 등
+- 다이어그램 구성
+  - **참여자(Actor)**: Controller, Service, Repository, Cache, External API
+  - **생명선(Lifeline)**: 각 참여자의 활동 구간
+  - **메시지(Message)**: 동기(→)/비동기(-->) 호출 구분
+  - **활성화 박스**: 처리 중인 시간 구간 표시
+  - **노트**: 중요한 비즈니스 로직이나 기술적 고려사항 설명
+- 참여자가 서비스 내부가 아닌 다른 마이크로 서비스, 외부시스템, 인프라 컴포넌트면 참여자 이름 끝에 '<>'를 붙임 
+  예) database "Redis Cache<>" as cache
+
+<작성순서>
+- 준비: 
+  - 유저스토리, UI/UX설계서, 외부시퀀스설계서 분석 및 이해 
+  - "@analyze --play" 프로토타입이 있는 경우 웹브라우저에서 실행하여 서비스 이해
+- 실행: 
+  - <시나리오 분류 가이드>에 따라 각 서비스별로 시나리오 분류 
+  - 내부시퀀스설계서 작성 
+    - <병렬수행>가이드에 따라 동시 수행 
+    - **PlantUML 스크립트 파일 생성 즉시 검사 실행**: 'PlantUML 문법 검사  가이드' 준용 
+- 검토:
+  - <작성원칙> 준수 검토
+  - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토
+  - 수정 사항 선택 및 반영
+  
+<시나리오 분류 가이드>
+-  시나리오 식별 방법
+  - **유저스토리 기반**: 각 유저스토리를 기준으로 시나리오 도출
+  - **비즈니스 기능 단위**: 하나의 완전한 비즈니스 기능을 수행하는 단위로 분류
+- 시나리오별 설계 원칙
+  - **단일 책임**: 하나의 시나리오는 하나의 명확한 비즈니스 목적을 가짐
+  - **완전성**: 해당 시나리오의 모든 API와 내부 처리를 포함
+  - **독립성**: 각 시나리오는 독립적으로 이해 가능해야 함
+  - **일관성**: 동일한 아키텍처 레이어 표현 방식 사용
+- 시나리오 명명 규칙
+  - **케밥-케이스 사용**: entity action 형태. 한글로 작성 (예: 사용자 등록, 주문 처리)
+  - **동사형 액션**: 실제 수행하는 작업을 명확히 표현
+  - **일관된 용어**: 프로젝트 내에서 동일한 용어 사용
+
+<병렬수행>
+- **서브 에이전트를 활용한 병렬 작성 필수**
+- 서비스별 독립적인 에이전트가 각 내부시퀀스설계를 동시에 작업
+- 모든 설계 완료 후 전체 검증
+
+[참고자료]
+- 유저스토리
+- UI/UX설계서
+- 외부시퀀스설계서
+- 프로토타입
+
+[예시]
+- 링크: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-시퀀스설계서(내부).puml
+
+[결과파일]
+- design/backend/sequence/inner/{서비스명}-{시나리오}.puml
+- 서비스명은 영어로 시나리오명은 한글로 작성  
+
diff --git a/claude/sequence-outer-design.md b/claude/sequence-outer-design.md
new file mode 100644
index 0000000..fc60efe
--- /dev/null
+++ b/claude/sequence-outer-design.md
@@ -0,0 +1,54 @@
+# 외부시퀀스설계가이드 
+
+[요청사항]
+- <작성원칙>을 준용하여 설계
+- <작성순서>에 따라 설계
+- [결과파일] 안내에 따라 파일 작성 
+
+[가이드]  
+<작성원칙>
+- **유저스토리와 매칭**되어야 함. **불필요한 추가 설계 금지**
+- **논리아키텍처에 정의한 참여자와 일치**해야 함 
+- UI/UX설계서의 '사용자 플로우'참조하여 설계
+- **해당 플로우에 참여하는** 프론트엔드, 모든 서비스, 인프라 컴포넌트(예: Gateway, Message Queue, Database), 외부시스템을 참여자로 추가
+- 플로우에 참여자들의 역할과 책임을 명확히 표시 
+- 플로우 수행에 필요한 프론트엔드부터 End-to-End 호출을 순서대로 표시하고 한글 설명 추가
+- 마이크로서비스 내부의 처리 흐름은 표시하지 않음
+- 동기/비동기 통신 구분 (실선/점선)
+- 캐시, 큐 등 인프라 컴포넌트와의 상호작용 포함
+<작성순서>
+- 준비: 
+  - 유저스토리, UI/UX설계서, 논리아키텍처 분석 및 이해 
+  - "@analyze --play" 프로토타입이 있는 경우 웹브라우저에서 실행하여 서비스 이해
+- 실행:
+  - <플로우 분류기준>에 따라 최적의 플로우를 결정함  
+  - 외부시퀀스설계서 작성 
+    - <병렬수행>가이드에 따라 병렬 수행  
+    - **PlantUML 스크립트 파일 생성 즉시 검사 실행**: 'PlantUML 문법 검사  가이드' 준용 
+- 검토:
+  - <작성원칙> 준수 검토
+  - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토
+  - 수정 사항 선택 및 반영    
+<플로우 분류기준>
+- **핵심 비즈니스 플로우별**: 사용자가 목표를 달성하기 위한 주요 업무 흐름
+- **통합 패턴별**: 동기/비동기, 캐시 활용, 외부 연동 등 기술적 통합 방식
+- **사용자 시나리오별**: 엔드투엔드 사용자 경험 기준
+- **데이터 흐름별**: 데이터의 생성, 변환, 저장 과정
+<병렬수행>
+- **서브 에이전트를 활용한 병렬 작성 필수**
+- 서비스별 독립적인 에이전트가 각 외부시퀀스설계를 동시에 작업
+- 모든 설계 완료 후 전체 검증
+
+[참고자료]
+- 유저스토리
+- UI/UX설계서
+- 논리아키텍처
+- 프로토타입
+
+[예시]
+- 링크: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-시퀀스설계서(외부).puml
+
+[결과파일]
+- **주요 비즈니스 플로우별로 파일을 분리하여 작성**
+- 플로우명은 한글로 네이밍 
+- 위치: design/backend/sequence/outer/{플로우명}.puml
diff --git a/claude/standard_comment.md b/claude/standard_comment.md
new file mode 100644
index 0000000..5200015
--- /dev/null
+++ b/claude/standard_comment.md
@@ -0,0 +1,518 @@
+# 개발주석표준 가이드
+
+## 📋 개요
+
+이 문서는 CMS 프로젝트의 JavaDoc 주석 작성 표준을 정의합니다. 일관된 주석 스타일을 통해 코드의 가독성과 유지보수성을 향상시키는 것을 목표로 합니다.
+
+## 🎯 주석 작성 원칙
+
+### 1. **기본 원칙**
+- **명확성**: 코드의 의도와 동작을 명확하게 설명
+- **일관성**: 프로젝트 전체에서 동일한 스타일 적용
+- **완전성**: 모든 public 메서드와 클래스에 주석 작성
+- **최신성**: 코드 변경 시 주석도 함께 업데이트
+
+### 2. **주석 대상**
+- **필수**: public 클래스, 인터페이스, 메서드
+- **권장**: protected 메서드, 중요한 필드
+- **선택**: private 메서드 (복잡한 로직인 경우)
+
+## 📝 JavaDoc 기본 문법
+
+### 1. **기본 구조**
+```java
+/**
+ * 클래스나 메서드의 간단한 설명 (첫 번째 문장)
+ * 
+ * 
      상세한 설명이 필요한 경우 여기에 작성합니다.
      
+ * 
+ * @param paramName 파라미터 설명
+ * @return 반환값 설명
+ * @throws ExceptionType 예외 상황 설명
+ * @since 1.0
+ * @author 작성자명
+ * @see 관련클래스#메서드
+ */
+```
+
+### 2. **주요 JavaDoc 태그**
+
+| 태그 | 설명 | 사용 위치 |
+|------|------|-----------|
+| `@param` | 메서드 파라미터 설명 | 메서드 |
+| `@return` | 반환값 설명 | 메서드 |
+| `@throws` | 예외 상황 설명 | 메서드 |
+| `@since` | 도입 버전 | 클래스, 메서드 |
+| `@author` | 작성자 | 클래스 |
+| `@version` | 버전 정보 | 클래스 |
+| `@see` | 관련 항목 참조 | 모든 곳 |
+| `@apiNote` | API 사용 시 주의사항 | 메서드 |
+| `@implNote` | 구현 관련 참고사항 | 메서드 |
+
+## 🎨 HTML 태그 활용 가이드
+
+### 1. **HTML 태그 사용 이유**
+
+JavaDoc은 소스코드 주석을 파싱하여 **HTML 형태의 API 문서**를 자동 생성합니다. HTML 태그를 사용하면:
+
+- **가독성 향상**: 구조화된 문서로 이해하기 쉬움
+- **자동 문서화**: JavaDoc 도구가 예쁜 HTML 문서 생성
+- **IDE 지원**: 개발 도구에서 리치 텍스트로 표시
+- **표준 준수**: Oracle JavaDoc 스타일 가이드 준수
+
+### 2. **자주 사용되는 HTML 태그**
+
+#### **텍스트 서식**
+```java
+/**
+ * 
      단락을 구분할 때 사용합니다.
      
+ * 중요한 내용을 강조할 때 사용합니다.
+ * 이탤릭체로 표시할 때 사용합니다.
+ * method()와 같은 코드를 표시할 때 사용합니다.
+ */
+```
+
+#### **목록 작성**
+```java
+/**
+ * 
      주요 기능:
      
+ * 
        
+ *   
      • 첫 번째 기능
        • 
+ *   
      • 두 번째 기능
        • 
+ *   
      • 세 번째 기능
        • 
+ * 
      
+ * 
+ * 
      처리 과정:
      
+ * 
        
+ *   
      1. 첫 번째 단계
        2. 
+ *   
      2. 두 번째 단계
        3. 
+ *   
      3. 세 번째 단계
        4. 
+ * 
      
+ */
+```
+
+#### **코드 블록**
+```java
+/**
+ * 
      사용 예시:
      
+ * 
      + * AuthController controller = new AuthController();
+ * LoginRequest request = new LoginRequest("user", "password");
+ * ResponseEntity<LoginResponse> response = controller.login(request);
+ * 
      
+ */
+```
+
+#### **테이블**
+```java
+/**
+ * 
      HTTP 상태 코드:
      
+ * 
+ *   
+ *   
+ *   
+ *   
+ * 
      상태 코드설명
      200성공
      400잘못된 요청
      401인증 실패
      
+ */
+```
+
+### 3. **HTML 태그 사용 규칙**
+
+- **<와 >**: 제네릭 타입 표현 시 `<T>` 사용
+- **줄바꿈**: `
      ` 태그 사용 (가급적 `
      ` 태그 권장)
+- **링크**: `{@link ClassName#methodName}` 사용
+- **인라인 코드**: `{@code variableName}` 또는 `` 사용
+
+## 📋 클래스 주석 표준
+
+### 1. **클래스 주석 템플릿**
+```java
+/**
+ * 클래스의 간단한 설명
+ * 
+ * 
      클래스의 상세한 설명과 목적을 여기에 작성합니다.
      
+ * 
+ * 
      주요 기능:
      
+ * 
        
+ *   
      • 기능 1
        • 
+ *   
      • 기능 2
        • 
+ *   
      • 기능 3
        • 
+ * 
      
+ * 
+ * 
      사용 예시:
      
+ * 
      + * ClassName instance = new ClassName();
+ * instance.someMethod();
+ * 
      
+ * 
+ * 
      주의사항:
      
+ * 
        
+ *   
      • 주의사항 1
        • 
+ *   
      • 주의사항 2
        • 
+ * 
      
+ * 
+ * @author 작성자명
+ * @version 1.0
+ * @since 2024-01-01
+ * 
+ * @see 관련클래스1
+ * @see 관련클래스2
+ */
+public class ClassName {
+    // ...
+}
+```
+
+### 2. **Controller 클래스 주석 예시**
+```java
+/**
+ * 사용자 관리 API 컨트롤러
+ * 
+ * 
      사용자 등록, 조회, 수정, 삭제 기능을 제공하는 REST API 컨트롤러입니다.
      
+ * 
+ * 
      주요 기능:
      
+ * 
        
+ *   
      • 사용자 등록 및 인증
        • 
+ *   
      • 사용자 정보 조회 및 수정
        • 
+ *   
      • 사용자 권한 관리
        • 
+ * 
      
+ * 
+ * 
      API 엔드포인트:
      
+ * 
        
+ *   
      • POST /api/users - 사용자 등록
        • 
+ *   
      • GET /api/users/{id} - 사용자 조회
        • 
+ *   
      • PUT /api/users/{id} - 사용자 수정
        • 
+ *   
      • DELETE /api/users/{id} - 사용자 삭제
        • 
+ * 
      
+ * 
+ * 
      보안 고려사항:
      
+ * 
        
+ *   
      • 모든 엔드포인트는 인증이 필요합니다
        • 
+ *   
      • 개인정보 처리 시 데이터 마스킹 적용
        • 
+ *   
      • 입력값 검증 및 XSS 방지
        • 
+ * 
      
+ * 
+ * @author cms-team
+ * @version 1.0
+ * @since 2024-01-01
+ * 
+ * @see UserService
+ * @see UserRepository
+ * @see UserDTO
+ */
+@RestController
+@RequestMapping("/api/users")
+public class UserController {
+    // ...
+}
+```
+
+## 📋 메서드 주석 표준
+
+### 1. **메서드 주석 템플릿**
+```java
+/**
+ * 메서드의 간단한 설명
+ * 
+ * 
      메서드의 상세한 설명과 동작을 여기에 작성합니다.
      
+ * 
+ * 
      처리 과정:
      
+ * 
        
+ *   
      1. 첫 번째 단계
        2. 
+ *   
      2. 두 번째 단계
        3. 
+ *   
      3. 세 번째 단계
        4. 
+ * 
      
+ * 
+ * 
      주의사항:
      
+ * 
        
+ *   
      • 주의사항 1
        • 
+ *   
      • 주의사항 2
        • 
+ * 
      
+ * 
+ * @param param1 첫 번째 파라미터 설명
+ *               - 추가 설명이 필요한 경우
+ * @param param2 두 번째 파라미터 설명
+ * 
+ * @return 반환값 설명
+ *         - 성공 시: 설명
+ *         - 실패 시: 설명
+ * 
+ * @throws ExceptionType1 예외 상황 1 설명
+ * @throws ExceptionType2 예외 상황 2 설명
+ * 
+ * @apiNote API 사용 시 주의사항
+ * 
+ * @see 관련메서드1
+ * @see 관련메서드2
+ * 
+ * @since 1.0
+ */
+public ReturnType methodName(Type param1, Type param2) {
+    // ...
+}
+```
+
+### 2. **API 메서드 주석 예시**
+```java
+/**
+ * 사용자 로그인 처리
+ * 
+ * 
      사용자 ID와 비밀번호를 검증하여 JWT 토큰을 생성합니다.
      
+ * 
+ * 
      처리 과정:
      
+ * 
        
+ *   
      1. 입력값 검증 (@Valid 어노테이션)
        2. 
+ *   
      2. 사용자 인증 정보 확인
        3. 
+ *   
      3. JWT 토큰 생성
        4. 
+ *   
      4. 사용자 세션 시작
        5. 
+ *   
      5. 로그인 메트릭 업데이트
        6. 
+ * 
      
+ * 
+ * 
      보안 고려사항:
      
+ * 
        
+ *   
      • 비밀번호는 BCrypt로 암호화된 값과 비교
        • 
+ *   
      • 로그인 실패 시 상세 정보 노출 방지
        • 
+ *   
      • 로그인 시도 로그 기록
        • 
+ * 
      
+ * 
+ * @param request 로그인 요청 정보
+ *                - username: 사용자 ID (3-50자, 필수)
+ *                - password: 비밀번호 (6-100자, 필수)
+ * 
+ * @return ResponseEntity<LoginResponse> 로그인 응답 정보
+ *         - 성공 시: 200 OK + JWT 토큰, 사용자 역할, 만료 시간
+ *         - 실패 시: 401 Unauthorized + 에러 메시지
+ * 
+ * @throws InvalidCredentialsException 인증 정보가 올바르지 않은 경우
+ * @throws RuntimeException 로그인 처리 중 시스템 오류 발생 시
+ * 
+ * @apiNote 보안상 이유로 로그인 실패 시 구체적인 실패 사유를 반환하지 않습니다.
+ * 
+ * @see AuthService#login(LoginRequest)
+ * @see UserSessionService#startSession(String, String, java.time.Instant)
+ * 
+ * @since 1.0
+ */
+@PostMapping("/login")
+public ResponseEntity login(@Valid @RequestBody LoginRequest request) {
+    // ...
+}
+```
+
+## 📋 필드 주석 표준
+
+### 1. **필드 주석 템플릿**
+```java
+/**
+ * 필드의 간단한 설명
+ * 
+ * 
      필드의 상세한 설명과 용도를 여기에 작성합니다.
      
+ * 
+ * 
      주의사항:
      
+ * 
        
+ *   
      • 주의사항 1
        • 
+ *   
      • 주의사항 2
        • 
+ * 
      
+ * 
+ * @since 1.0
+ */
+private final ServiceType serviceName;
+```
+
+### 2. **의존성 주입 필드 예시**
+```java
+/**
+ * 인증 서비스
+ * 
+ * 
      사용자 로그인/로그아웃 처리 및 JWT 토큰 관리를 담당합니다.
      
+ * 
+ * 
      주요 기능:
      
+ * 
        
+ *   
      • 사용자 인증 정보 검증
        • 
+ *   
      • JWT 토큰 생성 및 검증
        • 
+ *   
      • 로그인/로그아웃 처리
        • 
+ * 
      
+ * 
+ * @see AuthService
+ * @since 1.0
+ */
+private final AuthService authService;
+```
+
+## 📋 예외 클래스 주석 표준
+
+```java
+/**
+ * 사용자 인증 실패 예외
+ * 
+ * 
      로그인 시 사용자 ID 또는 비밀번호가 올바르지 않을 때 발생하는 예외입니다.
      
+ * 
+ * 
      발생 상황:
      
+ * 
        
+ *   
      • 존재하지 않는 사용자 ID
        • 
+ *   
      • 잘못된 비밀번호
        • 
+ *   
      • 계정 잠금 상태
        • 
+ * 
      
+ * 
+ * 
      처리 방법:
      
+ * 
        
+ *   
      • 사용자에게 일반적인 오류 메시지 표시
        • 
+ *   
      • 보안 로그에 상세 정보 기록
        • 
+ *   
      • 브루트 포스 공격 방지 로직 실행
        • 
+ * 
      
+ * 
+ * @author cms-team
+ * @version 1.0
+ * @since 2024-01-01
+ * 
+ * @see AuthService
+ * @see SecurityException
+ */
+public class InvalidCredentialsException extends RuntimeException {
+    // ...
+}
+```
+
+## 📋 인터페이스 주석 표준
+
+```java
+/**
+ * 사용자 인증 서비스 인터페이스
+ * 
+ * 
      사용자 로그인, 로그아웃, 토큰 관리 등 인증 관련 기능을 정의합니다.
      
+ * 
+ * 
      구현 클래스:
      
+ * 
        
+ *   
      • {@link AuthServiceImpl} - 기본 구현체
        • 
+ *   
      • {@link LdapAuthService} - LDAP 연동 구현체
        • 
+ * 
      
+ * 
+ * 
      주요 기능:
      
+ * 
        
+ *   
      • 사용자 인증 및 토큰 생성
        • 
+ *   
      • 로그아웃 및 토큰 무효화
        • 
+ *   
      • 토큰 유효성 검증
        • 
+ * 
      
+ * 
+ * @author cms-team
+ * @version 1.0
+ * @since 2024-01-01
+ * 
+ * @see AuthServiceImpl
+ * @see TokenProvider
+ */
+public interface AuthService {
+    // ...
+}
+```
+
+## 📋 Enum 주석 표준
+
+```java
+/**
+ * 사용자 역할 열거형
+ * 
+ * 
      시스템 사용자의 권한 수준을 정의합니다.
      
+ * 
+ * 
      권한 계층:
      
+ * 
        
+ *   
      1. {@link #ADMIN} - 최고 관리자 권한
        2. 
+ *   
      2. {@link #MANAGER} - 관리자 권한
        3. 
+ *   
      3. {@link #USER} - 일반 사용자 권한
        4. 
+ * 
      
+ * 
+ * @author cms-team
+ * @version 1.0
+ * @since 2024-01-01
+ */
+public enum Role {
+    
+    /**
+     * 시스템 관리자
+     * 
+     * 
      모든 시스템 기능에 대한 접근 권한을 가집니다.
      
+     * 
+     * 
      주요 권한:
      
+     * 
        
+     *   
      • 사용자 관리
        • 
+     *   
      • 시스템 설정
        • 
+     *   
      • 모든 데이터 접근
        • 
+     * 
      
+     */
+    ADMIN,
+    
+    /**
+     * 관리자
+     * 
+     * 
      제한된 관리 기능에 대한 접근 권한을 가집니다.
      
+     */
+    MANAGER,
+    
+    /**
+     * 일반 사용자
+     * 
+     * 
      기본적인 시스템 기능에 대한 접근 권한을 가집니다.
      
+     */
+    USER
+}
+```
+
+## 📋 주석 작성 체크리스트
+
+### ✅ **클래스 주석 체크리스트**
+- [ ] 클래스의 목적과 역할 명시
+- [ ] 주요 기능 목록 작성
+- [ ] 사용 예시 코드 포함
+- [ ] 주의사항 및 제약사항 명시
+- [ ] @author, @version, @since 태그 작성
+- [ ] 관련 클래스 @see 태그 추가
+
+### ✅ **메서드 주석 체크리스트**
+- [ ] 메서드의 목적과 동작 설명
+- [ ] 처리 과정 단계별 설명
+- [ ] 모든 @param 태그 작성
+- [ ] @return 태그 작성 (void 메서드 제외)
+- [ ] 가능한 예외 @throws 태그 작성
+- [ ] 보안 관련 주의사항 명시
+- [ ] 관련 메서드 @see 태그 추가
+
+### ✅ **HTML 태그 체크리스트**
+- [ ] 목록은 `
        `, `
          `, `
        1. ` 태그 사용
+- [ ] 강조는 `` 태그 사용
+- [ ] 단락 구분은 `
          ` 태그 사용
+- [ ] 코드는 `` 또는 `
          ` 태그 사용
+- [ ] 제네릭 타입은 `<`, `>` 사용
+
+## 📋 도구 및 설정
+
+### 1. **JavaDoc 생성**
+```bash
+# Gradle 프로젝트
+./gradlew javadoc
+
+# Maven 프로젝트
+mvn javadoc:javadoc
+
+# 직접 실행
+javadoc -d docs -cp classpath src/**/*.java
+```
+
+### 2. **IDE 설정**
+- **IntelliJ IDEA**: Settings > Editor > Code Style > Java > JavaDoc
+- **Eclipse**: Window > Preferences > Java > Code Style > Code Templates
+- **VS Code**: Java Extension Pack + JavaDoc 플러그인
+
+### 3. **정적 분석 도구**
+- **Checkstyle**: JavaDoc 누락 검사
+- **SpotBugs**: 주석 품질 검사
+- **SonarQube**: 문서화 품질 메트릭
+
+## 📋 참고 자료
+
+- [Oracle JavaDoc 가이드](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html)
+- [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)
+- [Spring Framework 주석 스타일](https://github.com/spring-projects/spring-framework/wiki/Code-Style)
+
+---
+
+> **💡 팁**: 이 가이드를 팀 내에서 공유하고, 코드 리뷰 시 주석 품질도 함께 검토하세요!
\ No newline at end of file
diff --git a/claude/standard_package_structure.md b/claude/standard_package_structure.md
new file mode 100644
index 0000000..81a4890
--- /dev/null
+++ b/claude/standard_package_structure.md
@@ -0,0 +1,173 @@
+패키지 구조 표준
+
+레이어드 아키텍처 패키지 구조
+
+├── {SERVICE}
+│   ├── domain
+│   ├── service
+│   ├── controller
+│   ├── dto
+│   ├── repository
+│   │   ├── jpa
+│   │   └── entity
+│   ├── config
+└── common
+        ├── dto
+        ├── util
+        ├── response
+        └── exception
+
+Package명: 
+- com.{ORG}.{ROOT}.{SERVICE}
+예) com.unicorn.lifesub.mysub, com.unicorn.lifesub.common
+
+변수: 
+- ORG: 회사 또는 조직명
+- ROOT: Root Project 명
+- SERVICE: 서비스명으로 Root Project의 서브 프로젝트임
+
+
+예시
+
+com.unicorn.lifesub.member
+ ├── MemberApplication.java
+ ├── controller
+ │   └── MemberController.java
+ ├── dto
+ │   ├── LoginRequest.java
+ │   ├── LogoutRequest.java
+ │   └── LogoutResponse.java  
+ ├── service
+ │   ├── MemberService.java
+ │   └── MemberServiceImpl.java
+ ├── domain
+ │   └── Member.java
+ ├── repository  
+ │   ├── entity
+ │   │   └── MemberEntity.java
+ │   └── jpa
+ │       └── MemberRepository.java
+ └── config
+     ├── SecurityConfig.java
+     ├── DataLoader.java
+     ├── SwaggerConfig.java
+     └── jwt
+         ├── JwtAuthenticationFilter.java
+         ├── JwtTokenProvider.java
+         └── CustomUserDetailsService.java
+
+
+클린 아키텍처 패키지 구조 
+
+├── biz
+│   ├── usecase
+│   │   ├── in
+│   │   ├── out
+│   ├── service
+│   └── domain
+│   └── dto
+├── infra
+│   ├── controller
+│   ├── dto
+│   ├── gateway
+│   │   ├── repository
+│   │   └── entity
+│   └── config    
+
+
+Package명: 
+- com.{ORG}.{ROOT}.{SERVICE}.biz
+- com.{ORG}.{ROOT}.{SERVICE}.infra
+예) com.unicorn.lifesub.mysub.biz, com.unicorn.lifesub.common
+
+변수: 
+- ORG: 회사 또는 조직명
+- ROOT: Root Project 명
+- SERVICE: 서비스명으로 Root Project의 서브 프로젝트임
+
+예시
+
+
+com.unicorn.lifesub.mysub
+ ├── biz
+ │   ├── dto
+ │   │   ├── CategoryResponse.java
+ │   │   ├── ServiceListResponse.java
+ │   │   ├── MySubResponse.java
+ │   │   ├── SubDetailResponse.java
+ │   │   └── TotalFeeResponse.java
+ │   ├── service
+ │   │   ├── FeeLevel.java
+ │   │   └── MySubscriptionService.java
+ │   ├── usecase
+ │   │   ├── in
+ │   │   │   ├── CancelSubscriptionUseCase.java
+ │   │   │   ├── CategoryUseCase.java
+ │   │   │   ├── MySubscriptionsUseCase.java
+ │   │   │   ├── SubscribeUseCase.java
+ │   │   │   ├── SubscriptionDetailUseCase.java
+ │   │   │   └── TotalFeeUseCase.java
+ │   │   └── out 
+ │   │       ├── MySubscriptionReader.java
+ │   │       ├── MySubscriptionWriter.java
+ │   │       └── SubscriptionReader.java
+ │   └── domain
+ │       ├── Category.java
+ │       ├── MySubscription.java
+ │       └── Subscription.java
+ └── infra  
+     ├── MySubApplication.java 
+     ├── controller
+     │   ├── CategoryController.java
+     │   ├── MySubController.java
+     │   └── ServiceController.java
+     ├── config
+     │   ├── DataLoader.java
+     │   ├── SecurityConfig.java
+     │   ├── SwaggerConfig.java
+     │   └── jwt
+     │       ├── JwtAuthenticationFilter.java
+     │       └── JwtTokenProvider.java
+     └── gateway
+         ├── entity
+         │   ├── CategoryEntity.java   
+         │   ├── MySubscriptionEntity.java
+         │   └── SubscriptionEntity.java
+         ├── repository
+         │   ├── CategoryJpaRepository.java
+         │   ├── MySubscriptionJpaRepository.java
+         │   └── SubscriptionJpaRepository.java  
+         ├── MySubscriptionGateway.java
+         └── SubscriptionGateway.java
+
+
+---
+
+common 모듈 패키지 구조
+
+├── common
+    ├── dto
+    ├── entity
+    ├── config
+    ├── util
+    └── exception
+
+
+com.unicorn.lifesub.common
+ ├── dto
+ │   ├── ApiResponse.java
+ │   ├── JwtTokenDTO.java
+ │   ├── JwtTokenRefreshDTO.java
+ │   └── JwtTokenVerifyDTO.java
+ ├── config
+ │   └── JpaConfig.java
+ ├── entity
+ │   └── BaseTimeEntity.java        
+ ├── aop  
+ │   └── LoggingAspect.java
+ └── exception
+     ├── ErrorCode.java
+     ├── InfraException.java
+     └── BusinessException.java
+
+
diff --git a/claude/standard_testcode.md b/claude/standard_testcode.md
new file mode 100644
index 0000000..1eec6d5
--- /dev/null
+++ b/claude/standard_testcode.md
@@ -0,0 +1,214 @@
+1.TDD 기본 이해
+
+1) TDD 목적  
+   코드 품질 향상으로 유지보수 비용 절감
+- 설계 품질 향상: 테스트를 먼저 작성하면서 코드 구조와 인터페이스를 먼저 고민
+- 회귀 버그 방지: 테스트 자동화로 코드 변경 시 기존 기능의 오작동을 빠르게 감지
+- 리팩토링 검증: 코드 개선 후 테스트 코드로 검증할 수 있어 리팩토링에 대한 자신감 확보
+- 살아있는 문서: 테스트 코드에 샘플 데이터를 이용한 예시가 있으므로 실제 코드의 동작 방식을 문서화
+
+---  
+
+2) 테스트 유형
+- 단위 테스트(Unit Test): 외부 기술요소(DB, 웹서버 등)와의 인터페이스 없이 단위 클래스의 퍼블릭 메소드 테스트
+- 통합 테스트(Integration Test): 일부 아키텍처 영역에서 외부 기술 요소와 인터페이스까지 테스트
+- E2E 테스트(E2E Test): 모든 아키텍처 영역에서 외부 기술 요소와 인터페이스를 테스트
+
+* 아키텍처 영역: 클래스를 아키텍처적으로 나눈 레이어를 의미함(예: controller, service, domain, repository)
+
+---
+
+3) 테스트 피라미드
+
+- 단위 테스트 70%, 통합 테스트 20%, E2E 테스트 10%의 비율로 권장
+- Mike Cohn이 "Succeeding with Agile"에서 처음 제시한 개념
+- 단위 테스트에서 E2E 테스트로 가면서 속도는 느려지고 비용은 높아짐
+
+---
+
+4) Red-Green-Refactor 사이클
+
+Red-Green-Refactor는 TDD(Test-Driven Development)를 수행하는 핵심 사이클임
+- Red (실패하는 테스트 작성)
+    - 새로운 기능에 대한 테스트 코드를 먼저 작성
+    - 아직 구현이 없으므로 테스트는 실패
+    - 이 단계에서 기능의 인터페이스를 설계
+- Green (테스트 통과하는 코드 작성)
+    - 테스트를 통과하는 최소한의 코드 작성
+    - 품질보다는 동작에 초점
+- Refactor (리팩토링)
+    - 중복 제거, 가독성 개선
+    - 테스트는 계속 통과하도록 유지
+    - 코드 품질 개선
+
+---
+2. 테스트 전략
+
+1) 테스트 수행 원칙: FIRST 원칙
+- Fast: 테스트는 빠르게 실행되어야 함
+- Isolated: 각 테스트는 독립적이어야 함
+- Repeatable: 어떤 환경에서도 동일한 결과가 나와야 함
+- Self-validating: 테스트는 성공/실패가 명확해야 함
+- Timely: 테스트는 실제 코드 작성 전/직후에 작성되어야 함
+
+---
+
+2) 공통 전략: 테스트 코드 작성 관련
+- 한 테스트는 한 가지만 테스트
+- Given-When-Then 패턴 사용
+    - Given(준비): 테스트에 필요한 상태와 데이터를 설정
+    - When(실행): 테스트하려는 동작을 수행
+    - Then(검증): 기대하는 결과가 나왔는지 확인
+- 깨끗한 테스트 코드 작성
+    - 테스트 의도를 명확히 하는 네이밍
+    - 테스트 케이스는 시나리오 중심으로 구성
+    - 공통 설정은 별도 메서드로 분리
+    - 매직넘버 대신 상수 사용
+    - 테스트 데이터는 최소한으로 사용
+- 경계값 테스트가 중요
+    - null 값
+    - 빈 컬렉션
+    - 최대/최소값
+    - 0이나 1과 같은 특수값
+    - 잘못된 포맷의 입력값
+
+---
+
+2) 공통 전략: 테스트 코드 관리 관련
+- 비용 효율적인 테스트 전략
+    - 자주 변경되는 비즈니스 로직에 대한 테스트 강화
+    - 실제 운영 환경과 유사한 통합 테스트 구성
+    - 테스트 실행 시간과 리소스 사용량 모니터링
+- 지속적인 테스트 개선
+    - 테스트 커버리지보다 테스트 품질 중시
+    - 깨진 테스트는 즉시 수정하는 문화 정착
+    - 테스트 코드도 실제 코드만큼 중요하게 관리
+- 팀 협업을 위한 가이드라인 수립
+    - 테스트 네이밍 컨벤션 수립
+    - 테스트 데이터 관리 전략 합의
+    - 테스트 실패 시 대응 프로세스 수립
+
+---
+
+3) 단위 테스트 전략
+- 테스트 범위 명확화
+    - 클래스의 각 public 메소드가 수행하는 단일 책임을 검증
+    - private 메서드는 public 메서드를 통해 간접적으로 테스트
+- 외부 의존성 처리
+    - DB, 파일, 네트워크 등 외부 시스템은 가짜 객체로 대체(Mocking)
+    - 테스트 더블(스턴트맨을 Stunt Double이라고 함. 대역으로 이해)은 꼭 필요한 동작만 구현
+        - Mock: 메소드 호출 여부와 파라미터 검증
+        - Stub: 반환값의 일치 여부 검증
+        - Spy: Mocking하지 않고 실제 메소드를 감싸서 호출횟수, 호출순서등 추가 정보 검증
+- 격리성 확보
+    - 테스트 간 상호 영향 없도록 설계: 동일 공유 자원/객체를 사용하지 않게 함
+    - 테스트 실행 순서와 무관하게 동작
+- 가독성과 유지보수성
+    - 테스트 대상 클래스당 하나의 테스트 클래스
+    - 테스트 메서드는 한 가지 시나리오만 검증
+
+---
+
+4) 단위 테스트 시 Mocking 전략
+- 외부 시스템(DB, 외부 API 등)은 반드시 Mocking
+- 같은 레이어의 의존성 있는 클래스는 실제 객체 사용
+- 예외적으로 의존 객체가 매우 복잡하거나 무거운 경우 Mocking 고려
+
+* 참고: 모의 객체 테스트 균형점 찾기  
+  출처: When to mocking by Uncle Bob(https://blog.cleancoder.com/uncle-bob/2014/05/10/WhenToMock.html)
+- 모의 객체를 이용 안 하면: 테스트가 오래 걸리고 결과를 신뢰하기 어려우며 인프라에 너무 많은 영향을 받음
+- 모의 객체를 지나치게 사용하면: 복잡하고 수정에 영향을 너무 많이 받으며 모의 인터페이스가 폭발적으로 증가
+- 균형점 찾기
+    - 아키텍처적으로 중요한 경계에서만 모의 테스트를 수행하고, 그 경계 안에서는 하지 않는다.  
+      (Mock across architecturally significant boundaries, but not within those boundaries.)
+    - 여기서 경계란 Controller, Service, Repository, Domain등의 레이어를 의미함
+
+---
+5) 통합 테스트 전략
+- 웹 서버 인터페이스
+    - @WebMvcTest, @WebFluxTest 활용
+    - Controller 계층의 요청/응답 검증
+    - Service 계층은 Mocking 처리
+
+- Database 인터페이스
+    - @DataJpaTest 활용
+    - TestContainer로 실제 DB 엔진 실행
+
+- 외부 서비스 인터페이스
+    - WireMock 등을 활용한 Mocking
+    - 실제 API 스펙 기반 테스트
+
+- 테스트 환경 구성
+    - 테스트용 별도 설정 파일 구성
+    - 테스트 데이터는 테스트 시작 시 초기화
+    - @Transactional을 활용한 테스트 격리
+    - 테스트 간 독립성 보장
+
+---
+6) E2E 테스트 전략
+- 원칙
+    - 단위 테스트나 컴포넌트 테스트에서 놓칠 수 있는 시나리오를 찾아내는 것이 목표임
+    - 조건별 로직이나 분기 상황(edge cases)이 아닌 상위 수준의 일반적인 시나리오만 테스트
+    - 만약 어떤 시스템 테스트 시나리오가 실패 했는데 단위 테스트나 통합 테스트가 없다면 만들어야 함
+
+- 운영과 동일한 테스트 환경 구성: 웹서버/WAS, DB, 캐시, MQ, 외부시스템
+- 테스트 데이터 관리
+    - 테스트용 마스터 데이터 구성
+    - 시나리오별 테스트 데이터 세트 준비
+    - 데이터 초기화 및 정리 자동화
+- 테스트 자동화 전략
+    - UI 테스트: Selenium, Cucumber, Playwright 등 도구 활용
+    - API 테스트: Rest-Assured, Postman 등 도구 활용
+
+---
+
+7) 테스트 코드 네이밍 컨벤션
+
+- 패키지 네이밍
+```
+[Syntax]
+{프로덕션패키지}.test.{테스트유형}
+
+[Example]
+- 단위테스트: com.company.order.test.unit
+- 통합테스트: com.company.order.test.integration
+- E2E테스트: com.company.order.test.e2e
+```
+
+- 클래스 네이밍
+```
+[Syntax]
+{대상클래스}{테스트유형}Test
+
+[Example]
+- 단위테스트: OrderServiceUnitTest
+- 통합테스트: OrderServiceIntegrationTest
+- E2E테스트: OrderServiceE2ETest
+```
+
+- 메소드 네이밍
+```
+[Syntax]
+given{초기상태}_when{행위}_then{결과}
+
+[Example]
+givenEmptyCart_whenAddItem_thenSuccess()
+givenInvalidToken_whenAuthenticate_thenThrowException()
+givenExistingUser_whenUpdateProfile_thenProfileUpdated()
+```
+
+- 테스트 데이터 네이밍
+```
+[Syntax]
+상수: {상태}_{대상}
+변수: {상태}{대상}
+
+[Example]
+// 상수
+VALID_USER_ID = 1L
+EMPTY_ORDER_LIST = Collections.emptyList()
+
+// 변수
+normalUser = new User(...)
+emptyCart = new Cart()
+```