kt-event-marketing/claude/sequence-inner-design.md

# 내부시퀀스설계 가이드 

[요청사항]
- <작성원칙>을 준용하여 설계
- <작성순서>에 따라 설계
- [결과파일] 안내에 따라 파일 작성 

[가이드]  
<작성원칙>
- **유저스토리와 매칭**되어야 함. **불필요한 추가 설계 금지**
- **외부시퀀스설계서에서 설계한 플로우와 일치**해야 함 
- UI/UX설계서의 '사용자 플로우'참조하여 설계
- 마이크로서비스 내부의 처리 흐름을 표시 
- **각 서비스-시나리오별로 분리하여 각각 작성**
- 각 서비스별 주요 시나리오마다 독립적인 시퀀스 설계 수행
- 프론트엔드와 백엔드 책임 분리: 프론트엔드에서 할 수 있는 것은 백엔드로 요청 안하게 함  
- 표현 요소
  - **API 레이어**: 해당 시나리오의 모든 관련 엔드포인트
  - **비즈니스 레이어**: Controller → Service → Domain 내부 플로우
  - **데이터 레이어**: Repository, Cache, External API 접근
  - **인프라 레이어**: 메시지 큐, 이벤트, 로깅 등
- 다이어그램 구성
  - **참여자(Actor)**: Controller, Service, Repository, Cache, External API
  - **생명선(Lifeline)**: 각 참여자의 활동 구간
  - **메시지(Message)**: 동기(→)/비동기(-->) 호출 구분
  - **활성화 박스**: 처리 중인 시간 구간 표시
  - **노트**: 중요한 비즈니스 로직이나 기술적 고려사항 설명
- 참여자가 서비스 내부가 아닌 다른 마이크로 서비스, 외부시스템, 인프라 컴포넌트면 참여자 이름 끝에 '<<E>>'를 붙임 
  예) database "Redis Cache<<E>>" 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
- 서비스명은 영어로 시나리오명은 한글로 작성