api2/CLAUDE.md

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

빌드 및 실행

# 빌드
./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/{파일경로}