api2/docs/verification-checklist.md

검증 및 체크리스트

기본 검증 원칙

• 현재 테스트 코드는 최소 수준이므로 기능 수정 시 단위 테스트 또는 최소 통합 검증 범위를 직접 보강하는 쪽을 우선한다.
• 기동 실패 가능성이 있는 설정 변경은 실행 또는 테스트로 검증한다.
• 검증하지 못한 내용은 추정으로 말하지 않고 미실행 사유를 적는다.

변경 시 체크리스트

• 변경한 코드와 직접 관련된 파일만 수정했는지 확인한다.
• 새 API, 스케줄러, 설정 추가 시 관련 설정 파일과 테스트를 함께 검토한다.
• 로그 레벨과 로그량이 운영 환경에서 감당 가능한지 확인한다.
• Mapper 인터페이스 추가/변경 시 XML namespace, id, parameter/result 매핑이 같이 맞는지 확인한다.
• 공개 경로나 권한 정책을 바꿨다면 SecurityConfig 와 Swagger 노출 범위를 같이 확인한다.
• 파일 업로드/다운로드 기능 수정 시 DB 상태, Redis 상태, 실제 파일 시스템 경로가 같이 맞는지 확인한다.
• 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 경로가 같은 저장 루트를 가리키는지 확인한다.

기능 특성별 점검 포인트

• 스케줄러 코드는 실행 주기, 중복 실행 가능성, 로그량을 반드시 점검한다.
• 인증 방식이 섞여 있으므로 세션 기반 처리와 JWT SecurityContext 사용 위치를 먼저 구분하고 수정한다.
• 파일 경로를 다루는 기능은 상대경로 탈출, 루트 이탈 방지 같은 검증을 같이 본다.
• 설정 파일 수정 시 local, pjt, 공통 설정 간 차이를 함께 확인한다.
• file-domain 정적 파일은 /uploads/editor/... 같은 최종 파일 URL이 브라우저에서 직접 열리는지 확인한다.
• /uploads/tmp/... 는 404로 막히는지 확인한다.
• SunEditor 업로드는 응답 JSON의 result[].url 이 file-domain 절대 URL인지 확인하고, 에디터 본문에 이미지가 실제 삽입되는지 확인한다.