FE 구현 플랜: 등록 관리 페이지

변경 이력

1. 개요

등록 관리 페이지(/enrollment)를 신규 구현한다.

구현 범위:

• FR-0: 등록 관리 메인 페이지 (카드 목록 + 통합 테이블)
• FR-1: 등록 현황 요약 카드
• FR-2: 등록자 목록 테이블 (고정 + 커스텀 컬럼)
• FR-3: 납부 여부 빠른 토글
• FR-4: 납부 일괄 승인
• FR-5: 등록자 상세/수정 슬라이드 오버 패널
• FR-6: CSV 다운로드
• FR-7-A: 참석 옵션 관리 (조건부 — PO Scope 확정 대기)
• FR-7-B: 커스텀 폼 필드 관리 (Form Builder)
• SidePanel 공통 컴포넌트 추출 + UserEditPanel 마이그레이션

2. 기술 결정사항

2-1. 기존 패턴 준수

2-2. 신규 결정

필터 URL 전략 비고: 기존 UsersPageClient는 검색어도 URL searchParams에 포함하지만, 등록 관리에서는 이름 검색을 로컬 state로 관리한다. 근거: (1) 이름 검색은 일시적 탐색 용도이므로 URL 보존 불필요, (2) 서버 필터(isPaid, attendanceType)만 URL에 두면 뒤로가기/공유 시 의미 있는 필터 상태가 보존된다. 서버 필터 변경 시 검색어는 유지된다.

3. 디렉토리 구조

