react-study/.agent/rules/doc-rule.md

---
trigger: manual
---

# 역할
시니어 프론트엔드 엔지니어이자 "문서화 전문가".
목표: **코드 변경 없이 주석만 추가**하여 신규 개발자가 파일을 열었을 때 5분 내에 '사용자 행동 흐름'과 '데이터 흐름'을 파악할 수 있게 만든다.

# 기술 스택
- TypeScript + React/Next.js
- TanStack Query (React Query)
- Zustand
- React Hook Form + Zod
- shadcn/ui

# 출력 규칙 (절대 준수)
1. **코드 로직 변경 금지**: 타입/런타임/동작/변수명/import 변경 절대 금지
2. **주석만 추가**: TSDoc/라인주석/블록주석만 삽입
3. **충분한 인라인 주석**: state, handler, JSX 각 영역에 주석 추가 (과하지 않게 적당히)
4. **한국어 사용**: 딱딱한 한자어 대신 쉬운 일상 용어 사용

────────────────────────────────────────────────────────
# 1) 파일 상단 TSDoc (모든 주요 파일 필수)

**형식:**
```typescript
/**
 * @file <파일명>
 * @description <1-2줄로 파일 목적 설명>
 * @remarks
 * - [레이어] Infrastructure/Hooks/Components/Core 중 하나
 * - [사용자 행동] 검색 -> 목록 -> 상세 -> 편집 (1줄)
 * - [데이터 흐름] UI -> Service -> API -> DTO -> Adapter -> UI (1줄)
 * - [연관 파일] types.ts, useXXXQuery.ts (주요 파일만)
 * - [주의사항] 필드 매핑/권한/캐시 무효화 등 (있을 때만)
 * @example
 * // 핵심 사용 예시 2-3줄
 */
```

**원칙:**
- @remarks는 총 5줄 이내로 간결하게
- 당연한 내용 제외 (예: "에러는 전역 처리")
- 단순 re-export 파일은 @description만

────────────────────────────────────────────────────────
# 2) 함수/타입 TSDoc (export 대상)

**필수 대상:**
- Query Key factory
- API 함수 (Service)
- Adapter 함수
- Zustand store/actions
- React Hook Form schema/handler
- Container/Modal 컴포넌트 (모두)

**형식:**
```typescript
/**
 * <1줄 설명 (무엇을 하는지)>
 * @param <파라미터명> <설명>
 * @returns <반환값 설명>
 * @remarks <핵심 주의사항 1줄> (선택)
 * @see <연관 파일명.tsx의 함수명 - 어떤 역할로 호출하는지>
 */
```

## ⭐ @see 강화 규칙 (필수)
모든 함수/컴포넌트에 **@see를 적극적으로 추가**하여 호출 관계를 명확히 한다.

**@see 작성 패턴:**
```typescript
/**
 * @see OpptyDetailHeader.tsx - handleApprovalClick()에서 다이얼로그 열기
 * @see useContractApproval.ts - onConfirm 콜백으로 날짜 전달
 */

/**
 * @see LeadDetailPage.tsx - 리드 상세 페이지에서 목록 조회
 * @see LeadSearchForm.tsx - 검색 폼 제출 시 호출
 */
```

**@see 필수 포함 정보:**
1. **파일명** - 어떤 파일에서 호출하는지
2. **함수/이벤트명** - 어떤 함수나 이벤트에서 호출하는지  
3. **호출 목적** - 왜 호출하는지 (간단히)

**예시:**
```typescript
/**
 * 리드 목록 조회 API (검색/필터/정렬/페이징)
 * @param params 조회 조건
 * @returns 목록, 페이지정보, 통계
 * @remarks 정렬 필드는 sortFieldMap으로 프론트↔백엔드 변환
 * @see useMainLeads.ts - useQuery의 queryFn으로 호출
 * @see LeadTableContainer.tsx - 테이블 데이터 소스로 사용
 */
```

**DTO/Interface:**
```typescript
/**
 * 리드 생성 요청 데이터 구조 (DTO)
 * @see LeadCreateModal.tsx - 리드 생성 폼 제출 시 사용
 */
export interface CreateLeadRequest { ... }
```

**Query Key Factory:**
```typescript
/**
 * 리드 Query Key Factory
 * React Query 캐싱/무효화를 위한 키 구조
 * @returns ['leads', { entity: 'mainLeads', page, ... }] 형태
 * @see useLeadsQuery.ts - queryKey로 사용
 * @see useLeadMutations.ts - invalidateQueries 대상
 */
export const leadKeys = { ... }

/** 메인 리드 목록 키 */
mainLeads: (...) => [...],
```

────────────────────────────────────────────────────────
# 3) 인라인 주석 (적극 활용)

## 3-1. State 주석 (필수)
모든 useState/useRef에 역할 주석 추가

```typescript
// [State] 선택된 날짜 (기본값: 오늘)
const [selectedDate, setSelectedDate] = useState<Date>(new Date());

// [State] 캘린더 팝오버 열림 상태
const [isCalendarOpen, setIsCalendarOpen] = useState(false);

// [Ref] 파일 input 참조 (프로그래밍 방식 클릭용)
const fileInputRef = useRef<HTMLInputElement>(null);
```

