diff --git a/README.md b/README.md index 8760c6a..f592f36 100644 --- a/README.md +++ b/README.md @@ -52,13 +52,13 @@ src/main/java/com/alist/api │ ├── migration # 마이그레이션 DB 설정 │ └── properties # 설정 프로퍼티 └── modules - ├── admin # 관리자 인증 API - ├── auth # 사용자 인증/SSO API + ├── admin # 관리자 인증/회원/스케줄/SSO 클라이언트 관리 API + ├── cors # DB 기반 허용 Origin 관리와 캐시 갱신 API ├── file # 단순 업로드, SunEditor 업로드, path 기반 view/download + ├── front # 사용자 인증/SSO API와 사용자 관리 API ├── main # 루트 응답 ├── migration # 레거시 사용자 조회 ├── tusFile # TUS 업로드 DB 기록, hook, 상태, 파일 목록/view/download/delete - └── user # 사용자 가입/마이그레이션 조회 ``` 리소스 파일은 아래 위치를 사용합니다. @@ -153,7 +153,7 @@ Windows: ### Admin API - `/admin/**` 는 별도 SecurityFilterChain을 사용합니다. -- `/admin/auth/**` 는 공개하고, 그 외 `/admin/**` 는 `ADMIN` 권한을 요구합니다. +- `/admin/auth/**`, `/admin/user/add` 는 공개하고, 그 외 `/admin/**` 는 `ADMIN` 권한을 요구합니다. - `GET /admin/auth/loginChecked` 는 토큰 재발급 없이 현재 관리자 로그인 상태만 확인합니다. ### API @@ -168,16 +168,17 @@ Windows: - `/actuator/health` - `/sso/**` - `/auth/**` -- `/user/signup` -- `/user/migrationUserList` -- `/tusFiles/uploadAuth` -- `/tusFiles/tusHook` +- `/user/add` +- `/user/migration/list` +- `/tus/file/upload/auth` +- `/tus/file/hook` +- `/file/**` -TUS 업로드 토큰은 일반 access token이 아니므로 `/tusFiles/uploadAuth`, `/tusFiles/tusHook` 은 JWT 필터 제외 경로에도 포함되어야 합니다. +TUS 업로드 토큰은 일반 access token이 아니므로 `/tus/file/upload/auth`, `/tus/file/hook` 은 file-domain nginx `auth_request` 설정과 Spring Security 공개 경로를 함께 맞춰야 합니다. ## CORS -`DynamicCorsFilter`가 최우선 필터로 동작하며, 허용 Origin 목록은 `CorsAllowedOriginsCache`에서 조회합니다. +`DynamicCorsFilter`가 최우선 필터로 동작하며, 허용 Origin 목록은 `CorsCache`에서 조회합니다. - 허용된 Origin에만 `Access-Control-Allow-Origin` 설정 - Credential 허용 @@ -194,12 +195,9 @@ file-domain nginx 의 TUS 업로드 경로는 별도 `map $http_origin $cors_all DB에 기록하지 않고 파일만 저장한 뒤 업무 테이블에 저장하기 좋은 값을 반환합니다. -- `POST /files/upload` -- `POST /admin/files/upload` -- `GET /files/view?path=/uploads/...` -- `GET /admin/files/view?path=/uploads/...` -- `GET /files/download?path=/uploads/...` -- `GET /admin/files/download?path=/uploads/...` +- `POST /file/upload` +- `GET /file/view?path=/uploads/...` +- `GET /file/download?path=/uploads/...` 응답 데이터 예시: @@ -220,8 +218,7 @@ DB에 기록하지 않고 파일만 저장한 뒤 업무 테이블에 저장하 SunEditor 업로드는 API로 저장하되, 에디터 본문에는 token이 필요 없는 file-domain URL을 저장합니다. -- `POST /files/suneditor/upload` -- `POST /admin/files/suneditor/upload` +- `POST /file/suneditor/upload` 응답 예시: @@ -241,20 +238,20 @@ SunEditor 업로드는 API로 저장하되, 에디터 본문에는 token이 필 대용량 업로드는 tusd와 연동하며 API는 DB 기록, 토큰 발급, 권한 검증, hook 반영을 담당합니다. -- `POST /tusFiles/uploadInit` -- `GET /tusFiles/uploadAuth` -- `POST /tusFiles/uploadStatus` -- `POST /tusFiles/tusHook` -- `POST /tusFiles/uploadCancel` -- `GET /tusFiles/list/{fileMasterIdx}` -- `GET /tusFiles/view/{fileUuid}` -- `GET /tusFiles/download/{fileUuid}` -- `POST /tusFiles/delete` +- `POST /tus/file/upload/init` +- `GET /tus/file/upload/auth` +- `POST /tus/file/upload/status` +- `POST /tus/file/hook` +- `POST /tus/file/upload/cancel` +- `GET /tus/file/list/{fileMasterIdx}` +- `GET /tus/file/view/{fileUuid}` +- `GET /tus/file/download/{fileUuid}` +- `POST /tus/file/delete` 운영 TUS 엔드포인트: ```text -https://file-alist.pjt.kr/tus/files/ +https://file-alist.pjt.kr/tus/file/ ``` ## file-domain 운영 메모 @@ -264,7 +261,7 @@ https://file-alist.pjt.kr/tus/files/ - 파일 도메인: `https://file-alist.pjt.kr` - nginx `/uploads/` 는 `/srv/project/alist/uploads/` 를 정적 파일로 제공합니다. - nginx `/uploads/tmp/` 는 임시 파일 노출 방지를 위해 404 처리합니다. -- nginx `/tus/files/` 는 tusd로 프록시하고 `auth_request /_upload_auth` 로 `/tusFiles/uploadAuth` 를 호출합니다. +- nginx `/tus/file/` 는 tusd로 프록시하고 `auth_request /_upload_auth` 로 `/tus/file/upload/auth` 를 호출합니다. ## 주요 인증 엔드포인트 @@ -280,7 +277,8 @@ https://file-alist.pjt.kr/tus/files/ - `POST /admin/auth/refresh` - `GET /admin/auth/loginChecked` - `POST /admin/auth/logout` -- `POST /user/signup` +- `POST /user/add` +- `POST /user/migration/list` ## Actuator diff --git a/docs/codebase-notes.md b/docs/codebase-notes.md index 7682d82..32e35ed 100644 --- a/docs/codebase-notes.md +++ b/docs/codebase-notes.md @@ -1,7 +1,7 @@ # 현재 코드베이스 메모 ## 현재 특히 주의할 점 -- `README.md`는 아직 템플릿 상태이므로 실제 동작 방식은 코드와 설정 파일을 기준으로 판단한다. +- `README.md`와 `docs/*.md`는 코드 변경 후 같이 갱신해야 한다. 의심되는 항목은 Controller, `SecurityConfig`, 설정 파일을 기준으로 다시 확인한다. - 예시 스케줄러 코드에는 깨진 문자열과 과도한 반복 로그가 보일 수 있으니 관련 수정 시 인코딩과 로그 정책을 함께 점검한다. - 테스트 코드가 충분하지 않을 수 있으므로 기능 변경 시 필요한 테스트를 보강한다. - 일부 Java 소스와 주석, Swagger 설명에 인코딩이 깨진 문자열이 있으므로 표시 문자열 수정은 영향 범위를 보고 묶어서 처리한다. @@ -9,6 +9,7 @@ - 파일 업로드는 두 흐름으로 분리되어 있다. `file` 모듈의 단순 업로드는 DB에 기록하지 않고 `uploadPath`, 파일명, 확장자, contentType, size, image width/height 정도만 반환한다. 각 업무 테이블 저장은 호출 측에서 처리한다. - SunEditor 이미지 업로드는 API로 파일을 저장하되 응답 URL은 `file.upload.view.file-domain + uploadPath` 로 만든다. 에디터 본문에 저장되는 URL은 admin/user 토큰에 의존하지 않는 file-domain URL이어야 한다. - TUS 업로드는 `tusFile` 모듈에서 DB master/detail 기록, upload token 발급, tusd hook 반영, 상태 조회, view/download/delete를 담당한다. -- TUS 인증 경로는 `/tusFiles/uploadAuth`, hook 경로는 `/tusFiles/tusHook` 이다. nginx `/_upload_auth` 와 Spring Security 공개 경로, JWT filter 제외 경로를 함께 맞춘다. +- TUS 인증 경로는 `/tus/file/upload/auth`, hook 경로는 `/tus/file/hook` 이다. nginx `/_upload_auth`, Spring Security 공개 경로, `tus-file.upload.tus-endpoint` 를 함께 맞춘다. +- 단순 파일 API는 `/file/upload`, `/file/suneditor/upload`, `/file/view`, `/file/download` 를 사용한다. `/admin/files/...` 또는 `/files/...` 예전 표기가 남아 있으면 최신 경로로 정리한다. - file-domain nginx 는 `/uploads/` 를 공개 정적 파일로 열고 `/uploads/tmp/` 는 404로 막는다. TUS 임시 디렉터리는 파일 시스템에서는 사용하지만 URL로 직접 노출하지 않는다. - Admin 로그인 상태 확인은 `/admin/auth/loginChecked` 를 사용한다. `/admin/auth/refresh` 는 토큰을 재발급하므로 새로고침 상태 확인용으로 쓰지 않는다. diff --git a/docs/project-overview.md b/docs/project-overview.md index cbe3a64..c7b68ad 100644 --- a/docs/project-overview.md +++ b/docs/project-overview.md @@ -30,6 +30,9 @@ - MyBatis는 인터페이스와 XML을 함께 사용한다. - Mapper 인터페이스는 `src/main/java/.../mapper`, SQL XML은 `src/main/resources/mapper/...` 경로를 짝으로 맞춘다. - 공통 응답은 `common/response`, 보안은 `config/security, jwt`, 전역 예외 처리는 `config/exception` 아래에 둔다. -- 모듈 패키지는 현재 `admin`, `auth`, `file`, `main`, `tusFile`, `user` 형태로 구성되어 있고, 필요한 모듈만 `dto`, `form`, `mapper`, `service`, `vo`를 둔다. +- 모듈 패키지는 현재 `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 흐름을 담당한다. diff --git a/docs/runtime-config.md b/docs/runtime-config.md index 29712db..4d2dcfe 100644 --- a/docs/runtime-config.md +++ b/docs/runtime-config.md @@ -30,7 +30,7 @@ - `spring.servlet.multipart.max-file-size` 와 `max-request-size` 는 `-1` 로 두고, 실제 제한은 업로드 서비스 정책에서 처리한다. ## file-domain nginx 기준 -- `/tus/files/` 는 tusd 로 프록시하며 `auth_request /_upload_auth` 로 `/tusFiles/uploadAuth` 를 호출한다. +- `/tus/file/` 는 tusd 로 프록시하며 `auth_request /_upload_auth` 로 API의 `/tus/file/upload/auth` 를 호출한다. - `/_upload_auth` 는 내부 location 으로만 열고 `Authorization`, `X-File-Uuid`, 필요 시 `Upload-Metadata`, `Upload-Length` 헤더를 API 로 전달한다. - `/uploads/` 는 `/srv/project/alist/uploads/` 를 정적 파일로 제공한다. - `/uploads/tmp/` 는 tusd 임시 파일 노출을 막기 위해 404 처리한다. diff --git a/docs/security-and-response.md b/docs/security-and-response.md index 5e96fc6..cd1e95f 100644 --- a/docs/security-and-response.md +++ b/docs/security-and-response.md @@ -10,9 +10,10 @@ - Swagger: `/v3/api-docs/**`, `/swagger-ui/**` → HTTP Basic 인증 (InMemory) - API: JWT Bearer 토큰 인증 (Stateless) - 세션/쿠키: Redis Session 저장소 사용, 쿠키 속성은 프로파일별 `cookie.*` 설정으로 제어 -- Admin API: `/admin/**` 는 별도 `SecurityFilterChain` 으로 분리하며 `/admin/auth/**` 만 공개하고 나머지는 `ADMIN` 권한을 요구한다. -- 공개 경로: `/`, `/actuator/health`, `/sso/**`, `/auth/**`, `/user/signup`, `/user/migrationUserList`, `/tusFiles/tusHook`, `/tusFiles/uploadAuth` -- TUS 업로드 토큰은 일반 access token 이 아니므로 `/tusFiles/uploadAuth`, `/tusFiles/tusHook` 은 `JwtAuthenticationFilter.shouldNotFilter(...)` 에서도 제외한다. +- Admin API: `/admin/**` 는 별도 `SecurityFilterChain` 으로 분리하며 `/admin/auth/**`, `/admin/user/add` 만 공개하고 나머지는 `ADMIN` 권한을 요구한다. +- 공개 경로: `/`, `/actuator/health`, `/sso/**`, `/auth/**`, `/user/add`, `/user/migration/list`, `/tus/file/hook`, `/tus/file/upload/auth`, `/file/**` +- TUS 업로드 토큰은 일반 access token 이 아니므로 `/tus/file/upload/auth`, `/tus/file/hook` 은 공개 경로와 file-domain nginx `auth_request` 설정을 함께 맞춘다. +- `JwtAuthenticationFilter` 는 shared API(`/tus/file/**`, `/file/**`, `/cors/**`)에서 user access token 또는 admin access token 모두 인증 주체로 받을 수 있다. - `/admin/auth/loginChecked` 는 admin access token 쿠키의 현재 로그인 상태 확인용이다. 토큰을 재발급하지 않으며 `isAdminAccessToken`, `isAdminRefreshToken`, `loggedIn`, `userId`, `userIdx`, `userTokenIdx`, `userRole` 형태의 값을 반환한다. - Swagger 인증과 API 인증은 `SecurityFilterChain` 을 분리해서 관리한다. diff --git a/docs/verification-checklist.md b/docs/verification-checklist.md index a6d560c..7580507 100644 --- a/docs/verification-checklist.md +++ b/docs/verification-checklist.md @@ -12,7 +12,8 @@ - Mapper 인터페이스 추가/변경 시 XML namespace, id, parameter/result 매핑이 같이 맞는지 확인한다. - 공개 경로나 권한 정책을 바꿨다면 SecurityConfig 와 Swagger 노출 범위를 같이 확인한다. - 파일 업로드/다운로드 기능 수정 시 DB 상태, Redis 상태, 실제 파일 시스템 경로가 같이 맞는지 확인한다. -- TUS 경로를 바꾸면 nginx `/_upload_auth`, tusd hook URL, `SecurityConfig` 공개 경로, `JwtAuthenticationFilter.shouldNotFilter(...)` 를 함께 확인한다. +- TUS 경로를 바꾸면 nginx `/_upload_auth`, tusd hook URL, `SecurityConfig` 공개 경로, `tus-file.upload.tus-endpoint` 를 함께 확인한다. +- `/file/**`, `/tus/file/**`, `/cors/**` 같은 shared API 권한을 바꾸면 user/admin 토큰 쿠키와 Bearer 인증이 모두 의도대로 동작하는지 확인한다. - SunEditor 또는 단순 업로드 설정을 바꾸면 `file.upload.root-path`, `file.upload.view.file-domain`, nginx `/uploads/` alias 경로가 같은 저장 루트를 가리키는지 확인한다. ## 기능 특성별 점검 포인트