packages/client/missionary-admin/src/
+-- apis/
|   +-- participation.ts              # [신규] Participation CRUD API + 타입
|   +-- participation.server.ts       # [신규] 서버 컴포넌트용 래퍼
|   +-- enrollment.ts                 # [신규] 메인 페이지 선교 요약 API + EnrollmentMissionSummary 타입
|   +-- enrollment.server.ts          # [신규] 서버 컴포넌트용 래퍼
|   +-- formField.ts                  # [신규] MissionaryFormField CRUD API + 타입
|   +-- attendanceOption.ts           # [신규] MissionaryAttendanceOption CRUD API + 타입
|   +-- missionary.ts                 # [기존 유지] 메인 페이지용 데이터는 enrollment.ts로 분리
|
+-- lib/
|   +-- queryKeys.ts                  # [수정] participations, formFields, attendanceOptions, enrollmentSummary 키 추가
|
+-- components/
|   +-- sidebar/Sidebar.tsx           # [수정] NAV_ITEMS에 "등록 관리" 추가
|   +-- ui/
|       +-- SidePanel.tsx             # [신규] 공통 슬라이드 오버 패널
|
+-- app/(admin)/
|   +-- enrollment/                   # [신규] 등록 관리 메인
|   |   +-- page.tsx                  #   서버 컴포넌트 (SSR initial data)
|   |   +-- loading.tsx               #   스켈레톤 로딩
|   |   +-- _components/
|   |   |   +-- EnrollmentListPage.tsx        # 메인 페이지 클라이언트 컴포넌트
|   |   |   +-- HighlightCardSection.tsx      # Section A: 마감 임박 카드 그리드
|   |   |   +-- MissionEnrollmentCard.tsx     # 개별 선교 카드
|   |   |   +-- MissionEnrollmentTable.tsx    # Section B: 통합 테이블
|   |   |   +-- MissionStatusChips.tsx        # 상태 필터 칩
|   |   +-- _hooks/
|   |       +-- useGetEnrollmentSummary.ts    # 메인 페이지 데이터 훅
|   |
|   +-- enrollment/[missionaryId]/    # [신규] 선교별 등록 관리 상세
|   |   +-- page.tsx                  #   서버 컴포넌트
|   |   +-- loading.tsx               #   스켈레톤 로딩
|   |   +-- _components/
|   |   |   +-- EnrollmentDetailPage.tsx      # 상세 페이지 클라이언트 오케스트레이션
|   |   |   +-- EnrollmentDetailHeader.tsx    # 페이지 헤더 (뒤로가기 + 선교명 + 상태)
|   |   |   +-- EnrollmentSummaryCard.tsx     # FR-1: 등록 현황 요약
|   |   |   +-- SummaryStatItem.tsx           # 요약 카드 내 수치 항목
|   |   |   +-- ProgressBar.tsx               # 달성률 프로그레스 바 (className으로 스타일 분기)
|   |   |   +-- EnrollmentToolbar.tsx         # 도구 모음 (필터 + 검색 + 버튼)
|   |   |   +-- ParticipantTable.tsx          # FR-2: 등록자 테이블
|   |   |   +-- ParticipantRow.tsx            # 테이블 행 (분리)
|   |   |   +-- PaymentBadge.tsx              # FR-3: 납부 토글 배지
|   |   |   +-- BulkApproveModal.tsx          # FR-4: 납부 일괄 승인 모달
|   |   |   +-- panel/
|   |   |   |   +-- ParticipantPanel.tsx      # FR-5: 등록자 상세/수정 패널
|   |   |   |   +-- ParticipantForm.tsx       # 패널 내 폼
|   |   |   |   +-- CustomFieldInput.tsx      # fieldType별 입력 분기
|   |   |   +-- form-builder/
|   |   |       +-- FormBuilderSection.tsx    # FR-7-B: 폼 빌더 섹션 전체
|   |   |       +-- FormBuilderToolbar.tsx    # sticky 툴바 (미저장 + 저장)
|   |   |       +-- FormFieldCard.tsx         # 필드 카드 (미확장/확장/고정)
|   |   |       +-- FormFieldSettings.tsx     # 확장 시 편집 영역
|   |   |       +-- AddFieldButton.tsx        # 점선 추가 카드
|   |   |       +-- AttendanceOptionManager.tsx  # FR-7-A: 참석 옵션 관리 (조건부)
|   |   |       +-- TagInput.tsx              # SELECT 선택지 입력
|   |   +-- _hooks/
|   |   |   +-- useGetParticipations.ts       # 등록자 목록 조회
|   |   |   +-- useGetParticipation.ts        # 등록자 상세 조회
|   |   |   +-- useUpdateParticipation.ts     # 등록자 수정 mutation
|   |   |   +-- useTogglePayment.ts           # 납부 토글 (낙관적 업데이트)
|   |   |   +-- useBulkApprovePayment.ts      # 납부 일괄 승인
|   |   |   +-- useGetFormFields.ts           # 폼 필드 목록 조회
|   |   |   +-- useFormFieldMutations.ts      # 폼 필드 CRUD mutations
|   |   |   +-- useGetAttendanceOptions.ts    # 참석 옵션 목록 조회
|   |   |   +-- useAttendanceOptionMutations.ts  # 참석 옵션 CRUD mutations
|   |   +-- _schemas/
|   |   |   +-- participantSchema.ts          # 등록자 수정 폼 zod 스키마
|   |   |   +-- formFieldSchema.ts            # 폼 필드 추가/수정 zod 스키마
|   |   +-- _utils/
|   |       +-- formatParticipant.ts          # 등록자 데이터 포맷 유틸
|   |       +-- csvDownload.ts                # CSV 다운로드 유틸
|   |
|   +-- users/_components/panel/
|       +-- UserEditPanel.tsx         # [수정] SidePanel 공통 컴포넌트로 교체

4. API 클라이언트 & 타입 정의

4-1. apis/enrollment.ts (메인 페이지 전용)

// === 메인 페이지 선교 요약 타입 ===
 
interface EnrollmentMissionSummary {
  id: string;
  name: string;
  order: number | null;
  category: 'DOMESTIC' | 'OVERSEAS';
  status: 'ENROLLMENT_PREPARING' | 'ENROLLMENT_OPENED' | 'ENROLLMENT_CLOSED' | 'COMPLETED';
  enrollmentDeadline: string | null;
  missionStartDate: string;
  missionEndDate: string;
  maximumParticipantCount: number | null;
  currentParticipantCount: number;
  paidCount: number;
  managerName: string | null;
}
 
