PRD: 등록 관리 페이지

변경 이력

1. 문제 정의 (Problem Statement)

해결하려는 문제

35차 군선교 등록자 관리 화면이 없다. 현재 Participation 테이블에 등록 데이터가 존재하지만, 관리자가 이를 조회·수정할 수 있는 관리 UI가 없어 운영이 불가능한 상태다.

또한 군선교 운영에 필요한 추가 등록 정보(팀 소속, 참석 일정, 유저 기수, 과거 참여 여부, 대학생 여부, 주소지)가 현재 스키마에 없어 수집 자체가 불가능하다.

현재 상태 (As-Is)

• Participation 테이블: 기본 필드(이름, 생년월일, 신청비용, 납부여부, 주민번호, 자차여부)만 존재
• 백엔드 API는 구현되어 있으나 관리자 화면이 없음
• 군선교 운영에 필요한 팀 소속, 유저 기수, 참석 일정 등의 필드 누락
• 입금 확인, 정원 현황 파악 등 핵심 운영 업무를 시스템으로 처리 불가

목표 상태 (To-Be)

• 독립 등록 관리 페이지(/enrollment)에서 모든 상태 선교의 등록자를 관리
• 관리자(ADMIN/STAFF)가 특정 차수의 등록자를 목록으로 조회
• 총 등록자 수, 정원 대비 현황, 입금 현황을 한눈에 파악
• 등록자 정보 수정(납부 여부 포함)
• 군선교 운영에 필요한 추가 필드 수집
• 선교별 커스텀 폼 필드를 관리자가 동적으로 구성 (Form Builder)

2. 사용자 및 권한 (Users & Permissions)

등록 관리 페이지 자체는 ADMIN/STAFF 전용이다. 일반 USER는 접근 불가.

3. 도메인 모델 (Data Model)

3-1. 용어 구분: 차수 vs 기수

이 두 개념은 완전히 다르며 혼동하지 않는다.

3-2. Participation 스키마 변경

기존 필드는 유지하고, 군선교 운영에 필요한 필드를 추가한다.

기존 필드 (변경 없음)

신규 추가 필드

v1.2 변경: address(주소지) 고정 필드 제거. 주소지가 필요한 경우 Form Builder 커스텀 필드(§ 3-5)로 수집한다.

v1.3 변경: attendanceType: Enum 제거 → attendanceOptionId: String FK로 교체. 참석 옵션은 선교별로 어드민이 직접 정의한다 (§ 3-3).

3-3. MissionaryAttendanceOption (참석 옵션 — v1.3 확정)

확정 구조: B안 — 차수별 참석 옵션 설정 테이블.

어드민이 선교별로 참석 옵션을 정의한다. AttendanceType(FULL/PARTIAL)은 통계 집계용 기준 분류로 남기고, 실제 표시 라벨은 선교마다 다르게 설정할 수 있다.

MissionaryAttendanceOption 모델

AttendanceType Enum (확정)

enum AttendanceType {
  FULL      // 풀참석 — FR-1 현황 집계에서 "풀참석 인원"으로 카운트
  PARTIAL   // 옵션참여 — FR-1 현황 집계에서 "옵션참여 인원"으로 카운트
}

운영 예시

관리 시점

• 어드민이 선교 생성/수정 시 또는 등록 관리 페이지에서 참석 옵션을 구성
• 옵션은 등록 시작 전에 설정하는 것을 권장. 등록 중 추가는 가능하나 기존 등록자에게 소급 변경 불가.
• 참석 옵션 삭제: 해당 옵션을 선택한 등록자가 있으면 삭제 불가 (API에서 400 반환)

3-4. 관계

