api2/docs/codebase-notes.md

현재 코드베이스 메모

현재 특히 주의할 점

• README.md와 docs/*.md는 코드 변경 후 같이 갱신해야 한다. 의심되는 항목은 Controller, SecurityConfig, 설정 파일을 기준으로 다시 확인한다.
• 예시 스케줄러 코드에는 깨진 문자열과 과도한 반복 로그가 보일 수 있으니 관련 수정 시 인코딩과 로그 정책을 함께 점검한다.
• 테스트 코드가 충분하지 않을 수 있으므로 기능 변경 시 필요한 테스트를 보강한다.
• 일부 Java 소스와 주석, Swagger 설명에 인코딩이 깨진 문자열이 있으므로 표시 문자열 수정은 영향 범위를 보고 묶어서 처리한다.
• application-local.yaml 은 로컬 실행값이 직접 들어가 있으므로 공유하거나 커밋할 때 민감정보 노출 여부를 한 번 더 확인한다.
• 파일 업로드는 두 흐름으로 분리되어 있다. 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 인증 경로는 /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 는 토큰을 재발급하므로 새로고침 상태 확인용으로 쓰지 않는다.