interface GetEnrollmentSummaryResponse {
  missions: EnrollmentMissionSummary[];
  totalRecruitingCount: number;        // ENROLLMENT_OPENED 상태 선교 수
  totalRecruitingParticipants: number;  // 모집 중 선교 등록자 합계
}
 
// === API 함수 ===
 
const enrollmentApi = {
  getEnrollmentSummary(): Promise<GetEnrollmentSummaryResponse>,
};

BE 확인 필요: 기존 GET /missionaries 확장 vs 신규 엔드포인트(GET /enrollment/summary) 결정. 응답에 currentParticipantCount, paidCount 집계가 포함되어야 함.

4-2. apis/participation.ts

// === 타입 정의 ===
 
interface AttendanceOption {
  id: string;
  missionaryId: string;
  type: 'FULL' | 'PARTIAL';
  label: string;
  order: number;
}
 
interface FormFieldDefinition {
  id: string;
  missionaryId: string;
  fieldType: 'TEXT' | 'TEXTAREA' | 'NUMBER' | 'BOOLEAN' | 'SELECT' | 'DATE';
  label: string;
  placeholder: string | null;
  isRequired: boolean;
  order: number;
  options: string[] | null;
  hasAnswers: boolean;  // 삭제 가능 여부 판단용
}
 
interface FormAnswer {
  id: string;
  formFieldId: string;
  value: string;
}
 
interface ParticipationTeam {
  id: string;
  teamName: string;
}
 
interface Participation {
  id: string;
  name: string;
  birthDate: string;
  applyFee: number | null;
  isPaid: boolean;
  identificationNumber: string | null;
  isOwnCar: boolean;
  missionaryId: string;
  userId: string;
  teamId: string | null;
  team: ParticipationTeam | null;
  createdAt: string;
  // 신규 필드
  affiliation: string;
  attendanceOptionId: string;
  attendanceOption: AttendanceOption;
  cohort: number;
  hasPastParticipation: boolean | null;
  isCollegeStudent: boolean | null;
  // 커스텀 필드 답변
  formAnswers: FormAnswer[];
}
 
interface GetParticipationsParams {
  missionaryId: string;
  page?: number;
  pageSize?: number;
  isPaid?: boolean;               // 서버 필터 (URL searchParams)
  attendanceType?: 'FULL' | 'PARTIAL';  // 서버 필터 (URL searchParams)
  // query(이름 검색)는 클라이언트 사이드이므로 API 파라미터에 포함하지 않음
}
 
interface PaginatedParticipationsResponse {
  items: Participation[];
  total: number;
  page: number;
  pageSize: number;
}
 
interface UpdateParticipationPayload {
  // 이름, 생년월일은 읽기 전용이므로 수정 payload에서 제외 (PO 확인 필요 — Design Spec 기준)
  affiliation?: string;
  attendanceOptionId?: string;
  cohort?: number;
  hasPastParticipation?: boolean;
  isCollegeStudent?: boolean;
  isPaid?: boolean;
  answers?: { formFieldId: string; value: string }[];
}
 
// === API 함수 ===
 
const participationApi = {
  getParticipations(params: GetParticipationsParams),
  getParticipation(id: string),
  updateParticipation(id: string, data: UpdateParticipationPayload),
  bulkApprovePayment(ids: string[]),
  downloadCsv(missionaryId: string),  // blob 반환
};

PO 확인 필요 (GAP 5): 이름/생년월일 편집 가능 여부. 현재 Design Spec 기준 읽기 전용으로 구현한다. PRD는 편집 가능이라 명시했으나, Design Spec에서 개인정보 섹션(bg-gray-50 + 잠금 아이콘)으로 분류했으므로 읽기 전용이 의도. PO 확인 후 변경 용이하도록 UpdateParticipationPayload에서 분리해 놓았다.

4-3. apis/formField.ts

const formFieldApi = {
  getFormFields(missionaryId: string),
  createFormField(missionaryId: string, data: CreateFormFieldPayload),
  updateFormField(missionaryId: string, fieldId: string, data: UpdateFormFieldPayload),
  deleteFormField(missionaryId: string, fieldId: string),
  reorderFormFields(missionaryId: string, data: { fieldIds: string[] }),
};

