레포 업데이트

docs/backend-log-policy.md

@@ -0,0 +1,74 @@
+# Backend Log Policy
+
+## 1. 목적
+- Backend 서버 로그의 기본 레벨과 운영 중 일시적 디버그 확장 규칙을 정의합니다.
+- 운영 환경에서 과도한 로그 노출을 피하면서, 장애 분석이 필요한 경우에는 명시적으로 진단 로그를 확장할 수 있게 합니다.
+
+## 2. 기준 변수
+- `APP_ENV`
+- `BACKEND_LOG_LEVEL` (선택 override)
+
+## 3. 기본 동작
+
+### 3.1 기본 레벨 결정
+- `APP_ENV=dev|local|development`
+  - 기본 로그 레벨: `debug`
+  - 기본 출력 형식: text
+- 그 외 환경(`stage`, `production`, `prod` 등)
+  - 기본 로그 레벨: `info`
+  - 기본 출력 형식: JSON
+
+### 3.2 명시 override
+- `BACKEND_LOG_LEVEL`이 설정되면 `APP_ENV` 기본값보다 우선합니다.
+- 허용 값:
+  - `debug`
+  - `info`
+  - `warn`
+  - `error`
+
+예시:
+```env
+APP_ENV=stage
+BACKEND_LOG_LEVEL=debug
+```
+
+위 설정이면 stage 환경이더라도 backend `slog`는 `debug`로 동작합니다.
+
+## 4. 운영 가이드
+- 운영/스테이징에서 장애 분석이 필요할 때만 `BACKEND_LOG_LEVEL=debug`를 일시적으로 설정합니다.
+- 이슈 분석이 끝나면 즉시 기본값으로 되돌리는 것을 권장합니다.
+- 기본 레벨(`info`)에서는 핵심 상태 변화와 경고/오류를 중심으로 남기고, 디버그 전용 진단 필드는 숨깁니다.
+
+## 5. Headless Login 진단 로그
+- `POST /api/v1/auth/headless/password/login` 같은 headless 로그인 경로는 기본적으로 `reason_code` 중심의 구조화 로그를 남깁니다.
+- `BACKEND_LOG_LEVEL=debug` 또는 `APP_ENV=dev|local|development`일 때만 아래 진단 필드를 추가로 남깁니다.
+  - `expected_audiences`
+  - `received_audiences`
+  - `received_kid`
+  - `claim_issuer`
+  - `claim_subject`
+  - `claim_expires_at`
+  - `claim_not_before`
+  - `claim_issued_at`
+- 민감 정보는 계속 로그에 남기지 않습니다.
+  - raw `client_assertion`
+  - password
+  - session token / cookie
+
+## 6. 구현 위치
+- logger 초기화: `backend/cmd/server/main.go`
+- 레벨 결정 로직: `backend/internal/logger/logger.go`
+- headless 로그인 debug 진단 필드: `backend/internal/handler/auth_handler.go`
+
+## 7. 검증
+```bash
+cd backend
+go test ./internal/logger -v
+go test ./cmd/server -run 'TestNewErrorHandler_' -v
+go test ./internal/handler -run 'TestHeadlessPasswordLogin_(DebugLogIncludesDiagnostics|InfoLogOmitsDebugDiagnostics)$' -v
+```
+
+## 8. 관련 문서
+- `README.md`
+- `docs/client-log-policy.md`
+- wiki update draft: `docs/wiki-error-handling-policy-backend-log-update.md`