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
 ```