4.0 KiB
4.0 KiB
인증 / 로그인 추적 / 에러 저장 인수인계서
작성일: 2026-05-06 대상: 후임 AI 엔지니어 또는 개발 관리자 작업 브랜치:
dev_ysCha
이 문서의 범위: 로그인·로그아웃 추적, 클라이언트 에러 저장 API 트랙만 다룹니다. 다른 트랙은
HANDOVER_INDEX.md참조.
0. 한 줄 요약
운영 중 자동 로그인/로그아웃이 의도대로 안 되는 케이스와 클라이언트에서 발생한 예외를 잡지 못하는 문제를 추적하기 위해, 추적 로그와 에러 저장 API를 단계적으로 보강한 트랙입니다.
1. 로그인 / 로그아웃 추적
1.1 한 일
| 단계 | 내용 | 커밋 |
|---|---|---|
| 1차 | 로그인·로그아웃 추적 | 60b84191 |
| 2차 | 자동 로그인 추적 | 1bf777f8 |
1.2 추적 로그의 목적
- 어디서 토큰이 사라지는지
- 어디서 자동 로그인 트리거가 안 잡히는지
- 어디서 로그아웃이 누락되는지
프론트(qcast-front) 에도 같은 목적의 추적 트랙이 있습니다 (
API_STABILITY_HANDOVER.md5절). 프론트와 백엔드 양쪽 로그를 같은 시점 기준으로 매칭해서 봐야 원인이 보입니다.
1.3 주의
- 추적 로그는 디버깅 목적으로 추가된 것이라, 운영에서 떼어낼지 유지할지 사용자에게 확인이 필요합니다.
- 토큰/세션 정보를 로그에 그대로 남기면 보안 이슈가 생기므로, 로그 내용에 민감 정보가 안 들어가는지 다시 확인하세요.
2. 에러 저장 API — errSave / quotationErrSave
2.1 한 일
| 단계 | 내용 | 커밋 |
|---|---|---|
| 1차 | errSave API 추가 |
63969fa2 |
| 2차 | errSave API 추가 (보강) |
23f70b21 |
| 3차 | errSave API 추가 2 |
d22a7508 |
| 별건 | quotationErrSave API 추가 (견적서 전용) |
0b9eeb99 |
2.2 무엇을 하나
- 클라이언트(프론트)에서 발생한 예외 / 에러를 백엔드로 전송해 저장.
- 운영 중 사용자가 알아채지 못하는 에러 추적용.
2.3 사용처 (프론트 측)
- 글로벌 에러 핸들러
- 주요 fetch 실패 catch 블록
- 견적서 출력 실패는
quotationErrSave로 분리
2.4 주의
- 에러 저장 자체가 또 실패하면 무한 루프 가 될 수 있습니다. 저장 실패 시에는 추가 호출을 하지 않도록 막아야 합니다.
- 로그에 사용자 입력값을 통째로 담으면 PII 가 들어갈 수 있어 위험. 필요한 식별자만 남기세요.
3. 안정성 보강
3.1 itemList null 체크
- 커밋:
b84e1fd0 - 견적서 항목 리스트가 null 인 경우 NPE 가 나던 문제. 호출부에서 null 체크 추가.
3.2 HttpMediaTypeNotAcceptableException 에러
- 커밋:
50d8a9e3 - 특정 요청에서 Accept 헤더 불일치로 예외 발생 → 컨버터/Producer 설정 보강.
4. 핵심 파일
| 파일/위치 | 역할 |
|---|---|
com.interplug.qcast.biz.auth.* |
로그인/세션 관련 |
com.interplug.qcast.biz.{도메인}.*ErrSaveController 또는 Service |
errSave 엔드포인트 |
com.interplug.qcast.biz.quotation.*ErrSave* |
quotationErrSave 엔드포인트 |
| 글로벌 ExceptionHandler | 알 수 없는 예외 처리 |
정확한 클래스명은 변경되었을 수 있으니 IDE 검색으로
errSave키워드 찾는 게 빠릅니다.
5. 인수 직후 권장 절차
- 이 문서 통독.
errSave키워드로 코드 베이스 검색해서 엔드포인트 위치 확인.- 로그인 컨트롤러에서 토큰 발급/검증 흐름 한 번 따라가 보기.
- 운영 로그에서
자동 로그인/로그아웃키워드로 grep 해 어떤 패턴이 잡히는지 확인.
6. 미해결 / 추적 중
- 자동 로그인 실패 케이스 완전 재현 안 됨. 추적 로그를 보면 단서가 보이는데, 환경별로 다르게 나타남.
- 인증 추적 로그를 운영에서 유지/제거할지 사용자 결정 필요.
끝.