# OAuth 2.0 인증 시스템 프로젝트

> aimond.io 에서 서비스할 대상 시스템의 프로토타입을 구성합니다.

## 📋 목차
- [프로젝트 개요](#프로젝트-개요)
- [시스템 아키텍처](#시스템-아키텍처)
- [기술 스택](#기술-스택)
- [서비스 구성](#서비스-구성)
- [빠른 시작](#빠른-시작)
- [개발 가이드](#개발-가이드)
- [API 문서](#api-문서)
- [배포 가이드](#배포-가이드)
- [문서](#문서)

## 🎯 프로젝트 개요

엔터프라이즈급 OAuth 2.0 기반 중앙 인증 시스템으로, 멀티 테넌트 환경에서 동적 테마 적용 및 세분화된 권한 관리를 제공합니다.

### 주요 특징
- ✅ **OAuth 2.0 표준 준수**: 완벽한 OAuth 2.0 플로우 구현
- ✅ **동적 테마 시스템**: 애플리케이션별 맞춤형 인증 페이지
- ✅ **3단계 권한 체계**: System Admin, Group Admin, User
- ✅ **API Gateway**: Apache APISIX를 통한 트래픽 관리
- ✅ **마이크로서비스 아키텍처**: 확장 가능한 서비스 구조
- ✅ **컨테이너 기반**: Docker를 통한 일관된 개발/운영 환경

## 🏗️ 시스템 아키텍처

```mermaid
graph TB
    subgraph "Client Layer"
        Browser[사용자 브라우저]
        Mobile[모바일 앱]
        API[API 클라이언트]
    end
    
    subgraph "API Gateway Layer"
        APISIX[Apache APISIX<br/>Rate Limiting<br/>Authentication<br/>Load Balancing]
        etcd[etcd<br/>Service Discovery]
    end
    
    subgraph "Application Services"
        OAuth[OAuth Service<br/>FastAPI]
        Frontend[Web Frontend<br/>React + Vite]
    end
    
    subgraph "Data Layer"
        MongoDB[(MongoDB<br/>Users/Apps/History)]
        Redis[(Redis<br/>Cache/Session)]
    end
    
    Browser --> APISIX
    Mobile --> APISIX
    API --> APISIX
    APISIX <--> etcd
    APISIX --> OAuth
    APISIX --> Frontend
    OAuth --> MongoDB
    OAuth --> Redis
```

## 🛠️ 기술 스택

### API Gateway
- **Apache APISIX 3.8.0**: 고성능 API Gateway
- **etcd 3.5**: 서비스 디스커버리 및 설정 관리

### Backend
- **Python 3.11**: 메인 프로그래밍 언어
- **FastAPI**: 고성능 웹 프레임워크
- **Motor**: MongoDB 비동기 드라이버
- **Authlib**: OAuth 2.0 구현
- **Celery**: 비동기 작업 처리

### Frontend
- **React 18**: UI 라이브러리
- **Vite**: 빌드 도구
- **TypeScript**: 타입 안정성
- **shadcn/ui**: UI 컴포넌트
- **Tailwind CSS**: 유틸리티 CSS
- **Zustand**: 상태 관리
- **React Query**: 서버 상태 관리

### Database & Cache
- **MongoDB 7.0**: 메인 데이터베이스
- **Redis 7**: 캐싱 및 세션 관리

### DevOps
- **Docker & Docker Compose**: 컨테이너화
- **Kubernetes**: 프로덕션 오케스트레이션
- **Nexus**: 아티팩트 저장소

## 📦 서비스 구성

### 1. OAuth 인증 서비스 (`/oauth`)

#### 백엔드 (`/oauth/backend`)
FastAPI 기반 OAuth 2.0 인증 서버

**주요 기능:**
- OAuth 2.0 Authorization Code Flow
- JWT 토큰 발급 및 검증
- 사용자 인증 및 권한 관리
- 애플리케이션 등록 및 관리
- 인증 히스토리 추적

**디렉토리 구조:**
```
oauth/backend/
├── app/
│   ├── api/           # API 엔드포인트
│   ├── core/          # 핵심 설정 및 유틸리티
│   ├── models/        # 데이터 모델
│   ├── services/      # 비즈니스 로직
│   └── main.py        # 애플리케이션 진입점
├── tests/             # 테스트 코드
├── requirements.txt   # Python 의존성
└── Dockerfile        # 컨테이너 이미지
```

#### 프론트엔드 (`/oauth/frontend`)
React + TypeScript 기반 인증 UI

**주요 기능:**
- 동적 테마 적용 로그인 페이지
- 사용자 프로필 관리
- 애플리케이션 관리 대시보드
- 권한 설정 인터페이스
- 인증 히스토리 뷰어

**디렉토리 구조:**
```
oauth/frontend/
├── src/
│   ├── components/    # React 컴포넌트
│   ├── pages/        # 페이지 컴포넌트
│   ├── hooks/        # Custom Hooks
│   ├── services/     # API 서비스
│   ├── stores/       # 상태 관리
│   └── utils/        # 유틸리티 함수
├── public/           # 정적 파일
└── package.json      # Node.js 의존성
```

### 2. API Gateway (`/apisix`)

Apache APISIX 설정 및 라우팅 규칙

**주요 설정:**
- 라우팅 규칙 (`routes.yaml`)
- Rate Limiting 정책
- JWT 인증 플러그인
- CORS 설정
- 캐싱 전략

**트래픽 제한:**
| 엔드포인트 | Rate Limit | Burst |
|-----------|------------|-------|
| /api/v1/auth/* | 10 req/s | 20 |
| /api/v1/users/* | 100 req/s | 50 |
| /api/v1/applications/* | 50 req/s | 25 |
| /api/v1/admin/* | 200 req/s | 100 |

### 3. 향후 추가될 서비스 (`/services`)

이 디렉토리에는 OAuth 인증을 사용할 서비스들이 추가됩니다.

## 🚀 빠른 시작

### 사전 요구사항
- Docker & Docker Compose
- Git
- Make (선택사항)

### 1. 저장소 클론
```bash
git clone http://gitea.yakenator.io/aimond/works.git
cd works
```

### 2. 환경 변수 설정
```bash
# 백엔드 환경 변수
cp oauth/backend/.env.example oauth/backend/.env
# .env 파일을 열어 필요한 값 수정
```

### 3. Docker Compose로 실행

#### Makefile 사용 (권장)
```bash
# 모든 서비스 시작
make up

# 백그라운드 실행
make up-d

# 로그 확인
make logs

# 서비스 중지
make down
```

#### Docker Compose 직접 사용
```bash
# 모든 서비스 시작
docker-compose up --build

# 백그라운드 실행
docker-compose up -d --build

# 로그 확인
docker-compose logs -f

# 서비스 중지
docker-compose down
```

### 4. 서비스 접속
- **API Gateway**: http://localhost:9080
- **APISIX Dashboard**: http://localhost:9000 (admin/admin123)
- **Frontend**: http://localhost:5173
- **API Documentation**: http://localhost:9080/api/v1/docs

## 💻 개발 가이드

### 개발 환경 규칙
- 모든 개발은 Docker 컨테이너 환경에서 진행
- 서비스 간 의존성은 healthcheck로 관리
- Hot reload 지원 (백엔드/프론트엔드)

### 코드 스타일
- **Python**: Black + Ruff
- **TypeScript**: ESLint + Prettier
- **Commit**: Conventional Commits

### 테스트
```bash
# 백엔드 테스트
make test-backend

# 프론트엔드 테스트
make test-frontend
```

### 디버깅
```bash
# 백엔드 컨테이너 접속
make exec-backend

# MongoDB 쉘 접속
make exec-mongo

# Redis CLI 접속
make exec-redis
```

## 📚 API 문서

### 주요 엔드포인트

#### 인증
- `POST /api/v1/auth/login`: 로그인
- `POST /api/v1/auth/logout`: 로그아웃
- `POST /api/v1/auth/refresh`: 토큰 갱신
- `GET /api/v1/auth/authorize`: OAuth 인증
- `POST /api/v1/auth/token`: 토큰 발급

#### 사용자
- `GET /api/v1/users/me`: 현재 사용자 정보
- `PUT /api/v1/users/me`: 사용자 정보 수정
- `POST /api/v1/users/me/password`: 패스워드 변경

#### 애플리케이션
- `GET /api/v1/applications`: 애플리케이션 목록
- `POST /api/v1/applications`: 애플리케이션 등록
- `PUT /api/v1/applications/{id}`: 애플리케이션 수정
- `DELETE /api/v1/applications/{id}`: 애플리케이션 삭제

상세 API 문서는 [oauth/docs/api-specification.md](oauth/docs/api-specification.md) 참조

## 🚢 배포 가이드

### 환경별 배포

#### 개발 환경 (dev)
```bash
docker-compose up -d
```

#### 검증 환경 (vei)
```bash
cd oauth/configs/vei
docker-compose -f docker-compose.yml up -d
```

#### 운영 환경 (prod)
```bash
kubectl apply -f .k8s/
```

### 백업 및 복구

#### 자동 백업
- 매일 새벽 3시 자동 백업
- 1개월 이상 데이터는 압축 아카이빙

#### 수동 백업
```bash
# MongoDB 백업
docker-compose exec mongodb mongodump --out /backup

# Redis 백업
docker-compose exec redis redis-cli BGSAVE
```

## 📖 문서

### 핵심 문서
- [CLAUDE.md](CLAUDE.md): 프로젝트 규칙 및 가이드
- [Architecture](oauth/docs/architecture.md): 시스템 아키텍처
- [API Specification](oauth/docs/api-specification.md): API 명세
- [APISIX Guide](oauth/docs/apisix-guide.md): API Gateway 가이드

### 개발 문서
- Frontend 개발 가이드 (작성 예정)
- Backend 개발 가이드 (작성 예정)
- 테스트 가이드 (작성 예정)

### 운영 문서
- 모니터링 가이드 (작성 예정)
- 트러블슈팅 가이드 (작성 예정)
- 성능 튜닝 가이드 (작성 예정)

## 🔐 보안

### 보안 기능
- JWT 기반 인증
- Rate Limiting
- IP 제한 (관리자 API)
- CORS 정책
- SQL Injection 방지
- XSS/CSRF 방지

### 보안 체크리스트
- [ ] 환경별 Secret Key 분리
- [ ] HTTPS 적용
- [ ] WAF 설정
- [ ] 정기 보안 감사
- [ ] 취약점 스캔

## 🤝 기여

### Git 협업 규칙
- **원격 저장소**: http://gitea.yakenator.io/aimond/works.git
- **브랜치 전략**: 
  - `main`: 프로덕션
  - `develop`: 개발
  - `feature/*`: 기능 개발
- **커밋 규칙**: 모든 작업 세션은 git commit으로 마무리

### 개발 프로세스
1. Feature 브랜치 생성
2. 개발 및 테스트
3. Pull Request 생성
4. 코드 리뷰
5. Merge

## 📝 라이선스

[LICENSE](LICENSE) 파일 참조

## 👥 팀

- 개발: Claude AI Assistant
- 기획/관리: 사용자

## 🔗 관련 링크

- [Gitea Repository](http://gitea.yakenator.io/aimond/works.git)
- [APISIX Documentation](https://apisix.apache.org/)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [React Documentation](https://react.dev/)

---

**Last Updated**: 2024-12-31
**Version**: 1.0.0