# 인증 / 로그인 추적 / 에러 저장 인수인계서

> 작성일: 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.md` 5절). 프론트와 백엔드 양쪽 로그를 **같은 시점 기준으로 매칭**해서 봐야 원인이 보입니다.

### 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. 인수 직후 권장 절차

1. 이 문서 통독.
2. `errSave` 키워드로 코드 베이스 검색해서 엔드포인트 위치 확인.
3. 로그인 컨트롤러에서 토큰 발급/검증 흐름 한 번 따라가 보기.
4. 운영 로그에서 `자동 로그인` / `로그아웃` 키워드로 grep 해 어떤 패턴이 잡히는지 확인.

---

## 6. 미해결 / 추적 중

- **자동 로그인 실패 케이스 완전 재현 안 됨**. 추적 로그를 보면 단서가 보이는데, 환경별로 다르게 나타남.
- 인증 추적 로그를 **운영에서 유지/제거**할지 사용자 결정 필요.

끝.