197 lines
6.7 KiB
Markdown
197 lines
6.7 KiB
Markdown
# 공통설계원칙
|
|
|
|
모든 설계 단계에서 공통으로 적용되는 핵심 원칙과 전략
|
|
|
|
## 🎯 핵심 원칙
|
|
|
|
### 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 스키마 정의
|
|
|
|
---
|
|
|
|
💡 **이 원칙들은 모든 설계 단계에서 일관되게 적용되어야 하며, 각 단계별 세부 가이드에서 구체적으로 구현됩니다.** |