# CLAUDE.md - alist API 프로젝트

## 프로젝트 개요
- **프로젝트명**: alist API
- **그룹**: com.alist
- **포트**: 8106
- **빌드 결과물**: `api.jar`

## 기술 스택
- **Java**: 21
- **Framework**: Spring Boot 3.5.10
- **빌드 도구**: Gradle
- **DB**: MariaDB
- **ORM**: MyBatis (mapper XML: `classpath:mapper/**/*.xml`)
- **인증**: JWT (jjwt 0.11.5) + Spring Security
- **API 문서**: Swagger (springdoc-openapi 2.6.0)
- **기타**: Lombok, Validation, Actuator, log4jdbc

## 패키지 구조
```
com.alist.api
├── common
│   ├── response/     # ApiResponse, ApiResponseCode
│   └── utils/        # 공통 유틸리티
├── config
│   ├── jwt/          # JWT 필터, 핸들러, Provider
│   ├── exception/    # GlobalExceptionHandler
│   ├── properties/   # JwtProperties 등
│   ├── SecurityConfig.java
│   └── OpenApiConfig.java
└── modules
    └── {도메인}/     # Controller, Service, Mapper, DTO
```

## 프로파일
| 프로파일 | 설명 |
|---------|------|
| `local` | 로컬 개발 환경 |
| `pjt` | 프로젝트(운영) 환경 |

## 보안 구조
- **Swagger**: `/v3/api-docs/**`, `/swagger-ui/**` → HTTP Basic 인증 (InMemory)
- **API**: JWT Bearer 토큰 인증 (Stateless)
- **공개 경로**: `/`, `/actuator/health`, `/auth/**`, `/api/user/signup`

## 빌드 및 실행
```bash
# 빌드
./gradlew bootJar

# 로컬 실행
./gradlew bootRun --args='--spring.profiles.active=local'

# JAR 실행
java -jar build/libs/api.jar --spring.profiles.active=local
```

## Swagger 접속
- URL: `http://localhost:8106/swagger-ui.html`
- 인증: `swagger.login.id` / `swagger.login.password` (환경별 yaml에 설정)

## 코드 작성 규칙
- 응답은 `ApiResponse<T>` 래퍼 사용
- 응답 코드는 `ApiResponseCode` enum 사용
- MyBatis Mapper XML은 `src/main/resources/mapper/` 하위에 작성
- 카멜케이스 자동 변환 활성화 (`map-underscore-to-camel-case: true`)
- 새 모듈은 `modules/{도메인}/` 하위에 Controller, Service, Mapper, DTO 구성

## CI/CD
- **Jenkins**: `Jenkinsfile.pjt`
- **Docker**: `Dockerfile`
- **배포 스크립트**: `deploy/` 디렉토리

## 개발 서버 (pjt)

### 도메인
- **API**: `api-alist.pjt.kr`
- **파일(업로드)**: `file-alist.pjt.kr`
- **Swagger**: `https://api-alist.pjt.kr/swagger-ui/index.html`

### Docker
- **레지스트리**: `registry.pjt.kr`
- **이미지**: `registry.pjt.kr/alist/api`
- **컨테이너명**: `alist-api`
- **포트**: `127.0.0.1:8106->8106/tcp`

### 서버 디렉토리 (`/srv/project/alist/`)
```
/srv/project/alist/
├── compose/     # docker-compose 파일
├── data/        # 데이터
├── env/         # 환경변수 파일
├── logs/        # 로그
├── scripts/     # 배포/운영 스크립트
└── uploads/     # 업로드 파일 (file-alist.pjt.kr 루트)
```

### Nginx
- `file-alist.pjt.kr` → `/srv/project/alist/uploads` (정적 파일 서빙)
- HTTP(80) → HTTPS(301) 리다이렉트
- SSL: Let's Encrypt
- 직접 접근 차단 (`allow 127.0.0.1; deny all;`)

### 파일 업로드
- 업로드 저장 경로: `/srv/project/alist/uploads/`
- 업로드 파일 접근 URL: `https://file-alist.pjt.kr/{파일경로}`