Missionary (차수) ──1:N──▶ Participation (등록)
Missionary (차수) ──1:N──▶ MissionaryAttendanceOption (참석 옵션)  ← 신규 (v1.3)
Missionary (차수) ──1:N──▶ MissionaryFormField (커스텀 폼 필드 정의)  ← 신규 (v1.2)
User ──1:N──▶ Participation
Team ──1:N──▶ Participation (optional)
MissionaryAttendanceOption ──1:N──▶ Participation (attendanceOptionId FK)  ← 신규 (v1.3)
Participation ──1:N──▶ ParticipationFormAnswer (커스텀 필드 답변)  ← 신규 (v1.2)
MissionaryFormField ──1:N──▶ ParticipationFormAnswer

3-5. Form Builder 신규 모델

MissionaryFormField (선교별 커스텀 폼 필드 정의)

어드민이 선교별로 동적으로 추가하는 커스텀 필드 정의.

FormFieldType Enum (확정):

enum FormFieldType {
  TEXT        // 단문 텍스트
  TEXTAREA    // 장문 텍스트
  NUMBER      // 숫자
  BOOLEAN     // 예/아니오 (체크박스)
  SELECT      // 단일 선택
  DATE        // 날짜
}

ParticipationFormAnswer (커스텀 필드 답변)

등록자가 커스텀 필드에 입력한 값.

설계 노트: 모든 답변을 String으로 저장하고 fieldType에 따라 역직렬화한다. Boolean은 "true"/"false", Number는 숫자 문자열, Date는 ISO 8601 문자열.

Form Builder 운영 규칙

4. 기능 요구사항 (Functional Requirements)

FR-0: 등록 관리 메인 페이지 (/enrollment)

등록 관리 페이지는 선교 상세 탭이 아닌 독립 페이지로 운영된다. 두 섹션으로 구성된다.

페이지 헤더 통계 (v3 목업)

• 위치: 페이지 상단 우측
• 표시 항목: "모집 중 N건 | 총 신청 N명"
  • 모집 중 N건: status === 'ENROLLMENT_OPENED' 선교 수
  • 총 신청 N명: 모집 중 선교 전체 currentParticipantCount 합산
• 데이터 소스: GET /missionaries 응답 클라이언트 집계 — 별도 API 없음

Section A — 모집 중 선교 (카드)

• 표시 조건: status === 'ENROLLMENT_OPENED'인 선교
• 표시 수: 모집 종료일 임박순 최대 3개
  • 0개: 카드 영역 없음(빈 상태 표시)
  • 1~2개: 해당 수만큼만 표시
  • 3개: 3개 표시
  • 4개 이상: 상위 3개만 카드, 나머지는 Section B 테이블에 포함
• 정렬 기준: 모집 종료일 오름차순 (동일 종료일 시 등록률 낮은 순 보조 정렬)
• 카드 클릭: /enrollment/[missionaryId] 이동 (등록자 목록, 현황 요약, CSV 등 전체 기능)
• 빈 상태: "현재 모집 중인 선교가 없습니다." + [선교 관리로 이동 →] 링크 (/missions)

Section B — 전체 선교 통합 테이블

• 표시 조건: 전체 선교 (모집 중 포함, Section A 표시 여부 무관). 모집 중 4개 이상인 경우 Section A에 미표시된 선교도 테이블에 포함
• 레이아웃: 테이블 (선교명, 카테고리, 기간, 상태, 총 등록자 수, 납부 완료 수)
• 검색/필터: 테이블 내부 헤더에 위치 (연계지 관리 패턴)
  • 상태 필터 칩: [전체★] [모집 중] [모집 마감] [종료] — 기본값: 전체
  • 선교명 검색: 테이블 헤더 내 검색 입력창
• 행 클릭: /enrollment/[missionaryId] 이동
• 접근 가능 기능: 등록자 목록 조회, 납부 여부 수정, 납부 일괄 승인(ADMIN), CSV 다운로드
• 빈 상태: "선교가 없습니다." (필터 적용 시: "조건에 맞는 선교가 없습니다.")

FR-1: 등록 현황 요약

• 설명: 페이지 상단에 등록 현황 요약 카드를 표시한다.
• 사용자: ADMIN, STAFF
• 표시 항목:
  • 총 등록자 수 / 정원 (예: 23 / 50명)
  • 정원 달성률 프로그레스 바
  • 납부 완료 인원 / 미납 인원
  • 풀참석 인원 / 옵션참여 인원
