[위치이동] file 위치이동

2026-03-13 17:49:36 +09:00
parent 67667724ee
commit a121c7710e
25 changed files with 239 additions and 49 deletions
@@ -37,6 +37,4 @@ out/
 .vscode/

 ### Claude Code ###
-.claude/
-
-AGENTS.md
+.claude/
@@ -0,0 +1,191 @@
+# AGENTS.md - alist API 프로젝트
+
+## Claude 작업 규칙 (중요!)
+
+### 코드 수정 시 반드시 따를 것
+1. **절대로 바로 파일을 수정하지 말 것**
+2. **먼저 수정 방향과 계획을 설명**
+3. **긴 소스 코드를 보여주기 전에 먼저 물어보기** 
+   - "코드 보여드릴까요?" 또는 "직접 수정하시겠어요?"
+   - 사용자가 원하면 코드 보여주기 (사용자가 직접 수정할 수도 있도록)
+4. **파일 작성/수정은 사용자가 요청할 때만**
+
+### 작업 순서 예시
+```
+1. "CORS 설정을 yml로 분리하겠습니다."
+2. "수정 내용:"
+   - CorsProperties.java 생성 필요
+   - CorsConfig.java 수정 필요  
+   - application-local.yaml 수정 필요
+3. "코드 보여드릴까요? 아니면 직접 수정하시겠어요?"
+4. (사용자가 "보여줘"라고 하면) 코드 보여주기
+5. (사용자가 "작성해줘"라고 하면) 파일 수정 진행
+```
+
+### 주의사항
+- **짧은 설명(수정 위치, 수정 방향)은 바로 보여줘도 됨**
+- **전체 메서드/클래스 같은 긴 코드는 반드시 물어본 후 보여주기**
+- **화면이 너무 길어지는 것 방지**
+
+## 프로젝트 개요
+- **프로젝트명**: 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`
+
+## 응답 코드 규칙
+
+`ApiResponseCode` enum으로 관리. 주요 코드:
+
+| 코드 | 메시지 | HTTP Status | 용도 |
+|------|--------|-------------|------|
+| `CODE_200` | 성공 | 200 OK | 일반 성공 |
+| `CODE_400` | 잘못된 요청 | 400 Bad Request | 일반 클라이언트 오류 |
+| `CODE_401` | 인증 필요 합니다. | 401 Unauthorized | 인증 없음 |
+| `CODE_403` | 접근 권한 필요 합니다. | 403 Forbidden | 권한 없음 |
+| `CODE_404` | 페이지를 찾을 수 없습니다. | 404 Not Found | 리소스 없음 |
+| `CODE_405` | 잘못된 요청입니다. 요청 방식을 확인해 주세요. | 405 Method Not Allowed | 메서드 불일치 |
+| `CODE_500` | 요청을 처리하는 중 오류가 발생했습니다. | 500 Internal Server Error | 서버 오류 |
+| `CODE_2001` | {0} 정보 조회에 성공하였습니다. | 200 OK | 단건 조회 성공 |
+| `CODE_2002` | {0} 등록 되었습니다. | 201 Created | 등록 성공 |
+| `CODE_2003` | 조회된 정보가 없습니다. | 200 OK | 조회 결과 없음 |
+| `CODE_2004` | 중복된 {0} 정보 입니다. | 409 Conflict | 중복 데이터 |
+| `CODE_4001` | 입력값을 확인해주세요. | 400 Bad Request | `@Valid` / 바인딩 / 타입오류 / JSON 파싱 실패 |
+| `CODE_4003` | 필수 요청 파라미터가 누락되었습니다. | 400 Bad Request | 필수 파라미터 누락 |
+
+- `{0}` 자리에 대상명 삽입 (예: `CODE_2001` → "회원 정보 조회에 성공하였습니다.")
+
+## 빌드 및 실행
+```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/{moduleName}/` 하위에 Controller, Service, Mapper, dto/, vo/ 구조로 생성
+- Mapper XML은 `resources/mapper/{moduleName}/` 에 위치
+
+## MyBatis 규칙
+- Mapper XML 위치: `src/main/resources/mapper/**/*.xml`
+- `map-underscore-to-camel-case: true` 설정 → DB 컬럼 `user_idx` → Java 필드 `userIdx` 자동 매핑
+- Mapper 인터페이스와 XML의 namespace, id 반드시 일치시킬 것
+- VO: DB 조회 결과 매핑용 / DTO: 서비스 레이어 간 데이터 전달용 / Form: 컨트롤러 입력 검증용
+
+## 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/{파일경로}`
+
+## TUS 업로드 운영 메모 (alist)
+- `tusd`는 API 내 라이브러리가 아니라 별도 실행형 업로드 서버(Go 바이너리)로 운영
+- 내부 바인딩: `127.0.0.1:8110`
+- base path: `/tus/files/`
+- 임시 업로드 경로: `/srv/project/alist/uploads/tmp`
+- 실행 파일 경로: `/srv/project/alist/tusd/tusd`
+
+### Nginx 라우팅
+- `https://file-alist.pjt.kr/tus/files/` -> `http://127.0.0.1:8110/tus/files/` 프록시
+- `location /tus/files/`는 `location /` 보다 구체적이므로 우선 매칭됨
+- `location /`가 차단(`deny all`)이어도 `/tus/files/`는 별도 허용 가능
+
+### systemd
+- 서비스 파일: `/etc/systemd/system/tusd-alist.service`
+- `User`/`Group`은 실제 서버 계정으로 맞춰야 함 (예: `bigfuntnp`)
+- 계정 불일치 시 `status=217/USER`, `Failed to determine user credentials` 발생
+
+### 자주 쓰는 점검
+```bash
+sudo ss -ltnp | grep 8110
+curl --http1.1 -i -X OPTIONS http://127.0.0.1:8110/tus/files/
+curl --http1.1 -i -X OPTIONS https://file-alist.pjt.kr/tus/files/
+```
+
+### 운영 메모
+- `-max-size`는 청크 크기가 아니라 최종 업로드 파일 전체 크기 제한
+- `bind: address already in use` 발생 시 포트 점유 프로세스 확인 후 정리
+- 인증/권한은 API(`init/complete`)에서 관리하고, 실제 업로드 전송은 TUS 경로로 처리
@@ -1,13 +1,13 @@
-package com.alist.api.common.modules.file;
+package com.alist.api.modules.file;

