works/CLAUDE.md

# OAuth 2.0 인증 시스템

## 문서 작성 규칙
- 모든 다이어그램은 Mermaid 문법을 사용하여 작성
- 코드 블록은 언어별 하이라이팅 적용
- API 명세는 OpenAPI 3.0 스펙 준수

## 개발 환경 규칙
- **모든 개발은 Docker 컨테이너 환경에서 진행**
- Docker Compose를 통한 통합 개발 환경 구성
- 서비스 간 의존성은 healthcheck를 통해 관리
- 모든 빌드는 depends_on과 condition을 사용하여 순차 실행

## Git 협업 규칙
- **원격 저장소**: http://gitea.yakenator.io/aimond/works.git
- **모든 작업 세션은 git commit으로 마무리**
- 커밋 메시지는 명확하고 구체적으로 작성
- 주요 기능 완료 시 즉시 커밋 및 푸시
- 브랜치 전략: main (production), develop (개발), feature/* (기능별)

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

## 시스템 아키텍처

### 기술 스택
- **API Gateway**: Apache APISIX 3.8.0
- **Frontend**: React 18 + Vite + TypeScript + shadcn/ui + Tailwind CSS
- **Backend**: Python 3.11 + FastAPI + Motor (MongoDB async)
- **Database**: MongoDB 7.0
- **Cache/Queue**: Redis 7
- **Service Discovery**: etcd 3.5
- **Container**: Docker + Docker Compose
- **Orchestration**: Kubernetes (Production)
- **Repository**: Nexus (Artifact Cache)

### 환경 구성
- **dev**: 로컬 개발 환경
- **vei**: 검증계 (Docker 환경)
- **prod**: 운영계 (K8s 환경)

## 공통 섹션

### 프로젝트 구조
```
/
├── oauth/                    # OAuth 인증 시스템
│   ├── backend/             # FastAPI 백엔드
│   ├── frontend/            # React 프론트엔드
│   ├── docs/                # 상세 문서
│   └── configs/             # 환경별 설정
│       ├── dev/
│       ├── vei/
│       └── prod/
├── services/                # 인증을 사용할 서비스들
├── .docker/                 # Docker 관련 파일
├── .k8s/                    # Kubernetes 매니페스트
└── docker-compose.yml       # 개발 환경 구성
```

### 개발 환경 시작하기

#### 사전 요구사항
- Docker & Docker Compose

#### 통합 개발 환경 실행 (Docker Compose)
```bash
# 모든 서비스 실행 (개발 모드)
docker-compose up --build

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

# 로그 확인
docker-compose logs -f [service_name]

# 서비스 중지
docker-compose down

# 볼륨 포함 삭제
docker-compose down -v
```

#### 서비스 접속 URL
- **API Gateway**: http://localhost:9080
- **APISIX Dashboard**: http://localhost:9000 (admin/admin123)
- **Frontend**: http://localhost:5173
- **Backend API**: http://localhost:9080/api/v1 (through APISIX)
- **MongoDB**: mongodb://localhost:27017
- **Redis**: redis://localhost:6379

### API 엔드포인트
- Health Check: `GET http://localhost:9080/health`
- API Documentation: `http://localhost:9080/api/v1/docs`
- APISIX Admin API: `http://localhost:9092/apisix/admin`
- APISIX Dashboard: `http://localhost:9000`

## OAuth 인증 시스템

[상세 문서는 oauth/docs 참조]

### 핵심 기능

#### 1. 사용자 관리
- **3단계 권한 체계**
  - System Admin: 전체 시스템 관리
  - Group Admin: 그룹/조직 관리
  - User: 일반 사용자

#### 2. 애플리케이션 관리
- 동적 테마 설정
- 애플리케이션별 인증 페이지 커스터마이징
- Client ID/Secret 관리
- Redirect URI 설정

#### 3. 권한 및 데이터 공유
- **공유 가능 권한**:
  - 싱글 사인온 (SSO) 여부
  - 이름
  - 성별
  - 생년월일
  - 이메일
  - 전화번호 (선택적)

#### 4. 보안 기능
- JWT 기반 인증
- Refresh Token 관리
- 세션 관리
- 접속 히스토리 추적

#### 5. 데이터 관리
- 접속 히스토리: 1개월 보관 후 압축 아카이빙
- 자동 백업: 매일 새벽 3시 실행
- 데이터 암호화

### 환경 변수 설정

#### 필수 환경 변수
```env
SECRET_KEY=your-secret-key
MONGODB_URL=mongodb://localhost:27017
DATABASE_NAME=oauth_db
REDIS_URL=redis://localhost:6379
ENVIRONMENT=dev
BACKUP_PATH=/var/backups/oauth
ARCHIVE_PATH=/var/archives/oauth
```

### 데이터베이스 스키마

#### Users Collection
- `_id`: ObjectId
- `email`: 이메일 (unique)
- `username`: 사용자명 (unique)
- `full_name`: 전체 이름
- `role`: 권한 (system_admin/group_admin/user)
- `hashed_password`: 암호화된 비밀번호
- `profile_picture`: 프로필 사진 URL
- `created_at`: 생성일시
- `updated_at`: 수정일시
- `last_login`: 마지막 로그인

#### Applications Collection
- `_id`: ObjectId
- `app_name`: 애플리케이션 이름
- `client_id`: OAuth Client ID (unique)
- `client_secret`: OAuth Client Secret
- `redirect_uris`: 허용된 Redirect URI 목록
- `theme`: 테마 설정 (색상, 로고, 폰트 등)
- `created_by`: 생성자 ID
- `created_at`: 생성일시

#### Auth History Collection
- `_id`: ObjectId
- `user_id`: 사용자 ID
- `application_id`: 애플리케이션 ID
- `action`: 인증 액션 (login/logout/token_refresh)
- `ip_address`: IP 주소
- `user_agent`: User Agent
- `created_at`: 발생일시

### 백업 및 아카이빙

#### 자동 백업 (Cron Job)
```bash
0 3 * * * /usr/local/bin/backup-oauth.sh
```

#### 백업 스크립트
```bash
#!/bin/bash
DATE=$(date +%Y%m%d)
mongodump --uri="mongodb://localhost:27017" --db=oauth_db --out=/var/backups/oauth/$DATE
tar -czf /var/backups/oauth/oauth_backup_$DATE.tar.gz /var/backups/oauth/$DATE
rm -rf /var/backups/oauth/$DATE
```

### 배포 가이드

#### Docker 빌드
```bash
# Backend
cd oauth/backend
docker build -t oauth-backend:latest .

# Frontend  
cd oauth/frontend
docker build -t oauth-frontend:latest .
```

#### Kubernetes 배포
```bash
kubectl apply -f .k8s/oauth-namespace.yaml
kubectl apply -f .k8s/oauth-configmap.yaml
kubectl apply -f .k8s/oauth-secret.yaml
kubectl apply -f .k8s/oauth-deployment.yaml
kubectl apply -f .k8s/oauth-ingress.yaml
```

### 모니터링 및 로깅
- Application Logs: `/var/log/oauth/`
- Access Logs: `/var/log/nginx/`
- Error Tracking: Sentry 연동 가능
- Metrics: Prometheus + Grafana

### 성능 최적화
- Redis 캐싱 전략
- MongoDB 인덱싱
- 비동기 처리 (FastAPI + Motor)
- CDN 활용 (정적 자원)

### 보안 체크리스트
- [ ] 환경별 Secret Key 분리
- [ ] HTTPS 적용
- [ ] Rate Limiting 설정
- [ ] CORS 정책 설정
- [ ] SQL Injection 방지
- [ ] XSS 방지
- [ ] CSRF 토큰 구현
- [ ] 민감 정보 암호화

### 트러블슈팅
[상세 내용은 oauth/docs/troubleshooting.md 참조]

### 추가 문서
- [API 명세서](oauth/docs/api-specification.md)
- [보안 가이드](oauth/docs/security-guide.md)
- [성능 튜닝](oauth/docs/performance-tuning.md)
- [마이그레이션 가이드](oauth/docs/migration-guide.md)