• API: GET /participations/enrollment-summary/:missionaryId
  • 응답: { totalParticipants, maxParticipants, paidCount, unpaidCount, fullAttendanceCount, partialAttendanceCount }
  • 목록 조회(GET /participations)와 분리 — 요약 통계는 별도 집계 쿼리로 성능 최적화

FR-2: 등록자 목록 조회

• 설명: 특정 차수의 등록자 전체를 테이블로 표시한다.

• 사용자: ADMIN, STAFF

• 필요 API: GET /participations?missionaryId=&isPaid=&query= (기존 + 검색 파라미터 추가)

• 표시 컬럼:

  • 등록일시 (createdAt)
  • 이름 (name)
  • 생년월일 (birthDate)
  • 소속 (affiliation)
  • 참석 일정 (attendanceOption.label 표시, type별 색상 구분)
  • 기수 (cohort)
  • 납부 여부 (isPaid: 뱃지)
  • 팀 (participation.team.teamName — 미배정 시 "미배정" 표시, 읽기 전용)
  • 커스텀 필드 컬럼 (선교별 MissionaryFormField 목록 기반으로 동적 렌더링)

  커스텀 컬럼 표시 정책: 커스텀 필드가 많을 경우 테이블 가로 스크롤 허용. 테이블 컬럼은 최대 12개를 기준으로 하며, 초과 시 상세 패널에서만 확인 가능.

• 필터:

  • 납부 여부: 전체 / 납부완료 / 미납
  • 참석 일정: 전체 / 풀참석(FULL) / 옵션참여(PARTIAL) — attendanceOption.type 기준

• 검색: 이름(name) 기준 클라이언트 사이드 검색

• 정렬: 등록일시 내림차순 기본 (최신 등록 먼저)

• 페이지네이션: 페이지 크기 20건, 서버 사이드 limit/offset

FR-3: 납부 여부 빠른 토글

• 설명: 목록에서 납부 여부를 행 단위로 즉시 토글할 수 있다.
• 사용자: ADMIN만
• 동작: isPaid 뱃지 클릭 → 즉시 PATCH /participations/:id 호출 (낙관적 업데이트)
• 피드백: 성공 시 뱃지 상태 변경 + 현황 요약 카드 자동 갱신. 실패 시 원상 복구 + 에러 Toast.

FR-4: 납부 일괄 승인

• 설명: 여러 등록자를 선택하여 납부 완료를 일괄 처리한다.
• 사용자: ADMIN만
• API: PUT /participations/approve (기존 존재)
• 동작: 체크박스 다중 선택 → "납부 승인" 버튼 활성화 → 확인 다이얼로그 → API 호출
• 확인 문구: "N명의 납부를 승인합니다."

FR-5: 등록자 상세 조회 및 수정

• 설명: 등록자 행 클릭 시 상세 패널(슬라이드 오버)에서 정보를 확인·수정한다.
• 사용자: ADMIN (수정), STAFF (조회만)
• 조회 API: GET /participations/:id
• 수정 API: PATCH /participations/:id
• 수정 가능 필드:
  • 이름, 생년월일
  • 소속(affiliation), 참석 일정(attendanceOptionId — 해당 선교의 옵션 중 선택), 기수(cohort)
  • 과거 참여 여부, 대학생 여부
  • 납부 여부 (isPaid)
  • 커스텀 필드 답변 (ParticipationFormAnswer) — fieldType에 맞는 입력 컴포넌트로 렌더링
• 읽기 전용 필드: 등록일시, 신청 선교, 신청자 계정 (userId), 팀 (team.teamName — 팀 배정 후 표시, 미배정 시 "미배정")
• 커스텀 필드 미답변 처리: 등록 후 추가된 필드는 답변이 없음(null). 패널에서 빈 입력 필드로 표시하며 ADMIN이 직접 입력 가능.

FR-6: CSV 다운로드

