Initial commit: OAuth 2.0 인증 시스템 프로젝트 초기 설정

- CLAUDE.md: 프로젝트 전체 가이드 및 규칙 정의 - CLAUDE/task-plan.md: 작업 체크리스트 및 상세 계획 - .gitignore: Git 제외 파일 설정 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-05 14:43:42 +09:00
commit abdcc31245
3 changed files with 545 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,79 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.venv
+pip-log.txt
+pip-delete-this-directory.txt
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.npm
+.eslintcache
+*.tsbuildinfo
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+*.env
+!.env.example
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Docker
+*.log
+.docker/data/
+
+# MongoDB
+/data/db/
+
+# Redis
+dump.rdb
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build outputs
+dist/
+build/
+*.egg-info/
+
+# Coverage
+coverage/
+.coverage
+*.cover
+.hypothesis/
+
+# Claude Code
+.claude/settings.local.json
+
+# Backups
+*.backup
+*.bak
+/var/backups/
+/var/archives/
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,236 @@
+# OAuth 2.0 인증 시스템
+
+## 문서 작성 규칙
+- 모든 다이어그램은 Mermaid 문법을 사용하여 작성
+- 코드 블록은 언어별 하이라이팅 적용
+- API 명세는 OpenAPI 3.0 스펙 준수
+
+## 개발 환경 규칙
+- **모든 개발은 Docker 컨테이너 환경에서 진행**
+- Docker Compose를 통한 통합 개발 환경 구성
+- 서비스 간 의존성은 healthcheck를 통해 관리
+- 모든 빌드는 depends_on과 condition을 사용하여 순차 실행
+
+## Git 협업 규칙
+- **원격 저장소**: http://gitea.yakenator.io/aimond/labs.git
+- **저장소 계정**: yakenator / asdfg23we
+- **모든 작업 세션은 git commit으로 마무리**
+- 커밋 메시지는 명확하고 구체적으로 작성
+- 주요 기능 완료 시 즉시 커밋 및 푸시
+- 브랜치 전략: main (production), develop (개발), feature/* (기능별)
+
+## 프로젝트 개요
+엔터프라이즈급 OAuth 2.0 기반 중앙 인증 시스템으로, 멀티 테넌트 환경에서 동적 테마 적용 및 세분화된 권한 관리를 제공합니다.
+
+## 시스템 아키텍처
+
+### 기술 스택
+- **Frontend**: React 18 + Vite + TypeScript + Material-UI (MUI)
+  - 이전: Lucide React + Tailwind CSS
+  - 현재: Material-UI (@mui/material, @emotion/react, @emotion/styled, @mui/icons-material)
+  - 디자인: Google OAuth 스타일 UI/UX
+- **Backend**: Python 3.11 + FastAPI + Motor (MongoDB async)
+- **Database**: MongoDB 7.0
+- **Cache/Queue**: Redis 7
+- **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=3bf17c7f-5446-4a18-9cb3-f885eba501e8
+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`: 수정일시
+
+#### 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
+- `result`: Process Result ( String )
+- `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 .
+```
+
+### 모니터링 및 로깅
+- 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 참조]
--- a/CLAUDE/task-plan.md
+++ b/CLAUDE/task-plan.md
@ -0,0 +1,230 @@
+# OAuth 2.0 인증 시스템 구축 작업 계획
+
+## 작업 체크리스트
+
+### Phase 1: 기본 구조 설정
+
+#### 1. 프로젝트 디렉토리 구조 생성
+- [ ] 메인 디렉토리 생성 (oauth/, services/, .docker/, .k8s/)
+- [ ] OAuth 하위 디렉토리 생성 (backend/, frontend/, docs/, configs/)
+- [ ] 환경별 설정 디렉토리 생성 (configs/dev/, configs/vei/, configs/prod/)
+
+#### 2. Docker Compose 파일 생성
+- [ ] docker-compose.yml 기본 파일 작성
+- [ ] MongoDB 7.0 서비스 정의
+- [ ] Redis 7 서비스 정의
+- [ ] APISIX Gateway 서비스 정의
+- [ ] OAuth Backend 서비스 정의
+- [ ] OAuth Frontend 서비스 정의
+- [ ] 네트워크 및 볼륨 설정
+- [ ] Health check 설정
+- [ ] 서비스 간 의존성 설정 (depends_on)
+
+#### 3. 환경 설정 파일 생성
+- [ ] .env.example 파일 생성
+- [ ] .env.dev 파일 생성
+- [ ] .gitignore 파일 생성
+
+---
+
+### Phase 2: OAuth 백엔드 구축
+
+#### 1. FastAPI 프로젝트 초기화
+- [ ] backend 디렉토리 구조 생성
+- [ ] requirements.txt 파일 작성
+- [ ] Dockerfile 작성
+- [ ] .env.example 작성
+
+#### 2. 기본 앱 구조 생성
+- [ ] app/__init__.py 생성
+- [ ] app/main.py (FastAPI 앱 진입점) 생성
+- [ ] app/config.py (환경 설정) 생성
+
+#### 3. 데이터베이스 모델 정의
+- [ ] app/models/__init__.py 생성
+- [ ] app/models/user.py (사용자 모델) 생성
+- [ ] app/models/application.py (애플리케이션 모델) 생성
+- [ ] app/models/auth_history.py (인증 히스토리 모델) 생성
+
+#### 4. 유틸리티 및 서비스 생성
+- [ ] app/utils/__init__.py 생성
+- [ ] app/utils/database.py (MongoDB 연결) 생성
+- [ ] app/utils/security.py (보안 관련) 생성
+- [ ] app/services/__init__.py 생성
+- [ ] app/services/auth_service.py 생성
+- [ ] app/services/token_service.py (JWT 처리) 생성
+
+#### 5. API 라우터 구현
+- [ ] app/routers/__init__.py 생성
+- [ ] app/routers/auth.py (인증 엔드포인트) 생성
+- [ ] app/routers/users.py (사용자 관리) 생성
+- [ ] app/routers/applications.py (애플리케이션 관리) 생성
+
+#### 6. 핵심 기능 구현
+- [ ] JWT 토큰 생성/검증 로직
+- [ ] 로그인/로그아웃 API
+- [ ] OAuth 2.0 Authorization Code Flow
+- [ ] Refresh Token 관리
+- [ ] 3단계 권한 체계 (System Admin/Group Admin/User)
+
+---
+
+### Phase 3: OAuth 프론트엔드 구축
+
+#### 1. React + Vite 프로젝트 초기화
+- [ ] Vite로 React 프로젝트 생성
+- [ ] TypeScript 설정
+- [ ] package.json 의존성 설정
+- [ ] tsconfig.json 설정
+- [ ] vite.config.ts 설정
+- [ ] Dockerfile 작성
+
+#### 2. MUI 및 기본 설정
+- [ ] Material-UI 설치 및 설정
+- [ ] @emotion/react, @emotion/styled 설치
+- [ ] @mui/icons-material 설치
+- [ ] 테마 설정 파일 생성
+- [ ] 글로벌 스타일 설정
+
+#### 3. 프로젝트 구조 생성
+- [ ] src/components/ 디렉토리 구조 생성
+- [ ] src/pages/ 디렉토리 생성
+- [ ] src/services/ 디렉토리 생성
+- [ ] src/contexts/ 디렉토리 생성
+- [ ] src/hooks/ 디렉토리 생성
+- [ ] src/utils/ 디렉토리 생성
+- [ ] src/types/ 디렉토리 생성
+
+#### 4. 핵심 컴포넌트 개발
+- [ ] AuthContext.tsx (인증 컨텍스트) 생성
+- [ ] Login.tsx (로그인 페이지) 생성
+- [ ] Register.tsx (회원가입 페이지) 생성
+- [ ] Dashboard.tsx (대시보드) 생성
+- [ ] Applications.tsx (애플리케이션 관리) 생성
+
+#### 5. API 서비스 구현
+- [ ] api.ts (API 클라이언트) 생성
+- [ ] 인증 API 연동
+- [ ] 사용자 API 연동
+- [ ] 애플리케이션 API 연동
+
+#### 6. 라우팅 설정
+- [ ] react-router-dom 설정
+- [ ] 보호된 라우트 구현
+- [ ] 네비게이션 구현
+
+---
+
+### Phase 4: 통합 및 테스트
+
+#### 1. Docker Compose 통합
+- [ ] 모든 서비스 Docker 빌드 테스트
+- [ ] docker-compose up 실행 테스트
+- [ ] 서비스 간 연결 확인
+- [ ] Health check 동작 확인
+
+#### 2. API Gateway 설정
+- [ ] APISIX 라우팅 규칙 설정
+- [ ] Backend API 프록시 설정
+- [ ] Frontend 정적 파일 서빙 설정
+- [ ] CORS 정책 설정
+
+#### 3. End-to-End 테스트
+- [ ] 사용자 회원가입 플로우 테스트
+- [ ] 로그인/로그아웃 테스트
+- [ ] OAuth 2.0 인증 플로우 테스트
+- [ ] 권한 관리 테스트
+- [ ] 애플리케이션 관리 테스트
+
+---
+
+### Phase 5: 배포 준비
+
+#### 1. Kubernetes 매니페스트 작성
+- [ ] Namespace 정의
+- [ ] ConfigMap 생성
+- [ ] Secret 생성
+- [ ] Deployment 정의
+- [ ] Service 정의
+- [ ] Ingress 설정
+
+#### 2. 환경별 설정 완료
+- [ ] 개발 환경 (dev) 설정 완료
+- [ ] 검증 환경 (vei) 설정 완료
+- [ ] 운영 환경 (prod) 설정 완료
+
+#### 3. 보안 체크
+- [ ] 환경별 Secret Key 분리
+- [ ] HTTPS 설정
+- [ ] Rate Limiting 설정
+- [ ] XSS/CSRF 방지 설정
+- [ ] 민감 정보 암호화
+
+#### 4. 백업 및 모니터링
+- [ ] 백업 스크립트 작성
+- [ ] Cron job 설정
+- [ ] 로깅 설정
+- [ ] 모니터링 대시보드 설정
+
+---
+
+### Phase 6: 문서화 및 Git 관리
+
+#### 1. 문서화
+- [ ] API 문서 작성 (OpenAPI 3.0)
+- [ ] 사용자 가이드 작성
+- [ ] 관리자 가이드 작성
+- [ ] 트러블슈팅 가이드 작성
+
+#### 2. Git 저장소 관리
+- [ ] Git 초기화
+- [ ] .gitignore 설정
+- [ ] 초기 커밋 생성
+- [ ] 원격 저장소 연결 (http://gitea.yakenator.io/aimond/works.git)
+- [ ] main 브랜치로 푸시
+- [ ] develop 브랜치 생성
+
+---
+
+## 진행 상태
+
+### 현재 진행 중인 작업
+- Phase 1: 기본 구조 설정
+
+### 완료된 작업
+- 작업 계획서 작성
+
+### 다음 작업
+- 프로젝트 디렉토리 구조 생성
+
+---
+
+## 참고사항
+
+### 기술 스택
+- **Frontend**: React 18 + Vite + TypeScript + Material-UI
+- **Backend**: Python 3.11 + FastAPI + Motor (MongoDB async)
+- **Database**: MongoDB 7.0
+- **Cache/Queue**: Redis 7
+- **API Gateway**: APISIX
+- **Container**: Docker + Docker Compose
+- **Orchestration**: Kubernetes (Production)
+
+### 접속 URL (개발 환경)
+- **API Gateway**: http://localhost:9080
+- **APISIX Dashboard**: http://localhost:9000 (admin/admin123)
+- **Frontend**: http://localhost:5173
+- **Backend API**: http://localhost:9080/api/v1
+- **MongoDB**: mongodb://localhost:27017
+- **Redis**: redis://localhost:6379
+
+### 환경 변수 템플릿
+```env
+SECRET_KEY=3bf17c7f-5446-4a18-9cb3-f885eba501e8
+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
+```