Skip to content

Commit 84a7d22

Browse files
9keyyyyCopilot
9keyyyy
and
Copilot
authored
refactor: four_pillar 모듈 구조 개선 (#27)
* refactor: apply four_pillar srp, clean architecture * Update src/four_pillars/domain/services/data_loader.py Co-authored-by: Copilot <[email protected]> * Update src/four_pillars/domain/services/calculator.py Co-authored-by: Copilot <[email protected]> * Update src/four_pillars/domain/services/data_loader.py Co-authored-by: Copilot <[email protected]> * fix: 불필요 모듈 삭제 * feat: readme 추가 --------- Co-authored-by: Copilot <[email protected]>
1 parent 27f0369 commit 84a7d22

File tree

26 files changed

+816
-1300
lines changed

26 files changed

+816
-1300
lines changed

‎README.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Satto Server
2+
3+
사주 기반 운세 및 로또 추천 서비스 백엔드
4+
5+
## 아키텍처
6+
7+
이 프로젝트는 **Clean Architecture** 패턴을 따릅니다.
8+
9+
### 레이어 구조
10+
11+
각 모듈(`users`, `lotto`, `fortune` 등)은 다음과 같은 레이어 구조를 가집니다:
12+
13+
```
14+
{module}/
15+
├── api/ # API 레이어 (프레젠테이션)
16+
│ ├── router.py # FastAPI 라우터 (엔드포인트 정의)
17+
│ └── schemas.py # 요청/응답 스키마 (Pydantic 모델)
18+
│
19+
├── application/ # 애플리케이션 레이어 (Use Case)
20+
│ └── service.py # 비즈니스 로직 구현, 도메인 조합
21+
│
22+
├── domain/ # 도메인 레이어 (비즈니스 규칙)
23+
│ ├── entities/ # 도메인 엔티티
24+
│ │ ├── models.py # SQLAlchemy 모델
25+
│ │ └── enums.py # 도메인 Enum
26+
│ └── interfaces.py # 리포지토리 인터페이스 (Protocol)
27+
│
28+
└── infrastructure/ # 인프라 레이어 (구현)
29+
└── repository.py # 리포지토리 구현 (데이터베이스 접근)
30+
```
31+
32+
#### 각 레이어의 역할
33+
34+
> **API Layer (`api/`)**
35+
- HTTP 요청/응답 처리
36+
- FastAPI 라우터를 통한 엔드포인트 정의
37+
- 요청 검증 및 응답 직렬화
38+
- 예: `@router.get("/users/{user_id}")` 엔드포인트 정의
39+
40+
> **Application Layer (`application/`)**
41+
- Use Case 구현
42+
- 도메인 로직 조합 및 오케스트레이션
43+
- 트랜잭션 관리
44+
- 예: `UserService.create_user()` - 사용자 생성 Use Case
45+
46+
> **Domain Layer (`domain/`)**
47+
- 비즈니스 규칙 및 도메인 모델
48+
- 외부 의존성 없음 (순수 비즈니스 로직)
49+
- 인터페이스 정의 (의존성 역전 원칙)
50+
- 예: `IUserRepository` 인터페이스, `User` 엔티티
51+
52+
> **Infrastructure Layer (`infrastructure/`)**
53+
- 외부 시스템과의 통신 구현
54+
- 데이터베이스 접근 구현
55+
- 외부 API 클라이언트
56+
- 예: `UserRepository` - MySQL 접근 구현
57+
58+
### 의존성 방향
59+
60+
```
61+
API → Application → Domain ← Infrastructure
62+
```
63+
64+
- **Domain**: 가장 안쪽 레이어, 외부 의존성 없음
65+
- **Application**: Domain을 사용하여 비즈니스 로직 구현
66+
- **Infrastructure**: Domain 인터페이스를 구현
67+
- **API**: Application을 호출하여 HTTP 요청 처리
68+
69+
## 주요 모듈
70+
71+
### `users`
72+
사용자 관리 모듈
73+
- 사용자 생성/조회/수정
74+
- 사주 정보 저장 및 조회
75+
76+
### `four_pillars`
77+
사주 계산 모듈
78+
- 생년월일 기반 사주 계산
79+
- 오행, 십신 분석
80+
- HCX API를 통한 사주 설명 생성
81+
82+
### `fortune`
83+
운세 모듈
84+
- 일일 운세 제공
85+
- 사주 기반 운세 분석
86+
87+
### `lotto`
88+
로또 추천 모듈
89+
- 사주 기반 로또 번호 추천
90+
- 로또 통계 및 당첨 확인
91+
92+
## 시작하기
93+
94+
### 요구사항
95+
- Python 3.13+
96+
- MySQL
97+
- uv (패키지 관리자)
98+
99+
### 설치
100+
101+
```bash
102+
# 의존성 설치
103+
uv sync
104+
105+
# 환경 변수 설정
106+
cp .env.example .env
107+
```
108+
109+
### 실행
110+
111+
```bash
112+
# 개발 서버 실행
113+
uvicorn src.main:app --reload
114+
115+
# 프로덕션 실행
116+
gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker
117+
```
118+
119+
## 전체 프로젝트 구조
120+
121+
```
122+
Satto-Server/
123+
├── src/
124+
│ ├── users/ # 사용자 모듈
125+
│ ├── four_pillars/ # 사주 계산 모듈
126+
│ ├── fortune/ # 운세 모듈
127+
│ ├── lotto/ # 로또 추천 모듈
128+
│ ├── hcx_client/ # HCX API 클라이언트
129+
│ ├── config/ # 설정
130+
│ └── common/ # 공통 유틸리티
131+
├── migrations/ # 데이터베이스 마이그레이션
132+
├── nginx/ # Nginx 설정
133+
└── pyproject.toml # 프로젝트 설정
134+
```
135+
136+
## 기술 스택
137+
138+
- **Framework**: FastAPI
139+
- **Database**: MySQL (SQLAlchemy)
140+
- **Migration**: Alembic
141+
- **Package Manager**: uv
142+
- **Code Quality**: ruff, mypy
143+
144+
145+
## 개발
146+
147+
### 코드 포맷팅
148+
```bash
149+
ruff format .
150+
ruff check .
151+
```
152+
153+
### 타입 체크
154+
```bash
155+
mypy src/
156+
```
157+
158+
### 데이터베이스 마이그레이션
159+
```bash
160+
# 마이그레이션 생성
161+
alembic revision --autogenerate -m "description"
162+
163+
# 마이그레이션 적용
164+
alembic upgrade head
165+
```
166+

‎src/four_pillars/__init__.py‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
"""사주 계산 모듈"""
2+
3+
from src.four_pillars.domain.entities.enums import FiveElements, TenGods
4+
from src.four_pillars.domain.entities.schemas import (
5+
FourPillar,
6+
FourPillarDetail,
7+
PillarInfo,
8+
)
9+
from src.four_pillars.domain.services.calculator import FourPillarsCalculator
10+
from src.four_pillars.infrastructure.description_generator import (
11+
FourPillarDescriptionGenerator,
12+
)
13+
14+
__all__ = [
15+
"FourPillarsCalculator",
16+
"FourPillarDescriptionGenerator",
17+
"FiveElements",
18+
"TenGods",
19+
"FourPillar",
20+
"FourPillarDetail",
21+
"PillarInfo",
22+
]

0 commit comments

Comments
 (0)