4-4. apis/attendanceOption.ts

const attendanceOptionApi = {
  getAttendanceOptions(missionaryId: string),
  createAttendanceOption(missionaryId: string, data: CreateAttendanceOptionPayload),
  updateAttendanceOption(missionaryId: string, optionId: string, data: UpdateAttendanceOptionPayload),
  deleteAttendanceOption(missionaryId: string, optionId: string),
};

4-5. lib/queryKeys.ts 확장

// 추가할 키
enrollmentSummary: {
  all: ['enrollmentSummary'] as const,
  list: () => [...queryKeys.enrollmentSummary.all, 'list'] as const,
},
participations: {
  all: ['participations'] as const,
  list: (params?: object) => [...queryKeys.participations.all, 'list', params] as const,
  detail: (id: string) => [...queryKeys.participations.all, 'detail', id] as const,
},
formFields: {
  all: ['formFields'] as const,
  list: (missionaryId: string) => [...queryKeys.formFields.all, 'list', missionaryId] as const,
},
attendanceOptions: {
  all: ['attendanceOptions'] as const,
  list: (missionaryId: string) => [...queryKeys.attendanceOptions.all, 'list', missionaryId] as const,
},

5. 구현 Wave (의존 관계 기반 순서)

Wave 0: 사전 준비

PR 없음 -- BE 의존성 확인 + 패키지 설치

Wave 1: 데이터 레이어 (API + 타입 + 쿼리 훅)

PR 1: feat: 등록 관리 API 클라이언트 및 쿼리 훅 추가 예상 ~300줄

Wave 1에서 EnrollmentMissionSummary 타입을 반드시 정의한다 (GAP 7). 메인 페이지 Section A/B 모두 이 타입에 의존한다.

Wave 2: 공통 컴포넌트 -- SidePanel 추출

PR 2: refactor: UserEditPanel에서 SidePanel 공통 컴포넌트 추출 예상 ~350줄

구현 순서 비고 (GAP 8): PRD SS6-2에서는 "FR-5 구현 -> 공통 추출 -> UserEditPanel 교체" 순서를 제시하지만, FE Plan에서는 "공통 추출(Wave 2) -> FR-5에서 재사용(Wave 6)" 순서를 채택했다. 근거: 공통 컴포넌트를 먼저 추출해야 ParticipantPanel에서 바로 재사용 가능하며, UserEditPanel 마이그레이션도 같은 PR에서 regression 확인이 가능하다.

SidePanel 핵심 구현 사항:

• 컨테이너: fixed right-0 top-0 h-full w-[560px] z-30
• 트랜지션: transition-transform duration-300 ease-[cubic-bezier(0.16,1,0.3,1)]
• 그림자: shadow-[-4px_0_24px_rgba(0,0,0,0.08),-1px_0_4px_rgba(0,0,0,0.04)]
• Backdrop: fixed inset-0 z-20 bg-black/20 (클릭 시 onClose)
• Esc 키로 닫기
• 마운트/언마운트 분리: 애니메이션 완료까지 DOM 유지 (mountedId 패턴)

UserEditPanel 마이그레이션 체크리스트:

• 슬라이드 인/아웃 애니메이션 동일
• 이전/다음 유저 네비게이션 동작
• 더보기 메뉴 (삭제) 동작
• 미저장 변경 경고 모달 동작
• 폼 저장/취소 동작

Wave 3: 등록 관리 메인 페이지 (FR-0)

PR 3: feat: 등록 관리 메인 페이지 구현 예상 ~450줄

MissionEnrollmentCard 구현 사항:

