shared-dg05-coffeeQuokka/hgzero

Fork 0

mirror of https://github.com/hwanny1128/HGZero.git synced 2025-12-06 12:36:23 +00:00

ondal b98db59c7c 논리아키텍처설계

2025-10-21 13:33:34 +09:00

6.7 KiB

Raw Blame History

공통설계원칙

모든 설계 단계에서 공통으로 적용되는 핵심 원칙과 전략

🎯 핵심 원칙

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)
지속적 개선: 피드백 기반 점진적 발전

🔧 의존성 분석 및 병렬 처리

의존성 분석 방법

서비스 간 의존성 파악

일정 서비스 → 프로파일 서비스 (멤버/여행 정보 조회)
일정 서비스 → 장소 서비스 (장소 정보 조회)  
장소 서비스: 독립적 (외부 API만 사용)

의존성 기반 그룹화

Group A (순차 처리): 프로파일 → 일정 서비스
Group B (독립 처리): 장소 서비스

에이전트 할당 및 병렬 처리

Agent 1: Group A 담당
  - 프로파일 서비스 설계
  - 일정 서비스 설계 (프로파일 참조)

Agent 2: Group B 담당  
  - 장소 서비스 설계 (독립적)

병렬 처리 적용 가이드

API 설계 단계

독립 서비스: 각각 별도 에이전트
의존 서비스: 동일 에이전트 내 순차 처리
공통 검증: 모든 에이전트 완료 후 swagger-cli 검증

시퀀스 설계 단계

외부 시퀀스: 플로우별 병렬 처리 (각 플로우는 독립적)
내부 시퀀스: 서비스별 병렬 처리 (서비스 내부는 독립적)

클래스/데이터 설계 단계

의존성 그룹별: 참조 관계가 있는 서비스들은 순차 처리
독립 서비스: 병렬 처리
공통 클래스: 모든 서비스 설계 완료 후 마지막 처리

🎨 PlantUML 작성 표준

기본 템플릿

@startuml
!theme mono

title [다이어그램 제목]

' 다이어그램 내용
@enduml

필수 검증

각 파일 생성 직후 PlantUML 문법 검사 수행
파이프 방식 권장: cat "파일" | docker exec -i plantuml ...
화살표 문법 주의: sequence diagram에서 ..> 사용 금지

스타일 가이드

폰트 크기: 적절한 가독성 확보
색상 구분: 서비스별, 레이어별 색상 구분
설명 추가: note를 활용한 상세 설명

🔌 API 설계 표준

파일 구조

design/backend/api/{service-name}-api.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 스키마 정의

💡 이 원칙들은 모든 설계 단계에서 일관되게 적용되어야 하며, 각 단계별 세부 가이드에서 구체적으로 구현됩니다.

6.7 KiB Raw Blame History