-import com.alist.api.common.modules.file.dto.*;
-import com.alist.api.common.modules.file.form.FileUploadForm;
-import com.alist.api.common.modules.file.form.TusHookForm;
-import com.alist.api.common.modules.file.form.UploadCancelForm;
-import com.alist.api.common.modules.file.form.UploadStatusForm;
+import com.alist.api.modules.file.dto.*;
+import com.alist.api.modules.file.form.FileUploadForm;
+import com.alist.api.modules.file.form.TusHookForm;
+import com.alist.api.modules.file.form.UploadCancelForm;
+import com.alist.api.modules.file.form.UploadStatusForm;
 import com.alist.api.common.response.ApiResponse;
 import com.alist.api.common.response.ApiResponseCode;
-import com.alist.api.common.modules.file.service.FileService;
+import com.alist.api.modules.file.service.FileService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
@@ -20,7 +20,6 @@ import org.springframework.http.*;
 import org.springframework.web.bind.annotation.*;

 import java.io.IOException;
-import java.net.URI;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.dto;
+package com.alist.api.modules.file.dto;

 import com.fasterxml.jackson.annotation.JsonIgnore;
 import lombok.Getter;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.dto;
+package com.alist.api.modules.file.dto;

 import lombok.Getter;
 import lombok.Setter;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.dto;
+package com.alist.api.modules.file.dto;

 import com.fasterxml.jackson.annotation.JsonIgnore;
 import lombok.Getter;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.dto;
+package com.alist.api.modules.file.dto;

 import lombok.Getter;
 import lombok.Setter;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.dto;
+package com.alist.api.modules.file.dto;

 import com.fasterxml.jackson.annotation.JsonIgnore;
 import lombok.Getter;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.dto;
