# Next.js 프로덕션 빌드 에러 원인 분석 및 조치 보고서

본 문서는 `apps/as` 프로덕션 빌드(`pnpm build:as` / `next build`) 과정에서 발생한 ESLint Hook 규칙 위반 및 TypeScript 컴파일 에러의 원인과 이를 해결한 조치 내역을 정리한 문서입니다.

---

## 1. 개요 및 장애 상황

- **대상 모듈**: `apps/as` (행정지원 프론트엔드 애플리케이션)
- **실행 명령**: `pnpm build:as` (또는 `pnpm --filter as build`)
- **발생 시점**: 2026-10-20
- **장애 영향**: Next.js 프로덕션 최적화 빌드 실패로 인해 배포 산출물(`.next`) 생성이 중단됨

### 빌드 실패 로그 요약
```text
as:build: Failed to compile.

as:build: ./src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx
as:build: 159:35  Error: React Hook "useStore" is called conditionally. React Hooks must be called in the exact same order in every component render.  react-hooks/rules-of-hooks

./src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx:164:5
Type error: Type 'boolean' has no properties in common with type '{ enabled?: boolean | undefined; structuralSharing?: boolean | undefined; }'.

./src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx:215:29
Type error: Property 'atrzSeq' does not exist on type 'ElaprDocPrgrsClientResponseDto'. Did you mean 'atrzSeqNo'?
```

---

## 2. 근본 원인 분석 (Root Cause Analysis)

### 2.1 React Hook 규칙 위반 (`react-hooks/rules-of-hooks`)
- **위치**: `apps/as/src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx` (158~159라인)
- **원인 코드**:
  ```tsx
  const storeContext = useContext(StoreContext);
  const userInfo = storeContext ? useStore(storeContext.userStore, (state) => state.userInfo) : null;
  ```
- **문제점**:
  - React Hooks는 조건문, 반복문, 삼항 연산자 내부에서 호출될 수 없으며, 모든 렌더링마다 항상 동일한 순서로 호출되어야 합니다.
  - 삼항 연산자 내에서 `useStore`를 호출하면서 `react-hooks/rules-of-hooks` 에러가 발생하여 빌드가 즉시 차단되었습니다.
  - 또한 프로젝트 전역에서 제공하는 표준 훅인 `useUserStore`(`@/shared/lib`)가 이미 존재함에도 불구하고 이를 사용하지 않고 수동으로 컨텍스트를 조회하여 분기 처리하고 있었습니다.

### 2.2 `useElaprBranchesByDocNo` 훅 옵션 매개변수 타입 불일치
- **원인 코드**:
  ```tsx
  const { data: elaprBranchList = [] } = useElaprBranchesByDocNo(
    fnrsCnsltnDocNo,
    open && Boolean(isForkJoin), // boolean 직접 전달
  );
  ```
- **문제점**:
  - `useElaprBranchesByDocNo`의 시그니처는 `(elaprDocNo, options?: { enabled?: boolean; structuralSharing?: boolean })`로 선언되어 있어, `boolean` 대신 객체 형태(`{ enabled: ... }`)로 전달해야 합니다.

### 2.3 전자결재 결재선 DTO 필드명 불일치
- **원인 코드**:
  ```tsx
  if (currentUserPrgrs?.atrzSeq && Number(currentUserPrgrs.atrzSeq) > 1) return true;
  ```
- **문제점**:
  - `ElaprDocPrgrsClientResponseDto` 인터페이스(`src/shared/model/pbadms-sprt.ts`)에 선언된 정식 결재 순번 필드명은 `atrzSeqNo?: number`입니다.
  - 기존 코드가 `atrzSeq`로 접근하여 TypeScript 컴파일 에러가 발생했습니다.

### 2.4 `PwrkCnsltnDocEvlDialog`의 필수 prop `onSaved` 누락
- **원인 코드**:
  ```tsx
  <PwrkCnsltnDocEvlDialog
    open={isEvlDialogOpen}
    pwrkCnsltnDocNo={completedDraft.pwrkCnsltnDocNo}
    onClose={() => setIsEvlDialogOpen(false)}
  />
  ```
- **문제점**:
  - `PwrkCnsltnDocEvlDialogProps`에 `onSaved: () => void;`가 필수로 선언되어 있었으나, 호출부에서 `onSaved` 콜백을 넘기지 않아 `Property 'onSaved' is missing` 컴파일 에러가 발생했습니다.

---

## 3. 조치 내역

### 3.1 컴포넌트 코드 수정 (`pwrk-cnsltn-doc-mng-dialog.tsx`)
1. **표준 `useUserStore` 훅 적용**:
   - `useStore`, `StoreContext`, `useContext`를 제거하고, `@/shared/lib`의 `useUserStore`를 무조건부로 호출하도록 변경.
2. **`useElaprBranchesByDocNo` 옵션 객체화**:
   - `{ enabled: open && Boolean(isForkJoin) }` 형태로 수정.
3. **결재 순번 속성 방어적 매핑**:
   - `atrzSeqNo`를 우선 참조하고 레거시/모의 데이터의 `atrzSeq`도 호환되도록 fallback 처리.
