docs: readme 문서 작성

Author: ImGdevel

README.md

@@ -1,234 +1,168 @@
 # ProjectVG API Server
 
-JWT + OAuth2 + WebSocket 인증 시스템을 포함한 ASP.NET Core API 서버입니다.
-
-## 🚀 빠른 시작
-
-### 1. 전체 개발 환경 설정 (최초 1회)
-```powershell
-# DB와 Redis를 포함한 전체 환경 설정
-.\scripts\dev-setup.ps1
-```
-
-### 2. API만 빠르게 재빌드 (개발 중)
-```powershell
-# API 코드 변경 후 빠른 재빌드
-.\scripts\start-api.ps1
-```
-
-### 3. 서비스 중지
-```powershell
-# 모든 서비스 중지
-.\scripts\stop-all.ps1
-```
+**Clean Architecture 기반 AI 채팅 플랫폼 백엔드 시스템**
+
+.NET 8.0 ASP.NET Core API 서버로, JWT/OAuth2 인증, WebSocket 실시간 통신, Redis 세션 관리를 구현한 AI 채팅 플랫폼입니다.
+
+## 🏗️ 시스템 아키텍처
+
+### Clean Architecture 구현
+```
+┌─────────────────── Presentation Layer ──────────────────┐
+│ ProjectVG.Api (Controllers, Middleware, Authentication)  │
+├─────────────────── Application Layer ───────────────────┤
+│ ProjectVG.Application (Services, DTOs, Business Logic)  │
+├─────────────────── Domain Layer ────────────────────────┤
+│ ProjectVG.Domain (Entities, Repositories, Domain Rules) │
+├─────────────────── Infrastructure Layer ────────────────┤
+│ ProjectVG.Infrastructure (Database, External Services)  │
+└─────────────────── Common/Tests ────────────────────────┘
+```
+
+### 기술 스택
+- **.NET 8.0**: C# 12, nullable reference types
+- **ASP.NET Core 8.0**: Controllers 기반 REST API
+- **Entity Framework Core 8.0**: Code-First, SQL Server
+- **Redis**: StackExchange.Redis 세션 관리
+- **Authentication**: JWT + Google OAuth2 PKCE
+- **Testing**: xUnit + Moq + FluentAssertions
+- **Container**: Docker + Docker Compose
+
+## 📋 핵심 기능
+
+### 인증 시스템
+- **JWT 토큰**: Access (15분) + Refresh (30일) 이중 토큰
+- **OAuth2 PKCE**: Google 인증, 게스트 로그인
+- **Redis 세션**: 분산 환경 토큰 관리, blacklist 지원
+- **다중 헤더**: Authorization, X-Access-Credit, X-Refresh-Credit
+
+### AI 캐릭터 관리
+- **하이브리드 설정**: JSON 필드 구성 + 직접 프롬프트 입력
+- **소유권 모델**: 시스템/공개/개인 캐릭터 권한 관리
+- **실시간 프롬프트 생성**: 설정 기반 SystemPrompt 동적 구성
+
+### 채팅 시스템
+- **이중 프로토콜**: WebSocket + HTTP REST API
+- **메시지 관리**: User/Assistant/System 역할 기반 대화
+- **외부 서비스 통합**: LLM, Memory, TTS 서비스 연동
+- **페이지네이션**: 대화 기록 효율적 조회
+
+### 크레딧 시스템
+- **금융급 정밀도**: Decimal(18,2) 정확한 잔액 관리
+- **불변 거래 기록**: 완전한 audit trail
+- **동시성 제어**: Optimistic concurrency 일관성 보장
+
+## 🔧 기술 구현
+
+### 성능 최적화
+- **메모리 관리**: IMemoryOwner<byte> LOH 회피, ArrayPool 버퍼 재사용
+- **비동기 패턴**: 모든 I/O 작업 async/await
+- **데이터베이스**: 연결 복원력 (지수 백오프 5회 재시도), 자동 마이그레이션
+- **ConfigureAwait 제거**: ASP.NET Core 환경 최적화로 가독성 향상
+
+### 보안 구현
+- **JWT 보안**: 32자 이상 암호키, 다중 소스 헤더 지원
+- **OAuth2 PKCE**: Proof Key for Code Exchange, CSRF 방지
+- **입력 검증**: Data Annotations + 도메인 레벨 검증
+- **SQL Injection 방지**: EF Core 매개변수화 쿼리
+
+### 테스트 전략
+- **100% 인증 커버리지**: JWT Provider (12), Token Service (15), Auth Service (15), JWT Filter (10) 테스트
+- **다층 테스트**: Unit Tests (Mock), Integration Tests (실제 DB), End-to-End Tests (API)
+- **성능 검증**: Base64 인코딩 13.5% 성능 향상 측정
+
+## 🗄️ 데이터 모델
+
+### Core Entities
+- **User**: OAuth2 기반 사용자, 16자 고유 UID, 크레딧 잔액
+- **Character**: 하이브리드 구성 (JSON/Direct), 공개/개인 구분
+- **ConversationHistory**: 역할별 메시지, 10,000자 제한
+- **CreditTransaction**: 불변 거래 기록, 소스 추적
+
+### 데이터베이스 설계
+- **Optimistic Concurrency**: RowVersion 타임스탬프
+- **JSON 컬럼**: 유연한 캐릭터 설정 저장
+- **정밀 Decimal**: 금융 거래 정확성
+- **인덱스 전략**: 사용자별, 캐릭터별 효율적 조회
+
+## 🌐 API 엔드포인트
+
+### 인증 (`/api/v1/auth`, `/auth`)
+- `POST /api/v1/auth/refresh` - Access Token 갱신
+- `POST /api/v1/auth/logout` - 세션 종료
+- `POST /api/v1/auth/guest-login` - 게스트 인증
+- `GET /auth/oauth2/authorize/{provider}` - OAuth2 시작
+
+### 캐릭터 (`/api/v1/character`)
+- `GET /api/v1/character` - 전체 캐릭터 조회
+- `POST /api/v1/character/individual` - JSON 설정 캐릭터 생성
+- `POST /api/v1/character/systemprompt` - 직접 프롬프트 캐릭터 생성
+- `GET /api/v1/character/my` - 내 캐릭터 관리
+
+### 채팅 및 크레딧
+- `POST /api/v1/chat` - 채팅 메시지 처리 (JWT 필수)
+- `GET /api/v1/credits/balance` - 크레딧 잔액
+- `GET /api/v1/credits/history` - 거래 내역 (페이지네이션)
 
 ## 📁 프로젝트 구조
 
 ```
-ProjectVG Server/
-├── ProjectVG.Api/           # API 레이어
-├── ProjectVG.Application/   # 애플리케이션 레이어
-├── ProjectVG.Domain/        # 도메인 레이어
-├── ProjectVG.Infrastructure/# 인프라 레이어
-├── ProjectVG.Common/        # 공통 라이브러리
-├── ProjectVG.Tests/         # 테스트 프로젝트
-├── scripts/                 # Docker 스크립트
-├── test-clients/           # 테스트 클라이언트
-└── docker-compose.yml      # API 서비스 설정
-```
-
-## 🔧 Docker 최적화 설정
-
-### 분리된 서비스 구조
-- **API 서비스**: `docker-compose.yml` (빠른 재빌드)
-- **DB & Redis**: `docker-compose.db.yml` (별도 관리)
-
-### 빌드 최적화
-- 멀티스테이지 빌드
-- 레이어 캐시 활용
-- .dockerignore로 불필요한 파일 제외
-- NuGet 복원 캐시
-
-### 네트워크 구성
-- API: `projectvg-network`
-- DB/Redis: `projectvg-external-db` (외부 네트워크)
-- localhost 연결로 통신
-
-## 🛠️ 개발 워크플로우
-
-### 초기 설정 (1회만)
-```powershell
-# 전체 개발 환경 설정 (DB + Redis + API)
-.\scripts\dev-setup.ps1
-```
-
-### 개발 중 (매일)
-```powershell
-# 코드 변경 후 API만 재빌드 (빠름!)
-.\scripts\start-api.ps1
-```
-
-### 개별 서비스 관리
-```powershell
-# DB와 Redis만 시작
-.\scripts\start-db.ps1
-
-# API만 시작
-.\scripts\start-api.ps1
-
-# 모든 서비스 중지 및 정리
-.\scripts\stop-all.ps1
-```
-
-### 테스트 실행
-```powershell
-# JWT 인증 시스템 테스트
-dotnet test ProjectVG.Tests/ProjectVG.Tests.csproj
-```
-
-## 🌐 서비스 연결 정보
-
-| 서비스 | URL | 포트 | 설명 |
-|--------|-----|------|------|
-| API | http://localhost:7910 | 7910 | 메인 API 서버 |
-| SQL Server | localhost | 1433 | 데이터베이스 |
-| Redis | localhost | 6380 | 캐시/세션 저장소 |
-
-### 데이터베이스 접속 정보
-- **Server**: localhost:1433
-- **Database**: ProjectVG
-- **Username**: sa
-- **Password**: ProjectVG123!
-
-## 🔐 JWT 인증 시스템
-
-### 주요 기능
-- ✅ JWT Access/Refresh 토큰
-- ✅ OAuth2 로그인 (Google)
-- ✅ 토큰 자동 갱신
-- ✅ Redis 기반 세션 관리
-- ✅ WebSocket 인증 준비
-
-### API 엔드포인트
-- `POST /api/auth/test-login` - 테스트 로그인
-- `POST /api/auth/refresh` - 토큰 갱신
-- `POST /api/auth/logout` - 로그아웃
-- `GET /api/test/me` - 사용자 정보 (인증 필요)
-
-## 🚀 배포
-
-### 자동 배포 (CI/CD)
-`release` 브랜치에 푸시하면 자동 배포됩니다.
-
-### 수동 배포
-```bash
-# 프로덕션 배포
-./deploy.sh
-
-# 개발 환경 배포  
-./deploy-dev.sh
-
-# Windows 환경
-.\scripts\deploy.ps1 -Environment dev
-.\scripts\deploy.ps1 -Environment prod
-```
-
-상세한 배포 가이드는 [DEPLOYMENT.md](DEPLOYMENT.md)를 참조하세요.
-
-## 🧪 테스트
-
-### 테스트 실행
-```powershell
-# 전체 테스트
-dotnet test ProjectVG.Tests/ProjectVG.Tests.csproj
-
-# 특정 테스트 클래스
-dotnet test --filter "FullyQualifiedName~JwtProviderTests"
-```
-
-### 테스트 커버리지
-- **JWT Provider**: 100% (12개 테스트)
-- **Token Service**: 100% (15개 테스트)
-- **Auth Service**: 100% (15개 테스트)
-- **JWT Filter**: 100% (10개 테스트)
-
-### OAuth2 테스트 클라이언트
-
-#### 자동 실행 스크립트
-```powershell
-# PowerShell 스크립트 (권장)
-.\scripts\start-oauth2-client.ps1
-
-# 배치 파일
-.\scripts\start-oauth2-client.bat
-```
-
-#### 수동 실행
-```powershell
-# 테스트 클라이언트 디렉토리로 이동
-cd test-clients
-
-# Python 서버 실행
-python start-oauth2-client.py
-```
-
-#### 브라우저 접속
-```
-http://localhost:3000
-```
-
-#### OAuth2 테스트 기능
-- ✅ PKCE (Proof Key for Code Exchange) 생성
-- ✅ OAuth2 Authorization Code Flow 테스트
-- ✅ Google OAuth2 연동
-- ✅ JWT 토큰 발급 확인
-- ✅ 사용자 정보 표시
-- ✅ 클립보드 복사 기능
-
-## 📝 환경 변수
-
-### 환경 변수 설정
-1. `env.example` 파일을 `.env`로 복사
-2. 필요한 값들을 수정
-
-### 주요 환경 변수
-```bash
-# 외부 서비스 연결
-LLM_BASE_URL=http://localhost:5601
-MEMORY_BASE_URL=http://localhost:5602
-TTS_API_KEY=your-tts-api-key
-
-# 데이터베이스 연결
-DB_CONNECTION_STRING=Server=localhost,1433;Database=ProjectVG;User Id=sa;Password=ProjectVG123!;TrustServerCertificate=true;MultipleActiveResultSets=true
-
-# Redis 연결
-REDIS_CONNECTION_STRING=localhost:6380
-
-# JWT 설정
-JWT_SECRET_KEY=your-super-secret-jwt-key-here-minimum-32-characters
-JWT_ACCESS_TOKEN_LIFETIME_MINUTES=15
-JWT_REFRESH_TOKEN_LIFETIME_DAYS=30
-
-# OAuth2 설정 (선택사항)
-GOOGLE_OAUTH_CLIENT_ID=your-google-client-id
-GOOGLE_OAUTH_CLIENT_SECRET=your-google-client-secret
-```
-
-## 🐛 문제 해결
-
-### 빌드 시간 단축 팁
-1. **DB/Redis 분리**: 한 번 시작하면 재시작 불필요
-2. **캐시 활용**: Docker 레이어 캐시 사용
-3. **선택적 빌드**: API만 재빌드
-
-### 일반적인 문제
-- **포트 충돌**: 다른 서비스가 7910, 1433, 6380 포트 사용 중
-- **DB 연결 실패**: DB 초기화 대기 시간 필요 (30초)
-- **Redis 연결 실패**: Redis 컨테이너 상태 확인
-
-## 📚 추가 문서
-
-- [API 참조](docs/api_reference.md)
-- [아키텍처 가이드](docs/architecture/)
-- [개발 가이드](docs/development/)
-- [코딩 컨벤션](docs/coding_conventions.md)
+ProjectVG.Api/                 # Presentation Layer
+├── Controllers/               # REST API 컨트롤러
+├── Middleware/               # 전역 예외 처리, WebSocket
+├── Filters/                  # JWT 인증 필터
+└── Models/                   # Request/Response DTO
+
+ProjectVG.Application/         # Application Layer
+├── Services/                 # 비즈니스 로직 서비스
+├── Models/                   # 애플리케이션 DTO
+└── Commands/                 # 명령 객체
+
+ProjectVG.Domain/             # Domain Layer
+├── Entities/                 # 도메인 엔티티
+├── Repositories/             # 리포지토리 인터페이스
+└── Common/                   # 기본 엔티티, 값 객체
+
+ProjectVG.Infrastructure/      # Infrastructure Layer
+├── Persistence/              # EF Core DbContext
+├── Auth/                     # JWT, OAuth2 구현
+├── Integrations/            # 외부 서비스 클라이언트
+└── Services/                 # 인프라 서비스
+
+ProjectVG.Tests/              # Test Suite
+├── Api/                     # 컨트롤러, 필터 테스트
+├── Application/             # 서비스 통합 테스트
+├── Auth/                    # 인증 시스템 테스트
+└── Infrastructure/          # 리포지토리, 외부 서비스 테스트
+```
+
+## 🔄 외부 서비스 연동
+
+### 연동 서비스
+- **LLM Service**: AI 모델 추론 처리
+- **Memory Service**: 대화 컨텍스트 관리
+- **TTS Service**: 텍스트 음성 변환
+
+### 데이터 저장소
+- **SQL Server**: 주 데이터베이스 (사용자, 캐릭터, 대화)
+- **Redis**: 세션 관리, 토큰 캐시
+
+## 💡 아키텍처 설계 원칙
+
+### Clean Architecture 적용
+- **의존성 역전**: Domain ← Application ← Infrastructure
+- **관심사 분리**: 각 레이어별 명확한 책임
+- **테스트 가능성**: Mock 기반 단위 테스트
+- **기술 독립성**: 프레임워크에 종속되지 않는 비즈니스 로직
+
+### 도메인 중심 설계
+- **Rich Domain Model**: 엔티티에 비즈니스 로직 캡슐화
+- **Repository Pattern**: 데이터 접근 추상화
+- **Value Objects**: 불변 도메인 개념
+- **Aggregate Root**: 일관성 경계 정의
+
+### 성능 고려사항
+- **비동기 처리**: I/O 바운드 작업 최적화
+- **메모리 효율성**: 대용량 데이터 스트리밍 처리
+- **연결 풀링**: 데이터베이스 연결 최적화
+- **캐싱 전략**: Redis 기반 세션/데이터 캐시