backend/agent 제외1. 미션
화면 · 앱 · 에이전트가 딛고 서는 모든 API와 데이터를 만든다. 클라이언트 3종이 같은 FastAPI 서버 하나를 바라보는 구조이므로, 이 도메인이 늦으면 나머지 전부가 목데이터에 갇힌다.
2. 범위
포함
- 인증 · 권한 — JWT, 역할 2종(
admin·member). 2026. 08. 31. 개정으로 면접관 배정 조회 제한은 폐지했고, 남은 제한은 평가 작성(배정된 건만)과 admin 전용 넷뿐이다 - 도메인 API — 공고 · 지원서 · 지원자 관리(단계 전환 포함) · 평가 · 메모
- 검색 · 필터 · 정렬 · 페이지네이션 + 인덱스 튜닝
- 스키마 — 인덱스 추가까지 측정 · 제안 · 반영 전부 이 도메인이다. ERD 갱신과 alembic 리비전을 코드와 같은 커밋에 묶고 머지 뒤 팀 채널에 한 줄 공지한다
- 파일(S3 presigned) · 메일(SES + SQS 워커) — 코드만
- 더미 데이터 10만 건 · 구조화 로깅 · 에러 코드 표준 · API 테스트
제외
- 버킷 · 큐 · SES 도메인 등 AWS 리소스 준비 — 인프라 소관
backend/app/agent/— 에이전트 도메인- Docker Compose · CI/CD — 인프라 도메인
3. 인터페이스 계약
제공 — API 문서에 정의된 REST 전부. 상세는 Swagger가 진실이다. 엔드포인트를 추가하거나 바꾸면 API 문서 갱신을 같은 커밋에 넣고, 머지 뒤 팀 채널에 한 줄 공지한다 — 2026. 08. 28. 리뷰 게이트 폐지로 승인 절차는 없다. 소비자는 프론트엔드 · 앱 · 에이전트 3종이다.
의존 — 인프라(접속 문자열 · AWS 자격 · S3 버킷 · SQS 큐 · SES 발신 도메인), 그리고 에이전트가 제공하는 요약 생성 함수. 지원서 접수 흐름이 그 함수를 호출하므로 시그니처는 두 오너 간 인터페이스 PR로 합의한다.
4. 주간 계획
| 주차 | 마일스톤 | 내용 | 완료 기준 |
|---|---|---|---|
| W108. 24. ~ 28. | 선행 해소 | 앱 뼈대 · ERD 확정 · 인증 · 공고 · 지원서 제출 · 지원자 목록 · 상세 · 평가 · 검색 | 달성 W2 예정이던 코어 API 물량을 W1 안에 소화했다. |
| W208. 31. ~ 09. 04. | M1 코어 API 초기 버전 | 인증 · 공고 · 지원서 제출 · 지원자 목록 · 상세 · 평가 · 검색 | 배포 URL의 Swagger에서 전부 호출 가능. 수직 슬라이스 — 공개 지원 폼 제출 → DB 저장 → 조회까지 관통 |
| W309. 07. ~ 11. | M2 전환 · 파일 · 메일 | 단계 전환과 이력 · 담당자 직접 등록 · 메모 · presigned 업로드 · 다운로드 · 파일 검증 · 메일 큐 · 접수 확인 메일 | 단계 변경 → 이력 기록 + 메일 실수신. 실패 재시도 로그. 업로드 → 다운로드 왕복 |
| W409. 14. ~ 18. | M3 성능 | 더미 10만 건 · 정렬 · 커서 페이지네이션 · 인덱스 튜닝(전후 측정) · 마감일 · 공개 링크 · 불합격 사유 · 일괄 변경 · 로깅 | 성능 문서에 주요 쿼리 4종의 전후 수치가 남는다 |
| W509. 21. ~ 25. | M4 품질 · 통합 | API 테스트 · 통합 버그픽스 · 에이전트 도구용 엔드포인트 보강 | 테스트가 30초 내 전부 통과하고 CI에서 돈다. QA 시나리오 백엔드 항목 전부 통과 |
| 버퍼09. 28. ~ 30. | 동결 | 코드 프리즈 · 잔여 버그 | 09. 30. 1차 완성 |
5. 진행 현황
2026. 09. 22. 기준. 작업 큐 22건이 전부 닫혔다. M1 코어 · M2 전환 · 파일 · 메일 · M3 성능까지 일정을 크게 앞질렀고, 마지막까지 남아 있던 API 테스트도 pytest 1,165건이 CI에서 통과한다. 승인 대기라는 상태는 없다 — 2026. 08. 28. 리뷰 게이트 폐지와 09. 04. 자체 머지 전환으로, CI가 초록이면 오너가 자기 PR을 자기가 머지한다. 지금 무게는 로드맵 W1~W5에 없던 확장분(실시간 AI 면접 · 회사 통합 API)의 구멍 메우기와 09. 28. ~ 30. 코드 프리즈 전 잔여 목록에 있다.
검색 총계 병목 — 111 ms → 7.8 ms
성능 문서가 "인덱스로는 못 푼다"고 측정만 남겨둔 전체 건수 집계 병목을 옵션으로 분리해 처리했다. 10만 건에서 이름 검색이 111 ms에서 7.8 ms로 줄었다. 기본값을 켜둔 채로 분리해 기존 호출은 그대로 동작한다.
풀리지 않는 병목 둘은 측정만 남겼다
① 매칭이 적은 검색어는 "50개 채우면 중단"이 안 통해 끝까지 훑는다(102 ms). ② 점수 정렬은 정렬 키가 집계값이라 10만 그룹을 다 만들어야 순서가 정해진다(170 ms). 둘 다 인덱스로 풀리지 않고 스키마 쪽 문제라, 고치는 대신 근거와 함께 기록만 남겼다.
마감된 공고는 404가 아니라 410 Gone
스케줄러를 만들지 않고 조회 시점 판정으로 처리했다. 마감을 404로 주면 지원자가 "링크가 틀렸나" 하고 헤맨다. 반대로 아직 공개한 적 없는 초안은 404가 맞다. 검증 중 410이 에러 코드 표에 없어 내부 오류로 나가던 것을 함께 고쳤다.
메일 발행을 커밋 뒤로 옮겼다
기존 발송 함수는 커밋 전에 큐로 발행해서, 롤백이 정상 경로인 일괄 변경에서는 되돌린 건의 메시지가 큐에 남았다. 행 기록과 발행을 분리해 커밋 뒤에 발행하도록 바꿨고, 단건 경로도 같은 순서로 정리해 기존 경합을 없앴다.
조회 API 13개를 계약과 전수 대조했다
초안 공고가 무인증으로 노출되는 문제를 고치면서 조회 엔드포인트 13개를 토큰 없이 전부 호출해 API 문서와 대조했다. 어긋난 것은 둘뿐이었고 지금은 전부 맞는다. "문서에 안 적혀 있다"와 "문서의 전역 규칙이 이미 덮는다"는 다르다 — 표만 보지 않고 머리말을 먼저 보는 것으로 판단 기준을 바꿨다.
6. 리스크 및 대응
| 리스크 | 대응 |
|---|---|
| 1인 절대량 큐 22건 |
완충 셋을 뒀다. ① 전환기 분담 6건을 인프라(총괄) 담당자와 앱 담당자가 셋씩 나눠 맡았다 ② 공고 API 실측 판정 — 예상보다 오래 걸리면 권장 항목부터 다음 주로 강등 ③ 권장 항목은 필수 항목보다 항상 뒤. |
| AWS 리드타임 | SES 샌드박스 해제가 늦으면 메일 항목이 선다. 인프라가 첫날 신청을 걸고, 막히면 콘솔 출력 발송자로 폴백해 워커 로직만 먼저 검증한다. |
| ERD 확정 지연 해소 |
W1 리스크였다 — 목업 머지가 선행이었고, W1 안에 확정됐다. 그 뒤로는 이 도메인이 코드와 같은 커밋에서 ERD를 직접 갱신한다 — 남의 확정을 기다리는 항목이 아니다. 지금은 v2.8(2026. 09. 17.)이고 alembic 리비전 26개가 따라붙어 있다. |
7. 발표 포인트
- 상태 전환 규칙을 DB 제약과 서비스 레이어 중 어디서 왜 강제했는가 — 정의되지 않은 전이를 어디서 막을지의 선택과 그 대가.
- 느린 쿼리를 어떻게 찾았고 인덱스로 몇 ms에서 몇 ms로 줄였는가 — 성능 문서의 실제 숫자로. 고치지 못한 병목을 근거와 함께 남긴 것까지 포함해서.
- 파일 업로드가 왜 API 서버를 거치면 안 되는가 — presigned URL로 S3에 직행시킨 이유.