admin/front 분리

2026-07-20 17:49:24 +09:00
parent 9269278e40
commit ed41ef24cb
673 changed files with 16782 additions and 11277 deletions
@@ -1,38 +1,59 @@
 # 프로젝트 개요

 ## 프로젝트 기본 정보
- 프로젝트 유형: Gradle 기반 Spring Boot 애플리케이션
+
+- 프로젝트 유형: Gradle 기반 Spring Boot 멀티모듈 모놀리식
 - Java 버전: 21
 - Spring Boot 버전: 3.5.10
- 기본 애플리케이션 이름: `api`
- 기본 포트: `8106`
- 실행 진입점: `src/main/java/com/alist/api/ApiApplication.java`
+- 저장소: 단일 Git 저장소
+- 실행 서버: admin, front
+
+## 모듈 구성
+
+| 모듈 | 역할 | 실행 여부 |
+|---|---|---|
+| `01-api-core` | 공통 인프라, 공통 기능, 업무 모듈 | 실행하지 않음 |
+| `02-api-admin` | 관리자 API, 관리자 보안과 Swagger 설정 | `api-admin.jar` |
+| `03-api-front` | 사용자 API, 사용자 보안과 Swagger 설정 | `api-front.jar` |
+
+admin/front는 `01-api-core`에 의존하지만 서로 의존하지 않습니다. 각 bootJar에는 core 라이브러리가 포함되며, 다른 서버의 Controller는 물리적으로 포함되지 않습니다.
+
+## 패키지 구조
+
+```text
+com.alist.api.core
+com.alist.api.admin
+com.alist.api.front
+```
+
+`core`는 다음 책임으로 나눕니다.
+
+- `common`: JWT, 예외, 응답, 페이징, 유틸과 같은 시스템 공통 기능
+- `config`: DataSource, MyBatis, 공통 인프라 설정
+- `modules.standard`: 재사용 가능한 표준 데이터 처리
+- `modules.bespoke`: 기준 테이블의 업무 전용 JOIN·집계·특수 SQL 데이터 접근
+
+`admin`과 `front`에는 Controller, 업무 Service, Form, 외부 응답 VO, 서버별 `SecurityConfig`, `OpenApiConfig`, 환경별 리소스를 둡니다. 업무 정책과 여러 core 호출의 조합, 트랜잭션 경계는 각 실행 모듈 Service가 소유합니다.
+
+admin과 front는 물리적으로 분리된 서버이므로 API path에 서버 구분 접두어를 중복하지 않습니다. 예를 들어 admin 인증 API는 `/admin/auth/login`이 아니라 `/auth/login`으로 둡니다.
+
+## 현재 이관 상태
+
+- 멀티모듈 Gradle 구조와 admin/front 개별 bootJar 구성이 완료되었습니다.
+- 공통 응답, 예외, JWT, DataSource, Mapper XML 리소스는 core로 이동했습니다.
+- 기존 admin/front 업무 API는 core standard/bespoke와 각 실행 모듈 Service 구조로 이관했습니다.
+- 단일 모듈 레거시 소스는 제거했으며, 이전 구현 이력은 Git history로 확인합니다.

 ## 기술 스택
- **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`: 배포 관련 리소스가 있으면 이 경로를 우선 확인한다.
+- Java 21, Spring Boot 3.5.10, Gradle
+- MyBatis, MariaDB, SQL Server 마이그레이션 데이터소스
+- Spring Security, JWT, Redis
+- Swagger / OpenAPI, Actuator, Lombok, Validation, log4jdbc

-## 현재 확인된 구조
- 현재 기준 메인 흐름은 `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 흐름을 담당한다.
+## 빌드 결과
+
+```text
+02-api-admin/build/libs/api-admin.jar
+03-api-front/build/libs/api-front.jar
+```