+package com.alist.api.modules.file.dto;

 import com.fasterxml.jackson.annotation.JsonIgnore;
 import lombok.Getter;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.dto;
+package com.alist.api.modules.file.dto;

 import lombok.Getter;
 import lombok.Setter;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.dto;
+package com.alist.api.modules.file.dto;

 import lombok.Getter;
 import lombok.Setter;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.dto;
+package com.alist.api.modules.file.dto;

 import lombok.Getter;
 import lombok.Setter;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.dto;
+package com.alist.api.modules.file.dto;

 import lombok.Getter;
 import lombok.Setter;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.dto;
+package com.alist.api.modules.file.dto;

 import com.fasterxml.jackson.annotation.JsonIgnore;
 import lombok.Getter;
@@ -1,7 +1,7 @@
-package com.alist.api.common.modules.file.form;
+package com.alist.api.modules.file.form;

-import com.alist.api.common.modules.file.dto.FileUploadDto;
-import com.alist.api.common.modules.file.dto.FileUploadItemDto;
+import com.alist.api.modules.file.dto.FileUploadDto;
+import com.alist.api.modules.file.dto.FileUploadItemDto;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotEmpty;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.form;
+package com.alist.api.modules.file.form;

 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.form;
+package com.alist.api.modules.file.form;

 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
@@ -1,6 +1,6 @@
-package com.alist.api.common.modules.file.form;
+package com.alist.api.modules.file.form;

-import com.alist.api.common.modules.file.dto.TusHookDto;
+import com.alist.api.modules.file.dto.TusHookDto;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import lombok.Getter;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.form;
+package com.alist.api.modules.file.form;

 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
@@ -1,4 +1,4 @@
-package com.alist.api.common.modules.file.form;
+package com.alist.api.modules.file.form;

 import jakarta.validation.constraints.NotBlank;
 import lombok.Getter;
@@ -1,6 +1,6 @@
-package com.alist.api.common.modules.file.form;
+package com.alist.api.modules.file.form;

-import com.alist.api.common.modules.file.dto.UploadStatusDto;
+import com.alist.api.modules.file.dto.UploadStatusDto;
 import jakarta.validation.constraints.NotBlank;
 import lombok.Getter;
 import lombok.Setter;
@@ -1,6 +1,6 @@
-package com.alist.api.common.modules.file.mapper;
+package com.alist.api.modules.file.mapper;

-import com.alist.api.common.modules.file.dto.*;
+import com.alist.api.modules.file.dto.*;
 import org.apache.ibatis.annotations.Mapper;

 import java.util.List;
@@ -1,9 +1,8 @@
-package com.alist.api.common.modules.file.service;
+package com.alist.api.modules.file.service;

-import com.alist.api.common.modules.file.dto.*;
-import com.alist.api.common.modules.file.mapper.FileMapper;
+import com.alist.api.modules.file.dto.*;
+import com.alist.api.modules.file.mapper.FileMapper;
 import com.alist.api.config.jwt.JwtTokenProvider;
-import jakarta.servlet.http.HttpServletRequest;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.data.redis.core.HashOperations;
@@ -28,4 +28,7 @@ management:
        include: health,info,metrics
  endpoint:
    health:
-      show-details: always
+      show-details: always
+  health:
+    db:
+      enabled: false
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

-<mapper namespace="com.alist.api.common.modules.file.mapper.FileMapper">
+<mapper namespace="com.alist.api.modules.file.mapper.FileMapper">

    <insert id="insertFileMasterInit" useGeneratedKeys="true" keyProperty="fileMasterIdx">
        /*FileMapper.insertFileMasterInit*/
@@ -115,7 +115,7 @@
                            END
            , LFM.UPDATE_DATE = NOW()
    </update>
-    <update id="updateTusUploadIdIfNull" parameterType="com.alist.api.common.modules.file.dto.FileUploadMetaDto">
+    <update id="updateTusUploadIdIfNull" parameterType="com.alist.api.modules.file.dto.FileUploadMetaDto">
        /*FileMapper.updateTusUploadIdIfNull*/
        UPDATE ALISTLMS.FILE_DETAIL
        SET TUS_UPLOAD_ID = #{tusUploadId}
