# alist API

Spring Boot 3 기반의 `alist` 백엔드 API 서버입니다.

## 프로젝트 개요

- 그룹: `com.alist`
- Java: `21`
- Spring Boot: `3.5.10`
- 포트: `8106`
- 빌드 결과물: `build/libs/api.jar`

## 기술 스택

- Spring Web
- Spring Security
- JWT (`jjwt 0.11.5`)
- Spring Session + Redis
- MyBatis (`mapper/**/*.xml`)
- MariaDB
- Swagger / OpenAPI (`springdoc-openapi 2.8.0`)
- Validation
- Actuator
- Lombok
- log4jdbc

## 주요 기능

- JWT 발급 및 검증
- Redis 기반 세션 관리와 쿠키 설정
- Swagger UI Basic 인증 보호
- DB 기반 허용 Origin 캐시를 사용하는 동적 CORS
- TUS 업로드 초기화, 권한 검증, 상태 조회, 완료 처리, 취소 처리
- 파일 조회/다운로드 API
- 공통 응답 래퍼 `ApiResponse<T>` 및 `ApiResponseCode` 사용

## 디렉터리 구조

```text
src/main/java/com/alist/api
├── common
│   ├── modules/file      # 공통 파일 업로드/다운로드 모듈
│   ├── response          # ApiResponse, ApiResponseCode
│   └── utils             # 공통 유틸리티
├── config
│   ├── cache             # CORS 허용 Origin 캐시
│   ├── exception         # 전역 예외 처리
│   ├── filter            # DynamicCorsFilter
│   ├── jwt               # JWT 인증 관련 구성
│   └── properties        # 설정 프로퍼티
└── modules
    ├── auth              # 인증/세션 관련 API
    ├── main              # 루트 리다이렉트
```

리소스 파일은 아래 위치를 사용합니다.

- 설정: `src/main/resources/application*.yaml`
- Mapper XML: `src/main/resources/mapper/**/*.xml`
- 로그 설정: `src/main/resources/logback-*.xml`

## 실행 방법

### 빌드

```bash
./gradlew bootJar
```

### 로컬 실행

```bash
./gradlew bootRun --args='--spring.profiles.active=local'
```

### JAR 실행

```bash
java -jar build/libs/api.jar --spring.profiles.active=local
```

## 프로파일

| 프로파일 | 설명 | 설정 파일 |
| --- | --- | --- |
| `local` | 로컬 개발 환경 | `src/main/resources/application-local.yaml` |
| `pjt` | 프로젝트 개발 서버 환경 | `src/main/resources/application-pjt.yaml` |

공통 설정은 `src/main/resources/application.yaml`에 있습니다.

## 필수 설정 항목

실행 전 아래 설정들이 환경에 맞게 준비되어 있어야 합니다.

### 데이터 저장소

- `spring.datasource.*`
- `spring.data.redis.*`
- `spring.session.*`

### 인증/보안

- `jwt.secret`
- `jwt.access-token-validity-seconds`
- `jwt.refresh-token-validity-seconds`
- `cookie.secure`
- `cookie.domain`
- `cookie.name`
- `cookie.same-site`
- `swagger.login.id`
- `swagger.login.password`

### 파일 업로드

- `file.upload.tus-endpoint`
- `file.upload.public-base-url`
- `file.upload.tmp-root`
- `file.upload.final-root`
- `file.upload.interrupt-seconds`
- `file.upload.auth-cache.ttl-seconds`

`pjt` 프로파일은 DB/Redis/JWT/Swagger 값을 환경변수로 주입받도록 작성되어 있습니다.

## 보안 구조

### Swagger

- 보호 경로: `/v3/api-docs/**`, `/swagger-ui/**`, `/swagger-ui.html`
- 인증 방식: HTTP Basic
- 계정 정보: `swagger.login.id`, `swagger.login.password`

### API

- 기본 인증 방식: JWT Bearer
- 세션 저장소: Redis
- 세션 쿠키: `RedisSessionConfig`에서 도메인, Secure, SameSite 제어

### 공개 경로

- `/`
- `/actuator/health`
- `/auth/**`
- `/files/tusHook`

루트 `/` 요청은 `/swagger-ui/index.html`로 리다이렉트됩니다.

## CORS

`DynamicCorsFilter`가 최우선 필터로 동작하며, 허용 Origin 목록은 `CorsAllowedOriginsCache`에서 조회합니다.

- 허용된 Origin에만 `Access-Control-Allow-Origin` 설정
- Credential 허용
- `OPTIONS` preflight 요청은 `200 OK`로 즉시 응답
- DB를 직접 매 요청마다 조회하지 않고 캐시된 목록을 사용

## 파일 업로드/다운로드

이 프로젝트는 대용량 업로드를 위해 TUS 서버(`tusd`)와 연동합니다. API는 업로드 메타데이터 관리, 업로드 권한 검증, 상태 저장, 완료/취소 처리를 담당합니다.

### 주요 업로드 엔드포인트

- `POST /files/uploadInit`
- `GET /files/uploadAuth`
- `POST /files/uploadStatus`
- `POST /files/tusHook`
- `POST /files/uploadCancel`

### 파일 조회 엔드포인트

- `GET /files/list/{fileMasterIdx}`
- `GET /files/view/{fileUuid}`
- `GET /files/download/{fileUuid}`

### 운영 메모