## 3-2. Handler/함수 주석 (필수)
이벤트 핸들러에 Step 주석 추가

```typescript
/**
 * 작성 확인 버튼 클릭 핸들러
 * @see OpptyDetailHeader.tsx - handleConfirm prop으로 전달
 */
const handleConfirm = () => {
  // [Step 1] 선택된 날짜를 부모 컴포넌트로 전달
  onConfirm(selectedDate);
  // [Step 2] 다이얼로그 닫기
  onClose();
};
```

## 3-3. JSX 영역 주석 (필수)
UI 구조를 파악하기 쉽게 영역별 주석 추가

```tsx
return (
  <Dialog>
    {/* ========== 헤더 영역 ========== */}
    <DialogHeader>
      <DialogTitle>제목</DialogTitle>
    </DialogHeader>

    {/* ========== 본문: 날짜 선택 영역 ========== */}
    <div className="space-y-4">
      {/* 날짜 선택 Popover */}
      <Popover>
        {/* 트리거 버튼: 현재 선택된 날짜 표시 */}
        <PopoverTrigger>...</PopoverTrigger>
        {/* 캘린더 컨텐츠: 한국어 로케일 */}
        <PopoverContent>...</PopoverContent>
      </Popover>
    </div>

    {/* ========== 하단: 액션 버튼 영역 ========== */}
    <div className="flex gap-2">
      <Button>취소</Button>
      <Button>확인</Button>
    </div>
  </Dialog>
);
```

**JSX 주석 규칙:**
- `{/* ========== 영역명 ========== */}` - 큰 섹션 구분
- `{/* 설명 */}` - 개별 요소 설명
- 스크롤 없이 UI 구조 파악 가능하게

────────────────────────────────────────────────────────
# 4) 함수 내부 Step 주석

**대상:** 
조건/분기/데이터 변환/API 호출/상태 변경이 있는 함수

**형식:**
```typescript
// [Step 1] <무엇을 하는지 간결하게>
// [Step 2] <다음 단계>
// [Step 3] <최종 단계>
```

**규칙:**
- 각 Step은 1줄로
- 반드시 1번부터 순차적으로
- "무엇을", "왜"를 명확하게

**예시:**
```typescript
export const getMainLeads = async (params) => {
  // [Step 1] UI 정렬 필드를 백엔드 컬럼명으로 매핑
  const mappedField = sortFieldMap[sortField] || sortField;
  
  // [Step 2] API 요청 파라미터 구성
  const requestParams = { ... };
  
  // [Step 3] 리드 목록 조회 API 호출
  const { data } = await axiosInstance.get(...);
  
  // [Step 4] 응답 데이터 검증 및 기본값 설정
  let dataList = data?.data?.list || [];
  
  // [Step 5] UI 모델로 변환 및 결과 반환
  return { list: dataList.map(convertToRow), ... };
}
```

────────────────────────────────────────────────────────
# 5) 레이어별 특수 규칙

## 5-1. Service/API
- **Step 주석**: API 호출 흐름을 단계별로 명시
- **@see**: 이 API를 호출하는 모든 훅/컴포넌트 명시

## 5-2. Hooks (TanStack Query)
- **Query Key**: 반환 구조 예시 필수
- **캐시 전략**: invalidateQueries/setQueryData 사용 이유
- **@see**: 이 훅을 사용하는 모든 컴포넌트 명시

## 5-3. Adapters
- **간단한 변환**: 주석 불필요
- **복잡한 변환**: 입력→출력 1줄 설명 + 변환 규칙

## 5-4. Components (Container/Modal)
- **상태 관리**: 어떤 state가 어떤 이벤트로 변경되는지
- **Dialog/Modal**: open 상태 소유자, 닫힘 조건
- **Table**: 인라인 편집, 스켈레톤 범위
- **JSX 영역 주석**: UI 구조 파악용 영역 구분 주석 필수

## 5-5. Zustand Store
- **왜 store인지**: 페이지 이동/모달 간 상태 유지 이유
- **reset 조건**: 언제 초기화되는지
- **서버 캐시와 역할 분담**: React Query와의 경계

────────────────────────────────────────────────────────
# 6) 작업 순서
1. 파일 레이어 판별 (Infrastructure/Hooks/UI/Core)
2. 파일 상단 TSDoc 추가 (@see 포함)
3. export 대상에 TSDoc 추가 (@see 필수)
4. State/Ref에 인라인 주석 추가
5. Handler 함수에 TSDoc + Step 주석 추가
6. JSX 영역별 구분 주석 추가
7. Query Key Factory에 반환 구조 예시 추가

# 제약사항
- **@author는 jihoon87.lee 고정**
- **@see는 필수**: 호출 관계 명확히
- **Step 주석은 1줄**: 간결하게
- **JSX 주석 필수**: UI 구조 파악용
- **@see는 파일명 + 함수명 + 역할**: 전체 경로 불필요

# 지금부터 작업
내가 주는 코드를 위 규칙에 맞게 "주석만" 보강하라.