• 설명: 현재 차수의 등록자 전체를 CSV로 다운로드한다.
• 사용자: ADMIN, STAFF
• API: GET /participations/download/:missionaryId (기존 존재 — 신규 필드 컬럼 추가 필요)
• 포함 컬럼: 등록일시, 이름, 생년월일, 소속(affiliation), 참석일정(attendanceOption.label), 기수(cohort), 납부여부, 과거참여, 대학생여부 + 커스텀 필드 컬럼(동적 추가)

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

등록 상세 페이지에 커스텀 폼 필드 관리(FR-7-B) 기능이 위치한다.

FR-7-A: 참석 옵션 관리 — 이번 Scope 제외 (v1.12)

v1.12 결정: 참석 옵션 관리 UI를 등록 상세 페이지에서 제거한다.

• 참석 옵션 정보(label)는 등록자 슬라이드 패널(FR-5)에서 읽기 전용으로만 표시한다.
• BE API(GET/POST/PATCH/DELETE /missionaries/:id/attendance-options)는 구현 상태로 유지한다.
• 참석 옵션 CRUD는 향후 선교 생성/수정 페이지 또는 별도 관리 화면에서 처리한다.

FR-7-B: 커스텀 폼 필드 관리

• 설명: ADMIN이 선교별 커스텀 폼 필드를 동적으로 추가·삭제·순서 변경할 수 있다.
• 사용자: ADMIN만
• 진입 경로: /enrollment/[missionaryId] → 폼 필드 관리 섹션
• UI 방식: Google Forms 스타일 인라인 WYSIWYG
  • 각 필드가 독립 카드로 표시되며, 프리뷰와 설정을 겸용
  • 카드 클릭 시 인라인 확장 편집 (별도 모달 없음)
  • 미확장 상태: 필드 프리뷰 표시 (label, fieldType 뱃지, 필수 여부)
  • 확장 상태: label·placeholder 편집, isRequired 토글, options 목록 편집(SELECT 타입)
  • 드래그로 순서 변경 (확장 상태에서도 가능)
  • 상단 sticky 툴바: 미저장 변경 사항 표시("저장되지 않은 변경 사항이 있습니다") + [미리보기] + [저장] 버튼
  • 저장은 명시적 액션(툴바 [저장]) — 자동 저장 없음
• API:
  • GET /missionaries/:id/form-fields — 필드 목록 조회 (각 필드에 hasAnswers: boolean 포함)
  • POST /missionaries/:id/form-fields — 필드 추가
  • PATCH /missionaries/:id/form-fields/:fieldId — 필드 수정 (label, isRequired, order, options)
  • PATCH /missionaries/:id/form-fields/reorder — 필드 순서 일괄 변경 (body: { items: [{ id, order }] })
  • DELETE /missionaries/:id/form-fields/:fieldId — 필드 삭제 (Soft delete)
• 필드 속성:
  • fieldType (TEXT / TEXTAREA / NUMBER / BOOLEAN / SELECT / DATE)
  • label (필수)
  • placeholder (선택)
  • isRequired (등록 시 필수 여부)
  • options (SELECT 타입 시 선택지 목록)
• 타이밍: 선교 상태와 무관하게 언제든지 추가/삭제 가능
• 삭제 정책: Soft delete. 삭제된 필드는 목록에서 숨겨지지만 기존 답변(ParticipationFormAnswer) 보존.
• 삭제 경고: hasAnswers === true인 필드 삭제 시 확인 다이얼로그 표시. 문구: "이 필드에 입력된 답변이 있습니다. 삭제하면 목록에서 숨겨지지만 기존 답변은 보존됩니다. 계속하시겠습니까?"
• 피드백: 저장 성공 시 툴바 미저장 상태 초기화 + 성공 Toast. 실패 시 에러 Toast.
• 엣지 케이스:
  • 등록자 있는 상태에서 필드 추가: 허용. 기존 등록자는 미답변 상태로 표시.
  • 필수 필드 추가: 기존 등록자 소급 미적용. 신규 등록자에게만 필수.
  • 미저장 상태에서 페이지 이탈: "저장되지 않은 변경 사항이 있습니다. 나가시겠습니까?" 확인 다이얼로그.