4. **`PwrkCnsltnDocEvlDialog`의 `onSaved` prop 연결 및 선택적(Optional) 처리**:
   - `pwrk-cnsltn-doc-evl-dialog.tsx`: `onSaved?: () => void;`로 변경하고 `onSaved?.()` 호출로 방어.
   - `pwrk-cnsltn-doc-mng-dialog.tsx`: `<PwrkCnsltnDocEvlDialog ... onSaved={() => setIsEvlDialogOpen(false)} />` 콜백 전달.

#### 핵심 변경 사항 (Diff)
```diff
--- a/apps/as/src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx
+++ b/apps/as/src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx
@@ -1,14 +1,11 @@
 "use client";
 
-import { useContext, useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import dynamic from "next/dynamic";
 
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { PanelRightClose, PanelRightOpen } from "lucide-react";
-import { useStore } from "zustand";
-
-import { getDefaultFileKey, useAlertStore, useTus } from "@/shared/lib";
-import { StoreContext } from "@/shared/providers";
+import { getDefaultFileKey, useAlertStore, useTus, useUserStore } from "@/shared/lib";
 
@@ -155,8 +152,7 @@ function PwrkCnsltnDocMngDialog({
   const queryClient = useQueryClient();
   const alert = useAlertStore((state) => state.setMessage);
-  const storeContext = useContext(StoreContext);
-  const userInfo = storeContext ? useStore(storeContext.userStore, (state) => state.userInfo) : null;
+  const userInfo = useUserStore((state) => state.userInfo);
 
@@ -165,7 +161,7 @@ function PwrkCnsltnDocMngDialog({
   const { data: elaprBranchList = [] } = useElaprBranchesByDocNo(
     fnrsCnsltnDocNo,
-    open && Boolean(isForkJoin),
+    { enabled: open && Boolean(isForkJoin) },
   );
 
@@ -216,11 +212,19 @@ function PwrkCnsltnDocMngDialog({
     if (effectiveBranchSeCd === "TOTAL_AGG") {
       if (effectiveAtrzSeList.includes("ATRZ04")) return false;
       if (effectiveAtrzSeList.some((cd) => APPROVER_ATRZ_SE_COM_CDS.has(cd))) return true;
-      if (currentUserPrgrs?.atrzSeq && Number(currentUserPrgrs.atrzSeq) > 1) return true;
+      const userSeq = currentUserPrgrs?.atrzSeqNo ?? (currentUserPrgrs as Record<string, unknown> | undefined)?.atrzSeq;
+      if (userSeq && Number(userSeq) > 1) return true;
       if (effectiveAtrzSeList.length > 0 && !effectiveAtrzSeList.includes("ATRZ04")) return true;
     }
     return false;
```

### 3.2 단위 테스트 모킹 보완 (`pwrk-cnsltn-doc-mng-dialog.test.tsx`)
- 단위 테스트 환경에서 `StoreProvider` 미감싸임 에러(`useUserStore must be used within StoreProvider`)가 발생하지 않도록 `@/shared/lib` 모킹 객체에 `useUserStore`를 추가.
```tsx
let mockUserInfo: any = null;

vi.mock("@/shared/lib", async (importOriginal) => {
  const actual = await importOriginal<typeof import("@/shared/lib")>();
  return {
    ...actual,
    getDefaultFileKey: () => "mock-key",
    useAlertStore: () => vi.fn(),
    useUserStore: (selector: (state: { userInfo: any }) => any) =>
      selector ? selector({ userInfo: mockUserInfo }) : { userInfo: mockUserInfo },
    useTus: () => ({
      uploadFileAsync: vi.fn(),
      isUploading: {},
      uploads: {},
    }),
  };
});
```

---

## 4. 검증 결과

| 검증 단계 | 명령어 | 결과 | 비고 |
|---|---|---|---|
| **1. 정적 타입 검사** | `pnpm --filter as exec tsc --noEmit` | **성공 (Exit 0)** | 컴파일 에러 0건 |
| **2. ESLint 린트 검사** | `pnpm --filter as lint` | **성공 (Exit 0)** | Hook 위반 에러 해결 |
| **3. 단위 테스트 (Vitest)** | `pnpm --filter as exec vitest run` | **전체 통과 (73/73 Tests)** | 14개 테스트 파일 100% Pass |
| **4. 프로덕션 빌드** | `pnpm build:as` | **성공 (Exit 0)** | 22/22 정적 페이지 최적화 완료 |

---

## 5. 재발 방지 표준 가이드

1. **React Hook 호출 규칙 준수**:
   - `useUserStore`, `useQuery`, `useStore` 등 모든 React Hook은 반드시 컴포넌트 함수의 최상단(Top-level)에서 무조건부로 호출해야 합니다.
   - 사용자 정보가 필요할 경우 개별 컨텍스트 접근 대신 표준 훅인 `useUserStore((state) => state.userInfo)`를 사용합니다.

2. **React Query 커스텀 훅 매개변수 규칙**:
   - 조건부 쿼리 실행이 필요한 경우 boolean 값을 단독으로 넘기지 않고 `{ enabled: boolean }` 형태의 옵션 객체 인터페이스를 유지합니다.

3. **엔티티 DTO 필드명 엄격 확인**:
   - 전자결재 결재선 DTO는 백엔드 명세에 따라 `atrzSeqNo`를 표준으로 사용하므로 레거시 명칭(`atrzSeq`)을 사용하지 않도록 타입을 확인합니다.