• <a href="/enrollment/[missionId]"> 전체 클릭
• 상단 컬러 바: 정원 100% -> bg-green-60, 마감 3일 이내 -> bg-warning-70, 그 외 -> bg-blue-60
• 카테고리 배지: 국내=bg-green-10 text-green-60, 해외=bg-blue-10 text-blue-60
• D-day 배지: D-3 이내=bg-warning-10 text-warning-70 font-bold, 그 외=bg-gray-100 text-gray-500
• ProgressBar: className props로 높이/색상 전달 (카드: h-1.5, 정원 초과 시 bg-warning-70)
• hover: hover:border-gray-400 hover:shadow-md, 제목 group-hover:text-primary-50

MissionEnrollmentTable 구현 사항:

• ENROLLMENT_PREPARING 상태 제외 (GAP 3): Section B에 표시하지 않는다. 준비 중 선교는 등록자가 없으므로 표시 대상이 아님.
• 표시 대상: ENROLLMENT_OPENED + ENROLLMENT_CLOSED + COMPLETED
• 컬럼: 선교명, 카테고리, 신청 마감(D-day), 등록자/정원, 달성률(인라인 프로그레스 바), 납부완료, 상태
• 선교명 검색: 클라이언트 사이드 + debounce 300ms + 로컬 state (GAP 12). 상태 필터 칩 변경 시 검색어 유지.
• 필터: 클라이언트 사이드 (선교명 검색 + 상태 필터 칩)
• 정렬: 상태 우선(모집 중 -> 마감 -> 종료), 동일 상태 내 마감일 오름차순
• 행 클릭: router.push('/enrollment/[missionaryId]')
• 페이지네이션: 20건/페이지, Pagination 컴포넌트

엣지 케이스:

• 모집 중 0개 (GAP 4): Section A 자체를 숨기되, Section B 테이블 위에 인라인 안내 표시: "현재 모집 중인 선교가 없습니다." + [선교 관리로 이동] 링크 (/missions). PO 확인 필요 -- Section A 영역에 빈 상태 UI를 표시할지, 테이블 위 인라인으로 충분한지.
• 모집 중 1~3개: 해당 수만큼 카드, Section B는 카드와 무관하게 전체 선교 표시 (ENROLLMENT_PREPARING 제외)
• 모집 중 4개+: 상위 3개만 카드, 전체 테이블 표시
• 정원 미설정: "N명", 달성률 --
• 빈 상태: 필터/검색 결과 없음 -> TableEmptyState + [초기화] 버튼

Wave 4: 등록 관리 상세 -- 현황 + 테이블 (FR-1, FR-2, FR-3, FR-6)

PR 4: feat: 등록 관리 상세 페이지 -- 현황 요약 및 등록자 테이블 예상 ~450줄

필터/검색 전략 (GAP 6, GAP 14):

서버 필터(isPaid, attendanceType, page)는 URL searchParams에 저장하여 뒤로가기/URL 공유 시 필터 상태를 보존한다. 이름 검색은 일시적 탐색 용도이므로 로컬 state로 관리한다.

EnrollmentSummaryCard 구현 사항:

• 3열 그리드: 총 등록자/정원 + 납부완료/미납 + 풀참석/옵션참여
• 각 항목: 라벨(text-xs text-gray-400) + 수치(text-2xl font-bold) + 보조 수치(text-sm text-gray-500)
• ProgressBar: className="h-2" (요약 카드용), 색상 bg-gray-800
• 정원 미설정: "총 N명", 프로그레스 바 숨김
• 정원 초과: 수치 text-warning-70 + "정원 초과" 배지
• 로딩: skeleton (animate-pulse)

ProgressBar 구현 (GAP - ProgressBar):

interface ProgressBarProps {
  value: number;       // 0~100 (퍼센트)
  className?: string;  // 외부에서 높이, 색상 등 전달
}
// 사용 예:
// 요약 카드: <ProgressBar value={46} className="h-2 bg-gray-800" />
// 메인 카드: <ProgressBar value={47} className="h-1.5 bg-blue-60" />
// 테이블:   <ProgressBar value={80} className="h-1.5 w-20 bg-blue-60" />
// 정원 초과: <ProgressBar value={110} className="h-1.5 bg-warning-70" />

ParticipantTable 구현 사항:

• 컬럼 순서: 체크박스(44px) | 등록일시(140px) | 이름(100px) | 생년월일(110px) | 소속(120px) | 참석 일정(110px) | 기수(70px) | 납부 여부(90px) | 팀(90px) | 커스텀 필드(각 100px)
• 커스텀 컬럼: 최대 3개, 초과분 미표시
• 테이블 컨테이너: overflow-x-auto
• 체크박스 전체선택: 현재 페이지 기준 (GAP 10). 전체 데이터 기준이 아님.
• 체크박스: ADMIN만 표시, 헤더 전체선택/해제
• 행 hover: hover:bg-gray-50 cursor-pointer
• 선택된 행: bg-blue-10
• 행 클릭: searchParams에 participantId 설정 (체크박스 영역 제외)
• 스켈레톤/빈 상태/에러 상태: 기존 TableSkeleton, TableEmptyState 활용

CSV 다운로드 (GAP 13):

• 다운로드 버튼 클릭 시 로딩 상태 표시 (버튼에 spinner)
• 다운로드 중: Button variant="outline" loading 상태, 클릭 비활성화
• 성공 시: 파일 자동 다운로드 (blob -> <a> + URL.createObjectURL)
• 실패 시: toast.error("CSV 다운로드에 실패했습니다. 다시 시도해주세요.")

useTogglePayment 낙관적 업데이트:

// onMutate: queryClient.setQueryData로 isPaid 즉시 반영
// onError: context.previousData로 롤백 + toast.error
// onSettled: invalidateQueries (목록 + 요약)

Wave 5: 납부 일괄 승인 (FR-4)

PR 4에 포함 (또는 분리 가능)

BulkApproveModal:

• 문구: "N명의 납부를 승인합니다. / 이 작업은 되돌릴 수 없습니다."
• 버튼: [취소] + [승인]
• 성공: 모달 닫기 + 목록 갱신 + 현황 카드 갱신 + toast.success("N명의 납부가 승인되었습니다.")
• 실패: toast.error("납부 승인에 실패했습니다. 다시 시도해주세요.")
• ADMIN 전용

Wave 6: 등록자 상세/수정 패널 (FR-5)

PR 5: feat: 등록자 상세/수정 슬라이드 오버 패널 예상 ~350줄

ParticipantPanel 구현 사항:

SidePanel Props 매핑:

• title: 등록자 이름
• subtitle: "신청일 . 선교명" (예: "2026.03.25 . 35차 군선교")
• badge: 납부 배지 (납부완료=success / 미납=warning)
• onPrev / onNext: 현재 목록 배열 기반 이전/다음 등록자
• menuItems: ADMIN -> 없음 (현재 Scope에 삭제 없음)
• actionBar: ADMIN -> 납부 여부 빠른 토글 바 (FR-3)
• onSave / onCancel: ADMIN -> 표시, STAFF -> 미표시

ParticipantForm 섹션 구조:

1. 참석 정보 (편집 가능, bg-white)
   • 소속(InputField), 참석 일정(Select -- 해당 선교 옵션), 기수(InputField type="number"), 과거 참여(Switch), 대학생 여부(Switch)
2. 개인 정보 (읽기 전용, bg-gray-50, 잠금 아이콘)
   • 이름 (읽기 전용), 생년월일 (읽기 전용)

   PO 확인 필요 (GAP 5): Design Spec 기준 읽기 전용. PRD와 충돌. 현재 읽기 전용으로 구현하되, 편집 전환이 필요하면 해당 필드의 readOnly prop만 제거하면 된다.

3. 기본 정보 (읽기 전용, bg-gray-50, 잠금 아이콘)
   • 등록일시, 신청 선교, 소속 팀
4. 추가 신청 정보 -- 커스텀 필드 (ADMIN이면 편집 가능, STAFF이면 읽기 전용)
   • CustomFieldInput으로 fieldType별 렌더링

CustomFieldInput 분기:

미답변 필드: 빈 값 + text-xs text-gray-400 "미입력" 레이블

Dirty Guard:

