[FEAT] 관리자 대시보드 통계 조회 API 검토

[exijn]

배경

관리자/교직원/개발자 대시보드 화면(Figma node 942:21779/942:20791/942:21970)이 PR #81로 이미 구현되어 있으나, KPI 카드·표·알림 데이터가 전부 하드코딩된 Mock이다 — 실제 API 연동이 전혀 시도되지 않았다.

Client 근거

• GETI-Client-V1(develop, 078388a) src/views/admin-dashboard/model/mock.ts — DASHBOARD_CONTENT 전체가 정적 상수(관리자/교직원/개발자 3종).
• src/views/admin-dashboard/ui/AdminDashboardPage.tsx — content: DashboardContent를 Props로만 받아 그대로 렌더링할 뿐, 어떤 Query Hook도 호출하지 않는다.

Widget별 필요 Metric (Client Mock 기준, 추측 아님)

관리자: 가입 승인 대기(교직원) 건수 · 전체 지원(서) 건수 · 공고 상세(모집/마감/비공개) 건수 · 프로그램 상태(진행/예정/종료) 건수 · 미답변 문의 건수 · 전체 지원 처리 현황 표(제출완료/검토중/수정요청 건수·비율) · 최근 운영 상태(공고·프로그램·미답변 문의 요약).

교직원: 신규 지원자 건수 · 수정요청 지원서 건수 · 기업 전달 대기 건수 · 진행 중 프로그램 건수 · 포트폴리오 미제출(기한 경과) 건수 · 담당 공고 현황 표(공고별 지원자·처리대기·상태) · 최근 알림 3종.

개발자: 정상 시스템 건수 · Discord 전송 실패 건수 · 정기 작업 실패 건수 · 외부 공고 수집 실패 건수 · 미처리 오류 문의 건수 · 최근 실패 내역 표 · 최근 운영 알림.

확정 계약

기준 시각/기간을 아래와 같이 확정한다(Client Mock의 "최근 7일" 표기는 아래 값으로 대체한다 — CLIENT_CONTRACT_ALIGNMENT_REQUIRED: 화면 문구를 실제 값에 맞게 정리해야 한다).

