api2/docs/project-overview.md

프로젝트 개요

프로젝트 기본 정보

• 프로젝트 유형: Gradle 기반 Spring Boot 애플리케이션
• Java 버전: 21
• Spring Boot 버전: 3.5.10
• 기본 애플리케이션 이름: api
• 기본 포트: 8106
• 실행 진입점: src/main/java/com/alist/api/ApiApplication.java

기술 스택

• 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.8.0)
• 기타: Lombok, Validation, Actuator, log4jdbc

디렉터리 가이드

• src/main/java/com/alist/api: 애플리케이션 시작점과 업무 코드를 둔다.
• src/main/java/com/alist/api/modules: 기능별 모듈 패키지를 둔다.
• src/main/resources: 설정 파일과 로깅 설정을 관리한다.
• deploy: 배포 관련 리소스가 있으면 이 경로를 우선 확인한다.

현재 확인된 구조

• 현재 기준 메인 흐름은 Controller -> Form -> Dto -> Service -> Mapper(XML) -> Vo -> Service -> Controller 순서로 연결된다.
• API 에서 request 받을 때 POST 는 주로 JSON을 사용한다. Controller 는 form 객체로 요청을 받은 뒤 DTO 로 변환해서 Service 에 전달한다.
• MyBatis는 인터페이스와 XML을 함께 사용한다.
• Mapper 인터페이스는 src/main/java/.../mapper, SQL XML은 src/main/resources/mapper/... 경로를 짝으로 맞춘다.
• 공통 응답은 common/response, 보안은 config/security, jwt, 전역 예외 처리는 config/exception 아래에 둔다.
• 모듈 패키지는 현재 admin, cors, file, front, main, migration, tusFile 형태로 구성되어 있고, 필요한 모듈만 dto, form, mapper, service, vo를 둔다.
• front 하위에는 사용자 인증/SSO(auth)와 사용자 관리(user) 흐름을 둔다.
• admin 하위에는 관리자 인증, 회원, 사용자, 스케줄, SSO 클라이언트 관리 흐름을 둔다.
• cors 모듈은 DB 기반 허용 Origin 관리와 캐시 갱신 API를 담당한다.
• file 모듈은 DB 기록 없는 단순 업로드, SunEditor 이미지 업로드, uploadPath 기반 view/download를 담당한다.
• tusFile 모듈은 DB 기록이 필요한 TUS 기반 대용량 업로드 초기화, 업로드 토큰 검증, tusd hook, 상태 조회, 파일 목록/view/download/delete 흐름을 담당한다.