Merge branch 'main' into feature/0612_sentry_fr_merge

# Conflicts: # apps/as/src/pages/instl-sncn/ui/cnfm-view-page.tsx # pnpm-lock.yaml
2026-07-08 16:47:33 +09:00
parent b65c50c5f9 8abf32bb53
commit 299ce3f1fe
736 changed files with 63742 additions and 12242 deletions
@@ -29,10 +29,8 @@
 예시 코드:

 ```ts
-export const CLAIM_NAME =
-  process.env.NEXT_PUBLIC_CLAIM_NAME || "Authorization";
-export const AUTH_USER_ID =
-  process.env.NEXT_PUBLIC_AUTH_USER_ID || "token-id";
+export const CLAIM_NAME = process.env.NEXT_PUBLIC_CLAIM_NAME || "Authorization";
+export const AUTH_USER_ID = process.env.NEXT_PUBLIC_AUTH_USER_ID || "token-id";
 export const ACCESS_TOKEN =
  process.env.NEXT_PUBLIC_ACCESS_TOKEN || "access-token";
 export const REFRESH_TOKEN =
@@ -82,6 +80,7 @@ export const {
  setToken,
  removeToken,
  setupRefreshTimer,
+  clearRefreshTimer,
  clearAuthToken,
  getAccessToken,
  getRefreshToken,
@@ -175,3 +174,14 @@ export { tokenManager } from "./lib/token-manager";
 - 로그인/갱신 로직이 `getRemainingMs` 기반 타이머를 사용한다.
 - BaseLayout 컴포넌트에 `tokenManager`가 주입되어 있다.
 - 외부 참조 경로가 `entities/auth` 배럴 경로로 통일되어 있다.
+
+## 5) 세션 연장 Confirm 적용 (후속 단계)
+
+리팩토링이 완료된 서비스(`authService` + `AuthWrapper` + `ConfirmProvider`)는 [세션 연장 Confirm 적용 가이드](./session-extend-confirm-guide.md)를 따라 JWT 만료 5분 전 confirm UX를 추가한다.
+
+추가 체크 항목:
+
+- `token-manager`에서 `clearRefreshTimer`를 re-export한다.
+- `AuthWrapper`에 `useSessionExtendConfirm`을 연결한다.
+- `clearRefreshTimer`는 앱 `token-manager` 싱글톤을 통해 전달한다 (`authService`의 `setupRefreshTimer`와 동일 인스턴스).
+- `ConfirmProvider` 하위에 `AuthWrapper`와 `ConfirmDialog`가 마운트되어 있다.
@@ -0,0 +1,245 @@
+# 세션 연장 Confirm 적용 가이드
+
+## 1) 문서 목적
+
+JWT 만료 **5분 전**에 `"로그인을 연장하시겠습니까?"` confirm 창을 띄우고, 사용자 선택에 따라 세션을 연장하거나 자동 갱신을 중단하는 기능을 서비스 앱에 적용하기 위한 가이드입니다.
+
+이 문서는 [서비스별 인증 처리 리팩토링 가이드](./auth-service-refactoring-guide.md)의 **후속 단계**로 읽습니다.  
+`@common/auth` 기반 `authService` + `token-manager` + `AuthWrapper` 패턴이 먼저 갖춰져 있어야 합니다.
+
+## 2) 선행 조건
+
+아래 항목이 완료된 서비스만 이 가이드를 적용합니다.
+
+| 항목                                                                             | 확인                                                                |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `createTokenManager(authConfig)` 사용                                            | [3-3. 토큰 매니저 공통화](./auth-service-refactoring-guide.md)      |
+| `authService.login` / `silentRefresh`에서 `getRemainingMs` + `setupRefreshTimer` | [3-4. 로그인 성공 처리 표준화](./auth-service-refactoring-guide.md) |
+| `authService.declineSessionExtend` 구현                                          | confirm 취소 시 refresh 타이머 해제                                 |
+| `AuthWrapper`에서 새로고침 시 refresh 타이머 복구                                | cs / as / st 참고                                                   |
+| `ConfirmProvider` + `ConfirmDialog` 마운트                                       | AppProvider                                                         |
+| `ConfirmProvider` **하위**에 `BaseLayout` → `Header` 렌더링                      | `useConfirm` 사용 조건                                              |
+| `BaseLayout`에 `authService` prop 전달                                           | Header까지 전달됨                                                   |
+
+**적용 완료 앱**: `cs`, `as`, `st`  
+**미적용**: `wr`, `sn`, `fo` 등 legacy `LoginApi` 패턴 앱
+
+## 3) 전체 흐름
+
+로그인 이후 JWT `exp`를 기준으로 **두 개의 독립 타이머**가 동작합니다.
+
+```mermaid
+sequenceDiagram
+  participant Login as authService.login
+  participant RefreshTimer as refreshTimer
+  participant Header as Header
+  participant User as 사용자
+  participant API as authService.silentRefresh
+
+  Login->>RefreshTimer: setupRefreshTimer(exp - 1분)
+  Header->>Header: confirm 예약(exp - 5분)
+  Note over Header: 만료 5분 전
+  Header->>User: 로그인을 연장하시겠습니까?
+  alt 확인
+    User->>API: silentRefresh()
+    API->>RefreshTimer: 새 토큰 기준 타이머 재설정
+    Header->>Header: confirm 타이머 재설정
+  else 취소
+    Header->>API: declineSessionExtend()
+    API->>RefreshTimer: clearRefreshTimer()
+    Note over RefreshTimer: 만료까지 자동 갱신 없음
+  end
+```
+
+| 시점                        | 동작                                  | 담당                                        |
+| --------------------------- | ------------------------------------- | ------------------------------------------- |
+| 로그인 / silentRefresh 성공 | 만료 1분 전 자동 `silentRefresh` 예약 | `authService` → `setupRefreshTimer`         |
+| 만료 5분 전                 | confirm 표시                          | `Header` → `useSessionExtendConfirm`        |
+| confirm **확인**            | 즉시 `silentRefresh` + 타이머 재설정  | Header → `authService.silentRefresh`        |
+| confirm **취소**            | 자동 `silentRefresh` 타이머 해제      | Header → `authService.declineSessionExtend` |
+
+### 3-1. 시간 계산 (`getRemainingMs`)
+
+`[packages/common/auth/jwt-utils.ts](../packages/common/auth/jwt-utils.ts)`
+
+```typescript
+export const REFRESH_BUFFER_MS = 60_000; // silent refresh: 만료 1분 전
+export const SESSION_EXTEND_CONFIRM_BUFFER_MS = 5 * 60_000; // confirm: 만료 5분 전
+
+getRemainingMs(token); // → refresh 타이머 delay
+getRemainingMs(token, SESSION_EXTEND_CONFIRM_BUFFER_MS); // → confirm 타이머 delay
+getRemainingMs(token, 0) > 0; // → 토큰 미만료 여부
+```
+
+`bufferMs` 인자 하나로 용도를 구분합니다. 기존 `getRemainingMs(token)` 호출부는 변경하지 않아도 됩니다.
+
+## 4) 공통 모듈 변경 사항
+
+### 4-1. `@common/auth` — `AuthService` / `clearRefreshTimer`
+
+`[packages/common/auth/types.ts](../packages/common/auth/types.ts)`
+
+```typescript
+export interface AuthService {
+  login(payload: AuthPayload): Promise<void>;
+  silentRefresh(): Promise<void>;
+  declineSessionExtend(): void; // confirm 취소 시 refresh 타이머 해제
+  logout(): Promise<void>;
+}
+```
+
+`[packages/common/auth/token-manager.ts](../packages/common/auth/token-manager.ts)`
+
+- `setupRefreshTimer`: 만료 1분 전 `silentRefresh` 예약 (기존)
+- `clearRefreshTimer`: 예약된 refresh 타이머 해제 (신규)
+- `clearAuthToken`: 내부에서 `clearRefreshTimer` 호출
+
+`refreshTimer`는 `createTokenManager()` 클로저 안의 **앱당 싱글톤** 변수입니다.  
+`authService.declineSessionExtend()`가 내부에서 `clearRefreshTimer()`를 호출하므로, Header는 token-manager를 직접 import하지 않습니다.
+
+### 4-2. `@common/components` — Header + `useSessionExtendConfirm`
+
+`[packages/common/components/src/ui/header/index.tsx](../packages/common/components/src/ui/header/index.tsx)`에서 훅을 실행합니다.
+
+```typescript
+useSessionExtendConfirm({
+  enabled:
+    mounted &&
+    isLoggedIn &&
+    !viewOnly &&
+    !!authService &&
+    !isAtLoginRedirectUrl(getAuthLoginRedirectUrl()),
+  getAccessToken: () => getCookie(appConfig.CLAIM_NAME ?? ""),
+  silentRefresh: authService.silentRefresh,
+  clearRefreshTimer: authService.declineSessionExtend,
+});
+```
+
+| enabled 조건                 | 이유                            |
+| ---------------------------- | ------------------------------- |
+| `mounted`                    | hydration 후 타이머 시작        |
+| `isLoggedIn`                 | 비로그인 제외                   |
+| `!viewOnly`                  | `VBaseLayout` 등 조회 전용 제외 |
+| `!!authService`              | legacy 앱 자동 비활성           |
+| `!isAtLoginRedirectUrl(...)` | 로그인 페이지 제외              |
+
+세션 만료 **카운트다운 UI**와 confirm 로직이 Header에 응집됩니다.
+
+## 5) 서비스별 적용 단계
+
+### 5-1. `auth-service`에 `declineSessionExtend` 추가
+
+`[apps/cs/src/entities/auth/api/auth-service.ts](../apps/cs/src/entities/auth/api/auth-service.ts)` 참고:
+
+```typescript
+import { clearRefreshTimer } from "../lib/token-manager";
+
+function declineSessionExtend(): void {
+  clearRefreshTimer();
+}
+
+export const authService: AuthService = {
+  login,
+  silentRefresh,
+  declineSessionExtend,
+  logout,
+};
+```
+
+### 5-2. `BaseLayout`에 `authService` 전달
+
+`[apps/cs/app/(main)/(with-base-layout)/layout.tsx](../apps/cs/app/(main)`/(with-base-layout)/layout.tsx) 참고:
+
+```tsx
+<BaseLayout
+  queryClient={queryClient}
+  authService={authService}
+  currentPath={pathname ?? ""}
+  handleMenuClick={handleMenuClick}
+>
+```
+
+`BaseLayout`은 `authService`를 `Header`에 그대로 전달합니다. **AuthWrapper에서 훅을 연결하지 않습니다.**
+
+### 5-3. `AuthWrapper` — refresh 타이머 복구만 유지
+
+`[apps/cs/src/entities/auth/lib/auth-wrapper.tsx](../apps/cs/src/entities/auth/lib/auth-wrapper.tsx)`:
+
+- `useSessionExtendConfirm` **사용하지 않음**
+- 페이지 새로고침 시 `setupRefreshTimer(authService.silentRefresh, remainingMs)` 복구 유지
+- 인증 체크, `auth:logout` 수신 유지
+
+### 5-4. `AppProvider` 구조 확인
+
+`[apps/cs/src/app/providers/app-provider.tsx](../apps/cs/src/app/providers/app-provider.tsx)` 참고:
+
+```tsx
+<ConfirmProvider>
+  <AuthWrapper>
+    {children}
+    <ConfirmDialog />
+  </AuthWrapper>
+</ConfirmProvider>
+```
+
+`Header`는 `ConfirmProvider` 하위에서 렌더링되므로 `useConfirm()`이 동작합니다.
+
+## 6) 책임 분리 요약
+
+| 레이어             | 파일                                 | 역할                                               |
+| ------------------ | ------------------------------------ | -------------------------------------------------- |
+| JWT 시간 계산      | `@common/auth` `jwt-utils.ts`        | `getRemainingMs`, 버퍼 상수                        |
+| refresh 타이머     | `@common/auth` `token-manager.ts`    | `setupRefreshTimer`, `clearRefreshTimer`           |
+| API 오케스트레이션 | `entities/auth/api/auth-service.ts`  | login, silentRefresh, declineSessionExtend, logout |
+| confirm UX         | `@common/components` `Header`        | 카운트다운 UI + 5분 전 confirm                     |
+| 앱 진입점          | `entities/auth/lib/auth-wrapper.tsx` | 타이머 복구, auth 체크                             |
+| 레이아웃           | `app/.../layout.tsx`                 | `authService` → `BaseLayout` → `Header`            |
+| UI 쉘              | `app/providers/app-provider.tsx`     | ConfirmProvider, ConfirmDialog                     |
+
+## 7) 엣지 케이스
+
+| 상황                 | 동작                                                            |
+| -------------------- | --------------------------------------------------------------- |
+| 토큰 유효 시간 < 5분 | `confirmMs === 0`이면 페이지 진입 즉시 confirm                  |
+| confirm **취소**     | `declineSessionExtend()` + 동일 JWT에 재표시 안 함              |
+| confirm **확인**     | `silentRefresh()` → 새 토큰 기준 confirm/refresh 타이머 재설정  |
+| `silentRefresh` 실패 | `authService`가 `auth:logout` 발행 → AuthWrapper 리다이렉트     |
+| 로그아웃             | `clearAuthToken`이 refresh 타이머 정리, 훅 cleanup              |
+| `viewOnly` Header    | confirm 비활성                                                  |
+| `authService` 미전달 | confirm 비활성 (wr/fo 등)                                       |
+| 페이지 새로고침      | AuthWrapper가 refresh 타이머 복구, Header가 confirm 타이머 복구 |
+
+## 8) 적용 체크리스트
+
+[리팩토링 가이드 체크리스트](./auth-service-refactoring-guide.md#4-서비스별-적용-체크리스트)에 더해 아래를 확인합니다.
+
+- [ ] `auth-service`에 `declineSessionExtend` 구현
+- [ ] `token-manager`에서 `clearRefreshTimer` re-export
+- [ ] `BaseLayout`에 `authService` prop 전달 (→ Header까지)
+- [ ] `ConfirmProvider` > `AuthWrapper` > `BaseLayout` > `Header` 계층 확인
+- [ ] `AuthWrapper`에 `useSessionExtendConfirm` **없음** 확인
+- [ ] 만료 5분 전 confirm 노출 확인
+- [ ] 확인 클릭 시 `SILENT_REFRESH` API 호출 확인
+- [ ] 취소 클릭 시 만료 1분 전 자동 refresh 미발생 확인
+
+## 9) 검증 방법
+
+1. 로그인 후 JWT `exp`가 5분 이내가 되도록 대기하거나 테스트 토큰 사용
+2. confirm 문구 `"로그인을 연장하시겠습니까?"` 표시 확인
+3. **확인** → Network 탭에서 `SILENT_REFRESH` PUT 호출, 쿠키 갱신, confirm 재예약
+4. **취소** → 만료 1분 전까지 `SILENT_REFRESH` 자동 호출 없음
+5. 취소 후 세션 만료 → 401 / 로그인 리다이렉트
+6. 새로고침 후 refresh·confirm 타이머 복구
+
+## 10) 참고 구현
+
+| 앱  | Header (공통)                                                                                                 | auth-service                                                                                        | BaseLayout layout                                                                                         |
+| --- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| cs  | `[packages/common/components/src/ui/header/index.tsx](../packages/common/components/src/ui/header/index.tsx)` | `[apps/cs/src/entities/auth/api/auth-service.ts](../apps/cs/src/entities/auth/api/auth-service.ts)` | `[apps/cs/app/(main)/(with-base-layout)/layout.tsx](../apps/cs/app/(main)`/(with-base-layout)/layout.tsx) |
+| as  | (동일)                                                                                                        | `[apps/as/src/entities/auth/api/auth-service.ts](../apps/as/src/entities/auth/api/auth-service.ts)` | `[apps/as/src/app/layouts/base-layout.tsx](../apps/as/src/app/layouts/base-layout.tsx)`                   |
+| st  | (동일)                                                                                                        | `[apps/st/src/entities/auth/api/auth-service.ts](../apps/st/src/entities/auth/api/auth-service.ts)` | `[apps/st/app/(main)/(with-base-layout)/layout.tsx](../apps/st/app/(main)`/(with-base-layout)/layout.tsx) |
+
+## 11) 관련 문서
+
+- [서비스별 인증 처리 리팩토링 가이드](./auth-service-refactoring-guide.md) — 선행 리팩토링
+- `[packages/common/auth/README.md](../packages/common/auth/README.md)` — `getRemainingMs`, token-manager API