Metric	기준	상태
신규 지원자	최근 3일(JobApplication 생성 시각 기준)	CONFIRMED
Discord 전송 실패	최근 24시간	REUSE_EXISTING_API — GET /api/v1/admin/discord-deliveries?status=FAILED(Issue #206/PR #213, Merge 완료)의 totalElements에 기간 Filter만 추가하면 된다
정기 작업 실패	최근 24시간	BLOCKED — #227(Scheduler 통합 조회 계약)이 먼저 확정/구현되어야 한다
외부 공고 수집 실패	최근 24시간	REUSE_EXISTING_API — 기존 Collector 실행 이력 조회 재사용(Issue #227과 조회 계층을 공유할 수 있는지 구현 시 확인)
가입 승인 대기	현재 값	REUSE_EXISTING_API — GET /api/v1/admin/members/search?status=PENDING&role=TEACHER의 totalElements(Issue #183/PR #216)
공고/프로그램/문의 상태별 건수	현재 값	REUSE_EXISTING_API — 각 목록 Endpoint의 상태별 totalElements 반복 조회
지원 처리 현황(상태별)	현재 값	REUSE_EXISTING_API — JobApplicationAdminServiceImpl.list의 기존 status Filter
기업 전달 대기	-	EXCLUDE — docs/application/application-domain-plan.md(§1.1)가 "기업 전달·전달완료 상태 구현 안 함"이라 명시했고 JobApplicationStatus.FORWARDED는 죽은 값으로 남아 있다. 실제 Lifecycle이 구현되기 전까지 이 Metric은 Dashboard에서 제외한다
포트폴리오 미제출(기한 경과)	-	BLOCKED — Portfolio Phase 2 Scope ①(학생 제출, PR #212)은 Merge됐지만 Issue #204가 다루는 관리자 제출 현황/일괄 다운로드(Scope ②)는 아직 OPEN이다. Phase 2가 완료되기 전에는 실제 Metric으로 구현하지 않는다
정상 시스템	실제 Health/Operation 상태 기준	BLOCKED — #227이 먼저 확정되어야 "정상"의 판정 기준(각 Task 상태 조합)이 생긴다

기존 API totalElements 조합으로 충분히 계산 가능한 Metric은 신규 Aggregate API를 만들지 않는다. 새 Aggregate가 필요한 항목(BLOCKED로 표시된 것들)만 해당 선행 Issue가 완료된 뒤 범위를 좁혀 후속 Issue로 구현한다.

요구사항

• 위 표의 CONFIRMED/REUSE_EXISTING_API 항목부터 Client가 기존 API 조합으로 연동한다(신규 Backend 작업 없이 가능).
• BLOCKED 항목은 선행 Issue([FEAT] 관리자 Scheduler 상태 조회·수동 재시도 계약 확정 #227, [FEAT] Portfolio Phase 2 - 학생 제출·관리자 제출 현황·일괄 다운로드 API 구현 #204) 완료 후 별도 후속 Issue로 좁혀 진행한다.
• EXCLUDE 항목(기업 전달 대기)은 Client Mock/화면에서 제거하거나 "미지원" 표시로 대체한다.

제외 범위

• Discord 전달 목록([FEAT] Discord 전달 내역 전체 목록 조회 API(Admin) #206/PR [FEAT] Discord 전달 내역 전체 목록 조회 Admin API 구현 #213, Merge 완료)과 Portfolio 제출 현황([FEAT] Portfolio Phase 2 - 학생 제출·관리자 제출 현황·일괄 다운로드 API 구현 #204, PR [FEAT] 포트폴리오 학생 제출 API 구현 (Phase 2 - Scope ①) #212 일부 Merge)은 각각 해당 Issue의 결과를 그대로 재사용하며 이 Issue가 재구현하지 않는다.
• Scheduler 통합 조회([FEAT] 관리자 Scheduler 상태 조회·수동 재시도 계약 확정 #227)는 이 Issue가 아니라 #227에서 확정한다.

Architecture

Cross-Domain(Member/Job/Program/Inquiry/Application/Notification/Discord/Scheduler/Collector) 성격이라 특정 Domain 하나에 두지 않는다. REUSE_EXISTING_API 항목은 기존 Endpoint를 Client가 여러 번 호출하는 방식으로 충분하므로 이 Issue에서 신규 Aggregate Query Port를 도입하지 않는다.

Performance

REUSE_EXISTING_API 항목은 Client가 필요한 만큼만 개별 호출하면 되므로 서버 Aggregate가 필요하지 않다. BLOCKED 항목이 실제 구현될 때 호출 수가 문제가 되면 그 시점에 Aggregate 필요성을 재검토한다.

Security

Role별(관리자/교직원/개발자) 대시보드가 서로 다른 Metric을 요구하므로, 각 REUSE_EXISTING_API 호출도 기존 Endpoint의 Role 정책을 그대로 따른다(별도 확대 없음).

Test

이 Issue 자체는 신규 Backend 코드를 추가하지 않으므로 별도 Test가 없다. BLOCKED 항목이 후속 Issue로 구현될 때 해당 Issue에서 Test를 추가한다.

완료 조건

• CONFIRMED/REUSE_EXISTING_API로 분류된 Metric에 대해 Client가 Mock 없이 실제 API로 표시할 수 있는 경로가 명시된다
• BLOCKED/EXCLUDE 항목의 후속 계획(선행 Issue, 제외 사유)이 명확히 기록된다

Related

• Issue [FEAT] 관리자 회원 목록·상세 조회 및 역할·계정 상태 변경 API #183(PR [FEAT] 관리자 회원 목록·상세 조회 및 역할·계정 상태 변경 API #216) — 가입 승인 대기 Metric 재사용
• Issue [FEAT] 지원자 관리 목록 필터 확장 #181(PR feat: 지원자 관리 목록 필터 확장 #211) — 지원자 목록 Filter
• Issue [FEAT] Discord 전달 내역 전체 목록 조회 API(Admin) #206(PR [FEAT] Discord 전달 내역 전체 목록 조회 Admin API 구현 #213, Merge 완료) — Discord 실패 Metric 재사용
• Issue [FEAT] Portfolio Phase 2 - 학생 제출·관리자 제출 현황·일괄 다운로드 API 구현 #204(PR [FEAT] 포트폴리오 학생 제출 API 구현 (Phase 2 - Scope ①) #212 일부 Merge, OPEN) — 포트폴리오 미제출 Metric BLOCKED 사유
• Issue [FEAT] 관리자 Scheduler 상태 조회·수동 재시도 계약 확정 #227 — 정기 작업 실패/정상 시스템 Metric BLOCKED 사유

Owner 후보

• Cross-Domain이라 단일 기능 구현자가 없다.
• Candidate(MEDIUM): Fresh-Banana — Application/Export/Member Admin 등 최근 가장 넓은 범위를 구현한 이력
• Confidence: MEDIUM (자동 Assign 금지, Assignee 비워둠)

[exijn]

최신 재-Audit 결과 (2026-08-26)

기준 SHA:

• Backend origin/develop: ce6e1aef1a7e6d3ccb6a89ebfb928e32f70fb645
• Frontend origin/develop: 49166b06964ed8b7bfa99de4cc24a6ceb0200fc9

REUSE_EXISTING_API

• 가입 승인 대기: GET /api/v1/admin/members/search?status=PENDING&role=TEACHER의 totalElements 재사용 가능
• 전체 지원/상태별 지원서: GET /api/v1/admin/job-applications의 status filter와 totalElements 재사용 가능
• 프로그램 상태: GET /api/v1/programs의 status/openOnly filter와 totalElements 재사용 가능
• 교직원 수정요청 지원서: status=REVISION_REQUESTED 재사용 가능
• 진행 중 프로그램: 기존 program 목록 조합 가능하나 Client의 상태 라벨은 별도 정렬 필요
• 최근 알림: GET /api/v1/notifications 재사용 가능
• Scheduler 실패: GET /api/v1/admin/system/jobs?status=FAILED&startAt&endAt
• Collector 실패: GET /api/v1/admin/collection-runs?status=FAILED&startAt&endAt
• 공개 공고 PUBLISHED/CLOSED 집계: GET /api/v1/jobs의 totalElements 범위에서 재사용 가능

MINIMAL_BACKEND_EXTENSION

• 최근 3일 신규 지원자: [FEAT] 관리자 지원서 목록 생성일 범위 필터 추가 #279 → PR #282
  • createdFrom 포함, createdTo 미포함, createdAt 기준
• Discord 실패 최근 24시간: [FEAT] Discord 전달 내역 기간 필터 추가 #280 → PR #283
  • startAt 포함, endAt 미포함, lastAttemptAt 기준
• 미답변 문의/오류 문의: [FEAT] 관리자 문의 답변 여부 필터 추가 #281 → PR #284
  • answered=false는 answeredAt IS NULL, inquiryType=ERROR와 조합 가능

EXCLUDE

• 기업 전달 대기: Backend의 FORWARDED enum은 실제 transition/service 사용이 없는 dead lifecycle이므로 구현하지 않음
• Dashboard 전용 Aggregate API, global permitAll/Security [FIX] OAuth 완료 후 전역 permitAll 해제 및 HTTP 인가 복구 #162 범위, Migration은 추가하지 않음

BLOCKED / PRODUCT DECISION_REQUIRED

• 포트폴리오 미제출: #204는 학생 제출만 완료되었고 관리자 submissions 목록/미제출 판정 API가 없어 Blocked
• 정상 시스템 수: [FEAT] 관리자 Scheduler 상태 조회·수동 재시도 계약 확정 #227 구현에는 SUCCESS/FAILED/NO_HISTORY 등 실행 상태는 있으나 “정상” 산정 기준이 확정되지 않음
• 담당 공고 현황: Client Mock의 담당자 Widget과 Backend 목록 계약이 일치하지 않아 담당자 모델/API 결정 필요
• 공고 모집중/마감/비공개: Client Mock의 비공개 라벨과 현재 공개 Job API(PUBLISHED/CLOSED)의 범위가 다름

CLIENT_MISMATCH

최신 Client develop의 관리자 Dashboard는 정적 Mock을 사용하며 Query/API Hook, loading/error state가 연결되어 있지 않습니다. 또한:

• 신규 지원자 문구가 최근 7일로 남아 있으나 요구 기준은 최근 3일
• 기업 전달 대기 Widget과 FORWARDED 표현 존재
• Program 상태 모델이 Backend DRAFT/PUBLISHED/CLOSED/DELETED와 불일치
• Scheduler Mock에 Backend OperationJobType에 없는 privacy cleanup과 다른 상태 모델 존재
• Portfolio 관리자 화면은 Mock이며 [FEAT] Portfolio Phase 2 - 학생 제출·관리자 제출 현황·일괄 다운로드 API 구현 #204 관리자 API가 없음

따라서 #219는 Backend Gap PR이 Merge되고 Client가 기존 API와 #282~#284를 연동하기 전에는 완료/종료할 수 없습니다.

[exijn]

최신 재-Audit 결과 (2026-08-28)

Baseline

• Server origin/develop: 30f3a3bb00d00db0e7916c1b8682823c6f41602d (PR [FEAT] 관리자 지원서 상태별 건수 조회 API 구현 #290 포함)
• Client origin/develop: 7565b1451589d06f6d9b4940f997e14baf28d1da (Client PR [FEAT] 지원자 관리 목록 필터 확장 #181 포함)
• Server/Client OPEN PR: 0건

이번 Audit은 최신 Server/Client의 실제 코드·Hook·Issue/PR 상태를 대조했다. 결론은 확정된 신규 Server Gap 없음, Client 미연동과 Product Decision 항목 잔존이다. Dashboard 전용 Mega/Aggregate API는 제안하지 않는다.

이미 해결된 선행 항목

• 지원서 상태별 건수: Server PR [FEAT] 관리자 지원서 상태별 건수 조회 API 구현 #290 Merge, GET /api/v1/admin/job-applications/status-counts; Client PR #181에서 관리자 Dashboard에 이미 연결됨.
• 최근 3일 신규 지원자용 생성일 필터: Server PR [FEAT] 지원서 생성일 범위 필터 추가 #282 Merge, 기존 지원서 목록의 createdFrom/createdTo.
• Discord 최근 24시간 실패용 기간 필터: Server PR [FEAT] Discord 전달 내역 기간 필터 추가 #283 Merge, GET /api/v1/admin/discord-deliveries의 status/startAt/endAt.
• 문의 답변 여부 필터: Server PR [FEAT] 문의 답변 여부 필터 추가 #284 Merge, GET /api/v1/admin/inquiries의 answered.
• Portfolio 관리자 제출 현황/미제출 판정: Server PR [FEAT] 관리자 포트폴리오 제출 현황·일괄 다운로드 구현 #285 Merge, GET /api/v1/portfolio-requests 및 GET /api/v1/admin/portfolio-requests/{requestId}/submissions?submitted=false.
• Portfolio 제출물 개별 다운로드 권한: Server PR [FEAT] 포트폴리오 제출물 첨부파일 다운로드 권한 판정 추가 #287 Merge.
• Scheduler 운영 조회: Server PR [FEAT] 관리자 정기 작업 상태 조회 API 구현 #239 Merge, GET /api/v1/admin/system/jobs.
• 관련 Server Issue [FEAT] Portfolio Phase 2 - 학생 제출·관리자 제출 현황·일괄 다운로드 API 구현 #204, [FEAT] Discord 전달 내역 전체 목록 조회 API(Admin) #206, [FEAT] 관리자 Scheduler 상태 조회·수동 재시도 계약 확정 #227, [FEAT] 관리자 지원서 목록 생성일 범위 필터 추가 #279, [FEAT] Discord 전달 내역 기간 필터 추가 #280, [FEAT] 관리자 문의 답변 여부 필터 추가 #281, [FEAT] Portfolio Phase 3 - 제출물 첨부파일 다운로드 권한(FileAccessChecker) 구현 #286, #289는 완료 상태다.

따라서 과거 Comment의 “Portfolio 관리자 API 없음”, “#227 Scheduler 미구현”, “지원서 status-count 미구현” 설명은 현재 기준으로 stale이며 아래 표에서 정정한다.

최신 Metric 대조

역할	Metric/Widget	상태	현재 Backend	현재 Client / 후속
ADMIN	가입 승인 대기	READY_EXISTING_API	GET /api/v1/admin/members/search?role=TEACHER&status=PENDING의 totalElements	useStaffApprovalCountQuery('pending')로 연결됨
ADMIN	전체 지원	READY_NEW_API	GET /api/v1/admin/job-applications/status-counts의 totalCount	useApplicationStatusCountsQuery()로 연결됨
ADMIN	지원 처리 현황	READY_NEW_API	같은 API의 SUBMITTED, REVISION_REQUESTED, APPROVED	Client가 각각 “검토 대기”, “수정 요청”, “승인 완료”로 표시함. REVIEWING 상태를 새로 만들지 않음
ADMIN	공고 상세(모집/마감/비공개)	PRODUCT_DECISION_REQUIRED	공개 GET /api/v1/jobs는 PUBLISHED/CLOSED만 허용. Admin 공고 목록 GET은 없음(상세만 모든 상태)	Client Mock 유지. “비공개”가 DRAFT인지 DELETED 포함인지 먼저 확정 필요
ADMIN	프로그램 상태(진행/예정/종료)	PRODUCT_DECISION_REQUIRED	GET /api/v1/programs?status=...는 존재하나 Server 상태는 DRAFT/PUBLISHED/CLOSED/DELETED, Client 라벨은 RECRUITING/APPLIED/UPCOMING/CLOSED	Server/Client 상태 매핑과 관리자 노출 범위 확정 필요. Client API Hook도 없음
ADMIN	미답변 문의	CLIENT_ONLY	GET /api/v1/admin/inquiries?answered=false (Server PR #284, DEVELOPER 권한)	현재 inquiries 카드는 “미지원”. Client Issue #182/#183에서 answered 타입·Hook 연동 필요
ADMIN	최근 운영 상태/알림	CLIENT_ONLY	Job/Program/Inquiry 목록과 /api/v1/notifications는 각각 존재하나 통합 activity-feed 계약은 없음	DashboardNotificationSidebar가 정적 Mock을 유지함. 새 Aggregate API 근거 없음
TEACHER	신규 지원자	CLIENT_ONLY	GET /api/v1/admin/job-applications?mineOnly=true&createdFrom=... (Server PR #282)	Client 지원서 API에 createdFrom/createdTo 타입이 아직 없고 Dashboard Hook도 없음. 기준은 #219 확정값인 최근 3일
TEACHER	수정 요청	CLIENT_ONLY	기존 지원서 목록의 status=REVISION_REQUESTED&mineOnly=true	Backend/Client 도메인 API는 있으나 Dashboard는 Mock
TEACHER	기업 전달 대기	EXCLUDE	FORWARDED는 Enum에만 있고 실제 Lifecycle/Transition이 없음	Mock 항목은 제거 또는 미지원 표시. Workflow/Status 추가 금지
TEACHER	진행 중 프로그램	CLIENT_ONLY + PRODUCT_DECISION_REQUIRED	인증된 GET /api/v1/programs와 status/openOnly 필터 존재	Client API/Hook 없음. “진행 중”을 Server 상태·기간 중 무엇으로 볼지 확인 필요
TEACHER	포트폴리오 미제출(기한 경과)	PRODUCT_DECISION_REQUIRED	요청 목록은 GET /api/v1/portfolio-requests, 요청별 미제출은 GET /api/v1/admin/portfolio-requests/{requestId}/submissions?submitted=false로 가능	Phase 2b는 더 이상 미구현이 아님. 다만 모든 기한 경과 요청 합산인지, 특정 요청인지, 학생 중복을 어떻게 셀지 정의 필요. Client API/Hook 없음
TEACHER	담당 공고 현황	PRODUCT_DECISION_REQUIRED	지원서 목록은 jobId/mineOnly를 지원하지만 담당 공고 자체의 Admin 목록/행별 요약 API는 없음	“담당” 기준과 “처리 대기” 상태 집합 확정 후에만 최소 Summary Server Gap 여부 판단. 현재 Issue 생성하지 않음
TEACHER	최근 알림	CLIENT_ONLY	GET /api/v1/notifications	Client Hook은 존재하지만 Dashboard는 정적 Mock
DEVELOPER	정상 시스템	PRODUCT_DECISION_REQUIRED	/actuator/health(/readiness)와 GET /api/v1/admin/system/jobs는 있으나 “Web/DB/Redis 3건 정상” 산식은 없음	정상의 판정 기준과 표시 단위 확정 전 구현 금지. Client Issue #183도 정상 시스템을 미지원으로 유지하도록 작성됨
DEVELOPER	Discord 전송 실패	CLIENT_ONLY	GET /api/v1/admin/discord-deliveries?status=FAILED&startAt=...&endAt=... (Server PR #283)	Client API/Hook은 있으나 기간 파라미터가 아직 없음. #219 확정값인 최근 24시간을 사용해야 함
DEVELOPER	정기 작업 실패	CLIENT_ONLY	GET /api/v1/admin/system/jobs?status=FAILED&startAt=...&endAt=... (Server PR #239)	Client entities/scheduler에 API/Hook 없음. 현재 Client #183 제안의 status=FAILED만으로는 #219의 최근 24시간 기준이 빠지므로 startAt/endAt를 포함해야 함
DEVELOPER	외부 공고 수집 실패	CLIENT_ONLY	GET /api/v1/admin/collection-runs?status=FAILED&startAt=...&endAt=...가 실패 실행 수와 totalElements를 제공함	Client Collector API가 기간/status를 지원하지만 Dashboard에 연결되지 않음. 최신 실패 실행 수와 개별 실패 항목 수를 같은 값으로 취급하지 않도록 #183 구현 시 구분 필요
DEVELOPER	미처리 오류 문의	CLIENT_ONLY	GET /api/v1/admin/inquiries?inquiryType=ERROR&answered=false (Server PR #284)	Client FetchAdminInquiryListParams에 answered가 아직 없고 Dashboard Hook도 없음. #182/#183에서 연동
DEVELOPER	최근 실패 내역	CLIENT_ONLY	Discord/Operation Job/Collection Run 각 목록 API로 필요한 원천 데이터 조회 가능	Client Dashboard가 Mock. 세 원천을 최근 시각 순으로 합칠지, lastError/실패 실행을 어떻게 표기할지 #183에서 확정
DEVELOPER	최근 운영 알림	CLIENT_ONLY	GET /api/v1/notifications	Client Hook은 존재하지만 Dashboard는 정적 Mock

Status 정책

• JobApplicationStatus: Server는 DRAFT를 관리자 목록·status-count에서 제외하고, 나머지 Enum(SUBMITTED, EDIT_REQUESTED, EDIT_ALLOWED, REVISION_REQUESTED, APPROVED, REJECTED, FORWARDED, WITHDRAWN)을 반환한다. Client 표의 Dashboard 계약은 SUBMITTED를 검토 대기로 표시한다.
• FORWARDED: Enum에만 존재하는 dead lifecycle이므로 기업 전달 대기 Widget은 EXCLUDE한다.
• JobStatus: DRAFT/PUBLISHED/CLOSED/DELETED; 공개 목록 Filter는 PUBLISHED/CLOSED만이다.
• ProgramStatus: DRAFT/PUBLISHED/CLOSED/DELETED; Client의 RECRUITING/APPLIED/UPCOMING/CLOSED와 직접 일치하지 않는다.

Client 실제 구현 상태

• Client src/app/(admin)/admin/page.tsx는 기본 /admin에서만 AdminDashboardLive를 렌더링한다.
• 기본 관리자 화면에서 실제 호출은 2건이다: 가입 승인 대기 1건 + 지원서 상태 집계 1건.
• 관리자 나머지 3개 KPI(공고·프로그램·문의)는 현재 미지원으로 렌더링되고, 알림 Sidebar는 Mock이다.
• ?variant=staff와 ?variant=developer는 모두 DASHBOARD_CONTENT 정적 Mock을 그대로 렌더링한다. 따라서 현재 첫 렌더 HTTP 요청은 각각 0건이다.
• Client PR #181은 Server PR #290을 이미 반영했지만, “관리자 2개 KPI만 실데이터” 범위로 Merge된 상태다. Client Issue [FEAT] 관리자 담당자 선택용 교사 목록 조회 지원 #182(관리자 문의 KPI)와 [FEAT] 관리자 회원 목록·상세 조회 및 역할·계정 상태 변경 API #183(개발자 Dashboard)은 아직 OPEN이다.

Request Count Audit

현재 코드 기준:

• ADMIN: 2회
• TEACHER preview: 0회
• DEVELOPER preview: 0회

후속 연동 시 Backend 호출은 독립 Metric 기준으로 추가한다. 예를 들어 Developer의 Discord 실패·Scheduler 실패·오류 문의는 최소 3개 목록 요청으로 구성할 수 있고, 실패 내역 표가 같은 응답을 재사용하면 추가 요청을 만들 필요가 없다. 이는 Dashboard Aggregate API가 필요한 상황이 아니라 Client Query 조합으로 처리할 수 있는 범위다.

잠재적인 N+1 후보는 TEACHER의 “담당 공고 현황”이다. 현재는 담당 공고 목록/행별 지원 요약 계약이 없으므로, Product Decision 없이 공고별 지원서 API 반복 호출을 구현하지 않는다.

Backend Gap / Product Decision

확정된 SERVER_GAP: NONE.

다음은 결정 후에만 최소 Server Gap으로 재평가한다.

1. Admin 공고 상태 KPI: 비공개의 실제 상태와 DELETED 포함 여부.
2. Teacher 담당 공고: 담당자 소유권 기준, 지원자 수/처리 대기 상태 집합, 0명 공고 포함 여부.
3. Portfolio 미제출: 한 요청 기준인지 전체 기한 경과 요청 합산인지, 학생 중복 집계 규칙.
4. Developer 정상 시스템: Health component 기준인지 Scheduler 상태 기준인지, “정상” 개수의 분모.
5. Developer 수집 실패: 실패 실행 수인지 최신 실행의 failureCount인지.

위 결정이 확정되기 전에는 신규 Server Issue를 생성하지 않는다. 이번 Audit에서 Created Issue는 없다.

Client-only 후속 작업

• Client Issue [FEAT] 관리자 담당자 선택용 교사 목록 조회 지원 #182: answered=false를 문의 Entity API에 반영하고 관리자 미답변 KPI 연결.
• Client Issue [FEAT] 관리자 회원 목록·상세 조회 및 역할·계정 상태 변경 API #183: Developer Dashboard의 Discord 기간 필터, Scheduler API/기간 필터, 오류 문의 필터, Collector/실패 표 연결. #219의 최근 24시간 기준(startAt/endAt)을 반영해야 한다.
• 별도 후속: Teacher Dashboard의 최근 3일/수정 요청/프로그램/Portfolio API 연결.
• Client Dashboard의 정적 알림 Sidebar와 ?variant=staff|developer Mock 제거 또는 실데이터 전환.

Stale Issue Cleanup

이번 Audit 대상 선행 Issue 중 stale 상태로 OPEN인 항목은 확인되지 않았다. #204, #206, #227, #279, #280, #281, #286, #289는 이미 CLOSED이며, #219는 Client Dashboard 통합과 Product Decision이 남아 있어 OPEN 유지한다. Client #182/#183도 구현 전이므로 OPEN 유지한다.

결론

#219는 완료/종료하지 않는다. Server 선행 기능은 최신 develop에 반영되었고, 현재 남은 작업은 확정된 Backend Gap 없이 Client 연동과 Product Decision 정리다. Product Decision이 확정된 항목만 별도 최소 Issue로 분리하고, 그 전에는 Dashboard Aggregate API를 추가하지 않는다.

[exijn]

최신 전면 재검증 결과 (2026-08-29)

Baseline

• Server origin/develop: 30f3a3bb00d00db0e7916c1b8682823c6f41602d (PR [FEAT] 관리자 지원서 상태별 건수 조회 API 구현 #290 포함)
• Client origin/develop: 7565b1451589d06f6d9b4940f997e14baf28d1da (Client PR [FEAT] 지원자 관리 목록 필터 확장 #181 포함)
• 재확인 시점의 Server OPEN PR: 0건

Dashboard Re-Audit

Widget	상태	근거/조치
가입 승인 대기	READY_EXISTING_API	GET /api/v1/admin/members/search?role=TEACHER&status=PENDING의 totalElements; Client 기본 관리자 화면에서 연결됨
전체 지원·지원 처리 현황	READY_NEW_API	GET /api/v1/admin/job-applications/status-counts; PR #290 및 Client PR #181 반영 확인. SUBMITTED를 검토 대기로 사용하며 REVIEWING 추가 안 함
최근 3일 신규 지원자	READY_EXISTING_API	PR #282의 createdFrom/createdTo 계약 확인. 현재 Dashboard는 Client-only
Discord 최근 24시간 실패	READY_EXISTING_API	PR #283의 startAt/endAt, lastAttemptAt 기준 확인. 현재 Dashboard는 Client-only
문의 답변 여부	READY_EXISTING_API	PR #284의 answered=false 및 inquiryType=ERROR 조합 확인. 현재 Dashboard는 Client-only
Portfolio 미제출	PRODUCT_DECISION_REQUIRED	PR #285의 요청별 submitted=false 조회는 존재하나 전체 기한 경과 합산·중복 집계 의미가 미확정
담당 공고 현황	PRODUCT_DECISION_REQUIRED	담당자 기준·행별 지원자/처리 대기 집합·0명 공고 포함 여부 미확정. 공고별 fan-out 구현 안 함
공고 모집/마감/비공개	PRODUCT_DECISION_REQUIRED	Server Job 상태와 Client 라벨 매핑 및 DELETED 포함 여부 미확정
프로그램 진행/예정/종료	PRODUCT_DECISION_REQUIRED	Server DRAFT/PUBLISHED/CLOSED/DELETED와 Client 라벨의 매핑·노출 범위 미확정
정상 시스템	PRODUCT_DECISION_REQUIRED	Health/Scheduler 중 판정 기준과 분모 미확정
최근 운영 상태/알림	CLIENT_ONLY	원천 API는 존재하지만 통합 Activity/Aggregate 계약은 없음; Client Sidebar는 Mock
기업 전달 대기	EXCLUDE	FORWARDED는 실제 Lifecycle 전이가 없는 dead enum; 구현·Issue 생성 안 함

Core E2E Audit

• Student: Auth/session refresh, profile, job/search/detail, bookmark, application/my-application, inquiry 계약은 Server Controller·Service·Repository 및 Client API가 대응한다. recommendation/portfolio/program 화면은 Client Mock 또는 미연동이며 Backend 신규 Gap으로 승격하지 않았다.
• Teacher: company 및 applicant 관리와 application review, portfolio admin, inquiry 계약은 Server에 존재한다. job/program/MOU 화면의 Client route/API 미연동은 Client-only이며 Backend 작업으로 만들지 않았다.
• Developer: member approval, inquiry, Discord delivery, collector, scheduler, audit log 계약과 권한 경계가 Server에 존재하며 Client 운영 화면 API와 대응한다.
• 성능: Dashboard용 N+1/동일 상태별 count loop는 최신 코드에서 신규 근거를 찾지 못했다. 담당 공고 fan-out은 계약 미확정으로 구현하지 않았다.
• 보안/계약: 요청 Body memberId 신뢰·IDOR·역할 누락을 신규 재현 가능한 범위에서 확인하지 못했고, Client가 사용하는 path/method/query/enum/pagination은 대응 Controller와 일치했다.

분류 및 조치

• SERVER_GAP: 없음
• READY_NEW_API: PR #290으로 이미 Merge됨
• READY_EXISTING_API: PR [FEAT] 관리자 정기 작업 상태 조회 API 구현 #239, [FEAT] 지원서 생성일 범위 필터 추가 #282, [FEAT] Discord 전달 내역 기간 필터 추가 #283, [FEAT] 문의 답변 여부 필터 추가 #284, [FEAT] 관리자 포트폴리오 제출 현황·일괄 다운로드 구현 #285, [FEAT] 포트폴리오 제출물 첨부파일 다운로드 권한 판정 추가 #287 및 기존 API 재사용
• CLIENT_ONLY: Dashboard 나머지 연동, 프로그램/추천/포트폴리오 정적 화면, 일부 교사·개발자 화면
• PRODUCT_DECISION_REQUIRED: Portfolio 합산, 담당 공고, Job/Program 상태, 정상 시스템, Collector 실패 의미
• EXCLUDE: [FEAT] File 도메인 전체 구현 (Epic) #84/File, File Cleanup/publicEndpoint/storage/S3/MinIO, [FEAT] PORTFOLIO_REQUEST·MEMBER_APPROVAL 알림 대상 접근 판정 추가 #192 및 PORTFOLIO_REQUEST·MEMBER_APPROVAL Target Resolver
• 새 Issue: 없음 (NO_ACTIONABLE_BACKEND_GAP)
• 새 Worktree/PR: 없음

기존 #219의 2026-08-28 기록에서 정정할 stale Backend 내용은 오늘 기준으로 남아 있지 않으며, 위 항목은 현재 SHA에서 재확인했다. Product Decision이 확정되기 전 Dashboard Aggregate API와 임의 상태 산식을 추가하지 않는다.

[exijn]

2026-08-31 7개 의심 항목 최종 Backend 재검증

기준 SHA:

• Server origin/develop: 30f3a3bb00d00db0e7916c1b8682823c6f41602d
• Client origin/develop: 0eb18376b3133b3a9c3b2aad70261c8ef950575c

이번 검증은 관리자 프로그램 목록, 시스템 헬스, 관리자 activity-feed, 포트폴리오 제출현황 count, 공고별 지원현황 집계, 지원서 자기소개, 지원 불가 사유 Error Code를 현재 코드·Client 호출·기존 Issue/PR과 대조했다.

항목	판정	근거/결론
관리자 프로그램 목록	REUSE_EXISTING_API	GET /api/v1/programs가 status/programType/openOnly/Pageable을 제공하고 대시보드 상태 건수에 사용할 수 있다. 관리자 프로그램 화면 자체는 Client Mock이며 admin 전용 목록이 없다는 이유로 Server API를 중복 생성하지 않는다.
시스템 헬스	CONTRACT_DECISION_REQUIRED	GET /api/v1/admin/system/jobs와 Actuator health는 존재한다. 다만 “정상 시스템 수”의 대상·분모·판정 산식은 확정되지 않았다.
관리자 activity-feed	REUSE_EXISTING_API	GET /api/v1/notifications가 본인 알림 목록의 unread/type/page/createdAt 계약을 제공한다. 전역 운영 감사 feed가 필요하다면 별도 제품 계약이 필요하지만 현재 Server Gap으로 확정하지 않는다.
포트폴리오 제출현황 count	REUSE_EXISTING_API	GET /api/v1/admin/portfolio-requests/{requestId}/submissions?submitted=false의 totalElements로 Request별 count를 얻을 수 있고, 요청 목록에는 DB 집계 Query도 있다. 여러 Request 합산 규칙은 제품 결정 사항이다.
공고별 지원현황 집계	CONTRACT_DECISION_REQUIRED	지원서 목록의 jobId/status/mineOnly와 DB Pageable Query는 존재한다. 현재 Client의 대시보드/기업 연결 공고 표는 Mock이고, 담당 범위·처리 대기 상태·0명 공고 포함 계약이 확정되지 않아 summary API를 만들지 않는다.
지원서 자기소개	CONTRACT_DECISION_REQUIRED	전용 Entity/DTO/Column은 없지만 Form 문항 answers/questions vertical slice가 존재하며 Client도 전용 입력을 비활성화하고 있다. 전용 필드인지 Form 문항인지 확정 전에는 Migration/DTO를 추가하지 않는다.
지원 불가 사유 Error Code	REUSE_EXISTING_API	GET /api/v1/jobs/{jobId}/application-eligibility가 BEFORE_START, AFTER_END, NOT_TARGET_GRADE, ALREADY_APPLIED 등 사유를 구분한다. 생성 POST의 JOB_NOT_APPLICABLE는 현재 application 명세의 의도된 계약이며 Error Code를 rename/삭제하지 않는다.

결론: CONFIRMED_BACKEND_GAP 없음. 새 Issue/Worktree/Commit/PR은 생성하지 않았다(NO_ACTIONABLE_BACKEND_GAP).

현재 Client 0eb1837에서는 개발자 대시보드의 Scheduler/Discord/문의 원천 API 연동이 추가되었고, 프로그램·포트폴리오 관리 및 일부 대시보드 화면은 여전히 Client Mock이다. 이 상태는 Backend 신규 Gap으로 승격하지 않는다.

제외 영역 #84/File, File 운영 설정·Cleanup·publicEndpoint·S3/MinIO 및 #192 Notification Target Resolver/PORTFOLIO_REQUEST/MEMBER_APPROVAL은 조사·수정·Issue 생성을 하지 않았다.