5. 기술 스펙 (Technical Specs)

기술 구현 상세는 별도 문서를 참조한다.

• 프론트엔드: ./fe-plan.md
• 백엔드: ./be-plan.md

6. 영향 범위 (Impact Scope)

6-1. Backend 변경 범위

6-2. Frontend 변경 범위

7. 화면 구성 (UI/UX)

UI 상세 명세: ./ui-spec.md

설계 결정사항

페이지 구성

/enrollment  ← 등록 관리 메인 페이지 (FR-0)
├── [Section A] 모집 중 선교 — 마감 임박순 최대 3개 카드
│   └── 카드 클릭 → /enrollment/[missionaryId]
└── [Section B] 전체 선교 통합 테이블 (상태 필터 칩 + 테이블 내부 검색)
    └── 행 클릭 → /enrollment/[missionaryId]

/enrollment/[missionaryId]  ← 선교별 등록 관리 상세
├── 관리 설정 섹션 (FR-7) ← ADMIN 전용
│   └── 커스텀 폼 필드 관리 (FR-7-B)
│       ├── 필드 카드 목록 (Google Forms 스타일 인라인 WYSIWYG, 드래그 순서 변경)
│       ├── [+ 필드 추가] 버튼
│       └── sticky 툴바: 미저장 상태 표시 + [미리보기] + [저장]
├── 등록 현황 요약 카드 (FR-1)
│   ├── 총 등록자 / 정원
│   ├── 납부완료 / 미납
│   └── 풀참석 / 옵션참여
├── 도구 모음
│   ├── 납부 여부 필터
│   ├── 참석 일정 필터
│   ├── 이름 검색
│   ├── [납부 승인] 버튼 (다중선택 시 활성)
│   └── [CSV 다운로드] 버튼
└── 등록자 테이블 (FR-2)
    ├── 고정 컬럼: 등록일시, 이름, 생년월일, 소속, 참석일정, 기수, 납부여부
    ├── 커스텀 필드 컬럼 (동적, 가로 스크롤)
    └── 행 클릭 → 슬라이드 오버 패널 (FR-5)
        ├── 고정 필드 표시/수정
        ├── 커스텀 필드 답변 표시/수정
        └── 이전/다음 네비게이션 (현재 페이지 목록 기준, URL searchParams 기반)

빈 상태 (Empty States)

• 등록자 없음: "아직 등록된 참가자가 없습니다." + Users 아이콘
• 검색 결과 없음: "검색 결과가 없습니다." + 검색어 초기화 버튼

에러 상태 (Error States)

• 목록 로드 실패: "데이터를 불러오지 못했습니다." + [다시 시도] 버튼
• 수정/납부 승인 실패: 에러 Toast (낙관적 업데이트 롤백 포함)

엣지 케이스 처리

• 이탈 방지: 수정 패널 dirty 상태에서 닫기 시 "저장하지 않은 변경사항이 있습니다." 확인 모달
• 정원 초과: 등록자 수가 maximumParticipantCount 초과 시 현황 카드에 경고 뱃지 표시
• 정원 미설정: maximumParticipantCount가 null이면 정원 표시 없이 총 등록자 수만 표시
• 커스텀 필드 없음: 폼 필드 관리 섹션에 빈 상태 UI — "아직 추가된 커스텀 필드가 없습니다." + [+ 필드 추가] CTA
• 커스텀 필드 미답변: 등록 후 추가된 필드는 상세 패널에서 빈 값으로 표시 ("미입력" 레이블)
• SELECT 필드 옵션 없음: options 빈 배열인 SELECT 필드 저장 시 "선택지를 1개 이상 입력해주세요." 검증 에러

8. Scope 밖 (Out of Scope)

9. 성공 지표 (Success Metrics)

10. 기술 의존성 (Dependencies)