@@ -165,7 +165,7 @@
            )
    </select>

-    <select id="selectFileUploadMetaByFileUuid" resultType="com.alist.api.common.modules.file.dto.FileUploadMetaDto">
+    <select id="selectFileUploadMetaByFileUuid" resultType="com.alist.api.modules.file.dto.FileUploadMetaDto">
        /*FileMapper.selectFileUploadMetaByFileUuid*/
        SELECT FILE_UUID, ORIGIN_NAME, SIZE_BYTES, CONTENT_TYPE, TUS_UPLOAD_ID, STATUS
        FROM ALISTLMS.FILE_DETAIL
@@ -186,7 +186,7 @@
            AND LFD.STATUS IN (0,1,2)
    </select>

-    <select id="selectUploadProgressByFileUuid" resultType="com.alist.api.common.modules.file.dto.UploadCancelDto">
+    <select id="selectUploadProgressByFileUuid" resultType="com.alist.api.modules.file.dto.UploadCancelDto">
        /*FileMapper.selectUploadProgressByFileUuid*/
        SELECT LFD.FILE_UUID
            , COALESCE(LFD.UPLOADED_BYTES, 0) AS UPLOADED_BYTES
@@ -200,7 +200,7 @@
        LIMIT 1
    </select>

-    <select id="selectMoveTaskByFileUuid" resultType="com.alist.api.common.modules.file.dto.FileMoveTaskDto">
+    <select id="selectMoveTaskByFileUuid" resultType="com.alist.api.modules.file.dto.FileMoveTaskDto">
        /*FileMapper.selectMoveTaskByFileUuid*/
        SELECT LFD.FILE_DETAIL_IDX
            , LFD.FILE_MASTER_IDX
@@ -226,7 +226,7 @@
        LIMIT 1
    </select>

-    <select id="selectFileDownloadListByFileMasterIdx" resultType="com.alist.api.common.modules.file.dto.FileDownloadItemDto">
+    <select id="selectFileDownloadListByFileMasterIdx" resultType="com.alist.api.modules.file.dto.FileDownloadItemDto">
        /*FileMapper.selectFileDownloadListByFileMasterIdx*/
        SELECT LFD.FILE_DETAIL_IDX
            , LFD.FILE_MASTER_IDX
@@ -248,7 +248,7 @@
        ORDER BY LFD.FILE_SEQ ASC, LFD.FILE_DETAIL_IDX ASC
    </select>

-    <select id="selectFileDetailByFileUuid" resultType="com.alist.api.common.modules.file.dto.FileDownloadDto">
+    <select id="selectFileDetailByFileUuid" resultType="com.alist.api.modules.file.dto.FileDownloadDto">
        /*FileMapper.selectFileDetailByFileUuid*/
        SELECT LFD.FILE_DETAIL_IDX
            , LFD.FILE_MASTER_IDX
@@ -272,7 +272,7 @@
        LIMIT 1
    </select>

-    <update id="updateFileMoveSuccess" parameterType="com.alist.api.common.modules.file.dto.FileMoveTaskDto">
+    <update id="updateFileMoveSuccess" parameterType="com.alist.api.modules.file.dto.FileMoveTaskDto">
        /*FileMapper.updateFileMoveSuccess*/
        UPDATE ALISTLMS.FILE_DETAIL
        SET SAVE_NAME = #{saveName}
@@ -288,7 +288,7 @@
            AND DEL_YN = 'N'
    </update>

-    <update id="updateFileMovePendingByFileUuid" parameterType="com.alist.api.common.modules.file.dto.FileMoveTaskDto">
+    <update id="updateFileMovePendingByFileUuid" parameterType="com.alist.api.modules.file.dto.FileMoveTaskDto">
        /*FileMapper.updateFileMovePendingByFileUuid*/
        UPDATE ALISTLMS.FILE_DETAIL
        SET MOVE_YN = 'N'