- TUS 업로드 엔드포인트: `https://file-alist.pjt.kr/tus/files/`
- 업로드 임시 경로: `/srv/project/alist/uploads/tmp`
- 업로드 최종 경로: `/srv/project/alist/uploads`
- 정적 파일 도메인: `https://file-alist.pjt.kr`

## 주요 인증 엔드포인트

- `POST /auth/token`
- `POST /auth/refresh`
- `GET /auth/loginChecked`
- `POST /auth/logout`
- `POST /user/signup`

## API 예시 요청/응답

아래 예시는 실제 컨트롤러의 요청 필드와 `ApiResponse<T>` 응답 구조를 기준으로 정리했습니다.

### 1. 토큰 발급

요청:

```http
POST /auth/token
Content-Type: application/json

{
  "id": "test"
}
```

응답 예시:

```json
{
  "data": {
    "id": null,
    "accessToken": "eyJhbGciOiJI..."
  },
  "code": "CODE_2001",
  "message": "임시 토큰 정보 조회에 성공하였습니다."
}
```

### 2. 테스트 회원가입

요청:

```http
POST /test/testSignup
Content-Type: application/json

{
  "id": "testuser01",
  "password": "pass1234"
}
```

응답 예시:

```json
{
  "data": {
    "userIdx": 101,
    "id": "testuser01"
  },
  "code": "CODE_2002",
  "message": "아이디 등록 되었습니다."
}
```

중복일 경우 예시:

```json
{
  "data": {
    "userIdx": null,
    "id": null
  },
  "code": "CODE_2004",
  "message": "중복된 아이디 정보 입니다."
}
```

### 3. 파일 업로드 초기화

요청:

```http
POST /files/uploadInit
Content-Type: application/json
Cookie: ALIST_SESSION=...

{
  "fileCategory": "notice",
  "folderPath": "/2026/03",
  "itemList": [
    {
      "originName": "guide.pdf",
      "sizeBytes": 102400,
      "contentType": "application/pdf"
    }
  ]
}
```

응답 예시:

```json
{
  "data": {
    "fileMasterIdx": 55,
    "tusEndpoint": "https://file-alist.pjt.kr/tus/files/",
    "itemList": [
      {
        "fileSeq": 1,
        "fileUuid": "2f5f3ef1-8a4e-4b2d-84da-1c1111111111",
        "uploadToken": "upload-token-sample",
        "originName": "guide.pdf",
        "sizeBytes": 102400,
        "contentType": "application/pdf"
      }
    ]
  },
  "code": "CODE_200",
  "message": "성공"
}
```

### 4. 업로드 상태 조회

요청:

```http
POST /files/uploadStatus
Content-Type: application/json

{
  "fileUuid": "2f5f3ef1-8a4e-4b2d-84da-1c1111111111"
}
```

응답 예시:

```json
{
  "data": {
    "fileUuid": "2f5f3ef1-8a4e-4b2d-84da-1c1111111111",
    "status": "UPLOADING",
    "uploadedBytes": 51200,
    "totalBytes": 102400,
    "percent": 50,
    "updatedAt": "2026-03-11T09:30:00"
  },
  "code": "CODE_200",
  "message": "성공"
}
```

조회 결과가 없을 경우 예시:

```json
{
  "data": {
    "fileUuid": null,
    "status": null,
    "uploadedBytes": null,
    "totalBytes": null,
    "percent": null,
    "updatedAt": null
  },
  "code": "CODE_2003",
  "message": "조회된 정보가 없습니다."
}
```

## Actuator

외부 노출 대상은 아래와 같습니다.

- `health`
- `info`
- `metrics`

헬스체크 기본 경로:

- `GET /actuator/health`

## 응답 규칙

모든 API 응답은 `ApiResponse<T>` 래퍼를 사용하며, 상태/메시지는 `ApiResponseCode` enum으로 관리합니다.

자주 사용하는 코드 예시는 아래와 같습니다.

| 코드 | HTTP Status | 의미 |
| --- | --- | --- |
| `CODE_200` | `200 OK` | 일반 성공 |
| `CODE_204` | `204 No Contnet` | 일반 성공 |
| `CODE_2001` | `200 OK` | 단건 조회 성공 |
| `CODE_2002` | `201 Created` | 등록 성공 |
| `CODE_2003` | `200 OK` | 조회 결과 없음 |
| `CODE_2004` | `409 Conflict` | 중복 데이터 |
| `CODE_4001` | `400 Bad Request` | 입력값/바인딩 오류 |
| `CODE_4003` | `400 Bad Request` | 필수 파라미터 누락 |
| `CODE_401` | `401 Unauthorized` | 인증 필요 |
| `CODE_403` | `403 Forbidden` | 권한 없음 |
| `CODE_500` | `500 Internal Server Error` | 서버 오류 |

## 배포 관련

- Dockerfile: `Dockerfile`
- Jenkins 파이프라인: `Jenkinsfile.pjt`
- 배포 스크립트: `deploy/`
- 개발 서버 API 도메인: `https://api-alist.pjt.kr`
- 파일 도메인: `https://file-alist.pjt.kr`
- Swagger: `https://api-alist.pjt.kr/swagger-ui/index.html`

## 참고

- Swagger 로컬 접속: [http://localhost:8106/swagger-ui.html](http://localhost:8106/swagger-ui.html)
- 운영 환경에서는 `application-pjt.yaml`의 환경변수 주입 방식 사용을 권장합니다.

## 라이선스

Proprietary