• isDirtyRef로 폼 변경 추적
• 닫기/외부 클릭/Esc 시: dirty면 확인 모달 (overlay.openAsync)
• 문구: "저장하지 않은 변경사항이 있습니다. 정말 닫으시겠어요?"
• [계속 수정] (primary) / [닫기] (outline destructive)

Wave 7: 폼 필드 관리 -- Form Builder (FR-7-B)

PR 6: feat: 폼 필드 관리 (Form Builder) 구현 예상 ~400줄

Design Spec SS4 (모달 기반 흐름)는 v1.6 이전 잔재로 무시한다 (GAP 1). SS2-2의 인라인 WYSIWYG만 따른다.

FormBuilderSection 상태 관리:

// 서버 데이터 (TanStack Query)
const { data: serverFields } = useGetFormFields(missionaryId);
 
// 로컬 편집 상태 (useState)
const [localFields, setLocalFields] = useState<LocalFormField[]>([]);
const [activeFieldId, setActiveFieldId] = useState<string | null>(null);
const [isDirty, setIsDirty] = useState(false);
 
// serverFields 변경 시 localFields 동기화
useEffect(() => {
  if (serverFields && !isDirty) {
    setLocalFields(serverFields);
  }
}, [serverFields, isDirty]);

FormFieldCard 3가지 상태:

미확장 카드 구성:

1. 드래그 핸들 (GripVertical, cursor-grab) -- @dnd-kit/sortable useSortable
2. 타입 배지 (Badge variant="outline")
3. 라벨 텍스트 (font-medium)
4. 필수 여부 (*필수 warning / 선택 gray)
5. [펼치기] 버튼

드래그 앤 드롭 구현:

// FormBuilderSection 내부
<DndContext
  sensors={sensors}
  collisionDetection={closestCenter}
  onDragEnd={handleDragEnd}
>
  <SortableContext items={fieldIds} strategy={verticalListSortingStrategy}>
    {localFields.map(field => (
      <FormFieldCard key={field.id} field={field} ... />
    ))}
  </SortableContext>
</DndContext>

삭제 규칙 (GAP 2):

• Design Spec 기준: 답변이 있는 필드는 삭제 불가.
  • 답변 있는 필드: [삭제] disabled + Tooltip "답변이 있는 필드는 삭제할 수 없습니다."
  • 답변 없는 필드: 인라인 확인 -> "삭제된 필드는 목록에서 숨겨지지만 기존 답변은 보존됩니다. 삭제하시겠어요?"
• hasAnswers 필드를 FormFieldDefinition 타입에 포함하여 삭제 가능 여부를 프론트에서 사전 판단.
• PO 확인 필요: PRD(Soft delete, 답변 있어도 삭제 가능) vs Design Spec(답변 있으면 삭제 불가). 현재 Design Spec 기준으로 구현하되, Soft delete 전환이 필요하면 hasAnswers 체크 조건만 제거하면 된다.

저장 로직 (GAP - Form Builder 저장 실패):

• [저장] 클릭 -> 변경된 필드 diff 계산 -> 각 변경 유형별 API 순차 호출
  • 추가된 필드: POST /form-fields
  • 수정된 필드: PATCH /form-fields/:id
  • 삭제된 필드: DELETE /form-fields/:id
  • 순서 변경: PATCH /form-fields/reorder (순서 일괄 업데이트)
• Partial commit 처리: 순차 호출 중 일부 실패 시:
  • 성공한 요청은 유지 (롤백하지 않음)
  • 실패한 건만 toast.error("일부 필드 저장에 실패했습니다. 실패한 항목을 확인 후 다시 저장해주세요.")
  • 실패한 필드는 로컬 상태에서 isDirty 유지 -> 재시도 가능
  • 성공한 필드는 서버와 동기화 (invalidateQueries)
• 전체 성공: isDirty = false + toast.success("저장되었습니다.")

이탈 방지:

• isDirty 상태에서 페이지 이탈(라우트 변경) 시: beforeunload 이벤트 + router.events 가드
• 문구: "저장되지 않은 변경 사항이 있습니다. 나가시겠어요?"

빈 상태:

• 필드 0개: 아이콘 + "아직 추가된 커스텀 필드가 없습니다." + [+ 필드 추가] CTA

Wave 8: 참석 옵션 관리 (FR-7-A) -- 조건부

PR 6에 포함 (Form Builder와 같은 섹션) PO Scope 확정 대기 (GAP 11): PO 확인 후 제외될 수 있음. 제외 시 Wave 8 전체 skip.

AttendanceOptionManager 구현:

• Form Builder 섹션 상단에 위치 (ADMIN 전용)
• 현재 옵션 목록: type 배지 (FULL=info / PARTIAL=outline) + label + [삭제]
• [+ 옵션 추가]: 인라인 또는 간단 모달 -- type(Select: 풀참석/옵션참여) + label(InputField)
• 삭제 시 등록자 존재하면: toast.error("N명이 선택한 옵션은 삭제할 수 없습니다.")

Wave 9: 통합 + 접근성 + 최종 점검

PR 7: feat: 등록 관리 접근성 및 통합 점검 예상 ~150줄

접근성 체크리스트 (Design Spec SS6):

• 납부 배지 토글: role="button" + aria-label
• 체크박스 헤더: aria-label="전체 선택"
• SidePanel: role="dialog" + aria-modal="true" + aria-labelledby
• 드래그 핸들: aria-label="순서 변경 핸들" + 키보드 대체 수단
• 커스텀 필드 입력: aria-required={isRequired} + htmlFor/id
• 스켈레톤: aria-busy="true" + aria-live="polite"

6. PR 전략

병렬 가능: PR 1 <-> PR 2 동시 작업 가능. PR 5 <-> PR 6 도 PR 4 이후 병렬 작업 가능.

의존 관계 다이어그램:

PR 1 (W1: API) -----> PR 3 (W3: 메인) -----> PR 4 (W4+5: 상세) --+-> PR 5 (W6: 패널)
                                                                   |
PR 2 (W2: SidePanel) -----------------------------------------+   +-> PR 6 (W7+8: Form Builder)
                                                               |
                                                               +-> PR 5 (W6: 패널)

                                                     PR 5 + PR 6 -> PR 7 (W9: 통합)

7. BE 의존성 체크리스트

FE 선행 개발이 가능하도록 MSW mock을 세팅하되, 실제 연동 전 아래 API가 완료되어야 한다.

8. 미결 사항

BE 확인 필요

PO 확인 필요

9. 테스트 전략

단위 테스트 (Vitest)

• 유틸 함수: formatParticipant, csvDownload, D-day 계산
• 커스텀 훅: useTogglePayment 낙관적 업데이트 로직

컴포넌트 테스트 (Vitest + RTL)

• PaymentBadge: ADMIN/STAFF 역할별 렌더링 + 클릭 동작
• CustomFieldInput: 6가지 fieldType별 렌더링
• MissionEnrollmentCard: 상태별 컬러 바, D-day 배지, 프로그레스 바
• SidePanel: 열기/닫기 애니메이션, Esc 키, dirty guard
• ProgressBar: className 전달에 따른 스타일 분기

통합 테스트 (Playwright -- 추후)

• 메인 -> 상세 -> 패널 열기 -> 수정 -> 저장 -> 목록 갱신 흐름
• 납부 토글 + 현황 카드 연동
• Form Builder 필드 추가/삭제/순서 변경/저장
• CSV 다운로드 성공/실패 흐름

10. Definition of Done

• TypeScript 에러 없음 (pnpm type-check)
• ESLint 통과 (pnpm lint:all)
• 핵심 유틸/훅 단위 테스트 작성
• 접근성 기본 체크 (SS6 체크리스트)
• 빌드 정상 (pnpm --filter missionary-admin build)
• Design Spec 엣지 케이스 처리 확인 (SS7 체크리스트)
• 기존 UserEditPanel regression 없음 (SidePanel 마이그레이션 후)
• CSV 다운로드 로딩/에러 상태 동작 확인
• Form Builder 저장 실패 시 partial commit 처리 동작 확인